The ConfigDoFValues data structure#

Overview#

ConfigDoFValues is a data structure used to hold a configuration’s degrees of freedom (DoF) values for efficient use in calculations.

The DoF values can be accessed via the following member functions:

occupation(): Occupation DoF values, as an integer array with one value for each site in the supercell
local_dof_values(): Local continuous DoF values, as two-dimensional floating-point arrays, accessed by DoF type, with one column of values for each site in the supercell.
global_dof_values(): Global continuous DoF values, as one-dimensional floating-point arrays, accessed by DoF type.

For CASM standard DoF types, this module provides methods for constructing properly sized ConfigDoFValues instances, and converting between two useful basis types as described below. See the CASM Degrees of Freedom (DoF) and Properties documentation for the full list of supported DoF types and their definitions. Some examples include:

“disp”: Atomic displacement
“EAstrain”: Euler-Almansi strain metric
“GLstrain”: Green-Lagrange strain metric
“Hstrain”: Hencky strain metric
“Cmagspin”: Collinear magnetic spin
“SOmagspin”: Non-collinear magnetic spin, with spin-orbit coupling

Data structure layout#

The size and order of values in ConfigDoFValues() is standardized as follows:

occupation(): Occupation DoF values are accesible as a np.ndarray[numpy.int32[n_sites, 1]], where n_sites is the number of sites in the supercell.
- The occupant values, for example [0, 1, 0, 2, 1, …], specify the occupant on each site in a supercell.
- The position in the array is called the linear_site_index.
- The values are indices into the list of allowed occupants, as specified by a Prim, on the associated supercell site.
- Sites in the occupation vector are organized in blocks by sublattice:
```
# Occupation vector layout:
# [<-- sublattice 0 -->][<-- sublattice 1 -->]...[<-- sublattice n-1 -->]
```
- For a particular supercell, each sublattice block is of size n_unitcells, the number of unitcells in the supercell
- In each sublattice block, the sites are ordered according to the linear_unitcell_index of a particular unit cell. Conversions between unit cell indices (i,j,k) and linear_unitcell_index can be done using UnitCellIndexConverter.
- Conversions between linear_site_index and IntegralSiteCoordinate (unit cell index (i,j,k) and sublattice index b) can be done using SiteIndexConverter.
- IntegralSiteCoordinate can be used for conversions to and from Cartesian and fractional coordinates.
local_dof_values(): Local continuous DoF values are accesible as a numpy.ndarray[numpy.float64[matrix_dim, n_sites]], where n_sites is the number of sites in the supercell, and matrix_dim varies by DoF type and basis type. A DoF type string (i.e. “disp” for displacements) is used as a key to access the values array.
- For example, when using the standard basis for displacement DoF, matrix_dim=3.
- Values can be accessed using indices [dof_component_index, linear_site_index]:
  - Columns of local_dof_values() correspond to sites in the supercell using the same indexing conventions as the occupation vector.
  - Rows of local_dof_values() correspond to components of a local DoF value.
global_dof_values(): Global continuous DoF values, accesible by DoF type as a numpy.ndarray[numpy.float64[vector_dim, 1]], where vector_dim varies by DoF type and basis type. A DoF type string (i.e. “GLstrain” for strain represented using the Green-Lagrange strain metric) is used as a key to access the values array.
- For example, when using the standard basis for strain DoF, vector_dim=6.
- Values can be accessed using index [dof_component_index]:
  - Elements of global_dof_values() correspond to components of a global DoF value.

Basis types#

There are two basis types for the continuous DoF values in ConfigDoFValues:

The “standard DoF basis”, using the standard definition of CASM supported DoF types (i.e. x, y, z for displacments)
- Used for input and output, such as serialization, conversion to Structure(), mapping from Structure(), etc.
The “prim DoF basis”, which is specified by the DoFSetBasis used to define the space of allowed DoF in a Prim
- Allows specifiying DoF values, including those that have been constrained to a subspace of the full standard DoF space (i.e. two-dimensional displacements, or only isotropic strains) using independent variables
- Used as the input to cluster expansion and order parameter calculators

When using the standard DoF basis:

The matrix_dim (row dimension) of local DoF and vector_dim of global DoF is the standard DoF dimension (i.e. 3 for displacements, 6 for strain), and DoF components are ordered using the CASM standard definitions. See the CASM Degrees of Freedom (DoF) and Properties documentation for definitions.

When using the prim DoF basis:

The matrix_dim (row dimension) of local DoF is the maximum dimension of the basis for that DoF type on any sublattice.
For local DoF, rows of zeros may be present at the bottom of a sublattice block if it is constrained to a smaller subspace than DoF of the same type on other sublattices.
The vector_dim of global DoF is the dimension of the basis for that DoF type.

Construction#

There are factory functions to construct properly sized and zero-valued ConfigDoFValues instances for both basis types:

make_default_config_dof_values(): Construct ConfigDoFValues sized for use of the “prim DoF basis” in a supercell of a particular size
make_default_standard_config_dof_values(): Construct ConfigDoFValues sized for use of the “standard DoF basis” in a supercell of a particular size

Changing basis#

Conversions between the two basis types can performed using:

from_standard_values(): Convert to the “prim DoF basis” from the “standard DoF basis”
to_standard_values(): Convert to the “standard DoF basis” from the “prim DoF basis”

Input and output#

For serialization, ConfigDoFValues can be converted to and from representations using plain old Python data types (list, dict, int, float, bool, str) using:

After conversion to dict, either json (for long term storage and portability) or pickle (for fast local storage) can be used to save ConfigDoFValues.

For a description of the format, see ConfigDoF JSON object.

Note

There is no change in basis when using to_dict or from_dict, so serialization can be done for ConfigDoFValues in either the standard DoF basis or prim DoF basis. However, the recommended convention is that the standard DoF basis is used for input and output.

Conversions to and from other data structures, such as conversion to Structure and mapping from Structure are outside the scope of this module. See libcasm-configuration and libcasm-mapping for those type of conversions.