Skip to content

Feature(lr): add analytic Gamma-point auxiliary-TDA derivative couplings - #8324

Open
Shane-Sayoko wants to merge 13 commits into
deepmodeling:developfrom
Shane-Sayoko:abacus-nacv
Open

Shane-Sayoko wants to merge 13 commits into
deepmodeling:developfrom
Shane-Sayoko:abacus-nacv

Conversation

@Shane-Sayoko

@Shane-Sayoko Shane-Sayoko commented Nov 17, 2026 •

Copy link
Copy Markdown

Reminder

  • I have read AGENTS.md and docs/developers_guide/agent_governance.md.
  • I have linked an issue or explained why this PR does not need one.
  • I have added adequate unit tests and/or case tests, or explained why not.
  • I have listed the exact verification commands run and their results.
  • I have described user-visible behavior changes, including INPUT parameter changes.
  • I have explained core-module impact for ESolver, HSolver, ElecState, Hamilt, Operator, Psi, or other source/ changes.
  • I have requested any needed governance exception below.

Linked Issue

No issue linked. This PR proposes a self-contained new capability for analytic nonadiabatic derivative couplings rather than fixing a tracked issue.

Unit Tests and/or Case Tests for my changes

  • Commands run:

    CPU/MPI verification was performed through Slurm using GCC 9.3.0, Intel MPI 2022.1, CMake 3.27.5 and LibXC 7.1.2. OpenMP and BLAS thread counts were set to one.

    The commands below abbreviate the recorded source, build, result, executable and compute-node paths as $SRC, $BUILD, $RESULTS, $ABACUS and $HOST. The build reused the existing configured MPI/LCAO/LibXC toolchain.

    cmake -S "$SRC" -B "$BUILD" "-DMPIEXEC_PREFLAGS=-hosts;$HOST"
    
    cmake --build "$BUILD" --parallel 24 --target \
      abacus_std_para \
      MODULE_IO_lr_nac_input \
      MODULE_LR_nacv_result \
      MODULE_LR_nacv_io \
      MODULE_LR_nacv_cg \
      MODULE_LR_nacv_factorization \
      MODULE_LR_nacv_xc_names \
      MODULE_LR_xc_kernel
    
    TEST_SELECTION='^(MODULE_IO_lr_nac_input|MODULE_LR_nacv_result|MODULE_LR_nacv_io|MODULE_LR_nacv_cg|MODULE_LR_nacv_cg_mpi4|MODULE_LR_nacv_factorization|MODULE_LR_nacv_factorization_mpi4|MODULE_LR_nacv_xc_names|MODULE_LR_xc_kernel|MODULE_LR_zeqlin_solv|MODULE_LR_zeqlin_failure_mpi|MODULE_LR_lr_util_phys_test|MODULE_LR_lr_util_algo_test|MODULE_LR_lr_util_pp|MODULE_LR_pot_grad_xc|MODULE_RI_invmat_ri)$'
    
    ctest --test-dir "$BUILD" --output-on-failure -V \
      -R "$TEST_SELECTION" --output-junit "$RESULTS/ctest.xml"

    CLI checks were run from a valid LiH input directory:

    "$ABACUS" --version
    "$ABACUS" --help lr_nac_pairs
    "$ABACUS" --help lr_nac_spin
    "$ABACUS" --help lr_grad_thr
    "$ABACUS" --help lr_grad_maxiter
    "$ABACUS" --check-input

    The complete official-baseline-to-feature diff was staged in an isolated audit checkout and checked with:

    git diff --cached --check
    python3 tools/03_code_analysis/agent_governance_check.py \
      --staged --format json
  • Result summary:

    • 15/15 selected CTest entries passed on this PR branch, including serial and four-rank MPI tests.
    • The focused NACV, INPUT and XC suites contain 55 distinct GoogleTest cases, excluding repeated MPI execution.
    • Eight new cases directly exercise production implementations:
      • NAC result assembly against the exact derivative coupling of a two-level avoided-crossing model.
      • Electronic-phase covariance of coupling vectors and numerators.
      • Non-diagonal CG response with multiple right-hand sides, independently known solutions, explicit residual verification and preservation of the input RHS.
      • Real and complex eigenstate serialization, writer-rank behavior and empty local amplitude windows.
    • The state-output test target explicitly defines NDEBUG, verifying that file writing still occurs when assertions are disabled.
    • Existing tests cover INPUT defaults and invalid values, complete orbital windows, occupations, raw/ETF conventions, unresolved gaps, CG convergence and iteration limits, repeated LU/Cholesky solves, distributed layouts and XC-kernel behavior.
    • All six CLI checks passed. The lr_grad_thr help correctly states that it applies only to NAC CG orbital-response solves.
    • Formatting, diff and governance checks passed.
    • Earlier LiH before/after regressions on the unchanged numerical implementation passed 32/32 paired comparisons. They covered RKS and explicitly unrestricted singlet references with LDA, PBE and B3LYP, LAPACK/CG response, distributed PBE solves and request-order independence. The system used a 1.5 Å bond, a 10 Å cubic cell and a 100 Ry cutoff. Electronic gauges were aligned independently through determinant overlaps.
  • Checks not run, with reason:

    • Full ab initio LiH regressions and independent finite differences were not repeated for the final test-only update; no numerical algorithm changed in that update.
    • The full repository regression suite, GPU builds and large periodic-system performance benchmarks were not run. Verification focused on the affected CPU/MPI LR and NAC paths.
    • General-k, noncollinear/SOC and spin-flip calculations are outside the implemented analytic NAC scope.

