Time-Dependent

TDExternalFields
Section: Time-Dependent
Type: block

The block TDExternalFields describes the type and shape of time-dependent external perturbations that are applied to the system.

Each line of the block describes an external field; this way you can actually have more than one laser (e.g. a "pump" and a "probe").

The syntax of each line is:

%TDExternalField
   type | ...other descriptors...
%


The first element of each line describes which kind of external field is described by the line: (i) an electric field (electric_field); (ii) a magnetic field (magnetic_field); (iii) a vector potential (vector_potential) -- this option, in the current version, is a field constant in space, which permits us to describe an electric perturbation in the velocity gauge; (iv) an arbitrary scalar potential (scalar_potential). The last element is optional and indicates the carrier phase function \(\phi(t)\). It is a time dependent function and as such it should match one of the function names given in the first column of the TDFunctions block.

The "other descriptors" depend on which kind of external field has been indicated in the first column.

(A) type = electric field, magnetic field, vector_potential

For these cases, the syntax is:

%TDExternalFields
   type | nx | ny | nz | omega | envelope_function_name | phase
%


The three (possibly complex) numbers (nx, ny, nz) mark the polarization direction of the field. The float omega will be the carrier frequency of the pulse (in energy units). The envelope of the field is a time-dependent function whose definition must be given in a TDFunctions block. envelope_function_name is a string (and therefore it must be surrounded by quotation marks) that must match one of the function names given in the first column of the TDFunctions block.

(B) type = scalar_potential

%TDExternalFields
   scalar_potential | "scalar_expression" | freq | envelope_function_name | phase
%


The scalar potential is not just a dipole, but any expression given by the string "scalar_expression". The temporal shape is determined by the envelope function defined by envelope_function_name.

A NOTE ON UNITS:

It is very common to describe the strength of a laser field by its intensity, rather than using the electric-field amplitude. In atomic units (or, more precisely, in any Gaussian system of units), the relationship between instantaneous electric field and intensity is: \( I(t) = \frac{c}{8\pi} E^2(t) \).

It is common to read intensities in W/cm\(^2\). The dimensions of intensities are [W]/(L\(^2\)T), where [W] are the dimensions of energy. The relevant conversion factors are:

Hartree / (\(a_0^2\) atomic_time) = \(6.4364086 \times 10^{15} \mathrm{W/cm}^2\)

eV / ( Å\(^2 (\hbar\)/eV) ) = \(2.4341348 \times 10^{12} \mathrm{W/cm}^2\)

If, in atomic units, we set the electric-field amplitude to \(E_0\), then the intensity is:

\( I_0 = 3.51 \times 10^{16} \mathrm{W/cm}^2 (E_0^2) \)

If, working with Units = ev_angstrom, we set \(E_0\), then the intensity is:

\( I_0 = 1.327 \times 10^{13} (E_0^2) \mathrm{W/cm}^2 \)


Options:


TDFreezeHXC
Section: Time-Dependent
Type: logical
Default: no

The electrons are evolved as independent particles feeling the Hartree and exchange-correlation potentials from the ground-state electronic configuration.


TDFreezeOrbitals
Section: Time-Dependent
Type: integer
Default: 0

(Experimental) You have the possibility of "freezing" a number of orbitals during a time-propagation. The Hartree and exchange-correlation potential due to these orbitals (which will be the lowest-energy ones) will be added during the propagation, but the orbitals will not be propagated.
Options:


TDFunctions
Section: Time-Dependent
Type: block

This block specifies the shape of a "time-dependent function", such as the envelope needed when using the TDExternalFields block. Each line in the block specifies one function. The first element of each line will be a string that defines the name of the function. The second element specifies which type of function we are using; in the following we provide an example for each of the possible types:


Options:


Time-Dependent::Absorbing Boundaries

ABHeight
Section: Time-Dependent::Absorbing Boundaries
Type: float
Default: -0.2 a.u.

When AbsorbingBoundaries = sin2, this is the height of the imaginary potential.


ABWidth
Section: Time-Dependent::Absorbing Boundaries
Type: float
Default: 0.4 a.u.

Width of the region used to apply the absorbing boundaries.


