Local cluster expansions#

Local cluster expansions describe a property of an event, such as the kinetically resolved activation energy of a hop, as a function of the occupations around the event.

HopEvent#

class icet.HopEvent(site_indices, offsets, species)[source]#

Prototype of a hop event in the primitive structure.

A hop event is an ordered tuple of lattice sites, each given as a basis index together with a unit cell offset in multiples of the primitive lattice vectors, plus the species that migrates between them. The first site is placed in the (0, 0, 0) cell by convention. An offset counts lattice vectors from the position of the basis site as the primitive structure gives it, including a position outside the cell.

site_indices#: Basis indices of the sites involved in the event.

offsets#: Unit cell offsets of the sites, one triple per site.

species#: Chemical symbol of the migrating species.

classmethod from_dict(dct)[source]#

Reconstructs an event from its dict representation.

Return type:: HopEvent

positions(primitive_structure)[source]#

Returns the Cartesian positions of the event sites.

Parameters:: primitive_structure (Atoms) – Primitive structure in which the event is defined.
Return type:: ndarray

property sites: list#: Lattice sites of the event as (basis index, offset) pairs.

to_dict()[source]#

Returns a dict representation, suitable for serialization.

Return type:: dict

icet.find_hop_events(primitive_structure, chemical_symbols, species, cutoff, vacancy_species='X', symprec=1e-05)[source]#

Finds the symmetry-distinct hop events of a primitive structure.

A candidate hop is an ordered pair of sites within cutoff of each other such that both sites allow the migrating species and the vacancy species. Both species are required on both sites, since the migrating atom sits on one site and the vacancy on the other, and the hop exchanges them. A binary alloy therefore needs the vacancy species among the allowed species of every sublattice it migrates on. Candidates that are equivalent under the space group of the sublattice-decorated primitive structure, including exchange of the endpoints, are reported once.

Parameters:

primitive_structure (Atoms) – Primitive structure.
chemical_symbols (list) – Allowed species, flat or per site.
species (str) – Chemical symbol of the migrating species.
cutoff (float) – Maximum distance between the endpoints of a hop.
vacancy_species (str) – Chemical symbol used for the vacant site. The default 'X' is the species of atomic number 0 that mchammer treats as a vacancy, which is what KineticMonteCarloEnsemble requires on the target site of a hop.
symprec (float) – Tolerance in Å passed to spglib, which also widens the cutoff.

Return type:

list

LocalClusterSpace#

class icet.LocalClusterSpace(primitive_structure, event, chemical_symbols, environment_cutoff, cluster_cutoffs=None, augmentation=None, symprec=1e-05)[source]#

An anchored local cluster space.

The space is anchored on an event prototype, a cluster of one or two sites of the primitive structure, one for the site of an interstitial and two for the endpoints of a hop. A model of a one-site event serves fitting and prediction, while KineticMonteCarloEnsemble requires an event of two sites. Basis functions are built from the occupations of the environment sites, meaning sites within environment_cutoff of the nearest anchor site that allow more than one species. The anchor sites themselves carry no basis functions, since their decoration is fixed by the event. Clusters that are equivalent under the point group that leaves both the crystal and the anchor invariant share one parameter.

Parameters:

primitive_structure (Atoms) – Primitive structure in which the event is defined.
event (HopEvent) – Event prototype that anchors the expansion.
chemical_symbols (list) – Species allowed on the sites of the primitive structure, either as a flat list valid for all sites or as one list per site.
environment_cutoff (float) – Maximum distance of an environment site from the nearest anchor site, which also bounds the singlets.
cluster_cutoffs (list) – Maximum intra-cluster distances per order, starting with pairs, following the convention of ClusterSpace.
augmentation (ConcentrationAugmentation) – Optional global features appended to the local cluster vector, given as a ConcentrationAugmentation, which documents what they are and what fitting them requires.
symprec (float) – Tolerance in Å passed to spglib, which also widens the cutoffs.

property as_list: list#: Human-readable summary of the elements of the space.

property augmentation: ConcentrationAugmentation#: Augmentation of the space, None when it carries none.

property augmentation_features: list#

Metadata of the augmentation features.

