QMol_TDCI_SSO_6BM - fmauger1/QMol-grid GitHub Wiki

QMol_TDCI_SSO_6BM

Sixth-order optimized Blanes and Moan [Blanes 2002] symplectic split-operator scheme for TDCI simulations.

Description

Use QMol_TDCI_SSO_6BM to propagate the TDCI dynamics of a Schrödinger-equation model with a Cartesian-grid discretization domain using a sixth-order optimized Blanes and Moan [Blanes 2002] scheme. The time propagation can be performed field free or with an external driving field in the dipole approximation and either length or velocity gauge. The derivation and details of the implementation of the symplectic split-operator can be found in [Mauger 2024]. During the TDCI propagation, several observables can be computed on-the-fly and stored in output structures in the QMol_TDCI_SSO_6BM object. Each of these can be activated independently and may define their own sampling times:

  • Save the Schrödinger-equation object into individual files
  • Save the dipole, dipole velocity, and dipole acceleration signals
  • Save Schrödinger-equation and wave function energies
  • Save the external field information
  • Save the ionization signal
  • Save the wave functions and their projection on a basis
  • Save the output of a function of the wave functions
  • Save restart data file

See the TDCI documentation page for examples of using most of these features.

QMol_TDCI_SSO_6BM is a handle class.

Class properties

Time propagation

display (disp)

Whether to display progress of the TDCI calculation as it goes on [ true (default) | false ]

time (T)

Time propagation vector [ vector (default []) ]

  • In all TDCI propagation simulations, T(1) specifies the starting time and T(end) the ending time.
  • In forward time propagation simulations (timeStep > 0 ), time values in T must be all increasing, while for backward time propagation (timeStep < 0 ) they must be all decreasing. Time increments in the vector T need not be equally spaced.
  • When display is activated, T specifies the intermediary times for the time-propagation progress display.
  • T is also the default time sampling for saved results that do not define their own.
  • Note that the time step used in TDCI propagations is set independently of T.

timeStep (dt)

Time step used for the time propagation [ scalar (default 0.01) ]

  • Positive (resp. negative) timeStep define forward (resp. backward) time propagation.

splitMotif

Splitting motif [ 'HDH' (default) | 'DHD' ]

  • Whether the splitting starts with applying the field-free CI Hamiltonian matrix ('HDH') or the dipole-coupling matrix ('DHD') part of the TDCI Hamiltonian.

absorbingBoundary (ABC)

Absorber at the edges of the domain [ [] (default) | mask object | CAP object ]

  • The boundary absorber aims at eliminating outgoing wave packets from the discretization domain and avoid spurious reflections from the finite dimension of the model.
  • Empty absorbingBoundary does not implement any absorbing boundary method, which may result in artifical reflections.
  • Mask absorbers are applied at the end of each propagation step. They are the easiest to use and implement but are first order, irrespective of the order of the time propagation scheme.
  • Complex absorbing potentials (CAPs) are integrated within the propagation scheme, as an imaginary potential term that causes exponential decay of selected portions of the wave packet. Under the right circumstances, CAPs can preserve the order of the propagation schemes.

externalField (EF)

External driving field [ [] (default) | QMol_extField_dipole object ]

  • When performing the TDCI propagation, any electricField, electricFieldDerivative, or potentialVector are repackaged into externalField.
  • If no electric field or potential vector is defined, either through externalField, electricField, or potentialVector, the TDCI propagation is performed field free.

externalFieldGauge (EFG)

Gauge in which the external driving field is described [ [] (default) | 'none' | 'length' ]

  • 'none' ignores any input external field and propagates the field-free TDCI dynamics.
  • The decision tree for the selection of the default gauge is detailed below.
  • Note that unlike TDSE and TDDFT propagators, TDCI does not support velocity gauge external driving.

electricField (FE)

Electric field of the external driving field [ [] (default) | function handle | griddedInterpolant ]

  • For developers: When initializing the class, non-empty electricField is moved into the externalField property object (if needed creating the object first). During run time, FE contains the value of the electric field used in the propagation (where relevant).

electricFieldDerivative (FDE)

