Octopus

TDChebyshevTol

TDDeltaKickTime

TDDeltaStrength

TDDeltaStrengthMode

TDDeltaUserDefined

TDDynamics

TDEasyAxis

TDEnergyUpdateIter

TDExcitedStatesToProject

TDExponentialMethod

Name 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:

lanczos:
Allows for larger time-steps. However, the larger the time-step, the longer the computational time per time-step. In certain cases, if the time-step is too large, the code will emit a warning whenever it considers that the evolution may not be properly proceeding -- the Lanczos process did not converge. The method consists in a Krylov subspace approximation of the action of the exponential (see M. Hochbruck and C. Lubich, SIAM J. Numer. Anal. 34, 1911 (1997) for details). The performance of the method is controlled by the tolerance (controlled by TDLanczosTol). The smaller the tolerance, the more precisely the exponential is calculated, but also the larger the dimension of the Arnoldi subspace. If the maximum dimension (currently 200) is not enough to meet the criterion, the above-mentioned warning is emitted. Be aware that the larger the required dimension of the Krylov subspace, the larger the memory required for this method. So if you run out of memory, try to reduce the time step.
taylor:
This method amounts to a straightforward application of the definition of the exponential of an operator, in terms of its Taylor expansion.
$\exp_{\rm STD} (-i\delta t H) = \sum_{i=0}^{k} {(-i\delta t)^i\over{i!}} H^i.$

The order k is determined by variable TDExpOrder. Some numerical considerations from Jeff Giansiracusa and George F. Bertsch suggest the 4th order as especially suitable and stable.
chebyshev:
In principle, the Chebyshev expansion of the exponential represents it more accurately than the canonical or standard expansion. TDChebyshevTol determines the tolerance to which the expansion is computed.
There exists a closed analytic form for the coefficients of the exponential in terms of Chebyshev polynomials:

$\exp_{\rm CHEB} \left( -i\delta t H \right) = \sum_{k=0}^{\infty} (2-\delta_{k0})(-i)^{k}J_k(\delta t) T_k(H),$

where $J_k$ are the Bessel functions of the first kind, and H has to be previously scaled to $[-1,1]$. See H. Tal-Ezer and R. Kosloff, J. Chem. Phys. 81, 3967 (1984); R. Kosloff, Annu. Rev. Phys. Chem. 45, 145 (1994); C. W. Clenshaw, MTAC 9, 118 (1955).

TDExpOrder

TDExternalFields

Name 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, in the form $f(x,y,z) \cos(\omega t + \phi (t)) g(t)$, where $f(x,y,z)$ is defined by by a field type and polarization or a scalar potential, as below; $\omega$ is defined by omega; $g(t)$ is defined by envelope_function_name; and $\phi(t)$ is the (time-dependent) phase from phase.

These perturbations are only applied for time-dependent runs. If you want the value of the perturbation at time zero to be applied for time-independent runs, use TimeZero = yes.

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

There are two ways to specify $f(x,y,z)$ but both use the same omega | envelope_function_name [| phase] for the time-dependence. 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. phase is optional and is taken to be zero if not provided, and is also a string specifying a time-dependent function.

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

For these cases, the syntax is:

%TDExternalFields type | nx | ny | nz | omega | envelope_function_name | phase (| px | py | pz ) %

The vector_potential option (constant in space) permits us to describe an electric perturbation in the velocity gauge. The three (possibly complex) numbers (nx, ny, nz) mark the polarization direction of the field. By default, (nx, ny, nz) are defined in Cartesian space. However, it is possible for solids to define them using the Miller indices. This can be achieved by defining the block MillerIndicesBasis. It is also possible to activate the nondipole SFA correction by inserting the laser propagation direction px | py | pz as prescribed in Phys. Rev. A 101, 043408 (2020).

(B) type = scalar_potential

%TDExternalFields scalar_potential | "spatial_expression" | omega | envelope_function_name | phase %

The scalar potential is any expression of the spatial coordinates given by the string "spatial_expression", allowing a field beyond the dipole approximation.

For DFTB runs, only fields of type type = electric field are allowed for the moment, and the type keyword is omitted.

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:

