Release v3.1.0

.github/workflows/build_uw3_and_test.yaml

@@ -1,7 +1,12 @@
 name: test_uw3
 
-# We should trigger this from an upload event. Note that pdoc requires us to import the
-# built code, so this is a building test as well as documentation deployment
+# Build + test on every PR / push to main / development.
+#
+# Uses pixi (with the committed pixi.lock) for a deterministic, fast install
+# rather than micromamba + environment.yaml, which had been backtracking for
+# 60+ minutes on conda-forge solves and timing the runner out before tests
+# could start. The pixi.lock matches what local development uses, so CI now
+# runs against the same dependency state developers see.
 
 on:
   push:
@@ -17,27 +22,27 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    timeout-minutes: 60
+
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install Conda environment with Micromamba
-        uses: mamba-org/setup-micromamba@v2
+      - name: Install pixi from lockfile
+        uses: prefix-dev/setup-pixi@v0.9.4
         with:
-          environment-file: ./environment.yaml
-          cache-downloads: true
-          cache-environment: true
+          # Use the env that matches local development for tests.
+          # `dev` = conda-petsc + runtime + dev features (pytest, jupyter, etc.)
+          environments: dev
+          # Hard-fail if pixi.lock disagrees with pixi.toml — never re-solve
+          # silently in CI; that's exactly the failure mode we're escaping.
+          frozen: true
+          cache: true
 
       - name: Build UW3
-        shell: bash -l {0}
-        run: |
-          export PETSC_DIR="/home/runner/micromamba/envs/uw3_test/lib"
-          VERSION=`python3 setup.py --version`
-          echo "UW - version " ${VERSION}
-
-          ## TODO. Use scripts/compile.sh once it is in development
-          pip install -e . --no-build-isolation
+        # `pixi run -e dev build` invokes the build task from pixi.toml,
+        # which is `pip install . --no-build-isolation` (non-editable —
+        # editable installs are project policy violation, see CLAUDE.md).
+        run: pixi run -e dev build
 
       - name: Run tests
-        shell: bash -l {0}
-        run: |
-          ./scripts/test.sh --p 2
+        run: pixi run -e dev ./scripts/test.sh --p 2

.gitignore

@@ -255,4 +255,5 @@ docs/beginner/tutorials/html5/*.html
 .pixi-env
 # PETSc build (directory in main repo, symlink in worktrees)
 petsc-custom/petsc
+petsc-custom/.petsc-version
 Untitled*.ipynb

CHANGES.md

@@ -1,5 +1,75 @@
 # CHANGES: Underworld3
 
+## 2026-05-20
+
+  - **Snapshot toolkit (PRs #195, #196, #198)**: unified
+    state-capture mechanism for Underworld3 models.
+
+    User-facing API on `Model`:
+
+    ```python
+    token = model.save_state()                  # in-memory "stash for timesteps"
+    model.load_state(token)                     # exact restore from token
+
+    model.save_state(file="step42.snap.h5")     # persistent on-disk snapshot
+    model.load_state("step42.snap.h5")          # restore from disk
+    ```
+
+    Same call, two storage modes. Captures the full model — every
+    registered mesh and mesh-variable, every swarm with per-particle
+    data, every solver-internal state-bearer (`ModelTracker`, `DDt`
+    instances, anything exposing the `Snapshottable` contract). User
+    guide: `docs/advanced/snapshot-restore.md`.
+
+    - **In-memory mode** (#195): bit-exact discard-of-a-step
+      guarantee, proven through real PETSc solves; parallel-correct
+      under MPI at any fixed rank count (recovers from genuine
+      cross-rank particle loss); rebuild-on-restore semantics for
+      swarms (the discarded step *is* what restore exists to undo).
+    - **`Model.tracker`** (#196): model-dwelling, snapshot-managed
+      record of where a run is. Holds `time` / `step` / `dt` plus
+      any quantity the user parks on it (`model.tracker.foo = ...`)
+      — anything on the tracker reverts with the model. Solvers do
+      not depend on it; using it is optional. A loose Python
+      variable is not reverted by `load_state`; the same value on
+      the tracker is.
+    - **On-disk mode (v1.1, #198)**: HDF5 wrapper file + companion
+      `.bulk/` directory. Wrapper is `h5ls`-inspectable without UW3
+      in the loop (carries run name, schema version, sim time, step,
+      MPI rank count, mesh/swarm/variable inventories). Bulk data
+      uses PR #146's PETSc DMPlex primitives for mesh + meshvars;
+      swarms get per-rank h5py sidecars for parallel correctness.
+      Same-rank-count restart contract; clean errors on rank-count
+      mismatch.
+
+    Related API changes:
+
+    - `MeshVariable.read_timestep` is now format-aware: detects
+      whether the file is a legacy `write_timestep` per-variable
+      file or a v1.1 snapshot wrapper and dispatches internally.
+      Existing scripts that call `var.read_timestep(...)` work
+      transparently against new files via a KDTree bridge over
+      `MeshVariable.read_checkpoint` (#146).
+    - `mesh.write_timestep()` / `mesh.write_checkpoint()` (PR #146)
+      remain unchanged — they serve different use cases
+      (visualisation + flexible/cross-resolution restart;
+      memory-efficient same-rank PETSc reload for postprocessing).
+      See "Choosing between paths" in the user guide.
+
+    State-as-dataclass contract for solver helpers:
+    `docs/developer/guides/state-as-dataclass.md` — declare
+    mutable evolution state as a `SnapshottableState` dataclass
+    and the snapshot mechanism captures/restores it with no extra
+    plumbing. Retrofitted for all five DDt flavors in this work
+    (`Symbolic`, `Eulerian`, `SemiLagrangian`, `Lagrangian`,
+    `Lagrangian_Swarm`).
+
+  - **Fix(ddt): `Lagrangian.__init__` typo (`uw.swarm.UWSwarm` →
+    `uw.swarm.Swarm`)** (PR #184). Lagrangian DDt had been
+    unconstructible since commit `0778b7d` (2025-07-07) — typo
+    introduced during the unrelated `evalf` cleanup. Surfaced
+    during the snapshot toolkit's retrofit work.
+
 ## 2026-03-14
 
   - **Release v3.0.0**: Merged development (398 commits) to main, tagged v3.0.0