witwin-maxwell 0.3.0__py3-none-win_amd64.whl

witwin/maxwell/fdtd/excitation/tfsf_apply.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+import torch
+
+from .tfsf_specs import reference_sample_axis_code
+from .temporal import apply_generic_source_terms
+
+
+_REFERENCE_PROVIDERS = {"plane_wave_ref_x_ez", "plane_wave_axis_aligned"}
+_AUXILIARY_PROVIDERS = {"plane_wave_ref_x_ez", "plane_wave_axis_aligned", "plane_wave_aux"}
+
+_MAGNETIC_FIELD_NAMES = ("Hx", "Hy", "Hz")
+_ELECTRIC_FIELD_NAMES = ("Ex", "Ey", "Ez")
+
+
+def _field_names_for_terms(term_key):
+    return _MAGNETIC_FIELD_NAMES if term_key == "magnetic_terms" else _ELECTRIC_FIELD_NAMES
+
+
+def _apply_batched_aux_terms(solver, batch, *, sample_kind, field_names):
+    if batch is None:
+        return
+
+    aux = solver._tfsf_state["auxiliary_grid"]
+    sample_origin = float(aux.s_min if sample_kind == "electric" else aux.s_min + 0.5 * aux.ds)
+    sample_field = aux.electric if sample_kind == "electric" else aux.magnetic
+    solver.fdtd_module.addBatchedInterpolatedSourcePatches3D(
+        fieldX=getattr(solver, field_names[0]),
+        fieldY=getattr(solver, field_names[1]),
+        fieldZ=getattr(solver, field_names[2]),
+        coeffData=batch["coeff_data"],
+        incidentField=sample_field,
+        samplePositions=batch["sample_positions"],
+        termStarts=batch["term_starts"],
+        termShapes=batch["term_shapes"],
+        termOffsets=batch["term_offsets"],
+        fieldCodes=batch["field_codes"],
+        fieldCodesPerCoeff=batch["field_codes_per_coeff"],
+        fieldOffsets=batch["field_offsets"],
+        origin=sample_origin,
+        ds=float(aux.ds),
+    ).launchRaw()
+
+
+def _apply_batched_reference_terms(solver, batch, *, sample_kind, field_names):
+    if batch is None:
+        return
+
+    aux = solver._tfsf_state["auxiliary_grid"]
+    sample_field = aux.electric if sample_kind == "electric" else aux.magnetic
+    solver.fdtd_module.addBatchedReferenceSourcePatches3D(
+        fieldX=getattr(solver, field_names[0]),
+        fieldY=getattr(solver, field_names[1]),
+        fieldZ=getattr(solver, field_names[2]),
+        coeffData=batch["coeff_data"],
+        incidentField=sample_field,
+        termStarts=batch["term_starts"],
+        termShapes=batch["term_shapes"],
+        termOffsets=batch["term_offsets"],
+        fieldCodes=batch["field_codes"],
+        sampleAxisCodes=batch["sample_axis_codes"],
+        sampleIndexStarts=batch["sample_index_starts"],
+        sampleIndices=batch["sample_indices"],
+        fieldCodesPerCoeff=batch["field_codes_per_coeff"],
+        fieldOffsets=batch["field_offsets"],
+        sampleIndicesPerCoeff=batch["sample_indices_per_coeff"],
+    ).launchRaw()
+
+
+def _apply_aux_terms(solver, terms, *, sample_kind):
+    if not terms:
+        return
+    aux = solver._tfsf_state["auxiliary_grid"]
+    sample_origin = float(aux.s_min if sample_kind == "electric" else aux.s_min + 0.5 * aux.ds)
+    sample_field = aux.electric if sample_kind == "electric" else aux.magnetic
+    for term in terms:
+        offset_i, offset_j, offset_k = term["offsets"]
+        solver.fdtd_module.addInterpolatedSourcePatch3D(
+            field=getattr(solver, term["field_name"]),
+            coeffPatch=term["coeff_patch"],
+            incidentField=sample_field,
+            samplePositions=term["sample_positions"],
+            origin=sample_origin,
+            ds=float(aux.ds),
+            offsetI=int(offset_i),
+            offsetJ=int(offset_j),
+            offsetK=int(offset_k),
+            scale=float(term["component_scale"]),
+        ).launchRaw()
+
+
+def _apply_reference_terms(solver, terms):
+    if not terms:
+        return
+
+    aux = solver._tfsf_state["auxiliary_grid"]
+    for term in terms:
+        sample_field = aux.electric if term["sample_kind"] == "electric" else aux.magnetic
+        if term["scalar_sample_index"] is not None:
+            offset_i, offset_j, offset_k = term["offsets"]
+            solver.fdtd_module.addScaledSliceSourcePatch3D(
+                field=getattr(solver, term["field_name"]),
+                sourcePatch=term["coeff_patch"],
+                incidentField=sample_field,
+                sampleIndex=int(term["scalar_sample_index"]),
+                offsetI=int(offset_i),
+                offsetJ=int(offset_j),
+                offsetK=int(offset_k),
+                scale=float(term["component_scale"]),
+            ).launchRaw()
+            continue
+        sample_indices_i32 = term.get("_sample_indices_i32")
+        if (
+            sample_indices_i32 is None
+            or not torch.is_tensor(sample_indices_i32)
+            or sample_indices_i32.device != sample_field.device
+        ):
+            sample_indices_i32 = term["sample_indices"].to(device=sample_field.device, dtype=torch.int32)
+            term["_sample_indices_i32"] = sample_indices_i32
+        sample_axis_code = int(term.get("_sample_axis_code", reference_sample_axis_code(term)))
+        term["_sample_axis_code"] = sample_axis_code
+        offset_i, offset_j, offset_k = term["offsets"]
+        solver.fdtd_module.addScaledLineSourcePatch3D(
+            field=getattr(solver, term["field_name"]),
+            coeffPatch=term["coeff_patch"],
+            incidentField=sample_field,
+            sampleIndices=sample_indices_i32,
+            sampleAxisCode=sample_axis_code,
+            offsetI=int(offset_i),
+            offsetJ=int(offset_j),
+            offsetK=int(offset_k),
+            scale=float(term["component_scale"]),
+        ).launchRaw()
+
+
+def _apply_tfsf_terms(solver, *, term_key, sample_kind, time_value):
+    if not getattr(solver, "tfsf_enabled", False):
+        return
+
+    provider = solver._tfsf_state.get("provider")
+    terms = solver._tfsf_state[term_key]
+    batch = solver._tfsf_state.get("magnetic_batch" if term_key == "magnetic_terms" else "electric_batch")
+    field_names = _field_names_for_terms(term_key)
+    if provider in _REFERENCE_PROVIDERS:
+        if batch is not None:
+            _apply_batched_reference_terms(
+                solver,
+                batch,
+                sample_kind=sample_kind,
+                field_names=field_names,
+            )
+            return
+        _apply_reference_terms(solver, terms)
+        return
+    if provider == "plane_wave_aux":
+        if batch is not None:
+            _apply_batched_aux_terms(
+                solver,
+                batch,
+                sample_kind=sample_kind,
+                field_names=field_names,
+            )
+            return
+        _apply_aux_terms(solver, terms, sample_kind=sample_kind)
+        return
+    apply_generic_source_terms(
+        solver,
+        terms,
+        source_time=solver._source_time,
+        omega=solver.source_omega,
+        time_value=time_value,
+        clamp_pec=False,
+    )
+
+
+# TFSF providers whose in-block correction both (1) reads the incident field from
+# the device-resident auxiliary 1D grid -- carrying no per-step host input -- and
+# (2) accumulates through the integer-indexed *reference* injection kernel, whose
+# warp-aggregated writes are collision-free for the axis-aligned face layout and
+# therefore bit-reproducible. This covers both injection modes of the axis-aligned
+# reference providers: the six-face box TFSF and the two-face (slab) TFSF share the
+# same auxiliary-line provider and reference kernels, so the non-periodic
+# normal-incidence slab captures identically to the box. The oblique auxiliary-line
+# provider (``plane_wave_aux``) is deliberately excluded: it accumulates through the
+# batched *interpolated* kernel, whose cross-warp atomic adds at the overlapping
+# oblique faces are not bit-reproducible run to run, so a captured graph could not
+# be proven bit-identical to the eager path. The grating-slab (``plane_wave_grating_
+# slab_cw``) and box-CW (``plane_wave_discrete_cw``) providers evaluate the incident
+# CW phasor on the host each step through ``apply_generic_source_terms`` and inject
+# it as a kernel launch scalar a captured graph would freeze, so they are excluded
+# too.
+_CAPTURABLE_TFSF_PROVIDERS = frozenset(_REFERENCE_PROVIDERS)
+
+
+def tfsf_incident_is_gpu_driven(solver) -> bool:
+    """True when an active TFSF source couples into the 3D field-update block only
+    by *reading* the device-resident auxiliary 1D incident grid through the
+    bit-reproducible reference injection kernel, so the block can be captured into a
+    CUDA graph and replayed bit-for-bit.
+
+    The reference providers apply their in-block H correction with the batched /
+    per-term reference kernels, which read ``aux.electric`` / ``aux.magnetic``
+    (persistent device tensors) at fixed integer sample indices and carry no
+    per-step host input. The 1D source waveform is evaluated on the host only in
+    ``advance_tfsf_auxiliary_electric`` (the E-side auxiliary advance), which runs
+    eagerly *after* the field-update block, outside the captured region. So for
+    these providers the block is a fixed, deterministic kernel sequence. This holds
+    for both the six-face box TFSF and the two-face (slab) TFSF, which share the
+    axis-aligned reference provider, so the non-periodic normal-incidence slab is
+    capturable exactly like the box.
+
+    The oblique auxiliary-line provider (``plane_wave_aux``) is excluded because its
+    batched interpolated injection kernel accumulates through non-deterministic
+    cross-warp atomic adds (bit-identical capture parity is impossible). The
+    grating-slab provider (``plane_wave_grating_slab_cw``, the Bloch-transverse
+    oblique slab) and the box-CW provider (``plane_wave_discrete_cw``) each evaluate
+    the incident CW phasor on the host every step via ``apply_generic_source_terms``
+    and inject it as a kernel launch scalar a captured graph would freeze at its
+    capture-time value, so they too stay on the eager path (capturing them would
+    require a GPU-driven generic source table, which is out of scope here).
+    """
+    state = getattr(solver, "_tfsf_state", None)
+    if not state:
+        return False
+    return state.get("provider") in _CAPTURABLE_TFSF_PROVIDERS
+
+
+def apply_tfsf_h_correction(solver, time_value):
+    _apply_tfsf_terms(
+        solver,
+        term_key="magnetic_terms",
+        sample_kind="electric",
+        time_value=time_value,
+    )
+
+
+def apply_tfsf_e_correction(solver, time_value):
+    _apply_tfsf_terms(
+        solver,
+        term_key="electric_terms",
+        sample_kind="magnetic",
+        time_value=time_value + 0.5 * float(solver.dt),
+    )
+
+
+def _advance_auxiliary_grid(solver, *, magnetic):
+    if not getattr(solver, "tfsf_enabled", False):
+        return None
+    if solver._tfsf_state.get("provider") not in _AUXILIARY_PROVIDERS:
+        return None
+    aux = solver._tfsf_state["auxiliary_grid"]
+    if magnetic:
+        aux.advance_magnetic()
+    else:
+        aux.advance_electric()
+    return None
+
+
+def advance_tfsf_auxiliary_magnetic(solver):
+    return _advance_auxiliary_grid(solver, magnetic=True)
+
+
+def advance_tfsf_auxiliary_electric(solver):
+    return _advance_auxiliary_grid(solver, magnetic=False)