What's changed?

  • Adds analytic nuclear derivative coupling vectors between the ground state and a TDA excited state, and between two TDA excited states, for the real Gamma-point LCAO ks-lr solver.

  • Differentiates the auxiliary TDA determinant expansion constructed from KS orbitals and LR amplitudes. This definition differs from full quadratic-response TDDFT couplings.

  • Supports closed-shell spin adaptation and collinear unrestricted references. The unrestricted channel retains the reference M_S; it does not project onto a pure total-spin eigenstate.

  • Adds four INPUT parameters:

    Parameter Default Purpose
    lr_nac_pairs Empty Requested surface pairs, e.g. 0 1 1 2
    lr_nac_spin singlet singlet, triplet or unrestricted updown channel
    lr_grad_thr 1e-6 Ry Absolute true-residual tolerance for NAC CG response
    lr_grad_maxiter 100 Total NAC CG update limit, including correction restarts

    Surface zero denotes the ground state; positive indices denote LR roots. An empty pair list disables NAC calculations. The existing lr_grad_solver selects the response solver; direct solvers ignore the two CG controls.

  • Writes raw NACV, electron-translation-factor-corrected NACV, moving-AO connection terms and gap-weighted numerators to the existing running log. Vectors are reported in bohr^-1, gaps in Hartree and numerators in Hartree/bohr.

  • Determines gap resolution from explicitly reapplied LR-operator residuals and a roundoff bound. Unresolved pairs retain their numerators and carry an explicit unresolved flag; their zero divided vectors must not be interpreted as physical zero couplings.

  • Certifies CG convergence using the actual response-operator residual. Reuses response operators, dense matrices and factorizations across requested pairs, and caches geometry-fixed force intermediates within one geometry.

  • Requires integer occupations and complete occupied/virtual orbital windows. Fractional occupations, DFT+U and NLCC pseudopotentials are outside the implemented scope.

Governance Notes

  • INPUT/docs changes:

    • Parameter registration, defaults, help and validation are maintained in C++ Input_Item metadata.
    • Adds docs/advanced/elec_properties/nacv.md and its documentation index entry.
    • Generated parameter YAML and Markdown files were not manually modified.
    • lr_grad_thr controls NAC CG response only; it does not change ordinary LR analytic-force response controls.
  • Core module impact:

    • NAC algorithms, response solvers, geometry caches and output handling are concentrated in module_lr/nacv_*.
    • ESolver changes assemble explicit inputs, collect LR residual information while the operator is available, and dispatch the NAC batch. The ESolver class header remains unchanged.
    • LR force interfaces receive narrowly scoped hooks for NAC contractions and optional geometry reuse.
    • Shared changes include real LU wrappers, functional-alias resolution for response kernels and empty-local-grid XC-kernel handling.
    • HSolver retains the official implementation. No redesign of ElecState or Psi is introduced.
    • Geometry caches are local to one NAC batch. Configuration is passed explicitly, without new global workflow variables or private-access testing macros.
    • Tests use the existing GoogleTest/CMake/CTest workflow and reside in the corresponding flat unittests/ directories.
    • The separate HSE sigma-cutoff and chain-rule fixes are excluded from this PR. Ground-state XC cutoff rules remain unchanged.

