peclet-geom 1.0.0__tar.gz

peclet_geom-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+# The gate that proves the split did what it claims: peclet-geom must build and pass WITHOUT an MPI
+# toolchain and WITHOUT Kokkos on the runner. If either ever creeps back into the dependency
+# closure, this job is where it shows up — a plain ubuntu-latest image has neither.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  no-mpi-no-kokkos:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      # Stated, not assumed: fail loudly if the image turns out to carry MPI, because then this job
+      # would prove nothing about the property it exists to protect.
+      - name: The runner has no MPI and no Kokkos
+        run: |
+          if command -v mpicxx >/dev/null || dpkg -l | grep -q libopenmpi-dev; then
+            echo "::error::this runner HAS an MPI toolchain — the no-MPI gate is vacuous here"; exit 1
+          fi
+          echo "no mpicxx, no libopenmpi-dev — the gate is meaningful"
+
+      - run: pip install numpy pytest nanobind scikit-build-core cmake
+      - name: Build and install (vendored core headers, no siblings present)
+        run: PECLET_VENDOR_DEPS=ON pip install -v .
+
+      - name: Import and exercise SceneBuilder
+        run: |
+          python - <<'PY'
+          from peclet import geom
+          s = geom.SceneBuilder()
+          for n in ("add_leaf", "add_union", "add_difference", "add_intersection",
+                    "principal_frame", "body_properties", "bake", "encode",
+                    "eval", "eval_root", "eval_root_grad"):
+              assert hasattr(s, n), n
+          print("peclet.geom OK:", geom.build_toolchain)
+          PY
+
+      # The byte gate. Its reference values are byte-identical to what the RELEASED peclet-core
+      # 1.0.2 produced for peclet.core.geom before the split, so a changed digit means the move was
+      # not a move.
+      #
+      # It is TOOLCHAIN-SPECIFIC and exits 77 ("skipped") against a reference recorded elsewhere —
+      # floating-point results are not comparable across compilers. The reference is recorded on the
+      # author's toolchain, so on a GitHub runner this normally SKIPS, and 77 must not read as a
+      # pass or as a failure. Core expresses the same thing through ctest's SKIP_RETURN_CODE 77;
+      # here it has to be spelled out, because a bare step treats 77 as failure.
+      - name: State-hash byte gate (skips across toolchains, by design)
+        run: |
+          set +e
+          OMP_NUM_THREADS=1 python python/state_hash.py --check python/state_hash_reference.json
+          rc=$?
+          set -e
+          case $rc in
+            0)  echo "::notice::byte gate RAN and matched — same toolchain as the reference" ;;
+            77) echo "::notice::byte gate SKIPPED: this runner's toolchain differs from the reference's."
+                echo "::notice::That is expected here. The gate is enforced locally before a release." ;;
+            *)  echo "::error::byte gate FAILED (exit $rc) — a state hash changed"; exit $rc ;;
+          esac

peclet_geom-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,70 @@
+name: Release
+
+# Publish peclet-geom to PyPI on a version tag via Trusted Publishing (OIDC).
+#
+# WHEELS, unlike its former housemate. peclet.geom links no MPI and no Kokkos — its closure is six
+# peclet/core/geom/*.hpp headers plus common/{types,portable}.hpp — so a portable binary wheel IS
+# possible, which is the entire point of the split (suite/docs/CORE_BOUNDARY.md). While this code
+# lived in peclet-core it inherited that package's MPI build requirement and could only ship an
+# sdist, which is what made it unobtainable on Colab.
+#
+# The core headers are vendored at PECLET_CORE_TAG (cmake/PecletDeps.cmake) by PECLET_VENDOR_DEPS=ON,
+# exactly as peclet-amr does: the suite siblings are absent on a runner.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  wheels:
+    name: wheels · ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, ubuntu-24.04-arm, windows-latest, macos-14]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pypa/cibuildwheel@v3.2.0
+        env:
+          CIBW_BUILD: "cp310-* cp311-* cp312-* cp313-* cp314-*"
+          CIBW_SKIP: "*-musllinux_*"
+          CIBW_ARCHS_MACOS: arm64
+          # No suite checkout on a runner: fetch the core headers at the pinned tag.
+          CIBW_ENVIRONMENT: "PECLET_VENDOR_DEPS=ON"
+          CIBW_BEFORE_ALL_LINUX: "cmake --version || true"
+          # A wheel that imports is the only wheel worth publishing.
+          CIBW_TEST_COMMAND: 'python -c "from peclet import geom; s = geom.SceneBuilder(); print(geom.build_toolchain)"'
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build --sdist
+      - uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write   # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

peclet_geom-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+build/
+build_*/
+*.so
+__pycache__/
+*.egg-info/
+dist/

peclet_geom-1.0.0/CITATION.cff

@@ -0,0 +1,31 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata below."
+title: "peclet-geom: analytic-SDF scene authoring for the peclet suite"
+abstract: >-
+  Header-only C++20 + MPI infrastructure shared across the peclet suite: ORB block domain decomposition,
+  asynchronous ghost-layer exchange (NBX + persistent neighborhood-collective engines, GPU-resident
+  variant), Lagrangian particle migration and ghosts, SDF geometry with VTI I/O, an AMR octree, and
+  dynamic (weighted-ORB) load balancing. Optional Kokkos GPU backends and Python bindings.
+type: software
+authors:
+  - family-names: Peters
+    given-names: "E.A.J.F."
+    alias: Frank
+    orcid: "https://orcid.org/0000-0001-6099-3583"
+    email: e.a.j.f.peters@tue.nl
+    affiliation: "Eindhoven University of Technology"
+version: 1.0.0
+date-released: 2026-09-21
+license: MIT
+# No Zenodo record yet — peclet-geom is new at 1.0.0 (split from peclet-core,
+# suite/docs/CORE_BOUNDARY.md). Add the concept DOI here once the record exists; do NOT
+# inherit peclet-core's, which belongs to a different artifact.
+repository-code: "https://github.com/computational-chemical-engineering/peclet-geom"
+keywords:
+  - signed distance field
+  - constructive solid geometry
+  - computational geometry
+  - rigid body dynamics
+  - inertia tensor
+  - scene authoring
+  - transport phenomena

peclet_geom-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frank Peters
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

