Force constant models¶
ForceConstantPotential¶
- class hiphive.ForceConstantPotential(cs, parameters, metadata=None)[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) – The cluster space the model is based upon
parameters (numpy.ndarray) – The fitted paramteres
metadata (dict) – metadata dictionary, will be pickled when object is written to file
- get_force_constants(atoms)[source]¶
Return the force constants of a compatible structure.
- Parameters
atoms (ase.Atoms) – input structure
- Returns
force constants
- Return type
- property metadata¶
metadata associated with force constant potential
- Type
dict
- property orbit_data: List[Dict[str, Any]]¶
list of dictionaries containing detailed information for each orbit, e.g. cluster radius and force constant
- Return type
List
[Dict
[str
,Any
]]
- print_tables()[source]¶
Prints information concerning the underlying cluster space to stdout,including, e.g., the number of cluster, orbits, and parameters by order and number of bodies.
- static read(filename)[source]¶
Reads a ForceConstantPotentialfrom file.
- Parameters
filename (str) – name of input file to load ForceConstantPotential from
- Returns
the original object as stored in the file
- Return type
- property symprec¶
ForceConstantCalculator¶
- class hiphive.calculators.ForceConstantCalculator(fcs, max_disp=3.0)[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
fcs (ForceConstants) – the force constants instance must include the atomic configuration
max_disp (float) – maximum allowed displacement before calculator raises ValueError
- calculate(atoms=None, properties=['energy'], system_changes=['positions', 'numbers', 'cell', 'pbc', 'initial_charges', 'initial_magmoms'])[source]¶
Do the calculation.
- properties: list of str
List of what needs to be calculated. Can be any combination of ‘energy’, ‘forces’, ‘stress’, ‘dipole’, ‘charges’, ‘magmom’ and ‘magmoms’.
- system_changes: list of str
List of what has changed since last calculation. Can be any combination of these six: ‘positions’, ‘numbers’, ‘cell’, ‘pbc’, ‘initial_charges’ and ‘initial_magmoms’.
Subclasses need to implement this, but can ignore properties and system_changes if they want. Calculated properties should be inserted into results dictionary like shown in this dummy example:
self.results = {'energy': 0.0, 'forces': np.zeros((len(atoms), 3)), 'stress': np.zeros(6), 'dipole': np.zeros(3), 'charges': np.zeros(len(atoms)), 'magmom': 0.0, 'magmoms': np.zeros(len(atoms))}
The subclass implementation should first call this implementation to set the atoms attribute and create any missing directories.
- Return type
None
- compute_energy_and_forces()[source]¶
Computes energy and forces.
- Returns
energy and forces
- Return type
float, list(list(float))
- implemented_properties: List[str] = ['energy', 'forces']¶
Properties calculator can handle (energy, forces, …)
ForceConstants¶
This module provides functionality for storing and handling of force constants.
- class hiphive.force_constants.ForceConstants(supercell)[source]¶
Base class for force constants
- assert_acoustic_sum_rules(order=None, tol=1e-06)[source]¶
Asserts that force constants obey acoustic sum rules.
- Parameters
order (
Optional
[int
]) – specifies which order to check, if None all are checkedtol (
float
) – numeric tolerance for checking sum rules
- Raises
AssertionError – if acoustic sum rules are violated
- property clusters: list¶
sorted list of clusters
- Return type
list
- compute_gamma_frequencies()[source]¶
Returns the Gamma frequencies in THz using the second-order force constants.
- Return type
- classmethod from_arrays(supercell, fc2_array=None, fc3_array=None)[source]¶
Constructs FCs from numpy arrays.
One or both of fc2_array and fc3_array must not be None
- classmethod from_dense_dict(fc_dict, supercell)[source]¶
All permutations of clusters that are not zero must be listed, if label symmetries are fullfilled will return a SortedForceConstants
- Parameters
fc_dict (
dict
) – keys corresponding to clusters and values to the force constantssupercell (
Atoms
) – atomic configuration
- classmethod from_sparse_dict(fc_dict, supercell)[source]¶
Assumes label symmetries, meaning only one cluster for each permuation should be included
- Parameters
fc_dict (
dict
) – keys corresponding to clusters and values to the force constantssupercell (
Atoms
) – atomic configuration
- get_fc_array(order, format='phonopy')[source]¶
Returns force constants in array format for specified order.
- Parameters
order (
int
) – force constants for this order will be returnedformat (
str
) – specify which format (shape) the NumPy array should have, possible values are phonopy and ase
- Return type
- Returns
NumPy array with shape (N,)*order + (3,)*order where N is
the number of atoms
- get_fc_dict(order=None)[source]¶
Returns force constant dictionary for one specific order.
The returned dict may be sparse or may be dense depending on the underlying force constants.
- Parameters
order (
Optional
[int
]) – force constants returned for this order- Return type
dict
- Returns
dictionary with keys corresponding to clusters and values to
respective force constant
- property n_atoms: int¶
number of atoms
- Return type
int
- print_force_constant(cluster)[source]¶
Prints force constants for a cluster in a nice format.
- Parameters
cluster (
Tuple
[int
]) – sites belonging to the cluster- Return type
None
- classmethod read(fname)[source]¶
Reads ForceConstants from file.
- Parameters
fname (
str
) – name of file from which to read
- classmethod read_phono3py(supercell, fname)[source]¶
Reads force constants from a phono3py calculation.
- Parameters
supercell (
Atoms
) – supercell structure (SPOSCAR)fname (
str
) – name of third-order force constant file
- classmethod read_phonopy(supercell, fname, format=None)[source]¶
Reads force constants from a phonopy calculation.
- Parameters
supercell (
Atoms
) – supercell structure (SPOSCAR)fname (
str
) – name of second-order force constant fileformat (
Optional
[str
]) – format for second-order force constants; possible values: “text”, “hdf5”
- classmethod read_shengBTE(supercell, fname, prim, symprec=1e-05)[source]¶
Reads third order force constants from a shengBTE calculation.
shengBTE force constants will be mapped onto a supercell.
- property supercell: ase.atoms.Atoms¶
supercell associated with force constants
- Return type
- write(fname)[source]¶
Writes entire ForceConstants object to file.
- Parameters
fname (
str
) – name of file to which to write- Return type
None
- write_to_phono3py(fname)[source]¶
Writes force constants in phono3py format.
- Parameters
fname (
str
) – name of file to which to write third-order force constant- Return type
None
- write_to_phonopy(fname, format=None)[source]¶
Writes force constants in phonopy format.
- Parameters
fname (
str
) – name of file to which to write second-order force constantformat (
Optional
[str
]) –- format for second-order force constants;
possible values: “text”, “hdf5”
- Return type
None
- write_to_shengBTE(fname, prim, **kwargs)[source]¶
Writes third order force constants in shengBTE format.
- Parameters
fname (
str
) – name of file to which to write third-order force constantprim (
Atoms
) – primitive configuration (must be equivalent to structure used in the shengBTE calculation)
- Return type
None
- class hiphive.force_constants.RawForceConstants(fc_dict, supercell)[source]¶
Force constants without label symmetries.
- Parameters
fc_dict (dict) – keys corresponding to clusters and values to the force constants, should contain all clusters with nonzero force constants
supercell (ase.Atoms) –
- property orders: List[int]¶
orders for which force constants exist
- Return type
List
[int
]
- class hiphive.force_constants.SortedForceConstants(fc_dict, supercell)[source]¶
Force constants with label symmetries.
- Parameters
fc_dict (dict) – keys corresponding to clusters and values to the force constants, should only contain sorted clusters
supercell (ase.Atoms) –
- property orders: List[int]¶
orders for which force constants exist
- Return type
List
[int
]
- write_to_GPUMD(fname_fc, fname_clusters, order, tol=1e-10)[source]¶
Writes force constants of the specified order in GPUMD format.
- Parameters
fname_fc (str) – name of file which contains the lookup force constants
fname_clusters (str) – name of file which contains the clusters and the fc lookup index
order (int) – force constants for this order will be written to file
tol (float) – if the norm of a force constant is less than tol then it is not written. if two force-constants are within tol; they are considered equal.
- hiphive.force_constants.array_to_dense_dict(fc_array, fc_tol=1e-10)[source]¶
Constructs a dense dict from an fc array in phonopy format.
Force constants with norm smaller than fc_tol will be considered zero and therefore not included in the fc_dict.
- Parameters
fc_array (
ndarray
) – force constant array in phonopy formatfc_tol (
float
) – tolerance for considering force constants zero or not
- Return type
dict
- hiphive.force_constants.check_label_symmetries(fc_dict)[source]¶
Checks label symmetries for dense fc dict.
Todo
tol, which one to use etc
- Parameters
fc_dict (
dict
) – keys corresponding to clusters and values to the force constants- Return type
bool
- hiphive.force_constants.dense_dict_to_sparse_dict(fc_dict)[source]¶
Converts dense dict to sparse dict.
This does not check if label symmetry is True, but rather will just keep the sorted clusters and their force constants.
- Parameters
fc_dict (
dict
) – keys corresponding to clusters and values to the force constants- Return type
dict
- hiphive.force_constants.symbolize_force_constant(fc, tol=1e-10)[source]¶
Carries out a symbolic symmetrization of a force constant tensor.
- Parameters
fc (
ndarray
) – force constant tensortol (
float
) – tolerance used to decide whether two elements are identical
- Return type
symbolic representation of force constant matrix
Constraints¶
- hiphive.enforce_rotational_sum_rules(cs, parameters, sum_rules=None, alpha=1e-06, **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 spaceparameters (
ndarray
) – parameters to be constrainedsum_rules (
Optional
[List
[str
]]) – type of sum rules to enforce; possible values: ‘Huang’, ‘Born-Huang’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]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', 'Born-Huang']) fcp = ForceConstantPotential(cs, new_params)