# 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, user_tag=None, **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 per-atom arrays with displacements and forces user_tag (str) – custom user tag to identify structure compute_fit_matrix (bool) – if True the fit matrix of the structure is computed meta_data (dict) – dict with meta_data about the atoms
cluster_space

ClusterSpace – copy of the cluster space the structure container is based on

data_shape

tuple – tuple of integers representing the shape of the fit data matrix

delete_all_structures()[source]

Remove all current structures in StructureContainer.

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. stacked fit matrices, stacked target forces for the structures numpy.ndarray, numpy.ndarray
get_structure_indices(user_tag)[source]

Get structure indices via user tag.

Parameters: user_tag (str, list) – user tag or list of user tags used for selecting structures list of structures with specified user tag list
print_cluster_space(include_orbits=False)[source]

Print information concerning the cluster space this structure container is based on.

Parameters: include_orbits (bool) – if True also print the list of orbits associated with the cluster space
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
write(f)[source]

Write a StructureContainer instance to a file.

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

## FitStructure¶

class hiphive.structure_container.FitStructure(atoms, fit_matrix, user_tag=None, **meta_data)[source]

This class holds a structure with displacements and forces as well as the fit matrix.

Parameters: atoms (ase.Atoms) – supercell structure user_tag (str) – custom user tag 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
atoms

ase.Atoms – supercell structure

displacements

numpy.ndarray – atomic displacements

fit_matrix

numpy.ndarray – the fit matrix

forces

numpy.ndarray – forces

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 FitStructure instance
user_tag

str – custom user tag

write(fileobj)[source]

Write the instance to file.

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

## 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 :mathmin(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 generated structures 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 generated structures list of ase.Atoms
hiphive.structure_generation.generate_phonon_rattled_structures(atoms, fc2, n_structures, temperature)[source]

Returns list of phonon-rattled configurations.

Configurations are generated by superimposing harmonic phonon eigenmodes with amplitudes corresponding to a certain temperatures and randomly drawn phase factors.

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)$
Parameters: atoms (ase.Atoms) – prototype structure fc2 (numpy.ndarray) – second order force constant matrix, with shape (3N, 3N) n_structures (int) – number of structures to generate temperature (float) – temperature (K) generated structures list of ase.Atoms