**DegeneracyThreshold**
*Section*: States
*Type*: float
*Default*: 1e-5

States with energy \(E_i\) and \(E_j\) will be considered degenerate
if \( \left| E_i - E_j \right| < \)`DegeneracyThreshold`.

**ExcessCharge**
*Section*: States
*Type*: float
*Default*: 0.0

The net charge of the system. A negative value means that we are adding
electrons, while a positive value means we are taking electrons
from the system.

**ExtraStates**
*Section*: States
*Type*: integer
*Default*: 0

The number of states is in principle calculated considering the minimum
numbers of states necessary to hold the electrons present in the system.
The number of electrons is
in turn calculated considering the nature of the species supplied in the
`Species` block, and the value of the `ExcessCharge` variable.
However, one may command `Octopus` to use more states, which is necessary if one wants to
use fractional occupational numbers, either fixed from the beginning through
the `Occupations` block or by prescribing
an electronic temperature with `Smearing`, or in order to calculate
excited states (including with `CalculationMode = unocc`).

**ExtraStatesToConverge**
*Section*: States
*Type*: integer
*Default*: 0

Only for unocc calculations.
Specifies the number of extra states that will be considered for reaching the convergence.
Together with `ExtraStates`, one can have some more states which will not be
considered for the convergence criteria, thus making the convergence of the
unocc calculation faster.
By default, all extra states need to be converged.

**InitialSpins**
*Section*: States
*Type*: block

The spin character of the initial random guesses for the spinors can
be fixed by making use of this block. Note that this will not "fix" the
the spins during the calculation (this cannot be done in spinors mode, in
being able to change the spins is why the spinors mode exists in the first
place).

This block is meaningless and ignored if the run is not in spinors mode
(`SpinComponents = spinors`).

The structure of the block is very simple: each column contains the desired
\(\left< S_x \right>, \left< S_y \right>, \left< S_z \right> \) for each spinor.
If the calculation is for a periodic system
and there is more than one *k*-point, the spins of all the *k*-points are
the same.

For example, if we have two spinors, and we want one in the \(S_x\) "down" state,
and another one in the \(S_x\) "up" state:

`%InitialSpins
0.5 | 0.0 | 0.0
-0.5 | 0.0 | 0.0
%`

WARNING: if the calculation is for a system described by pseudopotentials (as opposed to user-defined potentials or model systems), this option is meaningless since the random spinors are overwritten by the atomic orbitals.

This constraint must be fulfilled:

\( \left< S_x \right>^2 + \left< S_y \right>^2 + \left< S_z \right>^2 = \frac{1}{4} \)

**Occupations**
*Section*: States
*Type*: block

The occupation numbers of the orbitals can be fixed through the use of this
variable. For example:

`%Occupations
2 | 2 | 2 | 2 | 2
%`

