Parent class for time-dependent Schrödinger-equation theory (TDSE) model objects.

QMol_TDSE defines an abstract class for the time propagation of Schrödinger-equation (SE) models. It is designed to be agnostic of (i) the model dimension and (ii) the chosen discretization (Cartesian grid or basis). These are to be handled by the specific TDSE-implementation classes and their components.

QMol_TDSE defines many properties and methods. Here we only document the ones visible to end users and implementation-specific overloading classes (public or protected access attributes). We provide a quick overview of the requirements of implementation-specific classes for defining actual TDSE propagation schemes.

Description

Class properties

 Time propagation

 Save the Schrödinger-equation object into individual files

 Save the dipole, dipole velocity, and dipole acceleration signals

 Save the external field information

 Save the ionization signal

 Save restart data file

 Output results

 Other hidden class properties

Class methods

 Creation

  constructor

 Changing class properties

 Initializing the object

 Run-time documentation

 TDSE propagation

Overloading the class

 Methods that must be overloaded

 Additional optional methods to overload

Boundary absorber

 Mask function

 Complex absorbing potential (CAP)

Test suite

Notes

Whether to display progress of the TDSE calculations as they go on [ true (default) | false ]

Time propagation vector [ vector (default []) ]

• In all TDSE 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 TDSE propagations is set independently of T.

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

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

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 at the edges of the domain.
• Empty absorbingBoundary does not implement any absorbing boundary method and any part of the wave packet reaching the edges of the domain will be reflected (or artificially reappears on the other side of the domain through periodic effects).
• 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. See below for details on the required interface for absorbing mask classes.
• Complex absorbing potentials (CAPs) are integrated within the propagation scheme, as an imaginary potential term that causes exponential decay of the wave packet at the edges. Under the right circumstances, CAPs can preserve the order of the propagation schemes. See below for details on the required interface for CAP classes.

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

• Empty externalField performs field-free TDSE simulations.
• The specific type and interface for compatible field objects is left to the implementation-specific TDSE propagator -- see the corresponding documentation for details.

During the time propagation, copies of the Schrödinger-equation object can be saved in separate MATLAB files.

Activate saving the Schrödinger-equation object into separate files [ true | false (default) ]

Name for the files in which the Schrödinger-equation objects are saved [ character array (default 'QMolGrid--TDSE--SE') ]

• The Schrödinger-equation objects saved at different times are put in separate MATLAB (.mat) file, with names starting with saveSEFileName 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 saveSEFileName
• saveSEFileName is irrelevant when saveSE == false

Times at which to save the Schrödinger-equation object into a file [ [] (default) | positive scalar | negative integer | vector | 'all' ]

• Empty saveSETime uses the same values as in time for when to save the Schrödinger-equation object into MATLAB files.
• A positive scalar specifies the sampling time step when to save the Schrödinger-equation object into MATLAB files. For forward time propagation, it is equivalent to time(1):saveSETime:time(end), and for backward ones to time(1):-saveSETime: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(saveSETime)*timeStep:time(end), and for backward ones to time(1):-abs(saveSETime)*timeStep:time(end).
• A vector provides user-defined times at which to save the Schrödinger-equation 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 TDSE propagation below.

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

Index of the wave functions for which to compute the orbital-resolved 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 orbital-resolved dipole signal in an index vector
• Empty or 'all' saveDipoleWaveFunctionIndex computes the orbital-resolved dipole for all wave functions

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 ones 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 ones 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 is may be slow.
• See the note on how intermediate time saving is performed during the TDSE propagation below.

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

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

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 ones 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 ones 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 is may be slow.
• See the note on how intermediate time saving is performed during the TDSE propagation below.

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

Index of the Kohn-Sham orbitals for which to compute the orbital-resolved 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

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 ones 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 ones 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 is may be slow.
• See the note on how intermediate time saving is performed during the TDSE propagation below.

Whether to track the Schrödinger-equation energy during the TDSE propagation [ true | false (default) ]

Times at which to compute and save the Schrödinger-equation energy [ [] (default) | positive scalar | negative integer | vector | 'all' ]

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

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

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

• For a wave function $|\psi \rangle$ , the orbital energy is defined as $\langle \psi |\hat{\mathcal{H}} |\psi \rangle$ with $\hat{\mathcal{H}}$ the Schrödinger-equation Hamiltonian operator.
• 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 ones 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 ones 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 is may be slow.
• See the note on how intermediate time saving is performed during the TDSE propagation below.

For TDSE simulation with and external driving field, save the external field in 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 (except outSE).
• For practical reasons, the values for the external driving field may be slightly different than that of externalField. This features enables keeping the actual external-field values used throughout the propagation.

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

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

Index of the wave functions for which to compute the orbital-resolved 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

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 ones 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 ones 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 is may be slow.
• See the note on how intermediate time saving is performed during the TDSE propagation below.

Warning: The memory requirements for saving the wave function throughout the TDSE 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 Schrödinger-equation object in separate files, or if only the result of a specify calculation on the wave function is required consider consider using an installable output function.

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

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

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 ones 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 ones 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 TDSE propagation below.

Whether to save the projection of the wave functions onto a specific basis during the TDSE propagation [ true | false (default) ]

Projection basis [ [] (default) | basis ]

• Empty saveWaveFunctionProjectionBasis uses the initial wave functions as the projection basis
• User-defined basis is implementation dependent -- see the respective documentations for details

Index of the wave functions for which to perform the projection [ [] (default) | index vector | 'all' ]

• This is irrelevant if saveWaveFunctionProjection is false
• Empty saveWaveFunctionProjectionIndex disables saving of the wave functions and is technically equivalent to saveWaveFunctionProjection = false
• Specify the indexes of the wave functions for which to perform the projection in an index vector
• 'all' saves the projection for all the wave functions

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

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

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(wfcn,t) where wfcn is a wave function object 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 TDSE propagation.
• Warning: The Schrödinger-equation model wave functions are passed by reference to the output function. Thus modifying the wave functions in the output function will also modify them for the Schrödinger-equation model (and thus TDSE propagation) and will likely result in erroneous results or produce an error.

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 ones 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 ones 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 TDSE propagation below.

During the time propagation, a restart file can be generated to enable resuming the simulation if it is cut short. Stopping the TDSE 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 TDSE-propagator and Schrödinger-equation-model objects, respectively called TDSE and SE in the MATLAB restart file.

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

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

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

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 ones 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 ones 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 TDSE propagation below.

During a TDSE propagation, the results of on-the-fly calculations are stored in structures in the QMol_TDSE object. Note that QMol_TDSE 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, than 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.

In restart mode, each output structure in the QMol_TDSE object contains the fields ind and n, respectively with the propagation time indexes at which to save the associated results and the next index in ind at which saving should be performed. These two fields are removed from each output structure upon completion of the TDSE propagation.

Support for saving the Schrödinger-equation object into individual MATLAB files during propagation [ [] (default) | structure ]

• outSE is only relevant during TDSE time propagation and in restart mode. It is automatically cleared at the end of the propagation.

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

• TDSE propagation that do not compute the dipole signal (saveDipole = false ) leave 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 indexes of the wave functions associated with each of these are included in outDipole.indexWaveFunction
• In restart mode, outDipole also contains a handful of additional fields relevant for run-time calculations. These fields are saved in the MATLAB restart file but removed upon completion of the TDSE propagation.

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

• TDSE propagation that do not compute the dipole signal (saveDipoleVelocity = false ) leave 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 indexes of the wave functions associated with each of these are included in outDipoleVelocity.indexWaveFunction
• In restart mode, outDipoleVelocity also contains a handful of additional fields relevant for run-time calculations. These fields are saved in the MATLAB restart file but removed upon completion of the TDSE propagation.

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

• TDSE propagation that do not compute the dipole signal (saveDipoleAcceleration = false ) leave 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 indexes of the wave functions associated with each of these are included in outDipoleAcceleration.indexWaveFunction
• In restart mode, outDipoleAcceleration also contains a handful of additional fields relevant for run-time calculations. These fields are saved in the MATLAB restart file but removed upon completion of the TDSE propagation.

Result of the Schrödinger-equation-energy calculations during the TDSE propagation [ [] | structure ]

• TDSE propagation that do track the Schrödinger-equation energy (saveEnergySE = false ) leave outEnergySE empty. Otherwise
• outEnergySE.time defines the precise times at which the Schrödinger-equation energies are computed
• outEnergySE.total contains the total Schrödinger-equation energy, which should be constant (within the precision of the propagation scheme)
• outEnergySE.kinetic contains the kinetic-energy component, including the driving-field potential vector in the velocity gauge.
• outEnergySE.potential contains the potential-energy component.
• outEnergySE.externalField contains the energy contribution from the driving electric field in the length gauge.
• outEnergySE.autonomization contains the energy brought in and out of the system by the external driving field (if any).
• In restart mode, outEnergySE also contains a handful of additional fields relevant for run-time calculations. These fields are saved in the MATLAB restart file but removed upon completion of the TDSE propagation.

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

• TDSE propagation that do track the Schrödinger-equation energy (saveEnergyWaveFunction = false ) leave outEnergyWaveFunction empty. Otherwise
• 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 Schrödinger-equation Hamiltonian operator. In the velocity gauge, the external potential vector is accounted for in the kinetic-operator of $\hat{\mathcal{H}}$ while, in the length gauge, the external electric field is ignored.
• 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
• In restart mode, outEnergyWaveFunction also contains a handful of additional fields relevant for run-time calculations. These fields are saved in the MATLAB restart file but removed upon completion of the TDSE propagation.

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

• TDSE propagation that do track ionization (saveIonization = false ) leave 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 indexes of the wave functions associated with each of these are included in outIonization.indexWaveFunction
• In restart mode, outIonization also contains a handful of additional fields relevant for run-time calculations. These fields are saved in the MATLAB restart file but removed upon completion of the TDSE propagation.

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

• TDSE propagation that do not save the wave function (saveWaveFunction = false ) leave 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 indexes
• In restart mode, outWaveFunction also contains a handful of additional fields relevant for run-time calculations. These fields are saved in the MATLAB restart file but removed upon completion of the TDSE propagation.

Projection of the wave functions during the TDSE propagation [ [] | structure ]

