cwt3d 1.0.0__py3-none-any.whl

cwt3d/__init__.py

@@ -0,0 +1,9 @@
+"""Independent 3D-CWT core; importing it never loads legacy/COMSOL backends.
+
+NumPy/SciPy form the reference backend. Numba is optional and is neither
+imported nor required by the core mathematical conventions.
+"""
+
+from . import conventions
+
+__all__ = ["conventions"]

cwt3d/cache.py

@@ -0,0 +1,324 @@
+"""Opt-in, local NPZ+JSON coupling snapshots; never deserialize Python objects.
+
+Construction/key/load do not create directories. Only explicit build misses or
+store write. Corrupt/mismatched entries raise CacheError (never silent success).
+Expiration is a miss. No automatic prune: invoke prune/clear explicitly.
+Checksums detect damage, not an adversary able to rewrite both data and manifest;
+use a directory whose writers you trust. Reading cannot execute pickled code.
+"""
+from dataclasses import fields
+from hashlib import sha256
+import inspect
+import json
+import math
+import os
+from pathlib import Path
+import re
+import sys
+import tempfile
+import time
+import zipfile
+
+import numpy as np
+import scipy
+from .coupling import CouplingResult, build_coupling, _pack
+from .geometry import CircleHole, RightTriangleHole, SampledPermittivity
+from .waveguide import TEMode, _positive_scalar
+
+SCHEMA = 'cwt3d-coupling-v1'
+DEFAULT_MAX_BYTES = 256*1024*1024
+DEFAULT_MAX_AGE = 7*24*60*60
+_BUILD_SIGNATURE = inspect.signature(build_coupling)
+_ARRAY_NAMES = ('C1D', 'Crad', 'C2D', 'C2D_green', 'C2D_local', 'C', 'I', 'J',
+                'K', 'xi', 'xi_orders', 'aux_orders', 'mu', 'nu', 'varsigma')
+
+
+class CacheError(ValueError):
+    """Malformed, damaged or mismatched cache entry; explicit clear to rebuild."""
+
+
+def _json(value):
+    return json.dumps(value, sort_keys=True, separators=(',', ':'), allow_nan=False)
+
+
+def _array(value):
+    a = np.ascontiguousarray(value)
+    if a.dtype.kind not in 'iufc':
+        raise TypeError('cache arrays must be numeric')
+    return {'shape': list(a.shape), 'dtype': a.dtype.str,
+            'sha256': sha256(a.tobytes()).hexdigest()}
+
+
+def _canonical(value):
+    if isinstance(value, np.generic):
+        value = value.item()
+    if value is None or isinstance(value, (str, bool, int)):
+        return value
+    if isinstance(value, float):
+        return {'float': value.hex()}
+    if isinstance(value, complex):
+        return {'complex': [value.real.hex(), value.imag.hex()]}
+    if isinstance(value, (list, tuple)):
+        return [_canonical(v) for v in value]
+    if isinstance(value, np.ndarray):
+        return _array(value)
+    raise TypeError(f'unsupported cache key type: {type(value).__name__}')
+
+
+def algorithm_digest():
+    """Actual source digest, not callable identity/repr or a manual version only."""
+    root = Path(__file__).parent
+    digest = sha256()
+    for path in sorted(root.rglob('*.py')):
+        digest.update(path.relative_to(root).as_posix().encode())
+        digest.update(path.read_bytes())
+    return digest.hexdigest()
+
+
+def _document(mode, period_um, pc_layers, options):
+    if not isinstance(mode, TEMode):
+        raise TypeError('mode must be a normalized TEMode')
+    bound = _BUILD_SIGNATURE.bind(mode, period_um, pc_layers, **options)
+    bound.apply_defaults()
+    # Match the real build's scalar semantics, not the caller's container/dtype.
+    # Do not generalize this normalization to geometry or solved-field arrays.
+    period_um = _positive_scalar(period_um, 'period_um')
+    guide = mode.guide
+    geometry = []
+    for index, shape in sorted(dict(pc_layers).items()):
+        if isinstance(shape, SampledPermittivity):
+            state = {'period_um': shape.period_um, 'values': shape.values}
+        elif isinstance(shape, (CircleHole, RightTriangleHole)):
+            state = {f.name: getattr(shape, f.name) for f in fields(shape)}
+        else:
+            raise TypeError('unsupported cache geometry')
+        geometry.append([_canonical(index), type(shape).__name__,
+                         {k: _canonical(v) for k, v in state.items()}])
+    # Include the actual interpolation mesh/materials and normalized field,
+    # not just beta or a caller-assigned mode index. Altered solved shapes miss.
+    state = {'eps': guide.eps, 'thickness_um': guide.thickness_um,
+             'interfaces_um': guide.interfaces_um, 'k0': guide.k0,
+             'period_um': guide.period_um, 'nodes': guide._nodes,
+             'lengths': guide._lengths, 'materials': guide._materials,
+             'beta': mode.beta, 'value': mode._value, 'field': mode._field}
+    return {'schema': SCHEMA, 'algorithm': algorithm_digest(),
+            'numpy': np.__version__, 'scipy': scipy.__version__, 'byteorder': sys.byteorder,
+            'guide_mode': {k: _canonical(v) for k,v in state.items()},
+            'geometry': geometry, 'period_um': _canonical(period_um),
+            'options': {k: _canonical(v) for k,v in bound.arguments.items()
+                        if k not in ('mode', 'period_um', 'pc_layers')}}
+
+
+def _tuple(value):
+    return tuple(_tuple(v) for v in value) if isinstance(value, list) else value
+
+
+def _validate_metadata(metadata, document):
+    """Reject accidental public store mis-keying before writing/returning a hit."""
+    if metadata.get('provenance') != _json(document):
+        raise CacheError('result metadata provenance does not match complete key inputs')
+    options = document['options']
+    for name in ('cutoff', 'quadrature_order', 'fourier_order', 'backend'):
+        if _canonical(metadata[name]) != options[name]:
+            raise CacheError('result metadata does not match key numerical controls')
+    def real(value):
+        return float.fromhex(value['float']) if isinstance(value, dict) else float(value)
+    period = real(document['period_um'])
+    beta0 = 2*np.pi/period
+    beta = real(document['guide_mode']['beta'])
+    expected = dict(period_um=period, beta0=beta0,
+                    k0=real(document['guide_mode']['k0']),
+                    relative_detuning=(beta-beta0)/beta0, units='um^-1')
+    if any(metadata[name] != value for name, value in expected.items()):
+        raise CacheError('result metadata does not match key structure/period')
+    ids = [item[0] for item in document['geometry']]
+    if _json(metadata['pc_layers']) != _json(ids):
+        raise CacheError('result metadata does not match PC layer indices')
+    shapes = [[item[0], item[2]['values']['shape']] for item in document['geometry']
+              if item[1] == 'SampledPermittivity']
+    if _json(metadata['sampling_shapes']) != _json(shapes):
+        raise CacheError('result metadata does not match sampled dimensions')
+
+
+def _check_archive(path, max_bytes):
+    """Bound expanded bytes AND NPY declared shapes before np.load allocates."""
+    with zipfile.ZipFile(path) as archive:
+        members = archive.infolist()
+        if (len(members) != len(_ARRAY_NAMES)+1
+                or {x.filename for x in members} != {n+'.npy' for n in (*_ARRAY_NAMES, 'manifest')}
+                or sum(x.file_size for x in members) > max_bytes):
+            raise CacheError('entry exceeds cache schema/expanded byte budget')
+        for member in members:
+            with archive.open(member) as stream:
+                version = np.lib.format.read_magic(stream)
+                if version == (1, 0):
+                    shape, _, dtype = np.lib.format.read_array_header_1_0(stream)
+                elif version == (2, 0):
+                    shape, _, dtype = np.lib.format.read_array_header_2_0(stream)
+                else:
+                    raise CacheError('unsupported NPY format')
+                if (dtype.hasobject or dtype.kind not in 'iufc'
+                        or any(d < 0 for d in shape)
+                        or math.prod(shape)*dtype.itemsize != member.file_size-stream.tell()):
+                    raise CacheError('unsafe or mismatched NPY payload size/type')
+
+
+class CouplingCache:
+    """Explicit directory ownership prefix cwt3d-<SHA256>.npz.
+
+    Default age 7 days, size 256 MiB. Size limits bound each expanded entry and
+    explicit prune's total retained storage. readonly forbids every write/delete.
+    Concurrent misses may duplicate work; atomic replace keeps complete snapshots,
+    not guaranteed concurrent success. Windows open readers may block replacement
+    with PermissionError/WinError 5. Callers must serialize access or retry errors;
+    no cross-process lock or automatic retry is provided.
+    Private temp files are always in directory and cleaned on normal failure.
+    """
+    def __init__(self, directory, *, readonly=False, max_age=DEFAULT_MAX_AGE,
+                 max_bytes=DEFAULT_MAX_BYTES):
+        self.directory = Path(directory)
+        self.readonly = bool(readonly)
+        if max_age is not None and (isinstance(max_age, bool) or not np.isfinite(max_age) or max_age < 0):
+            raise ValueError('max_age must be None or finite nonnegative seconds')
+        if isinstance(max_bytes, bool) or not isinstance(max_bytes, int) or max_bytes <= 0:
+            raise ValueError('max_bytes must be a positive integer')
+        self.max_age, self.max_bytes = max_age, max_bytes
+
+    def key(self, mode, period_um, pc_layers, **options):
+        return sha256(_json(_document(mode, period_um, pc_layers, options)).encode()).hexdigest()
+
+    def document(self, mode, period_um, pc_layers, **options):
+        """Canonical JSON-compatible provenance for explicit store calls."""
+        return _document(mode, period_um, pc_layers, options)
+
+    def path(self, key):
+        if not isinstance(key, str) or re.fullmatch('[0-9a-f]{64}', key) is None:
+            raise ValueError('key must be lowercase SHA256 hex')
+        return self.directory/f'cwt3d-{key}.npz'
+
+    def _writable(self):
+        if self.readonly:
+            raise PermissionError('cache is readonly')
+
+    def load(self, key):
+        path = self.path(key)
+        if not path.exists():
+            return None
+        if path.is_symlink():
+            raise CacheError('cache entry must not be a symlink')
+        if self.max_age is not None and time.time()-path.stat().st_mtime > self.max_age:
+            return None
+        try:
+            _check_archive(path, self.max_bytes)
+            with np.load(path, allow_pickle=False) as data:
+                if set(data.files) != {*_ARRAY_NAMES, 'manifest'}:
+                    raise CacheError('unexpected array names')
+                raw = data['manifest']
+                if raw.dtype != np.uint8 or raw.ndim != 1:
+                    raise CacheError('manifest must be JSON bytes')
+                manifest = json.loads(raw.tobytes())
+                if manifest['schema'] != SCHEMA or manifest['key'] != key:
+                    raise CacheError('cache schema/key mismatch')
+                if sha256(_json(manifest['document']).encode()).hexdigest() != key:
+                    raise CacheError('cache key document mismatch')
+                if (manifest['document']['algorithm'] != algorithm_digest()
+                        or manifest['document']['numpy'] != np.__version__
+                        or manifest['document']['scipy'] != scipy.__version__
+                        or manifest['document']['byteorder'] != sys.byteorder):
+                    return None
+                arrays = {name: data[name] for name in _ARRAY_NAMES}
+                if any(_array(a) != manifest['arrays'][name] for name,a in arrays.items()):
+                    raise CacheError('array checksum/shape/dtype mismatch')
+                metadata = manifest['metadata']
+                check = sha256(_json(metadata).encode()).hexdigest()
+                if check != manifest['metadata_sha256']:
+                    raise CacheError('metadata checksum mismatch')
+                _validate_metadata(metadata, manifest['document'])
+                return CouplingResult(_pack(**arrays), **{k:_tuple(v) for k,v in metadata.items()})
+        except CacheError:
+            raise
+        except (OSError, ValueError, KeyError, TypeError, AttributeError, OverflowError,
+                zipfile.BadZipFile, EOFError, RuntimeError) as exc:
+            raise CacheError('invalid coupling cache entry') from exc
+
+    def store(self, key, result, *, document):
+        self._writable()
+        target = self.path(key)
+
+        if sha256(_json(document).encode()).hexdigest() != key:
+            raise CacheError('store document/key mismatch')
+        arrays = {name: getattr(result, name) for name in _ARRAY_NAMES}
+        metadata = {f.name: getattr(result, f.name) for f in fields(result) if f.name != '_arrays'}
+        _validate_metadata(metadata, document)
+        manifest = {'schema': SCHEMA, 'key': key, 'document': document,
+                    'metadata': metadata, 'metadata_sha256':sha256(_json(metadata).encode()).hexdigest(),
+                    'arrays': {name:_array(a) for name,a in arrays.items()}}
+        raw = _json(manifest).encode()
+        if sum(a.nbytes for a in arrays.values())+len(raw)+16384 > self.max_bytes:
+            raise CacheError('entry exceeds cache byte budget')
+        self.directory.mkdir(parents=True, exist_ok=True)
+        temp = None
+        try:
+            with tempfile.NamedTemporaryFile(dir=self.directory, prefix='.cwt3d-', suffix='.tmp', delete=False) as stream:
+                temp = Path(stream.name)
+                np.savez(stream, manifest=np.frombuffer(raw, dtype=np.uint8), **arrays)
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temp, target)
+        finally:
+            if temp is not None:
+                temp.unlink(missing_ok=True)
+
+    def build(self, mode, period_um, pc_layers, **options):
+        document = _document(mode, period_um, pc_layers, options)
+        key = sha256(_json(document).encode()).hexdigest()
+        result = self.load(key)
+        if result is not None:
+            return result
+        self._writable()
+        result = build_coupling(mode, period_um, pc_layers, **options)
+        self.store(key, result, document=document)
+        return result
+
+    def clear(self, key):
+        self._writable()
+        self.path(key).unlink(missing_ok=True)
+
+    def prune(self):
+        """Delete recognized owned entries, expired then oldest.
+
+        Recognition checks ZIP/NPY layout and schema/key document, not array or
+        metadata checksums/provenance. Thus recognized checksum-damaged entries
+        can be deleted by age/size policy. Unrecognized files, symlinks and
+        crash-left temp files are retained; max_bytes counts recognized files only.
+        """
+        self._writable()
+        entries = []
+        if not self.directory.exists():
+            return []
+        for path in self.directory.iterdir():
+            match = re.fullmatch(r'cwt3d-([0-9a-f]{64})\.npz', path.name)
+            if not match or path.is_symlink() or not path.is_file():
+                continue
+            try:
+                _check_archive(path, max(self.max_bytes, DEFAULT_MAX_BYTES))
+                with np.load(path, allow_pickle=False) as data:
+                    manifest = json.loads(data['manifest'].tobytes())
+                key = match[1]
+                if (manifest['schema'] != SCHEMA or manifest['key'] != key or
+                    sha256(_json(manifest['document']).encode()).hexdigest() != key):
+                    continue
+            except (OSError, ValueError, KeyError, TypeError, AttributeError,
+                    OverflowError, zipfile.BadZipFile, EOFError, RuntimeError):
+                continue
+            stat = path.stat()
+            entries.append((stat.st_mtime, stat.st_size, key, path))
+        total = sum(e[1] for e in entries)
+        removed = []
+        now = time.time()
+        for mtime, size, key, path in sorted(entries):
+            if (self.max_age is not None and now-mtime > self.max_age) or total > self.max_bytes:
+                path.unlink()
+                total -= size
+                removed.append(key)
+        return removed

cwt3d/conventions.py

@@ -0,0 +1,128 @@
+"""Shared mathematical conventions for the square-lattice TE reference core.
+
+Fields use exp(+i*omega*t) and exp(-i*beta0*(m*x+n*y)). Fourier
+coefficients use the positive exponent and the unit-cell average (1/area).
+The four TE amplitudes are (Rx, Sx, Ry, Sy): the x-travelling waves
+contribute to Ey and the y-travelling waves to Ex, with no extra sign.
+Thus Ey = Rx*exp(-i*beta0*x) + Sx*exp(+i*beta0*x), and
+Ex = Ry*exp(-i*beta0*y) + Sy*exp(+i*beta0*y), before any common
+longitudinal profile. Its normalization belongs to the future waveguide API.
+
+Internal lengths are micrometres (um); wavenumbers and amplitude losses
+are um^-1, never implicitly cm^-1. E(s)=E(0)*exp(-alpha*s) defines
+positive amplitude loss alpha; power decays as exp(-2*alpha*s).
+Negative alpha denotes gain. No eigenvalue-to-alpha rule is imposed here.
+"""
+
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+TIME_EXPONENT_SIGN = 1
+SPATIAL_EXPONENT_SIGN = -1
+FOURIER_COEFFICIENT_EXPONENT_SIGN = 1
+INTERNAL_LENGTH_UNIT = "um"
+INTERNAL_INVERSE_LENGTH_UNIT = "um^-1"
+
+
+@dataclass(frozen=True)
+class BasicWave:
+    """Immutable harmonic index and transverse electric-field component."""
+
+    name: str
+    m: int
+    n: int
+    electric_component: Literal["Ex", "Ey"]
+
+
+BASIC_WAVES = (
+    BasicWave("Rx", 1, 0, "Ey"),
+    BasicWave("Sx", -1, 0, "Ey"),
+    BasicWave("Ry", 0, 1, "Ex"),
+    BasicWave("Sy", 0, -1, "Ex"),
+)
+BASIC_WAVE_ORDER = tuple(wave.name for wave in BASIC_WAVES)
+
+
+def time_phase(omega_rad_per_time: ArrayLike, t: ArrayLike):
+    """Return exp(+i*omega*t); omega and t must use matching time units."""
+    return np.exp(1j * TIME_EXPONENT_SIGN * np.asarray(omega_rad_per_time) * np.asarray(t))
+
+
+def spatial_phase(m: int, n: int, *, beta0_per_um: ArrayLike,
+                  x_um: ArrayLike, y_um: ArrayLike):
+    """Return exp(-i*beta0*(m*x+n*y)) with NumPy broadcasting.
+
+    Coordinates must be in um and beta0 in um^-1; m,n are the signed
+    integer harmonic indices. This is a basis phase, not a Fourier solver.
+    """
+    argument = np.asarray(beta0_per_um) * (m * np.asarray(x_um) + n * np.asarray(y_um))
+    return np.exp(1j * SPATIAL_EXPONENT_SIGN * argument)
+
+
+def fourier_coefficient_phase(m: int, n: int, *, beta0_per_um: ArrayLike,
+                              x_um: ArrayLike, y_um: ArrayLike):
+    """Return the positive-exponent weight for the (m,n) coefficient.
+
+    Multiply the field by this weight and average over one unit cell.
+    Coordinates and beta0 use um and um^-1; no integration is done here.
+    """
+    argument = np.asarray(beta0_per_um) * (m * np.asarray(x_um) + n * np.asarray(y_um))
+    return np.exp(1j * FOURIER_COEFFICIENT_EXPONENT_SIGN * argument)
+
+
+def _real_finite(value: ArrayLike) -> NDArray[np.float64]:
+    array = np.asarray(value)
+    if array.dtype.kind not in "iuf":
+        raise TypeError("Expected real numeric values, not boolean, complex or text")
+    array = array.astype(np.float64)
+    if not np.all(np.isfinite(array)):
+        raise ValueError("Values must be finite")
+    return array
+
+
+def _scaled(value: ArrayLike, scale: float) -> float | NDArray[np.float64]:
+    with np.errstate(over="raise", invalid="raise"):
+        result = _real_finite(value) * scale
+    return float(result) if result.ndim == 0 else result
+
+
+def convert_length(value: ArrayLike, *, from_unit: Literal["um", "cm"],
+                   to_unit: Literal["um", "cm"]) -> float | NDArray[np.float64]:
+    """Convert real finite lengths between explicit 'um' and 'cm'.
+
+    Both units are required keywords; inverse-length/unknown units fail
+    rather than being guessed. Scalars return float; arrays return float64
+    arrays. Signed coordinates are allowed. Input arrays are not modified.
+    """
+    scales = {"um": 1.0, "cm": 1e4}  # length in internal um
+    if from_unit not in scales or to_unit not in scales:
+        raise ValueError("Length units must be 'um' or 'cm'")
+    return _scaled(value, scales[from_unit] / scales[to_unit])
+
+
+def convert_inverse_length(value: ArrayLike, *,
+                           from_unit: Literal["um^-1", "cm^-1"],
+                           to_unit: Literal["um^-1", "cm^-1"]) -> float | NDArray[np.float64]:
+    """Convert real finite wavenumbers/losses, preserving their sign.
+
+    Explicit unit strings prevent confusing lengths with inverse lengths:
+    1 um^-1 = 1e4 cm^-1. Scalars return float; arrays return float64
+    arrays. This does not convert amplitude loss into power loss.
+    """
+    scales = {"um^-1": 1.0, "cm^-1": 1e-4}
+    if from_unit not in scales or to_unit not in scales:
+        raise ValueError("Inverse-length units must be 'um^-1' or 'cm^-1'")
+    return _scaled(value, scales[from_unit] / scales[to_unit])
+
+
+def amplitude_loss_to_power_loss(alpha_per_um: ArrayLike) -> float | NDArray[np.float64]:
+    """Return power loss 2*alpha in um^-1 from amplitude loss in um^-1.
+
+    E(s)=E(0)*exp(-alpha*s), so |E(s)|^2=|E(0)|^2*exp(-2*alpha*s).
+    Signed real finite scalar/array inputs are supported; negative is gain.
+    Convert cm^-1 explicitly with convert_inverse_length before calling.
+    """
+    return _scaled(alpha_per_um, 2.0)

