Skip to content

Audit INPUT reset semantics and formalize final parameter validation #7719

Open

Description

@Stardust0831

ABACUS should preserve valid explicit INPUT requests and fill omitted parameters with documented contextual defaults. Invalid values or combinations should produce a clear error naming the parameters, explaining the legal values or requirements, and linking to the relevant manual section. A default formula must not silently overwrite an explicit value.

This issue began with #7514: kpar was finalized before automatic device selection completed, leaving an inconsistent GPU configuration. #7720 removed that specific path. The broader problem remains: a default can consume another parameter before its value is ready, and explicit input can still be overwritten later. The reset_after experiment in #7689 was closed without merging.

Merged progress:

Representative remaining failures, reproduced through the input reader:

  1. DeltaSpin default ordering and explicit overwrite. With PW SCF, nspin=2, sc_mag_switch=true, sc_scf_thr=10 and omitted mixing_restart, omitting scf_thr produces mixing_restart=-0.1; explicitly writing the equivalent scf_thr=1e-9 produces 1e-10. Both finish with scf_thr=1e-9: the restart default consumed the private -1 initializer too early. Separately, explicit mixing_restart=0.02 is overwritten by sc_scf_thr=0.001. Source.
  2. MD time-step conflicts. Explicit md_dt=1, td_dt=0.02, estep_per_md=2 changes md_dt to 0.04. Even md_dt=-1 can be replaced before its negative-value check. Omitted time steps may be derived; contradictory explicit requests should fail. Source.
  3. Vector truncation before validation. With ntype=1, orbital_corr 2 99 and hubbard_u 4 -7 become 2 and 4; the invalid trailing entries disappear. Validate the original elements and required length before resizing. Source.

Other audit areas include conflicting aliases/units, calculation-dependent force/stress/output settings, and configuration changes after INPUT preparation. Complex default chains also remain: MD time steps feed thermostat/barostat frequencies; cutoff defaults feed other cutoffs; EXX defaults depend on the functional and vector sizes; OFDFT presets write multiple parameters before vector resizing; symmetry settings feed EXX options. These dependencies require review, but their existence alone does not prove a numerical bug.

The next step is a shared default-resolution mechanism, extending the existing structured metadata:

  • Preserve each original request before readers or aliases can overwrite it. Valid explicit 0, false and documented negative values retain their meanings. Private initialization sentinels do not automatically become public automatic options.
  • Resolve only omitted defaults, using dependencies that are ready. Handle conditional dependencies and later structure/build context explicitly; detect cycles or ambiguous rules. Runtime order must not depend on documentation/registration order.
  • Use the same default declarations for execution, help and the generated manual. Keep descriptive availability, hard validity requirements, documented automatic options, and internal calculation state distinct.
  • Migrate legacy default writers and remove the old reset mechanism once coverage is complete. Test explicit-value preservation, omitted-versus-equivalent-explicit defaults, conflicting inputs and vector lengths. Validation must report errors without repairing input.

Draft follow-ups: DeltaSpin fix, DFT+U vector validation, and shared default-resolution proposal. These remain drafts in the fork; the proposal contains design documentation, not an implemented resolver.

Updated 2026-11-07. Source rechecked at develop commit 27c3e1065; reader reproductions used 3ded45144. The INPUT module is identical in these two commits. The examples above establish input-processing defects, not numerical failures for every affected feature.

Activity

  1. Stardust0831 commented on Jul 31, 2026

    @Stardust0831
    CollaboratorAuthor

    Updated 2026-11-07: #7731 has merged. It replaces contradictory spin/SDFT settings and invalid bndpar repairs with explicit validation errors.

    Subsequent fixes and the remaining default-order/explicit-overwrite work are summarized in the issue body. The earlier hook counts and candidate list are superseded; default resolution remains necessary, with valid explicit requests taking precedence.

  2. Growl1234 commented on Aug 1, 2026

    @Growl1234
    Collaborator

    I think this issue should also formalize parameter applicability, rather than focusing only on reset ordering.

    ABACUS currently exposes a flat INPUT namespace, while many parameters are meaningful only for a particular basis, solver, calculation type, or feature. Although Input_Item contains an availability field, it is currently descriptive metadata rather than an enforced runtime condition. All registered reset and validation hooks still participate in the same global pipeline.

    This creates another class of ambiguity: a parameter that is irrelevant to the selected calculation may still be accepted, silently ignored, or reset, and may even affect other parameters indirectly.

    I think the intended contract should be:

    1. An omitted applicable parameter may receive its documented default.
    2. An explicitly specified applicable parameter should be preserved when valid.
    3. A contradictory explicit combination should be rejected, not repaired by changing one of the requested values.
    4. An explicitly specified but inapplicable parameter should eventually be rejected with a clear diagnostic, rather than silently ignored or reset.
    5. Canonicalization should be limited to documented equivalent aliases and must not change calculation semantics.
    6. Internal derived state should be kept separate from user-facing INPUT values.

    It may also be useful to track whether each final value is explicit, defaulted, derived, or canonicalized. This would make it possible to enforce the rule that default resolution may fill omitted values but must not silently overwrite explicit user intent.

    With such a contract, reset dependencies or staged ordering become implementation details for resolving genuine defaults, rather than a general mechanism for repairing arbitrary invalid input combinations.

  3. Stardust0831 commented on Aug 1, 2026

    @Stardust0831
    CollaboratorAuthor

    Updated 2026-11-07: the old per-parameter table based on bdf5cd9 has been replaced by the current summary in the issue body.

    At 27c3e1065, 96 active reset callbacks remain. They include defaults, equivalent-value normalization, internal-state updates and checks; this is not a count of bugs. They still run in registration order, without a shared dependency-readiness mechanism. The reproduced mixing_restart failure is a concrete reason to address that mechanism.

    One older source observation remains for separate cleanup: the kpoint_file callback writes stru_file; its runtime reachability and impact have not been established. The previously noted ndz comparison is corrected in the current source.

  4. Stardust0831 commented on Aug 1, 2026

    @Stardust0831
    CollaboratorAuthor

    Updated 2026-11-07: the old availability tables and coverage counts are superseded by #7783 and #8192. Structured applicability and shared value/dependency contracts now generate documentation from the parameter registrations.

    availability remains descriptive. Rejection requires a declared validity rule or requirement; an inactive feature does not automatically make an explicitly disabled option illegal. Defaults are a separate contract and must preserve valid explicit requests.

    The issue body tracks the remaining work. The old parameter-by-parameter lists have been removed to keep this discussion readable.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions