Skip to content

TUI new-task wizard + task-folder helper (R5) - #107

Merged
hydrogen1222 merged 4 commits into
mainfrom
feat/tui-task-folder-wizard
Nov 17, 2026
Merged

hydrogen1222 merged 4 commits into
mainfrom
feat/tui-task-folder-wizard

Conversation

@hydrogen1222

@hydrogen1222 hydrogen1222 commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

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

Targets main, but is a stack: the wizard needs both open rounds - the models/ lookup for MODEL_PATH (#105, the model picker) and the generated INCAR templates (#106, the folder's INCAR.mliport). #105 and #106 are rebased onto the current main and merged in here, so until those two land this diff also shows their content; once they are in main the diff of this PR is exactly the ten wizard files. Merge order: #105 -> #106 -> this one.

What this PR does (R5)

Requirement Implementation
R5.1 wizard first, three questions MainScreen offers New task as its first entry. NewTaskScreen asks calculation type → structure file → model (backend Select first, then a ListView of the models/ listing, or a typed path). The folder name is pre-filled from the structure and calculation type, so it is a confirmation, not a fourth question.
R5.2 folder contents mliport/task_folder.py writes INCAR.mliport from build_incar_default (the same generator as mliport template) with MODEL_TYPE/MODEL_PATH filled in, and copies the structure byte for byte under POSCAR / structure.cif / structure.xyz. A bare model file name stays a name so the models/ convention still resolves it; anything else is recorded absolutely. The screen shows cd <folder> && mliport run and lists any REQUIRED placeholder still to fill (NEB endpoints, confsearch starts).
R5.2 "run now" uses mliport run "Create & Run" calls run_task_folder, which chdirs into the folder and calls mliport.cli.main(["run", "--incar", …]) — the same code path as the CLI, pinned by a test that asserts the exact argv and working directory. No subprocess, no second command builder.
R5.3 previous screens kept New AdvancedScreen keeps SP/OPT/MD/NEB/CONFSEARCH manual configuration, jobs, analysis and the template generator. TemplateScreen reuses build_incar_default and now accepts confsearch (it used to silently write an SP template).

Fail-closed: unknown calculation type, unsupported structure suffix, missing structure/model, a template without the two model lines, and an existing non-empty destination (or an existing INCAR.mliport / structure of ours) are errors, never guesses.

Tests

tests/mliport/mliport/test_task_folder_wizard.py — 23 tests: byte-identical structure copies, suffix normalization, the generated INCAR passing the same validation and resolution mliport run performs, template reuse, refusal cases, retained bare model name, placeholder report, run delegation (argv + cwd), the wizard's create and create-and-run buttons (Textual run_test), the models/ listing, and the new navigation. The two existing main-screen navigation tests were updated to look at the Advanced menu, which is the documented R5.3 change.

Local verification on the current head: full suite 2310 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 clean.

DATA IMPACT: no scientific record invalidated. The wizard only creates new files (it refuses to overwrite a previous task's INCAR or structure) and reuses the CLI run path; no default, unit, PBC semantic, model task/head or dtype changes.

Not merged without owner confirmation; review first.

@hydrogen1222

Copy link
Copy Markdown
Owner Author

Review round 1 — the wizard no longer runs a model decision the user did not make

An independent review found two problems in this delivery; both are fixed in 171d137b:

  1. "Create & Run" executed a hardcoded model task/head. The wizard filled MODEL_PATH/MODEL_TYPE and then offered one click to run, so the run inherited the template's TASK = omat (UMA's task family) or DPA's HEAD = Omat24 branch without the user ever choosing them — a silent model-identity decision, which AGENTS.md rule 3 forbids. TASK (and HEAD where the backend has an active one) is now written as REQUIRED, listed under "still to fill in", and run refuses the file until the user decides. A caller that already knows the decision can pass task=/head=.
  2. A model picked from a models/ subdirectory became a broken path. The picker lists entries like uma/s1.pt; because the value contains a separator it was written as a working-directory-relative path. Such a value is now looked up inside models/ and recorded absolutely, and a separated value that exists nowhere fails closed instead of producing an INCAR that cannot work.
  3. The "still to fill in" report now also covers the NEB endpoints, which became real REQUIRED placeholders in INCAR option table: generated templates, generated key reference docs (R3.1/R3.4/R4) #106 (the old test wrongly pinned "nothing pending").

Tests: the created INCAR is asserted to leave exactly TASK (plus HEAD for DPA) pending and to pass validation/resolution once filled; new cases cover a models/-relative entry, a non-existent separated value and an explicitly supplied task/head. Full suite on this branch: 2310 passed, 48 skipped; ruff clean.

Also note for review: this branch contains #104, #105 (merged) and #106, because the wizard needs the task-folder core, the models/ listing and the shared template generator. It will be rebased onto main once those land.

@hydrogen1222
hydrogen1222 force-pushed the feat/incar-option-table-and-docs branch from c5497ee to 34e1e9a Compare November 17, 2026 10:41
@hydrogen1222
hydrogen1222 force-pushed the feat/tui-task-folder-wizard branch 3 times, most recently from 644a859 to 02f5ffd Compare November 17, 2026 11:19
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.
The TUI opened on a list of calculation types, so the recommended workflow - a
task folder with an INCAR.mliport beside the structure, then `mliport run` with
no arguments - was not reachable from it at all, and the template screen
silently wrote an SP template when CONFSEARCH was selected.

What this changes:

- New `mliport/task_folder.py` (no Textual import, unit-testable):
  `create_task_folder` writes `INCAR.mliport` from the same generator as
  `mliport template` with `MODEL_TYPE`/`MODEL_PATH` filled in and copies the
  structure byte for byte under the name `mliport run` looks for (`POSCAR`,
  `structure.cif`, `structure.xyz`); a bare model file name stays a name so the
  `models/` lookup applies, anything else is recorded as an absolute path.
  `run_task_folder` is the single "run now" entry point: it chdirs into the
  folder and calls `mliport.cli.main(["run", "--incar", ...])`, i.e. exactly
  what `cd <folder> && mliport run` does. An unsupported suffix, an unknown
  calculation type, a template without the two model lines and an existing
  non-empty destination all fail closed.
- `MainScreen` now offers "New task" first, then "Advanced" and "Exit". The
  wizard asks three things - calculation type, structure file, model (backend
  first, then a file from the `models/` listing, or a typed path) - and shows
  the derived folder, the `cd <folder> && mliport run` command and any
  `REQUIRED` placeholder that still needs filling (NEB endpoints, confsearch
  starts).
- `AdvancedScreen` keeps every previous entry: the manual SP/OPT/MD/NEB/
  CONFSEARCH configuration screens, jobs, analysis and the template generator,
  which now accepts `confsearch` instead of falling back to SP.

Tests: `tests/mliport/mliport/test_task_folder_wizard.py` (23 tests) covers the
folder contents (byte-identical structure, shared template body, the generated
INCAR passing the same validation and resolution `mliport run` performs),
suffix normalization, the refusal cases, the retained bare model name, the
placeholder report, the `run` delegation (argv and working directory), the
wizard's create and create-and-run buttons, the `models/` listing and the new
navigation. The two existing main-screen navigation tests now look at the
Advanced menu. Full suite: 2303 passed, 48 skipped; ruff,
`scripts/check_repository_hygiene.py`, `scripts/generate_docs.py --check` and
`mkdocs build --strict` are clean.

Docs: `docs/configuration.md` (+ `.zh.md`) describes the wizard-first TUI and
the Advanced menu.

DATA IMPACT: no scientific record invalidated. The wizard writes new files only
(it refuses to overwrite a previous task's INCAR or structure) and reuses the
CLI run path, so no default, unit, PBC semantic, model task/head or dtype is
changed.

Tracking: #61
…bpaths

Review findings on the R5 delivery:

- The wizard filled `MODEL_PATH`/`MODEL_TYPE` and then offered a one-click
  `mliport run`, so the run inherited the template's hardcoded model decision:
  UMA's `TASK = omat` family and DPA's `HEAD = Omat24` branch were executed
  without the user ever choosing them (AGENTS.md rule 3: never silently change
  a model task/head). `TASK` (and `HEAD` where the backend has an active one)
  is now written as `REQUIRED`, the wizard lists it under "still to fill in",
  and `run` refuses the file until the user decides. A caller that already
  knows the decision can pass `task=`/`head=` explicitly.
- A model picked from a `models/` subdirectory (`uma/s1.pt`, exactly what the
  picker lists) was written as a working-directory-relative path, because the
  value contains a separator. Such a value is now looked up inside `models/`
  and recorded absolutely; a separated value that exists nowhere fails closed
  instead of producing an INCAR that cannot work.
- NEB and confsearch folders created by the wizard now report their unfilled
  endpoints/start keys (`NEB_INITIAL`/`NEB_FINAL` became real `REQUIRED`
  placeholders in the previous commit), which the old test wrongly pinned as
  "nothing pending".

Tests: the created INCAR is asserted to leave exactly `TASK` (plus `HEAD` for
DPA) pending and to pass validation/resolution once filled; new cases cover a
`models/`-relative entry, a separated value that does not exist, an
explicitly supplied task/head, and the updated placeholder report. The
productization invariant that compares raw template lines now strips the
generated inline comment (its intent - no active `MODEL_TYPE = UMA` - is
unchanged). Full suite: 2310 passed, 48 skipped; ruff clean.

DATA IMPACT: no scientific record invalidated. The wizard no longer starts a
run with a task/head the user did not choose, and no default, unit, PBC
semantic, model task/head or dtype was changed.

Tracking: #61
@hydrogen1222
hydrogen1222 force-pushed the feat/tui-task-folder-wizard branch from 02f5ffd to 0822c20 Compare November 17, 2026 11:19
@hydrogen1222
hydrogen1222 changed the base branch from feat/incar-option-table-and-docs to main November 17, 2026 11:19
#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).
@hydrogen1222
hydrogen1222 merged commit 449ec9a into main Nov 17, 2026
14 checks passed
@hydrogen1222
hydrogen1222 deleted the feat/tui-task-folder-wizard branch November 17, 2026 12:18
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