thunder4d 0.9.0__tar.gz

thunder4d-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor Koltalo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

thunder4d-0.9.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: thunder4d
+Version: 0.9.0
+Summary: thunder4d: Transverse-resolved Herriott-cell UPPE solver for Nonlinear Dynamics close to Experimental Reality, 4D
+Author-email: Victor Koltalo <victor.koltalo@ensta.fr>
+License-Expression: MIT
+Project-URL: Documentation, https://victorkolt.github.io/thunder4D/
+Project-URL: Source, https://github.com/victorkolt/thunder4D
+Keywords: UPPE,multipass cell,MPC,nonlinear optics,ultrafast,post-compression,Herriott cell,spatio-temporal,pulse propagation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Requires-Dist: scipy>=1.10
+Provides-Extra: examples
+Requires-Dist: matplotlib; extra == "examples"
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x; extra == "gpu"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+Requires-Dist: sphinx_rtd_theme>=2; extra == "docs"
+Dynamic: license-file
+
+# thunder4D
+
+**T**ransverse-resolved **H**erriott-cell **U**PPE solver for **N**onlinear **D**ynamics close to **E**xperimental **R**eality, **4D**: a 4D (x, y, z, t) UPPE solver for multipass cells. Python package: `thunder4d`.
+
+Full documentation: `https://victorkolt.github.io/thunder4d/`.
+
+`thunder4D` simulates nonlinear pulse propagation in a gas-filled Herriott-type multipass cell (MPC) with full spatial and temporal resolution: the field is A(x, y, t) and it is propagated along z. It is built to study spatial and spatio-spectral effects that 1D or radially symmetric codes cannot capture:
+
+- spatial effects in non-Gaussian inputs (clipped, aberrated, high-order beams),
+- spatio-spectral homogeneity, radial chirp,
+- time-dependent nonlinear mode mismatch,
+- influence of space-time couplings (spatial chirp, pulse-front tilt, …) on the output.
+
+The code is pure Python. NumPy (≥ 2.0) is required. SciPy is optional but strongly recommended, because `scipy.fft` is about 8× faster than `numpy.fft` for the 2D transforms. Matplotlib is only needed for the examples. An NVIDIA GPU is optional: with CuPy installed (`pip install cupy-cuda12x`), `suggest_grid(..., device="auto")` (the default) runs the propagation on the GPU, and `device="cpu"` / `"gpu"` force one or the other. `thunder4d.gpu_available()` tells you whether CuPy works; `thunder4d.to_host(array)` converts a device array to NumPy. Everything returned by `thunder4d.diagnostics` is a NumPy array on either device.
+
+## Quick start
+
+```python
+import thunder4d as m
+from thunder4d import diagnostics as dg
+
+# medium and cell
+gas  = m.Material("Ar", pressure_bar=1.0)
+cell = m.MPC.herriott(R=0.5, N=20, k=3, branch="planar", medium=gas)  # 20 passes, 54 deg Gouy/pass, re-entrant
+
+# grid sized from the cell
+grid = m.suggest_grid(cell, lambda0=1030e-9, lambda_min=900e-9, lambda_max=1200e-9, pulse_fwhm=200e-15, box_factor=12)
+print(grid.describe())
+
+# 1) spectrum (+ phase)
+E = m.gaussian_spectrum(grid, fwhm_fs=200)
+E = m.add_spectral_phase(grid, E, gdd_fs2=0)
+
+# 2) nonlinear mode matching, computed from a probe pulse of the right energy
+probe = m.Pulse.at_focus(grid, E, m.Beam(m.gaussian(1e-3)), 1.2e-3)
+mm = cell.match(probe)
+
+# 3) the actual input beam
+pulse = m.Pulse.at_focus(grid, E, m.Beam(m.gaussian(mm["w0"])), 1.2e-3)
+
+# 4) run
+sim = m.MPCSimulation(pulse, cell, phi_max=0.02, mode_reference=mm["w0"], profile_wavelengths=[1010e-9, 1030e-9, 1050e-9], profile_bandwidth=2e-9)
+sim.run()
+sim.save("run.npz")
+
+# 5) analyse the output
+x, lam, S = dg.spectrogram_x_lambda(grid, sim.Aw)
+c = dg.compress(grid, sim.Aw)
+print(c["fwhm_fs"], c["gdd_fs2"])
+```
+
+---
+
+## Physical model
+
+The field is a complex envelope A(x, y, t) with carrier exp[i(k₀z − ω₀t)], normalised so that |A|² is the intensity in W/m². It is propagated with the unidirectional pulse propagation equation (UPPE), written in the frame moving at the group velocity at λ₀:
+
+```
+∂A(kx, ky, Ω)/∂z = i [ kz(kx, ky, ω) − k₀ − k₁Ω ] A  +  i γ(Ω) FT_t[ |A|² A ]
+
+kz   = sqrt( k(ω)² − kx² − ky² )        (non-paraxial, full gas dispersion)
+k(ω) = n(ω) ω / c,   ω = ω₀ + Ω,   k₁ = dk/dω at ω₀
+γ(Ω) = n₂ ω/c · n(ω₀)/n(ω)               (self-steepening included)
+```
+
+- **Linear operator:** it is exact. It includes diffraction without the paraxial approximation, gas dispersion to all orders, and evanescent components, which decay.
+- **Kerr term:** it is the instantaneous electronic response. Its frequency dependence gives self-steepening. With `self_steepening=False` it becomes γ = n₂ω₀/c.
+- **Edge taper:** the nonlinear source is tapered to zero at the edges of the spectral window to avoid aliasing.
+
+## Numerical scheme
+
+- **Home domain:** the solver keeps the field in the mixed domain (x, y, Ω).
+  - The linear step needs only 2D spatial FFTs, because Ω is already a coordinate.
+  - The Kerr term does not depend on (kx, ky), so it needs only 1D temporal FFTs.
+- **Splitting:** symmetric Strang splitting (linear half-step, nonlinear step, linear half-step). Consecutive linear half-steps are merged.
+- **Nonlinear step:** fourth-order Runge–Kutta.
+- **Adaptive step size:** h = φ_max / (k₀ n₂ I_peak), where φ_max is the peak nonlinear phase allowed per step. It is limited to `dz_max` (default d/8, a quarter of a half-pass) and quantised to `dz_max · 2^(−n/4)`. The quantisation lets the linear propagators exp(iDh) be reused from a small cache.
+
+## Performance and memory
+
+- **Cost per step:** 2 spatial 2D FFTs, 8 temporal 1D FFTs (RK4) and a few array operations. With SciPy on one core, a 150 × 150 × 135 grid takes about 0.1–0.4 s per step. A 20-pass run at B ≈ 16 rad needs about 900 steps.
+- **Steps per pass:** they scale with the B-integral per pass divided by `phi_max`.
+- **Memory:** about 8–10 field arrays: the field, RK4 buffers, the linear operator `D`, up to `cache_size` cached propagators and the cached mirror transfer. One complex64 array is Nx·Ny·Nt·8 bytes, so 256 × 256 × 256 is 134 MB.
+- **Speed-ups:**
+  - SciPy backend with all cores (`fft_backend="scipy"`, `workers=-1`, the default with `"auto"`).
+  - `record_every > 1`, or `near_field=False` (near-field diagnostics, i.e. of the collimated beam, use per-colour matrix transforms).
+  - Fewer `profile_wavelengths`.
+  - A smaller `cache_size` if memory is tight.
+- **Long runs:** use `run(max_seconds=…)` with `checkpoint` / `resume`.
+
+## Limitations
+
+**Not included**
+- **Ionisation and plasma:** fine for MPCs operated well below ionisation thresholds.
+- **Raman response:** relevant for N₂, air and other molecular gases.
+- **Off-axis geometry:** the real cell is folded, so the beam hits the mirrors at small angles. The resulting astigmatism and the actual spot pattern are not modelled; the unfolded on-axis picture is used.
+- **Non-uniform media:** gas plates, windows or pressure gradients are not built in. The nonlinear mode matching formula also assumes a uniformly filled cell with constant power during a pass.
+- **Vectorial effects:** the field is scalar, with a single polarisation.

