Background
Issue #7514 and PR #7689 exposed a broader problem in the INPUT pipeline: a parameter can be read correctly but then be finalized from another parameter that has not reached its own final value yet. As a result, writing a value explicitly or relying on the equivalent default can produce different final states.
PR #7689 tested the known ordering dependencies with per-parameter reset_after declarations, but it is now closed and that design was not adopted. Its regression cases still demonstrate that ordering is real and user-visible, while raising a larger maintainability question: should all of the current reset_value behavior exist, and which invalid combinations should be rejected instead of silently rewritten?
At the final #7689 revision, the INPUT registration sources contained roughly 99 reset_value hooks and 130 check_value hooks. Only the dependencies needed for the known failures were declared. Continuing to add dependency edges case by case may make the reset graph difficult to reason about without first reviewing the semantics of the resets themselves.
PR #7720 handles the device case separately by making cpu the default, requiring explicit device gpu selection, and rejecting device auto. This removes that specific automatic-device dependency but does not resolve the other confirmed reset-order cases tracked here.
Confirmed behavior
Four pairs of complete ABACUS cases were tested with INPUT, byte-identical STRU/KPT within each pair, real pseudopotential/orbital files, and four MPI ranks. The two INPUT files in each pair differ by exactly one parameter line.
| Case |
Difference between paired INPUT files |
State used by the #7689 regression |
Old behavior |
| Basis |
omit ecutwfc vs. write ecutwfc 100 |
basis_type=lcao, ecutwfc=100 |
omitted case finalized as ecutwfc=50 |
| Noncollinear spin |
omit nspin vs. write nspin 4 |
nspin=4, two Fermi levels |
omitted case produced only one Fermi level |
| Mixing |
omit scf_thr vs. write scf_thr 1e-9 |
scf_thr=1e-9, mixing_restart=1e-10 |
omitted case retained mixing_restart=-0.1 |
| SDFT fallback |
default KSDFT vs. write transitional esolver_type=sdft with nbands_sto=0 |
esolver_type=ksdft, bndpar=1 |
transitional case retained bndpar=2 |
On baseline commit 085b91e4f, 4 of the 8 cases had the wrong final state. On PR commit 9b8e4ed05, all 8 reached the state used by those regression tests. This confirms that the existing reset order can make final behavior depend on whether an otherwise equivalent value appears explicitly in INPUT. It does not by itself establish that every silent reset in those tests is desirable.
Prefer validation over cross-parameter repair
Before encoding another reset-order dependency, decide whether the final parameter combination is valid at all. Contradictory user intent should normally produce a clear input error instead of being silently rewritten into a different calculation.
noncolin=true requires nspin=4. If nspin is omitted and therefore remains at an incompatible default, or is explicitly set to another value, final validation should report the conflict and require nspin=4; it should not silently rewrite nspin.esolver_type=sdft with nbands_sto=0 is contradictory and should be rejected before any fallback. bndpar should be validated according to its own parallelization constraints, not changed merely because esolver_type was silently rewritten.- More generally, avoid coupling otherwise independent parameters through repair-style resets. Defaults may still be derived where that behavior is intentional, but explicit or final contradictions should fail with the parameter names, values, reason, and corrective action.
Proposed direction
1. Audit every reset
Review every reset_value hook and record:
- what invariant or user-facing behavior requires it;
- whether it fills an omitted default, canonicalizes a value, derives internal state, or silently overrides an explicit user value;
- which already-finalized parameter group it is allowed to read;
- whether the same situation should instead be reported as invalid input.
Resets that only hide an unsupported or contradictory explicit combination should preferably be removed and replaced by a clear validation error. A user-specified value should not be silently changed unless that behavior is deliberate, documented, and tested.
2. Define staged finalization responsibilities
The implementation does not have to expose an unrestricted dependency graph for every keyword. A small number of ordered groups may be easier to review, for example:
- primitive/runtime choices such as device;
- parallelization parameters;
- basis and solver selection;
- electronic-structure and mixing defaults;
- post-processing options.
The exact grouping should be decided from the reset audit. A reset in a later group may consume finalized values from an earlier group, but should not mutate parameters owned by an earlier group.
3. Formalize the final parameter validation phase
ReadInput already invokes per-item check_value hooks after reset and broadcast. This should be treated as an explicit final validation contract, reviewed for completeness and kept mutation-free.
After all defaults and derived values have stabilized, invalid final states should stop before calculation and report:
- the parameter names and final values involved;
- why the combination is invalid or unsupported;
- which value was derived/defaulted where relevant;
- what the user can change to make the input valid.
The validation phase should not silently repair the state. This separates "derive a valid final value" from "prove the final state is legal" and avoids credible-looking output from an unsupported configuration.
4. Consider a schema-driven INPUT builder as a separate user-facing layer
An external interactive tool, similar in role to the CP2K input construction module in Multiwfn or to VASPKIT, could make the large ABACUS parameter space easier and safer to use. It could guide the user from high-level choices to only the parameters relevant to those choices. For example, magnetic parameters would be exposed only after the user enables the corresponding spin/noncollinear functionality.
This should consume machine-readable metadata rather than duplicate INPUT rules in a separate hard-coded program. The schema would ideally describe:
- parameter type, allowed values/range, unit, and documentation;
- default and whether it depends on other finalized choices;
- applicability conditions such as basis, solver, device, calculation type, or magnetic mode;
- conflicts, requirements, and unsupported combinations;
- whether a value was chosen explicitly or generated as a default.
ABACUS already maintains parameter metadata in docs/parameters.yaml, which may be a useful starting point, but conditional applicability and cross-field constraints would need a reviewed representation. The same metadata could support a CLI wizard, a GUI/web form, editor completion, and static INPUT linting.
The builder is an aid, not the authority. Hand-written files, workflow scripts, and old generated inputs must still be accepted or rejected by the final validation inside ABACUS. The core executable remains responsible for the definitive error and reason.
Suggested acceptance criteria
Relationship to existing work
This issue continues to track the remaining reset audit, staged finalization responsibilities, and final validation design independently of focused fixes such as #7720.
Background
Issue #7514 and PR #7689 exposed a broader problem in the INPUT pipeline: a parameter can be read correctly but then be finalized from another parameter that has not reached its own final value yet. As a result, writing a value explicitly or relying on the equivalent default can produce different final states.
PR #7689 tested the known ordering dependencies with per-parameter
reset_afterdeclarations, but it is now closed and that design was not adopted. Its regression cases still demonstrate that ordering is real and user-visible, while raising a larger maintainability question: should all of the currentreset_valuebehavior exist, and which invalid combinations should be rejected instead of silently rewritten?At the final #7689 revision, the INPUT registration sources contained roughly 99
reset_valuehooks and 130check_valuehooks. Only the dependencies needed for the known failures were declared. Continuing to add dependency edges case by case may make the reset graph difficult to reason about without first reviewing the semantics of the resets themselves.PR #7720 handles the device case separately by making
cputhe default, requiring explicitdevice gpuselection, and rejectingdevice auto. This removes that specific automatic-device dependency but does not resolve the other confirmed reset-order cases tracked here.Confirmed behavior
Four pairs of complete ABACUS cases were tested with
INPUT, byte-identicalSTRU/KPTwithin each pair, real pseudopotential/orbital files, and four MPI ranks. The two INPUT files in each pair differ by exactly one parameter line.ecutwfcvs. writeecutwfc 100basis_type=lcao,ecutwfc=100ecutwfc=50nspinvs. writenspin 4nspin=4, two Fermi levelsscf_thrvs. writescf_thr 1e-9scf_thr=1e-9,mixing_restart=1e-10mixing_restart=-0.1esolver_type=sdftwithnbands_sto=0esolver_type=ksdft,bndpar=1bndpar=2On baseline commit
085b91e4f, 4 of the 8 cases had the wrong final state. On PR commit9b8e4ed05, all 8 reached the state used by those regression tests. This confirms that the existing reset order can make final behavior depend on whether an otherwise equivalent value appears explicitly in INPUT. It does not by itself establish that every silent reset in those tests is desirable.Prefer validation over cross-parameter repair
Before encoding another reset-order dependency, decide whether the final parameter combination is valid at all. Contradictory user intent should normally produce a clear input error instead of being silently rewritten into a different calculation.
noncolin=truerequiresnspin=4. Ifnspinis omitted and therefore remains at an incompatible default, or is explicitly set to another value, final validation should report the conflict and requirenspin=4; it should not silently rewritenspin.esolver_type=sdftwithnbands_sto=0is contradictory and should be rejected before any fallback.bndparshould be validated according to its own parallelization constraints, not changed merely becauseesolver_typewas silently rewritten.Proposed direction
1. Audit every reset
Review every
reset_valuehook and record:Resets that only hide an unsupported or contradictory explicit combination should preferably be removed and replaced by a clear validation error. A user-specified value should not be silently changed unless that behavior is deliberate, documented, and tested.
2. Define staged finalization responsibilities
The implementation does not have to expose an unrestricted dependency graph for every keyword. A small number of ordered groups may be easier to review, for example:
The exact grouping should be decided from the reset audit. A reset in a later group may consume finalized values from an earlier group, but should not mutate parameters owned by an earlier group.
3. Formalize the final parameter validation phase
ReadInputalready invokes per-itemcheck_valuehooks after reset and broadcast. This should be treated as an explicit final validation contract, reviewed for completeness and kept mutation-free.After all defaults and derived values have stabilized, invalid final states should stop before calculation and report:
The validation phase should not silently repair the state. This separates "derive a valid final value" from "prove the final state is legal" and avoids credible-looking output from an unsupported configuration.
4. Consider a schema-driven INPUT builder as a separate user-facing layer
An external interactive tool, similar in role to the CP2K input construction module in Multiwfn or to VASPKIT, could make the large ABACUS parameter space easier and safer to use. It could guide the user from high-level choices to only the parameters relevant to those choices. For example, magnetic parameters would be exposed only after the user enables the corresponding spin/noncollinear functionality.
This should consume machine-readable metadata rather than duplicate INPUT rules in a separate hard-coded program. The schema would ideally describe:
ABACUS already maintains parameter metadata in
docs/parameters.yaml, which may be a useful starting point, but conditional applicability and cross-field constraints would need a reviewed representation. The same metadata could support a CLI wizard, a GUI/web form, editor completion, and static INPUT linting.The builder is an aid, not the authority. Hand-written files, workflow scripts, and old generated inputs must still be accepted or rejected by the final validation inside ABACUS. The core executable remains responsible for the definitive error and reason.
Suggested acceptance criteria
reset_valuehooks.noncolin=trueunless the finalnspinis explicitly compatible (nspin=4).esolver_type=sdftwithnbands_sto=0instead of silently changingesolver_typeand then resettingbndpar.Relationship to existing work
device=autois finalized afterkparreset, leading to inconsistent PW/GPU parallel setup and corrupted direct cubes #7514 is the original user-visible GPU/device/KPAR failure.reset_afterdesign discussion.autorather than adopting the broader reset-order design.This issue continues to track the remaining reset audit, staged finalization responsibilities, and final validation design independently of focused fixes such as #7720.