# Workflow¶

## Overview¶

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.

The typical workflow involves the following steps:

- generate a set of input structures and compute the forces in these structures using a reference method, most commonly density functional theory
- 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 - initialize a structure container (via
`StructureContainer`

) using the cluster space from the second step and the set of input structures with reference forces from the first step for training and validation - fit the parameters using an optimizer (e.g.,
`Optimizer`

,`EnsembleOptimizer`

, or`CrossValidationEstimator`

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

- create force constant matrices
(via
`ForceConstants`

) for a specific supercell structure and analyze properties related to phonons using phonopy, phono3py or shengBTE, or - create a force constant calculator
(via
`ForceConstantCalculator`

) for a specific supercell structure and run molecular dynamics simulations using the atomic simulation environment, from which one can extract various quantities including e.g., the thermal conductivity, phonon dispersions, phonon lifetimes, and free energies while fully including anharmonic effects.

This basic workflow is illustrated in detail in the tutorial section. Further applications are discussed in the additional 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¶

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.