pdate tutorial steps 8-10 to the redesigned httk-workflow CLI and templates

Author: rartino

docs/tutorial/08-prepare-vasp.md

@@ -1,30 +1,39 @@
 # Prepare a VASP calculation
 
-```{admonition} Status
-:class: caution
+In v1 this was a Python call (`prepare_single_run`) followed by running
+`vasp` by hand. In v2 the packaged VASP runners do both halves: preparation
+derives every input you do not supply, and the workflow manager runs the
+calculation.
 
-V2 has dependency-free VASP work-directory preparation, but not yet the v1
-one-call path from `UnitcellStructure` to a complete run directory. In particular,
-*httk-io* reads POSCAR but does not write it. Supply `Run/POSCAR` and
-`Run/INCAR`, then prepare the remaining inputs explicitly.
+```console
+httk project init --name tutorial
+httk workflow job new --template vasp-static --from POSCAR --tag example
+httk workflow workspace settings set vasp.command vasp_std
+httk workflow workspace settings set vasp.pseudo_library /path/to/potpaw_PBE
+httk workflow run
 ```
 
-```python
-from httk.workflow.vasp import VaspPreparationOptions, prepare_vasp_inputs
+`job new` scaffolds and submits one job from the packaged `vasp-static`
+template (`vasp-relax` and `vasp-relax-static` work the same way), staging the
+structure as the `files/POSCAR` the runner reads. No INCAR, KPOINTS, or POTCAR
+needs to be written: the runner's `prepare` step derives the k-point grid,
+assembles the POTCAR from the pseudopotential library, and fills in `MAGMOM`
+and `NBANDS`, with any explicit `--input incar_tags=...` winning over derived
+values. `run` executes the manager until nothing is ready, driving the job
+through prepare, run, and collect; the results and logs end up in the payload
+directory the `job new` command printed.
 
-choices = prepare_vasp_inputs(
-    VaspPreparationOptions(
-        pseudopotential_library="/path/to/potpaw_PBE",
-        kpoint_density=40,
-    ),
-    directory="Run",
-)
-print(choices)
-```
+Both `vasp.*` settings are stored on the workspace, so they are set once, not
+per job; a real `HTTK_VASP_COMMAND` environment variable remains a deployment
+override and wins over the workspace setting.
 
-This normalizes POSCAR handedness, assembles POTCAR, writes KPOINTS, and updates
-INCAR with recorded choices. Execution is separately available through
-`run_vasp` or the native workflow runner API.
+```{admonition} Status
+:class: caution
+
+The starting structure must already be a VASP structure file: *httk-io* reads
+POSCAR but does not yet write it, so there is no route yet from a loaded
+`UnitcellStructure` (steps 1–7) to a POSCAR on disk.
+```
 
-See the workflow runner helpers in the versioned *httk-workflow* documentation
-listed by the {doc}`module directory <../modules>`.
+See the quickstart and the packaged VASP runner guide in the versioned
+*httk-workflow* documentation listed by the {doc}`module directory <../modules>`.

docs/tutorial/09-create-batch.md

@@ -1,36 +1,43 @@
 # Generate a batch of jobs
 
-V2 replaces implicit task directories with explicit immutable job payloads.
-This small example creates and submits one payload per name:
+Point `job new` at a *directory* and every `POSCAR*` or `*.vasp` file in it
+becomes one job, each tagged after its file. The runner is published once for
+the whole set:
+
+```console
+httk workflow job new --template vasp-relax --from structures/ \
+    --input kpoint_density=30.0 --placement batch
+```
+
+In Python the same thing streams, which is how a batch of any size is built —
+neither side of the loop is ever materialized, and each job costs one payload
+directory and one state marker:
 
 ```python
 from pathlib import Path
 
