diff --git a/benchmarks/__main__.py b/benchmarks/__main__.py
index ca53439a8..d2267b8c7 100644
--- a/benchmarks/__main__.py
+++ b/benchmarks/__main__.py
@@ -67,6 +67,8 @@ def main(argv: list[str] | None = None) -> int:
args.threads,
args.production or physical_cores(),
backend=args.backend,
+ noise=args.noise,
+ fft_size=args.fft_size,
)
show_plan(rows, skipped, args.repeats)
return 0
diff --git a/benchmarks/ab.py b/benchmarks/ab.py
index aa1a1b8e9..f56eb2c02 100644
--- a/benchmarks/ab.py
+++ b/benchmarks/ab.py
@@ -33,12 +33,13 @@
receipt,
)
from benchmarks.system import eligible_cpus, guard, physical_cores, thread_environment
-from benchmarks.track import selection_options, steppers
+from benchmarks.track import BACKENDS, selection_options, steppers
__all__ = [
"ARMS",
"ab",
"ab_options",
+ "arm_configuration",
"arm_order",
"field_difference",
"show_summary",
@@ -66,6 +67,25 @@ def ab_options(parser: argparse.ArgumentParser) -> None:
"--timeout", type=float, default=3600.0, help="per-worker limit, seconds"
)
parser.add_argument("--json", action="store_true")
+ parser.add_argument(
+ "--baseline-backend",
+ choices=BACKENDS,
+ help="the baseline arm's backend; default: --backend",
+ )
+ parser.add_argument(
+ "--candidate-backend",
+ choices=BACKENDS,
+ help="the candidate arm's backend; default: --backend",
+ )
+
+
+def arm_configuration(configuration: Record, backend: str) -> Record:
+ """Return one arm's configuration: its backend and that backend's precision."""
+ return {
+ **configuration,
+ "backend": backend,
+ "precision": "single" if backend == "mlx" else "double",
+ }
def arm_order(round_index: int) -> tuple[str, ...]:
@@ -184,14 +204,21 @@ def ab(args: argparse.Namespace) -> int:
if args.rounds < 1 or args.repeats < 1 or args.timeout <= 0:
raise SuiteError("rounds, repeats and timeout must be positive")
started = time.perf_counter()
+ backends = {
+ "baseline": args.baseline_backend or args.backend,
+ "candidate": args.candidate_backend or args.backend,
+ }
rows, skipped = plan_rows(
select(tuple(args.case), tuple(args.set), all_cases=args.all),
steppers(args.stepper),
args.threads,
args.production or physical_cores(),
- backend=args.backend,
+ # A configuration either arm cannot run is left out for both.
+ backend="mlx" if "mlx" in backends.values() else args.backend,
fraction=args.length,
device=args.device,
+ noise=args.noise,
+ fft_size=args.fft_size,
)
for reason in skipped:
print(f"skipped {reason}")
@@ -211,6 +238,7 @@ def ab(args: argparse.Namespace) -> int:
"created": now(),
"purpose": "exploratory A/B",
"pythons": pythons,
+ "backends": backends,
"rounds": args.rounds,
"repeats": args.repeats,
"length": args.length,
@@ -236,7 +264,9 @@ def ab(args: argparse.Namespace) -> int:
events, elapsed = launch_worker(
pythons[arm],
{
- "configuration": row["configuration"],
+ "configuration": arm_configuration(
+ row["configuration"], backends[arm]
+ ),
"repeats": args.repeats,
"fields": str(
(output / "fields" / arm / f"{row['id']}.npy").resolve()
@@ -282,7 +312,10 @@ def ab(args: argparse.Namespace) -> int:
print(canonical(summary))
else:
show_summary(summary)
- same = pythons["baseline"] == pythons["candidate"]
+ same = (
+ pythons["baseline"] == pythons["candidate"]
+ and backends["baseline"] == backends["candidate"]
+ )
print(
("A/A control: the same interpreter for both arms. " if same else "")
+ (f"Results: {output.resolve()} ({time.perf_counter() - started:.0f} s)")
diff --git a/benchmarks/builders.py b/benchmarks/builders.py
index 2b8134a53..8c8575856 100644
--- a/benchmarks/builders.py
+++ b/benchmarks/builders.py
@@ -46,7 +46,58 @@ def integrator(stepper: str) -> Multistep | RungeKutta | None:
}[stepper]
-def capillary(name: str) -> Simulation:
+def variant(configuration: Record) -> Record:
+ """Return the keywords that turn a case into its backend, precision, noise and grid.
+
+ ``precision`` is ``"single"`` on ``mlx`` and ``"double"`` elsewhere unless the
+ configuration names it. A single-precision run, or one asked for ``noise="none"``,
+ is noiseless: no seed and no noise model, so that a cross-backend A/B compares
+ one workload. ``fft_size="pow2"`` rebuilds the case's time grid at the next power
+ of two; the transverse grids are kept, as their sizes set the physics.
+ """
+ precision = configuration.get("precision") or (
+ "single" if configuration["backend"] == "mlx" else "double"
+ )
+ noiseless = precision == "single" or configuration.get("noise") == "none"
+ fft_size = configuration.get("fft_size") or "case"
+ if fft_size not in ("case", "pow2"):
+ raise SuiteError(f"unknown fft_size {fft_size}")
+ return {
+ "precision": precision,
+ "noiseless": noiseless,
+ "fft_size": fft_size,
+ "backend": configuration["backend"],
+ }
+
+
+def _launch(options: Record) -> dict[str, Any]:
+ """Return the noise and seed keywords of a noisy case under `options`."""
+ if options["noiseless"]:
+ return {"noise": None, "seed": None}
+ return {"seed": SEED}
+
+
+def _limits(
+ options: Record,
+ length: float,
+ wavelength: float,
+ limits: tuple[float, float],
+ trange: float,
+ *,
+ envelope: bool = False,
+) -> dict[str, Any]:
+ """Return the grid keywords: the interface's own, or a power-of-two grid."""
+ if options["fft_size"] == "case":
+ return {"wavelength_limits": limits, "trange": trange}
+ from solprop.grid import EnvelopeGrid, FieldGrid # noqa: PLC0415
+
+ kind = EnvelopeGrid if envelope else FieldGrid
+ return {
+ "grid": kind.from_limits(length, wavelength, limits, trange, fft_size="pow2")
+ }
+
+
+def capillary(name: str, options: Record | None = None) -> Simulation:
"""Build a capillary case on its resolved or mode-averaged route.
A ``_averaged`` case asks the interface for ``mode_average=True``, as a user
@@ -55,6 +106,8 @@ def capillary(name: str) -> Simulation:
"""
from solprop.driver import Simulation # noqa: PLC0415 - worker-only imports
+ options = options or variant({"backend": "native"})
+
averaged = name.endswith("_averaged")
if name.startswith("rdw") or name == "he_rdw_averaged":
return Simulation.from_capillary(
@@ -63,13 +116,14 @@ def capillary(name: str) -> Simulation:
"He",
(0.8, 0.0),
wavelength=800e-9,
- wavelength_limits=(90e-9, 4e-6),
- trange=400e-15,
fwhm=7.5e-15,
energy=275e-6,
modes=4 if name == "rdw" else 1,
mode_average=averaged,
- seed=SEED,
+ precision=options["precision"],
+ backend=options["backend"],
+ **_limits(options, 1.5, 800e-9, (90e-9, 4e-6), 400e-15),
+ **_launch(options),
)
if name == "ctc":
return Simulation.from_capillary(
@@ -78,13 +132,14 @@ def capillary(name: str) -> Simulation:
"H2",
40.0,
wavelength=515e-9,
- wavelength_limits=(220e-9, 4e-6),
- trange=2e-12,
fwhm=400e-15,
energy=10e-6,
modes=3,
loss=0.0,
- seed=SEED,
+ precision=options["precision"],
+ backend=options["backend"],
+ **_limits(options, 0.13, 515e-9, (220e-9, 4e-6), 2e-12),
+ **_launch(options),
)
if name in ("ctc_reduced", "ctc_reduced_two_mode"):
# The reduced case of the comb-to-continuum tests: the fundamental alone on a
@@ -96,14 +151,15 @@ def capillary(name: str) -> Simulation:
"H2",
40.0,
wavelength=515e-9,
- wavelength_limits=(250e-9, 2e-6),
- trange=2e-12,
fwhm=400e-15,
energy=10e-6,
modes=1 if name == "ctc_reduced" else 2,
raman=True,
temperature=294.0,
- seed=SEED,
+ precision=options["precision"],
+ backend=options["backend"],
+ **_limits(options, 0.1, 515e-9, (250e-9, 2e-6), 2e-12),
+ **_launch(options),
)
if name.startswith("argon_blueshift"):
return Simulation.from_capillary(
@@ -115,12 +171,20 @@ def capillary(name: str) -> Simulation:
fwhm=30e-15,
energy=3e-6,
loss=False,
- trange=400e-15,
- wavelength_limits=(160e-9, 4e-6),
modes=1,
envelope=name == "argon_blueshift_envelope",
mode_average=averaged,
- seed=SEED,
+ precision=options["precision"],
+ backend=options["backend"],
+ **_limits(
+ options,
+ 0.2,
+ 800e-9,
+ (160e-9, 4e-6),
+ 400e-15,
+ envelope=name == "argon_blueshift_envelope",
+ ),
+ **_launch(options),
)
if name == "h2_raman_averaged":
return Simulation.from_capillary(
@@ -133,11 +197,12 @@ def capillary(name: str) -> Simulation:
energy=3e-6,
loss=False,
plasma=False,
- trange=800e-15,
- wavelength_limits=(200e-9, 4e-6),
modes=1,
mode_average=True,
- seed=SEED,
+ precision=options["precision"],
+ backend=options["backend"],
+ **_limits(options, 0.4, 1030e-9, (200e-9, 4e-6), 800e-15),
+ **_launch(options),
)
if name in ("h2_raman_6ps", "h2_raman_6ps_averaged"):
return Simulation.from_capillary(
@@ -151,16 +216,17 @@ def capillary(name: str) -> Simulation:
loss=False,
plasma=False,
raman=True,
- trange=6e-12,
- wavelength_limits=(400e-9, 4e-6),
modes=1,
mode_average=averaged,
- seed=SEED,
+ precision=options["precision"],
+ backend=options["backend"],
+ **_limits(options, 2.0, 1030e-9, (400e-9, 4e-6), 6e-12),
+ **_launch(options),
)
raise SuiteError(f"capillary builder not implemented for {name}")
-def gnlse(name: str) -> Simulation:
+def gnlse(name: str, options: Record | None = None) -> Simulation:
"""Extract the ideal soliton and the SEP 13 Raman/shock envelope inputs.
Higher dispersion coefficients and the Raman/shock launch follow Dudley,
@@ -172,6 +238,7 @@ def gnlse(name: str) -> Simulation:
from solprop.driver import Simulation # noqa: PLC0415
+ options = options or variant({"backend": "native"})
if name == "gnlse_soliton":
beta2, gamma, width = -11.83e-27, 0.11, 100e-15
return Simulation.from_gnlse(
@@ -179,8 +246,6 @@ def gnlse(name: str) -> Simulation:
math.pi / 2 * width**2 / abs(beta2),
[0.0, 0.0, beta2],
wavelength=835e-9,
- wavelength_limits=(500e-9, 2e-6),
- trange=4e-12,
width=width,
peak_power=3**2 * abs(beta2) / (gamma * width**2),
shape="sech",
@@ -190,6 +255,16 @@ def gnlse(name: str) -> Simulation:
# and a seed would make it a different workload (SEP 37 measured 65 times
# the steps with one).
noise=None,
+ precision=options["precision"],
+ backend=options["backend"],
+ **_limits(
+ options,
+ math.pi / 2 * width**2 / abs(beta2),
+ 835e-9,
+ (500e-9, 2e-6),
+ 4e-12,
+ envelope=True,
+ ),
)
if name == "gnlse_raman_shock":
return Simulation.from_gnlse(
@@ -209,21 +284,22 @@ def gnlse(name: str) -> Simulation:
-1.7140e-144,
],
wavelength=835e-9,
- wavelength_limits=(400e-9, 2e-6),
- trange=12.5e-12,
# 50 fs FWHM, T0 = 28.4 fs (Dudley, Genty and Coen, section III).
fwhm=50e-15,
shape="sech",
peak_power=10e3,
raman=True,
shock=True,
- seed=SEED,
+ precision=options["precision"],
+ backend=options["backend"],
+ **_limits(options, 0.15, 835e-9, (400e-9, 2e-6), 12.5e-12, envelope=True),
+ **_launch(options),
)
raise SuiteError(f"GNLSE builder not implemented for {name}")
def spatial_grids(
- name: str,
+ name: str, fft_size: str = "case", precision: str = "double"
) -> tuple[EnvelopeGrid | FieldGrid, FreeGrid | LineGrid | RadialGrid]:
"""Return a free-space case's time and transverse grids, without its launch.
@@ -253,7 +329,7 @@ def spatial_grids(
(143e-9, 600e-9),
window,
thg=False,
- fft_size="smooth",
+ fft_size="pow2" if fft_size == "pow2" else "smooth",
)
return grid, FreeGrid(
half_width * 1.1, size, half_width * 1.1, size, collar_fraction=0.0
@@ -264,6 +340,9 @@ def spatial_grids(
800e-9,
(350e-9, 2e-6) if plasma else (500e-9, 1.6e-6),
250e-15,
+ fft_size="pow2" if fft_size == "pow2" else "auto",
+ # As the keyword interfaces choose for a run on mlx (single precision).
+ transforms="mlx" if precision == "single" else "fftw",
)
if name == "spatial_absorber":
# SEP 40: the aperture of three waists with 2.6 radii of room outside it, for
@@ -280,7 +359,7 @@ def spatial_grids(
raise SuiteError(f"spatial builder not implemented for {name}")
-def kerr(name: str, settings: SimulationSettings) -> Simulation:
+def kerr(name: str, settings: SimulationSettings, fft_size: str = "case") -> Simulation:
"""Build SEP 28's full Cartesian envelope beam and material.
The Sellmeier coefficients are inherited from the SEP 28 builder, citing
@@ -295,7 +374,7 @@ def kerr(name: str, settings: SimulationSettings) -> Simulation:
from solprop.pulses import GaussianPulse, SpatialPulse # noqa: PLC0415
from solprop.spatial import SpatialMedium # noqa: PLC0415
- grid, space = spatial_grids(name)
+ grid, space = spatial_grids(name, fft_size)
assert isinstance(space, FreeGrid)
glass = SellmeierGlass(
name="malitson",
@@ -317,7 +396,9 @@ def kerr(name: str, settings: SimulationSettings) -> Simulation:
)
-def spatial(name: str, settings: SimulationSettings) -> Simulation:
+def spatial(
+ name: str, settings: SimulationSettings, options: Record | None = None
+) -> Simulation:
"""Extract the SEP 16 filament with its original physical resolution."""
import math # noqa: PLC0415
@@ -335,9 +416,10 @@ def spatial(name: str, settings: SimulationSettings) -> Simulation:
from solprop.pulses import GaussianPulse, SpatialPulse # noqa: PLC0415
from solprop.spatial import SpatialMedium, critical_power # noqa: PLC0415
+ options = options or variant({"backend": "native"})
if name == "planar":
return _planar(settings)
- grid, space = spatial_grids(name)
+ grid, space = spatial_grids(name, options["fft_size"], options["precision"])
plasma = "filament" in name
medium = SpatialMedium("Ar", 1.0)
chi3 = gamma3("Ar", wavelength=800e-9)
@@ -364,7 +446,7 @@ def spatial(name: str, settings: SimulationSettings) -> Simulation:
settings = dataclasses.replace(settings, spatial_absorber=SpatialAbsorber())
if isinstance(space, RadialGrid):
return Simulation.from_radial(
- grid, space, medium, responses, pulse, settings=settings, seed=SEED
+ grid, space, medium, responses, pulse, settings=settings, **_launch(options)
)
return Simulation.from_free(
grid, space, medium, responses, pulse, settings=settings
@@ -445,8 +527,10 @@ def build(configuration: Record) -> Simulation:
"field_planes": (len(itinerary),) if fields == "planes" else (),
}
chosen = integrator(configuration["stepper"])
+ options = variant(configuration)
if case.builder in ("kerr", "spatial"):
settings = SimulationSettings(
+ precision=options["precision"],
save_planes=itinerary,
dz_max=case.length,
dz_init=case.length * 1e-4,
@@ -465,7 +549,9 @@ def build(configuration: Record) -> Simulation:
),
propagator_mode="tabulate",
)
- return (kerr if case.builder == "kerr" else spatial)(case.name, settings)
+ if case.builder == "kerr":
+ return kerr(case.name, settings, options["fft_size"])
+ return spatial(case.name, settings, options)
if case.builder == "exercise":
from benchmarks.exercises import exercise # noqa: PLC0415
@@ -488,9 +574,9 @@ def build(configuration: Record) -> Simulation:
)
return simulation
elif case.builder == "capillary":
- simulation = capillary(case.name)
+ simulation = capillary(case.name, options)
elif case.builder == "gnlse":
- simulation = gnlse(case.name)
+ simulation = gnlse(case.name, options)
elif case.builder == "smoke":
simulation = smoke()
else:
diff --git a/benchmarks/registry.py b/benchmarks/registry.py
index 73052d7f2..72a581887 100644
--- a/benchmarks/registry.py
+++ b/benchmarks/registry.py
@@ -115,7 +115,7 @@ def digest(self) -> str:
record.pop(key)
return identity(record)
- def configuration(
+ def configuration( # noqa: PLR0913 - the shared command-line selection
self,
stepper: str,
width: int,
@@ -124,11 +124,16 @@ def configuration(
warmup: float = 0.02,
*,
device: bool = False,
+ noise: str = "case",
+ fft_size: str = "case",
) -> Record:
"""Resolve one measurement without constructing a scientific object.
On a device build, `width` is the host's thread count and `device` says the
- native backend must run on the accelerator.
+ native backend must run on the accelerator. ``mlx`` runs in single precision,
+ every other backend in double; ``noise="none"`` drops the case's noise and
+ ``fft_size="pow2"`` rebuilds its time grid at a power of two
+ (``benchmarks.builders.variant``).
"""
if stepper not in self.steppers:
raise SuiteError(f"{self.name} admits only {', '.join(self.steppers)}")
@@ -141,6 +146,9 @@ def configuration(
"stepper": stepper,
"threads": width,
"backend": backend,
+ "precision": "single" if backend == "mlx" else "double",
+ "noise": noise,
+ "fft_size": fft_size,
"device": device,
"stop": self.length * fraction,
"fraction": fraction,
diff --git a/benchmarks/runner.py b/benchmarks/runner.py
index c2f9e6b77..c9e55809f 100644
--- a/benchmarks/runner.py
+++ b/benchmarks/runner.py
@@ -20,10 +20,12 @@
from benchmarks.system import POOL_VARIABLES, widths
__all__ = [
+ "MLX_BUILDERS",
"ROOT",
"estimate",
"freeze_harness",
"launch_worker",
+ "mlx_refusal",
"plan_rows",
"prepared_python",
"receipt",
@@ -68,6 +70,8 @@ def plan_rows( # noqa: PLR0913
backend: str = "native",
fraction: float = 1.0,
device: bool = False,
+ noise: str = "case",
+ fft_size: str = "case",
) -> tuple[list[Record], list[str]]:
"""Resolve configurations in run order; explain every one left out.
@@ -87,12 +91,21 @@ def plan_rows( # noqa: PLR0913
"schedule only"
)
continue
+ if backend == "mlx" and (refusal := mlx_refusal(case, stepper)):
+ skipped.append(f"{case.name} {stepper}: {refusal}")
+ continue
rows.append(
{
"id": f"{case.name}.{stepper}."
+ ("device" if device else f"t{width}"),
"configuration": case.configuration(
- stepper, width, backend, fraction, device=device
+ stepper,
+ width,
+ backend,
+ fraction,
+ device=device,
+ noise=noise,
+ fft_size=fft_size,
),
"cost": None if device else case.cost[0 if width == 1 else 1],
}
@@ -101,6 +114,24 @@ def plan_rows( # noqa: PLR0913
return rows, skipped
+MLX_BUILDERS = ("capillary", "gnlse", "kerr", "spatial")
+"""The builders whose cases ``mlx`` can run: its fibre, radial and Cartesian routes."""
+
+
+def mlx_refusal(case: Case, stepper: str) -> str | None:
+ """Say why ``mlx`` cannot run a configuration, or ``None`` when it can.
+
+ ``mlx`` admits what single precision admits (``translate.precision``) -- no planar
+ or general modal route, no TDSE or coupled flow -- and runs the Adams integrator in
+ its exponential formulation only.
+ """
+ if case.builder not in MLX_BUILDERS or case.name == "planar":
+ return "mlx runs the fibre, radial and Cartesian routes only"
+ if stepper == "multistep-interaction":
+ return "mlx runs the Adams integrator's exponential formulation only"
+ return None
+
+
def estimate(rows: list[Record], runs: int) -> float | None:
"""Estimate seconds for `runs` complete runs per row, or ``None`` if unknown."""
costs = [row["cost"] for row in rows]
diff --git a/benchmarks/track.py b/benchmarks/track.py
index 822c5fee6..a41a64721 100644
--- a/benchmarks/track.py
+++ b/benchmarks/track.py
@@ -36,10 +36,14 @@
thread_environment,
)
+BACKENDS = ("numpy_ref", "native", "mlx")
+"""The backends a benchmark can name; ``mlx`` only on an Apple GPU."""
+
REPEAT_TOLERANCE = 1e-9
"""The relative L2 difference two repeats' final fields may have: rounding only."""
__all__ = [
+ "BACKENDS",
"REPEAT_TOLERANCE",
"admissible",
"history_rows",
@@ -71,7 +75,24 @@ def selection_options(parser: argparse.ArgumentParser) -> None:
parser.add_argument(
"--production", type=int, help="production width; default: physical cores"
)
- parser.add_argument("--backend", choices=("numpy_ref", "native"), default="native")
+ parser.add_argument(
+ "--backend",
+ choices=BACKENDS,
+ default="native",
+ help="mlx runs in single precision, noiselessly; the others in double",
+ )
+ parser.add_argument(
+ "--noise",
+ choices=("case", "none"),
+ default="case",
+ help="none drops each case's noise, to match an mlx run's workload",
+ )
+ parser.add_argument(
+ "--fft-size",
+ choices=("case", "pow2"),
+ default="case",
+ help="pow2 rebuilds each case's time grid at a power of two",
+ )
parser.add_argument(
"--device",
action="store_true",
@@ -328,6 +349,8 @@ def track(args: argparse.Namespace) -> int:
production,
backend=args.backend,
device=args.device,
+ noise=args.noise,
+ fft_size=args.fft_size,
)
if not rows:
raise SuiteError("no configuration in the selection")
diff --git a/benchmarks/worker.py b/benchmarks/worker.py
index d422e2a54..d4eabf818 100644
--- a/benchmarks/worker.py
+++ b/benchmarks/worker.py
@@ -96,7 +96,7 @@ def runtime(backend: str, device: bool = False) -> Record:
import solprop # noqa: PLC0415
packages = {}
- for name in ("solprop", "numpy", "scipy", "optmat"):
+ for name in ("solprop", "numpy", "scipy", "optmat", "mlx"):
try:
packages[name] = importlib.metadata.version(name)
except importlib.metadata.PackageNotFoundError:
@@ -323,6 +323,7 @@ def measure(configuration: Record, repeats: int, fields: Path | None) -> Record:
"finite": bool(np.all(np.isfinite(final))),
"repeat_difference": difference,
"integrator": integrator_label(problem.stepper.integrator),
+ "precision": configuration.get("precision", "double"),
"rtol": controller.rtol,
"atol": controller.atol,
"noise": simulation.noise_resolution.resolved
diff --git a/changelog.d/342-single-precision-adams.added.md b/changelog.d/342-single-precision-adams.added.md
new file mode 100644
index 000000000..2418caf0e
--- /dev/null
+++ b/changelog.d/342-single-precision-adams.added.md
@@ -0,0 +1 @@
+`precision="single"` now admits the Adams integrator, `Multistep()` in its exponential formulation, on `numpy_ref` and on `mlx`, where its history stays on the GPU and each trial's flow, moments and compensation are formed there in double-float arithmetic. Binary32 Adams agrees with binary64 Adams to the method's own truncation on eight survival cases (the guide's single-precision page has the record), and on the capillaries it is closer to the binary64 result than binary32 Runge–Kutta is. A single-precision Adams history now resumes in binary32. A single-precision run now takes each interface's own default integrator, as a binary64 one does: `Multistep()` on `prop_capillary`, `prop_radial` and `prop_planar`, where it was `RungeKutta()`. (#342)
diff --git a/changelog.d/343-mlx-compiled-stages.changed.md b/changelog.d/343-mlx-compiled-stages.changed.md
new file mode 100644
index 000000000..74077509f
--- /dev/null
+++ b/changelog.d/343-mlx-compiled-stages.changed.md
@@ -0,0 +1 @@
+The `mlx` backend compiles each stage on the GPU with `mx.compile`, so a stage's element-wise passes run as a few fused kernels and its graph is not rebuilt in Python, and forms a stage's propagator and its inverse in one kernel. A trial takes 1.5 to 2.6 times less time on the capillary, radial and Cartesian routes, measured on an Apple M5 Max, and the results are bitwise unchanged. `SOLPROP_MLX_FUSED=0` evaluates operation by operation. (#343)
diff --git a/changelog.d/343-mlx-device-edge.changed.md b/changelog.d/343-mlx-device-edge.changed.md
new file mode 100644
index 000000000..344bf3471
--- /dev/null
+++ b/changelog.d/343-mlx-device-edge.changed.md
@@ -0,0 +1 @@
+On `mlx`, the transverse edge is read on the GPU where no collar is requested, rather than by copying the whole state to the host at every read, and a Cartesian run's operator is built in one pass and no longer forms an unused prefactor. On an Apple M5 Max the 384 x 384 x 750 Kerr beam takes 0.82 of `native`'s time, the 192 x 192 one 0.40. (#343)
diff --git a/changelog.d/343-mlx-device-statistics.changed.md b/changelog.d/343-mlx-device-statistics.changed.md
new file mode 100644
index 000000000..2b22115f0
--- /dev/null
+++ b/changelog.d/343-mlx-device-statistics.changed.md
@@ -0,0 +1 @@
+On `mlx`, a saved plane's field-grid plasma statistics (the ionised fractions and peak rates at every node) are now evaluated on the GPU with the propagation's own rate, scan and population kernels, as the envelope grid's already were, rather than on the host in binary64 from every node's field. On a 128 x 128 Cartesian argon filament the statistics of a plane took about 3 s and now take under 0.1 s; the values agree with the reference to about 1e-6 of their largest. (#343)
diff --git a/changelog.d/343-mlx-first-same-as-last.changed.md b/changelog.d/343-mlx-first-same-as-last.changed.md
new file mode 100644
index 000000000..6ddc9fc38
--- /dev/null
+++ b/changelog.d/343-mlx-first-same-as-last.changed.md
@@ -0,0 +1 @@
+The `mlx` backend's Runge–Kutta march now reuses the last stage of an accepted DOPRI5 step as the first stage of the next, as `native` does, so a step takes six evaluations of the nonlinear source instead of seven where the temporal collar is applied in the stages. The results are bitwise the same. (#343)
diff --git a/changelog.d/343-mlx-lab-frame-trial.fixed.md b/changelog.d/343-mlx-lab-frame-trial.fixed.md
new file mode 100644
index 000000000..6691a96f2
--- /dev/null
+++ b/changelog.d/343-mlx-lab-frame-trial.fixed.md
@@ -0,0 +1 @@
+An adaptive `RungeKutta()` run on `mlx` is no longer held to short steps by binary32's exponent range: a trial whose collar or loss would overflow the interaction picture's inverse propagator (`|Re dPhi|` past 88.7) is combined in the lab frame by forward flows instead, where it was rejected and shrunk before. A radial Kerr beam whose first trial reaches 459 now takes its millimetre in one step, as binary64 does, against 14 steps and 2 rejections. Runs within the range are unchanged. (#343)
diff --git a/changelog.d/343-single-forward-flows.fixed.md b/changelog.d/343-single-forward-flows.fixed.md
new file mode 100644
index 000000000..64cfb713d
--- /dev/null
+++ b/changelog.d/343-single-forward-flows.fixed.md
@@ -0,0 +1 @@
+A single-precision run with the low-storage march or the exponential Adams method is no longer refused when a step's damping exceeds binary32's exponent range: those methods apply forward flows only, which underflow harmlessly in a damped bin, so only growth is limited. The Cartesian Kerr beams' replayed 0.5 µm steps, refused before on their spectral collar, now run in binary32 and agree with binary64 to 2e-7. The check uses the operator's rate bounds on the free-space and radial routes instead of forming the operator over the grid (seconds at 384 x 384 x 750). (#343)
diff --git a/changelog.d/85-mlx-grid-sizes.changed.md b/changelog.d/85-mlx-grid-sizes.changed.md
new file mode 100644
index 000000000..f69ec9099
--- /dev/null
+++ b/changelog.d/85-mlx-grid-sizes.changed.md
@@ -0,0 +1 @@
+A single-precision `prop_capillary`, `prop_gnlse` or `prop_waveguide` run on `mlx` (or `backend="auto"`) now builds its grid for MLX's transforms: past 4096 samples a power of two, which MLX's GPU transforms run six to twelve times faster than the 2-3-5-smooth sizes FFTW prefers. The helium RDW capillary's grid is 16384 fine samples instead of 10240, and a trial took a quarter of the time. `FieldGrid.from_limits` and `EnvelopeGrid.from_limits` take `transforms="mlx"` for a grid of one's own, and `fft_cost` takes the library. Binary64 runs and single-precision runs on `numpy_ref` are unchanged. (#85)
diff --git a/changelog.d/85-single-free-space-tolerance.changed.md b/changelog.d/85-single-free-space-tolerance.changed.md
new file mode 100644
index 000000000..e3dee3563
--- /dev/null
+++ b/changelog.d/85-single-free-space-tolerance.changed.md
@@ -0,0 +1 @@
+A single-precision free-space run (`prop_free`, Cartesian and line) now takes free space's binary64 default tolerance, `rtol=1e-4`, instead of `1e-5`: binary32 at `1e-4` was measured as close to a tight binary64 reference as binary64 at `1e-4` on a radial filament, a radial beam with its transverse collar and a Cartesian filament. The Cartesian filament takes 48 steps instead of 61. (#85)
diff --git a/docs/dev/backends.md b/docs/dev/backends.md
index 7d4acc921..ec34977ac 100644
--- a/docs/dev/backends.md
+++ b/docs/dev/backends.md
@@ -180,7 +180,10 @@ its engines and the native backend's resident engine pass it down. `numpy_ref` t
`PLAIN`, the uncompiled Python forms, so the oracle never runs the compiled code it
checks; `native` takes its own
`NATIVE`, C++ transcriptions (`native/include/solprop_native/chebyshev.hpp` and
-`lagrange_basis.hpp`). Both perform the same operations in the same order under
+`lagrange_basis.hpp`); `mlx` takes `NATIVE` too, as its stage tables are host work.
+Only where the native package is absent -- it is a runtime dependency, so the
+documentation build and the `no-native` lane -- does `mlx` import with `PLAIN`, the
+same rows more slowly. Both perform the same operations in the same order under
strict arithmetic, so the rows a table keeps for its last positions are shared whichever
filled them. A record may add a third operation, an exponential Adams trial's
coefficient tables in one call (`Helpers.tables`, the composition of
@@ -467,8 +470,10 @@ lookup, the envelope-grid plasma's cycle moments and the statistics are evaluate
binary64 from the binary32 field, which is what the oracle defines. Its constructor, and
so `mlx`'s, applies the settings' own admission (`translate.precision.admit_precision`):
a problem that reaches `registry.select` without passing `SimulationSettings` is still
-refused the Adams integrator, outside the survival study's private switch, and an
-adaptive `rtol` below the floor. `native` refuses a single-precision
+refused an adaptive `rtol` below the floor. The Adams integrator is admitted (#342):
+binary32 Adams agrees with binary64 Adams to the method's own truncation on the survival
+cases, and a single-precision history resumes in binary32 (`HostHistory.load_rows`,
+`NumpySingleBackend._adams_restore`). `native` refuses a single-precision
problem by name.
**Selection.** `backends/registry.py`: `available()` detects with
@@ -492,7 +497,9 @@ A backend whose `StepDriver.reads_transverse_edge` is set hands the monitor's
`TransverseEdge` an `_EdgeReading` from `StepDriver._edge_reading` at the edge's reads, at saved planes, and with a
requested collar at every committed step. The reading is numbers and never the field: region sums, each
column's energy and any collar's strip and current. The default forms them with `_HostEdgeReduction` on a host copy,
-the reference, which `numpy_ref` and `mlx` use. `native` forms them on its own state against
+the reference, which `numpy_ref` uses, and `mlx` where a collar's strip or current is asked for. `mlx` otherwise forms the node and column
+energies on the device (`MlxBackend._edge_reading`: the Cartesian or line grid's transverse inverse transform, the radial synthesis in
+binary32), within a millionth of the state's energy of the host's, and reads those sums only. `native` forms them on its own state against
the edge's `_EdgeTables`, four regions' weights on the nodes, so it holds no face, mask or judgement, and a
field-free run crosses no state (`tests/backends/test_native_edge_reading.py`). A requested collar's lines are described
once, as `_edge_lines`, for both reductions (`tests/backends/test_native_edge_collar.py`): native takes each strip's padded
@@ -1646,8 +1653,9 @@ statistics from the widened state -- while the state and every per-step pass liv
device (`mlx_gpu/passes.py`, the oracle's passes in MLX). It admits the fibre, radial
and Cartesian (and line) routes with Runge–Kutta, the low-storage march (`MlxLowStorage`)
and lockstep batches (`MlxBatchRunner`, which builds every member's step before one
-evaluation, reached through `select_batch`; the `Batch` executor refuses `mlx`), with every response the oracle runs; a z table, Adams and interpolated
-planes are refused by name. The radial route is the fibre route's quadrature with the Hankel
+evaluation, reached through `select_batch`; the `Batch` executor refuses `mlx`), with every response the oracle runs, and the exponential Adams integrator
+(`MlxAdams`, below); a z table, the interaction formulation and interpolated planes are
+refused by name. The radial route is the fibre route's quadrature with the Hankel
matrices as its synthesis and projection, its plasma spectrum formed on the nodes and
projected once (`_device_radial_plasma`), and its absorber matrix applied in the stage.
The Cartesian route (`_device_free`) uploads its separable operator once, at unit
@@ -1659,19 +1667,95 @@ gated and edge currents, the envelope plasma's drive and loss -- are projected i
matrix product (`passes.project_many`), measured at 1.18 times faster on a one-mode
plasma capillary, where launches bound the stage, and neutral on larger ones.
+**Compiled stages.** On the Metal device each stage is one `mx.compile` graph
+(`MlxBackend._stage_core`), and so are a stage's input combination, the step's end and
+the norm's reductions: MLX fuses their element-wise passes into few kernels and replays
+the traced graph rather than rebuilding it in Python. A compiled function sees only its
+inputs, so everything that varies with position -- the taper and its inverse, Kerr's,
+Raman's and the plasma channels' factors, the populations' `1 - p` and `p` -- is formed on
+the host in binary64, rounded once as the eager stage rounded it, and passed as one float32
+vector (`_StageValues`); the prefactor, the Raman spectrum and the propagators are inputs
+too, and what the alarm reads comes back as outputs. MLX compiles each operation with the
+eager kernel's rounding (no contraction, no reassociation), so the compiled stage is
+bitwise the eager one on every route (`log1p` aside, an equally accurate but different
+function, which the GPU's rate kernel does not use); MLX's eager `x**2` rounds through
+`pow`, so the passes square by products. A stage's propagator and its inverse are one
+kernel (`DoubleFloatTerms.pair`), the inverse's phasor the conjugate of the forward's
+(bitwise the separate kernel's), formed once per distinct fraction of a trial.
+`SOLPROP_MLX_FUSED=0` evaluates op by op, for comparison.
+
+**First-same-as-last.** Under DOPRI5 `mlx` reuses an accepted step's last stage as the
+next step's first, as `native` does, and keeps a first stage across a rejection at the
+same anchor. Each stage returns its source before the inverse propagator; the last
+stage's input is the trial state itself, and the next first stage's propagators are
+exactly one, so the reused stage is bitwise the one a fresh evaluation would form (a
+test holds the march to that). It is taken only where the step's finish leaves the
+state as it is: not under the split-step collar, and dropped when the collar's quiet
+setting changes (`_collar_changed`) or the anchor moved by a landing. The oracle keeps
+every stage (`docs/dev/stepper.md` section 10, trap 10).
+
+**The lab-frame trial.** The interaction picture's stage input
+`exp(Phi_i) (a + h sum_j a_ij exp(-Phi_j) S_j)` forms the inverse `exp(-Phi_j)`, which
+overflows binary32 once a strong collar or loss puts `|Re Phi_j|` past 88.72; the
+controller then rejects the trial with an infinite norm and shrinks it far below what
+binary64 takes. When a bound on any `|Re Phi|` of the trial
+(`DoubleFloatTerms.real_reach`: the weighted sum of each term's largest `|Re T_t|`,
+stored at upload) passes nine tenths of `log FLT_MAX`, `MlxBackend._trial_graph`
+combines the stages in the lab frame instead: `exp(Phi_i) a + h sum_j a_ij
+exp(Phi_i - Phi_j) S_j` for each input and `exp(Phi) a + h sum_j b_j exp(Phi - Phi_j)
+S_j` at the end (`_transported_input`, `_transported_end`). The nodes never decrease,
+so every factor is a forward flow and a damped bin underflows harmlessly. It is the
+same method rearranged: forced on every trial it agrees with the interaction picture
+to a few binary32 units (5e-7 of the peak on the tests' soliton and capillary; 8e-7 to
+7e-6 over the RDW, filament and blueshift cases), but costs one double-float flow per
+distinct node difference -- 2.7 s against 0.22 s on a mode-averaged RDW, whose operator
+has 18 terms -- so it is taken only past the bound, and every other run is bitwise as
+before. The radial Kerr beam whose first trial reaches `|Re Phi| = 459` then takes its
+millimetre in one step as binary64 does, where the interaction picture is rejected
+twice and needs 14. Only the Metal device takes it; the CPU device stays the oracle's
+form. The stages it forms are untransported sources, so first-same-as-last holds
+across the two forms.
+
+**Adams** (`mlx_gpu/adams.py`, #342). `MlxBackend._adams_engine` returns `MlxAdams`, an
+`AdamsEngine` whose history -- the untransported source rows and, for a varying
+operator, each sample's state -- stays on the device; the march keeps the controller.
+A trial makes one source evaluation and one synchronisation, which reads the defects'
+scaled sums, the anchor's, the trial state's finiteness and the envelope plasma's
+failures. Its flow and moments come from one double-float kernel
+(`DoubleFloatTerms.trial`): the step's exponent combined from the operator's terms,
+`exp(x)` with its phase reduced by whole turns of a double-float `2 pi`, and
+`k! phi_{k+1}(x)` by the reference's far recurrence beyond its join and its scaled
+series and doubling within it, each rounded once -- within one binary32 ulp of the
+binary64 forms rounded, as SEP 33 rounds every propagator. The same pass forms the
+transported compensation's factors (SEP 16 section 4.2), `exp(s_j x)(D(z_j) - x/h)`
+with the rates differenced in their weights over the terms in binary64
+(`linop.rate_weights`, native's form), so a sample keeps its rate as weights and a
+snapshot holds `rate_weights`. The predictor and the corrector with its defects are one
+kernel each (`adams._APPLY`), every formula's increment per element in registers in the
+reference's order. A carrier frame, or an operator without device terms (the Cartesian
+route's separable one), takes the host moments; the interaction formulation, the
+untransported witness and MLX's CPU device are refused. The backend takes the native
+package's compiled helpers (`solprop_native._helpers.NATIVE`, SEP 29 section 6.6), which
+evaluate the stage tables' rows and the Adams basis bitwise as the Python forms do. On an Apple M5 Max under load,
+one DOPRI5 trial on power-of-two grids, op by op against compiled: `he_rdw_averaged` 5.30
+against 2.91 ms, `rdw` 7.76 against 4.76, `radial_filament_256` 14.1 against 6.88,
+`spatial_absorber` 3.69 against 2.38, `kerr_beam_192` 246 against 131 and
+`cartesian_filament_128` 806 against 316 ms.
+
**Status: experimental** in the first release. The custom Metal kernels (`gpu_only` in
`tests/backends/test_mlx.py`) run on Metal in CI's macOS default lane, which asserts
that the device is available. That lane runs without coverage or the runtime type
checks, no CI pass selects MLX's CPU device, basedpyright on Linux cannot resolve
`mlx.core`, and the coverage lane omits `mlx_gpu`
-([testing](testing.md#the-mlx-omission)). The default `fft_size="auto"` takes the smooth
-size that a cost model fitted to FFTW's CPU transforms ranks cheapest
-(`grid._RADIX_PENALTY`); MLX's GPU FFT runs such sizes four to eight times slower than
-the next power of two (real transforms on an Apple M5 Max: 902 µs at 12288 against
-218 µs at 16384, 7629 µs at 98304 against 992 µs at 131072), so on default grids `mlx`
-can be slower than binary64 `native`, and the guide sends single-precision grids to
-`fft_size="pow2"`. Full support waits on power-of-two grids by default under single
-precision (or a per-backend transform cost), a macOS `mlx` CI job (coverage with a
+([testing](testing.md#the-mlx-omission)). `fft_size="auto"` minimises a per-library
+transform cost (`grid.fft_cost`): FFTW's (`grid._RADIX_PENALTY`) by default, MLX's when a
+keyword interface builds the grid of a single-precision run on `mlx` or `auto`
+(`driver.simulation._transform_library`), or when a grid is built with
+`transforms="mlx"`. MLX's GPU FFT is direct at every 2-3-5-smooth length up to 4096 and
+at powers of two, and takes Bluestein's algorithm elsewhere, six to twelve times the
+next power of two (an rfft and irfft pair on an Apple M5 Max: 715 µs at 10240 against
+63 µs at 16384), so past 4096 its cost picks the power of two. Full support waits on a
+macOS `mlx` CI job (coverage with a
recorded floor, the runtime type checks, basedpyright on `mlx_gpu`), the default
in-stage collar's tests restored on the default geometry, bounds against the oracle
that can detect an `mlx` error, and a re-timing on an idle machine
diff --git a/docs/dev/benchmarks.md b/docs/dev/benchmarks.md
index 4bd416786..61c0f0c39 100644
--- a/docs/dev/benchmarks.md
+++ b/docs/dev/benchmarks.md
@@ -2512,6 +2512,54 @@ Before the fold's fix, `radial_filament_256` 0.993 and `planar` 0.980 at nine th
The H200 has since measured the step in the scratch's order, above. An AMD Instinct MI300X has measured what rocFFT's plans hold and what a whole state's collar is worth, and an MI325X the step and the device tests with HIP in the scratch's new order, above.
+### `mlx` against `native` on an Apple M5 Max
+
+Single precision on `mlx` was slower than binary64 `native` on the helium RDW capillary,
+by 3.7 times as each backend runs it by default and 4.7 mode-averaged. Four causes,
+each measured on an Apple M5 Max (MLX 0.32.4) shared with other work, so ratios only,
+interleaved:
+
+- **Grid sizes.** `fft_size="auto"` took FFTW's 2-3-5-smooth sizes; MLX's GPU FFT is
+ direct at every smooth size up to 4096 and at powers of two, and takes Bluestein's
+ algorithm elsewhere: an rfft and irfft pair at 10240 took 715 µs, at 16384 63 µs. The
+ keyword interfaces now size a single-precision `mlx` run's grid with MLX's costs
+ (`grid.fft_cost(n, "mlx")`); one mode-averaged RDW trial went from 18.6 to 4.66 ms.
+- **Launches.** A DOPRI5 trial was about 2000 graph nodes, half of them launches of
+ about 10 µs. Each stage is now one `mx.compile` graph, bitwise the eager one; one
+ trial, op by op against compiled: `he_rdw_averaged` 5.30 against 2.91 ms, `rdw` 7.76
+ against 4.76, `radial_filament_256` 14.1 against 6.88, `spatial_absorber` 3.69 against
+ 2.38, `kerr_beam_192` 246 against 131, `cartesian_filament_128` 806 against 316.
+ Starting each stage as it is built took another 7 to 12 %.
+- **The integrator.** Single precision refused Adams, so `mlx` stepped DOPRI5 where
+ `native` stepped Adams. Adams is admitted now (#342) and runs on the device
+ (`MlxAdams`): warm, a four-mode `rdw` step is 1.48 ms.
+- **Host statistics.** A plane's field-grid plasma statistics scanned every node on the
+ host in binary64: 37.7 s of a 50.6 s tenth of `cartesian_filament_128`. On the device
+ with the stage's kernels the run took 21.5 s, and an RK trial there is 223 ms on
+ `mlx` against 511 ms on `native` at all cores.
+
+`python -m benchmarks ab --baseline-backend native --candidate-backend mlx`, a third
+of each case, two rounds, the ratio `mlx`/`native` (below one, `mlx` faster):
+
+| case | before, each default | after, each default | after, Adams on both |
+|---|---:|---:|---:|
+| `rdw` | 3.72 | 1.24 | 0.84 |
+| `he_rdw_averaged` | 4.72 | 2.40 | 1.68 |
+| `radial_filament_256` | 1.10 | 0.45 | 0.42 |
+| `spatial_absorber` | 0.71 | 0.80 | 0.27 |
+| `cartesian_filament_128` | 2.50 | 0.79 | |
+
+The single-precision default is still Runge-Kutta, so on the capillaries the middle
+column sets `mlx`'s DOPRI5 against `native`'s Adams. Whole runs, RK at `rtol = 1e-4`:
+`radial_filament_256` 0.67 s on `mlx` against 2.07 s on `native`, `spatial_absorber`
+1.98 against 5.54. The short runs' ratios carry the planes' shared host statistics
+(12 planes) as a fixed cost. `kerr_beam_*` was refused on `mlx` past a tenth of its
+length: over its 0.5–0.6 µm steps the spectral collar reaches `|Re ΔΦ|` of 150–180,
+past binary32's 88.7. Its low-storage march applies forward flows only, which a damped
+bin underflows harmlessly, so binary32 now holds it to growth alone; with the edge read
+on the device and the operator built once, whole runs take 1.05 s on `mlx` against
+2.64 s on `native` (192²) and 7.72 against 9.43 s (384²), the fields 2e-7 apart.
+
## Reference tables
These tables back the indicative results above.
diff --git a/docs/dev/figures/build.py b/docs/dev/figures/build.py
index 16e64bbf6..3a0d42321 100644
--- a/docs/dev/figures/build.py
+++ b/docs/dev/figures/build.py
@@ -734,7 +734,7 @@ class Layer(NamedTuple):
),
Module(
"backends/mlx_gpu/",
- ("backend", "batch", "passes", "arithmetic", "envelope"),
+ ("backend", "batch", "passes", "arithmetic", "envelope", "adams"),
),
),
"D": (
diff --git a/docs/dev/figures/layers.svg b/docs/dev/figures/layers.svg
index 065e0c7bd..dab8987ca 100644
--- a/docs/dev/figures/layers.svg
+++ b/docs/dev/figures/layers.svg
@@ -189,10 +189,10 @@ text { font-family: Inter, "Helvetica Neue", Helvetica, Arial, sans-serif; fill:
transforms · single · admission
envelope_plasma · general_modal
tdse
-
+
backends/mlx_gpu/
backend · batch · passes
-arithmetic · envelope
+arithmetic · envelope · adams
D
diff --git a/docs/guide/numerics/choosing-a-stepper.md b/docs/guide/numerics/choosing-a-stepper.md
index 204f38ab9..543feba35 100644
--- a/docs/guide/numerics/choosing-a-stepper.md
+++ b/docs/guide/numerics/choosing-a-stepper.md
@@ -37,9 +37,9 @@ on; pass `integrator=`, `rtol=` or `atol=` to choose another.
| `prop_free` (Cartesian, line) | `RungeKutta()` | 1e-4 | 0 | none |
| `prop_planar` | `Multistep()` | 1e-5 | 0 | none (not carried) |
-Under `precision="single"` every interface takes `RungeKutta()` and no noise, and its
-`rtol` is the larger of the table's and `1e-6`, at most `1e-5`: `1e-6` on `prop_gnlse`
-and `prop_capillary`, `1e-5` on the others, free space included
+Under `precision="single"` every interface takes the table's integrator and no noise,
+and its `rtol` is the larger of the table's and `1e-6`, at most
+`1e-4`: `1e-6` on `prop_gnlse` and `prop_capillary`, the table's on the others
([single precision](../performance/single-precision.md)). The
spatial interfaces' tolerances apply where their `SimulationSettings` give no
controller; a free-space run that names no integrator takes `RungeKutta()`. A default
diff --git a/docs/guide/numerics/fixed-schedules.md b/docs/guide/numerics/fixed-schedules.md
index 5866c0618..36241b3ee 100644
--- a/docs/guide/numerics/fixed-schedules.md
+++ b/docs/guide/numerics/fixed-schedules.md
@@ -122,8 +122,9 @@ alone, replay with fixed orders: `RungeKutta()`, as above, or
`Multistep(variable_order=False)`, whose order rises from one as its history accrues to
`order` and stays there, by a rule that reads no estimate. Two such replays of one
schedule make the same truncation errors, so their difference is rounding alone.
-Single precision steps with `RungeKutta()`, and refuses `Multistep()`, so a comparison
-across precisions is a Runge–Kutta one. Recording the order sequence in the schedule
+Single precision steps with each interface's own default, so a comparison across
+precisions replays the same method; name `Multistep(variable_order=False)` or
+`RungeKutta()` on both to fix its orders. Recording the order sequence in the schedule
would also fix a variable-order replay's orders, and make it match its adaptive run;
that would extend the saved schedule and is not done, since a fixed order gives the
comparison without it.
diff --git a/docs/guide/performance/backends.md b/docs/guide/performance/backends.md
index c0286bd8e..4e33e28d2 100644
--- a/docs/guide/performance/backends.md
+++ b/docs/guide/performance/backends.md
@@ -50,8 +50,8 @@ what runs it: a CPU build of the native backend, in a second environment, or
`Multistep()` ([the Adams integrator](../numerics/adams.md)) and `RungeKutta()`, each
the default of some interfaces
([the defaults](../numerics/choosing-a-stepper.md#the-defaults)), are available across
-the binary64 backends for their supported configurations; single precision
-refuses `Multistep()` on every backend. Beside a coupled flow, Adams requires its
+the binary64 backends for their supported configurations; single precision admits
+`Multistep()` in its exponential formulation on `numpy_ref` and `mlx`. Beside a coupled flow, Adams requires its
exponential formulation; CF4 requires Runge–Kutta on the reference backend. Check the
response and geometry chapters for further restrictions. The backend used is
logged at INFO and recorded in the output.
@@ -183,10 +183,10 @@ to binary64 ([transverse boundaries](../free-space/model.md#transverse-boundarie
The backend is **experimental** in this release. Its Metal kernels run in the macOS
default lane of continuous integration, which requires a usable Metal device, but
coverage and runtime type checks remain absent there
-([the remaining CI gaps](../../dev/testing.md#the-mlx-omission)). Its speed has not been
-re-measured on the default grids, whose 2-3-5-smooth sizes MLX's GPU transform runs
-four to eight times slower than powers of two: build single-precision grids with
-`fft_size="pow2"` ([grid sizes on `mlx`](single-precision.md#grid-sizes-on-mlx)).
+([the remaining CI gaps](../../dev/testing.md#the-mlx-omission)). MLX's GPU transform
+runs 2-3-5-smooth sizes past 4096 six to twelve times slower than powers of two, so the
+keyword interfaces size a single-precision run's grid for it, and a grid of your own
+takes `transforms="mlx"` ([grid sizes on `mlx`](single-precision.md#grid-sizes-on-mlx)).
MLX computes float32 matrix products in TF32 by default on Apple GPUs, which SEP 25's
arithmetic rules forbid. solprop sets `MLX_ENABLE_TF32=0` when it imports the backend,
diff --git a/docs/guide/performance/single-precision.md b/docs/guide/performance/single-precision.md
index b65258157..0884fc697 100644
--- a/docs/guide/performance/single-precision.md
+++ b/docs/guide/performance/single-precision.md
@@ -13,9 +13,8 @@ Single precision runs on the `mlx` backend, on the GPU of an Apple-silicon Mac
and radial and Cartesian free space. Its Metal kernels run in the macOS lane of
continuous integration. `mlx` is **experimental** in this release: its coverage is not
measured, the survival record below was measured on the reference implementation
-(on `mlx` for two cases only), and on the default grids it can be slower than binary64
-`native`; build single-precision grids
-with `fft_size="pow2"` ([grid sizes on `mlx`](#grid-sizes-on-mlx)). `numpy_ref` runs
+(on `mlx` for two cases only), and the keyword interfaces size its grids for MLX's
+transforms ([grid sizes on `mlx`](#grid-sizes-on-mlx)). `numpy_ref` runs
every route below as the reference implementation, which defines the arithmetic and
measures it but is not fast; away from Apple silicon it is the supported way to run single
precision, by name, because `native` computes in binary64 only
@@ -51,26 +50,33 @@ interfaces. Under single precision:
target below binary32's rounding per step buys steps without accuracy. A fixed
schedule reads no tolerance.
- **The default tolerance.** Each interface takes the larger of its binary64 default
- and the floor, and no more than `1e-5`
+ and the floor, and no more than `1e-4`
({data}`~solprop.translate.precision.SINGLE_RTOL_CAP`), the loosest value the
survival record below measured: `1e-6` on `prop_gnlse` (whose binary64 default is
`1e-7`) and `prop_capillary`, `1e-5` on `prop_waveguide`, `prop_radial` and
- `prop_planar`, and `1e-5` in free space, whose binary64 `1e-4` is not yet qualified in
- binary32. A spatial interface applies it where its `SimulationSettings` give no
+ `prop_planar`, and `1e-4` in free space
+ ([its record](#free-space-at-its-binary64-tolerance)). A spatial interface applies it where its `SimulationSettings` give no
controller; an explicit `rtol` or controller is the caller's.
- **The step's exponent.** Binary32 represents ``exp(x)`` only up to $x \approx 88.7$
- (binary64 to 709.8). The interaction picture multiplies by the linear propagator and
- its inverse, so a replayed step (or an adaptive run's floor `dz_min`) over which a
- strong collar or loss reaches that exponent is refused at translation, with the
- shortest step that fits, and one within a tenth of it is warned of. A 1 mm capillary's
- default collar on 0.25 mm steps is one such case.
-- **The integrator.** The default is `RungeKutta()` (DOPRI5) and the low-storage march is
- admitted; the Adams integrator, `Multistep()`, is refused until its single-precision
- accuracy is established. The binary64 default of `prop_capillary` and `prop_radial` is
- `Multistep()` ([the defaults](../numerics/choosing-a-stepper.md#the-defaults)), so on
- those interfaces a default run changes method as well as arithmetic when it changes
- precision: to compare the two precisions, pass `integrator=RungeKutta()` to both, as
- the survival record below does.
+ (binary64 to 709.8). The Runge–Kutta interaction picture multiplies by the linear
+ propagator and its inverse, so under `RungeKutta()` a replayed step (or an adaptive
+ run's floor `dz_min`) over which a strong collar or loss reaches that exponent is
+ refused at translation, with the shortest step that fits, and one within a tenth of
+ it is warned of; a 1 mm capillary's default collar on 0.25 mm steps is one such case.
+ On `mlx` an adaptive `RungeKutta()` trial past that range is combined in the lab frame
+ instead, by forward flows only, so it is not rejected and shrunk for the inverse's
+ sake: a radial Kerr beam whose first trial reaches 459 takes its millimetre in one
+ step, as binary64 does. The low-storage march and the exponential Adams method apply forward flows only: a
+ damped bin's flow underflows harmlessly towards zero, so they are limited by growth
+ alone, which no passive medium has. The Kerr beams' 0.5 µm steps, whose spectral
+ collar reaches 150 to 180, run in binary32 with `LowStorageRungeKutta()` for this
+ reason.
+- **The integrator.** Each interface takes its binary64 default
+ ([the defaults](../numerics/choosing-a-stepper.md#the-defaults)): `Multistep()` in
+ its exponential formulation on `prop_capillary`, `prop_radial` and `prop_planar`
+ ([the Adams record](#the-adams-integrator-in-binary32)), `RungeKutta()` (DOPRI5)
+ elsewhere; the low-storage march is admitted too. A run changes arithmetic, not
+ method, when it changes precision.
- **Noise.** A default `noise` resolves to none, and the run records why; an explicit
noise model is refused (below).
- **The backend.** `backend="auto"` resolves to `"mlx"` when MLX and a Metal GPU are
@@ -92,35 +98,39 @@ interfaces. Under single precision:
| gradients, tapers, loss, both temporal absorber schemes, the polarisation taper | yes | yes, where the operator is device-ready (not a z table) |
| Runge–Kutta, the low-storage march | yes | yes |
| fixed-schedule batches through `Batch` | yes | refused |
-| the Adams integrator | refused, pending its accuracy record | refused |
+| the Adams integrator | the exponential formulation | the exponential formulation, its history on the GPU; on the Metal device only |
| noise models | refused (a known limitation, below) | refused |
| the general modal route, the hybrid planar kind, coupled flows, TDSE responses, the dispersive electronic response, the far-field statistics | refused | refused |
## Grid sizes on `mlx`
A grid's default sample count, `fft_size="auto"`, is the cheapest size with prime
-factors 2, 3 and 5 by a cost model fitted to FFTW's transforms on CPUs
-([grids](../setup/grids.md#coarse-and-fine-sampling)). MLX's GPU transform runs those
-sizes four to eight times slower than the next power of two. On an Apple M5 Max one real
-transform took:
+factors 2, 3 and 5 by a transform-cost model ([grids](../setup/grids.md#coarse-and-fine-sampling)).
+For FFTW on a CPU that is often a smooth size such as 10240. MLX's GPU transform runs
+any such size up to 4096 directly, but above 4096 only powers of two: every other
+length takes Bluestein's algorithm, six to twelve times slower than the next power of
+two. On an Apple M5 Max an rfft and irfft pair took:
| samples | µs | next power of two | µs |
|---|---|---|---|
-| 12288 | 902 | 16384 | 218 |
-| 98304 | 7629 | 131072 | 992 |
+| 5120 | 502 | 8192 | 78 |
+| 10240 | 715 | 16384 | 63 |
-So on a default grid a single-precision run on `mlx` can be slower than a binary64 run
-on `native`. For a single-precision run, build the grid with `fft_size="pow2"` and pass
-it as `grid=`; the keyword interfaces build `"auto"` grids:
+So `"auto"` minimises the cost of the transform library the run will use
+({py:func}`solprop.grid.fft_cost`). The keyword interfaces (`prop_capillary`,
+`prop_gnlse`, `prop_waveguide`) take MLX's costs when the run is single precision on
+`mlx` (or `backend="auto"`, which resolves to it), and so build a power of two past
+4096 samples; with `backend="numpy_ref"`, or in binary64, they keep FFTW's. A grid of
+your own, as the free-space interfaces take, chooses with `transforms=`:
```python
from solprop.grid import FieldGrid
-grid = FieldGrid.from_limits(0.1, 800e-9, (200e-9, 3e-6), 200e-15, fft_size="pow2")
+grid = FieldGrid.from_limits(0.1, 800e-9, (200e-9, 3e-6), 200e-15, transforms="mlx")
```
-On the CPU backends `"auto"` stays the cheaper choice. Making powers of two the
-single-precision default is planned, with a re-timing of `mlx` on such grids.
+`fft_size="pow2"` gives the same sizes past 4096. A run on `mlx` with a smooth grid
+past 4096 samples, given explicitly, runs correctly but slowly.
## How the arithmetic is kept accurate
@@ -194,6 +204,51 @@ bands): both survive.
The field envelope of $10^{-3}$ is reached after about $3\times10^4$ steps; a run
that needs more takes binary64.
+### Free space at its binary64 tolerance
+
+Free space's binary64 default, `rtol = 1e-4`, was qualified in binary32 on 5 November
+2026 ([#85](https://github.com/LupoLab/solprop/issues/85)); until then a single-precision
+free-space run took `1e-5`. Each case ran with `RungeKutta()`, noise-free, on a
+power-of-two grid, in binary32 on `mlx` and binary64 on `native`, against a binary64 run
+at `rtol = 1e-6` (the field's relative difference):
+
+| case | binary64 at `1e-4` | binary32 at `1e-4` | binary64 at `1e-5` | binary32 at `1e-5` |
+|---|---|---|---|---|
+| radial filament in argon with plasma, 3 cm | 9.8e-5 | 2.0e-5 | 1.2e-5 | 1.0e-5 |
+| radial Kerr beam with its transverse collar, 8 cm | 2.5e-5 | 2.1e-5 | 1.7e-6 | 2.0e-6 |
+| Cartesian argon filament, 128 × 128, 1.5 cm | 6.9e-5 | 2.4e-5 | 6.2e-6 | 5.2e-6 |
+
+Binary32 at `1e-4` is as close to the reference as binary64 at `1e-4`, or closer: the
+tolerance, not the precision, sets the error. The Cartesian filament takes 48 steps at
+`1e-4` against 61 at `1e-5`.
+
+### The Adams integrator in binary32
+
+`Multistep()` was admitted on 5 November 2026 by the rule
+[#342](https://github.com/LupoLab/solprop/issues/342) proposed: binary32 Adams judged
+against binary64 Adams at the same tolerance, rather than against Runge–Kutta, whose
+difference from Adams is the methods' truncation. Each case ran its whole length,
+noise-free, on a power-of-two grid, at each interface's default tolerance, on `mlx`
+(binary32) and `native` (binary64). The table gives the relative difference of the
+final fields, and binary64 Runge–Kutta's from binary64 Adams as the scale of the
+methods' own truncation:
+
+| case | binary32 Adams against binary64 Adams | binary64 RK against binary64 Adams | binary32 RK against binary64 Adams |
+|---|---|---|---|
+| He capillary gradient, mode-averaged, 1.5 m (RDW) | 2.3e-6 | 3.6e-6 | 4.3e-5 |
+| the same, four modes | 4.3e-6 | 1.7e-6 | 1.3e-4 |
+| Ar capillary, field-grid plasma, 0.2 m | 1.3e-5 | 2.3e-5 | 4.9e-5 |
+| Ar capillary, envelope-grid plasma, 0.2 m | 8.2e-5 | 1.1e-4 | 1.2e-4 |
+| H₂ capillary, Raman, mode-averaged, 0.4 m | 8.0e-5 | 2.9e-5 | 1.0e-4 |
+| GNLSE, Raman and shock, 0.15 m | 2.2e-4 | 3.1e-5 | 9.4e-5 |
+| radial filament in argon with plasma, 3 cm | 6.8e-6 | 1.4e-5 | 1.1e-5 |
+| radial Kerr beam with its transverse collar, 8 cm | 5.0e-6 | 6.7e-6 | 7.7e-6 |
+
+Every case is far inside the field envelope of $10^{-3}$, and all but the GNLSE within a
+small multiple of the methods' own difference; the GNLSE runs at `1e-6` in binary32
+against binary64's `1e-7` (the floor), which accounts for its row. On the capillaries
+binary32 Adams is closer to the binary64 reference than binary32 Runge–Kutta is.
+
## Known limitations
- **Noise.** A one-photon-per-mode seed is of order $10^{-5}$ of a microjoule pulse's peak
diff --git a/docs/guide/setup/grids.md b/docs/guide/setup/grids.md
index 4666c73a5..9e562c6a2 100644
--- a/docs/guide/setup/grids.md
+++ b/docs/guide/setup/grids.md
@@ -144,7 +144,9 @@ $$t_n=\left(n-\frac{n_t}{2}\right)\delta t,\qquad n=0,\ldots,n_t-1.$$
The sample count is even. By default (`fft_size="auto"`) the fine size is the
cheapest even number with prime factors 2, 3 and 5 between the requirement and the next
power of two, by a transform-cost model fitted to measured FFT timings
-({py:func}`solprop.grid.fft_cost`); `fft_size="pow2"` takes the next power of two and
+({py:func}`solprop.grid.fft_cost`); FFTW's by default, and MLX's, which prefers powers
+of two past 4096 samples, with `transforms="mlx"` or for a single-precision keyword run
+on `mlx`. `fft_size="pow2"` takes the next power of two and
`fft_size="smooth"` the next 2-3-5 size. For example, a requirement of 4100 samples
rounds to 8192 with the power-of-two choice and 4320 with the smooth choice.
diff --git a/src/solprop/backends/mlx_gpu/adams.py b/src/solprop/backends/mlx_gpu/adams.py
new file mode 100644
index 000000000..d056caf33
--- /dev/null
+++ b/src/solprop/backends/mlx_gpu/adams.py
@@ -0,0 +1,863 @@
+# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""The exponential Adams history on the Metal device, for the ``mlx`` backend.
+
+:class:`MlxAdams` is an :class:`~solprop.backends.multistep.AdamsEngine`: the march
+(:class:`~solprop.backends.multistep.AdamsMarch`) keeps the controller -- the orders,
+the slots, rejection, restarts -- and this engine keeps the history's untransported
+source rows on the device and forms each trial there, as
+:class:`~solprop.backends.multistep.HostHistory` forms it on the host. The step's flow
+``exp(x)`` and its moments ``k! phi_{k+1}(x)`` are evaluated on the host in binary64 and
+rounded once to binary32, as the single-precision oracle rounds them; the predictor,
+the corrector and the defects are compiled device passes over the rows, with their
+Lagrange coefficients as inputs; and a trial reads its norms, the anchor's magnitude,
+the trial state's finiteness and the envelope plasma's failures in one
+synchronisation. One source evaluation per trial.
+
+It takes the exponential formulation, with or without a carrier frame. A varying
+operator (a gradient, a taper) adds the transported compensation of SEP 16 section 4.2:
+each history sample keeps its state on the device and its rate ``D(z_j)`` on the host,
+the state-independent factor ``exp((1 - theta_j) x) (D(z_j) - x / h)`` is formed in
+binary64 and rounded once, and the products with the states and the integrated Adams
+weights are device passes. The backend refuses the untransported witness by name.
+"""
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass
+from functools import cache
+from typing import TYPE_CHECKING, Any, cast
+
+import mlx.core as mx # pyright: ignore[reportMissingImports] - macOS arm64 only
+import numpy as np
+
+from solprop.backends.exponential import carrier_reference
+from solprop.backends.multistep import (
+ ExponentialKernels,
+ _carrier_factors,
+ _exponential_corrector,
+ source_absent,
+)
+from solprop.exceptions import BackendError
+from solprop.stepper.multistep import (
+ Multistep,
+ integrated_weights,
+ lagrange_coefficients,
+)
+from solprop.translate.linop import rate_weights
+
+if TYPE_CHECKING:
+ from solprop.backends.mlx_gpu.backend import MlxBackend
+
+__all__ = ["MlxAdams"]
+
+
+_APPLY = """
+ // One thread per element: every formula f of the trial,
+ // dz (sum_k M_k (sum_j c_fjk X_j) + sum_r q_fr Y_r), in the reference's order
+ // (ExponentialKernels._applied: each moment's combination first).
+ uint i = thread_position_in_grid.x;
+ if (i >= N) { return; }
+ float2 m[K];
+ for (int k = 0; k < K; ++k) {
+ complex64_t v = moments[k * N + i];
+ m[k] = float2(v.real, v.imag);
+ }
+ float2 x[J];
+ for (int j = 0; j < J; ++j) {
+ complex64_t v = values[j * N + i];
+ x[j] = float2(v.real, v.imag);
+ }
+ float2 y[R > 0 ? R : 1];
+ for (int r = 0; r < R; ++r) {
+ complex64_t v = extra[r * N + i];
+ y[r] = float2(v.real, v.imag);
+ }
+ float h = dz[0];
+ for (int f = 0; f < F; ++f) {
+ float2 total = float2(0.0f, 0.0f);
+ for (int k = 0; k < K; ++k) {
+ float2 combined = float2(0.0f, 0.0f);
+ for (int j = 0; j < J; ++j) {
+ combined += tables[(f * J + j) * K + k] * x[j];
+ }
+ total += float2(m[k].x * combined.x - m[k].y * combined.y,
+ m[k].x * combined.y + m[k].y * combined.x);
+ }
+ for (int r = 0; r < R; ++r) { total += weights[f * R + r] * y[r]; }
+ out[f * N + i] = complex64_t(h * total.x, h * total.y);
+ }
+"""
+
+
+@cache
+def _apply_kernel() -> object:
+ """Return the compiled kernel of an Adams trial's formulas (:func:`_applied`).
+
+ Returns
+ -------
+ object
+ The ``mlx.core.fast.metal_kernel`` callable.
+ """
+ return mx.fast.metal_kernel(
+ name="solprop_adams_apply",
+ input_names=["moments", "values", "tables", "extra", "weights", "dz"],
+ output_names=["out"],
+ source=_APPLY,
+ compile_options={"math_mode": "safe"},
+ )
+
+
+def _applied(
+ moments: mx.array,
+ tables: mx.array,
+ values: list[mx.array],
+ dz: mx.array,
+ extra: list[mx.array] | None = None,
+ weights: mx.array | None = None,
+) -> mx.array:
+ """Return every formula's increment, one kernel thread per element.
+
+ ``dz (sum_k M_k (sum_j c_fjk X_j) + sum_r q_fr Y_r)`` for each formula ``f``.
+
+ Parameters
+ ----------
+ moments : mlx.core.array
+ ``(n_moments, *shape)``.
+ tables : mlx.core.array
+ ``c_fjk``, float32, ``(n_f, len(values), n_k)`` with ``n_k <= n_moments``.
+ values : list of mlx.core.array
+ The samples ``X_j``.
+ dz : mlx.core.array
+ The step, a float32 scalar.
+ extra : list of mlx.core.array or None, optional
+ A varying operator's compensation rows ``Y_r``.
+ weights : mlx.core.array or None, optional
+ ``q_fr``, float32, ``(n_f, len(extra))``.
+
+ Returns
+ -------
+ mlx.core.array
+ ``(n_f, *shape)``.
+ """
+ n_f, n_j, n_k = tables.shape
+ shape = values[0].shape
+ n = values[0].size
+ rows = [] if extra is None else extra
+ stacked = mx.stack(rows) if rows else mx.zeros((1, *shape), dtype=mx.complex64)
+ q = weights if weights is not None else mx.zeros((n_f, 1), dtype=mx.float32)
+ (out,) = _apply_kernel()( # pyright: ignore[reportCallIssue]
+ inputs=[moments, mx.stack(values), tables, stacked, q, dz.reshape(1)],
+ template=[("N", n), ("F", n_f), ("J", n_j), ("K", n_k), ("R", len(rows))],
+ grid=(n, 1, 1),
+ threadgroup=(min(256, n), 1, 1),
+ output_shapes=[(n_f, *shape)],
+ output_dtypes=[mx.complex64],
+ )
+ return out
+
+
+def _scaled_square_sum(values: mx.array, index: mx.array) -> list[mx.array]:
+ """Return the power of two at or below the peak and the scaled sum of squares.
+
+ SEP 33's rule 6 over the norm's bins, as the Runge-Kutta norm reduces.
+
+ Parameters
+ ----------
+ values : mlx.core.array
+ A state-shaped array.
+ index : mlx.core.array
+ The norm's bins.
+
+ Returns
+ -------
+ list of mlx.core.array
+ The power and the sum, float32 scalars.
+ """
+ array = mx.take(values, index, axis=-1)
+ peak = mx.max(mx.abs(array))
+ power = mx.where(peak > 0, mx.floor(mx.log2(peak)), 0.0)
+ scaled = array * mx.power(2.0, -power)
+ re, im = mx.real(scaled), mx.imag(scaled)
+ return [power, mx.sum(re * re + im * im)]
+
+
+def _predict( # noqa: PLR0913, PLR0917 - a kernel's buffers
+ state: mx.array,
+ flow: mx.array,
+ moments: mx.array,
+ values: list[mx.array],
+ coefficients: mx.array,
+ dz: mx.array,
+ carried: list[mx.array] | None = None,
+ weights: mx.array | None = None,
+) -> mx.array:
+ """Return the predicted field ``exp(x) u_n + dz sum_k M_k sum_j c_jk F_j``.
+
+ Parameters
+ ----------
+ state, flow, moments : mlx.core.array
+ The anchor, ``exp(x)`` and the moments.
+ values : list of mlx.core.array
+ The history rows read, newest first, rotated under a carrier frame.
+ coefficients : mlx.core.array
+ The predictor's Lagrange coefficients, ``(len(values), n_k)``.
+ dz : mlx.core.array
+ The step.
+ carried : list of mlx.core.array or None, optional
+ A varying operator's carried compensations.
+ weights : mlx.core.array or None, optional
+ The predictor's integrated weights over them, ``(len(carried),)``.
+
+ Returns
+ -------
+ mlx.core.array
+ The lab-frame field at the end of the step.
+ """
+ if carried is not None and weights is not None:
+ increment = _applied(
+ moments, coefficients[None], values, dz, carried, weights[None]
+ )
+ else:
+ increment = _applied(moments, coefficients[None], values, dz)
+ return flow * state + increment[0]
+
+
+def _correct( # noqa: PLR0913, PLR0917 - a kernel's buffers
+ state: mx.array,
+ flow: mx.array,
+ moments: mx.array,
+ values: list[mx.array],
+ corrector: mx.array,
+ rows: mx.array,
+ dz: mx.array,
+ index: mx.array,
+ compensation: dict[str, Any] | None = None,
+) -> tuple[mx.array, list[mx.array], mx.array]:
+ """Return the corrected field, the reductions its norms are read from, the defects.
+
+ Parameters
+ ----------
+ state, flow, moments : mlx.core.array
+ As for the predictor.
+ values : list of mlx.core.array
+ The new source, then the history rows read.
+ corrector : mlx.core.array
+ The corrector's coefficients, ``(width, n_k)``.
+ rows : mlx.core.array
+ Each scored order's defect coefficients, ``(n_rows, width, n_k)``.
+ dz : mlx.core.array
+ The step.
+ index : mlx.core.array
+ The norm's bins.
+ compensation : dict or None, optional
+ A varying operator's terms: ``carried``, the history's compensations;
+ ``endpoint``, the new sample's; ``corrector`` and ``predictor``, each scored
+ order's integrated weights, ``(n_rows, 1 + n_carried)`` (the endpoint's first)
+ and ``(n_rows, n_carried)``.
+
+ Returns
+ -------
+ tuple
+ The field; per defect, then for the anchor, a power of two and a scaled
+ sum of squares, then whether the field is finite, as float32 scalars; and
+ the defects, ``(n_rows, *shape)``, for a controller that weights each bin.
+ """
+ tables = mx.concatenate([corrector[None], rows], axis=0)
+ if compensation is None:
+ increments = _applied(moments, tables, values, dz)
+ else:
+ # The corrector's weights over (endpoint, history) for the step's own order,
+ # then each defect's: its corrector's less its predictor's.
+ after = compensation["corrector"]
+ before = mx.pad(compensation["predictor"], [(0, 0), (1, 0)])
+ weights = mx.concatenate([after[:1], after - before], axis=0)
+ increments = _applied(
+ moments,
+ tables,
+ values,
+ dz,
+ [compensation["endpoint"], *compensation["carried"]],
+ weights,
+ )
+ advanced = flow * state + increments[0]
+ defects = increments[1:]
+ reductions: list[mx.array] = []
+ for row in range(rows.shape[0]):
+ reductions += _scaled_square_sum(defects[row], index)
+ reductions += _scaled_square_sum(state, index)
+ reductions.append(mx.all(mx.isfinite(advanced)).astype(mx.float32))
+ return advanced, reductions, defects
+
+
+_predict_fused = mx.compile(_predict)
+_correct_fused = mx.compile(_correct)
+
+
+@dataclass
+class _Trial:
+ """A formed trial, held until the march accepts or rejects it."""
+
+ dz: float
+ source: mx.array
+ advanced: mx.array
+ lab: mx.array
+ rate: np.ndarray | None
+
+
+class MlxAdams:
+ """The exponential Adams history and its arithmetic, on the Metal device.
+
+ Parameters
+ ----------
+ backend : solprop.backends.mlx_gpu.backend.MlxBackend
+ The backend whose state, sources, controller and synchronisation are used.
+ method : solprop.stepper.multistep.Multistep
+ The method, in the exponential formulation.
+
+ Attributes
+ ----------
+ dense : None
+ No dense observation: ``interpolate_planes`` is refused on ``mlx``.
+ compensated : bool
+ Whether a varying operator's samples carry the transported compensation.
+ carrier : solprop.backends.exponential.CarrierReference or None
+ The carrier frame the trials remove (SEP 35), as the host engine's.
+ """
+
+ dense: Any = None
+
+ def __init__(self, backend: "MlxBackend", method: Multistep) -> None: # noqa: UP037 - a type-checking import
+ """Hold the backend and an empty history; nothing is read from the device."""
+ self._backend = backend
+ self._method = method
+ self._kernels = ExponentialKernels(helpers=backend.helpers)
+ self._rows: list[mx.array | None] = [None] * self.n_slots
+ problem = backend._problem
+ self.compensated = problem.linear.phi_representation in (
+ "expansion",
+ "table",
+ ) and not source_absent(problem)
+ # A compensated history's sample states on the device, and their rates
+ # D(z_j) as weights over the operator's terms on the host.
+ self._states: list[mx.array | None] = [None] * self.n_slots
+ self._rates: list[np.ndarray | None] = [None] * self.n_slots
+ self._trial: _Trial | None = None
+ self.carrier = carrier_reference(backend._problem, method)
+
+ @property
+ def n_slots(self) -> int:
+ """The history's rows: the method's order and two more.
+
+ Returns
+ -------
+ int
+ ``order + 2``.
+ """
+ return self._method.order + 2
+
+ def reset(self) -> None:
+ """Forget any trial in flight."""
+ self._trial = None
+
+ def hold(self) -> object:
+ """Return the accepted state, the device array itself.
+
+ Returns
+ -------
+ object
+ The state.
+ """
+ return self._backend._require_state()
+
+ def restore(self, z: float, held: object) -> None:
+ """Make a held state current again at `z`.
+
+ Parameters
+ ----------
+ z : float
+ Its position, m.
+ held : object
+ What :meth:`hold` returned.
+ """
+ self._backend._adams_restore(z, cast(Any, held))
+
+ def start(self, z: float, *, stored: bool) -> None:
+ """Evaluate the source at the accepted state into row zero.
+
+ Parameters
+ ----------
+ z : float
+ The accepted position, m.
+ stored : bool
+ Must be true: the general path runs on the host and is refused.
+
+ Raises
+ ------
+ BackendError
+ For an unstored sample, which only the general path asks for.
+ """
+ if not stored:
+ msg = "the mlx Adams engine keeps every sample in its history"
+ raise BackendError(msg)
+ backend = self._backend
+ backend._hoist(z)
+ state = cast(mx.array, backend._require_state())
+ self._rows[0] = backend._adams_lab_source(state, z, purpose="startup")
+ if self.compensated:
+ # The startup sample's state and rate, read on the far side of a kink
+ # that restarted the history.
+ self._states[0] = state
+ self._rates[0] = rate_weights(
+ backend._problem.linear, z, helpers=backend.helpers
+ )
+
+ def value(self, slot: int) -> None:
+ """Return nothing: the history's rows stay on the device.
+
+ Parameters
+ ----------
+ slot : int
+ The row.
+ """
+ del slot
+
+ def fused_trial(self, *args: object, **kwargs: object) -> np.ndarray:
+ """Refuse the interaction formulation, which this engine does not run.
+
+ Parameters
+ ----------
+ *args, **kwargs : object
+ The march's trial arguments.
+
+ Raises
+ ------
+ BackendError
+ Always.
+ """
+ del args, kwargs
+ msg = "the mlx Adams engine runs the exponential formulation only"
+ raise BackendError(msg)
+
+ def fused_accept(self, keep: np.ndarray, free: int, *, interpolate: bool) -> None:
+ """Refuse the interaction formulation, which this engine does not run.
+
+ Parameters
+ ----------
+ keep : numpy.ndarray
+ The rows kept.
+ free : int
+ The free row.
+ interpolate : bool
+ Whether the interpolant is kept.
+
+ Raises
+ ------
+ BackendError
+ Always.
+ """
+ del keep, free, interpolate
+ msg = "the mlx Adams engine runs the exponential formulation only"
+ raise BackendError(msg)
+
+ def exponential_trial( # noqa: PLR0912, PLR0915 - one trial, pass by pass
+ self,
+ z: float,
+ dz: float,
+ nodes: list[float],
+ slots: np.ndarray,
+ order: int,
+ orders: list[int],
+ ) -> np.ndarray:
+ """Form one exponential trial on the device and return its defects' norms.
+
+ :meth:`HostHistory.exponential_trial
+ `'s arithmetic over
+ device rows, read in one synchronisation.
+
+ Parameters
+ ----------
+ z, dz : float
+ The anchor and the step, m.
+ nodes : list of float
+ The history's normalised positions, newest first.
+ slots : numpy.ndarray
+ Their rows, ``int64``.
+ order : int
+ The step's order.
+ orders : list of int
+ The orders scored, the step's own first.
+
+ Returns
+ -------
+ numpy.ndarray
+ One scaled norm per scored order; infinite when the trial is not finite.
+ """
+ backend = self._backend
+ state = cast(mx.array, backend._require_state())
+ backend._hoist(z)
+ backend._envelope_failures = []
+ width = 1 + max(orders)
+ helpers = backend.helpers
+ bundle = backend._stage_scalars(z, z + dz)
+ carrier = self.carrier
+ active = carrier is not None and carrier.active
+ weights_x = None
+ if bundle.phi_delta is not None and backend._terms.phi is not None:
+ weights_x = np.asarray(bundle.phi_delta, dtype=np.float64).reshape(-1)
+ exponent = shift = None
+ rows_read = slots[: width - 1]
+ carried = endpoint = rate = None
+ if self.compensated:
+ rate = rate_weights(
+ backend._problem.linear, z + dz, before=True, helpers=helpers
+ )
+ if weights_x is not None and not active:
+ # SEP 33: the flow and its moments to binary64 accuracy, each rounded
+ # once, from the step's exponent in double-float on the device; with a
+ # varying operator, in the same pass, the compensation's factors.
+ if self.compensated:
+ assert rate is not None
+ differences = [
+ cast(np.ndarray, self._rates[int(slot)]) - weights_x / dz
+ for slot in rows_read
+ ]
+ flow, moments, factors = backend._phi.trial(
+ np.stack([weights_x, *differences, rate - weights_x / dz]),
+ width,
+ np.array([1.0 - node for node in nodes[: len(rows_read)]]),
+ endpoint=True,
+ )
+ carried = [
+ factor * cast(mx.array, self._states[int(slot)])
+ for factor, slot in zip(factors, rows_read, strict=False)
+ ]
+ endpoint = factors[-1]
+ else:
+ flow, moments = backend._phi.moments(
+ *backend._phi.device_weights(weights_x), width
+ )
+ else:
+ exponent = np.array(backend._delta_phi(bundle))
+ if active:
+ assert carrier is not None
+ shift = carrier.shift(exponent)
+ moments = mx.array(
+ np.asarray(self._kernels.moments(exponent, width, shift=shift)).astype(
+ np.complex64
+ )
+ )
+ flow = mx.array(np.exp(exponent).astype(np.complex64))
+ values: list[mx.array] = []
+ for slot in rows_read:
+ row = self._rows[int(slot)]
+ assert row is not None # every slot the march reads holds a sample
+ values.append(row)
+ if shift is not None:
+ factors = _carrier_factors(nodes, len(values), shift).astype(np.complex64)
+ values = [
+ mx.array(factor) * value
+ for factor, value in zip(factors, values, strict=True)
+ ]
+ length = mx.array(dz, dtype=mx.float32)
+ predictor = lagrange_coefficients(nodes[:order], check=False, helpers=helpers)
+ weights = None
+ if self.compensated:
+ assert weights_x is not None and rate is not None # an expansion's terms
+ if carried is None:
+ carried = self._carried(weights_x, dz, nodes, rows_read)
+ phi = backend._phi
+ endpoint = phi.combination(*phi.device_weights(rate - weights_x / dz))
+ weights = self._weights(nodes, [order], len(carried))[1][0]
+ # Chosen here: the march builds the engine before the backend's own tables.
+ fused = backend._fused
+ lab = (_predict_fused if fused else _predict)(
+ state,
+ flow,
+ moments,
+ values[:order],
+ mx.array(np.asarray(predictor, dtype=np.float32)),
+ length,
+ carried,
+ weights,
+ )
+ source = cast(
+ mx.array, backend._adams_lab_source(lab, z + dz, purpose="predictor")
+ )
+ corrector = _exponential_corrector(nodes, order, width, helpers=helpers)
+ rows = self._kernels.defect_rows(nodes, orders, width)
+ compensation = None
+ if carried is not None:
+ assert endpoint is not None
+ after, before = self._weights(nodes, orders, len(carried))
+ compensation = {
+ "carried": carried,
+ # The new sample's compensation at the predicted state, untransported:
+ # (D(z + h) - x / h), its weights differenced in binary64.
+ "endpoint": endpoint * lab,
+ "corrector": after,
+ "predictor": before,
+ }
+ advanced, reductions, defects = (_correct_fused if fused else _correct)(
+ state,
+ flow,
+ moments,
+ [source, *values],
+ mx.array(np.asarray(corrector, dtype=np.float32)),
+ mx.array(np.asarray(rows, dtype=np.float32)),
+ length,
+ backend._norm_index,
+ compensation,
+ )
+ read = backend._synchronised([*reductions, backend._failure_count()])
+ backend._raise_on_failures(float(read[-1]))
+ self._trial = _Trial(
+ dz=dz, source=source, advanced=advanced, lab=lab, rate=rate
+ )
+ if not np.all(np.isfinite(read[:-1])) or read[-2] != 1.0:
+ return np.full(len(orders), math.inf)
+ squares = [
+ math.ldexp(float(read[2 * k + 1]), 2 * int(read[2 * k]))
+ for k in range(len(orders) + 1)
+ ]
+ magnitude = math.sqrt(squares[-1])
+ scale = backend._norm_controller.scale(magnitude, magnitude)
+ if isinstance(scale, np.ndarray):
+ return self._weighted(defects, scale)
+ return np.array([math.sqrt(square) / scale for square in squares[:-1]])
+
+ def _carried(
+ self, weights: np.ndarray, dz: float, nodes: list[float], slots: np.ndarray
+ ) -> list[mx.array]:
+ """Return the history samples' compensations carried to the step's end.
+
+ ``exp(s_j x) (D(z_j) - x / h) u_j``, ``s_j = 1 - theta_j``. Both factors are
+ double-float combinations of the operator's terms, each rounded once: the
+ flow at weights ``s_j w`` and the difference of rates at ``r_j - w / h``, the
+ rates differenced in their weights in binary64 before anything multiplies
+ them (SEP 16 section 4.2), as the native engine forms them.
+
+ Parameters
+ ----------
+ weights : numpy.ndarray
+ ``x``'s weights over the operator's terms, binary64.
+ dz : float
+ The step, m.
+ nodes : list of float
+ The history's normalised positions, newest first.
+ slots : numpy.ndarray
+ The rows read, newest first.
+
+ Returns
+ -------
+ list of mlx.core.array
+ One carried row per sample.
+ """
+ phi = self._backend._phi
+ carried = []
+ for node, slot in zip(nodes, slots, strict=False):
+ rate, state = self._rates[int(slot)], self._states[int(slot)]
+ assert rate is not None and state is not None
+ flow, _ = phi.pair(*phi.device_weights((1.0 - node) * weights))
+ difference = phi.combination(*phi.device_weights(rate - weights / dz))
+ carried.append(flow * (difference * state))
+ return carried
+
+ def _weights(
+ self, nodes: list[float], orders: list[int], count: int
+ ) -> tuple[mx.array, mx.array]:
+ """Return each order's corrector and predictor weights over the carried rows.
+
+ The transported treatment's ordinary integrated Adams weights, the
+ corrector's through the endpoint sample, padded with zeros to the rows the
+ trial carries.
+
+ Parameters
+ ----------
+ nodes : list of float
+ The history's normalised positions, newest first.
+ orders : list of int
+ The orders.
+ count : int
+ The carried rows.
+
+ Returns
+ -------
+ tuple of mlx.core.array
+ ``(n_orders, 1 + count)`` and ``(n_orders, count)``, float32.
+ """
+ helpers = self._backend.helpers
+ after = np.zeros((len(orders), 1 + count))
+ before = np.zeros((len(orders), count))
+ for row, order in enumerate(orders):
+ after[row, : order + 1] = integrated_weights(
+ np.asarray([1.0, *nodes[:order]]), check=False, helpers=helpers
+ )
+ before[row, :order] = integrated_weights(
+ np.asarray(nodes[:order]), check=False, helpers=helpers
+ )
+ return (
+ mx.array(after.astype(np.float32)),
+ mx.array(before.astype(np.float32)),
+ )
+
+ def _weighted(self, defects: mx.array, scale: np.ndarray) -> np.ndarray:
+ """Return the norms under a controller that scales each bin.
+
+ Parameters
+ ----------
+ defects : mlx.core.array
+ The trial's defects, one per scored order, compensation included.
+ scale : numpy.ndarray
+ The scale of every bin.
+
+ Returns
+ -------
+ numpy.ndarray
+ One norm per order.
+ """
+ backend = self._backend
+ weights = mx.array(
+ (1.0 / scale[backend._problem.grids.norm_mask]).astype(np.float32)
+ )
+ weighted = mx.take(defects, backend._norm_index, axis=-1) * weights
+ re, im = mx.real(weighted), mx.imag(weighted)
+ sums = mx.sum((re * re + im * im).reshape(defects.shape[0], -1), axis=1)
+ return np.sqrt(np.array(sums, dtype=np.float64))
+
+ def exponential_accept(
+ self, keep: np.ndarray, free: int, *, interpolate: bool
+ ) -> None:
+ """Adopt the held trial; its source takes row `free`.
+
+ Parameters
+ ----------
+ keep : numpy.ndarray
+ The rows kept; nothing moves in this formulation.
+ free : int
+ The row the new sample takes.
+ interpolate : bool
+ Must be false: dense observation is refused on ``mlx``.
+ """
+ del keep, interpolate
+ trial = self._trial
+ assert trial is not None
+ self._trial = None
+ self._backend._adams_adopt(trial.advanced, trial.dz)
+ self._rows[free] = trial.source
+ if self.compensated:
+ self._states[free] = trial.lab
+ self._rates[free] = trial.rate
+
+ def snapshot_nbytes(self) -> int:
+ """Return the bytes :meth:`snapshot_rows` would copy.
+
+ Returns
+ -------
+ int
+ The rows' size, complex64.
+ """
+ shape = self._backend._require_state().shape
+ rows = 2 if self.compensated else 1
+ terms = self._backend._phi.n_terms if self.compensated else 0
+ return rows * self.n_slots * math.prod(shape) * 8 + 8 * self.n_slots * terms
+
+ def snapshot_rows(self) -> dict[str, np.ndarray]:
+ """Return host copies of the history's rows, in complex64.
+
+ Returns
+ -------
+ dict
+ ``"store"``: one row per slot, zero where the history has none yet.
+ """
+ shape = self._backend._require_state().shape
+ rows = {"store": self._host(self._rows, shape)}
+ if self.compensated:
+ rows["states"] = self._host(self._states, shape)
+ rates = np.zeros((self.n_slots, self._backend._phi.n_terms))
+ for slot, rate in enumerate(self._rates):
+ if rate is not None:
+ rates[slot] = rate
+ rows["rate_weights"] = rates
+ return rows
+
+ def _host(self, rows: list[mx.array | None], shape: tuple[int, ...]) -> np.ndarray:
+ """Return device rows on the host, complex64, zero where there is none.
+
+ Parameters
+ ----------
+ rows : list of mlx.core.array or None
+ One per slot.
+ shape : tuple of int
+ The state's shape.
+
+ Returns
+ -------
+ numpy.ndarray
+ ``(n_slots, *shape)``.
+ """
+ host = np.zeros((self.n_slots, *shape), dtype=np.complex64)
+ for slot, row in enumerate(rows):
+ if row is not None:
+ host[slot] = np.array(row)
+ return host
+
+ def load_rows(self, rows: Mapping[str, np.ndarray], shape: tuple[int, ...]) -> None:
+ """Install rows a snapshot holds, narrowed to complex64 on the device.
+
+ Parameters
+ ----------
+ rows : collections.abc.Mapping
+ The rows, by name.
+ shape : tuple of int
+ The state's shape.
+
+ Raises
+ ------
+ BackendError
+ If the rows are not a store of this history's shape, or hold any other
+ name (a compensated or coupled history's).
+ """
+ expected = {"store": (self.n_slots, *shape)}
+ if self.compensated:
+ expected |= {
+ "states": (self.n_slots, *shape),
+ "rate_weights": (self.n_slots, self._backend._phi.n_terms),
+ }
+ names = set(expected)
+ if set(rows) != names or any(
+ rows[name].shape != expected[name] for name in names
+ ):
+ msg = (
+ "the mlx backend cannot continue this Adams history: it keeps "
+ f"rows {expected} and nothing else"
+ )
+ raise BackendError(msg)
+ self.reset()
+ self._rows = [mx.array(row) for row in rows["store"].astype(np.complex64)]
+ if self.compensated:
+ self._states = [
+ mx.array(row) for row in rows["states"].astype(np.complex64)
+ ]
+ self._rates = [
+ np.array(row, dtype=np.float64) for row in rows["rate_weights"]
+ ]
+
+ def observe(self, position: float) -> object:
+ """Refuse dense observation, which ``mlx`` does not run.
+
+ Parameters
+ ----------
+ position : float
+ The plane, m.
+
+ Raises
+ ------
+ BackendError
+ Always.
+ """
+ del position
+ msg = "the mlx backend does not interpolate planes"
+ raise BackendError(msg)
diff --git a/src/solprop/backends/mlx_gpu/arithmetic.py b/src/solprop/backends/mlx_gpu/arithmetic.py
index d6e2d1a9f..ca3cacda9 100644
--- a/src/solprop/backends/mlx_gpu/arithmetic.py
+++ b/src/solprop/backends/mlx_gpu/arithmetic.py
@@ -30,6 +30,7 @@
import mlx.core as mx # pyright: ignore[reportMissingImports] - macOS arm64 only
import numpy as np
+from solprop.backends.exponential import _SERIES_TERMS, PHI_JOIN
from solprop.exceptions import BackendError
__all__ = [
@@ -40,6 +41,7 @@
"gemm_probe",
"on_gpu",
"population",
+ "population_parameters",
"prefix_scan",
"rate_kernel",
]
@@ -123,26 +125,276 @@
out_im[i] = magnitude * metal::fma(s, delta, s);
"""
+_PAIR = """
+ uint i = thread_position_in_grid.x;
+ if (i >= N) { return; }
+ float2 re = float2(0.0f, 0.0f);
+ float2 im = float2(0.0f, 0.0f);
+ for (int t = 0; t < TERMS; ++t) {
+ float2 w = float2(w_hi[t], w_lo[t]);
+ uint k = t * N + i;
+ re = df_add(re, df_mul(w, float2(re_hi[k], re_lo[k])));
+ im = df_add(im, df_mul(w, float2(im_hi[k], im_lo[k])));
+ }
+ // The combination kernel's exponential at both signs from one combination: the
+ // inverse's magnitude is the same expression at sign -1, and its phasor is the
+ // forward's conjugate, cosine and sine being even and odd exactly.
+ float turns = metal::rint(im.x * INV_TWO_PI);
+ float2 period = float2(TWO_PI_HI, TWO_PI_LO);
+ float2 phase = df_add(im, df_mul(float2(-turns, 0.0f), period));
+ float angle = phase.x + phase.y;
+ float c = metal::precise::cos(angle);
+ float s = metal::precise::sin(angle);
+ float2 norm = df_add(two_prod(c, c), two_prod(s, s));
+ float delta = -0.5f * ((norm.x - 1.0f) + norm.y);
+ float cc = metal::fma(c, delta, c);
+ float ss = metal::fma(s, delta, s);
+ float forward = metal::precise::exp(re.x) * (1.0f + re.y);
+ float back = metal::precise::exp(-re.x) * (1.0f + -re.y);
+ forward_re[i] = forward * cc;
+ forward_im[i] = forward * ss;
+ back_re[i] = back * cc;
+ back_im[i] = -(back * ss);
+"""
+
+_MOMENTS_HEADER = """
+struct dfc { float2 re; float2 im; };
+inline float2 df_neg(float2 a) { return float2(-a.x, -a.y); }
+inline float2 df_sub(float2 a, float2 b) { return df_add(a, df_neg(b)); }
+inline float2 df_div_f(float2 a, float b) {
+ float q1 = a.x / b;
+ float2 p = two_prod(q1, b);
+ float r = ((a.x - p.x) - p.y) + a.y;
+ return quick_two_sum(q1, r / b);
+}
+inline float2 df_div(float2 a, float2 b) {
+ float q1 = a.x / b.x;
+ float2 r = df_sub(a, df_mul(float2(q1, 0.0f), b));
+ float q2 = r.x / b.x;
+ r = df_sub(r, df_mul(float2(q2, 0.0f), b));
+ float q3 = r.x / b.x;
+ return df_add(quick_two_sum(q1, q2), float2(q3, 0.0f));
+}
+inline dfc c_add(dfc a, dfc b) { return {df_add(a.re, b.re), df_add(a.im, b.im)}; }
+inline dfc c_sub(dfc a, dfc b) { return {df_sub(a.re, b.re), df_sub(a.im, b.im)}; }
+inline dfc c_mul(dfc a, dfc b) {
+ return {df_sub(df_mul(a.re, b.re), df_mul(a.im, b.im)),
+ df_add(df_mul(a.re, b.im), df_mul(a.im, b.re))};
+}
+inline dfc c_real(dfc a, float2 s) { return {df_mul(a.re, s), df_mul(a.im, s)}; }
+inline dfc c_div_f(dfc a, float b) { return {df_div_f(a.re, b), df_div_f(a.im, b)}; }
+inline dfc c_ldexp(dfc a, int e) {
+ return {float2(metal::ldexp(a.re.x, e), metal::ldexp(a.re.y, e)),
+ float2(metal::ldexp(a.im.x, e), metal::ldexp(a.im.y, e))};
+}
+inline dfc c_div(dfc a, dfc b) {
+ float2 d = df_add(df_mul(b.re, b.re), df_mul(b.im, b.im));
+ dfc n = {df_add(df_mul(a.re, b.re), df_mul(a.im, b.im)),
+ df_sub(df_mul(a.im, b.re), df_mul(a.re, b.im))};
+ return {df_div(n.re, d), df_div(n.im, d)};
+}
+// exp(y) for |y| <= 1/2 by its Taylor series, Horner's form, 18 terms (the tail is
+// below 2^-60 relative).
+inline dfc c_exp_small(dfc y) {
+ dfc e = {float2(1.0f, 0.0f), float2(0.0f, 0.0f)};
+ for (int m = 18; m >= 1; --m) {
+ e = c_div_f(c_mul(e, y), float(m));
+ e.re = df_add(e.re, float2(1.0f, 0.0f));
+ }
+ return e;
+}
+// exp(x): the phase reduced by whole turns of a double-float 2 pi, then scaled to at
+// most 1/2, summed and squared back.
+inline dfc c_exp(dfc x) {
+ float turns = metal::rint(x.im.x * INV_TWO_PI);
+ dfc r = {x.re, df_add(x.im, df_mul(float2(-turns, 0.0f),
+ float2(TWO_PI_HI, TWO_PI_LO)))};
+ float size = metal::sqrt(r.re.x * r.re.x + r.im.x * r.im.x);
+ int s = size > 0.5f ? int(metal::ceil(metal::log2(size / 0.5f))) : 0;
+ dfc e = c_exp_small(c_ldexp(r, -s));
+ for (int level = 0; level < s; ++level) { e = c_mul(e, e); }
+ return e;
+}
+// One combination sum_t w_ct T_t of the terms, in double-float.
+#define COMBINE(c, out) \
+ out = {float2(0.0f, 0.0f), float2(0.0f, 0.0f)}; \
+ for (int t = 0; t < TERMS; ++t) { \
+ float2 w = float2(w_hi[(c) * TERMS + t], w_lo[(c) * TERMS + t]); \
+ uint k = t * N + i; \
+ out.re = df_add(out.re, df_mul(w, float2(re_hi[k], re_lo[k]))); \
+ out.im = df_add(out.im, df_mul(w, float2(im_hi[k], im_lo[k]))); \
+ }
+"""
+
+_MOMENTS = """
+ uint i = thread_position_in_grid.x;
+ if (i >= N) { return; }
+ // x = sum_t w_t T_t in double-float, as the propagator kernels combine it.
+ dfc x;
+ COMBINE(0, x)
+ dfc phi[P + 1];
+ float magnitude = metal::sqrt(x.re.x * x.re.x + x.im.x * x.im.x);
+ if (magnitude > JOIN) {
+ // exp(x) with the phase reduced by whole turns of a double-float 2 pi, then
+ // scaled to at most 1/2, summed and squared back; recurred up beyond the join,
+ // where the recurrence is stable (solprop.backends.exponential._phi_far).
+ phi[0] = c_exp(x);
+ for (int k = 1; k <= P; ++k) {
+ dfc shifted = phi[k - 1];
+ shifted.re = df_sub(shifted.re, float2(inv_fact[2 * (k - 1)],
+ inv_fact[2 * (k - 1) + 1]));
+ phi[k] = c_div(shifted, x);
+ }
+ } else {
+ // Near zero: the reference's scaling, highest series, downward recurrence and
+ // doubling (solprop.backends.exponential._phi_near), in double-float.
+ int s = magnitude > 0.5f ? int(metal::ceil(metal::log2(magnitude / 0.5f))) : 0;
+ dfc y = c_ldexp(x, -s);
+ dfc term = {float2(inv_fact[2 * P], inv_fact[2 * P + 1]), float2(0.0f, 0.0f)};
+ dfc total = term;
+ for (int m = 1; m < SERIES; ++m) {
+ term = c_div_f(c_mul(term, y), float(m + P));
+ total = c_add(total, term);
+ }
+ phi[P] = total;
+ for (int k = P - 1; k >= 1; --k) {
+ phi[k] = c_mul(y, phi[k + 1]);
+ phi[k].re = df_add(phi[k].re, float2(inv_fact[2 * k], inv_fact[2 * k + 1]));
+ }
+ phi[0] = c_exp_small(y);
+ for (int level = 0; level < s; ++level) {
+ dfc old[P + 1];
+ for (int k = 0; k <= P; ++k) { old[k] = phi[k]; }
+ phi[0] = c_mul(old[0], old[0]);
+ for (int k = 1; k <= P; ++k) {
+ dfc sum = c_mul(old[0], old[k]);
+ for (int j = 1; j <= k; ++j) {
+ sum = c_add(sum, c_real(old[j], float2(inv_fact[2 * (k - j)],
+ inv_fact[2 * (k - j) + 1])));
+ }
+ phi[k] = c_ldexp(sum, -k);
+ }
+ }
+ }
+ flow_re[i] = phi[0].re.x + phi[0].re.y;
+ flow_im[i] = phi[0].im.x + phi[0].im.y;
+ for (int k = 0; k < P; ++k) {
+ // k! phi_{k+1}, the factorial exact in binary32 (at most 7!).
+ float f = 1.0f;
+ for (int j = 2; j <= k; ++j) { f *= float(j); }
+ dfc m = c_real(phi[k + 1], float2(f, 0.0f));
+ moments_re[k * N + i] = m.re.x + m.re.y;
+ moments_im[k * N + i] = m.im.x + m.im.y;
+ }
+ // A varying operator's compensation factors (SEP 16 section 4.2): per history
+ // sample exp(s_j x) (D(z_j) - x / h), the rates' difference being combination
+ // 1 + j, each product rounded once; then the endpoint's D(z + h) - x / h.
+ for (int j = 0; j < SLOTS; ++j) {
+ dfc d;
+ COMBINE(1 + j, d)
+ dfc f = c_mul(c_exp(c_real(x, float2(spans[2 * j], spans[2 * j + 1]))), d);
+ factors_re[j * N + i] = f.re.x + f.re.y;
+ factors_im[j * N + i] = f.im.x + f.im.y;
+ }
+ if (ENDPOINT) {
+ dfc d;
+ COMBINE(1 + SLOTS, d)
+ factors_re[SLOTS * N + i] = d.re.x + d.re.y;
+ factors_im[SLOTS * N + i] = d.im.x + d.im.y;
+ }
+"""
+
@cache
-def _kernel() -> object:
- """Return the compiled double-float combination kernel.
+def _moments_kernel() -> object:
+ """Return the compiled kernel of an exponential Adams trial's flow and moments.
Returns
-------
object
The ``mlx.core.fast.metal_kernel`` callable.
"""
- source = (
- _COMBINE.replace("INV_TWO_PI", f"{1 / (2 * math.pi)!r}f")
+ return mx.fast.metal_kernel(
+ name="solprop_double_float_moments",
+ input_names=[
+ "re_hi",
+ "re_lo",
+ "im_hi",
+ "im_lo",
+ "w_hi",
+ "w_lo",
+ "inv_fact",
+ "spans",
+ ],
+ output_names=[
+ "flow_re",
+ "flow_im",
+ "moments_re",
+ "moments_im",
+ "factors_re",
+ "factors_im",
+ ],
+ source=_source(_MOMENTS)
+ .replace("JOIN", f"{PHI_JOIN!r}f")
+ .replace("SERIES", str(_SERIES_TERMS)),
+ header=_HEADER + _source(_MOMENTS_HEADER),
+ compile_options={"math_mode": "safe"},
+ )
+
+
+def _source(body: str) -> str:
+ """Return a double-float kernel's source with its constants in place.
+
+ Parameters
+ ----------
+ body : str
+ The kernel's body.
+
+ Returns
+ -------
+ str
+ The source.
+ """
+ return (
+ body.replace("INV_TWO_PI", f"{1 / (2 * math.pi)!r}f")
.replace("TWO_PI_HI", f"{_TWO_PI_HI!r}f")
.replace("TWO_PI_LO", f"{_TWO_PI_LO!r}f")
)
+
+
+@cache
+def _pair_kernel() -> object:
+ """Return the compiled kernel of a propagator and its inverse.
+
+ Returns
+ -------
+ object
+ The ``mlx.core.fast.metal_kernel`` callable.
+ """
+ return mx.fast.metal_kernel(
+ name="solprop_double_float_pair",
+ input_names=["re_hi", "re_lo", "im_hi", "im_lo", "w_hi", "w_lo"],
+ output_names=["forward_re", "forward_im", "back_re", "back_im"],
+ source=_source(_PAIR),
+ header=_HEADER,
+ compile_options={"math_mode": "safe"},
+ )
+
+
+@cache
+def _kernel() -> object:
+ """Return the compiled double-float combination kernel.
+
+ Returns
+ -------
+ object
+ The ``mlx.core.fast.metal_kernel`` callable.
+ """
return mx.fast.metal_kernel(
name="solprop_double_float_combine",
input_names=["re_hi", "re_lo", "im_hi", "im_lo", "w_hi", "w_lo"],
output_names=["out_re", "out_im"],
- source=source,
+ source=_source(_COMBINE),
header=_HEADER,
compile_options={"math_mode": "safe"},
)
@@ -199,12 +451,16 @@ class DoubleFloatTerms:
CPU device.
host : numpy.ndarray or None
The binary64 terms, kept on MLX's CPU device only.
+ real_bound : tuple of float
+ Each term's largest ``|Re T_t|``, so that ``sum_t |w_t| real_bound_t`` bounds
+ a combination's real parts without forming it.
"""
shape: tuple[int, ...]
n_terms: int
parts: tuple[mx.array, ...]
host: np.ndarray | None = None
+ real_bound: tuple[float, ...] = ()
@classmethod
def upload(cls, terms: np.ndarray) -> "DoubleFloatTerms": # noqa: UP037 - the runtime type hook resolves this while the class body runs
@@ -230,12 +486,29 @@ def upload(cls, terms: np.ndarray) -> "DoubleFloatTerms": # noqa: UP037 - the r
raise BackendError("a stage term must be finite to reach the device")
shape = values.shape[1:]
flat = values.reshape(-1)
+ bound = tuple(float(np.max(np.abs(term.real), initial=0.0)) for term in values)
if on_gpu():
re_hi, re_lo = _split(flat.real)
im_hi, im_lo = _split(flat.imag)
parts = tuple(mx.array(part) for part in (re_hi, re_lo, im_hi, im_lo))
- return cls(shape, int(values.shape[0]), parts)
- return cls(shape, int(values.shape[0]), (), values)
+ return cls(shape, int(values.shape[0]), parts, real_bound=bound)
+ return cls(shape, int(values.shape[0]), (), values, real_bound=bound)
+
+ def real_reach(self, weights: np.ndarray) -> float:
+ """Return a bound on ``max |Re sum_t w_t T_t|`` from the terms' own bounds.
+
+ Parameters
+ ----------
+ weights : numpy.ndarray
+ One binary64 weight per term.
+
+ Returns
+ -------
+ float
+ ``sum_t |w_t| max |Re T_t|``.
+ """
+ w = np.abs(np.asarray(weights, dtype=np.float64).reshape(-1))
+ return float(np.dot(w, np.asarray(self.real_bound)))
@property
def nbytes(self) -> int:
@@ -249,6 +522,239 @@ def nbytes(self) -> int:
host = 0 if self.host is None else int(self.host.nbytes)
return int(sum(part.nbytes for part in self.parts)) + host
+ def device_weights(self, weights: np.ndarray) -> tuple[mx.array, mx.array]:
+ """Split binary64 weights into the kernel's float32 heads and tails.
+
+ Parameters
+ ----------
+ weights : numpy.ndarray
+ One binary64 weight per term.
+
+ Returns
+ -------
+ tuple of mlx.core.array
+ The heads and the tails, ``(n_terms,)`` each.
+
+ Raises
+ ------
+ BackendError
+ If the weights do not match the terms.
+ """
+ w = np.asarray(weights, dtype=np.float64).reshape(-1)
+ if w.size != self.n_terms:
+ msg = f"{w.size} weights for {self.n_terms} stage terms"
+ raise BackendError(msg)
+ w_hi, w_lo = _split(w)
+ return mx.array(w_hi), mx.array(w_lo)
+
+ def pair(self, w_hi: mx.array, w_lo: mx.array) -> tuple[mx.array, mx.array]:
+ """Return ``exp(sum_t w_t T_t)`` and its inverse from one combination.
+
+ On the Metal device only; each equals :meth:`exponential` at its sign. Its
+ inputs are device arrays, so a compiled graph may call it.
+
+ Parameters
+ ----------
+ w_hi, w_lo : mlx.core.array
+ The weights' heads and tails (:meth:`device_weights`).
+
+ Returns
+ -------
+ tuple of mlx.core.array
+ The propagator and its inverse, complex64.
+ """
+ n = math.prod(self.shape)
+ forward_re, forward_im, back_re, back_im = _pair_kernel()( # pyright: ignore[reportCallIssue]
+ inputs=[*self.parts, w_hi, w_lo],
+ template=[("N", n), ("TERMS", self.n_terms)],
+ grid=(n, 1, 1),
+ threadgroup=(min(256, n), 1, 1),
+ output_shapes=[(n,)] * 4,
+ output_dtypes=[mx.float32] * 4,
+ )
+ forward = (forward_re + 1j * forward_im).astype(mx.complex64)
+ back = (back_re + 1j * back_im).astype(mx.complex64)
+ return forward.reshape(self.shape), back.reshape(self.shape)
+
+ def combination(self, w_hi: mx.array, w_lo: mx.array) -> mx.array:
+ """Return ``sum_t w_t T_t`` rounded once to complex64, from device weights.
+
+ :meth:`combine` with weights already on the device (:meth:`device_weights`).
+
+ Parameters
+ ----------
+ w_hi, w_lo : mlx.core.array
+ The weights' heads and tails.
+
+ Returns
+ -------
+ mlx.core.array
+ The combination.
+ """
+ n = math.prod(self.shape)
+ out_re, out_im = _kernel()( # pyright: ignore[reportCallIssue]
+ inputs=[*self.parts, w_hi, w_lo],
+ template=[
+ ("N", n),
+ ("TERMS", self.n_terms),
+ ("EXPONENTIAL", 0),
+ ("SIGN", 1),
+ ],
+ grid=(n, 1, 1),
+ threadgroup=(min(256, n), 1, 1),
+ output_shapes=[(n,), (n,)],
+ output_dtypes=[mx.float32, mx.float32],
+ )
+ return (out_re + 1j * out_im).astype(mx.complex64).reshape(self.shape)
+
+ def moments(
+ self, w_hi: mx.array, w_lo: mx.array, count: int
+ ) -> tuple[mx.array, mx.array]:
+ """Return ``exp(x)`` and ``k! phi_{k+1}(x)`` for ``k < count``, ``x = sum w T``.
+
+ An exponential Adams trial's flow and moments (SEP 16) in double-float, each
+ rounded once to complex64 (:meth:`trial` without a compensation). On the
+ Metal device only.
+
+ Parameters
+ ----------
+ w_hi, w_lo : mlx.core.array
+ The weights' heads and tails (:meth:`device_weights`).
+ count : int
+ The moments, at most :data:`~solprop.backends.exponential.MAX_PHI_ORDER`.
+
+ Returns
+ -------
+ tuple of mlx.core.array
+ The flow, of :attr:`shape`, and the moments, ``(count, *shape)``.
+ """
+ flow, moments, _ = self._trial(w_hi, w_lo, count, np.zeros(0), endpoint=False)
+ return flow, moments
+
+ def trial(
+ self,
+ weights: np.ndarray,
+ count: int,
+ spans: np.ndarray,
+ *,
+ endpoint: bool,
+ ) -> tuple[mx.array, mx.array, list[mx.array]]:
+ """Return an exponential Adams trial's flow, moments and compensation factors.
+
+ One pass over the terms, in double-float, every output rounded once:
+ ``exp(x)`` and ``k! phi_{k+1}(x)`` -- the reference's far recurrence beyond
+ its join and its scaled series and doubling within it
+ (:func:`solprop.backends.exponential.phi_functions`), ``exp`` reduced by whole
+ turns of a double-float ``2 pi`` -- with ``x`` the first row's combination;
+ then for each span ``s_j`` the factor ``exp(s_j x) R_j``, ``R_j`` the
+ combination of row ``1 + j``; then, with `endpoint`, the last row's
+ combination alone. On the Metal device only.
+
+ Parameters
+ ----------
+ weights : numpy.ndarray
+ Binary64 weights over the terms, ``(n_rows, n_terms)``: ``x``'s, each
+ history sample's difference of rates, and the endpoint's.
+ count : int
+ The moments, at most :data:`~solprop.backends.exponential.MAX_PHI_ORDER`.
+ spans : numpy.ndarray
+ ``s_j``, binary64, one per history sample.
+ endpoint : bool
+ Whether the last row is the endpoint's.
+
+ Returns
+ -------
+ tuple
+ The flow, of :attr:`shape`; the moments, ``(count, *shape)``; and the
+ samples' factors then the endpoint's, each of :attr:`shape`.
+
+ Raises
+ ------
+ BackendError
+ If the weights do not match the terms or the rows.
+ """
+ rows = np.asarray(weights, dtype=np.float64)
+ if rows.shape != (1 + len(spans) + int(endpoint), self.n_terms):
+ msg = f"trial weights of shape {rows.shape} for {self.n_terms} terms"
+ raise BackendError(msg)
+ hi, lo = _split(rows.reshape(-1))
+ return self._trial(
+ mx.array(hi), mx.array(lo), count, np.asarray(spans), endpoint=endpoint
+ )
+
+ def _trial(
+ self,
+ w_hi: mx.array,
+ w_lo: mx.array,
+ count: int,
+ spans: np.ndarray,
+ *,
+ endpoint: bool,
+ ) -> tuple[mx.array, mx.array, list[mx.array]]:
+ """Launch the trial kernel (:meth:`trial`) on weights already on the device.
+
+ Parameters
+ ----------
+ w_hi, w_lo : mlx.core.array
+ The rows' heads and tails, flattened.
+ count : int
+ The moments.
+ spans : numpy.ndarray
+ ``s_j``, binary64.
+ endpoint : bool
+ Whether the last row is the endpoint's.
+
+ Returns
+ -------
+ tuple
+ As :meth:`trial`.
+ """
+ n = math.prod(self.shape)
+ factorials = np.array(
+ [1.0 / math.factorial(k) for k in range(count + 1)], dtype=np.float64
+ )
+ hi, lo = _split(factorials)
+ span_hi, span_lo = _split(np.asarray(spans, dtype=np.float64))
+ n_factors = len(spans) + int(endpoint)
+ span_pairs = (
+ np.stack([span_hi, span_lo], axis=1)
+ if len(spans)
+ else np.zeros((1, 2), np.float32)
+ )
+ outputs = _moments_kernel()( # pyright: ignore[reportCallIssue]
+ inputs=[
+ *self.parts,
+ w_hi,
+ w_lo,
+ mx.array(np.stack([hi, lo], axis=1)),
+ mx.array(span_pairs),
+ ],
+ template=[
+ ("N", n),
+ ("TERMS", self.n_terms),
+ ("P", count),
+ ("SLOTS", len(spans)),
+ ("ENDPOINT", int(endpoint)),
+ ],
+ grid=(n, 1, 1),
+ threadgroup=(min(256, n), 1, 1),
+ output_shapes=[(n,), (n,), (count * n,), (count * n,)]
+ + [(max(n_factors, 1) * n,)] * 2,
+ output_dtypes=[mx.float32] * 6,
+ )
+ flow_re, flow_im, moments_re, moments_im, factors_re, factors_im = outputs
+ flow = (flow_re + 1j * flow_im).astype(mx.complex64).reshape(self.shape)
+ moments = (moments_re + 1j * moments_im).astype(mx.complex64)
+ factors = (factors_re + 1j * factors_im).astype(mx.complex64)
+ return (
+ flow,
+ moments.reshape(count, *self.shape),
+ [
+ factors[j * n : (j + 1) * n].reshape(self.shape)
+ for j in range(n_factors)
+ ],
+ )
+
def _evaluate(
self, weights: np.ndarray, *, exponential: int, sign: int
) -> mx.array:
@@ -372,7 +878,25 @@ def _population_kernel() -> object:
)
-def population(exposure: mx.array, preionisation: float) -> tuple[mx.array, mx.array]:
+def population_parameters(preionisation: float) -> np.ndarray:
+ """Return the population kernel's parameters, ``(1 - p, p)`` rounded to binary32.
+
+ Parameters
+ ----------
+ preionisation : float
+ ``p`` in ``[0, 1]``.
+
+ Returns
+ -------
+ numpy.ndarray
+ Float32, ``(2,)``.
+ """
+ return np.array([1.0 - preionisation, preionisation], dtype=np.float32)
+
+
+def population(
+ exposure: mx.array, preionisation: float | mx.array
+) -> tuple[mx.array, mx.array]:
"""Return the ionised fraction and the neutral survival in their stable forms.
The oracle's ``stable_population`` (SEP 33 section 4.4): ``f = p + (1 - p)
@@ -385,17 +909,21 @@ def population(exposure: mx.array, preionisation: float) -> tuple[mx.array, mx.a
----------
exposure : mlx.core.array
``X``, float32, non-negative.
- preionisation : float
- ``p`` in ``[0, 1]``.
+ preionisation : float or mlx.core.array
+ ``p`` in ``[0, 1]``, or on the Metal device the kernel's parameters
+ (:func:`population_parameters`) already on it, as a compiled stage passes them.
Returns
-------
tuple of mlx.core.array
The fraction and the survival, float32.
"""
- keep = float(np.float32(1.0 - preionisation))
- initial = float(np.float32(preionisation))
+ if isinstance(preionisation, mx.array):
+ parameters = preionisation
+ else:
+ parameters = mx.array(population_parameters(preionisation))
if not on_gpu():
+ keep, initial = (float(value) for value in np.array(parameters))
# MLX's CPU exp errs by up to 3e-6 relative near exp(-80); on the CPU device
# the host's binary64 forms, rounded once, are the oracle's own.
wide = np.array(exposure, dtype=np.float64)
@@ -407,7 +935,7 @@ def population(exposure: mx.array, preionisation: float) -> tuple[mx.array, mx.a
flat = exposure.reshape(-1)
n = flat.size
fraction, survival = _population_kernel()( # pyright: ignore[reportCallIssue]
- inputs=[flat, mx.array(np.array([keep, initial], dtype=np.float32))],
+ inputs=[flat, parameters],
template=[("N", n)],
grid=(n, 1, 1),
threadgroup=(min(256, n), 1, 1),
@@ -440,6 +968,14 @@ def population(exposure: mx.array, preionisation: float) -> tuple[mx.array, mx.a
}
"""
+_SCAN_THREADS = (512, 1024)
+"""A row's threads in the scan: 512 when there are many rows, 1024 for a few.
+
+On an Apple M5 Max (MLX 0.32) against the 256 before, chained scans: one row of 16383
+took 62 us against 105, sixteen of 8191 43 against 65, and 1024 rows of 2047 114
+against 116. Holding the row in threadgroup memory was slower at every shape.
+"""
+
@cache
def _scan_kernel() -> object:
@@ -474,11 +1010,13 @@ def prefix_scan(values: mx.array) -> mx.array:
"""
n = values.shape[-1]
rows = values.size // n
+ # Enough threads for the row in whole SIMD groups, up to the shape's width.
+ width = min(_SCAN_THREADS[rows < 64], 32 * math.ceil(n / 32))
out, _ = _scan_kernel()( # pyright: ignore[reportCallIssue]
inputs=[values.reshape(rows, n)],
template=[("N", n)],
- grid=(rows * 256, 1, 1),
- threadgroup=(256, 1, 1),
+ grid=(rows * width, 1, 1),
+ threadgroup=(width, 1, 1),
output_shapes=[(rows, n), (rows, n)],
output_dtypes=[mx.float32, mx.float32],
)
diff --git a/src/solprop/backends/mlx_gpu/backend.py b/src/solprop/backends/mlx_gpu/backend.py
index e56f48137..f45cf48d2 100644
--- a/src/solprop/backends/mlx_gpu/backend.py
+++ b/src/solprop/backends/mlx_gpu/backend.py
@@ -22,14 +22,16 @@
"""
import math
-from collections.abc import Mapping, Sequence
+import os
+from collections.abc import Iterator, Mapping, Sequence
from dataclasses import dataclass
-from typing import Any, cast
+from typing import Any, Literal, cast
import mlx.core as mx # pyright: ignore[reportMissingImports] - macOS arm64 only
import numpy as np
from jaxtyping import Complex
+from solprop._helpers import PLAIN, Helpers
from solprop.backends.memory import mlx_bounded, mlx_graph_bytes, mlx_stage_bytes
from solprop.backends.mlx_gpu import passes as device
from solprop.backends.mlx_gpu.arithmetic import (
@@ -38,29 +40,33 @@
gemm_probe,
on_gpu,
population,
+ population_parameters,
prefix_scan,
)
from solprop.backends.mlx_gpu.envelope import DeviceCycle, envelope_cycle
+from solprop.backends.numpy_ref.backend import QUADRATURE_ALARM
+from solprop.backends.numpy_ref.backend import logger as oracle_logger
from solprop.backends.numpy_ref.passes import _kerr as compiled_kerr
from solprop.backends.numpy_ref.passes import _raman_thg as raman_thg
from solprop.backends.numpy_ref.single import NumpySingleBackend
+from solprop.backends.populations import population_statistics
from solprop.boundaries import SPLIT_RATE_BUCKETS
from solprop.constants import EPS0
from solprop.exceptions import BackendError, ConvergenceError
-from solprop.grid import TimeGrid
+from solprop.grid import FreeGrid, LineGrid, RadialGrid, TimeGrid
from solprop.modes.protocol import Mode
from solprop.monitor import BoundaryEnergies, BoundaryMonitor
from solprop.profiles import ZProfile
from solprop.stepper.low_storage import LowStorageRungeKutta
from solprop.stepper.multistep import Multistep
from solprop.translate.envelope_plasma import EnvelopePlasmaAssembly
-from solprop.translate.linop import _separable_phase
from solprop.translate.precision import combine, narrow
from solprop.translate.problem import KernelProblem
from solprop.translate.responses import ResponseStage
-from solprop.translate.spatial import separable_values
+from solprop.translate.spatial import SeparableOperator, separable_values
from solprop.translate.stage import StageScalars
from solprop.translate.tdse import TDSEBinding
+from solprop.transverse_monitor import TransverseEdge, _EdgeReading
__all__ = ["DeviceSources", "MlxBackend", "MlxLowStorage", "refuse_unsupported"]
@@ -96,6 +102,89 @@ class DeviceSources:
current: mx.array | None
+_FUSED = os.environ.get("SOLPROP_MLX_FUSED", "1") != "0"
+"""Whether a Metal run compiles each stage with ``mx.compile`` (the default).
+
+A compiled stage fuses the stage's element-wise passes into few kernels and replays
+its graph without rebuilding it in Python. MLX compiles every operation with the
+eager kernel's rounding (no contraction to fused multiply-adds, no reassociation),
+except ``log1p``, whose compiled form is as accurate but not the same function.
+``SOLPROP_MLX_FUSED=0`` evaluates operation by operation, for comparisons.
+"""
+
+_TRANSPORT_REACH = 0.9 * math.log(float(np.finfo(np.float32).max))
+"""The bound on a trial's ``|Re dPhi|`` past which its stages are combined in the lab
+frame (:meth:`MlxBackend._trial_graph`): nine tenths of binary32's ``log FLT_MAX``."""
+
+try:
+ from solprop_native._helpers import ( # pyright: ignore[reportMissingImports]
+ NATIVE as _HELPERS,
+ )
+except ImportError: # the native package is optional: its forms are bitwise PLAIN's
+ _HELPERS: Helpers = PLAIN
+
+_HEAD = 5
+"""The stage values before the channels': the taper and its inverse, Kerr's factor
+and harmonic factor, and Raman's factor (:class:`_StageValues`)."""
+
+
+@dataclass(frozen=True)
+class _StageValues:
+ """A stage's position-dependent coefficients as one float32 device vector.
+
+ Each value is formed on the host in binary64 and rounded once, as the stage's
+ passes rounded the host scalars they were given, so that a compiled stage takes
+ them as inputs rather than as constants of its graph. The layout: the taper scale
+ and its inverse, Kerr's factor and its harmonic factor, Raman's factor, then four
+ values per field-grid plasma channel (the Drude and the ionisation-loss factors,
+ and the population's ``1 - p`` and ``p``) and four per envelope-plasma channel
+ (the drive's and the loss's factors, then ``1 - p`` and ``p``).
+
+ Attributes
+ ----------
+ vector : mlx.core.array
+ The float32 values.
+ plasma : int
+ Field-grid plasma channels.
+ """
+
+ vector: mx.array
+ plasma: int
+
+ def __getitem__(self, index: int) -> mx.array:
+ """Return one value, a float32 device scalar.
+
+ Parameters
+ ----------
+ index : int
+ Its position in the layout.
+
+ Returns
+ -------
+ mlx.core.array
+ The value.
+ """
+ return self.vector[index]
+
+ def channel(self, index: int, *, envelope: bool = False) -> mx.array:
+ """Return a channel's four values.
+
+ Parameters
+ ----------
+ index : int
+ The channel.
+ envelope : bool, optional
+ Whether it is an envelope-plasma channel.
+
+ Returns
+ -------
+ mlx.core.array
+ ``(4,)``: the two factors, then the population's parameters.
+ """
+ first = _HEAD + 4 * (index + (self.plasma if envelope else 0))
+ return self.vector[first : first + 4]
+
+
def _summed(totals: list[mx.array], parts: list[mx.array]) -> list[mx.array]:
"""Return two lists of arrays summed element by element.
@@ -135,6 +224,43 @@ def _restored(value: float, power: float, exponent: int) -> float:
return math.ldexp(value, 2 * int(power) + exponent)
+def _separable_tables(
+ separable: SeparableOperator,
+) -> tuple[np.ndarray, np.ndarray]:
+ """Return a separable operator at unit distance and its prefactor, in one pass.
+
+ ``translate.linop._separable_phase`` at unit distance and the prefactor of
+ :func:`~solprop.translate.spatial.separable_values`, bitwise, from one evaluation
+ of each bounded chunk of columns rather than one for each (seconds apiece on a
+ 384^2 x 750 grid).
+
+ Parameters
+ ----------
+ separable : solprop.translate.spatial.SeparableOperator
+ The constant-medium coefficients.
+
+ Returns
+ -------
+ tuple of numpy.ndarray
+ The operator, of ``value_shape``, and the prefactor, without its leading
+ batch axis.
+ """
+ shape = separable.value_shape
+ operator = np.empty(shape, dtype=np.complex128)
+ prefactor: np.ndarray | None = None
+ # _separable_phase's 64 MiB workspace ceiling.
+ chunk = max(1, (64 << 20) // (8 * 16 * len(separable.k_squared)))
+ for first in range(0, shape[1], chunk):
+ rows = slice(first, first + chunk)
+ values, factor = separable_values(separable, rows)
+ operator[:, rows] = values
+ if prefactor is None:
+ prefactor = np.empty(shape[1:], dtype=factor.dtype)
+ prefactor[rows] = factor
+ assert prefactor is not None
+ return operator, prefactor
+
+
def refuse_unsupported(problem: KernelProblem) -> None:
"""Refuse, by name, what the ``mlx`` backend does not run in this phase.
@@ -155,6 +281,8 @@ def refuse_unsupported(problem: KernelProblem) -> None:
"binary64 backend (native, numpy_ref)"
)
stepper = problem.stepper
+ method = stepper.integrator
+ adams = isinstance(method, Multistep)
refusals = [
(
not problem.device_ready,
@@ -163,8 +291,9 @@ def refuse_unsupported(problem: KernelProblem) -> None:
"backend='numpy_ref'",
),
(
- isinstance(stepper.integrator, Multistep),
- "the Adams integrator, which single precision does not admit",
+ adams and cast(Multistep, method).formulation != "exponential",
+ "the Adams integrator's interaction formulation; use the exponential "
+ "one, Multistep() by default",
),
(
stepper.interpolate_planes,
@@ -206,6 +335,12 @@ class MlxBackend(NumpySingleBackend):
name = "mlx"
+ # SEP 29 section 6.6: the stage tables' Chebyshev rows and the Adams basis from the
+ # native package's compiled record, which performs the reference's operations in
+ # its order (bitwise its results); only numpy_ref must keep the Python forms. An
+ # install without the native package takes those forms, the same numbers slower.
+ helpers = _HELPERS
+
_monitor_weights: mx.array | None = None
"""The boundary monitor's four weight rows on the device, each narrowed with its
own exponent (:attr:`_monitor_exponents`), while a monitor is bound (SEP 21)."""
@@ -230,12 +365,16 @@ class MlxBackend(NumpySingleBackend):
``uint8`` as the problem holds it, while a monitor of a split run is bound; ``None``
otherwise. A reading widens it to an index on the fly."""
+ _pending_alarm: tuple[mx.array, float] | None = None
+ """The last accepted step's quadrature alarm on the device and its position, not
+ yet read (:meth:`_update_alarm`)."""
+
_pending_found: tuple[mx.array, ...] = ()
"""The energy and the guards' energies of what the last accepted step's split found,
not yet read: device scalars with their rule-6 exponent (:meth:`_device_removal`),
restored into :attr:`_split_found` at the next synchronisation."""
- def __init__(
+ def __init__( # noqa: PLR0915 - one upload per table, each held for the run
self,
problem: KernelProblem,
*,
@@ -295,6 +434,41 @@ def __init__(
self._upload_envelope(responses.envelope_plasma)
self._raman_upload: tuple[object, mx.array] | None = None
self._unit = mx.ones((1,), dtype=mx.complex64)
+ geometry = transform.geometry
+ # The Cartesian collar's per-column rate, narrowed once (it is the problem's).
+ self._free_rate = (
+ None
+ if geometry is None or self._free_prefactor is None
+ else mx.array(self._cast(geometry.absorber_rate))
+ )
+ # Each stage is one compiled graph on the Metal device (_FUSED); its inputs are
+ # the lab field, the inverse propagator, the prefactor, the Raman spectrum and
+ # the stage's values, and everything else it reads is the problem's, fixed
+ # for the backend's life. MLX's CPU device evaluates op by op: its population
+ # and envelope plasma run on the host.
+ self._fused = _FUSED and on_gpu()
+ # First-same-as-last (DOPRI5): the last stage of an accepted step is the next
+ # step's first, as native reuses it, unless the step's finish changes the state
+ # (the split-step collar). The reuse is exact: the last stage's input is the
+ # accepted state, and the first stage's propagators are exactly one.
+ tableau = problem.stepper.tableau
+ self._fsal = bool(
+ tableau is not None
+ and tableau.first_same_as_last
+ and problem.responses.absorber_scheme != "split_step"
+ )
+ self._first: tuple[float, Any, mx.array] | None = None
+ self._edge_matrix: mx.array | None = None
+ self._pending_first: tuple[float, mx.array] | None = None
+ self._last_source: mx.array | None = None
+ compiled = mx.compile if self._fused else (lambda function: function)
+ self._stage_function = compiled(self._stage_core)
+ self._stage_input = compiled(self._stage_input_core)
+ self._trial_end = compiled(self._trial_end_core)
+ self._norm_sums = compiled(self._norm_sums_core)
+ self._transported_input = compiled(self._transported_input_core)
+ self._transported_end = compiled(self._transported_end_core)
+ self._alarm_ratio = compiled(self._alarm_ratio_core)
# Whether each stage is evaluated as it is formed, bounding the live graph to
# one stage; a batch evaluates its members' steps together instead.
self.evaluate_stages = mlx_bounded(
@@ -364,10 +538,8 @@ def _upload_operator(self, problem: KernelProblem) -> None:
if separable is not None:
# A separable operator is one term linear in the distance: the operator
# at unit distance, weighted by the bundle's dz (translate.linop).
- self._phi = DoubleFloatTerms.upload(
- _separable_phase(separable, 1.0, imaginary=False)[None]
- )
- _, prefactor = separable_values(separable)
+ operator, prefactor = _separable_tables(separable)
+ self._phi = DoubleFloatTerms.upload(operator[None])
self._free_prefactor = mx.array(self._cast(prefactor))
elif self._terms.phi is None:
raise BackendError("mlx needs the operator's device-ready terms")
@@ -406,6 +578,7 @@ def set_initial(
"""
super().set_initial(field, noise, z=z, resume=resume)
self._state = cast(Any, mx.array(np.asarray(self._require_state())))
+ self._first = self._pending_first = None
def _observed_field(
self, state: Any
@@ -467,6 +640,12 @@ def _finish(self, state: Any, dz: float) -> Any:
If the state is not finite.
"""
finished = state * self._active
+ if self._pending_first is not None:
+ # The accepted state is the last stage's input: masking leaves it as it is,
+ # its bins outside the band being zero, so that stage is the next first.
+ position, source = self._pending_first
+ self._first = (position, finished, source)
+ self._pending_first = None
responses = self._problem.responses
rate = responses.temporal_absorber
if rate is not None and responses.absorber_scheme == "split_step":
@@ -595,8 +774,12 @@ def _synchronised(self, values: list[mx.array]) -> np.ndarray:
"""
pending, self._pending_removal = self._pending_removal, ()
found, self._pending_found = self._pending_found, ()
- flat = [value.reshape(-1) for value in (*values, *found, *pending)]
+ alarm = () if self._pending_alarm is None else (self._pending_alarm[0],)
+ flat = [value.reshape(-1) for value in (*values, *found, *pending, *alarm)]
read = np.array(mx.concatenate(flat), dtype=np.float64)
+ if alarm:
+ self._resolve_alarm(float(read[-1]))
+ read = read[:-1]
count = sum(int(value.size) for value in values)
removals = count
if found:
@@ -769,19 +952,52 @@ def _trial_graph(self, z: float, dz: float) -> tuple[mx.array, mx.array, mx.arra
z, [z + dz, *(z + float(node) * dz for node in tableau.nodes)]
)
step = self._stage_scalars(z, z + dz)
+ # dz as a float32 device scalar, as a product with the state rounds it.
+ length = mx.array(dz, dtype=mx.float32)
+ # One propagator pair per distinct stage fraction: DOPRI5 reaches the step's
+ # end three times (its last two stages and the step itself).
+ pairs: dict[bytes, tuple[mx.array, mx.array]] = {}
stages: list[mx.array] = []
- solution = mx.zeros_like(state)
- error = mx.zeros_like(state)
- for index, node in enumerate(tableau.nodes):
- combination = mx.zeros_like(state)
- for previous in range(index):
- weight = float(tableau.matrix[index, previous])
- if weight != 0.0:
- combination = combination + weight * stages[previous]
- bundle = self._stage_scalars(z, z + float(node) * dz)
- forward, back = self._propagators(bundle)
- lab = forward * (state + dz * combination)
- stage = self._device_nonlinear(lab, bundle, back)
+ last = len(tableau.nodes) - 1
+ bundles = [
+ self._stage_scalars(z, z + float(node) * dz) for node in tableau.nodes
+ ]
+ # Past binary32's range the inverse propagator overflows: the stages are then
+ # combined in the lab frame, each carried by exp(Phi(c_i) - Phi(c_j)), a forward
+ # flow since the nodes never decrease, and no inverse is formed.
+ transported = self._needs_transport([step, *bundles])
+ flows: dict[bytes, mx.array] = {}
+ for index, bundle in enumerate(bundles):
+ first = self._first
+ if index == 0 and first is not None and first[0] == z and first[1] is state:
+ # First-same-as-last: the stage is the source at the state itself,
+ # evaluated already -- as the last stage of the step that reached it,
+ # or as this anchor's first stage before a rejection.
+ stages.append(first[2])
+ continue
+ if transported:
+ forward = self._forward_flow(bundle.phi_delta, flows)
+ factors = [
+ self._forward_flow(
+ np.asarray(bundle.phi_delta) - np.asarray(earlier.phi_delta),
+ flows,
+ )
+ for earlier in bundles[: len(stages)]
+ ]
+ lab = self._transported_input(state, stages, factors, forward, length)
+ # The source itself: a stage of this form is untransported.
+ stage = self._device_nonlinear(lab, bundle, self._unit)
+ else:
+ forward, back = self._propagator_pair(bundle, pairs)
+ lab = self._stage_input(state, stages, forward, length)
+ stage = self._device_nonlinear(lab, bundle, back)
+ if self._fsal and index == 0:
+ self._first = (z, state, stage)
+ elif self._fsal and index == last:
+ # Its input is the trial state itself: the next step's first stage,
+ # if this one is accepted with no change to the state (_finish).
+ assert self._last_source is not None # set by the stage just formed
+ self._pending_first = (z + dz, self._last_source)
# Evaluated at each stage boundary: the graph of one stage -- its node
# chunks and the scans' levels -- is then the most that is ever live
# (SEP 33 section 6.3), where a whole step's graph would hold seven.
@@ -789,13 +1005,147 @@ def _trial_graph(self, z: float, dz: float) -> tuple[mx.array, mx.array, mx.arra
# The previous split's pending removal with the first stage, which
# evaluates the state it was taken from: its time samples go then.
mx.eval(stage, *self._pending_removal)
+ elif self._fused:
+ # Started at once, so the device runs this stage while the host
+ # builds the next; the norm's read waits for all of them.
+ mx.async_eval(stage)
stages.append(stage)
- solution = solution + float(tableau.solution_weights[index]) * stage
- error = error + float(tableau.error_weights[index]) * stage
- propagator, _ = self._propagators(step)
- advanced = propagator * (state + dz * solution)
+ if transported:
+ factors = [
+ self._forward_flow(
+ np.asarray(step.phi_delta) - np.asarray(bundle.phi_delta), flows
+ )
+ for bundle in bundles
+ ]
+ flow = self._forward_flow(step.phi_delta, flows)
+ carried, advanced = self._transported_end(
+ state, stages, factors, flow, length
+ )
+ else:
+ propagator, _ = self._propagator_pair(step, pairs)
+ carried, advanced = self._trial_end(state, stages, propagator, length)
self._last_stages = stages
- return state, propagator * (dz * error), advanced
+ return state, carried, advanced
+
+ def _needs_transport(self, bundles: list[StageScalars]) -> bool:
+ """Return whether a trial's inverse propagators could overflow binary32.
+
+ Parameters
+ ----------
+ bundles : list of solprop.translate.stage.StageScalars
+ The step's and its stages' scalars.
+
+ Returns
+ -------
+ bool
+ Whether a bound on any ``|Re dPhi|`` passes nine tenths of ``log FLT_MAX``.
+ """
+ if not on_gpu():
+ return False
+ reach = max(
+ self._phi.real_reach(np.asarray(bundle.phi_delta)) for bundle in bundles
+ )
+ return reach > _TRANSPORT_REACH
+
+ def _forward_flow(self, weights: Any, flows: dict[bytes, mx.array]) -> mx.array:
+ """Return ``exp(sum_t w_t T_t)``, once per distinct weights in a trial.
+
+ Parameters
+ ----------
+ weights : numpy.ndarray
+ Binary64 weights over the operator's terms.
+ flows : dict
+ The trial's flows, by their weights' bytes.
+
+ Returns
+ -------
+ mlx.core.array
+ The flow; exactly one for zero weights.
+ """
+ w = np.asarray(weights, dtype=np.float64).reshape(-1)
+ if not np.any(w):
+ return self._unit
+ key = w.tobytes()
+ if key not in flows:
+ flows[key] = self._phi.pair(*self._phi.device_weights(w))[0]
+ return flows[key]
+
+ def _transported_input_core(
+ self,
+ state: mx.array,
+ sources: list[mx.array],
+ factors: list[mx.array],
+ forward: mx.array,
+ length: mx.array,
+ ) -> mx.array:
+ """Return a stage's input in the lab frame, carrying each earlier source.
+
+ ``exp(Phi_i) a + h sum_j a_ij exp(Phi_i - Phi_j) S_j``, the interaction
+ picture's input with its inverse propagators folded into forward flows.
+
+ Parameters
+ ----------
+ state : mlx.core.array
+ The state at the anchor.
+ sources : list of mlx.core.array
+ The earlier stages' sources, untransported.
+ factors : list of mlx.core.array
+ ``exp(Phi_i - Phi_j)`` per earlier stage.
+ forward : mlx.core.array
+ ``exp(Phi_i)``.
+ length : mlx.core.array
+ The step, a float32 scalar.
+
+ Returns
+ -------
+ mlx.core.array
+ The stage's input.
+ """
+ matrix = self._problem.stepper.tableau.matrix
+ index = len(sources)
+ combination = mx.zeros_like(state)
+ for previous, (source, factor) in enumerate(zip(sources, factors, strict=True)):
+ weight = float(matrix[index, previous])
+ if weight != 0.0:
+ combination = combination + weight * (factor * source)
+ return forward * state + length * combination
+
+ def _transported_end_core(
+ self,
+ state: mx.array,
+ sources: list[mx.array],
+ factors: list[mx.array],
+ flow: mx.array,
+ length: mx.array,
+ ) -> tuple[mx.array, mx.array]:
+ """Return the embedded difference and the trial state, in the lab frame.
+
+ Parameters
+ ----------
+ state : mlx.core.array
+ The state at the anchor.
+ sources : list of mlx.core.array
+ Every stage's source, untransported.
+ factors : list of mlx.core.array
+ ``exp(Phi(z + h) - Phi_j)`` per stage.
+ flow : mlx.core.array
+ ``exp(Phi(z + h) - Phi(z))``.
+ length : mlx.core.array
+ The step, a float32 scalar.
+
+ Returns
+ -------
+ tuple of mlx.core.array
+ The embedded difference at the step's end, and the trial state.
+ """
+ tableau = self._problem.stepper.tableau
+ solution = mx.zeros_like(state)
+ error = mx.zeros_like(state)
+ for index, (source, factor) in enumerate(zip(sources, factors, strict=True)):
+ carried = factor * source
+ solution = solution + float(tableau.solution_weights[index]) * carried
+ error = error + float(tableau.error_weights[index]) * carried
+ return length * error, flow * state + length * solution
def _trial_step(self, z: float, dz: float) -> tuple[float, mx.array]: # pyright: ignore[reportIncompatibleMethodOverride]
"""Take one interaction-picture DOPRI5 step on the device and score it.
@@ -815,6 +1165,103 @@ def _trial_step(self, z: float, dz: float) -> tuple[float, mx.array]: # pyright
state, error, advanced = self._trial_graph(z, dz)
return self._device_norm(error, state, advanced), advanced
+ def _stage_input_core(
+ self,
+ state: mx.array,
+ stages: list[mx.array],
+ forward: mx.array,
+ length: mx.array,
+ ) -> mx.array:
+ """Return a stage's lab-frame input, ``exp(dPhi) (a + h sum_j a_ij k_j)``.
+
+ Parameters
+ ----------
+ state : mlx.core.array
+ The state at the anchor.
+ stages : list of mlx.core.array
+ The step's earlier stages; their number is the stage's index.
+ forward : mlx.core.array
+ The stage's propagator.
+ length : mlx.core.array
+ The step's length, a float32 scalar.
+
+ Returns
+ -------
+ mlx.core.array
+ The stage's input.
+ """
+ matrix = self._problem.stepper.tableau.matrix
+ index = len(stages)
+ combination = mx.zeros_like(state)
+ for previous, stage in enumerate(stages):
+ weight = float(matrix[index, previous])
+ if weight != 0.0:
+ combination = combination + weight * stage
+ return forward * (state + length * combination)
+
+ def _trial_end_core(
+ self,
+ state: mx.array,
+ stages: list[mx.array],
+ propagator: mx.array,
+ length: mx.array,
+ ) -> tuple[mx.array, mx.array]:
+ """Return the trial's embedded difference and its state, at the step's end.
+
+ Parameters
+ ----------
+ state : mlx.core.array
+ The state at the anchor.
+ stages : list of mlx.core.array
+ Every stage of the step.
+ propagator : mlx.core.array
+ ``exp(dPhi)`` over the step.
+ length : mlx.core.array
+ The step's length, a float32 scalar.
+
+ Returns
+ -------
+ tuple of mlx.core.array
+ The embedded difference carried to the step's end, and the trial state.
+ """
+ tableau = self._problem.stepper.tableau
+ solution = mx.zeros_like(state)
+ error = mx.zeros_like(state)
+ for index, stage in enumerate(stages):
+ solution = solution + float(tableau.solution_weights[index]) * stage
+ error = error + float(tableau.error_weights[index]) * stage
+ return propagator * (length * error), propagator * (state + length * solution)
+
+ def _propagator_pair(
+ self,
+ bundle: StageScalars,
+ pairs: dict[bytes, tuple[mx.array, mx.array]] | None = None,
+ ) -> tuple[mx.array, mx.array]:
+ """Return a stage's propagator and its inverse, once per distinct exponent.
+
+ Parameters
+ ----------
+ bundle : solprop.translate.stage.StageScalars
+ The stage's host scalars.
+ pairs : dict or None, optional
+ The pairs this trial has formed, keyed by their weights' bytes.
+
+ Returns
+ -------
+ tuple of mlx.core.array
+ ``exp(dPhi)`` and ``exp(-dPhi)``.
+ """
+ assert bundle.phi_delta is not None # device-ready, refused otherwise
+ if not on_gpu():
+ return self._propagators(bundle)
+ key = np.asarray(bundle.phi_delta, dtype=np.float64).tobytes()
+ if pairs is not None and key in pairs:
+ return pairs[key]
+ pair = self._phi.pair(*self._phi.device_weights(bundle.phi_delta))
+ if pairs is not None:
+ pairs[key] = pair
+ return pair
+
def _propagators(self, bundle: StageScalars) -> tuple[mx.array, mx.array]:
"""Return ``exp(dPhi)`` and ``exp(-dPhi)`` of a stage, double-float accurate.
@@ -874,11 +1321,87 @@ def _device_raman(self, bundle: StageScalars) -> mx.array | None:
self._raman_upload = (spectrum, mx.array(spectrum))
return self._raman_upload[1]
- def _device_nonlinear( # noqa: PLR0915 - the oracle's modal stage, pass by pass
+ def _stage_values(self, bundle: StageScalars) -> _StageValues:
+ """Form a stage's position-dependent coefficients on the host and upload them.
+
+ Parameters
+ ----------
+ bundle : solprop.translate.stage.StageScalars
+ The stage's host scalars.
+
+ Returns
+ -------
+ _StageValues
+ The values, each rounded once from binary64.
+ """
+ responses = self._problem.responses
+ k = self._scale_exponent
+ taper = bundle.taper_scale
+ values = [taper, 1.0 / taper, 0.0, 0.0, 0.0]
+ if ResponseStage.KERR in responses.response_order:
+ kerr = compiled_kerr(responses)
+ factor = combine(
+ kerr.coefficient, bundle.kerr_density, exponent=2 * k
+ ).binary32()
+ values[2:4] = [factor, factor * kerr.harmonic_factor]
+ if ResponseStage.RAMAN_DRIVE in responses.response_order:
+ density = (
+ 1.0
+ if len(responses.raman_terms) > 1
+ else bundle.raman_densities[0]
+ if bundle.raman_densities
+ else bundle.density
+ )
+ values[4] = combine(
+ EPS0, density, exponent=2 * k + self._raman_exponent
+ ).binary32()
+ channels = responses.plasma_channels
+ if channels:
+ if len(channels) > 1:
+ densities = bundle.plasma_densities
+ initials = bundle.plasma_preionisation
+ else:
+ densities = (
+ bundle.plasma_densities[0]
+ if bundle.plasma_densities
+ else bundle.density,
+ )
+ initials = (bundle.preionisation,)
+ for channel, density, initial in zip(
+ channels, densities, initials, strict=True
+ ):
+ values += [
+ density * channel.charge_mass_ratio * channel.electrons_per_event,
+ density * channel.ionisation_potential,
+ *population_parameters(initial).tolist(),
+ ]
+ envelope = responses.envelope_plasma
+ if envelope is not None:
+ for channel, density, initial in zip(
+ envelope.channels,
+ bundle.plasma_densities,
+ bundle.plasma_preionisation,
+ strict=True,
+ ):
+ values += [
+ combine(channel.charge_mass_ratio, density).binary32(),
+ combine(
+ channel.ionisation_potential, density, exponent=-k
+ ).binary32(),
+ *population_parameters(initial).tolist(),
+ ]
+ return _StageValues(mx.array(np.array(values, dtype=np.float32)), len(channels))
+
+ def _device_nonlinear(
self, lab: mx.array, bundle: StageScalars, back: mx.array
) -> mx.array:
"""Evaluate one stage derivative on the device.
+ The host forms the stage's prefactor, Raman spectrum and values, and
+ :meth:`_stage_core` evaluates the stage from them, compiled on the Metal
+ device; what it returns beside the derivative -- the projections the alarm
+ reads and the envelope plasma's failures -- is kept here.
+
Parameters
----------
lab : mlx.core.array
@@ -893,6 +1416,63 @@ def _device_nonlinear( # noqa: PLR0915 - the oracle's modal stage, pass by pass
mlx.core.array
The stage derivative in the interaction variable.
"""
+ # The Raman spectrum first: forming it sets the block exponent that Raman's
+ # factor among the values carries.
+ raman = self._device_raman(bundle)
+ inputs = {
+ "lab": lab,
+ "back": back,
+ # The Cartesian route applies its own prefactor (_free_prefactor).
+ "prefactor": self._unit
+ if self._free_prefactor is not None
+ else self._device_prefactor(bundle),
+ "values": self._stage_values(bundle).vector,
+ }
+ if raman is not None:
+ inputs["raman"] = raman
+ if self._fused:
+ outputs = self._stage_function(inputs)
+ else:
+ outputs = self._stage_core(inputs, bundle)
+ self._envelope_failures += outputs.get("failures", [])
+ if "projected" in outputs:
+ plasma = outputs.get("plasma")
+ self._last_projected = outputs["projected"] # pyright: ignore[reportAttributeAccessIssue]
+ self._last_coarse = outputs.get("coarse") # pyright: ignore[reportAttributeAccessIssue]
+ self._last_plasma = None if plasma is None else tuple(plasma) # pyright: ignore[reportAttributeAccessIssue]
+ envelope = outputs.get("envelope")
+ self._last_envelope = None if envelope is None else tuple(envelope) # pyright: ignore[reportAttributeAccessIssue]
+ self._last_bundle = bundle
+ # The stage's source before its inverse propagator: the last stage's is the
+ # next step's first (first-same-as-last, _trial_graph).
+ self._last_source = outputs["source"]
+ return outputs["stage"]
+
+ def _stage_core( # noqa: PLR0912, PLR0915 - the oracle's modal stage, pass by pass
+ self, inputs: dict[str, mx.array], bundle: StageScalars | None = None
+ ) -> dict[str, Any]:
+ """Evaluate one stage derivative from its device inputs alone.
+
+ Everything else it reads is the problem's and fixed, so that ``mx.compile``
+ may trace it once per input structure.
+
+ Parameters
+ ----------
+ inputs : dict of mlx.core.array
+ ``lab``, ``back`` (``exp(-dPhi)``), ``prefactor`` and ``values`` (the
+ stage's :class:`_StageValues` vector), and ``raman`` with Raman.
+ bundle : solprop.translate.stage.StageScalars or None, optional
+ The stage's host scalars, for the host evaluations of MLX's CPU device;
+ never given to a compiled stage.
+
+ Returns
+ -------
+ dict
+ ``stage``, the derivative, and ``source``, the same before the inverse
+ propagator; on the modal route without its radial plasma
+ also ``projected``, and ``coarse``, ``plasma`` and ``envelope`` where they
+ exist; ``failures``, the envelope plasma's, when it runs.
+ """
problem = self._problem
grids, responses, transform = (
problem.grids,
@@ -900,19 +1480,25 @@ def _device_nonlinear( # noqa: PLR0915 - the oracle's modal stage, pass by pass
problem.transform,
)
kind = self._kind
+ lab, back = inputs["lab"], inputs["back"]
+ values = _StageValues(inputs["values"], len(responses.plasma_channels))
+ raman = inputs.get("raman")
+ failures: list[mx.array] = []
if self._free_prefactor is not None:
- return self._device_free(lab, bundle, back)
+ source = self._device_free(lab, values, raman, failures, bundle)
+ return {"stage": back * source, "source": source, "failures": failures}
modal_t = device.to_time(lab[0], self._pad_crop, grids.n_to, kind=kind)
absorber = self._device_absorber(modal_t)
if self._radial_plasma:
- spectrum = self._device_radial_plasma(modal_t, bundle)
- return back * self._normalised(spectrum, bundle, absorber)[None]
+ spectrum = self._device_radial_plasma(modal_t, values, raman)
+ source = self._normalised(spectrum, inputs["prefactor"], absorber)[None]
+ return {"stage": back * source, "source": source}
if len(responses.response_order) == 1:
if absorber is None:
- return mx.zeros_like(lab)
- return back * absorber[None]
- raman = self._device_raman(bundle)
- taper = bundle.taper_scale
+ zero = mx.zeros_like(lab)
+ return {"stage": zero, "source": zero}
+ return {"stage": back * absorber[None], "source": absorber[None]}
+ taper, inverse = values[0], values[1]
n_pol = transform.n_pol
# Per stream (the polarisation, the plasma's gated and edge currents, the
# envelope plasma's drive and loss), the projection on the fine quadrature
@@ -923,7 +1509,7 @@ def _device_nonlinear( # noqa: PLR0915 - the oracle's modal stage, pass by pass
for first in range(0, transform.n_nodes, transform.node_chunk):
rows = slice(first * n_pol, (first + transform.node_chunk) * n_pol)
field = device.synthesise(modal_t, self._synthesis[rows], taper, n_pol)
- sources = self._device_sources(field, bundle, raman)
+ sources = self._device_sources(field, values, raman)
streams = [sources.polarisation]
if sources.current is not None:
plasma = True
@@ -933,42 +1519,43 @@ def _device_nonlinear( # noqa: PLR0915 - the oracle's modal stage, pass by pass
]
if self._cycles:
envelope = True
- streams += list(self._device_envelope(field, bundle))
+ streams += list(self._device_envelope(field, values, failures, bundle))
parts = device.project_many(
- streams, self._projection[:, rows], taper, n_pol
+ streams, self._projection[:, rows], inverse, n_pol
)
fine = parts if fine is None else _summed(fine, parts)
if self._coarse is not None:
parts = device.project_many(
- streams, self._coarse[:, rows], taper, n_pol
+ streams, self._coarse[:, rows], inverse, n_pol
)
embedded = parts if embedded is None else _summed(embedded, parts)
assert fine is not None
projected, *rest = fine
coarse, *coarse_rest = [None] * len(fine) if embedded is None else embedded
+ # What the alarm reads (_update_alarm), returned beside the stage.
+ outputs: dict[str, Any] = {"projected": projected, "failures": failures}
+ if coarse is not None:
+ outputs["coarse"] = coarse
gated = edge = None
if plasma:
gated, edge = rest[:2]
- self._last_plasma = (gated, edge, *coarse_rest[:2]) # pyright: ignore[reportAttributeAccessIssue]
+ outputs["plasma"] = [gated, edge, *coarse_rest[:2]]
rest, coarse_rest = rest[2:], coarse_rest[2:]
- else:
- self._last_plasma = None
drives = rest if envelope else None
- self._last_envelope = ( # pyright: ignore[reportAttributeAccessIssue]
- (*rest, *coarse_rest) if envelope else None
- )
- self._last_projected = projected # pyright: ignore[reportAttributeAccessIssue]
- self._last_coarse = coarse # pyright: ignore[reportAttributeAccessIssue]
- self._last_bundle = bundle
+ if envelope:
+ outputs["envelope"] = [*rest, *coarse_rest]
spectrum = device.to_frequency(projected, self._crop, kind=kind)
if gated is not None and edge is not None:
spectrum = spectrum + self._device_held(gated, edge)
if drives is not None:
spectrum = spectrum + self._envelope_spectrum(drives)
- return back * self._normalised(spectrum, bundle, absorber)[None]
+ normalised = self._normalised(spectrum, inputs["prefactor"], absorber)
+ outputs["source"] = normalised[None]
+ outputs["stage"] = back * outputs["source"]
+ return outputs
def _normalised(
- self, spectrum: mx.array, bundle: StageScalars, absorber: mx.array | None
+ self, spectrum: mx.array, prefactor: mx.array, absorber: mx.array | None
) -> mx.array:
"""Apply the prefactor and window to a source spectrum and add the collar.
@@ -976,8 +1563,8 @@ def _normalised(
----------
spectrum : mlx.core.array
The coarse source spectrum.
- bundle : solprop.translate.stage.StageScalars
- The stage's host scalars.
+ prefactor : mlx.core.array
+ The stage's prefactor (:meth:`_device_prefactor`).
absorber : mlx.core.array or None
The in-stage collar's term.
@@ -986,7 +1573,7 @@ def _normalised(
mlx.core.array
The stage derivative before the inverse propagator.
"""
- normalised = self._device_prefactor(bundle) * self._omega_window * spectrum
+ normalised = prefactor * self._omega_window * spectrum
return normalised if absorber is None else normalised + absorber
def _device_held(self, gated: mx.array, edge: mx.array) -> mx.array:
@@ -1041,7 +1628,7 @@ def _device_absorber(self, modal_t: mx.array) -> mx.array | None:
return device.to_frequency(term, self._crop, kind=self._kind) * self._active
def _device_radial_plasma(
- self, modal_t: mx.array, bundle: StageScalars
+ self, modal_t: mx.array, values: _StageValues, raman: mx.array | None
) -> mx.array:
"""Return the radial route's plasma-bearing source spectrum.
@@ -1052,8 +1639,10 @@ def _device_radial_plasma(
----------
modal_t : mlx.core.array
The modal field on the fine time grid.
- bundle : solprop.translate.stage.StageScalars
- The stage's host scalars.
+ values : _StageValues
+ The stage's values.
+ raman : mlx.core.array or None
+ The narrowed Raman kernel spectrum.
Returns
-------
@@ -1061,15 +1650,12 @@ def _device_radial_plasma(
The coarse source spectrum before the prefactor.
"""
transform = self._problem.transform
- raman = self._device_raman(bundle)
n_pol = transform.n_pol
spectrum = None
for first in range(0, transform.n_nodes, transform.node_chunk):
rows = slice(first * n_pol, (first + transform.node_chunk) * n_pol)
- field = device.synthesise(
- modal_t, self._synthesis[rows], bundle.taper_scale, n_pol
- )
- sources = self._device_sources(field, bundle, raman)
+ field = device.synthesise(modal_t, self._synthesis[rows], values[0], n_pol)
+ sources = self._device_sources(field, values, raman)
nodal = device.to_frequency(
sources.polarisation, self._crop, kind=self._kind
)
@@ -1078,17 +1664,20 @@ def _device_radial_plasma(
self._t_window * sources.current,
self._t_window_derivative * sources.current,
)
- part = device.project(
- nodal, self._projection[:, rows], bundle.taper_scale, n_pol
- )
+ part = device.project(nodal, self._projection[:, rows], values[1], n_pol)
spectrum = part if spectrum is None else spectrum + part
assert spectrum is not None
return spectrum
def _device_free(
- self, lab: mx.array, bundle: StageScalars, back: mx.array
+ self,
+ lab: mx.array,
+ values: _StageValues,
+ raman: mx.array | None,
+ failures: list[mx.array],
+ bundle: StageScalars | None = None,
) -> mx.array:
- """Evaluate a Cartesian (or line) stage derivative on the device.
+ """Evaluate a Cartesian (or line) stage's source on the device, untransported.
The oracle's ``_nonlinear_free``: the transverse inverse transform, the
responses per chunk of columns on the fine time grid, the forward transforms,
@@ -1098,15 +1687,19 @@ def _device_free(
----------
lab : mlx.core.array
The lab-frame stage input, ``(1, n_columns, n_pol, n_omega)``.
- bundle : solprop.translate.stage.StageScalars
- The stage's host scalars.
- back : mlx.core.array
- ``exp(-dPhi)`` of the stage.
+ values : _StageValues
+ The stage's values.
+ raman : mlx.core.array or None
+ The narrowed Raman kernel spectrum.
+ failures : list of mlx.core.array
+ Receives the envelope plasma's failure counts.
+ bundle : solprop.translate.stage.StageScalars or None, optional
+ The host scalars, for MLX's CPU device's host envelope plasma.
Returns
-------
mlx.core.array
- The stage derivative in the interaction variable.
+ The stage's source before the inverse propagator.
"""
problem = self._problem
transform, grids, responses = (
@@ -1124,14 +1717,13 @@ def _device_free(
physical = mx.fft.ifftn(lab[0].reshape(shape), axes=[0, 1]).reshape(
lab.shape[1:]
)
- raman = self._device_raman(bundle)
parts = []
for first in range(0, transform.n_nodes, transform.node_chunk):
rows = physical[first : first + transform.node_chunk]
field = grids.pad_scale * device.to_time(
rows, self._pad_crop, grids.n_to, kind=kind
)
- sources = self._device_sources(field, bundle, raman)
+ sources = self._device_sources(field, values, raman)
part = device.to_frequency(sources.polarisation, self._crop, kind=kind)
if sources.current is not None:
part = part + self._device_held(
@@ -1140,7 +1732,7 @@ def _device_free(
)
if self._cycles:
part = part + self._envelope_spectrum(
- list(self._device_envelope(field, bundle))
+ list(self._device_envelope(field, values, failures, bundle))
)
parts.append(part)
spectrum = mx.concatenate(parts, axis=0) if len(parts) > 1 else parts[0]
@@ -1155,7 +1747,8 @@ def _device_free(
temporal = self._temporal_rate
if responses.absorber_scheme != "nonlinear":
temporal = None
- spatial = mx.array(self._cast(geometry.absorber_rate))
+ spatial = self._free_rate
+ assert spatial is not None
parts = []
for first in range(0, transform.n_nodes, transform.node_chunk):
rows = slice(first, first + transform.node_chunk)
@@ -1173,10 +1766,10 @@ def _device_free(
lab.shape[1:]
)
result = result + self._active * collar
- return back * result[None]
+ return result[None]
def _device_sources(
- self, field: mx.array, bundle: StageScalars, raman: mx.array | None
+ self, field: mx.array, values: _StageValues, raman: mx.array | None
) -> DeviceSources:
"""Evaluate the responses at a chunk of nodes, the oracle's ``single_sources``.
@@ -1184,8 +1777,8 @@ def _device_sources(
----------
field : mlx.core.array
The scaled field at the nodes.
- bundle : solprop.translate.stage.StageScalars
- The stage's host scalars.
+ values : _StageValues
+ The stage's values.
raman : mlx.core.array or None
The narrowed Raman kernel spectrum.
@@ -1205,56 +1798,34 @@ def _device_sources(
current = None
for stage in responses.response_order:
if stage is ResponseStage.KERR:
- kerr = compiled_kerr(responses)
- factor = combine(
- kerr.coefficient, bundle.kerr_density, exponent=2 * k
- ).binary32()
- total = total + device.kerr(field, kerr, factor, self._device_carrier)
+ total = total + device.kerr(
+ field,
+ compiled_kerr(responses),
+ values[2],
+ self._device_carrier,
+ values[3],
+ )
elif stage is ResponseStage.RAMAN_DRIVE:
assert raman is not None
- density = (
- 1.0
- if len(responses.raman_terms) > 1
- else bundle.raman_densities[0]
- if bundle.raman_densities
- else bundle.density
- )
- factor = combine(
- EPS0, density, exponent=2 * k + self._raman_exponent
- ).binary32()
total = total + device.raman(
- field, raman, factor, kind=self._kind, thg=raman_thg(responses)
+ field, raman, values[4], kind=self._kind, thg=raman_thg(responses)
)
elif stage is ResponseStage.PLASMA_CURRENT:
- channels = responses.plasma_channels
- if len(channels) > 1:
- densities = bundle.plasma_densities
- initials = bundle.plasma_preionisation
- else:
- densities = (
- bundle.plasma_densities[0]
- if bundle.plasma_densities
- else bundle.density,
- )
- initials = (bundle.preionisation,)
- constants = tuple(
- (
- density
- * channel.charge_mass_ratio
- * channel.electrons_per_event,
- density * channel.ionisation_potential,
- )
- for channel, density in zip(channels, densities, strict=True)
- )
+ channels = [
+ values.channel(index)
+ for index in range(len(responses.plasma_channels))
+ ]
physical = field * float(2.0**k)
current = device.plasma_current(
physical,
self._rate_tables,
- constants,
- tuple(initials),
+ tuple((channel[0], channel[1]) for channel in channels),
+ tuple(channel[2:] for channel in channels),
self._problem.grids.dt_fine,
responses.plasma_integral,
- evaluate=self.evaluate_stages,
+ # A compiled stage is one graph; only an op-by-op stage is
+ # evaluated in pieces.
+ evaluate=self.evaluate_stages and not self._fused,
) * float(2.0**-k)
elif stage not in _SOURCE_STAGES:
msg = f"mlx does not run the {stage.name} stage"
@@ -1262,7 +1833,11 @@ def _device_sources(
return DeviceSources(total * self._t_window, current)
def _device_envelope(
- self, field: mx.array, bundle: StageScalars
+ self,
+ field: mx.array,
+ values: _StageValues,
+ failures: list[mx.array],
+ bundle: StageScalars | None = None,
) -> tuple[mx.array, mx.array]:
"""Return the envelope plasma's windowed drive and loss at a chunk of nodes.
@@ -1276,8 +1851,12 @@ def _device_envelope(
----------
field : mlx.core.array
The scaled envelope at the nodes, ``(n_nodes, n_pol, n_to)``.
- bundle : solprop.translate.stage.StageScalars
- The stage's host scalars.
+ values : _StageValues
+ The stage's values.
+ failures : list of mlx.core.array
+ Receives each channel's failure count.
+ bundle : solprop.translate.stage.StageScalars or None, optional
+ The stage's host scalars, which MLX's CPU device evaluates with.
Returns
-------
@@ -1285,31 +1864,22 @@ def _device_envelope(
The drive and the loss, complex64.
"""
if not on_gpu():
+ assert bundle is not None # an op-by-op stage is given its scalars
drive, loss = super()._envelope_sources(np.array(field), bundle)
return mx.array(drive), mx.array(loss)
- envelope = self._problem.responses.envelope_plasma
- assert envelope is not None
k = self._scale_exponent
half_step = float(np.float32(0.5 * self._problem.grids.dt_fine))
drive = mx.zeros_like(field)
loss = mx.zeros_like(field)
- for channel, cycle, density, initial in zip(
- envelope.channels,
- self._cycles,
- bundle.plasma_densities,
- bundle.plasma_preionisation,
- strict=True,
- ):
- rate, current, failures = envelope_cycle(field, cycle, k)
- self._envelope_failures.append(failures)
+ for index, cycle in enumerate(self._cycles):
+ rate, current, failed = envelope_cycle(field, cycle, k)
+ failures.append(failed)
increments = (rate[..., :-1] + rate[..., 1:]) * half_step
zero = mx.zeros((*rate.shape[:-1], 1), dtype=mx.float32)
exposure = mx.concatenate([zero, prefix_scan(increments)], axis=-1)
- fraction, survival = population(exposure, initial)
- weight = combine(channel.charge_mass_ratio, density).binary32()
- work = combine(
- channel.ionisation_potential, density, exponent=-k
- ).binary32()
+ channel = values.channel(index, envelope=True)
+ fraction, survival = population(exposure, channel[2:])
+ weight, work = channel[0], channel[1]
drive = drive + (weight * fraction)[:, None, :] * field
loss = loss + (work * survival)[:, None, :] * current
return drive * self._t_window, loss * self._t_window
@@ -1365,6 +1935,122 @@ def _envelope_populations(
np.array(mx.stack(peaks), dtype=np.float64),
)
+ def _species_statistics(
+ self,
+ field: Complex[np.ndarray, "n_modes n_pol n_omega"],
+ scans: dict[int, tuple[np.ndarray, np.ndarray]] | None = None,
+ member: int = 0,
+ ) -> dict[str, np.ndarray]:
+ """Evaluate the field-grid plasma's populations at every node on the device.
+
+ The oracle's statistics (:meth:`NumpyRefBackend._species_statistics`) with the
+ stage's own formulation, as :meth:`_envelope_populations` evaluates the
+ envelope grid's: the nodes formed from the plane's state on the device, each
+ channel's rate kernel, running integral and stable population, chunk by
+ chunk, and only the final fractions and peak rates read. On a Cartesian grid
+ the host's evaluation transformed every column in binary64, seconds a plane.
+ Elsewhere -- the envelope grid, no plasma, MLX's CPU device -- the oracle's.
+
+ Parameters
+ ----------
+ field : numpy.ndarray
+ One batch member at this plane, shape (n_modes, n_pol, n_omega).
+ scans : dict or None, optional
+ Where to leave this observation's channel fractions and peak rates at
+ every node, keyed by `member`, for the on-axis statistics to reuse.
+ member : int, optional
+ The batch member, the key into `scans`.
+
+ Returns
+ -------
+ dict
+ The five species statistics and the two total plasma statistics.
+ """
+ responses = self._problem.responses
+ transform = self._problem.transform
+ slab = transform.geometry is not None and transform.geometry.kind == "slab"
+ if (
+ not on_gpu()
+ or responses.envelope_plasma is not None
+ or not responses.plasma_channels
+ or slab
+ ):
+ return super()._species_statistics(field, scans, member)
+ initials = tuple(
+ float(channel.preionisation(self._z))
+ for channel in responses.population_channels
+ )
+ parameters = [mx.array(population_parameters(p)) for p in initials]
+ k = self._scale_exponent
+ # The state's own scale: the narrowed field is the propagation's.
+ state = mx.array((field * math.ldexp(1.0, -k)).astype(np.complex64))
+ grids = self._problem.grids
+ fractions: list[list[mx.array]] = [[] for _ in initials]
+ peaks: list[list[mx.array]] = [[] for _ in initials]
+ for nodes in self._device_nodes(state):
+ physical = nodes * float(2.0**k)
+ if physical.shape[-2] == 1:
+ magnitude = mx.abs(physical[..., 0, :])
+ else:
+ x, y = physical[..., 0, :], physical[..., 1, :]
+ magnitude = mx.sqrt(x * x + y * y)
+ for index, table in enumerate(self._rate_tables):
+ rate = table(magnitude)
+ exposure = device.running_integral(
+ rate, grids.dt_fine, responses.plasma_integral
+ )[..., -1]
+ if responses.plasma_integral.policy != "trapezoid":
+ exposure = mx.maximum(exposure, 0.0)
+ fraction, _ = population(exposure, parameters[index])
+ fractions[index].append(fraction)
+ peaks[index].append(mx.max(rate, axis=-1))
+ read = [mx.concatenate(rows) for rows in (*fractions, *peaks)]
+ values = np.array(mx.stack(read), dtype=np.float64)
+ found, highest = values[: len(initials)], values[len(initials) :]
+ if scans is not None:
+ scans[member] = (found, highest)
+ return population_statistics(self._problem, self._z, found, highest)
+
+ def _device_nodes(self, state: mx.array) -> Iterator[mx.array]:
+ """Yield a scaled state's field at the nodes on the fine time grid, by chunk.
+
+ Parameters
+ ----------
+ state : mlx.core.array
+ One member's scaled spectral columns, ``(n_modes, n_pol, n_omega)``.
+
+ Yields
+ ------
+ mlx.core.array
+ The scaled field at a chunk of nodes, ``(n_chunk, n_components, n_to)``.
+ """
+ problem = self._problem
+ grids, transform = problem.grids, problem.transform
+ kind = self._kind
+ if self._free_prefactor is not None:
+ geometry = transform.geometry
+ assert geometry is not None
+ nx, ny = geometry.shape
+ physical = mx.fft.ifftn(
+ state.reshape(ny, nx, *state.shape[1:]), axes=[0, 1]
+ ).reshape(state.shape)
+ for first in range(0, transform.n_nodes, transform.node_chunk):
+ rows = physical[first : first + transform.node_chunk]
+ yield grids.pad_scale * device.to_time(
+ rows, self._pad_crop, grids.n_to, kind=kind
+ )
+ return
+ taper = (
+ 1.0
+ if transform.taper_scale is None
+ else float(transform.taper_scale(self._z))
+ )
+ modal_t = device.to_time(state, self._pad_crop, grids.n_to, kind=kind)
+ n_pol = transform.n_pol
+ for first in range(0, transform.n_nodes, transform.node_chunk):
+ rows = slice(first * n_pol, (first + transform.node_chunk) * n_pol)
+ yield device.synthesise(modal_t, self._synthesis[rows], taper, n_pol)
+
def _envelope_spectrum(self, drives: list[mx.array]) -> mx.array:
"""Return the drive's and the loss's spectrum times their factors.
@@ -1436,6 +2122,46 @@ def _device_norm(
float
The norm, binary64; infinite if any value is not finite.
"""
+ residual, reductions = self._norm_sums(error, state, advanced)
+ reductions.append(self._failure_count())
+ values = self._synchronised(reductions)
+ self._raise_on_failures(values[-1])
+ if not np.all(np.isfinite(values[:-1])) or values[-2] != 1.0:
+ return math.inf
+ squares = [
+ math.ldexp(values[2 * k + 1], 2 * int(values[2 * k])) for k in range(3)
+ ]
+ scale = self._controller.scale(math.sqrt(squares[1]), math.sqrt(squares[2]))
+ if isinstance(scale, np.ndarray):
+ weights = mx.array(
+ (1.0 / scale[self._problem.grids.norm_mask]).astype(np.float32)
+ )
+ weighted = residual * weights
+ re, im = mx.real(weighted), mx.imag(weighted)
+ return math.sqrt(float(cast(float, mx.sum(re * re + im * im).item())))
+ return math.sqrt(squares[0]) / scale
+
+ def _norm_sums_core(
+ self, error: mx.array, state: mx.array, advanced: mx.array
+ ) -> tuple[mx.array, list[mx.array]]:
+ """Return the norm's residual and its scaled sums of squares, on the device.
+
+ Parameters
+ ----------
+ error : mlx.core.array
+ The embedded difference carried to the end of the step.
+ state : mlx.core.array
+ The state at the anchor.
+ advanced : mlx.core.array
+ The trial state.
+
+ Returns
+ -------
+ tuple
+ The residual on the norm's bins, and for it, the anchor and the trial
+ state a power of two and a sum of squares each, then whether the trial
+ state is finite, as float32.
+ """
index = self._norm_index
residual = mx.take(error, index, axis=-1)
reductions = []
@@ -1454,48 +2180,119 @@ def _device_norm(
# One synchronisation per trial: the three sums, their powers and whether the
# whole trial state is finite, which spares the finish a check of its own.
reductions.append(mx.all(mx.isfinite(advanced)).astype(mx.float32))
- reductions.append(self._failure_count())
- values = self._synchronised(reductions)
- self._raise_on_failures(values[-1])
- if not np.all(np.isfinite(values[:-1])) or values[-2] != 1.0:
- return math.inf
- squares = [
- math.ldexp(values[2 * k + 1], 2 * int(values[2 * k])) for k in range(3)
- ]
- scale = self._controller.scale(math.sqrt(squares[1]), math.sqrt(squares[2]))
- if isinstance(scale, np.ndarray):
- weights = mx.array(
- (1.0 / scale[self._problem.grids.norm_mask]).astype(np.float32)
- )
- weighted = residual * weights
- re, im = mx.real(weighted), mx.imag(weighted)
- return math.sqrt(float(cast(float, mx.sum(re * re + im * im).item())))
- return math.sqrt(squares[0]) / scale
+ return residual, reductions
def _update_alarm(self) -> None:
- """Evaluate the quadrature alarm on the host from the last stage's rows."""
- held = (
- self._last_projected,
- self._last_coarse,
- self._last_plasma,
- self._last_envelope,
- )
- to_host = lambda value: None if value is None else np.array(value) # noqa: E731
- self._last_projected = to_host(held[0]) # pyright: ignore[reportAttributeAccessIssue]
- self._last_coarse = to_host(held[1]) # pyright: ignore[reportAttributeAccessIssue]
- if held[2] is not None:
- self._last_plasma = tuple(to_host(part) for part in held[2]) # pyright: ignore[reportAttributeAccessIssue]
- if held[3] is not None:
- self._last_envelope = tuple(to_host(part) for part in held[3]) # pyright: ignore[reportAttributeAccessIssue]
- try:
+ """Score the quadrature alarm on the device, read with the next synchronisation.
+
+ The oracle's measure (:meth:`NumpyRefBackend._update_alarm`), the relative
+ difference between the Kronrod and the embedded Gauss projections of the last
+ stage's sources, formed on the device in binary32 and scaled by a power of two
+ so that its sums cannot overflow; its one scalar is read with the next trial's
+ norm (:meth:`_synchronised`) or when a statistic asks for it, rather than
+ copying the stage's rows to the host at every accepted step.
+ """
+ # The stage left device arrays where the oracle's leaves host ones.
+ coarse = cast(Any, self._last_coarse)
+ projected = cast(Any, self._last_projected)
+ envelope = cast(Any, self._last_envelope)
+ plasma = cast(Any, self._last_plasma)
+ if coarse is None or projected is None or self._last_bundle is None:
+ self._pending_alarm = None
super()._update_alarm()
- finally:
- (
- self._last_projected,
- self._last_coarse,
- self._last_plasma,
- self._last_envelope,
- ) = held # pyright: ignore[reportAttributeAccessIssue]
+ return
+ weight = self._device_prefactor(self._last_bundle) * self._omega_window
+ kind = self._kind
+ # The transforms are linear, so the difference is taken before them: two
+ # binary32 spectra transformed apart would differ by their rounding, near the
+ # alarm's own level.
+ fine = device.to_frequency(projected, self._crop, kind=kind)
+ gap = device.to_frequency(coarse - projected, self._crop, kind=kind)
+ if envelope is not None:
+ drive, loss, coarse_drive, coarse_loss = envelope
+ fine = fine + self._envelope_spectrum([drive, loss])
+ gap = gap + self._envelope_spectrum(
+ [coarse_drive - drive, coarse_loss - loss]
+ )
+ if plasma is not None:
+ gated, edge, coarse_gated, coarse_edge = plasma
+ fine = fine + self._device_held(gated, edge)
+ gap = gap + self._device_held(coarse_gated - gated, coarse_edge - edge)
+ self._pending_alarm = (
+ self._alarm_ratio(weight * fine, weight * gap),
+ self._last_bundle.z1,
+ )
+
+ def _alarm_ratio_core(self, fine: mx.array, gap: mx.array) -> mx.array:
+ """Return ``|gap| / |fine|``, NaN where ``fine`` vanishes.
+
+ Parameters
+ ----------
+ fine, gap : mlx.core.array
+ The Kronrod projection's weighted spectrum, and the embedded one's
+ difference from it.
+
+ Returns
+ -------
+ mlx.core.array
+ A float32 scalar.
+ """
+ peak = mx.max(mx.abs(fine))
+ power = mx.where(peak > 0, mx.floor(mx.log2(peak)), 0.0)
+ factor = mx.power(2.0, -power)
+ scaled, difference = fine * factor, gap * factor
+ total = mx.sum(mx.square(mx.real(scaled)) + mx.square(mx.imag(scaled)))
+ gap = mx.sum(mx.square(mx.real(difference)) + mx.square(mx.imag(difference)))
+ return mx.where(total > 0, mx.sqrt(gap / total), math.nan)
+
+ def _resolve_alarm(self, value: float | None = None) -> None:
+ """Turn a pending device alarm into the oracle's value and its warning.
+
+ Parameters
+ ----------
+ value : float or None, optional
+ The pending scalar, already read; read here when not given.
+ """
+ pending, self._pending_alarm = self._pending_alarm, None
+ if pending is None:
+ return
+ ratio, position = pending
+ self._alarm = float(cast(float, ratio.item())) if value is None else value
+ if self._alarm > QUADRATURE_ALARM and not self._alarm_reported:
+ self._alarm_reported = True
+ oracle_logger.warning(
+ "the transverse quadrature reproduces the nonlinear polarisation to "
+ "only %.2e at z = %.6g m, above the %.0e alarm; the integrand is not "
+ "resolved by this rule (a kinked ionisation rate, or too few nodes for "
+ "the mode set) and no step size can fix it",
+ self._alarm,
+ position,
+ QUADRATURE_ALARM,
+ )
+
+ def _begin_plane(self) -> None:
+ """Forget the last plane's quadrature alarm, pending or read."""
+ self._pending_alarm = None
+ super()._begin_plane()
+
+ def _backend_stat(self, name: str, state: Any) -> np.ndarray: # pyright: ignore[reportIncompatibleMethodOverride]
+ """Return a backend statistic, reading a pending alarm first.
+
+ Parameters
+ ----------
+ name : str
+ The statistic.
+ state : numpy.ndarray
+ The state at this plane.
+
+ Returns
+ -------
+ numpy.ndarray
+ The value with a leading batch axis.
+ """
+ if name == "quadrature_error":
+ self._resolve_alarm()
+ return super()._backend_stat(name, state)
# The low-storage march's hooks and engine.
@@ -1541,6 +2338,202 @@ def _adams_propagator( # pyright: ignore[reportIncompatibleMethodOverride]
"""
return self._propagators(self._stage_scalars(anchor, position))[0]
+ def _edge_reading(
+ self,
+ state: Any,
+ edge: TransverseEdge,
+ *,
+ faces: bool = True,
+ current: bool = False,
+ full: bool = False,
+ ) -> _EdgeReading:
+ """Read the transverse edge on the device, where no collar is requested.
+
+ The host reduction (``_HostEdgeReduction``) of the node and column energies,
+ formed on the device -- a Cartesian or line grid's transverse inverse
+ transform, a radial grid's synthesis -- with only the nodes' and columns'
+ sums read, where the default copied the whole state to the host and widened
+ it at every read. A requested collar's strip and current, a planar grid and
+ MLX's CPU device take the host reduction.
+
+ Parameters
+ ----------
+ state : mlx.core.array
+ The scaled state.
+ edge : solprop.transverse_monitor.TransverseEdge
+ The run's edge.
+ faces : bool, optional
+ Whether the nodes, the columns and any collar's strip are wanted.
+ current : bool, optional
+ Whether a collar's inward current is wanted.
+ full : bool, optional
+ Whether every node is wanted, not only the rows a read uses.
+
+ Returns
+ -------
+ solprop.transverse_monitor._EdgeReading
+ The reading.
+ """
+ reduction = edge.reduction
+ space = reduction.space
+ if (
+ not on_gpu()
+ or current
+ or not faces
+ or reduction.lines
+ or not isinstance(space, (FreeGrid, LineGrid, RadialGrid))
+ ):
+ return super()._edge_reading(
+ state, edge, faces=faces, current=current, full=full
+ )
+ member = cast(mx.array, state)[0]
+ flat = member.reshape(member.shape[0], -1)
+ if isinstance(space, RadialGrid):
+ synthesis = self._edge_synthesis(reduction)
+ nodes = synthesis @ mx.real(flat), synthesis @ mx.imag(flat)
+ physical = nodes[0] + 1j * nodes[1]
+ else:
+ cube = flat.reshape(space.n_y, space.n_x, -1)
+ physical = mx.fft.ifftn(cube, axes=[0, 1]).reshape(
+ space.n_y * space.n_x, -1
+ )
+ energies = [
+ mx.sum(
+ mx.real(rows) * mx.real(rows) + mx.imag(rows) * mx.imag(rows), axis=1
+ )
+ for rows in (physical, flat)
+ ]
+ read = np.array(mx.concatenate(energies), dtype=np.float64) * self.scale**2
+ node_energy, columns = read[: physical.shape[0]], read[physical.shape[0] :]
+ tables = reduction.tables
+ if not full:
+ # The host reads only the rows a read's sums touch, the others zero.
+ node_energy = np.where(tables.rows, node_energy, 0.0)
+ return _EdgeReading(
+ faces=tables.faces @ node_energy,
+ clip=tables.clip @ node_energy if full else None,
+ totals=tables.totals @ node_energy if full else None,
+ columns=columns,
+ )
+
+ def _edge_synthesis(self, reduction: Any) -> mx.array:
+ """Return a radial grid's synthesis from columns to nodes on the device.
+
+ Parameters
+ ----------
+ reduction : solprop.transverse_monitor._HostEdgeReduction
+ The edge's host reduction, which holds the binary64 matrix.
+
+ Returns
+ -------
+ mlx.core.array
+ The matrix in binary32, uploaded once.
+ """
+ if self._edge_matrix is None:
+ synthesis = reduction.synthesis()
+ assert synthesis is not None # a radial grid's
+ self._edge_matrix = mx.array(np.asarray(synthesis, dtype=np.float32))
+ return self._edge_matrix
+
+ def _collar_changed(self) -> None:
+ """Forget a reused first stage, evaluated under the other collar setting."""
+ self._first = self._pending_first = None
+
+ def _adams_engine(
+ self,
+ method: Multistep,
+ compensation: Literal["transported", "untransported"],
+ ) -> object:
+ """Return the device-resident exponential Adams history.
+
+ Parameters
+ ----------
+ method : solprop.stepper.multistep.Multistep
+ The method, in the exponential formulation (the other is refused).
+ compensation : {'transported', 'untransported'}
+ A varying operator's compensation; the untransported witness is refused.
+
+ Returns
+ -------
+ solprop.backends.mlx_gpu.adams.MlxAdams
+ The engine.
+
+ Raises
+ ------
+ BackendError
+ For the untransported compensation, a test witness of the reference.
+ """
+ from solprop.backends.mlx_gpu.adams import MlxAdams # noqa: PLC0415 - cycle
+
+ if not on_gpu():
+ msg = "mlx runs the Adams integrator on the Metal device only"
+ raise BackendError(msg)
+ engine = MlxAdams(self, method)
+ if engine.compensated and compensation != "transported":
+ msg = "mlx does not run the untransported compensation, a witness"
+ raise BackendError(msg)
+ return engine
+
+ def _adams_state(self) -> Complex[np.ndarray, "n_batch n_modes n_pol n_omega"]:
+ """Return a host copy of the scaled accepted state, as a snapshot keeps it.
+
+ Returns
+ -------
+ numpy.ndarray
+ The complex64 state ``a / s``.
+ """
+ return np.array(self._require_state())
+
+ def _adams_restore(
+ self, z: float, state: Complex[np.ndarray, "n_batch n_modes n_pol n_omega"]
+ ) -> None:
+ """Make an accepted state current at `z`, on the device in complex64.
+
+ Parameters
+ ----------
+ z : float
+ Its position, m.
+ state : numpy.ndarray or mlx.core.array
+ The scaled state, as :meth:`_adams_state` or the engine held it.
+ """
+ self._z = z
+ held = cast(Any, state)
+ self._state = cast(
+ Any,
+ held
+ if isinstance(held, mx.array)
+ else mx.array(np.asarray(held).astype(np.complex64)),
+ )
+
+ def _adams_adopt( # pyright: ignore[reportIncompatibleMethodOverride]
+ self, advanced: mx.array, dz: float
+ ) -> mx.array:
+ """Adopt an accepted Adams step on the device: the finish, then the state.
+
+ Parameters
+ ----------
+ advanced : mlx.core.array
+ The step's end state, complex64.
+ dz : float
+ The step, m.
+
+ Returns
+ -------
+ mlx.core.array
+ The finished state.
+
+ Raises
+ ------
+ BackendError
+ If the state left binary32.
+ """
+ if advanced.dtype != mx.complex64:
+ msg = f"an Adams step left complex64 for {advanced.dtype}"
+ raise BackendError(msg)
+ finished = self._finish(advanced, dz)
+ self._state = cast(Any, finished)
+ return finished
+
def _low_storage_engine(self, method: LowStorageRungeKutta) -> object:
"""Return the device engine of the low-storage march.
diff --git a/src/solprop/backends/mlx_gpu/passes.py b/src/solprop/backends/mlx_gpu/passes.py
index b98d53361..c00a08c00 100644
--- a/src/solprop/backends/mlx_gpu/passes.py
+++ b/src/solprop/backends/mlx_gpu/passes.py
@@ -161,7 +161,9 @@ def _product(matrix: mx.array, values: mx.array) -> mx.array:
return result.reshape(matrix.shape[0], *values.shape[1:])
-def synthesise(modal_t: mx.array, rows: mx.array, taper: float, n_pol: int) -> mx.array:
+def synthesise(
+ modal_t: mx.array, rows: mx.array, taper: float | mx.array, n_pol: int
+) -> mx.array:
"""Synthesise the field on a chunk of nodes, ``tau S a``.
Parameters
@@ -170,7 +172,7 @@ def synthesise(modal_t: mx.array, rows: mx.array, taper: float, n_pol: int) -> m
``(n_modes, n_pol_state, n_to)``.
rows : mlx.core.array
The chunk's rows of the narrowed synthesis matrix.
- taper : float
+ taper : float or mlx.core.array
The taper scale at this position.
n_pol : int
Components the transform resolves at each node.
@@ -185,7 +187,9 @@ def synthesise(modal_t: mx.array, rows: mx.array, taper: float, n_pol: int) -> m
return nodes.reshape(n_rows // n_pol, n_pol * n_pol_state, n_to)
-def project(values: mx.array, columns: mx.array, taper: float, n_pol: int) -> mx.array:
+def project(
+ values: mx.array, columns: mx.array, inverse: float | mx.array, n_pol: int
+) -> mx.array:
"""Project node values back onto the modes, ``P / tau``.
Parameters
@@ -194,8 +198,8 @@ def project(values: mx.array, columns: mx.array, taper: float, n_pol: int) -> mx
``(n_nodes_chunk, n_pol_node, n_to)``.
columns : mlx.core.array
The chunk's columns of the narrowed projection matrix.
- taper : float
- The taper scale.
+ inverse : float or mlx.core.array
+ The inverse of the taper scale, ``1 / tau``, formed in binary64.
n_pol : int
Components the transform resolves at each node.
@@ -206,11 +210,11 @@ def project(values: mx.array, columns: mx.array, taper: float, n_pol: int) -> mx
"""
n_chunk, n_pol_node, n_to = values.shape
rows = values.reshape(n_chunk * n_pol, n_pol_node // n_pol, n_to)
- return _product(columns * (1.0 / taper), rows)
+ return _product(columns * inverse, rows)
def project_many(
- values: list[mx.array], columns: mx.array, taper: float, n_pol: int
+ values: list[mx.array], columns: mx.array, inverse: float | mx.array, n_pol: int
) -> list[mx.array]:
"""Project several node arrays onto the modes in one matrix product.
@@ -225,8 +229,8 @@ def project_many(
``(n_nodes_chunk, n_pol_node, n_to)`` each, float32 or complex64.
columns : mlx.core.array
The chunk's columns of the narrowed projection matrix.
- taper : float
- The taper scale.
+ inverse : float or mlx.core.array
+ The inverse of the taper scale, ``1 / tau``, formed in binary64.
n_pol : int
Components the transform resolves at each node.
@@ -245,7 +249,7 @@ def project_many(
rows = mx.concatenate(parts, axis=-1).reshape(
n_chunk * n_pol, n_pol_node // n_pol, len(parts) * n_to
)
- product = _product(columns * (1.0 / taper), rows)
+ product = _product(columns * inverse, rows)
pieces = list(cast(list[mx.array], mx.split(product, len(parts), axis=-1)))
results = []
for array in values:
@@ -284,8 +288,9 @@ def analytic(values: mx.array) -> mx.array:
def kerr(
field: mx.array,
coefficients: KerrCoefficients,
- factor: float,
+ factor: float | mx.array,
carrier: mx.array | None,
+ harmonic: float | mx.array | None = None,
) -> mx.array:
"""Evaluate the Kerr polarisation, the oracle's ``kerr_single``.
@@ -295,10 +300,13 @@ def kerr(
The scaled field at the nodes.
coefficients : solprop.translate.responses.KerrCoefficients
The compiled coefficients.
- factor : float
+ factor : float or mlx.core.array
``coefficient * density * s**2``, rounded once.
carrier : mlx.core.array or None
The harmonic carrier on an envelope grid that radiates it.
+ harmonic : float or mlx.core.array or None, optional
+ ``factor * coefficients.harmonic_factor``, formed in binary64 and rounded
+ once; formed here from a host `factor` when not given.
Returns
-------
@@ -317,9 +325,10 @@ def kerr(
+ coefficients.conjugate_factor * squares * mx.conj(values)
)
if carrier is not None:
- polarisation = polarisation + (
- (factor * coefficients.harmonic_factor) * carrier * squares * values
- )
+ if harmonic is None:
+ assert not isinstance(factor, mx.array) # a compiled stage passes it
+ harmonic = factor * coefficients.harmonic_factor
+ polarisation = polarisation + harmonic * carrier * squares * values
return mx.real(polarisation) if coefficients.take_real else polarisation
@@ -353,7 +362,7 @@ def _drive(column: mx.array, *, kind: GridKind, thg: bool) -> mx.array:
def raman(
field: mx.array,
spectrum: mx.array,
- factor: float,
+ factor: float | mx.array,
*,
kind: GridKind,
thg: bool,
@@ -367,7 +376,7 @@ def raman(
spectrum : mlx.core.array
The narrowed kernel spectrum: ``(n_to + 1,)`` scalar, ``(1 | 2, n_to + 1)``
tensor.
- factor : float
+ factor : float or mlx.core.array
The combined coefficient, rounded once.
kind : {'field', 'envelope'}
The spectral layout.
@@ -662,11 +671,28 @@ def __call__(self, magnitude: mx.array) -> mx.array:
return mx.where(magnitude >= self.field_min, rate, 0.0)
+def _rounded(value: float | mx.array) -> float | mx.array:
+ """Return a host scalar rounded to binary32, or a device scalar as it is.
+
+ Parameters
+ ----------
+ value : float or mlx.core.array
+ A coefficient: a binary64 host value, or a float32 device scalar that a
+ compiled stage takes as an input (rounded once on the host).
+
+ Returns
+ -------
+ float or mlx.core.array
+ The same coefficient, as a multiplication rounds it.
+ """
+ return value if isinstance(value, mx.array) else float(np.float32(value))
+
+
def plasma_current( # noqa: PLR0913 - one array per channel input
field: mx.array,
tables: tuple[DeviceRateTable, ...],
- constants: tuple[tuple[float, float], ...],
- initials: tuple[float, ...],
+ constants: tuple[tuple[float | mx.array, float | mx.array], ...],
+ initials: tuple[float | mx.array, ...],
dt: float,
rule: RunningIntegral,
*,
@@ -680,10 +706,12 @@ def plasma_current( # noqa: PLR0913 - one array per channel input
The physical field ``s E``, float32, ``(n_nodes, n_pol, n_to)``.
tables : tuple of DeviceRateTable
One per channel.
- constants : tuple of tuple of float
- Per channel, ``density (e^2/m) n_c`` and ``density I_p``.
- initials : tuple of float
- Per channel, the pre-ionised fraction.
+ constants : tuple of tuple of float or mlx.core.array
+ Per channel, ``density (e^2/m) n_c`` and ``density I_p``: host values, or
+ float32 device scalars rounded once on the host.
+ initials : tuple of float or mlx.core.array
+ Per channel, the pre-ionised fraction, or the population kernel's parameters
+ on the device (:func:`~solprop.backends.mlx_gpu.arithmetic.population`).
dt : float
The sample spacing, s.
rule : solprop.nonlinear.ionisation.RunningIntegral
@@ -699,7 +727,10 @@ def plasma_current( # noqa: PLR0913 - one array per channel input
if field.shape[-2] == 1:
magnitude = mx.abs(field[..., 0, :])
else:
- magnitude = mx.sqrt(field[..., 0, :] ** 2 + field[..., 1, :] ** 2)
+ x, y = field[..., 0, :], field[..., 1, :]
+ # Products, not powers: MLX's eager x**2 rounds through pow (1.4 ulp), which a
+ # compiled stage would not, while x * x is correctly rounded in both.
+ magnitude = mx.sqrt(x * x + y * y)
weight = mx.zeros(magnitude.shape, dtype=mx.float32)
work = mx.zeros(magnitude.shape, dtype=mx.float32)
for table, (drude, potential), initial in zip(
@@ -710,8 +741,8 @@ def plasma_current( # noqa: PLR0913 - one array per channel input
if rule.policy != "trapezoid":
exposure = mx.maximum(exposure, 0.0)
fraction, survival = population(exposure, initial)
- weight = weight + float(np.float32(drude)) * fraction
- work = work + float(np.float32(potential)) * (rate * survival)
+ weight = weight + _rounded(drude) * fraction
+ work = work + _rounded(potential) * (rate * survival)
free = running_integral(weight[..., None, :] * field, dt, rule, evaluate=evaluate)
squared = magnitude * magnitude
guard = mx.where(
diff --git a/src/solprop/backends/multistep.py b/src/solprop/backends/multistep.py
index 6bf9fec1a..55e60c05c 100644
--- a/src/solprop/backends/multistep.py
+++ b/src/solprop/backends/multistep.py
@@ -2396,9 +2396,14 @@ def load_rows(self, rows: Mapping[str, np.ndarray], shape: tuple[int, ...]) -> N
)
raise BackendError(msg)
self.reset()
- self._store = np.array(rows["store"], dtype=np.complex128, copy=True)
+ # In the state's precision: binary32 on SEP 33's single-precision path, as the
+ # store was kept; the operator's rates stay binary64 there too.
+ dtype = (
+ np.complex64 if self._backend._problem.precision.single else np.complex128
+ )
+ self._store = np.array(rows["store"], dtype=dtype, copy=True)
if self.compensated:
- self._states = np.array(rows["states"], dtype=np.complex128, copy=True)
+ self._states = np.array(rows["states"], dtype=dtype, copy=True)
self._rates = np.array(rows["rates"], dtype=np.complex128, copy=True)
self._weights = [
None
diff --git a/src/solprop/backends/numpy_ref/single.py b/src/solprop/backends/numpy_ref/single.py
index 04679c19e..513565f09 100644
--- a/src/solprop/backends/numpy_ref/single.py
+++ b/src/solprop/backends/numpy_ref/single.py
@@ -62,7 +62,6 @@
from solprop.profiles import ZProfile
from solprop.stats import StatsSpec
from solprop.stepper.controller import PIController
-from solprop.stepper.multistep import Multistep
from solprop.translate.precision import (
admit_precision,
block_exponent,
@@ -160,7 +159,6 @@ def __init__(
admit_precision(
problem.precision,
backend=self.name,
- adams=isinstance(stepper.integrator, Multistep),
rtol=stepper.controller.rtol,
schedule=stepper.schedule is not None,
)
@@ -519,9 +517,6 @@ def _adams_adopt(
) -> Complex[np.ndarray, "n_batch n_modes n_pol n_omega"]:
"""Adopt an Adams step's state, refusing one that left binary32.
- The Adams integrator runs under single precision only inside the survival
- study (SEP 33, Q2).
-
Parameters
----------
advanced : numpy.ndarray
@@ -537,6 +532,20 @@ def _adams_adopt(
_require_dtype(np.asarray(advanced), self._complex, "the Adams state")
return super()._adams_adopt(advanced, dz)
+ def _adams_restore(
+ self, z: float, state: Complex[np.ndarray, "n_batch n_modes n_pol n_omega"]
+ ) -> None:
+ """Restore an accepted Adams state, in binary32: a snapshot holds binary64.
+
+ Parameters
+ ----------
+ z : float
+ Its position, m.
+ state : numpy.ndarray
+ The scaled state, as the march held or a snapshot read it.
+ """
+ super()._adams_restore(z, np.asarray(state).astype(self._complex, copy=False))
+
def _trial_step(
self, z: float, dz: float
) -> tuple[float, Complex[np.ndarray, "n_batch n_modes n_pol n_omega"]]:
diff --git a/src/solprop/driver/defaults.py b/src/solprop/driver/defaults.py
index 5e0d50925..2639fc8e9 100644
--- a/src/solprop/driver/defaults.py
+++ b/src/solprop/driver/defaults.py
@@ -323,7 +323,8 @@ def default_rtol(route: str, precision: str) -> float:
larger of it and :data:`~solprop.translate.precision.SINGLE_RTOL_FLOOR`, so it is
never tighter than its binary64 twin nor than binary32 rounding can serve, and at
most :data:`~solprop.translate.precision.SINGLE_RTOL_CAP`, the loosest value the
- single-precision survival record measured (the maintainers' ruling of 2026-10-28).
+ single-precision survival record measured (the maintainers' ruling of 2026-10-28;
+ the record reached free space's 1e-4 on 2026-11-05).
Parameters
----------
@@ -341,7 +342,7 @@ def default_rtol(route: str, precision: str) -> float:
--------
>>> from solprop.driver.defaults import default_rtol
>>> [default_rtol(route, "single") for route in ("gnlse", "capillary", "free")]
- [1e-06, 1e-06, 1e-05]
+ [1e-06, 1e-06, 0.0001]
>>> default_rtol("gnlse", "double")
1e-07
"""
@@ -369,7 +370,7 @@ def rtol_in_precision(rtol: float, precision: str) -> float:
--------
>>> from solprop.driver.defaults import rtol_in_precision
>>> [rtol_in_precision(rtol, "single") for rtol in (1e-8, 1e-5, 1e-3)]
- [1e-06, 1e-05, 1e-05]
+ [1e-06, 1e-05, 0.0001]
"""
if precision != "single":
return rtol
@@ -412,8 +413,9 @@ def default_integrator(route: str | None, precision: str) -> Multistep | RungeKu
A :data:`RouteName`, or ``None`` for settings built by hand, which step with
``Multistep()``.
precision : {'double', 'single'}
- The run's precision. Single precision refuses the Adams method until its
- survival is established (SEP 33, Q2), so it always takes ``RungeKutta()``.
+ The run's precision. Both take the route's own integrator: binary32 Adams
+ agrees with binary64 Adams to the method's truncation (#342), and on ``mlx``
+ it is the faster on the four-mode capillary and the radial routes.
Returns
-------
@@ -426,12 +428,11 @@ def default_integrator(route: str | None, precision: str) -> Multistep | RungeKu
>>> type(default_integrator("gnlse", "double")).__name__
'RungeKutta'
>>> type(default_integrator("capillary", "single")).__name__
- 'RungeKutta'
+ 'Multistep'
>>> type(default_integrator(None, "double")).__name__
'Multistep'
"""
- if precision == "single":
- return RungeKutta()
+ del precision # one rule in both precisions since #342
name = "Multistep" if route is None else route_defaults(route).integrator
return RungeKutta() if name == "RungeKutta" else Multistep()
diff --git a/src/solprop/driver/simulation.py b/src/solprop/driver/simulation.py
index a413f4d04..abe17c145 100644
--- a/src/solprop/driver/simulation.py
+++ b/src/solprop/driver/simulation.py
@@ -142,6 +142,7 @@
LineGrid,
RadialGrid,
TimeGrid,
+ TransformLibrary,
)
from solprop.linear import Frame, frame_origin, frame_quantities
from solprop.log import (
@@ -1009,13 +1010,12 @@ def __post_init__(self) -> None:
backend = _AutoBackend(backend, name)
object.__setattr__(self, "backend", backend)
# The precision's refusals come before the integrator's backend check, so a
- # single-precision run is told what single precision refuses -- the Adams
- # integrator -- rather than that a binary32 backend does not step it.
+ # single-precision run is told what single precision refuses rather than
+ # what its backend does not step.
try:
admit_precision(
precision,
backend=self.backend,
- adams=isinstance(self.integrator, Multistep),
rtol=getattr(self.controller, "rtol", None),
schedule=self.schedule is not None,
)
@@ -1394,10 +1394,10 @@ def _admit_integrator(integrator: Multistep, backend: str) -> None:
DriverError
Naming the conflict and the Runge-Kutta march every backend executes.
"""
- if backend not in ("auto", "numpy_ref", "native"):
+ if backend not in ("auto", "numpy_ref", "native", "mlx"):
msg = (
- f"the {integrator.name} integrator is implemented on numpy_ref and native "
- f"only, and backend {backend!r} would step the problem with its "
+ f"the {integrator.name} integrator is implemented on numpy_ref, native "
+ f"and mlx only, and backend {backend!r} would step the problem with its "
"Runge-Kutta march; pass one of those or 'auto', or "
"integrator=RungeKutta()"
)
@@ -4836,6 +4836,7 @@ def from_gnlse( # noqa: PLR0913 - the GNLSE's keyword surface
wavelength,
wavelength_limits,
trange,
+ transforms=_transform_library(precision, backend),
)
_check_selection_carrier(materials, working.reference_wavelength, wavelength)
mapping = _gnlse_fibre(
@@ -6748,6 +6749,7 @@ def _from_hollow( # noqa: PLR0913, PLR0915 - the interface's keyword surface
trange,
envelope=envelope,
thg=thg,
+ transforms=_transform_library(precision, backend),
)
materials = MaterialSelection() if materials is None else materials
_check_selection_carrier(materials, working.reference_wavelength, wavelength)
@@ -9080,12 +9082,43 @@ def _continues(
return True
+def _transform_library(precision: PrecisionName, backend: str) -> TransformLibrary:
+ """Return the transform library whose cost a run's ``"auto"`` grid minimises.
+
+ A single-precision run executes on ``mlx`` unless it names ``numpy_ref``
+ (``backend="auto"`` resolves to ``mlx`` under single precision, or is refused), and
+ MLX's GPU transforms past 4096 samples are fast at powers of two only
+ (:func:`solprop.grid.fft_cost`). Every other run transforms with FFTW.
+
+ Parameters
+ ----------
+ precision : {'double', 'single'}
+ The run's precision.
+ backend : str
+ The backend the run names.
+
+ Returns
+ -------
+ {'fftw', 'mlx'}
+ The library.
+
+ Examples
+ --------
+ >>> from solprop.driver.simulation import _transform_library
+ >>> _transform_library("single", "auto"), _transform_library("double", "auto")
+ ('mlx', 'fftw')
+ """
+ return "mlx" if precision == "single" and backend in ("auto", "mlx") else "fftw"
+
+
def _gnlse_grid(
grid: TimeGrid | None,
length: float,
wavelength: float,
wavelength_limits: tuple[float, float] | None,
trange: float | None,
+ *,
+ transforms: TransformLibrary = "fftw",
) -> TimeGrid:
"""Return the envelope grid a GNLSE run propagates on.
@@ -9101,6 +9134,9 @@ def _gnlse_grid(
Window limits, m.
trange : float or None
Time window, s.
+ transforms : {'fftw', 'mlx'}, optional
+ The library whose cost the built grid's 'auto' size minimises
+ (:func:`_transform_library`).
Returns
-------
@@ -9134,7 +9170,9 @@ def _gnlse_grid(
rule="grid-or-limits",
)
with _about(renamed=_GRID_KEYWORDS):
- return EnvelopeGrid.from_limits(length, wavelength, wavelength_limits, trange)
+ return EnvelopeGrid.from_limits(
+ length, wavelength, wavelength_limits, trange, transforms=transforms
+ )
def _gnlse_fibre( # noqa: PLR0913 - the coefficients of the mapping
@@ -10128,6 +10166,7 @@ def _capillary_grid( # noqa: PLR0913 - the three grid keywords and the two swit
*,
envelope: bool,
thg: bool,
+ transforms: TransformLibrary = "fftw",
) -> TimeGrid:
"""Return the grid a capillary run propagates on.
@@ -10148,6 +10187,9 @@ def _capillary_grid( # noqa: PLR0913 - the three grid keywords and the two swit
thg : bool
Whether the responses reach the third harmonic, which sets an envelope grid's
oversampling.
+ transforms : {'fftw', 'mlx'}, optional
+ The library whose cost the built grid's ``'auto'`` size minimises
+ (:func:`_transform_library`).
Returns
-------
@@ -10188,9 +10230,16 @@ def _capillary_grid( # noqa: PLR0913 - the three grid keywords and the two swit
with _about(renamed=_GRID_KEYWORDS):
if envelope:
return EnvelopeGrid.from_limits(
- length, wavelength, wavelength_limits, trange, thg=thg
+ length,
+ wavelength,
+ wavelength_limits,
+ trange,
+ thg=thg,
+ transforms=transforms,
)
- return FieldGrid.from_limits(length, wavelength, wavelength_limits, trange)
+ return FieldGrid.from_limits(
+ length, wavelength, wavelength_limits, trange, transforms=transforms
+ )
def _capillary_modes( # noqa: PLR0913 - capillary geometry and material keywords
diff --git a/src/solprop/grid.py b/src/solprop/grid.py
index 67522d72a..8c5dc0419 100644
--- a/src/solprop/grid.py
+++ b/src/solprop/grid.py
@@ -39,6 +39,7 @@
__all__ = [
"DEFAULT_COLLAR_FRACTION",
"FFT_SIZES",
+ "TRANSFORM_LIBRARIES",
"Collar",
"CollarPlacement",
"EnvelopeGrid",
@@ -48,6 +49,7 @@
"LineGrid",
"RadialGrid",
"TimeGrid",
+ "TransformLibrary",
"fft_cost",
"planck_taper",
"planck_taper_derivative",
@@ -1137,6 +1139,13 @@ def window_derivative(self, x: Float[np.ndarray, " n"]) -> Float[np.ndarray, " n
FFT_SIZES: Final = ("auto", "pow2", "smooth")
"""The transform-size rules of :meth:`FieldGrid.from_limits` and its envelope twin."""
+TransformLibrary = Literal["fftw", "mlx"]
+"""The transform library whose cost ``fft_size="auto"`` minimises: FFTW on a CPU, or
+MLX's Metal transforms on an Apple GPU (the ``mlx`` backend)."""
+
+TRANSFORM_LIBRARIES: Final = ("fftw", "mlx")
+"""The values of :data:`TransformLibrary`."""
+
DEFAULT_COLLAR_FRACTION: Final = 0.1
"""Width of each temporal collar, as a fraction of the realised window (SEP 21 D3)."""
@@ -1149,27 +1158,56 @@ def window_derivative(self, x: Float[np.ndarray, " n"]) -> Float[np.ndarray, " n
"""
-def fft_cost(n: int) -> float:
+_MLX_DIRECT_MAX: Final = 4096
+"""The longest transform MLX's GPU FFT runs directly at any 2-3-5-smooth length.
+
+Above it only a power of two keeps the direct algorithm; any other length takes
+Bluestein's, through padded transforms of twice the length or more.
+"""
+
+_MLX_BLUESTEIN_PENALTY: Final = 8.0
+"""The cost of an MLX GPU transform past :data:`_MLX_DIRECT_MAX` that is not a power of
+two, relative to the next power of two's.
+
+An Apple M5 Max (MLX 0.32), an rfft and irfft pair of one and of sixteen rows: every
+even 2-3-5-smooth length from 4320 to 10800 took 6 to 12 times the pair at the next
+power of two (10240: 715 us against 63 us at 16384), while every such length up to
+4096 took the time of a power of two.
+"""
+
+
+def fft_cost(n: int, library: TransformLibrary = "fftw") -> float:
"""Return the modelled relative cost of a real transform of length `n`.
- ``n log2 n``, times ``_RADIX_PENALTY`` for each factor of 3 and of 5.
+ For FFTW, ``n log2 n`` times ``_RADIX_PENALTY`` for each factor of 3 and of 5. For
+ MLX's GPU transforms, ``n log2 n`` at a power of two and at any length up to
+ 4096, and otherwise ``_MLX_BLUESTEIN_PENALTY`` times the next power of two's cost.
Parameters
----------
n : int
Transform length, at least 2.
+ library : {'fftw', 'mlx'}, optional
+ The library whose transforms are modelled; FFTW by default.
Returns
-------
float
- Relative cost, comparable between lengths only.
+ Relative cost, comparable between lengths of one library only.
Examples
--------
>>> from solprop.grid import fft_cost
>>> fft_cost(4096) < fft_cost(4374) # 4374 = 2 * 3^7
True
+ >>> fft_cost(16384, "mlx") < fft_cost(10240, "mlx")
+ True
"""
+ if library == "mlx":
+ if n <= _MLX_DIRECT_MAX or n & (n - 1) == 0:
+ return n * math.log2(n)
+ padded = 1 << (n - 1).bit_length()
+ return _MLX_BLUESTEIN_PENALTY * padded * math.log2(padded)
cost = n * math.log2(n)
for prime, penalty in _RADIX_PENALTY.items():
while n % prime == 0:
@@ -1358,6 +1396,7 @@ def _choose_sizes(
trange: float,
dt_fine: float,
fft_size: str,
+ library: TransformLibrary = "fftw",
) -> tuple[int, int]:
"""Choose the coarse and fine transform sizes together.
@@ -1378,8 +1417,10 @@ def _choose_sizes(
Requested time window, s.
dt_fine : float
Fine sample spacing, s.
- fft_size : {'pow2', 'smooth'}
- Rounding rule for both sizes.
+ fft_size : {'auto', 'pow2', 'smooth'}
+ Rounding rule for both sizes; ``'auto'`` takes the cheapest pair.
+ library : {'fftw', 'mlx'}, optional
+ The library whose cost ``'auto'`` minimises (:func:`fft_cost`).
Returns
-------
@@ -1394,7 +1435,8 @@ def _choose_sizes(
pairs = []
for n_fine in _smooth_sizes(_fft_size(needed, "smooth"), ceiling):
pair = _choose_sizes(half_bins, n_fine * dt_fine, dt_fine, "smooth")
- pairs.append((fft_cost(pair[1]) + fft_cost(pair[0]), pair[1], pair))
+ cost = fft_cost(pair[1], library) + fft_cost(pair[0], library)
+ pairs.append((cost, pair[1], pair))
return min(pairs)[2]
n_to = _fft_size(trange / dt_fine, fft_size)
half = half_bins(2.0 * np.pi / (n_to * dt_fine), n_to)
@@ -2015,6 +2057,7 @@ def from_limits( # noqa: PLR0913
dt: float | None = None,
ffac: float = 6.0,
fft_size: str = "auto",
+ transforms: TransformLibrary = "fftw",
collar_fraction: float = DEFAULT_COLLAR_FRACTION,
collar_placement: CollarPlacement = "outside",
# The return annotation stays quoted: beartype resolves it while the class body
@@ -2056,6 +2099,12 @@ def from_limits( # noqa: PLR0913
cheapest even 2-3-5-smooth size between the requirement and the next power
of two by a transform-cost model (:func:`fft_cost`); ``'pow2'`` the next
power of two; ``'smooth'`` the next even 2-3-5-smooth size.
+ transforms : {'fftw', 'mlx'}, optional
+ The transform library whose cost ``fft_size='auto'`` minimises: FFTW, the
+ default, or ``'mlx'`` for a single-precision run on the ``mlx`` backend,
+ whose GPU transforms past 4096 samples are fast at powers of two only
+ (:func:`fft_cost`). The keyword interfaces choose it from the run's
+ precision and backend.
collar_fraction : float, optional
Width of each temporal collar as a fraction of the realised window, in
``[0, 0.5)``. The collar lies **outside** the requested window: the grid is
@@ -2115,7 +2164,7 @@ def half_bins(d_omega: float, n_to: int) -> int:
return min(math.floor(omega_max_window / d_omega) + 2, n_to // 2 + 1)
needed = _needed_window(trange, collar_fraction, collar_placement)
- n_t, n_to = _choose_sizes(half_bins, needed, dt_fine, fft_size)
+ n_t, n_to = _choose_sizes(half_bins, needed, dt_fine, fft_size, transforms)
trange_even = n_to * dt_fine
d_omega = 2.0 * np.pi / trange_even
# dt comes from the integer ratio rather than from pi/omega[-1], so that the
@@ -2193,6 +2242,7 @@ def from_limits( # noqa: PLR0913
thg: bool = False,
ffac: float | None = None,
fft_size: str = "auto",
+ transforms: TransformLibrary = "fftw",
collar_fraction: float = DEFAULT_COLLAR_FRACTION,
collar_placement: CollarPlacement = "outside",
# The return annotation stays quoted: beartype resolves it while the class body
@@ -2237,6 +2287,9 @@ def from_limits( # noqa: PLR0913
fft_size : {'auto', 'pow2', 'smooth'}, optional
How the transform sizes are rounded up, as for
:meth:`FieldGrid.from_limits`; ``'auto'`` by default.
+ transforms : {'fftw', 'mlx'}, optional
+ The library whose cost ``'auto'`` minimises, as for
+ :meth:`FieldGrid.from_limits`; FFTW by default.
collar_fraction : float, optional
Width of each temporal collar as a fraction of the realised window, in
``[0, 0.5)``, outside the requested window, as for
@@ -2303,7 +2356,7 @@ def half_bins(d_omega: float, n_to: int) -> int:
return min(max(math.ceil(reach / d_omega), 1), n_to // 2)
needed = _needed_window(trange, collar_fraction, collar_placement)
- n_t, n_to = _choose_sizes(half_bins, needed, dt_fine, fft_size)
+ n_t, n_to = _choose_sizes(half_bins, needed, dt_fine, fft_size, transforms)
trange_even = n_to * dt_fine
d_omega = 2.0 * np.pi / trange_even
dt_coarse = dt_fine * (n_to // n_t)
diff --git a/src/solprop/recipe/metadata.py b/src/solprop/recipe/metadata.py
index 630e6fa28..753ce2ab0 100644
--- a/src/solprop/recipe/metadata.py
+++ b/src/solprop/recipe/metadata.py
@@ -2166,6 +2166,12 @@ def _grid(*rows: Row) -> tuple[Parameter, ...]:
"advanced",
"How the transform sizes are rounded up.",
),
+ _keyword(
+ "transforms",
+ _choice("fftw", "mlx"),
+ "advanced",
+ "Whose transform cost the automatic sizes are chosen by.",
+ ),
_keyword(
"collar_fraction",
_number(minimum=0.0, maximum=0.5),
diff --git a/src/solprop/translate/precision.py b/src/solprop/translate/precision.py
index 5c6eec9ba..250a13ae3 100644
--- a/src/solprop/translate/precision.py
+++ b/src/solprop/translate/precision.py
@@ -28,9 +28,6 @@
"""
import math
-from collections.abc import Iterator
-from contextlib import contextmanager
-from contextvars import ContextVar
from dataclasses import dataclass
from typing import Literal, get_args
@@ -60,7 +57,6 @@
"prefix_sum",
"scaled_square_sum",
"state_scale",
- "study_admission",
]
PrecisionName = Literal["double", "single"]
@@ -75,13 +71,15 @@
precision.
"""
-SINGLE_RTOL_CAP = 1e-5
+SINGLE_RTOL_CAP = 1e-4
"""The loosest default relative tolerance a single-precision run takes.
-The single-precision survival record measured 1e-6 and 1e-5 only, so an interface whose
-binary64 default is looser -- free space's 1e-4 -- takes this one under single
-precision until the looser value is qualified in binary32. An explicit tolerance above
-it is the caller's, and is admitted.
+The loosest the single-precision survival record has measured. It measured 1e-6 and
+1e-5 first; free space's binary64 default of 1e-4 was qualified in binary32 on 5
+November 2026 (#85): on a radial filament, a radial beam with its transverse collar and
+a Cartesian filament, binary32 at 1e-4 lies as close to a binary64 run at 1e-6 as
+binary64 at 1e-4 does, or closer. An explicit tolerance above it is the caller's, and
+is admitted.
"""
SINGLE_PRECISION_BACKENDS: tuple[str, ...] = ("numpy_ref", "mlx")
@@ -230,34 +228,10 @@ def precision_named(name: PrecisionName | Precision) -> Precision:
return SINGLE
-_STUDY: ContextVar[bool] = ContextVar("solprop_precision_study", default=False)
-
-
-@contextmanager
-def study_admission() -> Iterator[None]:
- """Admit, inside the block, what the survival study measures and the public refuses.
-
- The private, test-only route of SEP 33 section 5.2: the study runs the Adams
- integrator under single precision through it, to measure whether Adams can be
- admitted (Q2). No public interface sets it.
-
- Yields
- ------
- None
- Nothing; the admission is relaxed until the block exits.
- """
- token = _STUDY.set(True)
- try:
- yield
- finally:
- _STUDY.reset(token)
-
-
def admit_precision(
precision: Precision,
*,
backend: str,
- adams: bool,
rtol: float | None,
schedule: bool,
) -> None:
@@ -265,9 +239,10 @@ def admit_precision(
SEP 33 section 5.2. A binary64 run passes unchanged. A single-precision run is
refused on a backend that does not admit it (:data:`SINGLE_PRECISION_BACKENDS`),
- with the Adams integrator until the survival study admits it, and with an adaptive
- tolerance below :data:`SINGLE_RTOL_FLOOR`. The routes and responses no backend runs
- in binary32 are refused by
+ and with an adaptive tolerance below :data:`SINGLE_RTOL_FLOOR`. The Adams
+ integrator is admitted: binary32 Adams agrees with binary64 Adams to the method's
+ own truncation on the survival cases (#342). The routes and responses no backend
+ runs in binary32 are refused by
:meth:`~solprop.translate.problem.KernelProblem.validate`, where they are known.
Parameters
@@ -276,8 +251,6 @@ def admit_precision(
The run's precision.
backend : str
The concrete registry name the run executes on.
- adams : bool
- Whether the integrator is an Adams method.
rtol : float or None
The controller's relative tolerance, or ``None`` where the controller has none.
schedule : bool
@@ -291,8 +264,7 @@ def admit_precision(
Examples
--------
>>> from solprop.translate.precision import SINGLE, admit_precision
- >>> admit_precision(SINGLE, backend="numpy_ref", adams=False, rtol=1e-6,
- ... schedule=False) is None
+ >>> admit_precision(SINGLE, backend="numpy_ref", rtol=1e-6, schedule=False) is None
True
"""
if not precision.single:
@@ -304,13 +276,6 @@ def admit_precision(
f"{', '.join(SINGLE_PRECISION_BACKENDS)} (SEP 33)"
)
raise TranslationError(msg)
- if adams and not _STUDY.get():
- msg = (
- "the Adams integrator (Multistep) is not admitted under precision='single' "
- "until its single-precision survival is established; use "
- "integrator=RungeKutta(), the single-precision default"
- )
- raise TranslationError(msg)
if not schedule and rtol is not None and rtol < SINGLE_RTOL_FLOOR:
msg = (
f"rtol={rtol:g} is below the single-precision floor {SINGLE_RTOL_FLOOR:g}: "
diff --git a/src/solprop/translate/problem.py b/src/solprop/translate/problem.py
index ca25bf222..a696f38bb 100644
--- a/src/solprop/translate/problem.py
+++ b/src/solprop/translate/problem.py
@@ -1251,10 +1251,14 @@ def _check_precision(self) -> None:
def _check_single_exponent(self) -> None:
"""Refuse a step whose propagator or its inverse overflows binary32.
- The interaction picture multiplies each stage by ``exp(-dPhi)`` and the state
- by ``exp(dPhi)``; held in binary32, either is infinite once ``|Re dPhi|``
- passes ``log(FLT_MAX)``, about 88.72, where binary64 reaches 709.78. A strong
- spectral collar on a long step is the usual cause. As
+ The Runge-Kutta interaction picture multiplies each stage by ``exp(-dPhi)`` and
+ the state by ``exp(dPhi)``; held in binary32, either is infinite once
+ ``|Re dPhi|`` passes ``log(FLT_MAX)``, about 88.72, where binary64 reaches
+ 709.78. A strong spectral collar on a long step is the usual cause. The
+ low-storage march and the exponential Adams flow apply forward flows only, so a
+ damped bin's flow underflows harmlessly towards zero and only growth,
+ ``Re dPhi > 0``, can overflow: they are held to ``max Re dPhi``, Adams's times
+ the reach of its history (a sample is carried up to ``order + 1`` steps). As
:meth:`_check_exponent_budget` does for binary64, a replayed schedule's
longest step, or the floor ``dz_min``, is held to the limit -- an adaptive
controller rejects a non-finite trial above its floor and shrinks -- and every
@@ -1281,15 +1285,40 @@ def _check_single_exponent(self) -> None:
start = float(self.initial.z)
end = float(self.stepper.save_planes[-1])
step = min(step, end - start)
+ integrator = self.stepper.integrator
+ forward = not self.stepper.interpolate_planes and (
+ isinstance(integrator, LowStorageRungeKutta)
+ or (
+ isinstance(integrator, Multistep)
+ and integrator.formulation == "exponential"
+ )
+ )
+ reach = integrator.order + 1 if isinstance(integrator, Multistep) else 1
+ operator = self.linear.separable
+ geometry = self.transform.geometry
+ bounds = (
+ rate_bounds(operator)
+ if operator is not None
+ else radial_rate_bounds(self.linear)
+ if geometry is not None and geometry.kind == "radial"
+ else None
+ )
exponent = 0.0
- for first in {start, end - step}:
- phase = delta_phi(self.linear, first, first + step)
- exponent = max(exponent, float(np.max(np.abs(np.real(phase)))))
+ if bounds is not None:
+ # A free-space operator's rates, bounded as the binary64 budget bounds
+ # them, without forming the volume (seconds on a 384^2 x 750 grid).
+ growth = reach * step * bounds.gain
+ exponent = growth if forward else max(step * bounds.loss, growth)
+ for first in () if bounds is not None else {start, end - step}:
+ real = np.real(delta_phi(self.linear, first, first + step))
+ found = reach * float(np.max(real)) if forward else np.max(np.abs(real))
+ exponent = max(exponent, float(found))
if exponent <= EXPONENT_BUDGET * LOG_FLT_MAX:
return
+ name = "growth Re dPhi" if forward else "|Re dPhi|"
message = (
f"precision='single': the {source} {step:.3e} m gives a propagator "
- f"exponent |Re dPhi| of {exponent:.1f}"
+ f"exponent {name} of {exponent:.1f}"
)
remedy = (
"take steps shorter than "
@@ -1299,7 +1328,12 @@ def _check_single_exponent(self) -> None:
if exponent > LOG_FLT_MAX:
msg = (
f"{message}, past binary32's range exp({LOG_FLT_MAX:.2f}): the "
- f"interaction picture's inverse propagator overflows; {remedy}"
+ + (
+ "forward flow overflows"
+ if forward
+ else "interaction picture's inverse propagator overflows"
+ )
+ + f"; {remedy}"
)
raise TranslationError(msg)
warnings.warn(
diff --git a/tests/backends/test_compiled_multistep.py b/tests/backends/test_compiled_multistep.py
index efc416bed..a11494bfa 100644
--- a/tests/backends/test_compiled_multistep.py
+++ b/tests/backends/test_compiled_multistep.py
@@ -143,7 +143,7 @@ def test_the_settings_admit_the_compiled_backends():
**common,
)
assert settings.backend == "native"
- with pytest.raises(DriverError, match="numpy_ref and native only"):
+ with pytest.raises(DriverError, match="numpy_ref, native and mlx only"):
SimulationSettings(
control,
backend="cuda",
diff --git a/tests/backends/test_mlx.py b/tests/backends/test_mlx.py
index fb9a61cae..bbe2a0c47 100644
--- a/tests/backends/test_mlx.py
+++ b/tests/backends/test_mlx.py
@@ -47,6 +47,7 @@
record_after_march,
watched,
)
+from solprop.backends.mlx_gpu import backend as mlx_backend
from solprop.backends.mlx_gpu.arithmetic import (
DoubleFloatTerms,
fft_probe,
@@ -72,6 +73,7 @@
from solprop.stepper import (
FixedSchedule,
LowStorageRungeKutta,
+ Multistep,
PIController,
RungeKutta,
)
@@ -169,6 +171,191 @@ def test_low_storage_agrees_with_the_oracle():
assert_within(device, oracle, step_bound(10, 2, 11))
+@gpu_only
+def test_adams_agrees_with_the_oracle():
+ """The exponential Adams march replayed: its history and its trials on the device.
+
+ The moments are double-float on the device and binary64 on the host, each rounded
+ once, so they differ by at most one ulp; the step's bound covers that.
+ """
+ device, oracle = pair(lambda: gnlse("single", integrator=Multistep()))
+ assert_within(device, oracle, step_bound(10, 2, 11))
+
+
+def adams_gradient(backend: str) -> Simulation:
+ """Return an argon capillary on a pressure gradient, Kerr only, Adams replayed.
+
+ A varying operator: the history carries the transported compensation.
+ """
+ length = 0.004
+ return Simulation.from_capillary(
+ 50e-6,
+ length,
+ "Ar",
+ (1.0, 0.5),
+ wavelength=800e-9,
+ wavelength_limits=(300e-9, 3e-6),
+ trange=300e-15,
+ fwhm=10e-15,
+ energy=20e-6,
+ plasma=False,
+ n_save=2,
+ backend=backend,
+ precision="single",
+ integrator=Multistep(),
+ schedule=FixedSchedule.uniform(0.0, length, length / 16),
+ # The in-stage collar's stability would hold an Adams step to micrometres.
+ absorber_scheme="split_step",
+ noise=None,
+ )
+
+
+@gpu_only
+def test_a_compensated_adams_history_agrees_with_the_oracle():
+ device = finish(adams_gradient("mlx"))
+ oracle = finish(adams_gradient("numpy_ref"))
+ assert_within(device, oracle, step_bound(16, 2, 13))
+
+
+@gpu_only
+def test_the_trial_kernel_rounds_the_binary64_moments_once():
+ """Flow, moments and a compensation factor against binary64, rounded once."""
+ from solprop.backends.exponential import phi_functions # noqa: PLC0415
+
+ rng = np.random.default_rng(342)
+ n = 4096
+ # Bins on both sides of the join, with phases of thousands of radians.
+ terms = np.stack(
+ [
+ rng.normal(0, 0.3, n)
+ + 1j * rng.normal(0, 1, n) * np.repeat([0.4, 900], n // 2),
+ rng.normal(0, 0.01, n) + 1j * rng.normal(0, 0.2, n),
+ ]
+ ).reshape(2, 1, 1, n)
+ device = DoubleFloatTerms.upload(terms)
+ weights = np.array([0.6, 1.7])
+ rate = np.array([1.3, -0.2])
+ span = 0.4
+ flow, moments, factors = device.trial(
+ np.stack([weights, rate - weights / 2.0]), 7, np.array([span]), endpoint=False
+ )
+ x = np.tensordot(weights, terms, axes=1)
+ phi = phi_functions(x, 7)
+ expected = np.stack([math.factorial(k) * phi[k + 1] for k in range(7)])
+ factor = np.exp(span * x) * np.tensordot(rate - weights / 2.0, terms, axes=1)
+ for found, reference in (
+ (np.array(flow), np.exp(x)),
+ (np.array(moments), expected),
+ (np.array(factors[0]), factor),
+ ):
+ scale = np.maximum(np.abs(reference), np.finfo(np.float32).tiny)
+ # Rounded once from at least 44 bits: within one binary32 ulp.
+ assert np.max(np.abs(found - reference) / scale) <= 2 * U32
+
+
+@gpu_only
+@pytest.mark.parametrize(
+ "build",
+ [
+ pytest.param(lambda: capillary("single"), id="capillary"),
+ pytest.param(lambda: plasma_beam("single", route="radial"), id="radial"),
+ pytest.param(lambda: plasma_beam("single", route="cartesian"), id="cartesian"),
+ ],
+)
+def test_the_field_plasma_statistics_agree_with_the_oracle(build):
+ """The populations at every node, on the device by the stage's own passes.
+
+ The oracle scans in binary64 from the widened field; the device in binary32 with
+ the stage's rate kernel, running integral and stable population, as the envelope
+ grid's statistics already do.
+ """
+ from solprop.backends.numpy_ref.backend import NumpyRefBackend # noqa: PLC0415
+
+ with ExitStack() as cleanup:
+ backend = loaded(on("mlx", build()), cleanup)
+ backend.propagate_to(float(build().settings.save_planes[-1]))
+ observed = backend.observe().field
+ assert observed is not None
+ field = observed[0]
+ device = cast(MlxBackend, backend)._species_statistics(field)
+ oracle = NumpyRefBackend._species_statistics(cast(MlxBackend, backend), field)
+ assert set(device) == set(oracle)
+ assert float(np.max(oracle["species_ionisation"])) > 1e-8
+ for name, expected in oracle.items():
+ # The final fractions' binary32 scans: a few thousand units of rounding,
+ # against the statistic's largest value (an outer node's 1e-17 is zero there).
+ scale = float(np.max(np.abs(expected)))
+ np.testing.assert_allclose(device[name], expected, rtol=0.0, atol=1e-4 * scale)
+
+
+@pytest.mark.parametrize("steps", [None, 10], ids=["adaptive", "replayed"])
+def test_reusing_the_last_stage_as_the_next_first_changes_nothing(steps):
+ """First-same-as-last: the last stage's input is the accepted state itself.
+
+ The first stage's propagators are exactly one, so the reused stage is the one a
+ fresh evaluation would form, and the march is bitwise the same with or without it.
+ """
+ fields = []
+ for reuse in (False, True):
+ with ExitStack() as cleanup:
+ backend = cast(
+ MlxBackend,
+ loaded(on("mlx", gnlse("single", steps=steps)), cleanup),
+ )
+ assert backend._fsal
+ backend._fsal = reuse
+ backend.propagate_to(0.05)
+ observed = backend.observe()
+ assert observed.field is not None
+ fields.append((observed.field, observed.n_steps))
+ assert fields[0][1] == fields[1][1]
+ assert np.array_equal(fields[0][0], fields[1][0])
+
+
+@gpu_only
+@pytest.mark.parametrize("route", ["radial", "cartesian"])
+def test_the_transverse_edge_is_read_on_the_device_as_the_host_reads_it(route):
+ """Node and column energies from the device's own transform or synthesis.
+
+ Binary32 sums against the host's binary64 ones: held to a millionth of the
+ state's energy, three orders below the edge's warning.
+ """
+ from solprop.backends.driver import StepDriver # noqa: PLC0415
+
+ simulation = on("mlx", spatial_kerr(route, "single"))
+ problem = simulation.translate()
+ with ExitStack() as cleanup:
+ backend = cast(MlxBackend, select("mlx", problem, grid=simulation.grid))
+ cleanup.callback(backend.close)
+ monitor = simulation._boundary_monitor()
+ assert monitor is not None and monitor.transverse is not None
+ backend.set_initial(problem.initial.field0, None)
+ backend._bind_monitor(monitor)
+ backend.propagate_to(float(simulation.settings.save_planes[-1]))
+ state, edge = backend._require_state(), monitor.transverse
+ whole = StepDriver._edge_reading(backend, state, edge, full=True)
+ assert whole.totals is not None and whole.columns is not None
+ # The nodes' sums carry the grid's own weights, the columns' the state's.
+ scales = {"columns": float(np.sum(whole.columns))}
+ nodes = float(np.max(whole.totals))
+ for full in (True, False):
+ device = backend._edge_reading(state, edge, full=full)
+ host = StepDriver._edge_reading(backend, state, edge, full=full)
+ for name in ("faces", "clip", "totals", "columns"):
+ found, expected = getattr(device, name), getattr(host, name)
+ if expected is None:
+ assert found is None
+ continue
+ scale = scales.get(name, nodes)
+ assert np.max(np.abs(found - expected)) <= 1e-6 * scale
+
+
+def test_mlx_refuses_the_interaction_formulation_by_name():
+ simulation = gnlse("single", integrator=Multistep(formulation="interaction"))
+ with pytest.raises(BackendError, match="interaction formulation"):
+ select("mlx", simulation.translate(), grid=simulation.grid)
+
+
@pytest.mark.parametrize("gas", ["Ar", "N2"])
def test_a_plasma_capillary_agrees_with_the_oracle(gas):
"""Field plasma (argon), and molecular Raman beside it (nitrogen), 16 steps.
@@ -717,8 +904,8 @@ def test_a_non_finite_source_stops_every_march(march):
backend = cast(MlxBackend, loaded(on("mlx", simulation), cleanup))
original = backend._device_sources
- def poisoned(field, bundle, raman):
- sources = original(field, bundle, raman)
+ def poisoned(field, values, raman):
+ sources = original(field, values, raman)
return type(sources)(sources.polarisation * math.nan, sources.current)
backend._device_sources = poisoned
@@ -726,12 +913,14 @@ def poisoned(field, bundle, raman):
backend.propagate_to(0.05)
-def test_an_adaptive_trial_that_overflows_binary32_is_rejected_and_shrunk():
- """The device's trial past ``exp(88.72)`` is a rejection, as the oracle's is.
+def test_an_adaptive_trial_that_overflows_binary32_is_rejected_and_shrunk(monkeypatch):
+ """The interaction picture's trial past ``exp(88.72)`` is rejected, as the oracle's.
+ The lab-frame trial is turned off, so the device forms the inverse propagator.
Both runs are adaptive and take their own steps after the rejections, so they are
held to the survival record's field envelope, not to a rounding bound.
"""
+ monkeypatch.setattr(mlx_backend, "_TRANSPORT_REACH", math.inf)
device = run_to_end(overflowing_beam("single"), "mlx")
oracle = run_to_end(overflowing_beam("single"), "numpy_ref")
history = device.step_history
@@ -741,6 +930,46 @@ def test_an_adaptive_trial_that_overflows_binary32_is_rejected_and_shrunk():
assert_within(device.require_field(), oracle.require_field(), 1e-3)
+@gpu_only
+def test_a_trial_past_binary32s_range_is_taken_whole_in_the_lab_frame():
+ """Past ``|Re dPhi| = 79.8`` the stages are carried by forward flows alone.
+
+ No inverse is formed, so the device takes the millimetre in one step as binary64
+ does, where the interaction picture is rejected twice and shrinks. Both runs are
+ adaptive, so they are held to the survival record's field envelope.
+ """
+ device = run_to_end(overflowing_beam("single"), "mlx")
+ double = run_to_end(overflowing_beam("double"), "numpy_ref")
+ history = device.step_history
+ assert history.n_rejected == 0
+ assert int(np.sum(history.accepted)) == int(np.sum(double.step_history.accepted))
+ assert_within(device.require_field(), double.require_field(), 1e-3)
+
+
+@gpu_only
+@pytest.mark.parametrize("case", ["gnlse", "capillary"])
+def test_the_lab_frame_trial_is_the_interaction_picture_to_rounding(case, monkeypatch):
+ """Forced on every trial, the lab-frame combination changes only the rounding.
+
+ The same replayed steps (a soliton's ten, an ionising capillary's sixteen): the
+ forms differ by where each stage's flow is applied (``exp(Phi_i - Phi_j)`` on the
+ source against ``exp(Phi_i) exp(-Phi_j)``), a few units of binary32 rounding a
+ stage, against the field's largest sample.
+ """
+ fields = []
+ for reach in (math.inf, -1.0):
+ monkeypatch.setattr(mlx_backend, "_TRANSPORT_REACH", reach)
+ with ExitStack() as cleanup:
+ simulation = gnlse("single") if case == "gnlse" else capillary("single")
+ backend = loaded(on("mlx", simulation), cleanup)
+ backend.propagate_to(float(simulation.settings.save_planes[-1]))
+ observed = backend.observe()
+ assert observed.field is not None
+ fields.append(observed.field)
+ scale = float(np.max(np.abs(fields[0])))
+ assert_within(fields[1], fields[0], 1e-5 * scale, what="lab frame")
+
+
def test_the_state_stays_complex64_on_the_device():
with ExitStack() as cleanup:
backend = cast(MlxBackend, loaded(on("mlx", gnlse("single")), cleanup))
diff --git a/tests/backends/test_single_precision.py b/tests/backends/test_single_precision.py
index 9304689e3..636b730cb 100644
--- a/tests/backends/test_single_precision.py
+++ b/tests/backends/test_single_precision.py
@@ -83,7 +83,6 @@
PrecisionName,
combine,
precision_named,
- study_admission,
)
from vector_raman_cases import vector_problem
@@ -225,8 +224,10 @@ def automatic() -> Simulation:
automatic()
with pytest.raises(DriverError, match="binary64 only"):
dataclasses.replace(settings, backend="native")
- with pytest.raises(DriverError, match="Adams integrator"):
- dataclasses.replace(settings, integrator=Multistep())
+ # The Adams integrator is admitted (#342); the default stays Runge-Kutta.
+ assert isinstance(
+ dataclasses.replace(settings, integrator=Multistep()).integrator, Multistep
+ )
with pytest.raises(DriverError, match="floor"):
dataclasses.replace(
settings,
@@ -249,9 +250,9 @@ def test_the_compiled_backends_refuse_a_single_precision_problem(name):
def test_the_oracle_applies_the_settings_admission_to_a_problem_past_them():
"""``registry.select`` on a translated problem meets the settings' refusals too.
- The settings refuse the Adams integrator and a tolerance below the floor under
- single precision; a problem replaced after translation reached the backend without
- them. Adams is admitted again only inside the survival study's private switch.
+ The settings refuse a tolerance below the floor under single precision; a problem
+ replaced after translation reached the backend without them. The Adams integrator
+ is admitted (#342).
"""
problem = gnlse("single", steps=None).translate()
stepper = problem.stepper
@@ -264,12 +265,9 @@ def test_the_oracle_applies_the_settings_admission_to_a_problem_past_them():
stepper, controller=dataclasses.replace(stepper.controller, rtol=1e-8)
),
)
- with pytest.raises(BackendError, match=r"Adams integrator \(Multistep\)"):
- select("numpy_ref", adams)
with pytest.raises(BackendError, match="below the single-precision floor"):
select("numpy_ref", tight)
- with study_admission():
- select("numpy_ref", adams).close()
+ select("numpy_ref", adams).close()
def test_a_step_whose_inverse_propagator_overflows_binary32_is_refused():
@@ -285,11 +283,31 @@ def test_a_step_whose_inverse_propagator_overflows_binary32_is_refused():
capillary("single", length=length, schedule=schedule).translate()
+@pytest.mark.parametrize(
+ "integrator",
+ [LowStorageRungeKutta(), Multistep()],
+ ids=["low_storage", "adams"],
+)
+def test_a_forward_only_march_takes_the_damped_step_runge_kutta_cannot(integrator):
+ """The low-storage march and the exponential Adams flow form no inverse.
+
+ A damped bin's forward flow underflows towards zero in binary32, harmlessly, so the
+ step the Runge-Kutta interaction picture is refused (|Re dPhi| = 150) is admitted;
+ only growth would overflow them.
+ """
+ length = 0.001
+ schedule = FixedSchedule.uniform(0.0, length, length / 4)
+ capillary(
+ "single", length=length, schedule=schedule, integrator=integrator
+ ).translate()
+
+
def overflowing_beam(precision: str) -> Simulation:
"""Return a radial Kerr beam whose first trial step is the whole millimetre.
The default collar over that step reaches ``|Re dPhi| = 459``: inside binary64's
- range, past binary32's 88.72.
+ range, past binary32's 88.72, in the interaction picture's inverse propagator --
+ a Runge-Kutta trial's; the exponential Adams flow forms no inverse.
"""
length = 1e-3
grid = EnvelopeGrid.from_limits(
@@ -304,6 +322,7 @@ def overflowing_beam(precision: str) -> Simulation:
dz_init=length,
precision=precision, # pyright: ignore[reportArgumentType]
backend="numpy_ref",
+ integrator=RungeKutta(),
)
return Simulation.from_radial(
grid,
@@ -1141,15 +1160,13 @@ def gradient(precision: str) -> Simulation:
pytest.param(gradient, id="gradient"),
],
)
-def test_adams_runs_in_binary32_under_the_study_admission(build):
- """The study's private route (Q2): the flow, its moments and the prediction rounded.
+def test_adams_runs_in_binary32(build):
+ """The flow, its moments and the prediction rounded once (#342).
- Adams is refused publicly; the study measures it. Its binary32 result agrees with
- its binary64 one to the tolerance's truncation; on a gradient the operator is an
- expansion and the predictor carries its compensation.
+ Its binary32 result agrees with its binary64 one to the tolerance's truncation; on
+ a gradient the operator is an expansion and the predictor carries its compensation.
"""
- with study_admission():
- single, double = finish(build("single")), finish(build("double"))
+ single, double = finish(build("single")), finish(build("double"))
assert_within(single, double, 1e-4)
diff --git a/tests/driver/test_interface_defaults.py b/tests/driver/test_interface_defaults.py
index 46f8997bd..d5ecc5f8a 100644
--- a/tests/driver/test_interface_defaults.py
+++ b/tests/driver/test_interface_defaults.py
@@ -179,7 +179,7 @@ def test_a_copy_of_the_settings_still_names_no_integrator():
assert not dataclasses.replace(settings, step_planes=2).integrator_named
assert dataclasses.replace(settings, integrator=Multistep()).integrator_named
single = dataclasses.replace(settings, precision="single", backend="numpy_ref")
- assert isinstance(single.integrator, RungeKutta)
+ assert isinstance(single.integrator, Multistep)
assert not single.integrator_named
@@ -355,9 +355,9 @@ def _build(route, precision, through): # noqa: PLR0911 - one return per route f
)
-# route: (binary64 integrator, binary64 rtol, binary32 rtol). Binary32 steps with
-# RungeKutta() everywhere; its rtol is the larger of binary64's and the floor 1e-6,
-# capped at 1e-5 (the maintainers' ruling on the single-precision default).
+# route: (integrator, binary64 rtol, binary32 rtol). Both precisions step with the
+# route's integrator (#342); binary32's rtol is the larger of binary64's and the floor
+# 1e-6, capped at 1e-4 (the maintainers' ruling on the single-precision default).
DEFAULTS = {
"gnlse": (RungeKutta, 1e-7, 1e-6),
"capillary": (Multistep, 1e-6, 1e-6),
@@ -368,8 +368,8 @@ def _build(route, precision, through): # noqa: PLR0911 - one return per route f
"waveguide mode_average": (RungeKutta, 1e-5, 1e-5),
"waveguide general": (RungeKutta, 1e-5, 1e-5),
"radial": (Multistep, 1e-5, 1e-5),
- "free cartesian": (RungeKutta, 1e-4, 1e-5),
- "free line": (RungeKutta, 1e-4, 1e-5),
+ "free cartesian": (RungeKutta, 1e-4, 1e-4),
+ "free line": (RungeKutta, 1e-4, 1e-4),
"planar": (Multistep, 1e-5, 1e-5),
}
@@ -405,7 +405,7 @@ def test_every_route_resolves_its_default_integrator_and_tolerance(
if precision == "double":
assert (integrator, rtol) == (double_integrator, double_rtol)
else:
- assert (integrator, rtol) == (RungeKutta, single_rtol)
+ assert (integrator, rtol) == (double_integrator, single_rtol)
assert not simulation.settings.integrator_named
@@ -417,16 +417,18 @@ def test_a_copy_in_the_other_precision_takes_the_route_s_default(route):
assert type(double.integrator) is DEFAULTS[route][0]
assert not double.integrator_named
back = dataclasses.replace(double, precision="single")
- assert isinstance(back.integrator, RungeKutta)
+ assert type(back.integrator) is DEFAULTS[route][0]
+ assert not back.integrator_named
def test_the_single_precision_tolerance_rule():
assert [rtol_in_precision(rtol, "single") for rtol in (1e-8, 1e-7, 1e-6)] == [
SINGLE_RTOL_FLOOR
] * 3
- assert [rtol_in_precision(rtol, "single") for rtol in (1e-5, 1e-4, 1e-3)] == [
+ assert rtol_in_precision(1e-5, "single") == 1e-5
+ assert [rtol_in_precision(rtol, "single") for rtol in (1e-4, 1e-3)] == [
SINGLE_RTOL_CAP
- ] * 3
+ ] * 2
assert rtol_in_precision(1e-4, "double") == 1e-4
# An explicit tolerance is the caller's, above the cap included.
simulation = Simulation.from_waveguide(
@@ -438,18 +440,19 @@ def test_the_single_precision_tolerance_rule():
# ------------------------------------------------- refusals name their option
-def test_single_precision_refuses_the_adams_method_by_its_own_name():
+def test_single_precision_admits_the_adams_method():
+ # #342: binary32 Adams agrees with binary64 Adams to the method's own truncation.
for backend in ("numpy_ref", "mlx"):
- with pytest.raises(DriverError, match=r"Adams integrator \(Multistep\) is not"):
- SimulationSettings(
- PIController(rtol=1e-6, atol=0.0),
- save_planes=[1.0],
- dz_max=1.0,
- dz_init=1e-3,
- precision="single",
- backend=backend,
- integrator=Multistep(),
- )
+ settings = SimulationSettings(
+ PIController(rtol=1e-6, atol=0.0),
+ save_planes=[1.0],
+ dz_max=1.0,
+ dz_init=1e-3,
+ precision="single",
+ backend=backend,
+ integrator=Multistep(),
+ )
+ assert isinstance(settings.integrator, Multistep)
def test_a_tdse_run_s_refusals_name_the_precision_and_the_integrator():
@@ -636,7 +639,7 @@ def test_the_table_holds_what_every_route_resolves(route):
assert row.rtol == double_rtol
assert default_rtol(TABLE_ROWS[route], "single") == single_rtol
assert type(default_integrator(TABLE_ROWS[route], "double")) is integrator
- assert type(default_integrator(TABLE_ROWS[route], "single")) is RungeKutta
+ assert type(default_integrator(TABLE_ROWS[route], "single")) is integrator
def test_every_row_of_the_table_is_measured_or_a_named_variant():
diff --git a/tests/driver/test_resume_history.py b/tests/driver/test_resume_history.py
index 6eb03fddc..3b68aa0b4 100644
--- a/tests/driver/test_resume_history.py
+++ b/tests/driver/test_resume_history.py
@@ -43,6 +43,7 @@
from solprop.output.schema import MarchSnapshot, SavedPlane, _example_metadata
from solprop.stepper import Multistep, RungeKutta
from solprop.stepper.multistep import ComparisonMultistep
+from solprop.translate.precision import SINGLE_RTOL_FLOOR
# The fixtures here launch noise-free into time windows kept tight for speed, which
# hold more than a millionth of the energy in their guards or collar: the boundary
@@ -80,15 +81,24 @@ def build():
return build
-def varying(backend, rtol=RTOL):
+def varying(backend, rtol=RTOL, **keywords):
"""Return a helium capillary along a pressure gradient: a compensated march."""
def build():
- return gradient(integrator=EXPONENTIAL, rtol=rtol, backend=backend)
+ return gradient(integrator=EXPONENTIAL, rtol=rtol, backend=backend, **keywords)
return build
+def single(rtol):
+ """Return the precision of a single-precision case at `rtol`.
+
+ The tight reference runs below single precision's tolerance floor, so it is the
+ binary64 run, which the binary32 one is held against (#342).
+ """
+ return {"precision": "single" if rtol >= SINGLE_RTOL_FLOOR else "double"}
+
+
def coupled(backend, rtol=RTOL):
"""Return a coherent wall along a gradient: a frozen-residual coupled flow."""
@@ -148,6 +158,20 @@ def tight_run(build_tight, path):
"varying-native": lambda _, rtol=RTOL: varying("native", rtol),
"coupled-numpy_ref": lambda _, rtol=RTOL: coupled("numpy_ref", rtol),
"coupled-native": lambda _, rtol=RTOL: coupled("native", rtol),
+ # #342: binary32 Adams resumes in binary32, its history and state narrowed.
+ "single-soliton-numpy_ref": lambda build, rtol=RTOL: soliton(
+ build, "numpy_ref", rtol=rtol, atol=0.0, **single(rtol)
+ ),
+ "single-soliton-mlx": lambda build, rtol=RTOL: soliton(
+ build,
+ "mlx" if rtol >= SINGLE_RTOL_FLOOR else "native",
+ rtol=rtol,
+ atol=0.0,
+ **single(rtol),
+ ),
+ "single-varying-mlx": lambda _, rtol=RTOL: varying(
+ "mlx" if rtol >= SINGLE_RTOL_FLOOR else "native", rtol, **single(rtol)
+ ),
}
@@ -162,6 +186,10 @@ def test_a_resumed_run_is_the_uninterrupted_one(
):
if case.endswith("-native"):
pytest.importorskip("solprop_native")
+ if case.endswith("-mlx"):
+ # The skip reason native/ci/check_skips.py expects off macOS; the macOS lanes
+ # install MLX and require Metal, so there the case runs.
+ pytest.importorskip("mlx.core")
build = CASES[case](build_simulation)
whole, part = tmp_path / "whole.h5", tmp_path / "part.h5"
build().run(whole, progress="none")
diff --git a/tests/test_benchmark_ab.py b/tests/test_benchmark_ab.py
index e625fe1dd..b01a05baf 100644
--- a/tests/test_benchmark_ab.py
+++ b/tests/test_benchmark_ab.py
@@ -212,3 +212,13 @@ def test_small_case_runs_both_builds_in_alternating_order(
assert row["field_difference"] == 0.0
assert {item["python_executable"] for item in results["provenance"]["baseline"]}
assert read_record(out / "plan.json")["harness_files"]
+
+
+def test_each_arm_runs_its_own_backend_at_that_backends_precision():
+ values = {"case": "x", "backend": "native", "precision": "double"}
+ assert ab.arm_configuration(values, "mlx") == {
+ "case": "x",
+ "backend": "mlx",
+ "precision": "single",
+ }
+ assert ab.arm_configuration(values, "native")["precision"] == "double"
diff --git a/tests/test_benchmark_cases.py b/tests/test_benchmark_cases.py
index 425abaea4..c6087c660 100644
--- a/tests/test_benchmark_cases.py
+++ b/tests/test_benchmark_cases.py
@@ -234,3 +234,42 @@ def test_tracked_definitions_change_only_with_a_new_revision():
for name in ("spatial_absorber", "radial_filament_256", "radial_filament_512"):
assert revisions.pop(name) == 2, name
assert set(revisions.values()) == {1}
+
+
+def test_a_single_precision_variant_is_noiseless_and_a_pow2_grid_a_power_of_two():
+ values = {**configuration("he_rdw_averaged"), "precision": "single"}
+ single = build(values)
+ assert single.settings.precision == "single"
+ assert single.noise is None or single.noise.model is None
+ quiet = build({**configuration("he_rdw_averaged"), "noise": "none"})
+ assert quiet.settings.precision == "double"
+ assert quiet.noise is None or quiet.noise.model is None
+ pow2 = build({**configuration("he_rdw_averaged"), "fft_size": "pow2"})
+ n_t = pow2.grid.n_t
+ assert n_t & (n_t - 1) == 0
+ assert build(configuration("he_rdw_averaged")).grid.n_t == 5120
+ spatial = build({**configuration("radial_filament_256"), "fft_size": "pow2"})
+ assert spatial.grid.n_t & (spatial.grid.n_t - 1) == 0
+
+
+def test_mlx_configurations_run_in_single_precision_and_refuse_interaction_adams():
+ from benchmarks.runner import plan_rows # noqa: PLC0415
+
+ cases = (CASES["he_rdw_averaged"], CASES["planar"], CASES["kerr_beam_192"])
+ rows, skipped = plan_rows(
+ cases,
+ ("default", "multistep", "multistep-interaction"),
+ "1",
+ 1,
+ backend="mlx",
+ fft_size="pow2",
+ )
+ assert [row["id"] for row in rows] == [
+ "he_rdw_averaged.default.t1",
+ "he_rdw_averaged.multistep.t1",
+ "kerr_beam_192.default.t1",
+ ]
+ assert all(row["configuration"]["precision"] == "single" for row in rows)
+ assert all(row["configuration"]["fft_size"] == "pow2" for row in rows)
+ assert any("exponential formulation" in reason for reason in skipped)
+ assert any(reason.startswith("planar") for reason in skipped)
diff --git a/tests/test_grid.py b/tests/test_grid.py
index dae3db539..8d3d42883 100644
--- a/tests/test_grid.py
+++ b/tests/test_grid.py
@@ -175,6 +175,64 @@ def test_auto_sizes_cost_no_more_than_the_power_of_two():
assert auto.n_to % auto.n_t == 0
+def test_mlx_costs_choose_a_power_of_two_past_the_direct_length():
+ # MLX's GPU FFT is direct at any smooth length up to 4096 and at powers of two,
+ # and takes Bluestein's algorithm at every other length (grid._MLX_DIRECT_MAX).
+ assert fft_cost(16384, "mlx") < fft_cost(10240, "mlx")
+ assert fft_cost(3072, "mlx") < fft_cost(4096, "mlx")
+ assert fft_cost(3072, "fftw") == fft_cost(3072)
+ for trange in (137e-15, 400e-15, 550e-15, 923e-15):
+ mlx = FieldGrid.from_limits(**{**RDW, "trange": trange}, transforms="mlx")
+ pow2 = FieldGrid.from_limits(**{**RDW, "trange": trange}, fft_size="pow2")
+ direct = mlx.n_to <= 4096 or mlx.n_to & (mlx.n_to - 1) == 0
+ assert direct
+ assert mlx.n_to <= pow2.n_to
+ if pow2.n_to > 4096:
+ assert (mlx.n_t, mlx.n_to) == (pow2.n_t, pow2.n_to)
+ envelope = EnvelopeGrid.from_limits(
+ 1.0, 835e-9, (500e-9, 2e-6), 12.5e-12, transforms="mlx"
+ )
+ assert envelope.n_to & (envelope.n_to - 1) == 0
+ small = FieldGrid.from_limits(0.03, 800e-9, (500e-9, 1.6e-6), 250e-15)
+ assert small.n_to <= 4096
+ assert (
+ FieldGrid.from_limits(
+ 0.03, 800e-9, (500e-9, 1.6e-6), 250e-15, transforms="mlx"
+ ).n_to
+ == small.n_to
+ )
+
+
+def test_a_single_precision_interface_grid_is_sized_for_mlx():
+ from solprop.driver import Simulation # noqa: PLC0415
+ from solprop.translate.precision import PrecisionName # noqa: PLC0415
+
+ sizes = {}
+ runs: tuple[tuple[PrecisionName, str], ...] = (
+ ("double", "auto"),
+ ("single", "numpy_ref"),
+ ("single", "mlx"),
+ )
+ for precision, backend in runs:
+ simulation = Simulation.from_capillary(
+ 125e-6,
+ 1.5,
+ "He",
+ (0.8, 0.0),
+ wavelength=800e-9,
+ wavelength_limits=(90e-9, 4e-6),
+ trange=400e-15,
+ fwhm=7.5e-15,
+ energy=275e-6,
+ precision=precision,
+ backend=backend,
+ noise=None,
+ )
+ sizes[precision, backend] = simulation.grid.n_to
+ assert sizes["double", "auto"] == sizes["single", "numpy_ref"] == 10240
+ assert sizes["single", "mlx"] == 16384
+
+
@pytest.mark.parametrize("grid_name", ["field_grid", "envelope_grid"])
def test_coarse_and_fine_grids_satisfy_the_invariants(grid_name, request):
grid = request.getfixturevalue(grid_name)
diff --git a/tests/translate/test_precision.py b/tests/translate/test_precision.py
index a3904b8b8..08eed1e88 100644
--- a/tests/translate/test_precision.py
+++ b/tests/translate/test_precision.py
@@ -28,7 +28,6 @@
prefix_sum,
scaled_square_sum,
state_scale,
- study_admission,
)
TINY32 = float(np.finfo(np.float32).tiny)
@@ -50,13 +49,10 @@ def admit(
precision: Precision,
backend: str = "numpy_ref",
*,
- adams: bool = False,
rtol: float = 1e-6,
schedule: bool = False,
) -> None:
- admit_precision(
- precision, backend=backend, adams=adams, rtol=rtol, schedule=schedule
- )
+ admit_precision(precision, backend=backend, rtol=rtol, schedule=schedule)
admit(SINGLE)
admit(DOUBLE, "native", rtol=1e-12)
@@ -66,10 +62,6 @@ def admit(
admit(SINGLE, rtol=1e-7)
# A replayed schedule reads no tolerance.
admit(SINGLE, rtol=1e-12, schedule=True)
- with pytest.raises(TranslationError, match="Adams integrator"):
- admit(SINGLE, adams=True)
- with study_admission():
- admit(SINGLE, adams=True)
assert SINGLE_RTOL_FLOOR == 1e-6