Derivative of the electric field of the external driving field [ [] (default) | function handle | griddedInterpolant ]

  • griddedInterpolant electricFieldDerivative is provided for general support but note that non-function-handle electric field derivatives are computed self-consistently from the electric-field or potential-vector components.
  • For developers: When initializing the class, non-empty electricFieldDerivative is moved into the externalField property object (if needed creating the object first). During run time, FDE contains the value of the derivative of the electric field used in the propagation (where relevant).

potentialVector (FA)

Potential vector of the external driving field [ [] (default) | function handle | griddedInterpolant ]

  • For developers: When initializing the class, non-empty potentialVector is moved into the externalField property object (if needed creating the object first). During run time, FA contains the value of the potential vector used in the propagation (where relevant).

diffDT

Time step for used for computing time derivatives [ nonnegative scalar (default 1e-5) ]

Save the CI object into individual files

During the time propagation, copies of the CI object can be saved in separate MATLAB files.

saveCI (sCI)

Activate saving the CI object into separate files [ true | false (default) ]

saveCIFileName (sCIF)

Name for the files in which the CI objects are saved [ character array (default 'QMolGrid--TDCI--CI') ]

  • The CI objects saved at different times are put in separate MATLAB (.mat.) file, with names starting with saveCIFileName to which the iteration index is appended. Each file produced also contains a scalar variable t with the time information.
  • One may specify a location where to create the files by indicating the folder path in saveCIFileName.
  • saveCIFileName is irrelevant when saveSE == false .

saveCITime (sCIT)

Times at which to save the CI object into a file [ [] (default) | positive scalar | negative integer | vector | 'all' ]

  • Empty saveCITime uses the same values as in time for when to save the CI object into MATLAB files.
  • A positive scalar specifies the sampling time step when to save the CI object into MATLAB files. For forward time propagation, it is equivalent to time(1):saveCITime:time(end), and for backward ones to time(1):-saveCITime:time(end).
  • A negative integer specifies the number of propagation time steps between saves. For forward time propagation, it is equivalent to time(1):abs(saveCITime)\timeStep``:time(end), and for backward one to time(1):-abs(saveCITime)\timeStep``:time(end).
  • A vector provides user-defined times at which to save the CI object to a MATLAB file.
  • 'all' saves the Schrödinger-equation object into a MATLAB file after every time step. Warning: this is slow and may result in a very large number of file and/or large disk usage.
  • See the note on how intermediate time saving is performed during the TDCI propagation below.

Save the dipole, dipole velocity, and dipole acceleration signals

saveDipole (sDip)

Whether to calculate and save the dipole signal during the TDCI propagation [ true | false (default) ]

saveDipoleWaveFunctionIndex (sDipI)

Index of the wave functions for which to compute the dipole signal [ [] (default) | index vector | 'all' ]

  • This is irrelevant if saveDipole is false.
  • Specify the indexes of the wave functions for which to compute the dipole signal in an index vector.
  • Empty or 'all' saveDipoleWaveFunctionIndex computes the dipole for all wave functions.

saveDipoleTime (sDipT)

Times at which to compute and save the dipole signal [ [] (default) | positive scalar | negative integer | vector | 'all' ]

  • Empty saveDipoleTime uses the same values as in time for when to compute and save the dipole signal.
  • A positive scalar specifies the sampling time step between successive computations of the dipole signal. For forward time propagation, it is equivalent to time(1):saveDipoleTime:time(end), and for backward one to time(1):-saveDipoleTime:time(end).
  • A negative integer specifies the number of propagation time steps between dipole-signal computations. For forward time propagation, it is equivalent to time(1):abs(saveDipoleTime)\timeStep``:time(end), and for backward one to time(1):-abs(saveDipoleTime)\timeStep``:time(end).
  • A vector provides user-defined times at which to compute and save the dipole signal.
  • 'all' computes and saves the dipole signal after every time step. Warning: this may be slow.
  • See the note on how intermediate time saving is performed during the TDCI propagation below.

saveDipoleVelocity (sVel)

