Skip to content

feat(dfpt): analytic libxc XC kernel with the i(G+q) carrier term (exact GGA response at q != 0) - #8163

Merged
mohanchen merged 3 commits into
deepmodeling:developfrom
Zanthoxylum:dfpt-csj
Oct 20, 2026
Merged

mohanchen merged 3 commits into
deepmodeling:developfrom
Zanthoxylum:dfpt-csj

Conversation

@Zanthoxylum

@Zanthoxylum Zanthoxylum commented Oct 17, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

PW-DFPT phonons evaluated with GGA functionals carried a systematic error at every q != 0, while LDA agreed with reference codes everywhere and all functionals were correct at q = Gamma. This PR replaces the finite-difference first-order XC path with an analytic kernel built from libxc second derivatives whenever ABACUS is compiled with libxc (ENABLE_LIBXC), and adds an explicit warning on the FDM fallback path.

Part 1 — LDA vs GGA: what the bug was

For a phonon perturbation at wavevector q the first-order density is a carrier wave drho(r) = 2 Re[A(r) e^{i q r}] with a carrier-free amplitude A stored on the unit-cell FFT grid. The GGA first-order XC response is

B(r) = f_rho A + f_grad . grad A + i (q . f_grad) A
                               carrier term

The third term is the gradient carried by the phase factor e^{i q r} itself; it has no counterpart in grid gradients of A. The previous FDM path finite-differenced the XC potential on +/- A around the ground state, so its gradients only ever saw grad A — the carrier term was structurally missing. The term vanishes exactly in the two limits that matched the observed failure pattern:

  • LDA: f_grad = 0 — LDA phonons were correct at every q;
  • q = Gamma: q = 0 — optical modes were correct for every functional.

In between (GGA at q != 0) the omission interacted with the variational stiffness of the Sternheimer solve and the large-cancellation structure of polar materials, amplifying a percent-level kernel deficit into mode errors of tens of percent. QE evaluates the same response with the gradient operator acting on the physical field through i(G + q) (fft_qgradient in gradutils.f90, dgradcorr in LR_Modules), which includes the carrier exactly.

Part 2 — Why libxc for the kernel

