PAOFLOW.elphon.symmetry#

Symmetry expansion of the electron-phonon derivative (P2, step B).

A single symmetry-reduced displacement gives the Hamiltonian derivative along one direction d for the displaced atom. The full Cartesian derivative tensor dH/du_{kappa,alpha} (alpha = x, y, z) is recovered by applying the site-symmetry operations of the atom: each rotation W maps the measured response along d to the response along W.d (with the PAO orbitals rotated by the Wigner-D representation and the lattice vectors permuted). Collecting the responses along the star {W.d} and solving the linear system

response(n) = sum_alpha (n)_alpha * dH/du_{kappa,alpha}

for every generated direction n yields the three Cartesian derivatives (exactly as phonopy symmetrises its force constants).

This module provides the convention-free core – the Cartesian least-squares solve, the site-symmetry selection and the fractional->Cartesian rotation bridge that feeds PAOFLOW.hamiltonian.pao_sym.get_wigner(). The PAO Wigner-D rotation of the dV tensor itself is layered on top and validated against explicitly computed Cartesian displacements.

Functions#

frac_to_cartesian_rotation(w_frac, a_vectors)

Convert a fractional rotation W to its Cartesian form.

site_symmetry_rotations(sym_rot, shifts, ...[, tol])

Indices of the space-group operations that leave atom_index fixed.

cartesian_derivatives_from_directional(directions, ...)

Least-squares Cartesian derivatives from directional responses.

build_dv_symmetry_operators(a_vectors, tau, alat, ...)

Prepare the crystal-symmetry operator set that rotates a supercell PAO

rotate_dV_under_symmetry(dV, isym, ops[, chunk_bytes])

Rotate a supercell dV operator by space-group operation isym.

expand_directional_responses(directional, ops[, tol])

Symmetry-expand a reduced set of directional dV responses.

Module Contents#

PAOFLOW.elphon.symmetry.frac_to_cartesian_rotation(w_frac, a_vectors)[source]#

Convert a fractional rotation W to its Cartesian form.

With lattice vectors as the rows of a_vectors (A), a fractional rotation acting on fractional coordinates f corresponds to the Cartesian rotation R = A^T W A^{-T} acting on Cartesian coordinates r = A^T f.

Parameters:

  • w_frac (array_like, shape (3, 3)) – Rotation in fractional (crystal) coordinates.

  • a_vectors (array_like, shape (3, 3)) – Lattice vectors as rows (any consistent length unit).

Returns:

The Cartesian rotation matrix.

Return type:

ndarray, shape (3, 3)

PAOFLOW.elphon.symmetry.site_symmetry_rotations(sym_rot, shifts, frac_positions, atom_index, tol=0.0001)[source]#

Indices of the space-group operations that leave atom_index fixed.

Parameters:

  • sym_rot (array_like, shape (nsym, 3, 3)) – Fractional rotations.

  • shifts (array_like, shape (nsym, 3)) – Fractional translations (may be None -> treated as zero).

  • frac_positions (array_like, shape (natom, 3)) – Atomic positions in fractional coordinates.

  • atom_index (int) – Atom whose site symmetry is requested.

  • tol (float) – Fractional tolerance for the “maps to itself” test.

Returns:

Integer indices into sym_rot of the operations fixing the atom.

Return type:

ndarray

PAOFLOW.elphon.symmetry.cartesian_derivatives_from_directional(directions, responses, rcond=None)[source]#

Least-squares Cartesian derivatives from directional responses.

Solves response(n) = sum_alpha n_alpha D_alpha for the three Cartesian derivative tensors D_alpha given a set of unit directions n and their response tensors (all of identical shape). At least three independent directions are required.

Parameters:

  • directions (array_like, shape (ndir, 3)) – Displacement directions (need not be normalised; the magnitude scales the corresponding response).

  • responses (array_like, shape (ndir, *tensor_shape)) – Response tensor for each direction.

  • rcond (float, optional) – Cutoff passed to numpy.linalg.lstsq().

Returns:

The Cartesian derivative tensors [D_x, D_y, D_z].