• TDSE propagation that do not save the projection of the wave functions (saveWaveFunctionProjection = false ) leave outWaveFunctionProjection empty. Otherwise
• The specific shape of the saved wave functions' projection is implementation dependent -- see the corresponding documentation for details. At minimum, each implementation defines
• outWaveFunctionProjection.time defines the precise times at which the wave function projections are saved
• outWaveFunctionProjection.waveFunction contains the saved wave functions' projection and outWaveFunctionProjection.indexWaveFunction the corresponding wave function indexes
• The structure also retains a copy of the projection basis as QMol_disc_basis object(s)
• In restart mode, outWaveFunctionProjection also contains a handful of additional fields relevant for run-time calculations. These fields are saved in the MATLAB restart file but removed upon completion of the TDSE propagation.

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

• TDSE propagation that do not define an installable output function of the orbitals (saveOutputFunction = [] ) leave 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).

Support for enabling restart of the TDSE propagation [ [] (default) | structure ]

• outRestart is only relevant during TDSE time propagation and in restart mode. It is automatically cleared at the end of the propagation.

QMol_TDSE defines a handful of additional hidden properties used for the time propagation. These properties cannot be edited with the set method, nor by any function outside of the object (SetAccess=protected attribute).

Schrödinger-equation-model object [ [] (default) | QMol_SE handle object ]

• This is a copy of the Schrödinger-equation-model handle object passed to initialize.

Propagation time vector [ [] (default) | vector ]

• After the class is initialized, it is defined as uniquetol([obj.T(1):obj.dt:obj.T(end), obj.T(end)],1e-10,'DataScale',1)

Indexes of tspan matching the input time vector T [ [] (default) | index vector ]

• After the class is initialized, it is defined as getOutputIndex(T)

Restart structure [ [] (default) | restart ]

• Collect all the variables and information required for the restart mode
• QMol_TDSE uses the following fields (therefore not available for implementation-specific TDSE propagators overloading the class): kstart, ndisp, and idp

Create a TDSE-model object with empty class properties.

obj = QMol_TDSE;

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

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

Update the name properties of a TDSE-model object to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the TDSE class properties and is case insensitive. In restart mode, output results structures can also be edited with set. QMol_TDSE 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 all class properties

obj.clear;

Clear a specific set of the class properties. Suitable name is any of the TDSE 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 QMol_TDSE class.

QMol_TDSE defines a main initialize interface (with public access attribute) and a suite of individual initialization properties (with protected access attributes) for each of the output results.

Initialize a TDSE-model object without allocating the output-result structures

obj.initialize(SE);

• SE is the Schrödinger-equation-model handle object, i.e., QMol_SE, that describes the Schrödinger-equation systems to propagate.
• For developers: initialize also has a specific interface when called from the propagate method that initializes the absorbing boundaries (if any) and determines whether the output-result structures should be initialized too. Overloading classes should avoid redefining initialize; If the overloading class needs to perform some initialization (at the beginning of a TDSE propagation or upon restart), overload the initializeChildren method instead.

Initialize implementation-specific part of overloading class at the beginning of a TDSE propagation (from scratch)

obj.initializeChildren(false);

• QMol_TDSE calls the initializeChildren method after having initialized all its member properties (including the SE object being propagated).
• This should not initialize implementation-specific additional output, which are initialized with setOutputChildren

Initialize implementation-specific part of overloading class in restart mode.

obj.initializeChildren(true);

• QMol_TDSE calls the initializeChildren method after having reinitialized all its member properties (including the SE object being propagated).
• Note that the restart mode does not call setTimeStep during the initialization. All relevant time step information should be stored with the class of in the restart structure and initializeChildren should bring them back to a working configuration.

Get the time-propagation index for when to save a given result.

ind = obj.getOutputIndex(t);

• Vector t = [t_1, t_2, ___ ] returns the indexes of the iteration time steps closest to the listed times t_1, t_2, ...
• Scalar t > 0 returns the indexes of the iteration time steps closest to the time sampling time(1), time(1)+t, time(1)+2*t, ... for forward time propagations and time(1), time(1)-t, time(1)-2*t, ... for backward ones
• Integer t < 0 returns the indexes of the iteration time steps of time(1), time(1)-timeStep*t, time(1)-2*timeStep*t, ... for forward time propagations and time(1), time(1)+timeStep*t, time(1)+2*timeStep*t, ... for backward ones

ind = obj.getOutputIndex('all');

• Returns the indexes associated with all the iteration time steps

Initialize additional output results defined in an specific implementation of the TDSE propagator (the children class should then overload this method)

obj.setOutputChildren('init');

Cleanup the additional output results defined in an specific implementation of the TDSE propagator at the end of the computation

obj.setOutputChildren('clean');

setOutputChildren should not be called in restart mode (all relevant parameters should be saved with the QMol_TDSE object in the restart MATLAB file).

Initialize the outSE structure before running a TDSE computation

obj.setOutputSE('init');

Cleanup the outSE structure at the end of the TDSE computation

obj.setOutputSE('clean');

setOutputSE should not be called in restart mode (all relevant parameters should be saved with the QMol_TDSE object in the restart MATLAB file).