electric_field:
The external field is an electric field, the usual case when we want to describe a laser in the length gauge.
magnetic_field:
The external field is a (homogeneous) time-dependent magnetic field.
vector_potential:
The external field is a time-dependent homogeneous vector potential, which may describe a laser field in the velocity gauge.
scalar_potential:
The external field is an arbitrary scalar potential, which may describe an inhomogeneous electrical field.

TDFloquetDimension

TDFloquetFrequency

TDFloquetSample

TDFreezeDFTUOccupations

TDFreezeHXC

TDFreezeOrbitals

TDFreezeU

TDFunctions

TDGlobalForce

TDIonicTimeScale

TDKickFunction

TDLanczosTol

TDMaxSteps

TDMomentumTransfer

TDMultipleMomentumTransfer

TDMultipoleLmax

TDOutput

Name TDOutput
Section Time-Dependent::TD Output
Type block
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.

Example:

%TDOutput multipoles energy %

Options:

multipoles:
Outputs the (electric) multipole moments of the density to the file td.general/multipoles. This is required to, e.g., calculate optical absorption spectra of finite systems. The maximum value of $l$ can be set with the variable TDMultipoleLmax.
angular:
Outputs the orbital angular momentum of the system to td.general/angular. This can be used to calculate circular dicrhoism. Not implemented for periodic systems. In case of a nonlocal pseudopotential, the gauge used can be specified using the variable MagneticGaugeCorrection.
spin:
(Experimental) Outputs the expectation value of the spin, which can be used to calculate magnetic circular dichroism.
populations:
(Experimental) Outputs the projection of the time-dependent Kohn-Sham Slater determinant onto the ground state (or approximations to the excited states) to the file td.general/populations. Note that the calculation of populations is expensive in memory and computer time, so it should only be used if it is really needed. See TDExcitedStatesToProject.
geometry:
If set (and if the atoms are allowed to move), outputs the coordinates, velocities, and forces of the atoms to the the file td.general/coordinates. On by default if MoveIons = yes.
dipole_acceleration:
When set, outputs the acceleration of the electronic dipole, calculated from the Ehrenfest theorem, in the file td.general/acceleration. This file can then be processed by the utility oct-harmonic-spectrum in order to obtain the harmonic spectrum.
laser:
If set, outputs the laser field to the file td.general/laser. On by default if TDExternalFields is set.
energy:
If set, octopus outputs the different components of the energy to the file td.general/energy. Will be zero except for every TDEnergyUpdateIter iterations.
td_occup:
(Experimental) If set, outputs the projections of the time-dependent Kohn-Sham wavefunctions onto the static (zero-time) wavefunctions to the file td.general/projections.XXX. Only use this option if you really need it, as it might be computationally expensive. See TDProjStateStart. The output interval of this quantity is controled by the variable TDOutputComputeInterval In case of states parallelization, all the ground-state states are stored by each task.
local_mag_moments:
If set, outputs the local magnetic moments, integrated in sphere centered around each atom. The radius of the sphere can be set with LocalMagneticMomentsSphereRadius.
gauge_field:
If set, outputs the vector gauge field corresponding to a spatially uniform (but time-dependent) external electrical potential. This is only useful in a time-dependent periodic run. On by default if GaugeVectorField is set.
temperature:
If set, the ionic temperature at each step is printed. On by default if MoveIons = yes.
ftchd:
Write Fourier transform of the electron density to the file ftchd.X, where X depends on the kick (e.g. with sin-shaped perturbation X=sin). This is needed for calculating the dynamic structure factor. In the case that the kick mode is qbessel, the written quantity is integral over density, multiplied by spherical Bessel function times real spherical harmonic. On by default if TDMomentumTransfer is set.
dipole_velocity:
When set, outputs the dipole velocity, calculated from the Ehrenfest theorem, in the file td.general/velocity. This file can then be processed by the utility oct-harmonic-spectrum in order to obtain the harmonic spectrum.
eigenvalues:
Write the KS eigenvalues.
ionization_channels:
Write the multiple-ionization channels using the KS orbital densities as proposed in C. Ullrich, Journal of Molecular Structure: THEOCHEM 501, 315 (2000).
total_current:
Output the total current (average of the current density over the cell).
partial_charges:
Bader and Hirshfeld partial charges. The output file is called 'td.general/partial_charges'.
td_kpoint_occup:
Project propagated Kohn-Sham states to the states at t=0 given in the directory restart_proj (see %RestartOptions). This is an alternative to the option td_occup, with a formating more suitable for k-points and works only in k- and/or state parallelization
td_floquet:
Compute non-interacting Floquet bandstructure according to further options: TDFloquetFrequency, TDFloquetSample, TDFloquetDimension. This is done only once per td-run at t=0. works only in k- and/or state parallelization
n_excited_el:
Output the number of excited electrons, based on the projections of the time evolved wave-functions on the ground-state wave-functions. The output interval of this quantity is controled by the variable TDOutputComputeInterval Note that if one sets RecalculateGSDuringEvolution=yes, the code will recompute the GS states and use them for the computing the number of excited electrons. This is useful if ions are moving or if one wants to get the number of excited electrons in the basis of the instantaneous eigenvalues of the Hamiltonian (Houston states).
coordinates_sep:
Writes geometries in a separate file.
velocities_sep:
Writes velocities in a separate file.
forces_sep:
Writes forces in a separate file.
total_heat_current:
Output the total heat current (average of the heat current density over the cell).
total_magnetization:
Writes the total magnetization, where the total magnetization is calculated at the momentum defined by TDMomentumTransfer. This is used to extract the magnon frequency in case of a magnon kick.
photons_q:
Writes photons_q in a separate file.
maxwell_field:
Writes total electric field (if coupling is in length_geuge) or vector potential (if coupling is in velocity_gauge) coming from the interaction with Maxwell systems (only if Maxwell-TDDFT coupling is in dipole).
norm_ks_orbitals:
Writes the norm of each Kohn-Sham orbital. The data is ordered per row as: Iteration time (state 1 kpoint 1) (state2 kpoint1) ... (state-Nstates kpoint1) (state1 kpoint2) ... (state-Nstates kpoint-nkpt) noting that the kpoint index will also include the spin index for spin-polarised calculations.