would fix the occupations of the five states to 2. There can be at most as many columns as states in the calculation. If there are fewer columns than states, then the code will assume that the user is indicating the occupations of the uppermost states where all lower states have full occupation (i.e. 2 for spin-unpolarized calculations, 1 otherwise) and all higher states have zero occupation. The first column will be taken to refer to the lowest state such that the occupations would be consistent with the correct total charge. For example, if there are 8 electrons and 10 states (from

1 | 0 | 1

%

would be equivalent to a full specification

2 | 2 | 2 | 1 | 0 | 1 | 0 | 0 | 0 | 0

%

This is an example of use for constrained density-functional theory, crudely emulating a HOMO->LUMO+1 optical excitation. The number of rows should be equal to the number of k-points times the number of spins. For example, for a finite system with

The

%Occupations

2 | 2/3 | 2/3 | 2/3

%

If you want the calculation to be spin-polarized (which makes more sense), you could do:

%Occupations

2/3 | 2/3 | 2/3

0 | 0 | 0

%

Note that in this case the first state is absent, the code will calculate four states (two because there are four electrons, plus two because

If the sum of occupations is not equal to the total charge set by

**OnlyUserDefinedInitialStates**
*Section*: States
*Type*: logical
*Default*: no

If true, then only user-defined states from the block `UserDefinedStates`
will be used as initial states for a time-propagation. No attempt is made
to load ground-state orbitals from a previous ground-state run.

**RestartFixedOccupations**
*Section*: States
*Type*: logical
*Default*: no

Setting this variable will make the restart proceed as
if the occupations from the previous calculation had been set via the `Occupations` block,
*i.e.* fixed. Otherwise, occupations will be determined by smearing.

**RestartReorderOccs**
*Section*: States
*Type*: logical
*Default*: no

Consider doing a ground-state calculation, and then restarting with new occupations set
with the `Occupations` block, in an attempt to populate the orbitals of the original
calculation. However, the eigenvalues may reorder as the density changes, in which case the
occupations will now be referring to different orbitals. Setting this variable to yes will
try to solve this issue when the restart data is being read, by reordering the occupations
according to the order of the expectation values of the restart wavefunctions.

**Smearing**
*Section*: States
*Type*: float
*Default*: 0.1 eV

If `Occupations` is not set, `Smearing` is the
smearing width used in the `SmearingFunction` to distribute the electrons
among the existing states.

**SmearingFunction**
*Section*: States
*Type*: integer
*Default*: semiconducting

This is the function used to smear the electronic occupations.
It is ignored if the `Occupations` block is set.
*Options*:

**semiconducting**: Semiconducting occupations,*i.e.*the lowest lying states are occupied until no more electrons are left.**fermi_dirac**: Simple Fermi-Dirac distribution. In this case,`Smearing`has the meaning of an electronic temperature. DN Mermin,*Phys. Rev.***137**, A1441 (1965).**cold_smearing**: N Marzari, D Vanderbilt, A De Vita, and MC Payne,*Phys. Rev. Lett.***82**, 3296 (1999).**methfessel_paxton**: M Methfessel and AT Paxton,*Phys. Rev. B***40**, 3616 (1989). In this case, the variable`SmearingMPOrder`sets the order of the smearing. Occupations may be negative.**spline_smearing**: Nearly identical to Gaussian smearing. JM Holender, MJ Gillan, MC Payne, and AD Simpson,*Phys. Rev. B***52**, 967 (1995).

**SmearingMPOrder**
*Section*: States
*Type*: integer
*Default*: 1

Sets the order of the Methfessel-Paxton smearing function.

**SpinComponents**
*Section*: States
*Type*: integer
*Default*: unpolarized

The calculations may be done in three different ways: spin-restricted (TD)DFT (*i.e.*, doubly
occupied "closed shells"), spin-unrestricted or "spin-polarized" (TD)DFT (*i.e.* we have two
electronic systems, one with spin up and one with spin down), or making use of two-component
spinors.
*Options*:

**unpolarized**: Spin-restricted calculations.**spin_polarized**: (Synonym`polarized`.) Spin-unrestricted, also known as spin-DFT, SDFT. This mode will double the number of wavefunctions necessary for a spin-unpolarized calculation.**spinors**: (Synonym:`non_collinear`.) The spin-orbitals are two-component spinors. This effectively allows the spin-density to be oriented non-collinearly:*i.e.*the magnetization vector is allowed to take different directions at different points. This vector is always in 3D regardless of`Dimensions`.

**StatesRandomization**
*Section*: States
*Type*: integer
*Default*: par_independent

The randomization of states can be done in two ways:
i) a parallelisation independent way (default), where the random states are identical,
irrespectively of the number of tasks and
ii) a parallelisation dependent way, which can prevent linear dependency
to occur for large systems.
*Options*:

**par_independent**: Parallelisation-independent randomization of states.**par_dependent**: The randomization depends on the number of taks used in the calculation.

**SymmetrizeDensity**
*Section*: States
*Type*: logical
*Default*: no

When enabled the density is symmetrized. Currently, this can
only be done for periodic systems. (Experimental.)

**TotalStates**
*Section*: States
*Type*: integer
*Default*: 0