One dict per feature with the keys sublattices (the sorted species tuple of the group for a concentration feature, the tuple of involved groups for an orbit feature), groups (always the tuple of involved groups), and order.

property chemical_symbols: list#: Species allowed on each site of the primitive structure.

property cluster_cutoffs: list#: Maximum intra-cluster distances per order, starting with pairs.

property environment_cutoff: float#: Maximum distance of an environment site from the anchor.

property environment_sites: list#: Environment sites as (basis index, offset) pairs.

property event: HopEvent#: Event prototype that anchors the expansion.

find_event_instances(structure)[source]#

Returns every instance of the event prototype in a supercell.

Each instance is the tuple of its anchor site indices in ascending order, and the instances are ordered by their first site.

Parameters:: structure (Atoms) – Supercell in which to find the instances.
Raises:: ValueError – If the environment of an instance wraps onto itself or onto the anchor, if the supercell is not an integer repetition of the primitive structure, or if it is too small for the hop itself.
Return type:: list

classmethod from_dict(dct)[source]#

Reconstructs a local cluster space from its dict representation.

Return type:: LocalClusterSpace

get_environment_site_mapping(structure, event_sites)[source]#

Maps the environment sites of the prototype onto supercell indices.

The mapping is ordered like environment_sites. A mapping in which two environment sites land on the same supercell index, or on an anchor site, indicates a cell too small for the environment, which makes basis columns of the expansion proportional and any fit on such cells rank deficient. This method raises in that case.

Parameters:

structure (Atoms) – Supercell containing the event instance.
event_sites (tuple) – Indices of the anchor sites in the supercell.

Return type:

list

get_local_cluster_vector(structure, event_sites)[source]#

Returns the local cluster vector of an event instance.

Parameters:

structure (Atoms) – Supercell whose occupations define the environment.
event_sites (tuple) – Indices of the anchor sites in the supercell. The orbit part of the vector ignores the occupations of the anchor sites, since the event decoration is fixed by the prototype. The augmentation features average over all sites of their group, anchors included, which preserves the hop-direction symmetry, since swapping the two anchor decorations leaves the occupation multiset unchanged.

Return type:

ndarray

get_site_permutations(sites)[source]#

Returns the permutations of the given sites under the point group that leaves the crystal and the anchor invariant.

Each permutation maps the position of a site to the position of its image, and an operation that carries a site outside the given set contributes none.

Parameters:: sites (list) – Lattice sites of the primitive structure, as (basis index, offset) pairs.
Return type:: list

get_site_position(site)[source]#

Returns the Cartesian position of a lattice site of the primitive structure.

Parameters:: site – Lattice site as a (basis index, offset) pair.
Return type:: ndarray

property orbits: list#: Orbits of decorated clusters under the anchor point group.

property primitive_structure: Atoms#: Primitive structure in which the event is defined (copy).

classmethod read(filename)[source]#

Reads a local cluster space from a file.

Parameters:: filename (str) – Name of the file from which to read.
Return type:: LocalClusterSpace

to_dict()[source]#

Returns a dict representation, suitable for serialization.

Return type:: dict

write(filename)[source]#

Saves the local cluster space to a file.

Parameters:: filename (str) – Name of the file to which to write.
Return type:: None

LocalStructureContainer#

class icet.LocalStructureContainer(local_cluster_space)[source]#

A container for the training data of a local cluster expansion.

Each row of the container is an event observation, meaning a structure, the sites of the event instance within it, and a dict of scalar properties. The properties are locally defined energy differences in which supercell size and reference energies cancel, for example the kinetically resolved activation energy of a hop. Usually absolute or per-atom energies should not be kept in this kind of container.

Parameters:: local_cluster_space (LocalClusterSpace) – Local cluster space in which the observations are expressed.

Example

The following snippet illustrates the intended workflow. One observation is added per event instance, and the container is then queried for the sensing matrix and the target vector of one property:

