States¶
General overview¶
All states should be stored in the states group of a ESCDF file. If several sets of states are present, they should be put in subgroups, with explicit names. The choice of name for the subgroup is left to the user, with the restriction that it cannot be any of the names already in use in these specifications. If only one set of states is to be specified, then it can be stored directly in the states group or in its own subgroup.
The group must have the following attributes:
- number_of_spins
- number_of_spinor_components
- number_of_components
- k_dependent
- max_state_index
- min_state_index
- numbers_of_states
- number_of_kpoints
The group must contain the following datasets:
- eigenvalues
- occupations
- reduced_coordinates_of_kpoints
- kpoint_weights
- coefficients_of_wavefunctions
The group may contain the following optional datasets:
- highest_state_index
- lowest_state_index
Detailed description of variables¶
General variables¶
- number_of_spins: unsigned int
Used to distinguish collinear spin-up and spin-down components:
1
for non-spin-polarized or spinor wavefunctions2
for collinear spin (spin-up and spin-down)
- number_of_spinor_components: unsigned int
For non-spinor wavefunctions, this dimension must be present and
equal to
1
. For spinor wavefunctions, this dimension must be equal to2
. - number_of_components: unsigned int
Used for the spin components of spin-density matrices:
1
for non-spin-polarized2
for collinear spin (spin-up and spin-down)4
for non-collinear spin
- max_state_index: int
- min_state_index: int
- highest_state_index: int
Highest index of a state for each kpoint, if varying (the attribute
k_dependent must be set to
yes
). Otherwise (the attribute k_dependent must be set tono
), might not contain any information, the highest index of states being set to max_state_index. - lowest_state_index: int
Lowest index of a state for each kpoint, if varying (the attribute
k_dependent must be set to
yes
). Otherwise (the attribute k_dependent must be set tono
), might not contain any information, the lowest index of states being set to min_state_index. This variable is useful for passing data from a ground-state calculation to an optical calculation in which only a subset of bands around the Fermi level are typically used. - eigenvalues double[number_of_spins][number_of_kpoints][max_number_of_states] One-particle eigenvalues/eigenenergies (real-part). The units attribute is required. The attribute scale_to_atomic_units might also be mandatory.
- k_dependent: bool Needed for the variables number_of_states, number_of_coefficients, and reduced_coordinates_of_plane_waves.
- numbers_of_states: int[number_of_spins] [number_of_kpoints] The attribute k_dependent must be defined
- occupations:
double[number_of_spins][number_of_kpoints][max_number_of_states]
Occupation numbers. Full occupation for spin-unpolarized cases
(number_of_spins =
1
AND number_of_spinor_components =1
) is2
, otherwise it is1
. - eigenvalues_imaginary: double[number_of_spins][number_of_kpoints][max_number_of_states] One-particle eigenvalues/eigenenergies (imaginary part), i.e. for complex-scaled Hamiltonian or self-energies.
Variables relating to k-points¶
- number_of_kpoints: int The number of kpoints.
- reduced_coordinates_of_kpoints: double[number_of_kpoints] [number_of_dimensions] k-point in relative / reduced coordinates, e.g. in the interval [0, 1]. The values in non-periodic dimensions should be zero.
- kpoint_weights: double[number of kpoints] k-point integration weights. The weights must sum to 1.
Optional information that could generate the k-grid:
- kpoint_grid_numbers: int[number of dimensions] Number of k-points in each direction of Monkhorst-Pack k-grid [Phys. Rev. B 13, 5188 (1976)].
- kpoint_grid_shift: double[number_of_dimensions] Shift for offset of Monkhorst-Pack k-grid, in fractional units (e.g. (-1, 1)).
- kpoint_energy_cutoff: double Like plane-wave kinetic energy cutoff, but applied to generating a sphere of k-points. This is the way of specifying the k-grid in some codes (eg. SIESTA).
Variables relating to wavefunctions¶
- coefficients_of_wavefunctions: Wavefunction coefficients. Note that each wavefunction must be normalized to 1.