Whether to calculate and save the dipole velocity signal during the TDCI propagation [ true | false (default) ]

saveDipoleVelocityWaveFunctionIndex (sVelI)

Index of the wave functions for which to compute the orbital-resolved dipole velocity signal [ [] (default) | index vector | 'all' ]

  • This is irrelevant if saveDipoleVelocity is false.
  • Specify the indexes of the wave functions for which to compute the dipole velocity signal in an index vector.
  • Empty or 'all' saveDipoleVelocityWaveFunctionIndex computes the dipole velocity for all wave functions.

saveDipoleVelocityTime (sVelT)

Times at which to compute and save the dipole velocity signal [ 'dipole' (default) | positive scalar | negative integer | vector | 'all' ]

  • 'dipole' saveDipoleVelocityTime uses the same times as for saveDipoleTime.
  • A positive scalar specifies the sampling time step between successive computations of the dipole velocity signal. For forward time propagation, it is equivalent to time(1):saveDipoleVelocityTime:time(end), and for backward one to time(1):-saveDipoleVelocityTime:time(end).
  • A negative integer specifies the number of propagation time steps between dipole-velocity-signal computations. For forward time propagation, it is equivalent to time(1):abs(saveDipoleVelocityTime)\timeStep``:time(end), and for backward one to time(1):-abs(saveDipoleVelocityTime)\timeStep``:time(end).
  • A vector provides user-defined times at which to compute and save the dipole velocity signal.
  • 'all' computes and saves the dipole velocity signal after every time step. Warning: this may be slow.
  • See the note on how intermediate time saving is performed during the TDCI propagation below.

saveDipoleAcceleration (sAcc)

Whether to calculate and save the dipole acceleration signal during the TDCI propagation [ true | false (default) ]

saveDipoleAccelerationWaveFunctionIndex (sAccI)

Index of the wave functions for which to compute the dipole acceleration signal [ [] (default) | index vector | 'all' ]

  • This is irrelevant if saveDipoleAcceleration is false.
  • Specify the indexes of the wave functions for which to compute the dipole acceleration signal in an index vector.
  • Empty or 'all' saveDipoleAccelerationWaveFunctionIndex computes the dipole acceleration for all wave functions.

saveDipoleAccelerationTime (sAccT)

Times at which to compute and save the dipole acceleration signal [ 'dipole' (default) | positive scalar | negative integer | vector | 'all' ]

  • 'dipole' saveDipoleAccelerationTime uses the same times as for saveDipoleTime.
  • A positive scalar specifies the sampling time step between successive computations of the dipole acceleration signal. For forward time propagation, it is equivalent to time(1):saveDipoleAccelerationTime:time(end), and for backward one to time(1):-saveDipoleAccelerationTime:time(end).
  • A negative integer specifies the number of propagation time steps between dipole-acceleration-signal computations. For forward time propagation, it is equivalent to time(1):abs(saveDipoleAccelerationTime)\timeStep``:time(end), and for backward one to time(1):-abs(saveDipoleAccelerationTime)\timeStep``:time(end).
  • A vector provides user-defined times at which to compute and save the dipole acceleration signal.
  • 'all' computes and saves the dipole acceleration signal after every time step. Warning: this may be slow.
  • See the note on how intermediate time saving is performed during the TDCI propagation below.

Save CI and wave function energies

saveEnergyCI (sECI)

Whether to track the CI energy during the TDCI propagation [ true | false (default) ]

saveEnergyCITime (sECIT)

Times at which to compute and save the CI energy [ [] (default) | positive scalar | negative integer | vector | 'all' ]

  • Empty saveEnergyCITime uses the same values as in time for when to compute and save the CI energy
  • A positive scalar specifies the sampling time step between successive computations of the CI energy. For forward time propagation, it is equivalent to time(1):saveEnergyCITime:time(end), and for backward one to time(1):-saveEnergyCITime:time(end).
  • A negative integer specifies the number of propagation time steps between CI-energy computations. For forward time propagation, it is equivalent to time(1):abs(saveEnergyCITime)\timeStep``:time(end), and for backward one to time(1):-abs(saveEnergyCITime)\timeStep``:time(end).
  • A vector provides user-defined times at which to compute and save the CI energy.
  • 'all' computes and saves the CI energy after every time step. Warning: this may be slow.
  • See the note on how intermediate time saving is performed during the TDCI propagation below.