AbsorbingBoundaries
Section: Time-Dependent::Absorbing Boundaries
Type: integer
Default: not_absorbing

To improve the quality of the spectra by avoiding the formation of standing density waves, one can make the boundaries of the simulation box absorbing.
Options:


Time-Dependent::Open Boundaries

MemoryMaxIter
Section: Time-Dependent::Open Boundaries
Type: integer
Default: 500

Sets the maximum iteration number to converge the memory coefficients.


MemoryTol
Section: Time-Dependent::Open Boundaries
Type: float
Default: 1e-12

Decides when to consider the memory coefficients converged.


Time-Dependent::PhotoElectronSpectrum

PESMask2PEnlargeFactor
Section: Time-Dependent::PhotoElectronSpectrum
Type: float
Default: 1.0

Mask two points enlargement factor. Enlarges the mask box by adding two points at the edges of the box in each direction (x,y,z) at a distance L=Lb*PESMask2PEnlargeFactor where Lb is the box size. This allows to run simulations with an additional void space at a price of adding few points. The Fourier space associated with the new box is restricted by the same factor.

Note: needs PESMaskPlaneWaveProjection = nfft_map or pnfft_map .


PESMaskEnlargeFactor
Section: Time-Dependent::PhotoElectronSpectrum
Type: float
Default: 1

Mask box enlargement level. Enlarges the mask bounding box by a PESMaskEnlargeFactor. This helps to avoid wavefunction wrapping at the boundaries.


PESMaskFilterCutOff
Section: Time-Dependent::PhotoElectronSpectrum
Type: float
Default: -1

In calculation with PESMaskMode = fullmask_mode and NFFT, spurious frequencies may lead to numerical instability of the algorithm. This option gives the possibility to filter out the unwanted components by setting an energy cut-off. If PESMaskFilterCutOff = -1 no filter is applied.


PESMaskIncludePsiA
Section: Time-Dependent::PhotoElectronSpectrum
Type: logical
Default: false

Add the contribution of \(\Psi_A\) in the mask region to the photo-electron spectrum. Literally adds the Fourier components of: \(\Theta(r-R1) \Psi_A(r)\) with \(\Theta\) being the Heaviside step function. With this option PES will contain all the contributions starting from the inner radius \(R1\). Use this option to improve convergence with respect to the box size and total simulation time. Note: Carefully choose \(R1\) in order to avoid contributions from returning electrons.


PESMaskMode
Section: Time-Dependent::PhotoElectronSpectrum
Type: integer
Default: mask_mode

PES calculation mode.
Options:


PESMaskOutputInterpolate
Section: Time-Dependent::PhotoElectronSpectrum
Type: logical
Default: false

Use interpolation to evaluate the quantities in polar coordinates. NOTE: In 3D this is practically prohibitive in the present implementation. We suggest to use the postprocessing tool oct-photoelectron_spectrum in this case.


PESMaskPlaneWaveProjection
Section: Time-Dependent::PhotoElectronSpectrum
Type: integer
Default: fft_map

With the mask method, wavefunctions in the continuum are treated as plane waves. This variable sets how to calculate the plane-wave projection in the buffer region. We perform discrete Fourier transforms (DFT) in order to approximate a continuous Fourier transform. The major drawback of this approach is the built-in periodic boundary condition of DFT. Choosing an appropriate plane-wave projection for a given simulation in addition to PESMaskEnlargeFactor and PESMask2PEnlargeFactorwill help to converge the results.

NOTE: depending on the value of PESMaskMode PESMaskPlaneWaveProjection, may affect not only performance but also the time evolution of the density.
Options:


PESMaskPropagator
Section: Time-Dependent::PhotoElectronSpectrum
Type: integer
Default: volkov

Photoelectron waves time-propagation operator in momentum space.
Options:


PESMaskShape
Section: Time-Dependent::PhotoElectronSpectrum
Type: integer
Default: m_sin2

The mask function shape.
Options:


PESMaskSize
Section: Time-Dependent::PhotoElectronSpectrum
Type: block

Set the size of the mask function. Here you can set the inner (R1) and outer (R2) radius by setting the block as follows:

