assystant 0.1.0__tar.gz

assystant-0.1.0/.github/workflows/clean-install.yml

@@ -0,0 +1,143 @@
+# Proves a fresh environment can `pip install assystant` with no
+# --no-build-isolation and no pre-installed scientific stack: build sdist and
+# wheel in isolation, install each into an empty venv from outside the
+# checkout, then run the CLI and the test suite against the installed copy.
+#
+# Upstream requirements that are not released yet are built as release
+# candidates by the `upstream` job (see there).
+
+name: clean-install
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  # Release candidates for upstream packages that are not on PyPI yet.
+  # For each requirement below, if PyPI already satisfies it nothing is built
+  # and the install jobs test against the published release. Otherwise a wheel
+  # is built from the upstream pull request that prepares that release (the
+  # same way its release workflow will build it) and handed to the install
+  # jobs via --find-links. Once the releases are out this job is a no-op and
+  # the CANDIDATES entries can be deleted.
+  upstream:
+    runs-on: ubuntu-latest
+    env:
+      # requirement | GitHub repo | git ref | versioneer tag to stamp (or "-")
+      CANDIDATES: |
+        pyiron_workflow_vasp>=0.2.0,<0.3 | pyiron/pyiron_workflow_vasp | pull/7/head | pyiron_workflow_vasp-0.2.0
+        pyiron_workflow_assyst>=0.2.0,<0.3 | ligerzero-ai/pyiron_workflow_assyst | pull/2/head | -
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheels for unreleased upstream requirements
+        run: |
+          set -euo pipefail
+          python -m pip install --upgrade pip build pyyaml==6.0.1 toml==0.10.2
+          WH="$RUNNER_TEMP/wheelhouse"; mkdir -p "$WH"
+          while IFS='|' read -r req repo ref tag; do
+            req=$(echo "$req" | xargs); repo=$(echo "$repo" | xargs)
+            ref=$(echo "$ref" | xargs); tag=$(echo "$tag" | xargs)
+            [ -z "$req" ] && continue
+            if python -m pip download -q --no-deps -d "$RUNNER_TEMP/probe" "$req" 2>/dev/null; then
+              echo "::notice::$req is on PyPI; testing against the release"
+              continue
+            fi
+            echo "::warning::$req is not on PyPI yet; building a candidate from $repo@$ref"
+            src="$RUNNER_TEMP/src-${repo##*/}"
+            git clone -q "https://github.com/$repo" "$src"
+            git -C "$src" fetch -q origin "$ref"
+            git -C "$src" checkout -q FETCH_HEAD
+            if [ "$tag" != "-" ]; then
+              # -f: the upstream tag may already exist on another commit; this
+              # clone is throwaway, so stamping the candidate is local only.
+              git -C "$src" -c user.name=ci -c user.email=ci@localhost tag -f "$tag"
+            fi
+            # pyiron release workflows rewrite == pins into ranges before
+            # building; do the same so the candidate carries release metadata.
+            script="$src/.github/actions/.support/update_pyproject_dependencies.py"
+            if [ -f "$script" ]; then
+              (cd "$src" && python "$script" --input_toml=pyproject.toml \
+                --lower_bound_yaml=.ci_support/lower-bound.yml \
+                --upper_bound_yaml=.ci_support/upper-bound.yml \
+                --semantic_upper_bound=minor --always_pin_unstable=yes \
+                --output_toml=none \
+                --pypi_to_conda_name_map_file=.github/actions/.support/pypi_vs_conda_names.json)
+            fi
+            python -m build --wheel --outdir "$WH" "$src"
+          done <<< "$CANDIDATES"
+          # The artifact must exist even when nothing was built, and upload-artifact
+          # skips hidden files, so leave a visible manifest.
+          (cd "$WH" && ls *.whl 2>/dev/null || true) > "$WH/MANIFEST.txt"
+          ls -la "$WH"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheelhouse
+          path: ${{ runner.temp }}/wheelhouse/
+          if-no-files-found: ignore
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel (isolated)
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  install:
+    needs: [build, upstream]
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        source: [wheel, sdist]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/download-artifact@v4
+        with:
+          name: wheelhouse
+          path: ${{ runner.temp }}/wheelhouse
+      - name: Install into a fresh venv from outside the checkout
+        run: |
+          WORK="$RUNNER_TEMP/clean"
+          mkdir -p "$WORK"
+          python -m venv "$WORK/venv"
+          "$WORK/venv/bin/python" -m pip install --upgrade pip
+          if [ "${{ matrix.source }}" = wheel ]; then
+            PKG=$(ls "$GITHUB_WORKSPACE"/dist/*.whl)
+          else
+            PKG=$(ls "$GITHUB_WORKSPACE"/dist/*.tar.gz)
+          fi
+          cd "$WORK"
+          "$WORK/venv/bin/python" -m pip install --find-links "$RUNNER_TEMP/wheelhouse" "${PKG}[test]"
+          "$WORK/venv/bin/python" -m pip check
+      - name: Import and CLI smoke test
+        working-directory: ${{ runner.temp }}/clean
+        run: |
+          venv/bin/python -c "import assystant, sys; print(assystant.__version__, assystant.__file__); assert 'site-packages' in assystant.__file__"
+          venv/bin/assystant --help
+          venv/bin/assystant gen "$GITHUB_WORKSPACE/examples/Al_tutorial.yaml" --root "$RUNNER_TEMP/clean/camp" --no-progress
+      - name: Test suite against the installed package
+        working-directory: ${{ runner.temp }}/clean
+        run: |
+          cp -r "$GITHUB_WORKSPACE/tests" tests
+          venv/bin/python -m pytest tests -q -p no:cacheprovider

assystant-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,104 @@
+# Build and publish assystant to PyPI.
+#
+# - pull_request: build + `twine check` only (dry run, nothing is published).
+# - release published: build, verify the release tag matches the package
+#   version, then publish via PyPI trusted publishing (OIDC, no API token).
+#
+# Trusted publisher on PyPI: owner ligerzero-ai, repository assystant,
+# workflow release.yml, environment pypi.
+
+name: release
+
+on:
+  release:
+    types: [published]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check distributions
+        run: twine check --strict dist/*
+
+      - name: Verify release tag matches package version
+        if: github.event_name == 'release'
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+          DIST: assystant
+        run: |
+          set -euo pipefail
+          wheels=(dist/*.whl)
+          if [ "${#wheels[@]}" -ne 1 ]; then
+            echo "::error::expected exactly one wheel in dist/, found ${#wheels[@]}"
+            exit 1
+          fi
+          wheel_version=$(basename "${wheels[0]}" | cut -d- -f2)
+          meta_version=$(python - "${wheels[0]}" <<'PY'
+          import sys, zipfile
+          from email.parser import Parser
+          with zipfile.ZipFile(sys.argv[1]) as zf:
+              name = next(n for n in zf.namelist() if n.endswith(".dist-info/METADATA"))
+              print(Parser().parsestr(zf.read(name).decode())["Version"])
+          PY
+          )
+          if [ "$wheel_version" != "$meta_version" ]; then
+            echo "::error::wheel filename version $wheel_version != METADATA version $meta_version"
+            exit 1
+          fi
+          # Accept "v<ver>", "<dist>-<ver>" (underscore or hyphen spelling), or "<ver>".
+          ver="$TAG"
+          for prefix in "v" "${DIST}-" "${DIST//_/-}-"; do
+            if [ "${ver#"$prefix"}" != "$ver" ]; then
+              ver="${ver#"$prefix"}"
+              break
+            fi
+          done
+          if [ "$ver" != "$meta_version" ]; then
+            echo "::error::release tag '$TAG' (version '$ver') does not match package version '$meta_version'"
+            exit 1
+          fi
+          echo "Tag '$TAG' matches package version $meta_version"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/assystant
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

assystant-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.superpowers/
+*.egg-info/
+build/
+dist/
+.ipynb_checkpoints/
+pyiron.log

assystant-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[semantic versioning](https://semver.org/).
+
+## [0.1.0] - Unreleased
+
+Initial release.
+
+### Added
+
+- `assystant` command-line driver for ASSYST campaigns:
+  - `gen`: PyXtal structure generation and INCAR assembly from a campaign config.
+  - `run`: per-structure DFT submission to SLURM via `sbatch`, with an in-job
+    runner and a `--dry-run` mode.
+  - `status`: campaign progress across structures.
+  - `collect`: collation of finished calculations into a training dataset.
+- `vasp.launcher` config option for the MPI launcher.
+- User documentation set under `docs/` and a runnable example campaign
+  (`examples/Fe_smoke.yaml`).
+- CI: `clean-install` workflow and a `release` workflow that publishes to PyPI
+  via trusted publishing.

assystant-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Han Lin Mai, Max-Planck-Institut für Nachhaltige Materialien GmbH (MPI-SusMat)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

assystant-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.5
+Name: assystant
+Version: 0.1.0
+Summary: Command-line driver for ASSYST campaigns: PyXtal generation -> per-structure DFT on SLURM -> collated training dataset
+Author: Han Lin Mai
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: assyst,dft,machine-learning-potentials,pyxtal,slurm,vasp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: <3.14,>=3.11
+Requires-Dist: numpy
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: pyiron-workflow-assyst<0.3,>=0.2.0
+Requires-Dist: pyiron-workflow<0.21,>=0.19
+Requires-Dist: pymatgen>=2023.0.0
+Requires-Dist: pyxtal>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tqdm>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=2.0; extra == 'dev'
+Requires-Dist: pytest>=6.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest>=6.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# assystant
+
+Run an ASSYST campaign end to end from a single YAML file: PyXtal structure
+generation → one SLURM job per structure running the ISIF7 → ISIF5 → ISIF2
+relaxation and permutation-statics chain → a single collated training dataset.
+
+ASSYST generates DFT training data for interatomic potentials: random crystals
+across all 230 spacegroups, relaxed through a three-stage ISIF chain, then
+high-accuracy statics on the relaxed images *and* on rattled, triaxially strained
+and sheared permutations of them — the off-equilibrium configurations a potential
+needs and that ordinary MD never visits.
+
+`assystant` drives that per campaign, replacing hand-copied
+`2025_03_16_Unaries.py` scripts, element lists hardcoded in notebook cells, and a
+`submit_temp.sh` maintained by hand with one line per element.
+
+```bash
+assystant gen     camp.yaml                        # PyXtal scan -> POSCARs + manifest
+assystant run     camp.yaml --dry-run --limit 1    # render one job; read it
+assystant run     camp.yaml                        # submit; also the resume command
+assystant status  camp.yaml --watch 300            # progress
+assystant collect camp.yaml -o train.pkl           # one dataframe
+```
+
+## Documentation
+
+| | |
+|---|---|
+| [**Overview**](docs/overview.md) | what ASSYST does, what `assystant` adds, how the three repos fit together |
+| [**Installation**](docs/installation.md) | dependencies, install order, the POTCAR config |
+| [**Worked example**](docs/worked-example.md) | a complete campaign, start to finish, that you can copy |
+| [**Configuration**](docs/configuration.md) | every YAML key: meaning, default, when to change it |
+| [**Commands**](docs/commands.md) | `gen` / `run` / `status` / `collect` reference |
+| [**Operations**](docs/operations.md) | content-hashed directories, the staleness guard, `--from-scratch`, smoke testing — the part that saves days |
+| [**Behaviour changes**](docs/behaviour-changes.md) | read before comparing new data against pre-2026 campaigns |
+| [**Troubleshooting**](docs/troubleshooting.md) | real failure modes and their actual error text |
+
+Background: [design spec](docs/2026_07_31_assystant_design.md) ·
+[implementation report](docs/implementation-report.txt)
+
+## Install
+
+```bash
+python -m pip install assystant
+```
+
+Python 3.11–3.13. No `--no-build-isolation`, no pre-installed scientific stack:
+`pip`, `uv pip install assystant`, a `venv`, a conda/mamba env or a pixi project
+all work the same way. See [installation](docs/installation.md) for each variant,
+the POTCAR configuration and what a real run additionally needs (SLURM, a VASP
+binary).
+
+> **Pre-release:** until `pyiron_workflow_vasp` 0.2.0 and
+> `pyiron_workflow_assyst` 0.2.0 are on PyPI, install those two from their wheels
+> first — see [installation](docs/installation.md#before-the-dependencies-are-on-pypi).
+
+## Quick start
+
+```bash
+assystant --help
+assystant gen examples/Al_tutorial.yaml --root ./al_campaign --no-progress
+```
+
+`gen` needs neither SLURM nor VASP, so this works on any machine: it writes 43
+POSCARs and a `manifest.csv` under `./al_campaign/Al/`. `--root` overrides the
+cluster path in the YAML. To go further — `run`, `status`, `collect` — edit the
+`slurm:` and `vasp:` sections to point at your partition, environment and VASP
+binary, and set up the [POTCAR config](docs/installation.md#the-potcar-library).
+
+[`examples/Al_tutorial.yaml`](examples/Al_tutorial.yaml) is a small, complete,
+minutes-long campaign walked through in
+[`docs/worked-example.md`](docs/worked-example.md).
+[`examples/Fe_unary.yaml`](examples/Fe_unary.yaml) shows production settings.
+[`examples/Fe_smoke.yaml`](examples/Fe_smoke.yaml) proves an install actually runs
+DFT, on a login node, in under a minute.
+
+## Layout on disk
+
+```
+<root>/
+  assystant_config.yaml                 the resolved config `run` was launched with
+  Fe/
+    manifest.csv                        index, hash, spacegroup, composition, n_atoms, V/atom
+    structures/00000_structure.vasp ...
+    struct_00000_3f9c1a20/              one per structure, content-hashed
+      assystant_job.sh
+      assystant.out / assystant.err
+      ISIF7.tar.gz  ISIF5.tar.gz  ISIF2.tar.gz  ...
+      df_ASSYST_jobs.pkl                present == finished
+```
+
+The `_3f9c1a20` is the first eight hex digits of the SHA-256 of the POSCAR. That
+is a correctness mechanism, not a naming convention — the caching layer
+underneath keys on directory path and never hashes its inputs, so a
+content-derived name is what stops one structure's results from being served for
+another. See
+[content-hashed run directories](docs/operations.md#content-hashed-run-directories).
+
+## Three things to know before your first campaign
+
+1. **Start with `--limit 1`.** A dry run proves the script renders; it cannot
+   prove the VASP binary, the modules, the POTCAR library or your INCAR work on a
+   compute node. Submit one, check it, then submit the rest.
+2. **`IBRION` is required** whenever `assyst.ionic_steps > 0`. A missing one makes
+   VASP default to molecular dynamics and refuse the job. Use `IBRION: 2`.
+3. **`ionic_steps` now applies to all three ISIF stages**, where pre-2026
+   campaigns applied it to ISIF7 only. New ISIF5/ISIF2 data is not directly
+   comparable with old datasets — see
+   [behaviour changes](docs/behaviour-changes.md).
+
+## Tests
+
+```bash
+python -m pip install "assystant[test]"
+pytest tests/ -q
+```
+
+108 tests. None call SLURM or VASP; `submit_campaign` takes `queued_dirs` and
+`submit_fn` injection seams for exactly that reason. For an end-to-end check that
+runs real DFT, use [`examples/Fe_smoke.yaml`](examples/Fe_smoke.yaml).
+
+## Releasing
+
+Releases go to PyPI from GitHub Actions via
+[trusted publishing](https://docs.pypi.org/trusted-publishers/), so no API token
+is stored anywhere.
+
+1. Bump `__version__` in `assystant/__init__.py` (the only place the version lives) and add
+   an entry to [`CHANGELOG.md`](CHANGELOG.md).
+2. Open a PR and merge it to `main`. The
+   [`release`](.github/workflows/release.yml) workflow builds the sdist and
+   wheel and runs `twine check --strict` on every PR as a dry run.
+3. Create a GitHub release with tag `v<version>` (e.g. `v0.1.0`). Publishing
+   the release builds again, checks that the tag matches the package version
+   (a `v` or `assystant-` prefix is stripped), and uploads to
+   [PyPI](https://pypi.org/p/assystant).
+
+One-time setup: on PyPI, add a trusted publisher for `assystant` with owner
+`ligerzero-ai`, repository `assystant`, workflow `release.yml` and environment
+`pypi`, and create a `pypi` environment in the GitHub repository settings
+(optionally with required reviewers).

assystant-0.1.0/README.md

@@ -0,0 +1,141 @@
+# assystant
+
+Run an ASSYST campaign end to end from a single YAML file: PyXtal structure
+generation → one SLURM job per structure running the ISIF7 → ISIF5 → ISIF2
+relaxation and permutation-statics chain → a single collated training dataset.
+
+ASSYST generates DFT training data for interatomic potentials: random crystals
+across all 230 spacegroups, relaxed through a three-stage ISIF chain, then
+high-accuracy statics on the relaxed images *and* on rattled, triaxially strained
+and sheared permutations of them — the off-equilibrium configurations a potential
+needs and that ordinary MD never visits.
+
+`assystant` drives that per campaign, replacing hand-copied
+`2025_03_16_Unaries.py` scripts, element lists hardcoded in notebook cells, and a
+`submit_temp.sh` maintained by hand with one line per element.
+
+```bash
+assystant gen     camp.yaml                        # PyXtal scan -> POSCARs + manifest
+assystant run     camp.yaml --dry-run --limit 1    # render one job; read it
+assystant run     camp.yaml                        # submit; also the resume command
+assystant status  camp.yaml --watch 300            # progress
+assystant collect camp.yaml -o train.pkl           # one dataframe
+```
+
+## Documentation
+
+| | |
+|---|---|
+| [**Overview**](docs/overview.md) | what ASSYST does, what `assystant` adds, how the three repos fit together |
+| [**Installation**](docs/installation.md) | dependencies, install order, the POTCAR config |
+| [**Worked example**](docs/worked-example.md) | a complete campaign, start to finish, that you can copy |
+| [**Configuration**](docs/configuration.md) | every YAML key: meaning, default, when to change it |
+| [**Commands**](docs/commands.md) | `gen` / `run` / `status` / `collect` reference |
+| [**Operations**](docs/operations.md) | content-hashed directories, the staleness guard, `--from-scratch`, smoke testing — the part that saves days |
+| [**Behaviour changes**](docs/behaviour-changes.md) | read before comparing new data against pre-2026 campaigns |
+| [**Troubleshooting**](docs/troubleshooting.md) | real failure modes and their actual error text |
+
+Background: [design spec](docs/2026_07_31_assystant_design.md) ·
+[implementation report](docs/implementation-report.txt)
+
+## Install
+
+```bash
+python -m pip install assystant
+```
+
+Python 3.11–3.13. No `--no-build-isolation`, no pre-installed scientific stack:
+`pip`, `uv pip install assystant`, a `venv`, a conda/mamba env or a pixi project
+all work the same way. See [installation](docs/installation.md) for each variant,
+the POTCAR configuration and what a real run additionally needs (SLURM, a VASP
+binary).
+
+> **Pre-release:** until `pyiron_workflow_vasp` 0.2.0 and
+> `pyiron_workflow_assyst` 0.2.0 are on PyPI, install those two from their wheels
+> first — see [installation](docs/installation.md#before-the-dependencies-are-on-pypi).
+
+## Quick start
+
+```bash
+assystant --help
+assystant gen examples/Al_tutorial.yaml --root ./al_campaign --no-progress
+```
+
+`gen` needs neither SLURM nor VASP, so this works on any machine: it writes 43
+POSCARs and a `manifest.csv` under `./al_campaign/Al/`. `--root` overrides the
+cluster path in the YAML. To go further — `run`, `status`, `collect` — edit the
+`slurm:` and `vasp:` sections to point at your partition, environment and VASP
+binary, and set up the [POTCAR config](docs/installation.md#the-potcar-library).
+
+[`examples/Al_tutorial.yaml`](examples/Al_tutorial.yaml) is a small, complete,
+minutes-long campaign walked through in
+[`docs/worked-example.md`](docs/worked-example.md).
+[`examples/Fe_unary.yaml`](examples/Fe_unary.yaml) shows production settings.
+[`examples/Fe_smoke.yaml`](examples/Fe_smoke.yaml) proves an install actually runs
+DFT, on a login node, in under a minute.
+
+## Layout on disk
+
+```
+<root>/
+  assystant_config.yaml                 the resolved config `run` was launched with
+  Fe/
+    manifest.csv                        index, hash, spacegroup, composition, n_atoms, V/atom
+    structures/00000_structure.vasp ...
+    struct_00000_3f9c1a20/              one per structure, content-hashed
+      assystant_job.sh
+      assystant.out / assystant.err
+      ISIF7.tar.gz  ISIF5.tar.gz  ISIF2.tar.gz  ...
+      df_ASSYST_jobs.pkl                present == finished
+```
+
+The `_3f9c1a20` is the first eight hex digits of the SHA-256 of the POSCAR. That
+is a correctness mechanism, not a naming convention — the caching layer
+underneath keys on directory path and never hashes its inputs, so a
+content-derived name is what stops one structure's results from being served for
+another. See
+[content-hashed run directories](docs/operations.md#content-hashed-run-directories).
+
+## Three things to know before your first campaign
+
+1. **Start with `--limit 1`.** A dry run proves the script renders; it cannot
+   prove the VASP binary, the modules, the POTCAR library or your INCAR work on a
+   compute node. Submit one, check it, then submit the rest.
+2. **`IBRION` is required** whenever `assyst.ionic_steps > 0`. A missing one makes
+   VASP default to molecular dynamics and refuse the job. Use `IBRION: 2`.
+3. **`ionic_steps` now applies to all three ISIF stages**, where pre-2026
+   campaigns applied it to ISIF7 only. New ISIF5/ISIF2 data is not directly
+   comparable with old datasets — see
+   [behaviour changes](docs/behaviour-changes.md).
+
+## Tests
+
+```bash
+python -m pip install "assystant[test]"
+pytest tests/ -q
+```
+
+108 tests. None call SLURM or VASP; `submit_campaign` takes `queued_dirs` and
+`submit_fn` injection seams for exactly that reason. For an end-to-end check that
+runs real DFT, use [`examples/Fe_smoke.yaml`](examples/Fe_smoke.yaml).
+
+## Releasing
+
+Releases go to PyPI from GitHub Actions via
+[trusted publishing](https://docs.pypi.org/trusted-publishers/), so no API token
+is stored anywhere.
+
+1. Bump `__version__` in `assystant/__init__.py` (the only place the version lives) and add
+   an entry to [`CHANGELOG.md`](CHANGELOG.md).
+2. Open a PR and merge it to `main`. The
+   [`release`](.github/workflows/release.yml) workflow builds the sdist and
+   wheel and runs `twine check --strict` on every PR as a dry run.
+3. Create a GitHub release with tag `v<version>` (e.g. `v0.1.0`). Publishing
+   the release builds again, checks that the tag matches the package version
+   (a `v` or `assystant-` prefix is stripped), and uploads to
+   [PyPI](https://pypi.org/p/assystant).
+
+One-time setup: on PyPI, add a trusted publisher for `assystant` with owner
+`ligerzero-ai`, repository `assystant`, workflow `release.yml` and environment
+`pypi`, and create a `pypi` environment in the GitHub repository settings
+(optionally with required reviewers).

assystant-0.1.0/assystant/__init__.py

@@ -0,0 +1,38 @@
+"""assystant -- run an ASSYST campaign end to end from one YAML file.
+
+``gen`` generates PyXtal structures, ``run`` submits one SLURM job per
+structure, ``status`` reports progress, ``collect`` concatenates the results
+into a single training dataset.
+"""
+
+from .config import (
+    CampaignConfig,
+    ConfigError,
+    StaleConfigError,
+    system_name,
+)
+from .generate import (
+    enumerate_compositions,
+    parse_struct_dir,
+    poscar_hash,
+    struct_dir_name,
+)
+from .incar import get_incar_magmom_string, stack_element_string
+from .submit import RESULT_FILENAME
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CampaignConfig",
+    "ConfigError",
+    "StaleConfigError",
+    "system_name",
+    "enumerate_compositions",
+    "parse_struct_dir",
+    "poscar_hash",
+    "struct_dir_name",
+    "get_incar_magmom_string",
+    "stack_element_string",
+    "RESULT_FILENAME",
+    "__version__",
+]