saveEnergyWaveFunction (sEWfcn)

Whether to track the wave function energies during the TDCI propagation [ true | false (default) ]

  • For a wave function $|\psi \rangle$ , the wave function energy is defined as $\langle \psi |\hat{\mathcal{H}} |\psi \rangle$ with $\hat{\mathcal{H}}$ the CI Hamiltonian operator.
  • Note that the energy of all the wave functions are computed and saved. One may use an installable output function to track the energy of a subset of wave functions.

saveEnergyWaveFunctionTime (sEWfcnT)

Times at which to compute and save the wave function energies [ [] (default) | positive scalar | negative integer | vector | 'all' ]

  • Empty saveEnergyWaveFunctionTime uses the same values as in time for when to compute and save the wave function energies
  • A positive scalar specifies the sampling time step between successive computations of the wave function energies. For forward time propagation, it is equivalent to time(1):saveEnergyWaveFunctionTime:time(end), and for backward one to time(1):-saveEnergyWaveFunctionTime:time(end).
  • A negative integer specifies the number of propagation time steps between wave-function-energy computations. For forward time propagation, it is equivalent to time(1):abs(saveEnergyWaveFunctionTime)\timeStep``:time(end), and for backward one to time(1):-abs(saveEnergyWaveFunctionTime)\timeStep``:time(end).
  • A vector provides user-defined times at which to compute and save the wave function energies.
  • 'all' computes and saves the wave function energies after every time step. Warning: this may be slow.
  • See the note on how intermediate time saving is performed during the TDCI propagation below.

Save the external field information

saveExternalField (sEF)

For TDCI simulation with and external driving field, save the external field in the output structures [ true | false (default) ]

  • When activated (saveExternalField = true), the information about the external driving field at the sampled times is added to each of the output structures.
  • For practical reasons, the values for the external driving field may be slightly different from that of externalField. This features enables keeping the actual external-field values used throughout the propagation.

Save the ionization signal

The ionization signal tracks how much density leaves the simulation domain by being absorbed at the boundaries.

saveIonization (sIon)

Whether to calculate and save the ionization signal during the TDCI propagation [ true | false (default) ]

saveIonizationWaveFunctionIndex (sIKSOI)

Index of the wave functions for which to compute the ionization signal [ [] (default) | index vector | 'all' ]

  • This is irrelevant if saveIonization is false.
  • Specify the indexes of the wave functions for which to compute the ionization signal in an index vector.
  • Empty or 'all' saveIonizationWaveFunctionIndex computes the ionization for all wave functions.

saveIonizationTime (sIonT)

Times at which to compute and save the ionization signal [ [] (default) | positive scalar | negative integer | vector | 'all' ]

  • Empty saveIonizationTime uses the same values as in time for when to compute and save the ionization signal.
  • A positive scalar specifies the sampling time step between successive computations of the ionization signal. For forward time propagation, it is equivalent to time(1):saveIonizationTime:time(end), and for backward one to time(1):-saveIonizationTime:time(end).
  • A negative integer specifies the number of propagation time steps between ionization-signal computations. For forward time propagation, it is equivalent to time(1):abs(saveIonizationTime)\timeStep``:time(end), and for backward one to time(1):-abs(saveIonizationTime)\timeStep``:time(end).
  • A vector provides user-defined times at which to compute and save the ionization signal.
  • 'all' computes and saves the ionization signal after every time step. Warning: this may be slow.
  • See the note on how intermediate time saving is performed during the TDCI propagation below.

Save the wave functions

Warning: The memory requirements for saving the wave functions throughout the TDCI propagation may grow very fast and trigger an error (if MATLAB runs out of memory). Instead, if the full wave function is required consider saving the CI object in separate files, or if only the result of a specify calculation on the wave functions is required consider consider using an installable output function.

saveWaveFunction (sWfcn)

