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 wavefunctions
    • 2 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 to 2.
  • number_of_components: unsigned int Used for the spin components of spin-density matrices:
    • 1 for non-spin-polarized
    • 2 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 to no), 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 to no), 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) is 2, otherwise it is 1.
  • 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.