Analytic NACV vs. Finite-Difference Results

1. Definitions and acceptance criteria

  • The tests validate nonadiabatic coupling vectors (NACVs) for real-valued auxiliary TDA/CIS wavefunctions at the Γ point. The pair 0–1 denotes S₀–S₁. For BC⁺, the pairs use the solver's root indices. Isolated states are aligned by a scalar phase. LiH has degenerate S₂ and S₃ states, so the tests use S₀–S₁ and S₁–S₄.
  • raw FD is obtained by central differencing Slater-determinant overlaps between electronic states at different geometries. AO FD is obtained from numerical derivatives of the cross-geometry AO overlaps and an independently evaluated Slater-determinant derivative with the electronic coefficients fixed at the reference geometry. ETF FD = raw FD − AO FD uses the independently evaluated AO FD. No fitted state rotations or artificial renormalization are applied.
  • The per-component criterion is |analytic − FD| ≤ 1e−5 + 0.001 × |FD|, in bohr⁻¹. The same tolerance form is used to check agreement between adjacent FD step sizes. Two step sizes, two state pairs, six Cartesian coordinates, and three quantities (raw, AO, and ETF) give 72 analytic–FD comparisons and 36 step-size checks. For the 12-atom TiO₂ cell, the corresponding counts are 432 and 216. Each listed step size is the displacement magnitude in bohr on either side of the reference geometry.
  • The Analytic–FD checks column counts individual comparisons within tolerance. Full acceptance also requires SCF convergence at the displaced geometries, electronic-state matching and phase alignment, and satisfaction of the FD step-size criterion.
  • All reported errors are absolute errors in bohr⁻¹. Each table specifies the step sizes used to obtain its maxima. The tolerance for an individual comparison depends on the corresponding |FD|.

2. MgO and anatase TiO₂ at 100 Ry

Both systems use closed-shell singlet TDA and the state pairs S₀–S₁ and S₁–S₂. The distorted two-atom MgO periodic cell has 28 AOs, 8 occupied orbitals, and 20 virtual orbitals, with six Cartesian coordinates tested. The 12-atom anatase TiO₂ periodic cell has 208 AOs, 48 occupied orbitals, and 160 virtual orbitals, with 36 Cartesian coordinates in the full test. The maxima below are taken over all completed comparisons at the listed step sizes and are reported in raw / AO / ETF order.

MgO
Functional h (bohr) Analytic–FD checks FD step-size checks Maximum error (raw / AO / ETF)
LDA 3.90625e-06 / 1.953125e-06 72/72 36/36 2.39433e-06 / 1.97701e-06 / 9.89849e-07
PWLDA 0.00025 / 0.000125 72/72 36/36 5.82139e-07 / 1.43165e-08 / 5.82187e-07
PBE 0.00025 / 0.000125 72/72 36/36 4.80928e-06 / 1.43797e-08 / 4.80933e-06
PBE0 0.00025 / 0.000125 72/72 36/36 1.16458e-04 / 2.81303e-09 / 1.16455e-04
HSE 0.00025 / 0.000125 70/72 36/36 1.21425e-02 / 2.64646e-09 / 1.21425e-02
LC_PBE 0.00025 / 0.000125 72/72 36/36 3.13647e-05 / 2.26502e-09 / 3.13639e-05
LC_WPBE 0.00025 / 0.000125 72/72 36/36 1.38721e-03 / 1.54515e-09 / 1.38722e-03
LRC_WPBE 0.00025 / 0.000125 72/72 36/36 4.58042e-04 / 1.33651e-09 / 4.58043e-04
LRC_WPBEH 0.00025 / 0.000125 72/72 36/36 2.68628e-03 / 1.0148e-08 / 2.68627e-03
TiO₂
Functional h (bohr) Analytic–FD checks FD step-size checks Maximum error (raw / AO / ETF)
PWLDA 0.00025 / 0.000125 432/432 216/216 6.26084e-04 / 2.83479e-10 / 6.26084e-04
PBE 0.00025 / 0.000125 432/432 216/216 7.43169e-04 / 2.8421e-10 / 7.43169e-04
HF 0.00025 / 0.000125 12/12 6/6 1.29033e-07 / 2.29534e-12 / 1.29032e-07
PBE0 0.00025 / 0.000125 432/432 216/216 8.76237e-04 / 7.90518e-10 / 8.76237e-04
B3LYP 0.00025 / 0.000125 432/432 216/216 7.91911e-04 / 5.90014e-10 / 7.91912e-04
CAM_PBEH 0.00025 / 0.000125 432/432 216/216 8.16031e-05 / 6.9882e-10 / 8.16032e-05