Whether to save the wave functions during the TDCI propagation [ true | false (default) ]

saveWaveFunctionIndex (sWfcnI)

Index of the wave functions to save [ [] (default) | index vector | 'all' ]

  • This is irrelevant if saveWaveFunction is false.
  • Empty saveWaveFunctionIndex disables saving of the wave functions and is technically equivalent to saveWaveFunction``= false.
  • Specify the indexes of the wave functions to save in an index vector.
  • 'all' saves all the wave functions.

saveWaveFunctionTime (sWfcnT)

Times at which to save the wave functions [ [] (default) | positive scalar | negative integer | vector | 'all' ]

  • Empty saveWaveFunctionTime uses the same values as in time for when to save the wave functions.
  • A positive scalar specifies the sampling time step between successive saving of the wave functions. For forward time propagation, it is equivalent to time(1):saveWaveFunctionTime:time(end), and for backward one to time(1):-saveWaveFunctionTime:time(end).
  • A negative integer specifies the number of propagation time steps between saving wave functions. For forward time propagation, it is equivalent to time(1):abs(saveWaveFunctionTime)\timeStep``:time(end), and for backward one to time(1):-abs(saveWaveFunctionTime)\timeStep``:time(end).
  • A vector provides user-defined times at which to save the wave functions.
  • 'all' saves the wave functions after every time step. Warning: generally discouraged as it likely results in very large memory requirements or cause an out-of-memory error -- see the warning above.
  • See the note on how intermediate time saving is performed during the TDCI propagation below.

Save the output of a functions of the wave function

This enables on-the-fly computation and saving of user-defined observables without having to save the CI object or the wave functions.

saveOutputFunction (sF)

Installable output function of the wave functions [ [] (default) | function handle ]

  • Leave empty to disable the feature.
  • Provide a function handle to enable the feature. The signature for the function is fun(CI,t), where CI is the CI model being propagated and t is the time (scalar). The function handle may return an array of arbitrary size and shape, but must return at least a scalar and the shape of the output must remain constant throughout the TDCI propagation.
  • Warning: The CI model is passed by reference to the output function. Thus modifying the CI object in the output function will also modify it for the CI model (and thus TDCI propagation) and will likely result in erroneous results or produce an error.

saveOutputFunctionTime (sFT)

Times at which to evaluate and save the installable output function of the wave functions [ [] (default) | positive scalar | negative integer | vector | 'all' ]

  • Empty saveOutputFunctionTime uses the same values as in time for when to evaluate and save the output function.
  • A positive scalar specifies the sampling time step between successive evaluation and saving of the output function. For forward time propagation, it is equivalent to time(1):saveOutputFunctionTime:time(end), and for backward one to time(1):-saveOutputFunctionTime:time(end).
  • A negative integer specifies the number of propagation time steps between evaluations and saving of the output function. For forward time propagation, it is equivalent to time(1):abs(saveOutputFunctionTime)\timeStep``:time(end), and for backward one to time(1):-abs(saveOutputFunctionTime)\timeStep``:time(end).
  • A vector provides user-defined times at which to evaluate and save the output function.
  • 'all' evaluates and saves the output function after every time step. Warning: this may be slow.
  • See the note on how intermediate time saving is performed during the TDCI propagation below.

Save restart data file

During the time propagation, a restart file can be generated to enable resuming the simulation if it is cut short. Stopping the TDCI simulation while it writes the restart info may lead to a corrupted file from which restart will not be possible. The restart file contains a copy of the TDCI-propagator and CI-model objects, respectively called TDCI and CI.

saveRestart (sRest)

Activate the generation of a restart file [ true | false (default) ]

saveRestartFileName (sRestF)

Name for the restart file [ character array (default 'QMolGrid--TDCI--Restart.mat') ]

  • saveRestartFileName must be a valid MATLAB file name ('.mat' extension).
  • saveRestartFileName is irrelevant when saveRestart == false .

saveRestartTime (sRestT)

