QMol_TDDFT

Parent class for time-dependent density-functional theory (TDDFT) model objects.

Description

QMol_TDDFT defines an abstract class for the time propagation of DFT models. It is designed to be agnostic of (i) the model dimension, (ii) the chosen discretization (Cartesian grid or basis), and (ii) spin polarized or restricted configuration. These are to be handled by the specific TDDFT-implementation classes and their components.

QMol_TDDFT 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 TDDFT propagation schemes.

Table of Contents

Description

Class properties

 Time propagation

 Save the DFT object into individual files

 Save the dipole, dipole velocity, and dipole acceleration signals

 Save DFT and orbital energies

 Save the external field information

 Save the ionization signal

 Save the Kohn-Sham orbitals (projection) and one-body density

 Save output functions of the one-body density and Kohn-Sham orbitals

 Save restart data file

 Output results

 Other hidden class properties

Class methods

 Creation

  constructor

 Changing class properties

 Initializing the object

 Run-time documentation

 TDDFT propagation

Overloading the class

 Methods that must be overloaded

 Additional optional methods to overload

Boundary absorber

 Mask function

 Complex absorbing potential (CAP)

Test suite

Notes

Class properties

Time propagation

display (disp)

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

time (T)

Time propagation vector [ vector (default []) ]

• In all TDDFT 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 TDDFT 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.

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

externalField (EF)

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

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

Save the DFT object into individual files

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

saveDFT (sDFT)

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

saveDFTFileName (sDFTF)

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

• The DFT objects saved at different times are put in separate MATLAB (.mat.) file, with names starting with saveDFTFileName 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 saveDFTFileName
• saveDFTFileName is irrelevant when saveDFT == false

saveDFTTime (sDFTT)

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

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

Save the dipole, dipole velocity, and dipole acceleration signals

saveDipole (sDip)

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

saveDipoleOrbitalIndex (sDipI)

Index of the Kohn-Sham orbitals for which to compute the orbital-resolved dipole signal [ [] (default) | index vector | cell | 'all' ]

• This is irrelevant if saveDipole is false
• Empty saveDipoleOrbitalIndex disables the orbital-resolved dipole signal calculation
• For spin restricted models, specify the indexes of the orbitals for which to compute the orbital-resolved dipole signal
• For spin polarized models, combine the up- and down-spin channel orbital indexes in a cell of the form {ind_up,ind_down}
• 'all' computes the orbital-resolved dipole for all orbitals

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 ones to time(1):-saveDipoleTime:time(end).
• A negative integer specifies the number of propagation time steps between dipole-signal computations. For forward time propagation, it is equivalent to time(1):abs(saveDipoleTime)*timeStep:time(end), and for backward ones to time(1):-abs(saveDipoleTime)*timeStep:time(end).
• A vector provides user-defined times at which to compute and save the dipole signal.
• 'all' computes and saves the dipole signal after every time step. Warning: this is may be slow.
• See the note on how intermediate time saving is performed during the TDDFT propagation below.

saveDipoleVelocity (sVel)

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

saveDipoleVelocityOrbitalIndex (sVelI)

Index of the Kohn-Sham orbitals for which to compute the orbital-resolved dipole velocity signal [ [] (default) | index vector | cell | 'all' ]

• This is irrelevant if saveDipoleVelocity is false
• Empty saveDipoleVelocityOrbitalIndex disables the orbital-resolved dipole velocity signal calculation
• For spin restricted models, specify the indexes of the orbitals for which to compute the orbital-resolved dipole velocity signal
• For spin polarized models, combine the up- and down-spin channel orbital indexes in a cell of the form {ind_up,ind_down}
• 'all' computes the orbital-resolved dipole velocity for all orbitals

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 ones to time(1):-saveDipoleVelocityTime:time(end).
• A negative integer specifies the number of propagation time steps between dipole-velocity-signal computations. For forward time propagation, it is equivalent to time(1):abs(saveDipoleVelocityTime)*timeStep:time(end), and for backward ones to time(1):-abs(saveDipoleVelocityTime)*timeStep:time(end).
• A vector provides user-defined times at which to compute and save the dipole velocity signal.
• 'all' computes and saves the dipole velocity signal after every time step. Warning: this is may be slow.
• See the note on how intermediate time saving is performed during the TDDFT propagation below.

saveDipoleAcceleration (sAcc)

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

saveDipoleAccelerationOrbitalIndex (sAccI)

Index of the Kohn-Sham orbitals for which to compute the orbital-resolved dipole acceleration signal [ [] (default) | index vector | cell | 'all' ]

• This is irrelevant if saveDipoleAcceleration is false
• Empty saveDipoleAccelerationOrbitalIndex disables the orbital-resolved dipole acceleration signal calculation
• For spin restricted models, specify the indexes of the orbitals for which to compute the orbital-resolved dipole acceleration signal
• For spin polarized models, combine the up- and down-spin channel orbital indexes in a cell of the form {ind_up,ind_down}
• 'all' computes the orbital-resolved dipole acceleration for all orbitals

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 ones to time(1):-saveDipoleAccelerationTime:time(end).
• A negative integer specifies the number of propagation time steps between dipole-acceleration-signal computations. For forward time propagation, it is equivalent to time(1):abs(saveDipoleAccelerationTime)*timeStep:time(end), and for backward ones to time(1):-abs(saveDipoleAccelerationTime)*timeStep:time(end).
• A vector provides user-defined times at which to compute and save the dipole acceleration signal.
• 'all' computes and saves the dipole acceleration signal after every time step. Warning: this is may be slow.
• See the note on how intermediate time saving is performed during the TDDFT propagation below.

Save DFT and orbital energies

saveEnergyDFT (sEDFT)

Whether to track the DFT energy during the TDDFT propagation [ true | false (default) ]

saveEnergyDFTTime (sEDFTT)

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

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

saveEnergyOrbital (sEKSO)

Whether to track the orbital energies during the TDDFT propagation [ true | false (default) ]

saveEnergyOrbitalTime (sEKSOT)

Times at which to compute and save the Kohn-Sham orbital energies [ [] (default) | positive scalar | negative integer | vector | 'all' ]

• For a Kohn-Sham orbital $|\phi \rangle$, the orbital energy is defined as $\langle \phi |{\hat{\mathcal{H}} }_{{\mathrm{D}\mathrm{F}\mathrm{T}}} |\phi \rangle$ with ${\hat{\mathcal{H}} }_{{\mathrm{D}\mathrm{F}\mathrm{T}}}$ the DFT Hamiltonian operator.
• Empty saveEnergyOrbitalTime uses the same values as in time for when to compute and save the Kohn-Sham orbital energies
• A positive scalar specifies the sampling time step between successive computations of the Kohn-Sham orbital energies. For forward time propagation, it is equivalent to time(1):saveEnergyOrbitalTime:time(end), and for backward ones to time(1):-saveEnergyOrbitalTime:time(end).
• A negative integer specifies the number of propagation time steps between Kohn-Sham-orbital-energy computations. For forward time propagation, it is equivalent to time(1):abs(saveEnergyOrbitalTime)*timeStep:time(end), and for backward ones to time(1):-abs(saveEnergyOrbitalTime)*timeStep:time(end).
• A vector provides user-defined times at which to compute and save the Kohn-Sham-orbital energies.
• 'all' computes and saves the Kohn-Sham orbital energies after every time step. Warning: this is may be slow.
• See the note on how intermediate time saving is performed during the TDDFT propagation below.

Save the external field information

saveExternalField (sEF)

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

• When activated (saveExternalField = true), the information about the external driving field at the sampled times is added to each of the output structures (except outDFT).
• 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.

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 TDDFT propagation [ true | false (default) ]

saveIonizationOrbitalIndex (sIKSOI)

Index of the Kohn-Sham orbitals for which to compute the orbital-resolved ionization signal [ [] (default) | index vector | cell | 'all' ]

• This is irrelevant if saveIonization is false
• Empty saveIonizationOrbitalIndex disables the orbital-resolved ionization signal calculation
• For spin restricted models, specify the indexes of the orbitals for which to compute the orbital-resolved ionization signal
• For spin polarized models, combine the up- and down-spin channel orbital indexes in a cell of the form {ind_up,ind_down}
• 'all' computes the orbital-resolved ionization for all orbitals

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 ones to time(1):-saveIonizationTime:time(end).
• A negative integer specifies the number of propagation time steps between ionization-signal computations. For forward time propagation, it is equivalent to time(1):abs(saveIonizationTime)*timeStep:time(end), and for backward ones to time(1):-abs(saveIonizationTime)*timeStep:time(end).
• A vector provides user-defined times at which to compute and save the ionization signal.
• 'all' computes and saves the ionization signal after every time step. Warning: this is may be slow.
• See the note on how intermediate time saving is performed during the TDDFT propagation below.

Save the Kohn-Sham orbitals (projection) and one-body density

Warning: The memory requirements for saving the orbitals or density throughout the TDDFT propagation may grow very fast and trigger an error (if MATLAB runs out of memory). Instead, if the full orbital/one-body density is required consider saving the DFT object in separate files, or if only the result of a specify calculation on the orbital/one-body density is required consider consider using installable output functions.

saveDensity (sRho)

Whether to save the one-body density during the TDDFT propagation [ true | false (default) ]

saveDensityTime (sRhoT)

Times at which to save the one-body density [ [] (default) | positive scalar | negative integer | vector | 'all' ]

