principia_materia.phonon_id.chainrule_derivatives module
- class principia_materia.phonon_id.chainrule_derivatives.ChainruleDerivatives(structure, supa, order, pg='C1', use_symmetric_basis=False, tol=1e-06)
Bases:
AnalyticTensors
Compute chainrule derivatives of a measurement for a given crystal system at given FTG and order.
In bundled irreducible derivatives (BID) method, for a given measurement basis, at a given order, structure and supercell, we can obtain a series of derivatives from finite displacement computations, referred to as \(\textbf{V}_{b}^{\hat{S}_{BZ}}\), where \(\hat{S}_{BZ}\) is the supercell matrix.
These measurement basis derivatives are linear combinations of irreducible derivatives in this system,
\[\textbf{V}_{b}^{\hat{S}_{BZ}} = \hat{C}_b^{\hat{S}_{BZ}} \textbf{d}_{ir}^{\hat{S}_{BZ}}\], where \(\hat{C}_b^{\hat{S}_{BZ}}\) is the chainrule matrix, and \(\textbf{d}_{ir}^{\hat{S}_{BZ}}\) is the vector of irreducible derivatives. This chainrule matrix is what we are aiming to find in this class, such linear combinations \(\hat{C}_b^{\hat{S}_{BZ}}\) can be calculated using chain rule derivatives. With the chainrule matrix and measurement basis derivatives, we can solve for irreducible derivatives.
Additionally, in hierarchical supercell BID method, at a given supercell, the irreducible derivatives that fit in smaller supercells are already computed. Thus we can split the chainrule matrix into 2 parts: a known part and an unknown part, where the task at hand is to solve the unknown part for the irreducible derivatives.
\[\textbf{V}_{b}^{\hat{S}_{BZ}} - \hat{C}_{b,known}^{\hat{S}_{BZ}} \textbf{d}_{ir,known}^{\hat{S}_{BZ}} = \hat{C}_{b,unknown}^{\hat{S}_{BZ}} \textbf{d}_{ir,unknown}^{\hat{S}_{BZ}}\]- Parameters:
structure (CrystalFTG object or a structure file of CrystalFTG) – The crystal structure.
supa (array of int, shape(dim, dim)) – The supercell matrix.
order (int) – Order of the dynamic tensor.
pg (str or PointGroup object) – The point group.
use_symmetric_basis (bool, optional, default to False) – Whether to use the symmetric basis or the naive basis for the hidden orders of the chainrule matrix.
tol (float, optional, default to 1.0E-6) – Error tolerence.
- add_known_ID(known_ID)
Mark irreducible derivatives as know ID.
- Parameters:
known_ID (list of nested tuples) – Irreducible derivaties to be marked as known.
- property basis_names
- property basis_vectors
- compute_chainrule(displacements, hidden_order=1)
Compute chainrule matrices/tensors that converts between irreducible derivatives and the measurement basis derivatives.
For a single measurement.
\[C_Q(u_1, \cdots, u_{O_{h}}) = \frac{1}{\left(O-O_{h}\right)!} \sum_{u_{O_{h} + 1}, \cdots, u_{O}} D_{Q}^{O}[u_{O_{h} + 1}, \cdots, u_{O}] \prod_{i=O_{h} + 1}^{O} \frac{\partial u_i}{\partial v_i}\]where \(O\) is order, \(O_{h}\) is the hidden order, \(u\) is q-space displacement basis, \(v\) is the measurement bases at otrder \(O\), \(V\) is the \(u_0\) line of the chainrule matrix, and \(D_Q^{O}\) is the tensor vector of \(Q\).
- Parameters:
displacements (array of floats, shape(N, order - hidden_order, natoms, dim) or (order - hidden_order, natoms, dim)) – Measurement basis displacements, can be 1 set of measurement or multiple measurements at the same time.
hidden_order (int, optional, default to 1) – The order of derivatives from first principles calculation.
- Returns:
chainrule_tensor – The chainrule matrix in a tensor form. If the input displacements shape is (order - hidden_order, natoms, dim), return value will be in shape (n_QpointsN, norbitals) * hidden_order + (n_irreducible_derivatives, ).
- Return type:
array of complex, shape(N, ) + (n_QpointsN, norbitals) * hidden_order + (n_irreducible_derivatives, )
- decompose_displacements(displacements)
Decompose the displacements in real space into reciprocal space.
- Parameters:
displacements (array of float, shape (n, ) + self.displacement_shape) – A measurement, which consists of several displacements.
- property displacement_shape
Shape of a single displacement.
A measurement basis usually consists of several displacements.
- get_chainrule_factors(measurement, hidden_order=1)
Compute chainrule factor of a measurement.
- Parameters:
measurement (array of float, shape(order - hidden_order, supercell.natoms, dim)) – A set of displacement to displace the system.
hidden_order (int, optional, default to 1) – The order of derivatives from first principles.
- Returns:
decomp_measurement – The chainrule factors.
- Return type:
array of complex, shape(order - hidden_order, multiplicity, norbitals)
- property known_ID
Names of known irreducible derivatives.
- property nonzero_ID_index
- normalize_displacements(displacements)
Normalize a measurement in reciprocal space.
The normalization makes the reciprocal space decomposition of the displacements to 1.
- Parameters:
displacements (array of float, shape (n, ) + self.displacement_shape) – A measurement, which consists of several displacements.
- set_basis()
Compute all the reciprocal displacement basis that fit in the supercell.
- set_naive_basis()
Compute all the naive reciprocal displacement basis that fit in the supercell.
- set_symmetric_basis()
Compute all the symmetric reciprocal displacement basis that fit in the supercell.
- property unknown_ID
Names of unknown irreducible derivatives.
- principia_materia.phonon_id.chainrule_derivatives.get_ChainruleDerivatives_from_hdf5(h5file, tol=1e-06)
Load ChainruleDerivatives from HDF5 file.
- principia_materia.phonon_id.chainrule_derivatives.get_ChainruleDerivatives_hdf5_wrapper()
HDF5 data wrapper for ChainruleDerivatives class.
- principia_materia.phonon_id.chainrule_derivatives.save_ChainruleDerivatives_to_hdf5(obj, h5file='analytic_tensors.hdf5', overwrite=False)
Save ChainruleDerivatives data into HDF5 file.
- Parameters:
obj (ChainruleDerivatives) – A ChainruleDerivatives object.
h5file (str or h5py.File/h5py.Group obejct, optional, default to "dynamic_tensors.hdf5") – Path to a HDF5 file or a h5py.File/h5py.Group object.
overwrite (bool, optional, default to False) – When the file exists, whether to replace the content of the file with the content to be saved.