Times at which to generate or update the restart file [ [] (default) | positive scalar | negative integer | vector | 'all' ]

  • Empty saveRestartTime uses the same values as in time for when to generate and update the restart file.
  • A positive scalar specifies the sampling time step when to generate and update the restart file. For forward time propagation, it is equivalent to time(1):saveRestartTime:time(end), and for backward one to time(1):-saveRestartTime:time(end).
  • A negative integer specifies the number of propagation time steps between the generation and update of the restart file. For forward time propagation, it is equivalent to time(1):abs(saveRestartTime)\timeStep``:time(end), and for backward one to time(1):-abs(saveRestartTime)\timeStep``:time(end).
  • A vector provides user-defined times at which to generate and update the restart file.
  • 'all' generates and updates the restart file after each time step. Warning: this is very slow and is strongly discouraged.
  • Note: In all cases, no restart file is generated for the initial time and final propagation time step.
  • See the note on how intermediate time saving is performed during the TDCI propagation below.

Output results

During a TDCI propagation, the results of on-the-fly calculations are stored in structures in the QMol_TDCI object. Note that QMol_TDCI does not interpolate its time propagation to fit user-supplied sample times. Instead, the results are saved at the closest propagation time steps, excluding duplicate times. This may result in sampled times that are different, or have a different (smaller) number of elements, from the ones specified above. Notably, using a sampling time that is not a multiple of the propagation time step may result in uneven saved time sampling. The actual times at with output are saved is included in each of the output structure.

When saveExternalField is true, each output-result structure includes the following fields:

  • outStructure.electricField contains the specific values for the electric field used in the TDCI propagation at the saved times.
  • In all cases, if the potential vector, electric field, or derivative of the electric field are calculated by the propagator during the simulations (see the decision tree below), those are included in outStructure.potentialVector, outStructure.electricField, and outStructure.electricFieldDerivative, respectively

In restart mode, each of the output structure contains a handful of additional fields to the ones listed below that are relevant for run-time calculations. These fields are saved in the MATLAB restart file but removed upon completion of the TDCI propagation.

outDipole (oDip)

Result of dipole-signal calculations during the TDCI propagation [ [] | structure ]

  • TDCI propagation that does not compute the dipole signal (saveDipole = false ) leaves outDipole empty. Otherwise:
  • outDipole.time defines the precise times at which the dipole signal is computed.
  • outDipole.waveFunction_x contains the dipole signal for selected wave functions. The indices of the wave functions associated with each of these are included in outDipole.indexWaveFunction.

outDipoleVelocity (oVel)

Result of dipole-velocity-signal calculations during the TDCI propagation [ [] | structure ]

  • TDCI propagation that does not compute the dipole signal (saveDipoleVelocity = false ) leaves outDipoleVelocity empty. Otherwise:
  • outDipoleVelocity.time defines the precise times at which the dipole velocity signal is computed.
  • outDipoleVelocity.waveFunction_x contains the dipole signal for selected wave functions. The indices of the wave functions associated with each of these are included in outDipoleVelocity.indexWaveFunction.

outDipoleAcceleration (oAcc)

Result of dipole-acceleration-signal calculations during the TDCI propagation [ [] | structure ]

  • TDCI propagation that does not compute the dipole signal (saveDipoleAcceleration = false ) leaves outDipoleAcceleration empty. Otherwise:
  • outDipoleAcceleration.time defines the precise times at which the dipole acceleration signal is computed.
  • outDipoleVelocity.waveFunction_x contains the dipole signal for selected wave functions. The indices of the wave functions associated with each of these are included in outDipoleAcceleration.indexWaveFunction.

outEnergyCI (oECI)

Result of the CI-energy calculations during the TDCI propagation [ [] | structure ]

  • TDCI propagation that does track the CI energy (saveEnergySE = false ) leaves outEnergySE empty. Otherwise:
  • outEnergyCI.time defines the precise times at which the CI energies are computed.
  • outEnergyCI.total contains the total Schrödinger-equation energy, which should be constant (within the precision of the propagation scheme).
  • outEnergyCI.Hamiltonian contains the field-free Hamiltonian (kinetic plus potential) component.
  • outEnergyCI.externalField contains the energy contribution from the driving electric field in the length gauge.
  • outEnergyCI.autonomization contains the energy brought in and out of the system by the external driving field (if any).