• Empty saveDensityTime uses the same values as in time for when to save the one-body density.
• A positive scalar specifies the sampling time step between successive saving of the one-body density. For forward time propagation, it is equivalent to time(1):saveDensityTime:time(end), and for backward ones to time(1):-saveDensityTime:time(end).
• A negative integer specifies the number of propagation time steps between saving the one-body density. For forward time propagation, it is equivalent to time(1):abs(saveDensityTime)*timeStep:time(end), and for backward ones to time(1):-abs(saveDensityTime)*timeStep:time(end).
• A vector provides user-defined times at which to save the one-body density.
• 'all' saves the one-body density 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 TDDFT propagation below.

saveOrbital (sKSO)

Whether to save the Kohn-Sham orbitals during the TDDFT propagation [ true | false (default) ]

saveOrbitalIndex (sKSOI)

Index of the Kohn-Sham orbitals to save [ [] (default) | index vector | cell | 'all' ]

• This is irrelevant if saveOrbital is false
• Empty saveOrbitalIndex disables saving of the Kohn-Sham orbitals and is technically equivalent to saveOrbital = false
• For spin restricted models, specify the indexes of the orbitals to save
• For spin polarized models, combine the up- and down-spin channel orbital indexes in a cell of the form {ind_up,ind_down}
• 'all' saves all the Kohn-Sham orbitals

saveOrbitalTime (sKSOT)

Times at which to save the Kohn-Sham orbitals [ [] (default) | positive scalar | negative integer | vector | 'all' ]

• Empty saveOrbitalTime uses the same values as in time for when to save the Kohn-Sham orbitals.
• A positive scalar specifies the sampling time step between successive saving of the Kohn-Sham orbitals. For forward time propagation, it is equivalent to time(1):saveOrbitalTime:time(end), and for backward ones to time(1):-saveOrbitalTime:time(end).
• A negative integer specifies the number of propagation time steps between saving Kohn-Sham orbitals. For forward time propagation, it is equivalent to time(1):abs(saveOrbitalTime)*timeStep:time(end), and for backward ones to time(1):-abs(saveOrbitalTime)*timeStep:time(end).
• A vector provides user-defined times at which to save the Kohn-Sham orbitals.
• 'all' saves the Kohn-Sham orbitals 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 TDDFT propagation below.

saveOrbitalProjection (sKSOP)

Whether to save the projection of the Kohn-Sham orbitals onto a specific basis during the TDDFT propagation [ true | false (default) ]

saveOrbitalProjectionBasis (sKSOPB)

Projection basis [ [] (default) | basis ]

• Empty saveOrbitalProjectionBasis uses the initial Kohn-Sham orbitals as the projection basis
• User-defined basis is implementation dependent -- see the respective documentations for details

saveOrbitalProjectionIndex (sKSOPI)

Index of the Kohn-Sham orbitals for which to perform the projection [ [] (default) | index vector | cell | 'all' ]

• This is irrelevant if saveOrbitalProjectionBasis is false
• Empty saveOrbitalProjectionIndex disables saving of the Kohn-Sham orbitals and is technically equivalent to saveOrbitalProjectionBasis = false
• For spin restricted models, specify the indexes of the orbitals for which to perform the projection
• For spin polarized models, combine the up- and down-spin channel orbital indexes in a cell of the form {ind_up,ind_down}
• 'all' saves the projection for all the Kohn-Sham orbitals

saveOrbitalProjectionTime (sKSOPT)

Times at which to save the projection of the Kohn-Sham orbitals [ [] (default) | positive scalar | negative integer | vector | 'all' ]

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

Save output functions of the one-body density and Kohn-Sham orbitals

saveOutputFunctionDensity (sFRho)

Installable output function of the one-body density [ [] (default) | function handle ]

• Leave empty to disable the feature
• Provide a function handle to enable the feature. The signature for the function is fun(rho,t) where rho is a one-body density object and t is the time (scalar). The functional handle may return an array of arbitrary size and shape, but must return at least a scalar.

saveOutputFunctionDensityTime (sFRhoT)

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

• Empty saveOutputFunctionDensityTime 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):saveOutputFunctionDensityTime:time(end), and for backward ones to time(1):-saveOutputFunctionDensityTime: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(saveOutputFunctionDensityTime)*timeStep:time(end), and for backward ones to time(1):-abs(saveOutputFunctionDensityTime)*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 TDDFT propagation below.

saveOutputFunctionOrbital (sFKSO)

Installable output function of the Kohn-Sham orbitals [ [] (default) | function handle ]

• Leave empty to disable the feature
• Provide a function handle to enable the feature. The signature for the function is fun(KSO,t) where KSO is a Kohn-Sham orbital object and t is the time (scalar). The functional handle may return an array of arbitrary size and shape, but must return at least a scalar.
• Warning: The DFT model Kohn-Sham orbitals are passed by reference to the output function. Thus modifying the Kohn-Sham orbitals in the output function will also modify them for the DFT model (and thus TDDFT propagation) and will likely result in erroneous results or produce an error.

saveOutputFunctionOrbitalTime (sFKSOT)

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

