Repository navigation
feat(dftu): add AMF and fixed-alpha mixing for the Full projector - #8359
rimujiangshu wants to merge 6 commits into
Conversation
Related to deepmodeling#8281. Preserve the existing default FLL path and add focused Full-projector DC, input, operator tests and documentation.
Keep both INPUT test registrations, follow the flat unit-test layout, and adapt AMF/mixed export guards to renamed upstream parameters without restricting legacy FLL. Verified 38 registered CTests and hamilt_lcao/abacus_input_yaml builds.
ABACUS-PR-BOT
left a comment
There was a problem hiding this comment.
One INPUT failure-path defect and three nonblocking suggestions remain. This was a static source and algebra review; no builds, numerical/MPI runs or CI diagnostics were performed, and the reported validation remains author-reported.
Non-blocking: Please add the exact feature SHA used for the earlier SCF comparisons and the values of DFTU_IO_TARGETS, DFTU_IO_TEST_REGEX and MERGE_TEST_REGEX (or explicit target/test lists). The upstream base SHA and command forms alone do not identify the tested feature revision or reproduce the reported 32/38-test selection.
| item.description = "Explicit finite weight in [0,1] for dftu_dc=mixed. Zero gives AMF and one gives FLL. Not accepted for other DC modes. This weight is fixed, not determined self-consistently."; | ||
| item.domain.scalar(); | ||
| item.read_value = [](const Input_Item& item, Parameter& para) { | ||
| para.input.dftu_alpha = parse_dftu_alpha(item.str_values.at(0)); |
There was a problem hiding this comment.
Finite out-of-range values such as dftu_alpha 1.1 pass this scalar domain and then throw uncaught from parse_dftu_alpha during rank-zero prepare_input(), before input_error is broadcast. This bypasses the normal INPUT diagnostic path while the other ranks wait in that broadcast. Please register the [0,1] domain constraint (or return the range error through prepare_input) and add a four-rank invalid-alpha reader case.
There was a problem hiding this comment.
Fixed in 0f2cb7c. The scalar domain now registers value>=0 and value<=1 before the rank-zero read_value callback. Added four-rank reader cases for -0.1, 1.1, nan and 0.5junk; all require exit 1, the INPUT diagnostic and all four shutdown markers. The original 1.1 failure was reproduced as exit 134 before the fix. All four cases and the full selected 42-test suite pass locally; accepted input values/default FLL are unchanged.
There was a problem hiding this comment.
Source review at 0f2cb7c0 confirms that the range error is addressed: [0,1] validation now returns a diagnostic before read_value, allowing the existing input_error broadcast to handle it. The four new reader cases require exit code 1 and all four shutdown markers. This was a static review; I have not independently verified the reported test or CI results.
| { | ||
| SCOPED_TRACE(modes[mode]); | ||
| SCOPED_TRACE(weights[mode]); | ||
| module_dm::DensityMatrix<TK, double> dm(paraV, nspin, nspin); |
There was a problem hiding this comment.
Non-blocking: This constructor creates one Gamma point per spin, and the DMK entries below are real, so the complex-density test does not exercise nontrivial multi-k phases. Add a small conjugate ±k case with nonzero R and complex Hermitian DMK, comparing the projected occupation, Hamiltonian contribution and energy against an independent contraction.
There was a problem hiding this comment.
Added in 0f2cb7c as DFTUTest.FullDcConjugateKDensityAndHamiltonian: conjugate +/-0.23 k points, nonzero +/-1 R blocks and complex Hermitian DMK, feeding the production DMK-to-DMR, occupation/reduction, Full DC, H(R) and H(k) routines. Occupation, potential/energy, every local H(k) entry and the density-Hamiltonian trace are checked against an independent direct k-space contraction for alpha=0/0.35/1, including reset/rebuild. Passes with 1, 2 and 4 MPI ranks. Neighbors/overlaps are explicit fixtures, not a claim of radial-integral/neighbor-search or SCF coverage; existing operator dispatch tests remain.
There was a problem hiding this comment.
The new conjugate ±k fixture addresses the phase-coverage request. Non-blocking: Please register a four-rank CTest entry filtered to DFTUTest.FullDcConjugateKDensityAndHamiltonian, with PROCESSORS 4, a timeout and OMP_NUM_THREADS=1. AddTest launches the binary directly, so normal CTest still uses one rank; an MPI entry would preserve the cross-owner regression in routine testing.
There was a problem hiding this comment.
Implemented in f40582a. The only change is nine lines in source/source_lcao/module_dftu/unittests/CMakeLists.txt.
MODULE_DFTU_op_conjugate_k_mpi4 now launches the existing MODULE_DFTU_op executable through the configured MPI launcher with four ranks, forwarding MPIEXEC_NUMPROC_FLAG, MPIEXEC_PREFLAGS and MPIEXEC_POSTFLAGS, and filtering to DFTUTest.FullDcConjugateKDensityAndHamiltonian. It sets PROCESSORS 4, TIMEOUT 120, and OMP_NUM_THREADS=1, inside the existing MPI/LCAO guards. No production sources, default FLL behavior, test assertions or tolerances were changed.
Built MODULE_DFTU_op and MODULE_DFTU_full_dc on an allocated CPU compute node, then ran:
ctest --test-dir build -V -j 4 --no-tests=error \
-R '^(MODULE_DFTU_full_dc|MODULE_DFTU_op|MODULE_DFTU_op_conjugate_k_mpi4)$'Result: 3/3 registered CTests passed, with no failures or skips. The full verbose log confirms four distinct MPI ranks and four successful executions of the filtered test. The post-test log checker initially encountered CTest's 1024-byte JUnit output truncation; the complete log was checked instead, without rerunning or changing the tests. No SCF calculation was run. This is focused compute-node validation, not a claim that the newly triggered upstream CI has already completed.
| const T nij = occupation[i * dimension + j]; | ||
| const T nji = occupation[j * dimension + i]; | ||
| if (!std::isfinite(std::real(nij)) || !std::isfinite(std::imag(nij)) | ||
| || std::abs(nij - std::conj(nji)) > 1.0e-10) |
There was a problem hiding this comment.
Non-blocking: Please assign nij - std::conj(nji) to a named local before passing it to std::abs. Current root AGENTS.md rule 14 requires computed arguments to be named, and the residual would then be directly inspectable when an occupation is rejected.
There was a problem hiding this comment.
Updated in 0f2cb7c: the computed difference is stored in hermiticity_residual before std::abs. The formula and 1e-10 Hermiticity threshold are unchanged. The focused Full DC tests and selected 42-test suite pass locally.
|
Follow-up to the review: all four points have been addressed for commit
The review fix passed 42/42 selected local CTests, with zero failures or skips. The upstream CI round for the current commit has also passed, including ASE: both previously failing Si tests ( Could a maintainer please re-review the updated commit and confirm whether the three inline threads can be resolved? They remain open for review; the replies are not a claim of reviewer approval. |
There was a problem hiding this comment.
I would suggest not adding DFTU-related check in module_parameter, otherwise the module will become huge if every parameter is checked in this way (more source files will be added). Adding the checks in DFT+U module may be another choice?
There was a problem hiding this comment.
Thanks for the suggestion. Moved dftu_dc_check.{h,cpp} to source/source_lcao/module_dftu under DFTU_LCAO in a86d6c1. module_parameter now only calls the check at the existing INPUT stage, after resets. The validation conditions, diagnostics and default FLL behavior are unchanged.
The dependency-light checker remains compiled through the unconditional io_input object target, so disabling LCAO does not remove INPUT validation or require linking the LCAO operator library. The serial-reader and legacy Makefile source references were updated as well.
Verified on a CPU compute node: 25 selected INPUT CTests passed, including the four-rank default/explicit FLL, AMF, mixed endpoints and invalid-alpha reader cases. In addition, the four serial INPUT test targets passed with LCAO disabled, and again with both MPI and LCAO disabled; abacus_input_yaml built and ran in all three configurations. No INPUT metadata/documentation change is needed because there is no user-facing behavior change. No SCF was run.
|
|
||
| namespace DFTU_LCAO | ||
| { | ||
| struct FullDcEnergy |
There was a problem hiding this comment.
it would be simpler if we don't use the struct, and put the two variables to related classes?
There was a problem hiding this comment.
Thanks. Removed FullDcEnergy in 93ab9d4. The helper now returns the interaction energy as a double and supplies the band correction through an explicit output reference. The Full operator continues to accumulate that correction in its existing u_energy/set_energy path; no additional persistent energy members are needed. The interaction value remains available to the derivative and energy-ledger tests without adding unused class state.
The numerical expressions, operation order, potential layout and legacy FLL branch are unchanged. All callers and tests were adapted; the tests also check that invalid inputs leave both output arguments unchanged and that zero-U/repeated calls do not retain an old correction. Existing references and tolerances were not relaxed.
Verified this exact revision on a CPU compute node: production dftu and hamilt_lcao targets built; 43 selected CTests passed with no failures/skips, including MODULE_DFTU_op_conjugate_k_mpi4 (all four ranks passed). The selection was:
ctest --test-dir build -V -j 4 --no-tests=error -R '^(MODULE_DFTU_(pots|energy|op_legacy|for_r|str_r|folding|fs_r|fs_reduce|fs_k|fs_accum|op|ijr|base_io|full_dc|op_conjugate_k_mpi4)|MODULE_IO_(read_item_serial|input_domain_reader|dftu_dc_check|read_inp_exx_dftu|libxc_r_suffix|frame_append|provenance_header|input_error_mpi_.*))$'OMP_NUM_THREADS=1 was used. No SCF or installation was performed. These are internal-interface changes, so the existing user documentation remains applicable. Both discussions are left open for your confirmation.
Linked Issue
Related to #8281.
What's changed?
Add AMF and fixed-alpha FLL/AMF interpolation to the existing Full DFT+U projector (
dft_plus_u=1, controlled byonsite_radius), while preserving FLL as the default.dftu_dc = fll | amf | mixed.dftu_alphain[0,1]formixed.alpha=0for AMF andalpha=1for FLL.Here, Full refers to the existing radius-adjustable localized projection with simplified
U_eff=U-J. This PR does not introduce an anisotropic U/J functional, another projector, Dual modifications or SOC support.Functional and compatibility
For each atom and spin channel, with
N = Tr(n)andM = 2l+1:AMF uses the orbital average within each spin channel, without additional normalization of the existing projected occupation. The band-energy correction remains
E_alpha - ReTr(V_alpha*n), evaluated at the same occupation as the potential.For
nspin=1, the existing per-spin occupation convention is retained: the shell energy is doubled, but the potential is not. Fornspin=2, each spin-channel contribution is accumulated once.Omitting the new parameters or explicitly selecting
dftu_dc fllretains the existing FLL potential and energy implementation. Additional AMF/mixed scope guards do not restrict legacy FLL requests.Example additions to a valid Full DFT+U input:
The new modes support double-precision CPU/LCAO, explicit PBE, collinear fixed-structure KS SCF, one k pool, one band group, atomic cold starts and
symmetry=0/-1. Unsupported combinations, including SOC, force/stress, restart/occupation initialization, occupation/DMR mixing, Yukawa U, U-ramping, EXX and guarded matrix exports, are rejected explicitly. These guards also apply to mixed endpoints.Unit Tests and/or Case Tests for my changes
Results below cover the selected tests and stated SCF configuration, using the frozen candidate based on upstream
f5315651166ea265ba673996e3c9efeb5e4cd9b0.The CTest selection includes energy-potential finite differences with trace-changing and off-diagonal perturbations, spin-factor and production-operator checks, and INPUT round-trip/MPI parameter tests.
SCF comparisons used CrI3,
nspin=2, a2x2x1k mesh,U_eff=2 eV, 100 Ry,genelpa,scf_thr=1e-9and at most 500 iterations. Runs used four MPI ranks on distinct physical cores with single-threaded math libraries. Energy and gap comparison thresholds were1e-7 eV/celland1e-6 eV, respectively. Reported equality refers to the recorded output precision.Recorded command forms, with paths and the selected test expression represented by variables:
DFTU_IO_TEST_REGEXselects the 32 registered tests above.CHECKED_MPIis the validation harness's binding-checked launcher. Each SCF configuration was run in a separate case directory.Implementation notes
DFTU_onsiteoperator with explicit immutable DC configuration.Upstream merge validation (2026-11-21)
Merged
developat153ad6290f95578d6ef97a719939b63d76ad4e99, preserving the original feature commit.unittests/, retaining its serial compilation scope and assertions.Fresh verification in the project's CPU
abacus-gnuimage (GCC 11.4.0, Open MPI 4.1.2;OMP_NUM_THREADS=1,OPENBLAS_NUM_THREADS=1):hamilt_lcaoandabacus_input_yamlbuilt successfully.git diff --check upstream/developpassed; governance has no blockers. The four standard-header include advisories are required by the declared string/vector/complex types and owned configuration members.DFTU_IO_TARGETSbuilds the selected DFT+U/INPUT executables.MERGE_TEST_REGEXextends the original 32-test selection withMODULE_IO_libxc_r_suffix,MODULE_IO_frame_append,MODULE_IO_provenance_header, and the threeMODULE_IO_input_error_mpi_out_*_zero_precisioncases.No SCF calculations were rerun for this merge; the SCF comparisons above remain attributed to the frozen candidate and configuration stated there.
Review follow-up: INPUT failure handling and phase coverage
Implemented in
0f2cb7c0225faccd75d30f36abac6376fd8f1922(tested tree4586b5c98a5f6c686814a82e41edbf31aeb5756b).Fresh local CPU validation: 42/42 registered CTests passed, zero failures
and zero skips, including the four new four-rank INPUT cases. The conjugate-k
test passed with 1 rank through CTest and separately with 2 and 4 MPI ranks.
hamilt_lcaoandabacus_input_yamlbuilt, and the generated alpha metadatacontains the
[0,1]value rule. Toolchain: GCC 11.4.0, Open MPI 4.1.2, officialabacus-gnuimage digestsha256:ee3101aea0e50813e2e408cb857e29ca9ea774da5a9b8c8d65b87cb7dd77799d,with single-threaded math/runtime settings. These are local results, not a
claim that the new GitHub CI or scientific SCF regressions have completed.
No SCF was rerun for this review fix; the earlier SCF evidence remains tied to
the exact historical revision below.
The alpha reader now registers
value>=0 and value<=1with the existing scalardomain validator. Invalid values are rejected before the rank-zero reader
callback, so the diagnostic follows the existing
input_errorbroadcast andnormal INPUT shutdown path. The direct parser's defensive checks remain.
There is no change to accepted values, DC defaults, the FLL implementation,
the functional, or numerical tolerances.
Four new registered reader cases use four MPI ranks each: alpha
-0.1,1.1,nanand0.5junk. They require exit code 1, the parameter/input-file/manualdiagnostic and all four reader shutdown markers, not merely a nonzero exit.
They extend the existing INPUT unit-test harness because a numerical Autotest
reference does not check per-rank failure-path shutdown.
DFTUTest.FullDcConjugateKDensityAndHamiltonianadds conjugate k points(+/-0.23,0,0), R=0,+/-1 atom blocks and complex Hermitian DMK with k weightsand spin degeneracy included. It connects production DMK-to-DMR, Full
occupation contraction/reduction, DC potential/energy, H(R) assembly and H(k)
folding. It compares against an independent direct k-space projector
contraction for alpha=0,0.35,1 and checks the density-Hamiltonian trace and
reset/rebuild behavior. Neighbors and overlaps are explicit fixtures: this is
not a test of neighbor search, radial integrals or a new SCF benchmark.
Existing operator-construction/dispatch and default-FLL tests are retained.
The Hermiticity residual is now a named local before
std::abs, with the samearithmetic and rejection tolerance.
No documentation update required for the manual INPUT reference:
[0,1]wasalready the documented contract. The new domain rule updates the registered
metadata used to generate the reference; generated YAML/Markdown artifacts
are not committed.
Exact historical verification identities and selections
The earlier SCF comparisons and 32 CTests used the frozen source tree
ee8ef1e9099bc81ae39eb0cc74665c0fc5b02ca2, subsequently published unchanged asfeature commit
3e3bcf2eec187e60341f80e13bf081baaf34f687, on upstream basef5315651166ea265ba673996e3c9efeb5e4cd9b0. The frozen tree was tested beforethat publication commit was created; this is a verified source-tree identity,
not a claim that the later Git commit ID was embedded in the old executable.
The tested patch SHA256 is
dbf805932c85d324230ce3e72d71017cff5e05af9ff91a034a5b0eda8c0fb048.The separate 38-test merge validation used
bf34603d1a1487a6de8faf25bde4e3a43c6d404b, tree7715f58253d6af8c7e40227fe899177cf4da9068, merged with upstream153ad6290f95578d6ef97a719939b63d76ad4e99. It did not rerun SCF.The following explicit target lists and anchored regexes resolve the variables
used above. The grouped 32-test regex selects exactly the recorded 32 names;
the six added merge tests are listed separately. Counts refer to registered
CTest entries, not the number of internal assertions or MPI ranks.
On the feature revision, build
"${FEATURE_TEST_TARGETS[@]}"instead andselect
"$DFTU_IO_TEST_REGEX". The historical SCF executable target wasabacus_std_para, built separately/in the same build command as those testtargets. The command above is the merge unit-test selection, not an SCF run.
The four new failure-path cases extend the 38-test selection with:
Their existing per-test timeout is 45 seconds (MPI subprocess: 30 seconds).
No references or convergence thresholds were loosened and no private run logs
or calculation inputs are included in the commit.
The review-fix selection and additional MPI phase checks can be run as: