# ESCDF - States

**Source authors:**

{{{authors}}}

**License:** {{{license}}}

**Download:** {{{download}}}

**Documentation:** {{{documentation}}}

__Links to other ESL entries__

__Links to other ESL entries__

__Links to other ESL entries__

__Links to other ESL entries__

__Links to other ESL entries__

__Links to other ESL entries__

**Functionalities:**

- {{{functionalities}}}

**Algorithms:**

- {{{algorithms}}}

**Generic interfaces:**

- {{{generic interfaces}}}

**APIs:**

- {{{apis}}}

**Data standards:**

- ESCDF - Electronic Structure Common Data Format
- ESCDF - System
- ESCDF - Basis sets
- ESCDF - Densities
- ESCDF - Potentials
- ESCDF - Extensions

**Software:**

Page under construction

## Contents

## Version

File format version number: 0.1

## 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 intUsed 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 intFor 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 intUsed 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**: intHighest 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**: intLowest 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**: boolNeeded 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**: intThe 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**: doubleLike 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.