make_cluster_expansion#

libcasm.clexulator.make_cluster_expansion(
coefficients: SparseCoefficients | list[SparseCoefficients],
supercell_neighbor_list: SuperNeighborList | None = None,
clexulator: Clexulator | LocalClexulator = None,
config_dof_values: ConfigDoFValues | None = None,
prim_neighbor_list: PrimNeighborList | None = None,
transformation_matrix_to_super: ndarray | None = None,
xtal_prim: Prim | None = None,
cluster_expansion_type: str | None = 'periodic',
clexulator_source: str | None = None,
compile_options: str | None = None,
so_options: str | None = None,
) → Tuple[ClusterExpansion, ClusterExpansionInfo][source]#

Factory function for constructing cluster expansion calculators

Basic usage, evaluating a periodic cluster expansion

For basic usage, it is convenient to let make_cluster_expansion() construct the clexulator and neighbor lists used by the cluster expansion, and the ConfigDoFValues instance which is evaluated by the cluster expansion. For example:

# construct a ClusterExpansion calculator
cluster_expansion, info = make_cluster_expansion(
    xtal_prim=xtal_prim, # libcasm.xtal.Prim
    clexulator_source=clexulator_source, # str, path to clexulator source code
    coefficients=coefficients, # libcasm.clexulator.SparseCoefficients
    transformation_matrix_to_super=transformation_matrix_to_super, # np.ndarray
)

For more details, see the section Evaluating a cluster expansion

In this case, the method returns the tuple (cluster_expansion, info), where cluster_expansion is a periodic cluster expansion calculator of type ClusterExpansion, and info is an instance of ClusterExpansionInfo, that can be used to access the neighbor lists and ConfigDoFValues instance that were generated.

Evaluating local cluster expansions

To evaluate local cluster expansions with a cluster_expansion of type LocalClusterExpansion, the cluster_expansion_type should be set to “local”.

Evaluating multiple cluster expansions using the same basis set

When multiple periodic or local cluster expansions use the same basis set with different expansion coefficients, the calculator types MultiClusterExpansion and MultiLocalClusterExpansion can be used to simplify evaluating them all with a single evaluation of the basis functions. These can be constructed by setting cluster_expansion_type to “multi_periodic” or “multi_local”, respectively, and using cofficients to provide a list of SparseCoefficients instead of a single instance.

Evaluating multiple cluster expansions in the same supercell

If multiple periodic or local cluster expansions will be used in the same supercell, it is necessary to set them all to evaluate the same ConfigDoFValues instance and preferrable to re-use neighbor lists. For this use case, the data from the output info can be used as input parameters to construct additional periodic or local cluster expansions in repeated uses of make_cluster_expansion(). For example:

formation_energy_cluster_expansion, info = make_cluster_expansion(
    coefficients=formation_energy_coefficients,
    clexulator_source=formation_energy_clexulator_source,
    xtal_prim=xtal_prim,
    transformation_matrix_to_super=transformation_matrix_to_super,
)
prim_neighbor_list=info.prim_neighbor_list
supercell_neighbor_list=info.supercell_neighbor_list
config_dof_values = info.config_dof_values
hop_1_cluster_expansion, _ = make_cluster_expansion(
    coefficients=[hop_1_kra_coefficients, hop_1_freq_coefficients],
    clexulator_sourcesource=hop_1_clexulator_source,
    prim_neighbor_list=prim_neighbor_list,
    supercell_neighbor_list=supercell_neighbor_list,
    config_dof_values=config_dof_values,
    cluster_expansion_type="multi_local",
)
Parameters:

  • coefficients (Union[SparseCoefficients, list[SparseCoefficients]]) – Cluster expansion coefficients to use. May be a single SparseCoefficients instance for evaluating a single cluster expansion (cluster_expansion_type equal to “periodic” or “local”), or a list of SparseCoefficients instances for constructing multiple cluster expansions that use the same cluster basis fucntions (cluster_expansion_type equal to “multi_periodic” or “multi_local”).

  • supercell_neighbor_list (Optional[SuperNeighborList]=None) – The SuperNeighborList to use. If None, a new instance will be constructed with the transformation_matrix_to_super parameter.

  • clexulator (Union[Clexulator, LocalClexulator]=None) – The Clexulator used to evaluate basis functions. If None, a new instance will be constructed using the prim_neighbor_list, clexulator_source, compile_options, and so_options parameters.

  • config_dof_values (Optional[ConfigDoFValues]=None) – The ConfigDoFValues to be evaluated. If None, a new instance will be constructed with the xtal_prim parameter.

  • prim_neighbor_list (Optional[PrimNeighborList]=None) – The PrimNeighborList to use if necessary to construct supercell_neighbor_list or clexulator. If None, a new instance will be constructed.

  • transformation_matrix_to_super (Optional[np.ndarray]=None) – The supercell definining transformation matrix to use if necessary to construct supercell_neighbor_list.

  • xtal_prim (Optional[Prim]=None) – The Prim, defining the crystal structure and allowed degrees of freedom (DoF), used if necessary to construct config_dof_values.

  • cluster_expansion_type (Optional[str] = "periodic") –

    Specify the type of cluster expansion calculator to construct. One of the following:

  • clexulator_source (Optional[str]=None) – The location of the clexulator source code file, used if necessary to construct clexulator. For local cluster expansions, this is the location of the prototype source code file.

  • compile_options (Optional[str] = None) – An optional parameter, forwarded to make_clexulator() or make_local_clexulator(), that is used if necessary to construct clexulator.

  • so_options (Optional[str] = None) – An optional parameter, forwarded to make_clexulator() or make_local_clexulator(), that is used if necessary to construct clexulator.

Returns:

(cluster_expansion, info) –

cluster_expansion:

The constructed cluster expansion calculator, of type specified by the cluster_expansion_type parameter.

info: ClusterExpansionInfo

Contains the prim_neighbor_list, supercell_neighbor_list, clexulator, and config_dof_values used to construct cluster_expansion.

Return type:

Tuple