Densities

General overview

Overall strategy

To represent densities, we have to follow the way they are decomposed within the different methods in use:

  • norm-conserving pseudopotentials: \(\tilde{\rho}(r) = \sum_{n} \langle \tilde{\Psi}_n \vert r \rangle \langle r \vert\tilde{\Psi}_n \rangle\);
  • ultrasoft pseudopotentials and PAW: \(\rho(r) = \tilde{\rho}(r) + \hat{\rho}(r)\);
  • all-electrons: \(\rho(r) = \left\lbrace \rho_{sph}^{core}(r) + \rho_{sph}^{val}(r) \right\rbrace + \rho_{inter}^{val}(r)\).

Mandatory components

For the use cases considered, the cell-associated electronic density can be represented in the following ways:

  • norm-conserving pseudopotentials method: \(\tilde{\rho}(r)\);
  • ultrasoft pseudopotentials and PAW methods: \(\tilde{\rho}(r) + \hat{\rho}(r)\);
  • all-electrons methods: \(\rho_{inter}^{val}(r)\).

For the use cases considered, the atom-centered electronic density can be represented in the following ways:

  • all-electrons methods: \(\rho_{sph}^{core}(r) + \rho_{sph}^{val}(r)\);
  • gaussians (?): \(\tilde{\rho}(r)\).

Optional components

In the case of PAW, providing the occupancy matrix elements \(\rho_{ij}\) in addition to the density components allows the rebuilding of all necessary quantities to restart a calculation.

Spinors

In the presence of spinors, there are 2 possible ways of representing the 4 density components:

  • total density \(\rho(r)\) + magnetic moment \(\vec{m}(r)\) (well-suited for visualisation);
  • the matrix elements \(\rho^{\alpha\beta}(r)\), for \(\alpha,\beta = \uparrow,\downarrow\);

which means that the chosen representation must be indicated as metadata.

Detailed description of variables

All densities should be stored in the densities group of a ESCDF file.

If several densities are present, they should be put in subgroups, with explicit names.

Variables relating to the cell associated densities

Cell description

The cell description is identical to the one in the ESCDF - Geometries. It must contain the following information:

  • number_of_physical_dimensions: unsigned int (always 3)
  • dimension_types: int [number_of_physical_dimensions] (between 0 and 2)
  • lattice_vectors: double [number_of_physical_dimensions] [number_of_physical_dimensions] (dimensional variable: length)

Densities description

These variables are designed to represent densities that are stored on a regular real-space grid. This grid is defined by its mesh size.

  • number_of_grid_points: unsigned int [number_of_physical_dimensions] When a direction is defined as periodic, the grid points in that direction do not contain the last plane, while for the other cases, the last plane in that direction contains a value.
  • values_on_grid: double [‘number_of_components, product(number_of_grid_points), real_or_complex] The default order is along z, y, and x (values along x axis are contiguous in memory). If the default ordering is not used, the attribute use_default_ordering must be set to false and grid_ordering must be provided.
  • use_default_ordering: int This attribute specifies if the default z, y, and x ordering is used or not. When false, the optional variable grid_ordering must be present.
  • grid_ordering: unsigned int [product(number_of_grid_points] This array provides a lookup table. ``grid_ordering``[i] = j means that values_on_grid[:,i,:] is the jth component of the density. This variable is optional, when not present the default ordering for the density is implicit.