# Core components¶

The low-level functions and classes described here are part of the hiPhive core components and not intended to be used directly during normal operation.

## cluster_space_builder¶

hiphive.core.cluster_space_builder.build_cluster_space(cluster_space, prototype_structure)[source]

The permutation list is an indexed fast lookup table for permutation vectors.

## constraints¶

hiphive.core.constraints.create_constraint_map(cs)[source]

## get_clusters¶

hiphive.core.get_clusters.create_neighbor_matrices(atoms, cutoff)[source]
hiphive.core.get_clusters.extend_cluster(cluster, order)[source]
hiphive.core.get_clusters.generate_geometrical_clusters(atoms, nPrim, cutoff, order)[source]
hiphive.core.get_clusters.get_clusters(atoms, cutoffs, nPrim, multiplicity=True, use_geometrical_order=False)[source]

Generate a list of all clusters in the atoms object which includes the center atoms with positions within the cell metric. The cutoff determines up to which order and range clusters should be generated.

With multiplicity set to True clusters like [0,0] and [3,3,4 etc will be generated. This is useful when doing force constants but not so much for cluster expansions.

The geometrical order is the total number of different atoms in the cluster. [0,0,1] would have geometrical order 2 and [1,2,3,4] would have order 4. If the key word is True the cutoff criteria will be based on the geometrical order of the cluster. This is based on the observation that many body interactions decrease fast with cutoff but anharmonic interactions can be quite long ranged.

Parameters: atoms (ase.Atoms) – can be a general atoms object but must have pbc=False. cutoffs (dict) – the keys specify the order while the values specify the cutoff radii multiplicity (bool) – includes clusters where same atom appears more than once geometrical_order (bool) – specifies if the geometrical order should be used as cutoff_order, otherwise the normal order of the cluster is used a list of clusters where each entry is a tuple of indices, which refer to the atoms in the input supercell list(tuple(int))

## get_orbits¶

hiphive.core.get_orbits.generate_translated_clusters(cluster, extended_atoms)[source]
hiphive.core.get_orbits.get_orbits(cluster_list, atom_list, rotation_matrices, translation_vectors, permutations, prim)[source]

Generate a list of the orbits for the clusters in a supercell configuration.

This method requires as input a list of the clusters in a supercell configuration as well as a set of symmetry operations (rotations and translations). From this information it will generate a list of the orbits, i.e. the set of symmetry inequivalent clusters each associated with its respective set of equivalent clusters.

Parameters: cluster_list (BiMap object) – a list of clusters atom_list (BiMap object) – a list of atoms in a supercell rotation_matrices (list of NumPy (3,3) arrays) – rotational symmetries to be imposed (e.g., from spglib) translation_vectors (list of NumPy (3) arrays) – translational symmetries to be imposed (e.g., from spglib) permutations (list of permutations) – lookup table for permutations prim (hiPhive Atoms object) – primitive structure orbits associated with the list of input clusters list of Orbits objs
hiphive.core.get_orbits.get_permutation_map(atoms, rotations, translations, basis)[source]
hiphive.core.get_orbits.populate_orbit(orbit, permutations, clusters, cluster, permutation_map, extended_atoms, cluster_is_found)[source]
hiphive.core.get_orbits.prepare_atoms(atom_list)[source]
hiphive.core.get_orbits.prepare_clusters(cluster_list)[source]
hiphive.core.get_orbits.prepare_permutations(permutations)[source]
hiphive.core.get_orbits.prepare_rotations(rotation_matrices)[source]
hiphive.core.get_orbits.prepare_translations(translation_vectors)[source]

## orbit¶

Contains the Orbit class which hold onformation about equivalent clusters.

class hiphive.core.orbit.Orbit[source]

This class serves as a container for storing data pertaining to an orbit.

orientation_families

orientation families of the orbit

Type: list of OrientationFamily objs
eigensymmetries

each eigensymmetry corresponds to a pair where the first index is the symmetry and the second is the permutation

Type: list of tuples
eigentensors

decomposition of the force constant into symmetry elements

Type: list(numpy.ndarray)
prototype_index

index of cluster that serves as prototype for this orbit

In the code the first symmetry is always the identity so the first orientation family should always correspond to the prototype

Type: int
static read(f)[source]

Parameters: f (string or file object) – name of input file (string) or stream to load from (file object)
write(f)[source]

Write a Orbit instance to a file.

Parameters: f (str or file object) – name of input file (str) or stream to write to (file object)
hiphive.core.orbit.get_geometrical_radius(positions)[source]

Compute the geometrical size of a 3-dimensional point cloud. The geometrical size is defined as the average distance to the geometric center.

Parameters: positions (list of 3-dimensional vectors) – positions of points in cloud geometric size of point cloud float
hiphive.core.orbit.get_maximum_distance(positions)[source]

Compute the maximum distance between any two points in a 3-dimensional point cloud. This is equivalent to the “size” criterion used when imposing a certain (pair) cutoff criterion during construction of a set of clusters.

Parameters: positions (list of 3-dimensional vectors) – positions of points in cloud maximum distance betwee any two points float

## orientation_family¶

This module contains the OrientationFamily class, which acts as a container for information concernign a set of clusters of equal orientation in space.

class hiphive.core.orientation_family.OrientationFamily(symmetry_index=None)[source]

A container for storing information for a “family of orientations”.

An orbit contains many clusters. Some of the clusters can be tranlsated onto each other and other must first be rotated. A set of clusters in the orbit which can all be translated onto each other are oriented in the same way and belongs to the same orientation family. The family is haracterized by the symmetry (rotation) which relates it to the prototype structure of the orbit.

Since the clusters are generally stored sorted the permutation information must also be stored.

Parameters: symmetry_index (int) – The index of the symmetry corresponding to spglibs symmetry
symmetry_index

The index of the symmetry corresponding to spglibs symmetry

Type: int
cluster_indices

The indices of the clusters belonging to this family

Type: list of ints
permutation_indices

The indices of the permutation vector

Type: list of ints
static read(f)[source]

Load a OrientationFamily object from a pickle file.

Parameters: f (str or file object) – name of input file (str) or stream to load from (file object) OrientationFamily object
write(f)[source]

Write the object to file.

Parameters: f (str or file object) – name of input file (str) or stream to write to (file object)

## eigentensors¶

hiphive.core.eigentensors.assemble_new_eigentensor(eigentensors, solution)[source]
hiphive.core.eigentensors.create_eigentensors(cs)[source]
hiphive.core.eigentensors.init_ets_from_label_symmetry(cluster)[source]

This function creates eigentensor which fulfill the atom label symmetry. The only information needed is the corresponding cluster

hiphive.core.eigentensors.populate_constraint_matrix(M, ets, R, p_inv)[source]
hiphive.core.eigentensors.renormalize_to_integer(vector)[source]

## tensors¶

Module containing tensor related functions

hiphive.core.tensors.rotate_tensor(T, R, path=None)[source]

Equivalent to T_abc… = T_ijk… R_ia R_jb R_kc …

hiphive.core.tensors.rotation_to_cart_coord(R, cell)[source]

Return the rotation matrix in cart coord given a cell metric

## atoms¶

Collection of functions and classes for handling information concerning atoms and structures, including the relationship between primitive cell and supercells that are derived thereof.

class hiphive.core.atoms.Atom(site, offset)[source]

Unique representation of an atom in a lattice with a basis

Class for storing information about the position of an atom in a supercell relative to the origin of the underlying primitive cell. This class is used for handling the relationship between a primitive cell and supercells derived thereof.

Parameters: site (int) – site index offset (list(float) or numpy.ndarray) – must contain three elements, offset_x, offset_y, offset_z
offset

translational offset of the supercell site relative to the origin of the primitive cell in units of primitive lattice vectors

Type: list(int)
pos(basis, cell)[source]
site

index of corresponding site in the primitive basis

Type: int
spos(basis)[source]
static spos_to_atom(spos, basis, tol=None)[source]
class hiphive.core.atoms.Atoms(symbols=None, positions=None, numbers=None, tags=None, momenta=None, masses=None, magmoms=None, charges=None, scaled_positions=None, cell=None, pbc=None, celldisp=None, constraint=None, calculator=None, info=None)[source]

Minimally augmented version of the ASE Atoms class suitable for handling primitive cell information.

basis

scaled coordinates of the sites in the primitive basis

Type: numpy.ndarray
static read(f)[source]

Load an hiPhive Atoms object from file.

Parameters: f (str or file object) – name of input file (str) or stream to load from (file object) hiPhive Atoms object
write(f)[source]

Writes the object to file.

Note: Only the cell, basis and numbers are stored!

Parameters: f (str or file object) – name of input file (str) or stream to write to (file object)
hiphive.core.atoms.atom_to_spos(atom, basis)[source]

Helper function for obtaining the position of a supercell atom in scaled coordinates.

Parameters: atom (hiPhive.Atom) – supercell atom basis (list(list(float)) or numpy.ndarray) – positions of sites in the primitive basis scaled coordinates of an atom in a supercell numpy.ndarray
hiphive.core.atoms.spos_to_atom(spos, basis, tol=0.0001)[source]

Helper function for transforming a supercell position to the primitive basis.

Parameters: spos (list(list(float)) or numpy.ndarray) – scaled coordinates of an atom in a supercell basis (list(list(float)) or numpy.ndarray) – positions of sites in the primitive basis tol (float) – a general tolerance supercell atom hiphive.Atom

## relate_structures¶

hiphive.core.relate_structures.align_supercell(supercell, prim, symprec=None)[source]

Rotate and translate a supercell configuration such that it is aligned with the target primitive cell.

Parameters: sc (ase.Atoms) – supercell configuration prim (ase.Atoms) – target primitive configuration symprec (float) – precision parameter forwarded to spglib aligned supercell configuration as well as rotation matrix (3x3 array) and translation vector (3x1 array) that relate the input to the aligned supercell configuration. tuple(ase.Atoms, numpy.ndarray, numpy.ndarray)
hiphive.core.relate_structures.are_nonpaired_configurations_equal(atoms1, atoms2)[source]

Checks whether two configurations are identical. To be considered equal the structures must have the same cell metric, elemental occupation, scaled positions (modulo one), and periodic boundary conditions.

Unlike the __eq__ operator of ase.Atoms the order of the atoms does not matter.

Parameters: atoms1 (ase.Atoms) – atoms2 (ase.Atoms) – bool – True if atoms are equal, False otherwise TODO (tol)
hiphive.core.relate_structures.get_primitive_cell(atoms, to_primitive=True, no_idealize=True, symprec=1e-05)[source]

Gets primitive cell from spglib.

Parameters: atoms (ase.Atoms) – atomic structure to_primitive (bool) – passed to spglib no_idealize (bool) – passed to spglib
hiphive.core.relate_structures.is_rotation(R, cell_metric=None)[source]

Checks if rotation matrix is orthonormal

A cell metric can be passed of the rotation matrix is in scaled coordinates

Parameters: R (numpy.ndarray) – rotation matrix (3x3 array) cell_metric (numpy.ndarray) – cell metric if the rotation is in scaled coordinates
hiphive.core.relate_structures.relate_structures(reference, target, symprec=1e-05)[source]

Finds rotation and translation operations that align two structures with periodic boundary conditions.

The rotation and translation in Cartesian coordinates will map the reference structure onto the target

Aligning reference with target can be achieved via the transformations >>> R, T = relate_structures(atoms_ref, atoms_target) >>> atoms_ref_rotated = rotate_atoms(atoms, R) >>> atoms_ref_rotated.translate(T) >>> atoms_ref_rotated.wrap() >>> atoms_ref_rotated == atoms_target

Parameters: reference (ase.Atoms) – The reference structure to be mapped target (ase.Atoms) – The target structure R (numpy.ndarray) – rotation matrix in Cartesian coordinates (3x3 array) T (numpy.ndarray) – translation vector in Cartesian coordinates
hiphive.core.relate_structures.rotate_atoms(atoms, rotation)[source]

Rotates the cell and positions of Atoms and returns a copy

Parameters: atoms (ase.Atoms) – atomic structure rotation (numpy.ndarray) – rotation matrix (3x3 array)

## utilities¶

The utilities module contains various support functions and classes.

class hiphive.core.utilities.Progress(tot=None, mode='frac', estimate_remaining=True)[source]

Progress bar like functionality.

close()[source]
tick()[source]

## core_config¶

hiphive.core.core_config.constraint_vectors_compress_mode = 'symbolic'

True, False

hiphive.core.core_config.constraint_vectors_simplify_before_compress = True

‘symbolic’, ‘numeric’, None

hiphive.core.core_config.constraint_vectors_simplify_before_solve = True

‘symbolic’, ‘numeric’

class hiphive.core.core_config.core_config[source]
class eigensymmetries[source]
crystal_symmetries = True
class iterative[source]
method = 'symbolic'
simplify = True
simplify_tolerance = None
zero_tolerance = 1e-12
method = 'iterative'
rotation_integer_tolerance = 1e-12
hiphive.core.core_config.eigentensor_compress_before_solve = None

This might make the nullspace() more stable True, False

hiphive.core.core_config.eigentensor_compress_mode = None

If this is True, before every symbolic compression the values will be simplified by sympy, potentially turning them into exact rational or irrational numbers. This can be useful for systems with non-integer rotation matrices in cartesian coordinates e.g. hcp. The main purpose is to make the rref more stable against repeating rounding errors. True, False

hiphive.core.core_config.eigentensor_simplify_before_compress = False

If non compress was used during construction but used before solving True, False

hiphive.core.core_config.eigentensor_simplify_before_last_compress = False

If the compress_mode is None the constraint matrix might be compressed right before the nullspace() solver ‘numeric’, ‘symbolic’, None

hiphive.core.core_config.eigentensor_simplify_before_solve = True

‘symbolic’, ‘numeric’

hiphive.core.core_config.eigentensor_solve_mode = 'symbolic'

‘symbolic’, ‘numeric’

hiphive.core.core_config.integer_tolerance = 1e-12

For each symmetry, the constraint matrix can be reduced to square again. This can be done either by ‘symbolic’, ‘numeric’ or not at all (None). Default is None since the matrix is often small enough to fit in memory. ‘symbolic’, ‘numeric’, None

hiphive.core.core_config.sum_rule_constraint_mode = 'symbolic'

True, False

hiphive.core.core_config.sum_rule_constraint_simplify = True

True, False