QMol_TDSE  fmauger1/QMolgrid GitHub Wiki
Parent class for timedependent Schrödingerequation theory (TDSE) model objects.
QMol_TDSE
defines an abstract class for the time propagation of Schrödingerequation (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 TDSEimplementation classes and their components.
QMol_TDSE
defines many properties and methods. Here we only document the ones visible to end users and implementationspecific overloading classes (public or protected access attributes). We provide a quick overview of the requirements of implementationspecific classes for defining actual TDSE propagation schemes.
Save the Schrödingerequation object into individual files
Save the dipole, dipole velocity, and dipole acceleration signals
Save the external field information
Methods that must be overloaded
Additional optional methods to overload
Complex absorbing potential (CAP)
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 andT(end)
the ending time.  In forward time propagation simulations (
timeStep > 0
) time values inT
must be all increasing, while for backward time propagation (timeStep < 0
) they must be all decreasing. Time increments in the vectorT
need not be equally spaced.  When
display
is activated,T
specifies the intermediary times for the timepropagation 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 fieldfree TDSE simulations.  The specific type and interface for compatible field objects is left to the implementationspecific TDSE propagator  see the corresponding documentation for details.
During the time propagation, copies of the Schrödingerequation object can be saved in separate MATLAB files.
Activate saving the Schrödingerequation object into separate files [ true  false (default) ]
Name for the files in which the Schrödingerequation objects are saved [ character array (default 'QMolGridTDSESE') ]
 The Schrödingerequation 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 variablet
with the time information.  One may specify a location where to create the files by indicating the folder path in
saveSEFileName

saveSEFileName
is irrelevant whensaveSE == false
Times at which to save the Schrödingerequation object into a file [ [] (default)  positive scalar  negative integer  vector  'all' ]
 Empty
saveSETime
uses the same values as intime
for when to save the Schrödingerequation object into MATLAB files.  A positive scalar specifies the sampling time step when to save the Schrödingerequation object into MATLAB files. For forward time propagation, it is equivalent to
time(1):saveSETime:time(end)
, and for backward ones totime(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 totime(1):abs(saveSETime)*timeStep:time(end)
.  A vector provides userdefined times at which to save the Schrödingerequation object to a MATLAB file.

'all'
saves the Schrödingerequation 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 orbitalresolved dipole signal [ [] (default)  index vector  'all' ]
 This is irrelevant if
saveDipole
isfalse
 Specify the indexes of the wave functions for which to compute the orbitalresolved dipole signal in an index vector
 Empty or
'all'
saveDipoleWaveFunctionIndex
computes the orbitalresolved 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 intime
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 totime(1):saveDipoleTime:time(end)
.  A negative integer specifies the number of propagation time steps between dipolesignal computations. For forward time propagation, it is equivalent to
time(1):abs(saveDipoleTime)*timeStep:time(end)
, and for backward ones totime(1):abs(saveDipoleTime)*timeStep:time(end)
.  A vector provides userdefined 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 orbitalresolved dipole velocity signal [ [] (default)  index vector  'all' ]
 This is irrelevant if
saveDipoleVelocity
isfalse
 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 forsaveDipoleTime
 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 totime(1):saveDipoleVelocityTime:time(end)
.  A negative integer specifies the number of propagation time steps between dipolevelocitysignal computations. For forward time propagation, it is equivalent to
time(1):abs(saveDipoleVelocityTime)*timeStep:time(end)
, and for backward ones totime(1):abs(saveDipoleVelocityTime)*timeStep:time(end)
.  A vector provides userdefined 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 KohnSham orbitals for which to compute the orbitalresolved dipole acceleration signal [ [] (default)  index vector  'all' ]
 This is irrelevant if
saveDipoleAcceleration
isfalse
 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 forsaveDipoleTime
 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 totime(1):saveDipoleAccelerationTime:time(end)
.  A negative integer specifies the number of propagation time steps between dipoleaccelerationsignal computations. For forward time propagation, it is equivalent to
time(1):abs(saveDipoleAccelerationTime)*timeStep:time(end)
, and for backward ones totime(1):abs(saveDipoleAccelerationTime)*timeStep:time(end)
.  A vector provides userdefined 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ödingerequation energy during the TDSE propagation [ true  false (default) ]
Times at which to compute and save the Schrödingerequation energy [ [] (default)  positive scalar  negative integer  vector  'all' ]
 Empty
saveEnergySETime
uses the same values as intime
for when to compute and save the Schrödingerequation energy  A positive scalar specifies the sampling time step between successive computations of the Schrödingerequation energy. For forward time propagation, it is equivalent to
time(1):saveEnergySETime:time(end)
, and for backward ones totime(1):saveEnergySETime:time(end)
.  A negative integer specifies the number of propagation time steps between Schrödingerequationenergy computations. For forward time propagation, it is equivalent to
time(1):abs(saveEnergySETime)*timeStep:time(end)
, and for backward ones totime(1):abs(saveEnergySETime)*timeStep:time(end)
.  A vector provides userdefined times at which to compute and save the Schrödingerequation energy.

'all'
computes and saves the Schrödingerequation 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ödingerequation Hamiltonian operator.  Empty
saveEnergyWaveFunctionTime
uses the same values as intime
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 totime(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 totime(1):abs(saveEnergyWaveFunctionTime)*timeStep:time(end)
.  A vector provides userdefined 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 (exceptoutSE
).  For practical reasons, the values for the external driving field may be slightly different than that of
externalField
. This features enables keeping the actual externalfield 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 orbitalresolved ionization signal [ [] (default)  index vector  'all' ]
 This is irrelevant if
saveIonization
isfalse
 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 intime
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 totime(1):saveIonizationTime:time(end)
.  A negative integer specifies the number of propagation time steps between ionizationsignal computations. For forward time propagation, it is equivalent to
time(1):abs(saveIonizationTime)*timeStep:time(end)
, and for backward ones totime(1):abs(saveIonizationTime)*timeStep:time(end)
.  A vector provides userdefined 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ödingerequation 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
isfalse
 Empty
saveWaveFunctionIndex
disables saving of the wave functions and is technically equivalent tosaveWaveFunction = 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 intime
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 totime(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 totime(1):abs(saveWaveFunctionTime)*timeStep:time(end)
.  A vector provides userdefined 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 outofmemory 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  Userdefined
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
isfalse
 Empty
saveWaveFunctionProjectionIndex
disables saving of the wave functions and is technically equivalent tosaveWaveFunctionProjection = 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 intime
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 totime(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 totime(1):abs(saveWaveFunctionProjectionTime)*timeStep:time(end)
.  A vector provides userdefined 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)
wherewfcn
is a wave function object andt
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ödingerequation 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ödingerequation 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 intime
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 totime(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 totime(1):abs(saveOutputFunctionTime)*timeStep:time(end)
.  A vector provides userdefined 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 TDSEpropagator and Schrödingerequationmodel 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 'QMolGridTDSERestart.mat') ]

saveRestartFileName
must be a valid MATLAB file name ('.mat' extension). 
saveRestartFileName
is irrelevant whensaveRestart == 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 intime
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 totime(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 totime(1):abs(saveRestartTime)*timeStep:time(end)
.  A vector provides userdefined 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 timestep.
 See the note on how intermediate time saving is performed during the TDSE propagation below.
During a TDSE propagation, the results of onthefly calculations are stored in structures in the QMol_TDSE
object. Note that QMol_TDSE
does not interpolate its time propagation to fit usersupplied 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ödingerequation 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 dipolesignal calculations during the TDSE propagation [ []  structure ]
 TDSE propagation that do not compute the dipole signal (
saveDipole = false
) leaveoutDipole
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 inoutDipole.indexWaveFunction
 In restart mode,
outDipole
also contains a handful of additional fields relevant for runtime calculations. These fields are saved in the MATLAB restart file but removed upon completion of the TDSE propagation.
Result of dipolevelocitysignal calculations during the TDSE propagation [ []  structure ]
 TDSE propagation that do not compute the dipole signal (
saveDipoleVelocity = false
) leaveoutDipoleVelocity
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 inoutDipoleVelocity.indexWaveFunction
 In restart mode,
outDipoleVelocity
also contains a handful of additional fields relevant for runtime calculations. These fields are saved in the MATLAB restart file but removed upon completion of the TDSE propagation.
Result of dipoleaccelerationsignal calculations during the TDSE propagation [ []  structure ]
 TDSE propagation that do not compute the dipole signal (
saveDipoleAcceleration = false
) leaveoutDipoleAcceleration
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 inoutDipoleAcceleration.indexWaveFunction
 In restart mode,
outDipoleAcceleration
also contains a handful of additional fields relevant for runtime calculations. These fields are saved in the MATLAB restart file but removed upon completion of the TDSE propagation.
Result of the Schrödingerequationenergy calculations during the TDSE propagation [ []  structure ]
 TDSE propagation that do track the Schrödingerequation energy (
saveEnergySE = false
) leaveoutEnergySE
empty. Otherwise 
outEnergySE.time
defines the precise times at which the Schrödingerequation energies are computed 
outEnergySE.total
contains the total Schrödingerequation energy, which should be constant (within the precision of the propagation scheme) 
outEnergySE.kinetic
contains the kineticenergy component, including the drivingfield potential vector in the velocity gauge. 
outEnergySE.potential
contains the potentialenergy 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 runtime 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ödingerequation energy (
saveEnergyWaveFunction = false
) leaveoutEnergyWaveFunction
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ödingerequation Hamiltonian operator. In the velocity gauge, the external potential vector is accounted for in the kineticoperator 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 runtime 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
) leaveoutIonization
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 inoutIonization.indexWaveFunction
 In restart mode,
outIonization
also contains a handful of additional fields relevant for runtime 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
) leaveoutWaveFunction
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 andoutWaveFunction.indexWaveFunction
the corresponding wavefunction indexes  In restart mode,
outWaveFunction
also contains a handful of additional fields relevant for runtime 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
) leaveoutWaveFunctionProjection
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 andoutWaveFunctionProjection.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 runtime 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 = []
) leaveoutOutputFunction
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 aNbynumel(outOutputFunction.time)
matrix withN
the number of elements in the output. Otherwise,outOutputFunction.result
is anMbynumel(outOutputFunction.time)
array withM
the size of the output. 
outOutputFunction.shape
contains the shape of the output function (N
orM
, 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.
Other hidden class properties
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ödingerequationmodel object [ [] (default) 
QMol_SE
handle object ]
 This is a copy of the Schrödingerequationmodel handle object passed to
initialize
.
Propagation time vector [ [] (default)  vector ]
 After the class is
initialize
d, it is defined asuniquetol([obj.T(1):obj.dt:obj.T(end), obj.T(end)],1e10,'DataScale',1)
Indexes of tspan
matching the input time vector T
[ [] (default)  index vector ]
 After the class is
initialize
d, it is defined asgetOutputIndex(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 implementationspecific TDSE propagators overloading the class):kstart
,ndisp
, andidp
Create a TDSEmodel object with empty class properties.
obj = QMol_TDSE;
Create a TDSEmodel object with the name
properties set to the specified value
. Several namevalue
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 TDSEmodel object to the specified value
. Several namevalue
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 namevalue pair assignment method used throughout the QMolgrid 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 QMolgrid 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 TDSEmodel object without allocating the outputresult structures
obj.initialize(SE);

SE
is the Schrödingerequationmodel handle object, i.e.,QMol_SE
, that describes the Schrödingerequation systems to propagate.  For developers:
initialize
also has a specific interface when called from thepropagate
method that initializes the absorbing boundaries (if any) and determines whether the outputresult structures should be initialized too. Overloading classes should avoid redefininginitialize
; If the overloading class needs to perform some initialization (at the beginning of a TDSE propagation or upon restart), overload theinitializeChildren
method instead.
Initialize implementationspecific part of overloading class at the beginning of a TDSE propagation (from scratch)
obj.initializeChildren(false);

QMol_TDSE
calls theinitializeChildren
method after having initialized all its member properties (including theSE
object being propagated).  This should not initialize implementationspecific additional output, which are initialized with
setOutputChildren
Initialize implementationspecific part of overloading class in restart mode.
obj.initializeChildren(true);

QMol_TDSE
calls theinitializeChildren
method after having reinitialized all its member properties (including theSE
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 therestart
structure andinitializeChildren
should bring them back to a working configuration.
Get the timepropagation 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 timest_1
,t_2
, ...  Scalar
t
> 0 returns the indexes of the iteration time steps closest to the time samplingtime(1)
,time(1)+t
,time(1)+2*t
, ... for forward time propagations andtime(1)
,time(1)t
,time(1)2*t
, ... for backward ones  Integer
t
< 0 returns the indexes of the iteration time steps oftime(1)
,time(1)timeStep*t
,time(1)2*timeStep*t
, ... for forward time propagations andtime(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 forsetOutputChildren
,setOutputSE
,setOutputDipole
,setOutputEnergy
,setOutputIonization
,setOutputWaveFunction
,setOutputFunction
, andsetOutputRestart
.
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
initialize
d for the memory footprint evaluation. If not already,getMemoryProfile
initializes theSE
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 runtime documentation for the specific configuration of a QMol_TDSE
object, which must have been initialize
d beforehand
obj.showDocumentation;
The runtime documentation performs the following steps
 Display the QMolgrid package header (showing the kernel, external component versions)
 Call the TDSEpropagator implementationspecific runtime documentation with the property
showDoc
.  Display the timepropagation 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 QMolgrid package footer
Propagate the TDSE dynamics starting from a Schrödingerequation model object (from scratch)
obj.propagate(SE);

SE
is the Schrödingerequationmodel handle object, i.e.,QMol_SE
, that describes the Schrödingerequation 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ödingerequationmodel object),t
(current time), andexternalField
(external field object)  For developers:
saveOutputSE
is also responsible for updating the counterobj.oSE.n
when it is called
Trigger the saving of the Schrödingerequation and wave function energies
obj.saveOutputEnergy(k,t);

k
is the current timepropagation 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 timepropagation 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
andobj.oFKSO.n
when it is called
QMol_TDSE
is an abstract class and only define the common steps and features for all TDSE propagators. Implementationspecific 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 namevalue pair constructor, namevalue 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 namevalue assignment
% Parentclass components
[~,PropNames] = QMol_TDSE.propertyNames;
ClassName = 'QMol_child_class';
PropNames = [PropNames,{'property1','property2'}];
end
end
Display the runtime 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 = {}
otherwiseref = {'ref 1','ref 2',___}
, where each of theref
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 implementationspecific properties should be covered here. All properties common to all TDSE propagators (e.g., time step) are handled in the parent
QMol_TDSE
class runtime 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:end1));
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:end1); 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:end1));
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:end1); 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
, andoutWaveFunction.indexWaveFunction
 In
