Cluster expansions¶
- class icet.ClusterExpansion(cluster_space: icet.core.cluster_space.ClusterSpace, parameters: numpy.array, metadata: Optional[dict] = 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
- Type
- parameters
parameter vector
- Type
np.ndarray
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 fractional_position_tolerance: float
tolerance applied when comparing positions in fractional coordinates (inherited from the underlying cluster space)
- get_cluster_space_copy() → icet.core.cluster_space.ClusterSpace[source]
Gets copy of cluster space on which cluster expansion is based
- property metadata: dict
metadata associated with 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: Union[ase.atoms.Atoms, _icet.Structure]) → float[source]
Predicts the property of interest (e.g., the energy) for the input structure using the cluster expansion.
- Parameters
structure – atomic configuration
- Returns
property value of predicted by the cluster expansion
- Return type
float
- property primitive_structure: ase.atoms.Atoms
primitive structure on which cluster expansion is based
- print_overview(print_threshold: Optional[int] = None, print_minimum: int = 10) → None[source]
Print an overview of the cluster expansion in terms of the orbits (order, radius, multiplicity, corresponding ECI etc).
- Parameters
print_threshold – if the number of orbits exceeds this number print dots
print_minimum – number of lines printed from the top and the bottom of the orbit list if print_threshold is exceeded
- prune(indices: Optional[List[int]] = None, tol: float = 0) → None[source]
Removes orbits from the cluster expansion (CE), for which the absolute values of the corresponding 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 achieved by setting the tol keyword.
- Parameters
indices – indices of parameters to remove from the cluster expansion.
tol – all orbits will be pruned for which the absolute parameter value(s) is/are within this tolerance
- static read(filename: str)[source]
Reads ClusterExpansion object from file.
- Parameters
filename – file from which to read
- property symprec: float
tolerance imposed when analyzing the symmetry using spglib (inherited from the underlying cluster space)
- to_dataframe() → pandas.core.frame.DataFrame[source]
Returns representation of the cluster expansion in the form of a DataFrame containing orbit information and effective cluster interactions (ECIs).
- write(filename: str) → None[source]
Writes ClusterExpansion object to file.
- Parameters
filename – name of file to which to write