Initialize the outDipole, outDipoleVelocity, and outDipoleAcceleration structures before running a TDSE computation

obj.setOutputDipole('init');

Cleanup the outDipole, outDipoleVelocity, and outDipoleAcceleration structures at the end of the TDSE computation

obj.setOutputDipole('clean');

setOutputDipole should not be called in restart mode (all relevant parameters should be saved with the QMol_TDSE object in the restart MATLAB file).

Initialize the outEnergySE and outEnergyWaveFunction structures before running a TDSE computation

obj.setOutputEnergy('init');

Cleanup the outEnergySE and outEnergyWaveFunction structures at the end of the TDSE computation

obj.setOutputEnergy('clean');

setOutputEnergy should not be called in restart mode (all relevant parameters should be saved with the QMol_TDSE object in the restart MATLAB file).

Initialize the outOutputFunction structure before running a TDSE computation

obj.setOutputFunction('init');

Cleanup the outOutputFunction structure at the end of the TDSE computation

obj.setOutputFunction('clean');

setOutputFunction should not be called in restart mode (all relevant parameters should be saved with the QMol_TDSE object in the restart MATLAB file).

Initialize the outIonization structure before running a TDSE computation

obj.setOutputIonization('init');

Cleanup the outIonization structure at the end of the TDSE computation

obj.setOutputIonization('clean');

setOutputIonization should not be called in restart mode (all relevant parameters should be saved with the QMol_TDSE object in the restart MATLAB file).

Initialize the outWaveFunction and outWaveFunctionProjection structures before running a TDSE computation

obj.setOutputWaveFunction('init');

Cleanup the outWaveFunction and outWaveFunctionProjection structures at the end of the TDSE computation

obj.setOutputWaveFunction('clean');

setOutputWaveFunction should not be called in restart mode (all relevant parameters should be saved with the QMol_TDSE object in the restart MATLAB file).

setOutputWaveFunction is implementation dependent and must be defined by each overloading TDSE propagation classes -- see the required signature and behavior below.

Initialize the outRestart structure before running a TDSE computation

obj.setOutputRestart('init');

Cleanup the outRestart structure and delete the restart file at the end of the TDSE computation

obj.setOutputRestart('clean');

setOutputRestart should not be called in restart mode (all relevant parameters should be saved with the QMol_TDSE object in the restart MATLAB file).

At the end of a TDSE propagation, performs the appropriate finalization, including cleanup of the output structures.

obj.finalize;

• This calls the 'clean' mode for setOutputChildren, setOutputSE, setOutputDipole, setOutputEnergy, setOutputIonization, setOutputWaveFunction, setOutputFunction, and setOutputRestart.

Get an estimate of the memory help by a QMol_TDSE 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 SE model object.
• The estimate includes (1) SE model, (2) TDSE 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 (small) properties.
• The output mem is the estimated size in bytes.

Additionally display the detail of the memory footprint with

mem = obj.getMemoryProfile(true);

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

obj.showDocumentation;

The run-time documentation performs the following steps

• Display the QMol-grid package header (showing the kernel, external component versions)
• Call the TDSE-propagator implementation-specific run-time documentation with the property showDoc.
• Display the time-propagation information
• Display the list of output calculated and saved during the TDSE propagation
• Display the bibliography associated with the list of cited references (from the previous steps)
• Display the funding information
• Display the QMol-grid package footer

Propagate the TDSE dynamics starting from a Schrödinger-equation model object (from scratch)

obj.propagate(SE);

• SE is the Schrödinger-equation-model handle object, i.e., QMol_SE, that describes the Schrödinger-equation systems to propagate.

Restart a TDSE propagation

obj.propagate('restart');

Trigger the saving of the SE object into a separate MATLAB file

obj.saveOutputSE(obj,t);

• t is the current time when the saving is performed
• Each output file contains SE (Schrödinger-equation-model object), t (current time), and externalField (external field object)
• For developers: saveOutputSE is also responsible for updating the counter obj.oSE.n when it is called

Trigger the saving of the Schrödinger-equation and wave function energies

obj.saveOutputEnergy(k,t);

• k is the current time-propagation step index
• t is the current time when the saving is performed
• If requested, the Schrödinger equation energy calls getExternalFieldEnergy to get the contribution from any external field and autonomization variable

Trigger the computation and saving of the installable output function

obj.saveOutputFunction(obj,k,t);

• k is the current time-propagation step index
• t is the current time when the saving is performed
• For developers: saveOutputFunction is also responsible for updating the counter obj.oFRho.n and obj.oFKSO.n when it is called

QMol_TDSE is an abstract class and only define the common steps and features for all TDSE propagators. Implementation-specific propagators must define specific methods and additional optional methods overload

To define a specific implementation of a TDSE propagation scheme, overloading classes must define the following methods with the specified signature and attributes

To enable name-value pair constructor, name-value pair set, and the clear methods

methods (Static=true,Access=?QMol_suite)
function [ClassName,PropNames] = propertyNames()
%propertyNames returns the names of member properties that can be set
%   through name-value assignment
    
    % Parent-class components
    [~,PropNames]       =   QMol_TDSE.propertyNames;

    ClassName           =   'QMol_child_class';
    PropNames           =   [PropNames,{'property1','property2'}];