sWfcnP
,outWaveFunctionProjection.time
,outWaveFunctionProjection.waveFunction
, andoutWaveFunctionProjection.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 andt
the current time. Implementationspecific TDSE propagators will often need to keep a copy ofdt
(as it may vary fromtimeStep
). 
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 onetimestep 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
% Orbitalresolved 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 dipolevelocity signal
if k == obj.oVel.ind(obj.oVel.n)
% Total dipole velocity
% Orbitalresolved 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
% Orbitalresolved 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 inobj.oDip
,obj.oVel
andobj.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ödingerequationfunctional energy from any external field. If not field is applied, or it does not contribute an explicit terms to the Schrödingerequation energy (e.g., velocitygauge dipole approximation), returnE = [0;0]

DE
is the autonomization energy variable, which tracks how much energy is put into or withdrawn from the Schrödingerequation system
Compute the ionization statistics
methods (Access=protected)
function saveOutputIonization(obj,k,t)
%saveOutputIonization
% Total ionization signal
% Orbitalresolved 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 inobj.oIon
(see the documentation entry for the name convention in what/how each should be saved).
Save the Wave functions (projection) and onebody 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 KohnSham orbitals
if k == obj.oWfcnP.ind(obj.oWfcnP.n)
% KohnSham 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 inobj.oWfcn
andobj.oWfcnP
(see their respective documentation entry for the name convention in what/how each should be saved).
Estimate the memory footprint of the implementationspecific 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 (whenopt == true
) 
getMemoryProfilePropagator
should only list the memory footprint of the propagation part of the implementationspecific class. Estimate of the memory footprint for the output results is handled with thegetMemoryProfileWaveFunction
andgetMemoryProfileChildren
properties.  The
SE
object is initialized whengetMemoryProfilePropagator
is called
Estimate the memory footprint for saving of the wave functions in the implementationspecific 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 (whenopt == true
) 
getMemoryProfileWaveFunction
should only list the memory footprint of the requested wave functions. Estimate of the memory footprint for any additional implementationspecific output results withgetMemoryProfileChildren
.  The
SE
object is initialized whengetMemoryProfileOrbitalDensity
is called
Estimate the memory footprint of additional output defined by the implementationspecific 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 (whenopt == true
) 
getMemoryProfileChildren
should only list the memory footprint of additional output defined by the implementationspecific TDSE propagator. Estimate of the memory footprint for the wave function output results is handled withgetMemoryProfileOrbitalDensity
 The
