CASM

First-principles statistical mechanical software for the study of multi-component crystalline solids

Degrees of Freedom (DoF) and Properties

Overview

CASM distinguishes between degrees of freedom (DoF), which are independent variables, and properties, which are dependent variables.

Whether a particular type of value is a degree of freedom or a property varies depending on the context.

Example:

  • When constructing a phonon Hamiltonian, atomic displacements are DoF.
  • When constructing an effective Hamiltonian that is a function of occupation only, atomic displacements are a property that is calculated.

In some cases, it is useful to treat some values of the same type as degrees of freedom.

Example: A system with some high mass elements with atomic displacements treated as DoF, and some low mass elements with atomic displacements treated as properties dependent on the location of the high mass atoms

In general, both DoF and properties may be anisotropic values, and the type of value determines how the value transforms under application of symmetry.

Example:

  • Cartesian coordinates, displacements, and lattice vectors all transform by applying the Cartesian matrix of a symmetry operation to the value being transformed.
  • Other types of values, such as strain and magnetic moments, require different symmetry representations.

In CASM, all types of values are represented using vectors, and symmetry representations take the form of permutations or transformation matrices.

Naming conventions

A particular instance of a DoF or property is labeled with a name string.

DoF Naming

Exact name strings of a supported DoF type must be used for a prim or Configuration.

Property Naming

Property name strings must end with the type name (i.e. "disp", "Ustrain", "energy", etc.) and may also include a modifier describing the particular property (i.e. "formation" in "formation_energy").

If a modifier exists, it must be separated from the type name by an underscore character (_). The name of a new type may not include an underscore.

Thus, whenever a particular property name is encountered, the property type can be determined and used to lookup the traits information needed to act on the property values.

Examples:

  • instance name: "energy" -> type name: "energy"
  • instance name: "relaxed_energy" -> type name: "energy"
  • instance name: "formation_energy" -> type name: "energy"
  • instance name: "relaxedenergy" -> Error (because there is no underscore)
  • instance name: "Ustrain" -> type name: "Ustrain"
  • instance name: "strain" -> Error (because there no strain metric)

Property name strings are used in:

Properties list

Standard property types included in CASM:

Name Description Type Variable descriptions Variable names (if different)
"cost" Cost function value Global $[C]$  
"disp"[1] Atomic displacement Site $[d_x, d_y, d_z]$  
"energy" Energy Global $[E]$  
"force" Force Site $[f_x, f_y, f_z]$  
"Cmagspin" Collinear magnetic spin Site $[m]$  
"Cunitmagspin" Collinear magnetic spin, constrained to unit length Site $[m]$  
"NCmagspin" Non-collinear magnetic spin, without spin-orbit coupling Site $[s_x, s_y, s_z]$  
"NCunitmagspin" Non-collinear magnetic spin, without spin-orbit coupling, constrained to unit length Site $[s_x, s_y, s_z]$  
"SOmagspin" Non-collinear magnetic spin, with spin-orbit coupling Site $[s_x, s_y, s_z]$  
"SOunitmagspin" Non-collinear magnetic spin, with spin-orbit coupling, constrained to unit length Site $[s_x, s_y, s_z]$  
"selectivedynamics"[2] Selective dynamics tag Site [“aflag”, “bflag”, “cflag”]  
"Bstrain"[1][3] Biot strain metric, $(U-I)$ Global $[E_{xx}, E_{yy}, E_{zz}, \sqrt(2)E_{yz}, \sqrt(2)E_{xz}, \sqrt(2)E_{xy}]$ $[e_1, e_2, e_3, e_4, e_5, e_6]$
"EAstrain"[1][3] Euler-Almansi strain metric, $\frac{1}{2}(I-(F F^{T})^{-1})$ Global $[E_{xx}, E_{yy}, E_{zz}, \sqrt(2)E_{yz}, \sqrt(2)E_{xz}, \sqrt(2)E_{xy}]$ $[e_1, e_2, e_3, e_4, e_5, e_6]$
"GLstrain"[1][3] Green-Lagrange strain metric, $\frac{1}{2}(C-I)$ Global $[E_{xx}, E_{yy}, E_{zz}, \sqrt(2)E_{yz}, \sqrt(2)E_{xz}, \sqrt(2)E_{xy}]$ $[e_1, e_2, e_3, e_4, e_5, e_6]$
"Hstrain"[1][3] Hencky strain metric, $\frac{1}{2}ln(C)$ Global $[E_{xx}, E_{yy}, E_{zz}, \sqrt(2)E_{yz}, \sqrt(2)E_{xz}, \sqrt(2)E_{xy}]$ $[e_1, e_2, e_3, e_4, e_5, e_6]$
"Ustrain"[1][3] Right stretch tensor, $U$ Global $[E_{xx}, E_{yy}, E_{zz}, \sqrt(2)E_{yz}, \sqrt(2)E_{xz}, \sqrt(2)E_{xy}]$ $[e_1, e_2, e_3, e_4, e_5, e_6]$

Notes:

  1. When both displacements and strain are applied, displacements are applied first and then the displaced coordinates and lattice vectors are strained.
  2. The "selectivedynamics" tag should be given a value of 1 to allow displacements along a given lattice vector (corresponding to T in a VASP POSCAR) and 0 to prevent them (F in a VASP POSCAR). The current implementation may be used with either (i) volume 1 configurations only, or (ii) restricted to the values [1., 1., 1.] or [0., 0., 0.]. Using "selectivedynamics" with mixed values (ex: [1., 0., 0.] and volume >1 configurations is not currently supported and will likely give invalid results because they will be applied to the supercell lattice vectors.
  3. The strain metrics, $E$, are defined in terms of the deformation gradient tensor, $F$, and Green’s deformation tensor, $C$. The deformation gradient tensor relates the strained and unstrained lattices through $L^{strained} = F * L^{ideal}$, where $L$ is a column-vector matrix of the lattice vectors. The deformation matrix tensor can be decomposed, via $F = R * U$, into a rotation tensor, $R$, and stretch tensor, $U$. Green’s deformation tensor, $C = F^{T}*F$, excludes rigid rotations.

DoF list

Standard DoF types included in CASM:

Name Description Type Standard basis Axis names (if different)
"disp"[1] Atomic displacement Site $[d_x, d_y, d_z]$  
"Cmagspin" Collinear magnetic spin Site $[m]$  
"Cunitmagspin" Collinear magnetic spin, constrained to unit length Site $[m]$  
"NCmagspin" Non-collinear magnetic spin, without spin-orbit coupling Site $[s_x, s_y, s_z]$  
"NCunitmagspin" Non-collinear magnetic spin, without spin-orbit coupling, constrained to unit length Site $[s_x, s_y, s_z]$  
"SOmagspin" Non-collinear magnetic spin, with spin-orbit coupling Site $[s_x, s_y, s_z]$  
"SOunitmagspin" Non-collinear magnetic spin, with spin-orbit coupling, constrained to unit length Site $[s_x, s_y, s_z]$  
"EAstrain"[1][2] Euler-Almansi strain metric, $\frac{1}{2}(I-(F F^{T})^{-1})$ Global $[E_{xx}, E_{yy}, E_{zz}, \sqrt(2)E_{yz}, \sqrt(2)E_{xz}, \sqrt(2)E_{xy}]$ $[e_1, e_2, e_3, e_4, e_5, e_6]$
"GLstrain"[1][2] Green-Lagrange strain metric, $\frac{1}{2}(C-I)$ Global $[E_{xx}, E_{yy}, E_{zz}, \sqrt(2)E_{yz}, \sqrt(2)E_{xz}, \sqrt(2)E_{xy}]$ $[e_1, e_2, e_3, e_4, e_5, e_6]$
"Hstrain"[1][2] Hencky strain metric, $\frac{1}{2}ln(C)$ Global $[E_{xx}, E_{yy}, E_{zz}, \sqrt(2)E_{yz}, \sqrt(2)E_{xz}, \sqrt(2)E_{xy}]$ $[e_1, e_2, e_3, e_4, e_5, e_6]$

Notes:

  1. When both displacements and strain are applied, displacements are applied first and then the displaced coordinates and lattice vectors are strained.
  2. The strain metrics, $E$, are defined in terms of the deformation gradient tensor, $F$, and Green’s deformation tensor, $C$. The deformation gradient tensor relates the strained and unstrained lattices through $L^{strained} = F * L^{ideal}$, where $L$ is a column-vector matrix of the lattice vectors. The deformation matrix tensor can be decomposed, via $F = R * U$, into a rotation tensor, $R$, and stretch tensor, $U$. Green’s deformation tensor, $C = F^{T}*F$, excludes rigid rotations.

Implementation

Note: This is an topic for developers. Please contact the CASM developers for additional information.

Implementing new properties

CASM implements a traits system, using the AnisoValTraits class, in which the value type name, as a string (i.e. "energy" for energy, "disp" for displacement, "occ" for occupation value), is used to lookup traits or methods that customize how a particular type is treated. This allows CASM to implement very general methods and provides for extensibility to new types of DoF and properties. Methods which work for a subset of value types are given the responsibility of checking their applicability and handling exceptions. Examples of supported value types and traits are given.

See implementations of AnisoValTraits instances for examples. To become a standard AnisoValTraits type, an instance must be added to the AnisoValTraits parsing dictionary.

Implementing new DoF

In order to implement a new DoF type, CASM must know how to convert between Configuration and Structure, and must know how to construct, write, and evaluate basis functions for that type. This requires an AnisoValTraits instance for the type and also that additional traits information must be provided by implementing a traits class derived from [DoFType::Traits].

Current DoF implementations include:

After a DoF traits class is implemented, it must be added it to the DoF traits parsing dictionary, which is accessed via DoFType::traits_dict().