Skip to content

INCAR option table: generated templates, generated key reference docs (R3.1/R3.4/R4) - #106

Merged
hydrogen1222 merged 5 commits into
mainfrom
feat/incar-option-table-and-docs
Nov 17, 2026
Merged

hydrogen1222 merged 5 commits into
mainfrom
feat/incar-option-table-and-docs

Conversation

@hydrogen1222

@hydrogen1222 hydrogen1222 commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Tracking: #61 — delivery 3 of the "任务文件夹 + INCAR + models/" split (spec: #61 (comment)).

Targets main. #104 has landed, so the branch is rebased onto the current main and its commits apply cleanly (the merged #104 content is no longer carried). Independent of #105 in code, but see the MODEL_PATH row 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 _SPECS stays the single list of keys:

Field Meaning
group / order section and position, shared by templates, mliport config schema and the docs
template / template_scopes whether/when a key appears in a generated template
applies_when / condition_calc_types "applies only when" (ENSEMBLE = NPT for the barostat block, THERMOSTAT = LANGEVIN for FRICTION, with the configuration search exempt because it is always Langevin)
example_when_inactive / example_condition_line / example_note keep a conditional key as a commented example (NPT block, mode-B confsearch block)
placeholder / template_value REQUIRED placeholders and display values for keys whose runtime default lives in the writer

A 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_PATH entry 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 = NPT as the switch. The 45 confsearch keys and the four MTK chain parameters got real one-line meanings read off the implementation, replacing the confsearch option <name> (spec section 12.3) placeholders.

R4 — key reference docs

New bilingual docs/incar.md + docs/incar.zh.md, generated by scripts/generate_docs.py from the same table (--check in CI and test_generated_docs_are_in_sync keep it honest): per section, per calculation type, a table of key, type, default, allowed values, meaning, applicability and aliases. Wired into mkdocs.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 schema now 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.
  • Task folder INCAR core: results/ default, config-before-structure, CONFSEARCH dispatch (R1 + R3.2/R3.3) #104's round-trip test (all templates accepted by run validation/resolution) still passes against the new generator.
  • tests/test_productization_invariants.py::test_pi03 compared 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.
  • Local verification: full suite 2265 passed, 48 skipped; ruff check/format --check, scripts/check_repository_hygiene.py, scripts/generate_docs.py --check, mkdocs build --strict and 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.

@hydrogen1222

Copy link
Copy Markdown
Owner Author

Review round 1 — template placeholders, model-section drift and reference-doc defects fixed

An independent review found the following in this delivery; all are fixed in c5497eea:

  1. The NEB template invented endpoints. NEB_INITIAL = initial.vasp / NEB_FINAL = final.vasp point at nothing, so a created task folder looked complete while the INCAR could never run (and the wizard's "still to fill in" report could not see them). They are now the fail-closed REQUIRED placeholder; the round-trip contract is unchanged (the test already fills them).
  2. The model section was a hand-written key list that had drifted — it still claimed "absolute path or path relative to settings.ini", which is wrong once a name is looked up in models/ and for an INCAR value. MODEL_TYPE/MODEL_PATH comments now come from the option table.
  3. The generated reference documented an impossible condition: the internal "always commented" sentinel rendered as CS_MODE = MODE_B, a value the validator rejects. Sentinel conditions are no longer printed, and example-only values are labelled as examples instead of "required".
  4. The page claimed to list every INCAR key but omitted the batch keys — there is now a ## Batch section and generated table (same note in both languages). The Chinese page translates the section headings and states honestly that the meaning column is the English option table.
  5. Two assertions could not fail: an ordering check true by construction and a key-set comparison padded with a hardcoded list. They now check both directions (every templated key is documented, every documented key is a real option spelling).

Also updated: the neutral-template helper and the productization invariant now strip the generated inline comment before comparing (their intent — no active MODEL_TYPE = UMA — is unchanged).

Full suite 2310 passed, 48 skipped; ruff, generate_docs.py --check, mkdocs build --strict and the docs contract are green; CI re-ran green.

Base automatically changed from feat/task-folder-incar-core to main November 16, 2026 06:38
… 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
hydrogen1222 force-pushed the feat/incar-option-table-and-docs branch from c5497ee to 34e1e9a Compare November 17, 2026 10:41
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
hydrogen1222 merged commit 116272c into main Nov 17, 2026
14 checks passed
@hydrogen1222
hydrogen1222 deleted the feat/incar-option-table-and-docs branch November 17, 2026 11:48
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).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant