Cluster expansions

class icet.ClusterExpansion(cluster_space, parameters, metadata=None)

Cluster expansions are obtained by combining a cluster space with a set of parameters, where the latter is commonly obtained by optimization. Instances of this class allow one to predict the property of interest for a given structure.

Note

Each element of the parameter vector corresponds to an effective cluster interaction (ECI) multiplied by the multiplicity of the underlying orbit.

cluster_space

Cluster space that was used for constructing the cluster expansion.

parameters

Parameter vector.

metadata

Metadata dictionary, user-defined metadata to be stored together with cluster expansion. Will be pickled when CE is written to file. By default contains icet version, username, hostname and date.

Raises:

ValueError – If cluster_space and parameters differ in length.

Example

The following snippet illustrates the initialization and usage of a ClusterExpansion object. Here, the parameters are taken to be a list of ones. Usually, they would be obtained by training with respect to a set of reference data:

>>> from ase.build import bulk
>>> from icet import ClusterSpace, ClusterExpansion

>>> # create cluster expansion with fake parameters
>>> prim = bulk('Au')
>>> cs = ClusterSpace(prim, cutoffs=[7.0, 5.0],
...                   chemical_symbols=[['Au', 'Pd']])
>>> parameters = len(cs) * [1.0]
>>> ce = ClusterExpansion(cs, parameters)

>>> # make prediction for supercell
>>> sc = prim.repeat(3)
>>> for k in [1, 4, 7]:
>>>     sc[k].symbol = 'Pd'
>>> print(ce.predict(sc))

property chemical_symbols: List[List[str]]

Species identified by their chemical symbols (copy).

property cutoffs: List[float]

Cutoffs for different n-body clusters (copy). The cutoff radius (in Ångstroms) defines the largest interatomic distance in a cluster.

property fractional_position_tolerance: float

Tolerance applied when comparing positions in fractional coordinates (inherited from the underlying cluster space).

get_cluster_space_copy()

Returns copy of cluster space on which cluster expansion is based.

Return type:

ClusterSpace

property metadata: dict

Metadata associated with the cluster expansion.

property orders: List[int]

Orders included in cluster expansion.

property parameters: List[float]

Parameter vector. Each element of the parameter vector corresponds to an effective cluster interaction (ECI) multiplied by the multiplicity of the respective orbit.

property position_tolerance: float

Tolerance applied when comparing positions in Cartesian coordinates (inherited from the underlying cluster space).

predict(structure)

Returns the property value predicted by the cluster expansion.

Parameters:

structure (Union[Atoms, Structure]) – Atomic configuration.

Return type:

float

property primitive_structure: Atoms

Primitive structure on which cluster expansion is based.

prune(indices=None, tol=0)

Removes orbits from the cluster expansion, for which the absolute values of the corresponding parameters are zero or close to zero. This commonly reduces the computational cost for evaluating the cluster expansion. It is therefore recommended to apply this method prior to using the cluster expansion in production. If the method is called without arguments only orbits will be pruned, for which the ECIs are strictly zero. Less restrictive pruning can be achieved by setting the tol keyword.

Parameters:

• indices (Optional[List[int]]) – Indices of parameters to remove from the cluster expansion.

• tol (float) – All orbits will be pruned for which the absolute parameter value(s) is/are within this tolerance.

Return type:

None

static read(filename)

Reads ClusterExpansion object from file.

Parameters:

filename (str) – File from which to read.

property symprec: float

Tolerance imposed when analyzing the symmetry using spglib (inherited from the underlying cluster space).

to_dataframe()

Returns a representation of the cluster expansion in the form of a DataFrame including effective cluster interactions (ECIs).

Return type:

DataFrame

write(filename)

Writes ClusterExpansion object to file.

Parameters:

filename (str) – name of file to which to write

Return type:

None