end
end

Display the run-time documentation for the specific implementation of the TDSE propagator

methods (Access=protected)
function ref = showDoc(obj)
%showDoc displays the documentation reflecting the specific implementation
%   of the TDSE propagator
    
    % Add specific documentation here

end
end

• If no reference is cited, return ref = {} otherwise ref = {'ref 1','ref 2',___}, where each of the ref corresponds to the bibliographic code for the reference (generally of the form 'name_of_first_author publication_year') and is case insensitive -- see the documentation page for a list of citable references.
• Note that only implementation-specific properties should be covered here. All properties common to all TDSE propagators (e.g., time step) are handled in the parent QMol_TDSE class run-time documentation.
• Only document the TDSE propagator. If additional output are implemented, document those with the docOutputChildren method

Initialize the outWaveFunction and outWaveFunctionProjection structures before running a TDSE computation and clean them up at the end of the computation. The method should have the following signature and features

methods (Access=protected)
function setOutputWaveFunction(obj,opt)
%setOutputOrbitalDensity

switch lower(opt)
case {'init','initialize','initialization'} %%%%%%%%%%%%%%%%%%%%%%%%%%%
 
    % Clean up any old data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    obj.oWfcn           =   [];
    obj.oWfcnP          =   [];
    
    % Wave functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    if obj.sWfcn
        % When to save the wave functions
        obj.oWfcn.ind   =   [obj.getOutputIndex(obj.sWfcnT),NaN];
        obj.oWfcn.time  =   obj.tspan(obj.oWfcn.ind(1:end-1));
        obj.oWfcn.n     =   1;

        if obj.sEF,         obj.setOutputExternalField('oWfcn','init');  end
        
        S               =   obj.SE.disc.SE_sizeWaveFunction;
        if numel(S) > 1   &&   S(end) == 1,     S   =   S(1:end-1);     end
        
        % Indexes
        if isempty(obj.sWfcnI),         obj.oWfcn.indexWaveFunction =   [];
        elseif ischar(obj.sWfcnI),                                                                  if strcmpi(obj.sWfcnI,'all')
                                        obj.oWfcn.indexWaveFunction =   1:obj.SE.N;                 else
                                        obj.oWfcn.indexWaveFunction =   [];
                                        warning('QMol:TDSE:saveWfcn', ...
                                            ['Unknown option for the saving of the wave functions ' obj.sKSOI ...
                                            '. No orbitals saved.']);                               end
        else,                           obj.oWfcn.indexWaveFunction =   obj.sWfcnI;
        end

        % Allocate output
        obj.oWfcn.shape         =   [S numel(obj.oWfcn.indexWaveFunction)];
        obj.oWfcn.waveFunction  =   NaN([obj.oWfcn.shape numel(obj.oWfcn.time)],'like',1i);

    else
        obj.oWfcn.shape =   [];
        obj.oWfcn.ind   =   NaN;
        obj.oWfcn.n     =   1;
    end
    
    % Wave functions' projection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    if obj.sWfcnP
        % When to save the wave function projections
        obj.oWfcnP.ind  =   [obj.getOutputIndex(obj.sWfcnPT),NaN];
        obj.oWfcnP.time =   obj.tspan(obj.oWfcnP.ind(1:end-1));
        obj.oWfcnP.n    =   1;

        if obj.sEF,         obj.setOutputExternalField('oWfcnP','init');    end
        
        % Projection basis
        if isempty(obj.sWfcnB)  % Project on initial wave functions
            obj.oWfcnP.basis    =   QMol_disc_basis('x',obj.SE.disc.x,'v',obj.SE.wfcn.wfcn);
            obj.oWfcnP.basis.initialize;
        else
            obj.oWfcnP.basis    =   obj.sWfcnB;
            obj.oWfcnP.basis.initialize;
        end

        % Indexes 
        S               =   obj.oWfcnP.basis.SE_sizeWaveFunction;
        if numel(S) > 1   &&   S(end) == 1,     S   =   S(1:end-1);   end

        if isempty(obj.sWfcnPI),        obj.oWfcnP.indexWaveFunction    =   [];
        elseif ischar(obj.sWfcnPI),                                                     if strcmpi(obj.sWfcnPI,'all')
                                        obj.oWfcnP.indexWaveFunction    =   1:obj.SE.N; else
                                        obj.oWfcnP.indexWaveFunction    =   [];
                                        warning('QMol:TDSE:saveWfcnProjection', ...
                                            ['Unknown option for the saving of the wave functions'' projection ' obj.sWfcnPI ...
                                            '. No wave function projections saved.']);  end
        else,                           obj.oWfcnP.indexWaveFunction    =   obj.sWfcnPI;
        end

            % Allocate output
            obj.oWfcnP.shape        =   [S numel(obj.oWfcnP.indexWaveFunction)];
            obj.oWfcnP.waveFunction =   NaN([obj.oWfcnP.shape numel(obj.oWfcnP.time)],'like',1i);

    else
        obj.oWfcnP.shape    =   [];
        obj.oWfcnP.ind      =   NaN;
        obj.oWfcnP.n        =   1;
    end
    