SE
object is initialized whengetMemoryProfileChildren
is called
Runtime documentation for additional implementationspecific output variables
methods (Access=protected)
function ref = docOutputChildren(obj)
%docOutputChildren
% Add specific documentation
end
end
 If no reference is cited, return
ref = {}
otherwiseref = {'ref 1','ref 2',___}
, where each of theref
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 userdefined properties).
 Only implementationspecific 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 runtime documentation.  Runtime documentation for the implementationspecific TDSE propagator is handled with
showDoc
and therefore should not be included here.
Implementationspecific TDSE propagation classes that overload QMol_TDSE
may define additional runtime 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 externalfield 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 externalfield 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 thesetOutputDipole
,setOutputEnergy
,setOutputFunction
,setOutputIonization
, andsetOutputWaveFunction

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 implementationspecific TDSE propagator in restart mode
methods (Access=protected)
function setRestartChildren(obj)
%setRestartChildren
% Initialize upon restart
end
end

setRestartChildren
is called after theQMol_TDSE
has performed its own reinitialization, notablySE
object has been initialized
Save additional implementationspecific output
methods (Access=protected)
function saveOutputChildren(obj,k,t)
%saveOutputChildren
% Save additional output
end
end

k
is the current timepropagation 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 externalfield information to a given output structure
methods (Access=protected)
function addOutputExternalField(obj,structName,k,t)
%addOutputExternalField
% Add externalfield information to output structure
end
end
 addOutputExternalField is called by
saveOutputDipole
,saveOutputEnergy
,saveOutputFunction
,saveOutputIonization
, andsaveOutputWaveFunction

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 timepropagation step index 
t
is the current time when the saving is performed
Save implementationspecific 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 timepropagation step index 
t
is the current time when the saving is performed 
saveRestartChildren
is called at the end of a timestep propagation (and the indexk
and timet
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 userfacing 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.
% Runtime 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 namevalue 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 accessright 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 KohnSham 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ödingerequation potential untouched
Complex absorbing potentials correspond to an imaginary component added to the Schrödingerequation potential that dampen the KohnSham 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 SEpotential object V
end
 Even when no mask is defined,
applyMask
must still be defined, doing nothing  V is a compatible Schrödingerequation potential; use its
add
property to add the CAP
For consistency with the rest of the QMolgrid 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