Evaluating order parameters#

DoFSpace#

A DoFSpace specifies a subspace of allowed degrees of freedom (DoF) values of a particular DoF type, with subspace basis $Q$ (with column basis vectors $q_{i}$ ), in terms of the prim DoF basis. This provides a definition for order parameters, $\vec{η}$ , according to $Q \vec{η} = \vec{x}$ , where $\vec{x}$ is a vector that is determined from the DoF values of a configuration.

Examples

For occupant DoF, $\vec{x}$ represents sublattice concentrations in the supercell commensurate with all ordered structures of interest, for example:

$\vec{x} = [n_{A}^{1}, n_{B}^{1}, n_{A}^{2}, n_{B}^{2}, \dots],$

where $n_{X}^{j}$ is the concentration of species $X$ on sublattice $j$ in the supercell.
For displacement DoF using the standard basis, $\vec{x}$ represents the average values of each displacement component on a sublattice in the supercell commensurate with all ordered structures of interest, for example:

$\vec{x} = [{\bar{d x}}^{1}, {\bar{d y}}^{1}, {\bar{d z}}^{1}, {\bar{d x}}^{2}, {\bar{d y}}^{2}, {\bar{d z}}^{2}, \dots],$

where ${\bar{d x}}^{j}, {\bar{d y}}^{j}, {\bar{d j}}^{j}$ indicates the average of the $x, y, z$ displacement component, respectively, on sublattice $j$ in the supercell.
For strain DoF, $\vec{x}$ represents the strain DoF values, for example:

$\vec{x} = [E_{x x}, E_{y y}, E_{z z}, \sqrt{2} E_{y z}, \sqrt{2} E_{x z}, \sqrt{2} E_{x y}] .$

Examples, non-standard prim basis

It is also possible to define order parameters in terms of a non-standard prim basis:

For displacement DoF using a non-standard prim basis allowing two-dimensional displacements:

$\vec{x} = [{\bar{d α}}^{1}, {\bar{d β}}^{1}, {\bar{d α}}^{2}, {\bar{d β}}^{2}, \dots],$

where ${\bar{d α}}^{j}, {\bar{d β}}^{j}$ indicates the average of the $α -, β -$ displacement component, respectively, on sublattice $j$ in the supercell commensurate with all ordered structures of interest.
For strain DoF using a symmetry-adapted prim strain basis, excluding shear:

$\vec{x} = [e_{1}, e_{2}, e_{3}],$

where $e_{1}, e_{2}, e_{3}$ are symmetry-adapted strains (see Thomas and Van der Ven [TVandVen17]):

$\begin{array}{r} \vec{e} = (\begin{array}{ccc} e_{1} \\ e_{2} \\ e_{3} \end{array}) = (\begin{array}{ccc} (E_{x x} + E_{y y} + E_{z z}) / \sqrt{3} \\ (E_{x x} - E_{y y}) / \sqrt{2} \\ (2 E_{z z} - E_{x x} - E_{y y} +) / \sqrt{6} \end{array}) . \end{array}$

Symmetry operations transform the DoF values of a configuration and the effect $\vec{x} \to {\vec{x}}^{'}$ can be represented by a symmetry representation matrix, $M_{i}$ , such that ${\vec{x}}^{'} = M_{i} \vec{x}$ .

Note

For each DoF type, there is a set of symmetry representation matrices, $M_{i}$ , which describe how the sublattice concentrations, average displacement components, and strain components, respectively, transform under symmetry operations.