thunder4d-0.9.0/README.md

@@ -0,0 +1,98 @@
+# thunder4D
+
+**T**ransverse-resolved **H**erriott-cell **U**PPE solver for **N**onlinear **D**ynamics close to **E**xperimental **R**eality, **4D**: a 4D (x, y, z, t) UPPE solver for multipass cells. Python package: `thunder4d`.
+
+Full documentation: `https://victorkolt.github.io/thunder4d/`.
+
+`thunder4D` simulates nonlinear pulse propagation in a gas-filled Herriott-type multipass cell (MPC) with full spatial and temporal resolution: the field is A(x, y, t) and it is propagated along z. It is built to study spatial and spatio-spectral effects that 1D or radially symmetric codes cannot capture:
+
+- spatial effects in non-Gaussian inputs (clipped, aberrated, high-order beams),
+- spatio-spectral homogeneity, radial chirp,
+- time-dependent nonlinear mode mismatch,
+- influence of space-time couplings (spatial chirp, pulse-front tilt, …) on the output.
+
+The code is pure Python. NumPy (≥ 2.0) is required. SciPy is optional but strongly recommended, because `scipy.fft` is about 8× faster than `numpy.fft` for the 2D transforms. Matplotlib is only needed for the examples. An NVIDIA GPU is optional: with CuPy installed (`pip install cupy-cuda12x`), `suggest_grid(..., device="auto")` (the default) runs the propagation on the GPU, and `device="cpu"` / `"gpu"` force one or the other. `thunder4d.gpu_available()` tells you whether CuPy works; `thunder4d.to_host(array)` converts a device array to NumPy. Everything returned by `thunder4d.diagnostics` is a NumPy array on either device.
+
+## Quick start
+
+```python
+import thunder4d as m
+from thunder4d import diagnostics as dg
+
+# medium and cell
+gas  = m.Material("Ar", pressure_bar=1.0)
+cell = m.MPC.herriott(R=0.5, N=20, k=3, branch="planar", medium=gas)  # 20 passes, 54 deg Gouy/pass, re-entrant
+
+# grid sized from the cell
+grid = m.suggest_grid(cell, lambda0=1030e-9, lambda_min=900e-9, lambda_max=1200e-9, pulse_fwhm=200e-15, box_factor=12)
+print(grid.describe())
+
+# 1) spectrum (+ phase)
+E = m.gaussian_spectrum(grid, fwhm_fs=200)
+E = m.add_spectral_phase(grid, E, gdd_fs2=0)
+
+# 2) nonlinear mode matching, computed from a probe pulse of the right energy
+probe = m.Pulse.at_focus(grid, E, m.Beam(m.gaussian(1e-3)), 1.2e-3)
+mm = cell.match(probe)
+
+# 3) the actual input beam
+pulse = m.Pulse.at_focus(grid, E, m.Beam(m.gaussian(mm["w0"])), 1.2e-3)
+
+# 4) run
+sim = m.MPCSimulation(pulse, cell, phi_max=0.02, mode_reference=mm["w0"], profile_wavelengths=[1010e-9, 1030e-9, 1050e-9], profile_bandwidth=2e-9)
+sim.run()
+sim.save("run.npz")
+
+# 5) analyse the output
+x, lam, S = dg.spectrogram_x_lambda(grid, sim.Aw)
+c = dg.compress(grid, sim.Aw)
+print(c["fwhm_fs"], c["gdd_fs2"])
+```
+
+---
+
+## Physical model
+
+The field is a complex envelope A(x, y, t) with carrier exp[i(k₀z − ω₀t)], normalised so that |A|² is the intensity in W/m². It is propagated with the unidirectional pulse propagation equation (UPPE), written in the frame moving at the group velocity at λ₀:
+
+```
+∂A(kx, ky, Ω)/∂z = i [ kz(kx, ky, ω) − k₀ − k₁Ω ] A  +  i γ(Ω) FT_t[ |A|² A ]
+
+kz   = sqrt( k(ω)² − kx² − ky² )        (non-paraxial, full gas dispersion)
+k(ω) = n(ω) ω / c,   ω = ω₀ + Ω,   k₁ = dk/dω at ω₀
+γ(Ω) = n₂ ω/c · n(ω₀)/n(ω)               (self-steepening included)
+```
+
+- **Linear operator:** it is exact. It includes diffraction without the paraxial approximation, gas dispersion to all orders, and evanescent components, which decay.
+- **Kerr term:** it is the instantaneous electronic response. Its frequency dependence gives self-steepening. With `self_steepening=False` it becomes γ = n₂ω₀/c.
+- **Edge taper:** the nonlinear source is tapered to zero at the edges of the spectral window to avoid aliasing.
+
+## Numerical scheme
+
+- **Home domain:** the solver keeps the field in the mixed domain (x, y, Ω).
+  - The linear step needs only 2D spatial FFTs, because Ω is already a coordinate.
+  - The Kerr term does not depend on (kx, ky), so it needs only 1D temporal FFTs.
+- **Splitting:** symmetric Strang splitting (linear half-step, nonlinear step, linear half-step). Consecutive linear half-steps are merged.
+- **Nonlinear step:** fourth-order Runge–Kutta.
+- **Adaptive step size:** h = φ_max / (k₀ n₂ I_peak), where φ_max is the peak nonlinear phase allowed per step. It is limited to `dz_max` (default d/8, a quarter of a half-pass) and quantised to `dz_max · 2^(−n/4)`. The quantisation lets the linear propagators exp(iDh) be reused from a small cache.
+
+## Performance and memory
+
+- **Cost per step:** 2 spatial 2D FFTs, 8 temporal 1D FFTs (RK4) and a few array operations. With SciPy on one core, a 150 × 150 × 135 grid takes about 0.1–0.4 s per step. A 20-pass run at B ≈ 16 rad needs about 900 steps.
+- **Steps per pass:** they scale with the B-integral per pass divided by `phi_max`.
+- **Memory:** about 8–10 field arrays: the field, RK4 buffers, the linear operator `D`, up to `cache_size` cached propagators and the cached mirror transfer. One complex64 array is Nx·Ny·Nt·8 bytes, so 256 × 256 × 256 is 134 MB.
+- **Speed-ups:**
+  - SciPy backend with all cores (`fft_backend="scipy"`, `workers=-1`, the default with `"auto"`).
+  - `record_every > 1`, or `near_field=False` (near-field diagnostics, i.e. of the collimated beam, use per-colour matrix transforms).
+  - Fewer `profile_wavelengths`.
+  - A smaller `cache_size` if memory is tight.
+- **Long runs:** use `run(max_seconds=…)` with `checkpoint` / `resume`.
+
+## Limitations
+
+**Not included**
+- **Ionisation and plasma:** fine for MPCs operated well below ionisation thresholds.
+- **Raman response:** relevant for N₂, air and other molecular gases.
+- **Off-axis geometry:** the real cell is folded, so the beam hits the mirrors at small angles. The resulting astigmatism and the actual spot pattern are not modelled; the unfolded on-axis picture is used.
+- **Non-uniform media:** gas plates, windows or pressure gradients are not built in. The nonlinear mode matching formula also assumes a uniformly filled cell with constant power during a pass.
+- **Vectorial effects:** the field is scalar, with a single polarisation.

thunder4d-0.9.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "thunder4d"
+license = "MIT"
+license-files = ["LICENSE"]
+dynamic = ["version"]
+description = "thunder4d: Transverse-resolved Herriott-cell UPPE solver for Nonlinear Dynamics close to Experimental Reality, 4D"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Victor Koltalo", email = "victor.koltalo@ensta.fr" }]
+keywords = ["UPPE", "multipass cell", "MPC", "nonlinear optics", "ultrafast", "post-compression",
+            "Herriott cell", "spatio-temporal", "pulse propagation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "numpy>=2.0",
+    "scipy>=1.10",
+]
+
+[project.optional-dependencies]
+examples = ["matplotlib"]
+gpu = ["cupy-cuda12x"]
+docs = ["sphinx>=7", "sphinx_rtd_theme>=2"]
+
+[project.urls]
+Documentation = "https://victorkolt.github.io/thunder4D/"
+Source = "https://github.com/victorkolt/thunder4D"
+
+[tool.setuptools]
+packages = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "src.__version__" }

thunder4d-0.9.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

thunder4d-0.9.0/src/__init__.py

@@ -0,0 +1,16 @@
+"""THUNDER4D - Transverse-resolved Herriott-cell UPPE solver for Nonlinear Dynamics close to Experimental Reality, 4D.
+
+4D (x, y, z, t) UPPE simulation of multipass cells.
+"""
+__version__ = "0.9.0"
+from .backend import gpu_available, to_host
+from .grid import Grid, suggest_grid, C0
+from .materials import Material
+from .pulse import (Pulse, Beam, gaussian, super_gaussian, top_hat, knife_edge, measured_profile,
+                    hermite_gauss, laguerre_gauss, mode_superposition,
+                    gaussian_spectrum, measured_spectrum, spectrum_from_temporal_field,
+                    add_spectral_phase, zernike_wavefront)
+from .cell import MPC
+from .solver import UPPESolver
+from .simulation import MPCSimulation
+from . import diagnostics

