**MagneticGaugeCorrection**
*Section*: Linear Response
*Type*: integer
*Default*: gipaw

For magnetic linear response: how to handle gauge-invariance in the description
of the coupling of electrons to the magnetic field.
*Options*:

**none**: No correction.**gipaw**: GIPAW correction: C Pickard and F Mauri,*Phys. Rev. Lett.***91**, 196401 (2003).**icl**: ICL correction: S Ismail-Beigi, EK Chang, and SG Louie,*Phys. Rev. Lett.***87**, 087402 (2001).

**ResponseMethod**
*Section*: Linear Response
*Type*: integer
*Default*: sternheimer

Some response properties can be calculated either via
Sternheimer linear response or by using finite
differences. You can use this variable to select how you want
them to be calculated, it applies to `em_resp` and `vib_modes`
calculation modes. By default, the Sternheimer linear-response
technique is used.
*Options*:

**sternheimer**: The linear response is obtained by solving a self-consistent Sternheimer equation for the variation of the orbitals. This is the recommended method.**finite_differences**: Properties are calculated as a finite-differences derivative of the energy obtained by several ground-state calculations. This method, slow and limited only to static response, is kept mainly because it is simple and useful for testing purposes.

**CasidaCalcForces**
*Section*: Linear Response::Casida
*Type*: logical
*Default*: false

(Experimental) Enable calculation of excited-state forces. Requires previous `vib_modes` calculation.

**CasidaCalcForcesKernel**
*Section*: Linear Response::Casida
*Type*: logical
*Default*: true

If false, the derivative of the kernel will not be included in the excited-state force calculation.

**CasidaCalcForcesSCF**
*Section*: Linear Response::Casida
*Type*: logical
*Default*: false

If true, the ground-state forces will be included in the excited-state forces, so they are total forces.
If false, the excited-state forces that are produced are only the gradients of the excitation energy.

**CasidaCalcTriplet**
*Section*: Linear Response::Casida
*Type*: logical
*Default*: false

For a non-spin-polarized ground state, singlet or triplet excitations can be calculated
using different matrix elements. Default is to calculate singlets. This variable has no
effect for a spin-polarized calculation.

**CasidaDistributedMatrix**
*Section*: Linear Response::Casida
*Type*: logical
*Default*: false

Large matrices with more than a few thousand rows and columns usually do
not fit into the memory of one processor anymore. With this option, the
Casida matrix is distributed in block-cyclic fashion over all cores in the
ParOther group. The diagonalization is done in parallel using ScaLAPACK
or ELPA, if available. For very large matrices (>100000), only the
ParOther strategy should be used because the diagonalization dominates
the run time of the computation.

**CasidaHermitianConjugate**
*Section*: Linear Response::Casida
*Type*: logical
*Default*: false

The Casida matrix is Hermitian, so it should not matter whether we calculate the upper or
lower diagonal. Numerical issues may cause small differences however. Use this variable to
calculate the Hermitian conjugate of the usual matrix, for testing.

**CasidaKSEnergyWindow**
*Section*: Linear Response::Casida
*Type*: float

An alternative to `CasidaKohnShamStates` for specifying which occupied-unoccupied
transitions will be used: all those whose eigenvalue differences are less than this
number will be included. If a value less than 0 is supplied, this criterion will not be used.

**CasidaKohnShamStates**
*Section*: Linear Response::Casida
*Type*: string
*Default*: all states

The calculation of the excitation spectrum of a system in the Casida frequency-domain
formulation of linear-response time-dependent density functional theory (TDDFT)
implies the use of a basis set of occupied/unoccupied Kohn-Sham orbitals. This
basis set should, in principle, include all pairs formed by all occupied states,
and an infinite number of unoccupied states. In practice, one has to truncate this
basis set, selecting a number of occupied and unoccupied states that will form the
pairs. These states are specified with this variable. If there are, say, 15 occupied
states, and one sets this variable to the value "10-18", this means that occupied
states from 10 to 15, and unoccupied states from 16 to 18 will be considered.

This variable is a string in list form, *i.e.* expressions such as "1,2-5,8-15" are
valid. You should include a non-zero number of unoccupied states and a non-zero number
of occupied states.

