Repository navigation
Feature(lr): add analytic Gamma-point auxiliary-TDA derivative couplings - #8324
Shane-Sayoko wants to merge 13 commits into
Conversation
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.
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.
ABACUS-PR-BOT
left a comment
There was a problem hiding this comment.
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.
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
left a comment
There was a problem hiding this comment.
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.
|
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 implementationFor distinct orthonormal excited roots, with Differentiating the TDA eigenvalue equation gives Ground-Excited state coupling (GE)In orthonormal orbital coordinates, a convenient constrained functional is Here
Excited-Excited state coupling (EE)
Polarizing the force (which is a quadratic form) gives Refactor comments
|
Reminder
AGENTS.mdanddocs/developers_guide/agent_governance.md.source/changes.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,$ABACUSand$HOST. The build reused the existing configured MPI/LCAO/LibXC toolchain.CLI checks were run from a valid LiH input directory:
The complete official-baseline-to-feature diff was staged in an isolated audit checkout and checked with:
Result summary:
NDEBUG, verifying that file writing still occurs when assertions are disabled.lr_grad_thrhelp correctly states that it applies only to NAC CG orbital-response solves.Checks not run, with reason:
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-lrsolver.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:
lr_nac_pairs0 1 1 2lr_nac_spinsingletsinglet,tripletor unrestrictedupdownchannellr_grad_thr1e-6Rylr_grad_maxiter100Surface zero denotes the ground state; positive indices denote LR roots. An empty pair list disables NAC calculations. The existing
lr_grad_solverselects 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 inHartree/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:
Input_Itemmetadata.docs/advanced/elec_properties/nacv.mdand its documentation index entry.lr_grad_thrcontrols NAC CG response only; it does not change ordinary LR analytic-force response controls.Core module impact:
module_lr/nacv_*.unittests/directories.Analytic NACV vs. Finite-Difference Results
1. Definitions and acceptance criteria
0–1denotes 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 FDis obtained by central differencing Slater-determinant overlaps between electronic states at different geometries.AO FDis 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 FDuses the independently evaluatedAO FD. No fitted state rotations or artificial renormalization are applied.|analytic − FD| ≤ 1e−5 + 0.001 × |FD|, inbohr⁻¹. 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.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
LC_PBELC_WPBELRC_WPBELRC_WPBEHTiO₂
CAM_PBEHThe 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₄.
LC_PBELC_WPBE4. 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.