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 aClusterSpace
object for a bodycenteredcubic (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

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)

print_tables
()[source]¶ Prints table data, i.e. information as a function of order and nbody 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 tarfiles. 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 filelike 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.

class
hiphive.cutoffs.
CutoffMaximumBody
(cutoff_list, max_nbody)[source]¶ Specify cutofflist plus maximum body
Usefull when creating e.g. 6th order expansions but with only 3body 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, nbody refers to number of atoms in a cluster. For example the cluster (0011) is a twobody cluster of fourth order and the cluster (123) is a threebody 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

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_order
¶ maximum order
 Type
int

nbodies
¶ allowed bodies
 Type
list(int)

orders
¶ allowed orders
 Type
list(int)

read
()[source]¶ Reads an instance from file.
 Parameters
fileobj (filelike object) – input file to read from

class
hiphive.cutoffs.
MaxTripletDistance
(max_dist)[source]¶ Rejects large threebody 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 threebody 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