QMol_TDSE - fmauger1/QMol-grid GitHub Wiki
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.
Save the Schrödinger-equation 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 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 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ödinger-equation 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ö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 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 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
isfalse
- 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 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 dipole-signal 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 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
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 dipole-velocity-signal 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 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
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 dipole-acceleration-signal 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 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 intime
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 totime(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 totime(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 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 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 (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 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
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 ionization-signal 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 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
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 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
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 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)
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ö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 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 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 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 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
) 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 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
) 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 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
) 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 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
) leaveoutEnergySE
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
) 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ö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
) 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 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
) 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 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
) 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 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 = []
) 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 aN-by-numel(outOutputFunction.time)
matrix withN
the number of elements in the output. Otherwise,outOutputFunction.result
is anM-by-numel(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ö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
initialize
d, it is defined asuniquetol([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
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 implementation-specific TDSE propagators overloading the class):kstart
,ndisp
, andidp
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 thepropagate
method that initializes the absorbing boundaries (if any) and determines whether the output-result 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 implementation-specific 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 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 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 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 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 run-time documentation for the specific configuration of a QMol_TDSE
object, which must have been initialize
d 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), 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ö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
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. 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 = {}
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 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
, 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. Implementation-specific 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 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 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ö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), returnE = [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 inobj.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 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 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 (whenopt == 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 thegetMemoryProfileWaveFunction
andgetMemoryProfileChildren
properties. - The
SE
object is initialized whengetMemoryProfilePropagator
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 (whenopt == 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 withgetMemoryProfileChildren
. - The
SE
object is initialized whengetMemoryProfileOrbitalDensity
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 (whenopt == 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 withgetMemoryProfileOrbitalDensity
- The
SE
object is initialized whengetMemoryProfileChildren
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 = {}
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 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 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 implementation-specific 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 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
, 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 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 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 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