• Empty saveOutputFunctionOrbitalTime 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):saveOutputFunctionOrbitalTime:time(end), and for backward ones to time(1):-saveOutputFunctionOrbitalTime: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(saveOutputFunctionOrbitalTime)*timeStep:time(end), and for backward ones to time(1):-abs(saveOutputFunctionOrbitalTime)*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 TDDFT 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 TDDFT 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 TDDFT-propagator and DFT-model objects, respectively called TDDFT and DFT in the MATLAB restart file.

saveRestart (sRest)

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

saveRestartFileName (sRestF)

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

• saveDFTFileName must be a valid MATLAB file name ('.mat' extension).
• saveDFTFileName 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 ones to time(1):-saveRestartTime:time(end).
• A negative integer specifies the number of propagation time steps between the generation and update of the restart file. For forward time propagation, it is equivalent to time(1):abs(saveRestartTime)*timeStep:time(end), and for backward ones to time(1):-abs(saveRestartTime)*timeStep:time(end).
• A vector provides user-defined times at which to generate and update the restart file.
• 'all' generates and updates the restart file after each time step. Warning: this is very slow and is strongly discouraged.
• Note: In all cases no restart file is generated for the initial time and final propagation time-step.
• See the note on how intermediate time saving is performed during the TDDFT propagation below.

Output results

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

outDFT (oDFT)

Support for saving the DFT object into individual MATLAB files during propagation [ [] (default) | structure ]

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

outDipole (oDip)

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

• TDDFT propagation that do not compute the dipole signal (saveDipole = false ) leave outDipole empty. Otherwise
• outDipole.time defines the precise times at which the dipole signal is computed
• outDipole.total contains the corresponding total dipole signal and, for spin-polarized DFT models, outDipole.totalUp and outDipole.totalDown contain the total dipole signal in the up- and down-spin channels respectively, Each successive row contains the dipole signal in the x, y, and z directions, respectively.
• Orbital-resolved dipole signals are stored in outDipole.orbital_x, outDipole.orbital_y, outDipole.orbital_z, outDipole.orbitalUp_x, outDipole.orbitalUp_y, outDipole.orbitalUp_z, outDipole.orbitalDown_x, outDipole.orbitalDown_y, and outDipole.orbitalDown_z. The indexes of the orbitals associated with each of these are included in outDipole.indexOrbital, outDipole.indexOrbitalUp, and outDipole.indexOrbitalDown
• 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 TDDFT propagation.

outDipoleVelocity (oVel)

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

• TDDFT propagation that do not compute the dipole signal (saveDipoleVelocity = false ) leave outDipoleVelocity empty. Otherwise
• outDipole.time defines the precise times at which the dipole velocity signal is computed
• outDipoleVelocity.total contains the corresponding total dipole velocity signal and, for spin-polarized DFT models, outDipoleVelocity.totalUp and outDipoleVelocity.totalDown contain the total dipole velocity signal in the up- and down-spin channels respectively, Each successive row contains the dipole velocity signal in the x, y, and z directions, respectively.
• Orbital-resolved dipole velocity signals are stored in outDipoleVelocity.orbital_x, outDipoleVelocity.orbital_y, outDipoleVelocity.orbital_z, outDipoleVelocity.orbitalUp_x, outDipoleVelocity.orbitalUp_y, outDipoleVelocity.orbitalUp_z, outDipoleVelocity.orbitalDown_x, outDipoleVelocity.orbitalDown_y, and outDipoleVelocity.orbitalDown_z. The indexes of the orbitals associated with each of these are included in outDipole.indexOrbital, outDipole.indexOrbitalUp, and outDipole.indexOrbitalDown
• 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 TDDFT propagation.

outDipoleAcceleration (oAcc)

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

• TDDFT propagation that do not compute the dipole signal (saveDipoleAcceleration = false ) leave outDipoleAcceleration empty. Otherwise
• outDipoleAcceleration.time defines the precise times at which the dipole acceleration signal is computed
• outDipoleAcceleration.total contains the corresponding total dipole acceleration signal and, for spin-polarized DFT models, outDipoleAcceleration.totalUp and outDipoleAcceleration.totalDown contain the total dipole acceleration signal in the up- and down-spin channels respectively, Each successive row contains the dipole acceleration signal in the x, y, and z directions, respectively.
• Orbital-resolved dipole velocity signals are stored in outDipoleAcceleration.orbital_x, outDipoleAcceleration.orbital_y, outDipoleAcceleration.orbital_z, outDipoleAcceleration.orbitalUp_x, outDipoleAcceleration.orbitalUp_y, outDipoleAcceleration.orbitalUp_z, outDipoleAcceleration.orbitalDown_x, outDipoleAcceleration.orbitalDown_y, and outDipoleAcceleration.orbitalDown_z. The indexes of the orbitals associated with each of these are included in outDipole.indexOrbital, outDipole.indexOrbitalUp, and outDipole.indexOrbitalDown
• 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 TDDFT propagation.