The TiO₂/HF test covered one Cartesian coordinate.

3. Closed-shell singlet LiH at 100 Ry

The Li–H bond length is fixed at 1.5 Å in a cubic box with a side length of 10 Å. The model has 12 AOs, 2 occupied orbitals, and 10 virtual orbitals. The tests cover all six Cartesian coordinates for S₀–S₁ and S₁–S₄.

Functional Analytic–FD checks FD step-size checks Maximum error at the finer step (raw / AO / ETF)
LDA 72/72 36/36 8.41687e-08 / 4.86442e-10 / 8.36822e-08
PWLDA 72/72 36/36 8.27297e-08 / 4.86487e-10 / 8.22432e-08
HF 72/72 36/36 4.00955e-08 / 4.33306e-10 / 3.97114e-08
B3LYP 70/72 34/36 7.52915e-05 / 4.82869e-10 / 7.5291e-05
LC_PBE 72/72 36/36 5.84194e-08 / 4.63546e-10 / 5.79558e-08
LC_WPBE 72/72 36/36 5.20881e-06 / 4.47155e-10 / 5.20893e-06

4. BC⁺ with UKS at fixed Mₛ = 1

The bond length is fixed at 1.469283924 Å in a cubic box with a side length of 10 Å. The calculation uses a 100 Ry cutoff and 26 AOs, with 4 α and 2 β occupied orbitals and 22 α and 24 β virtual orbitals. The tests cover all six Cartesian coordinates for root pairs 0–5 and 5–8. The FD step sizes are 0.0005 / 0.00025 bohr along the bond and 0.002 / 0.001 bohr perpendicular to it.

Root pair Maximum raw error Maximum AO error Maximum ETF error
0–5 8.67158e-05 1.44029e-09 8.67154e-05
5–8 2.17182e-04 7.00072e-10 2.17181e-04
  • Exceptions requested:
    • None.

Add reference-to-excited and excited-to-excited derivative couplings for real Gamma closed-shell and collinear unrestricted TDA references. Reuse LR force contractions and explicit Z-vector response controls; certify eigenpair and response residuals and write raw, ETF and AO-connection records to the existing running log.

Keep the independent HSE GS-response sigma-floor and LR-gradient sigma-clipping chain-rule fixes out of this review branch. No new physical correction or numerical-error investigation is included.

Keep dependencies explicit, name computed arguments, document units and ownership, and place focused tests in module unittests directories. Header additions provide complete result/container types or standard parameter declarations; existing declarations remain forward-declared where possible. Generated INPUT reference files and integration validation_tools are unchanged.

Validation on para Slurm: build and 12 selected CTest entries passed in 8879069.254. Governance, changed-line formatting, git diff --check, exclusion checks for the HSE repairs, and six version/help/check-input checks passed in 8879069.255. No new electronic-structure or finite-difference calculation was run for this separation; earlier HSE results from repaired snapshots do not certify this branch. Prepared for manual review.
Move reference validation, root preparation, residual reporting, pair iteration and NAC output into module_lr/nacv_workflow. Remove ESolver's public cal_nac method and persistent residual cache; restore esolver_lr_lcao_tddft.h to the official baseline. Keep only explicit data wiring and operator-lifetime hooks in runner. Extract full-precision LR eigenstate output into a shared I/O helper and make its existing print dependency self-contained.

Preserve force/Z-vector/ETF contractions, INPUT parameters, output filenames and GS density cutoffs. No HSE cutoff repairs are included in this branch. The read-only ground density is prepared once per geometry; each pair retains its own force evaluator.

Validation on para Slurm: 12 related CTest entries and six CLI checks passed, together with governance and changed-line formatting checks. LiH neutral singlet RKS/UKS with LDA, PBE and B3LYP passed all six before/after regressions; independent determinant overlaps fix electronic phases and degenerate blocks without fitting NAC. RKS uses roots 1/4 and UKS uses isolated roots 2/8. No FD was performed; no tolerance was relaxed. Native UKS/B3LYP cold-start XC failure was avoided with a common converged restart, without changing XC code.

Across both maintained branches: 12/12 cases, 5946 scalar checks passed; maximum raw/ETF NACV differences are 7.62e-13/7.86e-13 bohr^-1. Evidence: test/NACV_Refactor_20261116 on local and para workspaces.

No user documentation update is required: input, physical definition and output contract are unchanged; internal interfaces and borrowed lifetimes are documented with Doxygen. Header additions provide directly used stream, standard-container and distributed-layout definitions.
Move certified CG and Z-vector dispatch into nacv_cg/nacv_response, residual collection into nacv_workflow, full-precision state output into nacv_io, functional aliases into nacv_xc_names and INPUT registration into module_parameter/nacv_input. Restore nine pre-existing LR/ESolver files to the official 173620a (v3.11.0-beta13) implementation and keep esolver_lr_lcao_tddft.h unchanged. Retain only data wiring, operator-lifetime hooks, input/build registration and shared force/XC interfaces required to reuse the physical implementation.

Validate INPUT at its boundary and computed reference assumptions once per NAC batch; remove repeated internal defensive checks. Keep explicit convergence dependencies, C++11 interfaces, module unittests and existing running-log output. Ordinary LR response solvers follow the official path; certified response controls are NAC-only. Ground-state XC density cutoffs and HSE sigma repairs are not changed in this branch.

Validation on para Slurm: 12 related CTest entries, governance, changed-line formatting, diff checks and six CLI/input checks passed. LiH singlet RKS/UKS x LDA/PBE/B3LYP x lapack/CG passed all 12 before/after configurations on this branch; both maintained branches total 24/24 configurations, 84 state-pair comparisons and 11,892 scalar checks. Independent full-determinant overlaps determine electronic phases/degenerate blocks, without NAC fitting, normalization, FD or tolerance relaxation. Maximum raw/ETF vector differences are below 8e-13 bohr^-1. Frozen original UKS restart data avoid the existing cold-start XC issue.

Evidence and exact source/binary hashes: test/NACV_Isolation_20261116 on the local and para workspaces. Parameter metadata and NAC documentation describe the NAC-only controls; generated parameter documents are not edited.
Own response operators and one dense factorization per NAC geometry batch, reusing LU or symmetrized Cholesky factors for subsequent right-hand sides. Keep matrix-free CG and reuse its already successful true-residual certification instead of applying the unchanged operator twice at exit. The update-limit path still explicitly certifies the response with the original tolerance and iteration budget.

Cache overlap/kinetic derivatives, local potential and ground-state potential lazily in nacv_force. Share them with existing force contractions through a narrow read-only geometry view. Keep caches local to run_nac_requests, preserve separate GS/LR XC purposes, and avoid global configuration or ESolver changes. Shared implementation changes are limited to lr_force.cpp/h and missing real ScaLAPACK LU connector overloads, plus build registration. Force formulas, INPUT defaults, orbital windows, output filenames and GS density cutoffs remain unchanged. HSE sigma repairs are excluded from this branch.

Validation on para Slurm: LiH 1.5 A / 10 A box / 100 Ry, singlet RKS and explicit Ms=0 UKS, LDA/PBE/B3LYP, LAPACK/CG, two paired repetitions per configuration. Across both maintained branches all 48 primary before/after comparisons passed. Additional PBE distributed LU/Cholesky and reversed pair-order checks passed 8/8 each; total 128 program runs and 64 paired comparisons. Independent full-determinant overlaps set electronic gauge without fitting NAC, FD, normalization or tolerance changes. Maximum checked raw/ETF differences remain below 1e-12 bohr^-1.

