QMol_TDSE_SSO_2S - fmauger1/QMol-grid GitHub Wiki

QMol_TDSE_SSO_2S

Second-order Strang splitting (a.k.a. Verlet) symplectic split-operator scheme for TDSE simulations.

Description

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

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

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

QMol_TDSE_SSO_2S is a handle class overloading QMol_TDSE_SSO (and thus QMol_TDSE_sympSplitOp and QMol_TDSE).

Class properties

Time propagation

display (disp)

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

time (T)

Time propagation vector [ vector (default []) ]

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

timeStep (dt)

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

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

splitMotif

Splitting motif [ 'VTV' (default) | 'TVT' ]

  • Whether the splitting starts with applying the potential ('VTV') or kinetic ('TVT') part of the Schrödinger-equation Hamiltonian.

absorbingBoundary (ABC)

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

  • The boundary absorber aims at eliminating outgoing wave packets from the discretization domain and avoid spurious reflections 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.
  • 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.

externalField (EF)

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

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

externalFieldGauge (EFG)

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

  • 'none' ignores any input external field and propagates the field-free TDSE dynamics.
  • The decision tree for the selection of the default gauge is detailed below.

electricField (FE)

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

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

electricFieldDerivative (FDE)

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

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

potentialVector (FA)

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

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

diffDT

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

Save the Schrödinger-equation object into individual files

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

saveSE (sSE)

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

saveSEFileName (sSEF)

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

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

saveSETime (sSET)

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

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

Save the dipole, dipole velocity, and dipole acceleration signals

saveDipole (sDip)

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

saveDipoleWaveFunctionIndex (sDipI)

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

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

saveDipoleTime (sDipT)

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

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

saveDipoleVelocity (sVel)

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

saveDipoleVelocityWaveFunctionIndex (sVelI)

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

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

saveDipoleVelocityTime (sVelT)

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

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

saveDipoleAcceleration (sAcc)

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

saveDipoleAccelerationWaveFunctionIndex (sAccI)

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

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

saveDipoleAccelerationTime (sAccT)

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

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

Save Schrödinger-equation and wave function energies

saveEnergySE (sESE)

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

saveEnergySETime (sESET)

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

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

saveEnergyWaveFunction (sEWfcn)

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

  • 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.
  • 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.
  • Note that the energy of all the wave functions are computed and saved. One may use an installable output function to track the energy of a subset of wave functions.

saveEnergyWaveFunctionTime (sEWfcnT)

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

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

Save the external field information

saveExternalField (sEF)

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

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

Save the ionization signal

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

saveIonization (sIon)

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

saveIonizationWaveFunctionIndex (sIKSOI)

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

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

saveIonizationTime (sIonT)

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

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

Save the wave functions and their projection on a basis

Warning: The memory requirements for saving the wave functions 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 functions is required consider consider using an installable output function.

saveWaveFunction (sWfcn)

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

saveWaveFunctionIndex (sWfcnI)

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

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

saveWaveFunctionTime (sWfcnT)

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

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

saveWaveFunctionProjection (sWfcnP)

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

saveWaveFunctionProjectionBasis (sWfcnB)

Projection basis [ [] (default) | matrix basis | QMol_disc_basis ]

  • Empty saveWaveFunctionProjectionBasis uses the initial wave functions as the projection basis.
  • matrix saveWaveFunctionProjectionBasis specifies the projection basis to be used, with the projection vectors specified in each column of the matrix.
  • QMol_disc_basis saveWaveFunctionProjectionBasis uses the basis set of the associated domain definition.
  • For both matrix and QMol_disc_basis, the user-defined basis set is assumed to be a proper orthonormal family defined over the same domain grid as the Schrödinger-equation model being propagated. The TDSE propagator does not check for this and will produce erroneous results, or trigger an error, otherwise.

saveWaveFunctionProjectionIndex (sWfcnPI)

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

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

saveWaveFunctionProjectionTime (sWfcnPT)

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

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

Save the output of a functions of the wave function

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

saveOutputFunction (sF)

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

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

saveOutputFunctionTime (sFT)

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

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

Save restart data file

During the time propagation, a restart file can be generated to enable resuming the simulation if it is cut short. Stopping the 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.

saveRestart (sRest)

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

saveRestartFileName (sRestF)

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

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

saveRestartTime (sRestT)

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

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

Output results

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, from the ones specified above. Notably, using a sampling time that is not a multiple of the propagation time step may result in uneven saved time sampling. The actual times at with output are saved is included in each of the output structure.

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

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

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

