Cluster expansion details#

The CASM Clexulator#

CASM generates custom code for very efficient calculation of basis functions given a particular Prim and choice of cluster expansion basis functions. This source code is written to a file and then may be compiled, linked, and used at runtime via the class Clexulator (clexulator = CLuster EXpansion calcULATOR).

For periodic cluster expansions, CASM custom generates:

  • <primname>_Clexulator_<bsetname>.cc: a clexulator source code file that evaluates the basis functions

  • basis.json: a JSON file describing the cluster basis functions.

These files are written to a basis set directory, which is usually organized as:

/path/to/basis_sets/bset.<bsetname>/
├── <primname>_Clexulator_<bsetname>.cc
└── basis.json

Here, <primname> is the name given to the Prim and <bsetname> is a unique name for the cluster expansion basis set.

For local cluster expansions, CASM custom generates:

  • <primname>_Clexulator_<bsetname>.cc: a clexulator source code file for a prototype local cluster expansion

  • basis.json: a JSON file describing the cluster basis functions for the prototype

  • <equivalent_index>/<primname>_Clexulator_<bsetname>_<equivalent_index>.cc: source code files for each symmetrically equivalent local cluster expansion per unit cell

  • equivalents_info.json: a JSON file which describes the prototype local expansion basis set’s cluster basis and the symmetry operations which relate the prototype local expansion basis set to the symmetrically equivalent local cluster expansion basis sets.

From this information, CASM can compile functions to evaluate all the local cluster expansion basis functions and use a single set of expansion coefficients for each of the symmetrically equivalent local cluster expansions.

The files necessary for a local cluster expansion are all written to a local basis set directory, which is usually organized as:

/path/to/basis_sets/bset.<bsetname>/
├── 0
│   └── <primname>_Clexulator_<bsetname>_0.cc
├── 1
│   └── <primname>_Clexulator_<bsetname>_1.cc
├── ...
├── <primname>_Clexulator_<bsetname>.cc
├── equivalents_info.json
└── basis.json

As before, <primname> is the name given to the Prim and <bsetname> is a unique name for the local cluster expansion basis set.

Neighbor lists#

Clexulator source code contains the definition for a single translational equivalent of each cluster basis function. A neighbor list is used to determine the correct degree of freedom (DoF) values to evaluate the cluster basis function at a particular lattice translation. There are two types of neighbor lists:

  • PrimNeighborList: A prim neighbor list, defines an ordering of unit cells in the local neighborhood of a unit cell for a particular Prim.

  • SuperNeighborList: A neighbor list that uses the ordering specified by a prim neighbor list to construct a neighbor list for each unit cell in a supercell. One of these must be generated for each supercell in which cluster basis functions are evaluated.

For more details on constructing or using neighbor lists, see the section Neighbor lists.

When a Clexulator is constructed, a PrimNeighborList is constructed with the same ordering as the one used to write the basis functions, or if an existing PrimNeighborList is provided, it is validated that the ordering is the same. Then the PrimNeighborList can be used to construct SuperNeighborList for each supercell in which the cluster expansion will be evaluated.

Environment variables for compiling and linking Clexulator#

Before constructing a Clexulator or LocalClexulator, set the environment variable CASM_PREFIX to the location where CASM is installed in order to enable proper compilation and linking of the CASM clexulator using the CASM libraries:

export CASM_PREFIX=$(python -m libcasm.casmglobal --prefix)

In some cases, finer control of compilation and linking options may be necessary, which can be done as described in the make_clexulator documentation. For example, compiling and linking with gcc may require:

export CASM_SOFLAGS="-shared -Wl,--no-as-needed"

Constructing a Clexulator#

A Clexulator is constructed using a PrimNeighborList and the path to a CASM clexulator source file, using the factory function make_clexulator:

from libcasm.clexulator import make_clexulator, PrimNeighborList
prim_neighbor_list = PrimNeighborList()
clexulator = make_clexulator(
    source="/path/to/.../<primname>_Clexulator_<bsetname>.cc",
    prim_neighbor_list=prim_neighbor_list,
)

The PrimNeighborList provided to make_clexulator is expanded as necessary to include all sites required by the cluster basis functions.

Constructing a LocalClexulator#

A LocalClexulator is constructed in a similar manner as Clexulator, using the factory function make_local_clexulator:

from libcasm.clexulator import make_local_clexulator, PrimNeighborList
prim_neighbor_list = PrimNeighborList()
local_clexulator = make_local_clexulator(
    source="/path/to/.../<primname>_Clexulator_<bsetname>.cc",
    prim_neighbor_list=prim_neighbor_list,
)