Repository navigation
INCAR option table: generated templates, generated key reference docs (R3.1/R3.4/R4) - #106
Merged
Merged
Conversation
This was referenced Nov 15, 2026
Owner
Author
Review round 1 — template placeholders, model-section drift and reference-doc defects fixedAn independent review found the following in this delivery; all are fixed in
Also updated: the neutral-template helper and the productization invariant now strip the generated inline comment before comparing (their intent — no active Full suite |
… R3.1/R3.4/R4)
The templates and the documentation were hand-written copies of the option
table: the MD template wrote every thermostat's parameters, no template carried
a per-key explanation, the confsearch keys had placeholder descriptions
("confsearch option cs_mode (spec section 12.3)"), and there was no page that
listed what an INCAR key does, what it defaults to and when it applies.
What this changes:
- `OptionSpec` gains the presentation metadata the spec asks for: `group` and
`order` (section and position, shared by templates, `mliport config schema`
and the docs), `template`/`template_scopes` (whether and where a key appears
in a generated template), `applies_when` + `condition_calc_types` (for
example the MTK barostat keys only apply at `ENSEMBLE = NPT`, the Langevin
friction key only at `THERMOSTAT = LANGEVIN` but unconditionally in the
configuration search, which is always Langevin), `example_when_inactive`
(the commented NPT block), `placeholder` (`MODEL_PATH = REQUIRED`) and
`template_value`. One metadata table in `schema.py` annotates the existing
key list and is validated against it: an unknown or duplicated key is a
hard error at schema construction.
- All 45 confsearch keys and the four MTK chain parameters got real one-line
meanings, read off the implementation (`confsearch/options.py`), so the
templates and the reference page explain the science instead of pointing at
a spec section.
- `build_incar_default` now walks that table: sections appear once each in
`TEMPLATE_GROUP_ORDER`, every key carries its one-line comment, only the
selected calculation type's keys appear, only the selected thermostat's
parameters are written, and the MD template keeps the NPT keys as a
commented example with `# MD_ENSEMBLE = NPT` as the switch.
- New bilingual `docs/incar.md` (+ `.zh.md`) generated by
`scripts/generate_docs.py` from the same table (key, type, default, allowed
values, meaning, applicability, aliases, per section and per calculation
type); `--check` keeps it in sync. Wired into the `mkdocs.yml` nav, the docs
contract page list, `docs/configuration.md` (+ `.zh.md`),
`docs/quickstart.md` (+ `.zh.md`) - which also gains the task-folder
walkthrough next to the untouched command-line one - and one README row.
- `mliport config schema` prints the section of every key.
Tests: `tests/mliport/mliport/config/test_incar_templates.py` pins one section
per group in a fixed order, one comment per key, per-calc-type key sets, only
the selected thermostat's keys and the commented NPT example, and checks that
every template key is documented and every documented key is a real option
spelling. The #104 template round-trip test (5 types x 6 backends) still
passes against the new generator. Full suite: 2264 passed, 48 skipped; ruff,
`scripts/check_repository_hygiene.py`, `generate_docs.py --check` and
`mkdocs build --strict` are clean.
DATA IMPACT: no scientific record invalidated. No default value, unit, PBC
semantic, model task/head or dtype changed: the templates print the same
defaults as before (plus the meanings), and `_CONFSEARCH_DESCRIPTIONS` and the
NPT descriptions are documentation only. Existing INCAR files keep working
because no alias or key was removed.
Tracking: #61
…eference
Review findings on the R3/R4 delivery:
- The NEB template wrote `NEB_INITIAL = initial.vasp` / `NEB_FINAL =
final.vasp`. Those look like real files but point at nothing, so a created
task folder appeared complete while the INCAR could never run, and the "still
to fill in" report could not see them. They are now the fail-closed
`REQUIRED` placeholder (the round-trip test already fills them); the
round-trip contract is unchanged.
- The model section was still a hand-written key list with a stale claim
("absolute path or path relative to settings.ini", untrue once a name is
looked up in models/ and for an INCAR). Its `MODEL_TYPE`/`MODEL_PATH`
comments now come from the shared option table, so they cannot drift from
`docs/incar.md`.
- The generated key reference printed the internal "always commented" sentinel
as ``CS_MODE = MODE_B`` (a value the validator rejects) and labelled example
values as "required". Sentinel conditions are no longer rendered and example
values are marked as examples.
- The page claimed to list every INCAR key but omitted the batch keys; it now
has a `## Batch` section and generated table, with the same note in both
languages. The Chinese page translates the section headings and states that
the meaning column is the English option table.
- Two assertions could not fail (an ordering check that was true by
construction and a key-set comparison padded with a hardcoded list); they now
check both directions - every templated key is documented and every
documented key is a real option spelling.
Tests: template/defaults assertions updated for the REQUIRED endpoints and the
inline comments; the neutral-template helper now strips the generated comment
before comparing; config, CLI, docs-contract and TUI suites are green; ruff
clean.
DATA IMPACT: no scientific record invalidated. Template *values* for the NEB
endpoints become REQUIRED (they were never resovable), no default, unit, PBC
semantic, model task/head or dtype changed.
Tracking: #61
`mliport template` writes a one-line meaning after every value (#61 R3.1), so the template line reads `MODEL_TYPE = REQUIRED # MLIP engine.` and the old whole-line comparison against `MODEL_TYPE = REQUIRED` could not match. Strip the comment before comparing and assert on the assignment, which is what the invariant is about; the assertions themselves are unchanged.
#105 defines what a `MODEL_PATH` without a path separator means: it is a file name, resolved next to the declaring file first and then in `<MLIPORT_ROOT>/models` (one level of subdirectories, two matches refused). The unified option table still carried the pre-#105 wording, which the generated key reference in `docs/incar.md` (+ `.zh.md`) repeated for every calculation type. The description now comes from #105, and the generated pages are regenerated from it, so the table, `mliport config schema`, the templates and the reference page keep agreeing.
hydrogen1222
force-pushed
the
feat/incar-option-table-and-docs
branch
from
November 17, 2026 10:41
c5497ee to
34e1e9a
Compare
hydrogen1222
added a commit
that referenced
this pull request
Nov 17, 2026
The TUI wizard (this branch) needs both parents: the `models/` lookup for `MODEL_PATH` (#105) and the generated INCAR templates (#106). Both are rebased onto the same `main`, so this merge only resolves the CHANGELOG: the Unreleased section keeps the newest round first, i.e. this branch, then the option table, then `models/`, then the task folder round that is already in `main`.
The Unreleased section only ever grows at the top, so two open rounds that both prepend a block conflict on the same anchor line even though they touch different rounds. Keeping this entry next to the older task-folder round (the one it builds on) leaves the top anchor to the newer rounds and keeps the branches mergeable in either order.
hydrogen1222
added a commit
that referenced
this pull request
Nov 17, 2026
The wizard on this branch needs both stacks: the `models/` lookup for `MODEL_PATH` (#105) and the generated INCAR templates (#106). Both are rebased onto the same `main`, so the merge only has to settle the unchanged files; the CHANGELOG conflict does not arise because each round keeps its own anchor in the Unreleased section.
hydrogen1222
added a commit
that referenced
this pull request
Nov 17, 2026
#105 and #106 are merged, but this branch carried their pre-merge commits, so `main` and the branch had two merge bases and GitHub reported the pull request as conflicting even though the trees agreed. Merging `main` in brings the merge base down to one commit; the resulting tree is unchanged (the branch already contained every file of #105 and #106 verbatim).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Tracking: #61 — delivery 3 of the "任务文件夹 + INCAR +
models/" split (spec: #61 (comment)).Targets
main. #104 has landed, so the branch is rebased onto the currentmainand its commits apply cleanly (the merged #104 content is no longer carried). Independent of #105 in code, but see theMODEL_PATHrow below: the option table now carries #105's definition so the two PRs do not contradict each other after both land.What this PR does
R3.4 — one option table
OptionSpec(mliport/config/schema.py) gains the metadata the spec asks for, and_SPECSstays the single list of keys:group/ordermliport config schemaand the docstemplate/template_scopesapplies_when/condition_calc_typesENSEMBLE = NPTfor the barostat block,THERMOSTAT = LANGEVINforFRICTION, with the configuration search exempt because it is always Langevin)example_when_inactive/example_condition_line/example_noteplaceholder/template_valueREQUIREDplaceholders and display values for keys whose runtime default lives in the writerA single metadata table annotates the declared specs and fails hard on an unknown or duplicated key, so the table cannot drift from the key list (asserted by a test).
The
MODEL_PATHentry keeps the meaning #105 defines (a name without a path separator is looked up next to the declaring file and then in<MLIPORT_ROOT>/models, one level of subdirectories, two matches refused) instead of the pre-#105 wording, so the generated key reference does not contradict the resolver after both PRs land.R3.1 — templates
mliport template <type>is generated from that table: each section appears once in a fixed order, every key carries its one-line meaning, only the selected calculation type's keys appear, only the selected thermostat's parameters are written, and the MD template keeps the NPT keys as a commented example with# MD_ENSEMBLE = NPTas the switch. The 45 confsearch keys and the four MTK chain parameters got real one-line meanings read off the implementation, replacing theconfsearch option <name> (spec section 12.3)placeholders.R4 — key reference docs
New bilingual
docs/incar.md+docs/incar.zh.md, generated byscripts/generate_docs.pyfrom the same table (--checkin CI andtest_generated_docs_are_in_synckeep it honest): per section, per calculation type, a table of key, type, default, allowed values, meaning, applicability and aliases. Wired intomkdocs.yml, the docs contract page list,docs/configuration.md(+.zh.md),docs/quickstart.md(+.zh.md, which gains the task-folder walkthrough while the command-line walkthrough stays) and one README row.mliport config schemanow prints each key's section.Tests
tests/mliport/mliport/config/test_incar_templates.py(40 cases): one section per group in a fixed order across 5 calc types x 6 backends, one comment per key, only the selected thermostat, the commented NPT example, per-calc-type key sets, template keys ⊆ documented keys ⊆ real option spellings.runvalidation/resolution) still passes against the new generator.tests/test_productization_invariants.py::test_pi03compared whole template lines, which stopped matching once the template carries a one-line meaning after every value ([DEV MASTER · DO NOT MERGE/CLOSE] MLIP validation roadmap (#75) + confsearch living spec #61 R3.1). It now strips the inline comment and asserts on the assignment; the assertions themselves are unchanged.2265 passed, 48 skipped;ruff check/format --check,scripts/check_repository_hygiene.py,scripts/generate_docs.py --check,mkdocs build --strictand the docs contract tests all clean.The Unreleased CHANGELOG entry sits below the task-folder round rather than at the top of the section, so this branch and #105 do not conflict on the same anchor line; the two merge in either order.
DATA IMPACT: no scientific record invalidated. No default, unit, PBC semantic, model task/head or dtype changed — the templates print the same default values as before, and the new prose is documentation only. No INCAR key or alias was removed.
Not merged without owner confirmation; review first.