Core components¶
The lowlevel 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¶
get_clusters¶

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 object) – 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
Returns: a list of clusters where each entry is a tuple of indices, which refer to the atoms in the input supercell
Return type: list of tuples
get_orbits¶

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
Returns: orbits associated with the list of input clusters
Return type: list of Orbits objs
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
¶ list of OrientationFamily objs – The orientation families of the orbit

eigensymmetries
¶ list of tuples – Each eigensymmetry correspond to a pair where the first index is the symmetry and the second is the permutation

eigentensors
¶ list of NumPy arrays – The decomposition of the force constant into symmetry elements

prototype_index
¶ int – 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


hiphive.core.orbit.
get_geometrical_radius
(positions)[source]¶ Compute the geometrical size of a 3dimensional point cloud. The geometrical size is defined as the average distance to the geometric center.
Parameters: positions (list of 3dimensional vectors) – positions of points in cloud Returns: geometric size of point cloud Return type: float

hiphive.core.orbit.
get_maximum_distance
(positions)[source]¶ Compute the maximum distance between any two points in a 3dimensional 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 3dimensional vectors) – positions of points in cloud Returns: maximum distance betwee any two points Return type: float
orientation_family¶
The orientation_family
module contains the OrientationFamily class, which
acts like a struct that contains information about a set of equal 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
¶ int – The index of the symmetry corresponding to spglibs symmetry

cluster_indices
¶ list of ints – The indices of the clusters belonging to this family

permutation_indices
¶ list of ints – The indices of the permutation vector

eigentensors¶

hiphive.core.eigentensors.
create_einsum_path
(order)[source]¶ Ensum can be optimized if the shapes and contraction order of the inputs are known beforehand.
tensors¶
Module containing tensor related functions
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
(*args)[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. Initialize self
Parameters: site/offset – An Atom object can be initialized by providing either
 four elements, which are interpreted as site, offset_x, offset_y, offset_z
 a list with four elements, which is interpreted as [site, offset_x, offset_y, offset_z], or
 a list with two elements, which is interpreted as [site, [offset_x, offset_y, offset_z]].
where all of the elements are integers. Here, site indicates the index of a site in the primitive basis and offset describes the translation of the atom position in the supercell relative to the origin in units of the primitive cell vectors.
Examples
The three following commands yield identical results
>>> atom = Atom(1, 0, 0, 3) >>> atom = Atom(1, [0, 0, 3]) >>> atom = Atom([1, 0, 0, 3])

offset
¶ list of ints – translational offset of the supercell site relative to the origin of the primitive cell in units of primitive lattice vectors

site
¶ int – index of corresponding site in the primitive basis

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.
Saves and loads by pickle.

basis
¶ NumPy array – scaled coordinates of the sites in the primitive basis


hiphive.core.atoms.
align_super_cell
(sc, prim, symprec=None)[source]¶ Rotate and translate a supercell configuration such that it is aligned with the target primitive cell.
Parameters:  sc (ASE Atoms object) – supercell configuration
 prim (ASE Atoms object) – target primitive configuration
 symprec (float) – precision parameter forwarded to spglib
Returns: The method returns the aligned supercell configuration as well as the rotation matrix and the translation vector that related the input to the aligned supercell configuration.
Return type: tuple of ASE Atoms object, NumPy (3,3) array, 3dimensional vector

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 object) – supercell atom
 basis (list) – positions of sites in the primitive basis
Returns: array – scaled coordinates of an atom in a supercell
Return type: NumPy array

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) – scaled coordinates of an atom in a supercell
 basis (list) – positions of sites in the primitive basis
 tol (float) – a general tolerance
Returns: supercell atom
Return type: hiPhive Atom object
relate_structures¶

hiphive.core.relate_structures.
atoms_equal
(atoms_1, atoms_2)[source]¶ Compares two configurations with periodic boundary conditions.
The atoms should have the same * cell * elements * scaled positions (mod 1) * pbc
Compared to Atoms.__eq__ the order of the atoms does not matter

hiphive.core.relate_structures.
get_primitive_cell
(atoms, to_primitive=True, no_idealize=True)[source]¶ Get primitive cell from spglib
Parameters:  atoms (ASE Atoms object) –
 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 3x3 matrix) – The rotation matrix
 cell_metric (Numpy 3x3 matrix) – Optinal cell metric if the rotation is in scaled coordinates

hiphive.core.relate_structures.
relate_structures
(reference, target)[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
Parameters:  reference (ASE Atoms) – The reference structure to be mapped
 target (ASE Atoms) – The target structure
Returns:  R (NumPy (3, 3) array) – The rotation matrix in Cartesian coordinates
 T (NumPy (3) array) – The translation vector in Cartesian coordinates
utilities¶
The utilities
module contains various support functions and classes.
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’

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 noninteger 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
= 1e12¶ 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