case {'clean','finalize','finalization'} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    if obj.sWfcn,   obj.oWfcn   =   rmfield(obj.oWfcn,{'ind','n','shape'}); if obj.sEF %#ok<ALIGN> 
                    obj.setOutputExternalField('oWfcn' ,'clean');           end
    else,           obj.oWfcn   =   [];                                     end
    if obj.sWfcnP,  obj.oWfcnP  =   rmfield(obj.oWfcnP,{'ind','n','shape'});if obj.sEF %#ok<ALIGN> 
                    obj.setOutputExternalField('oWfcnP','clean');           end
    else,           obj.oWfcnP   =   [];                                    end
 
otherwise %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    % Unexpected option
    error('QMol:TDSE:setOutputWaveFunction',['Unknown option ' opt]);
end
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
end

At minimum, the method should initialize

• In obj.oWfcn, outWaveFunction.time, outWaveFunction.waveFunction, and outWaveFunction.indexWaveFunction
• In sWfcnP, outWaveFunctionProjection.time, outWaveFunctionProjection.waveFunction, and outWaveFunctionProjection.indexWaveFunction. The structure should also retain a copy of the projection basis.

(Re)set the time step to be used in the TDSE propagation

methods (Access=protected)
function setTimeStep(obj,dt,t)
%setTimeStep
    
    % Perform the proper (re)initialization 

end
end

• dt is the value of the time step to be used and t the current time. Implementation-specific TDSE propagators will often need to keep a copy of dt (as it may vary from timeStep).
• setTimeStep is called at the very beginning of the TDSE propagation and
• setTimeStep may also be called before performing the last iteration if a rescaling is required to reach the requested final time

Propagate the TDSE dynamics for exactly one time step

methods (Access=protected)
function applyTimeStep(obj,t)
%setTimeStep
    
    % Perform the time propagation

end
end

• t is the current time, from which to perform the one-time-step propagation

Save the dipole, dipole velocity, and/or dipole acceleration signal

methods (Access=protected)
function saveOutputDipole(obj,k,t)
%setTimeStep
    
    % Save the dipole signal
    if k == obj.oDip.ind(obj.oDip.n)
        % Total dipole

        % Orbital-resolved dipole (if any)
        
        % Add external field
        if obj.sEF,         obj.addOutputExternalField('oDip',k,t);         end

        % Update counter
        obj.oDip.n      =   obj.oDip.n + 1;
    end
    
    % Save the dipole-velocity signal
    if k == obj.oVel.ind(obj.oVel.n)
        % Total dipole velocity

        % Orbital-resolved dipole velocity (if any)
        
        % Add external field
        if obj.sEF,         obj.addOutputExternalField('oVel',k,t);         end

        % Update counter
        obj.oVel.n      =   obj.oVel.n + 1;
    end
    
    % Save the dipole acceleration signal
    if k == obj.oAcc.ind(obj.oAcc.n)
        % Total dipole acceleration

        % Orbital-resolved dipole acceleration (if any)
        
        % Add external field
        if obj.sEF,         obj.addOutputExternalField('oAcc',k,t);         end

        % Update counter
        obj.oAcc.n      =   obj.oAcc.n + 1;
    end

end
end

• saveOutputDipole is called is any of the dipole, dipole velocity, or dipole acceleration needs to be computed and saved. It must therefore determine which one(s) actually need to be.
• saveOutputDipole is also responsible for updating the counters in obj.oDip, obj.oVel and obj.oAcc (see their respective documentation entry for the name convention in what/how each should be saved).

Compute the contributions from any external field and autonomization variable

methods (Access=protected)
function [E,DE] = getExternalFieldEnergy(obj,t)
%getExternalFieldEnergy 
    
    % External field energy

    % Autonomization variable

end
end

• E is the contribution to the Schrödinger-equation-functional energy from any external field. If not field is applied, or it does not contribute an explicit terms to the Schrödinger-equation energy (e.g., velocity-gauge dipole approximation), return E = [0;0]
• DE is the autonomization energy variable, which tracks how much energy is put into or withdrawn from the Schrödinger-equation system

Compute the ionization statistics

methods (Access=protected)
function saveOutputIonization(obj,k,t)
%saveOutputIonization 
    
    % Total ionization signal

    % Orbital-resolved ionization signal
        
    % Add external field
    if obj.sEF,         obj.addOutputExternalField('oIon',k,t);         end

    % Update counter
    obj.oIon.n      =   obj.oIon.n + 1;

end
end

• saveOutputIonization is also responsible for updating the counters in obj.oIon (see the documentation entry for the name convention in what/how each should be saved).

Save the Wave functions (projection) and one-body density

methods (Access=protected)
function saveOutputWaveFunction(obj,k,t)
%setTimeStep
    
    % Save wave functions
    if k == obj.oWfcn.ind(obj.oWfcn.n)
        % Wave functions
        
        % Add external field
        if obj.sEF,         obj.addOutputExternalField('oWfcn',k,t);         end

        % Update counter
        obj.oWfcn.n     =   obj.oWfcn.n + 1;
    end
    
    % Save the projection of the Kohn-Sham orbitals
    if k == obj.oWfcnP.ind(obj.oWfcnP.n)
        % Kohn-Sham orbitals' projection
        
        % Add external field
        if obj.sEF,         obj.addOutputExternalField('oWfcnP',k,t);        end

        % Update counter
        obj.oWfcnP.n    =   obj.oWfcnP.n + 1;
    end

