Structures¶
StructureContainer¶

class
hiphive.
StructureContainer
(cs, fit_structure_list=None)[source]¶ This class serves as a container for structures as well as associated fit properties and fit matrices.
 Parameters
cs (ClusterSpace) – cluster space that is the basis for the container
fit_structure_list (list(FitStructure)) – structures to be added to the container

add_structure
(atoms, **meta_data)[source]¶ Add a structure to the container.
Note that custom information about the atoms object may not be stored inside, for example an ASE
SinglePointCalculator
will not be kept. Parameters
atoms (ase.Atoms) – the structure to be added; the Atoms object must contain supplementary peratom arrays with displacements and forces
meta_data (dict) – dict with meta_data about the atoms

cluster_space
¶ copy of the cluster space the structure container is based on
 Type

data_shape
¶ tuple of integers representing the shape of the fit data matrix
 Type
tuple

get_fit_data
(structures=None)[source]¶ Return fit data for structures. The fit matrices and target forces for the structures are stacked into NumPy arrays.
 Parameters
structures (list, tuple) – list of integers corresponding to structure indices. Defaults to None and in that case returns all fit data available.
 Returns
stacked fit matrices, stacked target forces for the structures
 Return type

static
read
(fileobj, read_structures=True)[source]¶ Restore a StructureContainer object from file.
 Parameters
f (str or file object) – name of input file (str) or stream to load from (file object)
read_structures (bool) – if True the structures will be read; if False only the cluster space will be read
FitStructure¶

class
hiphive.structure_container.
FitStructure
(atoms, fit_matrix, **meta_data)[source]¶ This class holds a structure with displacements and forces as well as the fit matrix.
 Parameters
atoms (ase.Atoms) – supercell structure
fit_matrix (numpy.ndarray) – fit matrix, N, M array with N = 3 * len(atoms)
meta_data (dict) – any meta data that needs to be stored in the FitStructure

displacements
¶ atomic displacements
 Type

fit_matrix
¶ the fit matrix
 Type

forces
¶ forces
 Type

static
read
(fileobj, read_fit_matrix=True)[source]¶ Read a OrientationFamily instance from a file.
 Parameters
fileobj (str or file object) – name of input file (str) or stream to read from (file object)
read_fit_matrix (bool) – whether or not to read the fit_matrix
 Returns
 Return type
FitStructure instance
Structure generation¶
This module enables the generation of structures with displacements that can be used to generate reference forces.

hiphive.structure_generation.
generate_mc_rattled_structures
(atoms, n_configs, rattle_std, d_min, seed=42, **kwargs)[source] Returns list of Monte Carlo rattled configurations.
Rattling atom i is carried out as a Monte Carlo move that is accepted with a probability determined from the minimum interatomic distance \(d_{ij}\). If :math`min(d_{ij})` is smaller than \(d_{min}\) the move is only accepted with a low probability.
This process is repeated for each atom a number of times meaning the magnitude of the final displacements is not directly connected to rattle_std.
Warning
Repeatedly calling this function without providing different seeds will yield identical or correlated results. To avoid this behavior it is recommended to specify a different seed for each call to this function.
Notes
The procedure implemented here might not generate a symmetric distribution for the displacements kwargs will be forwarded to mc_rattle (see user guide for a detailed explanation)
 Parameters
atoms (ase.Atoms) – prototype structure
n_structures (int) – number of structures to generate
rattle_std (float) – rattle amplitude (standard deviation in normal distribution); note this value is not directly connected to the final average displacement for the structures
d_min (float) – interatomic distance used for computing the probability for each rattle move
seed (int) – seed for setting up NumPy random state from which random numbers are generated
 Returns
generated structures
 Return type
list of ase.Atoms

hiphive.structure_generation.
generate_rattled_structures
(atoms, n_structures, rattle_std, seed=42)[source] Returns list of rattled configurations.
Displacements are drawn from normal distributions for each Cartesian directions for each atom independently.
Warning
Repeatedly calling this function without providing different seeds will yield identical or correlated results. To avoid this behavior it is recommended to specify a different seed for each call to this function.
 Parameters
atoms (ase.Atoms) – prototype structure
n_structures (int) – number of structures to generate
rattle_std (float) – rattle amplitude (standard deviation of the normal distribution)
seed (int) – seed for setting up NumPy random state from which random numbers are generated
 Returns
generated structures
 Return type
list of ase.Atoms

hiphive.structure_generation.
generate_phonon_rattled_structures
(atoms, fc2, n_structures, temperature)[source] Returns list of phononrattled configurations.
Configurations are generated by superimposing harmonic phonon eigenmodes with random amplitudes and phase factors consistent with a certain temperature.
Let \(\boldsymbol{X}_{ai}\) be the phonon modes indexed by atom \(a\) and mode \(i\), \(\omega_i\) the phonon frequencies, and let \(0 < Q_i \leq 1\) and \(0 \leq U_i < 1\) be uniformly random numbers. Then
\[\boldsymbol{R}_a = \boldsymbol{R}^0_a + \left<\frac{k_B T}{m_a} \right>^{1/2} \sum_i \frac{1}{\omega_i} \boldsymbol{X}_{ai} \sqrt{2 \ln Q_i} \cos(\pi \omega_i U_i)\]See: West and Estreicher PRL 96, 115504 (2006)
 Parameters
atoms (ase.Atoms) – prototype structure
fc2 (numpy.ndarray) – second order force constant matrix, with shape (3N, 3N) or (N, N, 3, 3). The conversion will be done internally if.
n_structures (int) – number of structures to generate
temperature (float) – temperature in Kelvin
 Returns
generated structures
 Return type
list(ase.Atoms)