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.