JSON-safe even for a nonfinite numerical observation.

Courant-stable timestep for 2D or 3D FDTD.

Estimate timesteps for given number of periods at freq_max.

Convert physical position to grid index (accounting for the leading per-face CPML offset pad_{axis}_lo).

Raises

ValueError If pos maps outside the grid. The pre-guard code returned an out-of-range index silently, which then indexed the wrong cell (or wrapped negatively) downstream.

Map a cell/edge extent without wrapping its exclusive high endpoint.

A constant coordinate denotes a plane and uses the point lookup. Non-periodic axes retain position_to_index's input-dtype division.

PRIMAL cell widths along axis, float64, full padded length.

Constant by construction: np.full(n, dx). The last entry is the fence-post node-provider (see rfx/_grid_metric.py), so the sum overshoots the realized extent by one cell -- use node_of.

DUAL (E-node) spacings along axis, float64.

On a constant axis dual[k] = (d[k-1]+d[k])/2 = d[k] exactly, and dual[0] = d[0] by the same rule, so this equals cells bit for bit. Spelled through the shared helper anyway so the two classes cannot drift apart in how the rule is written.

Padded index of the node nearest physical coordinate x.

Divides in float64 before applying the shared lower-node tie rule. position_to_index retains its input scalar's division dtype. Declared periodic axes wrap modulo their node count. In 2-D mode the z axis holds one cell and the answer is always 0, which is what position_to_index returns there.

Physical coordinate of the E node at padded index i.

(i - pad_lo) * dx -- the closed form _uniform_axis_nodes (rfx.geometry.rasterize_grid._uniform_axis_nodes) evaluates for the whole axis, so this equals coords_from_uniform_grid(grid).<axis>[i] bit for bit, and equals the bare i * dx on an axis with no pad.

The cell width at the "lo" or "hi" face of axis.

The number a CPML profile is entitled to calibrate against. Constant here, so both sides give dx.

Whether every cell on axis has the same width.

Always True on this class. Decision 4 selects the uniform kernel on this predicate rather than on "was a profile given", so that the kernel and the metric have one source.

Whether axis's cell widths are a JAX tracer (decision 6).

Always False here: a uniform Grid holds a Python float.

Create new instance of NonUniformGrid(nx, ny, nz, dx, dy, dx_arr, dy_arr, dz, dt, cpml_layers, inv_dx, inv_dy, inv_dz, inv_dx_h, inv_dy_h, inv_dz_h, pad_x_lo, pad_x_hi, pad_y_lo, pad_y_hi, pad_z_lo, pad_z_hi, dx_arr_f64, dy_arr_f64, dz_f64, face_layers)

Alias for field number 0

Alias for field number 1

Alias for field number 2

Alias for field number 3

Alias for field number 4

Alias for field number 5

Alias for field number 6

Alias for field number 7

Alias for field number 8

Alias for field number 9

Alias for field number 10

Alias for field number 11

Alias for field number 12

Alias for field number 13

Alias for field number 14

Alias for field number 15

Alias for field number 16

Alias for field number 17

Alias for field number 18

Alias for field number 19

Alias for field number 20

Alias for field number 21

Alias for field number 22

Alias for field number 23

Alias for field number 24

Alias for field number 25

Grid shape (nx, ny, nz) — duck-typing compatible with Grid.

Leading (lo) per-axis pad — the number coordinate-offset callers subtract from array indices to recover user coords.

Whether axis's cell widths are a JAX tracer (decision 6).

True on the mesh-as-design-variable path, where the profile is a trace leaf and has no host copy. A traced axis still steps the solver and still differentiates; what it cannot do is answer a host-side structural question, which is why index_of refuses on it.

PRIMAL cell widths along axis, full padded length n.

float64 on the host for a concrete axis -- the float64 spine, which is the source of truth (decision 1), NOT the float32 solver store. A traced axis returns its tracer unchanged, in jnp.

