tidy3d 2.11.0.dev0__tar.gz → 2.11.0.dev1__tar.gz

{tidy3d-2.11.0.dev0 → tidy3d-2.11.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tidy3d
-Version: 2.11.0.dev0
+Version: 2.11.0.dev1
 Summary: A fast FDTD solver
 License: LGPLv2+
 License-File: LICENSE
@@ -22,6 +22,7 @@ Provides-Extra: extras
 Provides-Extra: gdstk
 Provides-Extra: heatcharge
 Provides-Extra: pytorch
+Provides-Extra: pyvista
 Provides-Extra: ruff
 Provides-Extra: scikit-rf
 Provides-Extra: tests
@@ -52,13 +53,14 @@ Requires-Dist: matplotlib (>=3.10.0,<4.0.0)
 Requires-Dist: memory_profiler (>=0.61.0,<0.62.0) ; extra == "dev"
 Requires-Dist: mypy (==1.13.0) ; extra == "dev"
 Requires-Dist: myst-parser (>=4.0.1,<5.0.0) ; extra == "dev" or extra == "docs"
-Requires-Dist: nbconvert (>=7.11.0,<8.0.0) ; extra == "dev" or extra == "docs"
+Requires-Dist: nbconvert (>=7.17.0,<8.0.0) ; extra == "dev" or extra == "docs"
 Requires-Dist: nbdime (>=4.0.2,<5.0.0) ; extra == "dev" or extra == "docs"
 Requires-Dist: nbsphinx (>=0.8.7,<0.10.0) ; extra == "dev" or extra == "docs"
 Requires-Dist: networkx (>=2.6.3,<3.0.0) ; extra == "dev" or extra == "trimesh"
 Requires-Dist: numpy (>=2.2.6,<2.5.0)
 Requires-Dist: openpyxl (>=3.1.5,<4.0.0) ; extra == "dev" or extra == "docs"
 Requires-Dist: optax (>=0.2.2,<0.3.0) ; extra == "dev" or extra == "docs"
+Requires-Dist: orbax-checkpoint (<0.11.33) ; extra == "dev" or extra == "tests" or extra == "docs"
 Requires-Dist: pandas (>=2.2,<3.0)
 Requires-Dist: pre-commit (>=4,<5) ; extra == "dev" or extra == "tests"
 Requires-Dist: psutil (>=7.2.1,<8.0.0) ; extra == "dev" or extra == "tests"
@@ -76,6 +78,7 @@ Requires-Dist: pytest-env (>=1.1.5,<2.0.0) ; extra == "dev" or extra == "tests"
 Requires-Dist: pytest-testmon (>=2.1.3,<3.0.0) ; extra == "dev" or extra == "tests"
 Requires-Dist: pytest-timeout (>=2.4.0,<3.0.0) ; extra == "dev" or extra == "tests"
 Requires-Dist: pytest-xdist (>=3.6.1,<4.0.0) ; extra == "dev" or extra == "tests"
+Requires-Dist: pyvista (>=0.45,<0.47.0) ; extra == "dev" or extra == "pyvista"
 Requires-Dist: requests (>=2.31.0,<3.0.0)
 Requires-Dist: responses (>=0.25.8,<0.26.0)
 Requires-Dist: rich (>=13.0,<14.0)
@@ -95,7 +98,7 @@ Requires-Dist: sphinx-notfound-page (>=1.1.0,<2.0.0) ; extra == "dev" or extra =
 Requires-Dist: sphinx-sitemap (>=2.5.1,<3.0.0) ; extra == "dev" or extra == "docs"
 Requires-Dist: sphinx-tabs (>=3.4.7,<4.0.0) ; extra == "dev" or extra == "docs"
 Requires-Dist: sphinxemoji (>=0.3.2,<0.4.0) ; extra == "dev" or extra == "docs"
-Requires-Dist: tidy3d-extras (==2.11.0.dev0) ; extra == "extras"
+Requires-Dist: tidy3d-extras (==2.11.0.dev1) ; extra == "extras"
 Requires-Dist: tmm (>=0.2.0,<0.3.0) ; extra == "dev" or extra == "docs"
 Requires-Dist: toml (>=0.10.2,<0.11.0)
 Requires-Dist: tomlkit (>=0.13.2,<0.14.0)
@@ -103,9 +106,12 @@ Requires-Dist: torch (>=2.2.0,<3.0.0) ; (sys_platform != "darwin") and (extra ==
 Requires-Dist: torch (>=2.2.0,<3.0.0) ; (sys_platform == "darwin") and (extra == "dev" or extra == "pytorch")
 Requires-Dist: towncrier (>=25.8.0,<26.0.0) ; extra == "dev"
 Requires-Dist: tox (>=4.33.0,<5.0.0) ; extra == "dev"
+Requires-Dist: trame (>=3.0.0,<4.0.0) ; extra == "dev" or extra == "pyvista"
+Requires-Dist: trame-vtk (>=2.0.0,<3.0.0) ; extra == "dev" or extra == "pyvista"
+Requires-Dist: trame-vuetify (>=2.0.0,<3.0.0) ; extra == "dev" or extra == "pyvista"
 Requires-Dist: trimesh (>=4.6,<5.0.0) ; extra == "dev" or extra == "tests" or extra == "trimesh" or extra == "heatcharge"
 Requires-Dist: typing-extensions (>=4.15.0,<5.0.0)
-Requires-Dist: vtk (>=9.2.6,<10.0.0) ; extra == "dev" or extra == "vtk" or extra == "heatcharge"
+Requires-Dist: vtk (>=9.2.6,<10.0.0) ; extra == "dev" or extra == "vtk" or extra == "pyvista" or extra == "heatcharge"
 Requires-Dist: xarray (>=2023.8,<2026.0.0)
 Requires-Dist: zizmor (>=1.20.0,<2.0.0) ; extra == "dev"
 Project-URL: Bug Tracker, https://github.com/flexcompute/tidy3d/issues

{tidy3d-2.11.0.dev0 → tidy3d-2.11.0.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "tidy3d"
-version = "2.11.0.dev0"
+version = "2.11.0.dev1"
 description = "A fast FDTD solver"
 authors = ["Tyler Hughes <tyler@flexcompute.com>"]
 license = "LGPLv2+"
@@ -100,7 +100,7 @@ trimesh = { version = ">=4.6,<5.0.0", optional = true }
 # docs
 jupyter = { version = "^1.1.1", optional = true }
 jinja2 = { version = ">=3.1.2,<4.0.0", optional = true }
-nbconvert = { version = ">=7.11.0,<8.0.0", optional = true }
+nbconvert = { version = ">=7.17.0,<8.0.0", optional = true }
 sphinx = { version = ">=6,<9.0.0", optional = true }
 nbsphinx = { version = ">=0.8.7,<0.10.0", optional = true }
 sphinx-copybutton = { version = ">=0.5.2,<0.6.0", optional = true }
@@ -119,12 +119,17 @@ myst-parser = { version = "^4.0.1", optional = true }
 optax = { version = ">=0.2.2,<0.3.0", optional = true }
 signac = { version = "^2.3.0", optional = true }
 flax = { version = ">=0.8.2,<0.13", optional = true }
+orbax-checkpoint = { version = "<0.11.33", optional = true }
 sax = { version = "^0.11", optional = true }
 vtk = { version = ">=9.2.6,<10.0.0", optional = true }
+pyvista = { version = ">=0.45,<0.47.0", optional = true }
+trame = { version = ">=3.0.0,<4.0.0", optional = true }
+trame-vtk = { version = ">=2.0.0,<3.0.0", optional = true }
+trame-vuetify = { version = ">=2.0.0,<3.0.0", optional = true }
 sphinxemoji = { version = "^0.3.2", optional = true }
 cma = { version = "^4.4.1", optional = true }
 openpyxl = { version = "^3.1.5", optional = true }
-tidy3d-extras = { version = "2.11.0.dev0", optional = true }
+tidy3d-extras = { version = "2.11.0.dev1", optional = true }
 
 [tool.poetry.extras]
 dev = [
@@ -147,6 +152,7 @@ dev = [
   'nbsphinx',
   'networkx',
   'optax',
+  'orbax-checkpoint',
   'psutil',
   'pre-commit',
   'pydata-sphinx-theme',
@@ -178,6 +184,10 @@ dev = [
   'trimesh',
   'scikit-rf',
   'vtk',
+  'pyvista',
+  'trame',
+  'trame-vtk',
+  'trame-vuetify',
   'cma',
   'diff-cover',
   'openpyxl',
@@ -185,6 +195,7 @@ dev = [
   'libcst',
 ]
 tests = [
+  'orbax-checkpoint',
   'psutil',
   'pre-commit',
   'pylint',
@@ -197,6 +208,7 @@ tests = [
   'trimesh'
 ]
 docs = [
+  'orbax-checkpoint',
   "jupyter",
   "jinja2",
   "nbconvert",
@@ -229,6 +241,7 @@ gdstk = ["gdstk"]
 scikit-rf = ["scikit-rf"]
 trimesh = ["trimesh", "networkx", "rtree"]
 vtk = ["vtk"]
+pyvista = ["pyvista", "vtk", "trame", "trame-vtk", "trame-vuetify"]
 ruff = ["ruff"]
 heatcharge = ["trimesh", "vtk"]
 # plugins with extra deps
@@ -369,6 +382,7 @@ env = ["MPLBACKEND=Agg", "OMP_NUM_THREADS=1", "TIDY3D_MICROWAVE__SUPPRESS_RF_LIC
 doctest_optionflags = "NORMALIZE_WHITESPACE ELLIPSIS"
 norecursedirs = [
   "tests/_test_local",
+  "tests/_integration",
   "tests/test_cli",
   "tests/_test_data",
   "tests/_test_notebooks",

{tidy3d-2.11.0.dev0 → tidy3d-2.11.0.dev1}/tidy3d/__init__.py

@@ -138,7 +138,6 @@ from tidy3d.components.tcad.types import (
 
 from .components.apodization import ApodizationSpec
 
-# boundary placement for other solvers
 # boundary placement for other solvers
 from .components.bc_placement import (
     MediumMediumInterface,
@@ -201,7 +200,14 @@ from .components.data.data_array import (
     GroupIndexDataArray,
     HeatDataArray,
     IndexedDataArray,
+    IndexedFieldDataArray,
+    IndexedFieldTimeDataArray,
     IndexedFieldVoltageDataArray,
+    IndexedFreqDataArray,
+    IndexedSurfaceFieldDataArray,
+    IndexedSurfaceFieldTimeDataArray,
+    IndexedSurfaceFreqDataArray,
+    IndexedSurfaceTimeDataArray,
     IndexedTimeDataArray,
     IndexedVoltageDataArray,
     ModeAmpsDataArray,
@@ -239,8 +245,11 @@ from .components.data.monitor_data import (
     ModeData,
     ModeSolverData,
     PermittivityData,
+    SurfaceFieldData,
+    SurfaceFieldTimeData,
 )
 from .components.data.sim_data import DATA_TYPE_MAP, SimulationData
+from .components.data.unstructured.surface import TriangularSurfaceDataset
 from .components.data.utils import (
     TetrahedralGridDataset,
     TriangularGridDataset,
@@ -391,6 +400,8 @@ from .components.monitor import (
     ModeSolverMonitor,
     Monitor,
     PermittivityMonitor,
+    SurfaceFieldMonitor,
+    SurfaceFieldTimeMonitor,
 )
 
 # nonlinear
@@ -722,7 +733,14 @@ __all__ = [
     "ImpedanceCalculator",
     "IndexPerturbation",
     "IndexedDataArray",
+    "IndexedFieldDataArray",
+    "IndexedFieldTimeDataArray",
     "IndexedFieldVoltageDataArray",
+    "IndexedFreqDataArray",
+    "IndexedSurfaceFieldDataArray",
+    "IndexedSurfaceFieldTimeDataArray",
+    "IndexedSurfaceFreqDataArray",
+    "IndexedSurfaceTimeDataArray",
     "IndexedTimeDataArray",
     "IndexedVoltageDataArray",
     "InsulatingBC",
@@ -851,6 +869,10 @@ __all__ = [
     "StructureSimulationBoundary",
     "StructureStructureInterface",
     "SubpixelSpec",
+    "SurfaceFieldData",
+    "SurfaceFieldMonitor",
+    "SurfaceFieldTimeData",
+    "SurfaceFieldTimeMonitor",
     "SurfaceImpedance",
     "SurfaceImpedanceFitterParam",
     "TemperatureBC",
@@ -861,6 +883,7 @@ __all__ = [
     "Transformed",
     "TriangleMesh",
     "TriangularGridDataset",
+    "TriangularSurfaceDataset",
     "TwoPhotonAbsorption",
     "UniformCurrentSource",
     "UniformGrid",

{tidy3d-2.11.0.dev0 → tidy3d-2.11.0.dev1}/tidy3d/components/autograd/derivative_utils.py

@@ -10,8 +10,9 @@ from typing import TYPE_CHECKING, Any, Optional
 import numpy as np
 from numpy.typing import NDArray
 
-from tidy3d.components.data.data_array import ScalarFieldDataArray
+from tidy3d.components.data.data_array import ScalarFieldDataArray, SpatialDataArray
 from tidy3d.components.data.utils import _zeros_like
+from tidy3d.components.grid.grid import _compute_1d_cell_sizes
 from tidy3d.components.types import ArrayLike, Bound
 from tidy3d.config import config
 from tidy3d.constants import C_0, EPSILON_0, LARGE_NUMBER, MU_0
@@ -34,6 +35,7 @@ PermittivityData = dict[str, ScalarFieldDataArray]
 EpsType = ScalarFieldDataArray
 ArrayFloat = NDArray[np.floating]
 ArrayComplex = NDArray[np.complexfloating]
+TRANSPOSE_INTERP_COORDINATE_TOLERANCE = 1e-12
 
 
 class LazyInterpolator:
@@ -101,19 +103,6 @@ class DerivativeInfo:
     Dataset of relative permittivity values along all three dimensions.
     Used for automatically computing permittivity inside or outside of a simple geometry."""
 
-    eps_in: EpsType | None
-    """Permittivity inside the Structure.
-    Computed only when structure.medium.is_custom is False. Contains the simulation
-    permittivity inside the structure when the simulation background medium is set to
-    the structure medium and all structures after the current structure are kept. Should
-    be used as the inside permittivity for shape derivative computations."""
-
-    eps_out: EpsType
-    """Permittivity outside the Structure.
-    Contains the simulation permittivity outside the structure when the current structure
-    is removed from the structure list. Should be used as the outside permittivity for
-    shape derivative computations."""
-
     bounds: Bound
     """Geometry bounds.
     Bounds corresponding to the structure, used in Medium calculations."""
@@ -137,6 +126,19 @@ class DerivativeInfo:
 
     # Optional fields with defaults
 
+    eps_in: Optional[EpsType] = None
+    """Permittivity inside the Structure.
+    Computed only when structure.medium.is_custom is False. Contains the simulation
+    permittivity inside the structure when the simulation background medium is set to
+    the structure medium and all structures after the current structure are kept. Should
+    be used as the inside permittivity for shape derivative computations."""
+
+    eps_out: Optional[EpsType] = None
+    """Permittivity outside the Structure.
+    Contains the simulation permittivity outside the structure when the current structure
+    is removed from the structure list. Should be used as the outside permittivity for
+    shape derivative computations."""
+
     H_der_map: Optional[FieldDataDict] = None
     """Magnetic field gradient map.
     Dataset where the field components ("Hx", "Hy", "Hz") store the multiplication
@@ -196,34 +198,6 @@ class DerivativeInfo:
             return coords
         return np.nan_to_num(coords, posinf=LARGE_NUMBER, neginf=-LARGE_NUMBER)
 
-    @staticmethod
-    def _evaluate_with_interpolators(
-        interpolators: dict[str, Callable[[ArrayFloat], ArrayComplex]],
-        coords: ArrayFloat,
-    ) -> dict[str, ArrayComplex]:
-        """Evaluate field components at coordinates using cached interpolators.
-
-        Parameters
-        ----------
-        interpolators : dict
-            Dictionary mapping field component names to ``RegularGridInterpolator`` objects.
-        coords : np.ndarray
-            Spatial coordinates (N, 3) where fields are evaluated.
-
-        Returns
-        -------
-        dict[str, np.ndarray]
-            Dictionary mapping component names to field values at coordinates.
-        """
-        auto_cfg = config.adjoint
-        float_dtype = auto_cfg.gradient_dtype_float
-        complex_dtype = auto_cfg.gradient_dtype_complex
-
-        coords = DerivativeInfo._nan_to_num_if_needed(coords)
-        if coords.dtype != float_dtype and coords.dtype != complex_dtype:
-            coords = coords.astype(float_dtype, copy=False)
-        return {name: interp(coords) for name, interp in interpolators.items()}
-
     def create_interpolators(self, dtype: Optional[np.dtype[Any]] = None) -> dict[str, Any]:
         """Create interpolators for field components and permittivity data.
 
@@ -411,6 +385,14 @@ class DerivativeInfo:
                 "Please create interpolators using 'create_interpolators()' first."
             )
 
+        if self.eps_in is None or self.eps_out is None:
+            raise ValueError(
+                "Missing permittivity data for geometry gradients: both "
+                "'eps_in' and 'eps_out' must be provided."
+            )
+        eps_in = self.eps_in
+        eps_out = self.eps_out
+
         # In all paths below, we need to have computed the gradient integration for a
         # dielectric-dielectric interface.
         vjps_dielectric = self._evaluate_dielectric_gradient_at_points(
@@ -419,8 +401,8 @@ class DerivativeInfo:
             perps1,
             perps2,
             interpolators,
-            self.eps_in,
-            self.eps_out,
+            eps_in,
+            eps_out,
         )
 
         if self.is_medium_pec:
@@ -433,7 +415,7 @@ class DerivativeInfo:
             mask_pec = self._detect_pec_gradient_points(
                 spatial_coords,
                 normals,
-                self.eps_in,
+                eps_in,
                 interpolators["eps_data"],
                 is_outside=False,
             )
@@ -445,7 +427,7 @@ class DerivativeInfo:
                 perps1,
                 perps2,
                 interpolators,
-                ("eps_out", self.eps_out),
+                ("eps_out", eps_out),
                 is_outside=True,
             )
 
@@ -460,7 +442,7 @@ class DerivativeInfo:
             mask_pec = self._detect_pec_gradient_points(
                 spatial_coords,
                 normals,
-                self.eps_out,
+                eps_out,
                 interpolators["eps_data"],
                 is_outside=True,
             )
@@ -473,7 +455,7 @@ class DerivativeInfo:
                 perps1,
                 perps2,
                 interpolators,
-                ("eps_in", self.eps_in),
+                ("eps_in", eps_in),
                 is_outside=False,
             )
 
@@ -1103,7 +1085,285 @@ def integrate_within_bounds(arr: xr.DataArray, dims: list[str], bounds: Bound) -
     return _arr.integrate(coord=dims_integrate)
 
 
+def compute_spatial_weights(
+    arr: SpatialDataArray, dims: tuple[str, ...] = ("x", "y", "z")
+) -> SpatialDataArray:
+    """Compute cell-size weights for spatial coordinates.
+
+    Parameters
+    ----------
+    arr : SpatialDataArray
+        Data array providing spatial coordinates.
+    dims : tuple[str, ...]
+        Spatial dimension names to include in the weights.
+
+    Returns
+    -------
+    SpatialDataArray
+        DataArray of weights broadcastable to ``arr``.
+    """
+
+    weight_dims = []
+    weight_arrays = []
+    for dim in dims:
+        if dim not in arr.coords:
+            continue
+        coord = np.asarray(arr.coords[dim].data)
+        if coord.size <= 1:
+            continue
+        weight_dims.append(dim)
+        weight_arrays.append(_compute_1d_cell_sizes(coord))
+
+    if not weight_dims:
+        return SpatialDataArray(1.0)
+
+    weights = np.ix_(*weight_arrays)
+    weights_data = weights[0]
+    for weight_array in weights[1:]:
+        weights_data = weights_data * weight_array
+
+    coords = {dim: np.asarray(arr.coords[dim].data) for dim in weight_dims}
+    return SpatialDataArray(weights_data, coords=coords, dims=tuple(weight_dims))
+
+
+def transpose_interp_axis(
+    field_values: np.ndarray,
+    field_coords_1d: np.ndarray,
+    param_coords_1d: np.ndarray,
+    *,
+    method: str = "linear",
+    coordinate_tolerance: float = TRANSPOSE_INTERP_COORDINATE_TOLERANCE,
+) -> np.ndarray:
+    """Transpose (adjoint) of 1D interpolation along one axis."""
+    if param_coords_1d.size == 1:
+        return field_values.sum(axis=0, keepdims=True)
+    if np.any(param_coords_1d[1:] < param_coords_1d[:-1]):
+        raise ValueError("Spatial coordinates must be sorted before computing derivatives.")
+    if method not in ("linear", "nearest"):
+        raise ValueError(f"Unsupported interpolation method: {method!r}.")
+
+    param_coords_1d = np.asarray(param_coords_1d, dtype=float)
+    n_param = param_coords_1d.size
+    n_field = field_values.shape[0]
+    field_values_2d = field_values.reshape(n_field, -1)
+
+    field_coords = np.asarray(field_coords_1d, dtype=float)
+    if coordinate_tolerance > 0.0:
+        field_coords = np.clip(
+            field_coords,
+            param_coords_1d[0] - coordinate_tolerance,
+            param_coords_1d[-1] + coordinate_tolerance,
+        )
+
+    if method == "nearest":
+        param_midpoints = (param_coords_1d[1:] + param_coords_1d[:-1]) / 2.0
+        param_index_nearest = np.searchsorted(param_midpoints, field_coords)
+        param_values_2d = np.zeros((n_param, field_values_2d.shape[1]), dtype=field_values.dtype)
+        np.add.at(param_values_2d, param_index_nearest, field_values_2d)
+        return param_values_2d.reshape((n_param,) + field_values.shape[1:])
+
+    param_index_upper = np.searchsorted(param_coords_1d, field_coords, side="right")
+    param_index_upper = np.clip(param_index_upper, 1, n_param - 1)
+    param_index_lower = param_index_upper - 1
+
+    segment_width = param_coords_1d[param_index_upper] - param_coords_1d[param_index_lower]
+    segment_width = np.where(segment_width == 0, 1.0, segment_width)
+    frac_upper = (field_coords - param_coords_1d[param_index_lower]) / segment_width
+    frac_upper = np.clip(frac_upper, 0.0, 1.0)
+
+    w_lower = (1.0 - frac_upper)[:, None]
+    w_upper = frac_upper[:, None]
+
+    param_values_2d = np.zeros((n_param, field_values_2d.shape[1]), dtype=field_values.dtype)
+    np.add.at(param_values_2d, param_index_lower, field_values_2d * w_lower)
+    np.add.at(param_values_2d, param_index_upper, field_values_2d * w_upper)
+
+    return param_values_2d.reshape((n_param,) + field_values.shape[1:])
+
+
+def bounds_slice(
+    axis: NDArray,
+    vmin: float,
+    vmax: float,
+    *,
+    name: str,
+    warning_context: str,
+) -> slice:
+    """Compute a robust crop slice on a 1D axis."""
+    axis = np.asarray(axis, dtype=float)
+    n = axis.size
+
+    vmin_tol = vmin - TRANSPOSE_INTERP_COORDINATE_TOLERANCE
+    vmax_tol = vmax + TRANSPOSE_INTERP_COORDINATE_TOLERANCE
+
+    i0 = int(np.searchsorted(axis, vmin_tol, side="left"))
+    i1 = int(np.searchsorted(axis, vmax_tol, side="right"))
+    if i1 <= i0 and n:
+        old = (i0, i1)
+        if i1 < n:
+            i1 = i0 + 1
+        elif i0 > 0:
+            i0 = i1 - 1
+        log.warning(
+            f"Empty bounds crop on '{name}' while computing {warning_context}: "
+            f"bounds=[{vmin_tol!r}, {vmax_tol!r}], "
+            f"grid=[{axis[0]!r}, {axis[-1]!r}] -> indices {old}; using ({i0}, {i1}).",
+            log_once=True,
+        )
+    return slice(i0, i1)
+
+
+def transpose_interp_field_to_dataset(
+    adjoint_field: SpatialDataArray,
+    dataset_field: SpatialDataArray,
+    *,
+    center: tuple[float, float, float],
+    method: str | dict[str, str] = "linear",
+) -> SpatialDataArray:
+    """Accumulate adjoint fields onto dataset coordinates using adjoint interpolation."""
+
+    allowed_methods = ("linear", "nearest")
+    if isinstance(method, str):
+        method_by_dim = dict.fromkeys("xyz", method)
+    elif isinstance(method, dict):
+        invalid_dims = set(method) - set("xyz")
+        if invalid_dims:
+            raise ValueError(
+                f"Unsupported interpolation axis keys: {sorted(invalid_dims)!r}. "
+                "Expected subset of ('x', 'y', 'z')."
+            )
+        method_by_dim = {dim: method.get(dim, "linear") for dim in "xyz"}
+    else:
+        raise TypeError("Interpolation method must be a string or a dict keyed by 'x', 'y', 'z'.")
+    for dim, interp_method in method_by_dim.items():
+        if interp_method not in allowed_methods:
+            raise ValueError(
+                f"Unsupported interpolation method {interp_method!r} for axis '{dim}'."
+            )
+
+    def _align_freq(field: SpatialDataArray, target: SpatialDataArray) -> SpatialDataArray:
+        target_freqs = np.asarray(target.coords["f"].data)
+        if target_freqs.size == 1:
+            # Source datasets are single-frequency by construction. When adjoint
+            # fields carry multiple frequencies, gradients must accumulate all
+            # frequency contributions onto that single source-frequency slot.
+            # Any source-spectrum weighting has already been applied upstream
+            # to the adjoint fields in ``_process_source_gradients``.
+            summed = field.sum(dim="f")
+            summed = summed.expand_dims({"f": target_freqs}, axis=-1)
+            return summed.transpose(*field.dims)
+        source_freqs = np.asarray(field.coords["f"].data)
+        if target_freqs.size == source_freqs.size and np.allclose(
+            target_freqs, source_freqs, rtol=1e-12, atol=0.0
+        ):
+            return field
+        freq_interp_method = "nearest" if source_freqs.size <= 1 else "linear"
+        return field.interp(
+            {"f": target_freqs},
+            method=freq_interp_method,
+            kwargs={"bounds_error": False, "fill_value": 0.0},
+        ).fillna(0.0)
+
+    def _interp_axis(
+        arr: np.ndarray,
+        axis: int,
+        field_axis: np.ndarray,
+        param_axis: np.ndarray,
+        interp_method: str,
+    ) -> np.ndarray:
+        moved = np.moveaxis(arr, axis, 0)
+        moved = transpose_interp_axis(
+            moved,
+            field_axis,
+            param_axis,
+            method=interp_method,
+        )
+        return np.moveaxis(moved, 0, axis)
+
+    dataset_field_sorted = dataset_field._spatially_sorted
+    center = tuple(get_static(val) for val in center)
+    aligned = _align_freq(adjoint_field, dataset_field_sorted)
+    weights = compute_spatial_weights(aligned, dims=tuple("xyz"))
+    if weights.size > 1:
+        weights = weights.transpose(*weights.dims)
+    weighted = aligned * weights
+
+    field_coords = {
+        dim: np.asarray(weighted.coords[dim].data) for dim in weighted.dims if dim in "xyz"
+    }
+    param_coords = {}
+    for axis, dim in enumerate("xyz"):
+        if dim in dataset_field_sorted.coords:
+            param_coords[dim] = np.asarray(dataset_field_sorted.coords[dim].data) + center[axis]
+
+    crop_slices = {}
+    for dim in "xyz":
+        if dim not in field_coords or dim not in param_coords:
+            continue
+        param_axis = param_coords[dim]
+        vmin = float(np.min(param_axis))
+        vmax = float(np.max(param_axis))
+        crop_slices[dim] = bounds_slice(
+            field_coords[dim],
+            vmin,
+            vmax,
+            name=dim,
+            warning_context="source gradients (adjoint field grid -> source dataset)",
+        )
+
+    if crop_slices:
+        weighted = weighted.isel(**crop_slices)
+        field_coords = {
+            dim: np.asarray(weighted.coords[dim].data) for dim in weighted.dims if dim in "xyz"
+        }
+
+    values = np.asarray(weighted.data)
+    dims = list(weighted.dims)
+    for dim in "xyz":
+        if dim not in field_coords or dim not in param_coords:
+            continue
+        axis_index = dims.index(dim)
+        values = _interp_axis(
+            values,
+            axis_index,
+            field_coords[dim],
+            param_coords[dim],
+            method_by_dim[dim],
+        )
+
+    out_coords = {
+        dim: np.asarray(dataset_field_sorted.coords[dim].data) for dim in dataset_field_sorted.dims
+    }
+    result = SpatialDataArray(values, coords=out_coords, dims=tuple(dims))
+    if tuple(dims) != tuple(dataset_field_sorted.dims):
+        result = result.transpose(*dataset_field_sorted.dims)
+
+    needs_restore_order = any(
+        dim in dataset_field.coords
+        and not np.array_equal(
+            np.asarray(dataset_field.coords[dim].data),
+            np.asarray(dataset_field_sorted.coords[dim].data),
+        )
+        for dim in "xyz"
+    )
+    if needs_restore_order:
+        selection = {}
+        for dim in "xyz":
+            if dim in dataset_field.coords:
+                selection[dim] = np.asarray(dataset_field.coords[dim].data)
+        if selection:
+            result = result.sel(selection)
+
+    if tuple(result.dims) != tuple(dataset_field.dims):
+        result = result.transpose(*dataset_field.dims)
+    return result
+
+
 __all__ = [
     "DerivativeInfo",
+    "bounds_slice",
+    "compute_spatial_weights",
     "integrate_within_bounds",
+    "transpose_interp_axis",
+    "transpose_interp_field_to_dataset",
 ]