outEnergyDFT (oEDFT)

Result of the DFT-energy calculations during the TDDFT propagation [ [] | structure ]

• TDDFT propagation that do track the DFT energy (saveEnergyDFT = false ) leave outEnergyDFT empty. Otherwise
• outEnergyDFT.time defines the precise times at which the DFT energies are computed
• outEnergyDFT.total contains the total DFT energy, which should be constant (within the precision of the propagation scheme)
• outEnergyDFT.kinetic contains the kinetic-energy component. For spin-polarized models each the two rows contain the up- and down-spin kinetic energy components, respectively
• outEnergyDFT.external contains the external-energy component. For spin-polarized models each the two rows contain the up- and down-spin external energy components, respectively
• outEnergyDFT.Hartree contains the Hartree-energy component.
• outEnergyDFT.exchangeCorrelation contains the exchange-correlation-energy component.
• outEnergyDFT.externalField contains the energy contribution from external fields (if any). For spin-polarized models each the two rows contain the up- and down-spin energy components, respectively
• outEnergyDFT.autonomization contains the energy brought in and out of the system by the external driving field (if any).
• In restart mode, outEnergyDFT 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 TDDFT propagation.

outEnergyOrbital (oEKSO)

Result of the Kohn-Sham-orbital-energy calculations during the TDDFT propagation [ [] | structure ]

• TDDFT propagation that do track the DFT energy (saveEnergyOrbital = false ) leave outEnergyDFT empty. Otherwise
• For a Kohn-Sham orbital $|\phi \rangle$, the orbital energy is defined as $\langle \phi |{\hat{\mathcal{H}} }_{{\mathrm{D}\mathrm{F}\mathrm{T}}} |\phi \rangle$ with ${\hat{\mathcal{H}} }_{{\mathrm{D}\mathrm{F}\mathrm{T}}}$ the DFT Hamiltonian operator.
• outEnergyOrbital.time defines the precise times at which the Kohn-Sham-orbital energies are computed
• For spin-restricted models, each row of outEnergyOrbital.orbital contains the energies of the corresponding Kohn-Sham orbital
• For spin-polarized models, each row of outEnergyOrbital.orbitalUp and outEnergyOrbital.orbitalDown contains the energies of the corresponding Kohn-Sham orbital for the up- and down-spin channels, respectively.
• In restart mode, outEnergyOrbital 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 TDDFT propagation.

outIonization (oIon)

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

• TDDFT propagation that do track ionization (saveIonization = false ) leave outIonization empty. Otherwise
• outIonization.time defines the precise times at which the ionization is computed
• outIonization.total contains the total ionization
• For spin-polarized models, outIonization.totalUp and outIonization.totalDown contain the total ionization for the up- and down-spin channels, respectively.
• Orbital-resolved ionization signals are stored in outIonization.orbital, outIonization.orbitalUp, and outIonization.orbitalDown. The indexes of the orbitals associated with each of these are included in outIonization.indexOrbital, outIonization.indexOrbitalUp, and outIonization.indexOrbitalDown
• 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 TDDFT propagation.

outDensity (oRho)

One-body densities during the TDDFT propagation [ [] | structure ]

• TDDFT propagation that do not save the one-body density (saveDensity = false ) leave outDensity empty. Otherwise
• The specific shape of the saved one-body densities is implementation dependent -- see the corresponding documentation for details. At minimum, each implementation defines
• outDensity.time defines the precise times at which the one-body density is saved
• outDensity.total contains the corresponding one-body densities and, for spin-polarized DFT models, outDensity.totalUp and outDensity.totalDown contain the one-body densities in the up- and down-spin channels respectively.
• In restart mode, outDensity 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 TDDFT propagation.

outOrbital (oKSO)

Kohn-Sham orbitals during the TDDFT propagation [ [] | structure ]

• TDDFT propagation that do not save the Kohn-Sham orbitals (saveOrbital = false ) leave outOrbital empty. Otherwise
• The specific shape of the saved Kohn-Sham orbitals is implementation dependent -- see the corresponding documentation for details. At minimum, each implementation defines
• outOrbital.time defines the precise times at which the one-body density is saved
• For spin-restricted models, outOrbital.orbital contains the saved Kohn-Sham orbitals and outOrbital.indexOrbital the corresponding orbital indexes
• For spin-polarized models, outOrbital.orbitalUp and outOrbital.orbitalDown contains the saved Kohn-Sham orbitals for the up- and down-spin channels, respectively, and outOrbital.indexOrbitalUp and outOrbital.indexOrbitalDown the corresponding orbital indexes
• In restart mode, outOrbital 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 TDDFT propagation.

outOrbitalProjection (oKSOP)

Projection of the Kohn-Sham orbitals during the TDDFT propagation [ [] | structure ]

