Cluster space

ClusterSpace

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

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) – A configuration object that holds information on how the cluster space should be built, e.g., values for tolerances and specifications regarding the handling of acoustic sum rules; if config is not given then the keyword arguments that follow below can be used for configuration.

• 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
>>> from hiphive import ClusterSpace
>>> prim = bulk('W')
>>> cs = ClusterSpace(prim, [5.0, 4.0])

property acoustic_sum_rules: bool

True if acoustic sum rules are enforced.

property atom_list: BiMap

Atoms inside the cutoff relative to the of the center cell.

property cluster_list: BiMap

Clusters possible within the cutoff.

property cutoffs: Cutoffs

Cutoffs used for constructing the cluster space.

get_n_dofs_by_order(order)

Returns number of degrees of freedom for the given order.

Parameters:

order (int) – Order for which to return the number of DOFs.

Return type:

int

Returns:

Number of degrees of freedom.

get_parameter_indices(order)

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

Parameters:

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

Return type:

list[int]

Returns:

List of parameter indices associated with the requested order.

Raises:

ValueError – If the order is not included in the cluster space.

property length_scale: bool

Normalization constant of the force constants.

property n_dofs: int

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.

property orbit_data: list[dict]

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

property orbits: list[Orbit]

Orbits associated with the lattice structure.

property permutations: list[ndarray]

Lookup for permutation references.

property primitive_structure: Atoms

Structure of the lattice.

print_orbits()

Prints a list of all orbits.

print_tables()

Prints information concerning the underlying cluster space to stdout, including, e.g., the number of cluster, orbits, and parameters by order and number of bodies.

read()

Reads a cluster space from file.

Parameters:

f (Union[str, BinaryIO, TextIO]) – Name of input file (str) or stream to load from (file object).

property rotation_matrices: list[ndarray]

Symmetry elements (3x3 matrices) representing rotations.

property spacegroup: str

Space group of the lattice structure obtained from spglib.

property symprec: float

Symprec value used when constructing the cluster space.

property translation_vectors: list[ndarray]

Symmetry elements representing translations.

write(fileobj)

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 (Union[str, BinaryIO, TextIO]) – 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.

property wyckoff_sites: list

Wyckoff sites in the primitive cell.

Cutoffs

class hiphive.cutoffs.BaseClusterFilter

Base cluster filter class.

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

setup(atoms)

The filter is passed the environment of the primitive cell.

Parameters:

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

class hiphive.cutoffs.CutoffMaximumBody(cutoff_list, max_nbody)

Class for specifying cutoff-list plus maximum body.

Usefull when creating, e.g., sixth order expansions but with only 3-body interactions.

Parameters:

• cutoff_list (list[float]) – 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)

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.

property cutoff_matrix: ndarray

Copy of cutoff matrix.

get_cutoff(order, nbody)

Returns the 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.

Return type:

float

property max_cutoff: float

Maximum cutoff.

property max_nbody: int

Maximum body.

max_nbody_cutoff(nbody)

Return maximum cutoff for a given body.

Parameters:

nbody (int)

max_nbody_order(nbody)

Returns maximum order for a given body.

Parameters:

nbody (int)

property max_order: int

Maximum order.

property nbodies: list[int]

Allowed bodies.

property orders: list[int]

Allowed orders.

read()

Reads a Cutoffs instance from file.

Parameters:

fileobj (Union[BinaryIO, TextIO]) – Input file to read from.

to_filename_tag()

Simple function turning cutoffs into a string to be used in, e.g., file names.

Return type:

str

write(fileobj)

Writes instance to file.

Parameters:

fileobj (Union[BinaryIO, TextIO]) – File-like object to which the cutoffs will be written.

hiphive.cutoffs.estimate_maximum_cutoff(atoms, max_iter=11)

Estimates the maximum possible cutoff given the atoms object.

Parameters:

• atoms (Atoms) – Structure used for checking compatibility with cutoff.

• max_iter (int) – Number of iterations in binary search.

Return type:

float

hiphive.cutoffs.is_cutoff_allowed(atoms, cutoff)

Checks if atoms is compatible with cutoff.

Parameters:

• atoms (Atoms) – Structure used for checking compatibility with cutoff.

• cutoff (float) – Cutoff to be tested.

Return type:

bool

Returns:

True if cutoff is compatible with atoms, else False.