This variable sets the total number of states that Octopus will
use. This is normally not necessary since by default Octopus
sets the number of states to the minimum necessary to hold the
electrons present in the system. (This default behavior is
obtained by setting `TotalStates` to 0).

If you want to add some unoccupied states, probably it is more convenient to use the variable
`ExtraStates`.

**TransformStates**
*Section*: States
*Type*: block
*Default*: no

Before starting the `td` calculation, the initial states (that are
read from the `restart/gs` directory, which should have been
generated in a previous ground-state calculation) can be "transformed"
among themselves. The block `TransformStates` gives the transformation matrix
to be used. The number of rows and columns of the matrix should equal the number
of the states present in the time-dependent calculation (the independent
spin and *k*-point subspaces are all transformed equally); the number of
columns should be equal to the number of states present in the
`restart/gs` directory. This number may be different: for example,
one could have run previously in `unocc` mode in order to obtain unoccupied
Kohn-Sham states, and therefore `restart/gs` will contain more states.
These states can be used in the transformation.

Note that the code will not check the orthonormality of the new states!

Each line provides the coefficients of the new states, in terms of
the old ones. The coefficients are complex, but the imaginary part will be
ignored for real wavefunctions.
Note: This variable cannot be used when parallel in states.

**UserDefinedStates**
*Section*: States
*Type*: block

Instead of using the ground state as initial state for
time-propagations it might be interesting in some cases
to specify alternate states. Like with user-defined
potentials, this block allows you to specify formulas for
the orbitals at *t*=0.

Example:

`%UserDefinedStates
1 | 1 | 1 | formula | "exp(-r^2)*exp(-i*0.2*x)" | normalize_yes
%`

The first column specifies the component of the spinor, the second column the number of the state and the third contains

Alternatively, if column four states

1 | 1 | 1 | file | "/path/to/file" | normalize_no

%

Octopus reads first the ground-state orbitals from the

The sixth (optional) column indicates whether

**file**: Read initial orbital from file. Accepted file formats, detected by extension: obf, ncdf and csv (real only).**normalize_no**: Do not normalize orbitals.**formula**: Calculate initial orbital by given analytic expression.**normalize_yes**: Normalize orbitals (default).

**DensitytoCalc**
*Section*: States::ModelMB
*Type*: block

Choice of which particle density (event. matrices) will be calculated and output, in the
modelmb particles scheme.

`%DensitytoCalc
proton | 1 | 10
electron | 2 | 15
%`

would ask octopus to calculate the density matrix corresponding to the 1st particle (whose coordinates correspond to dimensions 1 to ndim_modelmb), which is an proton, then that corresponding to the 2nd particle (electron with dimensions ndim_modelmb+1 to 2*ndim_modelmb), printing 10 natural orbitals for the first and 15 for the second.

proton | 1 | -1

electron | 2 | -1

%

would ask octopus to print out just the densities for particles 1 and 2 without any density matrix output.

**DescribeParticlesModelmb**
*Section*: States::ModelMB
*Type*: block

Characterization of different modelmb particles in gr%mesh%sb%dim dimensional space.

`%DescribeParticlesModelmb
proton | 1 | 1800. | 1. | fermion
proton | 1 | 1800. | 1. | fermion
electron | 2 | 1. | 1. | fermion
%`

would tell

**fermion**: Particle is a fermion.**boson**: Particle is a boson.**anyon**: Particle is neither fermion nor boson.

**NDimModelmb**
*Section*: States::ModelMB
*Type*: integer
*Default*: 1

Number of dimensions for modelmb space.
Full Ndim = `NDimModelmb`*`NParticleModelmb`

**NParticleModelmb**
*Section*: States::ModelMB
*Type*: integer
*Default*: 0

Number of particles in modelmb space.
Full Ndim = `NDimModelmb`*`NParticleModelmb`

**NTypeParticleModelmb**
*Section*: States::ModelMB
*Type*: integer
*Default*: 1

Number of different types of particles in modelmb space.