outEnergyWaveFunction (oEWfcn)

Result of the wave-function-energy calculations during the TDCI propagation [ [] | structure ]

  • TDCI propagation that does track the CI energy (saveEnergyWaveFunction = false ) leaves outEnergyWaveFunction empty. Otherwise:
  • For a wave function $|\psi \rangle$ , the energy is defined as $\langle \psi |\hat{\mathcal{H}} |\psi \rangle$ with $\hat{\mathcal{H}}$ the CI Hamiltonian operator.
  • outEnergyWaveFunction.time defines the precise times at which the wave function energies are computed.
  • Each row of outEnergyWaveFunction.waveFunction contains the energies of the corresponding wave functions.

outIonization (oIon)

Result of the ionization calculations during the TDCI propagation [ [] | structure ]

  • TDCI propagation that does track ionization (saveIonization = false ) leaves outIonization empty. Otherwise:
  • outIonization.time defines the precise times at which the ionization is computed.
  • outIonization.waveFunction contains the ionization for the selected wave functions. The indices of the wave functions associated with each of these are included in outIonization.indexWaveFunction.

outWaveFunction (oWfcn)

Wave functions during the TDCI propagation [ [] | structure ]

  • TDCI propagation that does not save the wave function (saveWaveFunction = false ) leaves outWaveFunction empty. Otherwise:
  • The specific shape of the saved wave functions is implementation dependent -- see the corresponding documentation for details. At minimum, each implementation defines:
  • outWaveFunction.time defines the precise times at which the wave functions are saved.
  • outWaveFunction.waveFunction contains the saved wave functions and outWaveFunction.indexWaveFunction the corresponding wave-function indices.

outOutputFunction (oF)

Result of the installable output function of the wave functions [ [] | structure ]

  • TDCI propagation that does not define an installable output function (saveOutputFunction = [] ) leaves outOutputFunction empty. Otherwise:
  • outOutputFunction.time defines the precise times at which the result of the output function is saved.
  • outOutputFunction.result contains the results of the output function. If the installable function returns a scalar or a column vector, outOutputFunction.result is a N-by-numel(outOutputFunction.time) matrix with N the number of elements in the output. Otherwise, outOutputFunction.result is an M-by-numel(outOutputFunction.time) array with M the size of the output.
  • outOutputFunction.shape contains the shape of the output function (N or M, as defined in the previous bullet point).

Class methods

Creation

constructor

Create a sixth-order optimized Blanes and Moan [Blanes 2002] TDCI-propagator object with empty class properties.

obj = QMol_TDCI_SSO_6BM;

Create a TDCI-propagator object with the name properties set to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the TDCI class properties and is case insensitive.

obj = QMol_TDCI_SSO_6BM(name1,value1);
obj = QMol_TDCI_SSO_6BM(name1,value1,name2,value2,___);

Changing class properties

set

Update the name properties of a TDCI-model object to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the TDCI class properties and is case insensitive. In restart mode, output result structures can also be edited with set. QMol_TDCI does not check the integrity of its input/output component during a restart and this feature should only be considered by advanced users.

obj.set(name1,value1);
obj.set(name1,value1,name2,value2,___);

This is the common name-value pair assignment method used throughout the QMol-grid package.

clear

Clear all class properties.

obj.clear;

Clear a specific set of the class properties. Suitable name is any of the TDCI class properties and is case insensitive.

obj.clear(name1,name2,___);

This is the common clear method available to all classes throughout the QMol-grid package. The clear method can be used to delete specific properties before saving an instance of the TDCI propagators class and propagation results.

Initializing the object

initialize

Initialize a sixth-order optimized Blanes and Moan [Blanes 2002] TDCI-propagator object without allocating the output-result structures.

obj.initialize(CI);
  • CI is the CI-model handle object that describes the CI systems to propagate.

Run-time documentation

getMemoryProfile

Get an estimate of the memory help by a QMol_TDCI_SSO_6BM object with either