• TDDFT propagation that do not save the projection of the Kohn-Sham orbitals (saveOrbitalProjection = false ) leave outOrbitalProjection empty. Otherwise
• The specific shape of the saved Kohn-Sham orbitals' projection is implementation dependent -- see the corresponding documentation for details. At minimum, each implementation defines
• outOrbitalProjection.time defines the precise times at which the one-body density is saved
• For spin-restricted models, outOrbitalProjection.orbital contains the saved Kohn-Sham orbitals' projection and outOrbitalProjection.indexOrbital the corresponding orbital indexes
• For spin-polarized models, outOrbitalProjection.orbitalUp and outOrbitalProjection.orbitalDown contains the saved Kohn-Sham orbitals' projection for the up- and down-spin channels, respectively, and outOrbitalProjection.indexOrbitalUp and outOrbitalProjection.indexOrbitalDown the corresponding orbital indexes
• The structure also retains a copy of the projection basis
• In restart mode, outOrbitalProjection 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 TDDFT propagation.

outOutputFunctionDensity (oFRho)

Result of the installable output function of the one-body density [ [] | structure ]

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

outOutputFunctionOrbital (oFKSO)

Result of the installable output function of the Kohn-Sham orbitals [ [] | structure ]

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

outRestart (oRest)

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

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

Other hidden class properties

QMol_TDDFT 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).

DFT

DFT-model object [ [] (default) | QMol_DFT_spinPol handle object | QMol_DFT_spinRes handle object ]

• This is a copy of the DFT-model handle object passed to initialize.

tspan

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

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

iref

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

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

restart

Restart structure [ [] (default) | restart ]

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

Class methods

Creation

constructor

Create a TDDFT-model object with empty class properties.

obj = QMol_TDDFT;

Create a TDDFT-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 TDDFT class properties and is case insensitive.

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

Changing class properties

set

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

Initializing the object

QMol_TDDFT 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

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

obj.initialize(DFT);

• DFT is the DFT-model handle object, i.e., QMol_DFT_spinPol or QMol_DFT_spinRes, that describes the DFT 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 TDDFT propagation or upon restart), overload the initializeChildren method instead.

initializeChildren

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

obj.initializeChildren(false);

• QMol_TDDFT calls the initializeChildren method after having initialized all its member properties (including the DFT 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_TDDFT calls the initializeChildren method after having reinitialized all its member properties (including the DFT object being propagated).
• Note that the restart mode does not call setTimeStep during the initialization. All relevant time step information should be stored with the class of in the restart structure and initializeChildren should bring them back to a working configuration.

getOutputIndex

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

ind = obj.getOutputIndex(t);

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

ind = obj.getOutputIndex('all');

• Returns the indexes associated with all the iteration time steps

setOutputChildren

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

obj.setOutputChildren('init');

Cleanup the additional output results defined in an specific implementation of the TDDFT 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_TDDFT object in the restart MATLAB file).

setOutputDFT

Initialize the outDFT structure before running a TDDFT computation

obj.setOutputDFT('init');

Cleanup the outDFT structure at the end of the TDDFT computation

obj.setOutputDFT('clean');

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

setOutputDipole

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

obj.setOutputDipole('init');

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

obj.setOutputDipole('clean');

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

setOutputEnergy

Initialize the outEnergyDFT and outEnergyOrbital structures before running a TDDFT computation

obj.setOutputEnergy('init');

Cleanup the outEnergyDFT and outEnergyOrbital structures at the end of the TDDFT computation

obj.setOutputEnergy('clean');

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

setOutputFunction

Initialize the outOutputFunctionDensity and outOutputFunctionOrbital structures before running a TDDFT computation

obj.setOutputFunction('init');

Cleanup the outOutputFunctionDensity and outOutputFunctionOrbital structures at the end of the TDDFT computation

obj.setOutputFunction('clean');

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

setOutputIonization

Initialize the outIonization structure before running a TDDFT computation

obj.setOutputIonization('init');

Cleanup the outIonization structure at the end of the TDDFT computation

obj.setOutputIonization('clean');

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

setOutputOrbitalDensity

Initialize the outDensity, outOrbital, and outOrbitalProjection structures before running a TDDFT computation

obj.setOutputOrbitalDensity('init');

Cleanup the outDensity, outOrbital, and outOrbitalProjection structures at the end of the TDDFT computation

obj.setOutputOrbitalDensity('clean');

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

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

setOutputRestart

Initialize the outRestart structure before running a TDDFT computation

obj.setOutputRestart('init');

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

obj.setOutputRestart('clean');

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

finalize

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

obj.finalize;

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

Run-time documentation

getMemoryProfile

Get an estimate of the memory help by a QMol_TDDFT 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 DFT model object.
• The estimate includes (1) DFT model, (2) TDDFT 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);

showDocumentation

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

obj.showDocumentation;

The run-time documentation performs the following steps

• Display the QMol-grid package header (showing the kernel, external component versions)
• Call the TDDFT-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 TDDFT 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