peclet_geom-1.0.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: peclet-geom
+Version: 1.0.0
+Summary: peclet.geom — analytic-SDF scene authoring: CSG trees, batch evaluation, lattice baking, rigid-body mass properties
+Keywords: signed distance field,SDF,CSG,constructive solid geometry,computational geometry,rigid body,inertia tensor,mesh-free,transport phenomena
+Author-Email: "E.A.J.F. Peters" <e.a.j.f.peters@tue.nl>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Project-URL: Homepage, https://github.com/computational-chemical-engineering/peclet
+Project-URL: Documentation, https://computational-chemical-engineering.github.io/peclet/
+Project-URL: Source, https://github.com/computational-chemical-engineering/peclet-geom
+Project-URL: Examples gallery, https://computational-chemical-engineering.github.io/peclet-examples/
+Project-URL: Issues, https://github.com/computational-chemical-engineering/peclet-geom/issues
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.20
+Description-Content-Type: text/markdown
+
+# peclet-geom
+
+`peclet.geom` — analytic-SDF scene authoring for the [peclet](https://github.com/computational-chemical-engineering/peclet)
+suite: CSG trees over signed-distance primitives, batch evaluation, lattice baking, and rigid-body
+mass properties (mass, centre of mass, the full inertia tensor, and the principal frame as three
+moments plus a quaternion).
+
+```bash
+pip install peclet-geom        # or just `pip install peclet` — it is part of the family
+```
+
+```python
+from peclet import geom
+
+s = geom.SceneBuilder()
+head   = s.add_leaf("torus", ...)
+handle = s.add_leaf("capsule", ...)
+body   = s.add_union([head, handle])
+m, com, inertia, quat = s.body_properties(body, lo, hi)
+racket = s.principal_frame(body, lo, hi)     # re-expressed exactly, no resampling
+```
+
+## Why this is its own package
+
+It is **host-only**: no MPI, no Kokkos, no GPU — its closure is six `peclet/core/geom/*.hpp`
+headers plus two common ones, and it depends on nothing but numpy at runtime. That is what lets it
+ship as wheels and be part of a plain `pip install peclet`.
+
+Until peclet 1.2.0 this code was `peclet.core.geom` inside the `peclet-core` distribution, whose
+build requires an MPI toolchain because it also builds the halo bindings. A pure-geometry API was
+therefore unobtainable without MPI — which broke eleven gallery pages and `peclet.dem`'s
+`scene_particle.build()`. The boundary rule and the migration ladder are in
+[suite/docs/CORE_BOUNDARY.md](https://github.com/computational-chemical-engineering/peclet/blob/main/docs/CORE_BOUNDARY.md).
+
+`peclet.core.geom` still works and is the *same object* — `peclet.core.geom.SceneBuilder is
+peclet.geom.SceneBuilder` — it gains a `DeprecationWarning` in 1.3.0 and is removed in 2.0.0.
+
+## Build from source
+
+```bash
+cmake -S python -B python/build -DCMAKE_BUILD_TYPE=Release
+cmake --build python/build -j
+PYTHONPATH=python/build python -c "from peclet import geom; print(geom.SceneBuilder())"
+```
+
+The core headers come from a sibling `../core` checkout if present, else are fetched at
+`PECLET_CORE_TAG` (`cmake/PecletDeps.cmake`). Point at a core worktree with
+`-DPECLET_SIBLING_PECLET_CORE=/path/to/core-worktree`.
+
+## Faithfulness gate
+
+`python/state_hash.py` hashes every public entry path. The recorded reference is byte-identical to
+what `peclet-core` 1.0.2 produced before the split — a changed digit is a bug in the move:
+
+```bash
+OMP_NUM_THREADS=1 PYTHONPATH=python/build python python/state_hash.py --check python/state_hash_reference.json
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

peclet_geom-1.0.0/README.md

@@ -0,0 +1,61 @@
+# peclet-geom
+
+`peclet.geom` — analytic-SDF scene authoring for the [peclet](https://github.com/computational-chemical-engineering/peclet)
+suite: CSG trees over signed-distance primitives, batch evaluation, lattice baking, and rigid-body
+mass properties (mass, centre of mass, the full inertia tensor, and the principal frame as three
+moments plus a quaternion).
+
+```bash
+pip install peclet-geom        # or just `pip install peclet` — it is part of the family
+```
+
+```python
+from peclet import geom
+
+s = geom.SceneBuilder()
+head   = s.add_leaf("torus", ...)
+handle = s.add_leaf("capsule", ...)
+body   = s.add_union([head, handle])
+m, com, inertia, quat = s.body_properties(body, lo, hi)
+racket = s.principal_frame(body, lo, hi)     # re-expressed exactly, no resampling
+```
+
+## Why this is its own package
+
+It is **host-only**: no MPI, no Kokkos, no GPU — its closure is six `peclet/core/geom/*.hpp`
+headers plus two common ones, and it depends on nothing but numpy at runtime. That is what lets it
+ship as wheels and be part of a plain `pip install peclet`.
+
+Until peclet 1.2.0 this code was `peclet.core.geom` inside the `peclet-core` distribution, whose
+build requires an MPI toolchain because it also builds the halo bindings. A pure-geometry API was
+therefore unobtainable without MPI — which broke eleven gallery pages and `peclet.dem`'s
+`scene_particle.build()`. The boundary rule and the migration ladder are in
+[suite/docs/CORE_BOUNDARY.md](https://github.com/computational-chemical-engineering/peclet/blob/main/docs/CORE_BOUNDARY.md).
+
+`peclet.core.geom` still works and is the *same object* — `peclet.core.geom.SceneBuilder is
+peclet.geom.SceneBuilder` — it gains a `DeprecationWarning` in 1.3.0 and is removed in 2.0.0.
+
+## Build from source
+
+```bash
+cmake -S python -B python/build -DCMAKE_BUILD_TYPE=Release
+cmake --build python/build -j
+PYTHONPATH=python/build python -c "from peclet import geom; print(geom.SceneBuilder())"
+```
+
+The core headers come from a sibling `../core` checkout if present, else are fetched at
+`PECLET_CORE_TAG` (`cmake/PecletDeps.cmake`). Point at a core worktree with
+`-DPECLET_SIBLING_PECLET_CORE=/path/to/core-worktree`.
+
+## Faithfulness gate
+
+`python/state_hash.py` hashes every public entry path. The recorded reference is byte-identical to
+what `peclet-core` 1.0.2 produced before the split — a changed digit is a bug in the move:
+
+```bash
+OMP_NUM_THREADS=1 PYTHONPATH=python/build python python/state_hash.py --check python/state_hash_reference.json
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

peclet_geom-1.0.0/cmake/PecletDeps.cmake

@@ -0,0 +1,50 @@
+# PecletDeps.cmake — dependency provisioning for peclet-geom.
+#
+# peclet-geom has exactly ONE dependency: the header-only peclet-core geom headers. No Kokkos, no
+# MPI, no morton (suite/docs/CORE_BOUNDARY.md §1.2) — which is what lets this package ship wheels
+# while peclet-halo stays an sdist.
+#
+# Two ways to build, selected automatically:
+#   * DEV / suite build — the sibling ../../core/include is used directly.
+#   * SELF-CONTAINED sdist (pip install peclet-geom) — the siblings are ABSENT, so the core headers
+#     are FetchContent-fetched at PECLET_CORE_TAG below.
+# Force the fetch with -DPECLET_VENDOR_DEPS=ON. Keep PECLET_CORE_TAG in lockstep with the other
+# packages' PecletDeps.cmake; the release pre-flight (tools/release/check_release_state.sh) checks it.
+#
+# The PECLET_SIBLING_PECLET_CORE override below is how concurrent work stays out of each other's
+# way: point a build at a core WORKTREE without touching the shared ../../core checkout.
+include_guard(GLOBAL)
+include(FetchContent)
+
+set(PECLET_CORE_TAG "v1.0.2" CACHE STRING "Vendored core git tag (headers)")
+option(PECLET_VENDOR_DEPS "Force FetchContent-fetch of the core headers (self-contained sdist)" OFF)
+
+function(peclet_sibling_include repo tag sibling_reldir outvar)
+  # Dev override for a sibling checked out somewhere else than `../<repo>` -- in particular a git
+  # WORKTREE, which is how the suite runs concurrent agents (`git worktree add ../core-w0`). Pass
+  # the repo ROOT (`/include` is appended):
+  #   -DPECLET_SIBLING_PECLET_CORE=/path/to/suite/core-w0
+  # Unset (the default) it resolves exactly as before, so every existing build is unchanged.
+  string(TOUPPER "${repo}" _ovr)
+  string(REPLACE "-" "_" _ovr "${_ovr}")
+  if(PECLET_SIBLING_${_ovr})
+    set(${outvar} "${PECLET_SIBLING_${_ovr}}/include" PARENT_SCOPE)
+    message(STATUS "[peclet] ${repo} headers from PECLET_SIBLING_${_ovr} -> ${PECLET_SIBLING_${_ovr}}/include")
+    return()
+  endif()
+  set(_local "${CMAKE_CURRENT_SOURCE_DIR}/${sibling_reldir}/include")
+  if(EXISTS "${_local}" AND NOT PECLET_VENDOR_DEPS)
+    set(${outvar} "${_local}" PARENT_SCOPE)
+    return()
+  endif()
+  string(TOLOWER "peclet_sib_${repo}" _name)
+  FetchContent_Declare(${_name}
+    GIT_REPOSITORY "https://github.com/computational-chemical-engineering/${repo}.git"
+    GIT_TAG ${tag} GIT_SHALLOW TRUE)
+  FetchContent_GetProperties(${_name})
+  if(NOT ${_name}_POPULATED)
+    FetchContent_Populate(${_name})
+  endif()
+  set(${outvar} "${${_name}_SOURCE_DIR}/include" PARENT_SCOPE)
+  message(STATUS "[peclet] vendored ${repo} headers -> ${${_name}_SOURCE_DIR}/include")
+endfunction()

peclet_geom-1.0.0/cmake/SuiteNanobind.cmake

@@ -0,0 +1,51 @@
+# SuiteNanobind.cmake — shared nanobind provisioning for the peclet suite.
+#
+# Policy: the suite's Python bindings use nanobind (replacing pybind11), built through
+# scikit-build-core for wheels and through plain CMake for the developer `cmake -S . -B build`
+# workflow. nanobind ships a CMake config inside its Python package; we locate it the same way
+# scikit-build-core does — by asking the active interpreter — so a single mechanism covers both
+# `pip install .` and a venv-driven dev build.
+#
+# Usage in a consumer CMakeLists:
+#     include(${SUITE_CMAKE_DIR}/SuiteNanobind.cmake)   # or list-append to CMAKE_MODULE_PATH
+#     suite_require_nanobind()
+#     nanobind_add_module(mymod NB_STATIC src/bindings.cpp)
+#     target_link_libraries(mymod PRIVATE Kokkos::kokkos)
+#
+# The Kokkos View <-> nanobind ndarray zero-copy bridge consumed by every binding lives in
+# core/include/peclet/core/python/ndarray_interop.hpp (peclet-core).
+
+include_guard(GLOBAL)
+
+# A macro (not a function): find_package(Python) sets plain variables like Python_INCLUDE_DIRS that
+# nanobind reads at module-creation time. A function would scope those locally, so nanobind-static
+# would later be compiled at directory scope without the Python headers. A macro runs in the
+# caller's scope, so the variables are visible where nanobind_add_module() is invoked.
+macro(suite_require_nanobind)
+  if(NOT COMMAND nanobind_add_module)
+    # Need the Development.Module component so nanobind can build extension modules. Honor an already
+    # chosen interpreter (scikit-build-core / an activated venv set Python_EXECUTABLE).
+    find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development.Module)
+
+    # Ask the interpreter where nanobind's CMake config lives (works for both pip-installed and
+    # venv-resident nanobind, and matches how scikit-build-core resolves it).
+    if(NOT nanobind_DIR)
+      execute_process(
+        COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+        OUTPUT_VARIABLE _suite_nb_cmake_dir
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+        RESULT_VARIABLE _suite_nb_result)
+      if(NOT _suite_nb_result EQUAL 0 OR NOT EXISTS "${_suite_nb_cmake_dir}")
+        message(FATAL_ERROR
+          "[suite] nanobind not found via '${Python_EXECUTABLE} -m nanobind --cmake_dir'. "
+          "Install it into the active environment:\n"
+          "    pip install nanobind\n"
+          "(scikit-build-core adds it automatically when building a wheel via pyproject.toml).")
+      endif()
+      set(nanobind_DIR "${_suite_nb_cmake_dir}")
+    endif()
+
+    find_package(nanobind CONFIG REQUIRED)
+    message(STATUS "[suite] Using nanobind from ${nanobind_DIR}")
+  endif()
+endmacro()

peclet_geom-1.0.0/pyproject.toml

@@ -0,0 +1,67 @@
+# peclet-geom — `peclet.geom`, analytic-SDF scene authoring.
+#
+# The family's first HOST-ONLY wheel. It exists because this code was unobtainable without an MPI
+# toolchain while it shared the `peclet-core` distribution with the halo bindings: the sdist builds
+# core/python/CMakeLists.txt, whose `find_package(MPI REQUIRED)` covered both targets even though
+# geom links no MPI. That cost eleven gallery pages and peclet.dem's scene_particle.build().
+# See suite/docs/CORE_BOUNDARY.md for the boundary rule and the migration ladder.
+#
+# Depends on nothing but numpy at runtime, and on the header-only peclet-core geom headers at build
+# time (cmake/PecletDeps.cmake, PECLET_CORE_TAG). No Kokkos, no MPI, no morton.
+
+[build-system]
+requires = ["scikit-build-core>=0.8", "nanobind>=2.0"]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "peclet-geom"
+version = "1.0.0"
+description = "peclet.geom — analytic-SDF scene authoring: CSG trees, batch evaluation, lattice baking, rigid-body mass properties"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "E.A.J.F. Peters", email = "e.a.j.f.peters@tue.nl" }]
+keywords = ["signed distance field", "SDF", "CSG", "constructive solid geometry", "computational geometry", "rigid body", "inertia tensor", "mesh-free", "transport phenomena"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Education",
+  "Programming Language :: C++",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Scientific/Engineering :: Mathematics",
+  "Topic :: Scientific/Engineering :: Physics",
+]
+
+dependencies = ["numpy>=1.20"]
+
+[project.urls]
+Homepage = "https://github.com/computational-chemical-engineering/peclet"
+Documentation = "https://computational-chemical-engineering.github.io/peclet/"
+Source = "https://github.com/computational-chemical-engineering/peclet-geom"
+"Examples gallery" = "https://computational-chemical-engineering.github.io/peclet-examples/"
+Issues = "https://github.com/computational-chemical-engineering/peclet-geom/issues"
+
+[tool.scikit-build]
+minimum-version = "0.8"
+cmake.version = ">=3.24"
+# The module lives in python/ (a standalone project); its install rules place peclet/geom/.
+cmake.source-dir = "python"
+wheel.install-dir = "."
+# The wheel's contents come entirely from the CMake install() rules; no auto-discovery.
+wheel.packages = []
+# Self-contained sdist: cmake/ carries the vendored SuiteNanobind and PecletDeps so `pip install
+# peclet-geom` builds with no suite checkout present (the failure core hit from 0.1.0 to 0.6.0).
+# NO sdist.include here, deliberately. scikit-build-core takes the sdist from the GIT file list by
+# default, which already excludes build trees via .gitignore — whereas `sdist.include = ["python"]`
+# FORCE-includes, overriding .gitignore, and a local `cmake -B python/build` then rides along:
+# measured 476 KB of CMakeCache and objects carrying absolute paths from the author's machine.
+# docs/RELEASE.md §A3 records this trap for the submodule sdists; the force-include is how it bites.
+# Everything this package needs (python/, cmake/, README, LICENSE, CITATION.cff) is tracked.
+sdist.exclude = ["python/build", "python/build_*", "**/__pycache__", "**/*.so", "dist"]

peclet_geom-1.0.0/python/CMakeLists.txt

@@ -0,0 +1,52 @@
+# Python bindings for the analytic-SDF scene authoring layer — `peclet.geom`.
+#
+# THE POINT OF THIS FILE IS WHAT IT DOES NOT DO. It calls no find_package(MPI) and no
+# find_package(Kokkos), because geom_bindings.cpp needs neither: its closure is six
+# peclet/core/geom/*.hpp headers plus common/{types,portable}.hpp, none of which include
+# peclet/core/common/mpi.hpp (suite/docs/CORE_BOUNDARY.md §2.1 makes that the boundary test).
+#
+# That is the defect this package exists to fix. While these bindings shared a distribution with
+# the halo bindings, core/python/CMakeLists.txt's `find_package(MPI REQUIRED)` covered both, so
+# `pip install` of a pure-geometry API needed an MPI toolchain — and eleven gallery pages plus
+# peclet.dem's scene_particle.build() were unobtainable without one.
+#
+#   cmake -S python -B python/build && cmake --build python/build -j
+#   PYTHONPATH=python/build python -c "from peclet.geom import SceneBuilder"
+cmake_minimum_required(VERSION 3.24)
+project(peclet_geom_python LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# SuiteNanobind: the umbrella's copy in a suite checkout, the vendored copy otherwise. Same
+# arrangement as core, for the same reason (DECISIONS.md: the sdist must be self-contained).
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../../cmake" "${CMAKE_CURRENT_SOURCE_DIR}/../cmake")
+include(SuiteNanobind)
+suite_require_nanobind()
+
+# The core headers, from the sibling checkout or vendored at PECLET_CORE_TAG (cmake/PecletDeps.cmake).
+include(${CMAKE_CURRENT_SOURCE_DIR}/../cmake/PecletDeps.cmake)
+peclet_sibling_include(peclet-core "${PECLET_CORE_TAG}" "../../core" PECLET_CORE_INCLUDE)
+
+nanobind_add_module(geom_bindings NB_STATIC geom_bindings.cpp)
+set_target_properties(geom_bindings PROPERTIES OUTPUT_NAME _geom
+                      LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/peclet/geom")
+target_include_directories(geom_bindings PRIVATE ${PECLET_CORE_INCLUDE})
+
+# state_hash.py refuses to compare hashes across toolchains, so the module must SAY which one built
+# it — otherwise --check skips (exit 77) and the byte gate silently proves nothing.
+target_compile_definitions(geom_bindings PRIVATE
+  "PECLET_GEOM_BUILD_TOOLCHAIN=\"${CMAKE_CXX_COMPILER_ID} ${CMAKE_CXX_COMPILER_VERSION} ${CMAKE_BUILD_TYPE} ${CMAKE_SYSTEM_PROCESSOR}\"")
+
+# The importable package: peclet/geom/{__init__.py, _geom<abi>.so, _geom.pyi, py.typed}. `peclet`
+# itself is a PEP-420 namespace owned by the member packages — it gets no __init__.py here.
+set(_pkg "${CMAKE_BINARY_DIR}/peclet/geom")
+file(MAKE_DIRECTORY "${_pkg}")
+configure_file(packaging/geom_init.py "${_pkg}/__init__.py" COPYONLY)
+configure_file(packaging/_geom.pyi    "${_pkg}/_geom.pyi"   COPYONLY)
+file(TOUCH "${_pkg}/py.typed")
+
+install(TARGETS geom_bindings LIBRARY DESTINATION peclet/geom)
+install(FILES packaging/geom_init.py DESTINATION peclet/geom RENAME __init__.py)
+install(FILES packaging/_geom.pyi    DESTINATION peclet/geom)
+install(FILES "${_pkg}/py.typed"     DESTINATION peclet/geom)

peclet_geom-1.0.0/python/geom_bindings.cpp

@@ -0,0 +1,362 @@
+// peclet.geom — Python authoring for the shared analytic-SDF scene layer.
+//
+// Was peclet.core.geom (package peclet-core) until the boundary split of suite/docs/CORE_BOUNDARY.md:
+// this is host-only SDF authoring with no MPI in it, and it was unobtainable without an MPI
+// toolchain while it shared a distribution with the halo bindings. Now its own package, with wheels.
+//
+// The missing ergonomic half of suite/docs/archive/ANALYTIC_SDF_GEOMETRY.md: SceneBuilder has been
+// C++ only, so every Python consumer (flow's set_scene, dem's add_analytic_wall / add_scene_shape,
+// the campaign gates) hand-assembled the flat (node_ints, node_reals, inst_ints, inst_reals)
+// arrays. This module binds the builder itself, batch evaluation, lattice baking (the dem
+// grid-particle path), and geom::bodyProperties — mass, COM, full inertia tensor, and the
+// principal decomposition as three moments plus a QUATERNION — with addReframed closing the
+// non-principal-reference-frame question exactly (one composed transform, no resampling).
+//
+// Host-only: no Kokkos, no MPI. Preprocessing tooling by design.
+#include <nanobind/nanobind.h>
+#include <nanobind/ndarray.h>
+#include <nanobind/stl/array.h>
+#include <nanobind/stl/pair.h>
+#include <nanobind/stl/string.h>
+#include <nanobind/stl/vector.h>
+
+#include <cstring>
+#include <limits>
+#include <string>
+#include <vector>
+
+#include "peclet/core/geom/body_properties.hpp"
+#include "peclet/core/geom/scene_builder.hpp"
+#include "peclet/core/geom/scene_query.hpp"
+
+namespace nb = nanobind;
+namespace g = peclet::core::geom;
+using peclet::core::Quat;
+using peclet::core::Vec3;
+
+namespace {
+
+int kindFromName(const std::string& k) {
+  if (k == "sphere")
+    return g::kSphere;
+  if (k == "box")
+    return g::kBox;
+  if (k == "hollow_cylinder")
+    return g::kHollowCylinder;
+  if (k == "hollow_cylinder_shell")
+    return g::kHollowCylinderShell;
+  if (k == "capsule")
+    return g::kCapsule;
+  if (k == "torus")
+    return g::kTorus;
+  if (k == "cone")
+    return g::kCone;
+  if (k == "ellipsoid")
+    return g::kEllipsoid;
+  if (k == "superquadric")
+    return g::kSuperquadric;
+  throw std::invalid_argument(
+      "unknown leaf kind '" + k +
+      "' (sphere, box, hollow_cylinder, hollow_cylinder_shell, capsule, torus, cone, ellipsoid, "
+      "superquadric; grids go through add_grid)");
+}
+
+g::Transform<double> makeTransform(std::array<double, 3> t, std::array<double, 4> q, double s) {
+  g::Transform<double> tr;
+  tr.translation = Vec3<double>{t[0], t[1], t[2]};
+  tr.rotation = Quat<double>{q[0], q[1], q[2], q[3]};
+  tr.scale = s;
+  return tr;
+}
+
+template <class T>
+nb::ndarray<nb::numpy, T> toArray(std::vector<T>&& v, std::initializer_list<std::size_t> shape) {
+  auto* held = new std::vector<T>(std::move(v));
+  nb::capsule owner(held, [](void* p) noexcept { delete static_cast<std::vector<T>*>(p); });
+  std::vector<std::size_t> sh(shape);
+  return nb::ndarray<nb::numpy, T>(held->data(), sh.size(), sh.data(), owner);
+}
+
+/// A thin owner: the builder plus a cached view for evaluation.
+struct PyScene {
+  g::SceneBuilder<double> b;
+
+  auto rootEval(int root) const {
+    const g::SceneView<double> sv = b.view();
+    if (root < 0 || root >= sv.nodeCount)
+      throw std::out_of_range("root node index out of range");
+    return [sv, root](Vec3<double> p) {
+      return g::evalTree<double>(g::TablePtr<g::ShapeNode<double>>{sv.nodes}, sv.nodeCount, root, p,
+                                 g::TablePtr<g::GridDesc<double>>{sv.grids},
+                                 g::PoolPtr<float>{sv.samples});
+    };
+  }
+};
+
+}  // namespace
+
+NB_MODULE(_geom, m) {
+  m.attr("build_toolchain") = PECLET_GEOM_BUILD_TOOLCHAIN;  // state_hash.py compares like with like
+  m.doc() =
+      "Analytic-SDF scene authoring: SceneBuilder (leaves + CSG + transforms + instancing), batch "
+      "evaluation, lattice baking, and rigid-body mass properties (mass, COM, inertia tensor, "
+      "principal moments + quaternion) by implicit quadrature.";
+
+  nb::class_<PyScene>(
+      m, "SceneBuilder",
+      "Authors an analytic constructive-solid-geometry (CSG) scene as two arrays: a forest of "
+      "NODES -- leaves (add_leaf), the union/intersection/difference combinators and "
+      "add_reframed copies, each addressed by the index its add_* call returns -- and a list of "
+      "INSTANCES (add_instance) that place one node's subtree in the world with a rigid-body "
+      "transform, optional linear/angular velocity and a material id. A node is a shape "
+      "DEFINITION; an instance is a PLACEMENT of one (see num_nodes vs num_instances). encode() "
+      "flattens both to the (node_ints, node_reals, inst_ints, inst_reals) arrays that "
+      "flow.set_scene, dem.add_analytic_wall and dem.add_scene_shape consume; eval()/eval_root() "
+      "evaluate the scene directly, for authoring and debugging (solvers evaluate on device from "
+      "the encoded arrays, not through this class).")
+      .def(nb::init<>(),
+           "SceneBuilder(): takes no arguments. Starts with an empty node forest and no "
+           "instances; build a tree bottom-up with add_leaf and the CSG combinators, place it "
+           "with add_instance, then encode() (or eval()/eval_root() to check it directly).")
+      .def(
+          "add_leaf",
+          [](PyScene& s, const std::string& kind, std::vector<double> params,
+             std::array<double, 3> translation, std::array<double, 4> rotation, double scale) {
+            std::initializer_list<double> il{};  // addLeaf takes an initializer_list; go via node
+            g::ShapeNode<double> nd;
+            nd.kind = kindFromName(kind);
+            for (std::size_t i = 0; i < params.size() && i < 8; ++i)
+              nd.params[i] = params[i];
+            nd.transform = makeTransform(translation, rotation, scale);
+            (void)il;
+            return s.b.addNode(nd);
+          },
+          nb::arg("kind"), nb::arg("params"),
+          nb::arg("translation") = std::array<double, 3>{0, 0, 0},
+          nb::arg("rotation") = std::array<double, 4>{0, 0, 0, 1}, nb::arg("scale") = 1.0,
+          "Add a leaf primitive; returns its node index. kind: sphere [r], box [hx,hy,hz], "
+          "hollow_cylinder [rOuter,height,thickness] (y axis, distance-exact), "
+          "hollow_cylinder_shell [rOuter,rInner,height] (z axis, sign-exact), capsule "
+          "[r,halfLength] (y), torus [R,r] (y), cone [rBottom,rTop,halfHeight] (y), ellipsoid "
+          "[rx,ry,rz] (BOUND), superquadric [rx,ry,rz,e] (BOUND). rotation is a quaternion "
+          "(x, y, z, w).")
+      .def(
+          "add_union",
+          [](PyScene& s, int a, int b2, std::array<double, 3> t, std::array<double, 4> q,
+             double sc) { return s.b.addUnion(a, b2, makeTransform(t, q, sc)); },
+          nb::arg("a"), nb::arg("b"), nb::arg("translation") = std::array<double, 3>{0, 0, 0},
+          nb::arg("rotation") = std::array<double, 4>{0, 0, 0, 1}, nb::arg("scale") = 1.0,
+          "SDF min of subtrees `a` and `b` (their node indices) -- the shape occupied by either "
+          "one; returns the new combinator's node index. `translation`/`rotation` (quaternion x, "
+          "y, z, w)/`scale` transform the frame BOTH children are evaluated in, so the union can "
+          "be placed, rotated or scaled as one rigid piece without touching a or b.")
+      .def(
+          "add_intersection",
+          [](PyScene& s, int a, int b2, std::array<double, 3> t, std::array<double, 4> q,
+             double sc) { return s.b.addIntersection(a, b2, makeTransform(t, q, sc)); },
+          nb::arg("a"), nb::arg("b"), nb::arg("translation") = std::array<double, 3>{0, 0, 0},
+          nb::arg("rotation") = std::array<double, 4>{0, 0, 0, 1}, nb::arg("scale") = 1.0,
+          "SDF max of subtrees `a` and `b` (their node indices) -- the shape occupied by both; "
+          "returns the new combinator's node index. `translation`/`rotation` (quaternion x, y, "
+          "z, w)/`scale` transform the frame both children are evaluated in, exactly as in "
+          "add_union.")
+      .def(
+          "add_difference",
+          [](PyScene& s, int a, int b2, std::array<double, 3> t, std::array<double, 4> q,
+             double sc) { return s.b.addDifference(a, b2, makeTransform(t, q, sc)); },
+          nb::arg("a"), nb::arg("b"), nb::arg("translation") = std::array<double, 3>{0, 0, 0},
+          nb::arg("rotation") = std::array<double, 4>{0, 0, 0, 1}, nb::arg("scale") = 1.0,
+          "a minus b.")
+      .def(
+          "add_reframed",
+          [](PyScene& s, int root, std::array<double, 3> t, std::array<double, 4> q, double sc) {
+            return s.b.addReframed(root, makeTransform(t, q, sc));
+          },
+          nb::arg("root"), nb::arg("translation") = std::array<double, 3>{0, 0, 0},
+          nb::arg("rotation") = std::array<double, 4>{0, 0, 0, 1}, nb::arg("scale") = 1.0,
+          "Deep-copy the subtree and pre-compose this transform onto the copied root, so "
+          "eval_new(p) = eval_old(toLocal(W, p)) -- i.e. this PLACES the copy at W. With the "
+          "inverse principal transform from body_properties (rotation = conjugate of its quat, "
+          "translation = -com rotated by the conjugate... see principal_frame()), the copy's "
+          "canonical frame IS the principal body frame, exactly, with no resampling.")
+      .def(
+          "principal_frame",
+          [](PyScene& s, int root, std::array<double, 3> lo, std::array<double, 3> hi, int n,
+             int order, int nseg) {
+            const auto bp =
+                g::bodyProperties<double>(s.rootEval(root), Vec3<double>{lo[0], lo[1], lo[2]},
+                                          Vec3<double>{hi[0], hi[1], hi[2]}, n, order, nseg);
+            // W with toLocal(W, p_body) = com + R p_body: q_W = conj(q_R), t_W = invR(q_R, -com)
+            const Quat<double> qc{-bp.quat.x, -bp.quat.y, -bp.quat.z, bp.quat.w};
+            const Vec3<double> tw =
+                peclet::core::invRotate(bp.quat, Vec3<double>{-bp.com.x, -bp.com.y, -bp.com.z});
+            g::Transform<double> W;
+            W.rotation = qc;
+            W.translation = tw;
+            return s.b.addReframed(root, W);
+          },
+          nb::arg("root"), nb::arg("lo"), nb::arg("hi"), nb::arg("n") = 32, nb::arg("order") = 5,
+          nb::arg("nseg") = 8,
+          "Measure the subtree's mass properties and return a NEW root whose canonical frame is "
+          "the principal body frame (COM at the origin, axes principal) -- the one-call answer to "
+          "'my shape's reference frame is not its principal frame'. The original subtree is "
+          "untouched.")
+      .def(
+          "add_instance",
+          [](PyScene& s, int root, std::array<double, 3> t, std::array<double, 4> q, double sc,
+             std::array<double, 3> lin, std::array<double, 3> ang, std::array<double, 3> cen,
+             int material) {
+            return s.b.addInstance(root, makeTransform(t, q, sc),
+                                   Vec3<double>{lin[0], lin[1], lin[2]},
+                                   Vec3<double>{ang[0], ang[1], ang[2]},
+                                   Vec3<double>{cen[0], cen[1], cen[2]}, material);
+          },
+          nb::arg("root"), nb::arg("translation") = std::array<double, 3>{0, 0, 0},
+          nb::arg("rotation") = std::array<double, 4>{0, 0, 0, 1}, nb::arg("scale") = 1.0,
+          nb::arg("lin_vel") = std::array<double, 3>{0, 0, 0},
+          nb::arg("ang_vel") = std::array<double, 3>{0, 0, 0},
+          nb::arg("center") = std::array<double, 3>{std::numeric_limits<double>::quiet_NaN(),
+                                                    std::numeric_limits<double>::quiet_NaN(),
+                                                    std::numeric_limits<double>::quiet_NaN()},
+          nb::arg("material") = -1,
+          "Place a tree in the world; returns the instance index. What flow's set_scene and the "
+          "resolved coupling consume. `center` is the centre of rotation for ang_vel: leave it NaN "
+          "(the default) and it FOLLOWS the body (the translation, re-anchored on every "
+          "set_instance_transform); give any finite point and it is PINNED there in world "
+          "coordinates -- (0, 0, 0) included. (Raw instance arrays keep the legacy reading of an "
+          "all-zero centre as 'follows the body'; pin a world-origin centre from a raw array "
+          "through "
+          "flow's set_instance_motion(center=...).)")
+      .def(
+          "encode",
+          [](PyScene& s) {
+            std::vector<int> ni, ii;
+            std::vector<double> nr, ir;
+            s.b.encode(ni, nr, ii, ir);
+            return nb::make_tuple(
+                toArray(std::move(ni), {ni.size()}), toArray(std::move(nr), {nr.size()}),
+                toArray(std::move(ii), {ii.size()}), toArray(std::move(ir), {ir.size()}));
+          },
+          "The flat (node_ints, node_reals, inst_ints, inst_reals) arrays -- exactly what "
+          "flow.set_scene, dem.add_analytic_wall and dem.add_scene_shape take.")
+      .def(
+          "eval",
+          [](PyScene& s, nb::ndarray<double, nb::shape<-1, 3>, nb::c_contig> pts) {
+            const g::SceneView<double> sv = s.b.view();
+            const std::size_t n = pts.shape(0);
+            std::vector<double> out(n);
+            const double* p = pts.data();
+            for (std::size_t i = 0; i < n; ++i)
+              out[i] = g::evalScene<double>(sv, Vec3<double>{p[3 * i], p[3 * i + 1], p[3 * i + 2]});
+            return toArray(std::move(out), {n});
+          },
+          nb::arg("points"),
+          "Signed distance of the whole scene (min over instances) at (N,3) world points. "
+          "Authoring/debug; solvers evaluate on device.")
+      .def(
+          "eval_root",
+          [](PyScene& s, int root, nb::ndarray<double, nb::shape<-1, 3>, nb::c_contig> pts) {
+            auto f = s.rootEval(root);
+            const std::size_t n = pts.shape(0);
+            std::vector<double> out(n);
+            const double* p = pts.data();
+            for (std::size_t i = 0; i < n; ++i)
+              out[i] = f(Vec3<double>{p[3 * i], p[3 * i + 1], p[3 * i + 2]});
+            return toArray(std::move(out), {n});
+          },
+          nb::arg("root"), nb::arg("points"),
+          "Signed distance of ONE subtree, in its own canonical frame, at (N,3) points.")
+      .def(
+          "eval_root_grad",
+          [](PyScene& s, int root, nb::ndarray<double, nb::shape<-1, 3>, nb::c_contig> pts) {
+            const g::SceneView<double> sv = s.b.view();
+            if (root < 0 || root >= sv.nodeCount)
+              throw std::out_of_range("root node index out of range");
+            const std::size_t n = pts.shape(0);
+            std::vector<double> val(n), grd(3 * n);
+            const double* p = pts.data();
+            for (std::size_t i = 0; i < n; ++i) {
+              Vec3<double> gv;
+              val[i] = g::evalTreeGrad<double>(
+                  g::TablePtr<g::ShapeNode<double>>{sv.nodes}, sv.nodeCount, root,
+                  Vec3<double>{p[3 * i], p[3 * i + 1], p[3 * i + 2]},
+                  g::TablePtr<g::GridDesc<double>>{sv.grids}, g::PoolPtr<float>{sv.samples}, gv);
+              grd[3 * i] = gv.x;
+              grd[3 * i + 1] = gv.y;
+              grd[3 * i + 2] = gv.z;
+            }
+            return nb::make_tuple(toArray(std::move(val), {n}), toArray(std::move(grd), {n, 3}));
+          },
+          nb::arg("root"), nb::arg("points"),
+          "Value AND analytic gradient of one subtree at (N,3) canonical points, one traversal: "
+          "(values (N,), gradients (N,3), unnormalised). At CSG ridges the gradient is the ACTIVE "
+          "branch's exact normal (deterministic left tie-break), not a finite-difference smear.")
+      .def(
+          "bake",
+          [](PyScene& s, int root, std::array<double, 3> origin, std::array<double, 3> spacing,
+             std::array<int, 3> dims) {
+            auto f = s.rootEval(root);
+            const int nx = dims[0], ny = dims[1], nz = dims[2];
+            if (nx < 2 || ny < 2 || nz < 2)
+              throw std::invalid_argument("bake: dims must be >= 2 per axis");
+            std::vector<float> out((std::size_t)nx * ny * nz);
+            for (int k = 0; k < nz; ++k)
+              for (int j = 0; j < ny; ++j)
+                for (int i = 0; i < nx; ++i)
+                  out[(std::size_t)i + (std::size_t)j * nx + (std::size_t)k * nx * ny] =
+                      (float)f(Vec3<double>{origin[0] + i * spacing[0], origin[1] + j * spacing[1],
+                                            origin[2] + k * spacing[2]});
+            return toArray(std::move(out), {(std::size_t)nx * ny * nz});
+          },
+          nb::arg("root"), nb::arg("origin"), nb::arg("spacing"), nb::arg("dims"),
+          "Sample a subtree on a lattice: flat float32, x-fastest (idx = i + j*nx + k*nx*ny), at "
+          "nodes origin + (i,j,k)*spacing -- the layout dem's grid-SDF particles and shell "
+          "generation consume.")
+      .def(
+          "body_properties",
+          [](PyScene& s, int root, std::array<double, 3> lo, std::array<double, 3> hi, int n,
+             int order, int nseg, double density) {
+            const auto bp = g::bodyProperties<double>(
+                s.rootEval(root), Vec3<double>{lo[0], lo[1], lo[2]},
+                Vec3<double>{hi[0], hi[1], hi[2]}, n, order, nseg, density);
+            nb::dict d;
+            d["volume"] = bp.volume;
+            d["mass"] = bp.mass;
+            d["com"] = std::array<double, 3>{bp.com.x, bp.com.y, bp.com.z};
+            std::vector<double> I(9), R(9);
+            for (int r = 0; r < 3; ++r)
+              for (int c = 0; c < 3; ++c) {
+                I[(std::size_t)(3 * r + c)] = bp.inertia[r][c];
+                R[(std::size_t)(3 * r + c)] = bp.rotation[r][c];
+              }
+            d["inertia_tensor"] = toArray(std::move(I), {3, 3});
+            d["principal"] =
+                std::array<double, 3>{bp.principal[0], bp.principal[1], bp.principal[2]};
+            d["rotation"] = toArray(std::move(R), {3, 3});
+            d["quat"] = std::array<double, 4>{bp.quat.x, bp.quat.y, bp.quat.z, bp.quat.w};
+            return d;
+          },
+          nb::arg("root"), nb::arg("lo"), nb::arg("hi"), nb::arg("n") = 32, nb::arg("order") = 5,
+          nb::arg("nseg") = 8, nb::arg("density") = 1.0,
+          "Mass properties of {subtree < 0} over [lo, hi] (which MUST contain the solid), constant "
+          "density, by implicit quadrature: dict with volume, mass, com, inertia_tensor (3,3 about "
+          "the COM), principal (3, ascending), rotation (3,3; columns = principal axes, "
+          "p_input = com + R p_body) and quat (x,y,z,w). Sign-exact bracketing means bound-only "
+          "leaves (ellipsoid, superquadric, CSG) carry NO systematic bias; measured ~4e-6 relative "
+          "at n=32 (ctest geom_body).")
+      .def(
+          "num_nodes", [](PyScene& s) { return (int)s.b.nodes().size(); },
+          "Number of NODES in the shape forest -- every leaf (add_leaf), CSG combinator "
+          "(add_union/add_intersection/add_difference) and add_reframed copy adds exactly one, "
+          "whether or not it has ever been placed with add_instance. A node is a shape "
+          "DEFINITION addressed by the index its add_* call returned, not something a solver "
+          "sees directly.")
+      .def(
+          "num_instances", [](PyScene& s) { return (int)s.b.instances().size(); },
+          "Number of INSTANCES -- entries created by add_instance, i.e. shape trees actually "
+          "PLACED in the world with a transform and optional rigid-body velocity/material id. "
+          "This is what solvers iterate over. Distinct from num_nodes: one node (say a stirrer "
+          "built as a union of two leaves) can be instanced zero, one, or many times at "
+          "different places, so num_instances can be smaller, equal to, or larger than "
+          "num_nodes.");
+}

peclet_geom-1.0.0/python/packaging/_geom.pyi

@@ -0,0 +1,76 @@
+# Type stub for peclet.core.geom — GENERATED by `python -m nanobind.stubgen -m peclet.core.geom -o packaging/core_geom.pyi`
+# (PYTHONPATH at the python build tree). Do not hand-edit; regenerate after changing geom_bindings.cpp.
+"""
+Analytic-SDF scene authoring: SceneBuilder (leaves + CSG + transforms + instancing), batch evaluation, lattice baking, and rigid-body mass properties (mass, COM, inertia tensor, principal moments + quaternion) by implicit quadrature.
+"""
+
+from collections.abc import Sequence
+from typing import Annotated
+
+import numpy
+from numpy.typing import NDArray
+
+
+class SceneBuilder:
+    def __init__(self) -> None: ...
+
+    def add_leaf(self, kind: str, params: Sequence[float], translation: Sequence[float] = [0.0, 0.0, 0.0], rotation: Sequence[float] = [0.0, 0.0, 0.0, 1.0], scale: float = 1.0) -> int:
+        """
+        Add a leaf primitive; returns its node index. kind: sphere [r], box [hx,hy,hz], hollow_cylinder [rOuter,height,thickness] (y axis, distance-exact), hollow_cylinder_shell [rOuter,rInner,height] (z axis, sign-exact), capsule [r,halfLength] (y), torus [R,r] (y), cone [rBottom,rTop,halfHeight] (y), ellipsoid [rx,ry,rz] (BOUND), superquadric [rx,ry,rz,e] (BOUND). rotation is a quaternion (x, y, z, w).
+        """
+
+    def add_union(self, a: int, b: int, translation: Sequence[float] = [0.0, 0.0, 0.0], rotation: Sequence[float] = [0.0, 0.0, 0.0, 1.0], scale: float = 1.0) -> int: ...
+
+    def add_intersection(self, a: int, b: int, translation: Sequence[float] = [0.0, 0.0, 0.0], rotation: Sequence[float] = [0.0, 0.0, 0.0, 1.0], scale: float = 1.0) -> int: ...
+
+    def add_difference(self, a: int, b: int, translation: Sequence[float] = [0.0, 0.0, 0.0], rotation: Sequence[float] = [0.0, 0.0, 0.0, 1.0], scale: float = 1.0) -> int:
+        """a minus b."""
+
+    def add_reframed(self, root: int, translation: Sequence[float] = [0.0, 0.0, 0.0], rotation: Sequence[float] = [0.0, 0.0, 0.0, 1.0], scale: float = 1.0) -> int:
+        """
+        Deep-copy the subtree and pre-compose this transform onto the copied root, so eval_new(p) = eval_old(toLocal(W, p)) -- i.e. this PLACES the copy at W. With the inverse principal transform from body_properties (rotation = conjugate of its quat, translation = -com rotated by the conjugate... see principal_frame()), the copy's canonical frame IS the principal body frame, exactly, with no resampling.
+        """
+
+    def principal_frame(self, root: int, lo: Sequence[float], hi: Sequence[float], n: int = 32, order: int = 5, nseg: int = 8) -> int:
+        """
+        Measure the subtree's mass properties and return a NEW root whose canonical frame is the principal body frame (COM at the origin, axes principal) -- the one-call answer to 'my shape's reference frame is not its principal frame'. The original subtree is untouched.
+        """
+
+    def add_instance(self, root: int, translation: Sequence[float] = [0.0, 0.0, 0.0], rotation: Sequence[float] = [0.0, 0.0, 0.0, 1.0], scale: float = 1.0, lin_vel: Sequence[float] = [0.0, 0.0, 0.0], ang_vel: Sequence[float] = [0.0, 0.0, 0.0], center: Sequence[float] = [float('nan'), float('nan'), float('nan')], material: int = -1) -> int:
+        """
+        Place a tree in the world; returns the instance index. What flow's set_scene and the resolved coupling consume. `center` is the centre of rotation for ang_vel: leave it NaN (the default) and it FOLLOWS the body (the translation, re-anchored on every set_instance_transform); give any finite point and it is PINNED there in world coordinates -- (0, 0, 0) included. (Raw instance arrays keep the legacy reading of an all-zero centre as 'follows the body'; pin a world-origin centre from a raw array through flow's set_instance_motion(center=...).)
+        """
+
+    def encode(self) -> tuple:
+        """
+        The flat (node_ints, node_reals, inst_ints, inst_reals) arrays -- exactly what flow.set_scene, dem.add_analytic_wall and dem.add_scene_shape take.
+        """
+
+    def eval(self, points: Annotated[NDArray[numpy.float64], dict(shape=(None, 3), order='C')]) -> NDArray[numpy.float64]:
+        """
+        Signed distance of the whole scene (min over instances) at (N,3) world points. Authoring/debug; solvers evaluate on device.
+        """
+
+    def eval_root(self, root: int, points: Annotated[NDArray[numpy.float64], dict(shape=(None, 3), order='C')]) -> NDArray[numpy.float64]:
+        """
+        Signed distance of ONE subtree, in its own canonical frame, at (N,3) points.
+        """
+
+    def eval_root_grad(self, root: int, points: Annotated[NDArray[numpy.float64], dict(shape=(None, 3), order='C')]) -> tuple:
+        """
+        Value AND analytic gradient of one subtree at (N,3) canonical points, one traversal: (values (N,), gradients (N,3), unnormalised). At CSG ridges the gradient is the ACTIVE branch's exact normal (deterministic left tie-break), not a finite-difference smear.
+        """
+
+    def bake(self, root: int, origin: Sequence[float], spacing: Sequence[float], dims: Sequence[int]) -> NDArray[numpy.float32]:
+        """
+        Sample a subtree on a lattice: flat float32, x-fastest (idx = i + j*nx + k*nx*ny), at nodes origin + (i,j,k)*spacing -- the layout dem's grid-SDF particles and shell generation consume.
+        """
+
+    def body_properties(self, root: int, lo: Sequence[float], hi: Sequence[float], n: int = 32, order: int = 5, nseg: int = 8, density: float = 1.0) -> dict:
+        """
+        Mass properties of {subtree < 0} over [lo, hi] (which MUST contain the solid), constant density, by implicit quadrature: dict with volume, mass, com, inertia_tensor (3,3 about the COM), principal (3, ascending), rotation (3,3; columns = principal axes, p_input = com + R p_body) and quat (x,y,z,w). Sign-exact bracketing means bound-only leaves (ellipsoid, superquadric, CSG) carry NO systematic bias; measured ~4e-6 relative at n=32 (ctest geom_body).
+        """
+
+    def num_nodes(self) -> int: ...
+
+    def num_instances(self) -> int: ...

peclet_geom-1.0.0/python/packaging/geom_init.py

@@ -0,0 +1,15 @@
+"""peclet.geom — analytic-SDF scene authoring: CSG trees, batch evaluation, lattice baking,
+and rigid-body mass properties (mass, centre of mass, inertia tensor, principal frame).
+
+Host-only and dependency-light by design: no MPI, no Kokkos, no Kokkos-backed solver. That is
+why it ships as wheels and is part of a plain ``pip install peclet``.
+
+Until peclet 1.2.0 this was ``peclet.core.geom`` in the ``peclet-core`` distribution, which could
+not be installed without an MPI toolchain. ``peclet.core.geom`` still works and is the same object
+(``peclet.core.geom.SceneBuilder is peclet.geom.SceneBuilder``); it warns from 1.3.0 and is removed
+in 2.0.0. See suite/docs/CORE_BOUNDARY.md.
+"""
+from ._geom import *  # noqa: F401,F403
+from . import _geom as _ext
+
+__all__ = [n for n in dir(_ext) if not n.startswith("_")]

peclet_geom-1.0.0/python/state_hash.py

@@ -0,0 +1,152 @@
+"""Fixed-seed reference runs of every public entry path of peclet.geom, hashed.
+
+The structural gate of suite/docs/QUALITY_PLAN.md §3.G: a refactor that moves code verbatim must
+leave every final state BYTE-IDENTICAL. This script runs one deterministic scenario per public
+entry path, hashes the final arrays (SHA-256 of the raw float64/int bytes) and prints them; with
+``--save FILE`` it records them as JSON and with ``--check FILE`` it compares against a recording
+and exits non-zero on any difference.
+
+    PYTHONPATH=<python build tree> OMP_NUM_THREADS=1 python python/state_hash.py --save pre.json
+    PYTHONPATH=<python build tree> OMP_NUM_THREADS=1 mpirun -np 2 python python/state_hash.py --check pre.json
+
+Under ``mpirun -np N`` (N > 1) the distributed paths (ParticleMigrator / ParticleHalo across ranks)
+run too; every per-rank array is gathered to rank 0 in
+rank order before hashing, so the hash names carry the rank count (``.np2``). Run at
+OMP_NUM_THREADS=1: the device reductions are order-dependent at more than one thread.
+
+Only ``geom`` here; the halo entry paths have the same script in peclet-halo (the `core` repo),
+and the AMR ones in peclet-amr. Split out of peclet-core 2026-09-21 (suite/docs/CORE_BOUNDARY.md);
+the geom hashes must be BYTE-IDENTICAL across that move, which is what proves it was a move.
+"""
+import argparse
+import hashlib
+import json
+import os
+import sys
+
+import numpy as np
+
+
+def sha(*arrays):
+    h = hashlib.sha256()
+    flat = []
+    for a in arrays:  # a binding may return a tuple of arrays: hash each member in order
+        flat += list(a) if isinstance(a, (tuple, list)) and not np.isscalar(a[0]) else [a]
+    for a in flat:
+        a = np.ascontiguousarray(a)
+        h.update(str(a.dtype).encode())
+        h.update(str(a.shape).encode())
+        h.update(a.tobytes())
+    return h.hexdigest()
+
+
+def gather_rows(comm, a):
+    """Concatenate a per-rank (n, k) array over ranks in rank order (rank 0 gets the result)."""
+    if comm is None or comm.size == 1:
+        return np.ascontiguousarray(a)
+    parts = comm.gather(np.ascontiguousarray(a), root=0)
+    return np.concatenate(parts, axis=0) if comm.rank == 0 else None
+
+
+# ---------------------------------------------------------------------------------------------
+# peclet.core.geom — a CSG scene evaluated on a grid, baked, and its mass properties.
+# ---------------------------------------------------------------------------------------------
+def run_geom(out, comm):
+    from peclet import geom
+    if comm is not None and comm.rank != 0:
+        return
+    s = geom.SceneBuilder()
+    sph = s.add_leaf("sphere", [0.3])
+    box = s.add_leaf("box", [0.25, 0.15, 0.2], translation=[0.2, 0.1, 0.0],
+                     rotation=[0.0, 0.0, 0.3826834323650898, 0.9238795325112867])
+    tor = s.add_leaf("torus", [0.35, 0.08], translation=[-0.1, 0.0, 0.2])
+    u = s.add_union(sph, box)
+    d = s.add_difference(u, tor)
+    s.add_instance(d, translation=[0.5, 0.5, 0.5])
+    s.add_instance(sph, translation=[0.15, 0.8, 0.3], scale=0.5)
+    n = 24
+    g = (np.arange(n) + 0.5) / n
+    pts = np.stack(np.meshgrid(g, g, g, indexing="ij"), axis=-1).reshape(-1, 3)
+    pts = np.ascontiguousarray(pts, dtype=np.float64)
+    out["geom.eval"] = sha(s.eval(pts))
+    out["geom.eval_root"] = sha(s.eval_root(d, pts))
+    out["geom.eval_root_grad"] = sha(s.eval_root_grad(d, pts))
+    baked = s.bake(d, [-0.6, -0.6, -0.6], [0.05, 0.05, 0.05], [24, 24, 24])
+    out["geom.bake"] = sha(np.asarray(baked))
+    bp = s.body_properties(d, [-0.8, -0.8, -0.8], [0.8, 0.8, 0.8], n=24)
+    out["geom.body_properties"] = sha(
+        np.array([bp["volume"], bp["mass"]]), np.asarray(bp["com"]), np.asarray(bp["inertia_tensor"]),
+        np.asarray(bp["principal"]), np.asarray(bp["rotation"]), np.asarray(bp["quat"]))
+
+
+# ---------------------------------------------------------------------------------------------
+RUNNERS = {"geom": run_geom}
+
+
+def toolchain():
+    """The module's compiler / version / build type. Hashes are only comparable within one."""
+    from peclet import geom
+    return getattr(geom, "build_toolchain", "unknown")
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--modules", default="geom", help="comma-separated subset of: geom (mpi moved to peclet-halo)")
+    ap.add_argument("--save", metavar="FILE", help="write the hashes as JSON")
+    ap.add_argument("--check", metavar="FILE", help="compare against a JSON recording")
+    args = ap.parse_args()
+    if os.environ.get("OMP_NUM_THREADS") != "1":
+        sys.stderr.write("state_hash: run with OMP_NUM_THREADS=1 (device reductions are order-dependent)\n")
+    comm = None
+    try:
+        from mpi4py import MPI
+        comm = MPI.COMM_WORLD
+    except ImportError:
+        pass
+    rank = comm.rank if comm is not None else 0
+    out = {}
+    for name in args.modules.split(","):
+        name = name.strip()
+        if not name:
+            continue
+        try:
+            RUNNERS[name](out, comm)
+        except ImportError as e:
+            if rank == 0:
+                print(f"# {name}: not importable ({e}); skipped")
+    if rank != 0:
+        return 0
+    for k in sorted(out):
+        print(f"{k} {out[k]}")
+    rc = 0
+    if args.check:
+        ref = json.load(open(args.check))
+        want = ref.pop("toolchain", None)
+        have = toolchain()
+        if want is not None and want != have:
+            print(f"state_hash: reference recorded with toolchain '{want}', this build is '{have}' — "
+                  "not comparable; SKIPPED (exit 77). Re-record with --save on this toolchain to gate it.")
+            return 77
+        # A recording may merge several rank counts; compare only the keys this run can produce
+        # (no `.npN` suffix, or the suffix of the current communicator size).
+        size = comm.size if comm is not None else 1
+        ref = {k: v for k, v in ref.items() if ".np" not in k or k.endswith(f".np{size}")}
+        for k in sorted(set(ref) | set(out)):
+            if k not in out:
+                print(f"MISSING {k}")
+                rc = 1
+            elif k not in ref:
+                print(f"NEW {k}")
+            elif ref[k] != out[k]:
+                print(f"DIFFER {k}: {ref[k][:16]}... -> {out[k][:16]}...")
+                rc = 1
+        print("state_hash: " + ("IDENTICAL" if rc == 0 else "DIFFERENCES FOUND"))
+    if args.save:
+        out["toolchain"] = toolchain()
+        with open(args.save, "w") as f:
+            json.dump(out, f, indent=1, sort_keys=True)
+    return rc
+
+
+if __name__ == "__main__":
+    sys.exit(main())

peclet_geom-1.0.0/python/state_hash_reference.json

@@ -0,0 +1,8 @@
+{
+ "geom.bake": "3d0033f786f20cf8a6caf8b05838a025ad591636bd1bf3ad4b36a89eabf8f5f3",
+ "geom.body_properties": "afb2cdfebdba03adfa66bd559024978f4092ee6ed857dc7dd727f003c4ab6529",
+ "geom.eval": "89e4051fed436b4e650739323ad49d3cb99d9996f513de92e55fd3a25bd69de5",
+ "geom.eval_root": "2567a7dac50a9f7d09cf5d0697587ba3730b0fc57ef481c231c396accb10e9b4",
+ "geom.eval_root_grad": "bf92ae4d692ce2187697e43c5ea4328b55460acf4a2e9d2a31868ff4c15c9234",
+ "toolchain": "GNU 14.2.0 Release x86_64"
+}