PAOFLOW.elphon.quadrupoles#

Dynamical quadrupoles from the long-wavelength expansion of the DFPT charge response.

The charge induced by a monochromatic displacement of atom kappa along beta has the multipole expansion (Royo and Stengel, PRX 9, 021050 (2019))

\[\varepsilon_L(\hat q)\Big[-\Omega\,\langle \tilde n_{\kappa\beta}(q)\rangle\, e^{i q\cdot\tau_\kappa} - i\, q_\beta Z^{\rm ion}_\kappa\Big] = -i\, q\cdot Z^*_{\kappa\beta} - \tfrac12\, q\cdot Q^{\kappa}_{\beta}\cdot q + O(q^3),\]

where \(\langle\tilde n\rangle\) is the cell average of the lattice-periodic part of the induced electron density per unit displacement (ph.x fildrho), \(-iq_\beta Z^{\rm ion}\) the point-ion charge moved with the atom (no higher multipoles), \(\varepsilon_L = \hat q\cdot\varepsilon^\infty\cdot\hat q\) removes the screening of the macroscopic field, which a finite-q DFPT run applies to the total (ion plus electron) charge, \(Z^*\) the Born charge and \(Q^\kappa_{\beta\alpha\gamma}\) the dynamical quadrupole in e bohr (second moment of the induced charge about the displaced atom, EPW’s Qmat(kappa, beta, alpha, gamma)). The response is real in real space, so the odd orders are imaginary and the even ones real: the quadrupole is the real part at order \(q^2\), uncontaminated by the \(q^2\) dependence of the dielectric function and by the ionic term, which are imaginary at orders \(q^3\) and \(q\).

Twelve single-q ph.x runs (six independent directions, two magnitudes) determine the 18 components per atom; the linear term reproduces the Born charges of the Gamma-point run, which checks the extraction and fixes the sign convention of the density file.

Attributes#

Functions#

single_q_phonon_inputs(prefix[, magnitudes, ...])

ph.x inputs of the single-q runs (fildrho) of the long-wavelength expansion.

find_density_response(phx_dir, prefix[, drho_name])

(drho file, patterns.1.xml) of a single-q ph.x run (_ph0/ layout).

cartesian_density_response(drho_patterns, u)

Induced density of every Cartesian displacement from the pattern-basis records.

expansion_coefficients(drho_cart, q_cart, tau_cart, ...)

Electronic charge response M_{kappa beta}(q) = -Omega <n~> e^{i q.tau} per Cartesian mode.

screened_to_bare(response, q_cart, alat, epsilon, zion)

A = eps_L (M - i q_beta Z_ion): the bare total charge response, -iq.Z* - q.Q.q/2 + ....

fit_multipoles(samples, alat[, epsilon, zion])

Born charges and quadrupoles from the expansion coefficients.

calibrate_sign(raw_linear, zstar, epsilon, zion)

+1 or -1: the sign that makes the raw linear coefficient of the samples physical.

write_quadrupole_fmt(path, quadrupoles)

Write EPW's quadrupole.fmt (atom dir Qxx Qyy Qzz Qyz Qxz Qxy per atom and direction).

quadrupoles_from_runs(runs, prefix, fft_grid, ...[, ...])

Read the single-q ph.x runs and fit the multipoles.

Module Contents#

PAOFLOW.elphon.quadrupoles.DIRECTIONS = ((1, 0, 0), (0, 1, 0), (0, 0, 1), (1, 1, 0), (1, 0, 1), (0, 1, 1))[source]#
PAOFLOW.elphon.quadrupoles.single_q_phonon_inputs(prefix, magnitudes=(0.02, 0.04), directions=DIRECTIONS, tr2_ph=1e-17, outdir='./')[source]#

ph.x inputs of the single-q runs (fildrho) of the long-wavelength expansion.

Parameters:
  • prefix (str) – QE prefix.

  • magnitudes (sequence of float, optional) – |q| in 2 pi / alat (two values allow the extrapolation to q -> 0).

  • directions (sequence of 3-vectors, optional) – Cartesian directions; six independent ones determine the symmetric quadratic forms.

  • tr2_ph (float, optional) – DFPT threshold (the q^2 term is small: keep it tight).

  • outdir (str, optional) – outdir of the run (each q in its own directory with a copy of the scf save).

Returns:

Run name, q in 2 pi / alat and the input text.

Return type:

list of (name, q_cart, text)

PAOFLOW.elphon.quadrupoles.find_density_response(phx_dir, prefix, drho_name='drho')[source]#

(drho file, patterns.1.xml) of a single-q ph.x run (_ph0/ layout).

Raises:

FileNotFoundError – If the density file or the patterns are missing.

PAOFLOW.elphon.quadrupoles.cartesian_density_response(drho_patterns, u)[source]#

Induced density of every Cartesian displacement from the pattern-basis records.

Parameters:
  • drho_patterns (ndarray (3 nat, nr1, nr2, nr3)) – One spin component of read_dvscf() applied to fildrho.

  • u (ndarray (3 nat, 3 nat)) – Displacement patterns (columns), read_patterns().

Returns:

Mode index 3 kappa + beta (the contraction of the induced potentials).

Return type:

ndarray (3 nat, nr1, nr2, nr3), complex

PAOFLOW.elphon.quadrupoles.expansion_coefficients(drho_cart, q_cart, tau_cart, alat, omega, sign=1.0)[source]#

Electronic charge response M_{kappa beta}(q) = -Omega <n~> e^{i q.tau} per Cartesian mode.

Parameters:
  • drho_cart (ndarray (3 nat, nr1, nr2, nr3)) – Lattice-periodic induced electron density per unit displacement (bohr^-3 / bohr).

  • q_cart (ndarray (3,)) – q in 2 pi / alat.

  • tau_cart (ndarray (nat, 3)) – Atomic positions (bohr).

  • alat (float) – bohr.

  • omega (float) – Cell volume (bohr^3).

  • sign (float, optional) – +1 when the file holds the induced electron (number) density; -1 for a charge density (calibrate_sign()).

Returns:

The screened electronic charge response (e per bohr of displacement, phase of the displaced atom removed); screened_to_bare() adds the ionic term and the screening.

Return type:

ndarray (nat, 3), complex

PAOFLOW.elphon.quadrupoles.screened_to_bare(response, q_cart, alat, epsilon, zion)[source]#

A = eps_L (M - i q_beta Z_ion): the bare total charge response, -iq.Z* - q.Q.q/2 + ....

Parameters:
  • response (ndarray (nat, 3)) – expansion_coefficients().

  • q_cart (ndarray (3,)) – q in 2 pi / alat.

  • alat (float)

  • epsilon (ndarray (3, 3)) – High-frequency dielectric tensor.

  • zion (ndarray (nat,)) – Valence charge of each atom’s pseudopotential.

PAOFLOW.elphon.quadrupoles.fit_multipoles(samples, alat, epsilon=None, zion=None)[source]#

Born charges and quadrupoles from the expansion coefficients.

Parameters:
  • samples (sequence of (q_cart, M)) – q in 2 pi / alat and expansion_coefficients() (nat, 3); six independent directions are needed, two magnitudes allow the q -> 0 extrapolation.

  • alat (float) – bohr.

  • epsilon (ndarray (3, 3), optional)

  • zion (ndarray (nat,), optional) – With both, the samples are converted with screened_to_bare() and the linear term is the Born charge Z*; without, the samples are fitted as given (zstar is then the raw linear coefficient, Z*/eps_L - Z_ion for a DFPT density).

Returns:

zstar (nat, 3, 3) [atom, field, displacement] from the imaginary part; quadrupoles (nat, 3, 3, 3) [atom, displacement, alpha, gamma] in e bohr (symmetric in the last two) extrapolated from the two smallest magnitudes (Richardson, O(q^2) corrections), quadrupoles_by_magnitude {|q|: Q}, residual_zstar and residual_quadrupole (relative least-squares residuals).

Return type:

dict

PAOFLOW.elphon.quadrupoles.calibrate_sign(raw_linear, zstar, epsilon, zion)[source]#

+1 or -1: the sign that makes the raw linear coefficient of the samples physical.

Parameters:
  • raw_linear (ndarray (nat, 3, 3)) – zstar of fit_multipoles() without epsilon/zion (the screened electronic response alone), expected to be Z*/eps_L - Z_ion; the ionic term dominates, so the test is robust even for Z* = 0.

  • zstar (ndarray (nat, 3, 3)) – Born charges of the Gamma-point DFPT run.

  • epsilon (ndarray (3, 3))

  • zion (ndarray (nat,))

PAOFLOW.elphon.quadrupoles.write_quadrupole_fmt(path, quadrupoles)[source]#

Write EPW’s quadrupole.fmt (atom dir Qxx Qyy Qzz Qyz Qxz Qxy per atom and direction).

PAOFLOW.elphon.quadrupoles.quadrupoles_from_runs(runs, prefix, fft_grid, tau_cart, alat, omega, epsilon, zion, zstar_ref=None, nspin_mag=1, drho_name='drho')[source]#

Read the single-q ph.x runs and fit the multipoles.

Parameters:
  • runs (sequence of (q_cart, directory)) – q in 2 pi / alat and the run directory holding _ph0/.

  • prefix (str)

  • fft_grid (sequence of int) – Dense FFT grid of the runs (read_nscf_plane_wave_setup(save)['fft_grid']).

  • tau_cart – As expansion_coefficients().

  • alat – As expansion_coefficients().

  • omega – As expansion_coefficients().

  • epsilon (ndarray (3, 3)) – High-frequency dielectric tensor of the Gamma run.

  • zion (ndarray (nat,)) – Valence charge of each atom’s pseudopotential.

  • zstar_ref (ndarray (nat, 3, 3), optional) – Born charges of the Gamma run: fixes the sign convention (calibrate_sign()) and is reported against the fitted value (zstar_ref).

  • nspin_mag (optional)

  • drho_name (optional)

Returns:

fit_multipoles() (zstar is the Born charge) plus sign and samples.

Return type:

dict