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.

# dot -Tsvg -o workflow.svg digraph g { graph [ fontname = "helvetica", fontsize = 12.0, rankdir = "TB", bgcolor = "transparent" ]; edge [ fontname = "helvetica", fontsize = 12.0, penwidth = 1.5 ] node [ fontname = "helvetica", fontsize = 12.0, fontcolor=white, shape="ellipse", color=cornflowerblue, style=filled]; Prototype [ color=darkgoldenrod2, label="prototype structure", shape=box]; Cutoffs [ color=darkgoldenrod2, label="cutoff radii for\neach order", shape=box]; Elements [ color=darkgoldenrod2, label="active species", shape=box]; Structures [ color=darkgoldenrod2, label="input structures\nwith reference data", shape=box]; ClusterSpace [ href="../moduleref_icet/cluster_space.html#icet.ClusterSpace", target="_top" ]; StructureContainer [ href="../moduleref_icet/structure_container.html#icet.StructureContainer", target="_top" ]; Optimizer [ label="Optimizer", href="../moduleref_icet/optimizers.html", target="_top"]; ClusterExpansion [ href="../moduleref_icet/cluster_expansion.html#icet.ClusterExpansion", target="_top" ]; ClusterExpansionCalculator [ href="../moduleref_mchammer/calculators.html#mchammer.calculators.ClusterExpansionCalculator", target="_top" ]; Supercell [ color=darkgoldenrod2, label="supercell structure", shape=box]; structures [ color=darkgoldenrod2, label="arbitrary structures", shape=box]; predict [ shape=rectangle, color=darkgreen, fontcolor=white, label="Predict property", href="../moduleref_icet/cluster_expansion.html#icet.ClusterExpansion.predict", target="_top"]; MC [ shape=rectangle, color=darkgreen, fontcolor=white, label="Monte Carlo simulations\nvia mchammer", href="../moduleref_mchammer/index.html", target="_top"]; Prototype -> ClusterSpace; Elements -> ClusterSpace; Cutoffs -> ClusterSpace; ClusterSpace -> StructureContainer; Structures -> StructureContainer; StructureContainer -> Optimizer [label="fit matrix and\nvector of target values"]; ClusterSpace -> ClusterExpansion; Optimizer -> ClusterExpansion [label=parameters]; structures -> predict; ClusterExpansion -> predict; Supercell -> ClusterExpansionCalculator; ClusterExpansion -> ClusterExpansionCalculator; ClusterExpansionCalculator -> MC; }

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

This basic workflow is illustrated in detail in the tutorial section. Further applications are discussed in the advanced topics section.

Key concepts

Cluster spaces

A cluster space (represented by the ClusterSpace class) is defined by providing a prototype structure, 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 prototype structure can be decomposed. (An orbit is a set of symmetry equivalent clusters, see Figure below).


insert figure that schematically shows clusters and orbits (and symmetry operations)

Structure containers

A structure container (represented by the StructureContainer class) is a collection of structures along with their decomposition into a specific cluster space. 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 allow one to train the effective cluster interaction (ECI) parameters associated with each orbit in the cluster space. They are available in the form of optimizer classes such as Optimizer, EnsembleOptimizer, or CrossValidationEstimator.

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.