TDDFT propagation

propagate

Propagate the TDDFT dynamics starting from a DFT model object (from scratch)

obj.propagate(DFT);

• DFT is the DFT-model handle object, i.e., QMol_DFT_spinPol or QMol_DFT_spinRes, that describes the DFT systems to propagate.

Restart a TDDFT propagation

obj.propagate('restart');

saveOutputDFT

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

obj.saveOutputDFT(obj,t);

• t is the current time when the saving is performed
• Each output file contains DFT (DFT-model object), t (current time), and externalField (external field object)
• For developers: saveOutputDFT is also responsible for updating the counter obj.oDFT.n when it is called

setOutputEnergy

Trigger the saving of the DFT and Kohn-Sham orbital 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 DFT energy calls getExternalFieldEnergy to get the contribution from any external field and autonomization variable

saveOutputFunction

Trigger the computation and saving of the installable output functions

obj.saveOutputFunction(obj,k,t);

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

Overloading the class

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

Methods that must be overloaded

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

propertyNames

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_TDDFT.propertyNames;

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

showDoc

Display the run-time documentation for the specific implementation of the molecular potential.

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

end
end

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

setOutputOrbitalDensity

Initialize the outDensity, outOrbital, and outOrbitalProjection structures before running a TDDFT computation and clean them up at the end of the computation. The method should have the following signature and features

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

switch lower(opt)
case {'init','initialize','initialization'} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

    % Clean up any old data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    obj.oRho            =   [];
    obj.oKSO            =   [];
    obj.oKSOP           =   [];
    
    % One-body density ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    if obj.sRho
        % When to save the DFT energies
        obj.oRho.ind    =   [obj.getOutputIndex(obj.sRhoT),NaN];
        obj.oRho.time   =   obj.tspan(obj.oRho.ind(1:end-1));
        obj.oRho.n      =   1;

        % Density output initialization
    else
        obj.oRho.ind    =   NaN;
        obj.oRho.n      =   1;
    end
    
    % Kohn-Sham orbitals ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    if obj.sKSO
        % When to save the DFT energies
        obj.oKSO.ind    =   [obj.getOutputIndex(obj.sKSOT),NaN];
        obj.oKSO.time   =   obj.tspan(obj.oKSO.ind(1:end-1));
        obj.oKSO.n      =   1;

        % Kohn-Sham orbitals output initialization
    else
        obj.oKSO.ind    =   NaN;
        obj.oKSO.n      =   1;
    end
    
    % Kohn-Sham orbitals' projection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    if obj.sKSOP
        % When to save the DFT energies
        obj.oKSOP.ind   =   [obj.getOutputIndex(obj.sKSOPT),NaN];
        obj.oKSOP.time  =   obj.tspan(obj.oKSOP.ind(1:end-1));
        obj.oKSOP.n     =   1;

        % Kohn-Sham orbitals' projection output initialization
    else
        obj.oKSOP.ind   =   NaN;
        obj.oKSOP.n     =   1;
    end
    
case {'clean','finalize','finalization'} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    obj.oRho            =   rmfield(obj.oRho,{'ind','n'});
    obj.oKSO            =   rmfield(obj.oKSO,{'ind','n'});
    obj.oKSOP           =   rmfield(obj.oKSOP,{'ind','n'});

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

At minimum, the method should initialize

• In obj.oRho, outDensity.total, outDensity.totalUp and outDensity.totalDown
• in obj.sKSO, outOrbital.orbital, outOrbital.indexOrbital, outOrbital.orbitalUp, outOrbital.orbitalDown, outOrbital.indexOrbitalUp, and outOrbital.indexOrbitalDown
• In obj.sKSOP, outOrbital.orbital, outOrbital.indexOrbital, outOrbital.orbitalUp, outOrbital.orbitalDown, outOrbital.indexOrbitalUp, and outOrbital.indexOrbitalDown. The structure should also retain a copy of the projection basis.

setTimeStep

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

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

end
end

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

applyTimeStep

Propagate the TDDFT 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

saveOutputDipole

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

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

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

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

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

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

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

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

end
end

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

getExternalFieldEnergy

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 DFT-functional energy from any external field. For spin-polarized models, it is a 2-vector with the up- and down-spin energy contributions, respectively. If not field is applied, or it does not contribute an explicit terms to the DFT energy (e.g., velocity-gauge dipole approximation), return E = [0;0]
• DE is the autonomization energy variable, which tracks how mucg energy is put into or withdrawn from the DFT system
• The DFT object contains an accurate one-body density

saveOutputIonization

Compute the ionization statistics

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

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

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

end
end

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

saveOutputOrbitalDensity

Save the Kohn-Sham orbitals (projection) and one-body density