Return type:

ndarray, shape (3, *tensor_shape)

PAOFLOW.elphon.symmetry.build_dv_symmetry_operators(a_vectors, tau, alat, sym_rot, equiv_atom, shells_per_atom, atom_labels, ngrid)[source]#

Prepare the crystal-symmetry operator set that rotates a supercell PAO operator (H or dV) exactly as PAOFLOW.hamiltonian.pao_sym.

The returned operators act on a supercell-basis operator M(k) (Bloch transform M(k) = sum_R M(R) exp(+2 pi i k.R)) via

\[M(W k) = U_k \, M(k) \, U_k^{\dagger} \;[\times U_{inv}]\]

with U_k = U * exp(-2 pi i (shift[a_index] . k)). This convention has been validated to reproduce H(Wk) to machine precision for every space group operation of the Al 2x2x2 supercell.

Parameters:

  • a_vectors ((3, 3) array) – Lattice vectors as rows, in alat units (supercell cell).

  • tau ((natom, 3) array) – Atomic positions in Cartesian (Bohr) coordinates.

  • alat (float) – Lattice parameter (Bohr) used to normalise tau.

  • sym_rot ((nsym, 3, 3) array) – Fractional (crystal) rotation matrices.

  • equiv_atom ((nsym, natom) int array) – equiv_atom[isym, i] is the atom that block i draws from under the operation (the map_equiv_atoms convention).

  • shells_per_atom (dict) – Mapping atom_label -> list of orbital l (PAOFLOW arry['shells']).

  • atom_labels (sequence) – Per-atom species labels (arry['atoms']).

  • ngrid (tuple(int, int, int)) – The supercell R/k grid sizes (n1, n2, n3).

Returns:

{'symop', 'symop_cart', 'U', 'phase', 'a_index', 'inv_flag', 'U_inv', 'equiv_atom', 'ngrid'}.

Return type:

dict

PAOFLOW.elphon.symmetry.rotate_dV_under_symmetry(dV, isym, ops, chunk_bytes=128 * 1024 * 1024)[source]#

Rotate a supercell dV operator by space-group operation isym.

dV is the electronic response (a Hermitian-structured PAO operator) to displacing one supercell atom kappa along a direction d. The result is the response of the image atom equiv_atom[isym, kappa] displaced along symop_cart[isym] . d – i.e. the caller relabels the displaced atom and direction accordingly.

Parameters:

  • dV (ndarray, shape (nawf, nawf, n1, n2, n3, nspin)) – Supercell real-space derivative.

  • isym (int) – Index of the operation in ops.

  • ops (dict) – Operator set from build_dv_symmetry_operators().

  • chunk_bytes (int, optional) – Approximate memory budget (bytes) for the per-chunk working arrays of the change-of-basis step. The (k, spin) batch is processed in blocks so peak memory stays bounded to roughly dVk + out + one chunk, rather than several nawf**2 * N_tot copies (many GB for large supercells). Larger values trade memory for slightly larger GEMMs.

Returns:

Rotated dV of identical shape.

Return type:

ndarray

PAOFLOW.elphon.symmetry.expand_directional_responses(directional, ops, tol=0.0001)[source]#

Symmetry-expand a reduced set of directional dV responses.

A symmetry-reduced calculation (displacement_mode='symmetry') measures the Hamiltonian derivative along a single direction per inequivalent atom. For each measured entry the site-symmetry operations of the displaced atom are applied to generate the star {W.d} of directions with their rotated dV tensors, so that every displaced atom acquires at least three linearly independent directions – the input the Cartesian least-squares solve (cartesian_derivatives_from_directional()) requires.

Parameters:

  • directional (list[dict]) – Measured responses {sc_atom, displacement, dV} (Cartesian displacement; supercell-basis dV).

  • ops (dict) – Operator set from build_dv_symmetry_operators() (of the reference supercell).

  • tol (float) – Tolerance for treating two (anti-)parallel directions as duplicates.

Returns:

Expanded list of {sc_atom, displacement, dV} entries.

Return type:

list[dict]