Release polish: WP0-WP8, catalogue, ASE, release system, branding

.claude/commands/regen.md

@@ -1,5 +1,5 @@
 ---
-description: Regenerate the five generated files (schemas, options.md, Python types and API docs) and check them
+description: Regenerate the six generated files (schemas, options.md, materials-catalogue.md, Python types and API docs) and check them
 allowed-tools: Bash(dotnet build:*), Bash(dotnet src/UltrafastEngine.Cli/bin/*), Bash(python3 python/tools/*), Bash(git diff:*), Bash(mypy:*)
 ---
 Regenerate everything derived from the schema declarations, the Python docstrings and the test attributes:
@@ -10,12 +10,13 @@ U="dotnet src/UltrafastEngine.Cli/bin/Release/net10.0/ultrafast.dll"
 $U schema system -o schemas/ufs.schema.json
 $U schema run -o schemas/run.schema.json
 $U reference -o docs/reference/options.md
+$U reference materials -o docs/reference/materials-catalogue.md
 python3 python/tools/gen_types.py
 python3 python/tools/gen_api_docs.py
 dotnet build tests/UltrafastEngine.Tests -c Release -f net10.0 2>&1 | grep -E "rror\(s\)"
 dotnet tests/UltrafastEngine.Tests/bin/Release/net10.0/UltrafastEngine.Tests.dll --matrix docs/reference/validation-matrix.md
 (cd python && mypy --follow-imports=silent src/ultrafast/build.py src/ultrafast/types.py)
 ```
 
-Then `git diff --stat` on those five files and summarise what changed in one or two lines (new keys, renamed
+Then `git diff --stat` on those generated files and summarise what changed in one or two lines (new keys, renamed
 types). Do not read the generated files in full; grep them for the keys you changed if you need to confirm.

.claude/commands/verify.md

@@ -5,7 +5,7 @@ allowed-tools: Bash, Read, Grep
 Run the complete verification. Delegate the long runs to the `test-runner` subagent so only the results come back.
 
 1. `dotnet build UltrafastEngine.sln -c Release` (0 errors; the only expected warning is the ZOS-API stub warning).
-2. Generated files current: run `/regen` steps and check `git diff --stat` shows no change in the five files.
+2. Generated files current: run `/regen` steps and check `git diff --stat` shows no change in the six generated files.
 3. C# tests: `dotnet tests/UltrafastEngine.Tests/bin/Release/net10.0/UltrafastEngine.Tests.dll --slow`; on machines with
    Mono also `mono tests/UltrafastEngine.Tests/bin/Release/net48/UltrafastEngine.Tests.exe --slow` (unset ULTRAFAST_STRICT_OPTIONS).
 4. Python: `python3 python/tools/build_engine.py`, then in `python/`:

.claude/hooks/after_edit.py

@@ -9,7 +9,8 @@
 import sys
 
 RULES = [
-    ("src/UltrafastEngine.Core/Schema/BuiltIn*.cs", "Schema declaration changed: run /regen (5 generated files) before the tests; document the key in docs/reference/."),
+    ("src/UltrafastEngine.Core/Data/materials/*", "Catalogue file changed: run /regen (docs/reference/materials-catalogue.md) and, if a number moved, regenerate the pinned snapshot on purpose (ULTRAFAST_WRITE_SNAPSHOT=1, see CatalogueSnapshotTests)."),
+    ("src/UltrafastEngine.Core/Schema/BuiltIn*.cs", "Schema declaration changed: run /regen (6 generated files) before the tests; document the key in docs/reference/."),
     ("src/UltrafastEngine.Core/Schema/Migrations.cs", "Migration changed: keep the old key working and add a test in SchemaTests."),
     ("src/UltrafastEngine.Core/Physics/*", "Propagation physics changed: run the analytic tests (PropagationTests, NerTests) and, if scalar results may change, the pyNLO cross-checks (/physics-change)."),
     ("src/UltrafastEngine.Core/Transverse/*", "Spatial propagation changed: keep it consistent with Physics/Nonlinear.cs; run SpatialTests and NerTests."),

.claude/hooks/protect_paths.py

@@ -18,6 +18,7 @@
     ("schemas/*.schema.json", "Generated file: change src/UltrafastEngine.Core/Schema/BuiltIn*.cs and run /regen."),
     ("docs/reference/options.md", "Generated file: change src/UltrafastEngine.Core/Schema/BuiltIn*.cs and run /regen."),
     ("python/src/ultrafast/types.py", "Generated file: change the schema declarations and run /regen (python3 python/tools/gen_types.py)."),
+    ("docs/reference/materials-catalogue.md", "Generated file: change the catalogue files in src/UltrafastEngine.Core/Data/materials and run /regen."),
     ("docs/reference/python-api.md", "Generated file: change the Python docstrings and run python3 python/tools/gen_api_docs.py."),
     ("docs/reference/validation-matrix.md", "Generated file: change the [Test] / [TestArea] attributes and run /regen."),
     ("*/bin/*", "Build output: change the source instead."),

.github/workflows/ci.yml

@@ -21,13 +21,14 @@ jobs:
   build-and-test:
     name: Build (net10.0, net48) and C# tests
     runs-on: ubuntu-24.04
+    timeout-minutes: 90
     steps:
       - uses: actions/checkout@v7
       - uses: actions/setup-dotnet@v6
         with:
           global-json-file: global.json
       - name: Install Mono (net48 reference assemblies and runtime)
-        run: sudo apt-get update && sudo apt-get install -y mono-complete
+        run: sudo apt-get -o Acquire::Retries=5 -o Acquire::http::Timeout=30 update && sudo apt-get -o Acquire::Retries=5 -o Acquire::http::Timeout=30 install -y mono-complete
       - name: Build everything
         run: dotnet build UltrafastEngine.sln -c Release
       - name: C# tests, .NET 10, including slow
@@ -38,6 +39,7 @@ jobs:
   tests-macos-windows:
     name: C# and Python tests on ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 90
     strategy:
       fail-fast: false
       matrix:
@@ -66,6 +68,7 @@ jobs:
   compile-platforms:
     name: Compile CLI for ${{ matrix.rid }}
     runs-on: ubuntu-24.04
+    timeout-minutes: 90
     strategy:
       fail-fast: false
       matrix:
@@ -81,6 +84,7 @@ jobs:
   python:
     name: Python tests (hosted engine, pyNLO)
     runs-on: ubuntu-24.04
+    timeout-minutes: 90
     steps:
       - uses: actions/checkout@v7
       - uses: actions/setup-dotnet@v6
@@ -102,6 +106,7 @@ jobs:
   components:
     name: Component test scripts (numbers only)
     runs-on: ubuntu-24.04
+    timeout-minutes: 90
     steps:
       - uses: actions/checkout@v7
       - uses: actions/setup-dotnet@v6
@@ -125,6 +130,7 @@ jobs:
   papers:
     name: Paper replications (fast tier)
     runs-on: ubuntu-24.04
+    timeout-minutes: 90
     steps:
       - uses: actions/checkout@v7
       - uses: actions/setup-dotnet@v6
@@ -151,6 +157,7 @@ jobs:
   docs-and-examples:
     name: Docs and example check
     runs-on: ubuntu-24.04
+    timeout-minutes: 90
     steps:
       - uses: actions/checkout@v7
       - uses: actions/setup-dotnet@v6

.github/workflows/docs.yml

@@ -22,6 +22,7 @@ jobs:
   build:
     name: Build the site (strict)
     runs-on: ubuntu-24.04
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@v7
       - uses: actions/setup-python@v7
@@ -43,6 +44,7 @@ jobs:
     if: github.event_name != 'pull_request'
     needs: build
     runs-on: ubuntu-24.04
+    timeout-minutes: 30
     permissions:
       pages: write
       id-token: write

.github/workflows/release.yml

@@ -0,0 +1,141 @@
+# Release assets on a version tag (v*): one .tar.gz per component and platform, manifest.json and install.py, attached to a GitHub release.
+# docs/releasing.md. NO TAG IS CREATED BY ANYONE BUT THE OWNER. The workflow can also be started by hand (workflow_dispatch) to build and
+# smoke-test the assets without publishing (the files stay as workflow artifacts).
+#
+# Jobs: `managed` builds everything that is pure .NET or plain files (the CLI for every platform is cross-published here, so macOS needs
+# no macOS runner), `native` builds the NativeAOT components (C API, native wheel) on each OS they must be built on, `publish` merges the
+# manifests, checks that no archive holds a ZOS-API file, installs a selection into a temporary folder, removes it again and uploads.
+# macOS NativeAOT (cpp, python-native for osx-*) is built on the owner's Mac (./build.sh --components cpp python-native ...) and uploaded
+# with `gh release upload`, because the macOS runner is not available to this repository (see ci.yml).
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+env:
+  DOTNET_CLI_TELEMETRY_OPTOUT: "1"
+  DOTNET_NOLOGO: "1"
+
+jobs:
+  managed:
+    name: Managed components and source folders
+    runs-on: ubuntu-24.04
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-dotnet@v6
+        with:
+          global-json-file: global.json
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Build the assets
+        run: >
+          python build/package.py --out dist
+          --components cli python csharp plugins schemas docs examples media tests component-tests papers source
+          --platform win-x64 linux-x64 linux-arm64 osx-arm64 osx-x64
+      - uses: actions/upload-artifact@v7
+        with:
+          name: assets-managed
+          path: dist/release-*/*
+          if-no-files-found: error
+
+  native:
+    name: NativeAOT components on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 120
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-24.04, rid: linux-x64 }
+          - { os: ubuntu-24.04-arm, rid: linux-arm64 }
+          - { os: windows-latest, rid: win-x64 }
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-dotnet@v6
+        with:
+          global-json-file: global.json
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Build the C API and the native wheel
+        run: python build/package.py --out dist --components cpp python-native --platform ${{ matrix.rid }}
+      - name: Smoke test, C example and ultrafast devices
+        shell: bash
+        run: |
+          set -e
+          mkdir -p smoke && cd smoke
+          python ../install.py --base-url ../dist/release-* --include cpp --dest cpp-install --no-pip
+          cmake -S cpp-install/cpp/example -B build -DULTRAFAST_DIR="$PWD/cpp-install/cpp"
+          cmake --build build --config Release
+      - uses: actions/upload-artifact@v7
+        with:
+          name: assets-native-${{ matrix.rid }}
+          path: dist/release-*/*
+          if-no-files-found: error
+
+  publish:
+    name: Check, smoke-test the installer, publish
+    needs: [managed, native]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 120
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-dotnet@v6
+        with:
+          global-json-file: global.json
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - uses: actions/download-artifact@v8
+        with:
+          path: parts
+      - name: Merge the job outputs into one release folder
+        run: |
+          mkdir -p release
+          # every job wrote manifest.json beside its assets; the assets have unique names, install.py is identical
+          for d in parts/*/; do cp -n "$d"*.tar.gz release/ 2>/dev/null || true; done
+          cp parts/assets-managed/install.py release/install.py
+          python build/release_components.py merge release/manifest.json parts/*/manifest.json
+      - name: No ZOS-API file in any archive or wheel (Ansys property)
+        run: python build/release_components.py check-zosapi release
+      - name: Planted file must be caught (the gate itself is tested)
+        run: python -m pytest -q python/tests/test_release.py -k "zosapi"
+        env: { PYTHONDONTWRITEBYTECODE: "1" }
+      - name: Smoke test, a selection into a temporary folder, then uninstall leaves it empty
+        run: |
+          set -e
+          python release/install.py --base-url release --platform linux-x64 --include cli schemas examples.Branched --dest "$RUNNER_TEMP/uf" --no-pip
+          "$RUNNER_TEMP/uf/bin/ultrafast" --version
+          "$RUNNER_TEMP/uf/bin/ultrafast" devices
+          ULTRAFAST_STRICT_OPTIONS=1 "$RUNNER_TEMP/uf/bin/ultrafast" run docs/examples/GettingStarted/spm-plate/plate.ufs docs/examples/GettingStarted/spm-plate/run.json -o "$RUNNER_TEMP/r"
+          python release/install.py --uninstall --dest "$RUNNER_TEMP/uf" --no-pip
+          test -z "$(ls -A "$RUNNER_TEMP/uf")"
+      - name: Smoke test, the wheel in a fresh environment lists devices and runs the quickstart
+        run: |
+          set -e
+          python release/install.py --base-url release --platform linux-x64 --include python --dest "$RUNNER_TEMP/py" --no-pip
+          python -m venv "$RUNNER_TEMP/venv"
+          "$RUNNER_TEMP/venv/bin/pip" install --find-links "$RUNNER_TEMP/py/python" "ultrafast-engine[hosted]"
+          "$RUNNER_TEMP/venv/bin/python" -c "import ultrafast; print(ultrafast.version())"
+          "$RUNNER_TEMP/venv/bin/python" -c "import ultrafast; print(ultrafast.devices())"
+          "$RUNNER_TEMP/venv/bin/python" docs/examples/GettingStarted/quickstart/quickstart.py
+      - name: Attach the assets (tag builds only)
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: softprops/action-gh-release@v3
+        with:
+          files: |
+            release/*.tar.gz
+            release/manifest.json
+            release/install.py
+          draft: true
+      - uses: actions/upload-artifact@v7
+        if: github.event_name == 'workflow_dispatch'
+        with:
+          name: release-folder
+          path: release/*