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.
config¶

class
hiphive.core.config.
config
[source]

hiphive.core.config.
constraint_vectors_compress_mode
= 'symbolic' True, False

hiphive.core.config.
constraint_vectors_simplify_before_compress
= True ‘symbolic’, ‘numeric’, None

hiphive.core.config.
constraint_vectors_simplify_before_solve
= True ‘symbolic’, ‘numeric’

hiphive.core.config.
eigentensor_compress_before_solve
= None This might make the nullspace() more stable True, False

hiphive.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.config.
eigentensor_simplify_before_compress
= False If non compress was used during construction but used before solving True, False

hiphive.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.config.
eigentensor_simplify_before_solve
= True ‘symbolic’, ‘numeric’

hiphive.core.config.
eigentensor_solve_mode
= 'symbolic' ‘symbolic’, ‘numeric’

hiphive.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.config.
sum_rule_constraint_mode
= 'symbolic' True, False

hiphive.core.config.
sum_rule_constraint_simplify
= True True, False
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.
clusters¶

hiphive.core.clusters.
create_neighbor_matrices
(atoms, cutoff)[source]

hiphive.core.clusters.
extend_cluster
(cluster, order)[source]

hiphive.core.clusters.
generate_geometrical_clusters
(atoms, n_prim, cutoff, order)[source]

hiphive.core.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
 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(tuple(int))
orbits¶
Contains the Orbit class which hold onformation about equivalent clusters.

class
hiphive.core.orbits.
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)

property
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] Load a ClusterSpace from file
 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)


class
hiphive.core.orbits.
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)
 Returns
 Return type
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)

hiphive.core.orbits.
generate_translated_clusters
(cluster, extended_atoms)[source]

hiphive.core.orbits.
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.orbits.
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

hiphive.core.orbits.
get_orbits
(cluster_list, atom_list, rotation_matrices, translation_vectors, permutations, prim, symprec)[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

hiphive.core.orbits.
get_permutation_map
(atoms, rotations, translations, basis, symprec)[source]

hiphive.core.orbits.
populate_orbit
(orbit, permutations, clusters, cluster, permutation_map, extended_atoms, cluster_is_found)[source]

hiphive.core.orbits.
prepare_atoms
(atom_list)[source]

hiphive.core.orbits.
prepare_clusters
(cluster_list)[source]

hiphive.core.orbits.
prepare_permutations
(permutations)[source]

hiphive.core.orbits.
prepare_rotations
(rotation_matrices)[source]

hiphive.core.orbits.
prepare_translations
(translation_vectors)[source]
rotational_constraints¶
Functionality for enforcing rotational sum rules

hiphive.core.rotational_constraints.
enforce_rotational_sum_rules
(cs, parameters, sum_rules=None, alpha=1e06, **ridge_kwargs)[source] Enforces rotational sum rules by projecting parameters.
Note
The interface to this function might change in future releases.
 Parameters
cs (ClusterSpace) – the underlying cluster space
parameters (numpy.ndarray) – parameters to be constrained
sum_rules (list(str)) – type of sum rules to enforce; possible values: ‘Huang’, ‘BornHuang’
alpha (float) – hyperparameter to the ridge regression algorithm; keyword argument passed to the optimizer; larger values specify stronger regularization, i.e. less correction but higher stability [default: 1e6]
ridge_kwargs (dict) – kwargs to be passed to sklearn Ridge
 Returns
constrained parameters
 Return type
Examples
The rotational sum rules can be enforced to the parameters before constructing a force constant potential as illustrated by the following snippet:
cs = ClusterSpace(reference_structure, cutoffs) sc = StructureContainer(cs) # add structures to structure container opt = Optimizer(sc.get_fit_data()) opt.train() new_params = enforce_rotational_sum_rules(cs, opt.parameters, sum_rules=['Huang', 'BornHuang']) fcp = ForceConstantPotential(cs, new_params)

hiphive.core.rotational_constraints.
get_rotational_constraint_matrix
(cs, sum_rules=None)[source]
translational_constraints¶
Functionality for enforcing translational sum rules

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

hiphive.core.translational_constraints.
get_translational_constraint_matrix
(cs)[source]
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

property
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]

property
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, velocities=None)[source] Minimally augmented version of the ASE Atoms class suitable for handling primitive cell information.
Saves and loads by pickle.

property
basis
scaled coordinates of the sites in the primitive basis
 Type

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)
 Returns
 Return type
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)

property

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
 Returns
scaled coordinates of an atom in a supercell
 Return type

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
 Returns
supercell atom
 Return type
hiphive.Atom
structures¶

class
hiphive.core.structures.
Atom
(*args, **kwargs)[source] This class represents a crystal atom in a given structure

property
number

property
pos

property

class
hiphive.core.structures.
BaseAtom
(site, offset)[source] This class represents an atom placed in an infinite crustal

astype
(dtype)[source] Useful arguments: list, tuple, np.int64

property
offset

property
site


class
hiphive.core.structures.
Structure
(atoms, symprec=1e06)[source] This class essentially wraps the ase.Atoms class but is a bit more carefull about pbc and scaled coordinates. It also returns hiphive.Atom objects instead

atom_from_pos
(pos, symprec=None)[source]

property
cell

property
spos


class
hiphive.core.structures.
Supercell
(supercell, prim, symprec)[source] This class tries to represent atoms in a supercell as positioned on the primitve lattice

index
(site, offset)[source]

wrap_atom
(atom)[source]


class
hiphive.core.structures.
SupercellAtom
(*args, **kwargs)[source] Represents an atom in a supercell but site and offset given by an underlying primitve cell

property
index

property

hiphive.core.structures.
pos_to_site_offset
(pos, cell, basis_spos, symprec)[source] helper to map pos > spos > site/offset

hiphive.core.structures.
pos_to_spos
(pos, cell)[source] Inverse of sps_to_pos

hiphive.core.structures.
site_offset_to_pos
(site, offset, cell, basis_spos)[source] helper to map site/offset > spos > pos

hiphive.core.structures.
site_offset_to_spos
(site, offset, basis_spos)[source] Returns the scaled position of an atom at specified site and offset relative to the basis in scaled coordinates

hiphive.core.structures.
spos_to_pos
(spos, cell)[source] Returns the Cartesian coordinate given the scaled coordinate and cell metric (cell vectors as rows)

hiphive.core.structures.
spos_to_site_offset
(spos, basis_spos, symprec)[source] Returns the site and offset of the atom at the specified scaled coordinate given the scaled positions of the basis atoms
structure_alignment¶

hiphive.core.structure_alignment.
align_supercell
(supercell, prim, symprec=None)[source] Rotate and translate a supercell configuration such that it is aligned with the target primitive cell.
 Parameters
 Returns
aligned supercell configuration as well as rotation matrix (3x3 array) and translation vector (3x1 array) that relate the input to the aligned supercell configuration.
 Return type
tuple(ase.Atoms, numpy.ndarray, numpy.ndarray)

hiphive.core.structure_alignment.
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 ofase.Atoms
the order of the atoms does not matter.

hiphive.core.structure_alignment.
get_primitive_cell
(atoms, to_primitive=True, no_idealize=True, symprec=1e05)[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.structure_alignment.
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.structure_alignment.
relate_structures
(reference, target, symprec=1e05)[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_ref, R) atoms_ref_rotated.translate(T) atoms_ref_rotated.wrap() atoms_ref_rotated == atoms_target

hiphive.core.structure_alignment.
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)
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.
rotate_tensor_precalc
(T, R)[source]

hiphive.core.tensors.
rotation_tensor_as_matrix
(R, order)[source]

hiphive.core.tensors.
rotation_to_cart_coord
(R, cell)[source] Return the rotation matrix in cart coord given a cell metric