-from httk.workflow import Workspace
-from httk.workflow.runtime_builders import JobSpec, prepare_job_payload
-
-workspace = Workspace.initialize("Runs")
-
-for name in ("CaTiO3", "TiO2", "CaO"):
-    payload = Path("payloads") / name
-    payload.mkdir(parents=True)
-    runner = payload / "run.sh"
-    runner.write_text("#!/bin/sh\nexec vasp_std\n", encoding="utf-8")
-    runner.chmod(0o755)
-
-    prepare_job_payload(
-        payload,
-        JobSpec(
-            name=name,
-            workflow="presentation.vasp-static",
-            runner_path="run.sh",
-            claim_pool="vasp",
-        ),
-    )
-    workspace.submit(payload, f"batch/{name}")
+from httk.workflow import Workspace, new_jobs
+from httk.workflow.registry import default_workspace
+from httk.workflow.scaffold import structure_tag
+
+workspace = Workspace(default_workspace().path)
+items = (
+    {"files": {"POSCAR": path}, "tag": structure_tag(path)}
+    for path in sorted(Path("structures").glob("POSCAR.*"))
+)
+for job in new_jobs(workspace, "vasp-relax", items, inputs={"kpoint_density": 30.0}):
+    print(job.job_key)
+```
+
+```{admonition} Status
+:class: caution
+
+v1 fed a database search directly into batch creation
+(`create_batch_task(..., {"structure": struct})`). The v2 equivalent —
+streaming the structures found in step 7 into `new_jobs` — waits on the
+POSCAR writer noted in step 8; today the batch starts from structure files
+on disk.
 ```
 
-A real payload also carries immutable POSCAR, INCAR, and other inputs. The
-runner should publish a structured success, failure, retry, or next-step
-outcome; see the *httk-workflow* native APIs in the versioned documentation
-listed by the {doc}`module directory <../modules>`.
+See the quickstart and the workflow CLI guide in the versioned *httk-workflow*
+documentation listed by the {doc}`module directory <../modules>`.

docs/tutorial/10-run-remotely.md

@@ -1,28 +1,35 @@
 # Send and run a batch remotely
 
-Remote setup and transfer remain command-line operations, now under the
-`httk workflow` command tree. The maintained adapters are explicit,
-versioned bundles.
+A *remote* is one machine the project can reach, named like a `git remote`; a
+workspace on it is addressed `REMOTE:NAME`. Setting up a cluster is a one-time
+sequence:
 
 ```console
-httk workflow project init . --name tutorial --default-queue default
-httk workflow remote add kappa --template ssh-slurm --non-interactive
-httk workflow remote configure kappa:default \
-  --set workspace=/remote/path/to/Runs
-httk workflow remote install kappa:default
+httk workflow remote add kappa --template ssh-slurm
+httk workflow remote configure kappa \
+    --set host=kappa.example.org --set username=rar \
+    --set workspace_root=/scratch/rar/httk
+httk workflow remote install kappa
+httk workflow workspace init kappa:runs
+httk workflow workspace settings set kappa:runs vasp.command "srun -n 32 vasp_std"
+```
+
+After that, each batch is send, run, watch — and one command to bring the
+finished jobs home:
 
-httk workflow workspace init local-runs --remote local --path Runs \
-  --extension detached-transfer-v1
-httk workflow workspace init kappa-runs --remote kappa:default \
-  --path /remote/path/to/Runs --extension detached-transfer-v1
-httk workflow transfer local-runs kappa-runs --job JOB_UUID
-httk workflow manager run kappa-runs --workers 8
-httk workflow workspace status kappa-runs
+```console
+httk workflow transfer default kappa:runs --placement batch
+httk workflow run kappa:runs --workers 8
+httk workflow workspace status kappa:runs
+httk workflow transfer kappa:runs default
 ```
 
-Both named workspaces must already exist with the `detached-transfer-v1`
-extension. Transfers preserve the job UUID, seal and validate payload digests,
-and retire the source only after acknowledgement.
+`transfer` detaches the selected jobs from the local default workspace, pushes
+each sealed bundle, validates its digest, and retires the source only after
+acknowledgement, so a job never exists in two runnable places. `run` on a
+remote workspace submits managers through the remote's scheduler over its
+adapter. The reverse `transfer` pulls home whatever has finished; a local
+`httk workflow harvest` then reads the results (next step).
 
-See the project and workflow CLI guide in the versioned *httk-workflow*
+See the task manager and workflow CLI guides in the versioned *httk-workflow*
 documentation listed by the {doc}`module directory <../modules>`.

docs/tutorial/index.md

@@ -31,7 +31,7 @@ python -m pip install httk2 "httk-data[db]" ase
 | 6 | Store structure data in SQLite | Available through representation-specific Records | `httk-data` |
 | 7 | Search the local database | Available | `httk-data` |
 | 8 | Prepare a VASP calculation | Partial: workdir preparation, no structure writer | `httk-workflow` |
-| 9 | Generate a batch | Available as explicit job payloads | `httk-workflow` |
+| 9 | Generate a batch | Available through job templates; database-fed batches need the POSCAR writer | `httk-workflow` |
 | 10 | Send and run remotely | Available through remote adapters | `httk-workflow` |
 | 11 | Read results into the database | Available as explicit extraction + record storage | `httk-workflow` + `httk-data` |
 | 12 | Draw a phase diagram | Available | `httk-analyse` |