# ESCDF - Densities

{{#if: |

Source authors:
{{{authors}}}

}}{{#if: |

}}{{#if: |

}}{{#if: |

Documentation: {{{documentation}}}

}}{{#if: |

| {{#if: |

| {{#if: |

| {{#if: |

|{{#if:
• ESCDF - Electronic Structure Common Data Format
• ESCDF - System
• ESCDF - Basis sets
• ESCDF - Potentials
• ESCDF - States
• ESCDF - Extensions
• |

| {{#if:
• libescdf
• |

|}}}}}}}}}}}}{{#if: |

Functionalities:

{{{functionalities}}}

}}{{#if: |

Algorithms:

{{{algorithms}}}

}}{{#if: |

Generic interfaces:

{{{generic interfaces}}}

}}{{#if: |

APIs:

{{{apis}}}

}}{{#if:
• ESCDF - Electronic Structure Common Data Format
• ESCDF - System
• ESCDF - Basis sets
• ESCDF - Potentials
• ESCDF - States
• ESCDF - Extensions
• |

Data standards:

}}{{#if:
• libescdf
• |

Software:

}}

Page under construction

## Version

File format version number: 0.1

## 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: ${\displaystyle {\tilde {\rho }}(r)=\sum _{n}\langle {\tilde {\Psi }}_{n}\vert r\rangle \langle r\vert {\tilde {\Psi }}_{n}\rangle }$;
• ultrasoft pseudopotentials and PAW: ${\displaystyle \rho (r)={\tilde {\rho }}(r)+{\hat {\rho }}(r)}$;
• all-electrons: ${\displaystyle \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: ${\displaystyle {\tilde {\rho }}(r)}$;
• ultrasoft pseudopotentials and PAW methods: ${\displaystyle {\tilde {\rho }}(r)+{\hat {\rho }}(r)}$;
• all-electrons methods: ${\displaystyle \rho _{inter}^{val}(r)}$.

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

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

### Optional components

In the case of PAW, providing the occupancy matrix elements ${\displaystyle \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 ${\displaystyle \rho (r)}$ + magnetic moment ${\displaystyle {\vec {m}}(r)}$ (well-suited for visualisation);
• the matrix elements ${\displaystyle \rho ^{\alpha \beta }(r)}$, for ${\displaystyle \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.