%PESMaskSize
   R1 | R2
%


PESMaskSpectEnergyMax
Section: Time-Dependent::PhotoElectronSpectrum
Type: float
Default: maxval(mask%Lk)\(^2/2\)

The maximum energy for the PES spectrum.


PESMaskSpectEnergyStep
Section: Time-Dependent::PhotoElectronSpectrum
Type: float

The PES spectrum energy step.


PESMaskStartTime
Section: Time-Dependent::PhotoElectronSpectrum
Type: float
Default: -1.0

The time photoelectrons start to be recorded. In pump-probe simulations, this allows getting rid of an unwanted ionization signal coming from the pump. NOTE: This will enforce the mask boundary conditions for all times.


PhotoElectronSpectrum
Section: Time-Dependent::PhotoElectronSpectrum
Type: flag
Default: none


Options:


PhotoElectronSpectrumPoints
Section: Time-Dependent::PhotoElectronSpectrum
Type: block

List of points at which to calculate the photoelectron spectrum by Suraud method. Required when PhotoElectronSpectrum = pes_rc. The exact syntax is:

%PhotoElectronSpectrumPoints
  x1 | y1 | z1
%


Time-Dependent::Propagation

IonsConstantVelocity
Section: Time-Dependent::Propagation
Type: logical
Default: no

(Experimental) If this variable is set to yes, the ions will move with a constant velocity given by the initial conditions. They will not be affected by any forces.


MoveIons
Section: Time-Dependent::Propagation
Type: logical
Default: no

This variable controls whether atoms are moved during a time propagation run. The default is no.


RecalculateGSDuringEvolution
Section: Time-Dependent::Propagation
Type: logical
Default: no

In order to calculate some information about the system along the evolution (e.g. projection onto the ground-state KS determinant, projection of the TDKS spin-orbitals onto the ground-state KS spin-orbitals), the ground-state KS orbitals are needed. If the ionic potential changes -- that is, the ions move -- one may want to recalculate the ground state. You may do this by setting this variable.

The recalculation is not done every time step, but only every RestartWriteInterval time steps.


TDDynamics
Section: Time-Dependent::Propagation
Type: integer
Default: ehrenfest

Type of dynamics to follow during a time propagation. For BO, you must set MoveIons = yes.
Options:


TDEnergyUpdateIter
Section: Time-Dependent::Propagation
Type: integer
Default: 10

This variable controls after how many iterations Octopus updates the total energy during a time-propagation run. For iterations where the energy is not updated, the last calculated value is reported. If you set this variable to 1, the energy will be calculated in each step.


TDExpOrder
Section: Time-Dependent::Propagation
Type: integer
Default: 4

For TDExponentialMethod = standard or chebyshev, the order to which the exponential is expanded. For the Lanczos approximation, it is the Lanczos-subspace dimension.


TDExponentialMethod
Section: Time-Dependent::Propagation
Type: integer
Default: taylor

Method used to numerically calculate the exponential of the Hamiltonian, a core part of the full algorithm used to approximate the evolution operator, specified through the variable TDPropagator. In the case of using the Magnus method, described below, the action of the exponential of the Magnus operator is also calculated through the algorithm specified by this variable.
Options:


TDIonicTimeScale
Section: Time-Dependent::Propagation
Type: float
Default: 1.0

This variable defines the factor between the timescale of ionic and electronic movement. It allows reasonably fast Born-Oppenheimer molecular-dynamics simulations based on Ehrenfest dynamics. The value of this variable is equivalent to the role of \(\mu\) in Car-Parrinello. Increasing it linearly accelerates the time step of the ion dynamics, but also increases the deviation of the system from the Born-Oppenheimer surface. The default is 1, which means that both timescales are the same. Note that a value different than 1 implies that the electrons will not follow physical behaviour.

According to our tests, values around 10 are reasonable, but it will depend on your system, mainly on the width of the gap.

Important: The electronic time step will be the value of TDTimeStep divided by this variable, so if you have determined an optimal electronic time step (that we can call dte), it is recommended that you define your time step as:

TDTimeStep = dte * TDIonicTimeScale

so you will always use the optimal electronic time step (more details).