end
end

• saveOutputWaveFunction is called is any of the wave functions or their projection needs to be saved. It must therefore determine which one(s) actually need to be.
• saveOutputWaveFunction is also responsible for updating the counters in obj.oWfcn and obj.oWfcnP (see their respective documentation entry for the name convention in what/how each should be saved).

Estimate the memory footprint of the implementation-specific part of the TDSE propagator

methods (Access=protected)
function mem = getMemoryProfilePropagator(obj,opt)
%getMemoryProfilePropagator 
    
    % Initialization
    if nargin < 2,  opt     =   false;  end

    % Estimate of the memory footprint

end
end

• Use QMol_SE_profiler.showMemoryFootprint to display the memory footprint of the propagator's components (when opt == true)
• getMemoryProfilePropagator should only list the memory footprint of the propagation part of the implementation-specific class. Estimate of the memory footprint for the output results is handled with the getMemoryProfileWaveFunction and getMemoryProfileChildren properties.
• The SE object is initialized when getMemoryProfilePropagator is called

Estimate the memory footprint for saving of the wave functions in the implementation-specific TDSE propagator

methods (Access=protected)
function mem = getMemoryProfileWaveFunction(obj,opt)
%getMemoryProfileOrbitalDensity
    
    % Initialization
    if nargin < 2,  opt     =   false;  end

    % Estimate of the memory footprint

end
end

• Use QMol_SE_profiler.showMemoryFootprint to display the memory footprint of saving the wave functions (when opt == true)
• getMemoryProfileWaveFunction should only list the memory footprint of the requested wave functions. Estimate of the memory footprint for any additional implementation-specific output results with getMemoryProfileChildren.
• The SE object is initialized when getMemoryProfileOrbitalDensity is called

Estimate the memory footprint of additional output defined by the implementation-specific part of the TDSE propagator

methods (Access=protected)
function mem = getMemoryProfileChildren(obj,opt)
%getMemoryProfilePropagator 
    
    % Initialization
    if nargin < 2,  opt     =   false;  end

    % Estimate of the memory footprint

end
end

• Use QMol_SE_profiler.showMemoryFootprint to display the memory footprint of the additional outputs (when opt == true)
• getMemoryProfileChildren should only list the memory footprint of additional output defined by the implementation-specific TDSE propagator. Estimate of the memory footprint for the wave function output results is handled with getMemoryProfileOrbitalDensity
• The SE object is initialized when getMemoryProfileChildren is called

Run-time documentation for additional implementation-specific output variables

methods (Access=protected)
function ref = docOutputChildren(obj)
%docOutputChildren 
    
    % Add specific documentation

end
end

• If no reference is cited, return ref = {} otherwise ref = {'ref 1','ref 2',___}, where each of the ref corresponds to the bibliographic code for the reference (generally of the form 'name_of_first_author publication_year') and is case insensitive -- see the documentation page for a list of citable references.
• For consistency with the other output available to all TDSE propagators, only list the additional output that are being calculated during the TDSE propagation (following user-defined properties).
• Only implementation-specific additional properties should be covered here. All properties common to all TDSE propagators (e.g., time step) are handled in the parent QMol_TDSE class run-time documentation.
• Run-time documentation for the implementation-specific TDSE propagator is handled with showDoc and therefore should not be included here.

Implementation-specific TDSE propagation classes that overload QMol_TDSE may define additional run-time results to save during the propagation. Those are initialized with the setOutputChildren method with the following signature (see also the example above for a more fleshed out template)

methods (Access=protected)
function setOutputChildren(obj,opt)
%setOutputChildren
switch lower(opt)
case {'init','initialize','initialization'} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

    % Clean up any old data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    
    % Initialize output structure(s) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    
case {'clean','finalize','finalization'} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    % Clean output structures at the end of the TDSE propagation

otherwise %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    % Unexpected option
    error('QMol:TDSE:setOutputChildren',['Unknown option ' opt]);
end
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
end
end

Enable saving of the external-field information in a given output structure

methods (Access=protected)
function setOutputExternalField(obj,structName,opt)
%setOutputExternalField
switch lower(opt)
case {'init','initialize','initialization'} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

    % Add proper field for external field information
    
case {'clean','finalize','finalization'} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    % Clean output structures at the end of the TDSE propagation
    % (for the external-field information only)

otherwise %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    % Unexpected option
    error('QMol:TDSE:setOutputExternalField',['Unknown option ' opt]);
end
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
end
end

• setOutputExternalField is called in the initialization and cleanup of each of the setOutputDipole, setOutputEnergy, setOutputFunction, setOutputIonization, and setOutputWaveFunction
• structName is the name of the output structure to which the external field info are to be initialized. obj.(structName) gives access to the corresponding property in the class.

Perform the necessary initialization of the implementation-specific TDSE propagator in restart mode

methods (Access=protected)
function setRestartChildren(obj)
%setRestartChildren
    
    % Initialize upon restart
end
end

• setRestartChildren is called after the QMol_TDSE has performed its own reinitialization, notably SE object has been initialized