TDOutputComputeInterval

TDOutputDFTU

TDOutputResolveStates

TDPhotonicTimeScale

TDPolarization

TDPolarizationDirection

TDPolarizationEquivAxes

TDPolarizationWprime

TDProjStateStart

TDPropagationTime

TDPropagator

Name 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:

etrs:
The idea is to make use of time-reversal symmetry from the beginning:
$ \exp \left(-i\delta t H_{n} / 2 \right)\psi_n = \exp \left(i\delta t H_{n+1} / 2 \right)\psi_{n+1}, $

and then invert to obtain:

$ \psi_{n+1} = \exp \left(-i\delta t H_{n+1} / 2 \right) \exp \left(-i\delta t H_{n} / 2 \right)\psi_{n}. $

But we need to know $H_{n+1}$, which can only be known exactly through the solution $\psi_{n+1}$. What we do is to estimate it by performing a single exponential: $\psi^{}{n+1}=\exp \left( -i\delta t H{n} \right) \psi_n$, and then $H_{n+1} = H[\psi^{}_{n+1}]$. Thus no extrapolation is performed in this case.
aetrs:
Approximated Enforced Time-Reversal Symmetry (AETRS). A modification of previous method to make it faster. It is based on extrapolation of the time-dependent potentials. It is faster by about 40%. The only difference is the procedure to estimate $H_{n+1}$: in this case it is extrapolated via a second-order polynomial by making use of the Hamiltonian at time $t-2\delta t$, $t-\delta t$ and $t$.
caetrs:
(experimental) Corrected Approximated Enforced Time-Reversal Symmetry (AETRS), this is the previous propagator but including a correction step to the exponential.
exp_mid:
Exponential Midpoint Rule (EM). This is maybe the simplest method, but it is very well grounded theoretically: it is unitary (if the exponential is performed correctly) and preserves time-reversal symmetry (if the self-consistency problem is dealt with correctly). It is defined as: $ U_{\rm EM}(t+\delta t, t) = \exp \left( -i\delta t H_{t+\delta t/2}\right)\,. $
crank_nicholson:
crank_nicolson:
Classical Crank-Nicolson propagator. $ (1 + i\delta t H_{n+1/2} / 2) \psi_{n+1} = (1 - i\delta t H_{n+1/2} / 2) \psi_{n} $
crank_nicholson_sparskit:
crank_nicolson_sparskit:
Classical Crank-Nicolson propagator. Requires the SPARSKIT library. $ (1 + i\delta t H_{n+1/2} / 2) \psi_{n+1} = (1 - i\delta t H_{n+1/2} / 2) \psi_{n} $
magnus:
Magnus Expansion (M4). This is the most sophisticated approach. It is a fourth-order scheme (a feature which it shares with the ST scheme; the other schemes are in principle second-order). It is tailored for making use of very large time steps, or equivalently, dealing with problem with very high-frequency time-dependence. It is still in a experimental state; we are not yet sure of when it is advantageous.
qoct_tddft_propagator:
WARNING: EXPERIMENTAL
runge_kutta4:
WARNING: EXPERIMENTAL. Implicit Gauss-Legendre 4th order Runge-Kutta.
runge_kutta2:
WARNING: EXPERIMENTAL. Implicit 2nd order Runge-Kutta (trapezoidal rule). Similar, but not identical, to Crank-Nicolson method.
expl_runge_kutta4:
WARNING: EXPERIMENTAL. Explicit RK4 method.
cfmagnus4:
WARNING EXPERIMENTAL