**CasidaMomentumTransfer**
*Section*: Linear Response::Casida
*Type*: block
*Default*: 0

Momentum-transfer vector for the calculation of the dynamic structure
factor. When this variable is set, the transition rates are determined
using an exponential operator instead of the normal dipole one.

**CasidaParallelEigensolver**
*Section*: Linear Response::Casida
*Type*: integer

Choose library to use for solving the parallel eigenproblem
of the Casida problem. This options is only relevant if a
distributed matrix is used (CasidaDistributedMatrix=true).
By default, elpa is chosen if available.
*Options*:

**casida_elpa**: Use ELPA library as parallel eigensolver**casida_scalapack**: Use Scalapack as parallel eigensolver

**CasidaPrintExcitations**
*Section*: Linear Response::Casida
*Type*: string
*Default*: write all

Specifies which excitations are written at the end of the calculation.

This variable is a string in list form, *i.e.* expressions such as "1,2-5,8-15" are
valid.

**CasidaQuadratureOrder**
*Section*: Linear Response::Casida
*Type*: integer
*Default*: 5

Only applies if `CasidaMomentumTransfer` is nonzero.
Directionally averaged dynamic structure factor is calculated by
averaging over the results from a set of \(\vec{q}\)-vectors. The vectors
are generated using Gauss-Legendre quadrature scheme [see *e.g.*
K. Atkinson, *J. Austral. Math. Soc.* **23**, 332 (1982)], and this
variable determines the order of the scheme.

**CasidaTheoryLevel**
*Section*: Linear Response::Casida
*Type*: flag
*Default*: `eps_diff + petersilka + lrtddft_casida`

Choose which electron-hole matrix-based theory levels to use in calculating excitation energies.
More than one may be used to take advantage of the significant commonality between the calculations.
`variational` and `lrttdft_casida` are not usable with complex wavefunctions.
Note the restart data saved by each theory level is compatible with all the others.
*Options*:

**lrtddft_casida**: The full Casida method. Only applies to real wavefunctions. Ref: C Jamorski, ME Casida, and DR Salahub,*J. Chem. Phys.***104**, 5134 (1996) and ME Casida, "Time-dependent density functional response theory for molecules," in*Recent Advances in Density Functional Methods*, edited by DE Chong, vol. 1 of*Recent Advances in Computational Chemistry*, pp. 155-192 (World Scientific, Singapore, 1995).**eps_diff**: Difference of eigenvalues,*i.e.*independent-particle approximation.**petersilka**: The Petersilka approximation uses only elements of the Tamm-Dancoff matrix between degenerate transitions (if no degeneracy, this is just the diagonal elements). Also called the "single-pole" approximation. This is acceptable if there is little mixing between single-particle transitions. Ref: M Petersilka, UJ Gossmann, and EKU Gross,*Phys. Rev. Lett.***76**, 1212 (1996); T Grabo, M Petersilka,and EKU Gross,*Theochem***501-502**353 (2000).**tamm_dancoff**: The Tamm-Dancoff approximation uses only occupied-unoccupied transitions and not unoccupied-occupied transitions. Ref: S Hirata and M Head-Gordon,*Chem. Phys. Lett.***314**, 291 (1999).**variational**: Second-order constrained variational theory CV(2)-DFT. Only applies to real wavefunctions. Ref: T Ziegler, M Seth, M Krykunov, J Autschbach, and F Wang,*J. Chem. Phys.***130**, 154102 (2009).

**CasidaTransitionDensities**
*Section*: Linear Response::Casida
*Type*: string
*Default*: write none

Specifies which transition densities are to be calculated and written down. The
transition density for the many-body state *n* will be written to a file called
`rho_0n` prefixed by the theory level. Format is set by `OutputFormat`.

This variable is a string in list form, *i.e.* expressions such as "1,2-5,8-15" are
valid.

**CasidaWeightThreshold**
*Section*: Linear Response::Casida
*Type*: float
*Default*: -1.

Specifies the threshold value for which the individual excitations are printed.
i.e. juste-h pairs with weight larger than this threshold will be printed.

If a negative value (default) is set, all coefficients will be printed.
For many case, a 0.01 value is a valid option.

**CasidaWriteDistributedMatrix**
*Section*: Linear Response::Casida
*Type*: logical
*Default*: false

Set to true to write out the full distributed Casida matrix to a file
using MPI-IO.

**PhotonmodesFilename**
*Section*: Linear Response::Casida
*Type*: string
*Default*: "photonmodes"

Filename for photon modes in text format
- first line contains 2 integers: number of photon modes and number of
columns
- each further line contains the given number of floats for one photon
mode

**KdotPCalcSecondOrder**
*Section*: Linear Response::KdotP
*Type*: logical
*Default*: false

If true, calculates second-order response of wavefunctions as well as first-order response.
Note that the second derivative of the Hamiltonian is NOT included in this calculation.
This is needed for a subsequent run in `CalculationMode = em_resp` with `EMHyperpol`.

**KdotPCalculateEffectiveMasses**
*Section*: Linear Response::KdotP
*Type*: logical
*Default*: true

If true, uses `kdotp` perturbations of ground-state wavefunctions
to calculate effective masses. It is not correct for degenerate states.

**KdotPEta**
*Section*: Linear Response::KdotP
*Type*: float
*Default*: 0.0

Imaginary frequency added to Sternheimer equation which may improve convergence.
Not recommended.

**KdotPOccupiedSolutionMethod**
*Section*: Linear Response::KdotP
*Type*: integer
*Default*: sternheimer_eqn

Method of calculating the contribution of the projection of the
linear-response wavefunctions in the occupied subspace.
*Options*:

**sternheimer_eqn**: The Sternheimer equation is solved including the occupied subspace, to get the full linear-response wavefunctions.**sum_over_states**: The Sternheimer equation is solved only in the unoccupied subspace, and a sum-over-states perturbation-theory expression is used to evaluate the contributions in the occupied subspace.

**KdotPUseNonLocalPseudopotential**
*Section*: Linear Response::KdotP
*Type*: logical
*Default*: true

For testing purposes, set to false to ignore the term \(-i \left[\vec{r}, V\right]\) in
the \(\vec{k} \cdot \vec{p}\) perturbation, which is due to non-local pseudopotentials.

**KdotPVelMethod**
*Section*: Linear Response::KdotP
*Type*: integer
*Default*: grad_vel

Method of velocity calculation.
*Options*:

**grad_vel**: \(-i \left(\nabla + \left[r, V_{\rm nl} \right] \right)\)**hcom_vel**: As a commutator of the position operator and Hamiltonian, \(-i \left[ r, H \right]\).

**BornChargeSumRuleCorrection**
*Section*: Linear Response::Polarizabilities
*Type*: logical
*Default*: true

Enforce the acoustic sum rule by distributing the excess sum of Born charges equally among the atoms.
Sum rule: \(\sum_{\alpha} Z^{*}_{\alpha, i, j} = Z_{\rm tot} \delta_{ij}\).
Violation of the sum rule may be caused by inadequate spacing, box size (in finite directions),
or *k*-point sampling (in periodic directions).

**EMCalcBornCharges**
*Section*: Linear Response::Polarizabilities
*Type*: logical
*Default*: false

Calculate linear-response Born effective charges from electric perturbation (experimental).

**EMCalcMagnetooptics**
*Section*: Linear Response::Polarizabilities
*Type*: logical
*Default*: false

Calculate magneto-optical response.

**EMCalcRotatoryResponse**
*Section*: Linear Response::Polarizabilities
*Type*: logical
*Default*: false

Calculate circular-dichroism spectrum from electric perturbation,
and write to file `rotatory_strength`.

**EMEta**
*Section*: Linear Response::Polarizabilities
*Type*: float
*Default*: 0.0

The imaginary part of the frequency, effectively a Lorentzian broadening
for peaks in the spectrum. It can help convergence of the SCF cycle for the
Sternheimer equation when on a resonance, and it can be used as a positive
infinitesimal to get the imaginary parts of response functions at poles.
In units of energy. Cannot be negative.