outDipole (oDip)

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

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

outDipoleVelocity (oVel)

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

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

outDipoleAcceleration (oAcc)

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

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

outEnergySE (oESE)

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

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

outEnergyWaveFunction (oEWfcn)

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

  • TDSE propagation that does track the Schrödinger-equation energy (saveEnergyWaveFunction = false) leaves outEnergyWaveFunction empty. Otherwise:
  • For a wave function $|\psi \rangle$ , the energy is defined as $\langle \psi |\hat{\mathcal{H}} |\psi \rangle$ with $\hat{\mathcal{H}}$ the 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.

outIonization (oIon)

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

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

outWaveFunction (oWfcn)

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

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

outWaveFunctionProjection (oWfcnP)

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

  • TDSE propagation that does not save the projection of the wave functions (saveWaveFunctionProjection = false) leaves outWaveFunctionProjection empty. Otherwise:
  • The specific shape of the saved wave functions' projection is implementation dependent -- see the corresponding documentation for details. At minimum, each implementation defines:
  • outWaveFunctionProjection.time defines the precise times at which the wave function projections are saved.
  • outWaveFunctionProjection.waveFunction contains the saved wave functions' projection and outWaveFunctionProjection.indexWaveFunction the corresponding wave function indices.
  • The structure also retains a copy of the projection basis as QMol_disc_basis object(s).

outOutputFunction (oF)

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

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

Class methods

Creation

constructor

Create a symplectic Strang-Splitting TDSE-propagator object with empty class properties.

obj = QMol_TDSE_SSO_2S;

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

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

Changing class properties

set

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 result 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

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 TDSE propagators class and propagation results.

Initializing the object

initialize

Initialize a symplectic Strang-splitting TDSE-propagator object without allocating the output-result structures.

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

Run-time documentation

getMemoryProfile

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

mem = obj.getMemoryProfile;
mem = obj.getMemoryProfile(false);
  • The object must be initialized for the memory footprint evaluation. If not already, getMemoryProfile initializes the Schrödinger-equation model object.
  • The estimate includes the (1) Schrödinger-equation 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 (expectedly small) properties.
  • The output mem is the estimated size in bytes.

Additionally display the detail of the memory footprint with

mem = obj.getMemoryProfile(true);

showDocumentation

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

obj.showDocumentation;

TDSE propagation

propagate

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.
  • Neither the TDSE-propagation obj nor the Schrödinger-equation-model SE objects need be initialized. In all cases both are (re)initialized at the beginning of the TDSE propagation to ensure proper and consistent linkage and setup between them.

Restart a TDSE propagation.

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

Choice of gauge

If no specific gauge is specified with externalFieldGauge, the gauge is selected following the decision tree:

  • Length gauge if externalField.electricField or electricField is a function handle, otherwise:
  • Velocity gauge if externalField.potentialVector or potentialVector is a function handle, otherwise:
  • Length gauge if externalField.electricField or electricField is a griddedInterpolant, otherwise:
  • Velocity gauge if externalField.potentialVector or potentialVector is a griddedInterpolant, otherwise:
  • Field free (ignore any input field).

External-field components used in simulations

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

  • If both are provided as function handles, then externalField.electricField and externalField.potentialVector are called whenever the values for the potential vector or electric field are required. Note that the TDSE propagator does not check whether the provided potential vector and electric field are consistent with each other ($E(t)=-\partial_t A(t)$) and providing non-matching components will likely result in erroneous results. Otherwise,
  • If only one of them is provided as a function handle, then both the potential vector and electric field are computed from that same function handle (see below for details on how this is done). Otherwise,
  • In the length gauge, if externalField.electricField is a griddedInterpolant then it is used to compute both the electric field and potential vector, otherwise, externalField.potentialVector is used to compute them both.
  • In the velocity gauge, if externalField.potentialVector is a griddedInterpolant then it is used to compute both the electric field and potential vector, otherwise, externalField.electricField is used to compute them both.
  • If none of the externalField.electricField and externalField.potentialVector are defined, the TDSE propagation is performed field free irrespective of the choice of externalFieldGauge and even if an externalField.electricFieldDerivative is defined.

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

For the electric-field derivative:

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

Numerical computation of missing or ignored field components:

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

Examples

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

Test suite

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

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

References

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

Notes

  • QMol_TDSE_SSO_2S was introduced in version 01.20.