TDReducedMomentumTransfer

TDSCFThreshold

TDScissor

TDStepsWithSelfConsistency

TDTDMFrequencies

TDTDMHoleCoordinates

TDTDMHoleReducedCoordinates

TDTimeStep

TemperatureFunction

TestBatchOps

TestHamiltonianApply

TestMaxBlockSize

TestMinBlockSize

TestMode

Name TestMode
Section Calculation Modes::Test
Type integer
Default hartree

Decides what kind of test should be performed.

Options:

hartree:
Tests the Poisson solvers used to calculate the Hartree potential.
derivatives:
Tests and benchmarks the implementation of the finite-difference operators, used to calculate derivatives.
orthogonalization:
Tests the implementation of the orthogonalization routines.
interpolation:
Test the interpolation routines.
ion_interaction:
Tests the ion-ion interaction routines.
projector:
Tests the code that applies the nonlocal part of the pseudopotentials in case of spin-orbit coupling
dft_u:
Tests the DFT+U part of the code for projections on the basis.
hamiltonian_apply:
Tests the application of the Hamiltonian, or a part of it
density_calc:
Calculation of the density.
exp_apply:
Tests the exponential of the Hamiltonian
boundaries:
Tests the boundaries conditions
subspace_diag:
Tests the subspace diagonalization
batch_ops:
Tests the batch operations
clock:
Tests for clock
linear_solver:
Tests the linear solvers
cgal:
Tests for cgal interface
dense_eigensolver:
Tests for dense eigensolvers (especially parallel ones)
grid_interpolation:
Tests for grid interpolation and multigrid methods.
iihash:
Tests for the integer-integer hash table.
sihash:
Tests for the string-integer hash table.
sphash:
Tests for the string-polymorphic hash table.
mpiwrappers:
Tests for the MPI wrappers with large integer displacements.
regridding:
Tests the regridding between two different grids.
helmholtz_decomposition:
Test for the Helmholtz decomposition subroutines
vecpot_analytical:
Tests analytically the vector potential from B field.
current_density:
Tests the different contributions to the total electronic current density
mixing_tests:
Unit test for the mixing
optimizers:
Tests for the optimizers, using standard test functions

TestRepetitions

TestType

TestVectorPotentialType

TheoryLevel

Thermostat

ThermostatMass

TimeZero

TotalStates

TransformStates

TransientAbsorptionReference

TransientMagnetizationReference

TransverseFieldCalculation