cwt3d/coupling.py

@@ -0,0 +1,186 @@
+"""Lossless square-lattice TE reference coupling, all C terms in um^-1.
+
+V=(Rx,Sx,Ry,Sy), harmonics=(+x,-x,+y,-y), fields=(y,y,x,x).
+Liang thesis (3.27)-(3.35), extended with LOCAL receiver/source xi in
+multiple PC layers. No averaging of xi before applying the Green operator.
+No legacy imports, output files, material-loss truncation or hidden redesign.
+"""
+from dataclasses import dataclass
+import numpy as np
+from .geometry import CircleHole, RightTriangleHole, SampledPermittivity, _integer
+from .fourier import shape_fourier, fft_fourier
+from .greens import LayeredGreen, PreparedLayeredGreen
+from .quadrature import mode_overlap, green_overlap
+from .waveguide import TEMode, _positive_scalar
+
+
+def _pack(**arrays):
+    return tuple((name,a.shape,a.dtype.str,a.tobytes())
+                 for name,value in arrays.items() for a in [np.asarray(value)])
+
+
+class _Snapshots:
+    def __getattr__(self,name):
+        for key,shape,dtype,data in self._arrays:
+            if name == key:
+                return np.ndarray(shape,dtype=dtype,buffer=data)
+        raise AttributeError(name)
+
+
+@dataclass(frozen=True)
+class CouplingResult(_Snapshots):
+    """Independent bytes-backed array headers on EVERY read.
+
+    C1D=kappa feedback; Crad=zeta; C2D=chi including -k0²/(2 beta0).
+    C2D_green and C2D_local separate mu and negative-nu contributions.
+    mu/nu have axes (auxiliary, receiver layer, source basic wave), and
+    varsigma has (auxiliary, receiver layer, component x/y, source wave).
+    They are dimensionless receiver-layer integrated fields, NOT averaged xi.
+    Summing the receiver-layer axis gives thesis (3.28)/(3.29)/(3.27).
+    I,J,K are layer overlaps; K radial axis corresponds to radial_orders
+    (zero is radiation). xi is the Fourier table with indices xi_orders.
+    No a-priori quadrature error estimate: order/cutoff are explicit metadata.
+    """
+    _arrays: tuple
+    period_um: float
+    beta0: float
+    k0: float
+    relative_detuning: float
+    cutoff: int
+    quadrature_order: int
+    pc_layers: tuple
+    radial_orders: tuple
+    all_aux_evanescent: bool
+    units: str = 'um^-1'
+    fourier_order: int = 64
+    backend: str = 'reference'
+    sampling_shapes: tuple = ()
+    # Immutable canonical input snapshot; empty for manually constructed results.
+    # Not an authentication signature against deliberate dataclass forgery.
+    provenance: str = ''
+
+
+def build_coupling(mode, period_um, pc_layers, *, cutoff=1,
+                   quadrature_order=12, fourier_order=64, beta_rtol=1e-8,
+                   backend='reference'):
+    """Build physical reference C using a normalized TEMode.
+
+    pc_layers maps guide epsilon indices 1..len(eps)-2 to a CircleHole,
+    RightTriangleHole or SampledPermittivity. Others have xi=0; empty mapping
+    is legal and gives C=0. Each geometry's mean MUST match guide epsilon.
+    Scalar period is explicitly square and must match mode.beta within
+    beta_rtol (default 1e-8 relative). A relaxed tolerance records detuning
+    but does not add a detuning diagonal or alter period/k0. This is the
+    near-Bragg coupling operator, not a self-consistent frequency solve.
+    Quadrature is fixed-order per material interval. Kernels/overlaps reused
+    by m²+n², never recomputed per matrix entry. Scalar TE/nonmagnetic only.
+    Propagating auxiliaries allowed; C2D Hermiticity then not promised.
+    backend='reference' is the unchanged dense per-pair regression anchor;
+    'prepared' uses one pole check/LU per radial kernel and batched source RHS,
+    with identical Fourier/quadrature orders and same-layer Duffy integration.
+    fourier_order and sampled grid shapes are retained in result metadata.
+    """
+    if not isinstance(mode,TEMode):
+        raise TypeError('mode must be a normalized TEMode')
+    if backend not in ('reference', 'prepared'):
+        raise ValueError("backend must be 'reference' or 'prepared'")
+    a = _positive_scalar(period_um,'period_um')
+    D = _integer(cutoff,'cutoff')
+    Q = _integer(quadrature_order,'quadrature_order')
+    F = _integer(fourier_order,'fourier_order')
+    if isinstance(beta_rtol,(bool,np.bool_)) or not np.isscalar(beta_rtol) or not np.isfinite(beta_rtol) or beta_rtol < 0:
+        raise ValueError('beta_rtol must be finite and nonnegative')
+    b = 2*np.pi/a
+    if not np.isfinite(b) or b <= 0 or not np.isfinite(b*b) or b*b == 0:
+        raise ValueError('beta0 or beta0 squared outside resolved finite range')
+    detuning = (mode.beta-b)/b
+    if abs(detuning) > beta_rtol:
+        raise ValueError('mode.beta does not match beta0=2*pi/period_um within beta_rtol')
+    guide = mode.guide
+    if guide.period_um is not None and not np.isclose(guide.period_um,a,rtol=1e-12,atol=0):
+        raise ValueError('period_um differs from guide fixed period')
+    layers = dict(pc_layers)
+    for l,h in layers.items():
+        if isinstance(l,(bool,np.bool_)) or not isinstance(l,(int,np.integer)) or not 1 <= l <= len(guide.eps)-2:
+            raise ValueError('PC layer indices must be finite internal epsilon indices')
+        if not isinstance(h,(CircleHole,RightTriangleHole,SampledPermittivity)):
+            raise TypeError('Unsupported PC geometry')
+        if not np.allclose(h.period_um,(a,a),rtol=1e-12,atol=0):
+            raise ValueError('geometry must have the specified square period')
+        material = h.values if isinstance(h,SampledPermittivity) else np.array([h.eps_background,h.eps_hole])
+        if np.any(material.imag != 0) or np.any(material.real <= 0):
+            raise ValueError('PC materials must be positive lossless epsilon')
+        mean = material.mean() if isinstance(h,SampledPermittivity) else h.mean_epsilon
+        if not np.isclose(mean,guide.eps[l],rtol=1e-11,atol=1e-12):
+            raise ValueError('geometry mean epsilon does not match averaged waveguide')
+    # Lazy import avoids a module-initialization cycle with the optional cache.
+    # Snapshot actual inputs, not a caller-supplied key or inferred Fourier table.
+    from .cache import _document, _json
+    provenance = _json(_document(mode, a, layers, dict(
+        cutoff=cutoff, quadrature_order=quadrature_order, fourier_order=fourier_order,
+        beta_rtol=beta_rtol, backend=backend)))
+    ids = tuple(sorted(layers))
+    basic = np.array([(1,0),(-1,0),(0,1),(0,-1)])
+    aux = [(m,n) for m in range(-D,D+1) for n in range(-D,D+1) if m*m+n*n > 1]
+    radial = (0,*sorted({m*m+n*n for m,n in aux}))
+    orders = np.array([(m,n) for m in range(-D-1,D+2) for n in range(-D-1,D+2)],dtype=int)
+    lookup = {tuple(o):i for i,o in enumerate(orders)}
+    xi = np.empty((len(ids),len(orders)),complex)
+    for i,l in enumerate(ids):
+        h = layers[l]
+        xi[i] = (fft_fourier(h,orders) if isinstance(h,SampledPermittivity)
+                 else shape_fourier(h,orders,quadrature_order=F))
+        xi[i,lookup[(0,0)]] = 0 # mean is already in the waveguide
+    def coeff(order):
+        return xi[:,lookup[tuple(order)]]
+    edges = guide.interfaces_um
+    bounds = [(edges[l-1],edges[l]) for l in ids]
+    I = np.array([mode_overlap(mode,t,Q) for t in bounds])
+    J = I/np.array([guide.eps[l] for l in ids])
+    K = np.empty((len(radial),len(ids),len(ids)),complex)
+    for index,r2 in enumerate(radial):
+        kernel_type = LayeredGreen if backend == 'reference' else PreparedLayeredGreen
+        kernel = kernel_type.from_structure(guide,b*np.sqrt(r2))
+        for i,left in enumerate(bounds):
+            for j,right in enumerate(bounds):
+                K[index,i,j] = green_overlap(mode,left,right,kernel,Q)
+    f = -guide.k0**2/(2*b)
+    c1,cr,cg,cl = [np.zeros((4,4),complex) for _ in range(4)]
+    for i,p in enumerate(basic):
+        for j,r in enumerate(basic):
+            if j == (i^1):
+                c1[i,j] = f*np.dot(coeff(p-r),I)
+            if i//2 == j//2:
+                cr[i,j] = f*guide.k0**2*(coeff(p)@K[0]@coeff(-r))
+    # Eminus=k0² G A xi Theta; Eplus=-B xi Theta/epsilon.
+    # Ex=(n Eminus+m Eplus)/r²; Ey=(-m Eminus+n Eplus)/r².
+    mus, nus, fields = [], [], []
+    for m,n in aux:
+        r2 = m*m+n*n
+        source = np.stack([coeff(np.array([m,n])-r) for r in basic],axis=1)
+        receiver = np.stack([coeff(p-np.array([m,n])) for p in basic])
+        mu = guide.k0**2*(K[radial.index(r2)]@source)
+        nu = -J[:,None]*source # retain (3.29)'s minus sign
+        A,B = np.array([-m,-m,n,n]),np.array([n,n,m,m])
+        transverse,longitudinal = np.array([-m,-m,n,n]),np.array([n,n,m,m])
+        mus.append(mu)
+        nus.append(nu)
+        # varsigma is integral of Theta* E_(x,y) over EACH receiver layer,
+        # before multiplying that layer's receiver xi; axes (layer, x/y, j).
+        fields.append(np.stack([(n*mu*A+m*nu*B)/r2,
+                                (-m*mu*A+n*nu*B)/r2],axis=1))
+        cg += f*(receiver@mu)*transverse[:,None]*A[None,:]/r2
+        cl += f*(receiver@nu)*longitudinal[:,None]*B[None,:]/r2
+    c2 = cg+cl
+    total = c1+cr+c2
+    if not np.isfinite(total).all():
+        raise ValueError('coupling outside finite numeric range')
+    return CouplingResult(_pack(C1D=c1,Crad=cr,C2D=c2,C2D_green=cg,C2D_local=cl,
+                                C=total,I=I,J=J,K=K,xi=xi,xi_orders=orders,
+                                aux_orders=np.array(aux,dtype=int),
+                                mu=np.array(mus),nu=np.array(nus),varsigma=np.array(fields)),
+                          a,b,guide.k0,float(detuning),D,Q,ids,radial,
+                          bool(all(b*b*r > guide.k0**2*max(guide.eps) for r in radial[1:])),
+                          fourier_order=F, backend=backend, provenance=provenance,
+                          sampling_shapes=tuple((l,layers[l].values.shape) for l in ids
+                                                if isinstance(layers[l],SampledPermittivity)))

cwt3d/finite/__init__.py

@@ -0,0 +1,16 @@
+"""Finite-domain staggered layout, sparse pencil, and targeted eigensolver."""
+from .grid import StaggeredGrid, WaveFields
+from .assembly import FinitePencil, assemble_pencil
+from .eigensolver import (
+    EigenResult, EigenSolveError, FactorizationError, solve_generalized, solve_finite,
+)
+from .fields import FiniteMode, reconstruct_field, reconstruct_mode, reconstruct_modes
+from .tracking import ClusterMatch, ModeTracking, track_modes
+
+__all__ = [
+    'StaggeredGrid', 'WaveFields', 'FinitePencil', 'assemble_pencil',
+    'EigenResult', 'EigenSolveError', 'FactorizationError',
+    'solve_generalized', 'solve_finite',
+    'FiniteMode', 'reconstruct_field', 'reconstruct_mode', 'reconstruct_modes',
+    'ClusterMatch', 'ModeTracking', 'track_modes',
+]