witwin 0.0.2__tar.gz → 0.4.0__tar.gz

witwin-0.4.0/.github/workflows/publish-witwin.yml

@@ -0,0 +1,210 @@
+name: Build and publish witwin
+
+on:
+  push:
+    branches:
+      - main
+      - "codex/**"
+  pull_request:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  validate_release:
+    if: github.event_name != 'release' || (startsWith(github.event.release.tag_name, 'witwin-v') && !github.event.release.prerelease)
+    name: Validate release
+    runs-on: ubuntu-latest
+    outputs:
+      package_dir: ${{ steps.package_dir.outputs.path }}
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Resolve package directory
+        id: package_dir
+        shell: bash
+        run: |
+          if [ -f pyproject.toml ]; then
+            echo "path=." >> "$GITHUB_OUTPUT"
+          elif [ -f core/pyproject.toml ]; then
+            echo "path=core" >> "$GITHUB_OUTPUT"
+          else
+            echo "Unable to find pyproject.toml for the witwin package." >&2
+            exit 1
+          fi
+
+      - name: Validate release tag and package version
+        if: github.event_name == 'release'
+        shell: bash
+        env:
+          PACKAGE_DIR: ${{ steps.package_dir.outputs.path }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import re
+          import sys
+          import tomllib
+          from pathlib import Path
+
+          tag = os.environ["RELEASE_TAG"]
+          match = re.fullmatch(r"witwin-v(?P<version>[0-9A-Za-z.+_-]+)", tag)
+          if match is None:
+              print(f"Release tag '{tag}' must match 'witwin-v<version>'.", file=sys.stderr)
+              raise SystemExit(1)
+
+          expected_version = match.group("version")
+          pyproject_path = Path(os.environ["PACKAGE_DIR"]) / "pyproject.toml"
+          project = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))["project"]
+          if project["name"] != "witwin":
+              print(f"Expected package name 'witwin', found '{project['name']}'.", file=sys.stderr)
+              raise SystemExit(1)
+          if project["version"] != expected_version:
+              print(
+                  f"Release tag version '{expected_version}' does not match "
+                  f"pyproject version '{project['version']}'.",
+                  file=sys.stderr,
+              )
+              raise SystemExit(1)
+          PY
+
+  build_wheel:
+    name: Build pure Python wheel
+    needs: validate_release
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build wheel
+        shell: bash
+        env:
+          PACKAGE_DIR: ${{ needs.validate_release.outputs.package_dir }}
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --wheel "$PACKAGE_DIR"
+
+      - name: Verify pure Python wheel
+        shell: bash
+        env:
+          PACKAGE_DIR: ${{ needs.validate_release.outputs.package_dir }}
+        run: |
+          python - <<'PY'
+          import os
+          import zipfile
+          from pathlib import Path
+
+          wheels = list((Path(os.environ["PACKAGE_DIR"]) / "dist").glob("*.whl"))
+          assert len(wheels) == 1, wheels
+          wheel = wheels[0]
+          assert wheel.name.endswith("-py3-none-any.whl"), wheel.name
+          native_suffixes = (".c", ".cc", ".cpp", ".cxx", ".cu", ".cuh", ".h", ".hpp", ".so", ".pyd", ".dll")
+          native = [
+              name for name in zipfile.ZipFile(wheel).namelist()
+              if name.lower().endswith(native_suffixes)
+          ]
+          assert not native, native
+          PY
+
+      - name: Upload wheel artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheel
+          path: ${{ needs.validate_release.outputs.package_dir }}/dist/*.whl
+          if-no-files-found: error
+
+  build_sdist:
+    name: Build source distribution
+    needs: validate_release
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build source distribution
+        shell: bash
+        env:
+          PACKAGE_DIR: ${{ needs.validate_release.outputs.package_dir }}
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --sdist "$PACKAGE_DIR"
+
+      - name: Verify pure Python source distribution
+        shell: bash
+        env:
+          PACKAGE_DIR: ${{ needs.validate_release.outputs.package_dir }}
+        run: |
+          python - <<'PY'
+          import os
+          import tarfile
+          from pathlib import Path
+
+          archives = list((Path(os.environ["PACKAGE_DIR"]) / "dist").glob("*.tar.gz"))
+          assert len(archives) == 1, archives
+          native_suffixes = (".c", ".cc", ".cpp", ".cxx", ".cu", ".cuh", ".h", ".hpp")
+          with tarfile.open(archives[0]) as archive:
+              native = [
+                  member.name for member in archive.getmembers()
+                  if member.isfile() and member.name.lower().endswith(native_suffixes)
+              ]
+          assert not native, native
+          PY
+
+      - name: Upload source distribution artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: ${{ needs.validate_release.outputs.package_dir }}/dist/*.tar.gz
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    if: github.event_name == 'release'
+    needs:
+      - build_wheel
+      - build_sdist
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/witwin/
+
+    steps:
+      - name: Download wheel artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: wheel
+          path: dist
+
+      - name: Download source distribution artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          skip-existing: true

{witwin-0.0.2 → witwin-0.4.0}/.gitignore

@@ -171,9 +171,6 @@ venv.bak/
 
 # mkdocs documentation
 /site
-.slangtorch_cache/
-.fdtd_runtime_*.slang
-.adjoint_kernels_runtime_*.slang
 *.png
 *.npy
 *.npz
@@ -229,6 +226,9 @@ __marimo__/
 # Streamlit
 .streamlit/secrets.toml
 
-# Native CUDA mesh SDF prebuilt extensions (built per-platform in CI)
-witwin/core/geometry/cuda/prebuilt/*.pyd
-witwin/core/geometry/cuda/prebuilt/*.so
+# Repository-local agent and test scratch directories
+.pytest_tmp/
+.codex_tmp/
+.codex-tmp/
+.test-tmp/
+.tmp/

witwin-0.4.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: witwin
+Version: 0.4.0
+Summary: Witwin shared logical-world, geometry, material, and dynamics contracts
+License-Expression: MIT
+Requires-Python: <3.15,>=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: torch>=2.10
+Provides-Extra: all
+Requires-Dist: witwin-genesis<0.2,>=0.1; extra == 'all'
+Requires-Dist: witwin-maxwell<0.3,>=0.2; extra == 'all'
+Requires-Dist: witwin-radar<0.4,>=0.3; extra == 'all'
+Provides-Extra: genesis
+Requires-Dist: witwin-genesis<0.2,>=0.1; extra == 'genesis'
+Provides-Extra: maxwell
+Requires-Dist: witwin-maxwell<0.3,>=0.2; extra == 'maxwell'
+Provides-Extra: radar
+Requires-Dist: witwin-radar<0.4,>=0.3; extra == 'radar'
+Description-Content-Type: text/markdown
+
+# WiTwin Core
+
+WiTwin Core is the shared logical-world and geometry package of the WiTwin stack. It defines solver-neutral scene, material, antenna, dynamics, snapshot, and geometry contracts. Solver packages compile those contracts into their own runtime resources and results.
+
+## Get Started
+
+Core supports CPython 3.10-3.14 and PyTorch 2.10 or newer.
+
+```bash
+pip install witwin
+```
+
+## Pure Python Distribution
+
+Core ships as a platform-independent `py3-none-any` wheel and contains no C++ or
+CUDA sources. Mesh SDF evaluation always has a PyTorch implementation. Solver
+packages may register their own optional accelerators; Maxwell owns and packages
+the CUDA mesh-SDF implementation used by Maxwell workflows.
+
+## What It Provides
+
+- Canonical `Scene`, `SceneSnapshot`, `Structure`, and stable logical IDs
+- Solver-neutral `PhysicalMaterial`, layers, roughness, dispersion, and phase-screen assignments
+- Logical TX/RX antenna state, planar receiver grids, rigid motion, trajectories, and deformation state
+- Stable structure, surface, material, assignment, primitive, and antenna identities
+- Typed mesh UV topology and explicit finite/perfect conductor material identity
+- Runtime-checkable `GeometrySpec` and `MaterialSpec` contracts
+- Shared analytic geometry primitives and differentiable mesh/SDF utilities
+- Granular topology, geometry, material, and assignment versions
+
+Core owns the logical `Scene`; each solver owns its compiled scene lifecycle, native resources, caches, and results. Radar-specific SMPL geometry lives in `witwin.radar.geometry`; Maxwell-specific `PolySlab` geometry lives in `witwin.maxwell.geometry`.
+
+## Stable API
+
+The supported public API is the set of names exported by `witwin.core.__all__`.
+Applications should import contracts, geometry types, identity allocators, and
+math utilities directly from `witwin.core`. CI locks this symbol set so adding,
+removing, or renaming a public symbol requires an intentional API change.
+Modules and names outside that export set are implementation details and may be
+reorganized between releases.
+
+## Coordinate and Motion Semantics
+
+Antenna orientation maps endpoint-local coordinates into world coordinates.
+Euler orientation is `(yaw, pitch, roll)` in radians with intrinsic Z-Y-X
+rotations; quaternion orientation is scalar-first `(w, x, y, z)`.
+Polarization and antenna element positions are endpoint-local, while
+`ReceiverGrid.x_axis` and `y_axis` are world-frame grid directions. Core's
+Torch rotation and projection helpers preserve autograd.
+
+Snapshot deformation is composed before motion: absolute deformation vertices
+replace authored local mesh vertices, or offsets are added to them; authored
+geometry transforms are applied next. `RigidMotion.rotation` then left-composes
+the authored rotation and its world-frame translation is added last. Endpoint
+motion follows the same rule after antenna-local orientation.
+
+`PhysicalMaterial(conductor_model="perfect")`, or the equivalent
+`PhysicalMaterial.perfect_conductor()`, carries explicit PEC identity while
+keeping finite logical material parameters. Solver-owned compilers map that
+identity to their native material ABI; Core does not encode native model IDs or
+effective conductivity constants.
+
+## 0.4 Migration
+
+- `Mesh.vertices`, `Mesh.faces`, `Mesh.world_vertices`, and
+  `Mesh.bounds_world` are tensor-valued contracts. `bounds_world` has shape
+  `(2, 3)`, with minimum coordinates in row 0 and maximum coordinates in row 1.
+- Tensor-authored geometry is never implicitly moved to the requested device.
+  Place authored tensors explicitly before construction; conflicting devices
+  fail loudly.
+- CUDA-authored meshes do not run host topology diagnostics or build a host BVH.
+  `fill_mode="auto"` therefore requires an explicit topology decision before
+  an SDF query.
+- `Material` is removed. `PhysicalMaterial` is the only public name for the
+  material contract; the two were aliases of one class. Replace
+  `from witwin.core import Material` with
+  `from witwin.core import PhysicalMaterial`.
+- `Structure` and `MaterialAssignment` now live in `witwin.core.structure`
+  rather than `witwin.core.material`, which keeps only material specifications.
+  Both remain exported from `witwin.core`, so package-level imports are
+  unaffected.
+- Continuous physical quantities are annotated `ScalarLike`
+  (`float | torch.Tensor`) instead of `Any`. `ScalarLike` and `ComplexLike` are
+  exported from `witwin.core`. This is a typing change only; the accepted
+  runtime values are unchanged.
+- `witwin.core.identity` documents its two allocation modes. Use
+  `reserve_*_id(value)` whenever identities must be reproducible across
+  processes; `new_*_id()` draws from a process-global counter and is
+  order-dependent.
+
+## Related Solvers
+
+- [WiTwin Maxwell](https://github.com/witwin-ai/witwin-maxwell)
+- [WiTwin Radar](https://github.com/witwin-ai/witwin-radar)
+
+## Developer
+
+<a href="http://xingyuchen.me/">
+  <img src="https://github.com/Asixa.png" alt="Xingyu Chen" width="48" height="48" style="border-radius:50%;">
+</a>
+
+[Xingyu Chen](http://xingyuchen.me/)

witwin-0.4.0/README.md

@@ -0,0 +1,102 @@
+# WiTwin Core
+
+WiTwin Core is the shared logical-world and geometry package of the WiTwin stack. It defines solver-neutral scene, material, antenna, dynamics, snapshot, and geometry contracts. Solver packages compile those contracts into their own runtime resources and results.
+
+## Get Started
+
+Core supports CPython 3.10-3.14 and PyTorch 2.10 or newer.
+
+```bash
+pip install witwin
+```
+
+## Pure Python Distribution
+
+Core ships as a platform-independent `py3-none-any` wheel and contains no C++ or
+CUDA sources. Mesh SDF evaluation always has a PyTorch implementation. Solver
+packages may register their own optional accelerators; Maxwell owns and packages
+the CUDA mesh-SDF implementation used by Maxwell workflows.
+
+## What It Provides
+
+- Canonical `Scene`, `SceneSnapshot`, `Structure`, and stable logical IDs
+- Solver-neutral `PhysicalMaterial`, layers, roughness, dispersion, and phase-screen assignments
+- Logical TX/RX antenna state, planar receiver grids, rigid motion, trajectories, and deformation state
+- Stable structure, surface, material, assignment, primitive, and antenna identities
+- Typed mesh UV topology and explicit finite/perfect conductor material identity
+- Runtime-checkable `GeometrySpec` and `MaterialSpec` contracts
+- Shared analytic geometry primitives and differentiable mesh/SDF utilities
+- Granular topology, geometry, material, and assignment versions
+
+Core owns the logical `Scene`; each solver owns its compiled scene lifecycle, native resources, caches, and results. Radar-specific SMPL geometry lives in `witwin.radar.geometry`; Maxwell-specific `PolySlab` geometry lives in `witwin.maxwell.geometry`.
+
+## Stable API
+
+The supported public API is the set of names exported by `witwin.core.__all__`.
+Applications should import contracts, geometry types, identity allocators, and
+math utilities directly from `witwin.core`. CI locks this symbol set so adding,
+removing, or renaming a public symbol requires an intentional API change.
+Modules and names outside that export set are implementation details and may be
+reorganized between releases.
+
+## Coordinate and Motion Semantics
+
+Antenna orientation maps endpoint-local coordinates into world coordinates.
+Euler orientation is `(yaw, pitch, roll)` in radians with intrinsic Z-Y-X
+rotations; quaternion orientation is scalar-first `(w, x, y, z)`.
+Polarization and antenna element positions are endpoint-local, while
+`ReceiverGrid.x_axis` and `y_axis` are world-frame grid directions. Core's
+Torch rotation and projection helpers preserve autograd.
+
+Snapshot deformation is composed before motion: absolute deformation vertices
+replace authored local mesh vertices, or offsets are added to them; authored
+geometry transforms are applied next. `RigidMotion.rotation` then left-composes
+the authored rotation and its world-frame translation is added last. Endpoint
+motion follows the same rule after antenna-local orientation.
+
+`PhysicalMaterial(conductor_model="perfect")`, or the equivalent
+`PhysicalMaterial.perfect_conductor()`, carries explicit PEC identity while
+keeping finite logical material parameters. Solver-owned compilers map that
+identity to their native material ABI; Core does not encode native model IDs or
+effective conductivity constants.
+
+## 0.4 Migration
+
+- `Mesh.vertices`, `Mesh.faces`, `Mesh.world_vertices`, and
+  `Mesh.bounds_world` are tensor-valued contracts. `bounds_world` has shape
+  `(2, 3)`, with minimum coordinates in row 0 and maximum coordinates in row 1.
+- Tensor-authored geometry is never implicitly moved to the requested device.
+  Place authored tensors explicitly before construction; conflicting devices
+  fail loudly.
+- CUDA-authored meshes do not run host topology diagnostics or build a host BVH.
+  `fill_mode="auto"` therefore requires an explicit topology decision before
+  an SDF query.
+- `Material` is removed. `PhysicalMaterial` is the only public name for the
+  material contract; the two were aliases of one class. Replace
+  `from witwin.core import Material` with
+  `from witwin.core import PhysicalMaterial`.
+- `Structure` and `MaterialAssignment` now live in `witwin.core.structure`
+  rather than `witwin.core.material`, which keeps only material specifications.
+  Both remain exported from `witwin.core`, so package-level imports are
+  unaffected.
+- Continuous physical quantities are annotated `ScalarLike`
+  (`float | torch.Tensor`) instead of `Any`. `ScalarLike` and `ComplexLike` are
+  exported from `witwin.core`. This is a typing change only; the accepted
+  runtime values are unchanged.
+- `witwin.core.identity` documents its two allocation modes. Use
+  `reserve_*_id(value)` whenever identities must be reproducible across
+  processes; `new_*_id()` draws from a process-global counter and is
+  order-dependent.
+
+## Related Solvers
+
+- [WiTwin Maxwell](https://github.com/witwin-ai/witwin-maxwell)
+- [WiTwin Radar](https://github.com/witwin-ai/witwin-radar)
+
+## Developer
+
+<a href="http://xingyuchen.me/">
+  <img src="https://github.com/Asixa.png" alt="Xingyu Chen" width="48" height="48" style="border-radius:50%;">
+</a>
+
+[Xingyu Chen](http://xingyuchen.me/)

witwin-0.4.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "witwin"
+version = "0.4.0"
+description = "Witwin shared logical-world, geometry, material, and dynamics contracts"
+readme = "README.md"
+requires-python = ">=3.10,<3.15"
+license = "MIT"
+
+dependencies = [
+    "numpy>=1.24",
+    "torch>=2.10",
+]
+
+[project.optional-dependencies]
+maxwell = ["witwin-maxwell>=0.2,<0.3"]
+radar   = ["witwin-radar>=0.3,<0.4"]
+genesis = ["witwin-genesis>=0.1,<0.2"]
+all     = [
+    "witwin-maxwell>=0.2,<0.3",
+    "witwin-radar>=0.3,<0.4",
+    "witwin-genesis>=0.1,<0.2",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["witwin"]