Merge development: add GitHub Release workflow and release notes

Underworld development team with AI support from Claude Code

# Conflicts:
#	docs/conf.py

Author: lmoresi

.github/workflows/binder-image.yml

@@ -8,7 +8,7 @@ name: "GHCR: Binder Base Image"
 
 on:
   push:
-    branches: [main, development, 'release/*']
+    branches: [main, development]
     tags: ['v*']  # Build on release tags (v3.0.0, v3.1.0, etc.)
     paths:
       # Only rebuild when these files change (Cython/dependencies require rebuild)

.github/workflows/release.yml

@@ -0,0 +1,68 @@
+name: Create GitHub Release
+
+# Creates a GitHub Release when a version tag is pushed.
+#
+# If a release notes file exists at docs/release-notes/vX.Y.Z.md,
+# it is used as the release body (published immediately).
+# If no notes file exists, a draft release is created instead —
+# someone must write the notes and publish manually.
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write
+
+jobs:
+  create-release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        run: |
+          TAG_NAME=${GITHUB_REF#refs/tags/}
+          echo "TAG_NAME=${TAG_NAME}" >> $GITHUB_ENV
+
+          # Detect pre-releases (alpha, beta, rc)
+          if [[ "$TAG_NAME" =~ (a|b|rc)[0-9]+ ]]; then
+            echo "IS_PRERELEASE=true" >> $GITHUB_ENV
+          else
+            echo "IS_PRERELEASE=false" >> $GITHUB_ENV
+          fi
+
+      - name: Check for release notes file
+        id: notes
+        run: |
+          NOTES_FILE="docs/release-notes/${TAG_NAME}.md"
+          if [ -f "$NOTES_FILE" ]; then
+            echo "found=true" >> $GITHUB_OUTPUT
+            echo "path=${NOTES_FILE}" >> $GITHUB_OUTPUT
+          else
+            echo "found=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create release (with notes)
+        if: steps.notes.outputs.found == 'true'
+        run: |
+          gh release create "$TAG_NAME" \
+            --title "Underworld3 ${TAG_NAME}" \
+            --notes-file "${{ steps.notes.outputs.path }}" \
+            ${{ env.IS_PRERELEASE == 'true' && '--prerelease' || '' }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create draft release (no notes file)
+        if: steps.notes.outputs.found == 'false'
+        run: |
+          gh release create "$TAG_NAME" \
+            --title "Underworld3 ${TAG_NAME}" \
+            --draft \
+            --generate-notes \
+            --notes "$(printf '> **Release notes not yet written.**\n>\n> No file found at `docs/release-notes/%s.md`.\n> Please add release notes and publish this draft.\n\n---\n\n## Auto-generated commit log\n\n' "$TAG_NAME")$(gh api repos/${{ github.repository }}/releases/generate-notes -f tag_name="$TAG_NAME" --jq '.body' 2>/dev/null || echo 'See commit history for changes.')" \
+            ${{ env.IS_PRERELEASE == 'true' && '--prerelease' || '' }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CHANGES.md

@@ -1,5 +1,22 @@
 # CHANGES: Underworld3
 
+## 2026-03-14
+
+  - **Release v3.0.0**: Merged development (398 commits) to main, tagged v3.0.0
+  - **Release v0.99**: Tagged pixi-compatible snapshot of previous main for JOSS compatibility
+  - Binder infrastructure overhaul:
+    - Four versioned binder links: v0.99, v3.0.0, main, development
+    - CI workflow handles nested branch names and `v*` tag builds
+    - Manual dispatch overrides (`uw3_branch`, `image_tag`) for building old tags
+    - Launcher dispatch payload fixed (field name mismatch prevented branch creation)
+    - Dockerfile made resilient to different dependency versions (no hardcoded paths)
+    - Deleted obsolete `uw3-release-candidate` branch
+  - README updated: versioned binder badges, fixed CI badge filenames (.yml → .yaml)
+  - `petsc_save_checkpoint()` now delegates to `write_timestep()` (fixes #80):
+    - Gains vertex/cell compat groups, field projection, tensor repacking
+    - Single checkpoint code path for easier maintenance
+  - Cleaned up 10 merged feature/bugfix branches
+
 ## 2026-03-13
 
   - New `uw.maths.BdIntegral` for boundary and surface integrals (closes #47):

CLAUDE.md

@@ -229,14 +229,9 @@ Underworld development team with AI support from [Claude Code](https://claude.co
 - Changes go to `.pixi/envs/default/lib/python3.12/site-packages/underworld3/`
 - Verify with `uw.model.__file__`
 
-**⚠️ STALE BUILD CACHE**: If `./uw build` succeeds but Python still uses old code
-(e.g. a new parameter is "unknown"), pip's wheel cache is stale. Fix with:
-```bash
-rm -rf build/lib.* build/bdist.*
-pixi run -e default pip install --no-build-isolation --force-reinstall --no-deps .
-```
-This is the most common build issue — `./uw build` reuses cached wheels when the
-version number hasn't changed. Always verify changes are installed before debugging.
+**Note**: `./uw build` uses `--no-cache-dir` to prevent pip from reusing stale
+wheels (UW3 is always version `0.0.0`). If you still suspect stale code, clean
+the build directory: `rm -rf build/lib.* build/bdist.*` then rebuild.
 
 ### Test Quality Principles
 **New tests must be validated before making code changes to fix them!**
@@ -445,6 +440,22 @@ velocity.norm()         # Magnitude
 
 ## Coding Conventions
 
+### Prefer Glob and Grep Over find
+**Use the Glob and Grep tools instead of `find` in Bash.**
+- `Glob` handles file pattern matching (e.g., `**/*.py`, `src/**/*.pyx`)
+- `Grep` handles content search (e.g., searching for class definitions, imports)
+- Both are faster, safer, and give the user better visibility than shell `find`
+- `find` with `-exec`, `-execdir`, or `-delete` can execute arbitrary commands — avoid it
+- Only fall back to `find` via Bash if Glob/Grep genuinely cannot express the query
+
+### Desktop Notifications for Background Monitoring
+When using CronCreate for background monitoring (CI status, issues, etc.), use
+platform-appropriate notification commands. Both are in the allowed tools list:
+- **macOS**: `osascript -e 'display notification "message" with title "title" sound name "Glass"'`
+- **Linux**: `notify-send "title" "message"`
+
+Be quiet when everything is fine — only notify when something needs attention.
+
 ### Plan File Naming Policy
 **Plan files must have descriptive names that indicate their content.**
 

docs/beginner/parameters.md

@@ -251,6 +251,47 @@ mpirun -np 256 python convection.py \
     -uw_max_iterations 100
 ```
 
+## Using Parameters with Solvers: Expressions
+
+When passing parameters to solver constitutive models, wrap them in
+`uw.expression()`. This creates a named symbolic container that the JIT
+compiler can update efficiently — changing the value between time steps
+does **not** trigger recompilation of the C extension.
+
+```python
+import underworld3 as uw
+
+# Define parameters
+VISCOSITY = 1e21      # Named constant
+MODULUS = 1e10        # Named constant
+DT = 0.01            # Timestep
+
+params = uw.Params(
+    uw_viscosity = VISCOSITY,
+    uw_modulus = MODULUS,
+)
+
+# Wrap in expressions for solver use
+eta = uw.expression("eta", params.uw_viscosity)
+mu = uw.expression("mu", params.uw_modulus)
+dt_e = uw.expression("dt_e", DT)
+
+# Pass expressions to constitutive model
+stokes.constitutive_model.Parameters.shear_viscosity_0 = eta
+stokes.constitutive_model.Parameters.shear_modulus = mu
+stokes.constitutive_model.Parameters.dt_elastic = dt_e
+
+# Time-stepping: change dt without recompilation
+for step in range(100):
+    dt_e.sym = compute_new_timestep()  # Updates value, ~0ms
+    stokes.solve()                      # No JIT rebuild needed
+```
+
+Without expressions, changing a solver parameter between steps requires
+setting `_force_setup=True` on the solve call, which triggers a full JIT
+recompilation (~5–15 seconds). With expressions, parameter updates go
+through PETSc's `constants[]` array and cost essentially nothing.
+
 ## Angle Units
 
 Angles work naturally - you can define in degrees and provide radians (or vice versa):

docs/beginner/tutorials/1-Meshes.ipynb

@@ -17,7 +17,7 @@
     },
     "tags": []
    },
-   "source": "# Notebook 1: Meshes\n\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/underworldcode/uw3-binder-launcher/development?labpath=underworld3%2Fdocs%2Fbeginner%2Ftutorials%2F1-Meshes.ipynb)\n\n<div style=\"float: right; width: 40%\">\n    \n![](media/SampleSphericalMesh.png)\n\n</div>\n\n\n\nThis notebook introduces the mesh discretisation that we use in `Underworld3` and how you can build one of the pre-defined meshes. This notebook also show you how to use the `pyvista` visualisation tools for `Underworld3` objects. The mesh holds information on the mesh geometry, boundaries and coordinate systems and you can attach data to the mesh (see Notebook 2: [Variables](2-Variables.ipynb)). "
+   "source": "# Notebook 1: Meshes\n\n[![Run this notebook on Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/underworldcode/uw3-binder-launcher/development?labpath=docs%2Fbeginner%2Ftutorials%2F1-Meshes.ipynb)\n\n<div style=\"float: right; width: 40%\">\n    \n![](media/SampleSphericalMesh.png)\n\n</div>\n\n\n\nThis notebook introduces the mesh discretisation that we use in `Underworld3` and how you can build one of the pre-defined meshes. This notebook also show you how to use the `pyvista` visualisation tools for `Underworld3` objects. The mesh holds information on the mesh geometry, boundaries and coordinate systems and you can attach data to the mesh (see Notebook 2: [Variables](2-Variables.ipynb)). "
   },
   {
    "cell_type": "code",

docs/beginner/tutorials/10-Particle_Swarms.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "id": "26d2a9ca-c094-40f2-b978-333c14142874",
    "metadata": {},
-   "source": "# Notebook 8: Particle Swarms\n\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/underworldcode/uw3-binder-launcher/development?labpath=underworld3%2Fdocs%2Fbeginner%2Ftutorials%2F10-Particle_Swarms.ipynb)\n\n\n<!--\n<div style=\"float: right; width: 50%; padding-left:10px;\">\n<img src=\"media/CompositeImage.png\" width=100%>\n<caption>\n<i>\n    Flow in a pipe with inflow at the left boundary\n    after 50, 100, 150 timesteps (top to bottom) showing the\n    progression of the impulsive initial condition. For details,\n    see the notebook code.\n</i>\n</caption>\n</div>\n-->\n\nWe used a particle swarm to track the flow in Example 7. We called this a \"passive\" swarm because the points did not influence the flow in any way but were simply carried along with the fluid. \n\nParticle swarms are unstructured data objects that live within the computational domain. Their points can be moved arbitrarily through the domain and points may migrate from one process to another when the coordinates are changed. By default they carry only the particle location, but we can add scalar, vector and tensor variables to the swarm and they will be transported with the particles.\n\nParticle transport is usually through a velocity or displacement field that incrementally changes the locations. This is a common use, but particles can be used to represent any unstructured field. For example, during mesh adaptation, the nodal points from the previous mesh are equivalent to a disconnected swarm from the point of view of the new mesh. The same is true when reading data save from one mesh to the `MeshVariables` on another.\n"
+   "source": "# Notebook 8: Particle Swarms\n\n[![Run this notebook on Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/underworldcode/uw3-binder-launcher/development?labpath=docs%2Fbeginner%2Ftutorials%2F10-Particle_Swarms.ipynb)\n\n\n<!--\n<div style=\"float: right; width: 50%; padding-left:10px;\">\n<img src=\"media/CompositeImage.png\" width=100%>\n<caption>\n<i>\n    Flow in a pipe with inflow at the left boundary\n    after 50, 100, 150 timesteps (top to bottom) showing the\n    progression of the impulsive initial condition. For details,\n    see the notebook code.\n</i>\n</caption>\n</div>\n-->\n\nWe used a particle swarm to track the flow in Example 7. We called this a \"passive\" swarm because the points did not influence the flow in any way but were simply carried along with the fluid. \n\nParticle swarms are unstructured data objects that live within the computational domain. Their points can be moved arbitrarily through the domain and points may migrate from one process to another when the coordinates are changed. By default they carry only the particle location, but we can add scalar, vector and tensor variables to the swarm and they will be transported with the particles.\n\nParticle transport is usually through a velocity or displacement field that incrementally changes the locations. This is a common use, but particles can be used to represent any unstructured field. For example, during mesh adaptation, the nodal points from the previous mesh are equivalent to a disconnected swarm from the point of view of the new mesh. The same is true when reading data save from one mesh to the `MeshVariables` on another.\n"
   },
   {
    "cell_type": "code",

docs/beginner/tutorials/11-Multi-Material_SolCx.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "id": "cell-intro",
    "metadata": {},
-   "source": "# Notebook 9: Multi-Material Constitutive Models\n\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/underworldcode/uw3-binder-launcher/development?labpath=underworld3%2Fdocs%2Fbeginner%2Ftutorials%2F11-Multi-Material_SolCx.ipynb)\n\n\n**PHYSICS:** fluid_mechanics  \n**DIFFICULTY:** intermediate  \n**PURPOSE:** demonstration\n\n## Description\n\nThis notebook demonstrates the new multi-material constitutive model by recreating the classic SolCx benchmark using two different materials instead of a piecewise viscosity function.\n\n**Key Features:**\n- Multi-material constitutive model with level-set averaging\n- Index swarm variable for material tracking\n- Comparison with analytical SolCx solution\n- Simple setup suitable for quickstart examples\n\n**Physical Setup:**\n- Two materials: low viscosity ($\\eta=1$) and high viscosity ($\\eta=10^6$)\n- Material boundary at x = 0.5\n- SolCx harmonic forcing: $f_y = -\\cos(\\pi x) \\sin(2\\pi y)$\n- Free slip boundary conditions\n\n## Mathematical Foundation\n\nThe multi-material model uses level-set weighted flux averaging:\n$$\\mathbf{f}_{\\text{composite}}(\\mathbf{x}) = \\sum_{i=0}^{N-1} \\phi_i(\\mathbf{x}) \\cdot \\mathbf{f}_i(\\mathbf{x})$$\n\nwhere $\\phi_i(\\mathbf{x})$ are level-set functions from IndexSwarmVariable."
+   "source": "# Notebook 9: Multi-Material Constitutive Models\n\n[![Run this notebook on Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/underworldcode/uw3-binder-launcher/development?labpath=docs%2Fbeginner%2Ftutorials%2F11-Multi-Material_SolCx.ipynb)\n\n\n**PHYSICS:** fluid_mechanics  \n**DIFFICULTY:** intermediate  \n**PURPOSE:** demonstration\n\n## Description\n\nThis notebook demonstrates the new multi-material constitutive model by recreating the classic SolCx benchmark using two different materials instead of a piecewise viscosity function.\n\n**Key Features:**\n- Multi-material constitutive model with level-set averaging\n- Index swarm variable for material tracking\n- Comparison with analytical SolCx solution\n- Simple setup suitable for quickstart examples\n\n**Physical Setup:**\n- Two materials: low viscosity ($\\eta=1$) and high viscosity ($\\eta=10^6$)\n- Material boundary at x = 0.5\n- SolCx harmonic forcing: $f_y = -\\cos(\\pi x) \\sin(2\\pi y)$\n- Free slip boundary conditions\n\n## Mathematical Foundation\n\nThe multi-material model uses level-set weighted flux averaging:\n$$\\mathbf{f}_{\\text{composite}}(\\mathbf{x}) = \\sum_{i=0}^{N-1} \\phi_i(\\mathbf{x}) \\cdot \\mathbf{f}_i(\\mathbf{x})$$\n\nwhere $\\phi_i(\\mathbf{x})$ are level-set functions from IndexSwarmVariable."
   },
   {
    "cell_type": "markdown",

docs/beginner/tutorials/12-Units_System.ipynb

@@ -3,7 +3,7 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": "# Notebook 12: Working with Physical Units\n\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/underworldcode/uw3-binder-launcher/development?labpath=underworld3%2Fdocs%2Fbeginner%2Ftutorials%2F12-Units_System.ipynb)\n\n\nUnderworld3 has built-in support for physical units throughout the modeling workflow. This makes your models easier to understand and helps catch dimensional errors early.\n\nIn this notebook you'll learn:\n- Creating physical quantities (temperatures, velocities, viscosities)\n- Converting between units\n- Working with unit-aware arrays and coordinates\n- Automatic unit tracking through derivatives"
+   "source": "# Notebook 12: Working with Physical Units\n\n[![Run this notebook on Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/underworldcode/uw3-binder-launcher/development?labpath=docs%2Fbeginner%2Ftutorials%2F12-Units_System.ipynb)\n\n\nUnderworld3 has built-in support for physical units throughout the modeling workflow. This makes your models easier to understand and helps catch dimensional errors early.\n\nIn this notebook you'll learn:\n- Creating physical quantities (temperatures, velocities, viscosities)\n- Converting between units\n- Working with unit-aware arrays and coordinates\n- Automatic unit tracking through derivatives"
   },
   {
    "cell_type": "code",

docs/beginner/tutorials/13-Scaling-problems-with-physical-units.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "id": "cell-0",
    "metadata": {},
-   "source": "# Notebook 13: Non-Dimensional Scaling\n\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/underworldcode/uw3-binder-launcher/development?labpath=underworld3%2Fdocs%2Fbeginner%2Ftutorials%2F13-Scaling-problems-with-physical-units.ipynb)\n\n\nWhen working with physical problems, the range of scales can cause numerical difficulties. For example, mantle convection involves:\n- Velocities of ~10\u207b\u2079 m/s (tiny)\n- Viscosities of ~10\u00b2\u00b9 Pa\u00b7s (huge)\n- Pressures of ~10\u2079 Pa (large)\n\nNon-dimensional (ND) scaling transforms the problem so all quantities are order-one, improving numerical conditioning and stability.\n\nIn this notebook you'll learn:\n- Setting reference quantities for automatic scaling\n- Solving Poisson and Stokes equations with ND scaling\n- Understanding what happens under the hood\n- Validating that ND and dimensional solutions match"
+   "source": "# Notebook 13: Non-Dimensional Scaling\n\n[![Run this notebook on Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/underworldcode/uw3-binder-launcher/development?labpath=docs%2Fbeginner%2Ftutorials%2F13-Scaling-problems-with-physical-units.ipynb)\n\n\nWhen working with physical problems, the range of scales can cause numerical difficulties. For example, mantle convection involves:\n- Velocities of ~10\u207b\u2079 m/s (tiny)\n- Viscosities of ~10\u00b2\u00b9 Pa\u00b7s (huge)\n- Pressures of ~10\u2079 Pa (large)\n\nNon-dimensional (ND) scaling transforms the problem so all quantities are order-one, improving numerical conditioning and stability.\n\nIn this notebook you'll learn:\n- Setting reference quantities for automatic scaling\n- Solving Poisson and Stokes equations with ND scaling\n- Understanding what happens under the hood\n- Validating that ND and dimensional solutions match"
   },
   {
    "cell_type": "code",