Cluster expansions#

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

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).

copy()[source]

Returns an independent copy of this cluster expansion.

Nothing is shared with this cluster expansion except the orbit list, which cannot be modified and therefore makes the copy cheap. Pruning or editing either cluster expansion leaves the other as it was, including through a value nested in the metadata.

The copy carries the metadata of this cluster expansion rather than metadata describing when the copy was made. A value in the metadata that cannot be copied makes this method raise. Writing a cluster expansion pickles its metadata, so such a value already prevents write() from working.

The copy module of the standard library goes through this method, so copy.copy() and copy.deepcopy() both return an equally independent cluster expansion.

Return type:: ClusterExpansion

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()[source]

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

The copy shares the immutable orbit list with this cluster expansion and is therefore cheap. Pruning or merging it replaces its orbit list and leaves the cluster expansion untouched, which is what keeps the parameters of the expansion consistent with the cluster space they were fitted against.

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)[source]

Returns the property value predicted by the cluster expansion.

Parameters:: structure (Atoms) – Atomic configuration.
Return type:: float

property primitive_structure: Atoms: Primitive structure on which cluster expansion is based.

prune(indices=None, tol=0)[source]

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 (list[int] | None) – 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)[source]

Reads ClusterExpansion object from file.

Parameters:: filename (str) – File from which to read.
Return type:: ClusterExpansion

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

to_dataframe()[source]

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

Return type:: DataFrame

write(filename)[source]

Writes ClusterExpansion object to file.

Parameters:: filename (str) – name of file to which to write
Return type:: None