TDLanczosTol
Section: Time-Dependent::Propagation
Type: float
Default: 1e-5

An internal tolerance variable for the Lanczos method. The smaller, the more precisely the exponential is calculated, and also the bigger the dimension of the Krylov subspace needed to perform the algorithm. One should carefully make sure that this value is not too big, or else the evolution will be wrong.


TDMaximumIter
Section: Time-Dependent::Propagation
Type: integer
Default: 1500

Number of time-propagation steps that will be performed. By default 1500.

Tip: If you would like to specify the real time of the propagation, rather than the number of steps, just use something like:

TDMaximumIter = 1000.0 / TDTimeStep


TDPropagator
Section: Time-Dependent::Propagation
Type: integer
Default: etrs

This variable determines which algorithm will be used to approximate the evolution operator \(U(t+\delta t, t)\). That is, given \(\psi(\tau)\) and \(H(\tau)\) for \(\tau \le t\), calculate \(t+\delta t\). Note that in general the Hamiltonian is not known at times in the interior of the interval \([t,t+\delta t]\). This is due to the self-consistent nature of the time-dependent Kohn-Sham problem: the Hamiltonian at a given time \(\tau\) is built from the "solution" wavefunctions at that time.

Some methods, however, do require the knowledge of the Hamiltonian at some point of the interval \([t,t+\delta t]\). This problem is solved by making use of extrapolation: given a number \(l\) of time steps previous to time \(t\), this information is used to build the Hamiltonian at arbitrary times within \([t,t+\delta t]\). To be fully precise, one should then proceed self-consistently: the obtained Hamiltonian at time \(t+\delta t\) may then be used to interpolate the Hamiltonian, and repeat the evolution algorithm with this new information. Whenever iterating the procedure does not change the solution wavefunctions, the cycle is stopped. In practice, in Octopus we perform a second-order extrapolation without a self-consistency check, except for the first two iterations, where obviously the extrapolation is not reliable.

The proliferation of methods is certainly excessive. The reason for it is that the propagation algorithm is currently a topic of active development. We hope that in the future the optimal schemes are clearly identified. In the mean time, if you do not feel like testing, use the default choices and make sure the time step is small enough.
Options:


TDSCFThreshold
Section: Time-Dependent::Propagation
Type: float
Default: 1.0e-3

Since the KS propagator is non-linear, each propagation stepp should be performed self-consistently. In practice, for most purposes this is not necessary, except perhaps in the first iterations. This variable holds the number of propagation steps for which the propagation is done self-consistently.

The self consistency has to be measured against some accuracy threshold. This variable controls the value of that threshold.


TDStepsWithSelfConsistency
Section: Time-Dependent::Propagation
Type: integer
Default: 3

Since the KS propagator is non-linear, each propagation step should be performed self-consistently. In practice, for most purposes this is not necessary, except perhaps in the first iterations. This variable holds the number of propagation steps for which the propagation is done self-consistently.

The special value all_steps forces self-consistency to be imposed on all propagation steps. A value of 0 means that self-consistency will not be imposed. The default is 3, which means that self-consistency is only enforced during the first three steps.
Options:


TDTimeStep
Section: Time-Dependent::Propagation
Type: float

The time-step for the time propagation. For most propagators you want to use the largest value that is possible without the evolution becoming unstable.

The default value is the maximum value that we have found empirically that is stable for the spacing Octopus is using. However, you might need to adjust this value.


TemperatureFunction
Section: Time-Dependent::Propagation
Type: integer
Default: "temperature"

If a thermostat is used, this variable indicates the name of the function in the TDFunctions block that will be used to control the temperature. The values of the temperature are given in degrees Kelvin.


Thermostat
Section: Time-Dependent::Propagation
Type: integer
Default: none

This variable selects the type of thermostat applied to control the ionic temperature.
Options:


ThermostatMass
Section: Time-Dependent::Propagation
Type: float
Default: 1.0

This variable sets the fictitious mass for the Nose-Hoover thermostat.


Time-Dependent::Response

TDDeltaKickTime
Section: Time-Dependent::Response
Type: float
Default: 0.0