mem = obj.getMemoryProfile;
mem = obj.getMemoryProfile(false);
  • The object must be initialized for the memory footprint evaluation. If not already, getMemoryProfile initializes the CI model object.
  • The estimate includes the (1) CI model, (2) TDCI propagator, and (3) output results. Note that all these components may not be used in actual simulations and the memory estimate tries to be conservative. On the other hand, it only includes the discretization of member components on the domain grid and ignores other (expectedly small) properties.
  • The output mem is the estimated size in bytes.

Additionally display the detail of the memory footprint with

mem = obj.getMemoryProfile(true);

showDocumentation

Display the run-time documentation for the specific configuration of a QMol_TDCI_SSO_6BM object, which must have been initialized beforehand

obj.showDocumentation;

TDCI propagation

propagate

Propagate the TDCI dynamics starting from a CI model object (from scratch).

obj.propagate(CI);
  • CI is the CI-model handle object that describes the CI systems to propagate.
  • Neither the TDCI-propagation obj nor the CI-model CI objects need be initialized. In all cases both are (re)initialized at the beginning of the TDCI propagation to ensure proper and consistent linkage and setup between them.

Restart a TDCI propagation.

obj.propagate('restart');
  • This can be performed after loading the corresponding restart MATLAB file into the workspace.

Choice of gauge

TDCI propagators only support length gauge

External-field components used in simulations

Depending on the types of input, not all provided external-field may be used in the simulations. For the potential vector and electric field -- recall that electricField and potentialVector are repackaged into externalField at the beginning of the simulation:

  • If both are provided as function handles, then externalField``.electricField is called whenever the values for the electric field are required. Otherwise,
  • If externalField``.potentialVector provided as a function handle, then the electric field is computed from it (see below for details on how this is done). Otherwise,
  • If externalField``.electricField is a griddedInterpolant then it is used to compute the electric field. Otherwise,
  • It externalField``.potentialVector is a griddedInterpolant then it is used to compute both the electric field.
  • If none of the externalField``.electricField and externalField``.potentialVector are defined, the TDCI propagation is performed field free irrespective of the choice of externalFieldGauge and even if an externalField``.electricFieldDerivative is defined.

The choice of ignoring some (interpolated) input fields is made to ensure the self-consistency of the TDCI dynamics, and associated observables, during the numerical propagation. To force using an interpolated field input, one can encapsulate it into a function handle @(t) interpolatedField(t).

For the electric-field derivative:

  • If externalField``.electricFieldDerivative is defined as a function handle, then externalField``.electricFieldDerivative is called when the derivative of the electric field is required.
  • Otherwise the electric-field derivative is numerically computed from externalField``.electricField or externalField``.potentialVector, depending on which field component(s) are being used in the TDCI propagation.

Numerical computation of missing or ignored field components:

  • Where required, the potential vector is computed from the electric field using a Simpson's 1/3 quadrature rule.
  • Where required, the electric field is computed from the potential vector using a second-order centered finite difference with diffDT time step.
  • Where required, the electric field derivative is computed from the electric field or the potential vector using a second-order centered finite difference with diffDT time step.

Examples

See the main documentation page for examples of TDCI simulations with various output computations.

Test suite

For consistency with the rest of the QMol-grid package, QMol_TDCI_SSO_6BM defines an associated test suite. Run the test suite for the class in normal or summary mode respectively with

QMol_test.test('TDCI_SSO_6BM');
QMol_test.test('-summary','TDCI_SSO_6BM');

References

[Blanes 2002] S. Blanes and P.C. Moan, "Practical symplectic partitioned Runge-Kutta and Runge-Kutta-Nystrom methods," Journal of Computational and Applied Mathematics 142, 313 (2002).

[Mauger 2024] F. Mauger, C. Chandre, M.B. Gaarde, K. Lopata, and K.J. Schafer, "Hamiltonian formulation and symplectic split-operator schemes for time-dependent density-functional-theory equations of electron dynamics in molecules," Communications in Nonlinear Science and Numerical Simulation 129, 107685 (2024).

Notes

  • QMol_TDCI_SSO_6BM was introduced in version 01.23