Workflow

Note

This page provides an overview of the icet workflow. For a detailed introduction on how to use icet, please see the tutorial section. Further use cases and features are discussed in the advanced topics section with more detailed information regarding generating structures, the construction of cluster expansion models, and the sampling of such models.

Overview

The following figure illustrates the icet workflow. Here, classes are shown in blue, input parameters and data in orange, and functionalities invoked via external libraries are indicated in green.

The typical workflow involves the following steps:

1. initialize a cluster space (via ClusterSpace) by providing a prototype structure (typically a primitive cell), the species that are allowed on each site as well as cutoff radii for clusters of different orders

2. initialize a structure container (via StructureContainer) using the cluster space created previously and add a set of input structures with reference data for the property or properties of interest

3. fit the parameters using an optimizer (e.g., Optimizer, EnsembleOptimizer, or CrossValidationEstimator from the trainstation package)

4. construct a cluster expansion (via ClusterExpansion) by combining the cluster space with a set of parameters obtained by optimization

The final cluster expansion can be used in a number of ways. Most commonly one creates a cluster expansion calculator (via ClusterExpansionCalculator) for a specific supercell structure and subsequently carries out Monte Carlo simulations via the mchammer module

It is also possible to use a cluster expansion (via ClusterExpansion) directly to make predictions for arbitrary supercells of the primitive prototype structure, obtained e.g., by structure enumeration.

Key concepts

Cluster spaces

A cluster space (represented by the ClusterSpace class) is defined by providing a prototype structure (usually a primitive cell), the species allowed on each site, and a set of cutoffs for each (cluster) order to be included, as demonstrated in the tutorial section that illustrates the basic construction of a cluster expansion. It contains the set of clusters (pairs, triplets, quadruplets etc.) and orbits into which a structure can be decomposed. (An orbit is a set of symmetry equivalent clusters, see figure below). Such a decomposition is referred to as a cluster vector.

In simpler terms, a cluster vector is a numerical representation of an alloy structure, and a cluster space enables such representations to be obtained.

Clusters representing different orbits: one pair, one triplet, and one quadruplet. An orbit comprises all clusters that are equivalent under the symmetry operation of the underlying lattice.

Structure containers

A structure container (represented by the StructureContainer class) is a collection of structures along with their cluster vectors. Structure containers allow one to easily compile structures for training and validation, as demonstrated in the tutorial on basic construction of a cluster expansion. They can also be written to file for later use.

Optimizers

Optimizers allow one to train the effective cluster interactions (ECI) associated with each orbit in the cluster space. This functionality is maintained in the trainstation package, the documentation of which can be found here and which provides optimizer classes such as Optimizer, EnsembleOptimizer and CrossValidationEstimator.

Note

The optimized parameters returned by the optimizer are actually not the ECIs themselves but the ECIs times the multiplicity of the respective orbit. The distinction is handled internally but it is something to be aware of when inspecting the parameters directly.

Cluster expansions

A cluster expansion (CE; represented by the ClusterExpansion class) is obtained by combining a cluster space with a set of parameters as illustrated in the tutorial on basic construction of a cluster expansion. CEs are the main output of the icet model construction cycle. While they are specific for a given prototype structure and cluster space they are not tied to a specific supercell structure. CEs can be written to file for later use.

Cluster expansion calculators

A cluster expansion calculator (represented by the ClusterExpansionCalculator class) is needed in order to carry out Monte Carlo simulations via the mchammer module. They are generated by applying a CE to a specific supercell and are subsequently used to initialize a Monte Carlo ensemble as shown in the MC tutorial section.