The delta-perturbation that can be applied by making use of the TDDeltaStrength variable, can be applied at the time given by this variable. Usually, this time is zero, since one wants to apply the delta pertubation or "kick" at a system at equilibrium, and no other time-dependent external potential is used. However, one may want to apply a kick on top of a laser field, for example.


TDDeltaStrength
Section: Time-Dependent::Response
Type: float
Default: 0

When no laser is applied, a delta (in time) perturbation with strength TDDeltaStrength can be applied. This is used to calculate, e.g., the linear optical spectra. If the ions are allowed to move, the kick will affect them also. The electric field is \(-(\hbar k / e) \delta(t)\) for a dipole with zero wavevector, where k = TDDeltaStrength, which causes the wavefunctions instantaneously to acquire a phase \(e^{ikx}\). The unit is inverse length.


TDDeltaStrengthMode
Section: Time-Dependent::Response
Type: integer
Default: kick_density

When calculating the density response via real-time propagation, one needs to perform an initial kick on the KS system, at time zero. Depending on what kind of response property one wants to obtain, this kick may be done in several modes. For use to calculate triplet excitations, see MJT Oliveira, A Castro, MAL Marques, and A Rubio, J. Nanoscience and Nanotechnology 8, 3392 (2008).
Options:


TDDeltaUserDefined
Section: Time-Dependent::Response
Type: string

By default, the kick function will be a dipole. This will change if (1) the variable TDDeltaUserDefined is present in the inp file, or (2) if the block TDKickFunction is present in the inp file. If both are present in the inp file, the TDKickFunction block will be ignored. The value of TDDeltaUserDefined should be a string describing the function that is going to be used as delta perturbation.


TDKickFunction
Section: Time-Dependent::Response
Type: block