witwin/maxwell/fdtd/excitation/tfsf_common.py

@@ -0,0 +1,421 @@
+from __future__ import annotations
+
+import math
+
+import torch
+
+from ..dispersion import solve_numerical_wavenumber
+from .spatial import beam_profile_from_source, plane_wave_profile
+from .tfsf_specs import AXIS_INDEX, reference_sample_axis_code
+from .temporal import build_source_term
+
+
+def nearest_index(axis_coords, value: float) -> int:
+    return int(torch.argmin(torch.abs(axis_coords - float(value))).item())
+
+
+def resolve_bounds_indices(scene, bounds):
+    lower = []
+    upper = []
+    for axis_coords, axis_bounds in zip((scene.x, scene.y, scene.z), bounds):
+        lower.append(nearest_index(axis_coords, axis_bounds[0]))
+        upper.append(nearest_index(axis_coords, axis_bounds[1]))
+    return tuple(lower), tuple(upper)
+
+
+# Relative spacing spread at or below which the injection region is treated as
+# exactly uniform: the legacy scalar spacing is returned bit-for-bit and no new
+# numerics run, so uniform grids stay unchanged.
+_UNIFORM_SPACING_RTOL = 1e-6
+# Maximum tolerated numerical phase-velocity spread across a TFSF injection
+# region before the single auxiliary-grid spacing can no longer match the graded
+# main grid. The leading FDTD dispersion relation gives a relative
+# numerical-wavenumber excess of (k0*d)^2/24 for a vacuum wave of wavenumber
+# k0 = omega/c (the TFSF background is enforced to be vacuum); the spread of that
+# excess between the finest and coarsest cell in the region is the residual the
+# total/scattered-field faces cannot cancel and thus leaks into the scattered
+# region. 1e-3 keeps that residual at or below the uniform-grid leakage floor the
+# axis-aligned null tests already assert.
+_TFSF_DISPERSION_SPREAD_BOUND = 1e-3
+
+
+def require_locally_uniform_axis(solver, axis, start, stop, *, context):
+    """Return the effective primal spacing over cells [start, stop) for the
+    auxiliary-grid dispersion match, accepting a bounded amount of grading.
+
+    A perfectly uniform region (spread <= ``_UNIFORM_SPACING_RTOL`` relative)
+    returns its exact cell spacing, bit-for-bit as before. A mildly graded region
+    is accepted when the numerical phase-velocity spread it induces across the
+    region stays below ``_TFSF_DISPERSION_SPREAD_BOUND``, in which case the
+    region-mean spacing is used as the single effective delta. A region too
+    graded for that bound raises with the predicted error, because a single
+    auxiliary spacing would inject a spurious incident field on the TFSF faces.
+    """
+    primal = {
+        "x": solver.scene.dx_primal64,
+        "y": solver.scene.dy_primal64,
+        "z": solver.scene.dz_primal64,
+    }[axis]
+    window = primal[max(int(start), 0) : min(int(stop), len(primal))]
+    d_min = float(window.min())
+    d_max = float(window.max())
+    if (d_max - d_min) <= _UNIFORM_SPACING_RTOL * d_max:
+        return d_min
+
+    # Region-mean effective spacing minimizes the mean phase mismatch; the
+    # residual is the numerical-dispersion wavenumber spread it leaves across the
+    # region, evaluated at the source (center) frequency.
+    d_eff = float(window.mean())
+    k0 = abs(float(solver.source_omega)) / float(solver.c)
+    dispersion_spread = (k0 * k0) * (d_max * d_max - d_min * d_min) / 24.0
+    if dispersion_spread > _TFSF_DISPERSION_SPREAD_BOUND:
+        raise ValueError(
+            f"{context} along axis '{axis}' is too graded for the auxiliary-grid "
+            "dispersion match: the numerical phase-velocity spread across the "
+            f"injection region (+1 cell) is {dispersion_spread:.3e} "
+            f"(min={d_min:g}, max={d_max:g}, k0={k0:g}), above the bound "
+            f"{_TFSF_DISPERSION_SPREAD_BOUND:.0e}. Refine GridSpec.custom for "
+            f"locally uniform grid spacing along axis '{axis}' over the injection "
+            "region, or move the region."
+        )
+    return d_eff
+
+
+def validate_bounds(solver, lower, upper):
+    shape = (solver.Nx, solver.Ny, solver.Nz)
+    for axis, lo, hi, size in zip("xyz", lower, upper, shape):
+        low_margin = solver.scene.pml_thickness_for_face(axis, "low") + 2
+        high_margin = solver.scene.pml_thickness_for_face(axis, "high") + 2
+        if hi <= lo + 1:
+            raise ValueError(f"TFSF bounds must span at least two cells along {axis}.")
+        if lo < low_margin or hi > size - high_margin - 1:
+            raise ValueError("TFSF bounds must lie strictly inside the non-PML simulation region.")
+
+
+def validate_background_is_vacuum(solver, lower, upper, tol=1e-5):
+    eps = solver.epsilon_r
+    mu = solver.mu_r
+    slices = (
+        (slice(lower[0], lower[0] + 1), slice(lower[1], upper[1] + 1), slice(lower[2], upper[2] + 1)),
+        (slice(upper[0], upper[0] + 1), slice(lower[1], upper[1] + 1), slice(lower[2], upper[2] + 1)),
+        (slice(lower[0], upper[0] + 1), slice(lower[1], lower[1] + 1), slice(lower[2], upper[2] + 1)),
+        (slice(lower[0], upper[0] + 1), slice(upper[1], upper[1] + 1), slice(lower[2], upper[2] + 1)),
+        (slice(lower[0], upper[0] + 1), slice(lower[1], upper[1] + 1), slice(lower[2], lower[2] + 1)),
+        (slice(lower[0], upper[0] + 1), slice(lower[1], upper[1] + 1), slice(upper[2], upper[2] + 1)),
+    )
+    for face_slice in slices:
+        eps_face = eps[face_slice]
+        mu_face = mu[face_slice]
+        if not torch.allclose(eps_face, torch.ones_like(eps_face), atol=tol, rtol=0.0):
+            raise ValueError("TFSF boundary must remain in vacuum on all faces.")
+        if not torch.allclose(mu_face, torch.ones_like(mu_face), atol=tol, rtol=0.0):
+            raise ValueError("TFSF boundary must remain in vacuum on all faces.")
+
+
+def solve_auxiliary_step(solver, k_numeric: float) -> float:
+    omega = float(solver.source_omega)
+    if omega <= 0.0 or k_numeric <= 1e-12:
+        return float(solver.c) * float(solver.dt)
+
+    rhs = math.sin(0.5 * omega * float(solver.dt)) / (float(solver.c) * float(solver.dt))
+    low = float(solver.c) * float(solver.dt) * (1.0 + 1e-6)
+    high = 0.999 * math.pi / k_numeric
+    if high <= low:
+        high = low * 1.5
+
+    def residual(ds):
+        return math.sin(0.5 * k_numeric * ds) / ds - rhs
+
+    low_residual = residual(low)
+    high_residual = residual(high)
+    if low_residual < 0.0:
+        return low
+    if high_residual > 0.0:
+        return high
+
+    for _ in range(80):
+        mid = 0.5 * (low + high)
+        if residual(mid) >= 0.0:
+            low = mid
+        else:
+            high = mid
+    return 0.5 * (low + high)
+
+
+def entry_projection(bounds, direction):
+    x_bounds, y_bounds, z_bounds = bounds
+    min_projection = None
+    for x in x_bounds:
+        for y in y_bounds:
+            for z in z_bounds:
+                projection = x * float(direction[0]) + y * float(direction[1]) + z * float(direction[2])
+                if min_projection is None or projection < min_projection:
+                    min_projection = projection
+    return float(min_projection)
+
+
+def projection_extrema(bounds, direction):
+    x_bounds, y_bounds, z_bounds = bounds
+    min_projection = None
+    max_projection = None
+    for x in x_bounds:
+        for y in y_bounds:
+            for z in z_bounds:
+                projection = x * float(direction[0]) + y * float(direction[1]) + z * float(direction[2])
+                if min_projection is None or projection < min_projection:
+                    min_projection = projection
+                if max_projection is None or projection > max_projection:
+                    max_projection = projection
+    return float(min_projection), float(max_projection)
+
+
+def box_center_tensor(solver, bounds):
+    return torch.tensor(
+        [
+            0.5 * (bounds[0][0] + bounds[0][1]),
+            0.5 * (bounds[1][0] + bounds[1][1]),
+            0.5 * (bounds[2][0] + bounds[2][1]),
+        ],
+        device=solver.device,
+        dtype=solver.Ex.dtype,
+    )
+
+
+def make_aux_term(solver, *, field_name, offsets, coeff_patch, sample_positions, component_scale):
+    return {
+        "field_name": field_name,
+        "offsets": offsets,
+        "coeff_patch": coeff_patch.contiguous(),
+        "sample_positions": sample_positions.contiguous(),
+        "component_scale": float(component_scale),
+    }
+
+
+def _field_component_code(field_name: str) -> int:
+    component = field_name[-1].lower()
+    if component == "x":
+        return 0
+    if component == "y":
+        return 1
+    return 2
+
+
+def _pack_batched_term_metadata(solver, terms):
+    coeff_cursor = 0
+    term_starts = []
+    term_shapes = []
+    term_offsets = []
+    field_codes = []
+    coeff_chunks = []
+    field_code_chunks = []
+    field_offset_chunks = []
+    field_offset_dtype = torch.int32
+    for term in terms:
+        field_shape = tuple(int(length) for length in getattr(solver, term["field_name"]).shape)
+        if math.prod(field_shape) > torch.iinfo(torch.int32).max:
+            field_offset_dtype = torch.int64
+            break
+
+    for term_index, term in enumerate(terms):
+        coeff_flat = (term["coeff_patch"] * float(term["component_scale"])).reshape(-1)
+        shape = tuple(int(length) for length in term["coeff_patch"].shape)
+        offsets = tuple(int(offset) for offset in term["offsets"])
+        local_linear = torch.arange(int(coeff_flat.numel()), device=solver.device, dtype=torch.int32)
+        stride_i = shape[1] * shape[2]
+        local_i = local_linear // stride_i
+        remainder = local_linear - local_i * stride_i
+        local_j = remainder // shape[2]
+        local_k = remainder - local_j * shape[2]
+        field_code = _field_component_code(term["field_name"])
+        field_shape = tuple(int(length) for length in getattr(solver, term["field_name"]).shape)
+        field_i = local_i + offsets[0]
+        field_j = local_j + offsets[1]
+        field_k = local_k + offsets[2]
+        coeff_chunks.append(coeff_flat)
+        field_code_chunks.append(
+            torch.full(
+                (int(coeff_flat.numel()),),
+                field_code,
+                device=solver.device,
+                dtype=torch.int32,
+            )
+        )
+        field_offset_chunks.append(
+            (
+                field_i.to(dtype=torch.int64) * (field_shape[1] * field_shape[2])
+                + field_j.to(dtype=torch.int64) * field_shape[2]
+                + field_k.to(dtype=torch.int64)
+            ).to(dtype=field_offset_dtype).contiguous()
+        )
+        term_starts.append(coeff_cursor)
+        term_shapes.append(list(shape))
+        term_offsets.append(list(offsets))
+        field_codes.append(field_code)
+        coeff_cursor += int(coeff_flat.numel())
+
+    if not coeff_chunks:
+        return None
+
+    coeff_data = torch.cat(coeff_chunks).contiguous()
+    return {
+        "coeff_data": coeff_data,
+        "term_starts": torch.tensor(term_starts, device=solver.device, dtype=torch.int32),
+        "term_shapes": torch.tensor(term_shapes, device=solver.device, dtype=torch.int32),
+        "term_offsets": torch.tensor(term_offsets, device=solver.device, dtype=torch.int32),
+        "field_codes": torch.tensor(field_codes, device=solver.device, dtype=torch.int32),
+        "field_codes_per_coeff": torch.cat(field_code_chunks).contiguous(),
+        "field_offsets": torch.cat(field_offset_chunks).contiguous(),
+    }
+
+
+def build_batched_reference_terms(solver, terms):
+    metadata = _pack_batched_term_metadata(solver, terms)
+    if metadata is None:
+        return None
+
+    sample_cursor = 0
+    sample_axis_codes = []
+    sample_index_starts = []
+    sample_chunks = []
+    sample_index_per_coeff_chunks = []
+    for term in terms:
+        sample_indices = term["sample_indices"].to(device=solver.device, dtype=torch.int32).reshape(-1)
+        shape = tuple(int(length) for length in term["coeff_patch"].shape)
+        local_linear = torch.arange(int(term["coeff_patch"].numel()), device=solver.device, dtype=torch.int32)
+        stride_i = shape[1] * shape[2]
+        local_i = local_linear // stride_i
+        remainder = local_linear - local_i * stride_i
+        local_j = remainder // shape[2]
+        local_k = remainder - local_j * shape[2]
+        axis = int(reference_sample_axis_code(term))
+        sample_linear = local_i if axis == 0 else (local_j if axis == 1 else local_k)
+        sample_chunks.append(sample_indices)
+        sample_index_per_coeff_chunks.append(sample_indices[sample_linear.to(dtype=torch.long)])
+        sample_axis_codes.append(axis)
+        sample_index_starts.append(sample_cursor)
+        sample_cursor += int(sample_indices.numel())
+
+    metadata["sample_axis_codes"] = torch.tensor(sample_axis_codes, device=solver.device, dtype=torch.int32)
+    metadata["sample_index_starts"] = torch.tensor(sample_index_starts, device=solver.device, dtype=torch.int32)
+    metadata["sample_indices"] = torch.cat(sample_chunks).contiguous()
+    metadata["sample_indices_per_coeff"] = torch.cat(sample_index_per_coeff_chunks).contiguous()
+    return metadata
+
+
+def build_batched_aux_terms(solver, terms):
+    metadata = _pack_batched_term_metadata(solver, terms)
+    if metadata is None:
+        return None
+
+    metadata["sample_positions"] = torch.cat(
+        [term["sample_positions"].reshape(-1) for term in terms]
+    ).contiguous()
+    return metadata
+
+
+def slice_coeff_patch(solver, spec, curl_attr_map):
+    offsets = spec["offsets"]
+    shape = spec["shape"]
+    axis = spec["delta_axis"]
+    scene = solver.scene
+    # The spec is a one-cell curl correction: E-face terms divide by the dual
+    # spacing at the E element's coordinate, H-face terms by the primal
+    # spacing at the H element's coordinate (the spacing their field update
+    # uses along the derivative axis).
+    if spec["field_name"].startswith("E"):
+        spacing64 = {"x": scene.dx_dual64, "y": scene.dy_dual64, "z": scene.dz_dual64}[axis]
+    else:
+        spacing64 = {"x": scene.dx_primal64, "y": scene.dy_primal64, "z": scene.dz_primal64}[axis]
+    delta = float(spacing64[int(offsets[AXIS_INDEX[axis]])])
+    return getattr(solver, curl_attr_map[spec["field_name"]])[
+        offsets[0] : offsets[0] + shape[0],
+        offsets[1] : offsets[1] + shape[1],
+        offsets[2] : offsets[2] + shape[2],
+    ] / delta
+
+
+def build_terms_from_specs(solver, specs, vector, curl_attr_map, term_factory):
+    terms = []
+    for spec in specs:
+        component_scale = vector[spec["incident_name"]]
+        coeff = float(spec["sign"]) * component_scale
+        if isinstance(coeff, torch.Tensor):
+            if torch.max(torch.abs(coeff)).item() <= 1e-12:
+                continue
+        elif abs(float(coeff)) <= 1e-12:
+            continue
+        coeff_patch = slice_coeff_patch(solver, spec, curl_attr_map)
+        term = term_factory(spec, coeff_patch, component_scale)
+        if term is not None:
+            terms.append(term)
+    return terms
+
+
+def build_term_from_profile(
+    solver,
+    *,
+    field_name,
+    offsets,
+    scale,
+    delay_patch,
+    activation_delay_patch,
+    source_time,
+    omega,
+    source_index=None,
+):
+    if torch.max(torch.abs(scale)).item() <= 1e-12:
+        return None
+    if source_time["kind"] == "cw" and activation_delay_patch is None:
+        phase_shift = float(omega) * delay_patch
+        return build_source_term(
+            solver,
+            field_name=field_name,
+            offsets=offsets,
+            cw_cos_patch=scale * torch.cos(phase_shift),
+            cw_sin_patch=scale * torch.sin(phase_shift),
+            source_index=source_index,
+            source_time=source_time,
+            omega=omega,
+        )
+    return build_source_term(
+        solver,
+        field_name=field_name,
+        offsets=offsets,
+        patch=scale,
+        delay_patch=delay_patch,
+        activation_delay_patch=activation_delay_patch,
+        source_index=source_index,
+        source_time=source_time,
+        omega=omega,
+    )
+
+
+def incident_profile(
+    solver,
+    source,
+    positions,
+    reference_point,
+    *,
+    phase_speed,
+    source_frequency=None,
+    polarization_override=None,
+):
+    if source["kind"] == "plane_wave":
+        return plane_wave_profile(
+            positions,
+            direction=source["direction"],
+            reference_point=reference_point,
+            propagation_speed=phase_speed,
+        )
+    return beam_profile_from_source(
+        positions,
+        source,
+        frequency=solver.source_frequency if source_frequency is None else float(source_frequency),
+        propagation_speed=phase_speed,
+        polarization=polarization_override,
+    )
+
+
+def project_positions(positions, direction):
+    direction_tensor = positions.new_tensor(direction)
+    return torch.sum(positions * direction_tensor, dim=-1)