**EMForceNoKdotP**
*Section*: Linear Response::Polarizabilities
*Type*: logical
*Default*: false

If the system is periodic, by default wavefunctions from a previous `kdotp` run will
be read, to be used in the formulas for the polarizability and
hyperpolarizability in the quantum theory of polarization. For testing purposes,
you can set this variable to true to disregard the `kdotp` run, and use the formulas
for the finite system. This variable has no effect for a finite system.

**EMFreqs**
*Section*: Linear Response::Polarizabilities
*Type*: block

This block defines for which frequencies the polarizabilities
will be calculated. If it is not present, the static (\(\omega = 0\)) response
is calculated.

Each row of the block indicates a sequence of frequency values, the
first column is an integer that indicates the number of steps, the
second number is the initial frequency, and the third number the final
frequency. If the first number is one, then only the initial value is
considered. The block can have any number of rows. Consider the next example:

`%EMFreqs
31 | 0.0 | 1.0
1 | 0.32
%`

**EMFreqsSort**
*Section*: Linear Response::Polarizabilities
*Type*: logical
*Default*: true

If true, the frequencies specified by the `EMFreqs` block are sorted, so that
they are calculated in increasing order. Can be set to false to use the order as stated,
in case this makes better use of available restart information.

**EMHyperpol**
*Section*: Linear Response::Polarizabilities
*Type*: block

This block describes the multiples of the frequency used for
the dynamic hyperpolarizability. The results are written to the
file `beta` in the directory for the first multiple.
There must be three factors, summing to zero: \(\omega_1 + \omega_2 + \omega_3 = 0\).
For example, for second-harmonic generation, you could use
`1 | 1 | -2`.

**EMKPointOutput**
*Section*: Linear Response::Polarizabilities
*Type*: logical
*Default*: false

Give in the output contributions of different k-points to the dielectric constant.
Can be also used for magneto-optical effects.

**EMMagnetoopticsNoHVar**
*Section*: Linear Response::Polarizabilities
*Type*: logical
*Default*: true

Exclude corrections to the exchange-correlation and Hartree terms
from consideration of perturbations induced by a magnetic field

**EMOccupiedResponse**
*Section*: Linear Response::Polarizabilities
*Type*: logical
*Default*: false

Solve for full response without projector into unoccupied subspace.
Not possible if there are partial occupations.
When `EMHyperpol` is set for a periodic system, this variable is ignored and
the full response is always calculated.

**EMPerturbationType**
*Section*: Linear Response::Polarizabilities
*Type*: integer
*Default*: electric

Which perturbation to consider for electromagnetic linear response.
*Options*:

**none**: Zero perturbation, for use in testing.**electric**: Electric perturbation used to calculate electric polarizabilities and hyperpolarizabilities.**magnetic**: Magnetic perturbation used to calculate magnetic susceptibilities.

**EMWavefunctionsFromScratch**
*Section*: Linear Response::Polarizabilities
*Type*: logical
*Default*: false

Do not use saved linear-response wavefunctions from a previous run as starting guess.
Instead initialize to zero as in `FromScratch`, but restart densities will still
be used. Restart wavefunctions from a very different frequency can hinder convergence.

**vdWNPoints**
*Section*: Linear Response::Polarizabilities
*Type*: integer
*Default*: 6

How many points to use in the Gauss-Legendre integration to obtain the
van der Waals coefficients.

**LRConvAbsDens**
*Section*: Linear Response::SCF in LR calculations
*Type*: float
*Default*: 1e-5

The tolerance in the absolute variation of the density response, to determine if
the SCF for linear response is converged.
\(\varepsilon = \int {\rm d}^3r \left| \rho^{out}(\bf r) -\rho^{inp}(\bf r) \right|\).
A zero value means do not use this criterion.

**LRConvRelDens**
*Section*: Linear Response::SCF in LR calculations
*Type*: float
*Default*: 0.0

The tolerance in the relative variation of the density response, to determine if
the SCF for linear response is converged.
\(\varepsilon = \frac{1}{N_{\rm elec}}\) `LRConvAbsDens`.
A zero value means do not use this criterion.

**LRMaximumIter**
*Section*: Linear Response::SCF in LR calculations
*Type*: integer
*Default*: 200

The maximum number of SCF iterations to calculate response.

**LRTolAdaptiveFactor**
*Section*: Linear Response::SCF in LR calculations
*Type*: float
*Default*: 0.1

This factor controls how much the tolerance is decreased
during the self-consistency process. Smaller values mean that
tolerance is decreased faster.

**LRTolIterWindow**
*Section*: Linear Response::SCF in LR calculations
*Type*: float
*Default*: 10

Number of iterations necessary to reach the final tolerance.

**LRTolScheme**
*Section*: Linear Response::SCF in LR calculations
*Type*: integer
*Default*: tol_adaptive

The scheme used to adjust the tolerance of the solver during
the SCF iteration. For `kdotp` and magnetic `em_resp` modes, or
whenever `HamiltonianVariation = V_ext_only`, the
scheme is set to `tol_fixed`, and this variable is ignored.
*Options*:

**tol_fixed**: The solver tolerance is fixed for all the iterations; this improves convergence but increases the computational cost**tol_adaptive**: The tolerance is increased according to the level of convergence of the SCF.**tol_linear**: The tolerance decreases linearly for the first`LRTolIterWindow`iterations.**tol_exp**: The tolerance decreases exponentially for the first`LRTolIterWindow`iterations.

**LRTolFinalTol**
*Section*: Linear Response::Solver
*Type*: float
*Default*: 1e-6

This is the tolerance to determine that the linear solver has converged.

**LRTolInitTol**
*Section*: Linear Response::Solver
*Type*: float
*Default*: 1e-2

This is the tolerance to determine that the linear solver has converged,
for the first SCF iteration. Ignored if `LRTolScheme = fixed`.

**LinearSolver**
*Section*: Linear Response::Solver
*Type*: integer
*Default*: qmr_symmetric

Method for solving linear equations, which occur for Sternheimer linear
response and OEP. The solvers vary in speed, reliability (ability to
converge), and domain of applicability. QMR solvers are most reliable.
*Options*:

