PAOFLOW.elphon.dvscf_fd

Finite-difference dV = dH/du in the supercell PAO basis (P1).

For every reference-cell displacement the PAO real-space Hamiltonian HRs of the +delta and -delta supercells is rebuilt (from the displaced DFT .save via the standard projection / pao_hamiltonian pipeline) and central-differenced,

dV_{kappa,alpha}(R) = (HRs[+delta] - HRs[-delta]) / (2 delta),

giving the derivative of the Hamiltonian with respect to displacing atom kappa along Cartesian direction alpha, in the supercell PAO basis. The fold to the primitive cell and the assembly of g_mn^v(k, q) follow in P2.

Functions

finite_difference_dV(hrs_plus, hrs_minus, distance)	Central finite difference of the supercell PAO Hamiltonian.
build_supercell_HRs(savedir[, workpath, ...])	Rebuild the PAO real-space Hamiltonian HRs for one supercell .save.
supercell_symmetry_operators(savedir[, workpath, ...])	Crystal-symmetry operators of a (reference) supercell .save.
good_subspace_projectors(HRs_ref, eta[, tol])	Build the good-projectability subspace projectors P_good(K).
project_dV_good(dV_R, Pg)	Project a real-space supercell dV onto the good subspace P_good.
compute_dV(data_controller[, elphon_dir, ...])	Rebuild HRs per displaced supercell and finite-difference to dV.

Module Contents

PAOFLOW.elphon.dvscf_fd.finite_difference_dV(hrs_plus, hrs_minus, distance)

Central finite difference of the supercell PAO Hamiltonian.

Parameters:

• hrs_plus (ndarray) – HRs of the +delta / -delta supercells, identical shape (nawf, nawf, nk1, nk2, nk3, nspin) (eV).

• hrs_minus (ndarray) – HRs of the +delta / -delta supercells, identical shape (nawf, nawf, nk1, nk2, nk3, nspin) (eV).

• distance (float) – Displacement amplitude delta in Bohr.

Returns:

dV = (HRs[+] - HRs[-]) / (2 delta) (eV/Bohr), same shape.

Return type:

ndarray

PAOFLOW.elphon.dvscf_fd.build_supercell_HRs(savedir, workpath='.', configuration='standard', basispath=None, pthr=0.95, shift_type=1, return_shift=False, return_symmetry_inputs=False)

Rebuild the PAO real-space Hamiltonian HRs for one supercell .save.

Runs the standard PAOFLOW pipeline (projections -> projectability -> pao_hamiltonian) on the displaced supercell and returns its HRs array (nawf, nawf, nk1, nk2, nk3, nspin). If return_shift is True also returns the completion energy eta (attr['shift']), needed to build the good-projectability subspace projector. If return_symmetry_inputs is True also returns the arrays needed to build the crystal-symmetry operators (so a single reference-supercell build can serve the dV finite difference and the symmetry expansion).

Extra return values follow HRs in the order shift, symmetry_inputs.

PAOFLOW.elphon.dvscf_fd.supercell_symmetry_operators(savedir, workpath='.', configuration='standard', basispath=None, pthr=0.95, shift_type=1)

Crystal-symmetry operators of a (reference) supercell .save.

Runs the PAO pipeline on the undisplaced supercell to obtain its space-group operations, atomic positions and orbital layout, and packages them (via PAOFLOW.elphon.symmetry.build_dv_symmetry_operators()) into the operator set used to symmetry-rotate the supercell dV tensor.

Returns:

The operator set from build_dv_symmetry_operators().

Return type:

dict

PAOFLOW.elphon.dvscf_fd.good_subspace_projectors(HRs_ref, eta, tol=0.05)

Build the good-projectability subspace projectors P_good(K).

The PAO Hamiltonian completes the unrepresented subspace with +eta(1 - P), so the complement eigenstates of H^PAO(K) sit exactly at eta while the physical (projectable) bands lie strictly below it. Diagonalising the reference H^PAO(K) (from HRs_ref) and keeping the eigenvectors with eigenvalue < eta - tol therefore isolates the good subspace, and P_good = sum_good |v><v|.

Parameters:

• HRs_ref (ndarray, (nawf, nawf, n1, n2, n3, nspin)) – Reference (undisplaced) supercell PAO Hamiltonian in real space.

• eta (float) – Completion energy attr['shift'].

• tol (float) – Margin below eta separating good bands from the complement.

Returns:

The projector P_good(K) on the supercell k-grid (folded-fftfreq).

Return type:

ndarray, (nawf, nawf, n1, n2, n3, nspin) complex

PAOFLOW.elphon.dvscf_fd.project_dV_good(dV_R, Pg)

Project a real-space supercell dV onto the good subspace P_good.

Transforms dV(R) -> dV(K), applies P_good(K) dV(K) P_good(K) at every supercell k-point, and transforms back. This removes the coupling to (and through) the eta-completion complement – the unphysical off-diagonal channel – while preserving the physical good-good deformation potential.

PAOFLOW.elphon.dvscf_fd.compute_dV(data_controller, elphon_dir='elphon', configuration=None, basispath=None, pthr=0.95, shift_type=1, verify_saves=True, project_good_subspace=True)

Rebuild HRs per displaced supercell and finite-difference to dV.

Reads the displacements.json manifest written by the generate phase. For each symmetry-reduced displacement it computes the directional derivative of the PAO Hamiltonian per unit displacement along the (Cartesian) displacement direction: a central difference when the explicit - partner is present, otherwise a forward difference against the reference supercell.

The reduced directional derivatives are the response dataset; the full dH/du_{kappa,alpha} tensor for every atom and Cartesian direction is reconstructed from them by crystal symmetry in the next stage (analogous to phonopy’s force-constant symmetrization).

Returns:

{'distance', 'reference_prefix', 'directional': [ {sc_atom, displacement, dV}, ... ]} where dV is the supercell-basis derivative (eV/Bohr). Also stored as arry['elphon_dV'].

Return type:

dict