On the same eight physical CPUs, within-worker ABBA timings showed NAC batch speedups of 1.058-2.026x, geometric mean 1.423x; full-program geometric mean 1.115x. Four workers share each reserved node and two observations per version are reported without confidence-interval claims. All 24 NAC benchmark configurations were faster. Detailed timings, RSS and source/binary hashes are saved under test/NACV_Reuse_20261116 in the local and para workspaces.

Fourteen related CTest entries passed, including repeated factorizations with varying RHS counts, zero-storage MPI ranks, singular/indefinite failures and CG application counts. Governance, formatting, diff and six CLI/input checks passed. No new user-facing parameter or physical-definition change requires generated parameter documentation.
@Shane-Sayoko Shane-Sayoko changed the title Abacus nacv Feature(lr): add analytic Gamma-point auxiliary-TDA derivative couplings Nov 17, 2026
Keep geometry-local requests, force intermediates and response operators in nacv.cpp/nacv.h. Group certified response solvers, result assembly, XC name helpers and state output in nacv_tools.cpp/nacv_tools.h. Preserve the actual solver, result, output and XC unit cases under matching test names.

Validation on para Slurm 8879069: 17 affected CTest entries passed; LiH RKS/UKS with LDA, PBE and B3LYP passed all 8 original-vs-consolidated comparisons, including PBE CG. Original numerical and residual tolerances are unchanged; no FD was run. The companion HSE branch passed its corresponding 8 comparisons and 18 CTest entries.

Restore the original ASE solver fixtures: selecting ScaLAPACK did not resolve the CI failure matching existing issue deepmodeling#7794. Both official and NACV binaries pass the Si reference locally on para with LibXC disabled and enabled.

No INPUT, output format or documented physical approximation changes; no user-document update is required for this structural refactor.
@mohanchen mohanchen added EXX/lr-TDDFT/RPA/BSE/GW Related to beyond DFT methods Refactor Refactor ABACUS codes Compile & CICD & Docs & Dependencies Issues related to compiling ABACUS labels Nov 17, 2026

@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.

Three source-backed issues need attention: deferred root bounds, filtered state export, and the accepted Hartree-disabled configuration. The remaining comments are nonblocking.

Static review at 0885ecd3950670700190f898bbc82198d969a94b: whitespace and governance checks completed with no blockers and 12 header-dependency warnings, assessed individually. No builds, runtime tests or CI results were verified; LiH comparisons remain author-reported. Full interacting numerical accuracy, the documented HSE approximation and MPI failure cleanup remain unverified.

Comment thread source/source_lcao/module_lr/nacv.cpp Resolved
Comment thread source/source_lcao/module_lr/nacv.cpp Resolved
Validate resolved roots and require Hartree in the reference. Preserve all state coefficients, report completed files, and propagate MPI write failures before gathering log messages. Reuse LR functional definitions and add independent LiH overlap regression coverage.

@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.

The earlier bounds, Hartree and state-export defects are addressed in source. One conditional test-file collision remains; the original threads also contain the two nonblocking follow-ups.

Static incremental review at 0db7ee1ddea96e2a0e0ddd8c505c33062622be60; no builds, tests or CI results were independently verified. The author identifies this SHA for the reported runs. The external finite-difference generator remains unavailable, although the checked-in values and material hashes are internally consistent. git diff --check failed on trailing whitespace in the four imported material files.

@mohanchen
mohanchen requested a review from maki49 November 19, 2026 08:50
@maki49

maki49 commented Nov 22, 2026

Copy link
Copy Markdown
Collaborator

I read the real Gamma-point LR-TDDFT (TDA) NACV implementation with the help of AI, summarize the core formula-code correspondence as follows and give some refactor suggestions from my point of view.

Core formulas and their implementation

For distinct orthonormal excited roots, with $\Delta_{IJ}=\Omega_J-\Omega_I$, as a starting point the NACV writes

