# Force constant models¶

## ForceConstantPotential¶

class hiphive.ForceConstantPotential(cs, parameters)[source]

A finalized force constant model. Can produce force constants for any structure compatible with the structure for which the model was set up.

Parameters: cs (ClusterSpace object) – The cluster space the model is based upon parameters (array) – The fitted paramteres
get_force_constants(atoms)[source]

Return the force constants of a compatible structure.

Parameters: atoms (ASE Atoms object) – input structure ForceConstants object
orbit_data

list – list of dictionaries containing detailed information for each orbit, e.g. cluster radius and force constant

primitive_structure

ASE Atoms object – structure of the lattice

static read(f)[source]

Load a ForceConstantPotential object from a pickle file.

Parameters: f (str or file object) – name of input file (str) or stream to load from (file object) the original object as stored in the file ForceConstantPotential object
write(f)[source]

Write a ForceConstantPotential instance to a pickle file.

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

## ForceConstantCalculator¶

class hiphive.calculators.ForceConstantCalculator(fcs)[source]

This class provides an ASE calculator that can be used in conjunction with integrators and optimizers with the atomic simulation environment (ASE). To initialize an object of this class one must provide the ideal atomic configuration along with a compatible force constant model.

Parameters: atoms_ideal (ASE Atoms object) – ideal (reference) configuration (i.e. without displacements) fcs (ForceConstants object) – the ForceConstants object must be compatible with the ideal (reference) configuration
calculate(atoms=None, properties=['energy'], system_changes=['positions', 'numbers', 'cell', 'pbc', 'initial_charges', 'initial_magmoms'])[source]
compute_energy_and_forces()[source]

Compute energy and forces.

Returns: energy and forces float, list of 3-dimensional vectors
implemented_properties = ['energy', 'forces']

## ForceConstants¶

class hiphive.ForceConstants(fc_dict=None, cluster_groups=None, fc_list=None, atoms=None)[source]

Container class for force constants.

Either specify fc_dict or both cluster_groups and fc_list.

Parameters: fc_dict (dict) – dict which holds all force constants with clusters as keys and the respective force constant as value cluster_groups (list) – list of groups of clusters, clusters in the same group should have identical force constants. fc_list (list) – list of force constants, one force constant for each cluster group atoms (ASE Atoms object) – supercell corresponding to the fcs
_fc_dict

dict – dictionary that holds all force constants with clusters as keys and the respective force constant as value

assert_acoustic_sum_rules(order=None, tol=1e-06)[source]

Asserts that acoustic sum rules are enforced for fcs

Parameters: order (int, Optional) – specifies which order to check, if None all are checked tol (float) – numeric tolerance for checking sum rules This method raise an assertion error if sum rules are not enforced.
atoms

ASE Atoms object – supercell corresponding to force constants

clusters
get_fc_array(order)[source]

Return force constants in array format for specified order.

Parameters: order (int) – force constants for this order will be returned NumPy array with shape (N,)*order + (3,)*order where N is the number of atoms NumPy array
get_fc_dict(order=None, permutations=False)[source]

Return force constant dictionary for one specific order.

Parameters: order (int) – fcs returned for this order permutations (bool) – if True returns all permutations of cluster, else only force constants for sorted cluster dictionary with keys corresponding to clusters and values to the respective force constant dict
natoms

int – Number of atoms (maximum index in a cluster +1)

orders

list – List of the orders for which force constants exists

print_cluster(cluster: tuple)[source]

Prints ForceConstants[cluster] in a nice format.

Parameters: cluster (tuple) – tuple of ints indicating the sites belonging to the cluster
static read(f)[source]

Load a ForceConstants instance from file

Parameters: f (string or file object) – name of input file (string) or stream to load from (file object)
sparse

bool – If True the object was initialized with sparse data

write(f)[source]

Write a ForceConstants instance to a file.

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

## Constraints¶

hiphive.enforce_rotational_sum_rules(cs, parameters, sum_rules, **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 (array) – parameters to be constrained sum_rules (list of str) – type of sum rules to enforce; possible values: ‘Huang’, ‘Born-Huang’ ridge_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: 1e-6] iterations (int) – number of iterations to run the projection since each step projects the solution down to each nullspace in serial; keyword argument passed to the optimizer [default: 10] constrained parameters array

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', 'Born-Huang'])
fcp = ForceConstantPotential(cs, new_params)