[Stardust0831]

Closed after reviewing the intended INPUT semantics. gamma_only=1 has also served as a convenient request for Gamma-point sampling without a separate KPT file. Rejecting that request outright for PW would remove an existing user workflow; a reset audit alone does not establish that the input is invalid. Any future change should distinguish the sampling request from the internal algorithm choice and protect user-supplied KPT contents.

The magnetic-mixing fix in #8185 and the focused mem_saver validation in #8186 remain separate draft PRs. #7719 remains open for further reset auditing and standardized value/dependency validation.

---

Replace silent correction of an invalid, explicitly specified INPUT parameter with a clear input error. With basis_type=pw, gamma_only=1 currently becomes 0 and ABACUS creates or overwrites KPT before continuing. This PR stops instead, reports the supplied value and the required gamma_only=0, gives a Gamma-mesh example and manual link, and preserves KPT.

#7719 tracks INPUT finalization that silently changes user-specified parameters and can make an explicit value behave differently from the equivalent default. Its central requirement is to preserve valid explicit input and replace silent correction of invalid or contradictory input with a clear error: name the offending parameters and values, explain the conflict, and provide legal values/corrective guidance and the relevant manual link. Intentional defaults for omitted parameters remain useful; they must not overwrite the user's explicit choices.

Linked Issue

Part of #7719.

Unit Tests and/or Case Tests for my changes

Commands run with OMP_NUM_THREADS=1 and LD_LIBRARY_PATH=/home/stardust/miniconda3/envs/phono3py/lib (GNU 13.4, CPU/OpenMP, MPI and LCAO numerical backends disabled):

cmake --build /tmp/abacus-7719-small-pr-build --target MODULE_IO_read_item_serial MODULE_IO_availability abacus_pw_omp -j8
ctest --test-dir /tmp/abacus-7719-small-pr-build --output-on-failure -R '^MODULE_IO_(read_item_serial|availability)$'
/tmp/abacus-7719-small-pr-build/abacus_pw_omp --version
/tmp/abacus-7719-small-pr-build/abacus_pw_omp -h gamma_only
/tmp/abacus-7719-small-pr-build/abacus_pw_omp --check-input
/tmp/abacus-7719-small-pr-build/abacus_pw_omp --generate-parameters-yaml > /tmp/abacus-7719-gamma-parameters.yaml
python3 docs/generate_input_main.py /tmp/abacus-7719-gamma-parameters.yaml --output /tmp/abacus-7719-gamma-input-main.md --verbose

Build and both CTest targets passed. The new reader regression checks rejected PW input with an existing and an absent KPT, asserts file preservation, and checks the diagnostic. Supported PW and LCAO inputs also pass.

--check-input was run from six valid case directories: PW 1 with/without KPT exits 1; PW default/0 and LCAO 1 with nspin=1/2 exit 0. KPT contents/existence remain unchanged in all six cases. Executable reports v3.11.0-beta11; help and generated Markdown include the updated behavior (579 parameters, 37 categories). MPI/GPU and numerical LCAO calculations were not run: this change is in the shared input reader.

The shipped PW cases now explicitly use gamma_only=0 and supply their single-Gamma KPT. The five regression meshes and all numerical reference files are unchanged; four example directories that previously relied on implicit KPT creation now include that file.

Additional fixture verification (same toolchain environment), from /tmp/abacus-7719-gamma-fixtures/tests/01_PW containing copies of the updated cases:

bash ../integrate/Autotest.sh -a /tmp/abacus-7719-small-pr-build/abacus_pw_omp -n 0 -o 1 -j 1 -r '^(027_PW_PINT_RKS|028_PW_PINT_UKS)$' -f CASES_CPU.txt

Both previously failing PW numerical cases passed all four energy/reference checks with the existing 1e-7 eV tolerance. Both focused CTest targets also passed after the migration. --check-input passed for eight updated INPUT files and preserved their KPT files. Three DeePKS test INPUTs reached the expected local-build limitation (please compile with DeePKS); they require the ML-enabled CI build. A scan of shipped INPUT files in tests/examples/source found no remaining basis_type=pw with gamma_only=1.

What's changed?

• Replace the PW reset/file-writing hook with validation; preserve the existing LCAO nspin=4 rejection.
• Explain that PW Gamma-point sampling uses gamma_only=0 and a 1 1 1 0 0 0 Gamma mesh in KPT.
• Migrate the shipped PW tests/examples to explicit Gamma meshes, including KPT files for examples that relied on automatic creation.
• Update the gamma_only registration metadata and focused reader tests. Other reset cases in Audit INPUT reset semantics and formalize final parameter validation #7719 are outside this small PR.

Governance Notes

• INPUT/docs changes: gamma_only validation, diagnostics, and registration metadata updated. No documentation update required outside the Input_Item registration; generated YAML/Markdown are build artifacts.
• Core module impact: shared INPUT parsing only; no ESolver, HSolver, ElecState, Hamilt, Operator, or Psi changes. Removes global warning-stream references.
• Verification: git diff --cached --check and python3 tools/03_code_analysis/agent_governance_check.py --staged --event-path /mnt/g/work/agent/abacus/issue-7719-pr-notes/gamma-event.json --format text passed. Whole-file quality scoring reports 13/0 for the touched implementation/test files (baseline 0/0); these existing oversized files remain below 60.
• Exceptions requested: none.