Evaluating a local cluster expansion

Construct a LocalClusterExpansion

By setting the cluster_expansion_type parameter to “local”, make_cluster_expansion() can also be used to construct a LocalClusterExpansion calculator:

# construct a LocalClusterExpansion calculator
local_cluster_expansion, info = make_cluster_expansion(
    cluster_expansion_type="local",
    xtal_prim=xtal_prim,
    clexulator_source=clexulator_source,
    coefficients=coefficients,
    transformation_matrix_to_super=transformation_matrix_to_super,
)

# get the ConfigDoFValues that cluster_expansion will evaluate
config_dof_values = info.config_dof_values

For local cluster expansion construction, clexulator_source is the path to the prototype local clexulator source code file (i.e. /path/to/<primname>_Clexulator_<bsetname>.cc).

Note

For local cluster expansions, clexulator source code is written for each symmetrically equivalent local basis set, which are stored indexed files relatives to the prototype local basis set. For more details see, Cluster Expansion Details.

Evaluate the local cluster expansion

The local cluster expansion value can be evaluated at a particular choice of:

• unitcell_index: Linear unit cell index specifying in which unit cell to evaluate the local correlations, as defined by UnitCellIndexConverter.

• equivalent_index: Index of the equivalent local basis set to evaluate. This index specifies a combined choice of (i) a particular phenomenal cluster of sites and (ii) a particular orientation of the local basis set at that cluster, when there are multiple symmetrically equivalent local basis sets around the same phenomenal cluster.

For a particular application, there should be a method that helps find the correct unitcell_index and equivalent_index, which depends on the details of the phenomena being modeled.

For example, OccEvent is a class which describes a diffusive hop of one or more occupants. A local cluster expansion can be used to predict the kinetically resolved activation barrier around a particular hop. The correct unitcell_index and equivalent_index to use for evaluating the local cluster expansion around a particular hop in a particular supercell can be found using the method get_occevent_coordinate(), which searches a list of phenomenal OccEvent to find which one is a strictly translational equivalent:

from libcasm.enumerate import get_occevent_coordinate

# ... calculate local cluster expansion value for the current state
#     of the ConfigDoFValues that local_cluster_expansion has been set with ...

# evaluate and return local cluster expansion value:
unitcell_index, equivalent_index = get_occevent_coordinate(
    occ_event=occ_event, # libcasm.occ_events.OccEvent
    phenomenal_occevent=phenomenal_occevent, # List[libcasm.occ_events.OccEvent]
    supercell=supercell, # libcasm.configuration.Supercell
)
value = local_cluster_expansion.value(unitcell_index, equivalent_index)