wavesimpro 1.10.1__tar.gz → 1.10.2__tar.gz

{wavesimpro-1.10.1 → wavesimpro-1.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavesimpro
-Version: 1.10.1
+Version: 1.10.2
 Summary: WavesimPro Python API — cloud execution client for the Rayfos simulation platform
 Author: Rayfos
 Project-URL: Repository, https://github.com/rayfos/wavesimpro
@@ -67,7 +67,8 @@ field = wp.read_binary_field(run.download("output.bin"))
   `create_stl_primitive`, `create_gds_primitive` (with `create_gds_layer_config` /
   `create_gds_structure_override`), `create_voxels_model_primitive`.
 - Per-primitive sub-pixel flag (`subpixel=True/False` on every shape, STL and GDSII helper)
-  to choose which shapes get smoothed interfaces.
+  to choose which shapes get smoothed interfaces. Off by default: a setup with no averaged
+  shape is voxelised exactly as before 1.10 and runs on every compute node.
 - Per-axis pixel sizes (`pixel_size=[dx, dy, dz]`) and sub-pixel permittivity averaging
   (`subpixel_factor=`), when the compute node supports them.
 - Preflight memory check and cost estimate before a run.

{wavesimpro-1.10.1 → wavesimpro-1.10.2}/README.md

@@ -44,7 +44,8 @@ field = wp.read_binary_field(run.download("output.bin"))
   `create_stl_primitive`, `create_gds_primitive` (with `create_gds_layer_config` /
   `create_gds_structure_override`), `create_voxels_model_primitive`.
 - Per-primitive sub-pixel flag (`subpixel=True/False` on every shape, STL and GDSII helper)
-  to choose which shapes get smoothed interfaces.
+  to choose which shapes get smoothed interfaces. Off by default: a setup with no averaged
+  shape is voxelised exactly as before 1.10 and runs on every compute node.
 - Per-axis pixel sizes (`pixel_size=[dx, dy, dz]`) and sub-pixel permittivity averaging
   (`subpixel_factor=`), when the compute node supports them.
 - Preflight memory check and cost estimate before a run.

{wavesimpro-1.10.1 → wavesimpro-1.10.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wavesimpro"
-version = "1.10.1"
+version = "1.10.2"
 description = "WavesimPro Python API — cloud execution client for the Rayfos simulation platform"
 readme = "README.md"
 requires-python = ">=3.8"

{wavesimpro-1.10.1 → wavesimpro-1.10.2}/src/wavesimpro/__init__.py

@@ -54,7 +54,7 @@ from .json_helper import (
     parse_progress_data,
 )
 
-__version__ = "1.10.1"
+__version__ = "1.10.2"
 __all__ = [
     # Client
     "RayfosClient",

wavesimpro-1.10.2/src/wavesimpro/model.py

@@ -0,0 +1,588 @@
+"""
+Object model for a Wavesim setup: media, primitives, sources and monitors.
+
+Everything here is a thin, typed layer over the ``create_*`` JSON helpers in
+``json_helper``. The objects carry the user's intent (a sphere of index 1.2,
+sub-pixel averaged); ``Setup`` / ``submit`` turn them into WavesimProperties,
+upload what needs uploading (STL/GDS files, voxel arrays, source fields) and fill
+in the file ids and medium ids. The user never writes a medium id.
+
+Coordinates
+-----------
+Primitive positions, service-computed source positions and monitor positions are
+WORLD coordinates in micrometres, with the origin at the CENTRE of the simulation
+domain (the server's CoordinateSystemCenter). The domain spans
+[-size/2, +size/2] on every axis, where size = grid × pixel_size.
+
+Array arguments (a permittivity array, or a user field for ``FieldSource``) are
+VOXEL-INDEX based, like the FOSS ``wavesim.simulate``: index (0, 0, 0) is the
+domain corner at (-size_x/2, -size_y/2, -size_z/2) µm, and a field source's
+position is the voxel index of its corner.
+
+Overlapping primitives
+----------------------
+The service resolves overlaps with the painter's rule: the LATER primitive in
+the list wins wherever two primitives cover the same probe. Nothing is blended.
+``Setup`` warns loudly when two shapes of different material may overlap (their
+bounding boxes intersect); overlaps between shapes of the same material are
+harmless and not reported.
+
+Staircase rule (``subpixel=False``)
+-----------------------------------
+A voxel belongs to the shape when its centre is inside. A centre exactly on the
+surface may go either way (floating point); keep the radius / size off exact
+multiples of the pixel size when that matters.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
+
+import numpy as np
+
+from . import json_helper as jh
+
+Number = Union[int, float, complex]
+Vec3 = Tuple[float, float, float]
+
+
+# ---------------------------------------------------------------------------
+# Media
+# ---------------------------------------------------------------------------
+
+def _slug(text: str) -> str:
+    s = re.sub(r"[^a-z0-9]+", "-", text.strip().lower()).strip("-")
+    return s or "medium"
+
+
+def _n_id(n: complex) -> str:
+    """Stable medium id derived from the refractive index, e.g. ``n1.2`` / ``n3.48k0.01``."""
+    re_s = f"{n.real:.6g}"
+    im_s = f"k{n.imag:.6g}" if n.imag else ""
+    return _slug(f"n{re_s}{im_s}")
+
+
+@dataclass(frozen=True)
+class Medium:
+    """A material: complex refractive index ``n + i k``.
+
+    ``Medium("silicon", 3.48)`` or ``Medium(n=1.2)``. Two media with the same
+    (n, k) are merged into one entry when the setup is submitted; the first
+    name seen is kept. ``k`` (the imaginary part of ``n``) is absorption; the
+    server stores it as ``primaryImaginary`` and uses eps = (n + ik)^2.
+    """
+
+    name: Optional[str] = None
+    n: Number = 1.0
+    color: Optional[str] = None
+
+    def __post_init__(self):
+        n = complex(self.n)
+        if not math.isfinite(n.real) or not math.isfinite(n.imag):
+            raise ValueError(f"Medium {self.name or ''}: refractive index must be finite, got {self.n!r}")
+        if n.real <= 0:
+            raise ValueError(f"Medium {self.name or ''}: refractive index real part must be > 0, got {n.real}")
+        object.__setattr__(self, "n", n)
+
+    @property
+    def key(self) -> Tuple[float, float]:
+        n = complex(self.n)
+        return (round(n.real, 9), round(n.imag, 9))
+
+    @property
+    def id(self) -> str:
+        return _slug(self.name) if self.name else _n_id(complex(self.n))
+
+    @property
+    def display_name(self) -> str:
+        if self.name:
+            return self.name
+        n = complex(self.n)
+        return f"n={n.real:g}" + (f"+{n.imag:g}i" if n.imag else "")
+
+    def to_dict(self, medium_id: Optional[str] = None) -> Dict[str, Any]:
+        n = complex(self.n)
+        return jh.create_medium(medium_id or self.id, self.display_name, n.real, n.imag, color=self.color)
+
+
+def as_medium(value: Union[Medium, Number], label: str = "n") -> Medium:
+    if isinstance(value, Medium):
+        return value
+    if isinstance(value, (int, float, complex, np.integer, np.floating, np.complexfloating)):
+        return Medium(n=complex(value))
+    raise TypeError(f"{label} must be a number (refractive index) or a Medium, got {type(value).__name__}")
+
+
+# ---------------------------------------------------------------------------
+# Primitives
+# ---------------------------------------------------------------------------
+
+_prim_counter = {"n": 0}
+
+
+def _auto_name(prefix: str) -> str:
+    _prim_counter["n"] += 1
+    return f"{prefix}_{_prim_counter['n']}"
+
+
+def _vec3(v, label: str) -> Vec3:
+    try:
+        x, y, z = (float(c) for c in v)
+    except (TypeError, ValueError):
+        raise TypeError(f"{label} must be three numbers (x, y, z), got {v!r}") from None
+    return (x, y, z)
+
+
+@dataclass
+class Primitive:
+    """Base of every geometry object a ``Setup`` can hold.
+
+    ``n`` is the material (a refractive index or a ``Medium``); ``subpixel``
+    chooses sub-pixel averaging of the interface voxels for THIS shape (True),
+    a centre-sampled staircase (False) or the setup's ``subpixel`` default (None).
+    When that is None too, the primitive is sent without a flag: with no averaged
+    primitive in the setup the server runs the classic voxeliser (the volume of
+    versions before 1.10) on any compute node; once some primitive is averaged,
+    unflagged ones are sent as False (centre-sampled).
+    """
+
+    n: Union[Medium, Number] = 1.0
+    name: Optional[str] = None
+    subpixel: Optional[bool] = None
+
+    kind: str = field(default="Primitive", init=False, repr=False)
+
+    def __post_init__(self):
+        self.n = as_medium(self.n, "n")
+        if self.name is None:
+            self.name = _auto_name(self.kind.lower())
+
+    @property
+    def medium(self) -> Medium:
+        return self.n  # type: ignore[return-value]
+
+    # Conservative axis-aligned bounding box in world µm, or None when unknown.
+    def bounding_box(self) -> Optional[Tuple[Vec3, Vec3]]:
+        return None
+
+    # Files to upload before the primitive can be serialised: list of (attribute, path).
+    def files(self) -> List[Tuple[str, Path]]:
+        return []
+
+    def to_dict(self, medium_id: str, file_ids: Dict[str, str], subpixel: Optional[bool]) -> Dict[str, Any]:
+        raise NotImplementedError
+
+
+def _rotated(center: Vec3, half: Vec3, rotation: Vec3) -> Tuple[Vec3, Vec3]:
+    """AABB of a box of half-extents ``half`` at ``center``; when rotated, the box
+    is replaced by its circumscribed sphere (conservative)."""
+    if any(abs(r) > 1e-12 for r in rotation):
+        r = math.sqrt(sum(h * h for h in half))
+        half = (r, r, r)
+    return (tuple(c - h for c, h in zip(center, half)),  # type: ignore[return-value]
+            tuple(c + h for c, h in zip(center, half)))
+
+
+@dataclass
+class Sphere(Primitive):
+    center: Vec3 = (0.0, 0.0, 0.0)
+    radius: float = 1.0
+    kind: str = field(default="Sphere", init=False, repr=False)
+
+    def __post_init__(self):
+        super().__post_init__()
+        self.center = _vec3(self.center, "center")
+        if self.radius <= 0:
+            raise ValueError(f"Sphere {self.name}: radius must be > 0")
+
+    def bounding_box(self):
+        r = float(self.radius)
+        return _rotated(self.center, (r, r, r), (0.0, 0.0, 0.0))
+
+    def to_dict(self, medium_id, file_ids, subpixel):
+        return jh.create_sphere_primitive(self.name, medium_id, *self.center, float(self.radius), subpixel=subpixel)
+
+
+@dataclass
+class Box(Primitive):
+    center: Vec3 = (0.0, 0.0, 0.0)
+    size: Vec3 = (1.0, 1.0, 1.0)
+    rotation: Vec3 = (0.0, 0.0, 0.0)
+    kind: str = field(default="Box", init=False, repr=False)
+
+    def __post_init__(self):
+        super().__post_init__()
+        self.center = _vec3(self.center, "center")
+        self.size = _vec3(self.size, "size")
+        self.rotation = _vec3(self.rotation, "rotation")
+        if any(s <= 0 for s in self.size):
+            raise ValueError(f"Box {self.name}: every size component must be > 0")
+
+    def bounding_box(self):
+        return _rotated(self.center, tuple(s / 2 for s in self.size), self.rotation)  # type: ignore[arg-type]
+
+    def to_dict(self, medium_id, file_ids, subpixel):
+        return jh.create_box_primitive(self.name, medium_id, *self.center, *self.size, subpixel=subpixel,
+                                       rotation_x=self.rotation[0], rotation_y=self.rotation[1],
+                                       rotation_z=self.rotation[2])
+
+
+@dataclass
+class Ellipsoid(Primitive):
+    center: Vec3 = (0.0, 0.0, 0.0)
+    radii: Vec3 = (1.0, 1.0, 1.0)
+    rotation: Vec3 = (0.0, 0.0, 0.0)
+    kind: str = field(default="Ellipsoid", init=False, repr=False)
+
+    def __post_init__(self):
+        super().__post_init__()
+        self.center = _vec3(self.center, "center")
+        self.radii = _vec3(self.radii, "radii")
+        self.rotation = _vec3(self.rotation, "rotation")
+        if any(r <= 0 for r in self.radii):
+            raise ValueError(f"Ellipsoid {self.name}: every radius must be > 0")
+
+    def bounding_box(self):
+        return _rotated(self.center, self.radii, self.rotation)
+
+    def to_dict(self, medium_id, file_ids, subpixel):
+        return jh.create_ellipsoid_primitive(self.name, medium_id, *self.center, *self.radii,
+                                             rotation_x=self.rotation[0], rotation_y=self.rotation[1],
+                                             rotation_z=self.rotation[2], subpixel=subpixel)
+
+
+def _axial_bbox(position: Vec3, radius: float, height: float, axis: str, anchor: str, rotation: Vec3):
+    """AABB of a cylinder-like solid of ``radius`` and ``height`` along ``axis``."""
+    i = "XYZ".index(axis.upper())
+    half = [radius, radius, radius]
+    half[i] = height / 2
+    center = list(position)
+    if anchor == "BottomCenter":
+        center[i] += height / 2
+    elif anchor == "TopCenter":
+        center[i] -= height / 2
+    return _rotated(tuple(center), tuple(half), rotation)  # type: ignore[arg-type]
+
+
+@dataclass
+class Cylinder(Primitive):
+    """Circular cylinder of ``radius`` extruded ``height`` along ``axis``.
+
+    ``position`` is the centre of the bottom face by default (``anchor="BottomCenter"``,
+    the server's default for axial shapes); ``anchor="Center"`` makes it the centroid.
+    """
+
+    position: Vec3 = (0.0, 0.0, 0.0)
+    radius: float = 1.0
+    height: float = 1.0
+    axis: str = "Z"
+    anchor: str = "BottomCenter"
+    rotation: Vec3 = (0.0, 0.0, 0.0)
+    kind: str = field(default="Cylinder", init=False, repr=False)
+
+    def __post_init__(self):
+        super().__post_init__()
+        self.position = _vec3(self.position, "position")
+        self.rotation = _vec3(self.rotation, "rotation")
+        if self.radius <= 0 or self.height <= 0:
+            raise ValueError(f"{self.kind} {self.name}: radius and height must be > 0")
+
+    def bounding_box(self):
+        return _axial_bbox(self.position, float(self.radius), float(self.height), self.axis, self.anchor, self.rotation)
+
+    def to_dict(self, medium_id, file_ids, subpixel):
+        return jh.create_cylinder_primitive(self.name, medium_id, *self.position, float(self.radius),
+                                            float(self.height), axis=self.axis, rotation_x=self.rotation[0],
+                                            rotation_y=self.rotation[1], rotation_z=self.rotation[2],
+                                            position_anchor=self.anchor, subpixel=subpixel)
+
+
+@dataclass
+class Cone(Cylinder):
+    """Cone: base disc of ``radius`` at ``position`` (BottomCenter), apex ``height`` along +``axis``."""
+
+    kind: str = field(default="Cone", init=False, repr=False)
+
+    def to_dict(self, medium_id, file_ids, subpixel):
+        return jh.create_cone_primitive(self.name, medium_id, *self.position, float(self.radius),
+                                        float(self.height), axis=self.axis, rotation_x=self.rotation[0],
+                                        rotation_y=self.rotation[1], rotation_z=self.rotation[2],
+                                        position_anchor=self.anchor, subpixel=subpixel)
+
+
+@dataclass
+class Prism(Cylinder):
+    """Regular N-sided prism: polygon of circumradius ``radius`` extruded ``height`` along ``axis``."""
+
+    sides: int = 6
+    top_scale: float = 1.0
+    twist_degrees: float = 0.0
+    kind: str = field(default="Prism", init=False, repr=False)
+
+    def to_dict(self, medium_id, file_ids, subpixel):
+        return jh.create_prism_primitive(self.name, medium_id, *self.position, float(self.radius),
+                                         float(self.height), number_of_sides=int(self.sides), axis=self.axis,
+                                         top_scale=float(self.top_scale), twist_degrees=float(self.twist_degrees),
+                                         rotation_x=self.rotation[0], rotation_y=self.rotation[1],
+                                         rotation_z=self.rotation[2], position_anchor=self.anchor,
+                                         subpixel=subpixel)
+
+
+@dataclass
+class Stl(Primitive):
+    """A triangle mesh from a local ``.stl`` file; uploaded by ``submit``.
+
+    ``center`` positions the mesh (world µm, domain centre = origin); ``scale``
+    and ``rotation`` (degrees) are applied by the server.
+    """
+
+    path: Union[str, Path] = ""
+    center: Vec3 = (0.0, 0.0, 0.0)
+    rotation: Vec3 = (0.0, 0.0, 0.0)
+    scale: Vec3 = (1.0, 1.0, 1.0)
+    kind: str = field(default="Stl", init=False, repr=False)
+
+    def __post_init__(self):
+        super().__post_init__()
+        self.path = Path(self.path)
+        if not self.path.is_file():
+            raise FileNotFoundError(f"Stl {self.name}: file not found: {self.path}")
+        self.center = _vec3(self.center, "center")
+        self.rotation = _vec3(self.rotation, "rotation")
+        self.scale = _vec3(self.scale, "scale")
+
+    def files(self):
+        return [("file", self.path)]
+
+    def to_dict(self, medium_id, file_ids, subpixel):
+        return jh.create_stl_primitive(self.name, file_ids["file"], medium_id, *self.center,
+                                       rotation_x=self.rotation[0], rotation_y=self.rotation[1],
+                                       rotation_z=self.rotation[2], scale_x=self.scale[0],
+                                       scale_y=self.scale[1], scale_z=self.scale[2], subpixel=subpixel)
+
+
+@dataclass
+class Gds(Primitive):
+    """A GDSII layout from a local ``.gds`` file, extruded per layer; uploaded by ``submit``.
+
+    ``layers`` maps a GDS layer number to ``(n, height_um)`` or ``(n, height_um, z_offset_um)``;
+    ``n`` may be a number or a ``Medium``. Layers not listed are not included. When
+    ``layers`` is None every layer of the file is extruded by ``layer_height`` µm in the
+    primitive's own material ``n``. The layout is centred on its top structure's bounding
+    box centre, placed at ``center`` (world µm).
+    """
+
+    path: Union[str, Path] = ""
+    center: Vec3 = (0.0, 0.0, 0.0)
+    layers: Optional[Dict[int, Sequence[Any]]] = None
+    layer_height: float = 1.0
+    rotation: Vec3 = (0.0, 0.0, 0.0)
+    scale: Vec3 = (1.0, 1.0, 1.0)
+    voxelization_method: str = "ViaStl"
+    kind: str = field(default="Gds", init=False, repr=False)
+
+    def __post_init__(self):
+        super().__post_init__()
+        self.path = Path(self.path)
+        if not self.path.is_file():
+            raise FileNotFoundError(f"Gds {self.name}: file not found: {self.path}")
+        self.center = _vec3(self.center, "center")
+        self.rotation = _vec3(self.rotation, "rotation")
+        self.scale = _vec3(self.scale, "scale")
+        if self.layer_height <= 0:
+            raise ValueError(f"Gds {self.name}: layer_height must be > 0")
+        if self.layers is not None:
+            parsed: Dict[int, Tuple[Medium, float, Optional[float]]] = {}
+            for num, spec in self.layers.items():
+                spec = tuple(spec) if isinstance(spec, (list, tuple)) else (spec,)
+                if len(spec) < 2 or len(spec) > 3:
+                    raise ValueError(
+                        f"Gds {self.name}: layers[{num}] must be (n, height_um) or (n, height_um, z_offset_um), got {spec!r}")
+                med = as_medium(spec[0], f"layers[{num}].n")
+                h = float(spec[1])
+                if h <= 0:
+                    raise ValueError(f"Gds {self.name}: layers[{num}] height must be > 0")
+                z = float(spec[2]) if len(spec) == 3 else None
+                parsed[int(num)] = (med, h, z)
+            self._layers = parsed
+        else:
+            self._layers = None
+
+    def layer_media(self) -> List[Medium]:
+        return [m for (m, _, _) in (self._layers or {}).values()]
+
+    def files(self):
+        return [("file", self.path)]
+
+    def to_dict(self, medium_id, file_ids, subpixel, layer_medium_ids: Optional[Dict[int, str]] = None):
+        configs = None
+        selected = None
+        if self._layers is not None:
+            selected = sorted(self._layers)
+            configs = [
+                jh.create_gds_layer_config(num, medium_id=(layer_medium_ids or {}).get(num, medium_id),
+                                           height_um=h, z_offset_um=z)
+                for num, (_, h, z) in sorted(self._layers.items())
+            ]
+        return jh.create_gds_primitive(self.name, file_ids["file"], medium_id, *self.center,
+                                       layer_height_um=float(self.layer_height), selected_layers=selected,
+                                       layer_configs=configs, voxelization_method=self.voxelization_method,
+                                       rotation_x=self.rotation[0], rotation_y=self.rotation[1],
+                                       rotation_z=self.rotation[2], scale_x=self.scale[0], scale_y=self.scale[1],
+                                       scale_z=self.scale[2], subpixel=subpixel)
+
+
+@dataclass
+class VoxelArray(Primitive):
+    """A user permittivity (or refractive index) array drawn as a voxel block.
+
+    The array is VOXEL-INDEX based; its corner (0,0,0) lands on the domain
+    corner unless ``center`` moves it. ``pixel_size`` None = the simulation
+    pixel size (array at grid resolution); a finer whole-number pitch is
+    block-averaged on the service when ``subpixel=True``. ``n`` is ignored
+    (the array carries its own values) and only names the medium entry.
+    """
+
+    array: Optional[np.ndarray] = None
+    data_type: str = "Permittivity"
+    center: Optional[Vec3] = None
+    pixel_size: Optional[Any] = None
+    antialias_width: Optional[float] = None
+    kind: str = field(default="VoxelArray", init=False, repr=False)
+
+    def __post_init__(self):
+        super().__post_init__()
+        if self.array is None:
+            raise ValueError("VoxelArray: array is required")
+        arr = np.asarray(self.array)
+        shape = arr.shape
+        while len(shape) < 3:
+            shape = shape + (1,)
+        self.array = arr.reshape(shape)
+        if self.data_type not in ("Permittivity", "RefractiveIndex"):
+            raise ValueError("VoxelArray: data_type must be 'Permittivity' or 'RefractiveIndex'")
+        if self.center is not None:
+            self.center = _vec3(self.center, "center")
+
+    @property
+    def shape(self) -> Tuple[int, int, int]:
+        return tuple(int(s) for s in self.array.shape[:3])  # type: ignore[return-value]
+
+    def to_dict(self, medium_id, file_ids, subpixel, pitch: Vec3 = (0.1, 0.1, 0.1), center: Vec3 = (0.0, 0.0, 0.0)):
+        nx, ny, nz = self.shape
+        fmt = "Complex64" if np.iscomplexobj(self.array) else "Float32"
+        return jh.create_voxels_model_primitive(
+            self.name, file_ids["array"], medium_id, *center, *pitch, nx, ny, nz, fmt, self.data_type,
+            subpixel=(True if subpixel else None), antialias_width=self.antialias_width)
+
+
+GEOMETRY_KINDS = (Sphere, Box, Ellipsoid, Cylinder, Cone, Prism, Stl, Gds)
+
+
+# ---------------------------------------------------------------------------
+# Sources and monitors
+# ---------------------------------------------------------------------------
+
+_POL_NAMES = {None: None, "none": None, "x": "x", "y": "y", "z": "z", 0: "x", 1: "y", 2: "z"}
+
+
+def normalize_polarization(pol) -> Optional[str]:
+    """None / 'none' → None (scalar); 'x'|'y'|'z' or 0|1|2 → 'x'|'y'|'z'."""
+    key = pol.lower() if isinstance(pol, str) else pol
+    if key not in _POL_NAMES:
+        raise ValueError(f"polarization must be None, 'x', 'y', 'z' or 0/1/2, got {pol!r}")
+    return _POL_NAMES[key]
+
+
+@dataclass
+class FieldSource:
+    """A user-computed source field placed on the grid.
+
+    ``field`` is a complex array (any shape up to 3D; a leading singleton
+    component axis of a 4D FOSS array is dropped). ``position`` is the VOXEL
+    INDEX of the field's corner (ix, iy, iz), as in ``wavesim.simulate``.
+    ``polarization`` None = scalar Helmholtz; 'x'|'y'|'z' (or 0|1|2) = Maxwell.
+    ``amplitude`` scales the field.
+    """
+
+    field: np.ndarray
+    position: Tuple[int, int, int] = (0, 0, 0)
+    polarization: Optional[Union[str, int]] = None
+    amplitude: complex = 1.0
+    name: Optional[str] = None
+
+    def __post_init__(self):
+        arr = np.asarray(self.field)
+        if arr.ndim == 4:
+            if arr.shape[0] != 1:
+                raise ValueError("FieldSource: a 4D field must have a single leading component (shape [1, nx, ny, nz])")
+            arr = arr[0]
+        shape = arr.shape
+        while len(shape) < 3:
+            shape = shape + (1,)
+        self.field = arr.reshape(shape).astype(np.complex64, copy=False)
+        pos = tuple(self.position)
+        if len(pos) != 3:
+            raise ValueError(f"FieldSource: position must be (ix, iy, iz) voxel indices, got {self.position!r}")
+        self.position = tuple(int(round(float(p))) for p in pos)  # type: ignore[assignment]
+        self.polarization = normalize_polarization(self.polarization)
+        if self.name is None:
+            self.name = _auto_name("source")
+
+    @classmethod
+    def from_foss(cls, item: tuple) -> "FieldSource":
+        """From the FOSS ``(array, position)`` tuple: position is (ix, iy, iz) for
+        scalar runs or (pol, ix, iy, iz) for vectorial ones."""
+        arr, pos = item
+        pos = list(pos)
+        if len(pos) == 4:
+            return cls(arr, (pos[1], pos[2], pos[3]), polarization=int(pos[0]))
+        if len(pos) == 3:
+            return cls(arr, (pos[0], pos[1], pos[2]), polarization=None)
+        raise ValueError(f"source position must be (ix, iy, iz) or (pol, ix, iy, iz), got {pos!r}")
+
+
+def PlaneWave(name: str = "PlaneWave1", center: Vec3 = (0.0, 0.0, 0.0), **kwargs) -> Dict[str, Any]:
+    """Service-computed plane wave; see ``create_plane_wave_source`` for the keyword arguments."""
+    x, y, z = _vec3(center, "center")
+    return jh.create_plane_wave_source(name, x, y, z, **kwargs)
+
+
+def GaussianBeam(name: str = "GaussianBeam1", center: Vec3 = (0.0, 0.0, 0.0), **kwargs) -> Dict[str, Any]:
+    """Service-computed Gaussian beam; see ``create_gaussian_beam_source``."""
+    x, y, z = _vec3(center, "center")
+    return jh.create_gaussian_beam_source(name, x, y, z, **kwargs)
+
+
+def PointSource(name: str = "PointSource1", center: Vec3 = (0.0, 0.0, 0.0), **kwargs) -> Dict[str, Any]:
+    """Service-computed point source; see ``create_point_source``."""
+    x, y, z = _vec3(center, "center")
+    return jh.create_point_source(name, x, y, z, **kwargs)
+
+
+def ModeSource(name: str = "Mode1", center: Vec3 = (0.0, 0.0, 0.0), **kwargs) -> Dict[str, Any]:
+    """Waveguide mode solved on the service at the source plane; see ``create_mode_source``."""
+    x, y, z = _vec3(center, "center")
+    return jh.create_mode_source(name, x, y, z, **kwargs)
+
+
+def Monitor(name: str = "Monitor_0", center: Vec3 = (0.0, 0.0, 0.0), size: Vec3 = (1.0, 1.0, 1.0),
+            **kwargs) -> Dict[str, Any]:
+    """A 3D field monitor (sub-cube of the output); see ``create_monitor``."""
+    cx, cy, cz = _vec3(center, "center")
+    sx, sy, sz = _vec3(size, "size")
+    return jh.create_monitor(name, cx, cy, cz, sx, sy, sz, **kwargs)
+
+
+def source_dict_is_polarized(src: Dict[str, Any]) -> bool:
+    pol = src.get("Polarization", "None")
+    return str(pol).lower() not in ("", "none")
+
+
+def boxes_intersect(a: Tuple[Vec3, Vec3], b: Tuple[Vec3, Vec3]) -> bool:
+    (amin, amax), (bmin, bmax) = a, b
+    return all(amin[i] <= bmax[i] and bmin[i] <= amax[i] for i in range(3))