The carrier term is analytic: restoring it requires the exact GGA kernel tensor (f_rho_rho, f_rho_sigma, f_sigma_sigma, f_sigma) evaluated on the ground-state density. Hand-deriving and maintaining analytic second derivatives per functional is error-prone and does not scale beyond PBE, while libxc (xc_gga_fxc / xc_lda_fxc, requirement >= 5.1.7) provides them for every functional it ships. Design decisions:

  • DFPT kernel only. The ground-state XC path is untouched (built-in functionals keep use_libxc = false), so ground-state baselines do not move.
  • Kernel mapping (sigma = |grad rho|^2, matching QE's libxc wrapper xc_wrapper_d_gga): k_rr = v2rho2, k_sr = 2 v2rhosigma, k_ss = 4 v2sigma2, k_s = 2 vsigma; LDA reduces to k_rr = v2rho2 (libxc vrho is already the potential form, so no additional rho renormalization appears — the potential-form kernels cancel it).
  • Units are folded in at construction: e2 = 2 (Hartree to Ry) and tpiba (PW_Basis gcar is dimensionless — the physical wavevector is tpiba * gcar, the same convention DFPT_Rho::v_hartree_q uses with its tpiba2 divisor).
  • nlcc base density. The kernel fields are linearized at the full ground-state XC density — valence plus the nonlinear core correction density when the pseudopotentials carry one (rho0 = rho + rho_core, exactly what PotXC_FDM feeds the internal functional, see pot_xc_fdm.cpp), while the first-order density itself stays valence-only (a frozen core does not respond). Feeding the valence density alone moves nlcc systems off their ground-state point: bn_cubic Gamma optical modes dropped ~15 cm^-1 versus both the FDM path and QE. Non-nlcc systems are unaffected.
  • Interface: XC_First_Order::set_context(q_cart) — a const per-q context hook on the existing provider base; the solver injects it in assemble_v_sc before apply. Without libxc the FDM adapter remains the default and now warns that the GGA response at q != 0 lacks the carrier term (LDA stays exact).
  • Tests: new MODULE_DFPT_xc_analytic_serial — LDA kernel vs finite difference of v_xc; the full GGA chain at Gamma cross-checked against a field-perturbation finite difference (an algebra-level independent path); carrier-term presence at finite q for GGA and exact q-independence for LDA. Existing DFPT serial suites are unchanged.

@mohanchen mohanchen added DFPT Density Functional Perturbation Theory Refactor Refactor ABACUS codes labels Oct 17, 2026
@mohanchen

Copy link
Copy Markdown
Collaborator

@ABACUS-PR-BOT could you review the PR?

@ABACUS-PR-BOT ABACUS-PR-BOT left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed statically at 7ac3caf8990cf93977584f2fa3b891658b870b93 with independent verification. No builds or runtime/numerical tests were run; CI diagnostics were unavailable. Low/signed-density regularization and per-Libxc FXC availability remain unresolved.

Non-blocking: please add the exact validation commands, Libxc/MPI configuration, and observed pass/fail/not-run outcomes to the PR body. The current test descriptions and frequency observations do not establish which checks actually ran.

Review finding of deepmodeling#8164 (P1): the sigma <= epsg guard zeroed k_rr_
together with the gradient fields, so flat-gradient regions (vacuum,
uniform-density interstitials) lost the local (rho-rho) XC response
entirely -- unlike QE, whose dv_of_drho accumulates the local term
separately from the guarded dgradcorr gradient terms. The local kernel
is finite in the zero-gradient limit (the LDA-like term of the GGA
functional), so only the density guard applies to it; the gradient
chain fields keep the epsg guard.

Adds the zero-gradient regression test the review asked for: a uniform
density (sigma == 0 everywhere) must respond with dvxc = k_rr A,
finite and nonzero, exact to 1e-10.
…n the kernel

Review findings of deepmodeling#8164 (two P2): xc_func_init used libxc defaults, so
configured LDA/GGA runs (xc_exch_ext / xc_corr_ext fractions, finite-T
LDA) differentiated a different functional in DFPT than the ground
state used; and the unconditional +1 sum lost the signed combination
factors (BLYP_LR subtracts its short-range ITYH/LYPR components).

- XC_Functional_Libxc::ext_params_for: expose the per-component
  parameter lists init_func would apply (external override in-built),
  so the kernel instantiates exactly the GS effective functional
  without duplicating the parameter tables
- XC_First_Order_Analytic gains a configured ctor taking those lists
  and the signed weights; the esolver factory feeds both from
  XC_Functional (new XC_Functional::get_weight accessor)
- per-component family dispatch: mixed LDA+GGA combinations evaluate
  LDA members through the LDA entry points
- tests: KSDT at nondefault theta matches the manually parameterized
  libxc second derivative; signed weights ({-2,+3}) scale every field;
  neutral configuration reproduces the plain ctor bit-for-bit
Review finding of deepmodeling#8164 (non-blocking): the trace/summary lines mutated
std::cout flags and precision, and the changes leaked into the opt-in
DFPT_DEBUG snapshots of the next iteration (setprecision(1) truncating
them). Both blocks now format into a local ostringstream, leaving the
shared stream state untouched.
@Zanthoxylum Zanthoxylum reopened this Oct 19, 2026
@Zanthoxylum

Copy link
Copy Markdown
Collaborator Author

Review response — fixes for the findings at 8d93aff (2026-10-19)

Context: the original content above entered develop through the squash-merge of #8164,
with three review findings unaddressed. This PR (reopened) now carries exactly the fixes
for those findings — commits 549a6d19c, db71dca3e, b05c3f346.

[P1] local GGA response below the gradient cutoff — fixed in 549a6d1

Finding: the sigma <= epsg guard zeroed k_rr_ together with the gradient fields,
so flat-gradient regions (vacuum, uniform-density interstitials) lost the local (rho-rho)
XC response entirely; QE retains that term through the separately accumulated local part
of dv_of_drho.

Fix: the local kernel is finite in the zero-gradient limit (the LDA-like term of the
GGA functional), so it is now guarded by the density threshold alone; only the gradient
chain fields (k_sr_/k_ss_/k_s_) keep the epsg guard. Added the zero-gradient
regression test the review asked for: a uniform density (sigma == 0 everywhere) must
respond with dvxc = k_rr A — finite, nonzero, exact to 1e-10 (the previous code
returned identically zero there).

[P2] configured Libxc parameters ignored — fixed in db71dca

Finding: xc_func_init used libxc defaults while the ground-state init_func
applies xc_exch_ext / xc_corr_ext and in-built parameters (finite-T LDA, tuned
fractions), so configured runs differentiated a different functional in DFPT.

Fix: new XC_Functional_Libxc::ext_params_for(func_id, ...) exposes the per-component
parameter lists init_func would apply — a read-only accessor over the existing in-built
and external tables (external overrides in-built), so the tables stay single-sourced in
module_xc with no duplication and no GS behavior change. XC_First_Order_Analytic gains a
configured constructor consuming those lists (xc_func_set_ext_params, with the same
n_ext_params validation as init_func), and the esolver factory feeds it. Test: a KSDT
kernel at nondefault theta = 0.007 matches the manually parameterized libxc second
derivative to 1e-12.

[P2] signed component weights lost — fixed in db71dca

Finding: the unconditional +1 sum lost the ground-state combination factors — e.g.
BLYP_LR subtracts its short-range ITYH/LYPR components while the kernel added them.

Fix: XC_Functional::get_weight(id) (inline, reads the existing scaling map) feeds
the signed per-component factors through the factory into every derivative field
accumulation. Tests: a {-2,+3} weighted combination scales all fields correctly, and a
neutral configuration (empty params, unit weights) reproduces the plain constructor
bit-for-bit.

Follow-ups included in the same commits

  • per-component family dispatch: mixed LDA+GGA combinations (func_type 2 with LDA
    members) now evaluate LDA members through the LDA entry points — the signed-weights
    test exposed this latent path;
  • stream-safe logging (b05c3f346): the displacement iteration trace and summary
    format through local ostringstream buffers, so setprecision/flags no longer leak
    into the opt-in DFPT_DEBUG snapshots of the next iteration (the non-blocking
    review note on feat(dfpt): iteration logging and dead-code cleanup #8164).

@mohanchen
mohanchen merged commit c2e8193 into deepmodeling:develop Oct 20, 2026
32 of 34 checks passed
@Zanthoxylum
Zanthoxylum deleted the dfpt-csj branch October 23, 2026 17:56
mohanchen pushed a commit that referenced this pull request Oct 29, 2026
…rho_broyden, rho_kerker, v_sc_plain (#8214)

* feat(dfpt): promote the response mixing scheme to INPUT parameters

dfpt_mix_type (plain|kerker) and dfpt_kerker_a2 replace the
design-phase env knobs DFPT_MIX_TYPE / DFPT_KERKER_A2 /
DFPT_MIX_BETA; the plain 0.4 default behavior is unchanged.

Also emit an explicit ModuleBase::WARNING when a displacement
response exhausts dfpt_max_iter (warning.log channel, next to the
stdout summary from the R4a fix in #8163).

Rebased from the dfpt-mix branch onto current develop (resolves
the logging-format conflict by combining both versions).

* feat(dfpt): Broyden mixing for the response SCF (dfpt_mix_type = broyden)

New INPUT parameter dfpt_broyden_ndim (default 8). When
dfpt_mix_type = broyden, the first-order density mixing uses the
Modified Broyden method (Johnson 1988) from the existing
Base_Mixing::Broyden_Mixing -- the same algorithm QE ph.x uses
(nmix_ph = 4 default there). The Broyden history is per
(q, displacement-cycle) and is dropped by reset_mixing.

The three-step Broyden interface (push_data + cal_coef + mix_data)
is wired inside mix_drho; the plain and kerker paths are unchanged.

* feat(dfpt): v_sc mixing route for the response SCF (dfpt_mix_type = v_sc)

When dfpt_mix_type = v_sc, the SCF fixed-point variable changes from
the first-order density drho to the screening potential v_sc: each
iteration solves the Sternheimer equation with the mixed potential,
obtains the output density, rebuilds the output potential from it, and
mixes the two potentials. The variable change provides implicit
K^-1 preconditioning (the Hartree+XC kernel's inverse), flattening the
Coulomb-stiff smallest-G shells that destabilize plain density mixing
(tio2 X response Jacobian eigenvalue ~ -2.2 on the {111}/{200} shells).

The residual in v_sc mode measures the potential self-consistency
||v_out - v_in||/||v_out||; the 2n+1 accumulation path uses the
converged output density from the converged potential.

plain, kerker, and broyden paths are unchanged.

* test(dfpt): disable Broyden mock test pending interface fix

The synthetic Broyden convergence test crashes inside
Broyden_Mixing::push_data with the mock SetupBases fixture (likely an
internal interface mismatch with the null screen/combine callbacks);
the real-system G5 validation (si/tio2 X with broyden) provides
end-to-end coverage of the mixing path. Re-enable after the mock
interface is understood.

* fix(dfpt): accept broyden and v_sc in the DFPT_Rho init validation and DFPT_PW setter

Two validation points silently rejected the new mixing types:
DFPT_PW::set_mix_type only accepted plain/kerker (broyden/v_sc were
dropped, leaving the default plain), and DFPT_Rho::init WARNING_QUIT
on any mix_type outside plain/kerker. Both now accept all four.

* fix(dfpt): provide the mix callback for Broyden push_data

Broyden_Mixing::tem_push_data calls mix(data, data_in, F) unconditionally
(broyden_mixing.cpp:47 has a nullptr guard for screen but NOT for mix);
passing an empty std::function threw bad_function_call -> SIGABRT. Provide
the actual preliminary mix (data = data_in + beta * F) that the Broyden
algorithm needs. tio2 X now converges at iteration ~18 (first time this
system converges in DFPT response SCF; plain and v_sc both oscillate at
residual ~0.8-1.7).

* fix(dfpt): reset the Broyden mixer's address binding between displacements

reset_mixing destroys the per-q Mixing_Data object but the Broyden
mixer's internal 'address' pointer still referenced the freed object;
the next displacement's push_data then hit the 'One Broyden_Mixing
object can only bind one Mixing_Data' guard and WARNING_QUIT. Call
broyden_mixer_->reset() alongside the mdata reset to clear the
dangling binding.

* refactor(dfpt): rename mixing methods to {variable}_{algorithm} format; add v_sc Broyden

dfpt_mix_type values renamed to a consistent naming scheme:
  plain       -> rho_plain (default)
  kerker      -> rho_kerker
  broyden     -> rho_broyden
  v_sc        -> v_sc_plain
  (new)       -> v_sc_broyden

v_sc_broyden uses a separate Broyden_Mixing instance on the nrxx-length
real-space screening potential (the density Broyden operates on npw-length
G-space arrays). The v_sc Mixing_Data is initialized and reset per
displacement cycle in solve_displacement.

The v_sc_* modes bypass DFPT_Rho's density mixing entirely (a rho_plain
config is passed to DFPT_Rho as a no-op) and do their own potential
mixing in solve_displacement's v_sc branch.

* feat(dfpt): set v_sc_broyden as the default mixing scheme

G5 validation across si X and tio2 X: both rho_broyden and
v_sc_broyden converge identically (same fixed point, ~13-17 iterations
per displacement; tio2 X converges for the first time ever in DFPT
while rho_plain diverges at 12+ unconverged displacements).
v_sc_broyden is chosen as the default because it exactly matches QE's
approach (Modified Broyden on the screening potential), provides
better-conditioned Broyden inner products through the implicit K^-1
weighting, and has theoretical headroom for nonlinear extensions.

All five mixing methods remain available via dfpt_mix_type:
rho_plain | rho_kerker | rho_broyden | v_sc_plain | v_sc_broyden

* fix(dfpt): address review findings on the mixing PR

- migrate the remaining old mix_type tokens: the rho_kerker branch in
  mix_drho, the serial-test fixtures, the Impl default (now the valid
  v_sc_broyden), and the read_inp_dfpt empty-input fallback (was the
  rejected "plain"); CI MODULE_DFPT_rho_serial died on the fixture token
- reset the shared Broyden mixer on every reset_mixing call, not only
  when the q already has a history entry: entering a fresh q left the
  mixer address-bound to the previous q's Mixing_Data and the first
  push died in the one-object-one-data guard
- reduce the Broyden cal_coef inner products and the residual norms
  over the pool (Parallel_Reduce::reduce_pool behind __MPI guards,
  xc_pot.cpp convention): each rank only holds its FFT slab / G-shell
  share, so unreduced Gram systems and stopping norms were partition
  dependent
- guard the relative-defect convergence metric: a zero output norm now
  only reports convergence when the defect itself is zero, and
  non-finite norms never converge (v_out = 1 - c v_in counterexample)
- enable the Broyden regression with a sourced model fixed point (the
  sourceless variant cannot converge under the relative residual) and
  add a two-q reset_mixing regression for the address-guard fix
- INPUT metadata: use the accepted rho_*/v_sc_* names in the
  descriptions, document which residual dfpt_conv_thr measures per
  scheme, and reword the v_sc comment (plain-mixing spectrum is
  invariant under the variable change; Broyden benefits from the
  K-weighted metric)
- forward-declare the mixing types in dfpt_rho.h and drop the concrete
  includes (dfpt_pw_impl.h already includes them directly)

* test(dfpt): correct the plain-mixing contraction note in the Broyden regression

Review follow-up: the binding populated shell is d = 0.5 with factor
|1 - beta (1 - D)| = 0.8 (>= 103 plain steps to 1e-10), not the
unpopulated-shell bound 0.6. Assertions are unchanged.

* fix(dfpt): address the human-review nits on the E-field loop and init

- E-field solve (dfpt_pw_q0.cpp): report non-convergence explicitly with
  the same ModuleBase::WARNING as solve_displacement (a silently
  truncated E-field solve corrupts Z* / LO-TO); the v_sc_* -> rho_plain
  mapping note is added at the init site
- DFPT_Rho::init: reject broyden_ndim < 1 for rho_broyden (Config is a
  C++11 aggregate, so brace-initialized callers get 0 and Broyden_Mixing
  would divide by zero in the % mixing_ndim wrap); fix the 'default 8'
  comment; accept only the rho_* tokens (the solver-side init already
  maps v_sc_*, so the nested branch was unreachable)
- drop the no-op set_drho_g write-back in the v_sc branch (data_ still
  holds the last compute_drho output) and reword the comment
- drop the out-of-repository MIXING_20261020.md reference
- rename safe_relative_defect_ -> safe_relative_defect (free function in
  an anonymous namespace; the trailing underscore is the member
  convention); sync the plain-mixing contraction notes in the test
  (roughly 100 iterations at 0.8/step on the binding shell)

* feat(dfpt): give the E-field solve the density-space Broyden mixer under v_sc_broyden

Review follow-up (Critsium-xy): with the v_sc_broyden default, the
E-field solve (Z* / epsilon_inf / LO-TO) silently fell back to plain
density mixing at beta 0.4 -- the weakest member of the family exactly
on the path that matters most for polar systems. Map v_sc_broyden to
rho_broyden for DFPT_Rho (v_sc_plain keeps rho_plain), so the E-field
loop runs Modified Broyden on the density while the displacement loop
keeps its potential-space Broyden.

Verification (si, Gamma + dfpt_compute_q0/dfpt_loto, default INPUT so
the path is exercised through the mapping): E-field 3/3 directions
converge in 12 iterations (bit-identical residuals to an explicit
rho_broyden run) versus 38 with the previous plain fallback --
displacements unchanged at 13 iterations (v_sc Broyden); Gamma
frequencies and the LO-TO block reproduce the pre-change values
exactly. INPUT metadata documents that dfpt_broyden_ndim now sizes
both Broyden instances and that the E-field residual is always the
density residual.
mohanchen pushed a commit that referenced this pull request Oct 31, 2026
…ynmatcc) and fix the mirrored structure-factor phase (#8237)

* feat(dfpt): promote the response mixing scheme to INPUT parameters

dfpt_mix_type (plain|kerker) and dfpt_kerker_a2 replace the
design-phase env knobs DFPT_MIX_TYPE / DFPT_KERKER_A2 /
DFPT_MIX_BETA; the plain 0.4 default behavior is unchanged.

Also emit an explicit ModuleBase::WARNING when a displacement
response exhausts dfpt_max_iter (warning.log channel, next to the
stdout summary from the R4a fix in #8163).

Rebased from the dfpt-mix branch onto current develop (resolves
the logging-format conflict by combining both versions).

* feat(dfpt): Broyden mixing for the response SCF (dfpt_mix_type = broyden)

New INPUT parameter dfpt_broyden_ndim (default 8). When
dfpt_mix_type = broyden, the first-order density mixing uses the
Modified Broyden method (Johnson 1988) from the existing
Base_Mixing::Broyden_Mixing -- the same algorithm QE ph.x uses
(nmix_ph = 4 default there). The Broyden history is per
(q, displacement-cycle) and is dropped by reset_mixing.

The three-step Broyden interface (push_data + cal_coef + mix_data)
is wired inside mix_drho; the plain and kerker paths are unchanged.

* feat(dfpt): v_sc mixing route for the response SCF (dfpt_mix_type = v_sc)

When dfpt_mix_type = v_sc, the SCF fixed-point variable changes from
the first-order density drho to the screening potential v_sc: each
iteration solves the Sternheimer equation with the mixed potential,
obtains the output density, rebuilds the output potential from it, and
mixes the two potentials. The variable change provides implicit
K^-1 preconditioning (the Hartree+XC kernel's inverse), flattening the
Coulomb-stiff smallest-G shells that destabilize plain density mixing
(tio2 X response Jacobian eigenvalue ~ -2.2 on the {111}/{200} shells).

The residual in v_sc mode measures the potential self-consistency
||v_out - v_in||/||v_out||; the 2n+1 accumulation path uses the
converged output density from the converged potential.

plain, kerker, and broyden paths are unchanged.

* test(dfpt): disable Broyden mock test pending interface fix

The synthetic Broyden convergence test crashes inside
Broyden_Mixing::push_data with the mock SetupBases fixture (likely an
internal interface mismatch with the null screen/combine callbacks);
the real-system G5 validation (si/tio2 X with broyden) provides
end-to-end coverage of the mixing path. Re-enable after the mock
interface is understood.

* fix(dfpt): accept broyden and v_sc in the DFPT_Rho init validation and DFPT_PW setter

Two validation points silently rejected the new mixing types:
DFPT_PW::set_mix_type only accepted plain/kerker (broyden/v_sc were
dropped, leaving the default plain), and DFPT_Rho::init WARNING_QUIT
on any mix_type outside plain/kerker. Both now accept all four.

* fix(dfpt): provide the mix callback for Broyden push_data

Broyden_Mixing::tem_push_data calls mix(data, data_in, F) unconditionally
(broyden_mixing.cpp:47 has a nullptr guard for screen but NOT for mix);
passing an empty std::function threw bad_function_call -> SIGABRT. Provide
the actual preliminary mix (data = data_in + beta * F) that the Broyden
algorithm needs. tio2 X now converges at iteration ~18 (first time this
system converges in DFPT response SCF; plain and v_sc both oscillate at
residual ~0.8-1.7).

* fix(dfpt): reset the Broyden mixer's address binding between displacements

reset_mixing destroys the per-q Mixing_Data object but the Broyden
mixer's internal 'address' pointer still referenced the freed object;
the next displacement's push_data then hit the 'One Broyden_Mixing
object can only bind one Mixing_Data' guard and WARNING_QUIT. Call
broyden_mixer_->reset() alongside the mdata reset to clear the
dangling binding.

* refactor(dfpt): rename mixing methods to {variable}_{algorithm} format; add v_sc Broyden

dfpt_mix_type values renamed to a consistent naming scheme:
  plain       -> rho_plain (default)
  kerker      -> rho_kerker
  broyden     -> rho_broyden
  v_sc        -> v_sc_plain
  (new)       -> v_sc_broyden

v_sc_broyden uses a separate Broyden_Mixing instance on the nrxx-length
real-space screening potential (the density Broyden operates on npw-length
G-space arrays). The v_sc Mixing_Data is initialized and reset per
displacement cycle in solve_displacement.

The v_sc_* modes bypass DFPT_Rho's density mixing entirely (a rho_plain
config is passed to DFPT_Rho as a no-op) and do their own potential
mixing in solve_displacement's v_sc branch.

* feat(dfpt): set v_sc_broyden as the default mixing scheme

G5 validation across si X and tio2 X: both rho_broyden and
v_sc_broyden converge identically (same fixed point, ~13-17 iterations
per displacement; tio2 X converges for the first time ever in DFPT
while rho_plain diverges at 12+ unconverged displacements).
v_sc_broyden is chosen as the default because it exactly matches QE's
approach (Modified Broyden on the screening potential), provides
better-conditioned Broyden inner products through the implicit K^-1
weighting, and has theoretical headroom for nonlinear extensions.

All five mixing methods remain available via dfpt_mix_type:
rho_plain | rho_kerker | rho_broyden | v_sc_plain | v_sc_broyden

* fix(dfpt): address review findings on the mixing PR

- migrate the remaining old mix_type tokens: the rho_kerker branch in
  mix_drho, the serial-test fixtures, the Impl default (now the valid
  v_sc_broyden), and the read_inp_dfpt empty-input fallback (was the
  rejected "plain"); CI MODULE_DFPT_rho_serial died on the fixture token
- reset the shared Broyden mixer on every reset_mixing call, not only
  when the q already has a history entry: entering a fresh q left the
  mixer address-bound to the previous q's Mixing_Data and the first
  push died in the one-object-one-data guard
- reduce the Broyden cal_coef inner products and the residual norms
  over the pool (Parallel_Reduce::reduce_pool behind __MPI guards,
  xc_pot.cpp convention): each rank only holds its FFT slab / G-shell
  share, so unreduced Gram systems and stopping norms were partition
  dependent
- guard the relative-defect convergence metric: a zero output norm now
  only reports convergence when the defect itself is zero, and
  non-finite norms never converge (v_out = 1 - c v_in counterexample)
- enable the Broyden regression with a sourced model fixed point (the
  sourceless variant cannot converge under the relative residual) and
  add a two-q reset_mixing regression for the address-guard fix
- INPUT metadata: use the accepted rho_*/v_sc_* names in the
  descriptions, document which residual dfpt_conv_thr measures per
  scheme, and reword the v_sc comment (plain-mixing spectrum is
  invariant under the variable change; Broyden benefits from the
  K-weighted metric)
- forward-declare the mixing types in dfpt_rho.h and drop the concrete
  includes (dfpt_pw_impl.h already includes them directly)

* test(dfpt): correct the plain-mixing contraction note in the Broyden regression

Review follow-up: the binding populated shell is d = 0.5 with factor
|1 - beta (1 - D)| = 0.8 (>= 103 plain steps to 1e-10), not the
unpopulated-shell bound 0.6. Assertions are unchanged.

* fix(dfpt): address the human-review nits on the E-field loop and init

- E-field solve (dfpt_pw_q0.cpp): report non-convergence explicitly with
  the same ModuleBase::WARNING as solve_displacement (a silently
  truncated E-field solve corrupts Z* / LO-TO); the v_sc_* -> rho_plain
  mapping note is added at the init site
- DFPT_Rho::init: reject broyden_ndim < 1 for rho_broyden (Config is a
  C++11 aggregate, so brace-initialized callers get 0 and Broyden_Mixing
  would divide by zero in the % mixing_ndim wrap); fix the 'default 8'
  comment; accept only the rho_* tokens (the solver-side init already
  maps v_sc_*, so the nested branch was unreachable)
- drop the no-op set_drho_g write-back in the v_sc branch (data_ still
  holds the last compute_drho output) and reword the comment
- drop the out-of-repository MIXING_20261020.md reference
- rename safe_relative_defect_ -> safe_relative_defect (free function in
  an anonymous namespace; the trailing underscore is the member
  convention); sync the plain-mixing contraction notes in the test
  (roughly 100 iterations at 0.8/step on the binding shell)

* feat(dfpt): give the E-field solve the density-space Broyden mixer under v_sc_broyden

Review follow-up (Critsium-xy): with the v_sc_broyden default, the
E-field solve (Z* / epsilon_inf / LO-TO) silently fell back to plain
density mixing at beta 0.4 -- the weakest member of the family exactly
on the path that matters most for polar systems. Map v_sc_broyden to
rho_broyden for DFPT_Rho (v_sc_plain keeps rho_plain), so the E-field
loop runs Modified Broyden on the density while the displacement loop
keeps its potential-space Broyden.

Verification (si, Gamma + dfpt_compute_q0/dfpt_loto, default INPUT so
the path is exercised through the mapping): E-field 3/3 directions
converge in 12 iterations (bit-identical residuals to an explicit
rho_broyden run) versus 38 with the previous plain fallback --
displacements unchanged at 13 iterations (v_sc Broyden); Gamma
frequencies and the LO-TO block reproduce the pre-change values
exactly. INPUT metadata documents that dfpt_broyden_ndim now sizes
both Broyden instances and that the E-field residual is always the
density residual.

* feat(dfpt): the two missing nlcc 2n+1 direct terms (QE dynmat_nlcc + dynmatcc)

The nlcc response was previously wired only through the SCF screening
channel (f_xc.(drho_val + drhoc) inside assemble_v_sc, QE dv_of_drho
semantics, verified line by line). QE ph.x adds two direct terms to the
force constants that have no wavefunction representation, and the bn_hex
isolation experiment (identical pseudos with the PP_NLCC block zeroed:
ABACUS vs QE optical rms 0.9 cm^-1 without nlcc, while the SCF-only nlcc
overshoots QE's nlcc effect by 4-12x with wrong signs on the A1/E2 soft
modes) shows they are the dominant cancellation partner of the screening
contribution:

- kernel term (QE dynmat_nlcc): D_ab += Omega/nrxx sum_r dvxc^a(r)
  conj(drhoc^b(r)) with dvxc^a = f_xc.(drho_val^a + drhoc^a) of the
  converged displacement a and the core response of every column b;
  dvxc^a is rebuilt in the two-pass accumulation loop from the newly
  stashed per-displacement density response plus a recomputed core
  response (the working slots hold the last solved displacement).
- diagonal term (QE dynmatcc): D_aa[i][j] += Int dr w_ij(r) v_xc^0(r)
  with w_ij the second-order shifted-core amplitude
  -tpiba^2 G_i G_j rhoc~(|G|) exp(-i G tau), evaluated through
  recip2real as a real field so the half-space G-sum convention never
  enters directly; v_xc^0 is the ground-state XC potential on the same
  valence+core density the kernel linearizes around, computed once in
  the esolver wiring (XC_Functional::v_xc) and delivered through the
  new DFPT_PW_InitContext::vxc_r provider (null disables the term).

Also: DFPT_Rho::compute_drhoc_g extracted as the pure core-response
builder (compute_drhoc keeps its data-slot semantics on top of it);
assemble_v_sc now takes the q index explicitly instead of reading the
drhoc slot through last_q_ (stale on the first assembly of a new q);
per-displacement density stash (set/get_drho_disp) mirrors the existing
v_sc stash.

Verification: MODULE_DFPT serial suite 9/9 (the new terms are inert
without nlcc pseudos); bn_cubic / bn_hex Gamma-vs-QE validation runs
attached in the PR.

* fix(dfpt): the working nlcc direct-term completion (validated on bn_cubic)

Three fixes over the first cut, pinned by the element-level matrix
comparison against QE dyn.G (bn_cubic: all blocks now agree to 2e-4,
TO frequencies to 0.007 cm-1):

- the per-q kernel table must fill EVERY displacement slot: rows of
  non-nlcc atoms need their dvaux too (f_xc applied to the valence
  response alone) -- leaving their slots empty silently dropped the
  entire one-sided cross-block X(N,B), the dominant mixed piece
- the effective Hermitian element is the symmetrized
  (1/2)(X_ab + conj(X_ba)) (QE dynmat_nlcc single ordering + final
  Hermitization); the earlier both-order full fill doubled the
  same-atom blocks, and the lower-triangle-only variant overshot the
  one-sided cross blocks
- the vxc provider must live in Impl-owned storage (the init context
  points at esolver stack state); the diagonal block is added once per
  atom (dir == 0)

* fix(dfpt): the core-response structure-factor phase was mirrored

compute_drhoc_g built the phase exp(+i(G+q).tau), which places the
first-order core density at the MIRROR site -tau instead of the atom
position tau (QE addcore: exp(-iG.tau) * exp(-i q.tau)). Every
validation so far was structurally blind to the sign: bn_cubic's B
sits at the origin (both conventions identical) and N carries no nlcc,
and the F2 numerical cross-check ran on the same blind system.

The bn_hex 16-block matrix comparison against QE dyn.G exposed it
element by element: with wurtzite B1=(1/3,2/3,1/4), the mirror of B1
lands exactly on N2=(2/3,1/3,3/4) and the mirror of B2 on N1, so the
mirrored core response produced spurious same-layer overlaps
((B1,B2)xx +0.053 vs the true 0.0013 interlayer scale) and lost the
real diagonal ones ((B1,B1)xx -0.105), collapsing the E2low interlayer
shear to -399 cm^-1 against QE's -29.8.

After the one-line conjugation, bn_hex stays bit-identical (B at the
origin) and bn_hex matches QE on every block to <= 2.5e-4 (B-involving)
with the optical rms dropping from 28.7 (C5, no core response) and
~60 (previous iterations) to 1.2 cm^-1; E2low recovers to -32.2 vs
-29.8 and the stiff modes to within 0.8 cm^-1.

* test(dfpt): nlcc phase-localization and fill-semantics regressions

Two-level regression suite replacing the temporary matrix dump (whose
diagnostic role -- the element-level QE comparison that pinned every
formula bug -- now lives as executable invariants):

Level 1 (dfpt_rho_serial_test): DrhocLocalizesAtTheAtomNotItsMirror.
An nlcc atom at the non-origin tau = (0.25, 0.31, 0.17) (the
anti-blind-spot position: every structure-factor phase is active) must
have its first-order core response |drhoc|^2 centroid AT the atom. The
mirrored phase exp(+i(G+q)tau) -- the bug every historical validation
missed because bn_cubic's B sits at the origin -- places it at the
mirror site instead. Includes a generic non-zero q variant.

Level 2 (dfpt_phon_serial_test): NlccDirectTermsFillSemantics. With a
synthetic all-slots kernel table and no dpsi (isolating the kernel
contribution from the bare cross term), the one-sided cross block must
carry exactly (1/2) conj(X_ba) (the symmetrized fill pinned by the
element-level QE comparison), and the accumulated matrix must stay
Hermitian. Together these guard against the three fill bugs fixed in
the parent commits (dead coreless rows, doubled same-atom blocks, and
the halved one-sided cross blocks).

The temporary DFPT_DUMP_DYN production block is removed (its commit
045f050 in the branch history retains the identical code for local
re-use during Project E matrix comparisons).

* fix(dfpt): C++11 aggregate: no default member initializer on InitContext

The vxc_r field carried a '= nullptr' default, which under C++11 makes
DFPT_PW_InitContext a non-aggregate; the 12-argument thin wrapper's
brace-init then fails to compile in the non-MPI / non-LCAO CI
configurations. Remove the default and pass nullptr explicitly as the
13th initializer in the wrapper.

* fix(dfpt): address review findings on the nlcc PR

P1 conjugation: the kernel contractions now conjugate the ROW response
(sum(conj(row)*col)), matching the wavefunction and Ewald terms; the
old unconjugated form flips the imaginary cross terms at nonzero q.
The fill-semantics regression test's independent recomputation is
updated to the same convention.

P1 pool reduction: the kernel and diagonal terms now normalize by
Omega/nxyz (the full grid, not the rank-local slab nrxx) and reduce
their products over the pool with Parallel_Reduce::reduce_pool behind
#ifdef __MPI guards (the mixing PR's convention).

Non-blocking: remove the leftover DFPT_DUMP_DYN production block;
extract the conditional setter arguments to named locals (AGENTS rule
14); tighten the mirror-distance assertions to minimum-image distances
that reject the reflected profile at any periodic image.

* fix(dfpt): address second-round review on the nlcc PR

P1 MPI participation (bot): the vxc provider now always passes a valid
pointer (never nullptr on an empty local slab), so every rank enters
accum_nlcc_diag's collective FFT/reduction path; the size checks
inside gate only the local work.

Rule 14 (bot): the gtau construction extracts cos(phase) and
-sin(phase) to named locals.

Formula comment (bot): dfpt_phon.h's class doc now states the
row-conjugated, pool-summed Omega/nxyz kernel convention, the
1/2-symmetrized fill, and the full-table f_xc.(drho_val + drhoc)
contract.

Phase-sensitive q test (bot): the generic-q drhoc check now also
verifies the G-space coefficient phase against the expected
exp(-i q_cart . tau_cart) via a dominant-G ratio between q and q=0,
catching a sign flip that the |field|^2 centroid is blind to.

Nonconstant diag oracle (bot): tracked as follow-up (the current
fill-semantics test targets the kernel path; a dedicated diag test
with an analytic vxc field is the next test addition).

* fix(dfpt): address third-round review on the nlcc PR

- compute_drhoc: early return for invalid/coreless atoms before the
  diagnostic iat2it indexing (public API safety)
- drho_disp stash: gated on nlcc_any, so coreless runs skip the
  3*nat*npw complex copies
- phase test: full TWO_PI-scaled phase reference with a tight 0.05-rad
  tolerance (both omission and reversal of exp(-i q.tau) are now
  rejected); ratio and trig arguments extracted to named locals
  (rule 14)
- set_dvxc_core_table comment: updated to describe the total-response
  f_xc.(drho_val + drhoc) table (not core-only)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

DFPT Density Functional Perturbation Theory Refactor Refactor ABACUS codes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants