# option keywords

Miscellaneous options

## option.bufferSize

Memory buffer size in bytes; RESCU vectorizes operation as much as
possible, which may lead to over allocate memory, it will not generate
variables larger than option.bufferSize if it can be avoided.

**type**: `scalar`

**default**: `134217728`

**example**: `option.bufferSize = 2^30`

## option.centerMolecule

Align the barycenter of the atoms and the center of the unit cell. This
may be useful when doing molecule calculations.

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.centerMolecule = true`

## option.initParaReal

Parallelize interpolation routines over real space. This is usually less
efficient but consumes less memory. You may have to use the option if
your pseudopotential or orbitals have a large radius.

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.initParaReal = true`

## option.maxSCFiteration

Maximal number of self-consistent steps; the Kohn-Sham solver will
return an answer even if it has not converged.

**type**: `scalar`

**default**: `100`

**example**: `option.maxSCFiteration = 50`

## option.plorder

Reorder the atoms in the principal layer ordering. This is essential for
using certain algorithms.

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.plorder = true`

## option.precision

This keyword sets various other keywords related to precision (e.g.
domain.fourierInit, domain.highres, domain.vnlReal, diffop.method,
interpolation.method, interpolation.vloc). It is not relevant for atomic
orbital calculations (LCAO.status = true). Simply put, RESCU will solve
the Kohn-Sham equation in real space or using planewaves if you choose
\'real\' or \'pw\' respectively. Next, \'low\', \'med\' and \'high\'
refers to the precision, which is controlled by various keywords. Now
the fine prints. If you choose \'real\', RESCU will discretize the
non-local pseudopotential operator in real space. This is more
efficient, but it can cause the so-called eggbox effect, whereby the
total energy and other physical quantities undergo periodic variations
with respect to the real space grid, i.e. the discretized equations are
not strictly translationally invariant. This is alright for certain
kinds of calculations (e.g. BS, DOS) and detrimental to other kinds
(e.g. relaxation). In the \'med\' and \'high\' settings, the eggbox
effect is mitigated by the use of a fine grid which is twice as fine as
the regular grid for the discretization of the non-local pseudopotential
operator. This will increase the computational cost however. If you
choose \'pw\', then RESCU will discretize the non-local pseudopotential
operator in reciprocal space. This is computationally expensive in large
systems, but it prevents the so-called eggbox effect; in part that is,
because one can never eliminate the eggbox effect associated with the
local exchange-correlation potential. In the the \'med\' and \'high\'
settings, a finer grid is employed for the evaluation of the local
potential operators (e.g. vps, vh, vxc).

**type**: `string`

**default**: `'real-low'`

**allowed**:
`'real-low','real-med','real-high','pw-low','pw-med','pw-high'`

**example**: `option.precision = 'pw-high'`

## option.replicateCell

Replicate the current system along various dimensions. Automates
building supercells.

**type**: `array`

**default**: `[1,1,1]`

**size**: `[1,3]`

**example**: `option.replicateCell = [2,3,5]`

## option.shortRange

Use the short range implementation instead of the Ewald sum
implementation. The efficiency of both scheme is similar, but the short
range implementaion simplifies the treatment of various boundary
conditions. Some boundary conditions require short range consequently.

**type**: `scalar`

**default**: `true`

**allowed**: `true,false`

**example**: `option.shortRange = true`

## option.saveDensity

Determine whether to include the density in the results. If
option.saveDensity \< 0, then the density is saved every so many steps
during the self-consistent calculation. For example, if
option.saveDensity=-3, then the density is saved every third step.

**type**: `scalar`

**default**: `1`

**example**: `option.saveDensity = true`

## option.saveDFPT

Determine whether to include the DFPT struct in the results.

**type**: `scalar`

**default**: `true`

**allowed**: `true,false`

**example**: `option.saveDFPT = true`

## option.saveEigensolver

Determine whether to save the entire eigensolver structure.

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.saveEigensolver = true`

## option.saveInterpolation

Determine whether to save the entire interpolation structure.

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.saveInterpolation = true`

## option.saveLevel

Determine the amount the information saved in the MAT-file. If
option.saveLevel = 1, RESCU will save basic inputs such as the atomic
structure and relevant outputs. Advanced users and developers can save
the complete set of parameters and variables stored in the main RESCU
structure by setting option.saveLevel = 2.

**type**: `scalar`

**default**: `1`

**example**: `option.saveLevel = 2`

## option.saveLCAO

Determine whether to save the atomic orbital coefficients. The
coefficients for k-point kk and spin ss are stored in the HDF5 result
file under the location /LCAO/coeffii, where ii =
sub2ind(\[nkpt,nspin\],kk,ss). The function loadDistArray can be used to
load the data as follows: distArray =
loadDistArray(filename,\'/LCAO/coeffii\').

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.saveLCAO = true`

## option.saveLcaoHam

If option.saveLcaoHam is set to true, then RESCU will save the atomic
orbital Hamiltonian (and overlap) to an HDF5 file. For large systems,
this may require a lot of disk space. It is then possible to set
option.saveLcaoHam to \'sparse\', in which case RESCU will save the
Hamiltonian to a text file using the column/row sparse format. If
option.saveLcaoHam is set to \'wannier90\', it will save the Hamiltonian
using the same format as if it is set to \'sparse\', but without
omitting zero elements.

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.saveLcaoHam = true`

## option.saveMisc

Determine whether to save the aosubspace,YkqG,XHX,XSX,XVX fields.

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.saveMisc = true`

## option.saveMixing

Determine whether to save the entire mixing structure.

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.saveMixing = true`

## option.savePartialWeights

Determine whether to save the partial weights. The partial weight of the
eigenpair(i,k,s) (i-band,k-kpoint,s-spin) is $\sum\limits\nu
S_{\nu,\mu}^{k} c_{\nu i}^{*k}c_{\mu i}^{k}$ where S is the overlap
matrix and $(\mu,\nu)$ are generic orbital indices. Note that partial
weights are complex numbers, but they add up to exactly one for a given
eigenpair. The partial weights for k-point kk and spin ss are stored in
the HDF5 result file under the location /LCAO/partialWeightii, where ii
= sub2ind(\[nkpt,nspin\],kk,ss). The function loadDistArray can be used
to load the data as follows: distArray =
loadDistArray(filename,\'/LCAO/partialWeightii\').

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.savePartialWeights = true`

## option.savePotential

Determine whether to save the potentials or perturbed Hartree plus
exchange-correlation potential (dvhxc) in a dfpt calculation. If set to
true, the following potentials are recalculated from the most recent
trial density and saved to the H5-file (in case of dfpt calculation,
only converged perturbed dvhxc is saved): vna, vdh and vxc.
Alternatively, the sought potentials can be specified via
option.savePotential using a cell array as follows (not applicable to
dfpt calculations): option.savePotential = {\'vh\',\'vps\'}. The valid
potentials are: \'vatom\', \'vdh\', \'veff\', \'vh\', \'vna\', \'vps\',
\'vxc\'. Each potential is stored in the HDF5 result file under the
location /potential/xxx. The function loadDistArray can be used to load
the data as follows: distArray =
loadDistArray(filename,\'/potential/vdh\').

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.savePotential = true`

## option.saveTau

Determine whether to save the kinetic energy density tau. The electron
localization function ELF, is also calculated and saved. ELF and tau are
spin-dependent even if the calculation is performed in the degenerate
spin framework. They are stored in the HDF5 result file under the
location /rho/elf and /rho/tau respectively. The function loadDistArray
can be used to load the data as follows: distArray =
loadDistArray(filename,\'/rho/elf\').

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.saveTau = true`

## option.saveWavefunction

Determine whether to include the subspace/wavefunctions in the results.
If option.saveWavefunction \< 0, then the wavefunctions are saved every
so many steps during the self-consistent calculation. For example, if
option.saveWavefunction=-3, then the wavefunctions are saved every third
step. The wavefunctions for k-point kk and spin ss are stored in the
HDF5 result file under the location /waveFunction/psinn, where nn =
sub2ind(\[nkpt,nspin\],kk,ss). The function loadDistArray can be used to
load the data as follows: distArray =
loadDistArray(filename,\'/waveFunction/psinn\').

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.saveWavefunction = true`

## option.saveDensityMatrix

Determine whether to save LCAO density-matrix at the end of SCF in the
h5 file. Please note that to use this option, LCAO.status must be true,
all symmetry mush be false, all number of k-grid must be odd (i.e.
Gamma-centered sampling).

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.saveDensityMatrix = true`

## option.saveDensityMatrixK

Determine whether to save k-point-dependent LCAO density-matrix at the
end of SCF in the h5 file. The density matrix for k-point kk and spin ss
is stored in the HDF5 result file under the location
/DensityMatrix/kcellii, where ii = sub2ind(\[nkpt,nspin\],kk,ss). The
function loadDistArray can be used to load the data as follows:
distArray = loadDistArray(filename,\'/DensityMatrix/kcellii\').

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.saveDensityMatrixK = true`

## option.timeLimit

This keyword let RESCU knows how long (in hours) it should run before
quitting. For example, if option.timeLimit = 12, when RESCU gets close
to 12 hours of execution, it will save its current state in the location
given by info.savepath and quit. RESCU should then be restarted in the
same directory, with the same number of processes, and it will
automatically load its past state and keep going with the calculation.
Beware, this may require a lot of disk space in large scale computation;
be sure to point info.savepath to a large disk.

**type**: `scalar`

**example**: `option.timeLimit = 12`

## option.useMemCopy

If set to true, RESCU will use the C-function memCpy to avoid
duplicating large arrays. This can reduce the memory requirements by
roughly 30%. Note that this may lead to memory corruption on some
systems.

**type**: `scalar`

**default**: `false`

**allowed**: `true,false`

**example**: `option.useMemCopy = true`
