# Cluster expansions¶

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

Cluster expansions are obtained by combining a cluster space with a set of effective cluster interactions (ECIs). Instances of this class allow one to predict the property of interest for a given structure.

cluster_space

cluster space that was used for constructing the cluster expansion

Type

icet.ClusterSpace

parameters

effective cluster interactions (ECIs)

Type

np.ndarray

Example

The following snippet illustrates the initialization and usage of a ClusterExpansion object. Here, the ECIs 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 ECIs
>>> prim = bulk('Au')
>>> cs = ClusterSpace(prim, cutoffs=[7.0, 5.0],
...                   chemical_symbols=[['Au', 'Pd']])
>>> ecis = len(cs) * [1.0]
>>> ce = ClusterExpansion(cs, ecis)

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

property fractional_position_tolerance

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

Return type

float

get_cluster_space_copy()[source]

Gets copy of cluster space on which cluster expansion is based

Return type

ClusterSpace

property metadata

Return type

dict

property orders

orders included in cluster expansion

Return type

List[int]

property parameters

effective cluster interactions (ECIs)

Return type

List[float]

property parameters_as_dataframe

dataframe containing orbit data and ECIs

Return type

DataFrame

plot_parameters(fname, orders=None)[source]

Plot ECIs for given orders, default plots for all orders

property position_tolerance

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

Return type

float

predict(structure)[source]

Predicts the property of interest (e.g., the energy) for the input structure using the cluster expansion.

Parameters

structure (Union[Atoms, Structure]) – atomic configuration

Returns

property value of predicted by the cluster expansion

Return type

float

property primitive_structure

Primitive structure on which cluster expansion is based

Return type

Atoms

print_overview(print_threshold=None, print_minimum=10)[source]

Print an overview of the cluster expansion in terms of the orbits (order, radius, multiplicity, corresponding ECI etc).

Parameters
• print_threshold (Optional[int]) – if the number of orbits exceeds this number print dots

• print_minimum (int) – number of lines printed from the top and the bottom of the orbit list if print_threshold is exceeded

Return type

None

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

Removes orbits from the cluster expansion (CE), for which the effective cluster interactions (ECIs; parameters) are zero or close to zero. This commonly reduces the computational cost for evaluating the CE and is therefore recommended prior to using it in production. If the method is called without arguments orbits will be pruned, for which the ECIs are strictly zero. Less restrictive pruning can be achived by setting the tol keyword.

Parameters
• indices (Optional[List[int]]) – indices to parameters to remove in the cluster expansion.

• tol (float) – orbits for which the absolute ECIs is/are within this value will be pruned

static read(filename)[source]

Parameters

filename (str) – file from which to read

property symprec

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

Return type

float

write(filename)[source]

Writes ClusterExpansion object to file.

Parameters

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