PAOFLOW.elphon.do_gkq#

Assemble the real-space electron-phonon tensor g(kappa,alpha; R_e, R_p) (P2).

Ties together the finite-difference derivatives, the Cartesian solve and the supercell -> primitive fold:

  1. PAOFLOW.elphon.dvscf_fd.compute_dV() gives the directional derivatives (one per symmetry-reduced / Cartesian displacement).

  2. For every displaced atom the directional responses are combined into the three Cartesian derivatives (PAOFLOW.elphon.symmetry.cartesian_derivatives_from_directional()).

  3. Each Cartesian derivative (supercell basis) is folded to the primitive electron-phonon tensor (PAOFLOW.elphon.fold.fold_dV_to_primitive()).

The result is g_R of shape (natom_prim * 3, nawf_prim, nawf_prim, N1e, N2e, N3e, s1, s2, s3, nspin) – the Cartesian derivative dH/du_{kappa,alpha} of the primitive hopping over the electron grid R_e and the commensurate phonon-cell grid R_p.

Functions#

enforce_acoustic_sum_rule(g_R, cart_index)

Impose the translational acoustic sum rule on the real-space e-ph tensor.

assemble_eph_tensor(data_controller[, elphon_dir, ...])

Build the primitive Cartesian electron-phonon real-space tensor.

Module Contents#

PAOFLOW.elphon.do_gkq.enforce_acoustic_sum_rule(g_R, cart_index)[source]#

Impose the translational acoustic sum rule on the real-space e-ph tensor.

A rigid displacement of the whole crystal (every atom kappa in every cell R_p moved by the same vector along alpha) leaves each primitive hopping H_{mn}(R_e) unchanged, hence

\[\sum_{\kappa, R_p} g_{\kappa\alpha,\,mn}(R_e, R_p) = 0\]

for every alpha, R_e, m, n and spin. Finite differences on a metal built with the eta-shift completion satisfy this only up to numerical noise, so – exactly as EPW/phonopy enforce the ASR on the dynamical matrix and e-ph coupling – the residual is removed by subtracting its mean equally from every (kappa, R_p) slice sharing a Cartesian direction alpha.

Parameters:

  • g_R (ndarray) – Shape (natom*3, nawf, nawf, N1e, N2e, N3e, s1, s2, s3, nspin).

  • cart_index (list[tuple[int, int]]) – (prim_atom, alpha) label of each leading row of g_R.

Returns:

  • g_R (ndarray) – The corrected tensor (modified in place and returned).

  • residual (float) – Frobenius norm of the rigid-shift residual before enforcement, ||sum_{kappa,R_p} g||, summed over the three Cartesian directions – a small value (relative to ||g||) certifies a trustworthy tensor.

PAOFLOW.elphon.do_gkq.assemble_eph_tensor(data_controller, elphon_dir='elphon', configuration=None, basispath=None, pthr=0.95, shift_type=1, enforce_asr=True, symmetry_expand='auto')[source]#

Build the primitive Cartesian electron-phonon real-space tensor.

Requires directional derivatives that span the three Cartesian directions for every displaced atom. With displacement_mode='cartesian' these are measured directly; with displacement_mode='symmetry' a single reduced direction per atom is symmetry-expanded to the full star (Wigner-D rotation of the PAO dV) via PAOFLOW.elphon.symmetry.expand_directional_responses().

Parameters:

  • symmetry_expand ({'auto', True, False}, optional) – Whether to symmetry-expand the directional responses. 'auto' (default) expands only when some displaced atom lacks three independent directions; True always expands; False never does.

  • enforce_asr (bool, optional) – If True (default), impose the translational acoustic sum rule on the assembled tensor via enforce_acoustic_sum_rule(). The pre- enforcement residual is reported in the returned 'asr_residual'.

Returns:

{'g_R', 'cart_index', 's2p', 'translations', 'naw', 'asr_residual'} where g_R has shape (natom_prim*3, nawf_prim, nawf_prim, N1e, N2e, N3e, s1, s2, s3, nspin) and cart_index lists the (prim_atom, alpha) label of each leading row. Also stored on the controller as arry['elphon_g_R'].

Return type:

dict