>>> from ase.build import bulk
>>> from icet import (HopEvent, LocalClusterSpace,
...                   LocalStructureContainer)
>>> primitive_structure = bulk('Al', a=4.0)
>>> event = HopEvent(site_indices=(0, 0),
...                  offsets=((0, 0, 0), (1, 0, 0)),
...                  species='Al')
>>> local_cluster_space = LocalClusterSpace(
...     primitive_structure, event, [['Al', 'X']],
...     environment_cutoff=3.0)
>>> container = LocalStructureContainer(local_cluster_space)
>>> supercell = bulk('Al', a=4.0, cubic=True).repeat(2)
>>> supercell[0].symbol = 'X'
>>> container.add_event(supercell, (1, 2),
...                     properties={'E_kra': 0.42})
>>> container.add_event(supercell, (4, 5),
...                     properties={'E_kra': 0.51})
>>> matrix, targets = container.get_fit_data(key='E_kra')
>>> print(matrix.shape, targets)
(2, 5) [0.42 0.51]

The target of each observation comes from an external calculation, for example a nudged elastic band run on the supercell.

add_event(structure, event_sites, properties)[source]#

Adds an event observation to the container.

The local cluster vector of the event instance is computed and stored when the observation is added. A write of the container keeps the cell, the positions, the atomic numbers and the periodic boundary conditions of the structure.

Parameters:

structure (Atoms) – Supercell containing the event instance.
event_sites (tuple) – Indices of the anchor sites in the supercell.
properties (dict) – Scalar properties of the observation. Every value must be a finite real number. The values are fit targets, and a single non-finite one turns the whole parameter vector of the fit into NaN without an error anywhere.

Return type:

None

property available_properties: list[str]#: Names of the properties that occur in the container.

get_condition_number(structure_indices=None)#

Returns the condition number for the sensing matrix.

A very large condition number can be a sign of multicollinearity. More information can be found [here](https://en.wikipedia.org/wiki/Condition_number).

Parameters:: structure_indices (list[int] | None) – List of structure indices to include. By default (None) the method will return all fit data available.
Return type:: float
Returns:: Condition number of the sensing matrix.

get_fit_data(structure_indices=None, key='energy')#

Returns fit data for all structures. The feature vectors and target properties for all structures are stacked into numpy arrays.

Parameters:

structure_indices (list[int] | None) – List of structure indices. By default (None) the method will return all fit data available.
key (str) – Name of property to use. If None do not include property values. This can be useful if only the fit matrix is needed. By default the energy.

Return type:

tuple[ndarray, ndarray]

Returns:

Feature vectors and target properties for desired structures.

property local_cluster_space: LocalClusterSpace#: Local cluster space in which the observations are expressed.

classmethod read(filename)[source]#

Reads a container from a gzip-compressed JSON file.

Parameters:: filename (str) – Name of the file from which to read.
Return type:: LocalStructureContainer

to_dataframe()#

Summary of the container in DataFrame format.

Return type:: DataFrame

write(filename)[source]#

Writes the container to a gzip-compressed JSON file.

Parameters:: filename (str) – Name of the file to which to write.
Return type:: None

LocalClusterExpansion#

class icet.LocalClusterExpansion(local_cluster_space, parameters, metadata=None)[source]#

A local cluster expansion pairs a local cluster space with a set of parameters, where the latter is commonly obtained by fitting to locally defined energy differences such as kinetically resolved activation barriers. Instances of this class predict the local property for an event instance in a supercell.

Parameters:

local_cluster_space (LocalClusterSpace) – Local cluster space that defines the basis of the expansion.
parameters (ndarray) – Parameter vector, one element per element of the space.
metadata (dict | None) – User-defined metadata to be stored together with the expansion.

Raises:

ValueError – If local_cluster_space and parameters differ in length.

property local_cluster_space: LocalClusterSpace#: Local cluster space on which the expansion is based.

predict(structure, event_sites)[source]#

Returns the local property predicted for an event instance.

Parameters:

structure (Atoms) – Supercell whose occupations define the environment.
event_sites (tuple) – Indices of the anchor sites in the supercell.

Return type:

float

classmethod read(filename)[source]#

Reads a local cluster expansion from a file.

Parameters:: filename (str) – Name of the file from which to read.
Return type:: LocalClusterExpansion

write(filename)[source]#

Writes the local cluster expansion to a file.

Metadata is serialized as JSON, with numpy values converted to plain numbers and lists.

Parameters:: filename (str) – Name of the file to which to write.
Return type:: None