The following figure illustrates the hiPhive 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\n(primitive cell)", shape=box]; Cutoffs [ color=darkgoldenrod2, label="cutoff radii for\neach order", shape=box]; Structures [ color=darkgoldenrod2, label="input structures\nwith reference forces", shape=box]; ClusterSpace [ href="../moduleref/cluster_space.html#hiphive.ClusterSpace", target="_top" ]; StructureContainer [ href="../moduleref/structures.html#hiphive.StructureContainer", target="_top" ]; Optimizer [ label="Optimizer", href="../moduleref/fitting.html", target="_top"]; ForceConstantPotential [ href="../moduleref/force_constants.html#hiphive.ForceConstantPotential", target="_top" ]; ForceConstants [ href="../moduleref/force_constants.html#hiphive.ForceConstants", target="_top" ]; ForceConstantCalculator [ href="../moduleref/force_constants.html#hiphive.calculators.ForceConstantCalculator", target="_top" ]; Supercell [ color=darkgoldenrod2, label="supercell structure", shape=box]; MD [ shape=rectangle, color=darkgreen, label="molecular dynamics simulations\n(via ASE)", fontcolor=white]; phonons [ shape=rectangle, color=darkgreen, label="properties related to phonons\n(via phonopy, phono3py, shengBTE)", fontcolor=white]; Prototype -> ClusterSpace; Cutoffs -> ClusterSpace; ClusterSpace -> StructureContainer; Structures -> StructureContainer; StructureContainer -> Optimizer [label="fit matrix and\nvector of target values"]; ClusterSpace -> ForceConstantPotential; Optimizer -> ForceConstantPotential [label=parameters]; ForceConstantPotential -> ForceConstants; Supercell -> ForceConstants; ForceConstants -> phonons; ForceConstants -> ForceConstantCalculator; ForceConstantCalculator -> MD; }

The typical workflow involves the following steps:

  1. initialize a cluster space (via ClusterSpace) by providing a prototype structure (typically a primitive cell) 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 forces for training and validation
  3. fit the parameters using an optimizer (e.g., Optimizer, EnsembleOptimizer, or CrossValidationEstimator)
  4. construct a force constant potential (via ForceConstantPotential) by combining the cluster space with a set of parameters obtained by optimization

The final FCP can be used in a number of ways. For example one can

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 along with a set of cutoffs for each (cluster) order to be included, as demonstrated in the tutorial section that illustrates the construction of a force constant potential. 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). A cluster space furthermore contains information pertaining to the symmetry operations that connect the clusters belonging to the same orbit and that ultimately define the relation between the parameters of a force constant potential and the force constants.

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 force constant potential construction. They can also be written to file for later use.


Optimizers allow one to train the parameters associated with each orbit in the cluster space. They are available in the form of optimizer classes such as Optimizer, EnsembleOptimizer, or CrossValidationEstimator.

Force constant potentials

A force constant potential (FCP; represented by the ForceConstantPotential class) is obtained by combining a cluster space with a set of parameters as illustrated in the tutorial on force constant potential construction. FCPs are the main output of the hiPhive model construction cycle. While they are specific for a given prototype structure and cluster space they are not tied to a specific supercell structure. FCPs can be written to file for later use.

Force constant matrices

Force constant matrices (represented by the ForceConstants class) are obtained by applying an FCP to a specific supercell structure. This allows one to conduct further analyses e.g., via phonopy, phono3py or shengBTE. This functionality is demonstrated in the tutorials on thermal properties in the harmonic approximations and phonon lifetimes.

Force constant calculators

An ASE calculator object (provided by the ForceConstantCalculator class) can be generated by applying an FCP to a specific supercell and can be subsequently employed to carry out e.g., molecular dynamics (MD) simulations as shown in the MD tutorial section.