If the block TDKickFunction is present in the input file, and the variable TDDeltaUserDefined is not present in the input file, the kick function to be applied at time zero of the time-propagation will not be a "dipole" function (i.e. \(\phi \rightarrow e^{ikx} \phi\), but a general multipole in the form \(r^l Y_{lm}(r)\).

Each line has three columns: integers l and m that defines the multipole, and a weight. Any number of lines may be given, and the kick will be the sum of those multipoles with the given weights.

This feature allows calculation of quadrupole, octupole, etc., response functions.


TDMomentumTransfer
Section: Time-Dependent::Response
Type: block

Momentum-transfer vector for the calculation of the dynamic structure factor. When this variable is set, a non-dipole field is applied, and an output file ftchd is created (it contains the Fourier transform of the charge density at each time). The type of the applied external field can be set by an optional last number. Possible options are qexp (default), qcos, qsin, or qcos+qsin. In the formulae below, \(\vec{q}\) is the momentum-transfer vector.
Options:


Time-Dependent::Response::Dipole

TDPolarization
Section: Time-Dependent::Response::Dipole
Type: block

The (real) polarization of the delta electric field. Normally one needs three perpendicular polarization directions to calculate a spectrum (unless symmetry is used). The format of the block is:

%TDPolarization
  pol1x | pol1y | pol1z
  pol2x | pol2y | pol2z
  pol3x | pol3y | pol3z
%


Octopus uses both this block and the variable TDPolarizationDirection to determine the polarization vector for the run. For example, if TDPolarizationDirection=2 the polarization (pol2x, pol2y, pol2z) would be used. These directions may not be in periodic directions.

The default value for TDPolarization is the three Cartesian unit vectors (1,0,0), (0,1,0), and (0,0,1).

Note that the directions do not necessarily need to be perpendicular when symmetries are used.

WARNING: If you want to obtain the cross-section tensor, the TDPolarization block must be exactly the same for the run in each direction. The direction must be selected by the TDPolarizationDirection variable.


TDPolarizationDirection
Section: Time-Dependent::Response::Dipole
Type: integer
Default: 1

When a delta potential is included in a time-dependent run, this variable defines in which direction the field will be applied by selecting one of the lines of TDPolarization. In a typical run (without using symmetry), the TDPolarization block would contain the three Cartesian unit vectors (the default value), and one would make 3 runs varying TDPolarization from 1 to 3. If one is using symmetry, TDPolarization should run only from 1 to TDPolarizationEquivAxes.


TDPolarizationEquivAxes
Section: Time-Dependent::Response::Dipole
Type: integer
Default: 0

Defines how many of the TDPolarization axes are equivalent. This information is stored in a file and then used by oct-propagation_spectrum to rebuild the full polarizability tensor from just the first TDPolarizationEquivAxes directions. This variable is also used by CalculationMode = vdw.


TDPolarizationWprime
Section: Time-Dependent::Response::Dipole
Type: block

This block is needed only when TDPolarizationEquivAxes is set to 3. In such a case, the three directions (pol1, pol2, and pol3) defined in the TDPolarization block should be related by symmetry operations. If A is the symmetry operation that takes you from pol1 to pol2, then TDPolarizationWprime should be set to the direction defined by A\(^{-1}\)pol3. For more information see MJT Oliveira et al., J. Nanoscience and Nanotechnology 8, 3392 (2008).


Time-Dependent::TD Output

TDExcitedStatesToProject
Section: Time-Dependent::TD Output
Type: block

[WARNING: This is a *very* experimental feature] To be used with TDOutput = populations. The population of the excited states (as defined by where |Phi(t)> is the many-body time-dependent state at time t, and |Phi_I> is the excited state of interest) can be approximated -- it is not clear how well -- by substituting for those real many-body states the time-dependent Kohn-Sham determinant and some modification of the Kohn-Sham ground-state determinant (e.g., a simple HOMO-LUMO substitution, or the Casida ansatz for excited states in linear-response theory. If you set TDOutput to contain populations, you may ask for these approximated populations for a number of excited states, which will be described in the files specified in this block: each line should be the name of a file that contains one excited state.

This file structure is the one written by the casida run mode, in the files in the directory *_excitations. The file describes the "promotions" from occupied to unoccupied levels that change the initial Slater determinant structure specified in ground_state. These promotions are a set of electron-hole pairs. Each line in the file, after an optional header, has four columns:

i a sigma weight

where i should be an occupied state, a an unoccupied one, and sigma the spin of the corresponding orbital. This pair is then associated with a creation-annihilation pair \(a^{\dagger}_{a,sigma} a_{i,sigma}\), so that the excited state will be a linear combination in the form:

\(\left|{\rm ExcitedState}\right> = \sum [ weight(i,a,sigma) a^{\dagger}_{a,sigma} a_{i,sigma} \left|{\rm GroundState}\right> ]\)

where weight is the number in the fourth column. These weights should be normalized to one; otherwise the routine will normalize them, and write a warning.


TDMultipoleLmax
Section: Time-Dependent::TD Output
Type: integer
Default: 1

Maximum electric multipole of the density output to the file td.general/multipoles during a time-dependent simulation. Must be non-negative.


TDOutput
Section: Time-Dependent::TD Output
Type: flag
Default: multipoles + energy (+ others depending on other options)

Defines what should be output during the time-dependent simulation. Many of the options can increase the computational cost of the simulation, so only use the ones that you need. In most cases the default value is enough, as it is adapted to the details of the TD run. If the ions are allowed to be moved, additionally the geometry and the temperature are output. If a laser is included it will output by default.

Note: the output files generated by this option are updated every RestartWriteInterval steps.
Options:


TDProjStateStart
Section: Time-Dependent::TD Output
Type: integer
Default: 1

To be used with TDOutput = td_occup. Not available if TDOutput = populations. Only output projections to states above TDProjStateStart. Usually one is only interested in particle-hole projections around the HOMO, so there is no need to calculate (and store) the projections of all TD states onto all static states. This sets a lower limit. The upper limit is set by the number of states in the propagation and the number of unoccupied states available.


Time-Dependent::TDPSF

TDPSFDelta
Section: Time-Dependent::TDPSF
Type: float
Default: 0.0001

Filter error threshold.


TDPSFKmin
Section: Time-Dependent::TDPSF
Type: float
Default: \(\pi\)/width

k-space filter width.


TDPSFSigma
Section: Time-Dependent::TDPSF
Type: float
Default: \(\sqrt{2}\)

Standard deviation of the phase-space filter.