**idrs**: This is the "Induced Dimension Reduction", IDR(s) (for s=4). IDR(s) is a robust and efficient short recurrence Krylov subspace method for solving large nonsymmetric systems of linear equations. It is described in [Peter Sonneveld and Martin B. van Gijzen, SIAM J. Sci. Comput. 31, 1035 (2008)]. We have adapted the code released by M. B. van Gizjen [http://ta.twi.tudelft.nl/nw/users/gijzen/IDR.html].**bicgstab**: Biconjugate gradients stabilized. Slower than`cg`, but more reliable. General matrices.**cg**: Conjugate gradients. Fast but unreliable. Hermitian matrices only (no eta in Sternheimer).**multigrid**: Multigrid solver, currently only Gauss-Jacobi (experimental). Slow, but fairly reliable. General matrices.**qmr_symmetric**: Quasi-minimal residual solver, for (complex) symmetric matrices. [Real symmetric is equivalent to Hermitian.] Slightly slower than`bicgstab`but more reliable. For Sternheimer, must be real wavefunctions, but can have eta.**qmr_symmetrized**: Quasi-minimal residual solver, using the symmetrized form \(A^\dagger A x = A^\dagger y\) instead of \(A x = y\). Reliable but very slow. General matrices.**qmr_dotp**: Quasi-minimal residual solver, for Hermitian matrices, using the symmetric algorithm with conjugated dot product (experimental). Slightly slower than`bicgstab`but more reliable. Can always be used in Sternheimer.**qmr_general**: Quasi-minimal residual solver, for general matrices, using the most general form of the algorithm. Slow and unreliable.**sos**: Sum over states: the Sternheimer equation is solved by using the explicit solution in terms of the ground-state wavefunctions. You need unoccupied states to use this method. Unlike the other methods, may not give the correct answer.

**LinearSolverMaxIter**
*Section*: Linear Response::Solver
*Type*: integer
*Default*: 1000

Maximum number of iterations the linear solver does, even if
convergence is not achieved.

**EMCalcDiagonalField**
*Section*: Linear Response::Static Polarization
*Type*: logical
*Default*: true

Calculate *yz*-field for \(\beta_{xyz}\) hyperpolarizability, which is sometimes harder to converge.
Only applies if `ResponseMethod = finite_differences`.

**EMStartDensityIsZeroField**
*Section*: Linear Response::Static Polarization
*Type*: logical
*Default*: true

Use the charge density from the zero-field calculation as the starting density for
SCF calculations with applied fields. For small fields, this will be fastest.
If there is trouble converging with larger fields, set to false,
to initialize the calculation for each field from scratch, as specified by the LCAO variables.
Only applies if `ResponseMethod = finite_differences`.

**EMStaticElectricField**
*Section*: Linear Response::Static Polarization
*Type*: float
*Default*: 0.01 a.u.

Magnitude of the static electric field used to calculate the static polarizability,
if `ResponseMethod = finite_differences`.

**EMVerbose**
*Section*: Linear Response::Static Polarization
*Type*: logical
*Default*: false

Write full SCF output.
Only applies if `ResponseMethod = finite_differences`.

**EMWriteRestartDensities**
*Section*: Linear Response::Static Polarization
*Type*: logical
*Default*: true

Write density after each calculation for restart, rather than just the resulting electronic dipole moment.
Only applies if `ResponseMethod = finite_differences`. Restarting from calculations at smaller
fields can be helpful if there are convergence problems.

**HamiltonianVariation**
*Section*: Linear Response::Sternheimer
*Type*: integer
*Default*: hartree+fxc

The terms to be considered in the variation of the
Hamiltonian. The external potential (V_ext) is always considered. The default is to include
also the exchange-correlation and Hartree terms, which fully
takes into account local fields.
Just `hartree` gives you the random-phase approximation (RPA).
If you want to choose the exchange-correlation kernel, use the variable
`XCKernel`. For `kdotp` and magnetic `em_resp` modes,
or if `TheoryLevel = independent_particles`,
the value `V_ext_only` is used and this variable is ignored.
*Options*:

**V_ext_only**: Neither Hartree nor XC potentials included.**hartree**: The variation of the Hartree potential only.**fxc**: The exchange-correlation kernel (the variation of the exchange-correlation potential) only.

**PhotonEta**
*Section*: Linear Response::Sternheimer
*Type*: float
*Default*: 0.0000367

This variable provides the value for the broadening of the photonic spectra
when the coupling of electrons to photons is enabled in the frequency-dependent Sternheimer equation

**Preorthogonalization**
*Section*: Linear Response::Sternheimer
*Type*: logical

Whether initial linear-response wavefunctions should be orthogonalized
or not against the occupied states, at the start of each SCF cycle.
Default is true only if `SmearingFunction = semiconducting`,
or if the `Occupations` block specifies all full or empty states,
and we are not solving for linear response in the occupied subspace too.

**CalcInfrared**
*Section*: Linear Response::Vibrational Modes
*Type*: logical
*Default*: true

If set to true, infrared intensities (and Born charges) will be calculated
and written in `vib_modes/infrared`.

**CalcNormalModeWfs**
*Section*: Linear Response::Vibrational Modes
*Type*: logical
*Default*: false

If set to true, the response wavefunctions for each normal mode will be calculated
and written in directory `restart/vib_modes/phn_nm_wfs_XXXXX`.
This part is time-consuming and not parallel, but not needed for most purposes.

**Displacement**
*Section*: Linear Response::Vibrational Modes
*Type*: float
*Default*: 0.01 a.u.

When calculating phonon properties by finite differences (`CalculationMode = vib_modes,
ResponseMethod = finite_differences`),
`Displacement` controls how much the atoms are to be moved in order to calculate the
dynamical matrix.

**SymmetrizeDynamicalMatrix**
*Section*: Linear Response::Vibrational Modes
*Type*: logical
*Default*: true

If set to true, all entries of the dynamical matrix will be calculated and then
the matrix will be symmetrized to enforce \(D_{ij} = D_{ji}\). If set to false,
only the upper half of the matrix will be calculated.