# Cluster space¶

## ClusterSpace¶

class hiphive.ClusterSpace(prototype_structure, cutoffs, config=None, cluster_filter=None, **kwargs)[source]

Primitive object for handling clusters and force constants of a structure.

Parameters
• prototype_structure (ase.Atoms) – prototype structure; spglib will be used to find a suitable cell based on this structure unless the cell is already a primitive cell.

• cutoffs (list or Cutoffs) – cutoff radii for different orders starting with second order

• cluster_filter (ClusterFilter) – accepts a subclass of hiphive.filters.BaseClusterFilter to further control which orbits to include.

• config (Config object) – config object containing information on how the cluster space should be built, e.g. values for tolerances and if acoustic sum rules be enforced

• not config is given then kwargs can be used to specify (If) –

• acoustic_sum_rules (bool) – If True the aucostic sum rules will be enforced by constraining the parameters.

• symprec (float) – numerical precision that will be used for analyzing the symmetry (this parameter will be forwarded to spglib)

• length_scale (float) – This will be used as a normalization constant for the eigentensors

Examples

To instantiate a ClusterSpace object one has to specify a prototype structure and cutoff radii for each cluster order that should be included. For example the following snippet will set up a ClusterSpace object for a body-centered-cubic (BCC) structure including second order terms up to a distance of 5 A and third order terms up to a distance of 4 A.

>>> from ase.build import bulk
>>> prim = bulk('W')
>>> cs = ClusterSpace(prim, [5.0, 4.0])

acoustic_sum_rules

True if acoustic sum rules are enforced

Type

bool

atom_list

atoms inside the cutoff relative to the of the center cell

Type

BiMap

cluster_list

clusters possible within the cutoff

Type

BiMap

cutoffs

cutoffs used for constructing the cluster space

Type

Cutoffs

get_n_dofs_by_order(order)[source]

Returns number of degrees of freedom for the given order.

Parameters

order (int) – order for which to return the number of dofs

Returns

number of degrees of freedom

Return type

int

get_parameter_indices(order)[source]

Returns a list of the parameter indices associated with the requested order.

Parameters

order (int) – order for which to return the parameter indices

Returns

list of parameter indices associated with the requested order

Return type

list(int)

Raises

ValueError – if the order is not included in the cluster space

length_scale

normalization constant of the force constants

Type

float

n_dofs

number of free parameters in the model

If the sum rules are not enforced the number of DOFs is the same as the total number of eigentensors in all orbits.

Type

int

orbit_data

detailed information for each orbit, e.g., cluster radius and atom types.

Type

list(dict)

orbits

orbits associated with the lattice structure.

Type

list(Orbit)

permutations

lookup for permutation references

Type

list(numpy.ndarray)

primitive_structure

structure of the lattice

Type

ase.Atoms

print_orbits()[source]

Prints a list of all orbits.

print_tables()[source]

Prints table data, i.e. information as a function of order and n-body for the clusterspace.

read()[source]

Reads a cluster space from file.

Parameters

f (str or file object) – name of input file (str) or stream to load from (file object)

rotation_matrices

symmetry elements (3x3 matrices) representing rotations

Type

list(numpy.ndarray)

spacegroup

space group of the lattice structure obtained from spglib

Type

str

symprec

symprec value used when constructing the cluster space

Type

float

translation_vectors

symmetry elements representing translations

Type

list(numpy.ndarray)

write(fileobj)[source]

Writes cluster space to file.

The instance is saved into a custom format based on tar-files. The resulting file will be a valid tar file and can be browsed by by a tar reader. The included objects are themself either pickles, npz or other tars.

Parameters

fileobj (str or file-like object) – If the input is a string a tar archive will be created in the current directory. Otherwise the input must be a valid file like object.

wyckoff_sites

wyckoff sites in the primitive cell

Type

list

## Cutoffs¶

class hiphive.cutoffs.BaseClusterFilter[source]

Base cluster filter class.

This filter simply accepts all proposed clusters. A proper subclass must implement the same methods.

setup(atoms)[source]

The filter is passed the environment of the primitive cell.

Parameters

atoms (ase.Atoms) – non-pbc primitive cell plus neighboring atoms

class hiphive.cutoffs.CutoffMaximumBody(cutoff_list, max_nbody)[source]

Specify cutoff-list plus maximum body

Usefull when creating e.g. 6th order expansions but with only 3-body interactions.

Parameters
• cutoff_list (list) – list of cutoffs for order 2, 3, etc. Must be in decresing order

• max_nbody (int) – No clusters containing more than max_nbody atoms will be generated

class hiphive.cutoffs.Cutoffs(cutoff_matrix)[source]

This class maintains information about the cutoff configuration, i.e. which clusters will be included (=”inside cutoff”). It also encapsulates functionality that is used e.g., during cluster space construction.

Here, n-body refers to number of atoms in a cluster. For example the cluster (0011) is a two-body cluster of fourth order and the cluster (123) is a three-body cluster of third order.

Parameters

cutoff_matrix (numpy.ndarray) – the matrix element ij provides to the cutoff for order j+2 and nbody i+2; elements with i>j will be ignored

cutoff_matrix

copy of cutoff matrix

Type

numpy.ndarray

get_cutoff(order, nbody)[source]

Returns cutoff for a given body and order.

Parameters
• order (int) –

• nbody (int) –

Raises
• ValueError – if order is not in orders

• ValueError – if nbody is not in nbodies

• ValueError – if nbody is larger than order

Returns

Return type

float

max_cutoff

maximum cutoff

Type

float

max_nbody

maximum body

Type

int

max_nbody_cutoff(nbody)[source]

Return maximum cutoff for a given body.

max_nbody_order(nbody)[source]

Returns maximum order for a given body

max_order

maximum order

Type

int

nbodies

allowed bodies

Type

list(int)

orders

allowed orders

Type

list(int)

read()[source]

Parameters

fileobj (file-like object) – input file to read from

to_filename_tag()[source]

Simple function turning cutoffs into a string to be used in e.g. filenames.

write(fileobj)[source]

Writes instance to file.

Parameters

fileobj (file-like object) – file-like object to which the cutoffs will be written to

class hiphive.cutoffs.MaxTripletDistance(max_dist)[source]

Rejects large three-body clusters.

If two or all pairs within the cluster are further away from each other than the specified distance the cluster is rejected. Alternatively, only one pair distance can exceed the specified cutoff.

The filter only rejects for three-body clusters. All other clusters are accepted.

Parameters

max_dist (float) – maximum distance allowed for the two closest pairs

hiphive.cutoffs.estimate_maximum_cutoff(atoms, max_iter=11)[source]

Estimates the maximum possible cutoff given the atoms object

Parameters
• atoms (ase.Atoms) – structure used for checking compatibility with cutoff

• max_iter (int) – number of iterations in binary search

hiphive.cutoffs.is_cutoff_allowed(atoms, cutoff)[source]

Checks if atoms is compatible with cutoff

Parameters
• atoms (ase.Atoms) – structure used for checking compatibility with cutoff

• cutoff (float) – cutoff to be tested

Returns

True if cutoff compatible with atoms object, else False

Return type

bool