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

{witwin_maxwell-0.3.0 → witwin_maxwell-0.4.0}/.github/workflows/publish-witwin-maxwell.yml

@@ -5,14 +5,13 @@ on:
     branches:
       - master
       - "codex/**"
+    tags:
+      - "witwin-maxwell-v*"
   pull_request:
-  release:
-    types: [published]
   workflow_dispatch:
 
 jobs:
   validate_release:
-    if: github.event_name != 'release' || (startsWith(github.event.release.tag_name, 'witwin-maxwell-v') && !github.event.release.prerelease)
     name: Validate release
     runs-on: ubuntu-latest
     outputs:
@@ -41,11 +40,11 @@ jobs:
           fi
 
       - name: Validate release tag and package version
-        if: github.event_name == 'release'
+        if: startsWith(github.ref, 'refs/tags/witwin-maxwell-v')
         shell: bash
         env:
           PACKAGE_DIR: ${{ steps.package_dir.outputs.path }}
-          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          RELEASE_TAG: ${{ github.ref_name }}
         run: |
           python - <<'PY'
           import os
@@ -112,6 +111,7 @@ jobs:
           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"
@@ -139,6 +139,7 @@ jobs:
           "CUDA_BIN_PATH=$cudaRoot" >> $env:GITHUB_ENV
 
       - name: Show toolchain
+        if: runner.os == 'Windows'
         shell: bash
         run: |
           python --version
@@ -152,16 +153,62 @@ jobs:
           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.9;9.0;10.0;10.1;12.0+PTX"
+          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 }}
@@ -171,33 +218,13 @@ jobs:
             "$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: Repair Linux wheel platform tag
-        if: runner.os == 'Linux'
-        shell: bash
-        env:
-          PACKAGE_DIR: ${{ needs.validate_release.outputs.package_dir }}
-        run: |
-          python -m pip install auditwheel patchelf
-          mkdir -p "$PACKAGE_DIR"/wheelhouse
-          for whl in "$PACKAGE_DIR"/dist/*-linux_x86_64.whl; do
-            python -m auditwheel repair "$whl" \
-              --plat manylinux_2_35_x86_64 \
-              --wheel-dir "$PACKAGE_DIR"/wheelhouse \
-              --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
-          done
-          rm -f "$PACKAGE_DIR"/dist/*-linux_x86_64.whl
-          mv "$PACKAGE_DIR"/wheelhouse/*.whl "$PACKAGE_DIR"/dist/
-          ls -l "$PACKAGE_DIR"/dist
-
       - name: Smoke install prebuilt wheel
         shell: bash
         env:
@@ -263,6 +290,7 @@ jobs:
           - {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
@@ -349,7 +377,7 @@ jobs:
 
   publish:
     name: Publish to PyPI
-    if: github.event_name == 'release'
+    if: startsWith(github.ref, 'refs/tags/witwin-maxwell-v')
     needs:
       - build_cuda_wheels
       - test_torch_compatibility
@@ -381,3 +409,42 @@ jobs:
         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.3.0 → witwin_maxwell-0.4.0}/.gitignore

@@ -10,6 +10,7 @@ __pycache__/
 # Distribution / packaging
 .Python
 build/
+.build/
 develop-eggs/
 dist/
 downloads/
@@ -231,6 +232,14 @@ __marimo__/
 
 # Repository-local development content and build artifacts
 .bench_tmp/
-docs/dev/
+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.

{witwin_maxwell-0.3.0 → witwin_maxwell-0.4.0}/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable user-visible changes to WiTwin Maxwell are documented here. The proj
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-23
+
+### Added
+
+- RF port, network, antenna, phased-array, thin-wire, electrostatic, capacitance, SAR, exposure, ESD, dielectric-breakdown, gyromagnetic, and generalized surface-impedance workflows.
+- Distributed forward and adjoint execution, including CPML-trainable reverse paths and deterministic multi-device scene-gradient aggregation.
+
+### Changed
+
+- Moved material sampling to native Yee-component locations, improving the geometry validation cluster while changing geometry-resolved numerical baselines.
+- Published one PyTorch Stable ABI CUDA binary per platform for PyTorch 2.10 and newer, load-tested through PyTorch 2.13 and CPython 3.10-3.14.
+- Built Linux wheels against `manylinux_2_28`; Linux and Windows CUDA fat binaries include native SM87 SASS.
+- Made version tags drive the gated package publication and release-artifact workflow.
+
+### Fixed
+
+- Closed release-blocking CUDA graph, distributed checkpoint, conformal PEC, observer staggering, near-to-far quadrature, modal selection, and surface-impedance correctness gaps.
+
+Complete capability boundaries, validation evidence, behavior changes, and known limitations are documented in the [0.4.0 release notes](docs/reference/release-notes-0.4.0.md).
+
 ## [0.3.0] - 2026-07-13
 
 ### Added
@@ -46,6 +66,7 @@ Detailed numerical conventions, pitfalls, final comparison values, and intention
 
 - Previous public release.
 
-[Unreleased]: https://github.com/witwin-ai/witwin-maxwell/compare/witwin-maxwell-v0.3.0...HEAD
+[Unreleased]: https://github.com/witwin-ai/witwin-maxwell/compare/witwin-maxwell-v0.4.0...HEAD
+[0.4.0]: https://github.com/witwin-ai/witwin-maxwell/compare/witwin-maxwell-v0.3.0...witwin-maxwell-v0.4.0
 [0.3.0]: https://github.com/witwin-ai/witwin-maxwell/compare/witwin-maxwell-v0.2.0...witwin-maxwell-v0.3.0
 [0.2.0]: https://github.com/witwin-ai/witwin-maxwell/releases/tag/witwin-maxwell-v0.2.0

witwin_maxwell-0.4.0/CLAUDE.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.