witwin-maxwell 0.2.0__tar.gz → 0.4.0__tar.gz

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

@@ -0,0 +1,450 @@
+name: Build and publish witwin-maxwell
+
+on:
+  push:
+    branches:
+      - master
+      - "codex/**"
+    tags:
+      - "witwin-maxwell-v*"
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  validate_release:
+    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 maxwell/pyproject.toml ]; then
+            echo "path=maxwell" >> "$GITHUB_OUTPUT"
+          else
+            echo "Unable to find pyproject.toml for the witwin-maxwell package." >&2
+            exit 1
+          fi
+
+      - name: Validate release tag and package version
+        if: startsWith(github.ref, 'refs/tags/witwin-maxwell-v')
+        shell: bash
+        env:
+          PACKAGE_DIR: ${{ steps.package_dir.outputs.path }}
+          RELEASE_TAG: ${{ github.ref_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-maxwell-v(?P<version>[0-9A-Za-z.+_-]+)", tag)
+          if match is None:
+              print(f"Release tag '{tag}' must match 'witwin-maxwell-v<version>'.", file=sys.stderr)
+              raise SystemExit(1)
+
+          expected_version = match.group("version")
+          pyproject_path = Path(os.environ["PACKAGE_DIR"]) / "pyproject.toml"
+          data = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+
+          project = data["project"]
+          package_name = project["name"]
+          package_version = project["version"]
+
+          if package_name != "witwin-maxwell":
+              print(f"Expected package name 'witwin-maxwell', found '{package_name}'.", file=sys.stderr)
+              raise SystemExit(1)
+
+          if package_version != expected_version:
+              print(
+                  f"Release tag version '{expected_version}' does not match pyproject version '{package_version}'.",
+                  file=sys.stderr,
+              )
+              raise SystemExit(1)
+
+          print(f"Validated {package_name} {package_version} from {pyproject_path}.")
+          PY
+
+  build_cuda_wheels:
+    name: Build stable CUDA wheel / ${{ matrix.os }}
+    needs: validate_release
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, windows-2022]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Free disk space (Linux)
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          echo "Disk before cleanup:"; df -h /
+          sudo rm -rf /usr/share/dotnet /opt/ghc /usr/local/lib/android \
+            /usr/local/share/boost /opt/hostedtoolcache/CodeQL \
+            /usr/local/share/powershell /usr/share/swift || true
+          sudo docker image prune --all --force || true
+          echo "Disk after cleanup:"; df -h /
+
+      - name: Install CUDA Toolkit
+        if: runner.os == 'Windows'
+        uses: Jimver/cuda-toolkit@v0.2.35
+        with:
+          cuda: "12.8.1"
+          method: local
+          log-file-suffix: "${{ runner.os }}-stable-abi"
+
+      - name: Set up MSVC
+        if: runner.os == 'Windows'
+        uses: ilammy/msvc-dev-cmd@v1
+        with:
+          arch: x64
+
+      - name: Export Windows CUDA_HOME
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $cudaRoot = $env:CUDA_PATH
+          if (-not $cudaRoot) {
+            $nvcc = (Get-Command nvcc -ErrorAction Stop).Source
+            $cudaRoot = Split-Path (Split-Path $nvcc -Parent) -Parent
+          }
+          "CUDA_HOME=$cudaRoot" >> $env:GITHUB_ENV
+          "CUDA_PATH=$cudaRoot" >> $env:GITHUB_ENV
+          "CUDA_ROOT=$cudaRoot" >> $env:GITHUB_ENV
+          "CUDA_BIN_PATH=$cudaRoot" >> $env:GITHUB_ENV
+
+      - name: Show toolchain
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          python --version
+          nvcc --version
+          command -v cl || true
+
+      - name: Install CUDA extension build dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel ninja numpy
+          python -m pip install torch==2.10.0 --index-url https://download.pytorch.org/whl/cu128
+          python -m pip install build
+
+      - name: Build packaged stable FDTD CUDA extension
+        if: runner.os == 'Windows'
+        shell: bash
+        env:
+          MAX_JOBS: "2"
+          WITWIN_CUDA_GENCODE_ARCHES: "7.0;7.5;8.0;8.6;8.7;8.9;9.0;10.0;10.1;12.0+PTX"
+          PACKAGE_DIR: ${{ needs.validate_release.outputs.package_dir }}
+          WITWIN_MAXWELL_FDTD_CUDA_BUILD_DIR: ${{ runner.temp }}/witwin_maxwell_fdtd_cuda/stable_abi_v1
+        run: |
+          python "$PACKAGE_DIR"/scripts/build_fdtd_cuda_prebuilt.py --verbose
+
+      - name: Build manylinux_2_28 wheel
+        if: runner.os == 'Linux'
+        uses: pypa/cibuildwheel@v3.3.0
+        env:
+          CIBW_BUILD: cp310-manylinux_x86_64
+          CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
+          CIBW_BEFORE_ALL_LINUX: >-
+            dnf install -y dnf-plugins-core gcc-toolset-12 &&
+            rpm --import https://developer.download.nvidia.com/compute/cuda/repos/rhel8/x86_64/D42D0685.pub &&
+            dnf config-manager --add-repo https://developer.download.nvidia.com/compute/cuda/repos/rhel8/x86_64/cuda-rhel8.repo &&
+            dnf clean expire-cache &&
+            dnf install -y cuda-toolkit-12-8 &&
+            ln -sfn /usr/local/cuda-12.8 /usr/local/cuda &&
+            /usr/local/cuda/bin/nvcc --version
+          CIBW_ENVIRONMENT_LINUX: >-
+            CUDA_HOME=/usr/local/cuda
+            CUDA_PATH=/usr/local/cuda
+            CUDA_ROOT=/usr/local/cuda
+            CUDA_BIN_PATH=/usr/local/cuda
+            CUDACXX=/usr/local/cuda/bin/nvcc
+            CUDAHOSTCXX=/opt/rh/gcc-toolset-12/root/usr/bin/g++
+            PATH=/usr/local/cuda/bin:$PATH
+            LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
+            MAX_JOBS=2
+            WITWIN_CUDA_GENCODE_ARCHES="7.0;7.5;8.0;8.6;8.7;8.9;9.0;10.0;10.1;12.0+PTX"
+          CIBW_BEFORE_BUILD_LINUX: >-
+            pip install --upgrade pip setuptools wheel ninja numpy build &&
+            pip install torch==2.10.0 --index-url https://download.pytorch.org/whl/cu128 &&
+            python {project}/scripts/build_fdtd_cuda_prebuilt.py --verbose &&
+            python {project}/scripts/verify_cuda_binary_arches.py
+            --stem witwin_maxwell_fdtd_cuda
+            {project}/witwin/maxwell/fdtd/cuda/prebuilt
+          CIBW_REPAIR_WHEEL_COMMAND_LINUX: >-
+            auditwheel repair --plat manylinux_2_28_x86_64
+            --wheel-dir {dest_dir}
+            --exclude libc10.so --exclude libc10_cuda.so
+            --exclude libtorch.so --exclude libtorch_cpu.so
+            --exclude libtorch_cuda.so --exclude libtorch_python.so
+            --exclude libcudart.so.12 --exclude libcuda.so.1
+            {wheel}
+        with:
+          package-dir: ${{ needs.validate_release.outputs.package_dir }}
+          output-dir: ${{ needs.validate_release.outputs.package_dir }}/dist
+
+      - name: Verify compiled CUDA architectures
+        if: runner.os == 'Windows'
+        shell: bash
+        env:
+          PACKAGE_DIR: ${{ needs.validate_release.outputs.package_dir }}
+        run: |
+          python "$PACKAGE_DIR"/scripts/verify_cuda_binary_arches.py \
+            --stem witwin_maxwell_fdtd_cuda \
+            "$PACKAGE_DIR"/witwin/maxwell/fdtd/cuda/prebuilt
+
+      - name: Build platform wheel
+        if: runner.os == 'Windows'
+        shell: bash
+        env:
+          PACKAGE_DIR: ${{ needs.validate_release.outputs.package_dir }}
+        run: |
+          python -m build --wheel "$PACKAGE_DIR"
+
+      - name: Smoke install prebuilt wheel
+        shell: bash
+        env:
+          PACKAGE_DIR: ${{ needs.validate_release.outputs.package_dir }}
+          WITWIN_MAXWELL_FDTD_CUDA_PREBUILT: "1"
+          WITWIN_MAXWELL_FDTD_CUDA_BUILD_DIR: ${{ runner.temp }}/missing_prebuilt_build_dir
+        run: |
+          python -m pip uninstall -y witwin-maxwell || true
+          python -m pip install --no-deps "$PACKAGE_DIR"/dist/*.whl
+          python - <<'PY'
+          import importlib.util
+          import os
+          import site
+          import zipfile
+          from pathlib import Path
+
+          wheel = next((Path(os.environ["PACKAGE_DIR"]) / "dist").glob("*.whl"))
+          names = zipfile.ZipFile(wheel).namelist()
+          native = [name for name in names if "witwin_maxwell_fdtd_cuda" in name and name.endswith((".so", ".pyd"))]
+          assert len(native) == 1, native
+          assert "/prebuilt/" in f"/{native[0]}"
+          assert "torch_" not in native[0]
+
+          candidates = []
+          for root in site.getsitepackages() + [site.getusersitepackages()]:
+              candidates.append(Path(root) / "witwin" / "maxwell" / "fdtd" / "cuda" / "build.py")
+          build_path = next((path for path in candidates if path.exists()), None)
+          assert build_path is not None, f"installed build.py not found in {candidates}"
+
+          spec = importlib.util.spec_from_file_location("witwin_maxwell_fdtd_cuda_build", build_path)
+          module = importlib.util.module_from_spec(spec)
+          spec.loader.exec_module(module)
+
+          path = module.prebuilt_extension_path()
+          assert path.exists(), f"missing packaged prebuilt extension: {path}"
+          assert path.parent.name == "prebuilt"
+          extension = module.build_extension()
+          print(f"Loaded packaged FDTD CUDA extension from {extension.__file__}")
+          PY
+
+      - name: Upload wheel artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheel-${{ matrix.os }}
+          path: ${{ needs.validate_release.outputs.package_dir }}/dist/*.whl
+          if-no-files-found: error
+
+  test_torch_compatibility:
+    name: Stable ABI / ${{ matrix.os }} / py${{ matrix.compatibility.python_version }} / torch${{ matrix.compatibility.torch_version }}
+    needs:
+      - validate_release
+      - build_cuda_wheels
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, windows-2022]
+        compatibility:
+          - {python_version: "3.10", torch_version: "2.10.0", cuda_index: "cu128"}
+          - {python_version: "3.11", torch_version: "2.10.0", cuda_index: "cu128"}
+          - {python_version: "3.12", torch_version: "2.10.0", cuda_index: "cu128"}
+          - {python_version: "3.13", torch_version: "2.10.0", cuda_index: "cu128"}
+          - {python_version: "3.14", torch_version: "2.10.0", cuda_index: "cu128"}
+          - {python_version: "3.14", torch_version: "2.11.0", cuda_index: "cu128"}
+          - {python_version: "3.14", torch_version: "2.12.0", cuda_index: "cu126"}
+          - {python_version: "3.14", torch_version: "2.13.0", cuda_index: "cu126"}
+
+    steps:
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.compatibility.python_version }}
+
+      - name: Download stable wheel
+        uses: actions/download-artifact@v4
+        with:
+          name: wheel-${{ matrix.os }}
+          path: dist
+
+      - name: Install compatibility environment
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --no-cache-dir "torch==${{ matrix.compatibility.torch_version }}" \
+            --index-url "https://download.pytorch.org/whl/${{ matrix.compatibility.cuda_index }}"
+          python -m pip install --no-deps dist/*.whl
+
+      - name: Load the same stable binary
+        shell: bash
+        env:
+          EXPECTED_TORCH: ${{ matrix.compatibility.torch_version }}
+          WITWIN_MAXWELL_FDTD_CUDA_PREBUILT: "1"
+          WITWIN_MAXWELL_FDTD_CUDA_BUILD_DIR: ${{ runner.temp }}/must-not-jit-build
+        run: |
+          python - <<'PY'
+          import importlib.util
+          import os
+          import site
+          from pathlib import Path
+
+          import torch
+
+          assert torch.__version__.split("+", 1)[0] == os.environ["EXPECTED_TORCH"]
+          candidates = [
+              Path(root) / "witwin" / "maxwell" / "fdtd" / "cuda" / "build.py"
+              for root in site.getsitepackages() + [site.getusersitepackages()]
+          ]
+          build_path = next((path for path in candidates if path.exists()), None)
+          assert build_path is not None, candidates
+          spec = importlib.util.spec_from_file_location("witwin_maxwell_fdtd_cuda_build", build_path)
+          module = importlib.util.module_from_spec(spec)
+          spec.loader.exec_module(module)
+
+          native_path = module.prebuilt_extension_path()
+          assert native_path.exists(), native_path
+          extension = module.build_extension()
+          assert Path(extension.__file__).resolve() == native_path.resolve()
+          assert extension.update_magnetic_hx_standard is not None
+          print(f"Loaded {native_path.name} with torch {torch.__version__} on Python {os.sys.version.split()[0]}")
+          PY
+
+  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 distributions
+        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: 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: startsWith(github.ref, 'refs/tags/witwin-maxwell-v')
+    needs:
+      - build_cuda_wheels
+      - test_torch_compatibility
+      - build_sdist
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/witwin-maxwell/
+
+    steps:
+      - name: Download wheel artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: wheel-*
+          path: dist
+          merge-multiple: true
+
+      - 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
+
+  create_release:
+    name: Create release
+    if: startsWith(github.ref, 'refs/tags/witwin-maxwell-v')
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Download wheel artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: wheel-*
+          path: dist
+          merge-multiple: true
+
+      - name: Download source distribution artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+      - name: Create release with distribution artifacts
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version="${GITHUB_REF_NAME#witwin-maxwell-v}"
+          notes="docs/reference/release-notes-${version}.md"
+          test -f "$notes"
+          gh release create "$GITHUB_REF_NAME" \
+            --verify-tag \
+            --title "witwin-maxwell ${version}" \
+            --notes-file "$notes" \
+            dist/*

{witwin_maxwell-0.2.0 → witwin_maxwell-0.4.0}/.gitignore

@@ -10,6 +10,7 @@ __pycache__/
 # Distribution / packaging
 .Python
 build/
+.build/
 develop-eggs/
 dist/
 downloads/
@@ -54,6 +55,7 @@ coverage.xml
 *.py.cover
 .hypothesis/
 .pytest_cache/
+.pytest_tmp/
 cover/
 
 # Translations
@@ -171,12 +173,8 @@ venv.bak/
 
 # mkdocs documentation
 /site
-.slangtorch_cache/
-.*_runtime_*.slang
 witwin/maxwell/fdtd/cuda/prebuilt/*.pyd
 witwin/maxwell/fdtd/cuda/prebuilt/*.so
-.fdtd_runtime_*.slang
-.adjoint_kernels_runtime_*.slang
 *.png
 *.npy
 *.npz
@@ -231,3 +229,17 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+# Repository-local development content and build artifacts
+.bench_tmp/
+docs/
+assets/
+benchmark/
+
+# Repository-local agent and test scratch directories
+.codex_tmp/
+.codex-tmp/
+.test-tmp/
+.tmp/
+experiments/
+.worktrees/

witwin_maxwell-0.4.0/AGENTS.md

@@ -0,0 +1,161 @@
+# Repository Agent Guide
+
+This document defines the working rules for coding agents in this repository. Keep `AGENTS.md` and `CLAUDE.md` identical.
+
+## Core Rules
+
+- Use the `maxwell` conda environment for all Python commands, tests, and scripts.
+- Keep the codebase clean. Do not preserve legacy code, compatibility shims, or backward-support paths unless explicitly requested.
+- Write all code comments and commit messages in English.
+- Never add AI or agent attribution to git history. Commit messages must not contain
+  `Co-Authored-By` trailers naming an assistant, `Claude-Session` or similar session
+  links, or "generated with" banners, and the author/committer identity is always the
+  human owner. This applies to commits, tags, PR titles and PR bodies.
+- Keep third-party commercial product, service, and solver names out of commit messages, branch names, PR titles, general development documents, comments, and feature descriptions. Describe the behavior with neutral terms such as `external reference solver`, `reference backend`, or `third-party adapter` so commercial brands do not spread through the repository or GitHub history.
+- Use an exact commercial product name only where technically required for an interoperability API, adapter module, executable command, dependency declaration, legal attribution, or a narrowly scoped adapter test/document. Do not repeat that name in unrelated implementation, validation, or numerical-method changes unless the user explicitly requests it.
+- Maintain `FEATURE_LIST.md` as the user-facing feature inventory. Every new user-visible feature, public API capability, or meaningful workflow addition must update that file in the same change.
+- Store active development documents by type under `docs/plans/`, `docs/memory/`, `docs/assessments/`, and `docs/reference/`. Keep solver and feature areas together in each type directory; use descriptive filenames instead of extra `fdtd`, `fdfd`, or similar directory layers. Move completed or superseded development documents to the matching type under `docs/archive/`. Keep `FEATURE_LIST.md` at the repository root as the user-facing feature inventory.
+- Prioritize correctness and efficiency over convenience.
+- Core computation is GPU-first. Minimize GPU-CPU transfers and do not introduce new CPU fallback paths unless explicitly requested.
+- PyTorch-native integration is a hard requirement. New differentiable or optimization-facing APIs must be designed as native PyTorch workflows, not thin wrappers around non-PyTorch side paths.
+- The stable public architecture is `Scene + Simulation + Result`. New user-facing code must follow this model.
+- `Scene` must support both direct declarative construction (`mw.Scene(...)`) and a PyTorch-native module-style scene definition that ultimately materializes into the same public `Scene` object model.
+- Do not reintroduce old public convenience paths such as `Scene.set_*`, `Scene.with_*`, `mw.FDFD`, or `mw.FDTD`.
+- Preserve the compile-layer naming convention: scene-facing helpers use `compile_*` names such as `Scene.compile_materials(...)`, `Scene.compile_relative_materials(...)`, and `Scene.compile_material_tensors(...)`.
+- Shared core geometry constructors default to `device=None`; `Scene(...)` owns device placement and defaults to CUDA.
+
+## Project Overview
+
+This repository is a PyTorch-native differentiable full-wave electromagnetic simulation framework for Maxwell's equations with two internal solver runtimes:
+
+- `FDFD`: frequency-domain finite-difference solver using sparse linear algebra.
+- `FDTD`: time-domain Yee-grid solver with native CUDA kernels, CPML support, and differentiable adjoint workflows.
+
+The public API is declarative:
+
+- `Scene`: physical problem definition
+- `Simulation`: execution configuration and backend selection
+- `Result`: fields, monitors, metadata, plotting, and persistence
+
+For differentiable and optimization workflows, the public API must also remain PyTorch-native:
+
+- trainable scene definitions may be implemented as `torch.nn.Module` via `SceneModule`
+- module-style scenes must compile or materialize to the same `Scene` public contract
+- solver entry remains `Scene -> Simulation -> Result`, even when the `Scene` is produced by a PyTorch module
+
+Supporting first-class Maxwell scene objects include:
+
+- `Domain`
+- `GridSpec`
+- `BoundarySpec`
+- `BoundaryKind`
+- `MaterialRegion`
+- `Structure`
+- `Material`
+- `PointDipole`
+- `PlaneWave`
+- `GaussianBeam`
+- `ModeSource`
+- `PointMonitor`
+- `PlaneMonitor`
+- `FluxMonitor`
+- `ModeMonitor`
+- `ModePort`
+
+The current codebase is organized as a Python package under `witwin/maxwell/`, with tests under `tests/`. Shared geometry and structure primitives are re-exported through `witwin.maxwell` but originate from the shared `witwin.core` dependency.
+
+## Repository Layout
+
+- `witwin/maxwell/__init__.py`: public package exports.
+- `witwin/maxwell/scene.py`: declarative scene model, domain/grid/boundary handling, `MaterialRegion`, and `SceneModule`.
+- `witwin/maxwell/media.py`: public Maxwell material models, dispersion poles, and diagonal anisotropy descriptors.
+- `witwin/maxwell/sources.py`: public source definitions and source-time waveforms.
+- `witwin/maxwell/monitors.py`: point, plane, flux, and modal monitors.
+- `witwin/maxwell/ports.py`: first-class modal port definitions.
+- `witwin/maxwell/simulation.py`: public simulation entrypoint, runtime preparation, and backend dispatch.
+- `witwin/maxwell/result.py`: unified simulation result container.
+- `witwin/maxwell/compiler/`: scene compilers for materials, sources, ports, and monitors.
+- `witwin/maxwell/fdfd/`: internal FDFD runtime and postprocessing helpers.
+- `witwin/maxwell/fdtd/`: internal FDTD runtime, CPML logic, source injection, observers, and adjoint support.
+- `witwin/maxwell/postprocess/`: near/far-field, directivity, RCS, scattering-parameter, and modal postprocessing.
+- `witwin/maxwell/adapters/`: interoperability adapters such as Tidy3D export.
+- `witwin/maxwell/visualization/`: shared visualization utilities.
+- `docs/plans/`: active implementation plans and functional roadmaps.
+- `docs/memory/`: current implementation notes and durable engineering context.
+- `docs/assessments/`: current audits and capability assessments.
+- `docs/reference/`: maintained technical reference material.
+- `docs/archive/`: completed or superseded plans, assessments, design records, and status snapshots.
+- `tests/`: pytest-based coverage for public API behavior, numerics, gradients, and validation workflows.
+
+## Working Expectations
+
+- Prefer package-style imports from `witwin.maxwell`, typically `import witwin.maxwell as mw`.
+- New public examples, tests, and scripts should look like `Scene -> Simulation -> Result`, not direct backend construction.
+- Build scenes with `Domain`, `GridSpec`, `BoundarySpec`, `Structure`, `Material`, source objects, monitor objects, `ModePort`, and `MaterialRegion` as appropriate.
+- Use the declarative `BoundaryKind` / `BoundarySpec` vocabulary consistently; do not introduce new raw boundary-mode strings outside validated APIs.
+- Use `Scene.add_structure(...)`, `Scene.add_source(...)`, `Scene.add_monitor(...)`, `Scene.add_port(...)`, and `Scene.add_material_region(...)` for scene assembly.
+- For PyTorch-native scene definitions, prefer `SceneModule` subclasses that expose `to_scene()` and return a standard `Scene`; do not create a second incompatible simulation entrypoint.
+- When behavior changes in a way a user would notice, update `FEATURE_LIST.md` to keep the documented feature inventory current.
+- If backend internals must be inspected, prefer `Simulation.prepare()` and then inspect `prepared.solver` rather than importing or constructing backend classes through the public path.
+- Keep new implementations aligned with the current declarative 3D API and compiler/runtime split.
+- If a design choice would add extra abstraction, data copies, or compatibility branches, prefer the simpler and faster path.
+- When changing numerics, preserve Yee-grid consistency, PML behavior, Bloch/periodic boundary semantics, and GPU execution flow.
+- Avoid adding duplicate implementations in parallel files. Update the primary module instead.
+
+## Running Code
+
+Activate the environment first:
+
+```bash
+conda activate maxwell
+```
+
+Common commands:
+
+```bash
+python -m pytest tests
+python -m pytest tests/api/public/test_public_api.py tests/api/public/test_simulation_smoke.py
+python -m pytest tests/core/scene/test_scene.py tests/materials/compiler/test_material_compiler.py
+python -m pytest tests/boundaries/cpml/test_fdtd_cpml.py tests/monitors/observers/test_fdtd_observers.py
+python -m pytest tests/gradients/test_fdtd_adjoint_bridge.py
+python -m pytest tests/validation/benchmark/test_benchmark_system.py
+python -m benchmark
+python -m benchmark dipole_vacuum
+python -m benchmark planewave_vacuum
+```
+
+Benchmark / validation workflow:
+
+- Use `python -m benchmark` as the unified Maxwell-vs-Tidy3D validation entrypoint.
+- Scenario definitions live under `benchmark/scenes/`, grouped by family under directories such as `dipole/` and `planewave/`.
+- Tidy3D reference caches are stored under `benchmark/cache/`.
+- Generated comparison plots are stored under `benchmark/plots/`.
+- Benchmark metrics are aggregated into `benchmark/RESULTS.md` and should be updated by rerunning the benchmark command after benchmark-related changes.
+
+If you add or modify Python code, prefer validating with targeted pytest coverage first, then broader tests if needed.
+
+## Windows / Codex Execution Notes
+
+- In this environment, `rg` may exist but fail with `Access is denied`. If that happens, switch immediately to PowerShell-native search with `Get-ChildItem` + `Select-String` instead of retrying `rg`.
+- `conda run -n maxwell` may fail to pass stdin through to `python -` reliably in this Codex/PowerShell setup. Prefer `conda run -n maxwell python -c ...` for short snippets, or invoke the environment interpreter directly with `C:\Users\Asixa\miniconda3\envs\maxwell\python.exe`.
+- Windows command-line length limits are easy to hit with `python -c` and large inline scripts. For long scripts, pass the code through an environment variable such as `PYCODE` and execute `python -c "import os; exec(os.environ['PYCODE'])"`, or use the environment interpreter with stdin if that path is reliable.
+- Large single-shot `apply_patch` updates can also hit Windows path/command length limits. If a full-file replacement fails for size reasons, rewrite it in smaller patch chunks instead of retrying the same oversized patch.
+- When checking whether `AGENTS.md` and `CLAUDE.md` match, do not use bare `fc` in PowerShell because it resolves to `Format-Custom`. Call `fc.exe` explicitly if you want the file-compare tool.
+
+## Dependencies
+
+Primary dependencies include:
+
+- PyTorch
+- NumPy
+- SciPy
+- Matplotlib
+- tqdm
+- CuPy
+- witwin
+
+Optional dependencies:
+
+- `tidy3d` for adapter export and benchmark cross-validation workflows
+
+An NVIDIA GPU with CUDA is expected for core solver workflows.