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

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

@@ -233,7 +233,7 @@ jobs:
           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 -m pip install "$PACKAGE_DIR"/dist/*.whl
           python - <<'PY'
           import importlib.util
           import os
@@ -263,6 +263,17 @@ jobs:
           assert path.parent.name == "prebuilt"
           extension = module.build_extension()
           print(f"Loaded packaged FDTD CUDA extension from {extension.__file__}")
+
+          # Import outside the checkout so missing runtime dependencies cannot
+          # be hidden by source-tree imports or the build-only ABI smoke test.
+          import subprocess
+          import tempfile
+          subprocess.run([
+              os.sys.executable, "-c",
+              "import witwin.maxwell as mw; from importlib.metadata import version; "
+              "assert mw.BatchExecution and mw.Scene and mw.Simulation; "
+              "print('Installed package:', version('witwin-maxwell'))",
+          ], cwd=tempfile.gettempdir(), check=True)
           PY
 
       - name: Upload wheel artifact
@@ -343,6 +354,12 @@ jobs:
           extension = module.build_extension()
           assert Path(extension.__file__).resolve() == native_path.resolve()
           assert extension.update_magnetic_hx_standard is not None
+          import ctypes
+          library = ctypes.CDLL(str(native_path))
+          for name in ("mw_batch_budget_create", "mw_batch_budget_exchange",
+                       "mw_batch_budget_bytes", "mw_batch_budget_close",
+                       "mw_batch_malloc", "mw_batch_free"):
+              assert getattr(library, name) is not None, name
           print(f"Loaded {native_path.name} with torch {torch.__version__} on Python {os.sys.version.split()[0]}")
           PY
 

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

@@ -241,5 +241,15 @@ benchmark/
 .codex-tmp/
 .test-tmp/
 .tmp/
-experiments/
+# Experiment outputs are enormous (90+ GB of generated datasets) and stay local. The generator
+# *source* is not an output: it defines the dataset contract that downstream consumers depend on,
+# so it is tracked explicitly. Add a file here rather than relaxing the rule -- `experiments/*`
+# keeps every other directory excluded while still letting git descend far enough for these
+# negations to apply.
+experiments/*
+!experiments/fdtd_data_generator/
+experiments/fdtd_data_generator/*
+!experiments/fdtd_data_generator/generate.py
+!experiments/fdtd_data_generator/README.md
+!experiments/fdtd_data_generator/REPORT.md
 .worktrees/

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

@@ -4,6 +4,33 @@ All notable user-visible changes to WiTwin Maxwell are documented here. The proj
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-09-08
+
+### Added
+
+- Experimental `Simulation.batch(...)` execution with reusable capacity-limited CUDA slots, batched field/CPML/source/observer updates, and ordinary owned `Result` objects.
+- Local material compilation reuse, automatic resident capacity, private per-device CUDA allocation budgets, multi-GPU and dual-slot scheduling, and opt-in measured throughput tuning.
+- PyTorch-native Batch checkpoint adjoints for supported density, dielectric geometry, and named source-scale inputs, including delayed backward after slot reuse or close.
+- Reproducible Batch performance, memory, material-compilation, and device-scaling audits with numerical controls and process-contention records.
+
+### Fixed
+
+- Material-aware time-step stability, source timing, complex CPML and Mur boundary histories, and capture/resume state consistency in FDTD.
+- Batch parameter cache identity, iterator ownership, result scene snapshots, selected electric spectra, and redundant spectral allocations in retained adjoint state.
+- Automatic worker capacity distribution and isolation of tuning RNG, module state, and cross-device tensor copies.
+- Corrected the base dependency range to `witwin>=0.4,<0.5`, matching the published `PhysicalMaterial` contract instead of an unavailable version range.
+- Preserved local compilation reuse when declared design replacements acquire new base-package structure/material identity tokens.
+- Declared plotting/progress/notebook display import dependencies and extended release checks to installed-package imports and native Batch allocator exports.
+
+### Limitations
+
+- Batch remains experimental with a narrower capability set than ordinary FDTD. Fused batch reverse kernels, exact preplanning of all retained outputs, and exclusive multi-GPU throughput acceptance remain pending.
+- See [0.5.1 release notes](docs/reference/release-notes-0.5.1.md) for validation evidence and the supported execution contract.
+
+## [0.5.0] - Unpublished
+
+- The version tag built CUDA wheels but failed the installed-package import gate because `IPython` was undeclared. No distributions were uploaded to PyPI.
+
 ## [0.4.0] - 2026-07-23
 
 ### Added
@@ -66,7 +93,8 @@ Detailed numerical conventions, pitfalls, final comparison values, and intention
 
 - Previous public release.
 
-[Unreleased]: https://github.com/witwin-ai/witwin-maxwell/compare/witwin-maxwell-v0.4.0...HEAD
+[Unreleased]: https://github.com/witwin-ai/witwin-maxwell/compare/witwin-maxwell-v0.5.1...HEAD
+[0.5.1]: https://github.com/witwin-ai/witwin-maxwell/compare/witwin-maxwell-v0.4.0...witwin-maxwell-v0.5.1
 [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 → witwin_maxwell-0.5.1}/FEATURE_LIST.md

@@ -2,6 +2,41 @@
 
 This document tracks the current user-visible capabilities of the `maxwell` package.
 
+Release 0.5.1 introduces the experimental Batch execution tier and FDTD correctness repairs described in [the release notes](docs/reference/release-notes-0.5.1.md). Existing ordinary-simulation capabilities retain their documented scope; Batch support is specified separately below.
+
+- Package installation requires `witwin>=0.4,<0.5` and uses its public `PhysicalMaterial` contract; the dependency range resolves against published base-package versions.
+- Release wheels declare their plotting/progress/notebook display import dependencies. Publishing validates package imports outside the checkout and the native Batch allocator symbols across the platform/ABI matrix.
+
+- Batch tuning isolates copyable `SceneModule` parameters, buffers and Python attributes per trial, preserves shared tensor storage, and starts each candidate from the same CPU/CUDA RNG state. Only the final ordinary preparation updates the caller's module state. Trial copies and scene materialization on another execution device use that device's private memory account. Arbitrary external side effects and allocations on producer devices outside the execution policy are outside this isolation/accounting contract.
+
+- `python -m benchmark batch --scaling-audit WORKLOAD --devices cuda:0 cuda:1 --variants N --concurrency B --update-report` interleaves complete streamed runs on each GPU and all GPUs, including CPU output readiness, and checks spectra against independent simulations. Raw artifacts retain all timing samples and competing compute-process observations. The matching two-device 1.7x gate requires numerical agreement and observed exclusive compute access; foreign processes or sampler errors prevent acceptance. Periodic sampling cannot prove complete exclusivity or exclude display activity. Idle prepared comparison modes remain resident, so this workflow does not measure isolated memory use.
+
+- Batch native checkpoint adjoints differentiate density templates, nonmagnetic, nonconductive dielectric structure geometry and named source scales, including zero/negative amplitudes, shared parameter reductions and gradients gathered from multiple devices. Native B-lane forward records independent checkpoints; reverse currently uses the existing native per-lane adjoint. Tapes retain immutable runtime snapshots and their allocation pools through delayed backward after slot reuse or close. Input version guards reject intervening tracked mutations; no_grad skips tapes, and SceneModule graphs refresh between runs and optimizer updates. Fixed time horizons and the existing native-adjoint boundary/material capability limits apply. Spectral normalization removes the unit-amplitude waveform envelope and preserves physical source amplitude. Missing permeability/conductivity/PEC-mask and material-region geometry gradient channels fail explicitly. Result solver statistics expose checkpoint counts/bytes and private-pool accounting after backward.
+
+- Batch multi-GPU and dual-slot execution supports static or throughput dispatch, bounded completed-output queues, input/completion order, cancellation and persistent reuse. Each device shares one strict allocation account across worker and output pools. GPU output gathering preserves ownership and caller-stream ordering. Coordinated host submission protects CUDA Graph capture while previously submitted device work can overlap. Scene.clone(device=...) migrates nested geometry/material tensors without mutating the source scene and preserves PyTorch gradient paths. Dual-GPU numerical correctness is tested; throughput scaling requires a dedicated measurement window.
+
+- `BatchExecution(tune=True)` measures complete streamed forward runs over finite B/Q/Graph-step candidates, with one warmup and three timed repeats. Reports include preparation cost, samples, per-device backing-memory peaks, capacity rejections, selected policy and tuning cost. The candidate set includes balanced cohort sizes and skips automatic dual slots when the device count already covers every cohort. Automatic dual slots require a successful single-slot baseline and a repeatable 5% gain; policies within 5% prefer lower memory. Trials publish no results, preserve caller RNG state and create gradient tapes without calling backward. Final execution uses a fresh context; explicit policies remain fixed, while automatic capacity retains bounded OOM reduction. The objective excludes backward and user-retained N-result storage, and tuning cost may outweigh savings for short one-shot tasks.
+
+- Batch automatic capacity calibrates a prepared lane, bounds B by compatible-group size and available worker count to leave work for each device/slot, selects a conservative B and retries capacity failures with bounded B reduction before publishing the affected cohort. Explicit byte limits use a private native CUDA allocation pool: backing segments, cached blocks, Graph pool tensors and retained GPU outputs remain charged, providing a conservative hard upper bound on Batch-owned live tensor storage without replacing the process default allocator. Reports expose actual capacity, reductions and charged/peak bytes. CUDA context/library allocations are external to this pool; segment granularity may reject a request whose logical tensor sum is smaller than the limit. The native PyTorch caching allocator is required.
+
+- Density-template Batch execution reuses one fixed material bank and samples only each changed region's conservative influence patch with global Yee coordinates, subpixel averaging and differentiation halos. Periodic axes retain their whole extent. Fixed material/grid/geometry values are checked before reuse; changed channels materialize dense runtime arrays while unchanged channels share bank storage. Local reuse currently covers fixed Box density regions with static edge-native materials; declared Box/Sphere structure movement and static material changes use conservative Box influence envelopes, while perturbation grids and trainable geometry use separate compiler paths.
+
+- Experimental Batch forward execution through `Simulation.batch(...)`, `BatchExecution`, `BatchParameters`, `BatchVariation`, `BatchOutput`, and `BatchPlanReport`. `prepare()` now returns a reusable `PreparedBatch`; `run()` returns an ordered `BatchResult` containing ordinary Results. One or more CUDA devices with one or two persistent capacity-B field slots per device support real static-material FDTD, point sources, point/plane/flux monitors, dense/slab CPML, none/periodic/PEC/PMC boundaries, incomplete cohorts, density/source-scale template updates, and repeated runs. Native E/H and CPML kernels advance all resident lanes together; source patches batch lanes using reusable GPU waveform tables, original overlap order, periodic endpoint routing and native rounding, while point/plane/flux spectra batch lanes and frequencies using GPU phase, window and source-normalization recurrences, preserving the ordinary monitor preparation and export contract. Compiled spacing, CPML profiles and equal coefficients share verified storage; differing coefficients promote to per-lane storage, density templates reuse local patches, and independent scenes with declared material regions or supported structure envelopes reuse local compilation. Monitor-only multifrequency execution does not allocate full-field DFT. Requested electric spectra allocate and accumulate only the selected Yee components; omitted components use zero-byte descriptors in the native fused kernel. Finalization and adjoint seeds preserve this selection, and Result solver stats expose batch_dft_accumulator_bytes.
+- `BatchResult.stack(selector, device=...)`, `save(directory)` and `load(directory, scenes=..., map_location=...)` preserve variant ordering and failures. `BatchItem` and context-managed `BatchResultIterator` provide demand-driven delivery, cancellation, failure records and explicit early close. Closed iterators retain their own final execution records when the prepared context is reused. Results own output storage and detached snapshots of declarative scene tensors and nested metadata, retain no live solver slot, and survive optimizer updates, repeated runs and `PreparedBatch.close()`. Adjoint frequency entries share one owned copy of each spectral bank instead of duplicating its per-frequency views. Full-field exports use canonical Result field keys, so `tensor("Ez")`, `field("E")` and frequency selection work like ordinary simulation results; gradient tapes separately retain the original inputs and version guards. Result plotting facades are created on demand so streamed GPU outputs release without waiting for cyclic garbage collection.
+- Batch execution remains an incomplete optimization tier: `batch_size="auto"` selects capacity from a prepared-lane measurement, and `graph="auto"` attempts complete timestep CUDA Graph capture. RF ports, advanced material dynamics, magnetic full-field/material export fail explicitly. Structure envelopes prove containment using a design circumsphere inside the Box envelope insphere; this conservatively supports arbitrary rotations and rejects out-of-envelope or unsupported changes. Undeclared geometry changes use full-scene compilation. Fused B-lane reverse kernels, exact all-output preplanning and measured multi-GPU throughput acceptance remain pending. Dry plans remain unresolved; run reports expose `native_pipeline_eager`, `native_pipeline_graph` or mixed execution. Input Scene topology and fixed declarations must remain unchanged; tracked trainable tensor and template parameter updates are supported. Template caches retain input tensor identities and detect version-tracked PyTorch updates; inference tensors conservatively recompile each run. Untracked external storage or `.data` writes require a new input tensor. Concurrent iterator `next()` or `close()` calls reject while `next()` is active; request cancellation and wait for it to return before closing.
+
+- Experimental batch baseline instrumentation: `python -m benchmark batch --inventory` lists three fixed workloads; `--audit WORKLOAD --device cuda:0` records single-run tensor storage ownership, prepare/completed manifests, allocator peaks and sampled driver memory under `benchmark/plots/batch/`. `--compare WORKLOAD --variants N` measures independent sequential, spawned-process and `run_many` baselines with cold startup, interleaved warm rounds, per-worker allocator peaks, sampled total device memory and per-variant complex spectrum comparisons. `--include-native` adds native Batch with resident B selected by `--concurrency`; `--native-graph off|auto|required` selects its graph policy, and warm rounds reuse its PreparedBatch. Reports preserve historical baselines in separate sections and distinguish timing-round memory (including idle sessions) from fresh isolated-memory rounds. Complete business throughput and memory acceptance remain pending.
+
+- `python -m benchmark batch --tune-audit WORKLOAD --variants N --concurrency MAX_B --devices cuda:0 cuda:1 --update-report` records all public tuning candidates, independent hot repeats, spectrum parity and the 90% measured-candidate threshold. Raw JSON includes timing scope and tuning overhead; report sections survive ordinary regeneration. Multi-device scaling acceptance requires a separate exclusive-device comparison.
+
+- Batch baseline sections in `benchmark/RESULTS.md` survive ordinary benchmark report regeneration.
+- Complete Batch timestep CUDA Graph capture includes fields, CPML, source patches, boundary corrections, full-field DFT and spectral observers. `graph="required"` and `graph_steps=K` support exact tail chunks and shutoff check boundaries; repeated runs reuse fixed observer and selected full-field DFT storage and captures. Scalar waveform spectral schedules are cached; changed frequency/window/horizon declarations rebuild tables and storage generations invalidate captures when addresses change. Capture epochs serialize process-wide and exclude admission of registered Batch work; concurrent active participants cause auto policy to step eagerly and required policy to fail explicitly. Batch captures use thread-local capture error checking on owned slot buffers, allowing independent consumer-thread tensor allocations and operations; captured inputs and execution storage must remain unchanged. The ordinary graph runner retains global capture checking.
+- Source-scale-only Batch templates compile one shared material bank across lanes, cohort changes and parameter updates. Density templates reuse local material patches; declared independent Scene variations can reuse verified local patches. Old cohort graph/source/observer owners release before new solver construction, reducing overlapping preparation allocations.
+- Static compiled material arrays and physical material arrays share storage across resident lanes only after device, dtype, shape and value equality checks. Unequal dielectric regions remain independent; evolving fields and CPML histories always retain distinct lane storage.
+- Inactive off-diagonal, nonlinear and modulation material channels use scalar-backed, read-only broadcast tensors until a blend activates them. Subpixel accumulation preserves compact zeros, while trainable occupancy retains its original autograd dependency. FDTD creates electric/magnetic dispersion templates only for material families with poles, avoiding unused whole-volume inverse-material arrays.
+- Regional material compiler audits through `python -m benchmark batch --regional-audit local_spectrum` interleave full and local compilation, record patch extents and synchronized wall time, and compare all material tensor channels outside timing. The measurement excludes initial bank construction and FDTD stepping.
+- Batch developer profiling through `python -m benchmark batch --profile WORKLOAD --concurrency B` separates uninstrumented latency, CPU dispatch scopes, CUDA activity and diagnostic field-only graph replay with spectrum parity checks. `--capacity-audit WORKLOAD --variants N --capacities 1 2 4 10` records actual solver reconstruction counts and costs across repeated cohorts. These diagnostic measurements do not enable the public graph scheduler or constitute business throughput acceptance.
+
 ## Maintenance Rule
 
 - Update this file whenever a new user-visible feature, public API capability, or meaningful workflow is added, removed, or materially changed.
@@ -9,6 +44,8 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 
 ## Packaging And Platform Support
 
+- Native FDTD extension preparation honors toolkit paths set after module import and reports toolkit discovery separately from process-level CUDA device access, including container and sandbox visibility.
+
 - Prebuilt CUDA 12.8 wheels for CPython 3.10-3.14 on Linux x86_64 and Windows x86_64.
 - Each wheel includes one Python-independent LibTorch Stable ABI FDTD library targeting PyTorch 2.10 or newer; the same binary is CI load-tested with PyTorch 2.10, 2.11, and 2.12 across CPython 3.10-3.14.
 - Native CUDA images cover compute capabilities 7.0, 7.5, 8.0, 8.6, 8.9, 9.0, 10.0, 10.1, and 12.0, with compute 12.0 PTX retained for forward-compatible Blackwell execution.
@@ -40,7 +77,7 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 - `BoundarySpec.bloch_wavevector="auto"` marker for solver-resolved Bloch phase workflows during FDTD preparation
 - Public `BoundaryKind` literal type for boundary-mode selection across declarative scene APIs
 - Shared `witwin.core.Structure` records pairing geometry and material, with `priority`, `enabled`, and `tags`
-- `Geometry.with_material(...)` convenience path returns a shared `Structure`
+- Declarative `Structure(geometry=..., material=...)` construction uses the shared structure contract
 - `MaterialRegion` for density-based PyTorch-native material overlays: Box occupancy participates in the same per-subsample arithmetic or polarized interface averaging as an equivalent `Structure`, each Yee axis blends from its own current background toward the density-defined scalar `eps/mu`, density textures are sampled differentiably on-device, and the compiled model retains base/design tensors plus the nominal design mask
 - Scene assembly with `Scene.add_structure(...)`, `Scene.add_source(...)`, `Scene.add_monitor(...)`, and `Scene.add_material_region(...)`
 - Experimental linear-circuit declarations through `Scene.add_circuit(...)` and `Scene.compile_circuits()`: a `Circuit` owns deterministic node/device order with a unique ground node, reuses the public `Resistor` / `Capacitor` / `Inductor` types with circuit-node terminals, binds only existing lumped/terminal EM ports, and performs explicit floating-network, source-loop, branch-dependency, and dense-size diagnostics without a CPU solver fallback
@@ -49,7 +86,7 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 - Experimental standalone nonlinear circuit transient (Phase 1, no FDTD coupling): `run_nonlinear_transient(...)` runs Newton in the transient loop over a fixed or non-uniform time grid, folding each device's stored-charge companion into the residual/Jacobian with the same trapezoidal (`2/dt`) / backward-Euler (`1/dt`) bilinear-transform convention as the linear reactive elements (`_charge_companion` / `advance_charge_state`, so the diode `junction_capacitance` and `VoltageDependentCapacitor` `Q(V)` are consumed and the charge history advances only on an accepted step). The transient runs a backward-Euler first step (trapezoidal startup) so a prescribed non-DC `initial_state` does not carry the `i_cap^0 = 0` first-step artifact. `solve_dc_operating_point(...)` finds the operating point with a geometric gmin continuation ladder ending exactly at `gmin=0` (no residual artificial conductance), treating capacitors as open at DC. A step in which a `PiecewiseLinearIV` device crosses a knot is re-solved with a local backward-Euler companion so the trapezoidal reactive companion does not ring on the conduction-slope kink, and that step's KCL residual and charge-history advance are taken under the same backward-Euler companion it was solved with. Under `failure='record_and_stop'` a non-convergent step (or DC start) truncates the trajectory rather than committing the unconverged iterate: `converged=False` with `stopped_step` recording the failing index. `multistart_dc(...)` sweeps seeds and deduplicates the converged DC operating points into a `MultistartReport` that distinguishes a unique operating point from multistability on an N-shaped negative-differential-resistance device (a benign non-convergence maps to `-1`; a non-finite device evaluation propagates as a device-model error rather than being masked). Verified CPU/fp64: diode DC I-V vs analytic Shockley `< 1e-5` across a bias sweep; half-wave and center-tapped full-wave rectifier steady-ripple output vs a frozen oversampled backward-Euler reference `< 1%` normalized RMS; every converged transient step meets the KCL residual tolerance; a linear-`Q(V)` capacitor discharge reproduces the analytic RC decay `< 1e-4`.
 - Experimental standalone CUDA linear-MNA runtime through `compile_mna_system(...)`: double- or single-precision DC operating points and trapezoidal/backward-Euler transients cover shared R/L/C devices, independent and E/G/F/H controlled sources, mutual inductance, scheduled switches, constrained or zero DAE initialization, local backward-Euler damping at startup/breakpoints, reusable piecewise factorizations, trainable CUDA parameters, and torch-native `CircuitData` node voltages, physical branch currents, device powers, energy residuals, and solver diagnostics
 - Experimental strong FDTD/circuit co-simulation for one circuit bound to one or more lumped/terminal ports through the ordinary `Scene -> Simulation.fdtd(...) -> Result` flow: `compile_coupled_mna_system(...)` condenses every exact Yee edge Norton operator into one GPU MNA/DAE solve at the same midpoint, supports controlled sources across bound ports and PULSE/SIN/PWL schedules, reuses the existing compiled terminal geometry and polarity, scatters solved currents before tail corrections, reuses piecewise LU factors and preallocated solve buffers, vectorizes fixed R/C networks, and publishes consistent port and `CircuitData` samples. Fixed built-in source/switch schedules support factor-class CUDA Graph replay, and `compile_batched_mna_factors(...)` provides an internal fixed-shape `[batch, unknown, unknown]` cached GPU solve primitive. `CircuitData.save/load` uses detached safe tensor-only snapshots; Result v2 persistence is a detached CPU snapshot that must be loaded only from trusted sources. `PreparedSimulation.run_until(...)` plus a fresh single-GPU `prepare().run(resume_from=...)` restores physical fields/CPML, port accumulators, circuit histories and result prefixes under a strict execution fingerprint. Spatial multi-GPU forward runs assign each wholly shard-owned bound port to one owner and the circuit graph to the owner of the minimum global reference edge, exchange one voltage/current scalar pair per remote port per step, keep same-shard ports on a zero-P2P fast path, and move final `PortData`/`CircuitData` once to `result_device`; full distributed field-shard checkpoint replay and distributed gradients remain deferred. Direct excitation or `PortSweep` of a bound port, a nonzero DC port current inconsistent with the zero initial Yee field, multi-circuit execution, resumable full-field/observer runs, and one port spanning an x split fail explicitly.
-- Experimental single-device FDTD thin-wire workflow keeps immutable, physical-radius `ThinWire` centerlines separate from volume `Structure` geometry through `Scene.add_thin_wire(...)` / read-only `Scene.thin_wires`; PEC straight, bent, branched, named-junction, and closed-loop paths compile into one cached energy-paired current/charge graph and run through native CUDA sampling, recurrence, and sorted-transpose deposition without thin-cylinder voxelization. Physical polyline spans own circuit state while cell-local `WireFragment` records own conservative arbitrary-direction coupling, including uniform/custom/auto grids and legal interior paths under real-periodic boundaries; face-touching wraps and Bloch paths fail closed. Open and named-PEC-grounded endpoints are supported. Standard `LumpedPort` and `TerminalPort` declarations bind to wire nodes or a removed feed gap through `WireNodeRef` / `WirePortBinding`, retain Yee-staggered voltage/current phasors, and share the ordinary `Result.port(...)` and RF adjoint path. `WireMonitor` returns frequency-first device-resident current/charge/loss selections as differentiable `WireData`; wire `I/q` participate in schema-v2 checkpoint/replay, and native standard/CPML reverse paths provide exact recurrence/deposition transposes plus fixed-stencil coordinate, physical-radius, local isotropic host-material, gap-weight, and source-amplitude gradients. The solver reports compressed state and a conservative joint Maxwell/wire CFL adjustment; differentiable runs require a fixed step below that joint bound. Spatial multi-GPU forward runs assign each cell-local sampling/deposition Yee edge to its owning shard and the whole compressed `I/q` recurrence plus every `WireMonitor` to the single owner of the minimum global sampling edge (declaration-order independent), reduce per-segment EMF partials to that owner with a deterministic rank-ordered sum, advance `I/q` owner-only, broadcast the advanced current back so every owned edge deposits exactly once, and move final `WireData` once to `result_device`: a physical segment may span any number of shards, its fragments split at each partition boundary, and the shared joint Maxwell/wire dt is taken from the full-domain single-GPU wire runtime so the step matches bitwise. A wire crossing the x split reproduces the single-GPU forward bitwise at a short horizon (deterministic reductions and per-edge deposition are bit-exact) while over long runs individual field phases drift by chaotic float32 halo-curl accumulation as in any distributed FDTD, yet the discrete lossless-loop energy invariant across the split stays tight. A trainable wire under multi-GPU (the Phase 7 adjoint bridge does not checkpoint or replay wire state), a distributed CPML or Mur absorbing boundary, and a wire mixed with an embedded network or lumped circuit fail closed at prepare. Finite-conductor wires now have a first-class material law `WireConductor.finite(conductivity, permeability=...)` and a per-unit-length series-impedance model (`witwin.maxwell.compiler.wire_impedance`): the exact analytic solid-round-wire skin-effect impedance `Z'(omega) = m/(2 pi a sigma) . I0(ma)/I1(ma)` with the exact DC resistance `1/(pi a^2 sigma)`, and a passive rational auxiliary-differential-equation fit of the excess impedance that reuses the shared network rational-fitting stack (`fit_rational`, `RationalModel.to_state_space`, bilinear `discretize`, and the pole-aware positive-real passivity certificate) rather than duplicating any pole fitting. The analytic AC resistance meets the 2% analytic gate against an independent evaluation and the ADE realizes the broadband impedance with a numerically certified non-growing discretization (not positive-real by construction: the improper skin-effect impedance carries an out-of-band direct term, so dissipativity is asserted per segment by the checked in-band positive-resistance condition plus a combined current/ADE spectral-radius `< 1` certificate, not guaranteed by construction). A finite-conductor wire now runs: the passive series impedance folds into the wire current update as an energy-consistent trapezoidal companion (`L dI/dt + R_dc I + ADE-excess = emf + potential drop`) whose PEC limit is the byte-identical lossless leapfrog, and the build adaptively selects the highest fit order whose combined current/ADE companion is certified non-growing (physical in-band positivity plus spectral radius `< 1`) or fails closed. The `ohmic_loss` monitor emits real per-frequency dissipation `0.5 Re(Z'(f)) length |I(f)|^2` (PEC segments report exactly zero), consistent with the recurrence's own dissipation. A finite conductor's field-coupled reverse/adjoint replay and checkpoint/resume fail closed (the ADE loss-state transpose and checkpoint schema, the field-coupled conductivity current sensitivity `dI/dsigma`, and distributed wire reverse/gradient communication remain deferred). The deterministic conductivity adjoint of the dissipation channel ships separately (see the next entry).
+- Experimental single-device FDTD thin-wire workflow keeps immutable, physical-radius `ThinWire` centerlines separate from volume `Structure` geometry through `Scene.add_thin_wire(...)` / read-only `Scene.thin_wires`; PEC straight, bent, branched, named-junction, and closed-loop paths compile into one cached energy-paired current/charge graph and run through native CUDA sampling, recurrence, and sorted-transpose deposition without thin-cylinder voxelization. Physical polyline spans own circuit state while cell-local `WireFragment` records own conservative arbitrary-direction coupling, including uniform/custom/auto grids and legal interior paths under real-periodic boundaries; face-touching wraps and Bloch paths fail closed. Open and named-PEC-grounded endpoints are supported. Standard `LumpedPort` and `TerminalPort` declarations bind to wire nodes or a removed feed gap through `WireNodeRef` / `WirePortBinding`, retain Yee-staggered voltage/current phasors, and share the ordinary `Result.port(...)` and RF adjoint path. `WireMonitor` returns frequency-first device-resident current/charge/loss selections as differentiable `WireData`; wire `I/q` participate in schema-v3 checkpoint/replay, and native standard/CPML reverse paths provide exact recurrence/deposition transposes plus fixed-stencil coordinate, physical-radius, local isotropic host-material, gap-weight, and source-amplitude gradients. The solver reports compressed state and a conservative joint Maxwell/wire CFL adjustment; differentiable runs require a fixed step below that joint bound. Spatial multi-GPU forward runs assign each cell-local sampling/deposition Yee edge to its owning shard and the whole compressed `I/q` recurrence plus every `WireMonitor` to the single owner of the minimum global sampling edge (declaration-order independent), reduce per-segment EMF partials to that owner with a deterministic rank-ordered sum, advance `I/q` owner-only, broadcast the advanced current back so every owned edge deposits exactly once, and move final `WireData` once to `result_device`: a physical segment may span any number of shards, its fragments split at each partition boundary, and the shared joint Maxwell/wire dt is taken from the full-domain single-GPU wire runtime so the step matches bitwise. A wire crossing the x split reproduces the single-GPU forward bitwise at a short horizon (deterministic reductions and per-edge deposition are bit-exact) while over long runs individual field phases drift by chaotic float32 halo-curl accumulation as in any distributed FDTD, yet the discrete lossless-loop energy invariant across the split stays tight. A trainable wire under multi-GPU (the Phase 7 adjoint bridge does not checkpoint or replay wire state), a distributed CPML or Mur absorbing boundary, and a wire mixed with an embedded network or lumped circuit fail closed at prepare. Finite-conductor wires now have a first-class material law `WireConductor.finite(conductivity, permeability=...)` and a per-unit-length series-impedance model (`witwin.maxwell.compiler.wire_impedance`): the exact analytic solid-round-wire skin-effect impedance `Z'(omega) = m/(2 pi a sigma) . I0(ma)/I1(ma)` with the exact DC resistance `1/(pi a^2 sigma)`, and a passive rational auxiliary-differential-equation fit of the excess impedance that reuses the shared network rational-fitting stack (`fit_rational`, `RationalModel.to_state_space`, bilinear `discretize`, and the pole-aware positive-real passivity certificate) rather than duplicating any pole fitting. The analytic AC resistance meets the 2% analytic gate against an independent evaluation and the ADE realizes the broadband impedance with a numerically certified non-growing discretization (not positive-real by construction: the improper skin-effect impedance carries an out-of-band direct term, so dissipativity is asserted per segment by the checked in-band positive-resistance condition plus a combined current/ADE spectral-radius `< 1` certificate, not guaranteed by construction). A finite-conductor wire now runs: the passive series impedance folds into the wire current update as an energy-consistent trapezoidal companion (`L dI/dt + R_dc I + ADE-excess = emf + potential drop`) whose PEC limit is the byte-identical lossless leapfrog, and the build adaptively selects the highest fit order whose combined current/ADE companion is certified non-growing (physical in-band positivity plus spectral radius `< 1`) or fails closed. The `ohmic_loss` monitor emits real per-frequency dissipation `0.5 Re(Z'(f)) length |I(f)|^2` (PEC segments report exactly zero), consistent with the recurrence's own dissipation. A finite conductor's field-coupled reverse/adjoint replay and checkpoint/resume fail closed (the ADE loss-state transpose and checkpoint schema, the field-coupled conductivity current sensitivity `dI/dsigma`, and distributed wire reverse/gradient communication remain deferred). The deterministic conductivity adjoint of the dissipation channel ships separately (see the next entry).
 - Finite-conductor thin-wire conductivity adjoint (dissipation channel): the exact closed-form conductivity sensitivity of the analytic scaled-Bessel internal impedance, `d Z'(omega)/d sigma = (i omega mu)/(4 pi sigma) . (1 - (I0(ma)/I1(ma))^2)` (`witwin.maxwell.compiler.wire_impedance.internal_impedance_conductivity_gradient`), whose DC limit is exactly `d R_dc/d sigma = -1/(pi a^2 sigma^2)`. A PyTorch-native autograd path (`witwin.maxwell.fdtd.wire_lossy.analytic_ac_resistance`) makes a scalar conductivity leaf differentiate the per-unit-length AC resistance `Re(Z'(f; sigma))`, so an ohmic-dissipation objective `0.5 . Re(Z'(f; sigma)) . length . |I(f)|^2` has an exact conductivity gradient (validated against a float64 central difference of the analytic model, no rational fit involved), and `LossySegmentModel.conductivity_ac_resistance_gradient(frequencies)` returns the per-segment `d Re(Z')/d sigma` for the built model. This deterministic channel deliberately avoids the field-coupled current sensitivity, which stays fail closed because the recurrence's ADE coefficients come from a nondeterministic shared rational fit. A distributed (multi-GPU) forward carrying a finite-conductor wire fails closed rather than silently running it as a lossless PEC wire, because the distributed owner runtime builds only the lossless current update.
 - Scene-level port assembly with type and unique-name validation through `Scene.add_port(...)`; `ModePort` continues to materialize through `Scene.resolved_sources()` / `Scene.resolved_monitors()`, while axis-aligned `LumpedPort` and `TerminalPort` declarations compile through `Scene.compile_ports()` into the same sparse Yee E-line/H-loop geometry without adding a second solver entrypoint. The first `TerminalPort` contract resolves two uniquely named, unrotated PEC `Box` structures across facing surfaces, uses the center of their transverse footprint overlap for voltage integration, and constructs its current contour from that overlap at the explicit reference plane
 - Phase-0 RF conventions use explicit negative-to-positive voltage paths, right-hand-rule current loops, peak phasors with `exp(-i*omega*t)`, average power `0.5*Re(V*conj(I))`, and complex-reference Kurokawa power waves. `PortData` keeps an explicit frequency axis and reports V/I, a/b, impedance, incident/reflected/accepted power, return loss, and VSWR; `NetworkData` fixes `[frequency, output_port, input_port]` ordering, complex `z0[frequency, port]`, valid excitation columns, differentiable S/Z/Y conversion, and reference-impedance renormalization through `torch.linalg.solve`
@@ -104,9 +141,10 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 - `PerturbationMedium(base, perturbation=..., eps_sensitivity=...)` shifts a base `Material`'s permittivity by an external perturbation field, `eps(x) = eps_base + eps_sensitivity * perturbation(x)` (for example a temperature or carrier-density map): the 3D torch `perturbation` grid maps over the structure's `Box` extent exactly like `MaterialRegion.density`, composes with the soft geometry occupancy, and is applied at compile time before ADE templating so dispersive bases see the shifted `eps_inf`; the map is PyTorch-native and differentiable, and a `perturbation` tensor with `requires_grad=True` is discovered as a trainable material input by the FDTD/FDFD gradient bridges (validated against per-element finite differences)
 - Axis-aligned diagonal anisotropy through `DiagonalTensor3` for `epsilon_tensor`, `mu_tensor`, and `sigma_e_tensor`, plus symmetric positive-definite off-diagonal electric permittivity through `Tensor3x3`
 - A `DiagonalTensor3` `epsilon_tensor` composes with electric dispersive poles in the same `Material`: each Yee axis carries its own background permittivity `eps_inf_i` while the shared isotropic pole susceptibility disperses all axes, giving the per-axis frequency permittivity `eps_i(omega) = eps_inf_i + chi(omega)` (birefringent background with material dispersion), validated against the analytic per-axis pole susceptibility and differentiable through the FDTD adjoint
-- A full off-diagonal `Tensor3x3` `epsilon_tensor` composes with electric dispersive poles in the same `Material` (a rotated birefringent dispersive crystal): the poles enter isotropically so the lab-frame response is `eps(omega) = eps_inf_tensor + chi(omega) * I`, and the FDTD forward applies the same per-edge instantaneous inverse permittivity tensor `eps_inf^-1` to both `curl(H)` (diagonal effective permittivity plus native off-diagonal coupling kernels) and the ADE polarization current (diagonal subtraction against `eps_eff` plus native off-diagonal current-coupling kernels), which diagonalizes exactly in the crystal principal frame and reproduces the ordinary and extraordinary indices `n_o(omega) = sqrt(eps_ordinary + chi(omega))` and `n_e(omega) = sqrt(eps_extraordinary + chi(omega))`, validated within 2% by propagating both eigen-polarizations of a 45-degree rotated uniaxial Lorentz slab at two frequencies; this combination is FDTD forward-only, its adjoint stays guarded
+- Full off-diagonal permittivity composes with isotropic electric dispersive poles in the same material. The reciprocal inverse-material operator acts on both the Yee curl and ADE current, preserving the crystal principal response under grid refinement. This combination remains forward-only; its coupled material adjoint is guarded.
 - A full off-diagonal `Tensor3x3` `epsilon_tensor` structure may overlap the CPML absorber (an anisotropic crystal reaching the boundary): a dedicated native CUDA aniso CPML kernel coordinate-stretches every off-diagonal `curl(H)` derivative with a per-direction psi memory owned by the target Yee edge (the two transverse directions use the E-field node profiles, the edge's own half-point direction uses the H-field profile), which reduces exactly to the raw off-diagonal update outside the absorber and, inside it, restores the stability and absorption that the un-stretched coupling loses; validated by a homogeneous rotated birefringent crystal filling the domain whose post-pulse residual field energy stays within 2x of the isotropic-PML baseline (the un-stretched coupling diverges instead). The split-field graded-sigma absorbers (`absorber="pml"`/`"absorber"`) have no per-direction auxiliary memory to stretch the coupling, so an anisotropic overlap there is rejected with a physics-worded error; the adjoint likewise rejects an anisotropic structure overlapping the CPML because the reverse replay does not yet stretch the off-diagonal coupling
-- A full off-diagonal `Tensor3x3` `epsilon_tensor` composes with electric conductivity (`sigma_e`, or a `DiagonalTensor3 sigma_e_tensor`) in the same `Material` (a lossy anisotropic crystal): the FDTD forward folds the loss through the exact per-edge semi-implicit tensor inverse `B = dt * (eps_inf + dt/2 * diag(sigma))^-1`, giving the update `E^{n+1} = E^n + B . (curl(H) - sigma . E^n)` with the diagonal decay `1 - sigma_i * B_ii` and a native off-diagonal conduction-current subtraction `-B_ij * sigma_j E_j^n` that couples the transverse components; for an isotropic conductivity this diagonalizes in the crystal principal frame, so a uniform field decays at exactly the analytic per-axis semi-implicit rate (validated to 1e-3, including the off-diagonal-generated cross component) and a plane wave through the slab absorbs at the analytic extraordinary complex index `n = sqrt(eps_e + i sigma/(omega eps0))` (transmitted amplitude within 5%); this combination is FDTD forward-only, its adjoint stays guarded
+- Spatially varying positive-definite full permittivity tensors compile into a volume-weighted reciprocal Yee operator by inverting node tensors and scattering reciprocal cross-component contributions. The native update and transpose share the same four weights per target edge, including nonuniform grids. Electric conductivity uses node-local shifted inverses with a separate conservative global conductivity feedback bound; the local shift is not treated as an exact global implicit solve. Full-tensor conductive and dispersive runs remain forward-only. Active off-diagonal CPML memories are included in disk checkpoints.
+- PointDipole, UniformCurrentSource and electric CustomCurrentSource drives inside full-tensor media apply the complete inverse-material operator, including transverse electric response. Constitutive source patches compile once and use the existing native injection path, including periodic wrapping. In supported real CPML adjoint scenes, material gradients include this source contraction at trainable material interfaces; the existing full-tensor adjoint boundary restrictions still apply.
 - A `DiagonalTensor3` `mu_tensor` composes with magnetic dispersive poles in the same `Material` (the magnetic mirror of the diagonal-anisotropic electric-dispersion combination): each Yee edge carries its own background permeability `mu_inf_i` while the shared isotropic magnetic pole susceptibility disperses all axes, giving the per-axis frequency permeability `mu_i(omega) = mu_inf_i + chi_m(omega)` (a birefringent magnetic background with material dispersion), validated against the analytic per-axis magnetic pole susceptibility read from the magnetic ADE state; a full off-diagonal `Tensor3x3` magnetic tensor remains unsupported as a static tensor field, while a *non-reciprocal* off-diagonal permeability is instead provided by the dedicated `GyromagneticFerrite` material (below), which carries the gyrotropy in a local magnetization state rather than by widening `mu_tensor`
 - `GyromagneticFerrite` first-class SI material for DC-biased ferrites (the framework's first non-reciprocal medium): `GyromagneticFerrite(eps_r, saturation_magnetization, bias_field=(x,y,z), gilbert_damping, gyromagnetic_ratio, mu_infinity, sigma_e)` defines a gyromagnetic (Polder) permeability from a linearized Landau-Lifshitz-Gilbert model, validated for `saturation_magnetization > 0`, `bias_field != 0`, `gilbert_damping >= 0`, and `gyromagnetic_ratio > 0`; `GyromagneticFerrite.from_cgs(saturation_4piMs_gauss=..., bias_Oe=...)` accepts CGS datasheet quantities and records the exact SI conversion in `cgs_conversion`, and `GyromagneticFerrite.from_resonance(resonance_frequency=..., saturation_magnetization=..., linewidth=...)` back-computes the bias and Gilbert damping from the gyromagnetic resonance; `permeability_tensor_at_freq(frequency)` / `polder_tensor(angular_frequency)` return the torch-native, differentiable complex 3x3 lab-frame Polder tensor `mu_r = mu*(I - b b^T) + mu_infinity*(b b^T) + i*kappa*[b]_x` (`exp(-i*omega*t)` convention, Hermitian when lossless and passive-absorptive when `gilbert_damping > 0`, off-diagonal `kappa` and the Faraday rotation flipping sign under bias reversal while the diagonal is unchanged); the full sign/unit conventions, LLG->Polder derivation, implicit-midpoint discretization, discrete-energy passivity proof, and frozen acceptance budget are recorded in `docs/reference/ferrite-physics-contract.md`. `Scene.compile_gyromagnetic_materials(dt=...)` lowers every ferrite structure into a `CompiledGyromagneticLayout` structure-of-arrays (active-cell indices, raw occupancy, per-cell bias unit vector and right-handed orthonormal local basis with an axis-aligned z/x/y fast path, `omega_0`/`omega_m`/`gilbert_damping`/`mu_infinity`, the dt-independent 2x2 magnetization-ADE matrices, and -- once `dt` is bound -- the implicit-midpoint Cayley propagator that is orthogonal when lossless and a strict contraction when lossy), with an explicit staircase partial-fill (the anti-symmetric gyrotropic tensor is never scalar-averaged) and a full off-diagonal `mu_r(f)` per-cell tensor accessor `CompiledGyromagneticLayout.permeability_tensor(frequency)`; the layout is cached per scene and serializable, and its per-cell state-space / propagator matrices agree bit-for-bit with the Phase-0 verification oracle. The FDTD time-domain solver runs a ferrite scene directly through the standard `Scene -> Simulation -> Result` path: the ferrite compiles as its diagonal background and the non-reciprocal off-diagonal permeability is produced by a local magnetization-ADE advanced at each ferrite cell (`gyromagnetic_enabled`), inserted into the magnetic update as `H -= dM/mu_infinity` (the magnetic mirror of the electric-side full-anisotropy correction). The forward advances an arbitrary bias -- an axis-aligned z/x/y fast path (where the two transverse magnetic components co-locate on the shared Yee overlap) plus a general per-cell path for an oblique or spatially-mixed bias -- is unconditionally stable and passive (the discrete magnetic energy does not grow at zero damping, monotonically decays for positive Gilbert damping), reproduces the frozen discrete Polder response and its bias-reversal non-reciprocity, composes with PML and electric conductivity, adds zero operations to a ferrite-free scene, and is CUDA-graph capturable (no per-step allocation or host synchronization); the field<->magnetization coupling is the implicit midpoint of the coupled system (the magnetization is driven by the time-centred pre/post-update H and the correction feeds back simultaneously via a precomputed per-cell 2x2 inverse), which is discretely non-growing in a lossless closed cavity unlike an explicit pre-update-advance / post-update-correct split; a general (non-axis-aligned) uniform bias and a scene mixing bias directions (mixed axes, opposed signs on one axis such as a +z/-z latching circulator, or differing magnitudes/materials) are supported through a per-cell general-bias path -- a pure coordinate rotation of the same contracted implicit-midpoint update (identity collocation reused), where the purely-local magnetization ADE makes a mixed-bias scene the direct sum of independent per-cell passive blocks with correct per-region handedness -- while only a Bloch-periodic ferrite run still fails closed (the real magnetization-ADE correction cannot carry the complex Bloch phase), and every non-FDTD-forward consumer of a ferrite scene fails closed rather than silently simulating a reciprocal medium: the frequency-domain (FDFD) solve, the differentiable adjoint (no reverse gyromagnetic core yet), and the multi-GPU distributed solve all reject a ferrite, while single-device checkpoint/resume round-trips the magnetization state
 <!-- BEGIN g3-ferrite-general-bias (Plan 08 slice 2a/2b, general + mixed bias ferrite forward) -->
@@ -263,6 +301,16 @@ result = mw.Simulation.fdtd(scene, frequencies=[200e12]).run()
 
 ## FDTD Solver Workflow
 
+- CUDA Graph preparation restores nonzero electric/magnetic ADE, Mur, wire and other carried state on both successful capture and warmup failure, using live device storage without expanding slab CPML buffers. Resume format v3 derives its complete physical-state layout from the checkpoint schema, including network recurrence, bidirectional delay, wire and real/imaginary Mur histories, and preserves nonlinear envelope diagnostics; incomplete older formats are rejected explicitly.
+- Mur boundaries update both real and imaginary tangential fields, including mixed Bloch/Mur domains. Adjoint checkpoints and replay carry each face's histories, and the reverse applies the exact ordered discrete transpose, including shared corners, before the native Maxwell reverse step.
+- One FDTD time plan includes every field source, modal/terminal drive and circuit waveform. Source permutations preserve automatic duration and sampling; pure CW apodized sampling uses `transient_cycles` and the slowest requested/source period, followed by `steady_cycles`. Pulses and mixed CW/pulse drives record their full response from step zero. Explicit `window="none"` retains full-response recording including startup. Continuing or unknown-support drives disable decay shutoff, and future pulses delay its earliest eligible step. Callable waveforms require explicit `time_steps`; metadata reports short runs, source completion, sampling and support. Source normalization requires a common incident waveform across all field/port drives; ambiguous circuit-driven normalization is rejected.
+- Raw `FieldTimeMonitor` and `FluxTimeMonitor` records are returned identically by fixed and trainable FDTD runs, including time-only runs. These recording buffers are detached and carry `differentiable=False`; adjoint objective gradients use the supported spectral monitor outputs.
+- Full-tensor stability bounds use a positive-definiteness check and the inverse matrix norm with linear preparation storage. Nonlinear envelope diagnostics inspect occupied chi2 edges; linear source cells cannot trigger that nonlinear bound. Resume identity includes material laws, face configuration, network dynamics and wire coefficients, while excluding nonlinear coefficient work buffers that are rebuilt every step.
+
+- FDTD preparation selects the final time step from high-frequency Yee material bounds, declared density ranges, modulation minima, and strength-dependent electric/magnetic ADE response rates, with a 0.9 stability margin and separate material-response resolution. `TimeConfig(dt=...)` pins a validated step for optimization and reproducibility; automatic step selection is numerical configuration and field gradients hold dt fixed. A trainable `Simulation` freezes its first prepared step across parameter updates and rejects an update that makes it unsafe; comparisons across separate Simulation objects should explicitly share `TimeConfig.dt`. Material, boundary, source and port coefficients bind after the joint wire constraint, and distributed shards use the same globally validated step. Solver statistics expose the bounds and limiting factor. For chi2 or negative Kerr increments, an automatically bounded field envelope (or explicit `TimeConfig(max_electric_field=...)` per-component bound) limits the negative permittivity increment; device-resident peak tracking rejects runs that exceed it. Gain media retain their explicit opt-in and are not classified as passive.
+
+- Mixed Bloch/CPML differentiable forward stepping uses independent real and imaginary magnetic absorption memory. Scalar mode operators, material potentials, and sparse eigenvector seeds use the same row-major aperture layout for rectangular grids and unequal transverse spacings.
+
 - Time-domain simulation through `Simulation.fdtd(...)`
 - CUDA-only solver execution; `Simulation.fdtd(...)` requires `Scene(device="cuda")`
 - Compiled native CUDA kernels are the only FDTD runtime backend; the Torch reference path has been retired from the runtime and relocated to the CUDA parity tests
@@ -279,6 +327,9 @@ result = mw.Simulation.fdtd(scene, frequencies=[200e12]).run()
 
 - Single- or multi-frequency DFT extraction through `frequency=` or `frequencies=[...]`
 - Source temporal frequency (`source_time.frequency`) remains distinct from simulation / monitor extraction frequencies; Maxwell does not infer extraction frequencies implicitly
+- Automatic FDTD time-step resolution includes declared field, port and circuit carriers, finite pulse ramps and widths, PWL knot intervals and exponential envelopes without changing the default carrier of another source. Explicit and optimization-locked time steps are shared by single-device and distributed adjoint preparation.
+- Field and lumped-port spectral observers consume the same all-source sampling window and phase origin. Port-only incident-waveform normalization uses a unit-amplitude, zero-phase reference while retaining physical drive amplitude and phase; terminal adjoint seeds transpose the stored forward phase tables.
+- Detached field-time recording preserves complex Bloch fields and is available in supported distributed point-monitor adjoint runs, including time-only output. Complex-field `FluxTimeMonitor` is rejected because a unique instantaneous flux is undefined; spectral `FluxMonitor` provides complex-field power measurements.
 - ADE-based electric and magnetic dispersive-material updates for Debye, Drude, and Lorentz media
 - Static isotropic or diagonal electric conductivity (`sigma_e`) in the time-domain update, folded into the per-component lossy-dielectric `Ca`/`Cb` coefficients via the standard semi-implicit trapezoidal scheme so simple lossy dielectrics no longer require a fitted Drude pole
 - Static magnetic conductivity `Material(sigma_m=...)` [Ohm/m], the magnetic dual of `sigma_e`: the magnetic conduction current `sigma_m * H` on Faraday's law folds semi-implicitly into the per-component H-update decay/curl coefficients `Da = (1 - h)/(1 + h)`, `Db = (dt/mu)/(1 + h)` with `h = 0.5 * sigma_m * dt / mu` (the exact mirror of the `sigma_e` E-update fold), reducing to the lossless leapfrog where `sigma_m = 0` and composing multiplicatively with the CPML split-field decay; a magnetically-lossy slab attenuates a plane wave at the analytic rate `alpha = (omega/c) Im(sqrt(1 + i sigma_m/(omega mu0)))` (within 2%), and a matched lossy layer satisfying the impedance-match condition `sigma_m/mu0 = sigma_e/eps0` reflects below a same-thickness PML baseline (an unmatched electric-only layer of the same thickness reflects more). `sigma_m` folds into eps-independent H coefficients that the reverse replay already reads, so it is transparent to the FDTD adjoint (an eps design differentiates alongside a `sigma_m` structure); FDFD and Tidy3D export reject it (magnetically-lossy media are outside their model) rather than silently dropping it
@@ -639,6 +690,7 @@ Capability level: **differentiable-surrogate (non-physical, non-regulatory)**. T
 
 - The delay-free embedded-network same-step coupling solve now applies the constant direct-loop operator through two precomputed composite matvecs, `branch_current = (M^-1 C) @ state + (M^-1 D) @ v`, instead of a per-step sequential pivoted-LU triangular substitution. The composite operators are formed once at prepare time by LU-solving the constant `C` and `D` against the loop matrix `M = I + D * diag(Z_f)` (not by naive matrix inversion), so the eager and CUDA-graph coupling paths become bitwise-identical and the per-step kernel-launch count of the connected 8-port/order-32 feedback block drops from 78 to 27 (65%). The op-stream before/after evidence is a reproducible artifact (`docs/assessments/e4-network-coupling-op-stream-2026-07-19.json`) and gate (`tests/rf/network/test_network_coupling_op_stream.py`); numerics are unchanged within the direct loop's floating-point roundoff bound and the existing multiport/ill-conditioned parity gates.
 - Embedded networks with explicit port delay now checkpoint and resume correctly: the frozen FDTD checkpoint schema captures the bidirectional reference-plane rings, the Thiran fractional-delay filter memory, and the shared ring cursor, so `run_until(k)` + `run(resume_from=...)` reproduces the uninterrupted delayed-network fields and diagnostics bit-for-bit (`tests/rf/network/test_network_delay_checkpoint.py`). Previously a resumed delayed network silently restarted its reference planes from zero.
+- Resume schema v4 also persists the seven breakdown histories and reconstructs the next-step conductivity coefficients without advancing timers or charging dissipation twice. Resume identity checks include gyromagnetic bias and compiled breakdown configuration; completed-step dynamic histories do not change configuration identity. Embedded graph capture restores gyromagnetic memory on success and failure, and Mur adjoints preserve the boundary histories alongside RF state.
 - Differentiable adjoints of explicit-delay embedded networks remain fail-closed with a precise rejection reason (the bidirectional ring couples steps up to `max_delay_steps` apart, possibly across checkpoint segments, and the fractional-delay filter is an IIR recurrence, neither of which the segment-local network pullback reverses); forward runs including checkpoint/resume are fully supported.
 - WavePort embedding stays fail-closed with an accurate rejection message: an embedded state-space network couples through a scalar voltage/current terminal on a single lumped Yee edge (LumpedPort or resolved TerminalPort), but a WavePort is a modal port with no scalar time-domain terminal (V, I) contract. This is a missing design contract, not a bug.
 <!-- END e4b-network-coupling -->

{witwin_maxwell-0.4.0 → witwin_maxwell-0.5.1}/PKG-INFO

@@ -1,15 +1,18 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: witwin-maxwell
-Version: 0.4.0
+Version: 0.5.1
 Summary: Witwin Maxwell - Electromagnetic simulation (FDTD/FDFD)
 Project-URL: License, https://witwin.ai/license
 License-Expression: LicenseRef-Witwin-Research OR LicenseRef-Witwin-Commercial
 License-File: LICENSE
 Requires-Python: <3.15,>=3.10
+Requires-Dist: ipython>=8
+Requires-Dist: matplotlib>=3.7
 Requires-Dist: numpy>=1.24
 Requires-Dist: scipy>=1.10
 Requires-Dist: torch>=2.10
-Requires-Dist: witwin<0.2,>=0.1
+Requires-Dist: tqdm>=4.65
+Requires-Dist: witwin<0.5,>=0.4
 Provides-Extra: direct
 Requires-Dist: nvidia-cudss-cu12; extra == 'direct'
 Requires-Dist: nvmath-python[cu12]; extra == 'direct'
@@ -160,7 +163,7 @@ python -m benchmark planewave_vacuum
 
 Benchmark assets live under `benchmark/scenes/`, `benchmark/cache/`, `benchmark/plots/`, and `benchmark/RESULTS.md`.
 
-The release validation suite combines unit/API tests, native CUDA parity and adjoint tests, and numerical comparisons against an external reference solver. Cross-solver comparisons use common physical-domain coordinates, external PML on both sides, coordinate-aligned complex field slices, and solver-independent scalar observables. See [`benchmark/RESULTS.md`](benchmark/RESULTS.md) for the generated comparison table and the validation-status section of the [0.4.0 release notes](docs/reference/release-notes-0.4.0.md) for what the evidence does and does not cover.
+The release validation suite combines unit/API tests, native CUDA parity and adjoint tests, and numerical comparisons against an external reference solver. Cross-solver comparisons use common physical-domain coordinates, external PML on both sides, coordinate-aligned complex field slices, and solver-independent scalar observables. See [`benchmark/RESULTS.md`](benchmark/RESULTS.md) for the generated comparison table and the validation-status section of the [0.5.1 release notes](docs/reference/release-notes-0.5.1.md) for what the evidence does and does not cover.
 
 ## Current Notes
 

{witwin_maxwell-0.4.0 → witwin_maxwell-0.5.1}/README.md

@@ -140,7 +140,7 @@ python -m benchmark planewave_vacuum
 
 Benchmark assets live under `benchmark/scenes/`, `benchmark/cache/`, `benchmark/plots/`, and `benchmark/RESULTS.md`.
 
-The release validation suite combines unit/API tests, native CUDA parity and adjoint tests, and numerical comparisons against an external reference solver. Cross-solver comparisons use common physical-domain coordinates, external PML on both sides, coordinate-aligned complex field slices, and solver-independent scalar observables. See [`benchmark/RESULTS.md`](benchmark/RESULTS.md) for the generated comparison table and the validation-status section of the [0.4.0 release notes](docs/reference/release-notes-0.4.0.md) for what the evidence does and does not cover.
+The release validation suite combines unit/API tests, native CUDA parity and adjoint tests, and numerical comparisons against an external reference solver. Cross-solver comparisons use common physical-domain coordinates, external PML on both sides, coordinate-aligned complex field slices, and solver-independent scalar observables. See [`benchmark/RESULTS.md`](benchmark/RESULTS.md) for the generated comparison table and the validation-status section of the [0.5.1 release notes](docs/reference/release-notes-0.5.1.md) for what the evidence does and does not cover.
 
 ## Current Notes
 

witwin_maxwell-0.5.1/experiments/fdtd_data_generator/README.md

@@ -0,0 +1,48 @@
+# WiTwin Maxwell converged CW-FDTD data generator
+
+This experiment creates random box, sphere, and cylinder scenes driven by a
+continuous-wave point dipole, solves the 3-D FDTD transient, and exports the
+converged complex 2 GHz phasor field.
+
+Each sample contains:
+
+- `sample_NNNNN.npz`: `field` shaped `(N,N,N,6)` and `permittivity` shaped
+  `(N,N,N)`, both `float32`;
+- `sample_NNNNN_meta.json`: the exact scene, DFT window, solve attempts,
+  convergence certificate, timings, storage, and peak GPU memory;
+- `summary.json`: aggregate convergence, runtime, and exact byte counts.
+
+The field channels are `Ex_real`, `Ex_imag`, `Ey_real`, `Ey_imag`, `Ez_real`,
+and `Ez_imag`. External CPML cells are cropped and staggered Yee components
+are interpolated to physical-domain cell centers.
+
+## Steady-state contract
+
+The default run uses a fixed 80-cycle Hanning DFT window after at least five
+domain round trips of transient propagation. A time probe is placed half a
+wavelength from the source and at every object center. Two adjacent final
+four-cycle windows are fitted to complex Ex/Ey/Ez phasors. Both the vector
+phasor change and vector-energy-weighted sinusoid-fit residual must be at most
+1%.
+
+If a scene fails, the generator reruns it with a longer pre-DFT transient
+while keeping the 80-cycle DFT window fixed. The wait doubles up to 640 cycles.
+A sample that still fails is rejected and is never written. This prevents
+early transient fields from entering a nominally steady dataset.
+
+```bash
+/home/xingyu/miniconda3/envs/maxwell/bin/python \
+  experiments/fdtd_data_generator/generate.py \
+  --num-samples 100 --grid-size 256 --gpus 0,1
+```
+
+The default output is `dataset_256_steady`; the historical 256-step
+Gaussian-pulse dataset in `dataset_256` is not overwritten. Generation is
+resumable only for samples whose data size, configuration, generator contract,
+and convergence certificate all match exactly. Existing partial or
+incompatible samples cause an error instead of being overwritten.
+
+Uncompressed NPZ is the default for predictable throughput. CUDA Graph is off
+by default for stable long batches. `--time-steps` is a fixed-step diagnostic
+override; normal dataset generation should use the automatic steady-state
+runtime.

witwin_maxwell-0.5.1/experiments/fdtd_data_generator/REPORT.md

@@ -0,0 +1,60 @@
+# 256³ FDTD dataset report
+
+> **Historical transient result — not a steady-state dataset.** These files
+> used a Gaussian pulse for only 256 steps (2.438 ns, 4.876 carrier cycles).
+> The pulse had not reached any sample's nearest object by its peak; the
+> resulting field was a localized source wave packet. Keep this report only
+> for provenance. New converged CW results are written to
+> `dataset_256_steady`.
+
+## Result
+
+- Completed samples: 100 / 100
+- Field shape per sample: `(256, 256, 256, 6)`, `float32`
+- Permittivity shape per sample: `(256, 256, 256)`, `float32`
+- Field channels: Ex/Ey/Ez real and imaginary parts
+- Output: uncompressed NPZ plus one JSON sidecar per sample
+- Random seed scheme: `20260715 + sample_id`
+
+## Simulation settings
+
+- Solver: WiTwin Maxwell FDTD, full-field single-frequency DFT
+- Frequency: 2.0 GHz
+- Grid spacing: 0.0093685143125 m (16 points per wavelength)
+- Physical domain: 2.398339664 m per side
+- External CPML: 10 cells per face
+- Time steps: 256
+- Random scene: 1–4 boxes, spheres, or cylinders with relative permittivity 2–12
+- Source: randomized Gaussian-pulse point dipole
+- Output grid: external CPML cropped; Yee fields and permittivity interpolated to cell centers
+
+## Timing
+
+- Mean solve time: 1.703638 s/sample
+- Solve range: 1.596418–2.366009 s/sample
+- Mean complete sample time (scene + solve + save): 3.643796 s/sample
+- Sum of complete sample times: 364.379564 s
+- Two-GPU campaign wall time: 254.604915 s (4 min 14.60 s)
+- Final resumable completion pass: 96.300185 s
+- Stable non-CUDA-Graph GPU peak: about 6.092 GiB per worker
+
+The campaign wall time includes the first real-sample benchmark, an initial
+CUDA-Graph batch that exposed graph-memory accumulation after long repeated
+scene creation, and the successful resumable non-graph completion pass. The
+generator now defaults to the stable non-CUDA-Graph mode.
+
+## Storage
+
+- Data files: 46,976,256,800 bytes
+- Sample metadata: 250,795 bytes
+- Dataset payload + sample metadata: 46,976,507,595 bytes
+- Entire dataset directory: 46,976,508,871 bytes
+- Entire directory in binary units: 43.750283 GiB
+- Per NPZ sample: 469,762,568 bytes (448.000496 MiB)
+
+## Validation
+
+All 100 sequential NPZ names and JSON sidecars are present. Every NPZ contains
+exactly `field.npy` and `permittivity.npy` with the same byte size. Samples
+0, 49, and 99 were fully loaded and verified for shape, dtype, and finite
+values.