thunder4d-0.9.0/src/backend.py

@@ -0,0 +1,64 @@
+"""Array backend: NumPy on the CPU, CuPy on an NVIDIA GPU.
+
+Only the heavy arrays live on the device: the field A(x, y, Om), the propagators, the absorbers and
+the mirror transfer function. Axes (grid.x, grid.lam, ...) and everything returned by
+`thunder4d.diagnostics` are always NumPy arrays; `to_host` converts a device array.
+"""
+import numpy as np
+
+_GPU_OK = None
+
+
+def gpu_available():
+    """True if CuPy is installed and a working CUDA device can run a kernel and an FFT."""
+    global _GPU_OK
+    if _GPU_OK is None:
+        try:
+            import cupy as cp
+            import cupyx.scipy.fft as cfft
+            if cp.cuda.runtime.getDeviceCount() < 1:
+                raise RuntimeError("no CUDA device")
+            a = cp.ones((8, 8), cp.complex64)
+            cfft.fft2(a, axes=(0, 1))
+            float(cp.sum(cp.abs(a) ** 2))       # compiles a kernel: fails on unsupported GPUs
+            _GPU_OK = True
+        except Exception:
+            _GPU_OK = False
+    return _GPU_OK
+
+
+def resolve_device(device="auto"):
+    """'auto' -> 'gpu' if CuPy works else 'cpu'; 'cpu' / 'gpu' are forced."""
+    device = "cpu" if device is None else str(device).lower()
+    if device == "auto":
+        return "gpu" if gpu_available() else "cpu"
+    if device == "cpu":
+        return "cpu"
+    if device in ("gpu", "cuda"):
+        if not gpu_available():
+            raise RuntimeError("device='gpu' requested but CuPy with a working CUDA device was not "
+                               "found (pip install cupy-cuda12x); use device='auto' or 'cpu'")
+        return "gpu"
+    raise ValueError("device must be 'auto', 'cpu' or 'gpu'")
+
+
+def get_xp(device):
+    """Array module for a resolved device name."""
+    if device == "gpu":
+        import cupy
+        return cupy
+    return np
+
+
+def is_device_array(a):
+    return type(a).__module__.split(".")[0] == "cupy"
+
+
+def xp_of(a):
+    """Array module that owns `a` (numpy for anything that is not a CuPy array)."""
+    return get_xp("gpu") if is_device_array(a) else np
+
+
+def to_host(a):
+    """NumPy view/copy of an array that may live on the GPU (no copy for NumPy input)."""
+    return a.get() if is_device_array(a) else np.asarray(a)

thunder4d-0.9.0/src/cell.py

@@ -0,0 +1,142 @@
+"""Module 2: the multipass cell.
+
+Unfolded picture used by the solver: one pass = cell centre -> d/2 -> curved mirror -> d/2 -> cell
+centre. The field is recorded at the cell centre (waist plane of the eigenmode, flat phase) after
+every pass, which is where the modal decomposition on the cell eigenmodes is exact.
+
+Nonlinear mode matching (aberration-free Kerr lens, uniform medium, power P constant along a pass):
+the envelope equation of a gaussian becomes the linear one with lambda -> lambda sqrt(1 - P/Pc),
+Pc = lambda^2/(2 pi n0 n2). Hence the matched waist and mirror spot are the linear ones scaled by
+(1 - P/Pc)^(1/4), and the B-integral per pass (on axis, peak) is
+    B = 8 pi n2 P / (lambda lambda_eff) * atan(d / 2 zR')      (-> 2 theta P/Pc for P << Pc).
+A pulse can only be matched at one power: the wings of the pulse see the linear mode. This
+time-dependent mismatch is precisely one of the couplings the 4D code resolves.
+"""
+import numpy as np
+from .grid import C0
+
+FS = 1e-15
+
+
+class MPC:
+    """Symmetric two-mirror cell.
+
+    R            : mirror radius of curvature [m]
+    d            : mirror separation [m]
+    medium       : Material
+    n_passes     : number of passes (centre -> mirror -> centre = 1 pass = 1 bounce)
+    mirror_gdd_fs2, mirror_tod_fs3 : dispersion per bounce
+    mirror_reflectivity : scalar, or callable R(lambda[m]) (intensity)
+    mirror_phase : optional callable phi(lambda[m]) [rad] per bounce (measured GDD curves, ...)
+    mirror_diameter : clear aperture [m] (soft super-gaussian edge), None = infinite
+    """
+
+    def __init__(self, R, d, medium, n_passes, *, mirror_gdd_fs2=0.0, mirror_tod_fs3=0.0,
+                 mirror_reflectivity=1.0, mirror_phase=None, mirror_diameter=None):
+        if not 0 < d < 2 * R:
+            raise ValueError("unstable cell: need 0 < d < 2R")
+        self.R, self.d, self.medium, self.n_passes = float(R), float(d), medium, int(n_passes)
+        self.gdd, self.tod = mirror_gdd_fs2, mirror_tod_fs3
+        self.refl, self.mphase = mirror_reflectivity, mirror_phase
+        self.diameter = mirror_diameter
+        self.g = 1 - d / R
+        self.theta = np.arccos(self.g)  # Gouy phase per pass
+        self._bounce_cache = None
+
+    @classmethod
+    def herriott(cls, R, N, k, medium, branch="concentric", n_passes=None, **kw):
+        """Re-entrant Herriott cell: N passes (twice the spots per mirror), d = R (1 +- cos(2*pi k/N)).
+        N must be even for the concentric branch. Default n_passes = N (one full re-entrant cycle);
+        pass n_passes to simulate any other number of passes in the same cell."""
+        value = np.cos(2 * np.pi * k / N)
+        if branch == "concentric":
+            if N % 2:
+                raise ValueError(
+                    f"N = {N} is odd: the concentric branch is only re-entrant for even N. N is the "
+                    f"number of passes of one re-entrant cycle (e.g. N = {2 * N}, k = {2 * k}); "
+                    f"to simulate a different number of passes, set n_passes separately.")
+            d = R * (1+ value)
+        elif branch == "planar":
+            d = R * (1 - value)
+        else:
+            raise ValueError(f"unknown branch {branch!r}: use 'concentric' or 'planar'")
+        return cls(R, d, medium, n_passes or N, **kw)
+
+    # ------------------------------------------------------------ modes
+    def linear_mode(self, lam):
+        n0 = self.medium.n(2 * np.pi * C0 / lam)
+        lm = lam / n0
+        w0 = np.sqrt(lm / (2 * np.pi) * np.sqrt(self.d * (2 * self.R - self.d)))
+        wm = np.sqrt(lm * self.R / np.pi * np.sqrt(self.d / (2 * self.R - self.d)))
+        return {"w0": w0, "w_mirror": wm, "zR": np.pi * w0 ** 2 / lm, "gouy_per_pass": self.theta}
+
+    def nonlinear_mode(self, P, lam=None, verbose=False):
+        """Kerr-lens matched eigenmode for power P [W]."""
+        lam = lam or self._lam0
+        Pc = self.medium.critical_power(lam)
+        r = P / Pc
+        if r >= 1:
+            raise ValueError(f"P/Pc = {r:.2f} >= 1: no matched mode (self-focusing)")
+        lin = self.linear_mode(lam)
+        s = (1 - r) ** 0.25
+        w0, wm = lin["w0"] * s, lin["w_mirror"] * s
+        lam_eff = lam * np.sqrt(1 - r)
+        zRp = np.pi * w0 ** 2 / lam_eff
+        B = 8 * np.pi * self.medium.n2 * P / (lam * lam_eff) * np.arctan(self.d / (2 * zRp))
+        out = {"P": P, "Pc": Pc, "P_over_Pc": r, "w0": w0, "w_mirror": wm,
+               "w0_linear": lin["w0"], "w_mirror_linear": lin["w_mirror"], "B_per_pass": B,
+               "B_total": B * self.n_passes,
+               "I_peak_center_W_cm2": 2 * P / (np.pi * w0 ** 2) * 1e-4}
+        if verbose:
+            print(self.report(out))
+        return out
+
+    def match(self, pulse, power="peak", verbose=True):
+        """Nonlinear mode matching from a Pulse (or a power in W). power: 'peak' | 'weighted'."""
+        self._lam0 = pulse.grid.lambda0 if hasattr(pulse, "grid") else self._lam0
+        if hasattr(pulse, "grid"):
+            P = pulse.peak_power() if power == "peak" else pulse.weighted_power()
+        else:
+            P = float(pulse)
+        return self.nonlinear_mode(P, self._lam0, verbose=verbose)
+
+    _lam0 = 1030e-9
+
+    def report(self, m=None):
+        s = (f"MPC: R = {self.R:.3f} m, d = {self.d:.4f} m, {self.n_passes} passes, "
+             f"Gouy/pass = {np.degrees(self.theta):.2f} deg, {self.medium}")
+        if m:
+            s += (f"\n  P = {m['P']/1e9:.3g} GW, Pc = {m['Pc']/1e9:.3g} GW, P/Pc = {m['P_over_Pc']:.3f}"
+                  f"\n  waist  {m['w0_linear']*1e6:.0f} um (linear) -> {m['w0']*1e6:.0f} um (matched)"
+                  f"\n  mirror {m['w_mirror_linear']*1e6:.0f} um (linear) -> {m['w_mirror']*1e6:.0f} um (matched)"
+                  f"\n  B/pass ~ {m['B_per_pass']:.3f} rad, total ~ {m['B_total']:.2f} rad, "
+                  f"I_peak(centre) ~ {m['I_peak_center_W_cm2']:.3g} W/cm^2")
+        return s
+
+    # ------------------------------------------------------------ mirror
+    def bounce_factor(self, grid):
+        """Complex transfer of one mirror in (x, y, Om) (cached)."""
+        if self._bounce_cache is not None and self._bounce_cache[0] is grid:
+            return self._bounce_cache[1]
+        W = grid.Omega * FS
+        spec = np.exp(1j * (self.gdd / 2 * W ** 2 + self.tod / 6 * W ** 3)).astype(complex)
+        lam = grid.lam
+        if callable(self.refl):
+            spec *= np.sqrt(np.clip(self.refl(np.where(grid.valid, lam, 1.0)), 0, 1))
+        else:
+            spec *= np.sqrt(self.refl)
+        if self.mphase is not None:
+            spec *= np.exp(1j * self.mphase(np.where(grid.valid, lam, 1.0)))
+        spec *= grid.valid
+        F = np.exp(-1j * (grid.r2[:, :, None] * (grid.omega / C0 / self.R)[None, None, :]))
+        F *= spec[None, None, :]
+        if self.diameter is not None:
+            ap = np.exp(-(np.sqrt(grid.r2) / (self.diameter / 2)) ** 30)
+            F *= ap[:, :, None]
+        F = grid.asarray(F.astype(grid.dtype))     # built on the host, stored on the grid's device
+        self._bounce_cache = (grid, F)
+        return F
+
+    def bounce(self, Aw, grid):
+        Aw *= self.bounce_factor(grid)
+        return Aw