Save additional implementation-specific output

methods (Access=protected)
function saveOutputChildren(obj,k,t)
%saveOutputChildren
    
    % Save additional output
end
end

• k is the current time-propagation step index
• t is the current time when the saving is performed
• saveOutputChildren is called for every time step (including the starting and final times) of the TDSE propagation. The class is responsible for checking which additional data must be saved, if any, and doing the actual saving.

Adds the external-field information to a given output structure

methods (Access=protected)
function addOutputExternalField(obj,structName,k,t)
%addOutputExternalField

    % Add external-field information to output structure
end
end

• addOutputExternalField is called by saveOutputDipole, saveOutputEnergy, saveOutputFunction, saveOutputIonization, and saveOutputWaveFunction
• structName is the name of the output structure to which the external field info are to be saved. obj.(structName) gives access to the corresponding property in the class.
• k is the current time-propagation step index
• t is the current time when the saving is performed

Save implementation-specific info needed for restarting a TDSE calculation to the restart structure

methods (Access=protected)
function saveRestartChildren(obj,k,t)
%saveOutputChildren
    
    % Save additional output
end
end

• k is the current time-propagation step index
• t is the current time when the saving is performed
• saveRestartChildren is called at the end of a time-step propagation (and the index k and time t have been updated accordingly before calling the function)

TDSE propagators support both mask and complex absorbing boundary conditions. The template for absorbing boundary classes is

classdef QMol_SE_absorber < QMol_suite
%QMol_SE_absorber 

%% Documentation %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
methods (Static,Access=private)
function version
    QMol_doc.showVersion('##.##.###','##/##/####','Author Name')
end
end
methods (Static,Access={?QMol_doc,?QMol_SE_absorber})
function showInfo
    fprintf( '  * QMol_SE_absorber:\n');
    fprintf(['      > Absorbing boundaries\n',...
             '      > Type of absorber\n']); 
    QMol_SE_absorber.version;
end
end
methods (Access=public)
function ref = showDocumentation(obj)
%showDocumentation displays the documentation reflecting member property 
%   values
    
    % Initialization
    ref                 =   {};

    % Header
    fprintf('  * Absorbing boundaries                                  type of absorber\n');

    % Details of the absorber

    % Version
    obj.version;

end
function mem = getMemoryProfile(obj,opt)
%getMemoryProfile computes and returns an estimate of the total memory
%   footprint (in bytes) of the absorber with all its components
%   initialized and used.
    
    % Initialization
    if nargin < 2,  opt =   false;  end

    % Evaluate (and display) estimate of memory footprint

end
end
%% Properties %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
properties (Transient,Hidden,GetAccess=?QMol_suite,SetAccess={?QMol_TDSE_abs_mask,?QMol_TDSE})
    % Linked objects
    SE                              % SE.disc always defines the domain
end
    % Other properties of the class

%% Alias handling %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    % Mapping between user-facing long variable names and internal's short

%% Initialization %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
methods (Access=public)
function reset(obj)
%reset clears all temporary (transient) properties of the object. Should be
%   overloaded by each subclasses to perform proper reset actions.
    
    % Run-time variables
    obj.SE              =   [];
    
    % Initialization status
    obj.isInit          =   false;
end
function initialize(obj,SE,isFwd)
%initialize initializes the object

    % Initialization
    obj.reset;
    
    % Set links
    obj.SE              =   SE;

    % Initialize the absorber
    
    % Miscellaneous
    obj.isInit          =   true;

end
end
methods (Static=true,Access=?QMol_suite)
function [ClassName,PropNames] = propertyNames()
%propertyNames returns the names of member properties that can be set
%   through name-value assignment
    
    ClassName           =   'QMol_SE_absorber';
    PropNames           =   {};
end
end
%% Absorber %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
methods (Access=public)
    applyMask(obj,wfcn)
    V = getPotential(obj,V)
end
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
end

• Upon initialization, the class should retain a copy of the SE object with the access-right signature specified above (required for memory profiling)
• In the initialize method, isFwd indicates whether the TDSE propagation is is a forward (true) or backward (false) in time (to adjust the sign of the CAP)

Mask absorbers correspond to a given mask function that is multiplied to the Kohn-Sham orbitals after each propagation time step. Their signature is

function applyMask(obj,wfcn)
%applyMask
    
    % Multiply the orbitals in KSO by the mask
end
function V = getPotential(~,V)
%getPotential no complex potential, return the object untouched

end

• Even when no complex absorbing potential is defined, getPotential must still be defined, leaving the input Schrödinger-equation potential untouched

Complex absorbing potentials correspond to an imaginary component added to the Schrödinger-equation potential that dampen the Kohn-Sham orbitals at the boundaries. Their signature is

function applyMask(~,~)
%applyMask no mask applied, do nothinggetMem

end
function V = getPotential(obj,V)
%getPotential

    % Add the complex potential to the SE-potential object V

end

• Even when no mask is defined, applyMask must still be defined, doing nothing
• V is a compatible Schrödinger-equation potential; use its add property to add the CAP

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

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

See QMol_test for details regarding how to create a test suite for new classes.

• QMol_TDSE was introduced in version 01.20