The last entry is the bounding-node duplicate (#562): it supplies the N+1-th E node and carries no physical extent, so sum(cells) overshoots the realized wall-to-wall extent by one cell. Read extents from node_of or interior_cells.

A spine whose length disagrees with the axis is REFUSED rather than returned: the spine and the float32 store are two views of one padded profile, so a length mismatch means they are not, and every node derived from it would sit at the wrong index. A MISSING spine is a different case, handled below.

A grid built by hand (the NonUniformGrid(...) constructor called directly, rather than make_nonuniform_grid) may carry no spine. It then gets the float32 store widened back to float64 AND an ExactNodeSpineMissingWarning, the same degraded line and the same warning coords_from_nonuniform_grid emits -- silently falling back is the #802 realization with no trace of why.

DUAL (E-node) spacings along axis.

dual[0] = d[0], dual[k] = (d[k-1]+d[k])/2 -- the control volume an E node's material acts over, and the metric the NU E update divides its curl by. float64 for a concrete axis; a traced axis goes through e_node_dual_spacings so the gradient survives.

Reproduces e_node_dual_spacing_at(grid.cells(axis), k) for every k bit for bit. Against the float32 solver store the two spellings agree only to float32 roundoff -- that gap is the store's, not the rule's, and it is why the accessor reads the spine.

Padded index of the node nearest physical coordinate x.

Refuses on a traced axis (decision 6, closes G9). The existing position_to_index answers there by substituting a NOMINAL uniform mesh of fallback_dx cells and returns an index for a mesh the solver is not running -- silently the wrong cell whenever the traced profile is graded. That fallback stays in position_to_index for 0a because consumers still call it; 0b retires it as each consumer moves onto this accessor.

Which node (#1295, #1342): the nearest one by float64 distance, and at a tie (two distances agreeing to 1e-9 of the local cell) the LOWER one -- nearest_node_index, the function the sheet snap itself calls, on the node line the conductors are rasterized on (_axis_node_positions of the float64 spine: the closed form (i - pad_lo) * cell on a constant axis, the cumulative sum on a graded one). A port, source or probe and a sheet declared at the same coordinate therefore land on the same node, bit for bit. position_to_index and pos_to_nu_index resolve through the same function. The uniform Grid still rounds an exact tie to the even node until #1342.

A coordinate outside the interior span is REFUSED, as on the uniform grid. _axis_position_to_index clamps instead: argmin over the edge list always returns some index, so asking for a position a metre outside a 6 mm domain silently gives the last face and the caller stamps its material there. That legacy clamp stays where it is for 0a -- consumers still call position_to_index -- and 0b retires it as each consumer moves onto this accessor.

The bound is the interior, [node_of(pad_lo), node_of(last interior node)], because that is the range the edge list can represent; a coordinate inside an absorber pad has no interior node to name. The comparison carries DECLARED_SPAN_TOL_M (1e-12 m) of slack at each end. That is not a fudge factor: it is the node tolerance the mesh builder itself claims. make_band_profile guarantees that every declared interface lands on a cumulative node coordinate to 1e-12 m and that the cells sum to the declared span to the same figure, and assert_cells_span_declared_profile holds the constructor to it. A grid that only places a node to 1e-12 m cannot tell a coordinate 1e-13 m past the face from the face, so refusing one would be refusing a distinction the grid does not make. Outside that band the refusal is exact.

That figure grows with the column: the builder documents 1e-11 m on a 10 m column of 1e5 cells. On a board or a waveguide, the sizes this lane meshes, 1e-12 m is the right order. A caller meshing metres should read the builder's guarantee before trusting the boundary case.

Physical coordinate of the E node at padded index i.

Origin at the first interior node, so node_of(axis, pad_lo) == 0.0. Derived from the cells by cumulative sum, except that a CONSTANT axis takes the closed form (i - pad_lo) * d[0] -- which is what keeps a uniform-valued NU axis bit-identical to the uniform lane's own node line (#807). Both branches are _axis_node_positions, so this equals coords_from_nonuniform_grid(grid).<axis>[i] bit for bit.

A traced axis returns a traced scalar (jnp cumulative sum), the same arithmetic coords_from_nonuniform_grid runs in-trace.

Cost: this builds the whole axis to return one entry, because reusing the spine producer is what makes the answer bit-identical to the coordinate arrays. Nothing calls it in a loop in 0a. A consumer in 0b that needs many nodes asks coords_from_nonuniform_grid once, or this grows a cached array -- not a second spelling of the arithmetic.

The cell width at the "lo" or "hi" face of axis.

The number a CPML profile is entitled to calibrate against, per face. make_nonuniform_grid pins the first and last interior cells of x and y to the scalar dx / dy and pads each face with copies of them, so on a built grid both sides equal that scalar; z has no scalar and this is the only way to ask.

cpml.py fills its six per-face slots from this accessor.

Whether every cell on axis has the same width.

The predicate decision 4 selects the uniform kernel on, instead of "was a profile given" (rfx/api/_mesh.py:152-156).

A TRACED axis returns False. Constancy is not decidable on the host there, and False is the safe direction: it routes the axis to the non-uniform kernel, which is correct for a constant mesh too, whereas True would hand a possibly graded mesh to a kernel that folds one scalar.

Add a z-axis refinement region for SBP-SAT subgridding.

Refinement acts only through run() on a uniform mesh. Other solve entry points, including forward() and optimization, refuse it.

The experimental runner covers the specified z-range across the full x/y interior at dx_fine = dx_coarse / ratio. xy_margin enables an experimental research-only local x/y window whose fine region is inset from the physical x/y boundaries by that distance.

Parameters

z_range : (z_lo, z_hi) in metres Physical z-range for the fine region. ratio : int Refinement ratio (fine cells per coarse cell). Default 4. xy_margin : float or None Experimental x/y inset in metres. None keeps the full x/y interior. A finite non-negative value creates a local window spanning [xy_margin, Lx - xy_margin] and [xy_margin, Ly - xy_margin]. Production validation still rejects this lane until waveform gates and crossval pass. tau : float SAT penalty coefficient (default 0.5). Higher values give stronger coupling but more dissipation. validation : {"production", "research", "off"} Production refuses the unstable, unverified subgridded lane before stepping (#1465). An empty PEC cavity's first resonance is 8 % high and its field grows. Use dx/dy/dz profiles for local resolution. Explicit "research" or "off" runs with a warning; neither mode establishes physics support. topology : {"overlap_z_slab", "stage2_disjoint_3d"} Internal topology selector. "overlap_z_slab" is the current public runner. "stage2_disjoint_3d" records the selected centered/two-interface integration lane but remains a research-only contract until its public runner wiring and waveform gates pass.

Return the production-envelope validation report for subgridding.

Every mode reports the subgridded lane as unsupported because it is unstable and unverified (#1465). Experimental envelope checks remain available for research diagnostics; opting in does not confer support.

Register a named material.

Parameters

chi3 : float Third-order (Kerr) susceptibility in m^2/V^2. When non-zero, an ADE correction is applied after each E-field update inside the scan body.

Add a geometric shape filled with a named material.

Parameters

shape : Shape material : str Registered or library material name.

Notes

A PEC shape is a VOLUME under the lattice ownership contract (#931): its primal cells are sampled at cell centres and every E edge incident to an occupied cell is shorted, so a Box drawn z_a -> z_b on node planes realizes walls at BOTH planes with realized thickness = drawn thickness. A PEC Box with exactly one zero-extent axis (lo == hi) is a SHEET declaration, realized exactly as add_thin_conductor() would realize it. A PEC Box thinner than one local cell (but not zero) is refused at assembly; so is any PEC shape that rasterizes to zero cells. There is no per-entry realization knob.

Return the immutable host record of this configuration's built geometry.

Build only: entities, solved sheet spans, signed face residuals in metres, domain padding, and driven port edges. Dense diagnostic arrays are built on request here. run() attaches a compact record built independently from its own assembly as Result.realized_geometry.

Input-fidelity audit: declared vs solved, per entity, in input units — run BEFORE any solve. See rfx.fidelity.fidelity_report() (design rule: never predicts result-side impact; rasterization, realization class and materialization only).

Add a soft point source (no impedance loading).

Unlike add_port(), this does NOT add a resistive load. Ideal for resonance characterization where port loading would damp the cavity response.

Uses a differentiated GaussianPulse by default (near-zero DC content, ~1e-4). This prevents static charge accumulation on PEC surfaces.

Parameters

position : (x, y, z) in metres component : "ex", "ey", or "ez" waveform : excitation pulse (default: GaussianPulse(f0=freq_max/2, bandwidth=0.8)) amplitude_kind : 'field' | 'current' | None What the waveform amplitude MEANS — issue #571. Boundary- and mesh-independent once explicit:

- ``'current'``: the amplitude is a current moment I(t) in A·m,
  realized as ``E += Cb * I / dV`` on every path and boundary
  (Yee ``Cb = (dt/eps)/(1 + sigma*dt/(2*eps))``; ADI refuses
  ``'current'`` and requires explicit ``'field'``,
  ``dV`` = local cell volume). Resolution-independent injected
  power; Meep's convention; the declaration default.
- ``'field'``: the amplitude is a raw E-field increment per
  step, ``E += w(t)`` on every path and boundary.

Cell-volume convention: ``dV = dx * dy * dz`` at the source
cell; a 2D grid is treated as ONE CELL DEEP (``dz`` one cell,
duck-typed to ``dx``), so ``dV = dx**3`` on a cubic 2D grid,
not the per-unit-length ``dx**2``
(``rfx/api/_source_semantics.py``). On a non-uniform mesh
``dV`` is the E node's control volume — the primal per-cell
width on the component's own axis and the DUAL spacing
``(d[k-1]+d[k])/2`` on the two transverse axes (issue #672);
the two coincide on a uniform profile.

``None`` means ``'current'`` (E += Cb*I/dV, I is a current moment in A·m)
on every path and emits one
`DeprecationWarning` per Simulation. Pass the kind
explicitly to silence it.

The open-boundary + ``subpixel_smoothing`` cross-path residual
(0.18 % amplitude, issue #582) is a solver defect independent
of this parameter.

Add a polarized point source.

Parameters

position : (x, y, z) in metres polarization : str or tuple - "ez", "ex", "ey" — linear single-component - "circular" or "rhcp" — accepted complex-component shortcut; time-domain quadrature is not independently verified - "lhcp" — accepted complex-component shortcut; same limitation - (Ex, Ey) tuple — normalized component weights; real tuples are the documented linear-polarization scope - "slant45" — 45° linear (Ex = Ey) waveform : excitation pulse (default: GaussianPulse) amplitude_kind : 'field' | 'current' | None Threaded through to every internal add_source() call — see add_source for the semantics. None resolves to 'current' and warns once per simulation; pass the kind explicitly to silence the warning.

Add an SMA-style coaxial probe port.

Parameters

position : (x, y, z) — center of port on cavity wall (metres) face : "top", "bottom", "front", "back", "left", "right" pin_length : float — pin protrusion into cavity (default 5mm) pin_radius : float — center pin radius (default 0.635mm, SMA) outer_radius : float — outer conductor radius (default 2.055mm) impedance : float — port impedance (default 50 ohm) waveform : excitation pulse (default GaussianPulse at freq_max/2)

Add a thin conductor with subcell correction.

Parameters

shape : Shape Geometric region of the conductor. sigma_bulk : float Bulk conductivity (S/m). Default: copper (5.8e7).

**This single value decides the model.** At or above 1e6 S/m the
shape becomes a PEC sheet and ``thickness`` and ``eps_r`` are
never read (`rfx.materials.thin_conductor.apply_thin_conductor()`
returns the material arrays untouched and only ORs the mask). Below
1e6 S/m the shape becomes a lossy sheet whose conductivity is
``sigma_bulk * thickness / d_norm``, where ``thickness`` IS
load-bearing and ``d_norm`` is the local sheet-normal spacing
(see ``surface_impedance_f0`` below for the graded-mesh case).
Every real metal — copper 5.8e7, aluminium 3.5e7, even stainless
steel 1.4e6 — is on the PEC side, so by default
(``surface_impedance_f0`` unset) for metals this call models a
lossless perfect sheet and nothing else. Pass
``surface_impedance_f0`` to opt in to band-centre Leontovich
conductor loss instead (see below).

thickness : float Physical thickness (metres). Default: 35 µm (1 oz copper). Only used on the lossy path (sigma_bulk < 1e6); ignored entirely for metals — see sigma_bulk above. eps_r : float Relative permittivity (default 1.0). Lossy path only, same as thickness. surface_impedance_f0 : float or None Opt-in band-centre Leontovich surface-impedance loss (issue #669). Default None = exact legacy behaviour on every path. When set to a positive frequency (Hz), the sheet — for ANY sigma_bulk > 0, metals included — is modelled as a resistive sheet of sheet resistance Rs0 = sqrt(pi*f0*mu0/sigma_bulk) (the thick-conductor surface resistance at f0), realized NODE-THIN (#677): a per-step operator applies an exact exponential-stepping resistive update E = A*E + B*curlH with sheet conductivity sigma_sheet = (1/Rs0)/d_norm on exactly the tangential E edges a PEC sheet on the same cells would zero — so toggling surface_impedance_f0 on a metal changes LOSS, never the conductor's surface position (before #677 the sheet folded into materials.sigma as a full-cell slab, moving resonances by geometry). d_norm is the local spacing normal to the sheet: the cell size on a uniform grid, and on a graded one the E-node DUAL spacing (d[k-1]+d[k])/2 (#671). Both the uniform and the non-uniform (dz_profile) run()/S-parameter lanes apply the operator; lanes that do not (distributed, subgridded, ADI, UPML, dispersive-overlap, multimode-waveguide, MSL-junction/mixed, optimize/topology drivers) refuse f0 sheets loudly rather than silently dropping them; compute_msl_s_matrix applies the sheet through its run()/forward() device dispatches (#679). The sheet contributes NO PEC cells and no materials.sigma/eps_r entries.

**Consequence for material inspection (#695): an f0 sheet is
INVISIBLE to the assembled arrays.** It is absent from
``pec_mask`` and it adds nothing to ``materials.sigma``, so a
conductor test written the obvious way --
``pec_mask | (sigma > 1e3)`` -- finds no metal at all on a
board whose traces are all f0 sheets, and a connectivity
check built on it reports a perfectly healthy model as
disconnected. Use `Simulation.conductor_mask()`, which
returns ``pec_mask | (sigma > threshold) | union(f0 sheet
cell masks)`` -- the whole conductor footprint in one
spelling, on the grid the run will actually use. The runtime
edge masks (``mask_ex/ey/ez``) live on the
``SheetImpedanceCtx`` the runners build; the accessor returns
the CELL footprint, which is what an occupancy or
connectivity check wants.

Model scope (be precise about what you get):

- **Magnitude loss only.** The reactive part ``Xs = Rs``
  (internal inductance) is NOT modelled, so resonances read
  slightly high in frequency.
- **Frequency-flat within a run**: ``Rs`` is frozen at ``f0``
  with relative band error ``|sqrt(f/f0) - 1|`` (about +-11%
  across an 8-12 GHz band centred at 10 GHz).
- **Thick-conductor model**: valid for ``thickness >= ~3``
  skin depths at ``f0``. For thin films the DC path (omit this
  kwarg, ``sigma_bulk < 1e6``) is the correct model;
  ``thickness`` deliberately does NOT enter ``sigma_eff`` in f0
  mode (Leontovich loss is thickness-independent).
- **Transmission leakage** ``(2*Rs/eta0)**2`` makes the sheet
  unusable for shielding-effectiveness claims beyond ~60 dB.
  (Validated against the closed form ``T = 2Rs/(2Rs+eta0)``
  to within a few percent, frequency-flat —
  tests/oracle/test_leontovich_alpha_oracle.py.)
- The operator touches TANGENTIAL sheet edges only; the
  sheet-normal E component is never loaded (#677 removed the
  pre-existing isotropic-fold caveat).
- ``f0`` and ``sigma_bulk`` are differentiable DoFs in f0 mode
  (closed forms ``d(sigma_sheet)/df0 = -sigma_sheet/(2*f0)``,
  ``d(sigma_sheet)/d(sigma_bulk) =
  +sigma_sheet/(2*sigma_bulk)``). Geometry (the rasterized
  mask) stays non-differentiable. Traced values skip the
  concrete-value validation below.

Sheet shapes (issue #674): ANY shape implementing
``mask_on_coords`` and ``bounding_box`` may carry a
surface-impedance sheet — a patterned ground plane with
clearance holes, a meandered arm, an imported CAD outline
(`~rfx.geometry.mesh_import.MeshShape`), a disc, a
strip. The realization is per occupied cell, so a hole is
simply a cell the operator never touches. What is NOT supported
is a body with HEIGHT: the sheet must rasterize to exactly ONE
cell layer along its normal, because ``sigma_sheet`` is the
conductance of a single E node. A 3-D solid, a bent/L-shaped sheet, or a slab
thicker than a cell raises ``ValueError`` when the grid is
built — folding such a body per cell would multiply the sheet
conductance by the layer count while still reporting ``Rs0``.
A sheet that rasterizes to ZERO cells raises too: a sub-cell
mesh slab registers only where a grid node falls inside it, and
silently vaporized metal is the #369 class. (A ``Box`` drawn
with equal lo/hi on its normal axis snaps to the nearest node by
construction, so it always satisfies both.)

Validation at add time (concrete values only): ``f0 <= 0`` and
``sigma_bulk <= 0`` with ``f0`` set each raise ``ValueError``,
as does a shape with no ``mask_on_coords`` or no bounding box.
The rasterized one-layer and non-empty checks need the grid, so
they raise at build time, on BOTH lanes (the legacy DC path
also refuses non-Box shapes on a non-uniform mesh).

Notes

A PEC sheet occupying ONE cell is modelled as a surface, not as a conductor of that cell's thickness: rfx.boundaries.pec.apply_pec_mask() zeroes a tangential E component only where the mask has a neighbour along that component's axis, so the normal component survives as surface charge. Stamping the same conductor TWO cells thick therefore changes the model rather than the thickness. Measured on an MSL thru at dx = 84.67 µm: one cell gives Re(Z0) = 44.1 Ω and two cells 41.9 Ω. Reproduce with scripts/diagnostics/thin_conductor_cell_thickness_probe.py.

Note this pair no longer proves the model change on its own. Until issue #511 was fixed the one-cell reading was 38.8 Ω, so the thicker stamp appeared to read the HIGHER impedance — backwards for a fringing-capacitance effect, which is how the model change was first argued. That inversion was an extractor artifact: the modal voltage summed one Ez edge too many, and a two-cell stamp happens to mask that edge, so only the one-cell number was biased. With both corrected the ordering is the ordinary one (thicker → lower Z0) and the 2.25 Ω step is consistent with either a model change or a genuine thickness effect. The model change is still real — it follows from apply_pec_mask directly — but this measurement no longer discriminates between the two.

Conductor LOSS is therefore unavailable for metals through this API. On the lanes this repo gates that is a small omission — copper loss on a 10 mm 50 Ω microstrip is 0.04-0.05 dB at 3-4.5 GHz against a 0.45 dB gate budget, and the metal is 26-36 skin depths thick so its geometry is electromagnetically a half-space — but it is a real limit for anything whose loss budget IS the conductor, e.g. resonator Q.

Declare a thin PEC conductor by NODE INDICES instead of metres.

add_thin_conductor draws metal in metres, and the grid then decides which node lines that reaches. This draws it on the node lines directly: the conductor occupies node plane_index along normal_axis and the inclusive node ranges i_range / j_range on the other two axes, in increasing axis order — for the default normal_axis=2 that is i_range on x and j_range on y.

Indices are INTERIOR (unpadded) node indices: interior node i sits at i * dx from the domain origin on a uniform mesh, and is the i-th interior node on a graded one. Absorber padding is added when the sheet is realized.

Why it exists: the conductor's PHYSICAL size is then whatever the cells between those nodes add up to, so stretching the cells makes the metal longer without moving it off the lattice and without any sub-cell metal. That is what lets jax.grad reach a patch edge through dx_profile / dy_profile / dz_profile — a metric sheet on a mesh that is a JAX tracer is still refused, because its corners cannot be read off a traced node line.

The declaration is mesh-independent by construction, so the same call gives the same footprint on the uniform and non-uniform lanes, traced or not. A range spanning a single node line is refused: one node line carries no E edge, so the metal would carry no current.

Only the lossless PEC sheet is supported (sigma_bulk >= 1e6, surface_impedance_f0 unset); thickness and eps_r are accepted for signature compatibility with add_thin_conductor() and are not read, exactly as they are not read there for a metal.

Add a lumped port (single-cell) or wire port (multi-cell).

Parameters

position : (x, y, z) in metres component : "ex", "ey", or "ez" impedance : port impedance in ohms (default 50) waveform : excitation pulse (default: GaussianPulse at freq_max/2). Ignored when excite=False. extent : float or None When provided, the port spans from position along the port axis by this distance (metres), creating a multi-cell WirePort. For example component="ez", extent=0.0015 spans the port from z to z + 0.0015. radius : float or None Opt-in thin-probe radius in metres (requires extent). None preserves the legacy filament, whose effective radius is approximately 0.20 times the transverse cell size. The local self-field model requires a square, locally uniform transverse mesh, uniform spacing along the pin, and radius <= 0.2 times the transverse spacing. Supported on single-device, nondispersive 3-D second-order Yee run/forward; unsupported solvers and material updates raise before stepping. excite : bool (default True) When True the port has BOTH a resistive termination AND a time-domain source (legacy behaviour). When False the port is a passive matched load only — no source, just the σ=1/(Z0·A) resistive termination. Passive ports are required for multi-port S-parameter extraction: excite one port at a time and probe V/I at the others to fill off-diagonal entries of the S matrix. direction : {"+x", "-x", "+y", "-y"} or None Outward-normal direction of the port (from the port cell into the external world). Used by the S-matrix post- processing to orient the V/I → (incoming, outgoing) wave decomposition. When None, the runner auto-detects from the port's position (closest boundary face). reference_plane_cells : int or None Opt-in reference-plane port waves for the wire-port S-matrix OFF-diagonal extraction (issue #313). When set to an integer N >= 1, run(compute_s_params=True) registers TWO line V/I reference planes for this port at N and 2N cells outboard (into the DUT along the line axis, i.e. opposite direction): gap-voltage line integrals at integer Yee planes plus dual adjacent Ampere loops around the PEC signal trace, accumulated in the production scan. Off-diagonal S[i, j] entries whose ports BOTH opt in are then computed from the plane waves — forward/backward split with the MEASURED two-plane line impedance Zc^2 = (V1^2 - V2^2)/(I1^2 - I2^2) (never the nominal port impedance) and phase-only de-embedding to the port plane with the MEASURED per-bin beta from the same two planes. The Phase-0 closed-box flux referee showed the port-cell wave pair does not conserve power (the port plane is near-field dominated) while the plane waves close the power budget at all bins; the plane path removes the drive-side |S21| deflation kappa(f) = 1.49-1.86 of issue #313. None (default) keeps the shipped port-cell behaviour, byte-identical. The DIAGONAL S_jj always stays on the byte-frozen legacy path either way, so forward() / 1-port S11 results are unaffected. Requires a wire port (extent=) with an explicit direction transverse to the port component, a PEC signal trace uniform across both planes, and the uniform-mesh run() lane: the non-uniform and subgridded lanes raise NotImplementedError with the opt-in set, and the distributed lane does not support compute_s_params at all (it warns that the kwarg is unsupported and ignores it).

Choosing N: place BOTH planes (N and 2N cells) roughly >= 10
cells from every port so the two-plane Zc/beta measurement
sits outside the port near-fields — the Phase-0
pre-registration rule. Measured on the canonical 16 mm thru
(dx = 0.5 mm, gap-trimmed V, 2026-07-10 battery): N=3 planes
read beta/(w/c) = 1.16-1.20 and Zc = 52-53 ohm with Im/Re up
to 8.2% (near-field contaminated; |S21| closed-box-referee
residual -3.1% at 7 GHz, row energy |S11|^2+|S21|^2 up to
1.019), while N=10 planes read the clean mid-line
beta/(w/c) = 1.046-1.059 and Zc = 47.9-48.6 ohm (Im/Re <=
1.2%) and closed the closed-box referee within 0.9% at all
bins.

Add a microstrip-line (MSL) port spanning the full trace cross-section.

Unlike add_port() with extent=... (a one-cell-transverse wire port), this port covers the full width × height cross-section under the trace and uses 3-probe numerical de-embedding to extract β and Z0 empirically downstream of the feed plane.

Parameters

position : (x, y, z_lo) Physical feed-plane point. The coordinate on the PROPAGATION axis (named by direction) is the feed plane; the coordinate on the other in-board axis is the trace centre; z is the substrate bottom. So a "+x" port reads it as (x_feed, y_centre, z_lo) and a "+y" port as (x_centre, y_feed, z_lo). width : float Trace width in metres, spanning the in-board axis that is NOT the propagation axis (y for an x-directed port, x for a y-directed one). height : float Substrate thickness in metres — always the z extent, because the substrate normal is fixed to z (see direction). direction : str One of "+x", "-x", "+y", "-y" — the direction the launched wave propagates. The board lies in the xy-plane and the substrate normal is always z, so the feed may run along either in-board axis (issue #661: a CAD-imported board does not get to choose its orientation).

``"+z"`` / ``"-z"`` are REJECTED with a clear error rather
than supported: a z-propagating microstrip needs its
substrate normal along x or y, which ``position`` + scalar
``height`` cannot express, and which the Laplace mode solve,
the ``"ez"`` source component, the modal voltage
``V = Σ Ez·dz`` and the trace-conductor PEC scan all assume.
Accepting it would return a z-normal answer for a board that
is not oriented that way.

``mode="eigenmode"`` remains ``"+x"``/``"-x"`` only.

impedance : float Target Z0 in ohms (default 50). Used for the σ distribution. waveform : GaussianPulse or callable, optional Excitation waveform. Defaults to a band-limited Gaussian centred at freq_max/2. Ignored when excite=False. excite : bool True → resistive termination + active source; False → passive matched termination only. n_probe_offset : int, optional Distance (cells) from the feed plane to the first probe plane. Automatic offset and spacing counts are recomputed at driver time in the cells under the port, including graded runways, uniform dy_profile different from dx, and auto meshes. A ladder crossing a grading ramp retains counts based on scalar dx. When None, bound to the LARGER of two near-field clearances: (a) the wavelength reactive far-field (issue #80 Fix B), round(0.5 * lam_min_eff / (2*pi) / dx) with lam_min_eff = c / freq_max / sqrt(eps_r_sub_estimate); and (b) the source FRINGING transient round(5 * h_sub / dx), which decays over a few substrate thicknesses (h_sub = the port height), NOT over λ. For a thin high-εr substrate (b) dominates: clearing only (a) leaves probe 0 inside the fringing transient and corrupts the V·I-split S11 of a high-Q resonant load (issue #80 patch: |S11|=8.94/1.11 → passive ~0.99 once cleared). These two terms are only the UPSTREAM (lower) edge: at compute_msl_s_matrix time the auto default additionally solves the DOWNSTREAM constraint (issue #469) — the deepest probe must stay ≥ λ_g/4 (at freq_max) clear of the nearest reflector — picking the midpoint of the compliant interval when a reflector bounds it, keeping the upstream edge when none does, and warning loudly when the interval is empty (the feed line is too short for a clean N-probe measurement). Pass an explicit value to override (explicit values are never adjusted); < 5*h_sub/dx triggers a preflight near-field warning. n_probe_spacing : int, optional Distance (cells) between consecutive probe planes. Automatic counts use the same driver-time runway recount as the offset. When None, bound so the total N-probe array span stays ~lam_min_eff/8 independent of n_probes: round(lam_min_eff / 8 / (n_probes - 1) / dx). For n_probes=3 this is exactly lam_min_eff/16 (issue #80 Fix B). Shrinking the adjacent spacing as n_probes grows keeps the probe array from running off short lines.

An AUTO spacing is additionally WIDENED at driver time
(issue #681): ``compute_msl_s_matrix`` /
``compute_mixed_s_matrix`` re-solve it toward a total span of
``(n_probes−1)·λ_g(f_max)/4`` (λ_g from the HJ ε_eff), capped
by the downstream-reflector interval and the absorbing
boundary — a ~0.1·λ_g span leaves the β fit noise-fragile
(measured: median β error 5.5% at 0.10 λ_g vs 0.8% at
0.30 λ_g under 1% probe noise). An explicit value is never
touched.

n_probes : int Number of equally-spaced voltage probe planes registered for the N-probe least-squares wave-decomposition extractor (issue #80 Fix C). Probe n sits at offset + n*spacing cells from the feed plane. N >= 3 is required; the default 5 over-determines the 2-unknown (alpha, gamma) fit, which removes the 3-probe quadratic's q→1 singularity. The current probe at probe 0 is always recorded for the absolute Z0. name : str, optional Port label used in result dicts. Auto-generated when omitted. eps_r_sub : float, optional Substrate relative permittivity. Used both for the eigenmode source and as eps_r_sub_estimate for the wavelength-bound probe-placement defaults (issue #80 Fix B). When None the estimate is resolved from the dielectric geometry already registered under the port (a shape whose bounding box contains the substrate mid-point and whose material has eps_r > 1); if no such dielectric is found it falls back to 1.0, which is conservative (largest lam_min_eff → largest offset).

Add a lumped RLC element at a single cell.

The element is modelled via Auxiliary Differential Equations (ADE) that are updated each timestep alongside the standard Yee update. Any combination of R, L, C is valid (set unused components to 0).

Parameters

position : (x, y, z) in metres component : "ex", "ey", or "ez" R : float Resistance in ohms (default 0). L : float Inductance in henries (default 0). C : float Capacitance in farads (default 0). topology : "series" or "parallel"

Notes

For series topology with a single component (e.g., pure L with R=0 and C=0), the element is handled via material folding, not the full series ADE current tracker. To ensure the series ADE path is used, specify at least two non-zero components.

Add a normal-incidence plane-wave TFSF source.

Current scope is intentionally narrow: x-directed propagation, ez/ey polarization, 3D mode, and CPML boundaries. For oblique incidence, only the single transverse-axis plane implied by the chosen polarization is supported.

Parameters

closed_box : bool Use a finite six-face total-field box with CPML on all three axes. Normal incidence, uniform 3D Yee only. The default keeps the historical x slab with periodic y/z. Read the realized inclusive node bounds with tfsf_box_indices(). waveform : {"differentiated_gaussian", "modulated_gaussian", "continuous_wave"} Pulse shape injected into the 1D auxiliary grid. (continuous_wave is only supported at normal incidence — angle_deg == 0.)

``differentiated_gaussian`` (default, legacy rfx): baseband
pulse with no carrier, DC-free, spectrum peaks near
``f0·bandwidth``. Good for broadband measurements but
spectrum extends well below ``f0``.

``continuous_wave``: a single-frequency sinusoid at ``f0`` with a
raised-cosine turn-on (~8 periods), then constant amplitude. Use for
steady-state / narrowband measurements that need a well-defined
time-average ``⟨E²⟩ = A²/2`` (e.g. the quantitative Kerr SPM oracle,
#446). Not for broadband S-parameters — it excites only ``f0``.

``modulated_gaussian``: carrier-modulated Gaussian matching
Meep's ``GaussianSource(frequency=f0, fwidth=f0·bandwidth)``.
Spectrum is a Gaussian centered at ``f0`` with 1/e
half-width ``f0·bandwidth``. Use this for matched rfx-vs-Meep
crossval comparisons.

A ``CustomWaveform`` may supply a fixed, JAX-compatible real
scalar function of time, multiplied by ``amplitude``. It is
added to the auxiliary E node at ``t=n*dt``; it is not the
launched E amplitude. Normal incidence only; use a fixed
record length (``until_decay`` has no source-off contract).
These new source inputs support ordinary ``forward`` and its
internal checkpoints. External JAX transformations, including
grad/value_and_grad/JVP/vmap/jit/checkpoint/scan, are refused:
transformed scattered-field traces do not meet the cross-trace bar.

method : {"bloch", "methodB"} Oblique-incidence engine (ignored for angle_deg=0, which always uses the normal 1D-aux path). "bloch" (default) is the narrowband complex-Bloch 2D-aux path (fields go complex64; frequency-domain monitors are not transform-aware — see tfsf_2d.py). "methodB" is the open-domain oblique path (real float32, 1D-aux-along-k̂ + 4-edge box): the transverse axis becomes OPEN/CPML, z stays thin periodic (2.5-D, z-invariant far field), and NTFF/DFT/flux monitors read physical fields. "methodB" currently requires polarization='ez' and a single-device uniform grid.

Realized inclusive total-field node bounds on the padded grid.

The normal slab returns x only; closed_box=True returns x/y/z. NTFF cell-centre interpolation must clear these bounds, including the adjacent Yee samples (the NTFF placement check enforces this).

Add a rectangular waveguide port.

x_position is interpreted along the selected port-normal axis from direction. For example, direction='-y' uses x_position as the physical y-coordinate of the port plane.

Current scope supports axis-normal boundary ports using rectangular apertures, with boundary='cpml' and mode='3d'.

Calibration options:

• reference_plane / probe_plane: explicit reported planes in physical coordinates along the port normal axis
• calibration_preset='source_to_probe': auto-report S11 at the snapped source plane and S21 from source to the snapped probe plane
• calibration_preset=None or 'measured': use the snapped stored reference/probe planes directly

Sampling still occurs on the nearest snapped grid planes, and the result metadata reports those actual measurement planes explicitly.

waveform selects the source pulse shape. Default "modulated_gaussian" is the Meep-style bandpass pulse — no sub-cutoff DC content, so the in-band TFSF filter collapses to identity, reducing directional leakage in the H+E injection pair. "differentiated_gaussian" matches historical (legacy) rfx behaviour. Preliminary measurement shows directionality backward/forward ratio 13.3 % → 8.2 % for a WR-90 at f₀=10 GHz; further gains await the discrete-eigenmode profile work (P3).

Return the B1 face declaration with the current feature requirements.

No runner consumes this descriptor in B1. rcs=True collects the RCS requirement for a caller preparing that operation.

Add a Floquet port for periodic structure / phased array analysis.

The Floquet port injects a plane wave at the given scan angle and extracts Floquet mode amplitudes (S-parameters) from the unit cell response. Requires periodic BC on the two axes perpendicular to the port normal.

Parameters

position : float Physical coordinate along the port normal axis (metres). axis : str Port normal axis: "x", "y", or "z". scan_theta : float Scan angle theta from broadside (degrees). Default 0. scan_phi : float Scan angle phi in the transverse plane (degrees). Default 0. polarization : str "te" or "tm". Default "te". n_modes : int Number of Floquet modes to extract (default 1 = specular). freqs : array or None Analysis frequencies. Auto-generated if None. n_freqs : int Number of frequency points when freqs is None. f0 : float or None Source center frequency. Default: freq_max / 2. bandwidth : float Source fractional bandwidth. Default 0.5. amplitude : float Source amplitude. Default 1.0. name : str or None Optional name for the port. Auto-generated if None.

Add a point field probe.

Add a vector probe that records ALL 6 field components.

Records Ex, Ey, Ez, Hx, Hy, Hz at the same position. Results accessible via result.time_series columns [0..5].

Add a frequency-domain 2D plane probe.

Parameters

axis : "x", "y", or "z" Plane normal axis. coordinate : float Physical coordinate in metres along the selected axis. component : field component name One of ex/ey/ez/hx/hy/hz. freqs : array or None Probe frequencies in Hz. Default: linspace(freq_max/10, freq_max, n_freqs). n_freqs : int Number of frequencies if freqs is None. region : tuple or None Half-open transverse array-index crop (lo1, hi1, lo2, hi2). A 1 by 1 crop is a point DFT at that Yee component. name : str or None Optional result key.

Add a Poynting flux monitor on a plane (Meep flux-region equivalent).

Accumulates frequency-domain E and H tangential components to compute integral Re(E x H*) . n_hat dA at each frequency.

Parameters

axis : "x", "y", or "z" Plane normal axis. coordinate : float Physical coordinate in metres along the selected axis. freqs : array or None Monitor frequencies in Hz. n_freqs : int Number of frequencies if freqs is None. size : (float, float) or None Positive finite extents in the two tangential directions. A finite window snaps to cell edges, clamps to the physical interior with a warning on any clamp, and excludes CPML/bounding-node slots. None means the full allocated plane (legacy behaviour). center : (float, float) or None Physical centre of the flux region in the two tangential directions. None defaults to the declared domain midpoint on uniform grids and the realized interior midpoint on graded grids. For example, for an x-normal monitor the two tangential axes are (y, z). Exactly two finite values are required. Preflight reports finite requested/realized bounds in metres through report.flux_regions. name : str or None Result key. Default: flux_{axis}_{idx}.

Add a near-to-far-field transform box for radiation patterns.

Parameters

corner_lo, corner_hi : (x, y, z) in metres Opposite corners of the Huygens box. freqs : array or None Frequencies (Hz). Default: n_freqs points from freq_max/10 to freq_max. n_freqs : int Number of frequencies if freqs is None.

Accumulate the structure's own current as block moments, in-loop.

The radiation of a structure is what the current in it radiates. On the Yee lattice that current is an identity the solver already enforces — J = curl_h H - eps0 dE/dt at every electric-field edge — so it can be read off the fields the step is holding, with nothing modelled and nothing fitted. This monitor sums it over the slab between corner_lo and corner_hi into a few numbers per in-plane block (the total current moment and its first two spatial moments about the block's own centre) and DFTs those, instead of accumulating tangential E and H over a Huygens surface.

Parameters

corner_lo, corner_hi : (x, y, z) in metres Opposite corners of the slab, in the same frame as add_ntff_box(). The z range picks the node planes; the whole thickness goes into one block. block_size : float In-plane block side in metres, rounded to a whole number of cells. The realized side is what the monitor reports. freqs : array Frequencies (Hz). order : int 2 (the only accepted value) keeps P, Q and T — 30 numbers per block. Lower orders are refused; the low-level rfx.current_moments.build_current_moment_monitor keeps them.

Notes

margin_cells : int or (mx, my, mz) Extra cells around the declared corners. off_cells : int Shift of the in-plane partition origin, in cells. 0 and half a block are the two the block rule was measured with.

Notes

The slab must lie in the interior: inside the absorber the E update is not Ampere's law, so a current read there is the absorber's fiction. Periodic/Bloch axes, TFSF sources, stencil_order=4, a graded or dx != dy in-plane mesh, a traced mesh profile, and every lane whose scan body does not accumulate the monitor are refused rather than approximated. So is a model the pattern would silently leave out: magnetic material (mu_r != 1), a PEC or PMC domain face, a waveguide, coaxial or Floquet port, a microstrip port with mode="eigenmode", and any dielectric, conductor, dispersive cell, port, lumped element or source that is not inside the slab (its outermost edge layer counts as outside).

The named arguments here are the whole public surface. The low-level builder additionally takes deliberately wrong metrics, centres, curl signs and time stamps so the mutation harness can measure what the declared checks catch; those never reach a user's declaration.

Finalize mesh spacing/profiles and extent, returning the selected grid.

Call after adding mesh-driving materials/geometry and before placing lattice-aligned conductors. Later geometry cannot refine this mesh; unresolved features still raise under the normal conductor contract. Repeated calls preserve the same mesh. Build a new Simulation to remesh.

Grid previews (including preflight) alone do not finalize the mesh. Register boundary conditions and ports before retaining grid indices: port registration may change padding, though physical node positions in the domain stay fixed. Caller declarations remain available unchanged.

Return a consolidated mesh-quality and memory-planning report.

The report is intentionally advisory: it reuses preflight() for physics/geometry warnings, reuses estimate_ad_memory() when n_steps is provided, and adds a uniform-fine comparator that estimates how many cells a globally fine mesh would need if it used the minimum cell size present in any non-uniform profile.

This is the Stage-1 production-near "subgrid-like" planning surface: it helps users decide whether existing non-uniform mesh plus segmented checkpointing is enough before attempting research-only true subgridding.

checkpoint_every and checkpoint_segments are forwarded to the same AD estimator used by plan_ad_memory(); they are mutually exclusive. n_warmup is forwarded as reverse-mode tape metadata only, matching estimate_ad_memory.

Return an advisory mesh plan for this configured simulation.

Create a Simulation with auto-derived parameters.

Parameters

freq_range : (f_min, f_max) in Hz Analysis frequency range. All parameters (dx, domain, CPML, n_steps) are derived from this. accuracy : "draft", "standard", or "high" **kwargs : additional Simulation constructor args (override auto values)

Returns

Simulation with optimal configuration for the frequency range.

Example

>>> sim = Simulation.auto(freq_range=(1.5e9, 3.5e9))
>>> sim.add(Box(...), material="pec")
>>> result = sim.run(until_decay=1e-5)
>>> modes = result.find_resonances()

Run all pre-simulation checks and return warnings.

Resolves and caches the mesh from the current static declaration, without changing declared dx/domain/profiles. Auto-mesh selection is emitted as a UserWarning, separately from validation findings.

Parameters

strict : bool If True, raise ValueError on the first issue instead of collecting warnings. check_ntff : bool or "advisory" True (default): run the full NTFF check family (PEC-overlap hard error + λ/4 / λ/2 near-field gap advisories + the sub-wavelength ground-plane pattern advisory, issue #334). "advisory": run only the advisories — the tier run() uses, because the λ/4 and small-ground-plane warnings are physics-relevant to any far-field computation while the PEC-overlap hard error remains an inverse-design gate (issue #303). False: skip the family entirely. check_resolution : bool Run the tightened resolution check (existing _validate_mesh_quality uses per-material thresholds already — this flag kept for symmetry and future tightening). Default True. check_ad_memory : bool Run AD memory estimate and warn if > 85% of available VRAM. Requires n_steps_for_memory. Default False (diagnostic only). n_steps_for_memory : int or None Step count for AD memory sizing. Required when check_ad_memory. available_memory_gb : float or None Override VRAM detection. If None, best-effort via JAX devices.

Returns

PreflightReport A list subclass of PreflightIssue (each a str subclass), back-compatible with the legacy list[str] return. Empty if no issues found. Finite flux-window geometry is recorded separately in flux_regions, including for issue-free reports.

Preflight the selected S-parameter calculator without running FDTD.

This is a routing/contract check for the port-family-specific S-parameter APIs. It answers "which calculator should this simulation use?" before an expensive run starts:

• calculator="run" checks run(compute_s_params=True) for lumped/wire add_port(...) families.
• calculator="forward" checks forward(port_s11_freqs=...) for uniform single-device S11 vectors.
• calculator="msl" checks compute_msl_s_matrix(...).
• calculator="waveguide" checks compute_waveguide_s_matrix(...).

Parameters

calculator: One of "run", "forward", "msl", or "waveguide" (the corresponding method names are accepted as aliases). strict: If True, escalate ERROR-severity findings to a raise: collect everything, then raise a single ValueError listing the errors (aggregate-then-raise). The underlying NotImplementedError is recorded as an error-severity issue and re-surfaced as part of that aggregated ValueError (its exact type is not preserved).

Errors only, not "any issue": the waveguide setup audits report
advisory and informational findings on a perfectly valid routing,
and a healthy two-port guide ALWAYS carries the informational
E-plane note, so escalating on emptiness would make
``strict=True`` raise on every correct waveguide setup. Advisories
are still returned in the report and printed; read them there.
(This differs from ``preflight(strict=True)``, whose report has no
informational tier.)

normalize: Waveguide non-uniform preflight uses this to mirror compute_waveguide_s_matrix(normalize=...). None means the method default, currently False. include_general: If True, append the ordinary geometry/material preflight() issues after the S-parameter routing check.

Returns

PreflightReport A list subclass of PreflightIssue (back-compatible with the historical list[str]). Carries no ERROR-severity issue when the selected calculator is valid for the registered port families — read report.ok / report.errors rather than emptiness. calculator="waveguide" additionally runs the three setup audits (_validate_cfg_record_vs_far_boundary(), _validate_cfg_port_index_mirror_covariance() and _validate_cfg_layout_from_band_low_edge()), which report advisory and informational findings on a perfectly valid routing — a healthy two-port guide always carries at least the known E-plane-offset note. Those audits are evaluated at compute_waveguide_s_matrix's own default num_periods (WAVEGUIDE_DEFAULT_NUM_PERIODS); the record-length message names the num_periods that clears the threshold, which does not depend on the value it was evaluated at.

Compute MSL S from probe-plane V/I with fitted line diagnostics.

Returned S uses power waves for the positive real per-port analytic references: a=(V+RI)/(2sqrt(R)), b=(V-RI)/(2sqrt(R)). reference_impedances records those R values separately from the fitted Z0 and source/load resistances. For unequal references, transmission S differs from the legacy voltage ratio by sqrt(R_input/R_output); equal-reference results are unchanged.

S is the RAW extracted S-matrix on every channel — concrete, eps_override, traced — and the default enforce_passivity=False is what makes that one statement instead of three. The projection below cannot run under tracing or on the eps_override channel (it would zero the gradient wherever the clip bites), so while it was the default the S a caller measured and the S jax.grad differentiated were different functions wherever it bit. One function, chosen to be the measured one (PI decision, 2026-09-21; the contract is docs/design_notes/chain_closure_contract.md).

A raw S may exceed the passive bound, and the result says so rather than hiding it: sigma_max_excess[k] = max(sigma_max(S(f_k)) - 1, 0) is filled on every concrete call (None only under tracing), and a warning names the bin count and the worst sigma_max whenever any bin exceeds 0. A passive structure cannot scatter more power than it receives, so such a bin is a measurement artifact — the usual causes are a record that ended before the structure rang down and a mesh too coarse for the geometry (settling_db and reliable say which).

enforce_passivity=True opts back into the post-process: the assembled S(f) is projected onto the passive set per frequency (singular values clipped to 1 — the nearest matrix in spectral norm with ||S||_2 <= 1), the unprojected matrix is kept in S_raw, the per-bin clip amount in passivity_correction, and a warning names the touched bins. It is constraint enforcement, not a physics fix, and it is NOT small where the raw extraction is bad: on a thru fixture whose raw sigma_max ran 1.19-1.91, projecting moved |S21| 1.000 -> 0.61-0.72 and rotated its phase by up to 17 degrees, while Z0 and beta stay raw. Never quote projected values as physics where passivity_correction is large.

EXEMPTION (unchanged): even with enforce_passivity=True no projection is applied under tracing or on the eps_override channel (traced or concrete), so that finite-difference and jax.grad objectives see the same function; S is then the raw extraction with S_raw/passivity_correction absent and no projection warning. sigma_max_excess is still filled on the concrete eps_override channel, so the bound violation stays visible there (measured sigma_max 1.18 on a coarse thru).

Surface-impedance sheets (add_thin_conductor(..., surface_impedance_f0=...)) are supported on this lane (#677/#679): the sheet is realized node-thin by the per-step operator inside the run()/forward() device dispatches — no lane-level ctx is built here. Combination refusals fire downstream at whichever lane entry the call actually reaches, and the two channels carry their OWN copies: on run() the dispersive-substrate and boundary='upml' refusals come from run_uniform with run-lane wording, while the forward() / eps_override channel never enters run_uniform and raises instead from the forward-lane entry in rfx/api/_execute.py, naming that lane. #679 added the upml half there: before it, an eps_override call on a boundary='upml' sim silently ran the very combination run() refuses (the sheet operator overwriting UPML's split-field E update at its edges). ADI refuses on both channels through the shared refuse_f0_sheets helper; the subgridded and distributed lanes carry their own call sites at whichever entry reaches them — FENCE_REGISTRY in tests/unit/materials/test_sheet_impedance.py is the authoritative per-lane list, AST-guarded against drift. subpixel_smoothing / conformal_pec are run()-only keywords, so that combination is unreachable on the eps_override channel rather than refused there. The TRACE must remain PEC: an f0 sheet realizes no PEC edge, and the closed Ampere-loop current and the V span anchor on the realized PEC wall planes (#931 §1.9 — a PEC trace may be a volume Box or a sheet; both are found). The Hammerstad-Jensen beta/Z0 anchors and the real-beta N-probe fit assume a lossless line, so a sheet lying INSIDE a probed span adds per-length loss the fit cannot represent — reported Z0/q shift (the Z0 honesty guard may warn) while the V-I production S stays valid. A non-z-normal sheet (x/y-normal) carries Ez in its tangential edge set: crossing the feed plane or the V-integration column it legitimately modifies the measured/launched Ez — place sheets clear of feed and probe planes.

For each registered MSL port, runs one FDTD simulation with that port driven and the others passive. The passive ports are NOT assumed matched — |a_passive/a_driven| = 0.243-0.248 at the shipped R = 50 Ω (0.19-0.93 across terminations), re-measured on current main 2026-08-30 (#524, VESSL 369367257265, PR #799; the July figure quoted here before was 0.07-0.51) — so the S-matrix is recovered by solving the full wave system S = B·A⁻¹ over all drives rather than by the per-column ratio b_j/a_d (issue #507; the ratio reported the far port's echo as the structure's own reflection). At each port n_probes downstream DFT plane probes record Ez and the first probe also records the transverse H components for a closed Ampere-loop current. Production S is formed from this first-plane V/I and the analytic Hammerstad-Jensen reference impedance. The N-probe least-squares fit of V_n = α e^{-jβx_n} + γ e^{+jβx_n} supplies only the reported beta/Z0 diagnostics. Those fitted values do not enter S. S is referenced to each first probe plane, without translation back to the physical feed planes. The two bracketing H planes are linearly interpolated to the E-node using their physical coordinates, then the leapfrog temporal offset is corrected. Comparing different observation offsets still requires accounting for reference planes and impedances. probe_clearance reports the separate downstream layout recommendation; it is not a signal or accuracy score.

Parameters

n_steps : int or None Timesteps per FDTD run. None → auto from num_periods. num_periods : float Source-period multiples used to derive n_steps when not provided. Default 40 (MSL transients are slow to drain). freqs : array, optional Frequency grid. Defaults to linspace(freq_max / 10, freq_max, n_freqs). n_freqs : int Number of frequencies if freqs is None. raw_3probe_dump_path : str or None Optional .npz path. When provided, write the real simulation-derived N-probe voltage/current phasors used by the extractor, together with the production power-wave S-matrix, so the de-embedding can be independently checked without rerunning FDTD. The dump schema is rfx.msl_nprobe_dump v4: it explicitly records the power-wave convention and actual reference impedances. Legacy v3 records use voltage waves. raw_v has shape (n_driven, n_ports, n_probes_max, n_freqs). scripts/diagnostics/replay_msl_3probe_dump.py is SUPERSEDED for modern dumps (it expects the retired 3-probe/single-ratio v1 schema). Use rfx.validation.load_port_vi_dump_npz and replay_smatrix_from_port_vi_dump for independent S replay. strict_extractor : bool Honesty guard for the de-embedding (issue #80 Fix A). After extraction, the per-frequency |q| and extracted Z0 are validated against physical bounds (|q| <= 1 for a passive line; extracted Z0 within 10 % of the analytic Hammerstad-Jensen value). When False (default) a violation raises a loud warnings.warn(); when True it raises ValueError instead. With the N-probe extractor (Fix C) |q| and Z0 should be healthy so this rarely fires — it is the safety net for pathological geometries. enforce_passivity : bool Opt into the passivity projection as a post-process. False (default) returns the raw extracted S; see the section above for what each setting costs and which channels the projection can reach. Changed from True on 2026-09-21. checkpoint_segments : int or None Gradient-checkpointing segment count for the reverse-mode AD tape on the uniform mesh (the standard MSL path), forwarded to forward() (only active on the differentiable eps_override channel). Must DIVIDE the auto-computed n_steps exactly — padding is rejected because it would shift the DFT accumulator windows. Choose the divisor nearest sqrt(n_steps) so backward memory scales ~sqrt(n_steps)*carry instead of n_steps*carry — required for converged num_periods>=20 AD that otherwise OOMs (G-AD-CHECKPOINT). Default None leaves forward-only runs and small-period AD unchanged. checkpoint_every : int or None Non-uniform-mesh counterpart of checkpoint_segments (chunk size, not segment count; issue #73). Forwarded to forward(); raises NotImplementedError on the uniform path — use checkpoint_segments there. report_every : int or None Issue #667 — progress reporting for long solves. Forwarded to each per-drive run() call, tagged MSL drive pI/N so the drives are distinguishable in a log. None (default) is OFF and leaves the solve byte-identical. The measured case this exists for: a 42.15 M-cell / 225,000-step call whose last log line was written at second 0 and was still the last line 4 h 10 min later, with no way to tell slow from wedged. Ignored (with a warning) on the differentiable eps_override channel, which routes through the traced forward().

Returns

MSLSMatrixResult

One-port coaxial reflection on a real transmission line (broad-E5).

Builds a coextensive coax line (face='top', pin along -z) terminated in a matched resistive feed near the +z boundary, drives a TEM TFSF source one cell below the feed, and reflects off a calibration termination at the -z end: "short" (Γ=-1), "open" (Γ=+1), or "matched" (Γ→0). With termination="matched" and dut_impedance=R the DUT is instead a known resistive load (analytic Γ=(R-Z0)/(R+Z0)) — used by the broad-E5 envelope to test non-trivial reflection magnitudes against exact truth. The reflection is read from the modal voltage V(z)=∫E_r dr sampled at probe_count equally spaced planes and a matrix-pencil estimate of the complex propagation constant (β self-measured, Z0-free).

Unlike the single-plane coaxial lane removed in #1212 (V/I in a hardcoded closed PEC box — non-physical |S11|>1), this uses an absorbing CPML feed so a real line exists. Resolution recipe: keep ≥~4 cells across the (outer-inner) annulus (raise freq_max to shrink dx); the result status reports "under_resolved" below ~3.5 cells.

The conductors deliberately stop ~2 cells short of the +z PML — running PEC into CPML is numerically unstable.

The line sits in open space: the run absorbs on all three axes (cpml_axes=None reads the grid; all three axes are required), so what leaves the line's unshielded ends — the open termination, and the pin and shell ending one cell past the matched feed — is absorbed as it would radiate from a cable. cpml_axes="z" is refused: it left the lateral pads as vacuum backed by the PEC grid faces, a closed metal can that held that field, and the open's |S11| rose above 1 and grew with the record (issue 1218).

The enclosing Simulation must use float32 precision and the three-dimensional, second-order uniform Yee solver with boundary="cpml" and cpml_layers > 0. Unsupported precision, solver, grid, boundary, TFSF, and refinement settings raise before the grid is built. The run requires positive CPML thickness on all six faces and no periodic-axis override, and the line's conductors must keep at least one whole cell from every lateral absorber (the stamper refuses a line without that room).

This method constructs its own coaxial line, TEM source, DFT planes, and termination. Do not add separate geometry, thin conductors, lumped RLC elements, probes or field monitors, or NTFF boxes; those registrations are rejected rather than ignored. Use the documented Simulation, port, and method arguments instead.

The registered coaxial port supplies its x/y centre, face, inner and outer radii, and excitation waveform. The method derives its axial layout internally, so the port's z coordinate and pin_length do not place the line, and the port's impedance does not set either load. Use feed_impedance for the feed and dut_impedance only with termination="matched". probe_count must be an integer of at least three, and every requested plane must fit between the DUT and source; otherwise the method raises before starting the FDTD run.

Differentiable (eps_scale)

Pass eps_scale (a scalar or (nx, ny, nz) jnp array) to make the reflection differentiable w.r.t. the dielectric under jax.grad. It MULTIPLIES the stamped eps_r (eps_r <- eps_r * eps_scale), applied AFTER the numpy conductor/dielectric stamps so the fixed geometry (PTFE fill in eps_r, PEC pin/shell in sigma) is preserved and only modulated — a well-conditioned design channel (unlike replacing the fill with air). When provided, the field→voltage→reflection assembly runs on the jax.numpy path (coaxial_line_plane_voltage_jnp + the traced extractor) so the gradient flows design → FDTD → DFT planes → Γ. With eps_scale=None the result is byte-identical to the validated numpy path. The AD↔FD gate is tests/unit/autodiff/test_coax_end_to_end_ad.py.

Two-drive coaxial 2-port S-parameters (#489 stage 2) — VALIDATED WITH SCOPE.

Builds ONE through coax line spanning the z axis with a matched annular-resistor feed near EACH z end (mirroring the validated 1-port compute_coaxial_line_reflection() layout at both ends: each feed sits between that end's own TEM TFSF source and that end's own CPML, i.e. strictly on the scattered-only side of that drive's TFSF boundary — never in the path of that drive's own launched wave), then drives each end's source in turn (two separate FDTD runs). A probe array of probe_count equally spaced planes near each end recovers that array's local two-wave decomposition (matrix-pencil, Z0-free, same machinery as the 1-port method); the forward/back amplitudes are evaluated at each port's OWN reference plane (its feed's axial position) and assembled into a full 2x2 S-matrix via rfx.sources.coaxial_port. solve_two_port_from_wave_amplitudes() — the two-drive solve that does NOT assume the non-driven port sees zero incident wave (unlike the naive S[j,i] = b_j/a_i ratio, which has a hard terminator- reflection floor on a through line; see that function's docstring and docs/research_notes/20260729_i489_coax_two_port_design.md).

Port 1 is the +z end (mirrors the 1-port fixture's own face='top' orientation); port 2 is the -z end (mirror image, face='bottom'). Both drives share the SAME registered add_coaxial_port(...) geometry (x/y centre, pin/outer radii) and excitation waveform; the registered port's own position/face/pin_length do not place either end of the line (mirrors the 1-port method's own contract). Requires port.face == 'top' (arbitrary but consistent with the 1-port method; the value is not otherwise used to orient this method's own internally-built fixture).

Unlike the 1-port method, the returned result is routed through _finalize_sparam_result() (which runs the passivity/finiteness self-check via _warn_if_nonpassive_smatrix()) before being returned — the 1-port CoaxialLineReflectionResult bypasses that check (design-note incidental defect 3); this result does not.

This method constructs its own coaxial line, TEM sources, DFT planes, and feeds. Do not add separate geometry, thin conductors, lumped RLC elements, probes or field monitors, NTFF boxes, or TFSF sources; those registrations are rejected rather than ignored.

Same solver/precision/boundary contract as compute_coaxial_line_reflection() (float32, 3D uniform Yee, boundary='cpml' with positive CPML thickness on all six faces, cpml_axes='xyz', no periodic axes, no non-uniform mesh, no refinement). The run absorbs on all three axes: the line's two ends, one cell past each feed, are unshielded, and with absorbers on z only the lateral pads were a closed PEC can that held the field leaving them (issue 1218). cpml_axes='z' is refused.

Differentiable (eps_scale, #489 leg 3)

Pass eps_scale (a scalar or (nx, ny, nz) jnp array) to make the S-matrix differentiable w.r.t. the dielectric under jax.grad — same name, semantics, and MULTIPLIES-the-stamped-eps_r design as the 1-port compute_coaxial_line_reflection()'s own eps_scale (eps_r <- eps_r * eps_scale, applied once, after both feed stamps, so it reaches BOTH drives' FDTD runs — the through line has no DUT break to scope it to). When provided, both drives route their voltage extraction through rfx.sources.coaxial_port. coaxial_line_plane_voltage_jnp() (the same differentiable twin the 1-port path uses) instead of the concrete ~rfx.sources.coaxial_port.coaxial_line_plane_voltage(), and the assembly (_assemble_coaxial_two_port_from_voltages()) and the two-drive solve (~rfx.sources.coaxial_port. solve_two_port_from_wave_amplitudes()) both dispatch to their own jnp cores. With eps_scale=None the result is byte-identical to the validated numpy path (dual-path design, not a rewrite — mirrors the 1-port method's own contract). The per-drive ring-down settling_db witness needs a concrete time series and is skipped on this path (stays nan, same reasoning as the 1-port method's own "can't Python-branch on a tracer" note on its rec_resid contamination check); status is therefore "under_resolved" or "differentiable" here, never "contaminated"/"passed". cond_warn is also silently INERT on this path: the ill- conditioning warning it controls is Python control flow keyed on a concrete cond(A) value (rfx.sources.coaxial_port.solve_two_port_from_wave_amplitudes()'s NumPy branch), which the traced jnp core (_solve_two_port_from_wave_amplitudes_jnp) cannot evaluate and does not attempt to — this mirrors the settling_db/status losses above (same "can't Python-branch on a tracer" reason), not a separate defect; cond_a is still RETURNED (as a tracer), so a caller can inspect it after concretizing the result if degeneracy matters to them. The AD gate is tests/unit/autodiff/test_coax_two_port_ad.py.

extra_flux_monitors (issue #589 flux-adjudication instrument): an ENERGY-WITNESS channel, not an extractor change. Pass the entry objects Simulation.add_flux_monitor registers (build them on a scratch Simulation with the same domain and hand over its ._flux_monitors); each internal drive run then accumulates the requested Poynting-flux planes, and per-drive spectra come back name-keyed on result.flux_monitors ({port_name: {monitor_name: (n_monitor_freqs,) float64}}, net flux, positive = +axis). The S-parameter math is untouched — the non-perturbation witness (S bit-identical with and without monitors) is gated in tests/unit/sparams/test_coax_msl_transition.py::test_extra_flux_monitors_do_not_perturb_s. The registered-monitor guard is unchanged: monitors registered ON this sim still raise, because this method builds its own probes.

EXPERIMENTAL coax<->microstrip transition 2-port S-parameters (issue #489 leg 4).

Generalizes issue #488's mixed lumped/wire<->MSL assembler (compute_mixed_s_matrix()) to a coax<->MSL pair by combining, UNCHANGED, the less-invasive half of each family's own validated machinery instead of writing a new geometry-specific extractor:

• The coax side is built exactly like compute_coaxial_two_port()'s own single-ended stub (CPML, TEM TFSF source, matched annular- resistor feed, then a probe array), reusing ~rfx.sources.coaxial_port.stamp_coaxial_line(), ~rfx.sources.coaxial_port.stamp_coaxial_annular_resistor(), and ~rfx.sources.coaxial_port.build_coaxial_tem_plane_source_specs() verbatim — but only ONE end (this method has no second coax port).
• The MSL side is consumed exactly like compute_mixed_s_matrix() consumes its MSL ports: the caller registers arbitrary DUT geometry (substrate, trace, ground plane, and — unique to this transition — the ground-plane clearance hole and the vertical pin-to-trace post that connects the two families) via the ordinary sim.add(Box(...)/Cylinder(...), material=...) API, and this method reuses ~rfx.sources.msl_port.compute_msl_mode_profile(), ~rfx.sources.msl_port.setup_msl_port(), and ~rfx.sources.msl_port.make_msl_port_sources() verbatim for the MSL port's own termination/excitation.

This method does NOT build the junction geometry itself (the ground plane, its clearance hole, or the pin-to-trace post) — those are DUT-specific and belong to the caller's own registered geometry, exactly as compute_mixed_s_matrix() never builds its own substrate/trace. What this method DOES fix, by construction, is WHERE each port's own S-parameter reference plane sits: both are placed AT the physical launch discontinuity (see junction_x below and port.position[2] on the registered add_coaxial_port()), specifically to minimize the pre-declared "reference-plane mismatch" failure mode (the coax's axial z-feed-plane convention has no direct analogue in the MSL's along-trace x reference plane — these are different geometric axes entirely).

Registration contract

Exactly one add_coaxial_port() (face='bottom' — the physical convention this method assumes: the coax stub is built FROM the domain's low-z CPML face UP TO position[2] (rounded to the nearest grid z-node, half-cell ties to the lower node under the conductor-plane convention), where position[0], position[1] is the coax axis centre (x, y) and position[2] is the physical height of the caller's OWN registered ground-plane conductor — i.e. this is the ONE parameter that ties this method's auto-built coax stub to the caller's own junction geometry; get it wrong and the pin will either dangle in a gap or overlap the caller's own PEC). Exactly one add_msl_port(), whose position[2] (substrate bottom / ground height) MUST equal the coax port's position[2] to within one grid cell — both refer to the SAME physical ground plane. No other ports (lumped/wire/waveguide/Floquet), no TFSF, no lumped RLC, no pre-registered probes/DFT planes/flux monitors/NTFF (this method builds its own). self._geometry must be non-empty (the caller's substrate/trace/ground-plane/pin-post Boxes and Cylinders). The MSL source interval must meet its realized conductor surfaces. The auto-built stub stops below the junction node and preserves the caller's materials at and above it. These checks do not certify the junction's connectivity or its modal accuracy. Same solver/precision/boundary contract as compute_coaxial_two_port() (float32, 3D uniform Yee, boundary='cpml' with positive CPML on all six faces, absorption on all three axes): the coax's own far end needs an absorbing z face exactly like the coax lane, the MSL trace radiates in x/y too, and the caller's own ground plane is an INTERNAL stamped/registered PEC layer rather than the domain's z boundary — this is also WHY this method cannot reuse a PEC z_lo domain boundary as the MSL ground reference the way compute_mixed_s_matrix()'s magnitude_channel="flux" fixtures do (that would conflict with the coax's own need for an absorbing z_lo face).

Two-drive extraction (never a naive single-ratio)

Drives the coax source, then the MSL source, in two separate FDTD runs (never assuming the non-driven port sees zero incident wave — the terminator-floor problem compute_coaxial_two_port() already solved for symmetric coax applies here too, and likely worse, since the coax feed resistor and the MSL Hammerstad-Jensen termination have no reason to share a termination quality). Each port's own forward/backward wave amplitudes are recovered from its own probe ladder via ~rfx.sources.coaxial_port. coaxial_line_reflection_from_plane_voltages() (Z0-free matrix-pencil fit — see ~rfx.api._spec.CoaxMSLTransitionResult for why this is used for the MSL side too, not the lane's own N-probe fit), converted to POWER waves via each port's own analytic reference impedance, and assembled by ~rfx.sources.coaxial_port.solve_two_port_from_wave_amplitudes() (the same generic two-drive solve compute_coaxial_two_port() uses). See _assemble_coax_msl_transition_from_voltages() for the full pure-assembly derivation.

Parameters

junction_x : float Physical x-coordinate (metres) of the coax-to-trace launch discontinuity — the MSL side's own S-parameter reference plane. Must match wherever the caller's own registered pin-to-trace post / trace Box actually begins; this method does not infer it from geometry (mirrors the coax side's own reference plane being the registered port's position[2], not inferred). eps_r_sub : float, optional Substrate relative permittivity. If None, taken from the registered add_msl_port()'s own eps_r_sub (which must then be set explicitly — this method does not attempt the geometry-bounding-box auto-detection add_msl_port() itself offers, to keep the eps anchor unambiguous for the Hammerstad-Jensen Z0 used in the power-wave normalization). probe_count, probe_start_cells, probe_spacing_cells : int The COAX side's own probe array (mirrors compute_coaxial_two_port()'s identically-named parameters — this method's coax stub is short by construction, between the near-source feed and the junction, so these three rarely need to grow). msl_probe_count, msl_probe_start_cells, msl_probe_spacing_cells : int, optional The MSL side's OWN probe array, independent of the coax parameters above (added issue #489 leg 4 attempt 2 — the two families' probe ladders were coupled through one shared set of parameters through attempt 1, which is fine when both ladders are short but breaks as soon as the MSL side needs a ladder spanning a meaningful fraction of a guided wavelength, since the coax stub's own short z-extent cannot host the same span). Each defaults to None, meaning "use the correspondingly-named coax parameter" — this preserves attempt 1's exact behavior (and its committed fixture's numbers) when left unset.

NEAR-FIELD STANDOFF (issue #823) — the one constraint these
three are NOT free of. Every probe must clear BOTH ends the
ladder is referred to (the MSL port's own feed plane AND the
reference plane at ``junction_x``) by at least
``max(3, round(5*h_sub/dx))`` cells. Both are launch
discontinuities, and within a few substrate thicknesses of one
the field is not the guided mode yet, so a matrix-pencil fit
that includes such a probe reports the LADDER's error as the
field's: on the settled attempt-3 run (VESSL 369367257533) a
single probe 0.4 mm = 1.33*h_sub from the feed dragged the
full-ladder residual from 3.7e-3 to 0.342, and this lane spent
three attempts attributing that to junction physics. The
threshold is the repo's EXISTING issue-#80 Fix B constant —
see `rfx.api._preflight.msl_source_near_field_standoff_cells()`
for the derivation that licenses reusing it here, and for the
W/h limitation it carries. Preflight cannot enforce it on this
lane (these are METHOD arguments and never reach the
registered ``_MSLPortEntry``), so this method evaluates the
same predicate on its own REALIZED ladder and emits a
``UserWarning`` naming the offending probes. REPORT-ONLY:
nothing is refused. Read it together with
``result.ladder_split_gamma_dev`` /
``result.ladder_split_reflection_decades`` (computed when
``return_ladder_voltages=True``, ``None`` otherwise), which say
whether the ladder actually disagrees with itself.

strict_passivity : bool, default True Default True: this lane REFUSES a non-passive extracted S, raising ValueError from the shared guard (_warn_if_nonpassive_smatrix() via _finalize_sparam_result()) instead of returning the matrix. Pass strict_passivity=False to get the diagnostic matrix back with a UserWarning instead of the raise. The default is True here and False on the single-family coax two-port lane (compute_coaxial_two_port()), which is unaffected by this (issue #838, PI decision 2026-09-20).

extra_flux_monitors (issue #589 flux-adjudication instrument): an ENERGY-WITNESS channel, not an extractor change. Pass the entry objects Simulation.add_flux_monitor registers (build them on a scratch Simulation with the same domain and hand over its ._flux_monitors); each internal drive run then accumulates the requested Poynting-flux planes, and per-drive spectra come back name-keyed on result.flux_monitors ({"coax"|"msl": {monitor_name: (n_monitor_freqs,) float64}}, net flux, positive = +axis). The S-parameter math is untouched — the non-perturbation witness (S bit-identical with and without monitors) is gated in tests/unit/sparams/test_coax_msl_transition.py::test_extra_flux_monitors_do_not_perturb_s. The registered-monitor guard is unchanged: monitors registered ON this sim still raise, because this method builds its own probes.

Unless skip_preflight=True, the shared sheet-size verdict runs before stepping: snap="strict" blocks an off-size sheet and snap="declared" warns. Other preflight families are not run here.

return_ladder_voltages (issue #589 label-independent ladder dump): a second read-only channel, additive in exactly the same sense. When True, the RAW per-probe modal voltages this method already computed for both drives are attached to result.ladder_voltages (None otherwise) so the ladders can be re-read OFFLINE — adjacent-pair phase slope (which way the dominant wave travels), standing-wave ratio, subset matrix-pencil fits — without a second FDTD run and without trusting any incident/outgoing LABEL. The dict is documented field-by-field on ~rfx.api._spec.CoaxMSLTransitionResult. It is built from .copy() of arrays that are complete before, and consumed by, _assemble_coax_msl_transition_from_voltages(), so every S-parameter number is bit-identical with the option off or on — gated by tests/unit/sparams/test_coax_msl_transition_ladder_dump.py:: test_return_ladder_voltages_does_not_perturb_s (byte-identity A/B, the same discipline as the flux witness above; the round-trip assertion there also proves the dump IS what the assembler consumed). The same flag switches on the issue-#823 LADDER SELF-CONSISTENCY WITNESS, result.ladder_split_gamma_dev / result.ladder_split_reflection_decades (None when the flag is off): a disjoint-half refit of each ladder, i.e. a Python loop of 2 drives x n_freqs x 2 matrix pencils per ladder over exactly the arrays the dump exposes. It is computed AFTER the assembler from those arrays and moves no S-parameter number; it is opt-in so that a default call pays for no extra pencil solves. Documented field-by-field on ~rfx.api._spec.CoaxMSLTransitionResult.

Returns

CoaxMSLTransitionResult

Return the FULL conductor cell footprint of this simulation.

Since #677 a surface-impedance (surface_impedance_f0) thin conductor is a node-thin per-step operator: it touches neither pec_mask nor materials.sigma, so the obvious hand-written conductor test pec_mask | (sigma > 1e3) finds NOTHING for a board whose every trace is an f0 sheet and reports a healthy model as disconnected. There are now three places a conductor can live, and this accessor is the one spelling that covers all three::

pec_mask | (sigma > sigma_threshold) | union(f0 sheet masks)

Parameters

grid : Grid or NonUniformGrid or None Grid to rasterize against. None (default) builds the grid this simulation would actually run on -- the non-uniform grid when any of dx_profile / dy_profile / dz_profile is set, the uniform grid otherwise -- so the returned mask has the shape of the real run's arrays. sigma_threshold : float or None Conductivity (S/m) at or above which a cell counts as conductor. Default CONDUCTOR_SIGMA_THRESHOLD (1e3). The comparison is strict >, matching the sigma > 1e3 spelling this replaces.

Returns

jnp.ndarray Boolean array of grid.shape. All-False when the model has no conductor at all.

Notes

The f0 contribution is the sheet's rasterized CELL mask (the one-layer footprint apply_pec_mask would zero for the same shape), not the tangential EDGE masks the runtime operator applies. Cell footprint is what a connectivity / occupancy check wants; the edge masks live on SheetImpedanceCtx.

Return (shape, NamedSharding) for distributed forward designs.

The global shape is (nx_padded, ny, nz) with no ghosts, where nx_padded rounds the NU grid's x extent up to a multiple of the device count. Sharding is P("x") on the ordered devices (default: all global JAX devices). Every process must use the same list. Construct large designs with jax.make_array_from_callback or jax.make_array_from_single_device_arrays using this layout; no whole-domain device allocation is necessary. Forward ignores alignment-pad values, and their returned gradients are zero.

Place a concrete local whole-domain design in the forward layout.

This convenience initializer copies addressable x slabs from a host array; it is not an autodiff operation. Differentiate forward with respect to the returned global array. For designs too large for one host, construct shards directly using distributed_override_layout. On multiple processes each caller supplies the same concrete array.

Run a minimal differentiable forward simulation.

This path is designed for jax.grad / jax.value_and_grad and intentionally returns only the observables needed by differentiable objectives instead of the broader stateful run() result.

Parameters

gradient : {"autodiff", "adjoint"} Opt-in settled-spectrum reciprocity design eps adjoint. Design sigma overrides are refused (#1424): on lossless design cells the conductivity gradient has no settled value in a finite record (a static sensitivity remains although the field decays); this adjoint returns settled-spectrum gradients only. Fixed lossy materials are allowed. Stores design-edge DFTs and runs a second ordinary forward. ForwardResult.adjoint_settling reads the primal design-edge max|E| over the last period of the lowest bin, capped at the record length, divided by the record maximum. Above about 1e-2 means unsettled; small proves nothing: it follows the strongest field and says nothing about the adjoint record. Use gradient_record_length_witness to witness an adjoint gradient. Uniform Yee design_box only; unsupported paths raise. Checkpoint options are unused by the adjoint (its storage does not depend on them). eps_override : jnp.ndarray or None Replacement permittivity array with shape grid.shape. With distributed=True, eps/sigma/occupancy overrides also accept x-sharded global arrays from distributed_override_layout(). That form is required across processes; gradients keep its sharding. Use shard_distributed_override() for a concrete local initializer. sigma_override : jnp.ndarray or None Replacement conductivity array with shape grid.shape. mu_r_override : jnp.ndarray or None Replacement relative permeability array with shape grid.shape. Differentiable (the H-update coefficient is dt/(mu_r*MU_0*dx)), so jax.grad flows w.r.t. a magnetic-material design variable (ferrite / magnetic-RAM inverse design). Uniform single-device lane only; a non-uniform mesh or distributed=True raises (it would otherwise be silently dropped — a zero-gradient no-op). design_box : (corner_lo, corner_hi) or a DesignRegion, or None Issue #1179. Bounding box, in metres, of a design region whose permittivity is handed in separately as design_eps_override instead of being written into a whole-grid eps_override. Accepts a (corner_lo, corner_hi) pair or any object carrying corner_lo / corner_hi (DesignRegion, TopologyDesignRegion). Corners resolve to cells the way topology_optimize resolves them — grid.position_to_index on each corner, both ends INCLUSIVE — and the realized cell counts, not the declared extent, are what design_eps_override must match. One difference: a corner outside the interior is CLAMPED by topology_optimize and RAISES here, so a region that reaches into the absorber is a smaller design region there and an error on this path.

What it buys: the Yee E update is linear in the fields, so the
backward pass needs the primal field only where a coefficient is
a design variable. With the grid-wide coefficients left constant
and only this box recomputed from the traced permittivity,
reverse-mode AD stores box-shaped arrays per timestep where
``eps_override`` stores grid-shaped ones. The gradient is the
same gradient (measured to 2.5e-14 relative in float64 against
``eps_override`` on a 57x57x41 open-domain fixture); this is a
change of formulation, not an approximation, and it needs
neither ``checkpoint_segments`` nor any recompute.

**Pass ``checkpoint=False`` with it.** ``checkpoint=True`` (this
method's default) remats every step, which saves the scan CARRY
— the six grid-sized field arrays — once per step no matter what
the coefficients are. Measured on a 23x21x19 grid over 80 steps
with a 3x3x3 box: 0.59 MB of residuals at ``checkpoint=False``
against 26.2 MB at ``checkpoint=True``. The box removes the
coefficient term; only turning the per-step remat off removes
the carry term with it.

The GRADED MESH carries it too (#1183): the corners resolve
against the non-uniform grid's own cell edges and the box redo
uses the graded curl, so a thin substrate meshed with a
``dz_profile`` gets the same box-shaped tape. On that lane a
waveguide port, an MSL port and ``until_decay`` raise — the
first two write their own field or ``materials`` across a whole
plane from the background permittivity.

Fenced, not degraded — for a design PERMITTIVITY
(*design_eps_override*): ``distributed=True``,
``solver='adi'``, ``boundary='upml'``, Debye/Lorentz
dispersion, Kerr, subpixel/anisotropic permittivity,
``pec_occupancy_override``, ``stencil_order=4``, the oblique
Bloch path, combining with ``eps_override`` / ``sigma_override``
/ ``mu_r_override``, a box that reaches into the CPML absorber,
and a box holding a source, port, lumped-RLC or
surface-impedance-sheet cell all RAISE (a lumped or wire port
may stay inside with *design_box_holds_ports*). Each of those either
computes E by some other rule inside the box or reads the
background permittivity at a box cell, and a silently dropped
design variable is a zero gradient that reads like convergence.
A design OCCUPANCY has its own, shorter list — see
*design_occupancy_override*; in particular it does combine with
``eps_override`` and with ``pec_occupancy_override``, because
it reads no material array.

design_eps_override : jnp.ndarray or None Relative permittivity at the design_box cells, shaped like the realized box. Usually the traced quantity. Required with design_box unless design_occupancy_override is given instead, and rejected without a box. design_sigma_override : jnp.ndarray, 3-tuple of them, or None Conductivity at the design_box cells, same shape. None (default) keeps the run's own conductivity there, so a lossy background inside the box is carried exactly rather than silently replaced by a lossless one. A 3-tuple (sigma_x, sigma_y, sigma_z) gives each E component its own conductivity — what a conducting SHEET needs, whose current runs along its two in-plane edges only. See ~rfx.simulation.DesignBoxSpec. design_occupancy_override : jnp.ndarray or None Issue #1183. Relaxed-conductor occupancy in [0, 1] at the design_box cells — metal-shape design (a notch stub, topology optimisation) rather than a dielectric one. It REPLACES pec_occupancy_override at those cells and carries it everywhere else, and the gradient is the same gradient pec_occupancy_override gives with the same values written into it.

What it buys is the same trade: ``apply_pec_occupancy`` scales
every E component by ``1 - M``, so a traced whole-grid occupancy
makes the backward pass keep three GRID-sized primal E arrays
per timestep. Confined to a box, the arrays it keeps cover the
box plus one cell — the reach of the incident-cell rule — and
``1 - M`` itself is built once outside the time loop, because an
occupancy is a design variable and not a field. Pass
``checkpoint=False`` with it, for the reason above.

Uniform single-device Yee lane only; a graded mesh,
``distributed=True`` and ``solver='adi'`` raise. So do a
periodic axis (the incident rule wraps across the seam, so the
box's window is no longer the whole set of cells its occupancy
can move), combining it with *design_eps_override* in one call,
a box covering a cell the port setup CLEARS the occupancy at
(the port cell, its six face neighbours, an MSL port's in-plane
diagonal owners), and the Kottke occupancy lane
(``RFX_PEC_OCC_KOTTKE=1``), where the occupancy becomes an
inverse-eps tensor inside the E update that the box's values
never reach.

design_box_holds_ports : bool Let a permittivity design_box contain lumped and wire ports (default False: a box holding a port raises). A port is a device on its edges — a 50 ohm load and a drive built from the drawn materials before the time loop — so each edge a port drives or loads inside the box's update window keeps the coefficients the drawn materials give it, for the update and the drive alike: the design values do not reach it, their derivative through it is exactly zero, and a box holding a port with the background written into it gives the run without the box. Holding keeps the DRAWN material in the port's feed gap, so the modelled structure differs from the same design written as a whole-grid eps_override by that gap. Passive ports (excite=False) are held too. The other edges of the port's cells stay design variables; at a port's cell a design value is the cell's volume material. The held edges come back as ForwardResult.design_box_held_edges, (axis, i, j, k) with axis 0, 1, 2 for Ex, Ey, Ez. A soft source (even on a port's edge), a magnetic source and a lumped RLC element in the box still raise; an MSL port's termination is not held. pec_mask_override : jnp.ndarray or None Additional hard PEC mask to merge with geometry-defined PEC. pec_occupancy_override : jnp.ndarray or None Relaxed conductor occupancy field in [0, 1] for differentiable PEC-style optimisation. n_steps : int or None Number of timesteps. If None, auto-computed from num_periods. num_periods : float Number of periods at freq_max for auto step count. checkpoint : bool Enable gradient checkpointing (default True). checkpoint_segments : int or None If set, route the uniform single-device forward through the segmented-checkpoint path (issue #73), which trades ≈2x compute for ≈sqrt(n_steps) reverse-mode memory. Must divide n_steps exactly (padding is rejected so DFT accumulator windows do not shift). None (default) keeps the legacy per-step jax.checkpoint behaviour. Currently wired only on the uniform single-device path; non-uniform meshes and distributed=True raise NotImplementedError (use checkpoint_every on the non-uniform path instead). emit_time_series : bool Emit the probe time series in the returned ForwardResult (default True). emit_time_series=False skips the time-series buffers and is currently only supported on the non-uniform forward path; on the uniform path it raises NotImplementedError (frequency-domain objectives such as NTFF and S-params still emit the series there). checkpoint_every : int or None Non-uniform-mesh counterpart of checkpoint_segments (a chunk size, not a segment count; issue #73). When set to a positive integer K, the non-uniform scan is run as a scan-of-scan that remats every K steps for ≈sqrt(n_steps) memory. Currently only supported on the non-uniform forward path; on the uniform path it raises NotImplementedError (use checkpoint_segments there). None (default) leaves forward-only runs unchanged. n_warmup : int Number of leading timesteps to run with the carry stop_gradient'd so reverse-mode AD builds no tape for the initial transient (issue #40). Only the trailing n_steps - n_warmup steps participate in autodiff. Must satisfy n_warmup < n_steps. Default 0 (all steps differentiated).

The truncation error DEPENDS ON DISTANCE FROM THE SOURCE TO THE
DESIGN REGION — it is not simply "an approximation" that always
costs accuracy (an earlier version of this docstring implied the
error applies unconditionally; that was an overgeneralization
from a single, worst-case fixture — see below). Severing the
carry severs every gradient path through steps ``< n_warmup``,
but only steps during which the WAVEFRONT HAS ALREADY REACHED
the design region carry any such path to sever; before the
wavefront arrives the field there is ~0, so severing those
steps discards ~nothing and the gradient is (near-)exact.
Compute a safe bound yourself::

    K_safe ~= floor(min_distance(source, design_region) / (C0 * dt))

(``min_distance`` is the minimum over EVERY active source AND
over each source's own spatial extent, not just its nominal
position — a TFSF plane-wave source illuminates from an
entire box face, not a point; grid steps for the wavefront to
reach the closest design cell, ``C0`` = vacuum lightspeed,
``dt`` = ``sim._build_grid().dt`` /
``sim._build_nonuniform_grid().dt`` — a conservative floor valid
for any slower propagation). ``n_warmup <= K_safe`` stays
within this repo's ~1.5% AD-vs-FD noise floor (near-exact,
<0.1%, well below ``K_safe``); well beyond ``K_safe``, error
grows further and can reach the full gradient magnitude by
the time ``n_warmup`` reaches the loss window. Two measured
regimes (issue #626 part 2 / addendum, both vs an independent
central-FD oracle): a NEAR-SOURCE placement (design cell ~3
cells from the source, so ``K_safe ~ 0``) shows error growing
smoothly from a ~1.5% noise floor up to 58% at the
loss-window boundary itself, and EXACTLY zero (gradient fully
vanished) once ``n_warmup`` extends far enough into the loss
window (``tests/unit/autodiff/test_n_warmup.py::
test_warmup_truncation_error_grows_with_k``); a
FAR-FROM-SOURCE placement (design cell 62 cells from the
source, ``K_safe=108`` measured from the grid's own ``dt``)
shows AD matching the ``n_warmup=0`` FD oracle to <0.01%
through ``K_safe``-20, then growing SMOOTHLY (not a sharp
cliff) as ``n_warmup`` approaches ``K_safe`` -- 0.26% at
``K_safe``-4, 0.60% at ``K_safe``-2, 1.19% AT ``K_safe``
itself (still inside the noise floor above) -- continuing to
grow past it toward 75% by ``K_safe`` + 92 —
``scripts/diagnostics/i626_n_warmup_wavefront_locality.py``
(finely sampled around ``K_safe``; an earlier version of this
docstring, read from a coarser sweep that skipped every point
near the boundary, overstated the transition as a sharp
cliff "exactly at K_safe"). The near-source curve above is
the WORST case, not the general
case: use ``K_safe`` to decide whether YOUR source/design
placement is in the exact or the truncated regime before
assuming ``n_warmup`` costs accuracy. Forward (non-AD) output
is exactly ``n_warmup``-invariant (bit-identical) in every
placement measured; only the gradient is affected. Currently
only supported on the non-uniform / distributed-non-uniform
forward paths; on the uniform single-device lane it raises
``NotImplementedError`` (issue #626 — previously silently
accepted and ignored, worse than an error).  Use
*checkpoint_segments* for uniform-lane reverse-mode memory
relief instead — it is exact regardless of placement, at the
cost of recompute rather than gradient accuracy.

skip_preflight : bool Skip the consolidated preflight() validation suite that normally runs before the forward simulation (default False). Use only when preflight has already been run by the caller (e.g. rfx.optimize runs it once at entry) or to bypass a known-spurious warning on a deliberate configuration. distributed : bool, optional Opt-in, unstable, pending GPU evidence (issue #44). When True and a non-uniform mesh is configured, route the differentiable forward through the sharded NU runner (rfx.runners.distributed_nu.run_nonuniform_distributed_pec) using a 1-D x-slab decomposition across devices. Defaults to False (single-device path, no behaviour change). In v1.6.2 the distributed forward path is NU-only (DP3): a uniform mesh raises NotImplementedError. TFSF sources and waveguide ports are unsupported on this path and raise NotImplementedError at preflight. devices : list of jax.Device or None, optional Devices for the distributed run. When distributed=True and devices=None, defaults to jax.devices(). When an explicit list is supplied, every device must already exist in jax.devices() (otherwise ValueError). Passing devices= without distributed=True raises ValueError — there is no silent activation of the distributed lane. exchange_interval : int, optional Ghost-cell exchange interval for the distributed runner (default 1). Only 1 is currently supported by run_nonuniform_distributed_pec; other values are forward-compatible reservations and will raise inside the runner. port_s11_freqs : array-like or None Frequencies (Hz) at which to accumulate per-port V/I DFTs inside the JIT scan body so that ForwardResult.s_params is populated with wave-decomposition |S11| values for lumped/wire ports (issue #72) — the AD-traceable counterpart of run(compute_s_params=True). Required by the minimize_s11_at_freq_wave_decomp() objective. Currently supported on uniform and graded single-device paths; distributed=True raises NotImplementedError. rlc_values_override : dict or None Differentiable-value injection for lumped RLC elements added with add_lumped_rlc() (WP 4-E). LumpedRLCSpec stores plain floats, so a component value can only enter the AD tape as a tracer through this override. Maps a 0-based element index (registration order over add_lumped_rlc() calls) to a dict with any of the keys "R" / "L" / "C" whose values replace the registered floats — e.g. forward(rlc_values_override={0: {"R": R, "C": C}}, ...) makes R and C of the first RLC element differentiable. A missing element index or key falls back to the registered spec float. None (default) uses the registered floats for every element. Only wired on the uniform single-device path. NOTE: on this path a registered lumped RLC element now correctly affects forward() even without an override — previously it was a silent no-op. Uniform-path only; the non-uniform / distributed lanes do not iterate self._lumped_rlc in forward(). ringdown : rfx.ringdown.RingdownSpec or None Issue #1254. Complete the wire-port S-parameters of a record cut while the structure still rings, inside the differentiable program: ForwardResult.ringdown.s_params is the completion run(ringdown=...) gives of the same record (the poles of the port voltage and current identified on [window_start T, T], the unrecorded tail of each spectrum added in closed form), and jax.grad through it differentiates the infinite-record spectrum (the poles by the frozen Gauss-Newton implicit derivative, the residues re-fitted), not the cut record. .s_params_long is the completion from the window that starts twice as early; the gradient through it, against the gradient through .s_params, is the gradient's witness (rfx.ringdown.gradient_witness()). .report holds the checks of the value (W0, W1, WE and the rest, as run()'s), computed on the host from a concrete result and None while traced. Wire ports only (add_port(..., extent=...)); on the uniform lane one port and port_s11_freqs= are needed (the bins), on the graded lane the completion uses the lane's own bins. Everything run(ringdown=...) refuses is refused, and so are distributed=True and emit_time_series=False. None (default) leaves every output and the traced program as they were.

**_removed_kwargs Rejection shim for removed keywords, providing migration errors; it does not accept additional simulation options.

Returns

ForwardResult Minimal differentiable observables (time series and optional NTFF). settling_db and settling_witness score retained user-probe records on the concrete result using the run() diagnostic and underflow floor. They are host diagnostics, unavailable during tracing, and can be read on concrete records outside the jitted objective. Other result fields keep their existing JIT restrictions, including the host Grid object. Absent records yield None rather than a passing value. Use settling_verdict(result.settling_db) for the shared -40 dB bar.

Notes

forward() refuses refinement: it has no subgridded solve. forward() can be called inside jax.jit, so an optimisation step compiles once: step = jax.jit(jax.value_and_grad(loss)) compiles on its first call and reuses the program afterwards, while an un-jitted jax.value_and_grad(loss) compiles the whole solve again on every call (#1225). Under an outer jax.jit (single device), the set-up built from the model alone is evaluated while tracing and the time stepping is compiled into the caller's program (#1367, #1354), so a function with no traced input compiles too. The set-up's arrays become constants of that program: the first call costs a plain call's set-up on top of the compile, and the compiled program holds those arrays for as long as JAX caches it. The loop compiles over operands XLA cannot read, as in a plain call; what is computed from a traced input before the loop (a port's drive from a traced permittivity, #1320) is compiled with the caller's program, so the jitted value and gradient agree with a plain call to float32 rounding, not necessarily bit for bit.

Run the simulation.

Parameters

n_steps : int or None Number of timesteps. If None, auto-computed from num_periods. num_periods : float Number of periods at freq_max for auto timestep count. checkpoint : bool Enable gradient checkpointing for reverse-mode AD. compute_s_params : bool or None Compute S-parameter matrix. Default: True when ports exist. s_param_freqs : array or None Frequencies for S-parameters. Default: 50 points from freq_max/10 to freq_max. s_param_n_steps : int or None Timesteps for S-parameter simulation (may need more than the main simulation for frequency resolution). until_decay : float or None When provided, overrides n_steps and runs until field energy decays to this fraction of peak. E.g. 1e-3. Boundary-dependent stop (issue #169, RESOLVED for absorbing boundaries): On absorbing boundaries (cpml / upml) the stop now uses the total interior-domain energy U = sum(E^2 + H^2) over the non-CPML interior — a whole-domain quantity that does not pass through the per-cell interference nulls of the old single-cell point-field stop, so it is suitable for flux / S-parameter / transmission measurements on guided / low-loss geometries (#169 resolved). On closed / PEC boundaries domain energy does not decay, so the stop falls back to the historical instantaneous single-cell field; that fallback keeps the original limitation (valid only for lossy / radiating ring-down, not flux / S-param / transmission gating on guided / low-loss closed geometries — use a fixed n_steps there, see the rfx.simulation.run_until_decay() note). Non-uniform (dx/dy/dz-profile) meshes (issue #383): the same interior-energy stop runs on absorbing (cpml/upml) boundaries via a chunked host loop over the NU scan step (dV-weighted energy — per-cell dx*dy*dz — so graded cells are weighted faithfully). Closed-boundary NU sims refuse until_decay (no point-field fallback on the NU lane). On the NU decay path all step-sized buffers are allocated at decay_max_steps and flux monitors must keep the default rectangular DFT window. (The non-uniform runner additionally rejects its internal checkpoint_every segmentation option when a decay stop is requested; that option belongs to the forward() lane and is not reachable through run().) DC floor (issue #388): a soft-source waveform with net DC content deposits a static end-charge whose self-energy floors the interior-energy criterion; run() warns quantitatively when a planned soft-source waveform's relative DC exceeds 1e-3 (raise the GaussianPulse cutoff, narrow a ModulatedGaussian to bandwidth <= 0.4, or use a fixed n_steps). This advisory does NOT catch low-rel_DC floors amplified by thin source cells (the #388 patch class measured the floor at rel_DC ~6e-5) — see issue #388. decay_check_interval : int Check decay every N steps (default 50). decay_min_steps : int Always run at least this many steps (default 100). decay_max_steps : int Hard upper limit on steps (default 50000). decay_energy_consecutive : int Absorbing-boundary only: number of consecutive sub-threshold interior-energy checks required before stopping (default 2; >= 2 mandatory — the interior energy is not null-free and a single check can false-fire on a transient inter-packet dip). radiated_flux_box : tuple or None Physical lower/upper corners of a closed box enclosing the radiator, clear of CPML. Selects outgoing-flux decay instead of interior-energy decay on absorbing boundaries; None keeps the energy criterion. flux_env_checks : int Number of recent checks whose maximum absolute flux forms the radiated-flux envelope (default 4). snapshot : SnapshotSpec or None Field snapshot schedule and selection; None disables snapshots. subpixel_smoothing : bool or str Material-interface smoothing rule; False disables smoothing. True enables dielectric smoothing; "kottke_pec" selects the unified PEC occupancy rule on supported lanes. skip_preflight : bool Skip advisory preflight checks. Runtime admission guards still apply. decay_monitor_component : str Field component to monitor (default "ez"). Used only by the closed/PEC point-field fallback stop. decay_monitor_position : tuple or None Physical position to monitor. If None, use domain center. conformal_pec : bool Enable Dey-Mittra conformal PEC for second-order accuracy on curved PEC surfaces. Default False (staircase PEC). conformal_min_weight : float Minimum conformal weight for CFL stability clamping. Default 0.1. Recommended range: 0.05-0.3. devices : list of jax.Device or None When a list with len > 1 is provided, run the simulation distributed across those devices using 1D slab decomposition along the x-axis via shard_map. Supported combinations are listed in docs/guides/support_matrix.md. exchange_interval : int, optional Ghost exchange interval in timesteps; only integer 1 is supported. report_every : int or None Issue #667 — progress reporting for long solves. When set, print one [PROGRESS] ... line every N timesteps giving steps done / total, wall elapsed, implied rate and ETA, on the same stdout channel as preflight so a redirected job log captures it. None (default) is OFF and leaves the solve on its unchanged code path, so nothing moves for existing callers.

Supported on the **uniform lane only** (both the fixed
``n_steps`` scan and ``until_decay``); the distributed,
non-uniform, ADI and subgridded lanes warn and drop it rather
than silently producing no output. It is forward-only and
raises under ``jax.jit``/``grad``/``vmap`` (the check inspects
the carry, the per-step inputs and the material / geometry
arrays — the routes ``forward()``/``optimize()`` trace through).

On the fixed-``n_steps`` scan the reporting turns the single
compiled scan into ``ceil(n_steps / report_every)`` calls to
the SAME compiled scan with ``carry`` threaded through — a
continuation, not a re-solve, and bit-exact against
``report_every=None`` (locked by
``tests/unit/runners/test_run_progress_reporting.py``).

Each report costs one device synchronisation plus one print.
On a 118k-cell CPU fixture that cost was **not resolvable above
the measurement noise** at any cadence tried: a paired
off-vs-off self-control read -4.8% [-9.3, -0.9], and every
cadence from 2000 down to 25 landed inside that floor. The one
clean figure is +0.7-0.8% for a single-chunk run, bounding the
fixed per-report cost. So choose ``report_every`` for a useful
reporting interval, not to minimise an overhead this benchmark
could not detect; only the direction (finer cadence costs more)
is established. None of this speaks to the large-grid GPU
regime, which was not measured.

report_label : str Short tag prefixed to each progress line (e.g. "drive p1"). Ignored when report_every is None. ringdown : rfx.ringdown.RingdownSpec or None Issue #1254 — complete the wire-port S-parameters of a record cut while the structure still rings. The slow poles are identified on [window_start * T, T] of the port voltage and current (the source must be off there) and the unrecorded tail of each spectrum is added in closed form. The result is Result.ringdown (.s_params on the bins of Result.s_params, .report with the window, the poles and the witnesses: WE when available (otherwise W2), no growing pole, passivity, source off). Every other output is the one the same run gives without ringdown=. Wire ports (add_port(..., extent=...)) on the uniform (one port) and graded-mesh lanes, fixed record length; other ports, TFSF, Kerr, devices= and until_decay are refused with the reason. until_identified : bool Issue #1254 — with ringdown=, end the run once the completion is witnessed instead of at n_steps, which becomes the longest record allowed. The record is checked on a geometric schedule (every check at least 1.25x the record of the last); the run stops at the first check where every source is off over [T/4, T], the error witness WE is within witness_tol there and at the check before, the record is at least half the amplitude decay time Q / (pi f) of the slowest mode whose own unrecorded tail moves the completed S by witness_tol (a static field left in a closed box is left out; the largest such decay time over the checks the two-in-a-row rule rests on), and the completion reads passive with no growing pole. The result is the one run(n_steps=T, ringdown=...) returns for the stopping record T, with the stop report (every check's record, WE, the pole that set the floor, the conditions and the check's wall time) in Result.ringdown.stop. Each check identifies the record twice (0.1-3 s on a CPU for the test cavity); on a small model that costs more than the steps it saves. A weakly coupled high-Q mode holds the floor for half its own decay time, which can be longer than n_steps. When no check stops the run, the whole n_steps record is completed and the report names the condition that failed. Refused without ringdown=, with until_decay, snapshot=, DFT planes and flux monitors.

Returns

Result

Return or write the native runtime scene artifact.

path=None returns a JSON-serializable dict. Otherwise the scene is written as indented JSON and the output ~pathlib.Path is returned.

Return a runtime artifact report dict for this simulation.

Write a runtime artifact bundle and return ArtifactBundle.

Estimate reverse-mode AD memory for this simulation.

Returns a static-estimate AD_MemoryEstimate with forward, checkpointed-AD, and non-checkpointed-AD sizes in GB, plus a best-effort warning if estimated AD memory exceeds 85% of available VRAM. This artifact is planning evidence, not a certificate of peak runtime memory.

When checkpoint_every is provided, the returned ad_segmented_gb reflects the non-uniform segmented scan-of-scan chunk-size path from issue #31. When checkpoint_segments is provided, it reflects the uniform segmented-scan segment-count path from issue #73.

The segmented model (issue #277) counts BOTH terms of the rematerialized backward pass:

• segment-boundary storage — carry + cotangent per active segment, 2 * active_segments * field_bytes;
• the live-segment rematerialization tape — the backward pass replays one segment at a time, so that segment's per-step field tape (n_steps // checkpoint_segments steps on the uniform path, checkpoint_every steps on the chunked path) is resident on top of the boundary storage. The non-uniform runner pads the trailing chunk with zero source to a full chunk, so the full chunk length is the correct live-tape size; both live terms are capped at the active (post-warmup) step count.

The segmented estimate is therefore minimized when the two terms balance, near sqrt(2 * n_steps) steps per segment — NOT by pushing the segment count to either extreme. Use plan_ad_memory() to pick a balanced knob for a budget. n_warmup must be an integer with 0 <= n_warmup < n_steps and reduces reported reverse-mode tape time. The legacy ad_checkpointed_gb field keeps its old (optimistic) heuristic for backwards compatibility; it is NOT accurate for FDTD on the non-uniform path — see the class docstring.

Explain the static reverse-mode AD memory estimate.

This method uses the same conservative accounting as estimate_ad_memory(), then decomposes the selected AD memory number into named contributors. It is meant to answer "what is making this AD run large?" without claiming profiler evidence or a runtime peak bound.

Choose a segmented-AD memory plan for a memory budget.

The planner reuses estimate_ad_memory() and returns a calibrated conservative planning artifact rather than mutating the simulation or certifying runtime peak memory. If ordinary reverse-mode AD already fits under target_fraction * available_memory_gb, both checkpoint knobs are None. Otherwise it returns a segmented candidate: checkpoint_every for non-uniform grids or checkpoint_segments for uniform grids. Only wire the candidate when segmented_fits is true; a non-fitting plan keeps the least-memory candidate as diagnostics. n_warmup must be an integer with 0 <= n_warmup < n_steps and reduces active reverse-mode time. Raw estimates must also fit after multiplying by safety_factor before fit flags are set, so near-boundary plans stay conservative.

Return a one-call AD-memory preflight planning artifact.

The report composes existing static memory planning, static explainability, optional mesh advisories, and optional trace-time JAX saved-residual diagnostics. It does not run FDTD and does not upgrade static planning evidence into runtime memory proof.

Return a fail-closed compiler-memory certificate for one executable.

This method accepts an already-compiled JAX object and reads only its memory_analysis() output. It does not compile callables, run FDTD, profile runtime memory, or convert static memory plans into guarantees. Green statuses are bounded to the supplied compiled object and complete exact-scope metadata.

Compute a theoretically clean axis-normal boundary-aperture waveguide S-matrix.

Requires solver="yee". On a uniform mesh, precision selects field storage for every device and reference run, as on run(). A non-uniform mesh supports only precision="float32".

Parameters

num_periods : float Length of the FDTD run (in source-period multiples) used to derive n_steps when n_steps is not given. The spectra are computed POST-SCAN from the recorded modal V/I time series via a rectangular full-record DFT (matching OpenEMS's utilities.DFT_time2freq); num_periods therefore governs both the CPML drain horizon AND the DFT integration window. Phase 2 cleanup (2026-04-25) removed the legacy num_periods_dft early-gate knob — the rect full-record DFT is finite-energy on the recorded transient so no gating is needed even on strong reflectors. normalize : bool or "flux" Controls the S-parameter extraction algorithm:

``False`` (default) — modal V/I decomposition, no reference
run.  Magnitude includes Yee impedance mismatch
(Z_TE_num/Z_TE_exact ≈ 3 % at dx/λ = 0.07).  Use for
|S11| of strong reflectors (PEC short, high-Q resonators)
where this error is smaller than the ±10–20 % round-trip
dispersion error introduced by ``normalize=True``.  On the
differentiable chain: a traced ``eps_override`` /
``sigma_override`` flows through it.

``True`` — two-run modal normalization.  Cancels one-way
Yee dispersion for **transmission** (off-diagonal) by
dividing device outgoing waves by reference outgoing waves
at the same port.  **Does not** cancel dispersion for
reflection (round-trip vs one-way path mismatch); use
``normalize=False`` or ``normalize="flux"`` for S11 of
strong reflectors.  Host-assembled and **outside the
differentiable chain**: a traced ``eps_override`` /
``sigma_override`` (``jax.grad``, ``jax.jit``) raises
``NotImplementedError`` at this call, before any FDTD run;
a concrete override still runs forward.

``"flux"`` — hybrid power-flux extraction.  Magnitude from
Poynting-vector DFT (|S|² = P_flux / P_inc), phase from
modal V/I.  Corrects both the Z_TE impedance-mismatch error
in S11 and the round-trip dispersion error in the
``normalize=True`` diagonal formula.  Costs 2 × N_ports
FDTD runs (same as ``normalize=True``).  On the
differentiable chain like ``False``. On the uniform lane the
result promotes field, frequency, and JAX default float precision,
like ``False``: complex64 with x64 off and at least complex128 with
x64 on, including explicit float32 frequencies and float32/mixed fields.
Modal records retain at least the frequency and default float precision.
The non-uniform lane's result follows the ``freqs`` precision:
complex64 by default, complex128 under ``JAX_ENABLE_X64``.

**Reference impedance.**  On ``False`` and ``True`` each
S_ij is the modal voltage-wave ratio ``b_i / a_j``, where
the waves at a port are decomposed with that port's OWN
discrete modal impedance (Yee-discrete Z_TE or Z_TM from
the port's cutoff and cell size); no ``sqrt(Z_i / Z_j)``
renormalization is applied.  ``"flux"`` takes |S_ij| from
the power ratio and its phase from the same modal waves.
The returned matrix therefore equals a power-wave S only
when every port shares one cross-section and mode — the
validated scope (straight guides and same-guide junctions).
Ports with dissimilar cross-sections are outside it.

**Multimode.**  ``n_modes > 1`` on any port is assembled on
the host for every ``normalize`` value and is outside the
differentiable chain; ``eps_override`` / ``sigma_override``
differentiation is single-mode only.

checkpoint_segments : int or None Segmented gradient checkpointing for the uniform waveguide AD path (issue #73 / PR #125). Splits the n_steps scan into K segments that are rematerialised via jax.checkpoint during the backward pass, reducing peak reverse-mode memory from O(n_steps·|carry|) to O((K + n_steps/K)·|carry|) (≈ O(√n_steps·|carry|) at the optimal K ≈ √n_steps, at ≈ 2× backward compute cost). K is forwarded to rfx.simulation.run with checkpoint=True; K MUST exactly divide the auto-computed n_steps (the runner rejects non-divisors — choose the nearest divisor of √n_steps; padding is rejected because it would shift the V/I DFT windows). Default None is byte-identical to the pre-checkpoint scan.

On a NON-uniform mesh (``dx_profile`` / ``dy_profile`` /
``dz_profile``, issue #73) ``checkpoint_segments=K`` is now supported: ``K`` is
translated to the NU runner's ``checkpoint_every`` chunk size — the
divisor of ``n_steps`` nearest to ``n_steps/K`` — and applied to the
*device* run only (the vacuum reference is constant in the design
variable). The chunk MUST divide ``n_steps`` (same as the uniform
path): a non-divisor chunk would let the NU runner's zero-padding add
spurious ring-down steps to the carry-accumulated flux DFT and shift
the S-matrix. With an exact divisor the result is forward-IDENTICAL
and the ≈O(√n_steps) tape reduction is realised under ``jax.grad``
with ``normalize='flux'`` + an ``eps_override`` / ``sigma_override``
design variable.

port_reference_sims : list[Simulation] or None Per-driven-port matched-straight-guide reference simulations for interior-PEC multi-port structures (T-junctions, branches, septa). port_reference_sims[i] is a Simulation describing the STRAIGHT continuation of driven port i's guide with no junction — same domain / dx / boundary, geometry = port i's guide walls extended straight through. Only valid with normalize='flux' (raises otherwise); single-mode ports only; uniform mesh only; not combinable with eps_override / sigma_override.

**Multi-port junctions (port_reference_sims).** The default flux
path references incident power ``P_inc`` to a single shared VACUUM
run (empty domain, no interior PEC). For a straight guide the walls
come from ``pec_axes`` so that vacuum reference already carries the
guided ``P_inc`` correctly. For a junction the interior PEC septum /
branch is stripped from the vacuum reference, which then radiates
into free space: ``P_inc`` is mis-normalized and every ``|S|``
inflates hard (non-passive; ``normalize=True`` gave max|S|~230,
``normalize='flux'`` gave max|S|~9.8, |S11|~1.9 on the verified
compact 3-port T-junction). Passing ``port_reference_sims[i]`` = the
matched straight guide for driven arm ``i`` moves ``P_inc`` toward
the true single-mode guided incident power (PEC-folded identically
to the device run).

**Far-port discipline (required for a physical S-matrix).** This
plumbing is NECESSARY but NOT SUFFICIENT. A physical junction
S-matrix additionally requires: (1) each port's probe plane placed
>= 5 evanescent decay lengths of the next higher mode away from the
junction; (2) CPML thickness >= ~0.5 guide wavelengths at band
centre; (3) a converged mesh. On far-port geometry (arms 90/90/70 mm,
48 mm CPML, dx 1.0/0.667 mm) the matched-reference flux path reaches
passivity 1.006/1.002, reciprocity 0.001, mesh-convergence 0.0297
and 0.087 vs MEEP (r2000, cross-device). On COMPACT geometry the
matched reference fixes |S11| (1.86 → 0.49, physical) but the overall
matrix stays non-physical (residual max|S|~3.9); the two in-method
advisories (probe clearance, CPML thickness) warn when the far-port
discipline is not met.

The absorber half of that discipline is checked on **every**
uniform path, not just this one: an in-method advisory (issue
#494) fires whenever the absorber on a port's propagation axis is
thinner than ``0.5 * lambda_g`` at the **lowest** measured
frequency, which is where ``lambda_g`` is longest and the
``cpml_layers=16`` default weakest. It is checked in-method
because the functional entry points run no ``sim.preflight()``.
Treat ``0.5 * lambda_g`` as a floor, not a target: at the WR-90
band edge the measured residual ``|S11|`` ripple was 0.0706 at
0.30 ``lambda_g``, 0.0366 at 0.50 and 0.0093 at 0.75, so a
0.5-``lambda_g`` absorber can still set the accuracy envelope
instead of discretization. The advisory is silent on a
non-uniform mesh (``cpml_layers * dx`` is ambiguous under a
graded profile) and on a band that starts at or below cutoff
(``lambda_g`` is undefined there; the ``port_freqs_below_cutoff``
preflight owns that case).

This enables junction measurements UNDER the documented
discipline; it does NOT make arbitrary compact junctions
valid. Consult ``docs/guides/sparameter_support_matrix.md`` for
the current waveguide evidence and scope.

Mixed-family S-matrix: lumped/wire ports + MSL ports (issue #488).

End-to-end S-parameters on ONE structure carrying two port families — the first supported pair is a homogeneous lumped OR wire set (add_port) together with MSL ports (add_msl_port), e.g. a vertical probe feed launching onto a microstrip line.

Each port is driven in turn (lumped/wire ports first, then MSL ports, registration order within each family); the non-driven lumped/wire ports remain physical matched resistor loads and the non-driven MSL ports are passive probe columns. Extraction reuses the validated per-family wave machinery unchanged and combines the waves in the Kurokawa power-wave convention (each wave divided by sqrt(Re Z0) of its own port) — with unequal reference impedances across families a pseudo-wave ratio would be off by sqrt(Z_j/Z_i) (issue #460); reciprocity of a reciprocal structure is the committed internal falsifier for this choice.

MAGNITUDE CHANNEL (magnitude_channel, default "flux"): the #488 falsifier battery + an independent Poynting-flux referee measured the port-cell V*I accounting undercounting delivered power ~3x at a wire probe feed (the OPEN issue-#313 class) and the analytic Hammerstad-Jensen Z0 anchor diverging from the measured line ratio on an interface-aligned mesh. Off-diagonal MAGNITUDES are therefore taken from Poynting flux by default: auto-registered surfaces (a closed 5-face box around each lumped/wire port over the z-lo ground; a full cross-section plane at each MSL port's probe-0 x) give per-drive net powers, and

|S_ij|^2 = P_arrive,i / (P_net,j / (1 - |S_jj|^2))

where S_jj is the per-family diagonal supplying the reflection correction; no Z0 anchor enters the magnitude. Off-diagonal PHASE still comes from the wave channel (see below). magnitude_channel="wave" keeps the raw power-wave magnitudes (diagnostic; carries the #313 deflation at lumped/wire ports).

HONESTY NOTES (read before quoting numbers):

• Neither diagonal is verified on this lane, and the returned diagonal is not always the measured one. Two separate findings: (a) the wire port-cell V*I accounting was measured undercounting delivered power ~3x against an independent Poynting referee (the open issue #313 reaching the diagonal at a near-field-dominated vertical probe), and on an end-fed fixture the MSL probe plane's local V/I was ~591 ohm and strongly reactive while the reported |S22| was 0.03 — those cannot both be right. (b) With enforce_passivity=True (the default), _project_passive is a JOINT SVD clip: when any entry is non-passive it rewrites others as a side effect. Measured on the committed test fixture, the shipped MSL diagonal came out ~4x its unprojected value. So result.S's diagonal is a projected quantity, not a raw per-family measurement — read S_raw and passivity_correction for what was actually measured, and treat any diagonal-derived conclusion accordingly.

• The flux magnitudes inherit a flux-accounting envelope (box leakage + finite DFT; the Phase-0 referee class measured ~1.3% on the canonical thru) and an ill-conditioning guard: when 1 - |S_jj|^2 is small (near-total reflection at the driven port) the normalization is unreliable and a warning names the column.

• A per-column power sum near 1 is NOT evidence on this channel. Substituting the definition gives sum_i |S_ij|^2 = |S_jj|^2 + (P_arr/P_net)(1 - |S_jj|^2), which is identically 1 whenever the arriving power equals the net launched power — for ANY value of the diagonal. The flux normalization makes passivity an identity, not a measurement, so do not quote column power as a passivity check here (it still detects power GAIN, i.e. P_arr > P_net). The independent internal check on this channel is RECIPROCITY: S_ij and S_ji come from different runs with different normalizations, so their agreement is real evidence. It runs automatically on every extraction (see reciprocity_tol), audits the RAW matrix, and is the check that a wrong diagonal trips.
• With magnitude_channel="wave", off-diagonal magnitudes that RECEIVE at a lumped/wire port cell inherit the issue-#313 near-field deflation of the default port-cell waves. The returned s21_power_witness cross-checks the MSL-receiving direction against a delivered-power normalization; quote it alongside |S|.
• Cross-family off-diagonal PHASE mixes two reference-plane conventions (port cell vs de-embedded MSL probe plane) and a component-mixing ±1 (probes.py sign-convention fence); magnitude is the validated observable.
• settling_db is the ring-down witness (above −40 dB = truncation suspect); preflight output is part of the result.

v1 restrictions (loud NotImplementedError): uniform mesh only, no waveguide/Floquet/coax/TFSF registrations, no bare sources or 0-ohm ports (they would fire in every drive run), no reference_plane_cells wire ports, no mixed lumped+wire set (same fence as the production scan driver), imperative only (no eps_override AD channel). The default "flux" channel adds two more, because the per-port flux box omits its bottom face and treats the port extent as a height: a PEC z_lo boundary and vertical (component="ez") lumped/wire ports are required. magnitude_channel="wave" makes neither assumption.

Parameters

reciprocity_tol : float, default 0.06 Relative |S_ij| vs |S_ji| disagreement above which the reciprocity witness warns. Deliberately set BELOW the 9% residual measured on this lane's own reference fixture, so that fixture warns rather than passing silently: a tolerance above the known residual would document the check and never fire it.

Returns

MixedSMatrixResult

Compute S-parameters on whichever lane this simulation's ports select.

A single entry point over the per-family calculators. It inspects the registrations, chooses exactly one delegate, and forwards **kwargs to it UNCHANGED -- no default is invented here, so the delegate's signature, defaults, preconditions, warnings and return type are exactly what you would get calling it directly.

Dispatch table

=================================== ========================================== ================================ Registered Delegate Returns =================================== ========================================== ================================ waveguide ports only compute_waveguide_s_matrix WaveguideSMatrixResult MSL ports only compute_msl_s_matrix MSLSMatrixResult 1 coaxial port only compute_coaxial_line_reflection or CoaxialLineReflectionResult compute_coaxial_two_port -- ambiguous, or CoaxialTwoPortResult pass lane= 1 coaxial + 1 MSL compute_coax_msl_transition CoaxMSLTransitionResult lumped/wire (add_port) + MSL compute_mixed_s_matrix MixedSMatrixResult lumped/wire only NotImplementedError -- the run lane (Result.s_params) nothing ValueError -- anything else NotImplementedError -- =================================== ========================================== ================================

The lumped/wire family deliberately raises rather than calling run() for you: that lane returns a Result (not an S-matrix result type), and n_steps has no default there, so quietly substituting one would be inventing exactly the kind of default this dispatcher refuses to invent. Run it yourself::

res = sim.run(n_steps=..., compute_s_params=True)
res.s_params

Parameters

lane : str or None Explicit lane name (see s_matrix_lane()). Consumed here, never forwarded. Required for a single coaxial port, where compute_coaxial_line_reflection and compute_coaxial_two_port share one registration footprint; optional elsewhere, where it is checked against the registrations rather than overriding them. **kwargs Forwarded verbatim to the chosen delegate.

Returns

Whatever the chosen delegate returns -- see the table.

Raises

ValueError No ports registered, or lane= contradicts the registrations. Also raised by the chosen lane itself: compute_coax_msl_transition (1 coaxial + 1 MSL) refuses a non-passive extracted S by default and is the only lane in the table that does — forward strict_passivity=False through **kwargs to get the diagnostic matrix with a warning instead (issue #838). NotImplementedError Lumped/wire-only (use the run lane), a single coaxial port with no lane=, or a combination of port families no calculator covers. TypeError An unrecognised keyword argument. **kwargs swallows it here, so the message names the DELEGATE that rejected it -- Simulation.compute_waveguide_s_matrix() got an unexpected keyword argument 'foo' -- which also tells you which lane was chosen.

Notes

Preflight behaviour is inherited from the chosen lane and is not uniform across the table: compute_msl_s_matrix and compute_mixed_s_matrix run preflight automatically, the waveguide and coaxial lanes do not. See each delegate's row in tests/unit/preflight/test_preflight_advisory_emission_contract.py.

See Also

s_matrix_lane : the same choice, without running anything.

Which S-matrix lane this simulation's registrations select.

Runs no FDTD and touches no grid: it reads the port registries only, so it is cheap to call on a half-built Simulation and it is what the dispatch table's tests assert against.

Parameters

lane : str or None Optional explicit lane name, one of the compute_* names below or "run(compute_s_params=True)". Required on the single-coaxial-port row, where two lanes share one registration footprint (see the module docstring). On every other row it is checked against the lane the registrations determine and raises ValueError if it disagrees -- it can select a lane, never override the physics fence.

Returns

str The delegate's method name, e.g. "compute_waveguide_s_matrix", or the literal "run(compute_s_params=True)" for the lumped/wire family, which has no compute_* method.

Raises

ValueError No ports registered at all (the message lists the add_*_port builders), or a lane= that contradicts the registrations. NotImplementedError A single coaxial port (ambiguous -- pass lane=), or any combination of families no calculator covers. The message names the registered families with their counts.

Examples

>>> sim.add_waveguide_port(...); sim.add_waveguide_port(...)
>>> sim.s_matrix_lane()
'compute_waveguide_s_matrix'

Create new instance of SimResult(state, time_series, ntff_data, dft_planes, flux_monitors, waveguide_ports, wire_port_sparams, lumped_port_sparams, snapshots, ntff_box, grid, wire_refplane_sparams, snapshot_axes, dt, current_moment_data, current_moment_monitor, adjoint_settling, sparam_time_records, dft_time_records)

Alias for field number 0

Alias for field number 1

Alias for field number 2

Alias for field number 3

Alias for field number 4

Alias for field number 5

Alias for field number 6

Alias for field number 7

Alias for field number 8