Matrix representations, ${\tilde{M}}_{i}$ , that transform $\vec{η}$ according to ${\vec{η}}^{'} = {\tilde{M}}_{i} \vec{η}$ , are calculated as ${\tilde{M}}_{i} = Q^{- 1} M_{i} Q$ .

To calculate symmetry adapted order parameters, a DoFSpace should be constructed with a symmetry adapted basis, $Q$ , which block diagonalizes the matrix representations ${\tilde{M}}_{i}$ with the smallest possible blocks (the irreducible representations). A block-diagonal matrix representation can only transform vectors in the subspace corresponding to the block into other vectors in the same subspace. These are invariant subspaces under the application of the symmetry, and the order parameters in these subspaces can be used as input variables to symmetry adapted basis functions for properties of the configuration.

Construction of a symmetry adapted basis can be done using methods in libcasm-configuration, which provides support for determining and applying symmetry representations. This package provides the underlying methods that calculate $\vec{η}$ for a configuration (represented using ConfigDoFValues) given a particular choice of order parameter basis, $Q$ .

Global DoF#

For global DoF, each row of $Q$ , and corresponding element of $\vec{x}$ , is associated with one index:

dof_component_index: The index of the relevant global DoF value component on that site

Each element of $\vec{x}$ is the dof_component_index-th component of the global DoF value.

Local DoF#

For local continuous DoF and occupant DoF, DoFSpace is constructed with a supercell transformation matrix, $T$ , defining a DoFSpace supercell which specifies the periodicity of the order parameter. The DoFSpace supercell lattice vectors, as a column vector matrix, are $S = L T$ , where $L$ are the prim lattice vectors, as a column vector matrix.

Each row of $Q$ , and corresponding element in $\vec{x}$ , is associated with two indices:

linear_site_index: The index of the associated site in the DoFSpace supercell
dof_component_index: The index of the relevant DoF value component on that site

Note

The DoFSpace member function axis_info() can be used to lookup the mapping of DoF components to rows of $Q$ . For occupant DoF and local DoF, this includes the linear_site_index of the site where the DoF component is located.

For local continuous DoF, $\vec{x}$ is the average of the dof_component_index-th local DoF value component on sites belonging to the linear_site_index-th sublattice of the DoFSpace supercell.

For occupant DoF, $\vec{x}$ is the fraction sites belonging to the linear_site_index-th sublattice of the DoFSpace supercell that are occupied by the dof_component_index-th allowed occupant.

Note

For occupant DoF, elements of $\vec{x}$ as defined here are not independent. The sum of elements of $\vec{x}$ with the same linear_site_index must be 1.

The OrderParameter calculator#

The class OrderParameter is used to calculate:

the value of an order parameter
the change in the value of an order parameter given changes in degree of freedom (DoF) values

To calculate the order parameter value, OrderParameter uses:

DoFSpace: To specify the order parameter basis
SiteIndexConverter: To perform index conversions
ConfigDoFValues: OrderParameter is given a pointer to a ConfigDoFValues instance and calculates the order parameters using the current state of the DoF values

Construction#

A OrderParameter calculator can be constructed as follows:

import numpy as np
import libcasm.xtal as xtal
from libcasm.clexulator import (
    DoFSpace, OrderParameter,
)

# construct the Prim
xtal_prim = # xtal.Prim(...)

# specify the DoFSpace
dof_space = # DoFSpace(...)

# construct a OrderParameter calculator
order_parameter = OrderParameter(
    dof_space=dof_space,
)

Setup#

An OrderParameter instance is set to calculate order parameters in one supercell at a time, using the appropriate SiteIndexConverter. This can be set or changed using the update() method.

Order parameters are calculated for a ConfigDoFValues instance that can be specified using the call operator, the update() method, or the set() method.

Default configuration degree of freedom (DoF) values in a particular supercell can be constructed and the OrderParameter instance updated to evaluate using those values as follows:

import libcasm.xtal as xtal
from libcasm.clexulator import (
    make_default_config_dof_values,
)

# specify the supercell:
l_unitcells = # int(... specify a l * l * l unit cells sized supercell ...)
transformation_matrix_to_super = np.eye(3) * l_unitcells

# construct SiteIndexConverter
site_index_converter = xtal.SiteIndexConverter(
    transformation_matrix_to_super=transformation_matrix_to_super,
    n_sublattice=len(xtal_prim.occ_dof()),
)

# construct ConfigDoFValues, in the prim DoF basis
config_dof_values = make_default_config_dof_values(
    xtal_prim=xtal_prim,
    n_unitcells=round(np.linalg.det(transformation_matrix_to_super)),
)

# set the supercell and ConfigDoFValues used for order parameter calculation
order_parameter.update(
    transformation_matrix_to_super=transformation_matrix_to_super,
    site_index_converter=site_index_converter,
    config_dof_values=config_dof_values,
)

The transformation_matrix_to_super used to construct the ConfigDoFValues and SiteIndexConverter instances and given as the update() argument defines the supercell of the configuration being evaluated and therefore must be the same.

However, it does not need to be the same supercell as the DoFSpace is defined with. When evaluating the order paramers, if the configuration supercell differs from the the DoFSpace supercell:

For occupant DoF and local DoF, a commensurate supercell is determined internally and order parameters are evaluated as if the config_dof_values are tiled into the commensurate supercell.
For global DoF, the supercell is irrelevant.

Evaluate the order parameters#

The variable config_dof_values returned by make_cluster_expansion() is an instance of ConfigDoFValues which the OrderParameter calculator is set to evaluate.

Then, the cluster expansion value can be evaluated with:

# evaluate and get current order parameters value:
eta = order_parameter.value()

# eta is a const reference of type numpy.ndarray[numpy.float64[d, 1]],
# where d is the dimension of the DoFSpace basis (number of columns)

Internally, this uses config_dof_values to construct a vector, $\vec{x}$ , of the DoF values in the DoF space, averaged over the configuration supercell. Then, solving $Q \vec{η} = \vec{x}$ yields $\vec{η}$ .

Change DoF values and re-evaluate#

To change DoF values and re-calculate the cluster expansion, just modify the values of the ConfigDoFValues instance and re-evaluate. For a detailed discussion and some pitfalls, see the discussion Change DoF values and re-evaluate for ClusterExpansion.