methods (Access=protected)
function saveOutputOrbitalDensity(obj,k,t)
%setTimeStep
    
    % Save Kohn-Sham orbitals
    if k == obj.oKSO.ind(obj.oKSO.n)
        % Kohn-Sham orbitals
        
        % Add external field
        if obj.sEF,         obj.addOutputExternalField('oKSO',k,t);         end

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

        % Update counter
        obj.oKSOP.n     =   obj.oKSOP.n + 1;
    end
    
    % Save the one-body density
    if k == obj.oRho.ind(obj.oRho.n)
        % One-body density
        
        % Add external field
        if obj.sEF,         obj.addOutputExternalField('oRho',k,t);         end

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

end
end

• saveOutputOrbitalDensity is called is any of the Kohn-Sham orbitals, their projection, or one-body density needs to be saved. It must therefore determine which one(s) actually need to be.
• saveOutputOrbitalDensity is also responsible for updating the counters in obj.oKSO, obj.oKSOP and obj.oRho (see their respective documentation entry for the name convention in what/how each should be saved).

Additional optional methods to overload

getMemoryProfilePropagator

Estimate the memory footprint of the implementation-specific part of the TDDFT 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_DFT_profiler.showMemoryFootprint to display the memory footprint of the propagator's components (when opt == true)
• getMemoryProfilePropagator should only list the memory footprint of the propagation part of the implementation-specific class. Estimate of the memory footprint for the output results is handled with the getMemoryProfileOrbitalDensity and getMemoryProfileChildren properties.
• The DFT object is initialized when getMemoryProfilePropagator is called

getMemoryProfileOrbitalDensity

Estimate the memory footprint for saving of the Kohn-Sham orbitals and one-body density in the implementation-specific TDDFT propagator

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

    % Estimate of the memory footprint

end
end

• Use QMol_DFT_profiler.showMemoryFootprint to display the memory footprint of saving the Kohn-Sham orbitals ans/or one-body density (when opt == true)
• getMemoryProfileOrbitalDensity should only list the memory footprint of the requested Kohn-Sham orbitals and/or one-body density. Estimate of the memory footprint for any additional implementation-specific output results with getMemoryProfileChildren.
• The DFT object is initialized when getMemoryProfileOrbitalDensity is called

getMemoryProfileChildren

Estimate the memory footprint of additional output defined by the implementation-specific part of the TDDFT 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_DFT_profiler.showMemoryFootprint to display the memory footprint of the additional outputs (when opt == true)
• getMemoryProfileChildren should only list the memory footprint of additional output defined by the implementation-specific TDDFT propagator. Estimate of the memory footprint for the Kohn-Sham orbitals and one-body density output results is handled with getMemoryProfileOrbitalDensity
• The DFT object is initialized when getMemoryProfileChildren is called

docOutputChildren

Run-time documentation for additional implementation-specific output variables

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

end
end

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

setOutputChildren

Implementation-specific TDDFT propagation classes that overload QMol_TDDFT 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 TDDFT propagation

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

setOutputExternalField

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 TDDFT propagation
    % (for the external-field information only)

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

• setOutputExternalField is called in the initialization and cleanup of each of the setOutputDipole, setOutputEnergy, setOutputFunction, setOutputIonization, and setOutputOrbitalDensity
• 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.

setRestartChildren

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

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

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

saveOutputChildren

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 TDDFT propagation. The class is responsible for checking which additional data must be saved, if any, and doing the actual saving.

addOutputExternalField

Adds the external-field information to a given output structure

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

    % Add external-field information to output structure
end
end

• addOutputExternalField is called by saveOutputDipole, saveOutputEnergy, saveOutputFunction, saveOutputIonization, and saveOutputOrbitalDensity
• 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

saveRestartChildren

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

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

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

Boundary absorber

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

classdef QMol_DFT_absorber < QMol_suite
%QMol_DFT_absorber 

%% Documentation %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
methods (Static,Access=private)
function version
    QMol_doc.showVersion('##.##.###','##/##/####','Author Name')
end
end
methods (Static,Access={?QMol_doc,?QMol_DFT_absorber})
function showInfo
    fprintf( '  * QMol_DFT_absorber:\n');
    fprintf(['      > Absorbing boundaries\n',...
             '      > Type of absorber\n']); 
    QMol_DFT_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_DFT_absorber,?QMol_DFT})
    % Linked objects
    DFT                             % DFT.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.DFT             =   [];
    
    % Initialization status
    obj.isInit          =   false;
end
function initialize(obj,DFT,isFwd)
%initialize initializes the object

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

    % 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_DFT_absorber';
    PropNames           =   {};
end
end
%% Absorber %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
methods (Access=public)
    applyMask(obj,KSO)
    V = getPotential(obj,V)
end
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
end

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

Mask function

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,KSO)
%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 DFT potential untouched

Complex absorbing potential (CAP)

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

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

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

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

end

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

Test suite

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

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

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

Notes

• QMol_TDDFT was introduced in version 01.00 but version 01.10 drastically redesigned its interface and supported features
• getMemoryProfile was introduced in version 01.10