$$ d_{IJ}^{x,\mathrm{raw}} =\langle\Phi_I|\partial_x\Phi_J\rangle =X_I^{\mathsf T}\partial_x X_J +\sum_{ia,jb}X^I_{ai}X^J_{bj}\langle\Phi_i^a|\partial_x\Phi_j^b\rangle . $$

Differentiating the TDA eigenvalue equation gives $X_I^{\mathsf T}(\partial_x A_{\rm can})X_J/\Delta_{IJ}$ for the first term when the gap is resolved. In the real orthonormal spin-orbital basis, the Slater–Condon contraction for the second term is $\delta_{ij}\tau^x_{ab}-\delta_{ab}\tau^x_{ji}$, with $\tau^x_{pq}=\langle\phi_p|\partial_x\phi_q\rangle$. This form makes the particle and hole signs explicit.

Ground-Excited state coupling (GE)

In orthonormal orbital coordinates, a convenient constrained functional is

$$ \mathcal L_{0J}=Q_{0J}+Z_{0J}^{\mathsf T}g_{\rm GS}, \qquad Q_{0J}=-\Omega_J^\star\langle\Phi_J^\star|\Phi_0(C,R)\rangle . $$

Here $g_{\rm GS}$ is the occupied–virtual projection of the KS stationarity residual $FC-SC\epsilon$. The star denotes quantities frozen at the reference geometry. Moving the derivative onto the reference determinant by orthogonality gives $\mathrm dQ_{0J}/\mathrm dx=\Omega_J d_{0J}^{x,\mathrm{raw}}$.

  • For the ordinary LR force, the differentiated scalar is $X^{\mathsf T}AX$ with the usual normalization and orbital constraints. For GE the scalar is $Q_{0J}$, whose occupied–virtual rotation derivative is $-s\Omega_J X_J$. Thus stationarity gives $L_{\rm GS}Z_{0J}=s\Omega_J X_J$. The same ground-state Hessian is used by the force code (Z_vector_L/UL). ground_adjoint() builds the GE right-hand side directly, with $s=\sqrt{2}$ for a closed-shell singlet and $s=1$ for unrestricted spin blocks. Closed-shell GE triplet coupling vanishes. GE right-hand side
  • With the independent occupied–virtual rotations fixed ($U^x_{vo}=0$ for the explicit derivative), the derivative of $Q_{0J}$ projects the one-sided moving-AO overlap $\beta^x_{\mu\nu}=\langle\chi_\mu|\partial_x\chi_\nu\rangle$ onto the transition density. Write $S^x=\beta^x+(\beta^x)^{\mathsf T}$ and $\mathcal A^x=(\beta^x-(\beta^x)^{\mathsf T})/2$. With $D^{0J}=sC_vX_JC_o^{\mathsf T}$ (summed over spin blocks for unrestricted orbitals), $\delta W=(\Omega_J/2)\text{sym}(D^{0J})$, and $M^x=(\partial_x g_{\rm GS})_\theta$, the numerator is

$$ \begin{aligned} \Omega_J d_{0J}^{x,\mathrm{raw}} &=\frac{\mathrm dQ_{0J}}{\mathrm dx} =\partial_x\mathcal L_{0J}\\ &=Z_{0J}^{\mathsf T}M^x \underbrace{-\text{Tr}(\delta W S^x) +\Omega_J\text{Tr}(D^{0J}\mathcal A^x)} _{(\partial_x Q_{0J})_\theta}. \end{aligned} $$

evaluate_closed_shell_force() or evaluate_open_shell_force() at zero amplitude supplies $-Z_{0J}^{\mathsf T}M^x$ in force convention. The extra cal_force_overlap_edm() call supplies $+\text{Tr}(\delta W S^x)$ in the same convention. Negating their sum gives the ETF numerator. antisymmetric_ao_connection() supplies the AO term in units of inverse length, which is added to the ETF coupling to obtain the raw coupling. In numerator form this adds $\Omega_J\text{Tr}(D^{0J}\mathcal A^x)$. GE force and overlap calls

Excited-Excited state coupling (EE)

evaluate_aux_tda_nac() forms $X_\pm=(X_I\pm X_J)/\sqrt2$. solve_polarized() builds the usual LR force right-hand sides for these trial vectors and solves the same ground-state response equation for $Z_\pm$. Both force calls use $\bar\Omega_{IJ}=(\Omega_I+\Omega_J)/2$, the common Rayleigh quotient of $X_\pm$. This parameter enters the force and EDM contraction after the Z solve. In a general configuration basis the symmetric metric term contributes $+\tfrac12 S_\chi^x$ to the connection. Combining it with the $-\Omega_J S_\chi^x$ numerator term gives $-\bar\Omega_{IJ}S_\chi^x$, where $S_\chi$ is the configuration overlap.

Polarizing the force (which is a quadratic form) gives $N_{IJ}^{x,\mathrm{ETF}}=-(F_+^x-F_-^x)/2=c_I^{\mathsf T}(H_\chi^x-\bar\Omega_{IJ}S_\chi^x)c_J+\Delta_{IJ}c_I^{\mathsf T}C_{\rm orb}^xc_J$, where $C_{\rm orb}^x$ is the configuration connection induced by orbital rotations. The antisymmetric AO contribution is computed separately, so for a resolved gap $d_{IJ}^{x,\mathrm{raw}}=N_{IJ}^{x,\mathrm{ETF}}/\Delta_{IJ}+\text{Tr}(D^{IJ}\mathcal A^x)$. A short comment near the two force calls could make this decomposition easier to follow. EE force calls · Result assembly

Refactor comments

  • XC name normalization. Could canonical_xc_name() live in a shared LR/XC utility? Both kernel_pots.cpp and NAC validation use the same alias mapping. Moving it out of nacv_tools.h would remove the general LR kernel setup's dependency on NAC tools. LR caller

  • Force geometry. NacvForce adds ownership and lazy preparation of shared intermediates. Could LR_Force provide explicit preparation for a fixed-geometry batch and own the backing storage, so the virtual cache hook and subclass can be removed? ForceGeometry currently borrows its data. The batch lifetime should cover both the geometry and the reference density used to build the cached ground-state potential. The AO connection needs read-only access to the overlap derivatives. Preserve the ordinary on-demand force path and ensure any lazy preparation involving collectives is entered on every rank. Cache preparation

  • Split the NAC implementation by responsibility. Keep the ESolver-facing request types, collect_nac_eigenpairs() and run_nac_requests() in nacv.h. ESolver collects residuals while the excitation operator is still available. The pair workflow then follows this call chain.

    ESolver_LR::runner()
      -> LR::collect_nac_eigenpairs()  (while the LR operator is available)
      -> LR::run_nac_requests()
           -> evaluate_nac_pair()
                -> evaluate_aux_tda_nac()
                     GE: ground_adjoint() -> NacvResponse::solve()
                     EE: NacvResponse::solve_polarized() -> solve()
                          -> NacvResponse::Impl::solve_with()
                               -> solve_nac_cg() or cached direct solve
    
    • Keep evaluate_nac_pair(), evaluate_aux_tda_nac() and their workflow helpers in nacv.cpp.
    • NacvResponse and Impl could move to an internal header and source file. Keep the GE right-hand-side construction close to the GE branch, or expose a named GE response entry point if it moves with the response implementation.
    • Group pair_density_ao(), ground_density_ao() and nac_density_ao() with the AO connection calculation to anothor .cpp file. Keep local helpers private where possible. sparse_density() also serves the GE overlap correction, so it may need a narrow shared interface.
  • Separate the solver code from the other NAC utilities. Move solve_nac_cg() and NacvFactorization out of the diagnostics and I/O utilities. Compare their LAPACK/ScaLAPACK and CG paths with the existing LR Z-vector solvers before extracting shared code. Preserve the split between factorization and repeated solves and the MPI layouts. The NAC CG wrapper has its own tolerance and iteration controls and recomputes the true residual during iterations, so sharing that wrapper with the force path deserves a separate review.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Compile & CICD & Docs & Dependencies Issues related to compiling ABACUS EXX/lr-TDDFT/RPA/BSE/GW Related to beyond DFT methods Refactor Refactor ABACUS codes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants