diff --git a/benchmarks/ab.py b/benchmarks/ab.py index 4b9fb50e7..6a8aa7ce8 100644 --- a/benchmarks/ab.py +++ b/benchmarks/ab.py @@ -140,8 +140,8 @@ def same_work( ) -> bool | None: """Whether both builds took one and the same (accepted, rejected) steps. - ``None`` when a repetition did not count its steps (a group on ``Batch``, which - watches no point's run): nothing was compared, which is not a match. + ``None`` when a repetition did not count its steps: nothing was compared, which + is not a match. """ if any(None in steps for steps in baseline | candidate): return None diff --git a/benchmarks/builders.py b/benchmarks/builders.py index 0ad74db59..c4631b474 100644 --- a/benchmarks/builders.py +++ b/benchmarks/builders.py @@ -573,7 +573,7 @@ def build(configuration: Record) -> Simulation: "fields": fields, "field_planes": (len(itinerary),) if fields == "planes" else (), } - if case.workload in ("scan", "group"): + if case.workload == "scan": # A scan keeps the fields run_scan asks for; its points keep the default. del observed["fields"], observed["field_planes"] chosen = integrator(configuration["stepper"]) diff --git a/benchmarks/device_split.py b/benchmarks/device_split.py index 941f8e598..64f39a31e 100644 --- a/benchmarks/device_split.py +++ b/benchmarks/device_split.py @@ -240,6 +240,10 @@ def launch() -> object: def _calls(nx: int, steps: int, planes: int) -> dict[str, Any]: + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + specs = {"none": StatsSpec(names=())} specs.update( (name, StatsSpec(names=(name,))) @@ -298,7 +302,7 @@ def _calls(nx: int, steps: int, planes: int) -> dict[str, Any]: # host's azimuthal average of a Gaussian's fluence takes on this machine. widths = { "moments": _timed( - lambda: state.spatial_statistics(32, 0.5 * EPS0 * C, 0.0), 5 + lambda: _testing.spatial_statistics(state, 32, 0.5 * EPS0 * C, 0.0), 5 ), "host_average": _timed( lambda: cartesian_fluence_widths( diff --git a/benchmarks/exercises.py b/benchmarks/exercises.py index fbb828c7c..b2df09dc5 100644 --- a/benchmarks/exercises.py +++ b/benchmarks/exercises.py @@ -166,7 +166,7 @@ def mismatch(pressure: float) -> float: def fiber(index: int = 0, *, noise: bool = False) -> Simulation: - """Keep one member of the lockstep fixture, including its periodic statistics.""" + """Build the fibre exercise, including its periodic statistics.""" return Simulation.from_gnlse( 0.11 * (index + 1), 1e-3, diff --git a/benchmarks/native_session.py b/benchmarks/native_session.py index d55ec6272..2a6b17c08 100644 --- a/benchmarks/native_session.py +++ b/benchmarks/native_session.py @@ -39,10 +39,6 @@ _TIMED = frozenset( { - "adams_march_run", - "rk_march_run", - "statistics", - "spatial_statistics", "field_to_host", "advance", "export", diff --git a/benchmarks/registry.py b/benchmarks/registry.py index 62c83f857..691863d80 100644 --- a/benchmarks/registry.py +++ b/benchmarks/registry.py @@ -9,8 +9,8 @@ native backend unless asked otherwise (SEP 38). The ``tracking`` set is what ``python -m benchmarks track`` times by default; every other case runs only when named. The ``sep47`` set is SEP 47 section 7.2's matrix of short windows: each case holds the -events it measures (periodic rows, snapshots, a group's members, repeated inputs, saved -or field-free planes, a wide coupled flow) and finishes in seconds. +events it measures (periodic rows, snapshots, repeated inputs, saved or field-free +planes, a wide coupled flow) and finishes in seconds. """ from __future__ import annotations @@ -44,7 +44,7 @@ WIDTHS = ("1", "production") SEED = 20261027 """The noise seed every case fixes, so that its repeats take the same steps.""" -WORKLOADS = ("run", "with_input", "scan", "group") +WORKLOADS = ("run", "with_input", "scan") OUTPUTS = ("memory", "hdf5") _OPTIONAL = { "workload": "run", @@ -102,8 +102,7 @@ class Case: What one timed repetition is (SEP 47 section 7.2): ``"run"``, one run of the case; ``"with_input"``, three runs of it with other inputs through ``Simulation.with_input``; ``"scan"``, a four-point ``run_scan`` on ``Local`` - derived from the case with ``with_input``; ``"group"``, the same four points - on ``Batch(4)``, which needs a fixed `step`. + derived from the case with ``with_input``. output : str Where a ``"run"`` writes: ``"memory"`` or ``"hdf5"``, a file in the worker's scratch directory. @@ -141,8 +140,6 @@ def __post_init__(self) -> None: raise SuiteError(f"{self.name}: unknown workload or output") if self.fields not in ("all", "planes", "none"): raise SuiteError(f"{self.name}: unknown field retention {self.fields}") - if self.workload == "group" and self.step is None: - raise SuiteError(f"{self.name}: a group replays a fixed step") if self.snapshots is not None and ( self.workload != "run" or self.output != "hdf5" or self.snapshots < 0 ): @@ -679,16 +676,6 @@ def configuration( fields="none", **_SESSION, ), - Case( - "group_batch", - 1, - ("sep47",), - source="scan_local on Batch(4), replaying ten 1.6 mm steps", - workload="group", - fields="none", - step=1.6e-3, - **_SESSION, - ), *( Case( f"{base}_{kept}_{output}", diff --git a/benchmarks/sessions.py b/benchmarks/sessions.py index c632e5452..0e4692474 100644 --- a/benchmarks/sessions.py +++ b/benchmarks/sessions.py @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""Build SEP 47's fibre windows and run its repeated, scanned and grouped workloads. +"""Build SEP 47's fibre windows and run its repeated and scanned workloads. The ``sep47`` set's cases on one fibre (SEP 47 section 7.2): the N = 3 soliton of ``gnlse_soliton`` (its dispersion, nonlinearity, 100 fs sech launch and time grid, @@ -20,10 +20,7 @@ step planes becomes possible once SEP 47 schedules snapshots independently; - ``with_input_repeat``: three runs of other inputs through ``Simulation.with_input``; - ``scan_local``: four points derived from the case with ``with_input``, on ``Local``, - each run watched to count its steps; -- ``group_batch``: the same four points on ``Batch(4)``, replaying ten 1.6 mm steps - with the split-step collar, which a fixed step this long needs. ``Batch`` watches no - point's run, so its steps are left uncounted except by the structural counters. + each run watched to count its steps. Import this module only after the worker has configured its scientific runtimes. """ @@ -41,7 +38,7 @@ from benchmarks.records import Record, SuiteError from benchmarks.registry import CASES from solprop.driver import Simulation -from solprop.driver.executors import Batch, Local +from solprop.driver.executors import Local from solprop.driver.scan import Scan, run_scan from solprop.log import NullReporter, NullScanReporter, ProgressReporter from solprop.output import MemoryOutput @@ -181,7 +178,7 @@ def repetition( Parameters ---------- workload : str - ``"with_input"``, ``"scan"`` or ``"group"`` (``benchmarks.registry.Case``). + ``"with_input"`` or ``"scan"`` (``benchmarks.registry.Case``). simulation : solprop.driver.Simulation The case, as built. scratch : pathlib.Path @@ -192,9 +189,8 @@ def repetition( Returns ------- dict - Accepted and rejected steps summed over the runs, where they are watched - (``None`` for a group, whose ``Batch`` watches no point's run); whether the - last plane of every run is finite (its field, or for a field-free scan its + Accepted and rejected steps summed over the runs; whether the last plane of + every run is finite (its field, or for a field-free scan its statistics); the position reached and the runs made. numpy.ndarray or None The last run's final field, or ``None`` for a scan. @@ -219,7 +215,7 @@ def repetition( "finite": final is not None and bool(np.all(np.isfinite(final))), } return record, final - if workload not in ("scan", "group"): + if workload != "scan": raise SuiteError(f"unknown workload {workload}") watch = _Watch() path = scratch / f"{workload}.h5" @@ -227,7 +223,7 @@ def repetition( Scan(f"sep47_{workload}", scale=list(SCALES)), lambda point: simulation.with_input(launch(float(point.values["scale"]))), # pyright: ignore[reportArgumentType] - a scale variable output=path, - executor=Batch(len(SCALES)) if workload == "group" else Local(), + executor=Local(), fields=fields, # pyright: ignore[reportArgumentType] - a registry field retention progress=watch, ) @@ -237,10 +233,11 @@ def repetition( finite = [ _finite_statistics(read_point(path, index)) for index in range(len(SCALES)) ] - watched = len(watch.runs) == len(SCALES) + if len(watch.runs) != len(SCALES): + raise SuiteError(f"the {workload} watched {len(watch.runs)} runs") record = { - "accepted": sum(run.accepted for run in watch.runs) if watched else None, - "rejected": sum(run.rejected for run in watch.runs) if watched else None, + "accepted": sum(run.accepted for run in watch.runs), + "rejected": sum(run.rejected for run in watch.runs), "z": float(simulation.settings.save_planes[-1]), "runs": len(SCALES), "finite": None if None in finite else all(finite), diff --git a/benchmarks/worker.py b/benchmarks/worker.py index a29bf2ff1..c241c2760 100644 --- a/benchmarks/worker.py +++ b/benchmarks/worker.py @@ -10,7 +10,7 @@ constructs its backend, runs an untimed warm-up over the first part of the guide, then times complete runs through the driver's own loop, each restarted from the translated launch with the boundary monitor ``Simulation.run`` attaches, or the case's workload of -repeated inputs, a scan or a group (``benchmarks.registry.Case``). Asked to count, it +repeated inputs or a scan (``benchmarks.registry.Case``). Asked to count, it then makes one more repetition with the native adapter's structural counters on (SEP 47 section 7.3), reported apart so that counting costs no timed repetition anything. It prints one JSON event per line; the last is the receipt. diff --git a/changelog.d/241-reference-coupled-batch.changed.md b/changelog.d/241-reference-coupled-batch.changed.md deleted file mode 100644 index 2aae904de..000000000 --- a/changelog.d/241-reference-coupled-batch.changed.md +++ /dev/null @@ -1 +0,0 @@ -A `Batch` scan on `numpy_ref` now runs points with a coupled flow (a coherent wall, the taper coupling, a split block, a moving guide) member by member, each with its own trial and flow, instead of refusing them; points without one still take the reference's member-axis batch (#241). diff --git a/changelog.d/benchmark-sep47-matrix.added.md b/changelog.d/benchmark-sep47-matrix.added.md index 40be50e6c..b0a7ea84c 100644 --- a/changelog.d/benchmark-sep47-matrix.added.md +++ b/changelog.d/benchmark-sep47-matrix.added.md @@ -1 +1 @@ -The benchmark harness has a `sep47` set of short windows for SEP 47's performance matrix: statistics rows at every step under `Multistep()` and `RungeKutta()`, snapshot controllers idle, sparse and at every endpoint, repeated `with_input` runs, a four-point scan on `Local` and the same points on `Batch(4)`, saved and field-free radial and Cartesian planes in memory and in HDF5, and coupled flows of 4 and 17 channels. `track --counters` and `ab --counters` add one separately reported run per worker with structural counters from the native backend, counted the same way whether the native execution session or the transitional driver session serves the run: its returns to Python by cause, native march calls, attempts, planes, statistics rows, transverse-edge reads, the fields copied to the host and loaded into the native state, and their bytes. +The benchmark harness has a `sep47` set of short windows for SEP 47's performance matrix: statistics rows at every step under `Multistep()` and `RungeKutta()`, snapshot controllers idle, sparse and at every endpoint, repeated `with_input` runs, a four-point scan on `Local`, saved and field-free radial and Cartesian planes in memory and in HDF5, and coupled flows of 4 and 17 channels. `track --counters` and `ab --counters` add one separately reported run per worker with structural counters from the native backend, counted the same way whether the native execution session or the transitional driver session serves the run: its returns to Python by cause, native march calls, attempts, planes, statistics rows, transverse-edge reads, the fields copied to the host and loaded into the native state, and their bytes. diff --git a/changelog.d/group-admission-transactional.fixed.md b/changelog.d/group-admission-transactional.fixed.md deleted file mode 100644 index b4c2d604a..000000000 --- a/changelog.d/group-admission-transactional.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed group construction consuming the caller's starts and closing its backends when the group was refused: a refused or failed construction, on the NumPy reference and the native group alike, now leaves every start's field and every backend to the caller to retry with, and a start already used or one start or backend shared by two members is refused before anything is loaded (#623). diff --git a/changelog.d/scan-cgroup-memory.fixed.md b/changelog.d/scan-cgroup-memory.fixed.md index 33d5216cc..df50a4aa6 100644 --- a/changelog.d/scan-cgroup-memory.fixed.md +++ b/changelog.d/scan-cgroup-memory.fixed.md @@ -1 +1 @@ -`Pool` and `Batch` scans now size their workers from the tightest control-group memory limit on the process's own path (version 1 and 2), not the root group's, so a scan under a systemd slice or other cgroup manager without Slurm variables is no longer admitted against the whole machine. An unreadable or malformed limit file, and a malformed `SOLPROP_SCAN_CPU_OFFSET` or `SOLPROP_SCAN_CPU_COUNT`, now raise `DriverError` naming the file or variable instead of a bare `OSError` or `ValueError` (#170). +`Pool` scans now size their workers from the tightest control-group memory limit on the process's own path (version 1 and 2), not the root group's, so a scan under a systemd slice or other cgroup manager without Slurm variables is no longer admitted against the whole machine. An unreadable or malformed limit file, and a malformed `SOLPROP_SCAN_CPU_OFFSET` or `SOLPROP_SCAN_CPU_COUNT`, now raise `DriverError` naming the file or variable instead of a bare `OSError` or `ValueError` (#170). diff --git a/changelog.d/sep-0047-descriptor-contract.breaking.md b/changelog.d/sep-0047-descriptor-contract.breaking.md index af7fd5ff1..7b15e5e8b 100644 --- a/changelog.d/sep-0047-descriptor-contract.breaking.md +++ b/changelog.d/sep-0047-descriptor-contract.breaking.md @@ -6,10 +6,9 @@ alias. The nominal leading batch axis is gone: `PropagationProblem.shape`, `noise_phase`, `Backend.stats()`, the periodic rows of `StepStats` and `ResponseBudgetError.field` are all `(n_modes, n_pol, n_omega)`-shaped with no batch axis, `Initial.batch_params`, `Flags.single_batch` and `assemble(batch_params=...)` are -removed, `assemble` refuses a stacked field, and `RunEstimate.shape` has three entries. A -group of trajectories is a sequence of member problems, as a batched scan already runs -them; `solprop.driver.batch.split_observation` and `plane_from_observation(member=...)` -are removed. A march snapshot's stored state keeps its leading axis of one on disk, and +removed, `assemble` refuses a stacked field, and `RunEstimate.shape` has three entries. +`solprop.driver.batch.split_observation` and `plane_from_observation(member=...)` are +removed. A march snapshot's stored state keeps its leading axis of one on disk, and existing files stay readable. The route-specific optional fields `transform`, `flux`, `transverse`, `tdse` and `current_numerator` move into a closed union, `problem.route`, from the new module `solprop.translate.routes`: a `ModalRoute`, a `GeneralRoute` or a diff --git a/changelog.d/sep-0047-native-groups.changed.md b/changelog.d/sep-0047-native-groups.changed.md deleted file mode 100644 index 58e818090..000000000 --- a/changelog.d/sep-0047-native-groups.changed.md +++ /dev/null @@ -1 +0,0 @@ -A `Batch` scan's group of native points now runs in the native group session on the CPU build, and is admitted to it on a GPU build (CUDA or HIP; run on an NVIDIA A40, HIP and data-centre NVIDIA evidence to follow): each member in its own native execution session, which steps it natively from one save plane to the next and keeps its own events, statistics rows, boundary monitor and exports, with the same fields, statistics and step records as before. An Adams group no longer warns `HostMarchWarning` for its replay. A member's monitor that refuses its launch now ends it after its launch plane is committed, as a run of the point alone does, and in a group-wide failure the members that had already taken their turn report the steps they committed, eligible for a checkpoint. The native group session is the only native group: the lockstep batch it replaced is removed, and a group it does not run is refused by name before any member starts -- a feature the native session refuses, an adaptive member, step planes, or members that do not share the schedule or the general modal guide; a `Batch` scan forms none of these, since it requires a fixed schedule, refuses step planes and groups only points of one layout. A group of coupled-flow members, which the lockstep batch refused, now runs: each member carries its own flow in its own session ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md)). diff --git a/changelog.d/sep-0047-native-session-device.changed.md b/changelog.d/sep-0047-native-session-device.changed.md index 97f104595..430cded29 100644 --- a/changelog.d/sep-0047-native-session-device.changed.md +++ b/changelog.d/sep-0047-native-session-device.changed.md @@ -1 +1 @@ -On a GPU build (CUDA or HIP) of the native backend, runs are now admitted to the native execution session as on a CPU build ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md)): Adams and the embedded Runge-Kutta tableaux, adaptive or replayed, the low-storage replay, dense output (`interpolate_planes`), the modal, general and spatial routes (radial, Cartesian, line and planar, with their statistics and fluence widths), saved planes, periodic statistics rows, step planes, the temporal boundary monitor and a free-space run's transverse edge with a requested collar's current, the input and modified noise models and resumed Adams history. A `Batch` scan's group of native points is admitted to the native group session on a GPU build too, and a coupled flow wider than 16 channels or with bins off its eigenbasis route to the native Adams march, rather than solprop's Python march with a `HostMarchWarning`, so its fields differ from before at the rounding level; a bin off the route takes its matrix functions from the scaled Taylor series and squaring of the augmented exponential, and a step whose exponent there would need more than 30 squarings is refused by name, as on a CPU build. These have been run on an NVIDIA A40 (CUDA), where the session takes the same steps, statistics and fields as the backend's own march on the same device (dense Runge-Kutta planes and the transverse edge's ramp sums within rounding bounds); HIP and data-centre NVIDIA evidence is to follow, and they are not yet qualified on either vendor. A saved plane's field crosses from the device once, into its destination, with no extra host copy. +On a GPU build (CUDA or HIP) of the native backend, runs are now admitted to the native execution session as on a CPU build ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md)): Adams and the embedded Runge-Kutta tableaux, adaptive or replayed, the low-storage replay, dense output (`interpolate_planes`), the modal, general and spatial routes (radial, Cartesian, line and planar, with their statistics and fluence widths), saved planes, periodic statistics rows, step planes, the temporal boundary monitor and a free-space run's transverse edge with a requested collar's current, the input and modified noise models and resumed Adams history. A coupled flow wider than 16 channels or with bins off its eigenbasis route to the native Adams march, rather than solprop's Python march with a `HostMarchWarning`, so its fields differ from before at the rounding level; a bin off the route takes its matrix functions from the scaled Taylor series and squaring of the augmented exponential, and a step whose exponent there would need more than 30 squarings is refused by name, as on a CPU build. These have been run on an NVIDIA A40 (CUDA), where the session takes the same steps, statistics and fields as the backend's own march on the same device (dense Runge-Kutta planes and the transverse edge's ramp sums within rounding bounds); HIP and data-centre NVIDIA evidence is to follow, and they are not yet qualified on either vendor. A saved plane's field crosses from the device once, into its destination, with no extra host copy. diff --git a/changelog.d/sep-0047-native-session-production.changed.md b/changelog.d/sep-0047-native-session-production.changed.md index 6b06bddb3..cba910301 100644 --- a/changelog.d/sep-0047-native-session-production.changed.md +++ b/changelog.d/sep-0047-native-session-production.changed.md @@ -1 +1 @@ -Runs on the native backend's CPU build now go through the native execution session ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md)), the only native executor once the transitional driver session it replaced was removed, with the same steps, fields, statistics, step records and call ledgers as before. The session also runs resumed runs, carrying the Adams history and the call ledgers, the input and modified noise models (also on a propagator stored as a z table, and the input noise beside a free-space run's transverse edge), the boundary monitor (including a free-space run's transverse edge), dense output and the low-storage replay, and it exports the Adams history beside each saved plane and checkpoint. A signal during a run is still handled once the native call returns, within 256 attempts or 0.1 s; the run's checkpoint then includes every attempt made. Comparison methods, controllers that override `PIController`'s methods and TDSE responses are refused by name on native (see the reference-only entries). The four on-axis plasma statistics (`on_axis_electron_density`, `on_axis_peak_ionisation_rate` and their species forms) no longer send a run to the backend's own march: the session scans the axis row natively, agreeing with the earlier host scan to the node scans' parity tolerance (1e-10 relative). A spatial run's `beam_radius` and `fwhm_r` are now finished natively, so the default statistics of a radial or free-space run no longer leave the native session, and so is `zdw`, read from a table of each mode's zero-dispersion wavelength along z made once before the run (exact for a mode that does not vary along z, otherwise within 1e-6 of the wavelength, with the measured error in the run's execution record under `statistics_tables`); the native backend records `nan` where the band holds no zero, as `numpy_ref` does, instead of raising. The native backend refuses by name the metric statistics of a general modal basis whose metric varies inside one of its intervals. Statistics a problem does not carry are refused by name before the run starts, on every backend, instead of at the first saved plane: a modal statistic such as `omega0` on a spatial run, a spatial statistic such as `beam_radius` or `absorbed_power` on a modal run (where `numpy_ref` used to return the peak ionisation rate as `absorbed_power`), the plasma integration diagnostics without a field-grid plasma column, and the electron density or peak ionisation rate without a plasma response. A `Batch` scan's group with a noise model runs in the native group session too, each member's stored noise phase its own. On a CPU build, a coupled flow wider than 16 channels or with bins off its eigenbasis route now runs on the native Adams march in the session rather than on solprop's Python march: a bin off the route takes its matrix functions from the scaled Taylor series and squaring of the augmented exponential rather than SciPy's `expm`, a difference at the rounding level, and a step whose exponent there would need more than 30 squarings is refused by name. +Runs on the native backend's CPU build now go through the native execution session ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md)), the only native executor once the transitional driver session it replaced was removed, with the same steps, fields, statistics, step records and call ledgers as before. The session also runs resumed runs, carrying the Adams history and the call ledgers, the input and modified noise models (also on a propagator stored as a z table, and the input noise beside a free-space run's transverse edge), the boundary monitor (including a free-space run's transverse edge), dense output and the low-storage replay, and it exports the Adams history beside each saved plane and checkpoint. A signal during a run is still handled once the native call returns, within 256 attempts or 0.1 s; the run's checkpoint then includes every attempt made. Comparison methods, controllers that override `PIController`'s methods and TDSE responses are refused by name on native (see the reference-only entries). The four on-axis plasma statistics (`on_axis_electron_density`, `on_axis_peak_ionisation_rate` and their species forms) no longer send a run to the backend's own march: the session scans the axis row natively, agreeing with the earlier host scan to the node scans' parity tolerance (1e-10 relative). A spatial run's `beam_radius` and `fwhm_r` are now finished natively, so the default statistics of a radial or free-space run no longer leave the native session, and so is `zdw`, read from a table of each mode's zero-dispersion wavelength along z made once before the run (exact for a mode that does not vary along z, otherwise within 1e-6 of the wavelength, with the measured error in the run's execution record under `statistics_tables`); the native backend records `nan` where the band holds no zero, as `numpy_ref` does, instead of raising. The native backend refuses by name the metric statistics of a general modal basis whose metric varies inside one of its intervals. Statistics a problem does not carry are refused by name before the run starts, on every backend, instead of at the first saved plane: a modal statistic such as `omega0` on a spatial run, a spatial statistic such as `beam_radius` or `absorbed_power` on a modal run (where `numpy_ref` used to return the peak ionisation rate as `absorbed_power`), the plasma integration diagnostics without a field-grid plasma column, and the electron density or peak ionisation rate without a plasma response. On a CPU build, a coupled flow wider than 16 channels or with bins off its eigenbasis route now runs on the native Adams march in the session rather than on solprop's Python march: a bin off the route takes its matrix functions from the scaled Taylor series and squaring of the augmented exponential rather than SciPy's `expm`, a difference at the rounding level, and a step whose exponent there would need more than 30 squarings is refused by name. diff --git a/changelog.d/sep-0047-run-request.breaking.md b/changelog.d/sep-0047-run-request.breaking.md index 10f0d9236..b928e3733 100644 --- a/changelog.d/sep-0047-run-request.breaking.md +++ b/changelog.d/sep-0047-run-request.breaking.md @@ -14,10 +14,7 @@ expose it as `Backend.request`. A run starts through the backend's preparation: opens the backend's own session, the reference's `HostSession`, the native backend's `NativeSession` where it admits the run and the transitional session otherwise, and `solprop.backends.sessions.start_session` only starts it; a preparation refuses a -request that is not one run of the backend's own (`RunRequest.for_run` of it). A group -starts the same way: `Backend.prepare_group(members, problems, requests)`, called on -its first member, returns a `PreparedGroup` whose `start(starts, ...)` opens the -backend's own group, and `start_group` only starts it. A +request that is not one run of the backend's own (`RunRequest.for_run` of it). A `solprop.backends.registry.BackendEntry` row now names its backend's constructor (`factory`) and policies by import path, so a backend registers with one row. `PropagationProblem.validate()` now checks what the problem diff --git a/changelog.d/sep-0047-start-and-group.breaking.md b/changelog.d/sep-0047-start-and-group.breaking.md index 49070ee4c..7285616e2 100644 --- a/changelog.d/sep-0047-start-and-group.breaking.md +++ b/changelog.d/sep-0047-start-and-group.breaking.md @@ -7,8 +7,4 @@ the start's `plane_index` taking its place. A caller no longer calls `backend.set_initial` before `run_problem`. `Simulation.run`, `SimulationRunner`, scans and the benchmark suite start their runs this way, and a resumed run's call ledgers and Adams history travel in the start, a history the backend cannot install being -warned about and recorded as reset as before. A batched scan's points run as one group -through the group protocol (`solprop.backends.session.GroupSession`, SEP 47 section -6.7): each point keeps its own planes, statistics and outcome, a boundary stop still -fails its point alone, and a group-wide failure now reports each member's actual -position. +warned about and recorded as reset as before. diff --git a/changelog.d/sep-0052-batch-executor.removed.md b/changelog.d/sep-0052-batch-executor.removed.md new file mode 100644 index 000000000..7f030d99e --- /dev/null +++ b/changelog.d/sep-0052-batch-executor.removed.md @@ -0,0 +1,14 @@ +The `Batch` scan executor is removed, with the group machinery behind it on both backends +(SEP 52). On the native backend a `Batch` group built a complete backend for every member +and ran one session each, so it cost `size` times the memory of `Local` for no gain in +speed; on `numpy_ref` it fused only the Runge-Kutta stage sums. A script that imports +`Batch` now fails at import: use `Local()` to run the points one after another on one +reused backend, or `Pool()` to run them in parallel worker processes (as many workers as +`Batch` had members hold about what it did, and run their points concurrently); `Queue` +and `Slurm` spread them over controllers and cluster jobs. Every executor still replays a +fixed schedule. Also removed: `solprop.driver.batch`, +`solprop.backends.registry.select_batch`, `solprop.backends.BatchBackend`, +`Backend.max_batch`, `Backend.prepare_group`, the `GroupSession` and `PreparedGroup` +protocols, `check_group`, `start_group`, `solprop.backends.events.GroupBatch`, +`ExportTicket.member`, `StatsSpec.same_tables`, the reference's `HostGroup` and +`NumpyBatchBackend`, `solprop_native.group`, and the benchmark suite's `group_batch` case. diff --git a/changelog.d/sep-0052-native-seam-phase-0.changed.md b/changelog.d/sep-0052-native-seam-phase-0.changed.md new file mode 100644 index 000000000..c57a7bad6 --- /dev/null +++ b/changelog.d/sep-0052-native-seam-phase-0.changed.md @@ -0,0 +1 @@ +solprop-native's source build pins nanobind 3.1.0 (it took any release from 2.9 on), and the private extension's test-only entry points moved to its `_testing` submodule, which the wheel ships for solprop's own tests (SEP 52). diff --git a/docs/api/scans.md b/docs/api/scans.md index 6f5bf69f8..db86cfb26 100644 --- a/docs/api/scans.md +++ b/docs/api/scans.md @@ -8,7 +8,7 @@ modules involved are: - {mod}`solprop.driver.scan`: `Scan` (ordered variables and their global points), `ScanPoint` and `run_scan`; - {mod}`solprop.driver.executors`: the execution policies — `Local`, a spawned process - `Pool`, a lockstep `Batch`, a durable `Queue` and `Slurm`; + `Pool`, a durable `Queue` and `Slurm`; - {mod}`solprop.processing.scans`: the reductions a worker evaluates for each point (energy in a band, a spectrum, mode energies, a custom reduction) and the reader of a collected scan (`open`, `ScanOutput`); @@ -20,11 +20,4 @@ Backend and storage interfaces below are mainly for contributors extending an ex - {mod}`solprop.output.scan_artifacts`: the validated per-point results a durable queue stores; - {mod}`solprop.driver.executors.queue`: collecting a queue's results, safely repeatable; -- {mod}`solprop.driver.executors.slurm`: writing and submitting a Slurm array script; -- {mod}`solprop.driver.batch`: grouping compatible points into a batch and splitting its - output back into one run per point; -- {mod}`solprop.driver.executors.batch`: the controls of a fixed-schedule batch; -- {mod}`solprop.backends.host.group`: the backend side of a batch on the NumPy - reference, in which every member takes the same fixed steps and is observed on its - own. On the native backend a batch runs in the native group session - (`solprop_native.group`), one native execution session per member. +- {mod}`solprop.driver.executors.slurm`: writing and submitting a Slurm array script. diff --git a/docs/dev/accuracy.md b/docs/dev/accuracy.md index fe52bf593..123ed6f56 100644 --- a/docs/dev/accuracy.md +++ b/docs/dev/accuracy.md @@ -351,8 +351,8 @@ follows the kind ([testing.md](testing.md) section 3): - **Matched discrete computations: rounding budgets** (class R). One application, one - step, eight steps, a kernel, a scan, two thread layouts, a batch member or a scan - point against the same computation alone: the same method, orders, history, schedule + step, eight steps, a kernel, a scan, two thread layouts or a scan point against the + same computation alone: the same method, orders, history, schedule and inputs on both sides. The bound is fixed from operation and reduction counts and transform lengths, with a margin, before anything is measured. - **Adaptive runs: accuracy envelopes** (class T). A full adaptive run, the reduced M2 @@ -453,13 +453,11 @@ most 3.7e-11 of the peak. So the size of a step difference says little about the earlier comparison of 1.9e-12 in the steps with 1.5e-10 in the field, a factor of 65, set side by side two effects of the plan, not a cause and its result. -**Scans and batches** are execution paths, not numerical models: a scan point agrees with -the same simulation run alone, and a batch member with the same member run singly under -the same fixed schedule, within a matched-discrete rounding budget, on every backend (scan -points under `Local` and a fresh `Pool`; batches of 1, 2 and 3 with a partial final -group). Neither is required to be bitwise: a batch's lockstep reductions, its thread -layout and a worker process's library state may order sums differently. A scan point or -batch member run adaptively is class T against its own reference. The reduced M2 case on +**Scans** are execution paths, not numerical models: a scan point agrees with the same +simulation run alone within a matched-discrete rounding budget, on every backend (under +`Local` and a fresh `Pool`). It is not required to be bitwise: a worker process's thread +layout and library state may order sums differently. A scan point run adaptively is +class T against its own reference. The reduced M2 case on the GPU agreed with the fixed-schedule CPU fields to 7.9e-14 (a diagnostic; no bound asserted). A calibrated reduced-M2 schedule (eight seeds, 515 steps) transfers to 4.7e-7 in its scalar metrics against `rtol = 1e-10` diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md index 9c36bf3b9..1702a4ea0 100644 --- a/docs/dev/architecture.md +++ b/docs/dev/architecture.md @@ -25,7 +25,7 @@ Luna's scope and its most valuable design choices, and is designed around the fo - polarisation as an ordinary array axis, at no cost when unused; - a hot loop designed for threads and GPUs from the start, behind one seam; - lean memory: bounded buffers, node chunking, no materialised stages; -- an in-process batch mode for many small or several large problems; +- scans of many small or several large problems, from one process to a cluster; - a clean, fast-loading Python package that plays well with NumPy, SciPy, matplotlib and h5py. **Priorities, in order:** accuracy and reliability; then as much CPU performance as can be @@ -139,7 +139,7 @@ kernel layout carries the transverse columns in its mode axis (see §12). | **P** physics / convenience | grids, materials, modes, profiles, pulses, noise, linear-operator assembly, response *definitions*, ionisation and Raman models, boundaries, normalisation, tools | numpy, scipy, standard library, other P modules | none: clarity first; never in a hot loop | | **T** translation | turns P objects into validated kernel-ready arrays and the `PropagationProblem` contract | P, numpy, scipy | may be expensive once per problem; results cached and validated | | **B** backends | state buffers, transform plans, kernels, the inner z-loop, statistics kernels | numpy; the native package in `native/` (Kokkos, Kokkos-FFT and nanobind); from P only the types and constants the seam names — never a physics object | all hot-path rules of [backends.md](backends.md); in-place and `out=` allowed here only | -| **D** driver | `Simulation`, run loop over save planes, batch runners, `prop_capillary`/`prop_gnlse`, output handlers, statistics specs | P, T, B (through the seam only), h5py | none | +| **D** driver | `Simulation`, run loop over save planes, scan executors, `prop_capillary`/`prop_gnlse`, output handlers, statistics specs | P, T, B (through the seam only), h5py | none | | **X** processing / plotting | analysis of outputs, standard plots, design tools | numpy, scipy, matplotlib, D (outputs), T (reference tables and their identities, for `processing.modal`; the recorded plane measure, for `processing.mixtures` and `processing.planes`) — never B | none; may call backend statistics kernels through the D layer when a computation belongs on the device | **Transverse rules are built in P.** `modes/quadrature.py` constructs its rules @@ -220,7 +220,7 @@ against `src/solprop` by `tests/test_structure_figures.py`. | `translate/` | Validated `PropagationProblem` (`translate/problem.py`) and its route union (`translate/routes.py`), assembled by `assemble` (`translate/assembly.py`), with a capillary's coherent wall and taper coupling in `translate/walls.py` and the refusals and advisories assembly applies in `translate/validation.py`; parameter expansions and z tables; modal/radial/Cartesian transforms and the hybrid planar one (slab modes in x × FFT in y, `translate/planar.py`); dense tracked modal tables, the general modal route and the coupled-flow and metric records (`translate/general.py`, `translate/coupled.py`); the spatial plane measure (`translate/flux.py`, the `FluxPlan` of schema 35); the persisted frame integral and the filled input port of a problem's entrance (`translate/coupling.py`); what the general route and the coupled flow execute, checked once (`translate/admission.py`); response tables, masks and stage bundles | T | | `backends/` | Registry and protocols, sessions, the Adams call ledger both backends keep (`ledger.py`), node chunks, scalar bodies, spatial and population statistics, and the TDSE response's host source assembly (`tdse_source.py`) | B | | `backends/numpy_ref/` | Reference execution, its Adams kernels and tables (`multistep.py`) and its on-axis scan (`populations.py`) | B | -| `backends/host/` | The reference's own step driver, Adams and low-storage marches, fixed-schedule group, run session and group session ([SEP 47](seps/archive/sep-0047-run-ownership.md) phase 2); the parts the Python sessions compose are in `backends/session_core.py` | B | +| `backends/host/` | The reference's own step driver, Adams and low-storage marches and run session ([SEP 47](seps/archive/sep-0047-run-ownership.md) phase 2); the parts the Python sessions compose are in `backends/session_core.py` | B | | `stepper/`, `log.py`, `stats.py` | Tableaux, controllers, schedules, progress reporters and statistics specifications | D | | `driver/`, `driver/routes/`, `driver/executors/`, `scan.py` | The `Simulation` object (`simulation.py`) with its settings and their admission (`settings.py`), its input, launch, noise and peak field (`inputs.py`), its run record (`metadata.py`), resume (`resume.py`), many-input runner (`runner.py`) and TDSE run glue (`tdse_run.py`); the keyword routes behind its constructors, one module per family (`routes/`: GNLSE, hollow guides, general modal guides, spatial grids, and the material selection and keyword attribution they share); the convenience interfaces, scan/batch orchestration, Local/Pool/Queue/Slurm execution and scan CLI | D | | `calibration/` | The native backend's machine calibration ([SEP 46](seps/archive/sep-0046-machine-calibration.md)): reading, showing, exporting, importing and clearing profiles in the per-user store, through solprop-native's standard-library modules loaded by path so that the native runtime never starts (`calibration/_native.py`), the measuring controller, its child processes, the synthetic problems they time, the operation-grain candidates and the selection rule (`calibration/controller.py`, `child.py`, `problems.py`, `grain.py`, `selection.py`), the refinement of one simulation (`calibration/refine.py`, stage 2, which `Simulation.calibrate` runs), and the `solprop calibrate` command (`calibration/command.py`) | D | @@ -299,7 +299,7 @@ The outer loop is `solprop.driver.run.run_problem`, which takes a translated pro constructed backend, an output handler and a `Start` -- the entrance, or a resumed state with its call ledgers and method history -- which the run's session loads into the backend (SEP 47). Nothing in it is -specific to a `Simulation`; it is the piece a batch runner or a scan calls. What the +specific to a `Simulation`; it is the piece a runner or a scan calls. What the driver does not do is as much a part of the design as what it does: - It **never conjugates a spectrum**. The backend works in the FFT convention, the output @@ -582,10 +582,9 @@ propagated state*, never at the array-namespace level ```python class Backend(Protocol): name: str - max_batch: int + reads_transverse_edge: bool def prepare(self, problem, request) -> PreparedExecution: ... # a run's session - def prepare_group(self, members, problems, requests) -> PreparedGroup: ... def timing_probe(self, start) -> TimingProbe: ... # an estimate's trial def metadata(self) -> dict[str, object]: ... # what the execution was def available_device_memory(self) -> int | None: ... @@ -609,8 +608,7 @@ class Backend(Protocol): transforms to Accelerate, OpenBLAS or cuBLAS. The CUDA build uses time-parallel response teams, deterministic plasma scans and device reductions and is qualified on data-centre NVIDIA GPUs; the HIP build is qualified on AMD Instinct GPUs, with the HIP - sanitizer run still outstanding. Fixed-schedule fibre batching runs as the native group - session, one native session per member (§11). The private state is read only by the backend's own + sanitizer run still outstanding. The private state is read only by the backend's own session and timing probe. Its floating-point licence is [SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)'s: contraction by default, strict opt-outs for the protected helpers (stable increments, small-argument functions, @@ -624,7 +622,7 @@ qualified, and §11 its current limits. ## 10. Output and statistics -`MemoryOutput` (everything in RAM: fast, small problems, batch scans) and `HDF5Output` +`MemoryOutput` (everything in RAM: fast, small problems, scan points) and `HDF5Output` (streaming to disk, chunked per saved plane, optional compression, cache/resume) implement one save protocol (`output/store.py`) and one metadata schema (`output/metadata.py`, its record types in `output/records.py`): grid, modes, simulation type, the full configuration that built the `Simulation` (serialised physics objects), package and @@ -632,7 +630,7 @@ dependency versions, git provenance of the running code when available, the nois realisation, the stepper settings and the step schedule actually taken (z, h, error norm, rejections, wall time), the statistics, and the rows a periodic subset of them recorded between planes. Fields are stored in the canonical layout -`(n_z, n_modes, n_pol, n_omega)` (a batched scan stores each member separately), in the **optics** sign convention +`(n_z, n_modes, n_pol, n_omega)` (a scan stores each point separately), in the **optics** sign convention with the attribute `spectral_convention = "optics"` (ADR-017: the output layer conjugates on save and on resume); processing accessors squeeze trivial axes and accept `convention="fft"`. A TDSE run may also write its raw provider evaluations to a separate archive @@ -678,71 +676,19 @@ a mode-profile rebuild per accepted step is what cost Luna a fifth of its step. reduces and packs the statistics without observing the complete field. The rows are stored beside the step history and in the same ragged shape. -## 11. Scans and batch mode +## 11. Scans [Scans](scans.md) run above the backend seam. `Scan` gives each point a stable global index, parameters and seed. `run_scan` selects an executor; `Local` is the API default, `Pool` uses spawned processes for independent CPU runs, and `Queue`/`Slurm` provide -durable distributed execution. A controller owns the collected HDF5 scan file. - -Fixed-schedule fibre batches run as a group (`solprop.backends.session.GroupSession`, -started by `solprop.backends.sessions.start_group`; SEP 47 section 6.7): a sequence of -independently translated single-trajectory member problems — no problem carries a batch -axis — each started from its own `Start`, advanced -one common window (save plane) at a time, each member reporting its own events. The -batched scan's loop (`driver/_scan_batch.py`) is the group's service loop. A backend -chooses its own group: `start_group` asks the first member to prepare it, -`members[0].prepare_group(members, problems, requests)`, and starts the returned -`PreparedGroup`, naming no backend. Two groups serve it: - -- **The native group session** (`solprop_native.group.NativeGroupSession`) serves - every native group, on a CPU or a device build. It owns - one native execution session per member (`solprop_native.session.NativeSession`, - adopting the member backend the scan built), so each member's march, events, - attempts, statistics rows, tickets and boundary monitor are its own session's, and the group only orders the members' - advances. Within a window the members take turns in rounds of at most 256 common - steps (`ROUND_STEPS`), each turn native from end to end, and each member's noise - realisation and the noise phase its planes store are its own session's. The running members stand - at one common step between rounds, and a group-wide stop is polled there. A member's - trajectory is its lone native session's, bit for bit at one thread. The members share - the schedule and nothing mutable: no fused kernel, because the native marches own - each whole step. Its refusals (`solprop_native.group.refusal`) are named and made - before allocation: a run the native session refuses, an adaptive member, step planes, - or members that do not share the schedule, save planes, method, field shape and - statistics request. A batched scan forms none of these: it requires a fixed schedule, - refuses step planes and groups only points of one execution layout - (`solprop.driver.batch.compatible_groups`). -- **The reference's group** (`solprop.backends.host.group_session.HostGroupSession`, - prepared by `HostPreparedGroup`) serves every `numpy_ref` group. - It runs over the reference's group runner (`HostGroup`, or `NumpyBatchBackend`'s - member-axis stage arithmetic, which `select_batch` builds), which adopts the loaded member backends, each with its own tables, - state and noise, and advances them through each common step in turn. It keeps that - runner rather than composing one `HostSession` per member, because the runner's - arithmetic and failure positions are what a reference group means: - the module docstring gives the reasons. - -Admission uses memory ledgers and a free-device-memory query with headroom. - -Every backend has exact member-versus-singleton identity checks under the same -schedule. That does not imply a throughput improvement on every workload: whether a -batch beats independent runs depends on the problem size and the device. Adaptive -lockstep is not implemented. A boundary stop (the monitor's error, or its warning -raised as an error) fails its member alone. A group-level failure (a non-finite norm, -a step floor, a trial exception, an in-flight failure) fails every member of that -group, each reporting its own committed position and checkpoint eligibility. Members -take their steps in turn, so those ahead of the failing one have already taken the -failed step: the reference group's members are then in flight and poisoned, having -stepped without recording; a native group's have committed and recorded their whole -turn and stay eligible. Recovering the surviving members is an open question -([#171](https://github.com/LupoLab/solprop/issues/171)). A native member commits its -launch plane before its monitor judges the launch, as a lone run does (SEP 47 section -5.3), so a refused launch ends it in the window after the launch's; the reference -group attaches the monitors first. +durable distributed execution. A controller owns the collected HDF5 scan file. There +is no in-process lockstep batch: SEP 52 removed the `Batch` executor and its groups, +which on native built a backend per member and fused nothing, so a point runs as a +lone run does, on whichever executor. Independent simulations use spawned processes, normally one scientific thread per worker, rather than threads, because thread pools, FFTW plans and the OpenMP runtime are -process-global (ADR-013). Each member may use its own adaptive schedule outside a fixed -batch. +process-global (ADR-013). Each point may use its own adaptive schedule. ## 12. Parallelism and the GPU model @@ -754,7 +700,6 @@ process counts belong to the scan executor: |---|---|---|---| | small single | serial kernels and small transform pools by measured size rules | sequential | spawned processes | | large single | `prange` over node chunks; FFTW/BLAS threads on batched plans | sequential | processes | -| compatible fibre problems on GPU | member-owned stage work; fused accepted updates | fixed lockstep | backend batch | | large on GPU | one thread per element | sequential | one problem per device | The plasma cumulative integral is sequential in value but not necessarily in execution. On diff --git a/docs/dev/backends.md b/docs/dev/backends.md index a8c7c14d1..38446e5c9 100644 --- a/docs/dev/backends.md +++ b/docs/dev/backends.md @@ -35,13 +35,11 @@ statistic), and that structure is precisely what a fast backend exists to change ```python class Backend(Protocol): name: str - max_batch: int # 1 for backends that step one problem reads_transverse_edge: bool # whether a requested real-space collar can run on it @property def request(self) -> RunRequest: ... # the run request it was built for def prepare(self, problem, request) -> PreparedExecution: ... # a run's session - def prepare_group(self, members, problems, requests) -> PreparedGroup: ... def timing_probe(self, start: Start) -> TimingProbe: ... # commits nothing def march_export_refusal(self) -> str | None: ... def edge_memory(self, space: object) -> int: ... @@ -110,10 +108,8 @@ through `solprop_native.NativeBackend`, each called as it is selected. Before a native construction it runs SEP 46's first-use calibration; `SOLPROP_REQUIRE_DEVICE` reads the installed native build's `build_info()` (the reference is refused a required device by name); and `statistics_refusal` reads the -far-field statistics `NativeBackend.far_field_statistics` declares. `select_batch` is the -reference group's lockstep runner; the native group runs one native session per member -through its own `prepare_group` (**Selection** below). `auto` is `registry.AUTO`, -`native`, with no fallback. +far-field statistics `NativeBackend.far_field_statistics` declares. `auto` is +`registry.AUTO`, `native`, with no fallback. **Periodic-statistics storage hooks.** The seam carries three storage hooks for the periodic statistics — `_reset_step_stats`, `_record_step_stats`, `_drain_step_stats` — so @@ -122,39 +118,15 @@ march still decides which accepted steps produce rows and passes their history i The CPU backends inherit the host defaults. The hooks are part of the frozen surface ([kernel-contract.md §8](kernel-contract.md)). -**Batches.** `BatchBackend` adds independent member observations and metadata through -`select_batch(owners)`, the reference group's lockstep runner: `numpy_ref` alone -implements this fixed-schedule interface, and `select_batch` refuses a `native` member by -name, since a native group runs one native session per member through `start_group` -(`NativeBackend.prepare_group`, `solprop_native.group.NativeGroupSession`, SEP 47 §6.7) -and fuses nothing. Singleton constructors keep their single-member shape; the reference's -batch owns a sequence of independently loaded workspaces, evaluates the stage sums, the -stage input and the accepted update over the member axis and leaves response and -FFT work member-owned. A batch or group member agrees -with the same member run singly under the same schedule within a matched-discrete rounding -bound, on every backend -([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)). -`available_device_memory()` returns free device bytes or `None` on hosts, enabling common -admission without importing backend-specific array libraries in the driver. On a device -the per-member launch cost is not amortised, so a batch's gain over independent runs is -small and a batch ratio for any shape needs its own measurement -([benchmarks.md](benchmarks.md#indicative-results)). - -A general modal guide is a batchable member under a **narrower** admission rule than the -fibre one: the members of a general-guide group share the guide, the table, the gauge, the -materials and one explicit fixed schedule, and differ in their launch and their noise seed -alone. `modal_tables.identity`, the metric's kind and gauge and the compiled responses' -model and policy enter `driver.batch._signature`, because every other entry there -describes an execution *layout* and two different guides share all of it; and a group -assembled outside that grouping is refused by name, at `driver.batch`'s -`refuse_mixed_guides` and again by each backend's group: the reference's `_validate_members` -(`backends/host/group.py`) and the native `solprop_native.group.refusal`. A group hands each member its own problem, so a batched general run is what its members -are alone, to the same rounding bound; a problem is one trajectory and carries no batch -axis. A member carrying a coupled flow is refused by name by the reference's -lockstep batch (`NumpyBatchBackend`), whose stage arithmetic over the member axis applies -no flow action; the native group admits one, each member's own session carrying its flow. - -**Three things every backend owes, beyond the ten methods.** +**No groups.** A backend runs one trajectory per session; there is no group or batch +interface. A fixed-schedule `Batch` executor and its groups (`GroupSession`, +`prepare_group`, the reference's lockstep `HostGroup` and `NumpyBatchBackend`, and the +native group session) were removed by SEP 52: on native a group built a complete backend +per member and fused nothing. `available_device_memory()` returns free device bytes or +`None` on hosts, so that a scan's admission needs no backend-specific array library in +the driver. + +**Three things every backend owes, beyond the protocol's members.** **1. Reductions to the error bound.** The error norm and every statistic a backend reduces are compared by numerical error, not bits @@ -348,7 +320,7 @@ its own (its noise phase rides beside the field in a `StoredField`; a session's `noise_phase(ticket)` forms it at the pending plane, from the problem's scalar tables on the host, or, when `Phi` took the z table, from the table's slot at the plane, which `NativeSession` reads through the native session under its lock, as the backend reads it -from its state, and a group's member from its own session). A plane observer reads +from its state). A plane observer reads the stored field with no fetch, and a terminal checkpoint at the same plane takes the internal convention from it by the exact inverse (`spectrum_to_internal`, the store's own reader), with no second export or amplitude conversion. An output that is not a plane @@ -528,8 +500,8 @@ native backend's (`solprop_native.session.NativePrepared`) opens `NativeSession` native executor since SEP 47 phase 5, which refuses by name what it does not run, and refuses a `NativeBackend` subclass, whose overrides it would not call. Statistics the problem does not carry are refused by name before any session starts, on every executor, rather than left to the -first plane (`backends.session.statistics_unavailable`, read by every preparation, by -`check_group` and by the run layer): a modal statistic of a spatial route, a spatial one of a modal +first plane (`backends.session.statistics_unavailable`, read by every preparation and by the run +layer): a modal statistic of a spatial route, a spatial one of a modal route, the plasma integration diagnostics without the field-grid plasma column and the electron density or peak ionisation rate without a compiled plasma response (a `BackendError` at every door). `zdw` is read natively from a table of each mode's root along z, lowered once at preparation @@ -555,17 +527,7 @@ reads the polarisation ellipse, so on a one-component transform whose modes have axis the two rows go to a row of their own, which the envelope scan reads as a node of two components (`populations.envelope_populations` on the host's row). The native row agrees with the host's scan to the node scans' parity tolerance (`1e-10`), and is the same bits where -both read a Radau rule's axis node. A group starts through the same shape (SEP 47 §6.7): -`start_group` checks the group (`check_group`) and asks its first member, -`members[0].prepare_group(members, problems, requests)`, for a `PreparedGroup` whose -`start(starts, *, stop)` opens the backend's `GroupSession`, so it names no backend -either. The native backend's (`solprop_native.group.NativePreparedGroup`) opens -`NativeGroupSession`, which refuses by name what `solprop_native.group.refusal` names -(an adaptive member, step planes, members that do not share the schedule) before any -member session starts. The reference's (`backends.host.group_session.HostPreparedGroup`) -opens its own `HostGroupSession` over the group runner `select_batch` builds. A backend -that runs no group raises `BackendError` from `prepare_group`. The -three keyword arguments are what `stats()` needs and the kernel contract does not carry. +both read a Radau rule's axis node. The three keyword arguments are what `stats()` needs and the kernel contract does not carry. **Spatial statistics measure the medium's flux** ([SEP 34](seps/archive/sep-0034-medium-flux.md)). The shared spatial statistics, `backends.spatial.collect_spatial`, read the plane's @@ -865,7 +827,6 @@ build (ADR-076, §4). |---|---|---|---| | compact problem | one column on one node, fewer than 65 536 fine samples | kernels on a team of at most eight threads, transforms on that team, products on one BLAS thread | independent scans: Local, or spawned processes through Pool | | sized problem | the rest | each operation's width chosen from its own element count at construction: stage, response, dense product, FFT, Raman, copy, flow, modal and Adams | one process per problem | -| fixed-schedule batch | compatible independently loaded members | fused accept update over members; remaining work stays member-owned | one batch runner owns the group | The widths are constants of `include/solprop_native/core.hpp` (`operation_threads`, with their calibration in @@ -893,7 +854,7 @@ than the choice of backend: 3. **The best thread count is not the machine's.** It differs by operation and by problem, which is why each width is sized separately. For the scan pattern, k independent single-thread runs beat one k-thread run by 8.5x (measured on the retired `numba_cpu` - backend), so a batch runner should prefer processes to threads; the scan executors do this + backend), so a scan should prefer processes to threads; the scan executors do this through `Pool` ([scans.md](scans.md)). The pools, the widths and the wait policy are stored in the output metadata @@ -1022,9 +983,7 @@ frequency-dependent map of three Cartesian components. `moving guide ...` rows in `tests/backends/flow_rows.py`). Not bitwise: FFTW is not pocketfft, and numpy's complex product is an FMA on some hosts (§3.1a). - **Statistics** are solprop's `collect` on the observed channel field with the basis metric, as - on the reference, so on one state the two agree to the statistic's rounding bound. The - **native group session** takes general members unchanged, each one its lone native - session's run. + on the reference, so on one state the two agree to the statistic's rounding bound. - **Ledger**: the `general_*` rows, named and zero on every other route; the maps and the record's resident E/H reference are counted as the reference counts them. Moving maps add the coefficients (`general_synthesis`, `general_projection`), the two maps a stage evaluates @@ -1103,8 +1062,7 @@ name. - **Parity** is a rounding statement with the bound stated first: `tests/flow_parity.py` for the actions and the steps, and `parity_bound` in `tests/coupled_flow_cases.py` for ten fixed steps on each case (the case catalogue's rows, `tests/backends/flow_rows.py`). -- **FSAL** stays off beside a flow, as on the reference ([stepper.md §2](stepper.md)); - the native group refuses a member carrying the leaf by name, as the reference's does. +- **FSAL** stays off beside a flow, as on the reference ([stepper.md §2](stepper.md)). - **Ledger**: the `flow_*` rows, named and zero on every other route (§4). ### 3.10 The hybrid planar kind @@ -1655,9 +1613,7 @@ that order for the stage too. The state crosses the seam once at a load and once at an observation, straight between the memory space and the NumPy buffer. -The singleton constructor requires a one-member problem; fixed-schedule groups go -through `start_group` (`NativeBackend.prepare_group`), the native group session over one -native session per independently loaded member (§1). The backend +The constructor requires a one-member problem. The backend refuses scalar-only declarations on vector Raman problems, spectral responses other than the compiled envelope-plasma assembly, and, on a device build, z-tabulated operators or prefactors, before field-sized allocation (the CPU build runs them, §1). Supported mixture density, pre-ionisation and Raman decay paths @@ -1717,8 +1673,7 @@ the drive back by the inverse action and accumulates; the accepted update takes the state, the solution and the error sum, the old norm on the unmixed state. A zero stage fraction is flagged and not applied; FSAL is off on a flow. The `flow_*` rows join `memory_ledger()`, zero on every other route. Admission is solprop's shared list under the -name `native` plus one native limit (the delayed response's three components); the batch -backend refuses a flow member by name. +name `native` plus one native limit (the delayed response's three components). **The hybrid planar kind** runs on the same engine: columns `(p, k_y)` go to `(p, y)` rows by a one-axis y FFT, a node chunk holds whole y rows, and the slab rule synthesises and @@ -1914,7 +1869,7 @@ distinguishes these allocations from process peak RSS, host copies and FFT works backend allocates ([ADR-065](decisions.md)). A backend allocates and first-touches its buffers at construction, so a run that doesn't fit fails there, with `MemoryError` or killed by the kernel or the scheduler; `Simulation.estimate` reports the constructed -ledger's total. Scan workers and batch groups are still bounded, from measured RSS and +ledger's total. Scan workers are still bounded, from measured RSS and the ledger ([scans](../guide/workflows/scans.md)), and so is TDSE's atomic storage, by `TDSEExecution.memory_limit`. On the general modal route memory is dominated by the dense maps and the resident E/H reference, `16 Q C M n_omega` bytes per map and up to 14 such @@ -1973,8 +1928,7 @@ that execution space. | the Adams carrier frame (`Multistep(carrier_frame="scalar")`, SEP 35) | every guided route; free space refused | CPU builds, resident, on every representation of the operator (a z table's chord carried as its own scalar table, #255); device builds refused | refused by name | | the low-storage RK4IP march (`LowStorageRungeKutta`), replay-only | every diagonal-flow route | every diagonal-flow route, a resident engine whose step is one native call | flows recomputed per element; qualified under HIP, not under CUDA | | moving solid guide (moving maps beside a frozen-residual flow) | yes | yes | qualified | -| fixed-schedule groups | fibre and general guides; a coupled flow member by member (the lockstep batch for the rest) | fibre and general guides, a coupled flow included (the native group session) | fibre and general guides, and a coupled flow where the session admits each member (the native group session) | -| the native execution session and group session (SEP 47) | its own session (`HostSession`) | every native run and group (phase 5: no other native executor) | admitted on CUDA and HIP as on the CPU build (SEP 47 phase 4): beyond the modal route with planes, rows, the temporal monitor and the Adams history (phase 3), the spatial routes (radial, Cartesian, line, planar) with their fluence widths, a transverse edge and a collar's current, the noise models, dense output, the low-storage replay, a coupled flow wider than 16 channels or off its eigenbasis route, and the native group session; run on an NVIDIA A40 against the transitional bridge on the same device before phase 5 deleted it (bitwise, but for the bounded transverse sums and dense Runge-Kutta planes), not yet qualified on either vendor | +| the native execution session (SEP 47) | its own session (`HostSession`) | every native run (phase 5: no other native executor) | admitted on CUDA and HIP as on the CPU build (SEP 47 phase 4): beyond the modal route with planes, rows, the temporal monitor and the Adams history (phase 3), the spatial routes (radial, Cartesian, line, planar) with their fluence widths, a transverse edge and a collar's current, the noise models, dense output, the low-storage replay, and a coupled flow wider than 16 channels or off its eigenbasis route; run on an NVIDIA A40 against the transitional bridge on the same device before phase 5 deleted it (bitwise, but for the bounded transverse sums and dense Runge-Kutta planes), not yet qualified on either vendor | | periodic statistics between planes | yes | yes | yes: the native session takes each row natively and keeps it in a resident buffer until the next observation, with no return to Python (SEP 47 §6.4) | | Adams snapshots and a resume that continues the history (`MarchSnapshot`) | yes | yes: the resident engine copies its rows (`store`, and `states`, `rates`, `applied` where kept) to the host at a kept save and back on a resume | compiles; not qualified | | field-free observation (`observe(field=False)`), the runner, a transverse collar's rate and a set evanescent rate on the separable element | yes | yes (field-free observation needs no native change; the rate is one view in `SpatialCoefficients`) | compiles; not qualified | @@ -1990,7 +1944,7 @@ argon and nitrogen plasma on field and envelope grids, the rate table's hold abo model's maximum field, a helium/argon Kerr mixture, silver and silica walls, the GNLSE with the silica bundle, and gas Raman leaves of 4, 72 and 126 rows — dry air's composition leaf, driven by the summed density of its labels — on gradients to vacuum, -scalar and vector, field and envelope, and in lockstep batches. Each agrees with the +scalar and vector, field and envelope. Each agrees with the reference far inside its operation-count bound: fields to `5e-15` and statistics to `5e-14` or better, except the complete run that holds argon's rate (`6e-13` and `1.1e-13`). `native` assumes no term @@ -2013,7 +1967,7 @@ to run when two backends disagree, and the one that needs nothing beyond the pac dependencies. The native backend's device builds are qualified on a data-centre NVIDIA GPU (CUDA 13) and an AMD Instinct GPU (a ROCm 7 prerelease stack): the native tests, the native pytest suite, solprop's device lane and its -slow lane on `native` pass, repeats and batch members agree within +slow lane on `native` pass, repeats agree within [SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)'s rounding bounds, and the CUDA sanitizers (memcheck, racecheck, initcheck, synccheck) are clean. Thread-count probes are the only tests skipped on a device, which has no thread count to vary. diff --git a/docs/dev/benchmarking.md b/docs/dev/benchmarking.md index 5ef0776a1..863972a0f 100644 --- a/docs/dev/benchmarking.md +++ b/docs/dev/benchmarking.md @@ -300,7 +300,6 @@ uv run python -m benchmarks ab --set sep47 --threads 1 --counters \ | `snapshots_idle`, `snapshots_sparse`, `snapshots_every` | the same fibre to HDF5 with `step_planes=1` and a `SnapshotController` never asked, asked after every eighth accepted step, or asked at every accepted endpoint | a plane at every step; 0, 5 and 42 snapshots published | | `with_input_repeat` | three runs of the fibre with other peak powers through `Simulation.with_input` | three preparations from one translation | | `scan_local` | `run_scan` of four peak powers on `Local`, built with `with_input`, field-free | four points, no field copied to the host | -| `group_batch` | the same four points on `Batch(4)`, replaying ten 1.6 mm steps with the split-step collar | ten common steps of four members | | `radial_filament_256_{saved,free}_{memory,hdf5}` | the radial filament's first 3 mm, four planes, every field kept or none, to memory or to HDF5 | four planes, transverse-edge reads and collar checks | | `cartesian_filament_128_{saved,free}_{memory,hdf5}` | the Cartesian filament's first 1 mm, likewise | the same on a 128² grid | | `taper_flow_4`, `taper_flow_17` | 40 µm of a He capillary tapering from 50 to 48 µm with taper coupling, 4 or 17 modes | a coupled flow on the native Adams march, and one wider than 16 channels, whose host passes hold each bin's channel vectors in a row of their own (a device build's passes hold none) | @@ -323,7 +322,7 @@ repetition after the timed ones with the native adapter's counters on, reported receipt's `counted` and, in `ab`'s summary, per arm; counting therefore costs no timed repetition anything. With counting off, the adapter's path is the one before the counters except for a single attribute test per native call (a march call, a plane, a -statistics call, an edge read, a field crossing or load, a low-storage or group step, a +statistics call, an edge read, a field crossing or load, a low-storage step, a native session's `advance` or export): the per-attempt hooks are installed only while counting, and nothing else is computed, so no ledger entry was taken for them. @@ -347,15 +346,14 @@ the harness) holds: `session_warning`, `session_terminal`, or `session_progress` with its cause, `session_progress:buffer` (the attempt or row buffer filled), `session_progress:work_limit` (the caller's attempt bound) or - `session_progress:deadline` (its time bound). Members of the native group session are - native sessions and are counted so. A periodic row, a collar check, an edge read or a + `session_progress:deadline` (its time bound). A periodic row, a collar check, an edge read or a low-storage step is never a session return (SEP 47 section 7.3); - `march_calls`: native march calls by march, `adams_march` and `rk_march` from Python on the bridge, and the native session's own calls inside its `advance`, read from its status, as `session_adams`, `session_runge_kutta` or `session_low_storage`; - `attempts` and `accepted` (native march, native session and host attempts together; - a session's from its delivered chunks), `march_attempts`, `host_attempts`, - `low_storage_steps` and `group_steps` (a group's common steps); + a session's from its delivered chunks), `march_attempts`, `host_attempts` and + `low_storage_steps`; - `planes` (calls of `propagate_to` on the bridge, observations after the launch in a session), `statistics_rows` (periodic rows, wherever taken) and `statistics_evaluations` (rows and plane statistics together), and @@ -375,17 +373,13 @@ the harness) holds: The run's own record adds the planes saved and, for a snapshot case, the snapshots published; the peak resident memory is the worker's, as for every row. A host attempt -makes several native calls, which are not counted one by one; a group run's counts -include each point's resource probe, a native session that returns at its launch; and a -device's launches, +makes several native calls, which are not counted one by one; and a device's launches, transfers and allocations are not counted: they need a profiler. Counts explain a timing and do not replace it; check that both arms hold the same events before comparing their times (SEP 47 section 7.2). -A scan or group repetition builds its own backends, so its worker builds none beforehand -and warms up with one whole untimed repetition. `scan_local` watches each point's run -to count its steps; `Batch` watches none, so `group_batch`'s steps are counted only by -`--counters`, and `ab` reports its work as `unchecked` rather than `same`. Where a -repetition keeps no final field (field-free planes, a scan), finiteness is read from +A scan repetition builds its own backends, so its worker builds none beforehand and +warms up with one whole untimed repetition. `scan_local` watches each point's run to +count its steps. Where a repetition keeps no final field (field-free planes, a scan), finiteness is read from its last plane's statistics and the repeat difference is not defined; `track` treats either gap as unchecked, never as consistent. diff --git a/docs/dev/conventions.md b/docs/dev/conventions.md index 201c8d142..8a8a677b6 100644 --- a/docs/dev/conventions.md +++ b/docs/dev/conventions.md @@ -103,8 +103,8 @@ later. The amplitude conversion is a separate, named boundary beside these Fourier helpers: `fourier.power_amplitude` maps internal `a` to saved `b`, and its inverse maps a resumed plane back. A session applies it on export (`backends.export.ExportRecipe` with -`power=True`, bitwise the same as `power_amplitude`), for single runs and the batch scan -path alike, before the output handler's conjugation. It never changes the Fourier sign. Input +`power=True`, bitwise the same as `power_amplitude`), for single runs and scan points +alike, before the output handler's conjugation. It never changes the Fourier sign. Input assembly and `Simulation.with_input` divide at the entrance. These are the amplitude conversion sites; no propagation kernel converts amplitudes. @@ -335,12 +335,10 @@ Cartesian one). ## 6. Array layout and axis names Kernel state and canonical storage: `(n_modes, n_pol, n_omega)` complex128, ω -contiguous (C order): one trajectory. A group of trajectories is a sequence of member -problems, not a leading axis ([SEP 47](seps/archive/sep-0047-run-ownership.md) §6.7); a backend -may hold its state privately with a leading axis of one (the native build's four-axis +contiguous (C order): one trajectory. A backend may hold its state privately with a leading axis of one (the native build's four-axis layout), and a march snapshot's file keeps that axis. Every backend computes in binary64 -(ADR-077). Saved fields: `(n_z, n_modes, n_pol, n_omega)`; a batched scan stores each member -separately. Space-domain buffers: `(n_nodes_chunk, n_pol, n_to)`. Convenience accessors +(ADR-077). Saved fields: `(n_z, n_modes, n_pol, n_omega)`; a scan stores each point separately. +Space-domain buffers: `(n_nodes_chunk, n_pol, n_to)`. Convenience accessors may squeeze trivial axes; the seam and the files never do. Standard axis names, reused verbatim in every jaxtyping annotation and docstring: diff --git a/docs/dev/figures/backends.svg b/docs/dev/figures/backends.svg index 4bf3347dc..ac542c1ef 100644 --- a/docs/dev/figures/backends.svg +++ b/docs/dev/figures/backends.svg @@ -1,6 +1,6 @@ + width="1200" height="717.5" viewBox="0 0 1200 717.5"> - + One seam, a shared driver, and the backends behind them backends.md §1: the protocol is drawn at the level of operations on the propagated state, never at the array-namespace level. A backend is constructed from a validated PropagationProblem and host arrays and returns host arrays; its buffers, layout and plans are private. - + the seam · backends.protocol.Backend prepare bind a problem and its run request; each start opens a session -prepare_group -bind compatible members; the start opens their group -edge_memory -what reading a grid's edge will hold, for an estimate -march_export_refusal -why the march cannot carry its history, or None -timing_probe -single trials from a start, committing nothing, for timing -metadata -what the execution was: pools, plans, digests, propagator mode -memory_ledger -every named buffer and its size -available_device_memory -free device bytes for batch admission; None on hosts -close -idempotent - - -backends.registry.select(name, problem, grid=, modes=, profiles=) - -HostDriver (the reference's step loop) -the march and the landing -_march_to -the replay -_replay_to · _schedule_index_at -the history -_record · observe -the progress reporter -set_progress -the statistics channel -_take_step_stats · stats -the noise -_noise_field · _noise_at · _noise_phase -the per-stage bundle -_hoist · _stage_scalars · _delta_phi · _unitary_phase - -the stepper it drives -stepper.tableau -DOPRI5, Tsit5, the order-condition checks -stepper.controller -PIController: propose, accepts, rejection_factor, -equivalent_norm -stepper.schedule -landing, discover, calibrate, replay -what a backend supplies -_trial_step · _apply_mask · _finish · _begin_plane -· _on_accepted_step - - - -numpy_ref · the oracle -plain NumPy and scipy.fft -one named function per pass -the general representation, the z table included -propagator_mode auto → tabulate -_trial_step · _apply_mask · _finish · _observed_field - - - -native · what auto selects -solprop-native distribution, native/ -C++20 Kokkos + persistent Kokkos-FFT plans -one native call per seven-stage trial -OpenMP on CPUs; CUDA and HIP on GPUs -_trial_step · _apply_mask · _finish · _observed_field -Three things every backend owes beyond the methods: deterministic reductions, the device form of the stage, and the driver's bookkeeping. The error norm is control flow, so -a sum whose association depends on the thread count forks the trajectory. +edge_memory +what reading a grid's edge will hold, for an estimate +march_export_refusal +why the march cannot carry its history, or None +timing_probe +single trials from a start, committing nothing, for timing +metadata +what the execution was: pools, plans, digests, propagator mode +memory_ledger +every named buffer and its size +available_device_memory +free device bytes for scan admission; None on hosts +close +idempotent + + +backends.registry.select(name, problem, grid=, modes=, profiles=) + +HostDriver (the reference's step loop) +the march and the landing +_march_to +the replay +_replay_to · _schedule_index_at +the history +_record · observe +the progress reporter +set_progress +the statistics channel +_take_step_stats · stats +the noise +_noise_field · _noise_at · _noise_phase +the per-stage bundle +_hoist · _stage_scalars · _delta_phi · _unitary_phase + +the stepper it drives +stepper.tableau +DOPRI5, Tsit5, the order-condition checks +stepper.controller +PIController: propose, accepts, rejection_factor, +equivalent_norm +stepper.schedule +landing, discover, calibrate, replay +what a backend supplies +_trial_step · _apply_mask · _finish · _begin_plane +· _on_accepted_step + + + +numpy_ref · the oracle +plain NumPy and scipy.fft +one named function per pass +the general representation, the z table included +propagator_mode auto → tabulate +_trial_step · _apply_mask · _finish · _observed_field + + + +native · what auto selects +solprop-native distribution, native/ +C++20 Kokkos + persistent Kokkos-FFT plans +one native call per seven-stage trial +OpenMP on CPUs; CUDA and HIP on GPUs +_trial_step · _apply_mask · _finish · _observed_field +Three things every backend owes beyond the methods: deterministic reductions, the device form of the stage, and the driver's bookkeeping. The error norm is control flow, so +a sum whose association depends on the thread count forks the trajectory. \ No newline at end of file diff --git a/docs/dev/figures/build.py b/docs/dev/figures/build.py index 2775c0f75..da2d13dc0 100644 --- a/docs/dev/figures/build.py +++ b/docs/dev/figures/build.py @@ -745,16 +745,13 @@ class Layer(NamedTuple): "driver", "adams", "low_storage", - "group", "session", - "group_session", ), ), Module( "backends/numpy_ref/", ( "backend", - "batch", "passes", "multistep", "populations", @@ -810,7 +807,7 @@ class Layer(NamedTuple): "selection", ), ), - Module("driver/executors/", ("local", "pool", "queue", "slurm", "batch")), + Module("driver/executors/", ("local", "pool", "queue", "slurm")), Module( "driver/routes/", ("gnlse", "hollow", "general", "spatial", "materials", "keywords"), @@ -834,7 +831,6 @@ class Layer(NamedTuple): "tdse", "tdse_consistency", "scan", - "batch", "defaults", "estimate", "plane_view", @@ -1240,13 +1236,12 @@ class Pass(NamedTuple): SEAM_METHODS = ( ("prepare", "bind a problem and its run request; each start opens a session"), - ("prepare_group", "bind compatible members; the start opens their group"), ("edge_memory", "what reading a grid's edge will hold, for an estimate"), ("march_export_refusal", "why the march cannot carry its history, or None"), ("timing_probe", "single trials from a start, committing nothing, for timing"), ("metadata", "what the execution was: pools, plans, digests, propagator mode"), ("memory_ledger", "every named buffer and its size"), - ("available_device_memory", "free device bytes for batch admission; None on hosts"), + ("available_device_memory", "free device bytes for scan admission; None on hosts"), ("close", "idempotent"), ) """The methods of `backends.protocol.Backend`; the reference's stepping seam is diff --git a/docs/dev/figures/layers.svg b/docs/dev/figures/layers.svg index 473f8892b..70d7c5eea 100644 --- a/docs/dev/figures/layers.svg +++ b/docs/dev/figures/layers.svg @@ -188,15 +188,15 @@ text { font-family: Inter, "Helvetica Neue", Helvetica, Arial, sans-serif; fill: rk_core · exponential · low_storage session · events · export session_core · sessions - + backends/host/ driver · adams · low_storage -group · session · group_session - -backends/numpy_ref/ -backend · batch · passes -multistep · populations -envelope_plasma · general_modal +session + +backends/numpy_ref/ +backend · passes · multistep +populations · envelope_plasma +general_modal D @@ -229,26 +229,25 @@ text { font-family: Inter, "Helvetica Neue", Helvetica, Arial, sans-serif; fill: driver/executors/ local · pool · queue · slurm -batch driver/routes/ gnlse · hollow · general · spatial materials · keywords - + driver/ simulation · settings · inputs metadata · resume · runner tdse_run · run · summary interface · scaffold · mixtures material_output · tdse -tdse_consistency · scan · batch -defaults · estimate · plane_view +tdse_consistency · scan · defaults +estimate · plane_view session_loop - -recipe/ -core · document · errors · export -metadata · paths · pins · preview -provenance · quantity · registry + +recipe/ +core · document · errors · export +metadata · paths · pins · preview +provenance · quantity · registry cli.py diff --git a/docs/dev/kernel-contract.md b/docs/dev/kernel-contract.md index 2a9fb3e48..238ce03c6 100644 --- a/docs/dev/kernel-contract.md +++ b/docs/dev/kernel-contract.md @@ -45,7 +45,7 @@ hard-mask zeros, and explicitly exact zeros and no-ops. | field | type | meaning | |---|---|---| | `grid_kind` | `"field" \| "envelope"` | selects r2c/c2r vs c2c transforms and the response formulas | -| `shape` | `(n_modes, n_pol, n_omega)` | canonical state shape of the one trajectory the problem describes; a group of trajectories is a sequence of problems ([SEP 47](seps/archive/sep-0047-run-ownership.md) §6.7) | +| `shape` | `(n_modes, n_pol, n_omega)` | canonical state shape of the one trajectory the problem describes | | `flags` | frozen dataclass of static flags and counts | `single_mode`, `scalar_pol`, `has_plasma`, `has_raman`, `has_noise`, `has_temporal_absorber`, `constant_linop`, `mode_averaged`, `n_channels`, `n_raman` — kernels specialise on these at compile time. Derived from the content, never passed in | | `grids` | frozen dataclass | section 2 (`translate.masks.Grids`) | | `linear` | frozen dataclass | section 3 (`translate.linop.LinearOperator`) | @@ -157,24 +157,10 @@ relies on by name, and in an editable checkout compares the extension with its ` sources by digest (`BuildInfo.source_digest`). An added optional field leaves every problem that does not use it unchanged. -**Batches and device memory.** A group (`GroupSession`, from the first member's -`prepare_group`; SEP 47 section 6.7) runs independently translated member backends, which -carry their own parameter tables and noise. The native group runs one native session per -member; the reference's runs a `BatchBackend`, its lockstep runner -(`registry.select_batch`), whose successful construction adopts the loaded members' -lifetime. `observe_members()` returns one -ordinary host `Observation` per member, preserving independent error histories and -periodic-statistics rows. `member_metadata()` returns each member's resolved policies plus -batch settings. `Backend.available_device_memory()` returns current free device bytes, +**Device memory.** `Backend.available_device_memory()` returns current free device bytes, excluding live allocations and allocator reserves, or `None` for host execution; -a host backend returns `None` and a device backend answers for itself. Common batch -admission uses that probe before allocating a complete group, with 20% headroom and a -conservative per-member upper bound from the complete memory ledger. Only compatible -layouts under the same explicit fixed schedule can share a batch; mixed backend names are -refused. The batch's `max_batch` is its constructed member count. Calling its -single-observation API is refused because it would discard the independent diagnostic -histories. The descriptors, stage bundles and singleton output schema are those of a -singleton run. +a host backend returns `None` and a device backend answers for itself. A scan's memory +admission reads it with the backend's complete memory ledger. **The general-modal leaves.** `linear.coupled_flow` and `linear.modal_metric` (§3), `transform.modal_tables` (§4) and `responses.regional_responses` (§5) are optional. Each @@ -1138,7 +1124,7 @@ launch's remaining planes). | `controller` | frozen dataclass | `solprop.stepper.controller.PIController`: `rtol`, `atol`, `safety`, `max_factor`, `min_factor`, `beta1`, `beta2`, `lag`, `reject_free`, `estimator_order`, and `weights` (`None` for the weak norm, a `(n_omega,)` array for the weighted one). The tolerances and the norm choice live here and nowhere else. | | `dz_min`, `dz_max`, `dz_init` | float | caps on the controller's proposal; `dz_min` defaults to `solprop.stepper.controller.default_dz_min` of the run length and never applies to a landing step. Under the `"split_step"` scheme `assemble` holds `dz_max` to the launch's crossing limit and refuses a schedule past it (`split_crossing`, §1) | | `stretch` | float | landing stretch factor (`StepTargets.stretch`), default 1.1, equal to the controller's default growth cap but independent of it; 1 switches it off | -| `schedule` | `(n_steps,) float64` or `None` | fixed schedule to replay (lockstep batches require it); its edges must contain every save plane and hard kink, which `FixedSchedule.uniform` guarantees for a plain fixed-step run | +| `schedule` | `(n_steps,) float64` or `None` | fixed schedule to replay; its edges must contain every save plane and hard kink, which `FixedSchedule.uniform` guarantees for a plain fixed-step run | | `save_planes` | `(n_z,) float64` | z positions the driver will ask for; steps land on them unless `interpolate_planes` is set | | `propagator_mode` | `"auto" \| "tabulate" \| "recompute"` | ADR-004 and [backends.md §3.6](backends.md). `"auto"` is the default and is the backend's own choice, resolved at construction and written into the run's `backend` metadata group: `tabulate` for `numpy_ref` and `recompute` for `native` on a modal problem; `recompute` on every backend for a separable free-space operator, whose increment `D (z₂ − z₁)` is exact. Under the low-storage march `tabulate` is one volume of `exp(h D / 2)` reused while the step holds (a varying operator's `P` and `Q` for the step), admitted on the free and planar kinds too, and `"auto"` resolves to `tabulate` for a constant operator and `recompute` for a varying one (SEP 24 §4.3), and to `recompute` on a native device build, where an extra field read costs more than the exponential | | `integrator` | `Multistep \| LowStorageRungeKutta \| None` | The method stepping the problem instead of the tableau, or `None` for the Runge-Kutta march. `Multistep` ([SEP 13](seps/archive/sep-0013-expensive-response-steppers.md), [SEP 16](seps/archive/sep-0016-unified-multistep.md)) is the Adams march in its exponential or interaction formulation, with an optional carrier frame (`carrier_frame`, [SEP 35](seps/archive/sep-0035-carrier-frame-exponential-adams.md), added in version 37: `"off"` or `"scalar"`, the latter on `numpy_ref` and native CPU builds and refused by name elsewhere); it runs on `numpy_ref` and Kokkos on every diagonal-flow route, and beside the constant-Schur and frozen-residual coupled flows in the exponential formulation; with a `schedule` it replays the schedule's steps (`HostAdamsMarch._replay_to`); the TDSE response runs adaptive, on `numpy_ref` and the native CPU build (SEP 49). `LowStorageRungeKutta` ([SEP 24](seps/archive/sep-0024-low-storage-interaction-picture-runge-kutta.md)) is RK4 in the midpoint interaction picture in three registers: it replays a `schedule` and nothing else, records the norm 0.0 ("not estimated"), refuses a coupled flow, the TDSE response, interpolated planes and a step past RK4's negative-real interval 2.785, and runs on `numpy_ref` and solprop-native (a resident engine whose step is one native call) | @@ -1181,7 +1167,7 @@ steps produce rows and passes their exact history indices: The defaults keep a host buffer and call `stats()`. No backend needs to override the march or read its private row buffer. Device arrays remain behind the seam. The native backend inherits the host defaults. A backend must implement the contract, -including the batch admission interface of §1, explicit handling or refusal of envelope +including the device-memory probe of §1, explicit handling or refusal of envelope source assemblies, and an explicit refusal of each general-modal leaf, section method and spatial kind it does not execute. @@ -1233,8 +1219,7 @@ an exception. There is no version counter to bump (ADR-068). There are exactly two **backends**, `native` and `numpy_ref`, and no other will be added (ADR-077; [backends.md §1](backends.md)). Each consumes this contract as it stands, visits every route variant and component to prepare or refuse it by name, and -runs through its own `prepare` (one run) and `prepare_group` (a group of compatible -members, or a `BackendError` saying it runs none), so the run layer names no backend. +runs through its own `prepare`, so the run layer names no backend. Both qualify on the conformance suite in `tests/sessions`, native against the reference. diff --git a/docs/dev/scans.md b/docs/dev/scans.md index 04fa7a486..de1f859f8 100644 --- a/docs/dev/scans.md +++ b/docs/dev/scans.md @@ -1,16 +1,16 @@ -# Scans and batches +# Scans Scans are implemented above the backend seam. A point has a permanent zero-based index in C order. Executors change where that point runs; they do not change its physics, seed, backend or place in the output. Seeds derive from a `base_seed`, retained fields are -explicitly selected planes, and different output shapes have separate layouts. Lockstep -batching is first class for `numpy_ref` and `native`. Scans preserve the -selected backend and reject unsupported contracts explicitly. +explicitly selected planes, and different output shapes have separate layouts. Scans +preserve the selected backend and reject unsupported contracts explicitly. -The executors (`solprop.driver.executors`) are `Local` (sequentially, in the calling process), `Pool` -(spawned worker processes), `Batch` (fixed-schedule lockstep groups on one backend, -[backends.md §1](backends.md)), and the durable file `Queue` with its `Slurm` emitter, -which runs queue or chunk modes as array tasks. +The executors (`solprop.driver.executors`) are `Local` (sequentially, in the calling +process, reusing one backend where it can), `Pool` (spawned worker processes), and the +durable file `Queue` with its `Slurm` emitter, which runs queue or chunk modes as array +tasks. A fixed-schedule `Batch` executor ran compatible points as one group until +SEP 52 removed it: on native it built a backend per member for no gain in speed. ## Why the standard library @@ -40,7 +40,7 @@ sent to workers. Local execution also permits closures. ## Execution and memory -The layers are Slurm array, node controller, worker, and optionally a backend batch. +The layers are Slurm array, node controller and worker. The controller owns the collected HDF5 file. A worker receives point descriptions and returns statistics and reductions; retained fields travel only when requested. Every spawned interpreter inherits its thread environment before importing NumPy, diff --git a/docs/dev/seps/index.md b/docs/dev/seps/index.md index 0765e11f0..f025ed224 100644 --- a/docs/dev/seps/index.md +++ b/docs/dev/seps/index.md @@ -34,7 +34,7 @@ Proposals that are active, in draft, accepted, in progress or deferred. | [17](sep-0017-gas-two-photon-ionisation.md) | Broadband two-photon continuum response beside strong-field ionisation | Accepted | Feature | | [32](sep-0032-raman-maxwell-bloch.md) | Raman Maxwell–Bloch dynamics | Draft | Feature | | [51](sep-0051-save-planes.md) | One rule for the saved planes and the end of a run | Accepted | Change | -| [52](sep-0052-backend-shape.md) | One backend shape and a small native seam | Accepted | Change | +| [52](sep-0052-backend-shape.md) | One backend shape and a small native seam | In progress | Change | SEP 13, the standalone numerical prerequisite for SEP 12, SEP 14, which carried it to the compiled backends, and SEP 16, which unified the multistep family and made it the diff --git a/docs/dev/seps/sep-0052-backend-shape.md b/docs/dev/seps/sep-0052-backend-shape.md index 27b58f3ea..877ee0677 100644 --- a/docs/dev/seps/sep-0052-backend-shape.md +++ b/docs/dev/seps/sep-0052-backend-shape.md @@ -6,7 +6,7 @@ | **Title** | One backend shape and a small native seam | | **Author** | John Travers | | **Drafting agent** | Opus 5.5 (2026-11-15; revised after review, 2026-11-15) | -| **Status** | Accepted | +| **Status** | In progress | | **Review status** | Reviewed | | **Reviewers** | John Travers (human); GPT-6 (AI) | | **Type** | Change | @@ -15,7 +15,7 @@ | **Requires** | SEPs 25, 39, 45 and 47 | | **Supersedes** | — | | **Superseded-by** | — | -| **Implementation** | — | +| **Implementation** | Opus 5.5 (AI) for John Travers, through four stacked pull requests (D7): (1) phases 0–1, branch `feature/sep-0052-backend-shape-p1` ([#853](https://github.com/LupoLab/solprop/pull/853)); (2) phase 2 and phase 3's axis removal, `feature/sep-0052-backend-shape-p2`; (3) the rest of phase 3, `feature/sep-0052-backend-shape-p3`; (4) phases 4–5, `feature/sep-0052-backend-shape-p4`; started 2026-11-15 | | **Manual pages** | — | ## Part I — Proposal @@ -991,6 +991,130 @@ of what it changes (§6.1). ## Part II — Implementation record +### Milestone 1 (phases 0–1) — 2026-11-16 + +Branch `feature/sep-0052-backend-shape-p1` +([#853](https://github.com/LupoLab/solprop/pull/853)), the first of the four stacked pull +requests of D7, started 2026-11-15 by Opus 5.5 (AI) for John Travers. The two phases were +developed in parallel by AI agents on separate branches and merged into the milestone +branch, where the tests both touched were rerun. + +**Scope.** Phase 0, native deletions and the test module (`e9631521`); phase 1, removal +of `Batch` and the groups (`e52efb20`); their merge (`3a47dfc2`). + +**Delivered, phase 0.** + +- *Deleted bindings nothing reached:* `table_evaluate`, `table_rate`, `set_flow_actions` + (with its wrapper) and `shutdown_runtime`. `shutdown_kokkos` stays, because the + at-exit hook uses it. +- *Deleted the dead per-step Adams adapter:* `_ResidentAdams`'s `hold`, `restore`, + `start`, `snapshot_rows`, `fused_trial`, `fused_accept`, `exponential_trial`, + `exponential_accept`, `observe` and `march_stepped`, and the four bindings only they + reached (`adams_fused_trial_at`, `adams_fused_accept`, `adams_observe`, + `adams_exponential_observe`). No test used them. The C++ behind them stays, because + the compiled engines, the dense output and ctest use it. Construction, `reset`, + `value`, `snapshot_nbytes` and `load_rows` stay, as do the timing probe's paths + (`_trial_step`, `_prepare_trial`, `_score_trial`, `_ResidentLowStorage.step`, + `_ZTables`), which phase 4 replaces. +- *`_core._testing`:* a submodule of the same extension (`bind_testing` in + `native/src/bindings.cpp`, with `bind_helpers` and `bind_transverse` binding into it). + It holds 54 names in the seven groups of §6.5: the decision-trace marches and their + runners, `adams_march_fault`, `Monitor`, `TransverseEdge` and the watch functions, + the engine-level parity functions, the state-level statistics, the vector and width + helpers, and the runtime probes. State methods became functions that take the state + first. Eight more names moved than §6.5 lists, because tests reach them + (`adams_exponential_trial_at`, `adams_exponential_accept`, `adams_start`, + `adams_compensation_start`, `adams_hold`, `adams_restore`, `adams_rows_to_host`, + `table_rate_at`). `reference_stream_copies` did not move: calibration uses it. + `State` went from 96 bound names to 55. +- *Stub:* `_core.pyi` (953 → 636 lines) links a hand-written `_core_testing.pyi` (310 + lines). nanobind's `stubgen` types every record argument as a bare `dict`, which the + native tests' strict typing refuses, so the generated stub waits for phase 4's typed + record signatures. `native/scripts/problem_stub.py --check` now also compares the + `_testing` stub's names and members with the built module. +- *Smoke test:* `native/ci/smoke.py` imports `_testing` and checks `vector_exp` against + NumPy. +- *nanobind pinned* to 3.1.0 for the wheel build and the development group. +- Stale citations of the deleted adapter fixed in `dense.hpp`, `dense_output.hpp`, + `engines.hpp`, `engines.cpp` and `docs/dev/stepper.md`; `native/AGENTS.md` states the + `_testing` rule. + +**Delivered, phase 1.** + +- *Deleted modules:* `driver/executors/batch.py`, `driver/batch.py`, + `driver/_scan_batch.py`, `backends/host/group.py`, `backends/host/group_session.py`, + `backends/numpy_ref/batch.py` and `solprop_native/group.py`. +- *Removed members:* `Backend.max_batch`, `Backend.prepare_group`, `BatchBackend`, + `GroupSession`, `PreparedGroup`, `check_group`, `check_member_ticket`, `start_group`, + `select_batch`, the scan's group hook and its exports, and the `group_batch` + benchmark. Also group-only: `events.GroupBatch`, `ExportTicket.member`, the member + argument of `session_core.bind`, the native counters' group keys and + `StatsSpec.same_tables`. `Backend` now has exactly the members of §5.1, and its frozen + surface in `tests/backends/test_driver.py` is updated. +- *Documentation:* the scans guide loses its fixed-schedule batch section, and `Batch` + leaves the API page and about 25 guide pages; the developer pages (`scans.md`, + `architecture.md`, `backends.md`, `kernel-contract.md`, `stepper.md`, + `benchmarking.md`, `accuracy.md`, `conventions.md`, `testing.md`, `structure.md`) and + the regenerated `backends.svg` and `layers.svg` no longer describe groups. The + `Removed` fragment names `Local`, `Pool`, `Queue` and `Slurm`; three unreleased + fragments that only announced `Batch` features are deleted. +- The unit axis is untouched; it leaves in milestone 2. + +**Tests (§7 inventory).** + +- *Phase 0:* no test was deleted. Every caller of a moved name is repointed to + `_testing`, about 30 test files and helpers in `tests/` and `native/tests/`. Tests + that used the deleted adapter methods now use small helpers over the moved bindings + (`native_adams_start`, `native_adams_rows`, `native_exponential_trial`, + `native_stage_rows`, `native_rate_weights` in `tests/sessions/runs.py`). +- *Phase 1, deleted whole, group-only:* `tests/backends/test_batch_lockstep.py`, + `test_batch_validation.py`, `test_batch_responses.py`; `tests/driver/test_batch.py`, + `test_scan_batch.py`; `tests/sessions/test_group.py`, `test_group_seam.py`, + `test_native_group.py`; `native/tests/test_batch.py` (95 tests). +- *Phase 1, ported:* the scan builder became `tests/builders.py::fixed_fibre_point`; the + failed-launch probe test moved to `test_scan_worker_validation.py`; the group's final + warning became an eligibility assertion in `test_native_session_monitor.py`; the + z-table batch test became one single run per fibre against the reference; the + monitor's batch-versus-`Local` scans run on `Local`; `test_scans.py` and + `test_exponential_march.py` lost their batch parametrisation. +- *Phase 1, deleted inside mixed files,* each because the group was its subject: the + lockstep and refusal tests in `test_exponential_march.py`, `test_low_storage.py`, + `test_field_free_planes.py`, `test_moving_guide.py`, `test_split_block.py`, + `test_general_modal.py` (7), `test_native_coupled_flow.py`, + `test_scan_stop_progress.py`, `test_prepare.py` and the native group tests; the + batch-equals-members cases in `test_optmat_cases.py`, `test_vector_raman_routes.py`, + `test_coherent_capillary.py`, `test_envelope_plasma.py`, + `test_vector_raman_output.py` and `test_scan_derived_noise.py`; the GPU group test in + `test_native_session_device.py`. The single-run cases of each file stay. + +**Verification.** On an Apple M5 Max, CPU editable build: the directly affected test +modules at four workers (about 3,000 tests across `tests/backends`, `tests/driver`, +`tests/sessions`, the monitor, benchmark and capillary modules, `native/tests`, the +structure figures, the guide snippets and the changed modules' doctests), all passing +except `native/tests/test_band_plasma.py::test_response_column_boundary_preserves_full_and_tail_windows[19]`, +a thread-sizing assertion that also fails without this change on that machine; the +tests both phases touched, rerun after their merge; collection of every test; ruff, +basedpyright, the docstring check, codespell, the changelog check, `poe docs` and +`poe size-check`. Not run locally: ctest (only comments changed in the C++ library), +clang-tidy, the full and coverage lanes, the wheel build and smoke test, and the two +GPU-marked tests, which run in CI or need a device. + +**Cost** (`poe size --all`, Python only). Total 271,036 → 266,928 lines: `backends` +24,834 → 22,753, `solprop_native` 14,154 → 12,877, `driver` 27,203 → 26,460 (that +figure also includes an unrelated change merged from main). Binding units: +`bindings.cpp` 4,559 → 4,459, of which 683 now bind `_testing`. Tests: about 5,100 +lines removed with the group tests. + +**Deviations.** None from Part I. The `_testing` stub is hand-written until phase 4, +as stated above. + +**Open questions.** None new. + +**Handoff.** Milestone 2 adds the run records and engine protocols, records the +comparison corpus of §7 from this tree, pins the split collar's rules, and removes the +unit axis. `ApertureSet.same_as` is kept because tests use it, though production no +longer does. + ## Part III — History - 2026-11-15: Drafted, from a review of the native binding's use in production and of the @@ -1004,6 +1128,9 @@ of what it changes (§6.1). completes the protocol, engine, converter and qualification contracts. - 2026-11-15: John Travers reviewed the revised proposal and decided D7 (stacked phase pull requests). Accepted by John Travers in PR #850. Part I is frozen. +- 2026-11-15: Implementation started by Opus 5.5 (AI) for John Travers, on + `feature/sep-0052-backend-shape-p1`. +- 2026-11-16: Milestone 1 (phases 0–1) reported in Part II. ### AI review — 2026-11-15 diff --git a/docs/dev/stepper.md b/docs/dev/stepper.md index a0489fd9c..66dccdd20 100644 --- a/docs/dev/stepper.md +++ b/docs/dev/stepper.md @@ -176,9 +176,8 @@ fifth-order one, and the FSAL stage is not recycled before anything that depends completed step (irrelevant without dense output, but tested). **Who marches** ([SEP 47](seps/archive/sep-0047-run-ownership.md)). The NumPy reference runs -its own step driver and marches in `backends/host/`: `HostDriver`, `HostAdamsMarch`, -`HostLowStorageMarch` and the fixed-schedule group `HostGroup`. Every -native run is its native session's, whose compiled Runge-Kutta, Adams and low-storage +its own step driver and marches in `backends/host/`: `HostDriver`, `HostAdamsMarch` +and `HostLowStorageMarch`. Every native run is its native session's, whose compiled Runge-Kutta, Adams and low-storage marches decide natively from one policy record each: the native backend loads a start itself (`solprop_native._load`) and keeps its Adams march's policy, ledger and history in a record of its own (`_NativeAdamsMarch`), and inherits no Python step loop. The @@ -374,8 +373,8 @@ caps each proposal at `CARRIER_PHASE_CAP` of carrier phase before the landing ru (`HostAdamsMarch._capped`), measured by the reference element's chord alone (`CarrierChord`, the operator's own constant, expansion or z table at that element), so a capped step is not a landing; a replayed schedule is not capped. The native -engine (`_ResidentAdams`) forms its `sigma` from the same chord on the host and passes -it with the factors in `ExponentialWeights` (`shifted`, `shift`, `factor_re`, +engine (`engines::ResidentEngine`) forms its `sigma` from the same chord, read from the +stage tables (`stage::chord`), and passes it with the factors in `ExponentialWeights` (`shifted`, `shift`, `factor_re`, `factor_im`); its kernels read rows through `adams_history` and form moments through `adams_moment_phi`, and dense observation takes the accepted step's carrier frame. An inert or `"off"` run takes the unshifted arithmetic exactly. `"scalar"` runs on @@ -469,8 +468,6 @@ only at an accepted position with nothing ahead of it. **Prescribed schedules**: with a schedule the march replays its steps (`HostAdamsMarch._replay_to`), accepting each whatever its estimate, which is recorded as the Runge–Kutta replay records it; a hard kink on an edge restarts the history. -`HostAdamsMarch.replay_step` is also the unit a lockstep batch advances each member by -(`HostGroup._replay_to`), each member keeping its own history and ledger. The derivation, the stability limits and the measured comparison are in [SEP 13](seps/archive/sep-0013-expensive-response-steppers.md) and on the manual page @@ -692,8 +689,7 @@ Memory: the expansion is `n_terms × n_modes × n_pol × n_omega × 16 B` plus s `n_intervals × (degree+1) × n_modes × n_pol × n_omega × 16 B`. On the comb-to-continuum size — six modes, 16 385 bins, a 1.5 m hydrogen gradient — that is 49.7 MB against 792 MB for Φ and 15.1 MB against 759 MB for the prefactor, so the pair falls from 1.55 GB to -64.8 MB; `ΔΦ` falls from 17.8 ms to 1.2 ms with it. Either is shared -across batch members with the same fibre. +64.8 MB; `ΔΦ` falls from 17.8 ms to 1.2 ms with it. ## 5. The co-moving frame and analytic β₁ @@ -781,13 +777,11 @@ rejected a step the replay may choose a different order; and a resumed march can its history from a restart rather than carry the original one. A replay of an adaptive run is therefore an accuracy comparison (an envelope against a tighter or stored reference), and so is a resumed run against the uninterrupted one. Rounding-level -comparisons — backend against backend, one thread against many, a batch member against its -solo run — run **both** sides on one prescribed schedule with a fixed-order method and +comparisons — backend against backend, one thread against many, a scan point against its +run alone — run **both** sides on one prescribed schedule with a fixed-order method and matched startup, restart history and save planes ([testing.md](testing.md) section 3). Recording and replaying every adaptive decision is not provided. -Batch lockstep execution uses fixed schedules only (ADR-013). - ## 9. Open numerical questions The solver's open questions — error norms for weak observables, reject-free efficiency at diff --git a/docs/dev/structure.md b/docs/dev/structure.md index 92540e2b6..afe2f45a0 100644 --- a/docs/dev/structure.md +++ b/docs/dev/structure.md @@ -96,9 +96,7 @@ the noise and the per-stage bundle all live in the reference's step driver, ([SEP 47](seps/archive/sep-0047-run-ownership.md)) — and under that the the implemented backends: NumPy reference and native (built from `native/`). Each supplies trial/state operations and the relevant hooks; the loop's -statistics channel and progress reporter call back through the seam. Fixed fibre -batches extend this interface with independent member observations and metadata -([kernel contract](kernel-contract.md)). +statistics channel and progress reporter call back through the seam. ![The backend seam, the shared step driver, and the implemented backends](figures/backends.svg) diff --git a/docs/dev/testing.md b/docs/dev/testing.md index 822217a23..c40b23e1a 100644 --- a/docs/dev/testing.md +++ b/docs/dev/testing.md @@ -33,7 +33,7 @@ do not launch the full suite merely because a SEP is being committed or merged. | invariant | energy and photon number where conserved, Parseval, time reversal, symmetries, positivity, orthonormality of modes | grids, transforms, modes, responses | | convergence | halve the step or double the grid and the error scales at the expected order; three levels with an order gate that rejects `order > p + 3` | stepper, quadrature, tables, Chebyshev | | round trip | build → translate → run → process and recover a known input | pulses, output, processing | -| parity | field vs envelope for narrowband pulses; mode-averaged vs one-mode multimode; batch vs sequential; backend vs reference | every nonlinear feature, on each backend that runs it (on `numpy_ref` and `native` always; ADR-068, ADR-077) | +| parity | field vs envelope for narrowband pulses; mode-averaged vs one-mode multimode; scan point vs run alone; backend vs reference | every nonlinear feature, on each backend that runs it (on `numpy_ref` and `native` always; ADR-068, ADR-077) | | property-based | `hypothesis` over grid sizes, pulse parameters, pressures | grids, pulses, materials, Chebyshev | | golden regression | `pytest-regressions` (`num_regression`) with tolerance, reference stored next to the test | materials tables, stored Luna results | | reference problem | the ladder in [stepper.md §11](stepper.md#11-verification-ladder-for-solprops-solver-tests): P0 linear, P1 N-soliton with phase, P2 analytic z-varying loss and dispersion, P3 cross-scheme Richardson | solver work | @@ -242,13 +242,13 @@ or step; the accuracy of a reference (a table's stated accuracy, an experimental Luna result's own convergence). Independent floating-point computations are compared by numerical error, never by bits ([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)): no comparison requires bitwise agreement across backends, builds, machines, thread counts, -batch membership, scan execution or repeated runs. Every comparison belongs to one of five +scan execution or repeated runs. Every comparison belongs to one of five classes, and `tests/bounds.py` holds the reusable parts of their bounds. | class | what is compared | criterion | |---|---|---| | **P**, structural | lossless storage, copies and views; integer accounting and ledgers; identity metadata and hashes used for configuration identity, cache validation or provenance; hard-mask zeros; explicitly exact no-ops (a feature left off, a row reusing the data its plane stores) | exact (`np.array_equal`, `==`), with a comment saying why the contract is exact | -| **R**, matched discrete computation | two backends, thread counts, a batch member and its solo run, a scan point and its run, a fast path and the general path: the same method, orders, startup and restart history, schedule and inputs | a rounding bound | +| **R**, matched discrete computation | two backends, thread counts, a scan point and its run, a fast path and the general path: the same method, orders, startup and restart history, schedule and inputs | a rounding bound | | **T**, accuracy | adaptive runs, ordinary replay, resumed against uninterrupted runs: discrete trajectories that may differ | an accuracy envelope | | **D**, recorded state | a route's stored final state (§5) | `ndarrays_regression` at a bound of class R or T | | **N**, noise | a seeded realisation | a short-window R comparison, or an ensemble observable with a tolerance set from the ensemble size | diff --git a/docs/guide/numerics/adams.md b/docs/guide/numerics/adams.md index 8b0183d9f..57cbebaea 100644 --- a/docs/guide/numerics/adams.md +++ b/docs/guide/numerics/adams.md @@ -336,7 +336,7 @@ $$u_{n+1} = e^{hD}u_n + h\sum_k k!\,\varphi_{k+1}(hD-\sigma)\sum_j c_{jk}\,G_j, so the step interpolates the rotated samples $G_j$ and integrates them against the moments at $hD - \sigma$. The shift is the step's own carrier phase, $\sigma = \mathrm{i}\operatorname{Im}(hD)$ at the active bin nearest the reference -frequency, on the frame's mode and first polarisation, one per batch member. The +frequency, on the frame's mode and first polarisation. The state, the stored samples and the linear flow $e^{hD}$ are unchanged; only the function the polynomial follows is. Rotating the samples without shifting the moments would not be equivalent: it integrates $G$ against the wrong flow, an error of order @@ -711,8 +711,8 @@ gives the measured ranking by regime, on the native backend's CPU build and on d a hard kink restarts the history. A replay meets the run's accuracy target rather than reproducing it bit for bit: replaying an adaptive run's steps reproduces its positions, but the orders are chosen afresh and rejected trials are not replayed, so - where that run rejected a step the replay may choose a different order. Lockstep batches follow (each member keeps - its own history). The in-stage collar is a damping term integrated explicitly, so a + where that run rejected a step the replay may choose a different order. The in-stage + collar is a damping term integrated explicitly, so a replayed step must keep $h\alpha/2$ inside the method's real stability interval — 0.0877 for PEC5/6 against DOPRI5's 3.3 (the table above, extended to all orders in `solprop.stepper.multistep.PEC_REAL_INTERVAL`); the translation refuses a diff --git a/docs/guide/numerics/choosing-a-stepper.md b/docs/guide/numerics/choosing-a-stepper.md index 4adc29f54..0e10449a0 100644 --- a/docs/guide/numerics/choosing-a-stepper.md +++ b/docs/guide/numerics/choosing-a-stepper.md @@ -199,9 +199,8 @@ not matched `rtol`. At `rtol` of 5e-2 or more the Adams method is unreliable and **How long the run is, and how many.** A run's first few steps rebuild the history from order one, a fixed cost that a short run feels most. A single short run hardly matters; in a scan of thousands, measure one point with each integrator before choosing, and -spread the points over a `Pool` of one-thread workers, which scales with the cores: -batching in lockstep buys nothing on the CPU and about 1.1 times on a GPU -([scans](../workflows/scans.md#fixed-schedule-batches)). +spread the points over a `Pool` of one-thread workers, which scales with the cores +([scans](../workflows/scans.md#processes-and-resource-limits)). **Planes.** Both integrators interpolate save planes inside their steps (`interpolate_planes=True`) at the step's own order and no call; landing on them stays diff --git a/docs/guide/numerics/fixed-schedules.md b/docs/guide/numerics/fixed-schedules.md index 3d9cc90e5..b477b019d 100644 --- a/docs/guide/numerics/fixed-schedules.md +++ b/docs/guide/numerics/fixed-schedules.md @@ -1,6 +1,6 @@ # Fixed schedules and repeatable propagation -A fixed schedule prescribes where the solver steps. Use it to replay positions or run compatible problems in a batch, after checking its accuracy for the parameter range. Accepting every prescribed step does not make its local error acceptable. Adaptive stepping remains the starting point for discovering a suitable schedule. +A fixed schedule prescribes where the solver steps. Use it to replay positions or run an ensemble on identical steps, after checking its accuracy for the parameter range. Accepting every prescribed step does not make its local error acceptable. Adaptive stepping remains the starting point for discovering a suitable schedule. ## Fixed schedules: discover, calibrate, replay @@ -11,7 +11,7 @@ per-member variance that adds; for repeat calculations and debugging, since a re run takes the recorded steps and meets the original run's accuracy target (it need not reproduce its bits, [SEP 25](../../dev/seps/archive/sep-0025-rounding-level-reproducibility.md)); and on a device, where there is nothing to synchronise. Both modes are therefore first -class, and batch lockstep execution uses fixed schedules only. +class. 1. **Discover.** One adaptive run records $h(z)$; {py:obj}`~solprop.stepper.schedule.discover` turns the accepted step lengths into a diff --git a/docs/guide/numerics/reproducibility.md b/docs/guide/numerics/reproducibility.md index f220b8488..af5840d64 100644 --- a/docs/guide/numerics/reproducibility.md +++ b/docs/guide/numerics/reproducibility.md @@ -40,9 +40,8 @@ not a defect. ## Replaying a schedule -When the steps themselves must be the same, for a batch run in lockstep, for debugging, -or to make a numerical error common to every member of an ensemble, record the schedule -once and replay it ([fixed schedules](fixed-schedules.md)): +When the steps themselves must be the same, for debugging or to make a numerical error +common to every member of an ensemble, record the schedule once and replay it ([fixed schedules](fixed-schedules.md)): ```{code-block} python from solprop.stepper import calibrate, discover, replay diff --git a/docs/guide/performance/backends.md b/docs/guide/performance/backends.md index 05fecb6c7..64eb9eb00 100644 --- a/docs/guide/performance/backends.md +++ b/docs/guide/performance/backends.md @@ -136,10 +136,8 @@ ten steps before committing a long campaign to one backend. GPU or an AMD Instinct GPU than on an 18-core CPU socket (about four and three times on a scaled graded-index guide); a small case is limited by kernel-launch latency ([The native backend](native.md#running-on-a-gpu)). -- **Batches.** A fixed-schedule batch fuses the accepted updates of its members, while - the response and transform work stays per member, so it does not amortise a device's - launch sequence; measure a batch's gain for your own shape. On a CPU, a `Pool` of - one-thread workers is the better scan pattern. +- **Scans.** On a CPU, a `Pool` of one-thread workers is the scan pattern that scales + with the cores ([scans](../workflows/scans.md#processes-and-resource-limits)). ## Memory and scans diff --git a/docs/guide/performance/building-native.md b/docs/guide/performance/building-native.md index 88e778c77..f6c72311a 100644 --- a/docs/guide/performance/building-native.md +++ b/docs/guide/performance/building-native.md @@ -47,7 +47,7 @@ them: | [SLEEF](https://github.com/shibatch/sleef) | 3.9.0 | vector `exp`, `log` and `sincos` for the CPU kernels on x86-64 and macOS arm64 (see [vector maths](#vector-maths)); built static as its own CMake project, and not fetched where the system libm is used | | [GoogleTest](https://github.com/google/googletest) | 1.17.0 | the native tests only, when `BUILD_TESTING=ON` | -The Python build requirements are scikit-build-core 0.11 and nanobind 2.9 or newer. CPU +The Python build requirements are scikit-build-core 0.11 and nanobind 3.1.0, pinned. CPU builds contract multiply-adds (`-ffp-contract=fast` with GCC, `-ffp-contract=fast-honor-pragmas` with Clang, after `-fno-fast-math`) except in a few protected blocks, as [SEP 25](../../dev/seps/archive/sep-0025-rounding-level-reproducibility.md) sets out; diff --git a/docs/guide/performance/native.md b/docs/guide/performance/native.md index c8b0a1e31..c2c6c4537 100644 --- a/docs/guide/performance/native.md +++ b/docs/guide/performance/native.md @@ -31,7 +31,6 @@ The native backend runs: including guides that vary along z), the coupled flow of the coherent capillary wall and of tapers, with its `constant_schur` and `frozen_residual` sections; - radial, Cartesian, line and planar free-space and planar-guide geometries; -- fixed-schedule batches (lockstep scan members); - **the Chebyshev z table**: a linear operator or nonlinear prefactor that varies along z in a way that has to be tabulated, rather than expanded in the medium's parameters. Examples are a `SpecifiedMode` whose dispersion moves along z, the adiabatic opt-out diff --git a/docs/guide/performance/progress.md b/docs/guide/performance/progress.md index 5ada2af9b..4f783fa85 100644 --- a/docs/guide/performance/progress.md +++ b/docs/guide/performance/progress.md @@ -302,7 +302,7 @@ its run's `summary`, `started`, `plane`, `finished` and `interrupted` calls to t controller on its pipe, where they are made on the point's reporter as they arrive: a plane carries its position and the four scalars of its summary (steps, rejected steps, largest error norm, wall time), never a field, and `step` is not sent at all, since it is -called thousands of times a second. `Batch`, `Queue` and `Slurm` report only the points' +called thousands of times a second. `Queue` and `Slurm` report only the points' boundaries, as their results are collected. The table per executor, and the scan's `stop=` flag, are in [watching and stopping a scan](../workflows/scans.md#watching-and-stopping-a-scan). diff --git a/docs/guide/performance/tuning.md b/docs/guide/performance/tuning.md index dbda1370b..878450a56 100644 --- a/docs/guide/performance/tuning.md +++ b/docs/guide/performance/tuning.md @@ -176,7 +176,7 @@ execution. Stage and reduction work, packing and temporal copies, nonlinear resp native dense transforms, coupled matrix functions and FFT plans have separate size rules. Response sizing accounts for both the total work, active columns and fine samples per column. The choices and plans are cached when the backend is constructed; no runtime tuning occurs during propagation. Partial chunks -and fused batch updates use their own work sizes. Vendor BLAS pools retain their +use their own work sizes. Vendor BLAS pools retain their process-start settings. Non-OpenMP host builds preserve their execution-space policy; `build_info().cpu_size_policy_enabled` reports whether operation widths are supported. @@ -201,7 +201,7 @@ The calibration moves the samples per thread. | operation | work used for sizing | threading starts | full pool starts | |---|---|---:|---:| -| stage, update and reduction | elements in the field or fused batch | 4,096 (8,192 on macOS) | as threading | +| stage, update and reduction | elements in the field | 4,096 (8,192 on macOS) | as threading | | packing and temporal copies | entries actually copied | 65,536 | 65,536 | | nonlinear response | active columns × components × fine samples | 32,768 | 196,608, or 65,536 fine samples per column, or 40 component columns | | native/custom GEMM | output rows × inner dimension × samples | 1,048,576 | 1,048,576 | @@ -224,8 +224,8 @@ choices automatically; start by setting only the process cap when sharing a mach `python -m solprop_native` records the policy constants and explicit override mask. Its existing thread counts remain process capacities. The backend's metadata records -`execution_sizing`, with the chosen `threads` and sizing `elements` for each operation; -`batch_execution_sizing` covers fused batch work. Response entries also report +`execution_sizing`, with the chosen `threads` and sizing `elements` for each operation. +Response entries also report `fine_samples` and `columns`, because equal total work can have different column lengths. `build_info()` reports the resolved process values as `requested_threads`, `runtime_threads`, `thread_count` (kernels), `fftw_threads`, `raman_fft_threads`, diff --git a/docs/guide/results/interior-launch.md b/docs/guide/results/interior-launch.md index 4831f5d5c..425721d07 100644 --- a/docs/guide/results/interior-launch.md +++ b/docs/guide/results/interior-launch.md @@ -53,5 +53,5 @@ atomic runtime resources beside `backend="numpy_ref"` and a `Multistep` integrat The declared response sampling refines the existing fine lattice once, retaining the coarse grid, period and collars. An inherited standard temporal collar is evaluated on the finer lattice with the same physical reference length; a custom -absorber must already carry matching fine samples. Changing execution device, -batch width or memory limits does not alter the scientific resume identity. +absorber must already carry matching fine samples. Changing execution device or +memory limits does not alter the scientific resume identity. diff --git a/docs/guide/results/output.md b/docs/guide/results/output.md index 1889d0d8e..fbcc3fc5d 100644 --- a/docs/guide/results/output.md +++ b/docs/guide/results/output.md @@ -539,7 +539,7 @@ function. The default, `None`, leaves the run unchanged. This is an execution po outside the scientific configuration hash; `SimulationRunner`'s restriction on reusing TDSE across inputs still applies. -A snapshot requires an unbatched HDF5 run with `fields="all"`; it no longer needs +A snapshot requires an HDF5 run with `fields="all"`; it no longer needs `step_planes`, and it is taken with interpolated planes too ([SEP 47](../../dev/seps/archive/sep-0047-run-ownership.md)). With `interpolate_planes=True` a request is taken at the end of the step that crossed the plane being saved, once every diff --git a/docs/guide/results/resuming.md b/docs/guide/results/resuming.md index 10f22647a..71f410c40 100644 --- a/docs/guide/results/resuming.md +++ b/docs/guide/results/resuming.md @@ -304,8 +304,8 @@ A file written before this record has none: its retention reads as `{"state": "unknown", "reason": "legacy"}`, never as an invented reason, and it resumes as it always did. -Scientific changes still require a new run. Device choice, batch width and execution -memory limits may change on resume and are recorded in `outcome.execution`; a new +Scientific changes still require a new run. Device choice and execution memory +limits may change on resume and are recorded in `outcome.execution`; a new atomic call limit cannot be smaller than the calls already attempted. The driver validates the checkpoint and ledgers before preparing atomic resources. Resuming an already completed file returns it without preparing another backend or atomic diff --git a/docs/guide/results/statistics.md b/docs/guide/results/statistics.md index 3632adbd7..252d0ad87 100644 --- a/docs/guide/results/statistics.md +++ b/docs/guide/results/statistics.md @@ -615,7 +615,6 @@ reference within a rounding bound, and decides every hard edge as the reference The same pass also forms `on_axis_spectrum` (an aperture with $W\equiv1$). A solprop-native build from before this pass is refused them by name, before it is built. -Lockstep batch members must carry equal tables. ```{code-block} python import numpy as np diff --git a/docs/guide/setup/model-selection.md b/docs/guide/setup/model-selection.md index fc6aaa071..1c10ae3fb 100644 --- a/docs/guide/setup/model-selection.md +++ b/docs/guide/setup/model-selection.md @@ -210,7 +210,6 @@ repeatability tests pass on a data-centre NVIDIA GPU (CUDA) and an AMD Instinct | a frequency-dependent electronic response, `MaterialSelection(electronic="symmetric-kerr")` or `"gas-polynomial"` ([model](../media/dispersive-kerr.md)), on every route but the GNLSE | yes | yes | qualified | | the `input` noise model beside a coupled flow (a coherent wall, the taper coupling, a split block, a moving guide) | yes | admitted, not yet qualified | not qualified | | the `modified` noise model beside a coupled flow | refused | refused | refused | -| a coupled flow in a fixed-schedule `Batch` group | yes: member by member | yes: each member in its own native session | as the session admits each member; not qualified | `backend="auto"`, the default, is `native`, and it **never falls back**: it refuses if the native package is missing or the processor is below its minimum, and a problem the native diff --git a/docs/guide/waveguides/capillaries.md b/docs/guide/waveguides/capillaries.md index 40d9b3494..d6f404f85 100644 --- a/docs/guide/waveguides/capillaries.md +++ b/docs/guide/waveguides/capillaries.md @@ -111,7 +111,7 @@ a curve or `False` beside a wall is refused rather than silently dropped), and `model="reduced"` is refused because the condensation inverts the full model's eigenvalue. A tube lattice (`lattice=`) is refused beside it: an antiresonant fibre's loss is its tubes' resonances, not a boundary condition at one radius. Two -polarisations, a noise model and a fused batch are refused too, each by name. +polarisations and a noise model are refused too, each by name. **Validity.** The condensation is quasi-static and paraxial. Three dimensionless ratios are computed for the highest retained mode over the band the run **scores** — the diff --git a/docs/guide/waveguides/coherent-wall.md b/docs/guide/waveguides/coherent-wall.md index 7fbb6bf50..cae9d60e5 100644 --- a/docs/guide/waveguides/coherent-wall.md +++ b/docs/guide/waveguides/coherent-wall.md @@ -71,9 +71,9 @@ it. The condensation is onto the *complete* set of $J_0$ radial orders, so the block needs the contiguous set $\mathrm{HE}_{11}$ to $\mathrm{HE}_{1N}$ — `modes=N` on the capillary route builds exactly that — sharing one polarisation angle, one capillary model and one -declared guide. A sparse set, a mixed family, two polarisations, the -`modified` noise model and a fused batch are refused by name, each at the layer that -owns the refusal. The `input` noise model is admitted +declared guide. A sparse set, a mixed family, two polarisations and the +`modified` noise model are refused by name, each at the layer that owns the +refusal. The `input` noise model is admitted ([SEP 37](../../dev/seps/archive/sep-0037-noise-and-stepper-defaults.md), section 6): its draw is part of the launch, one photon per channel and bin in the $\mathrm{HE}_{1m}$ set, which is orthonormal in true power (real Bessel profiles, orthogonal on the core, diff --git a/docs/guide/waveguides/general-modal.md b/docs/guide/waveguides/general-modal.md index 5be4ef104..5ff583fa8 100644 --- a/docs/guide/waveguides/general-modal.md +++ b/docs/guide/waveguides/general-modal.md @@ -27,8 +27,8 @@ in the last two sections of this page; read them before planning a run. In short runs on **a field grid, for a guide of constant geometry or a solid guide whose geometry moves along z**, on `numpy_ref` and the native backend (its CPU build and its CUDA and HIP device builds alike); a coupled flow runs on all of them too. A general -modal run writes, reads back and resumes an HDF5 file, a scan point writes one, and a -batch of launches on one guide runs in lockstep. A declared basis over a block that is +modal run writes, reads back and resumes an HDF5 file, and a scan point writes one. A +declared basis over a block that is only *nearly* degenerate propagates as a coupled matrix flow, and a guide whose geometry moves carries the connection of its moving basis, which couples its channels. [Declared, refused, recorded](#declared-refused-recorded) is the whole route on one @@ -328,21 +328,6 @@ provider's own coordinates carries no such entry; the two gauges are always comp they refuse a resume in the other direction. {meth}`~solprop.output.memory.MemoryOutput.to_file` and a scan point write the same file. -**A batch member may be a general modal run**, under a narrower admission rule than the -one for fibre runs ({doc}`../workflows/scans`) and alongside it: the members of a general-guide group -share the physical guide, the table, the gauge, the materials and one explicit fixed -schedule, and differ in their **launch and their noise seed** and in nothing else. What -separates two guides is `modal_tables.identity` — its three declared identities and its -extents — in the grouping signature, beside the metric's kind and gauge and the compiled -responses' model and policy; two strands of different radius share every *layout* entry -of the signature and are told apart by what they physically are. Because a descriptor is only -as good as what it names, a group assembled by hand is refused by name at the driver and -again at the backend: *general-guide batch requires identical guide/table/gauge -identity*. The source pass is unchanged by batching: the lockstep runner hands each -member its own singleton row, and a batched run is what its members are alone, to -rounding. A problem is always one trajectory, so there is no fused batch axis to -refuse. - The file stores channel amplitudes, not fields. {py:mod}`solprop.processing.modal` is the way back — given the run's own tables, rebuilt from the guide the record names, it synthesises $\mathbf E$ in V/m and $\mathbf H$ in A/m at the guide's nodes and forms @@ -382,12 +367,11 @@ at the translation layer and in the backend. across the band, and the real cubic on a grid with no room for its harmonic. * A nonunitary basis, or one acting outside a declared block; and beside a split block, the `modified` noise model (its kept-apart draw's transport through a coupled flow is - not measured; the `input` draw is part of the launch and is admitted), a lockstep batch - member (it applies neither half of the flow) and a block whose exponent exceeds - `MAX_GENERAL_FLOW_EXPONENT`. + not measured; the `input` draw is part of the launch and is admitted) and a block + whose exponent exceeds `MAX_GENERAL_FLOW_EXPONENT`. * Beside a guide whose geometry moves: a snapshot position other than the entrance, a - run longer than the declared path, the `modified` noise model, a lockstep batch, a - fixed schedule that straddles a kink, and no flow at all beside the moving maps + run longer than the declared path, the `modified` noise model, a fixed schedule that + straddles a kink, and no flow at all beside the moving maps ([a guide whose geometry moves along z](moving-modal.md#a-guide-whose-geometry-moves-along-z)). * The scalar-route power names, `quadrature_error` and — beside a split block — `zdw`: a statistic the basis does not define is refused with its replacement where it has one, @@ -446,8 +430,8 @@ CPU build and its CUDA and HIP device builds: * a **graded-index** guide as readily as a step-index one: any provider that solves its own E and H, with `GradedIndexProvider(core_responses=…)` declaring what its core responds with; -* a launch into a **named channel** or a declared **transverse field**, and a **batch** - of launches on one guide. +* a launch into a **named channel** or a declared **transverse field**, and a + [scan](../workflows/scans.md) of launches on one guide. The route admits one combination and no other: a **field** grid; an identity metric whose certified defect is inside the route's budget, or the dense metric of a declared diff --git a/docs/guide/waveguides/modal-bases.md b/docs/guide/waveguides/modal-bases.md index 592ee9726..58c80c97a 100644 --- a/docs/guide/waveguides/modal-bases.md +++ b/docs/guide/waveguides/modal-bases.md @@ -120,11 +120,8 @@ differently, and the same comparison reads 2e-2. **Where it runs, and what it refuses by name.** Every backend executes the leaf — `numpy_ref` and `native`, on the CPU and on a GPU. A **noise** model beside it is refused, because the shot-noise draw ({doc}`../media/noise`) is transported by the unitary phase of a *diagonal* flow and its -transport through a coupled one has not been measured. In a `Batch` group the reference -takes a coupled member's trial member by member, because its member-axis batch evaluates -its own stage arithmetic and applies neither the flow action nor its residual; a native -`Batch` group runs each member in its own native session, flow and all. And a block whose exponent over the largest declared -step exceeds `MAX_GENERAL_FLOW_EXPONENT` (1e3) is refused: the block carries every +transport through a coupled one has not been measured. And a block whose exponent over +the largest declared step exceeds `MAX_GENERAL_FLOW_EXPONENT` (1e3) is refused: the block carries every channel's departure from the reference, so a basis declared over channels that were never a degenerate group would put their whole dispersion difference into a matrix exponential taken by scaling and squaring. diff --git a/docs/guide/waveguides/moving-modal.md b/docs/guide/waveguides/moving-modal.md index e2bb4a242..edc40f944 100644 --- a/docs/guide/waveguides/moving-modal.md +++ b/docs/guide/waveguides/moving-modal.md @@ -238,9 +238,8 @@ evaluates one of each. **Refused, by name**: a snapshot position other than the entrance, `sections=` or `path_rtol=` beside a guide whose geometry does not move, an entrance rule the provider would not build again, a run longer than the declared path, the `modified` noise model -(the `input` draw is part of the launch and is admitted), the reference's lockstep -batch (a native `Batch` group runs each member in its own session), a fixed -schedule that straddles a kink, or no flow at all beside moving maps. Every backend executes the moving maps — `numpy_ref` and `native` on +(the `input` draw is part of the launch and is admitted), a fixed schedule that +straddles a kink, or no flow at all beside moving maps. Every backend executes the moving maps — `numpy_ref` and `native` on the CPU and on a GPU. A declared circular basis is honoured: the metric then stays the identity, the basis being unitary and the measured Gram departure unitarily invariant. diff --git a/docs/guide/waveguides/solid-fibres.md b/docs/guide/waveguides/solid-fibres.md index 81230d35b..ce13d8248 100644 --- a/docs/guide/waveguides/solid-fibres.md +++ b/docs/guide/waveguides/solid-fibres.md @@ -351,8 +351,8 @@ frozen-section flow. The model, its validation and its limits are in It runs on both backends, `numpy_ref` and `native` (CPU and GPU builds). A strong taper couples strongly: the run's advisory step warns when the steps are too long, and `sections=` shortens the frozen sections. Beside a moving guide the -`modified` noise model, a lockstep batch and a fixed schedule that straddles a kink of -the path are refused. The +`modified` noise model and a fixed schedule that straddles a kink of the path are +refused. The [tapered graded-index worked example](../../auto_examples/waveguides/plot_05_moving_solid_guide.rst) runs eight tapers from abrupt to adiabatic against a first-order coupled-mode estimate and Love's criterion, rebuilds the fields at the entrance and the waist, and puts a @@ -384,8 +384,8 @@ The ones a user meets first: for its harmonic; * the per-channel power statistics (`energy`, `peak_power`, ...), replaced by `physical_energy` and `analytic_flux` ([reading the output](../results/reading-output.md)); -* on a moving guide, the `modified` noise model, a lockstep batch or a fixed schedule that - straddles a kink (above). +* on a moving guide, the `modified` noise model or a fixed schedule that straddles a + kink (above). The incident-beam launch into a fibre and its coupling budget were proposed and carried out by [SEP 31](../../dev/seps/archive/sep-0031-simulation-coupling.md). diff --git a/docs/guide/waveguides/supplied-guides.md b/docs/guide/waveguides/supplied-guides.md index ac4b016f8..ae2b902d5 100644 --- a/docs/guide/waveguides/supplied-guides.md +++ b/docs/guide/waveguides/supplied-guides.md @@ -126,15 +126,7 @@ It **writes and resumes an HDF5 file**: the file carries the channel labels, the provider, sampling, table and metric identities and the accessors the basis admits, so a resume against a changed guide, table, material or channel order is refused by the field that moved ([output](../results/resuming.md#what-a-general-modal-runs-key-holds)). -A scan point writes one -too. A **batch** member may be a general modal run, under a narrower admission rule than -an ordinary fibre batch's ([scans and batches](../workflows/scans.md#fixed-schedule-batches)): the -members of a group share the guide, the table, the gauge, the materials and one explicit -fixed schedule, and differ in their launch and their noise seed alone. What separates two -guides is `modal_tables.identity` in the grouping signature, because every other entry -there describes an execution layout two guides share entirely; a group assembled outside -that grouping is refused by name, at the driver and again at the backend. A batched run -is what its members are alone, to rounding. +A scan point writes one too ([scans](../workflows/scans.md)). A reconstruction of E and H needs the **guide beside the file**: the reference arrays are not stored in it, so rebuild the tables from the guide and pass the diff --git a/docs/guide/workflows/interactive.md b/docs/guide/workflows/interactive.md index e84930b74..e6e28a044 100644 --- a/docs/guide/workflows/interactive.md +++ b/docs/guide/workflows/interactive.md @@ -89,7 +89,7 @@ the same object as in its home module: * - group - names * - runs - - ``prop_capillary``, ``prop_gnlse``, ``prop_waveguide``, ``prop_free``, ``prop_planar``, ``Simulation``, ``SimulationSettings``, ``Multistep``, ``RungeKutta``, ``Scan``, ``ScanPoint``, ``run_scan``, ``Local``, ``Pool``, ``Queue``, ``Slurm``, ``Batch`` + - ``prop_capillary``, ``prop_gnlse``, ``prop_waveguide``, ``prop_free``, ``prop_planar``, ``Simulation``, ``SimulationSettings``, ``Multistep``, ``RungeKutta``, ``Scan``, ``ScanPoint``, ``run_scan``, ``Local``, ``Pool``, ``Queue``, ``Slurm`` * - outputs - ``open_file``, ``resume``, ``MemoryOutput``, ``HDF5Output``, ``CallbackOutput``, ``open_scan``, ``ScanOutput`` * - building blocks diff --git a/docs/guide/workflows/scans.md b/docs/guide/workflows/scans.md index a4c10f045..fd0d03c50 100644 --- a/docs/guide/workflows/scans.md +++ b/docs/guide/workflows/scans.md @@ -3,9 +3,9 @@ A parameter scan runs the same simulation over a grid of inputs — pressures, energies, durations, seeds — and collects what each point produced into one HDF5 file. This page is for anyone who wants more than a handful of runs: it describes how a scan is declared, -how the points are built and executed (one after another, in parallel processes, in -lockstep batches, or spread over cluster jobs), what is kept of each point, and how the -collected file is read back. +how the points are built and executed (one after another, in parallel processes, or +spread over cluster jobs), what is kept of each point, and how the collected file is +read back. The workflow has four parts: @@ -40,13 +40,12 @@ The builder receives a `ScanPoint` and returns a `Simulation`. Variables use the builder's units: pressure at the user interface is in bar, energy in J, lengths in m and times in s. A builder can select any installed backend. -Five executors, all in `solprop.driver.executors`, run the points: +Four executors, all in `solprop.driver.executors`, run the points: | executor | what it does | |---|---| | `Local()` | runs the points one after another in the current process; the default | | `Pool(workers, threads=1, ...)` | runs independent points in parallel worker processes; the executor to use for independent CPU runs | -| `Batch(size)` | advances compatible fixed-schedule points in lockstep inside one backend | | `Queue(path)` | a durable queue on a shared filesystem, drained by one or more controllers | | `Slurm(script, ...)` | prepares a queue and submits a Slurm array job that drains it | @@ -147,94 +146,22 @@ constructor's pulse recipe from the metadata, because it no longer describes the the exact initial spectrum is still recorded. Two points with equal physical fields need not have equal configuration hashes when their construction provenance differs. -## Fixed-schedule batches +## Each point's window and record -`Batch(size)` advances up to `size` points in lockstep, on one fixed step schedule, inside -one backend. It runs on `numpy_ref` and `native` (CPU and GPU builds), and -each backend is tested to give a batch member the output the same point gives run alone, -to rounding: the same steps, with sums that may be ordered differently -([SEP 25](../../dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). On the -native builds each member of a batch runs in its own native execution session, stepping -natively between save planes, its coupled flow (a coherent wall, for instance) included. -On the reference a coupled-flow member takes its own trial, flow included, member by -member; its member-axis batch serves the other points. - -```{code-block} python -from solprop.driver.executors import Batch -from solprop.driver.scan import run_scan - -# The builder must return fibre simulations with an explicit fixed schedule. -# It selects its backend as usual. -result = run_scan( - scan, - build_fixed_point, - executor=Batch(4, memory_limit=8 * 1024**3), - output="fixed_scan.h5", - fields="planes", - field_planes=[-1], - stats="all", -) -``` - -Prepare the replay schedule with the `discover`, `calibrate` and `replay` workflow of -{mod}`solprop.stepper.schedule` ([fixed schedules](../numerics/fixed-schedules.md#fixed-schedules-discover-calibrate-replay)) -and validate its transfer to the individual scan points before interpreting their -physics. A batch executor does not silently convert an adaptive simulation into a fixed -one, and it runs modal (fibre and capillary) propagation only, not radial, Cartesian or -planar grids. Adjacent points with matching grids, schedules, response layouts and -statistics can share a group; layout changes and the final partial batch make smaller -groups. Mixing backend names in a batch scan raises an error. Global point indices are -unchanged. General modal runs may be batched under a narrower rule -([running](../waveguides/supplied-guides.md#a-guide-instead-of-a-fill)). A member's field -crosses to the host only at a plane the scan reads, as for a point run alone: under -`fields="none"`, with reductions of statistics, none does. - -Each member watches its own time window, as the point would run alone +Each point watches its own time window, as it would run alone ([watching the window's edges](../numerics/boundaries.md#watching-the-windows-edges)): a point whose light reaches an edge is stopped and recorded as failed with its -`BoundaryError`, and the other members of its batch go on. Under an `"error"` warnings -filter a `BoundaryWarning` fails its own point in the same way, and only that point. +`BoundaryError`, and the other points go on. Under an `"error"` warnings filter a +`BoundaryWarning` fails its own point in the same way, and only that point. Every executor keeps each watched point's closing monitor record, done or failed, without its per-plane rows: `read_point(path, index)["boundary_monitor"]`. It is the record a run of the point alone would close with (the removed fraction, the guard maxima, where the run stopped), and the scan's schema is unchanged by it. -Memory admission probes the selected backend and keeps 20 % host headroom. It -records baseline and probe RSS, workspace and output estimates, shared table -bytes already included in the baseline, and the admitted group size. An explicit -`memory_limit` (bytes) further restricts the physical or scheduler allocation. This is an -admission estimate, not an operating-system memory limit; the builder itself must -fit while constructing up to `size` translated points. A budget that cannot fit -one member is refused. Device backends report free memory through the same interface: -admission probes each member, uses its complete ledger as a conservative upper bound on -device storage, and restricts the group before constructing all members. Allocator -reserves are excluded from free space. The recorded device bound may include host -buffers, so it can admit fewer members than a device-only ledger would. - -Each point records its actual batch size, execution strategy and resolved backend -policies. `native` fuses the accepted update across members, and -combines the error partials of all members in the same native kernel, while each member -keeps its own workspace; the response kernels and the FFT and BLAS plans stay per member. This partial fusion does not amortise the whole GPU launch -sequence. - -**What batching buys.** On the CPU, batching gives no speedup over running the points -one after another, so use `Pool` there. On a data-centre GPU, a native `Batch(8)` of -eight points of a shortened multimode resonant-dispersive-wave capillary on a fixed -515-step schedule gave about 1.1 times the throughput of `Local`, setup and output -included. That measures one shape on one schedule and does not predict others. For -comparison, on an 18-core x86-64 server a `Pool` of 8 to 18 one-thread workers gave -about four times the throughput of `Local` on a shortened six-mode hydrogen-filled -capillary, and one worker using all 36 hardware threads was slower than those pools. -Size workers within the actual CPU and memory allocation, and measure the workload that -matters to you; [performance tuning](../performance/tuning.md) explains the thread -settings of scan workers. - -Fields keep the single-run saved-plane shape. Error histories, noise, species axes -and periodic statistics remain separate per member. Reductions use the same -processing definitions and temporary disk spool as `Local` and `Pool`. Completed -points are revalidated as on the other routes before being skipped (below), so changing -executor does not change what a point records. +Fields keep the single-run saved-plane shape, and error histories, noise, species axes +and periodic statistics stay each point's own. Completed points are revalidated before +being skipped (below), so changing executor does not change what a point records. ## Processes and resource limits @@ -257,6 +184,14 @@ limit file that cannot be read, or a malformed `SOLPROP_SCAN_CPU_OFFSET` or This is admission control, not an operating-system memory limit; adaptive periodic statistics and custom reducer working memory can exceed the probe estimate. +**What a pool buys.** On an 18-core x86-64 server a `Pool` of 8 to 18 one-thread +workers gave about four times the throughput of `Local` on a shortened six-mode +hydrogen-filled capillary, and one worker using all 36 hardware threads was slower than +those pools. That measures one shape and does not predict others: size workers within +the actual CPU and memory allocation, and measure the workload that matters to you; +[performance tuning](../performance/tuning.md) explains the thread settings of scan +workers. + Pool builders and custom reducers must be pickleable, importable module-level callables. Keep entry-point execution under `if __name__ == "__main__"`. Nested functions, lambdas and live backend handles cannot be dispatched. Validation happens @@ -321,7 +256,7 @@ What an executor reports differs, because the points run in different places: |---|---|---| | `Local` | when the point is built, in this process | every call, `step` included, in this process | | `Pool` | when the point is sent to a worker | `summary`, `started`, `plane`, `finished` and `interrupted`, sent by the worker on its pipe and made in the controller as they arrive; each plane carries its position and the four scalars of its summary, never a field, and `step`, on the hot path, is not sent | -| `Batch`, `Queue`, `Slurm` | when the point's result is collected, just before `point_finished` | none | +| `Queue`, `Slurm` | when the point's result is collected, just before `point_finished` | none | All the calls are made in the process and thread that called `run_scan`. @@ -334,7 +269,6 @@ running stops as its executor allows: |---|---| | `Local` | the point in flight polls the flag as `Simulation.run(stop=...)` does: before every trial step, or on a native `Multistep()` march each time a native call returns, so it stops within one step or [that call's bound](../results/resuming.md#stopping-a-run) | | `Pool` | the controller sends each busy worker a stop message on its pipe, which that worker's run polls in the same way; it then collects the workers' results and shuts them down. Terminating a worker that does not exit remains the last resort | -| `Batch` | between groups: a group that has started runs to its end, and the claimed points of a group not yet run are given back | | `Queue`, `Slurm` | refused, with an error naming the queue's own tools: the points run in other processes or on other machines, which a flag in this process cannot reach. Use `scancel` for a Slurm job, or stop a queue's controllers with SIGTERM | A stopped point is not committed: the file holds the points finished before the stop, diff --git a/native/AGENTS.md b/native/AGENTS.md index aa858f4a1..174a5f37c 100644 --- a/native/AGENTS.md +++ b/native/AGENTS.md @@ -199,7 +199,10 @@ the gate. Never call Python from a Kokkos or OpenMP worker, or during teardown. - Public Python has complete annotations, NumPy-style docstrings, `__all__`, `py.typed` and a complete stub for the private extension; its bound problem's part is generated - (`scripts/problem_stub.py`, checked in the lint stage). Install a `NullHandler`; never + (`scripts/problem_stub.py`, checked in the lint stage). An entry point only solprop's + tests reach goes in the extension's private `_testing` submodule (solprop SEP 52), + which ships in the wheel and promises nothing; its stub, `_core_testing.pyi`, is + held to the module's names by the same check. Install a `NullHandler`; never configure the root logger or print diagnostics from library code. - Thread settings are read once, at import. Never change process thread settings (or a BLAS thread pool) after import. diff --git a/native/ci/smoke.py b/native/ci/smoke.py index f141c3ab4..9847c0372 100644 --- a/native/ci/smoke.py +++ b/native/ci/smoke.py @@ -14,8 +14,9 @@ loaded (FFT, BLAS, OpenMP) are the copies inside the installed wheel, not ones from the build machine or the system, and that the wheel neither carries nor imports a single-precision FFTW. On Arm it checks that the bundled FFTW carries the NEON codelets. -It then runs ``python -m solprop_native`` and checks -that the build record it prints is JSON. +It runs one check of the private test module the wheel ships (``_core._testing``, +solprop SEP 52): the vector-maths layer's exponential against NumPy's. It then runs +``python -m solprop_native`` and checks that the build record it prints is JSON. """ from __future__ import annotations @@ -28,7 +29,10 @@ import sys from pathlib import Path +import numpy as np + import solprop_native +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] def bundled(library: str, package: Path) -> bool: @@ -130,6 +134,13 @@ def main() -> None: required.add("LICENSE-libomp.txt or LICENSE-libgomp.txt") if missing := sorted(required - licences): sys.exit(f"the wheel lacks {', '.join(missing)}") + # The test module ships in the wheel; its exponential is held to one ulp (u10) by + # solprop's tests, and to a few here against NumPy's, whose libm adds its own. + x = np.linspace(-700.0, 700.0, 1001) + out = np.empty_like(x) + _testing.vector_exp(x, out) + if not np.allclose(out, np.exp(x), rtol=8 * np.finfo(np.float64).eps, atol=0.0): + sys.exit("the test module's vector_exp disagrees with NumPy's exponential") record = subprocess.run( [sys.executable, "-I", "-m", "solprop_native"], diff --git a/native/include/solprop_native/dense.hpp b/native/include/solprop_native/dense.hpp index 6242f1280..1a4b8d3a3 100644 --- a/native/include/solprop_native/dense.hpp +++ b/native/include/solprop_native/dense.hpp @@ -17,7 +17,7 @@ * * The implementations (`engines::AdamsDense`, `engines::RungeKuttaDense`, * dense_output.hpp) are solprop's own observations transcribed: the Adams march's - * interpolant over the last accepted step (`_ResidentAdams.observe`), and DOPRI5's + * interpolant over the last accepted step (`HostHistory.observe`), and DOPRI5's * continuous extension of Hairer, Norsett and Wanner II.6 carried to the plane by the * linear flow (`HostDriver._observe_inside`). * diff --git a/native/include/solprop_native/dense_output.hpp b/native/include/solprop_native/dense_output.hpp index 381e0a6f6..f796464d0 100644 --- a/native/include/solprop_native/dense_output.hpp +++ b/native/include/solprop_native/dense_output.hpp @@ -32,7 +32,7 @@ namespace solprop_native::dense { /** An observation's fraction of its step, `(position - z) / dz`. */ [[nodiscard]] double fraction(double position, double z, double dz); /** The interaction formulation's interpolant weights over `count` nodes `(1, - theta...)` at the fraction `theta` of a step `dz` (`_ResidentAdams.observe`): the + theta...)` at the fraction `theta` of a step `dz` (`HostHistory.observe`): the corrector's, `dz` times the integrated weights from 0 to `theta`, in the binding's slots. */ [[nodiscard]] AdamsWeights fused_weights(const double* nodes, std::size_t count, @@ -51,8 +51,8 @@ namespace solprop_native::dense { namespace solprop_native::engines { -/** The Adams march's dense output (solprop's `_ResidentAdams.march_stepped`, `observe`, - `hold` and `restore`): the interaction formulation's corrector interpolant, or the +/** The Adams march's dense output (solprop's `HostHistory.observe`, `hold` and + `restore`): the interaction formulation's corrector interpolant, or the exponential formulation's corrector with its compensation and carrier frame, over the last accepted step the engine kept. */ class AdamsDense final : public session::Dense { diff --git a/native/include/solprop_native/engines.hpp b/native/include/solprop_native/engines.hpp index 6e626e3ae..97a9743e9 100644 --- a/native/include/solprop_native/engines.hpp +++ b/native/include/solprop_native/engines.hpp @@ -52,7 +52,7 @@ void carrier_frame(ExponentialWeights& weights, const std::vector& value std::size_t rows); /** The resident engine: the general state's startup, exponential trial and accept, - with the stage tables of phase 1 (solprop's `_ResidentAdams`). */ + with the stage tables of phase 1 (solprop's `HostHistory`). */ class ResidentEngine final : public march::Engine { public: ResidentEngine(GeneralState& state, const stage::Tables& tables, diff --git a/native/pyproject.toml b/native/pyproject.toml index cc632fa2e..836e662b9 100644 --- a/native/pyproject.toml +++ b/native/pyproject.toml @@ -4,7 +4,10 @@ [build-system] requires = [ - "nanobind>=2.9", + # Pinned: the binding's code and its stub's generated part follow one nanobind release, + # and an isolated wheel build would otherwise take whatever release is newest. The dev + # group pins the same version for the editable build (solprop SEP 52). + "nanobind==3.1.0", # The distribution profile's Linux and Windows BLAS, copied into the wheel; never a runtime # dependency. Other builds ignore it. "scipy-openblas32>=0.3.34; sys_platform == 'linux' or sys_platform == 'win32'", diff --git a/native/scripts/check.sh b/native/scripts/check.sh index c5fa4924d..2a731ad0b 100755 --- a/native/scripts/check.sh +++ b/native/scripts/check.sh @@ -168,7 +168,7 @@ subprocess.run([sys.executable, "-I", "-m", "solprop_native"], check=True, captu # solprop #135: the strict files' probes round separately in the wheel, beside a control # that fuses (the x86-64-v2 variant, for processors without FMA, cannot fuse). from solprop_native import _core -control, *probes = _core.strict_witness(1.0 + 2.0**-30, 1.0 - 2.0**-30, -1.0) +control, *probes = _core._testing.strict_witness(1.0 + 2.0**-30, 1.0 - 2.0**-30, -1.0) assert probes == [0.0] * 9, probes assert control == -(2.0**-60) or info.cpu_baseline == "x86-64-v2", (control, info.cpu_baseline) PY diff --git a/native/scripts/problem_stub.py b/native/scripts/problem_stub.py index 64db04083..ed7bf855d 100644 --- a/native/scripts/problem_stub.py +++ b/native/scripts/problem_stub.py @@ -9,11 +9,17 @@ the setter's type as a plain attribute, so the stub stays short and strict pyright accepts the adapter's assignments, and replaces the text between the stub's markers. ``--check`` exits 1 instead when the committed stub differs (the native lint stage). + +The private test module ``_core._testing`` (solprop SEP 52) has a hand-written stub, +``_core_testing.pyi``, whose records stubgen would type only as bare ``dict``; +``--check`` also holds its names, and each class's members, to the built module's. """ +import ast import re import subprocess import sys +from collections.abc import Iterable from pathlib import Path from nanobind.stubgen import StubGen @@ -21,6 +27,7 @@ import solprop_native._core as core STUB = Path(__file__).resolve().parents[1] / "src/solprop_native/_core.pyi" +TESTING_STUB = STUB.with_name("_core_testing.pyi") BEGIN = ( "# Generated by native/scripts/problem_stub.py from nanobind.stubgen.\n" "# Array fields are copied in and out: assign a whole array, since an item\n" @@ -53,6 +60,37 @@ def generated() -> str: return BEGIN + formatted + END +def _public(names: Iterable[str]) -> set[str]: + """Return the names that do not start with an underscore, and ``__init__``.""" + return {name for name in names if not name.startswith("_") or name == "__init__"} + + +def testing_drift() -> list[str]: + """Return how ``_core_testing.pyi``'s names differ from ``_core._testing``'s.""" + tree = ast.parse(TESTING_STUB.read_text(encoding="utf-8")) + stub: dict[str, set[str] | None] = {} + for node in tree.body: + if isinstance(node, ast.FunctionDef): + stub[node.name] = None + elif isinstance(node, ast.ClassDef): + stub[node.name] = { + item.name for item in node.body if isinstance(item, ast.FunctionDef) + } + module = core._testing # pyright: ignore[reportPrivateUsage] + drift = [ + f"{name}: {'not in the stub' if name not in stub else 'not in the module'}" + for name in sorted(_public(dir(module)) ^ set(stub)) + ] + for name, members in stub.items(): + bound = getattr(module, name, None) + if members is not None and isinstance(bound, type): + drift.extend( + f"{name}.{member}: differs between the stub and the module" + for member in sorted(_public(vars(bound)) ^ members) + ) + return drift + + def main(argv: list[str]) -> int: """Rewrite the section, or with ``--check`` report whether it is stale.""" text = STUB.read_text(encoding="utf-8") @@ -61,6 +99,9 @@ def main(argv: list[str]) -> int: end = text.index(END, start) + len(END) head, current, tail = text[:start], text[start:end], text[end:] fresh = generated() + if drift := testing_drift(): + print(f"{TESTING_STUB.name} disagrees with _core._testing:", *drift, sep="\n ") + return 1 if "--check" in argv: if current != fresh: print(f"{STUB.name} is stale: run native/scripts/problem_stub.py") diff --git a/native/src/bindings.cpp b/native/src/bindings.cpp index 11df513d5..9f55010aa 100644 --- a/native/src/bindings.cpp +++ b/native/src/bindings.cpp @@ -1836,13 +1836,6 @@ class BoundState { } return general_state_->trial_step(dz, scalars); } - void set_flow_actions(const std::vector& forward, - const std::vector& inverse, - const std::vector& identity) { - require_open(); - flow_key_.reset(); - general_state_->set_flow_actions(forward, inverse, identity); - } std::vector flow_actions_to_host(const bool inverse) { require_open(); return general_state_->flow_actions_to_host(inverse); @@ -3198,24 +3191,15 @@ nb::dict build_record() { return result; } -} // namespace - -// NOLINTNEXTLINE(readability-function-size): the module's one table of bindings, kept whole -NB_MODULE(_core, module_) { - // Each registration makes the Python exception type; the handle need not outlive it. - const nb::exception envelope_convergence_error( - module_, "EnvelopeConvergenceError"); - const nb::exception backend_refusal(module_, - "BackendRefusal"); - module_.doc() = "Private nanobind seam for solprop-native"; - module_.def("initialize_runtime", &initialize_kokkos, "threads"_a, "kernels"_a = 0, - "fft"_a = 0, "raman_fft"_a = 0, "raman_tail_fft"_a = 0, - "band_tiles"_a = -1); - module_.def("fit_blas_threads", &fit_blas_threads, "threads"_a); - module_.def("register_host_blas", ®ister_host_blas); +// The private `_testing` module (solprop SEP 52 section 6.5): every entry point that +// only solprop's own tests reach, built into the same extension and shipped in the +// wheel. It promises nothing. A `State` method that moved here takes the state as its +// first argument. +// NOLINTNEXTLINE(readability-function-size): the test module's one table of bindings +void bind_testing(nb::module_& testing) { // solprop SEP 45 phase 1: the boundary watch's predictions, for solprop's tests to // hold against its monitor on drawn readings. - module_.def( + testing.def( "watch_check", [](const nb::dict policy, const nb::dict state, const RealInput reading, const double z) { @@ -3233,16 +3217,8 @@ NB_MODULE(_core, module_) { return out; }, "policy"_a, "state"_a, "reading"_a, "z"_a); - module_.def( - "rk_score", - [](const RealInput partials, const double rtol, const double atol) { - if (partials.ndim() != 2 || partials.shape(0) != 3) - throw std::invalid_argument("a trial's partials have shape (3, slots)"); - return native::rk::score(partials.data(), partials.shape(1), rtol, atol); - }, - "partials"_a, "rtol"_a, "atol"_a); // solprop SEP 47: the native half-maximum width the statistics plan finishes with. - module_.def( + testing.def( "half_width", [](const RealInput t, const RealInput power, const bool outer) { if (t.ndim() != 1 || power.ndim() != 1 || t.shape(0) != power.shape(0)) @@ -3255,7 +3231,7 @@ NB_MODULE(_core, module_) { // solprop #135: the strict files' probes as the built library holds them, beside a // control compiled with this file's contraction. Where the control fuses, a probe // that also fused has lost its file's rule, through inlining or the build's flags. - module_.def( + testing.def( "strict_witness", [](const double a, const double b, const double c) { const double product = a * b; @@ -3274,7 +3250,7 @@ NB_MODULE(_core, module_) { // solprop SEP 47: the fluence widths' native finishing on given profiles, for the // tests that hold it to solprop's own (`solprop.spatial.radial_fluence_widths`, // `_line_fluence_widths`). - module_.def( + testing.def( "radial_fluence_widths", [](const RealInput radius, const RealInput fluence, const RealInput weights, const double axis_fluence, const double e2_fraction) { @@ -3289,7 +3265,7 @@ NB_MODULE(_core, module_) { }, "radius"_a.noconvert(), "fluence"_a.noconvert(), "weights"_a.noconvert(), "axis_fluence"_a, "e2_fraction"_a); - module_.def( + testing.def( "fluence_block_widths", [](const BoundStatisticsPlan& plan, const RealInput block) { if (block.ndim() != 1) @@ -3299,7 +3275,7 @@ NB_MODULE(_core, module_) { return nb::make_tuple(widths[0], widths[1], widths[2]); }, "plan"_a, "block"_a.noconvert()); - module_.def( + testing.def( "line_fluence_widths", [](const RealInput x, const RealInput samples, const double e2_fraction) { if (x.ndim() != 1 || samples.ndim() != 1 || samples.shape(0) != x.shape(0) || @@ -3311,14 +3287,14 @@ NB_MODULE(_core, module_) { return nb::make_tuple(widths[0], widths[1], widths[2]); }, "x"_a.noconvert(), "samples"_a.noconvert(), "e2_fraction"_a); - module_.def( + testing.def( "watch_due", [](const nb::dict policy, const nb::dict state, const double z) { return native::watch::due(watch_policy_from(policy), watch_state_from(state), z); }, "policy"_a, "state"_a, "z"_a); - module_.def( + testing.def( "watch_split_limit", [](const nb::dict policy, const RealInput occupancy) { const auto rules = watch_policy_from(policy); @@ -3328,6 +3304,605 @@ NB_MODULE(_core, module_) { return native::watch::split_limit(rules, values.data()); }, "policy"_a, "occupancy"_a); + // solprop SEP 28 section 4.2's reference parts, for its benchmarks only. + testing.def( + "reference_fft3_pairs", + [](const ComplexInput& values, const std::size_t warm, const std::size_t pairs) { + if (values.ndim() != 3) + throw std::invalid_argument("the reference volume must be three-dimensional"); + return native::reference_fft3_pairs(values.data(), values.shape(0), + values.shape(1), values.shape(2), warm, + pairs); + }, + "values"_a, "warm"_a, "pairs"_a); + // The calling thread's OpenMP default as a native call sees it (solprop issue #130). + testing.def("scoped_openmp_default", &native::scoped_openmp_default); +#if !defined(KOKKOS_ENABLE_CUDA) && !defined(KOKKOS_ENABLE_HIP) + // solprop SEP 46: forget FFTW's process-wide wisdom, for a test of the planning + // transaction. + testing.def("forget_fftw_wisdom", [] { + fftw_init_threads(); + fftw_forget_wisdom(); + }); +#else + testing.def("forget_fftw_wisdom", [] {}); +#endif + testing.def("scoped_block_time", &native::scoped_block_time); + testing.def( + "import_fftw_wisdom", + [](const std::string& text) -> bool { +#if defined(KOKKOS_ENABLE_CUDA) || defined(KOKKOS_ENABLE_HIP) + static_cast(text); + return false; +#else + return native::import_fftw_wisdom(text); +#endif + }, + "text"_a); + nb::class_(testing, "ScriptedMarch") + .def(nb::init(), "policy"_a, + "norms"_a.noconvert(), "carrier_rate"_a, "steps"_a.noconvert(), + "edges"_a.noconvert()) + .def("run", &ScriptedMarch::run, "state"_a, "bounds"_a) + .def("log", &ScriptedMarch::log); + nb::class_(testing, "ScriptedRkMarch") + .def(nb::init(), "policy"_a, + "norms"_a.noconvert(), "h0"_a, "steps"_a.noconvert(), "edges"_a.noconvert()) + .def("run", &ScriptedRkMarch::run, "state"_a, "bounds"_a) + .def("log", &ScriptedRkMarch::log) + .def("used", &ScriptedRkMarch::used); + // solprop SEP 47 section 6.4: the owning boundary monitor alone, for solprop's tests + // to feed recorded readings through it and its own monitor alike. + nb::class_(testing, "Monitor") + .def( + "__init__", + [](native::watch::Monitor* self, const nb::dict config) { + new (self) native::watch::Monitor(watch_config_from(config)); + }, + "config"_a) + .def( + "resume", + [](native::watch::Monitor& self, const nb::dict record, const bool plane, + const nb::handle unwatched) { + self.resume(watch_resumption_from(record), plane, + watch_stretches_from(unwatched)); + }, + "record"_a, "plane"_a, "unwatched"_a) + .def( + "launch", + [](native::watch::Monitor& self, const RealInput reading, const double z, + const double floor, const std::optional& floor_regions) { + const auto values = real_vector(reading); + std::vector regions; + if (floor_regions) { + regions = real_vector(*floor_regions); + if (regions.size() != 4) + throw std::invalid_argument("the floor's regions are four"); + } + return watch_judgement_to( + self.launch(values.data(), values.size(), z, floor, + floor_regions ? regions.data() : nullptr)); + }, + "reading"_a, "z"_a, "floor"_a = 0.0, "floor_regions"_a.none() = nb::none()) + .def("due", &native::watch::Monitor::due, "z"_a) + .def("skip", &native::watch::Monitor::skip, "z"_a) + .def( + "step", + [](native::watch::Monitor& self, const RealInput reading, const double z, + const bool plane) { + const auto values = real_vector(reading); + return watch_judgement_to( + self.step(values.data(), values.size(), z, plane)); + }, + "reading"_a, "z"_a, "plane"_a = false) + .def("plane", &native::watch::Monitor::plane, "z"_a) + .def("note_collar", &native::watch::Monitor::note_collar, "left_out"_a) + .def("finish", + [](const native::watch::Monitor& self) { + const auto finish = self.finish(); + nb::dict out; + out["removed"] = finish.removed; + out["guard_low_max"] = finish.guard_max[0]; + out["guard_high_max"] = finish.guard_max[1]; + out["warns"] = finish.warns; + return out; + }) + .def("record", + [](const native::watch::Monitor& self) { + return watch_record_to(self.record()); + }) + .def("watch_state", + [](const native::watch::Monitor& self) { + return watch_state_to(self.state()); + }) + .def_prop_ro("stale", &native::watch::Monitor::stale) + .def_prop_ro("collar_quiet", &native::watch::Monitor::quiet) + .def_prop_ro("step_cap", &native::watch::Monitor::cap) + .def_prop_ro("rests", &native::watch::Monitor::rests) + .def("steps_to_check", &native::watch::Monitor::steps_to_check); + testing.def( + "trial_step", + [](BoundState& self, const double dz, const RealInput phi_delta, + const RealInput phi_at, const RealInput prefactor, const RealInput density, + const RealInput taper, const RealInput preionisation, + const RealInput raman_rates, const nb::object material, + const bool prepare_only) { + if (self.raman() && + (raman_rates.ndim() != 2 || raman_rates.shape(0) != self.stages() || + raman_rates.shape(1) != self.raman_terms())) + throw std::invalid_argument( + "raman_rates must have shape (n_stages, n_terms)"); + auto scalars = trial_from(phi_delta, phi_at, prefactor, density, taper, + preionisation, raman_rates); + if (!material.is_none()) { + const auto values = nb::cast(material); + scalars.kerr_density = + real_vector(exact_array(values["kerr_density"])); + scalars.plasma_densities = + real_vector(exact_array(values["plasma_densities"])); + scalars.plasma_preionisation = + real_vector(exact_array(values["plasma_preionisation"])); + scalars.raman_densities = + real_vector(exact_array(values["raman_densities"])); + if (values.contains("flow_section")) { + scalars.flow_section = nb::cast(values["flow_section"]); + scalars.flow_weights = + real_vector(exact_array(values["flow_weights"])); + } + if (values.contains("transform_weights")) + scalars.transform_weights = + real_vector(exact_array(values["transform_weights"])); + if (values.contains("dispersive_densities")) + scalars.dispersive_densities = + real_vector(exact_array(values["dispersive_densities"])); + } + std::vector partials; + { + const nb::gil_scoped_release release; + partials = self.trial_step(dz, scalars, prepare_only); + } + return real_output(std::move(partials), 3); + }, + "state"_a, "dz"_a, "phi_delta"_a.noconvert(), "phi_at"_a.noconvert(), + "prefactor"_a.noconvert(), "density"_a.noconvert(), "taper"_a.noconvert(), + "preionisation"_a.noconvert(), "raman_rates"_a.noconvert(), + "material"_a = nb::none(), "prepare_only"_a = false); + testing.def( + "adopt", + [](BoundState& self, const ComplexInput field, const double dz) { + const auto held = complex_vector(field); + const nb::gil_scoped_release release; + self.adopt(held, dz); + }, + "state"_a, "field"_a.noconvert(), "dz"_a); + testing.def( + "stage_to_host", + [](BoundState& self, const std::size_t stage) { + const auto count = self.elements(); + auto storage = native::crossing::host_buffer(2 * count); + { + const nb::gil_scoped_release release; + self.stage_to_host( + stage, {reinterpret_cast(storage.get()), count}); + } + return complex_buffer_output(std::move(storage), + {self.columns(), count / self.columns()}); + }, + "state"_a, "stage"_a); + testing.def( + "projected_to_host", + [](BoundState& self, const bool coarse) { + std::vector values; + { + const nb::gil_scoped_release release; + values = self.projected_to_host(coarse); + } + return complex_output(values, {self.columns(), values.size() / self.columns()}); + }, + "state"_a, "coarse"_a = false); + testing.def( + "weighted_error", + [](BoundState& self, const RealInput scale) { + std::vector partials; + const auto held_scale = real_vector(scale); + { + const nb::gil_scoped_release release; + partials = self.weighted_error(held_scale); + } + return real_output(std::move(partials), 1); + }, + "state"_a, "scale"_a.noconvert()); + testing.def( + "form_flow_actions", + [](BoundState& self, const std::size_t section, const double dz, + const RealInput fractions) { + const auto held_fractions = real_vector(fractions); + std::vector measured; + { + const nb::gil_scoped_release release; + measured = self.form_flow_actions(section, dz, held_fractions); + } + return real_output(std::move(measured), 1); + }, + "state"_a, "section"_a, "dz"_a, "fractions"_a.noconvert()); + testing.def( + "flow_actions_to_host", + [](BoundState& self, const bool inverse) { + std::vector values; + { + const nb::gil_scoped_release release; + values = self.flow_actions_to_host(inverse); + } + return complex_output(values, {values.size()}); + }, + "state"_a, "inverse"_a); + // solprop SEP 47 phase 4: the last exponential Adams trial's coupled block and + // exponent, observations for tests. + testing.def( + "adams_block_to_host", + [](BoundState& self) { + std::vector values; + { + const nb::gil_scoped_release release; + values = self.adams_block_to_host(); + } + return complex_output(values, {values.size()}); + }, + "state"_a); + testing.def( + "adams_exponent_to_host", + [](BoundState& self) { + std::vector values; + { + const nb::gil_scoped_release release; + values = self.adams_exponent_to_host(); + } + return complex_output(values, {values.size()}); + }, + "state"_a); + testing.def( + "adams_exponential_trial", + [](BoundState& self, const double dz, const IndexInput slots, + const RealInput predictor, const RealInput corrector, const RealInput rows, + const RealInput divisor, const RealInput phi_delta, const RealInput phi_at, + const RealInput prefactor, const RealInput density, const RealInput taper, + const RealInput preionisation, const RealInput raman_rates, + const nb::dict material, const RealInput sample_phi_delta, + const RealInput sample_phi_at, const RealInput sample_prefactor, + const RealInput sample_density, const RealInput sample_taper, + const RealInput sample_preionisation, const RealInput sample_raman_rates, + const nb::dict sample_material, const RealInput spans, + const RealInput comp_predictor, const RealInput comp_corrector, + const RealInput comp_rows, const RealInput rate, const RealInput carrier) { + auto weights = exponential_weights(slots, predictor, corrector, rows); + carrier_frame(weights, carrier, weights.width - 1); + const auto rate_weights = real_vector(rate); + // A varying operator's compensation tables (solprop's + // backends.multistep.compensation_tables); empty for a constant one. + weights.compensated = !rate_weights.empty(); + if (weights.compensated) { + const auto span_values = real_vector(spans); + const auto predictor_values = real_vector(comp_predictor); + const auto corrector_values = real_vector(comp_corrector); + const auto row_values = real_vector(comp_rows); + if (span_values.size() + 1 != weights.width || + predictor_values.size() != weights.order || + corrector_values.size() != weights.order + 1 || + row_values.size() != weights.n_rows * weights.width) + throw std::invalid_argument( + "Adams compensation tables have inconsistent extents"); + for (std::size_t t = 0; t < span_values.size(); ++t) + weights.span[t] = span_values[t]; + for (std::size_t t = 0; t < predictor_values.size(); ++t) + weights.comp_predictor[t] = predictor_values[t]; + for (std::size_t t = 0; t < corrector_values.size(); ++t) + weights.comp_corrector[t] = corrector_values[t]; + for (std::size_t row = 0; row < weights.n_rows; ++row) + for (std::size_t t = 0; t < weights.width; ++t) + weights.comp_rows[row][t] = row_values[row * weights.width + t]; + } + const auto scale = real_vector(divisor); + const auto step = adams_scalars(phi_delta, phi_at, prefactor, density, taper, + preionisation, raman_rates, material); + const auto sample = adams_scalars( + sample_phi_delta, sample_phi_at, sample_prefactor, sample_density, + sample_taper, sample_preionisation, sample_raman_rates, sample_material); + std::vector norms; + { + const nb::gil_scoped_release release; + norms = self.open_state().adams_exponential_trial(dz, weights, scale, step, + sample, rate_weights); + } + return real_output(std::move(norms), 1); + }, + "state"_a, "dz"_a, "slots"_a.noconvert(), "predictor"_a.noconvert(), + "corrector"_a.noconvert(), "rows"_a.noconvert(), "divisor"_a.noconvert(), + "phi_delta"_a.noconvert(), "phi_at"_a.noconvert(), "prefactor"_a.noconvert(), + "density"_a.noconvert(), "taper"_a.noconvert(), "preionisation"_a.noconvert(), + "raman_rates"_a.noconvert(), "material"_a, "sample_phi_delta"_a.noconvert(), + "sample_phi_at"_a.noconvert(), "sample_prefactor"_a.noconvert(), + "sample_density"_a.noconvert(), "sample_taper"_a.noconvert(), + "sample_preionisation"_a.noconvert(), "sample_raman_rates"_a.noconvert(), + "sample_material"_a, "spans"_a.noconvert(), "comp_predictor"_a.noconvert(), + "comp_corrector"_a.noconvert(), "comp_rows"_a.noconvert(), "rate"_a.noconvert(), + "carrier"_a.noconvert()); + testing.def( + "adams_exponential_trial_at", + [](BoundState& self, const double z, const double dz, const RealInput nodes, + const IndexInput slots, const std::size_t order, + const std::vector& orders, const bool compensated, + const RealInput carrier) { + auto weights = exponential_weights_at(nodes, slots, order, orders, compensated); + carrier_frame(weights, carrier, weights.width - 1); + const double end = z + dz; + auto trial = self.stage_trial(z, end); + const auto rate = compensated ? self.stage_rate(end) : std::vector{}; + std::vector norms; + { + const nb::gil_scoped_release release; + norms = self.open_state().adams_exponential_trial(dz, weights, {}, trial.step, + trial.sample, rate); + } + return real_output(std::move(norms), 1); + }, + "state"_a, "z"_a, "dz"_a, "nodes"_a.noconvert(), "slots"_a.noconvert(), "order"_a, + "orders"_a, "compensated"_a, "carrier"_a.noconvert()); + testing.def( + "adams_exponential_accept", + [](BoundState& self, const double dz, const std::size_t free, + const IndexInput dense, const bool interpolate) { + auto slopes = adams_rows(dense); + slopes.width = interpolate ? slopes.width + 1 : 0; + const nb::gil_scoped_release release; + self.open_state().adams_exponential_accept(dz, free, slopes); + }, + "state"_a, "dz"_a, "free"_a, "dense"_a.noconvert(), "interpolate"_a); + testing.def( + "adams_start", + [](BoundState& self, const std::size_t slot, const RealInput phi_delta, + const RealInput phi_at, const RealInput prefactor, const RealInput density, + const RealInput taper, const RealInput preionisation, + const RealInput raman_rates, const nb::dict material) { + const auto scalars = adams_scalars(phi_delta, phi_at, prefactor, density, taper, + preionisation, raman_rates, material); + const nb::gil_scoped_release release; + self.open_state().adams_start(slot, scalars); + }, + "state"_a, "slot"_a, "phi_delta"_a.noconvert(), "phi_at"_a.noconvert(), + "prefactor"_a.noconvert(), "density"_a.noconvert(), "taper"_a.noconvert(), + "preionisation"_a.noconvert(), "raman_rates"_a.noconvert(), "material"_a); + testing.def( + "adams_compensation_start", + [](BoundState& self, const std::size_t slot, const RealInput rate) { + const auto weights = real_vector(rate); + const nb::gil_scoped_release release; + self.open_state().adams_compensation_start(slot, weights); + }, + "state"_a, "slot"_a, "rate"_a.noconvert()); + testing.def( + "adams_hold", [](BoundState& self) { self.open_state().adams_hold(); }, + "state"_a); + testing.def( + "adams_restore", [](BoundState& self) { self.open_state().adams_restore(); }, + "state"_a); + testing.def( + "adams_rows_to_host", + [](BoundState& self, const std::string& name) { + auto& state = self.open_state(); + const auto extents = state.adams_row_extents(name); + // The array's own storage is written once, as the host engine's copy is. + auto storage = + std::make_unique(extents[0] * extents[1] * extents[2]); + { + const nb::gil_scoped_release release; + state.adams_rows_to_host(name, storage->data(), storage->size()); + } + auto* pointer = storage.get(); + nb::capsule owner(pointer, [](void* value) noexcept { + const std::unique_ptr held( + static_cast(value)); + }); + static_cast(storage.release()); // the capsule owns it now + const std::array shape{extents[0], extents[1], extents[2]}; + return ComplexOutput(pointer->data(), shape.size(), shape.data(), owner); + }, + "state"_a, "name"_a); + testing.def( + "adams_stage_scalars", + [](BoundState& self, const double z0, const double z1) { + const auto trial = self.stage_trial(z0, z1); + const auto& step = trial.step; + // The first stage row's values; the test of the native evaluation reads + // them against solprop's bundle. + nb::dict out; + out["phi_delta"] = step.phi_delta; + out["phi_at"] = step.phi_at; + out["prefactor"] = step.prefactor; + out["density"] = step.density; + out["taper"] = step.taper; + out["preionisation"] = step.preionisation; + out["raman_rates"] = step.raman_rates; + out["kerr_density"] = step.kerr_density; + out["plasma_densities"] = step.plasma_densities; + out["plasma_preionisation"] = step.plasma_preionisation; + out["raman_densities"] = step.raman_densities; + out["dispersive_densities"] = step.dispersive_densities; + out["flow_section"] = step.flow_section; + out["flow_weights"] = step.flow_weights; + out["transform_weights"] = step.transform_weights; + return out; + }, + "state"_a, "z0"_a, "z1"_a); + testing.def( + "adams_stage_rate", + [](BoundState& self, const double z) { return self.stage_rate(z); }, "state"_a, + "z"_a); + testing.def( + "has_stage_tables", + [](const BoundState& self) { return self.has_stage_tables(); }, "state"_a); + testing.def( + "table_rate_at", + [](BoundState& self, const double z, const bool before) { + const nb::gil_scoped_release release; + self.table_rate_at(z, before); + }, + "state"_a, "z"_a, "before"_a); + testing.def( + "phase_sum_to_host", + [](BoundState& self, const RealInput weights) { + const auto held = real_vector(weights); + auto& state = self.open_state(); + std::vector values; + { + const nb::gil_scoped_release release; + values = state.phase_sum_to_host(held); + } + return complex_output(values, {self.columns(), values.size() / self.columns()}); + }, + "state"_a, "weights"_a.noconvert()); + testing.def("promote_fsal", [](BoundState& self) { self.promote_fsal(); }, "state"_a); + testing.def( + "adams_march_run", + [](BoundState& self, const nb::dict march, const nb::dict bounds) { + return self.march_run(march, bounds); + }, + "state"_a, "march"_a, "bounds"_a); + testing.def( + "rk_march_run", + [](BoundState& self, const nb::dict march, const nb::dict bounds) { + return self.rk_march_run(march, bounds); + }, + "state"_a, "march"_a, "bounds"_a); + // A test hook: fail the resident engine's `stage` after `after` more calls; + // `trial_source` fails inside the trial's source evaluation. + testing.def( + "adams_march_fault", + [](BoundState& self, const std::string& stage, const std::size_t after, + const std::string& category) { self.march_fault(stage, after, category); }, + "state"_a, "stage"_a, "after"_a, "category"_a); + testing.def( + "statistics", + [](BoundState& self, const std::uint64_t flags, const RealInput windows, + const RealInput on_axis, const double density, const double taper, + const double preionisation, const double intensity_factor, + const nb::object channel_preionisation, const nb::object power_weight) { + const auto held_weight = + power_weight.is_none() ? std::vector{} + : real_vector(exact_array(power_weight)); + const auto held_windows = real_vector(windows); + const auto held_on_axis = real_vector(on_axis); + const auto initial = + channel_preionisation.is_none() + ? std::vector{} + : real_vector(exact_array(channel_preionisation)); + std::vector values; + { + const nb::gil_scoped_release release; + values = + self.statistics(flags, held_windows, held_on_axis, density, taper, + preionisation, intensity_factor, initial, held_weight); + } + return real_output(std::move(values), 1); + }, + "state"_a, "flags"_a, "windows"_a.noconvert(), "on_axis"_a.noconvert(), + "density"_a, "taper"_a, "preionisation"_a, "intensity_factor"_a, + "channel_preionisation"_a = nb::none(), "power_weight"_a = nb::none()); + testing.def( + "spatial_statistics", + [](BoundState& self, const std::uint64_t flags, const double intensity_factor, + const double z) { + std::vector values; + { + const nb::gil_scoped_release release; + values = self.spatial_statistics(flags, intensity_factor, z); + } + return real_output(std::move(values), 1); + }, + "state"_a, "flags"_a, "intensity_factor"_a, "z"_a); + testing.def( + "planned_statistics", + [](BoundState& self, const BoundStatisticsPlan& plan, const double z) { + const auto& held = plan.plan(); + std::vector values; + { + const nb::gil_scoped_release release; + values = self.planned_statistics(held, z); + } + return real_output(std::move(values), 1); + }, + "state"_a, "plan"_a, "z"_a); + testing.def( + "plane_fluence_trace", + [](BoundState& self, const double center_x, const double center_y, + const double dx, const double dy, const double extent, const double spacing, + const std::size_t n_radii, const RealInput cosines, const RealInput sines) { + if (cosines.ndim() != 1 || sines.ndim() != 1) + throw std::invalid_argument("fluence rings must be one-dimensional"); + const auto held_cosines = real_vector(cosines); + const auto held_sines = real_vector(sines); + std::vector values; + { + const nb::gil_scoped_release release; + values = self.plane_fluence_trace(center_x, center_y, dx, dy, extent, spacing, + n_radii, held_cosines, held_sines); + } + return real_output(std::move(values), 1); + }, + "state"_a, "center_x"_a, "center_y"_a, "dx"_a, "dy"_a, "extent"_a, "spacing"_a, + "n_radii"_a, "cosines"_a.noconvert(), "sines"_a.noconvert()); + testing.def( + "axis_spectrum", + [](BoundState& self, const RealInput matrix) { + if (matrix.ndim() != 2) + throw std::invalid_argument("an on-axis matrix must be two-dimensional"); + const auto held = real_vector(matrix); + std::vector values; + { + const nb::gil_scoped_release release; + values = self.axis_spectrum(held); + } + return complex_output(values, {values.size()}); + }, + "state"_a, "matrix"_a.noconvert()); + testing.def( + "monitor_reading", + [](BoundState& self) { + std::vector values; + { + const nb::gil_scoped_release release; + values = self.monitor_reading(); + } + return real_output(std::move(values), 1); + }, + "state"_a); + testing.def( + "quadrature_error", [](BoundState& self) { return self.quadrature_error(); }, + "state"_a); +} + +} // namespace + +// NOLINTNEXTLINE(readability-function-size): the module's one table of bindings, kept whole +NB_MODULE(_core, module_) { + // Each registration makes the Python exception type; the handle need not outlive it. + const nb::exception envelope_convergence_error( + module_, "EnvelopeConvergenceError"); + const nb::exception backend_refusal(module_, + "BackendRefusal"); + module_.doc() = "Private nanobind seam for solprop-native"; + module_.def("initialize_runtime", &initialize_kokkos, "threads"_a, "kernels"_a = 0, + "fft"_a = 0, "raman_fft"_a = 0, "raman_tail_fft"_a = 0, + "band_tiles"_a = -1); + module_.def("fit_blas_threads", &fit_blas_threads, "threads"_a); + module_.def("register_host_blas", ®ister_host_blas); + module_.def( + "rk_score", + [](const RealInput partials, const double rtol, const double atol) { + if (partials.ndim() != 2 || partials.shape(0) != 3) + throw std::invalid_argument("a trial's partials have shape (3, slots)"); + return native::rk::score(partials.data(), partials.shape(1), rtol, atol); + }, + "partials"_a, "rtol"_a, "atol"_a); module_.def("available_device_memory", []() -> nb::object { #ifdef KOKKOS_ENABLE_CUDA std::size_t free_bytes = 0; @@ -3363,35 +3938,10 @@ NB_MODULE(_core, module_) { return result; }, nb::arg("key"), nb::arg("wisdom"), nb::arg("effort")); - // solprop SEP 28 section 4.2's reference parts, for its benchmarks only. - module_.def( - "reference_fft3_pairs", - [](const ComplexInput& values, const std::size_t warm, const std::size_t pairs) { - if (values.ndim() != 3) - throw std::invalid_argument("the reference volume must be three-dimensional"); - return native::reference_fft3_pairs(values.data(), values.shape(0), - values.shape(1), values.shape(2), warm, - pairs); - }, - "values"_a, "warm"_a, "pairs"_a); module_.def("reference_stream_copies", &native::reference_stream_copies, "elements"_a, "warm"_a, "repeats"_a); - // The calling thread's OpenMP default as a native call sees it (solprop issue #130). - module_.def("scoped_openmp_default", &native::scoped_openmp_default); -#if !defined(KOKKOS_ENABLE_CUDA) && !defined(KOKKOS_ENABLE_HIP) - // solprop SEP 46: forget FFTW's process-wide wisdom, for a test of the planning - // transaction. - module_.def("forget_fftw_wisdom", [] { - fftw_init_threads(); - fftw_forget_wisdom(); - }); -#else - module_.def("forget_fftw_wisdom", [] {}); -#endif module_.def("configure_native_spin", &native::configure_native_spin, "milliseconds"_a); - module_.def("scoped_block_time", &native::scoped_block_time); - module_.def("shutdown_runtime", &shutdown_kokkos); module_.def("build_record", &build_record); // FFTW's wisdom as text, for the plan store the adapter owns // (solprop_native._wisdom). None where there is none to keep: a device build, @@ -3404,32 +3954,7 @@ NB_MODULE(_core, module_) { return text.empty() ? nb::none() : nb::cast(std::move(text)); #endif }); - module_.def( - "import_fftw_wisdom", - [](const std::string& text) -> bool { -#if defined(KOKKOS_ENABLE_CUDA) || defined(KOKKOS_ENABLE_HIP) - static_cast(text); - return false; -#else - return native::import_fftw_wisdom(text); -#endif - }, - "text"_a); - native::bindings::bind_helpers(module_); bind_problem(module_); - native::bindings::bind_transverse(module_); - nb::class_(module_, "ScriptedMarch") - .def(nb::init(), "policy"_a, - "norms"_a.noconvert(), "carrier_rate"_a, "steps"_a.noconvert(), - "edges"_a.noconvert()) - .def("run", &ScriptedMarch::run, "state"_a, "bounds"_a) - .def("log", &ScriptedMarch::log); - nb::class_(module_, "ScriptedRkMarch") - .def(nb::init(), "policy"_a, - "norms"_a.noconvert(), "h0"_a, "steps"_a.noconvert(), "edges"_a.noconvert()) - .def("run", &ScriptedRkMarch::run, "state"_a, "bounds"_a) - .def("log", &ScriptedRkMarch::log) - .def("used", &ScriptedRkMarch::used); nb::class_(module_, "State") .def(nb::init(), "problem"_a) .def( @@ -3453,61 +3978,6 @@ NB_MODULE(_core, module_) { : nb::cast(real_output(std::move(partials), 3)); }, "z"_a, "dz"_a, "nodes"_a, "prepare_only"_a = false) - .def( - "trial_step", - [](BoundState& self, const double dz, const RealInput phi_delta, - const RealInput phi_at, const RealInput prefactor, const RealInput density, - const RealInput taper, const RealInput preionisation, - const RealInput raman_rates, const nb::object material, - const bool prepare_only) { - if (self.raman() && - (raman_rates.ndim() != 2 || raman_rates.shape(0) != self.stages() || - raman_rates.shape(1) != self.raman_terms())) - throw std::invalid_argument( - "raman_rates must have shape (n_stages, n_terms)"); - auto scalars = trial_from(phi_delta, phi_at, prefactor, density, taper, - preionisation, raman_rates); - if (!material.is_none()) { - const auto values = nb::cast(material); - scalars.kerr_density = - real_vector(exact_array(values["kerr_density"])); - scalars.plasma_densities = - real_vector(exact_array(values["plasma_densities"])); - scalars.plasma_preionisation = - real_vector(exact_array(values["plasma_preionisation"])); - scalars.raman_densities = - real_vector(exact_array(values["raman_densities"])); - if (values.contains("flow_section")) { - scalars.flow_section = nb::cast(values["flow_section"]); - scalars.flow_weights = - real_vector(exact_array(values["flow_weights"])); - } - if (values.contains("transform_weights")) - scalars.transform_weights = - real_vector(exact_array(values["transform_weights"])); - if (values.contains("dispersive_densities")) - scalars.dispersive_densities = - real_vector(exact_array(values["dispersive_densities"])); - } - std::vector partials; - { - const nb::gil_scoped_release release; - partials = self.trial_step(dz, scalars, prepare_only); - } - return real_output(std::move(partials), 3); - }, - "dz"_a, "phi_delta"_a.noconvert(), "phi_at"_a.noconvert(), - "prefactor"_a.noconvert(), "density"_a.noconvert(), "taper"_a.noconvert(), - "preionisation"_a.noconvert(), "raman_rates"_a.noconvert(), - "material"_a = nb::none(), "prepare_only"_a = false) - .def( - "adopt", - [](BoundState& self, const ComplexInput field, const double dz) { - const auto held = complex_vector(field); - const nb::gil_scoped_release release; - self.adopt(held, dz); - }, - "field"_a.noconvert(), "dz"_a) // solprop SEP 24 phase 3: the low-storage march's resident step. .def( "low_storage_step", @@ -3540,29 +4010,6 @@ NB_MODULE(_core, module_) { self.open_state().adams_allocate(slots, compensated, interpolate); }, "slots"_a, "compensated"_a = false, "interpolate"_a = true) - .def( - "adams_compensation_start", - [](BoundState& self, const std::size_t slot, const RealInput rate) { - const auto weights = real_vector(rate); - const nb::gil_scoped_release release; - self.open_state().adams_compensation_start(slot, weights); - }, - "slot"_a, "rate"_a.noconvert()) - .def( - "adams_start", - [](BoundState& self, const std::size_t slot, const RealInput phi_delta, - const RealInput phi_at, const RealInput prefactor, const RealInput density, - const RealInput taper, const RealInput preionisation, - const RealInput raman_rates, const nb::dict material) { - const auto scalars = - adams_scalars(phi_delta, phi_at, prefactor, density, taper, - preionisation, raman_rates, material); - const nb::gil_scoped_release release; - self.open_state().adams_start(slot, scalars); - }, - "slot"_a, "phi_delta"_a.noconvert(), "phi_at"_a.noconvert(), - "prefactor"_a.noconvert(), "density"_a.noconvert(), "taper"_a.noconvert(), - "preionisation"_a.noconvert(), "raman_rates"_a.noconvert(), "material"_a) .def( "adams_scale", [](BoundState& self, const double rtol, const double atol, @@ -3572,46 +4019,9 @@ NB_MODULE(_core, module_) { self.open_state().adams_scale(rtol, atol, values); }, "rtol"_a, "atol"_a, "weights"_a.noconvert()) - .def( - "adams_fused_accept", - [](BoundState& self, const double dz, const IndexInput keep, - const std::size_t free, const IndexInput dense, const bool interpolate) { - const auto kept = adams_rows(keep); - auto slopes = adams_rows(dense); - // The interpolant's slopes are the new source and these rows. - slopes.width = interpolate ? slopes.width + 1 : 0; - const nb::gil_scoped_release release; - self.open_state().adams_fused_accept(dz, kept, free, slopes); - }, - "dz"_a, "keep"_a.noconvert(), "free"_a, "dense"_a.noconvert(), - "interpolate"_a) - .def("adams_hold", [](BoundState& self) { self.open_state().adams_hold(); }) - .def("adams_restore", [](BoundState& self) { self.open_state().adams_restore(); }) // solprop SEP 29 G2: the resident history's persistent rows across a resume. .def("adams_row_names", [](BoundState& self) { return self.open_state().adams_row_names(); }) - .def( - "adams_rows_to_host", - [](BoundState& self, const std::string& name) { - auto& state = self.open_state(); - const auto extents = state.adams_row_extents(name); - // The array's own storage is written once, as the host engine's copy is. - auto storage = - std::make_unique(extents[0] * extents[1] * extents[2]); - { - const nb::gil_scoped_release release; - state.adams_rows_to_host(name, storage->data(), storage->size()); - } - auto* pointer = storage.get(); - nb::capsule owner(pointer, [](void* value) noexcept { - const std::unique_ptr held( - static_cast(value)); - }); - static_cast(storage.release()); // the capsule owns it now - const std::array shape{extents[0], extents[1], extents[2]}; - return ComplexOutput(pointer->data(), shape.size(), shape.data(), owner); - }, - "name"_a) .def( "adams_rows_from_host", [](BoundState& self, const std::string& name, const ComplexInput rows) { @@ -3646,28 +4056,6 @@ NB_MODULE(_core, module_) { }, "kind"_a, "edges"_a.noconvert(), "lower"_a, "upper"_a, "coefficients"_a.noconvert()) - .def( - "table_evaluate", - [](BoundState& self, const IndexInput slots, const RealInput positions) { - if (slots.ndim() != 1 || positions.ndim() != 1) - throw std::invalid_argument( - "z table slots and positions must be one-dimensional"); - const auto held_slots = index_vector(slots); - const auto held_positions = real_vector(positions); - auto& state = self.open_state(); - const nb::gil_scoped_release release; - state.table_evaluate(held_slots, held_positions); - }, - "slots"_a.noconvert(), "positions"_a.noconvert()) - .def( - "table_rate", - [](BoundState& self, const std::size_t slot, const double z, - const bool before) { - auto& state = self.open_state(); - const nb::gil_scoped_release release; - state.table_rate(slot, z, before); - }, - "slot"_a, "z"_a, "before"_a) .def( "table_terms_to_host", [](BoundState& self, const std::string& kind, const std::size_t slot) { @@ -3681,111 +4069,6 @@ NB_MODULE(_core, module_) { {self.columns(), values.size() / self.columns()}); }, "kind"_a, "slot"_a) - .def( - "phase_sum_to_host", - [](BoundState& self, const RealInput weights) { - const auto held = real_vector(weights); - auto& state = self.open_state(); - std::vector values; - { - const nb::gil_scoped_release release; - values = state.phase_sum_to_host(held); - } - return complex_output(values, - {self.columns(), values.size() / self.columns()}); - }, - "weights"_a.noconvert()) - .def( - "adams_observe", - [](BoundState& self, const RealInput weights, const RealInput phi_delta, - const RealInput phi_at, const RealInput prefactor, const RealInput density, - const RealInput taper, const RealInput preionisation, - const RealInput raman_rates, const nb::dict material) { - native::AdamsWeights table; - const auto values = real_vector(weights); - if (values.size() > native::adams_max_samples) - throw std::invalid_argument("too many Adams interpolation weights"); - for (std::size_t t = 0; t < values.size(); ++t) { - table.predictor[t] = values[t]; - table.corrector[t] = values[t]; - } - const auto scalars = - adams_scalars(phi_delta, phi_at, prefactor, density, taper, - preionisation, raman_rates, material); - const nb::gil_scoped_release release; - self.open_state().adams_observe(table, scalars); - }, - "weights"_a.noconvert(), "phi_delta"_a.noconvert(), "phi_at"_a.noconvert(), - "prefactor"_a.noconvert(), "density"_a.noconvert(), "taper"_a.noconvert(), - "preionisation"_a.noconvert(), "raman_rates"_a.noconvert(), "material"_a) - .def( - "adams_exponential_trial", - [](BoundState& self, const double dz, const IndexInput slots, - const RealInput predictor, const RealInput corrector, const RealInput rows, - const RealInput divisor, const RealInput phi_delta, const RealInput phi_at, - const RealInput prefactor, const RealInput density, const RealInput taper, - const RealInput preionisation, const RealInput raman_rates, - const nb::dict material, const RealInput sample_phi_delta, - const RealInput sample_phi_at, const RealInput sample_prefactor, - const RealInput sample_density, const RealInput sample_taper, - const RealInput sample_preionisation, const RealInput sample_raman_rates, - const nb::dict sample_material, const RealInput spans, - const RealInput comp_predictor, const RealInput comp_corrector, - const RealInput comp_rows, const RealInput rate, const RealInput carrier) { - auto weights = exponential_weights(slots, predictor, corrector, rows); - carrier_frame(weights, carrier, weights.width - 1); - const auto rate_weights = real_vector(rate); - // A varying operator's compensation tables (solprop's - // backends.multistep.compensation_tables); empty for a constant one. - weights.compensated = !rate_weights.empty(); - if (weights.compensated) { - const auto span_values = real_vector(spans); - const auto predictor_values = real_vector(comp_predictor); - const auto corrector_values = real_vector(comp_corrector); - const auto row_values = real_vector(comp_rows); - if (span_values.size() + 1 != weights.width || - predictor_values.size() != weights.order || - corrector_values.size() != weights.order + 1 || - row_values.size() != weights.n_rows * weights.width) - throw std::invalid_argument( - "Adams compensation tables have inconsistent extents"); - for (std::size_t t = 0; t < span_values.size(); ++t) - weights.span[t] = span_values[t]; - for (std::size_t t = 0; t < predictor_values.size(); ++t) - weights.comp_predictor[t] = predictor_values[t]; - for (std::size_t t = 0; t < corrector_values.size(); ++t) - weights.comp_corrector[t] = corrector_values[t]; - for (std::size_t row = 0; row < weights.n_rows; ++row) - for (std::size_t t = 0; t < weights.width; ++t) - weights.comp_rows[row][t] = row_values[row * weights.width + t]; - } - const auto scale = real_vector(divisor); - const auto step = - adams_scalars(phi_delta, phi_at, prefactor, density, taper, - preionisation, raman_rates, material); - const auto sample = - adams_scalars(sample_phi_delta, sample_phi_at, sample_prefactor, - sample_density, sample_taper, sample_preionisation, - sample_raman_rates, sample_material); - std::vector norms; - { - const nb::gil_scoped_release release; - norms = self.open_state().adams_exponential_trial( - dz, weights, scale, step, sample, rate_weights); - } - return real_output(std::move(norms), 1); - }, - "dz"_a, "slots"_a.noconvert(), "predictor"_a.noconvert(), - "corrector"_a.noconvert(), "rows"_a.noconvert(), "divisor"_a.noconvert(), - "phi_delta"_a.noconvert(), "phi_at"_a.noconvert(), "prefactor"_a.noconvert(), - "density"_a.noconvert(), "taper"_a.noconvert(), "preionisation"_a.noconvert(), - "raman_rates"_a.noconvert(), "material"_a, "sample_phi_delta"_a.noconvert(), - "sample_phi_at"_a.noconvert(), "sample_prefactor"_a.noconvert(), - "sample_density"_a.noconvert(), "sample_taper"_a.noconvert(), - "sample_preionisation"_a.noconvert(), "sample_raman_rates"_a.noconvert(), - "sample_material"_a, "spans"_a.noconvert(), "comp_predictor"_a.noconvert(), - "comp_corrector"_a.noconvert(), "comp_rows"_a.noconvert(), - "rate"_a.noconvert(), "carrier"_a.noconvert()) // solprop SEP 39 phase 1: the trial's tables, stage scalars and rate formed // natively from the nodes and the tables uploaded once per run. .def( @@ -3794,7 +4077,6 @@ NB_MODULE(_core, module_) { self.set_stage_tables(stage_tables_from(tables)); }, "tables"_a) - .def("has_stage_tables", &BoundState::has_stage_tables) .def("table_slots", &BoundState::table_slots, "phi"_a, "prefactor"_a, "slots"_a, "rate"_a) .def( @@ -3804,13 +4086,6 @@ NB_MODULE(_core, module_) { return self.table_load(positions); }, "positions"_a) - .def( - "table_rate_at", - [](BoundState& self, const double z, const bool before) { - const nb::gil_scoped_release release; - self.table_rate_at(z, before); - }, - "z"_a, "before"_a) .def("table_evaluations", &BoundState::table_evaluations) // solprop SEP 39 phase 2: the native Adams march. .def( @@ -3824,7 +4099,6 @@ NB_MODULE(_core, module_) { }, "policy"_a, "fused"_a, "compensated"_a, "interpolate"_a, "steps"_a.noconvert(), "edges"_a.noconvert()) - .def("adams_march_run", &BoundState::march_run, "state"_a, "bounds"_a) .def("bind_host_source", &BoundState::bind_host_source, "owner"_a.none()) .def( "rk_march_configure", @@ -3836,7 +4110,6 @@ NB_MODULE(_core, module_) { }, "policy"_a, "nodes"_a, "rtol"_a, "atol"_a, "steps"_a.noconvert(), "edges"_a.noconvert()) - .def("rk_march_run", &BoundState::rk_march_run, "state"_a, "bounds"_a) .def("low_storage_configure", &BoundState::low_storage_configure, "flows"_a, "separable"_a, "origin"_a) .def("start_session", &start_session, "kind"_a, "state"_a, "plan"_a, "z"_a, @@ -3854,178 +4127,6 @@ NB_MODULE(_core, module_) { "partials"_a.noconvert(), "rtol"_a, "atol"_a) .def("flow_guard_configure", &BoundState::flow_guard_configure, "row_sum"_a, "condition_bound"_a, "taylor_scale"_a, "max_squarings"_a, "allowance"_a) - // A test hook: fail the resident engine's `stage` after `after` more calls; - // `trial_source` fails inside the trial's source evaluation. - .def("adams_march_fault", &BoundState::march_fault, "stage"_a, "after"_a, - "category"_a) - .def( - "adams_exponential_trial_at", - [](BoundState& self, const double z, const double dz, const RealInput nodes, - const IndexInput slots, const std::size_t order, - const std::vector& orders, const bool compensated, - const RealInput carrier) { - auto weights = - exponential_weights_at(nodes, slots, order, orders, compensated); - carrier_frame(weights, carrier, weights.width - 1); - const double end = z + dz; - auto trial = self.stage_trial(z, end); - const auto rate = - compensated ? self.stage_rate(end) : std::vector{}; - std::vector norms; - { - const nb::gil_scoped_release release; - norms = self.open_state().adams_exponential_trial( - dz, weights, {}, trial.step, trial.sample, rate); - } - return real_output(std::move(norms), 1); - }, - "z"_a, "dz"_a, "nodes"_a.noconvert(), "slots"_a.noconvert(), "order"_a, - "orders"_a, "compensated"_a, "carrier"_a.noconvert()) - .def( - "adams_fused_trial_at", - [](BoundState& self, const double z, const double dz, const RealInput nodes, - const IndexInput slots, const std::size_t order, - const std::vector& orders) { - const auto slot_values = index_vector(slots); - const auto weights = native::stage::fused_weights( - nodes.data(), element_count(nodes), slot_values.data(), - slot_values.size(), order, orders.data(), orders.size()); - const auto trial = self.stage_trial(z, z + dz); - std::vector norms; - { - const nb::gil_scoped_release release; - norms = self.open_state().adams_fused_trial(dz, weights, {}, trial.step); - } - return real_output(std::move(norms), 1); - }, - "z"_a, "dz"_a, "nodes"_a.noconvert(), "slots"_a.noconvert(), "order"_a, - "orders"_a) - .def( - "adams_stage_scalars", - [](BoundState& self, const double z0, const double z1) { - const auto trial = self.stage_trial(z0, z1); - const auto& step = trial.step; - // The first stage row's values; the test of the native evaluation reads - // them against solprop's bundle. - nb::dict out; - out["phi_delta"] = step.phi_delta; - out["phi_at"] = step.phi_at; - out["prefactor"] = step.prefactor; - out["density"] = step.density; - out["taper"] = step.taper; - out["preionisation"] = step.preionisation; - out["raman_rates"] = step.raman_rates; - out["kerr_density"] = step.kerr_density; - out["plasma_densities"] = step.plasma_densities; - out["plasma_preionisation"] = step.plasma_preionisation; - out["raman_densities"] = step.raman_densities; - out["dispersive_densities"] = step.dispersive_densities; - out["flow_section"] = step.flow_section; - out["flow_weights"] = step.flow_weights; - out["transform_weights"] = step.transform_weights; - return out; - }, - "z0"_a, "z1"_a) - .def( - "adams_stage_rate", - [](BoundState& self, const double z) { return self.stage_rate(z); }, "z"_a) - .def( - "adams_exponential_accept", - [](BoundState& self, const double dz, const std::size_t free, - const IndexInput dense, const bool interpolate) { - auto slopes = adams_rows(dense); - slopes.width = interpolate ? slopes.width + 1 : 0; - const nb::gil_scoped_release release; - self.open_state().adams_exponential_accept(dz, free, slopes); - }, - "dz"_a, "free"_a, "dense"_a.noconvert(), "interpolate"_a) - .def( - "adams_exponential_observe", - [](BoundState& self, const double xi, const double dz, - const RealInput coefficients, const RealInput dense_weight, - const RealInput dense_theta, const RealInput carrier) { - native::ExponentialWeights weights; - const auto weight_values = real_vector(dense_weight); - const auto theta_values = real_vector(dense_theta); - if (weight_values.size() != theta_values.size() || - weight_values.size() > native::adams_max_samples + 1) - throw std::invalid_argument( - "Adams compensation weights are inconsistent"); - for (std::size_t t = 0; t < weight_values.size(); ++t) { - weights.dense_weight[t] = weight_values[t]; - weights.dense_theta[t] = theta_values[t]; - } - const auto values = real_vector(coefficients); - const auto count = static_cast( - std::llround(std::sqrt(static_cast(values.size())))); - if (count * count != values.size() || count > native::adams_max_samples) - throw std::invalid_argument( - "Adams interpolant coefficients are not square"); - for (std::size_t j = 0; j < count; ++j) - for (std::size_t k = 0; k < count; ++k) - weights.corrector[j][k] = values[j * count + k]; - // The accepted step's carrier frame, its history rows after the endpoint. - carrier_frame(weights, carrier, count == 0 ? 0 : count - 1); - const nb::gil_scoped_release release; - self.open_state().adams_exponential_observe(xi, dz, weights); - }, - "xi"_a, "dz"_a, "coefficients"_a.noconvert(), "dense_weight"_a.noconvert(), - "dense_theta"_a.noconvert(), "carrier"_a.noconvert()) - .def( - "set_flow_actions", - [](BoundState& self, const ComplexInput forward, const ComplexInput inverse, - const BoolInput identity) { - const auto held_forward = complex_vector(forward); - const auto held_inverse = complex_vector(inverse); - const auto held_identity = bool_vector(identity); - const nb::gil_scoped_release release; - self.set_flow_actions(held_forward, held_inverse, held_identity); - }, - "forward"_a.noconvert(), "inverse"_a.noconvert(), "identity"_a.noconvert()) - .def( - "form_flow_actions", - [](BoundState& self, const std::size_t section, const double dz, - const RealInput fractions) { - const auto held_fractions = real_vector(fractions); - std::vector measured; - { - const nb::gil_scoped_release release; - measured = self.form_flow_actions(section, dz, held_fractions); - } - return real_output(std::move(measured), 1); - }, - "section"_a, "dz"_a, "fractions"_a.noconvert()) - // solprop SEP 47 phase 4: the last exponential Adams trial's coupled block and - // exponent, observations for tests. - .def("adams_block_to_host", - [](BoundState& self) { - std::vector values; - { - const nb::gil_scoped_release release; - values = self.adams_block_to_host(); - } - return complex_output(values, {values.size()}); - }) - .def("adams_exponent_to_host", - [](BoundState& self) { - std::vector values; - { - const nb::gil_scoped_release release; - values = self.adams_exponent_to_host(); - } - return complex_output(values, {values.size()}); - }) - .def( - "flow_actions_to_host", - [](BoundState& self, const bool inverse) { - std::vector values; - { - const nb::gil_scoped_release release; - values = self.flow_actions_to_host(inverse); - } - return complex_output(values, {values.size()}); - }, - "inverse"_a) .def( "prepare_raman", [](BoundState& self, const RealInput rates, const nb::object densities) { @@ -4040,65 +4141,6 @@ NB_MODULE(_core, module_) { self.prepare_raman(held_rates, held_densities); }, "rates"_a.noconvert(), "densities"_a = nb::none()) - .def( - "weighted_error", - [](BoundState& self, const RealInput scale) { - std::vector partials; - const auto held_scale = real_vector(scale); - { - const nb::gil_scoped_release release; - partials = self.weighted_error(held_scale); - } - return real_output(std::move(partials), 1); - }, - "scale"_a.noconvert()) - .def( - "spatial_statistics", - [](BoundState& self, const std::uint64_t flags, const double intensity_factor, - const double z) { - std::vector values; - { - const nb::gil_scoped_release release; - values = self.spatial_statistics(flags, intensity_factor, z); - } - return real_output(std::move(values), 1); - }, - "flags"_a, "intensity_factor"_a, "z"_a) - .def( - "plane_fluence_trace", - [](BoundState& self, const double center_x, const double center_y, - const double dx, const double dy, const double extent, - const double spacing, const std::size_t n_radii, const RealInput cosines, - const RealInput sines) { - if (cosines.ndim() != 1 || sines.ndim() != 1) - throw std::invalid_argument("fluence rings must be one-dimensional"); - const auto held_cosines = real_vector(cosines); - const auto held_sines = real_vector(sines); - std::vector values; - { - const nb::gil_scoped_release release; - values = - self.plane_fluence_trace(center_x, center_y, dx, dy, extent, spacing, - n_radii, held_cosines, held_sines); - } - return real_output(std::move(values), 1); - }, - "center_x"_a, "center_y"_a, "dx"_a, "dy"_a, "extent"_a, "spacing"_a, - "n_radii"_a, "cosines"_a.noconvert(), "sines"_a.noconvert()) - .def( - "axis_spectrum", - [](BoundState& self, const RealInput matrix) { - if (matrix.ndim() != 2) - throw std::invalid_argument("an on-axis matrix must be two-dimensional"); - const auto held = real_vector(matrix); - std::vector values; - { - const nb::gil_scoped_release release; - values = self.axis_spectrum(held); - } - return complex_output(values, {values.size()}); - }, - "matrix"_a.noconvert()) .def( "aperture_statistics", [](BoundState& self, const std::uint64_t flags, const RealInput apertures, @@ -4120,46 +4162,6 @@ NB_MODULE(_core, module_) { }, "flags"_a, "apertures"_a.noconvert(), "exponent"_a, "regions"_a.noconvert(), "intensity_factor"_a) - .def( - "planned_statistics", - [](BoundState& self, const BoundStatisticsPlan& plan, const double z) { - const auto& held = plan.plan(); - std::vector values; - { - const nb::gil_scoped_release release; - values = self.planned_statistics(held, z); - } - return real_output(std::move(values), 1); - }, - "plan"_a, "z"_a) - .def( - "statistics", - [](BoundState& self, const std::uint64_t flags, const RealInput windows, - const RealInput on_axis, const double density, const double taper, - const double preionisation, const double intensity_factor, - const nb::object channel_preionisation, const nb::object power_weight) { - const auto held_weight = - power_weight.is_none() - ? std::vector{} - : real_vector(exact_array(power_weight)); - const auto held_windows = real_vector(windows); - const auto held_on_axis = real_vector(on_axis); - const auto initial = - channel_preionisation.is_none() - ? std::vector{} - : real_vector(exact_array(channel_preionisation)); - std::vector values; - { - const nb::gil_scoped_release release; - values = self.statistics(flags, held_windows, held_on_axis, density, - taper, preionisation, intensity_factor, initial, - held_weight); - } - return real_output(std::move(values), 1); - }, - "flags"_a, "windows"_a.noconvert(), "on_axis"_a.noconvert(), "density"_a, - "taper"_a, "preionisation"_a, "intensity_factor"_a, - "channel_preionisation"_a = nb::none(), "power_weight"_a = nb::none()) .def( "finish", [](BoundState& self, const double dz) { @@ -4167,7 +4169,6 @@ NB_MODULE(_core, module_) { self.finish(dz); }, "dz"_a) - .def("promote_fsal", [](BoundState& self) { self.promote_fsal(); }) .def("clear_fsal", [](BoundState& self) { self.clear_fsal(); }) .def( "set_absorber_quiet", @@ -4198,15 +4199,6 @@ NB_MODULE(_core, module_) { self.bind_occupancy(held, count); }, "buckets"_a.noconvert(), "count"_a) - .def("monitor_reading", - [](BoundState& self) { - std::vector values; - { - const nb::gil_scoped_release release; - values = self.monitor_reading(); - } - return real_output(std::move(values), 1); - }) // solprop SEP 44: the bytes through the state's crossings, each way. .def("crossed_bytes", [](BoundState& self) { @@ -4291,32 +4283,6 @@ NB_MODULE(_core, module_) { return complex_buffer_output(std::move(storage), {self.columns(), count / self.columns()}); }) - .def( - "stage_to_host", - [](BoundState& self, const std::size_t stage) { - const auto count = self.elements(); - auto storage = native::crossing::host_buffer(2 * count); - { - const nb::gil_scoped_release release; - self.stage_to_host( - stage, {reinterpret_cast(storage.get()), count}); - } - return complex_buffer_output(std::move(storage), - {self.columns(), count / self.columns()}); - }, - "stage"_a) - .def( - "projected_to_host", - [](BoundState& self, const bool coarse) { - std::vector values; - { - const nb::gil_scoped_release release; - values = self.projected_to_host(coarse); - } - return complex_output(values, - {self.columns(), values.size() / self.columns()}); - }, - "coarse"_a = false) .def_prop_ro("dispersive_path", [](BoundState& self) { return self.dispersive_path(); }) .def("memory_ledger", @@ -4344,8 +4310,6 @@ NB_MODULE(_core, module_) { .def_prop_ro("rk_source_evaluations", [](BoundState& self) { return self.rk_source_evaluations(); }) .def_prop_ro("axis_scans", [](BoundState& self) { return self.axis_scans(); }) - .def_prop_ro("quadrature_error", - [](BoundState& self) { return self.quadrature_error(); }) .def("quadrature_peak", [](BoundState& self) { return self.quadrature_peak(); }) .def_prop_ro("synthesis_provider", [](BoundState& self) { return self.synthesis_provider(); }) @@ -4484,75 +4448,11 @@ NB_MODULE(_core, module_) { .def("table_phi", &BoundSession::table_phi, "sequence"_a, "generation"_a, "z"_a) .def("fail_outside", &BoundSession::fail_outside) .def("close", &BoundSession::close, nb::call_guard()); - // solprop SEP 47 section 6.4: the owning boundary monitor alone, for solprop's tests - // to feed recorded readings through it and its own monitor alike. - nb::class_(module_, "Monitor") - .def( - "__init__", - [](native::watch::Monitor* self, const nb::dict config) { - new (self) native::watch::Monitor(watch_config_from(config)); - }, - "config"_a) - .def( - "resume", - [](native::watch::Monitor& self, const nb::dict record, const bool plane, - const nb::handle unwatched) { - self.resume(watch_resumption_from(record), plane, - watch_stretches_from(unwatched)); - }, - "record"_a, "plane"_a, "unwatched"_a) - .def( - "launch", - [](native::watch::Monitor& self, const RealInput reading, const double z, - const double floor, const std::optional& floor_regions) { - const auto values = real_vector(reading); - std::vector regions; - if (floor_regions) { - regions = real_vector(*floor_regions); - if (regions.size() != 4) - throw std::invalid_argument("the floor's regions are four"); - } - return watch_judgement_to( - self.launch(values.data(), values.size(), z, floor, - floor_regions ? regions.data() : nullptr)); - }, - "reading"_a, "z"_a, "floor"_a = 0.0, "floor_regions"_a.none() = nb::none()) - .def("due", &native::watch::Monitor::due, "z"_a) - .def("skip", &native::watch::Monitor::skip, "z"_a) - .def( - "step", - [](native::watch::Monitor& self, const RealInput reading, const double z, - const bool plane) { - const auto values = real_vector(reading); - return watch_judgement_to( - self.step(values.data(), values.size(), z, plane)); - }, - "reading"_a, "z"_a, "plane"_a = false) - .def("plane", &native::watch::Monitor::plane, "z"_a) - .def("note_collar", &native::watch::Monitor::note_collar, "left_out"_a) - .def("finish", - [](const native::watch::Monitor& self) { - const auto finish = self.finish(); - nb::dict out; - out["removed"] = finish.removed; - out["guard_low_max"] = finish.guard_max[0]; - out["guard_high_max"] = finish.guard_max[1]; - out["warns"] = finish.warns; - return out; - }) - .def("record", - [](const native::watch::Monitor& self) { - return watch_record_to(self.record()); - }) - .def("watch_state", - [](const native::watch::Monitor& self) { - return watch_state_to(self.state()); - }) - .def_prop_ro("stale", &native::watch::Monitor::stale) - .def_prop_ro("collar_quiet", &native::watch::Monitor::quiet) - .def_prop_ro("step_cap", &native::watch::Monitor::cap) - .def_prop_ro("rests", &native::watch::Monitor::rests) - .def("steps_to_check", &native::watch::Monitor::steps_to_check); + auto testing = + module_.def_submodule("_testing", "Private entry points for solprop's own tests"); + native::bindings::bind_helpers(module_, testing); + native::bindings::bind_transverse(testing); + bind_testing(testing); if (Py_AtExit(&shutdown_after_interpreter) != 0) throw std::runtime_error( "cannot register the Kokkos runtime's shutdown at interpreter exit"); diff --git a/native/src/bindings_transverse.hpp b/native/src/bindings_transverse.hpp index 98d185af5..3db36a545 100644 --- a/native/src/bindings_transverse.hpp +++ b/native/src/bindings_transverse.hpp @@ -30,7 +30,7 @@ nanobind::dict transverse_record_to(const transverse::Record& record, const transverse::Finish& finish); /** A notice, as `_transverse.EdgeNotice.of` reads it. */ nanobind::dict transverse_notice_to(const transverse::Notice& notice); -/** Add `TransverseEdge` to the extension module. */ +/** Add `TransverseEdge` to the given module: the private `_testing` module. */ void bind_transverse(nanobind::module_& module_); } // namespace solprop_native::bindings diff --git a/native/src/engines.cpp b/native/src/engines.cpp index 74676d510..c21b19e0a 100644 --- a/native/src/engines.cpp +++ b/native/src/engines.cpp @@ -72,7 +72,7 @@ void ResidentEngine::trial(const double z, const double dz, state_.host_evaluation(z + dz, HostPurpose::predictor); if (fused_) { // The interaction formulation: the history transported to the anchor, the - // source evaluated at the step's end (solprop's `_ResidentAdams.fused_trial`). + // source evaluated at the step's end (solprop's `HostHistory.fused_trial`). const auto weights = stage::fused_weights(stencil.nodes.data(), stencil.held, stencil.rows.data(), slots, stencil.order, stencil.orders.data(), stencil.n_orders); @@ -90,8 +90,8 @@ void ResidentEngine::trial(const double z, const double dz, stencil.n_orders, compensated_); const double end = z + dz; if (tables_.chord != stage::Chord::none) { - // The carrier frame (solprop's `_ResidentAdams._carrier`): the chord's shift and - // each history row's rotation exp(i shift (1 - theta_t)). + // The carrier frame (solprop's `HostHistory.exponential_trial`): the chord's shift + // and each history row's rotation exp(i shift (1 - theta_t)). const double shift = stage::chord(tables_, z, end); const std::size_t rows = weights.width - 1; carrier_.assign(1 + 2 * rows, 0.0); diff --git a/native/src/helpers.cpp b/native/src/helpers.cpp index cabb4f2c4..57f549279 100644 --- a/native/src/helpers.cpp +++ b/native/src/helpers.cpp @@ -147,7 +147,7 @@ void vector_exp_complex(const Input& a, const Input& b, } // namespace -void bind_helpers(nb::module_& module_) { +void bind_helpers(nb::module_& module_, nb::module_& testing) { module_.def("clenshaw_points", &clenshaw_points, "z"_a.noconvert(), "edges"_a.noconvert(), "lower"_a, "upper"_a, "c"_a.noconvert(), "out"_a.noconvert()); @@ -161,11 +161,11 @@ void bind_helpers(nb::module_& module_) { "corrector"_a.noconvert(), "factored"_a.noconvert(), "spans"_a.noconvert(), "carried"_a.noconvert(), "endpoint"_a.noconvert(), "defects"_a.noconvert()); - module_.def("vector_exp", &vector_exp, "x"_a.noconvert(), "out"_a.noconvert()); - module_.def("vector_log", &vector_log, "x"_a.noconvert(), "out"_a.noconvert()); - module_.def("vector_sincos", &vector_sincos, "x"_a.noconvert(), "sine"_a.noconvert(), + testing.def("vector_exp", &vector_exp, "x"_a.noconvert(), "out"_a.noconvert()); + testing.def("vector_log", &vector_log, "x"_a.noconvert(), "out"_a.noconvert()); + testing.def("vector_sincos", &vector_sincos, "x"_a.noconvert(), "sine"_a.noconvert(), "cosine"_a.noconvert()); - module_.def("vector_exp_complex", &vector_exp_complex, "a"_a.noconvert(), + testing.def("vector_exp_complex", &vector_exp_complex, "a"_a.noconvert(), "b"_a.noconvert(), "real"_a.noconvert(), "imag"_a.noconvert()); } diff --git a/native/src/helpers.hpp b/native/src/helpers.hpp index de4bd83ad..059597289 100644 --- a/native/src/helpers.hpp +++ b/native/src/helpers.hpp @@ -11,9 +11,9 @@ namespace solprop_native::bindings { /** * Add the host helpers solprop's per-stage and per-step evaluations take from this * backend to the extension module: `clenshaw_points`, `basis_rows` and - * `trial_tables` (helpers.cpp), and the vector-maths layer's batch functions for its - * tests. + * `trial_tables` (helpers.cpp); and the vector-maths layer's batch functions, for its + * tests, to the private `testing` module. */ -void bind_helpers(nanobind::module_& module_); +void bind_helpers(nanobind::module_& module_, nanobind::module_& testing); } // namespace solprop_native::bindings diff --git a/native/src/solprop_native/__init__.py b/native/src/solprop_native/__init__.py index d25d92c76..bae2dd209 100644 --- a/native/src/solprop_native/__init__.py +++ b/native/src/solprop_native/__init__.py @@ -4,10 +4,10 @@ """Kokkos execution-space backend for :mod:`solprop`. -Singleton and fixed-batch workspaces support multimode scalar and two-component -propagation, Kerr, plasma, time-domain Raman, weighted control and member-owned -statistics. Native states remain resident in their execution space between calls; -observations are owning host ``complex128`` arrays. +Its workspaces support multimode scalar and two-component propagation, Kerr, plasma, +time-domain Raman, weighted control and statistics. Native states remain resident in +their execution space between calls; observations are owning host ``complex128`` +arrays. """ from __future__ import annotations @@ -463,8 +463,6 @@ class BuildInfo: def available_device_memory() -> int | None: """Return the selected accelerator's free bytes, or None for a host build. - A scan batch sizes its groups against them. - Returns ------- int or None diff --git a/native/src/solprop_native/_core.pyi b/native/src/solprop_native/_core.pyi index b1e43ff97..cd9fb9d4b 100644 --- a/native/src/solprop_native/_core.pyi +++ b/native/src/solprop_native/_core.pyi @@ -10,6 +10,12 @@ from typing import Any, overload import numpy as np import numpy.typing as npt +# The private test module, bound as the submodule `_testing` (solprop SEP 52), has its +# own hand-written stub; the extension has no `_core_testing` attribute. +from solprop_native import _core_testing + +_testing = _core_testing + # Generated by native/scripts/problem_stub.py from nanobind.stubgen. # Array fields are copied in and out: assign a whole array, since an item # assigned through a read copy changes nothing. @@ -261,19 +267,6 @@ class State: field: npt.NDArray[np.complex128], noise: npt.NDArray[np.complex128], ) -> None: ... - def trial_step( - self, - dz: float, - phi_delta: npt.NDArray[np.float64], - phi_at: npt.NDArray[np.float64], - prefactor: npt.NDArray[np.float64], - density: npt.NDArray[np.float64], - taper: npt.NDArray[np.float64], - preionisation: npt.NDArray[np.float64], - raman_rates: npt.NDArray[np.float64], - material: dict[str, npt.NDArray[np.float64] | int] | None = None, - prepare_only: bool = False, - ) -> npt.NDArray[np.float64]: ... def rk_trial( self, z: float, dz: float, nodes: list[float], prepare_only: bool = False ) -> npt.NDArray[np.float64]: ... @@ -282,39 +275,6 @@ class State: rates: npt.NDArray[np.float64], densities: npt.NDArray[np.float64] | None = None, ) -> None: ... - def set_flow_actions( - self, - forward: npt.NDArray[np.complex128], - inverse: npt.NDArray[np.complex128], - identity: npt.NDArray[np.bool_], - ) -> None: ... - def form_flow_actions( - self, section: int, dz: float, fractions: npt.NDArray[np.float64] - ) -> npt.NDArray[np.float64]: ... - def flow_actions_to_host(self, inverse: bool) -> npt.NDArray[np.complex128]: ... - def adams_block_to_host(self) -> npt.NDArray[np.complex128]: ... - def adams_exponent_to_host(self) -> npt.NDArray[np.complex128]: ... - def weighted_error( - self, scale: npt.NDArray[np.float64] - ) -> npt.NDArray[np.float64]: ... - def spatial_statistics( - self, flags: int, intensity_factor: float, z: float - ) -> npt.NDArray[np.float64]: ... - def plane_fluence_trace( - self, - center_x: float, - center_y: float, - dx: float, - dy: float, - extent: float, - spacing: float, - n_radii: int, - cosines: npt.NDArray[np.float64], - sines: npt.NDArray[np.float64], - ) -> npt.NDArray[np.float64]: ... - def axis_spectrum( - self, matrix: npt.NDArray[np.float64] - ) -> npt.NDArray[np.complex128]: ... def aperture_statistics( self, flags: int, @@ -323,22 +283,6 @@ class State: regions: npt.NDArray[np.float64], intensity_factor: float, ) -> npt.NDArray[np.float64]: ... - def planned_statistics( - self, plan: StatisticsPlan, z: float - ) -> npt.NDArray[np.float64]: ... - def statistics( - self, - flags: int, - windows: npt.NDArray[np.float64], - on_axis: npt.NDArray[np.float64], - density: float, - taper: float, - preionisation: float, - intensity_factor: float, - channel_preionisation: npt.NDArray[np.float64] | None = None, - power_weight: npt.NDArray[np.float64] | None = None, - ) -> npt.NDArray[np.float64]: ... - def adopt(self, field: npt.NDArray[np.complex128], dz: float) -> None: ... def low_storage_step( self, dz: float, @@ -355,77 +299,10 @@ class State: def adams_allocate( self, slots: int, compensated: bool = False, interpolate: bool = True ) -> None: ... - def adams_compensation_start( - self, slot: int, rate: npt.NDArray[np.float64] - ) -> None: ... - def adams_start( - self, - slot: int, - phi_delta: npt.NDArray[np.float64], - phi_at: npt.NDArray[np.float64], - prefactor: npt.NDArray[np.float64], - density: npt.NDArray[np.float64], - taper: npt.NDArray[np.float64], - preionisation: npt.NDArray[np.float64], - raman_rates: npt.NDArray[np.float64], - material: dict[str, npt.NDArray[np.float64] | int], - ) -> None: ... def adams_scale( self, rtol: float, atol: float, weights: npt.NDArray[np.float64] ) -> None: ... - def adams_fused_accept( - self, - dz: float, - keep: npt.NDArray[np.uint64], - free: int, - dense: npt.NDArray[np.uint64], - interpolate: bool, - ) -> None: ... - def adams_exponential_trial( - self, - dz: float, - slots: npt.NDArray[np.uint64], - predictor: npt.NDArray[np.float64], - corrector: npt.NDArray[np.float64], - rows: npt.NDArray[np.float64], - divisor: npt.NDArray[np.float64], - phi_delta: npt.NDArray[np.float64], - phi_at: npt.NDArray[np.float64], - prefactor: npt.NDArray[np.float64], - density: npt.NDArray[np.float64], - taper: npt.NDArray[np.float64], - preionisation: npt.NDArray[np.float64], - raman_rates: npt.NDArray[np.float64], - material: dict[str, npt.NDArray[np.float64] | int], - sample_phi_delta: npt.NDArray[np.float64], - sample_phi_at: npt.NDArray[np.float64], - sample_prefactor: npt.NDArray[np.float64], - sample_density: npt.NDArray[np.float64], - sample_taper: npt.NDArray[np.float64], - sample_preionisation: npt.NDArray[np.float64], - sample_raman_rates: npt.NDArray[np.float64], - sample_material: dict[str, npt.NDArray[np.float64] | int], - spans: npt.NDArray[np.float64], - comp_predictor: npt.NDArray[np.float64], - comp_corrector: npt.NDArray[np.float64], - comp_rows: npt.NDArray[np.float64], - rate: npt.NDArray[np.float64], - carrier: npt.NDArray[np.float64], - ) -> npt.NDArray[np.float64]: ... def adams_stage_tables(self, tables: dict[str, object]) -> None: ... - def has_stage_tables(self) -> bool: ... - def adams_exponential_trial_at( - self, - z: float, - dz: float, - nodes: npt.NDArray[np.float64], - slots: npt.NDArray[np.uint64], - order: int, - orders: list[int], - compensated: bool, - carrier: npt.NDArray[np.float64], - ) -> npt.NDArray[np.float64]: ... - def adams_stage_scalars(self, z0: float, z1: float) -> dict[str, list[float]]: ... def adams_march_configure( self, policy: dict[str, object], @@ -435,19 +312,6 @@ class State: steps: npt.NDArray[np.float64], edges: npt.NDArray[np.float64], ) -> None: ... - def adams_fused_trial_at( - self, - z: float, - dz: float, - nodes: npt.NDArray[np.float64], - slots: npt.NDArray[np.uint64], - order: int, - orders: list[int], - ) -> npt.NDArray[np.float64]: ... - def adams_march_run( - self, state: dict[str, object], bounds: dict[str, object] - ) -> dict[str, Any]: ... - def adams_march_fault(self, stage: str, after: int, category: str) -> None: ... def bind_host_source(self, owner: object | None) -> None: ... def rk_march_configure( self, @@ -458,9 +322,6 @@ class State: steps: npt.NDArray[np.float64], edges: npt.NDArray[np.float64], ) -> None: ... - def rk_march_run( - self, state: dict[str, object], bounds: dict[str, object] - ) -> dict[str, Any]: ... def low_storage_configure( self, flows: int, separable: bool, origin: float ) -> None: ... @@ -479,23 +340,7 @@ class State: max_squarings: int, allowance: float, ) -> None: ... - def adams_stage_rate(self, z: float) -> list[float]: ... - def adams_exponential_accept( - self, dz: float, free: int, dense: npt.NDArray[np.uint64], interpolate: bool - ) -> None: ... - def adams_exponential_observe( - self, - xi: float, - dz: float, - coefficients: npt.NDArray[np.float64], - dense_weight: npt.NDArray[np.float64], - dense_theta: npt.NDArray[np.float64], - carrier: npt.NDArray[np.float64], - ) -> None: ... - def adams_hold(self) -> None: ... - def adams_restore(self) -> None: ... def adams_row_names(self) -> list[str]: ... - def adams_rows_to_host(self, name: str) -> npt.NDArray[np.complex128]: ... def adams_rows_from_host( self, name: str, rows: npt.NDArray[np.complex128] ) -> None: ... @@ -507,36 +352,15 @@ class State: upper: float, coefficients: npt.NDArray[np.complex128], ) -> None: ... - def table_evaluate( - self, slots: npt.NDArray[np.uint64], positions: npt.NDArray[np.float64] - ) -> None: ... - def table_rate(self, slot: int, z: float, before: bool) -> None: ... def table_slots( self, phi: bool, prefactor: bool, slots: int, rate: bool ) -> None: ... def table_load(self, positions: list[float]) -> list[int]: ... - def table_rate_at(self, z: float, before: bool) -> None: ... def table_evaluations(self) -> int: ... def table_terms_to_host( self, kind: str, slot: int ) -> npt.NDArray[np.complex128]: ... - def phase_sum_to_host( - self, weights: npt.NDArray[np.float64] - ) -> npt.NDArray[np.complex128]: ... - def adams_observe( - self, - weights: npt.NDArray[np.float64], - phi_delta: npt.NDArray[np.float64], - phi_at: npt.NDArray[np.float64], - prefactor: npt.NDArray[np.float64], - density: npt.NDArray[np.float64], - taper: npt.NDArray[np.float64], - preionisation: npt.NDArray[np.float64], - raman_rates: npt.NDArray[np.float64], - material: dict[str, npt.NDArray[np.float64] | int], - ) -> None: ... def finish(self, dz: float) -> None: ... - def promote_fsal(self) -> None: ... def clear_fsal(self) -> None: ... def set_absorber_quiet(self, quiet: bool) -> None: ... def bind_monitor( @@ -546,7 +370,6 @@ class State: ) -> None: ... def unbind_monitor(self) -> None: ... def bind_occupancy(self, buckets: npt.NDArray[np.uint8], count: int) -> None: ... - def monitor_reading(self) -> npt.NDArray[np.float64]: ... def field_to_host(self) -> npt.NDArray[np.complex128]: ... def bind_edge( self, @@ -578,8 +401,6 @@ class State: npt.NDArray[np.float64], npt.NDArray[np.float64], npt.NDArray[np.float64], float ]: ... def set_crossing_workers(self, workers: int) -> None: ... - def stage_to_host(self, stage: int) -> npt.NDArray[np.complex128]: ... - def projected_to_host(self, coarse: bool = False) -> npt.NDArray[np.complex128]: ... @property def dispersive_path(self) -> dict[str, bool]: ... def memory_ledger(self) -> dict[str, int]: ... @@ -605,8 +426,6 @@ class State: def rk_source_evaluations(self) -> int: ... @property def axis_scans(self) -> int: ... - @property - def quadrature_error(self) -> float: ... def quadrature_peak(self) -> float: ... @property def synthesis_provider(self) -> str: ... @@ -622,41 +441,9 @@ class State: def build_record() -> dict[str, str | bool | int | None]: ... def export_fftw_wisdom() -> str | None: ... -def import_fftw_wisdom(text: str) -> bool: ... def fit_blas_threads(threads: int) -> str: ... def register_host_blas() -> None: ... def rk_score(partials: npt.NDArray[np.float64], rtol: float, atol: float) -> float: ... -def half_width( - t: npt.NDArray[np.float64], power: npt.NDArray[np.float64], outer: bool -) -> float: ... -def strict_witness( - a: float, b: float, c: float -) -> tuple[float, float, float, float, float, float, float, float, float, float]: ... -def radial_fluence_widths( - radius: npt.NDArray[np.float64], - fluence: npt.NDArray[np.float64], - weights: npt.NDArray[np.float64], - axis_fluence: float, - e2_fraction: float, -) -> tuple[float, float, float]: ... -def fluence_block_widths( - plan: StatisticsPlan, block: npt.NDArray[np.float64] -) -> tuple[float, float, float]: ... -def line_fluence_widths( - x: npt.NDArray[np.float64], samples: npt.NDArray[np.float64], e2_fraction: float -) -> tuple[float, float, float]: ... -def watch_check( - policy: dict[str, object], - state: dict[str, object], - reading: npt.NDArray[np.float64], - z: float, -) -> dict[str, Any]: ... -def watch_due( - policy: dict[str, object], state: dict[str, object], z: float -) -> bool: ... -def watch_split_limit( - policy: dict[str, object], occupancy: npt.NDArray[np.float64] -) -> float: ... def initialize_runtime( threads: int, kernels: int = 0, @@ -665,16 +452,9 @@ def initialize_runtime( raman_tail_fft: int = 0, band_tiles: int = -1, ) -> None: ... -def reference_fft3_pairs( - values: npt.NDArray[np.complex128], warm: int, pairs: int -) -> list[float]: ... def reference_stream_copies(elements: int, warm: int, repeats: int) -> list[float]: ... def time_fft_plan(key: str, wisdom: str, effort: str) -> dict[str, float]: ... -def forget_fftw_wisdom() -> None: ... -def scoped_openmp_default() -> int: ... def configure_native_spin(milliseconds: int) -> None: ... -def scoped_block_time() -> int: ... -def shutdown_runtime() -> None: ... @overload def clenshaw_points( z: npt.NDArray[np.float64], @@ -713,19 +493,6 @@ def trial_tables( endpoint: npt.NDArray[np.float64], defects: npt.NDArray[np.float64], ) -> None: ... -def vector_exp(x: npt.NDArray[np.float64], out: npt.NDArray[np.float64]) -> None: ... -def vector_log(x: npt.NDArray[np.float64], out: npt.NDArray[np.float64]) -> None: ... -def vector_sincos( - x: npt.NDArray[np.float64], - sine: npt.NDArray[np.float64], - cosine: npt.NDArray[np.float64], -) -> None: ... -def vector_exp_complex( - a: npt.NDArray[np.float64], - b: npt.NDArray[np.float64], - real: npt.NDArray[np.float64], - imag: npt.NDArray[np.float64], -) -> None: ... def available_device_memory() -> int | None: ... class EnvelopeConvergenceError(RuntimeError): ... @@ -867,87 +634,3 @@ class Session: ) -> npt.NDArray[np.complex128]: ... def fail_outside(self) -> SessionBatch | None: ... def close(self) -> None: ... - -class TransverseEdge: - def __init__(self, config: dict[str, object]) -> None: ... - def resume(self, record: dict[str, object]) -> None: ... - def launch( - self, - reading: dict[str, object], - z: float, - sums: tuple[float, float] | None = None, - noise: dict[str, object] | None = None, - ) -> dict[str, Any]: ... - def read( - self, - reading: dict[str, object], - z: float, - sums: tuple[float, float] | None = None, - ) -> dict[str, Any]: ... - def proceed(self) -> dict[str, Any]: ... - def step(self, current: float, z: float) -> None: ... - def ceiling(self) -> float: ... - def due(self, z: float, proposal: float) -> bool: ... - def wants_read(self, z: float) -> bool: ... - def launch_sums(self, columns: npt.NDArray[np.float64]) -> tuple[float, float]: ... - def read_sums(self, gap: float) -> tuple[float, float]: ... - def record(self) -> dict[str, Any]: ... - @property - def next_read(self) -> float: ... - @property - def every_step(self) -> bool: ... - @property - def resumed(self) -> bool: ... - @property - def pending(self) -> bool: ... - @property - def status(self) -> int: ... - -class Monitor: - def __init__(self, config: dict[str, object]) -> None: ... - def resume( - self, - record: dict[str, object], - plane: bool, - unwatched: list[list[float]], - ) -> None: ... - def launch( - self, - reading: npt.NDArray[np.float64], - z: float, - floor: float = 0.0, - floor_regions: npt.NDArray[np.float64] | None = None, - ) -> dict[str, Any]: ... - def due(self, z: float) -> bool: ... - def skip(self, z: float) -> None: ... - def step( - self, reading: npt.NDArray[np.float64], z: float, plane: bool = False - ) -> dict[str, Any]: ... - def plane(self, z: float) -> None: ... - def note_collar(self, left_out: bool) -> None: ... - def finish(self) -> dict[str, Any]: ... - def record(self) -> dict[str, Any]: ... - def watch_state(self) -> dict[str, Any]: ... - @property - def stale(self) -> bool: ... - @property - def collar_quiet(self) -> bool: ... - @property - def step_cap(self) -> float: ... - @property - def rests(self) -> bool: ... - def steps_to_check(self) -> int: ... - -class ScriptedMarch: - def __init__( - self, - policy: dict[str, object], - norms: npt.NDArray[np.float64], - carrier_rate: float, - steps: npt.NDArray[np.float64], - edges: npt.NDArray[np.float64], - ) -> None: ... - def run( - self, state: dict[str, object], bounds: dict[str, object] - ) -> dict[str, Any]: ... - def log(self) -> list[dict[str, Any]]: ... diff --git a/native/src/solprop_native/_core_testing.pyi b/native/src/solprop_native/_core_testing.pyi new file mode 100644 index 000000000..1223c0371 --- /dev/null +++ b/native/src/solprop_native/_core_testing.pyi @@ -0,0 +1,310 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +# The private test module `solprop_native._core._testing` (solprop SEP 52 section 6.5), +# imported as `from solprop_native._core import _testing`: the entry points only +# solprop's own tests reach. A `State` method that moved here takes the state first. +# `native/scripts/problem_stub.py --check` holds the names here to the module's. + +from __future__ import annotations + +from typing import Any + +import numpy as np +import numpy.typing as npt + +from solprop_native._core import State, StatisticsPlan + +def trial_step( + state: State, + dz: float, + phi_delta: npt.NDArray[np.float64], + phi_at: npt.NDArray[np.float64], + prefactor: npt.NDArray[np.float64], + density: npt.NDArray[np.float64], + taper: npt.NDArray[np.float64], + preionisation: npt.NDArray[np.float64], + raman_rates: npt.NDArray[np.float64], + material: dict[str, npt.NDArray[np.float64] | int] | None = None, + prepare_only: bool = False, +) -> npt.NDArray[np.float64]: ... +def adopt(state: State, field: npt.NDArray[np.complex128], dz: float) -> None: ... +def stage_to_host(state: State, stage: int) -> npt.NDArray[np.complex128]: ... +def projected_to_host( + state: State, coarse: bool = False +) -> npt.NDArray[np.complex128]: ... +def weighted_error( + state: State, scale: npt.NDArray[np.float64] +) -> npt.NDArray[np.float64]: ... +def form_flow_actions( + state: State, section: int, dz: float, fractions: npt.NDArray[np.float64] +) -> npt.NDArray[np.float64]: ... +def flow_actions_to_host(state: State, inverse: bool) -> npt.NDArray[np.complex128]: ... +def adams_block_to_host(state: State) -> npt.NDArray[np.complex128]: ... +def adams_exponent_to_host(state: State) -> npt.NDArray[np.complex128]: ... +def adams_exponential_trial( + state: State, + dz: float, + slots: npt.NDArray[np.uint64], + predictor: npt.NDArray[np.float64], + corrector: npt.NDArray[np.float64], + rows: npt.NDArray[np.float64], + divisor: npt.NDArray[np.float64], + phi_delta: npt.NDArray[np.float64], + phi_at: npt.NDArray[np.float64], + prefactor: npt.NDArray[np.float64], + density: npt.NDArray[np.float64], + taper: npt.NDArray[np.float64], + preionisation: npt.NDArray[np.float64], + raman_rates: npt.NDArray[np.float64], + material: dict[str, npt.NDArray[np.float64] | int], + sample_phi_delta: npt.NDArray[np.float64], + sample_phi_at: npt.NDArray[np.float64], + sample_prefactor: npt.NDArray[np.float64], + sample_density: npt.NDArray[np.float64], + sample_taper: npt.NDArray[np.float64], + sample_preionisation: npt.NDArray[np.float64], + sample_raman_rates: npt.NDArray[np.float64], + sample_material: dict[str, npt.NDArray[np.float64] | int], + spans: npt.NDArray[np.float64], + comp_predictor: npt.NDArray[np.float64], + comp_corrector: npt.NDArray[np.float64], + comp_rows: npt.NDArray[np.float64], + rate: npt.NDArray[np.float64], + carrier: npt.NDArray[np.float64], +) -> npt.NDArray[np.float64]: ... +def adams_exponential_trial_at( + state: State, + z: float, + dz: float, + nodes: npt.NDArray[np.float64], + slots: npt.NDArray[np.uint64], + order: int, + orders: list[int], + compensated: bool, + carrier: npt.NDArray[np.float64], +) -> npt.NDArray[np.float64]: ... +def adams_exponential_accept( + state: State, dz: float, free: int, dense: npt.NDArray[np.uint64], interpolate: bool +) -> None: ... +def adams_start( + state: State, + slot: int, + phi_delta: npt.NDArray[np.float64], + phi_at: npt.NDArray[np.float64], + prefactor: npt.NDArray[np.float64], + density: npt.NDArray[np.float64], + taper: npt.NDArray[np.float64], + preionisation: npt.NDArray[np.float64], + raman_rates: npt.NDArray[np.float64], + material: dict[str, npt.NDArray[np.float64] | int], +) -> None: ... +def adams_compensation_start( + state: State, slot: int, rate: npt.NDArray[np.float64] +) -> None: ... +def adams_hold(state: State) -> None: ... +def adams_restore(state: State) -> None: ... +def adams_rows_to_host(state: State, name: str) -> npt.NDArray[np.complex128]: ... +def adams_stage_scalars( + state: State, z0: float, z1: float +) -> dict[str, list[float]]: ... +def adams_stage_rate(state: State, z: float) -> list[float]: ... +def has_stage_tables(state: State) -> bool: ... +def table_rate_at(state: State, z: float, before: bool) -> None: ... +def phase_sum_to_host( + state: State, weights: npt.NDArray[np.float64] +) -> npt.NDArray[np.complex128]: ... +def promote_fsal(state: State) -> None: ... +def adams_march_run( + state: State, march: dict[str, object], bounds: dict[str, object] +) -> dict[str, Any]: ... +def rk_march_run( + state: State, march: dict[str, object], bounds: dict[str, object] +) -> dict[str, Any]: ... +def adams_march_fault(state: State, stage: str, after: int, category: str) -> None: ... +def statistics( + state: State, + flags: int, + windows: npt.NDArray[np.float64], + on_axis: npt.NDArray[np.float64], + density: float, + taper: float, + preionisation: float, + intensity_factor: float, + channel_preionisation: npt.NDArray[np.float64] | None = None, + power_weight: npt.NDArray[np.float64] | None = None, +) -> npt.NDArray[np.float64]: ... +def spatial_statistics( + state: State, flags: int, intensity_factor: float, z: float +) -> npt.NDArray[np.float64]: ... +def planned_statistics( + state: State, plan: StatisticsPlan, z: float +) -> npt.NDArray[np.float64]: ... +def plane_fluence_trace( + state: State, + center_x: float, + center_y: float, + dx: float, + dy: float, + extent: float, + spacing: float, + n_radii: int, + cosines: npt.NDArray[np.float64], + sines: npt.NDArray[np.float64], +) -> npt.NDArray[np.float64]: ... +def axis_spectrum( + state: State, matrix: npt.NDArray[np.float64] +) -> npt.NDArray[np.complex128]: ... +def monitor_reading(state: State) -> npt.NDArray[np.float64]: ... +def quadrature_error(state: State) -> float: ... +def watch_check( + policy: dict[str, object], + state: dict[str, object], + reading: npt.NDArray[np.float64], + z: float, +) -> dict[str, Any]: ... +def watch_due( + policy: dict[str, object], state: dict[str, object], z: float +) -> bool: ... +def watch_split_limit( + policy: dict[str, object], occupancy: npt.NDArray[np.float64] +) -> float: ... +def half_width( + t: npt.NDArray[np.float64], power: npt.NDArray[np.float64], outer: bool +) -> float: ... +def strict_witness( + a: float, b: float, c: float +) -> tuple[float, float, float, float, float, float, float, float, float, float]: ... +def radial_fluence_widths( + radius: npt.NDArray[np.float64], + fluence: npt.NDArray[np.float64], + weights: npt.NDArray[np.float64], + axis_fluence: float, + e2_fraction: float, +) -> tuple[float, float, float]: ... +def fluence_block_widths( + plan: StatisticsPlan, block: npt.NDArray[np.float64] +) -> tuple[float, float, float]: ... +def line_fluence_widths( + x: npt.NDArray[np.float64], samples: npt.NDArray[np.float64], e2_fraction: float +) -> tuple[float, float, float]: ... +def reference_fft3_pairs( + values: npt.NDArray[np.complex128], warm: int, pairs: int +) -> list[float]: ... +def scoped_openmp_default() -> int: ... +def scoped_block_time() -> int: ... +def forget_fftw_wisdom() -> None: ... +def import_fftw_wisdom(text: str) -> bool: ... +def vector_exp(x: npt.NDArray[np.float64], out: npt.NDArray[np.float64]) -> None: ... +def vector_log(x: npt.NDArray[np.float64], out: npt.NDArray[np.float64]) -> None: ... +def vector_sincos( + x: npt.NDArray[np.float64], + sine: npt.NDArray[np.float64], + cosine: npt.NDArray[np.float64], +) -> None: ... +def vector_exp_complex( + a: npt.NDArray[np.float64], + b: npt.NDArray[np.float64], + real: npt.NDArray[np.float64], + imag: npt.NDArray[np.float64], +) -> None: ... + +class TransverseEdge: + def __init__(self, config: dict[str, object]) -> None: ... + def resume(self, record: dict[str, object]) -> None: ... + def launch( + self, + reading: dict[str, object], + z: float, + sums: tuple[float, float] | None = None, + noise: dict[str, object] | None = None, + ) -> dict[str, Any]: ... + def read( + self, + reading: dict[str, object], + z: float, + sums: tuple[float, float] | None = None, + ) -> dict[str, Any]: ... + def proceed(self) -> dict[str, Any]: ... + def step(self, current: float, z: float) -> None: ... + def ceiling(self) -> float: ... + def due(self, z: float, proposal: float) -> bool: ... + def wants_read(self, z: float) -> bool: ... + def launch_sums(self, columns: npt.NDArray[np.float64]) -> tuple[float, float]: ... + def read_sums(self, gap: float) -> tuple[float, float]: ... + def record(self) -> dict[str, Any]: ... + @property + def next_read(self) -> float: ... + @property + def every_step(self) -> bool: ... + @property + def resumed(self) -> bool: ... + @property + def pending(self) -> bool: ... + @property + def status(self) -> int: ... + +class Monitor: + def __init__(self, config: dict[str, object]) -> None: ... + def resume( + self, + record: dict[str, object], + plane: bool, + unwatched: list[list[float]], + ) -> None: ... + def launch( + self, + reading: npt.NDArray[np.float64], + z: float, + floor: float = 0.0, + floor_regions: npt.NDArray[np.float64] | None = None, + ) -> dict[str, Any]: ... + def due(self, z: float) -> bool: ... + def skip(self, z: float) -> None: ... + def step( + self, reading: npt.NDArray[np.float64], z: float, plane: bool = False + ) -> dict[str, Any]: ... + def plane(self, z: float) -> None: ... + def note_collar(self, left_out: bool) -> None: ... + def finish(self) -> dict[str, Any]: ... + def record(self) -> dict[str, Any]: ... + def watch_state(self) -> dict[str, Any]: ... + @property + def stale(self) -> bool: ... + @property + def collar_quiet(self) -> bool: ... + @property + def step_cap(self) -> float: ... + @property + def rests(self) -> bool: ... + def steps_to_check(self) -> int: ... + +class ScriptedMarch: + def __init__( + self, + policy: dict[str, object], + norms: npt.NDArray[np.float64], + carrier_rate: float, + steps: npt.NDArray[np.float64], + edges: npt.NDArray[np.float64], + ) -> None: ... + def run( + self, state: dict[str, object], bounds: dict[str, object] + ) -> dict[str, Any]: ... + def log(self) -> list[dict[str, Any]]: ... + +class ScriptedRkMarch: + def __init__( + self, + policy: dict[str, object], + norms: npt.NDArray[np.float64], + h0: float, + steps: npt.NDArray[np.float64], + edges: npt.NDArray[np.float64], + ) -> None: ... + def run( + self, state: dict[str, object], bounds: dict[str, object] + ) -> dict[str, Any]: ... + def log(self) -> list[dict[str, Any]]: ... + def used(self) -> int: ... diff --git a/native/src/solprop_native/_counters.py b/native/src/solprop_native/_counters.py index ac4d584f0..e56b41d36 100644 --- a/native/src/solprop_native/_counters.py +++ b/native/src/solprop_native/_counters.py @@ -9,10 +9,10 @@ crossed to the host. Counting is off unless the benchmark worker turns it on: every hook reads :data:`active` once and does nothing while it is ``None``. A run that is not counted pays one attribute test per native march call, plane, statistics call, -edge read, field crossing or load, low-storage or group step and native session -``advance`` or export, and nothing per attempt: the two per-attempt hooks (solprop's -own loop's attempts and periodic rows) are installed on ``NativeBackend`` by -:func:`enable` and removed by :func:`disable`. Its numbers are unchanged either way. +edge read, field crossing or load, low-storage step and native session ``advance`` +or export, and nothing per attempt: the two per-attempt hooks (solprop's own loop's +attempts and periodic rows) are installed on ``NativeBackend`` by :func:`enable` and +removed by :func:`disable`. Its numbers are unchanged either way. The record covers the native execution session (:class:`~solprop_native.session.NativeSession`), which serves every native run since @@ -42,9 +42,7 @@ attempts, its periodic rows to the statistics rows and, with its plane statistics, to the statistics evaluations, and a non-launch observation to the planes; the session's own march calls inside the ``advance`` are counted from its status as - ``session_adams``, ``session_runge_kutta`` or ``session_low_storage``. Members of - the native group session (``solprop_native.group``) are native sessions and are - counted so; the group's common steps are counted among the group steps. + ``session_adams``, ``session_runge_kutta`` or ``session_low_storage``. - **Planes** (calls of ``propagate_to`` on the bridge; non-launch observations of a session), **statistics rows** (periodic rows, taken by solprop's loop on the bridge and natively in a session) and **statistics evaluations** (rows and plane @@ -100,9 +98,6 @@ class Counters: Accepted steps among them. low_storage_steps : int Low-storage engine steps, among the host attempts. - group_steps : int - Common steps of the native group session, which returns per window, not per - step. planes : int ``propagate_to`` calls, or a native session's observations: one per saved plane after the launch. @@ -131,7 +126,6 @@ class Counters: host_attempts: int = 0 host_accepted: int = 0 low_storage_steps: int = 0 - group_steps: int = 0 planes: int = 0 statistics_rows: int = 0 statistics_evaluations: int = 0 @@ -195,10 +189,6 @@ def session_batch( if calls: self.march_calls[march] += calls - def group_window(self, steps: int) -> None: - """Count the common steps of one window of the native group session.""" - self.group_steps += steps - def crossing(self, where: str, nbytes: int) -> None: """Count one field copied to the host.""" self.field_crossings[where] += 1 @@ -232,7 +222,6 @@ def record(self) -> dict[str, object]: "march_attempts": self.march_attempts, "host_attempts": self.host_attempts, "low_storage_steps": self.low_storage_steps, - "group_steps": self.group_steps, "planes": self.planes, "statistics_rows": self.statistics_rows, "statistics_evaluations": self.statistics_evaluations, diff --git a/native/src/solprop_native/backend.py b/native/src/solprop_native/backend.py index 9cd3ec518..124ee6c7a 100644 --- a/native/src/solprop_native/backend.py +++ b/native/src/solprop_native/backend.py @@ -13,7 +13,7 @@ import math import types import weakref -from collections.abc import Callable, Mapping, Sequence +from collections.abc import Mapping, Sequence from importlib.metadata import version from pathlib import Path from types import TracebackType @@ -22,7 +22,6 @@ import numpy as np import numpy.typing as npt from solprop import transverse_monitor -from solprop._helpers import Helpers from solprop._process import acquire_host_blas, thread_budget from solprop.backends import tdse_source from solprop.backends.exponential import ( @@ -44,11 +43,10 @@ general_planned_chunk, plan_node_chunk, ) -from solprop.backends.protocol import Backend, TimingProbe +from solprop.backends.protocol import TimingProbe from solprop.backends.session import ( ExecutionOptions, PreparedExecution, - PreparedGroup, Start, ) from solprop.backends.spatial import ( @@ -81,8 +79,6 @@ from solprop.stepper.multistep import ( MarchPolicy, Multistep, - integrated_weights, - lagrange_coefficients, march_policy, ) from solprop.translate.chebyshev import ( @@ -104,7 +100,6 @@ from solprop.translate.linop import ( delta_phi, power_weight_at, - rate_weights, unitary_phase, ) from solprop.translate.plasma_source import ( @@ -296,7 +291,6 @@ class NativeBackend: """ name = "native" - max_batch = 1 helpers = NATIVE far_field_statistics: ClassVar[frozenset[str]] = frozenset(FAR_FIELD_STATISTICS) """The far-field statistics of solprop SEP 23 this build forms natively. @@ -660,13 +654,7 @@ def _adams_engine( native=self._native_state, method=method, controller=self._stepper.controller, - n_omega=self._problem.grids.n_omega, - arrays=self._resident_arrays, - hoist=self._hoist, - adopted=_adopt_nothing, - rate=self._rate_weights, shape=self._layout, - helpers=self.helpers, compensated=compensated, interpolate=self._stepper.interpolate_planes, carrier=carrier_reference(self._problem, method), @@ -781,63 +769,6 @@ def _propagator_mode(self) -> PropagatorMode: """ return propagator_mode(self._problem, self._stepper, device=_on_device()) - def _resident_arrays(self, anchor: float, position: float) -> _TrialArrays: - """Return a resident trial's arrays, every stage row at `position`.""" - bundle = self._stage_scalars(anchor, position) - self._last_bundle = bundle - stages = self._stepper.tableau.n_stages - arrays, material = self._repeated_arrays(bundle) - flow = self._flow - if flow is not None: - # Beside a coupled flow the trial's section and a frozen-residual flow's - # weights at `position`; the resident passes need no Runge-Kutta action. - material |= { - "flow_section": bundle.flow_section, - "flow_weights": np.empty(0, dtype=np.float64) - if flow.residual_terms is None - else np.ascontiguousarray( - np.tile(_required(bundle.flow_weights, "flow_weights"), stages), - dtype=np.float64, - ), - } - return arrays, material - - def _repeated_arrays(self, bundle: StageScalars) -> _TrialArrays: - """Return the trial arrays of a step whose every stage row is `bundle`. - - `_trial_arrays` of the bundle repeated, value for value. With the weights a - constant's or an expansion's own and no further material rows (SEP 6's - channels, a moving guide's maps), each array is one row repeated in one call - rather than packed from a list of the same bundle, which costs a resident - Adams trial more than its coefficient tables. The other problems take - `_trial_arrays`. - """ - stages = self._stepper.tableau.n_stages - if ( - self._z_tables is not None - or self._terms.separable is not None - or self._problem.responses.dispersive_kerr is not None - or self._moving_maps - ): - return self._trial_arrays([bundle] * stages, bundle) - phi_delta = _required(bundle.phi_delta, "phi_delta")[np.newaxis] - phi_at = _required(bundle.phi_at, "phi_at")[np.newaxis] - prefactor = _required(bundle.prefactor, "prefactor")[np.newaxis] - return ( - np.repeat(phi_delta, stages + 1, axis=0), - np.repeat(phi_at, stages, axis=0), - np.repeat(prefactor, stages, axis=0), - np.full(stages, bundle.density, dtype=np.float64), - np.full(stages, bundle.taper_scale, dtype=np.float64), - np.full(stages, bundle.preionisation, dtype=np.float64), - _repeated_row(bundle.raman_rates, stages), - ), { - "kerr_density": np.full(stages, bundle.kerr_density, dtype=np.float64), - "plasma_densities": _repeated_row(bundle.plasma_densities, stages), - "plasma_preionisation": _repeated_row(bundle.plasma_preionisation, stages), - "raman_densities": _repeated_row(bundle.raman_densities, stages), - } - def _trial_step(self, z: float, dz: float) -> tuple[float, _core.State]: partials = self._prepare_trial(z, dz) return self._score_trial(partials), self._native_state @@ -1002,20 +933,6 @@ def _phi_increment(self, z0: float, z1: float) -> RealArray: return tables.phi_row(tables.load([z0, z1]), z0, z1) return _required(self._stage_scalars(z0, z1).phi_delta, "phi_delta") - def _rate_weights(self, z: float, *, before: bool = False) -> RealArray: - """Return ``D(z)``'s weights over the native ``Phi`` terms (solprop SEP 16). - - solprop's :func:`~solprop.translate.linop.rate_weights` for a constant or an - expansion; for a z table, the rate table evaluated natively into its slot - (solprop SEP 29 G1). - """ - tables = self._z_tables - if tables is not None and tables.phi: - return tables.rate(z, before=before) - return rate_weights( - self._problem.linear, z, before=before, helpers=self.helpers - ) - def _delta_phi(self, bundle: StageScalars) -> ComplexArray: """Return the stage's exponent on the host, a z table's from its native slots. @@ -1559,36 +1476,6 @@ def prepare( return NativePrepared(self, problem, request) - def prepare_group( - self, - members: Sequence[Backend], - problems: Sequence[PropagationProblem], - requests: Sequence[RunRequest], - ) -> PreparedGroup: - """Prepare a group of compatible native members (SEP 47 section 6.7). - - Its start opens the native group session - (:class:`solprop_native.group.NativePreparedGroup`), which refuses by name a - group it does not run. - - Parameters - ---------- - members : sequence of solprop.backends.protocol.Backend - One constructed native backend per member, this one first. - problems : sequence of solprop.translate.problem.PropagationProblem - Each member's independently translated problem. - requests : sequence of solprop.translate.run_request.RunRequest - Each member's run request. - - Returns - ------- - solprop.backends.session.PreparedGroup - The prepared group. - """ - from .group import NativePreparedGroup - - return NativePreparedGroup(members, problems, requests) - def close(self) -> None: """Release native plans and views; repeated calls have no effect.""" if not self._closed: @@ -1606,14 +1493,6 @@ def close(self) -> None: self._closed = True -def _adopt_nothing(z: float | None) -> None: - """Adopt nothing: the backend keeps no march state beside the native state. - - - ``z``: where the engine's state moved, m; unused. - """ - del z - - @dataclasses.dataclass(frozen=True) class _BuildFacts: """The parts of a backend's metadata that are fixed for the process.""" @@ -1642,11 +1521,6 @@ def _build_facts() -> _BuildFacts: ) -def _repeated_row(values: tuple[float, ...], count: int) -> RealArray: - """Return a stage row of host scalars repeated `count` times, ``(count, n)``.""" - return np.repeat(np.array([values], dtype=np.float64), count, axis=0) - - def _required(values: RealArray | None, name: str) -> RealArray: if values is None: raise BackendError(f"device-ready problem has no {name}") @@ -1669,59 +1543,33 @@ def _require_initial_array(field: object, shape: tuple[int, ...]) -> None: # 42), and the driver's load copies the field into a contiguous state first. -type _TrialArrays = tuple[ - tuple[RealArray, RealArray, RealArray, RealArray, RealArray, RealArray, RealArray], - dict[str, npt.NDArray[np.float64] | int], -] - - @dataclasses.dataclass class _ResidentAdams: """solprop's Adams history kept in the native state (solprop SEP 16 phase 3b). - The native Adams march's engine (the reference's ``AdamsEngine``, in - ``solprop.backends.numpy_ref.multistep``): the history's rows, a trial's predictor, - its source, the corrected field and the defect norms, the adoption and transport of - an accepted step and dense observation run in the engine, with only the trial's - scalars, coefficient tables and norms crossing. solprop's host engine - (``HostHistory``) is its reference. The backend hands it the native state and three - of its own operations. + The native Adams march (solprop SEP 39) takes its trials, accepts, start-up and + dense observations in C++ (``adams_march.cpp``, ``dense.cpp``); this record holds + what Python still does with the history: it allocates the rows and sets the + controller's scale when it is built, and copies a resumed snapshot's rows in + (:meth:`load_rows`). A session snapshot copies them out natively + (``Session.march_snapshot``). """ native: _core.State method: Multistep controller: PIController - n_omega: int - arrays: Callable[[float, float], _TrialArrays] - """``(anchor, position) -> trial arrays`` with every stage row at `position`.""" - hoist: Callable[[float], None] - adopted: Callable[[float | None], None] - """Make the native state the backend's, at a new position when one is given.""" - rate: Callable[..., RealArray] - """``(z, *, before=False) -> D(z)``'s weights over the native ``Phi`` terms.""" shape: tuple[int, ...] """The state layout, ``(1, n_modes, n_pol, n_omega)``.""" - helpers: Helpers - """The backend's Chebyshev and Adams-basis helpers (``NativeBackend.helpers``).""" interpolate: bool compensated: bool = False """Whether trials carry a varying operator's transported compensation.""" carrier: CarrierReference | None = None - """The run's carrier frame (solprop SEP 35): its shift is formed on the host from - the reference element's chord, one scalar a trial, and nothing is read back.""" - dense: None = None - _trial: tuple[float, float, list[float], npt.NDArray[np.int64], int] | None = None - _step: tuple[float, float, npt.NDArray[np.float64]] | None = None - _exponential: bool = False - _coefficients: npt.NDArray[np.float64] | None = None - _dense_nodes: npt.NDArray[np.float64] | None = None - _trial_carrier: RealArray = dataclasses.field(default_factory=lambda: _NO_CARRIER) - _dense_carrier: RealArray = dataclasses.field(default_factory=lambda: _NO_CARRIER) + """The run's carrier frame (solprop SEP 35), whose chord tables the native state + reads (:func:`_chord_tables`).""" def __post_init__(self) -> None: """Allocate the history's rows in the native state.""" self.native.adams_allocate(self.n_slots, self.compensated, self.interpolate) - self._exponential = self.method.formulation == "exponential" # The controller's scale is formed on the device each trial, so that the # state's magnitude never crosses: it is solprop's own, since PIController # is final (ADR-077). @@ -1740,83 +1588,8 @@ def n_slots(self) -> int: """The history's rows: the method's order and two more.""" return self.method.order + 2 - def march_stepped( - self, - step: tuple[float, float, list[float]] | None, - *, - fused: bool, - carrier: Sequence[float], - ) -> None: - """Adopt what a native march call leaves (solprop SEP 39 phase 2). - - No trial is held, and the last accepted step's anchor, step and nodes ``(1, - theta...)``, if the call accepted one, set the dense observation's - interpolant: the fused path's nodes, or the exponential corrector's - coefficients on them, with the step's carrier rotations. - """ - self._trial = None - if step is not None: - z, dz, nodes = step - interpolant = ( - np.array(nodes) - if fused - else lagrange_coefficients(nodes, check=False, helpers=self.helpers) - ) - self._step = (z, dz, interpolant) if self.interpolate else None - self._dense_nodes = np.array(nodes) - self._dense_carrier = ( - np.asarray(carrier, dtype=np.float64) if carrier else _NO_CARRIER - ) - self.adopted(None) - def reset(self) -> None: - """Forget the last accepted step and any trial in flight.""" - self._trial = None - self._step = None - self._dense_carrier = _NO_CARRIER - - def _carrier(self, z: float, dz: float, nodes: list[float], rows: int) -> RealArray: - """Return a trial's packed carrier frame, empty without one. - - ``(Im sigma, Re f_0, Im f_0, ...)`` over the `rows` history rows the trial - reads, ``f_t = exp(sigma (1 - theta_t))``; ``sigma`` is the reference element's - chord over the step (solprop SEP 35 section 6.1), formed from the operator's - own representation, so a device build reads nothing back. - """ - carrier = self.carrier - if carrier is None or not carrier.active: - return _NO_CARRIER - assert carrier.chord is not None - # One batch member per native state. - shift = float(np.imag(carrier.chord.exponent(z, z + dz))[0]) - packed = np.empty(1 + 2 * rows, dtype=np.float64) - packed[0] = shift - # exp(i shift s) as NumPy's complex exponential forms it: exp(0) (cos + i sin). - spans = 1.0 - np.asarray(nodes[:rows], dtype=np.float64) - packed[1::2] = np.cos(shift * spans) - packed[2::2] = np.sin(shift * spans) - return packed - - def hold(self) -> object: - """Keep the accepted state aside in the engine across a dense observation.""" - self.native.adams_hold() - return None - - def restore(self, z: float, held: object) -> None: - """Make the held accepted state current again at `z`.""" - del held - self.native.adams_restore() - self.adopted(z) - - def start(self, z: float) -> None: - """Evaluate the history's first sample at the accepted state into row zero.""" - self.hoist(z) - arrays, material = self.arrays(z, z) - with _envelope_errors(): - self.native.adams_start(0, *arrays, material) - if self.compensated: - # The startup sample's state and rate, read on the far side of a kink. - self.native.adams_compensation_start(0, self.rate(z)) + """Forget the last step: the native march holds no trial between calls.""" def value(self, slot: int) -> None: """The rows are resident: there is no host row to name.""" @@ -1825,34 +1598,20 @@ def value(self, slot: int) -> None: # --- persistence across a resume (solprop SEP 29 G2) ------------------------------ def snapshot_nbytes(self) -> int: - """Return the bytes :meth:`snapshot_rows` would copy, copying nothing.""" + """Return the bytes a snapshot of the rows copies, copying nothing.""" rows = len(self.native.adams_row_names()) return rows * self.n_slots * math.prod(self.shape) * 2 * 8 - def snapshot_rows(self) -> dict[str, ComplexArray]: - """Return host copies of the rows a resume needs to continue the history. - - The rows ``HostHistory`` also writes keep its names and layout, - ``(n_slots, n_batch, n_modes, n_pol, n_omega)``: ``"store"`` and, compensated, - ``"states"`` and ``"rates"``. A frozen-residual flow's history holds each - sample's generator applied to its state, ``"applied"``, where the host engine - holds the sample's weights (``"weights_"``); the two are not - interchangeable, and each engine refuses the other's. The copies are lossless. - Only the trial's scratch stays behind; the step's bookkeeping is the march's. - """ - expected = (self.n_slots, *self.shape) - return { - name: self.native.adams_rows_to_host(name).reshape(expected) - for name in self.native.adams_row_names() - } - def load_rows(self, rows: Mapping[str, np.ndarray], shape: tuple[int, ...]) -> None: - """Install rows `snapshot_rows` returned, for a state of `shape`. - - Everything is checked before any row is copied, so a refused snapshot leaves - the history as it was. The trial in flight and the last step's interpolant - are forgotten, as ``HostHistory.load_rows`` forgets them: the march's next step - is a new trial. + """Install a snapshot's rows, for a state of `shape`. + + The rows keep ``HostHistory``'s names and layout, ``(n_slots, n_batch, + n_modes, n_pol, n_omega)``: ``"store"`` and, compensated, ``"states"`` and + ``"rates"``. A frozen-residual flow's history holds each sample's generator + applied to its state, ``"applied"``, where the host engine holds the sample's + weights (``"weights_"``); the two are not interchangeable, and each engine + refuses the other's. Everything is checked before any row is copied, so a + refused snapshot leaves the history as it was. """ names = self.native.adams_row_names() weights = sorted(name for name in rows if name.startswith("weights_")) @@ -1880,160 +1639,12 @@ def load_rows(self, rows: Mapping[str, np.ndarray], shape: tuple[int, ...]) -> N f"the snapshot's {name!r} rows ({row.dtype}, shape {row.shape}) do " f"not fit the native backend's complex store of shape {expected}" ) - self.reset() for name in names: flat = np.ascontiguousarray(rows[name], dtype=np.complex128) self.native.adams_rows_from_host( name, flat.reshape(self.n_slots, -1, shape[-1]) ) - def fused_trial( - self, - z: float, - dz: float, - nodes: list[float], - slots: npt.NDArray[np.int64], - order: int, - orders: list[int], - ) -> RealArray: - """Form an interaction-formulation trial natively; return its scored norms. - - The native state forms the tables and the stage scalars from the nodes alone - (solprop SEP 39 phase 3), by the same operations as the host's. - """ - with _envelope_errors(): - norms = self.native.adams_fused_trial_at( - z, - dz, - np.asarray(nodes, dtype=np.float64), - np.ascontiguousarray(slots[: max(max(orders), order)], dtype=np.uint64), - order, - list(orders), - ) - self._trial = (z, dz, nodes, slots, order) - return np.asarray(norms, dtype=np.float64).reshape(-1) - - def fused_accept( - self, keep: npt.NDArray[np.int64], free: int, *, interpolate: bool - ) -> None: - """Adopt the held trial in the engine; keep its interpolant there.""" - assert self._trial is not None - z, dz, nodes, slots, order = self._trial - self._trial = None - self.native.adams_fused_accept( - dz, - np.ascontiguousarray(keep, dtype=np.uint64), - free, - np.ascontiguousarray(slots[:order], dtype=np.uint64), - interpolate, - ) - self.adopted(None) - self._step = (z, dz, np.array([1.0, *nodes[:order]])) if interpolate else None - - def exponential_trial( - self, - z: float, - dz: float, - nodes: list[float], - slots: npt.NDArray[np.int64], - order: int, - orders: list[int], - ) -> RealArray: - """Form an exponential trial natively; return its scored norms. - - The step's exponent, flow and moments come from the trial's own arrays; the - predicted field's source is evaluated in the laboratory frame, at a trial - whose anchor is the step's end. The native state forms the tables, the stage - scalars and the rate from the nodes alone (solprop SEP 39 phase 1), by the - same operations as the host's: the coefficient tables - (``lagrange::trial_tables``), the stage scalars and the rate from the tables - uploaded once, and the divisor; the carrier frame's shift is the host's. A run - that interpolates its planes keeps the corrector's coefficients on the host for - its observations, from the same basis. - """ - width = 1 + max(orders) - carrier = self._carrier(z, dz, nodes, width - 1) - with _envelope_errors(): - norms = self.native.adams_exponential_trial_at( - z, - dz, - np.asarray(nodes, dtype=np.float64), - np.ascontiguousarray(slots[: max(width - 1, order)], dtype=np.uint64), - order, - list(orders), - self.compensated, - carrier, - ) - self._trial = (z, dz, nodes, slots, order) - self._trial_carrier = carrier - self._coefficients = ( - lagrange_coefficients( - [1.0, *nodes[:order]], check=False, helpers=self.helpers - ) - if self.interpolate - else _NO_COEFFICIENTS - ) - self._dense_nodes = np.array([1.0, *nodes[:order]]) - return np.asarray(norms, dtype=np.float64).reshape(-1) - - def exponential_accept( - self, keep: npt.NDArray[np.int64], free: int, *, interpolate: bool - ) -> None: - """Adopt the held trial in the engine; the new sample takes row `free`.""" - del keep # untransported samples are never re-anchored - assert self._trial is not None - z, dz, _, slots, order = self._trial - self._trial = None - self.native.adams_exponential_accept( - dz, - free, - np.ascontiguousarray(slots[:order], dtype=np.uint64), - interpolate, - ) - self.adopted(None) - coefficients = self._coefficients - assert coefficients is not None - self._step = (z, dz, coefficients) if interpolate else None - # The accepted step's shift and the rotations of the `order` history rows its - # interpolant reads, held across later trials and rejections. - trial = self._trial_carrier - self._dense_carrier = trial[: 1 + 2 * order] if trial.size else _NO_CARRIER - - def observe(self, position: float) -> object: - """Interpolate the last accepted step natively into the engine's state.""" - assert self._step is not None - z, dz, nodes = self._step - if self._exponential: - # `nodes` holds the accepted corrector's coefficients here; a varying - # operator's compensation is interpolated over the step's own samples. - xi = (position - z) / dz - weights = thetas = np.empty(0, dtype=np.float64) - if self.compensated: - assert self._dense_nodes is not None - thetas = self._dense_nodes - weights = integrated_weights( - thetas, xi, check=False, helpers=self.helpers - ) - self.native.adams_exponential_observe( - xi, - dz, - np.ascontiguousarray(nodes, dtype=np.float64).reshape(-1), - np.ascontiguousarray(weights, dtype=np.float64), - np.ascontiguousarray(thetas, dtype=np.float64), - np.ascontiguousarray(self._dense_carrier), - ) - return self.native - # The step's own derivative polynomial. - theta = (position - z) / dz - weights = dz * integrated_weights( - nodes, theta, check=False, helpers=self.helpers - ) - arrays, material = self.arrays(z, position) - self.native.adams_observe( - np.ascontiguousarray(weights, dtype=np.float64), *arrays, material - ) - return self.native - _EMPTY = np.empty(0, dtype=np.complex128) """No modified-noise realisation: the native state adds none.""" @@ -2041,12 +1652,6 @@ def observe(self, position: float) -> object: _NO_SCHEDULE = np.empty(0, dtype=np.float64) """The empty schedule of an adaptive march's configuration.""" -_NO_CARRIER = np.empty(0, dtype=np.float64) -"""The empty carrier frame: the native trial takes the unshifted arithmetic.""" - -_NO_COEFFICIENTS = np.empty((0, 0), dtype=np.float64) -"""The corrector's coefficients a staged trial keeps when no plane is interpolated.""" - _STAGE_CONSTANT = 1 _STAGE_EXPANSION = 2 _STAGE_TABLE = 3 @@ -2138,7 +1743,7 @@ def _on_device() -> bool: The budget is spent on the host plan's conservative inventory (twenty column buffers a Cartesian column, about three times the live buffers, solprop issue #349), so the live space-domain buffers take near a twelfth of the free bytes, leaving the rest for the -state, the march's registers and a scan's other members.""" +state and the march's registers.""" def device_node_chunk( @@ -2890,20 +2495,6 @@ def at_row(self, slot_of: Mapping[float, int], z: float, count: int) -> RealArra row[slot_of[z]] = 1.0 return row - def rate(self, z: float, *, before: bool) -> RealArray: - """Evaluate ``D(z)`` into the rate slot; return its weights over the terms. - - - ``z``: position, m. - - ``before``: read an interior breakpoint from the interval ending there. - - Returns: shape ``(n_phi,)``, one at the rate slot. - """ - assert self._native is not None - assert self.rate_slot is not None - self._native.table_rate_at(float(z), before) - row = np.zeros(self.n_phi) - row[self.rate_slot] = 1.0 - return row - def values(self, kind: Literal["phi", "prefactor"], z: float) -> ComplexArray: """Return a table's value at `z` on the host, from its native slot.""" assert self._native is not None diff --git a/native/src/solprop_native/group.py b/native/src/solprop_native/group.py deleted file mode 100644 index 0fe0edbb1..000000000 --- a/native/src/solprop_native/group.py +++ /dev/null @@ -1,853 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""The native group session: compatible members marched through one fixed schedule. - -:class:`NativeGroupSession` implements solprop's -:class:`~solprop.backends.session.GroupSession` (SEP 47 section 6.7) over one native -execution session per member (:class:`~solprop_native.session.NativeSession`). The -group owns its members explicitly, through their session protocol: each member's -native session is the one mutable owner of that member's trajectory -- its march, its -events and attempts, its periodic rows, its tickets and its boundary monitor -- and the -group only orders their advances, assembles each member's window from its chunks and -maps the group's tickets onto the members'. No member reaches another's state, and the -group reaches no private driver attribute. - -**The window.** One :meth:`~NativeGroupSession.advance` runs every running member to -the next save plane of the common schedule (the launch first, the completion last). -Members take their turns in rounds of at most :data:`ROUND_STEPS` common steps: each -running member advances that many steps in turn, natively and without returning to -Python between steps but at the session's bounded yields, before the next takes its -turn. The schedule is common, so after every round the running members stand at one -common step, and the group-wide stop token is polled there. - -**Failure** follows section 6.7. A boundary stop -- the monitor's error, or a boundary -warning raised as an error under the caller's filters -- ends its member alone, at the -point its own session reached, and the others go on. Any other failure of a member (a -non-finite norm, a step floor, a trial exception, an in-flight failure, a statistics -failure) ends the group: every member still running ends with that same error, at its -own committed position, with its own checkpoint eligibility. Members ahead of the -failing one in its round have already committed (and recorded) the steps of their turn; -no common cursor or rollback is invented. A failed window delivers each member's -attempts since its previous event in its terminal event, and no observation. - -**Tickets.** Each member's latest native batch stays pending until that member's next -turn (acknowledging the group's batch releases the group's tickets only), so a member -the group ended before its turn can still be exported at its committed state, and a -group ticket -- which names its member, since every member's shares one batch and -generation -- is served by that member's own pending ticket. A member with no batch of -its own pending when the group ends (one that never launched, or whose own advance -raised) has nothing to export, and its terminal event is poisoned. An exception that -escapes a member's advance ends the group failed like a member's own failure, the -chunks drained so far delivered; an interrupt then propagates, the group's failed batch -left pending. - -**Numerics.** A member's trajectory is its lone native session's: the march, the -monitor, the statistics and the export are the native session's own, so a member's -fields and statistics are those of the same problem run alone through the native -session -- bit for bit at one thread on the native CPU build. The members share the -schedule and nothing mutable; in particular they do not share a fused accepted update -(SEP 47 section 6.7 asks for coarse groups, not fused kernels). - -:func:`refusal` names what the group does not run, decided from the members' problems, -requests and starts before anything is allocated, and :class:`NativePreparedGroup`, the -native backend's prepared group (``NativeBackend.prepare_group``, which solprop's -``start_group`` calls), refuses it by name: a group is a shared fixed schedule (SEP 47 -section 6.7), so an adaptive member and members that do not share the schedule are -refused, as the lockstep group this replaced refused them, and so are step planes, -which the group's save-plane windows do not observe. A coupled flow is admitted: each -member's flow action and explicit residual are its own session's, so nothing of the -member's step is shared or fused. A batched scan never forms a refused group: it -requires a fixed schedule, refuses step planes and groups only points of one execution -layout. -""" - -from __future__ import annotations - -import dataclasses -from collections.abc import Mapping, Sequence -from typing import TYPE_CHECKING, Any, cast - -import numpy as np -from solprop.backends.events import ( - Eligibility, - Event, - ExportTicket, - GroupBatch, - ObservationReady, - Outcome, - Progress, - ServiceKind, - ServiceRequired, - Terminal, - emit_warning, - join_attempts, -) -from solprop.backends.session import ( - GroupSession, - SessionError, - SessionLedger, - SessionState, - SessionStatus, - check_group, - check_member_ticket, -) -from solprop.exceptions import BackendError, BoundaryError, StopRequested - -from . import _counters -from .backend import NativeBackend -from .session import NativeSession -from .session import refusal as member_session_refusal - -if TYPE_CHECKING: - from types import TracebackType - - import numpy.typing as npt - from solprop.backends.events import Receipt - from solprop.backends.export import ExportRecipe - from solprop.backends.protocol import Backend, BackendHistory, StepStats - from solprop.backends.session import Start - from solprop.log import StopFlag - from solprop.translate.problem import PropagationProblem - from solprop.translate.run_request import RunRequest - -__all__ = ["ROUND_STEPS", "NativeGroupSession", "NativePreparedGroup", "refusal"] - -ROUND_STEPS = 256 -"""The most common steps a member takes in one turn, as one native advance makes at -most (``solprop.backends.session.DEFAULT_WORK_LIMIT``); the group-wide stop is polled -between rounds.""" - -STRATEGY = "native_group_session" -"""The group's ``batch_strategy`` in each member's execution record.""" - -_Chunk = tuple["BackendHistory | None", "StepStats | None"] - - -def refusal( - problems: Sequence[PropagationProblem], - requests: Sequence[RunRequest], - starts: Sequence[Start], -) -> str | None: - """Return why the native group refuses a group, naming the feature, or ``None``. - - Decided from the members' problems, requests and starts alone, before anything is - allocated. Each member must be a run the native session admits - (:func:`solprop_native.session.refusal`), replaying a fixed schedule; the members - must share the schedule, the save planes, the method, the field shape, the - statistics request and the general modal guide, which a batched scan's grouping - guarantees. - - Parameters - ---------- - problems : collections.abc.Sequence of solprop.translate.problem.PropagationProblem - Each member's translated problem, at least one. - requests : collections.abc.Sequence of solprop.translate.run_request.RunRequest - Each member's run request, in member order. - starts : collections.abc.Sequence of solprop.backends.session.Start - Each member's start, in member order. - - Returns - ------- - str or None - The reason, or ``None`` when the native group admits the group. - """ - for index, (problem, request, start) in enumerate( - zip(problems, requests, starts, strict=True) - ): - refused = member_session_refusal(problem, request, start) or _member_refusal( - request - ) - if refused is not None: - return f"{refused} (member {index})" - first_problem, first = problems[0], requests[0] - for index, (problem, request) in enumerate( - zip(problems[1:], requests[1:], strict=True), start=1 - ): - if not _same_group(problem, request, first_problem, first): - return ( - f"member {index}, which does not share member 0's schedule, save " - "planes, method, field shape or statistics request" - ) - if _guide(problem) != _guide(first_problem): - # The backend's own check, which does not depend on a caller having - # grouped carefully (solprop.driver.batch.refuse_mixed_guides is the - # driver's), as the lockstep group this replaced made it. - return ( - f"member {index}: a general-guide batch requires identical " - "guide/table/gauge identity, and its transform.modal_tables, " - "linear.modal_metric or responses.regional_responses is not member " - "0's; members may differ in their launch and their noise seed alone" - ) - return None - - -def _guide(problem: PropagationProblem) -> object: - """Return what general modal guide a problem carries, comparably. - - The tables' declared identities, the metric's kind and gauge, the compiled - responses' model and policy, and a split block's flow, as the reference group - compares them; ``None`` off the general modal route. - - - Returns: a scalar-and-string description, or ``None``. - """ - tables = problem.transform.modal_tables - if tables is None: - return None - metric = problem.linear.modal_metric - responses = problem.responses.regional_responses - flow = problem.linear.coupled_flow - return ( - tuple(sorted(dict(tables.identity).items(), key=str)), - None if metric is None else (metric.kind, metric.gauge_id), - None if responses is None else (responses.model_id, responses.policy_id), - None - if flow is None - else (flow.gauge_id, flow.certificate_id, flow.section_methods), - ) - - -class NativePreparedGroup: - """The native backend's prepared group (SEP 47 section 6.7). - - Each :meth:`start` opens the native group session, which refuses by name a group - it does not run (:func:`refusal`) before any member session starts. - - Parameters - ---------- - members : collections.abc.Sequence of solprop.backends.protocol.Backend - One constructed native backend per member; they stay the caller's until a - started group owns them. - problems : collections.abc.Sequence of solprop.translate.problem.PropagationProblem - Each member's independently translated problem. - requests : collections.abc.Sequence of solprop.translate.run_request.RunRequest - Each member's run request. - """ - - def __init__( - self, - members: Sequence[Backend], - problems: Sequence[PropagationProblem], - requests: Sequence[RunRequest], - ) -> None: - """Hold the members, their problems and their requests.""" - self._members = tuple(members) - self._problems = tuple(problems) - self._requests = tuple(requests) - - @property - def backend(self) -> str: # numpydoc ignore=RT01 - """Registered name of the backend that prepared it (the first member's).""" - return self._members[0].name - - def start( - self, starts: Sequence[Start], *, stop: StopFlag | None = None - ) -> GroupSession: - """Start the native group session. - - Parameters - ---------- - starts : collections.abc.Sequence of solprop.backends.session.Start - Each member's entrance; the group takes their fields. - stop : solprop.log.StopFlag or None, optional - A group-wide stop token. - - Returns - ------- - solprop.backends.session.GroupSession - The started group. - - Raises - ------ - solprop.exceptions.BackendError - Naming what the native group does not run (:func:`refusal`), or if a - member is not a native backend. - """ - return NativeGroupSession( - cast("Sequence[NativeBackend]", self._members), - self._problems, - self._requests, - starts, - stop=stop, - ) - - -def _member_refusal(request: RunRequest) -> str | None: - """Return why one member's request falls outside a group's windows, or ``None``.""" - # A coupled flow is admitted: the lockstep batch this replaced refused one because - # its fused accepted update applied no flow action, and a native group fuses - # nothing -- each member's session carries its own flow (SEP 47 section 6.7). - if request.replay is None: - return "an adaptive march: a group replays one common fixed schedule" - if request.observation.step_planes: - return "step planes, which a group's save-plane windows do not observe" - # Interpolated planes are refused beside a schedule where the stepper is built. - return None - - -def _same_group( - problem: PropagationProblem, - request: RunRequest, - first_problem: PropagationProblem, - first: RunRequest, -) -> bool: - """Return whether a member shares member 0's schedule, planes, method and spec. - - - Returns: True when they agree. - """ - assert request.replay is not None - assert first.replay is not None - schedule, reference = request.replay.schedule, first.replay.schedule - spec, reference_spec = request.observation.stats, first.observation.stats - return ( - schedule.z_start == reference.z_start - and np.array_equal(schedule.steps, reference.steps) - and np.array_equal( - request.observation.save_planes, first.observation.save_planes - ) - and request.integration.method == first.integration.method - and problem.shape == first_problem.shape - and (spec.names, spec.periodic, spec.period) - == (reference_spec.names, reference_spec.periodic, reference_spec.period) - ) - - -def _bound(event: Event, receipt: Receipt, member: int) -> Event: - """Return a member's event with its ticket, if any, rebound to the group's batch.""" - ticket = cast("ExportTicket | None", getattr(event, "ticket", None)) - if ticket is None: - return event - return cast( - "Event", - dataclasses.replace( - cast("Any", event), - ticket=ExportTicket(receipt, ticket.generation, ticket.z, member), - ), - ) - - -class _Window: - """One member's progress through the current window: its chunks and its end. - - Attributes - ---------- - chunks : list of tuple - The attempts and rows of each batch the member delivered in this window. - event : solprop.backends.events.Event or None - The window's end for the member: its observation or its terminal event, its - history the window's chunks joined; ``None`` while it runs. - """ - - def __init__(self) -> None: - """Start an empty window.""" - self.chunks: list[_Chunk] = [] - self.event: Event | None = None - - def joined(self) -> tuple[BackendHistory, StepStats]: - """Return the window's attempts and rows so far, as one record.""" - return join_attempts(self.chunks) - - -class NativeGroupSession: - """A :class:`~solprop.backends.session.GroupSession` of native sessions. - - Parameters - ---------- - members : collections.abc.Sequence of solprop_native.backend.NativeBackend - One constructed backend per member, each built for its problem and holding no - state. Once the group is constructed it owns them, each through its member's - native session, and closes them with itself; a construction that fails closes - the sessions it started and leaves the backends to the caller. - problems : collections.abc.Sequence of solprop.translate.problem.PropagationProblem - Each member's independently translated problem. - requests : collections.abc.Sequence of solprop.translate.run_request.RunRequest - Each member's run request, with its own fresh boundary monitor; their schedule, - save planes and statistics are the group's common ones. - starts : collections.abc.Sequence of solprop.backends.session.Start - Each member's entrance. The group takes each start's field once it is - constructed; a construction that fails leaves them to the caller. - stop : solprop.log.StopFlag or None, optional - A group-wide stop token, polled between rounds of common steps. - - Raises - ------ - solprop.backends.session.SessionError - If the sequences differ in length or are empty, if a start is not a fresh - entrance or was already used, or if two members share a start or a backend. - solprop.exceptions.BackendError - Naming what the native group refuses (:func:`refusal`), before anything is - allocated, or if a member is not a native backend. - """ - - def __init__( - self, - members: Sequence[NativeBackend], - problems: Sequence[PropagationProblem], - requests: Sequence[RunRequest], - starts: Sequence[Start], - *, - stop: StopFlag | None = None, - ) -> None: - """Refuse what the native group does not run, then start each member.""" - check_group(members, problems, requests, starts) - if any( - not isinstance(cast("object", member), NativeBackend) for member in members - ): - msg = "the native group session takes native backends" - raise BackendError(msg) - refused = refusal(problems, requests, starts) - if refused is not None: - msg = f"the native group session does not run {refused}" - raise BackendError(msg) - # Each member session loads a copy of its start, and the originals' fields are - # taken only once every member has started: a construction that fails leaves - # the caller its starts and its backends to retry with. - sessions: list[NativeSession] = [] - try: - for member, problem, request, start in zip( - members, problems, requests, starts, strict=True - ): - sessions.append( - NativeSession( - problem, request, dataclasses.replace(start), backend=member - ) - ) - except BaseException: - for session in sessions: - session._owns = False # pyright: ignore[reportPrivateUsage] - the caller keeps its backend - session.close() - raise - for start in starts: - start.take_field() - self._sessions = tuple(sessions) - self._planes = int(np.asarray(requests[0].observation.save_planes).size) - self._stop = stop - self._ledger = SessionLedger() - self._launched = False - self._index = 0 - count = len(self._sessions) - self._outcomes: list[Outcome | None] = [None] * count - # Each member's pending native batch, acknowledged at its next turn. - self._pending: list[Receipt | None] = [None] * count - # The member tickets the pending group batch's tickets stand for. - self._tickets: dict[int, ExportTicket] = {} - - # -- protocol ------------------------------------------------------------------- - - @property - def n_members(self) -> int: # numpydoc ignore=RT01 - """Number of members.""" - return len(self._sessions) - - @property - def finished(self) -> bool: # numpydoc ignore=RT01 - """Whether the group's terminal batch was issued: every member has ended.""" - return self._ledger.finished - - @property - def closed(self) -> bool: # numpydoc ignore=RT01 - """Whether the group was closed.""" - return self._ledger.state is SessionState.CLOSED - - def advance(self) -> GroupBatch: - """Run every running member through the next common window, and report it. - - Returns - ------- - solprop.backends.events.GroupBatch - Each member's events in the window. - """ - self._ledger.check_advance() - self._tickets = {} - if not self._launched: - self._launched = True - return self._window(stepping=False, final=False) - if self._index >= self._planes: - return self._window(stepping=False, final=True) - self._index += 1 - return self._window(stepping=True, final=False) - - def acknowledge(self, receipt: Receipt) -> None: - """Release the pending batch and allow advancing past it. - - Each member's own pending batch is acknowledged at its next turn, so that a - member the group ends before then can still be exported. - - Parameters - ---------- - receipt : solprop.backends.events.Receipt - The pending batch's receipt. - """ - self._ledger.acknowledge(receipt) - self._tickets = {} - - def export( - self, - member: int, - ticket: ExportTicket, - recipe: ExportRecipe, - out: npt.NDArray[np.complex128] | None = None, - ) -> npt.NDArray[np.complex128]: - """Fill a destination with one member's converted field at a pending ticket. - - Parameters - ---------- - member : int - The member's position. - ticket : solprop.backends.events.ExportTicket - A ticket of the pending batch, for this member. - recipe : solprop.backends.export.ExportRecipe - The conversion. - out : numpy.ndarray or None, optional - The destination; a new array by default. - - Returns - ------- - numpy.ndarray - The member's converted field, exported natively by its session. - - Raises - ------ - solprop.backends.session.SessionError - If the ticket expired, or is not one of this member's. - """ - self._ledger.check_ticket(ticket) - check_member_ticket(ticket, self._member(member)) - return self._sessions[member].export(self._held(member, ticket), recipe, out) - - def noise_phase(self, member: int, ticket: ExportTicket) -> np.ndarray | None: - """Return one member's noise phase at a pending ticket, which its session forms. - - Each member carries its own realisation and its own propagator, so its phase - is its native session's (:meth:`NativeSession.noise_phase`). - - Parameters - ---------- - member : int - The member's position. - ticket : solprop.backends.events.ExportTicket - A ticket of the pending batch, for this member. - - Returns - ------- - numpy.ndarray or None - The phase, shape ``(n_modes, n_pol, n_omega)``, or ``None`` without a - noise model. - - Raises - ------ - solprop.backends.session.SessionError - If the ticket expired, or is not one of this member's. - """ - self._ledger.check_ticket(ticket) - check_member_ticket(ticket, self._member(member)) - return self._sessions[member].noise_phase(self._held(member, ticket)) - - def _held(self, member: int, ticket: ExportTicket) -> ExportTicket: - """Return the member's own pending ticket that a group ticket stands for.""" - held = self._tickets.get(member) - if held is None or held.generation != ticket.generation: - msg = ( - f"the export ticket for z = {ticket.z!r} m is not one of member " - f"{member}'s in the pending batch" - ) - raise SessionError(msg) - return held - - def member_status(self, member: int) -> SessionStatus: - """Return one member's committed position, counters and outcome. - - Parameters - ---------- - member : int - The member's position. - - Returns - ------- - solprop.backends.session.SessionStatus - Its native session's position and counters; a member that ended reports - its own outcome while the group goes on. - """ - index = self._member(member) - status = self._sessions[index].status() - outcome = self._outcomes[index] - state = self._ledger.state - if outcome is not None and state is not SessionState.CLOSED: - state = SessionState.FINISHED - return SessionStatus( - z=status.z, - plane_index=status.plane_index, - attempts=status.attempts, - rejected=status.rejected, - state=state, - outcome=outcome, - ) - - def execution_record(self, member: int) -> Mapping[str, object]: - """Return one member's execution facts, with the group's strategy. - - Parameters - ---------- - member : int - The member's position. - - Returns - ------- - collections.abc.Mapping - Its native session's record, with the group's size and strategy. - """ - record = dict(self._sessions[self._member(member)].execution_record()) - record.update( - batch_size=len(self._sessions), - batch_strategy=STRATEGY, - fused_batch_kernels=False, - ) - return record - - def monitor_record(self, member: int) -> Mapping[str, object] | None: - """Return one member's boundary-monitor record, which its session keeps. - - Parameters - ---------- - member : int - The member's position. - - Returns - ------- - collections.abc.Mapping or None - Its record, or ``None`` when unwatched. - """ - return self._sessions[self._member(member)].monitor_record() - - def close(self) -> None: - """Release every member's session and backend; idempotent.""" - if self._ledger.close(): - self._tickets = {} - for session in self._sessions: - session.close() - - def __enter__(self) -> "NativeGroupSession": # noqa: UP037 - runtime type hook - """Return the group. - - Returns - ------- - NativeGroupSession - This group. - """ - return self - - def __exit__( - self, - kind: type[BaseException] | None, - error: BaseException | None, - trace: TracebackType | None, - ) -> None: - """Close the group. - - Parameters - ---------- - kind : type or None - The exception type, if one is propagating. - error : BaseException or None - The exception, if one is propagating. - trace : types.TracebackType or None - Its traceback. - """ - del kind, error, trace - self.close() - - # -- internals ------------------------------------------------------------------ - - def _member(self, member: int) -> int: - """Return a valid member position.""" - if not 0 <= member < len(self._sessions): - msg = f"the group has {len(self._sessions)} members, not a member {member}" - raise SessionError(msg) - return member - - def _window(self, *, stepping: bool, final: bool) -> GroupBatch: - """Run every running member to its window's end, in rounds; report it. - - - ``stepping``: the window takes common steps (a save plane's), so the stop - token is polled before its first round. The launch and the completion take - none; any later round of any window is polled too. - - ``final``: the window is the completion, which ends the group. - """ - windows = { - index: _Window() - for index, outcome in enumerate(self._outcomes) - if outcome is None - } - try: - rounds = 0 - while active := [i for i, w in windows.items() if w.event is None]: - # Before every round that may step: a save plane's first, and any - # later round of any window, which only steps can have made necessary. - stop = self._stop - if (stepping or rounds) and stop is not None and stop.is_set(): - return self._ended(Outcome.STOPPED, StopRequested(stop), windows) - rounds += 1 - for index in active: - error = self._turn(index, windows[index]) - if error is not None: - return self._ended(Outcome.FAILED, error, windows) - except BaseException as escaped: - # A failure outside a member's own terminal event -- the session refusing - # a call, an exception a warning's display raised, an interrupt -- ends - # the group with the chunks drained so far delivered; an interrupt then - # propagates, the group's failed batch pending, so it advances no more. - ended = self._ended(Outcome.FAILED, escaped, windows) - if isinstance(escaped, Exception): - return ended - raise - events: list[tuple[Event, ...]] = [()] * len(self._sessions) - steps = 0 - for index, window in windows.items(): - assert window.event is not None - events[index] = (window.event,) - if window.event.history is not None: - steps = max(steps, window.event.history.n_steps) - if (counters := _counters.active) is not None: - counters.group_window(steps) - ended = final or all(outcome is not None for outcome in self._outcomes) - return self._issue(events, outcome=Outcome.COMPLETED if ended else None) - - def _turn(self, index: int, window: _Window) -> BaseException | None: - """Advance one member by a round of common steps, or to its window's end. - - - Returns: a group-wide failure the member reported, which ends the group; - ``None`` otherwise, its window's end, if reached, in `window`. - """ - session = self._sessions[index] - made = 0 - while made < ROUND_STEPS and window.event is None: - receipt = self._pending[index] - if receipt is not None: - session.acknowledge(receipt) - self._pending[index] = None - batch = session.advance(work_limit=ROUND_STEPS - made) - self._pending[index] = batch.receipt - (event,) = batch.events - if isinstance(event, Progress): - window.chunks.append((event.history, event.step_stats)) - made += event.history.n_steps - elif isinstance(event, ServiceRequired): - window.chunks.append((event.history, event.step_stats)) - made += 0 if event.history is None else event.history.n_steps - self._serve(index, window, event) - elif isinstance(event, ObservationReady): - history, rows = join_attempts( - [*window.chunks, (event.history, event.step_stats)] - ) - window.event = _with_chunk(event, history, rows) - else: - assert isinstance(event, Terminal) - history, rows = join_attempts( - [*window.chunks, (event.history, event.step_stats)] - ) - window.event = _with_chunk(event, history, rows) - self._outcomes[index] = event.outcome - group_wide = event.outcome is not Outcome.COMPLETED and not isinstance( - event.error, BoundaryError - ) - if group_wide: - return event.error - return None - - def _serve(self, index: int, window: _Window, event: ServiceRequired) -> None: - """Serve a member's barrier: a warning is emitted; one raised ends the member. - - A boundary warning the caller's filters raise ends that member alone, at the - warning's committed endpoint, with its field there eligible for a checkpoint, - as a lone run of it ends (SEP 47 section 5.5). The group asks for no snapshot. - - - ``window``: its window, ended here when the warning is raised. - """ - if event.kind is not ServiceKind.WARNING: - return - try: - emit_warning(event, stacklevel=4) - except Warning as raised: - history, rows = window.joined() - window.event = Terminal( - Outcome.FAILED, - event.z, - Eligibility.ELIGIBLE, - raised, - event.ticket, - history, - rows, - ) - self._outcomes[index] = Outcome.FAILED - - def _ended( - self, outcome: Outcome, error: BaseException, windows: dict[int, _Window] - ) -> GroupBatch: - """End every running member with a group-wide stop or failure. - - - ``windows``: the window's progress of each member running when it began. - - Returns: each running member's terminal event at its own committed position; a - member that ended in this window keeps its own terminal event. - """ - events: list[tuple[Event, ...]] = [()] * len(self._sessions) - for index, window in windows.items(): - if isinstance(window.event, Terminal): - events[index] = (window.event,) - continue - # A member that reached its plane ends there, its observation's attempts - # delivered; any other at the common step it stood at. - ended = window.event - history, rows = ( - (ended.history, ended.step_stats) - if isinstance(ended, ObservationReady) - else window.joined() - ) - # A member holds an exportable state only while a batch of its own is - # pending: one that never launched, or whose own advance raised, has - # none, and claims no checkpoint. - ticket = self._sessions[index].pending_ticket() - self._outcomes[index] = outcome - events[index] = ( - Terminal( - outcome, - self._sessions[index].status().z, - Eligibility.POISONED if ticket is None else Eligibility.ELIGIBLE, - error, - ticket, - history, - rows, - ), - ) - return self._issue(events, outcome=outcome, error=error) - - def _issue( - self, - members: list[tuple[Event, ...]], - *, - outcome: Outcome | None = None, - error: BaseException | None = None, - ) -> GroupBatch: - """Issue a window's events under a new receipt, its tickets the group's. - - - ``outcome``: the group's outcome, when the batch ends it. - """ - receipt = self._ledger.issue(outcome=outcome) - for index, events in enumerate(members): - for event in events: - ticket = cast("ExportTicket | None", getattr(event, "ticket", None)) - if ticket is not None: - self._tickets[index] = ticket - bound = tuple( - tuple(_bound(event, receipt, index) for event in events) - for index, events in enumerate(members) - ) - return GroupBatch(receipt, bound, outcome, error) - - -def _with_chunk(event: Event, history: BackendHistory, rows: StepStats) -> Event: - """Return a member's window-ending event carrying the whole window's chunk.""" - return cast( - "Event", - dataclasses.replace(cast("Any", event), history=history, step_stats=rows), - ) diff --git a/native/src/solprop_native/session.py b/native/src/solprop_native/session.py index ebb6fc146..833c9f59b 100644 --- a/native/src/solprop_native/session.py +++ b/native/src/solprop_native/session.py @@ -62,7 +62,6 @@ native monitor and the draw's readings by the native transverse edge, and the noise phase at each plane, formed on the host or, for a z table's propagator phase, read from its slot in the leased state; -- no group (:mod:`solprop_native.group` runs one native session per member); - the TDSE response on a CPU build, through the march's host source (solprop SEP 49): each ``advance`` opens an interruptible scope beside its commit, so a signal held while the host source waits is raised there, and a host source's failure is the @@ -377,10 +376,9 @@ class NativeSession: backend : solprop_native.backend.NativeBackend or None, optional A backend already built for `problem` and holding no state, to run on in place of building one: a runner's or a run's (:func:`solprop.backends.sessions. - start_session`), or a group's member, as a batched scan constructs it - (:class:`~solprop_native.group.NativeGroupSession`). Its own time grid, modes, - profiles, far-field tables and execution options are used, and `grid`, - `modes`, `profiles` and `options` must then be left out. A failed construction + start_session`). Its own time grid, modes, profiles, far-field tables and + execution options are used, and `grid`, `modes`, `profiles` and `options` must + then be left out. A failed construction leaves it to the caller. owns : bool, optional Whether closing the session closes `backend`: false for a runner's backend diff --git a/native/tests/session_runs.py b/native/tests/session_runs.py index a6d061917..1af6652e3 100644 --- a/native/tests/session_runs.py +++ b/native/tests/session_runs.py @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""Drive a native session or a native group to its end and keep what it observed. +"""Drive a native session to its end and keep what it observed. The native test root's copy of solprop's ``tests/sessions/runs.py``, with the same names and semantics, since this root cannot import solprop's test helpers: :func:`run` @@ -13,19 +13,12 @@ :func:`load_native` and :func:`native_trial` reach the native state's own trial, which the kernel-level checks make where they once called the driver's trial step. A failed run raises its error by default, as a service loop does. - -The group tests compare each member of a native group session -(:class:`solprop_native.group.NativeGroupSession`, started through solprop's -:func:`~solprop.backends.sessions.start_group`) with the same member run alone through -the native session (:func:`alone`): the oracle that replaced the transitional lockstep -batch in solprop SEP 47's phase 5. """ from __future__ import annotations -import functools import math -from collections.abc import Callable, Generator, Sequence +from collections.abc import Callable, Generator from contextlib import contextmanager from dataclasses import dataclass from typing import Any, cast @@ -44,7 +37,7 @@ from solprop.backends.export import ExportRecipe from solprop.backends.protocol import BackendHistory, StepStats, StepSummary from solprop.backends.session import RunSession, SessionStatus, Start -from solprop.backends.sessions import start_group, start_session +from solprop.backends.sessions import start_session IDENTITY = ExportRecipe(power=False, optics=False) """The state as the session holds it, in the internal FFT convention.""" @@ -543,70 +536,6 @@ def native_trial(backend: Any, z: float, dz: float, *, field: Any = None) -> np. return np.array(state.rk_trial(z, dz, nodes, prepare_only=False), dtype=np.float64) -class _Recorder: - """Keep one trajectory's observations, each with the attempts and rows since the - previous one, assembled from every event's chunk (exactly-once delivery). - - The comparable record of a group member and of its lone session, which - :func:`assert_same` compares. - """ - - def __init__(self) -> None: - self.planes: list[dict[str, Any]] = [] - self._chunks: list[tuple[Any, Any]] = [] - - def __call__(self, session: RunSession, batch: EventBatch) -> None: - """Record a lone session's batch, as :func:`drive`'s ``between``.""" - self.take(session.export, batch.events) - - def take(self, export: Any, events: Sequence[Any]) -> None: - """Record a batch's events, exporting each observation's field. - - A run that failed raises its failure here, so that no caller compares a run - cut short. - """ - for event in events: - if isinstance(event, Terminal) and event.error is not None: - raise event.error - history = getattr(event, "history", None) - if history is not None: - self._chunks.append((history, getattr(event, "step_stats", None))) - if not isinstance(event, ObservationReady): - continue - history, rows = join_attempts(self._chunks) - self._chunks = [] - self.planes.append( - { - "z": float(event.z), - "attempts": { - "z": np.asarray(history.z).copy(), - "dz": np.asarray(history.dz).copy(), - "accepted": np.asarray(history.accepted).copy(), - "error_norm": np.asarray(history.error_norm).copy(), - }, - "field": np.array(export(event.ticket, IDENTITY)), - "stats": { - name: np.asarray(value) for name, value in event.stats.items() - }, - "row_z": np.asarray(rows.z).copy(), - "rows": { - name: np.asarray(value).copy() - for name, value in rows.values.items() - }, - } - ) - - -def alone(owner: Any, problem: Any, request: Any, start: Start) -> list[dict[str, Any]]: - """Run one member alone through the native session; return its observations. - - The session owns `owner` and closes it; the observations are :func:`grouped`'s. - """ - recorder = _Recorder() - run(owner, problem, request, start, owns=True, export=None, between=recorder) - return recorder.planes - - def drain(session: Any) -> Terminal: """Advance a started session to its end, exporting nothing; return its terminal. @@ -619,58 +548,3 @@ def drain(session: Any) -> Terminal: for event in batch.events: if isinstance(event, Terminal): return event - - -def grouped( - owners: Sequence[Any], - problems: Sequence[Any], - requests: Sequence[Any], - starts: Sequence[Start], -) -> list[list[dict[str, Any]]]: - """Run members as one native group; return each member's observations. - - The group owns `owners` and closes them. - """ - group = start_group(owners, problems, requests, starts) - recorders = [_Recorder() for _ in range(group.n_members)] - try: - assert type(group).__name__ == "NativeGroupSession" - while not group.finished: - batch = group.advance() - for index, events in enumerate(batch.members): - recorders[index].take(functools.partial(group.export, index), events) - group.acknowledge(batch.receipt) - finally: - group.close() - return [recorder.planes for recorder in recorders] - - -def one_thread() -> bool: - """Return whether the native backend runs one thread, as the default lane sets it. - - The members of a group are bitwise their lone sessions there, where the - reductions' order is fixed. - """ - import os - - return "1" in { - os.environ.get("SOLPROP_NATIVE_THREADS"), - os.environ.get("SOLPROP_THREADS"), - } - - -def assert_same(left: Any, right: Any, what: str = "") -> None: - """Assert two recorded values agree bitwise, nested dicts and lists included.""" - if isinstance(left, dict): - mine, theirs = cast("dict[str, Any]", left), cast("dict[str, Any]", right) - assert mine.keys() == theirs.keys(), what - for key in mine: - assert_same(mine[key], theirs[key], f"{what}.{key}") - return - if isinstance(left, list): - mine_list, theirs_list = cast("list[Any]", left), cast("list[Any]", right) - assert len(mine_list) == len(theirs_list), what - for index, (one, other) in enumerate(zip(mine_list, theirs_list, strict=True)): - assert_same(one, other, f"{what}[{index}]") - return - assert np.asarray(left).tobytes() == np.asarray(right).tobytes(), what diff --git a/native/tests/test_api_contract.py b/native/tests/test_api_contract.py index 2b4399f7b..2dc8ab1f5 100644 --- a/native/tests/test_api_contract.py +++ b/native/tests/test_api_contract.py @@ -36,6 +36,7 @@ import solprop_native as native from solprop_native import _bind, _core # pyright: ignore[reportPrivateUsage] +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] POOL_VARIABLES = ( "SOLPROP_NATIVE_KERNEL_THREADS", @@ -1028,14 +1029,14 @@ def test_the_reference_parts_time_what_they_are_asked_to() -> None: """ rng = np.random.default_rng(28) volume = rng.standard_normal((3, 4, 5)) + 1j * rng.standard_normal((3, 4, 5)) - pairs = _core.reference_fft3_pairs(np.ascontiguousarray(volume), 1, 3) + pairs = _testing.reference_fft3_pairs(np.ascontiguousarray(volume), 1, 3) copies = _core.reference_stream_copies(1000, 1, 4) assert len(pairs) == 3 assert all(seconds > 0.0 for seconds in pairs) assert len(copies) == 4 assert all(seconds > 0.0 for seconds in copies) with pytest.raises(ValueError, match="three-dimensional"): - _core.reference_fft3_pairs(np.ascontiguousarray(volume[0]), 0, 1) + _testing.reference_fft3_pairs(np.ascontiguousarray(volume[0]), 0, 1) def test_operation_sizing_metadata_preserves_process_cap( diff --git a/native/tests/test_backend.py b/native/tests/test_backend.py index 86f200303..759a1c44e 100644 --- a/native/tests/test_backend.py +++ b/native/tests/test_backend.py @@ -45,6 +45,7 @@ import solprop_native from solprop_native import NativeBackend, _core, build_info, check_build +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] from solprop_native.backend import ( _lower, # pyright: ignore[reportPrivateUsage] _LowerPlan, # pyright: ignore[reportPrivateUsage] @@ -178,21 +179,21 @@ def test_stage_observation_owns_its_host_copy_and_checks_lifetime( backend = NativeBackend(problem, run_request, grid=grid) state = load_native(backend, problem.initial.field0, clear_fsal=False) with pytest.raises(RuntimeError, match="stage"): - state.stage_to_host(0) + _testing.stage_to_host(state, 0) native_trial(backend, 0.0, 1e-4) - derivative = state.stage_to_host(0) + derivative = _testing.stage_to_host(state, 0) assert derivative.shape == (1, grid.n_omega) assert derivative.dtype == np.complex128 assert np.max(np.abs(derivative)) > 0 saved = derivative.copy() derivative.fill(0) # Exact: a second host copy of the same device stage, not a recomputation. - np.testing.assert_array_equal(state.stage_to_host(0), saved) + np.testing.assert_array_equal(_testing.stage_to_host(state, 0), saved) with pytest.raises(IndexError, match="stage"): - state.stage_to_host(run_request.stepper.tableau.n_stages) + _testing.stage_to_host(state, run_request.stepper.tableau.n_stages) backend.close() with pytest.raises(RuntimeError, match="closed"): - state.stage_to_host(0) + _testing.stage_to_host(state, 0) def test_the_solprop_version_is_recorded_and_never_compared( @@ -911,7 +912,7 @@ def test_packed_real_blas_radial_envelope_matches_the_reference_when_eligible() assert not provider.endswith("-packed-real"), provider assert ledger.get("radial_blas_buffers", 0) == 0 native_trial(backend, 0.0, 0.0) - actual = np.asarray(state.stage_to_host(0)).reshape(problem.shape) + actual = np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) finally: backend.close() scale = float(np.max(np.abs(expected))) diff --git a/native/tests/test_band_column_budget.py b/native/tests/test_band_column_budget.py index d9639e1c2..cd5f660fe 100644 --- a/native/tests/test_band_column_budget.py +++ b/native/tests/test_band_column_budget.py @@ -82,6 +82,7 @@ import solprop_native from solprop_native import NativeBackend +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] type Real = npt.NDArray[np.float64] type Complex = npt.NDArray[np.complex128] @@ -239,7 +240,7 @@ def stages( state = load_native(backend, problem.initial.field0, clear_fsal=False) # A zero-length trial exposes the first stage, N(E, z = 0). native_trial(backend, 0.0, 0.0) - actual = np.asarray(state.stage_to_host(0)).reshape(problem.shape) + actual = np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) finally: backend.close() return actual, expected diff --git a/native/tests/test_band_pathological.py b/native/tests/test_band_pathological.py index dd635c4cc..ea94bdb29 100644 --- a/native/tests/test_band_pathological.py +++ b/native/tests/test_band_pathological.py @@ -64,6 +64,7 @@ march_bound, ) from test_band_stress import vector +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] type ComplexArray = npt.NDArray[np.complex128] @@ -203,7 +204,7 @@ def source_of_native( try: state = load_native(backend, problem.initial.field0, clear_fsal=False) native_trial(backend, 0.0, 0.0) - return np.asarray(state.stage_to_host(0)).reshape(problem.shape) + return np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) finally: backend.close() diff --git a/native/tests/test_band_plasma.py b/native/tests/test_band_plasma.py index 7a6ef33ea..8aa185cb4 100644 --- a/native/tests/test_band_plasma.py +++ b/native/tests/test_band_plasma.py @@ -66,6 +66,7 @@ _lower, # pyright: ignore[reportPrivateUsage] - corrupt native payloads _LowerPlan, # pyright: ignore[reportPrivateUsage] - corrupt native payloads ) +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] INFO = solprop_native.build_info() DEVICE_BUILD = INFO.device_backend != "none" @@ -445,7 +446,7 @@ def test_one_evaluation_matches_the_reference() -> None: state = load_native(backend, problem.initial.field0, clear_fsal=False) # A zero-length trial exposes the first stage, N(E, z = 0). native_trial(backend, 0.0, 0.0) - actual = np.asarray(state.stage_to_host(0)).reshape(problem.shape) + actual = np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) finally: backend.close() scale = float(np.max(np.abs(expected))) @@ -497,7 +498,7 @@ def test_every_stage_of_a_trial_matches_the_reference( assert backend.metadata()["projection_provider"] == "folded" native_trial(backend, 0.0, dz) actual = [ - np.asarray(state.stage_to_host(stage)).reshape(problem.shape) + np.asarray(_testing.stage_to_host(state, stage)).reshape(problem.shape) for stage in range(len(expected)) ] finally: @@ -601,7 +602,7 @@ def test_quadrature_keeps_accepted_scores_through_rejection_and_reset( rtol=0.0, atol=bound * float(np.max(np.abs(want_field))), ) - score = state.quadrature_error + score = _testing.quadrature_error(state) assert math.isfinite(score) np.testing.assert_allclose( score, want.stats["quadrature_error"], rtol=0.0, atol=score_bound @@ -620,7 +621,8 @@ def test_quadrature_keeps_accepted_scores_through_rejection_and_reset( # field stay. (Its positions are the first step's, inside the problem's # tables, which end at the second plane.) native_trial(backend, dz, 0.5 * dz) - assert state.quadrature_error == score # Stored accepted value, no arithmetic. + # The stored accepted value, no arithmetic. + assert _testing.quadrature_error(state) == score assert math.isnan(state.quadrature_peak()) np.testing.assert_array_equal(state.field_to_host().reshape(got.shape), got) @@ -629,7 +631,7 @@ def test_quadrature_keeps_accepted_scores_through_rejection_and_reset( backend.prepare(problem, run_request).start( Start.entrance(problem), owns=False ).close() - assert math.isnan(state.quadrature_error) + assert math.isnan(_testing.quadrature_error(state)) assert math.isnan(state.quadrature_peak()) again = run(backend, problem, run_request).fields np.testing.assert_allclose( diff --git a/native/tests/test_band_stress.py b/native/tests/test_band_stress.py index 620c74716..72ee4ea49 100644 --- a/native/tests/test_band_stress.py +++ b/native/tests/test_band_stress.py @@ -69,6 +69,7 @@ evaluation_bound, march_bound, ) +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] type ComplexArray = npt.NDArray[np.complex128] @@ -285,7 +286,7 @@ def test_one_evaluation_matches_the_reference(kind: str) -> None: state = load_native(backend, problem.initial.field0, clear_fsal=False) # A zero-length trial exposes the first stage, N(E, z = 0). native_trial(backend, 0.0, 0.0) - actual = np.asarray(state.stage_to_host(0)).reshape(problem.shape) + actual = np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) finally: backend.close() scale = float(np.max(np.abs(expected))) diff --git a/native/tests/test_batch.py b/native/tests/test_batch.py deleted file mode 100644 index efc230e7b..000000000 --- a/native/tests/test_batch.py +++ /dev/null @@ -1,108 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""Native groups against their members alone. - -A native group (solprop SEP 47 section 6.7) runs each member in its own native session; -the transitional lockstep batch it replaced was deleted in SEP 47's phase 5, with the -fused batch update state it stepped. -""" - -from __future__ import annotations - -import dataclasses -import math - -import numpy as np -import pytest -from bounds import assert_within, gamma, step_bound -from conftest import PhaseACase -from session_runs import alone, assert_same, grouped, one_thread -from solprop.backends.session import Start -from solprop.stats import StatsSpec -from solprop.stepper import FixedSchedule - -from solprop_native import NativeBackend - - -@pytest.mark.parametrize("count", [1, 3]) -@pytest.mark.parametrize("weighted", [False, True]) -def test_group_members_match_their_lone_sessions( - phase_a_case: PhaseACase, count: int, weighted: bool -) -> None: - """Each member of a native group agrees with the same member run alone. - - Both replay one prescribed schedule with the explicit pair, each member in its own - native session (solprop SEP 47 section 6.7): bit for bit at one thread, where the - reductions' order is fixed, and otherwise to rounding (solprop SEP 25). Bounds, - fixed beforehand: - - - the field, the transforms' budget of four steps (:func:`bounds.step_bound`); - - the step positions, lengths, acceptances and row positions exactly, as the - schedule prescribes them; - - each error norm, one step's budget over ``rtol`` (the embedded difference's - rounding is relative to the field, scored against ``rtol |E|``), twice for the - weighted controller's bins, plus the field's budget relatively; - - the energy and peak-power statistics, the field's budget twice (a squared - modulus) times the square root of the samples (a peak read from a normwise - bound), plus the energy sum's own ``gamma(n)``. - """ - original, run_request, grid = phase_a_case - spec = StatsSpec(names=("energy", "peak_power"), periodic=("energy",), period=2) - controller = run_request.stepper.controller - if weighted: - controller = dataclasses.replace( - controller, weights=np.linspace(0.5, 1.5, grid.n_omega) - ) - run_request = run_request.with_stepper( - dataclasses.replace( - run_request.stepper, - controller=controller, - schedule=FixedSchedule.uniform(0.0, 1e-3, 2.5e-4), - ) - ).for_run(stats=spec) - problems = [ - dataclasses.replace( - original, - initial=dataclasses.replace( - original.initial, field0=original.initial.field0 * (index + 1) - ), - ) - for index in range(count) - ] - requests = [run_request] * count - group = grouped( - [NativeBackend(one, run_request, grid=grid) for one in problems], - problems, - requests, - [Start.entrance(one) for one in problems], - ) - singles = [ - alone(NativeBackend(one, run_request, grid=grid), one, run_request, start) - for one, start in ((one, Start.entrance(one)) for one in problems) - ] - field_bound = step_bound(grid.n_to, 4) - statistic_bound = 2 * math.sqrt(grid.n_to) * field_bound + gamma(grid.n_to) - for member, single in zip(group, singles, strict=True): - assert [plane["z"] for plane in member] == [plane["z"] for plane in single] - if one_thread(): - assert_same(member, single) - for actual, expected in zip(member, single, strict=True): - assert_within(actual["field"], expected["field"], field_bound, what="field") - for name in ("z", "dz", "accepted"): - np.testing.assert_array_equal( - actual["attempts"][name], expected["attempts"][name], err_msg=name - ) - np.testing.assert_allclose( - actual["attempts"]["error_norm"], - expected["attempts"]["error_norm"], - rtol=field_bound, - # Twice: the weighted controller's bin weights reach 1.5. - atol=2 * step_bound(grid.n_to, 1) / controller.rtol, - ) - np.testing.assert_array_equal(actual["row_z"], expected["row_z"]) - for name, values in expected["rows"].items(): - assert_within(actual["rows"][name], values, statistic_bound, what=name) - for name, value in expected["stats"].items(): - assert_within(actual["stats"][name], value, statistic_bound, what=name) diff --git a/native/tests/test_coupled_flow.py b/native/tests/test_coupled_flow.py index 73209941b..8f2068498 100644 --- a/native/tests/test_coupled_flow.py +++ b/native/tests/test_coupled_flow.py @@ -28,7 +28,6 @@ import numpy as np import numpy.typing as npt import pytest -from session_runs import alone, assert_same, grouped, one_thread from session_runs import run as run_session from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.backend import ( @@ -48,11 +47,11 @@ from solprop.translate.run_request import RunRequest from solprop_native import NativeBackend, _core +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] from solprop_native.backend import ( _host_flow, # pyright: ignore[reportPrivateUsage] _lower_flow, # pyright: ignore[reportPrivateUsage] ) -from solprop_native.group import refusal as group_refusal type ComplexArray = npt.NDArray[np.complex128] type RealArray = npt.NDArray[np.float64] @@ -280,84 +279,6 @@ def test_ten_steps_of_the_flow_are_the_reference_within_the_bound(name: str) -> assert float(np.max(np.abs(actual - expected))) / scale <= bound -def _owner( - case: Simulation, problem: PropagationProblem, run_request: RunRequest -) -> NativeBackend: - """Return a native backend for one member, with the case's modes and profiles.""" - return NativeBackend( - problem, - run_request, - grid=case.grid, - modes=case.modes, - profiles=case.profiles, - ) - - -@pytest.mark.parametrize("name", sorted(CASES)) -def test_a_coupled_flow_group_runs_each_member_as_its_lone_session(name: str) -> None: - """A native group admits coupled-flow members (solprop SEP 47 section 6.7). - - Each member runs in its own native session, its flow action and explicit residual - its own, so nothing of a member's step is shared: on one thread, where the - reductions' order is fixed, each member is the same problem run alone through the - native session bit for bit. On any thread count each member's final field is - ``numpy_ref``'s within the ten-step bound :func:`_parity_bound`, fixed before the - native run from the reference's own runs (``numpy_ref``'s lockstep batch refuses a - coupled member, so the reference is each member run alone). The members differ in - their launch alone. - """ - case = CASES[name]() - original = case.translate() - run_request = case._run_request() # pyright: ignore[reportPrivateUsage] - grid = cast(FieldGrid, case.grid) - problems = [ - dataclasses.replace( - original, - initial=dataclasses.replace( - original.initial, field0=original.initial.field0 * scale - ), - ) - for scale in (1.0, 0.75) - ] - starts = [Start.entrance(one) for one in problems] - requests = [run_request] * len(problems) - assert group_refusal(problems, requests, starts) is None - bounds: list[tuple[ComplexArray, float]] = [] - for problem in problems: - expected = run(NumpyRefBackend, problem, run_request, grid) - small = np.asarray(problem.initial.field0 * 1e-3, dtype=np.complex128) - linear = 1e3 * run(NumpyRefBackend, problem, run_request, grid, small) - bounds.append((expected, _parity_bound(problem, run_request, expected, linear))) - # The session forms the run's statistics, the gas's density among them, from the - # case's profiles. - members = grouped( - [_owner(case, one, run_request) for one in problems], - problems, - requests, - starts, - ) - for problem, member, (expected, bound) in zip( - problems, members, bounds, strict=True - ): - assert member[-1]["z"] == LENGTH - np.testing.assert_array_equal( - member[-1]["attempts"]["dz"], np.full(STEPS, LENGTH / STEPS) - ) - scale = float(np.max(np.abs(problem.initial.field0))) - actual = np.asarray(member[-1]["field"], dtype=np.complex128) - assert float(np.max(np.abs(actual - expected))) / scale <= bound - if one_thread(): - single = alone( - _owner(case, problem, run_request), - problem, - run_request, - Start.entrance(problem), - ) - assert_same(member, single) - # The members differ: each is its own launch, not one copied. - assert not np.array_equal(members[0][-1]["field"], members[1][-1]["field"]) - - def test_a_step_beyond_the_certificate_is_refused_by_name() -> None: # The certificate guards the Runge-Kutta march's inverse flow action; solprop's # default exponential formulation acts forward only and does not measure it. @@ -426,9 +347,9 @@ def test_the_engine_forms_the_reference_s_actions_within_the_formation_bound() - native = backend._native_state # pyright: ignore[reportPrivateUsage] shape = (fractions.size, -1, reference.n_modes, reference.n_modes) for section in range(reference.frozen.shape[0]): - measured = native.form_flow_actions(section, dz, fractions)[0] - forward = native.flow_actions_to_host(False).reshape(shape) - inverse = native.flow_actions_to_host(True).reshape(shape) + measured = _testing.form_flow_actions(native, section, dz, fractions)[0] + forward = _testing.flow_actions_to_host(native, False).reshape(shape) + inverse = _testing.flow_actions_to_host(native, True).reshape(shape) for slot, fraction in enumerate(fractions): if fraction == 0.0: continue diff --git a/native/tests/test_dispersive.py b/native/tests/test_dispersive.py index a0a88f4fb..5a4232550 100644 --- a/native/tests/test_dispersive.py +++ b/native/tests/test_dispersive.py @@ -42,6 +42,7 @@ from solprop.translate.run_request import RunRequest from solprop_native import NativeBackend, _core +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] from solprop_native.backend import ( _lower, # pyright: ignore[reportPrivateUsage] _lower_dispersive, # pyright: ignore[reportPrivateUsage] @@ -287,7 +288,8 @@ def test_a_trial_without_the_densities_is_refused() -> None: assert terms is not None n_phi = terms.shape[0] with pytest.raises(ValueError, match="dispersive densities"): - backend._native_state.trial_step( # pyright: ignore[reportPrivateUsage] + _testing.trial_step( + backend._native_state, # pyright: ignore[reportPrivateUsage] 1e-4, np.zeros((stages + 1) * n_phi), np.zeros(stages * n_phi), @@ -321,7 +323,7 @@ def test_one_evaluation_matches_the_reference(evaluator: str, thg: bool) -> None if isinstance(backend, NativeBackend): state = load_native(backend, problem.initial.field0, clear_fsal=False) native_trial(backend, 0.0, 0.0) - spectra.append(state.projected_to_host(False)) + spectra.append(_testing.projected_to_host(state, False)) else: backend.set_initial(problem.initial.field0, None) backend._adams_lab_source(problem.initial.field0[None], 0.0) # pyright: ignore[reportPrivateUsage] diff --git a/native/tests/test_envelope_plasma.py b/native/tests/test_envelope_plasma.py index faf1e3aaf..23eb591ee 100644 --- a/native/tests/test_envelope_plasma.py +++ b/native/tests/test_envelope_plasma.py @@ -12,21 +12,12 @@ import sys from dataclasses import replace from pathlib import Path -from typing import Any, cast +from typing import cast import numpy as np import pytest from legacy_geometry import LEGACY_GRID -from session_runs import ( - alone, - assert_same, - drain, - grouped, - load_native, - native_trial, - one_thread, - run, -) +from session_runs import drain, load_native, native_trial, run from solprop.backends.events import Outcome from solprop.backends.node_chunk import plan_node_chunk from solprop.backends.numpy_ref import NumpyRefBackend @@ -48,6 +39,7 @@ from thread_sizing import Sizing, assert_threaded from solprop_native import NativeBackend, _core, build_info +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] from solprop_native.backend import ( _lower, # pyright: ignore[reportPrivateUsage] - validate the native boundary _LowerPlan, # pyright: ignore[reportPrivateUsage] - validate the native boundary @@ -195,7 +187,7 @@ def test_envelope_current_streams_use_large_radial_projection() -> None: )[0] state = load_native(actual, problem.initial.field0, clear_fsal=False) native_trial(actual, 0.0, 0.0) - observed = np.asarray(state.stage_to_host(0)).reshape(problem.shape) + observed = np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) info = build_info() if info.device_backend == "none": assert str(actual.metadata()["projection_provider"]).endswith( @@ -480,72 +472,3 @@ def corrupt_payload(*args: object, **keywords: object) -> _core.Problem: assert result.all_planes()[-1].z == grid.length finally: owner.close() - - -def test_envelope_native_group_keeps_noisy_members_and_statistics_independent() -> None: - """Noisy members of a native group agree with the same members run alone. - - Each member and its lone native session share a stored noise draw and replay - eight prescribed steps, each member in its own native session (solprop SEP 47 - section 6.7): bit for bit at one thread, and otherwise held to - :func:`native_bound` (solprop SEP 25), with the schedule's row positions exact. - Every step's periodic row is compared, and the plane statistics at the end. - """ - from solprop.noise import modified_noise - - problem, run_request, grid = envelope_case("modal", 2) - bound = native_bound(problem, grid) - problems: list[PropagationProblem] = [] - starts: list[Start] = [] - singles: list[list[dict[str, Any]]] = [] - for index in range(2): - draw = modified_noise( - grid, np.random.default_rng(390 + index), n_modes=1, n_pol=2 - ) - initial = replace( - problem.initial, - field0=problem.initial.field0 * (1 + 0.125 * index), - noise0=draw.spectrum, - noise_model=draw.model, - ) - one = replace( - problem, initial=initial, flags=replace(problem.flags, has_noise=True) - ) - problems.append(one) - starts.append(Start.entrance(one, noise=draw)) - owner = NativeBackend( - one, run_request, grid=grid, options=envelope_options("modal") - ) - singles.append(alone(owner, one, run_request, Start.entrance(one, noise=draw))) - owners = [ - NativeBackend(one, run_request, grid=grid, options=envelope_options("modal")) - for one in problems - ] - group = grouped(owners, problems, [run_request] * 2, starts) - periodic = set(run_request.observation.stats.periodic) - for member, single in zip(group, singles, strict=True): - # Every step's row reached the end plane. - assert set(single[-1]["rows"]) == periodic - assert len(single[-1]["row_z"]) == 8 - if one_thread(): - assert_same(member, single) - assert [plane["z"] for plane in member] == [plane["z"] for plane in single] - for got, expected in zip(member, single, strict=True): - field = expected["field"] - np.testing.assert_allclose( - got["field"], field, rtol=bound, atol=bound * np.max(np.abs(field)) - ) - for name in NAMES: - np.testing.assert_allclose( - got["stats"][name], expected["stats"][name], rtol=bound, atol=1e-30 - ) - # Exact: the prescribed schedule's positions. - np.testing.assert_array_equal(got["row_z"], expected["row_z"]) - assert got["rows"].keys() == expected["rows"].keys() - for name in expected["rows"]: - np.testing.assert_allclose( - got["rows"][name], - expected["rows"][name], - rtol=bound, - atol=1e-30, - ) diff --git a/native/tests/test_envelope_subnormal.py b/native/tests/test_envelope_subnormal.py index b25068cda..271468fbd 100644 --- a/native/tests/test_envelope_subnormal.py +++ b/native/tests/test_envelope_subnormal.py @@ -47,6 +47,7 @@ from solprop_native import NativeBackend from bounds import fft_bound +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] pytestmark = pytest.mark.filterwarnings( "ignore::solprop.exceptions.MaterialRangeWarning" @@ -123,7 +124,7 @@ def evaluate( # A zero-length trial exposes the first stage, N(E, z = 0). state = load_native(backend, problem.initial.field0, clear_fsal=False) native_trial(backend, 0.0, 0.0) - stage = np.asarray(state.stage_to_host(0)).reshape(problem.shape) + stage = np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) else: backend.set_initial(problem.initial.field0, None) backend._hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe diff --git a/native/tests/test_free.py b/native/tests/test_free.py index 23073c5b4..ea815c826 100644 --- a/native/tests/test_free.py +++ b/native/tests/test_free.py @@ -26,6 +26,7 @@ from solprop.translate.run_request import RunRequest from solprop_native import NativeBackend, _core +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] from solprop_native.backend import ( _lower, # pyright: ignore[reportPrivateUsage] _LowerPlan, # pyright: ignore[reportPrivateUsage] @@ -217,16 +218,16 @@ def test_adams_dense_storage_is_optional_and_reallocation_is_idempotent( expected = (2 * slots + 4 + (slots + 4 if dense else 0)) * field_bytes assert state.memory_ledger()["adams_history"] == expected + 8 * omega if dense: - state.adams_hold() - state.adams_restore() + _testing.adams_hold(state) + _testing.adams_restore(state) np.testing.assert_array_equal( state.field_to_host().reshape(-1), initial ) else: with pytest.raises(RuntimeError, match="dense observation storage"): - state.adams_hold() + _testing.adams_hold(state) with pytest.raises(RuntimeError, match="dense observation storage"): - state.adams_restore() + _testing.adams_restore(state) finally: state.close() state.close() @@ -251,7 +252,7 @@ def test_adams_rows_cross_to_the_host_and_back_exactly( rng = np.random.default_rng(29) rows = rng.standard_normal(shape) + 1j * rng.standard_normal(shape) state.adams_rows_from_host("store", rows) - back = state.adams_rows_to_host("store") + back = _testing.adams_rows_to_host(state, "store") assert back.shape == shape assert back.dtype == np.complex128 np.testing.assert_array_equal(back, rows) @@ -267,11 +268,11 @@ def test_adams_rows_cross_to_the_host_and_back_exactly( with pytest.raises(TypeError): state.adams_rows_from_host("store", np.asfortranarray(rows)) with pytest.raises(ValueError, match="unknown Adams history row"): - state.adams_rows_to_host("slopes") + _testing.adams_rows_to_host(state, "slopes") with pytest.raises(RuntimeError, match="not allocated"): - state.adams_rows_to_host("states") + _testing.adams_rows_to_host(state, "states") # Nothing was copied by a refused call. - np.testing.assert_array_equal(state.adams_rows_to_host("store"), rows) + np.testing.assert_array_equal(_testing.adams_rows_to_host(state, "store"), rows) finally: state.close() diff --git a/native/tests/test_general_modal.py b/native/tests/test_general_modal.py index c9be00038..65831772c 100644 --- a/native/tests/test_general_modal.py +++ b/native/tests/test_general_modal.py @@ -29,7 +29,7 @@ import numpy as np import numpy.typing as npt import pytest -from session_runs import alone, assert_same, grouped, launch, one_thread, run +from session_runs import launch, run from solprop.backends.node_chunk import DEFAULT_NODE_BUDGET, general_node_chunk from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.session import Start @@ -558,44 +558,6 @@ def test_the_two_channel_cases_agree_to_rounding_under_the_thread_count( _agree_across_threads(names, (1, threads), tmp_path) -def test_a_group_of_general_members_agrees_with_its_members_alone() -> None: - """Each member of a native group is the same member run alone. - - Each member and its lone native session march the same prescribed, fixed-order - steps, each member in its own native session (solprop SEP 47 section 6.7): bit - for bit at one thread, and otherwise held to the member's own - :func:`_parity_bound` (solprop SEP 25). - """ - case = CASES["delayed_tensor"]() - launches = [case.state, 0.5 * case.state[::-1].copy()] - cases = [dataclasses.replace(case, state=state) for state in launches] - bounds = [ - _parity_bound(one, _run(NativeBackend, one)[0], _linear(one)) for one in cases - ] - problem, request = case.problem, case.run_request - z = float(problem.initial.z) - - def owner() -> NativeBackend: - return NativeBackend(problem, request, grid=case.simulation.grid) - - singles = [ - alone(owner(), problem, request, Start(field=state, z=z)) for state in launches - ] - members = grouped( - [owner() for _ in launches], - [problem] * len(launches), - [request] * len(launches), - [Start(field=state, z=z) for state in launches], - ) - for member, single, bound in zip(members, singles, bounds, strict=True): - assert single[-1]["z"] == Z_END - if one_thread(): - assert_same(member, single) - assert [plane["z"] for plane in member] == [plane["z"] for plane in single] - actual, expected = member[-1]["field"], single[-1]["field"] - assert float(np.max(np.abs(actual - expected))) <= bound - - def _moving_grin() -> tuple[Simulation, PropagationProblem, RunRequest]: """Build solprop's graded-index sector on a 10 % taper over the millimetre. diff --git a/native/tests/test_mixtures.py b/native/tests/test_mixtures.py index b4ab05229..31f58f4e9 100644 --- a/native/tests/test_mixtures.py +++ b/native/tests/test_mixtures.py @@ -22,6 +22,7 @@ from solprop.translate.run_request import RunRequest from solprop_native import NativeBackend, _core +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] from solprop_native.backend import ( _lower, # pyright: ignore[reportPrivateUsage] - corrupt native payloads _LowerPlan, # pyright: ignore[reportPrivateUsage] - corrupt native payloads @@ -132,11 +133,20 @@ def test_native_statistics_refuse_channel_preionisation_shape( try: load_native(backend, problem.initial.field0, clear_fsal=False) with pytest.raises(ValueError, match="channel preionisation"): - backend._native_state.statistics( # pyright: ignore[reportPrivateUsage] - native refusal - 1 << 11, np.empty(0), np.empty(0), 0.0, 1.0, 0.0, 1.0, np.zeros(1) + _testing.statistics( + backend._native_state, # pyright: ignore[reportPrivateUsage] - native refusal + 1 << 11, + np.empty(0), + np.empty(0), + 0.0, + 1.0, + 0.0, + 1.0, + np.zeros(1), ) with pytest.raises(ValueError, match="channel preionisation"): - backend._native_state.statistics( # pyright: ignore[reportPrivateUsage] - native refusal + _testing.statistics( + backend._native_state, # pyright: ignore[reportPrivateUsage] - native refusal 1 << 11, np.empty(0), np.empty(0), diff --git a/native/tests/test_planning.py b/native/tests/test_planning.py index 4216361cc..0748a4e0d 100644 --- a/native/tests/test_planning.py +++ b/native/tests/test_planning.py @@ -14,6 +14,7 @@ import solprop_native as native from solprop_native import _core +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] from solprop_native.backend import NativeBackend if native.build_info().device_backend != "none": # pragma: no cover - device builds @@ -94,7 +95,7 @@ def test_stale_wisdom_never_reaches_a_profiled_workspace( # a profile forgets it before planning, and its estimate plans are FFTW's own. wisdom = _capture(phase_a_case) for text in wisdom.values(): - assert _core.import_fftw_wisdom(text) + assert _testing.import_fftw_wisdom(text) assert _entries(_core.export_fftw_wisdom()) > 0 efforts = {"rows": "estimate", "threaded_rows": "estimate", "planes": "estimate"} found = _plan(phase_a_case, {"mode": "profile", "efforts": efforts, "wisdom": {}}) diff --git a/native/tests/test_radial.py b/native/tests/test_radial.py index 50d602f7b..c2e793747 100644 --- a/native/tests/test_radial.py +++ b/native/tests/test_radial.py @@ -21,6 +21,7 @@ from solprop.translate.assembly import assemble from solprop_native import NativeBackend, build_info +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] @pytest.mark.parametrize( @@ -134,7 +135,7 @@ def test_radial_partial_chunks_preserve_the_reference_source( assert (ledger["retained_synthesis"] > 0) == retained state = load_native(backend, problem.initial.field0, clear_fsal=False) native_trial(backend, 0.0, 0.0) - actual = np.asarray(state.stage_to_host(0)).reshape(problem.shape) + actual = np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) assert np.isfinite(actual).all() scale = float(np.max(np.abs(expected))) assert scale > 0 @@ -142,7 +143,7 @@ def test_radial_partial_chunks_preserve_the_reference_source( assert np.count_nonzero(actual[..., ~grid.active_mask]) == 0 load_native(backend, np.zeros_like(problem.initial.field0), clear_fsal=False) native_trial(backend, 0.0, 0.0) - assert np.count_nonzero(state.stage_to_host(0)) == 0 + assert np.count_nonzero(_testing.stage_to_host(state, 0)) == 0 assert backend.memory_ledger() == ledger finally: backend.close() diff --git a/native/tests/test_thread_default.py b/native/tests/test_thread_default.py index 2b4a589ba..909fe3f07 100644 --- a/native/tests/test_thread_default.py +++ b/native/tests/test_thread_default.py @@ -19,14 +19,16 @@ import solprop_native from solprop_native import ( - _core, _wait, # pyright: ignore[reportPrivateUsage] ) +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] def _on_a_thread() -> int: seen: list[int] = [] - worker = threading.Thread(target=lambda: seen.append(_core.scoped_openmp_default())) + worker = threading.Thread( + target=lambda: seen.append(_testing.scoped_openmp_default()) + ) worker.start() worker.join() return seen[0] @@ -35,9 +37,9 @@ def _on_a_thread() -> int: def test_a_native_call_sees_the_runtime_width_on_every_thread(): width = solprop_native.build_info().runtime_threads if not solprop_native.build_info().openmp_library: - assert _core.scoped_openmp_default() == 1 + assert _testing.scoped_openmp_default() == 1 return - assert _core.scoped_openmp_default() == width + assert _testing.scoped_openmp_default() == width # A Python thread starts from the runtime's process-wide default (every CPU unless # OMP_NUM_THREADS says otherwise), which the scope replaces and then restores. assert _on_a_thread() == width @@ -46,7 +48,7 @@ def test_a_native_call_sees_the_runtime_width_on_every_thread(): def test_llvm_threads_spin_briefly_inside_native_calls_only(): """On LLVM's runtime the core spins idle threads inside a call (ADR-071).""" - inside = _core.scoped_block_time() + inside = _testing.scoped_block_time() if inside < 0: pytest.skip("GNU's runtime reads its spin count once, at start") if solprop_native.WAIT_POLICY != "spin": diff --git a/native/tests/test_wisdom.py b/native/tests/test_wisdom.py index f22b7c314..9fed9c670 100644 --- a/native/tests/test_wisdom.py +++ b/native/tests/test_wisdom.py @@ -18,6 +18,7 @@ import solprop_native from solprop_native import NativeBackend, _core, _wisdom +from solprop_native._core import _testing # pyright: ignore[reportPrivateUsage] _KEY = "machine-and-build" @@ -249,7 +250,7 @@ def measured(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path: monkeypatch.setenv(_wisdom.ENVIRONMENT, str(tmp_path / "wisdom")) monkeypatch.setattr(_wisdom, "_read", {}) monkeypatch.setattr(_wisdom, "_measured", {}) - _core.forget_fftw_wisdom() + _testing.forget_fftw_wisdom() path = _wisdom.wisdom_file() assert path is not None return path @@ -294,7 +295,7 @@ def test_a_second_run_of_a_shape_plans_without_measuring( # A new process: nothing of this one's plans in memory or in FFTW. monkeypatch.setattr(_wisdom, "_read", {}) monkeypatch.setattr(_wisdom, "_measured", {}) - _core.forget_fftw_wisdom() + _testing.forget_fftw_wisdom() second = NativeBackend(problem, run_request, grid=grid) try: metadata = second.metadata() @@ -383,7 +384,7 @@ def test_an_estimate_run_takes_the_stored_plans_without_seeding( monkeypatch.setenv("SOLPROP_FFTW_PLAN", "estimate") monkeypatch.setattr(_wisdom, "_read", {}) monkeypatch.setattr(_wisdom, "_measured", {}) - _core.forget_fftw_wisdom() + _testing.forget_fftw_wisdom() second = NativeBackend(problem, run_request, grid=grid) try: found = _planning(second) diff --git a/pyproject.toml b/pyproject.toml index 4ad4b4468..fa23bc677 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -87,10 +87,11 @@ dev = [ # adds checks); clang-tidy's PyPI wheels start at 23.1.3, the nearest to the # formatter's 23.1.0, and exist for Linux and macOS (the gate is bash) but not # Windows on Arm, where a sync would build LLVM. The build tools let it build the - # editable package and the distribution wheel without isolation. + # editable package and the distribution wheel without isolation; nanobind is the + # release the native build-system pins. "clang-format==23.1.0", "clang-tidy==23.1.4; sys_platform == 'linux' or sys_platform == 'darwin'", - "nanobind>=2.9", + "nanobind==3.1.0", "scikit-build-core>=0.11", "setuptools-scm>=9", "scipy-openblas32>=0.3.34; sys_platform == 'linux' or sys_platform == 'win32'", diff --git a/src/solprop/backends/__init__.py b/src/solprop/backends/__init__.py index 83d9978d5..10d210218 100644 --- a/src/solprop/backends/__init__.py +++ b/src/solprop/backends/__init__.py @@ -15,17 +15,15 @@ from solprop.backends.protocol import ( Backend, BackendHistory, - BatchBackend, Observation, StepStats, StepSummary, ) -from solprop.backends.registry import available, resolve_name, select, select_batch +from solprop.backends.registry import available, resolve_name, select __all__ = [ "Backend", "BackendHistory", - "BatchBackend", "Observation", "StepStats", "StepSummary", @@ -33,6 +31,5 @@ "available", "resolve_name", "select", - "select_batch", "thread_budget", ] diff --git a/src/solprop/backends/events.py b/src/solprop/backends/events.py index b5111614d..c0ef5e14f 100644 --- a/src/solprop/backends/events.py +++ b/src/solprop/backends/events.py @@ -57,7 +57,6 @@ "Event", "EventBatch", "ExportTicket", - "GroupBatch", "ObservationKind", "ObservationReady", "Outcome", @@ -178,16 +177,11 @@ class ExportTicket: The committed state generation (or dense observation) the field is taken from. z : float Position of that state, m. - member : int or None - The group member whose field it names (a - :class:`~solprop.backends.session.GroupSession`'s ticket, whose members share - one batch and generation); ``None`` for a lone session's. """ receipt: Receipt generation: int z: float - member: int | None = None @dataclass(frozen=True, eq=False) @@ -393,38 +387,6 @@ def terminal(self) -> Terminal | None: # numpydoc ignore=RT01 return None -@dataclass(frozen=True, eq=False) -class GroupBatch: - """What one call to a group's ``advance`` produced: one common schedule window. - - A group (:class:`solprop.backends.session.GroupSession`) advances its members - through one shared fixed schedule. Each member keeps its own events: its - observations, with its own attempts and statistics and a ticket for its field, - and its own terminal outcome (SEP 47 section 6.7). - - Attributes - ---------- - receipt : Receipt - Acknowledge it to release the window and advance to the next. - members : tuple of tuple - Each member's events in member order, in committed order; empty for a - member that ended in an earlier window. - outcome : Outcome or None - The group's own outcome when the batch ends it: ``COMPLETED`` once the - schedule is run, whatever each member's outcome; ``FAILED`` or ``STOPPED`` - when a group-wide failure or stop ended every member still running. - ``None`` otherwise. - error : BaseException or None - A group-wide failure's primary error, carried also by each such member's - :class:`Terminal`; ``None`` otherwise. - """ - - receipt: Receipt - members: tuple[tuple[Event, ...], ...] - outcome: Outcome | None = None - error: BaseException | None = None - - def _column( histories: list[BackendHistory], name: str, dtype: type = np.float64 ) -> np.ndarray: diff --git a/src/solprop/backends/host/__init__.py b/src/solprop/backends/host/__init__.py index 8be5240a8..7a3d7e8bb 100644 --- a/src/solprop/backends/host/__init__.py +++ b/src/solprop/backends/host/__init__.py @@ -6,11 +6,9 @@ The stateful control the reference session runs on: the step driver (:mod:`solprop.backends.host.driver`), the Adams march -(:mod:`~solprop.backends.host.adams`), the -low-storage march (:mod:`~solprop.backends.host.low_storage`), the fixed-schedule group -(:mod:`~solprop.backends.host.group`), the reference's run session -(:mod:`~solprop.backends.host.session`) and its group session -(:mod:`~solprop.backends.host.group_session`). The reference shares only stateless +(:mod:`~solprop.backends.host.adams`), the low-storage march +(:mod:`~solprop.backends.host.low_storage`) and the reference's run session +(:mod:`~solprop.backends.host.session`). The reference shares only stateless numerical modules with the native backend -- the controller cores, tableaux, stage tables, the exponential coefficients, the Adams and low-storage host engines (:class:`~solprop.backends.numpy_ref.multistep.HostHistory`, diff --git a/src/solprop/backends/host/adams.py b/src/solprop/backends/host/adams.py index a70c1cb77..4c5aa3c63 100644 --- a/src/solprop/backends/host/adams.py +++ b/src/solprop/backends/host/adams.py @@ -399,9 +399,8 @@ def _replay_to(self, schedule: FixedSchedule, target: float) -> None: def replay_step(self, dz: float, end: float, slack: float) -> float: """Take one prescribed step from the backend's position and accept it. - The unit a replay and a lockstep group advance by - (:class:`solprop.backends.host.group.HostGroup`): the budget, the startup of - an empty history, the step and, when `end` is a hard kink, the restart. + The unit a replay advances by: the budget, the startup of an empty history, + the step and, when `end` is a hard kink, the restart. Parameters ---------- diff --git a/src/solprop/backends/host/driver.py b/src/solprop/backends/host/driver.py index f2d607f54..5e3a3ad8d 100644 --- a/src/solprop/backends/host/driver.py +++ b/src/solprop/backends/host/driver.py @@ -50,7 +50,6 @@ from solprop.backends.session import ( ExecutionOptions, PreparedExecution, - PreparedGroup, Start, ) from solprop.exceptions import BackendError, BoundaryError, ConvergenceError @@ -318,8 +317,6 @@ class HostDriver[_StateT](ABC): # noqa: UP049 - the protected state type is pri ---------- name : str The registry name, set by the subclass and used in every log line. - max_batch : int - How many problems the backend steps at once. propagator_default : {'tabulate', 'recompute'} What this backend resolves the contract's ``"auto"`` propagator mode to. The default suits a backend that evaluates two complex exponentials per stage; one @@ -332,7 +329,6 @@ class HostDriver[_StateT](ABC): # noqa: UP049 - the protected state type is pri """ name: str = "driver" - max_batch: int = 1 propagator_default: PropagatorMode = "tabulate" helpers: Helpers = PLAIN @@ -481,7 +477,7 @@ def _reserve_source_calls(self, count: int) -> None: """Reserve a complete trial's external source calls when a service is bound. The base always raises: the driver that runs an Adams march (the reference - backend) keeps its own reservations, and a group's members reserve theirs. + backend) keeps its own reservations. """ raise NotImplementedError @@ -730,44 +726,9 @@ def prepare( # A concrete driver is a backend: this base is the march, and the subclass # supplies the rest of the protocol (`memory_ledger`, `close`). They are not - # abstract here, so that a batch's protocol check can refuse a driver without. + # abstract here, so that a protocol check can refuse a driver without. return HostPrepared(cast("Backend", self), problem, request) - def prepare_group( - self, - members: Sequence[Backend], - problems: Sequence[PropagationProblem], - requests: Sequence[RunRequest], - ) -> PreparedGroup: - """Prepare a group of compatible members of this backend (SEP 47 section 6.7). - - The reference's own group - (:class:`~solprop.backends.host.group_session.HostGroupSession`): its members - advance in lockstep through one fixed schedule on the reference's group runner - (:class:`~solprop.backends.host.group.HostGroup` or - :class:`~solprop.backends.numpy_ref.batch.NumpyBatchBackend`, chosen by - :func:`solprop.backends.registry.select_batch`). - - Parameters - ---------- - members : sequence of solprop.backends.protocol.Backend - One constructed backend per member, this one first. - problems : sequence of solprop.translate.problem.PropagationProblem - Each member's independently translated problem. - requests : sequence of solprop.translate.run_request.RunRequest - Each member's run request. - - Returns - ------- - solprop.backends.session.PreparedGroup - The prepared group. - """ - from solprop.backends.host.group_session import ( # noqa: PLC0415 - it builds on this module - HostPreparedGroup, - ) - - return HostPreparedGroup(members, problems, requests) - @property def request(self) -> RunRequest: # numpydoc ignore=RT01 """Request this backend was built for. @@ -1310,8 +1271,7 @@ def propagate_to(self, z: float) -> StepSummary: self._z, record.n_accepted + record.n_rejected, record.n_rejected, - # The run's integrator, not this driver's march: a lockstep runner holds - # none of its own while its members each hold one. + # The run's integrator decides: the low-storage march estimates no error. NOT_ESTIMATED if isinstance(self._stepper.integrator, LowStorageRungeKutta) else f"{record.tolerance_ratio:.3e}", @@ -1395,9 +1355,8 @@ def in_flight(self) -> tuple[float, float] | None: # numpydoc ignore=RT01 def position(self) -> float: # numpydoc ignore=RT01 """Where the march stands, m. - The committed state's position, or the end of a step a group took but - neither validated nor recorded, which leaves the state in flight - (:attr:`in_flight`). + The committed state's position, or the end of a low-storage step a failure + abandoned, which leaves the state in flight (:attr:`in_flight`). """ return float(self._z) diff --git a/src/solprop/backends/host/group.py b/src/solprop/backends/host/group.py deleted file mode 100644 index 6bda576b4..000000000 --- a/src/solprop/backends/host/group.py +++ /dev/null @@ -1,545 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""The reference's fixed-schedule group: lockstep over independent member workspaces. - -:class:`HostGroup` executes each member's own kernels at each shared step of a common -fixed schedule (SEP 47 section 6.7: a reference group iterates its members in Python). -It is owned by the NumPy reference since SEP 47 phase 2; the native bridge's copy of -the lockstep runner was deleted in phase 5, when the native group session -(``solprop_native.group``) became the only native group. -""" - -import copy -import functools -from collections.abc import Callable, Mapping, Sequence -from contextlib import ExitStack -from typing import cast - -import numpy as np -from jaxtyping import Complex - -from solprop.backends.host.adams import HostAdamsMarch -from solprop.backends.host.driver import HostDriver, replay_tolerance -from solprop.backends.protocol import Backend, Observation -from solprop.exceptions import BackendError, BoundaryError, BoundaryWarning -from solprop.monitor import BoundaryMonitor -from solprop.stats import StatsSpec -from solprop.stepper.schedule import FixedSchedule -from solprop.translate.problem import PropagationProblem - -__all__ = ["HostGroup"] - - -def _refuse_invalid_norm(norms: Sequence[float], backend: str) -> None: - """Name the member whose diagnostic no step record on any route can carry. - - A batch only replays, so every step it records is accepted, and a non-finite or - negative error norm on an accepted step is refused by ``BackendHistory`` and - ``StepSummary`` at the next save plane whether the member ran in a batch or - alone, so this is not a batch-only rule; what the batch owes the caller is the - member's index, rather than an anonymous history error one plane later that - the reader cannot attribute to a point. - """ - for index, norm in enumerate(norms): - if not (np.isfinite(norm) and norm >= 0.0): - raise BackendError( - f"{backend} batch member {index} returned an invalid error norm " - f"{norm!r}, which its own step record also refuses" - ) - - -class HostGroup(HostDriver[tuple[object, ...]]): - """Advance loaded member workspaces through one shared fixed-schedule march. - - Each workspace retains its own parameter tables, noise, error estimate and - statistics storage hooks. The maximum norm is a batch diagnostic only: fixed - replay does not use it to change any member's schedule. Member observations - carry their own error histories, never that maximum. - - The caller validates layout compatibility and admits memory before constructing - this runner. Ownership of the loaded workspaces transfers to the runner after - successful construction; ``close`` releases every member. - - Each member watches its own time window (SEP 21). A member whose monitor stops it - stops watching while the others go on, and :attr:`member_stops` says which, so - that a batched scan fails that point alone, as a run of it alone would fail. - - Parameters - ---------- - members : sequence of solprop.backends.host.driver.HostDriver - Nonempty sequence of loaded singleton backends with the same name and fixed - schedule. All must be at the entrance with no previously attempted steps. - - Raises - ------ - BackendError - If members mix backends, lack a common fixed schedule, are already advanced, - or have different save planes or periodic-statistics requests. - """ - - def __init__(self, members: Sequence[HostDriver[object]]) -> None: - self._members: tuple[HostDriver[object], ...] = tuple(members) - _validate_members(self._members) - first = self._members[0] - # The members read the transverse edge, or not; the runner speaks for them. - self.reads_transverse_edge = first.reads_transverse_edge - super().__init__(first._problem, first._request) - self.name = first.name - self.max_batch = len(self._members) - self._state = tuple(member._require_state() for member in self._members) - self._member_norms: tuple[float, ...] = () - self._stops: list[BoundaryError | BoundaryWarning | None] = [None] * len( - self._members - ) - self._records: list[Mapping[str, object] | None] = [None] * len(self._members) - - def _apply_mask( - self, state: Complex[np.ndarray, "n_batch n_modes n_pol n_omega"] - ) -> tuple[object, ...]: - """Refuse loading a shared field in place of independently loaded members.""" - del state - raise BackendError("HostGroup requires independently loaded members") - - def _trial_step(self, z: float, dz: float) -> tuple[float, tuple[object, ...]]: - """Evaluate independent trial states at one common fixed step. - - - ``z``: start position, m. - - ``dz``: positive step length, m. - - Returns: maximum diagnostic norm and independently owned trial states. - """ - trials = tuple(member._trial_step(z, dz) for member in self._members) - self._member_norms = tuple(norm for norm, _ in trials) - _refuse_invalid_norm(self._member_norms, "lockstep") - return max(self._member_norms), tuple(state for _, state in trials) - - def _replay_to(self, schedule: FixedSchedule, target: float) -> None: - """Replay the shared schedule; members stepped by their own march each own one. - - Runge-Kutta members share the base replay through :meth:`_trial_step`. An - Adams member's history, order and ledger are its own, and a low-storage - member's registers and flow table (SEP 24), so each takes the common step - through its own march - (:meth:`solprop.backends.host.adams.HostAdamsMarch.replay_step`, - :meth:`solprop.backends.host.low_storage.HostLowStorageMarch.replay_step`) and - the shared itinerary is recorded once, with each member's own norm. A member - left in flight by an abandoned step refuses the next one. - - - ``target``: position to reach, m. - """ - marches = [ - member._adams if member._adams is not None else member._low_storage - for member in self._members - ] - if marches[0] is None: - super()._replay_to(schedule, target) - return - edges = schedule.edges - slack = replay_tolerance(schedule, target) - # Before any member steps: a member left in flight refuses, and the members - # ahead of it in the batch must not be advanced again past the itinerary. - for member in self._members: - member._refuse_in_flight() - while self._schedule_index < schedule.n_steps and self._z < target - slack: - self._poll_stop() - dz = float(schedule.steps[self._schedule_index]) - end = float(edges[self._schedule_index + 1]) - norms: list[float] = [] - for member, march in zip(self._members, marches, strict=True): - assert march is not None # one integrator: every member has a march - norms.append(march.replay_step(dz, end, slack)) - # Stepped, but neither validated nor recorded: until the common step - # is, this member's state is neither end of its record, so a later - # member's failure or a refused norm leaves it in flight, not - # resumable (SEP 47 section 6.7). - member._in_flight = (self._z, dz) - self._member_norms = tuple(norms) - _refuse_invalid_norm(self._member_norms, "lockstep") - for member in self._members: - member._in_flight = None - self._state = tuple(member._require_state() for member in self._members) - self._schedule_index += 1 - self._z = end - self._record(end, dz, max(self._member_norms), accepted=True) - self._accepted_norms.append(max(self._member_norms)) - # A member whose next proposal fell below the floor raises it once the - # common step is recorded (SEP 39 section 4.4). - for march in marches: - if isinstance(march, HostAdamsMarch): - march._raise_floor() - self._take_step_stats() - if self._natural_stop(target): - return - if self._z < target - slack: - msg = ( - f"the replayed schedule ends at {float(schedule.z_end):.6g} m and " - f"cannot reach z = {target:.6g} m" - ) - raise BackendError(msg) - - def _finish(self, state: tuple[object, ...], dz: float) -> tuple[object, ...]: - """Apply each member's accepted-step boundary handling. - - - ``dz``: accepted step length, m. - """ - finished = tuple( - member._finish(value, dz) - for member, value in zip(self._members, state, strict=True) - ) - for member, value in zip(self._members, finished, strict=True): - member._state = value - return finished - - def _record(self, z: float, dz: float, norm: float, accepted: bool) -> None: - """Record the common itinerary and each member's own error estimate. - - - ``z``: end position, m. - - ``dz``: step length, m. - """ - super()._record(z, dz, norm, accepted) - for member, own_norm in zip(self._members, self._member_norms, strict=True): - member._z = z - member._schedule_index = self._schedule_index - member._record(z, dz, own_norm, accepted) - member._accepted_norms.append(own_norm) - - def attach_monitor(self, monitor: BoundaryMonitor) -> None: - """Give every member its own copy of the boundary monitor (SEP 21). - - Parameters - ---------- - monitor : solprop.monitor.BoundaryMonitor - A monitor with nothing recorded, copied per member. - """ - self.attach_monitors([copy.deepcopy(monitor) for _ in self._members]) - - def attach_monitors(self, monitors: Sequence[BoundaryMonitor | None]) -> None: - """Give each member its own boundary monitor, or none (SEP 21). - - A launch the monitor refuses stops that member's watch alone - (:attr:`member_stops`). - - Parameters - ---------- - monitors : collections.abc.Sequence - One monitor with nothing recorded, or ``None``, per member, in member - order. - - Raises - ------ - BackendError - If the count differs from the members'. - """ - if len(monitors) != len(self._members): - raise BackendError( - f"{len(monitors)} boundary monitors for {len(self._members)} members" - ) - for index, (member, monitor) in enumerate( - zip(self._members, monitors, strict=True) - ): - if monitor is not None: - self._watched(index, functools.partial(member.attach_monitor, monitor)) - - @property - def member_stops( - self, - ) -> tuple[BoundaryError | BoundaryWarning | None, ...]: # numpydoc ignore=RT01 - """What stopped each member's watch, in member order. - - The :class:`~solprop.exceptions.BoundaryError` that stopped a member, the - :class:`~solprop.exceptions.BoundaryWarning` raised as an error for it - under an ``"error"`` warnings filter, or ``None`` for one still watched - or never watched. - """ - return tuple(self._stops) - - @property - def member_records( - self, - ) -> tuple[Mapping[str, object] | None, ...]: # numpydoc ignore=RT01 - """Each member's monitor record, as it closed, in member order. - - A stopped member's is its record at the stop; a watched one's is read now. - - The :meth:`~solprop.monitor.BoundaryMonitor.summary` of each member, or - ``None`` for one never watched. - """ - return tuple( - record if member._monitor is None else member._monitor.summary() - for member, record in zip(self._members, self._records, strict=True) - ) - - def finish_monitors(self) -> None: - """Report each still-watched member's removed fraction at the run's end. - - A warning raised as an error fails that member alone (:attr:`member_stops`), - as a run of it alone would fail. - """ - for index, member in enumerate(self._members): - monitor = member._monitor - if monitor is not None: - self._watched(index, monitor.finish) - - def _watched(self, index: int, call: Callable[[], None]) -> None: - """Make one member's monitor call; a stop ends that member's watch alone. - - The member's march goes on with the others, unwatched and with its collar in - every stage; its result is the caller's to discard. - """ - member = self._members[index] - try: - call() - except (BoundaryError, BoundaryWarning) as error: - self._stops[index] = error - # Only a watched member's call raises its stop: attach_monitor watches it - # before the launch is judged, and the other calls return when unwatched. - monitor = member._monitor - assert monitor is not None - self._records[index] = monitor.summary() - member._monitor = None - # The member's backend stops reading for it, a split's removal included. - member._bind_monitor(None) - member._set_collar_quiet(False) - - def _monitor_plane(self) -> None: - """Close each member's boundary-monitor row for the plane just reached.""" - for index, member in enumerate(self._members): - self._watched(index, member._monitor_plane) - - def _take_step_stats(self) -> None: - """Collect periodic rows through each backend's storage hooks.""" - for index, member in enumerate(self._members): - self._watched(index, member._take_step_stats) - - def _begin_plane(self) -> None: - """Reset each member's observation interval without releasing buffers.""" - for member in self._members: - member._reset_step_stats(release=False) - member._begin_plane() - - def stats(self, spec: StatsSpec) -> dict[str, np.ndarray]: - """Collect member statistics, stacked on a leading member axis. - - Parameters - ---------- - spec : solprop.stats.StatsSpec - Names and windows evaluated independently by each member. - - Returns - ------- - dict of str to numpy.ndarray - Host statistics, each member's own stacked in member order. - """ - self._require_state() - values = [member.stats(spec) for member in self._members] - if any(value.keys() != values[0].keys() for value in values): - raise BackendError("lockstep members returned different statistic names") - return {name: np.stack([value[name] for value in values]) for name in values[0]} - - def observe_members(self, *, field: bool = True) -> tuple[Observation, ...]: - """Drain each member's host observation and its own diagnostic history. - - Parameters - ---------- - field : bool, optional - Whether each member's field and noise phase cross to the host, as for a - lone run's ``observe``. Default ``True``. - - Returns - ------- - tuple of solprop.backends.protocol.Observation - Each member's observation in member order, with its own field or no - field, and independently retained periodic rows. - """ - self._require_state() - observations = tuple(member.observe(field=field) for member in self._members) - self._history = [] - return observations - - def observe(self, *, field: bool = True) -> Observation: # noqa: ARG002 - refused - """Refuse an observation that would substitute a shared member history. - - Parameters - ---------- - field : bool, optional - Unused: the observation is refused either way. - - Raises - ------ - BackendError - Always; use ``observe_members`` to retain each member's error norms. - """ - raise BackendError("use observe_members to preserve individual error histories") - - def available_device_memory(self) -> int | None: - """Read the selected device's free bytes through its first member. - - Returns - ------- - int or None - Free device bytes, or None for a host batch. - """ - self._check_open() - return self._members[0].available_device_memory() - - def metadata(self) -> dict[str, object]: - """Describe the lockstep execution strategy without implying fused kernels. - - Returns - ------- - dict - Selected backend, member count and workspace strategy. - """ - return { - "backend": self.name, - "batch_size": self.max_batch, - "batch_strategy": "member_workspaces", - "fused_batch_kernels": False, - } - - def member_metadata(self) -> tuple[dict[str, object], ...]: - """Return each member's resolved policies with the shared batch strategy. - - Returns - ------- - tuple of dict - Complete backend provenance in member order. - """ - return tuple(member.metadata() | self.metadata() for member in self._members) - - def memory_ledger(self) -> dict[str, int]: - """Name each member's workspace allocations separately. - - Returns - ------- - dict of str to int - Backend allocation bytes under member-prefixed names. Shared translation - products are accounted separately by the common driver's host budget. - """ - return { - f"member/{index}/{name}": size - for index, member in enumerate(self._members) - for name, size in cast(Backend, member).memory_ledger().items() - } - - def close(self) -> None: - """Release every member workspace and the common march state.""" - try: - with ExitStack() as cleanup: - for member in self._members: - cleanup.callback(cast(Backend, member).close) - finally: - self._state = None - self._closed = True - self._history = [] - self._rows.clear() - self._members = () - - -def _validate_members(members: tuple[HostDriver[object], ...]) -> None: - """Require one backend and a shared entrance-to-end replay contract.""" - if not members: - raise BackendError("lockstep execution requires at least one member") - first = members[0] - settings = first._stepper - schedule = settings.schedule - if schedule is None: - raise BackendError("lockstep execution requires an explicit fixed schedule") - for member in members: - if not isinstance(member, Backend): - raise BackendError("lockstep members must implement the backend protocol") - # Before the load: a member of another backend may hold no state here at all. - if member.name != first.name: - raise BackendError("lockstep execution refuses mixed backends") - member._require_state() - if member._z != 0.0 or member._history or member._schedule_index != 0: - raise BackendError( - "lockstep members must be freshly loaded at the entrance" - ) - problem, stepper = member._problem, member._stepper - tableau, reference_tableau = stepper.tableau, settings.tableau - if any( - not np.array_equal(getattr(tableau, name), getattr(reference_tableau, name)) - for name in ("matrix", "nodes", "solution_weights", "error_weights") - ): - raise BackendError("lockstep members require the same tableau") - if not np.array_equal(problem.grids.norm_mask, first._problem.grids.norm_mask): - raise BackendError("lockstep members require the same frequency mask") - other = stepper.schedule - if stepper.integrator != settings.integrator: - raise BackendError("lockstep members require the same integrator") - if problem.shape != first._problem.shape: - raise BackendError("lockstep members require matching field shapes") - if ( - other is None - or other.z_start != schedule.z_start - or not np.array_equal(other.steps, schedule.steps) - or not np.array_equal(stepper.save_planes, settings.save_planes) - ): - raise BackendError( - "lockstep members require the same schedule and save planes" - ) - spec = member._request.observation.stats - reference = first._request.observation.stats - if (spec.names, spec.periodic, spec.period) != ( - reference.names, - reference.periodic, - reference.period, - ) or not ( - np.array_equal(spec.energy_windows, reference.energy_windows) - and spec.same_tables(reference) - ): - raise BackendError("lockstep members require the same statistics request") - _refuse_mixed_guides(problem, first._problem) - - -def _general_leaves(problem: PropagationProblem) -> object: - """Return what general modal guide a problem carries, comparably. - - - Returns: a scalar-and-string description, or ``None`` where the problem carries no - general modal route at all. - """ - tables = problem.transform.modal_tables - if tables is None: - return None - metric = problem.linear.modal_metric - responses = problem.responses.regional_responses - # The flow is in the description because a declared basis of a split block puts - # one on this route, and two members whose blocks differ are two different - # guides however identical their tables read. - flow = problem.linear.coupled_flow - return ( - tuple(sorted(dict(tables.identity).items(), key=str)), - None if metric is None else (metric.kind, metric.gauge_id), - None if responses is None else (responses.model_id, responses.policy_id), - None - if flow is None - else (flow.gauge_id, flow.certificate_id, flow.section_methods), - ) - - -def _refuse_mixed_guides( - problem: PropagationProblem, reference: PropagationProblem -) -> None: - """Refuse a lockstep group whose members are not one general modal guide. - - The narrow admission rule for a batch of general modal guides, applied at the - backend: a general-guide batch shares the physical guide, the ordered channels, - the materials, the gauge and the table identity, and its members differ in - their launch and their noise seed alone. The grouping signature separates two - guides already (:func:`solprop.driver.batch.refuse_mixed_guides`); this is the - check that does not depend on a caller having grouped carefully, written - against the leaves a backend actually sees rather than against the driver's - descriptor. - """ - if _general_leaves(problem) == _general_leaves(reference): - return - msg = ( - "general-guide batch requires identical guide/table/gauge identity: this " - "member's transform.modal_tables, linear.modal_metric or " - "responses.regional_responses is not member zero's. Members may differ in " - "their launch and their noise seed and in nothing else, because one " - "immutable reference is shared across the group" - ) - raise BackendError(msg) diff --git a/src/solprop/backends/host/group_session.py b/src/solprop/backends/host/group_session.py deleted file mode 100644 index 812807062..000000000 --- a/src/solprop/backends/host/group_session.py +++ /dev/null @@ -1,694 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""The NumPy reference's group session (SEP 47 section 6.7). - -:class:`HostGroupSession` is the :class:`~solprop.backends.session.GroupSession` that -serves every ``numpy_ref`` group, and :class:`HostPreparedGroup` is -the prepared group a reference backend returns from ``prepare_group``. The group loads -each member from its start and hands the loaded members to the reference's group runner -(:class:`~solprop.backends.host.group.HostGroup`, or its member-axis arithmetic -:class:`~solprop.backends.numpy_ref.batch.NumpyBatchBackend`, the choice -:func:`solprop.backends.registry.select_batch` makes), -which advances every member through each step of the common fixed schedule in turn. -The session presents that march through the group protocol: one window per save plane, -each member's own events, tickets, counters and outcome, and the failure distinction of -SEP 47 section 6.7. - -**Why the runner, rather than one** :class:`~solprop.backends.host.session.HostSession` -**per member.** The native group composes one native session per member -(``solprop_native.group.NativeGroupSession``), each advancing a whole window before the -next. The reference group keeps its runner because what it must preserve is the -runner's, and composed member sessions would change both: - -- *Its arithmetic.* A group evaluates its stages on arrays with a leading - member axis (``NumpyBatchBackend``), whose reductions are ordered differently from a - lone run's: a member and its lone run agree to rounding, not bitwise - (``tests/backends/test_batch_lockstep.py``). Member sessions would run the lone path - and change every group's result. -- *Its failure positions.* Members take each common step in turn, so a failure in one - member ends the group with the members ahead of it in flight at that step's end - (poisoned) and those behind it at the step's start (SEP 47 section 6.7). Member - sessions advancing whole windows in turn would leave the members ahead committed at - the window's end instead. - -Each member's boundary monitor is still its own: a stop ends that member alone while -the others go on (:attr:`~solprop.backends.host.group.HostGroup.member_stops`). -""" - -from __future__ import annotations - -from collections.abc import Mapping, Sequence -from types import TracebackType -from typing import TYPE_CHECKING, Any, cast - -import numpy as np - -from solprop.backends.events import ( - Eligibility, - Event, - ExportTicket, - GroupBatch, - ObservationKind, - ObservationReady, - Outcome, - Receipt, - Terminal, - join_attempts, -) -from solprop.backends.export import ExportRecipe, apply_recipe -from solprop.backends.host.driver import HostDriver -from solprop.backends.protocol import ( - BackendHistory, - Observation, - StepStats, - StepSummary, - stepping, -) -from solprop.backends.session import ( - SessionError, - SessionLedger, - SessionState, - SessionStatus, - Start, - check_group, - check_member_ticket, -) -from solprop.backends.session_core import EMPTY_SUMMARY, bind, export_weight -from solprop.exceptions import StopRequested -from solprop.log import StopFlag -from solprop.translate.problem import PropagationProblem -from solprop.translate.run_request import RunRequest - -if TYPE_CHECKING: - # Under TYPE_CHECKING, so that the runtime type checks of the test suite do not - # check a refused export destination's shape before the group refuses it. - from jaxtyping import Complex - - from solprop.backends.protocol import Backend - -__all__ = ["HostGroupSession", "HostPreparedGroup"] - - -class HostGroupSession: - """The reference's :class:`~solprop.backends.session.GroupSession`. - - As the batched scan always has, the first advance gives every member its boundary - monitor before the launch plane is reported, so that a launch a monitor refuses - ends that member at once. - - Parameters - ---------- - members : collections.abc.Sequence of solprop.backends.protocol.Backend - One constructed reference backend per member, all of one backend. Once the - group is constructed it owns them and closes them with itself; a construction - that fails leaves them to the caller. - problems : collections.abc.Sequence of solprop.translate.problem.PropagationProblem - Each member's independently translated problem. - requests : collections.abc.Sequence of solprop.translate.run_request.RunRequest - Each member's run request, with its own fresh boundary monitor; their save - planes and statistics are the group's common schedule. - starts : collections.abc.Sequence of solprop.backends.session.Start - Each member's start: its entrance, with no method history or monitor to - continue. The group takes each start's field once it is constructed; a - construction that fails leaves them to the caller. - stop : solprop.log.StopFlag or None, optional - A group-wide stop token, polled before every common step. - - Raises - ------ - solprop.backends.session.SessionError - If the sequences differ in length or are empty, if a start is not a fresh - entrance or was already used, or if two members share a start or a backend. - solprop.exceptions.BackendError - If the runner refuses the members (``select_batch``): another backend, or - another schedule, planes or periodic statistics. - """ - - def __init__( - self, - members: Sequence[Backend], - problems: Sequence[PropagationProblem], - requests: Sequence[RunRequest], - starts: Sequence[Start], - *, - stop: StopFlag | None = None, - ) -> None: - """Load every member from its start and build the group runner.""" - from solprop.backends.registry import select_batch # noqa: PLC0415 - cycle - - count = len(members) - check_group(members, problems, requests, starts) - observation = requests[0].observation - # The reference's members step on the host (`HostStepping`). - hosted = tuple(stepping(member) for member in members) - # The entrances are read here and taken only once the runner admits the - # group, so that a refused group leaves the caller's starts to retry with. - for member, start in zip(hosted, starts, strict=True): - member.set_initial( - np.asarray(start.field), - start.noise, - z=float(start.z), - resume=start.resume, - ) - self._members = hosted - # The same members, as the reference's marches whose position and attempt - # record the group reads: the runner below steps host drivers alone. - self._hosts = cast("tuple[HostDriver[Any], ...]", self._members) - self._problems = tuple(problems) - self._requests = tuple(requests) - self._planes = np.asarray(observation.save_planes, dtype=np.float64) - self._runner = select_batch(self._members) - self._runner.set_stop(stop) - for start in starts: - start.take_field() - self._ledger = SessionLedger() - self._launched = False - self._index = 0 - self._generation = 0 - self._z = float(starts[0].z) - self._outcomes: list[Outcome | None] = [None] * count - self._attempts = [0] * count - self._rejected = [0] * count - self._observed: dict[int, Observation] = {} - self._observed_generation = -1 - # Set once a group-wide stop or failure ended every running member. - self._broken = False - # Each member's attempts drained since its previous event and not yet delivered. - self._drained: dict[int, tuple[BackendHistory, StepStats]] = {} - - # -- protocol ------------------------------------------------------------------- - - @property - def n_members(self) -> int: # numpydoc ignore=RT01 - """Number of members.""" - return len(self._members) - - @property - def finished(self) -> bool: # numpydoc ignore=RT01 - """Whether the group's terminal batch was issued. - - True once every member has ended. - """ - return self._ledger.finished - - @property - def closed(self) -> bool: # numpydoc ignore=RT01 - """Whether the group was closed.""" - return self._ledger.state is SessionState.CLOSED - - def advance(self) -> GroupBatch: - """Run every running member through the next common window, and report it. - - Returns - ------- - solprop.backends.events.GroupBatch - Each member's events in the window. - """ - self._ledger.check_advance() - if not self._launched: - self._launched = True - return self._launch() - if self._index >= self._planes.size: - return self._complete() - target = float(self._planes[self._index]) - try: - summary = self._runner.propagate_to(target) - except StopRequested as error: - return self._ended(Outcome.STOPPED, error) - except Exception as error: - return self._ended(Outcome.FAILED, error) - self._z = float(summary.z) - self._generation += 1 - plane = self._index - self._index += 1 - return self._window(ObservationKind.PLANE, plane, summary) - - def acknowledge(self, receipt: Receipt) -> None: - """Release the pending batch and allow advancing past it. - - Parameters - ---------- - receipt : solprop.backends.events.Receipt - The pending batch's receipt. - """ - self._ledger.acknowledge(receipt) - self._observed = {} - - def export( - self, - member: int, - ticket: ExportTicket, - recipe: ExportRecipe, - out: Complex[np.ndarray, "n_modes n_pol n_omega"] | None = None, - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Fill a destination with one member's converted field at a pending ticket. - - Parameters - ---------- - member : int - The member's position. - ticket : solprop.backends.events.ExportTicket - A ticket of the pending batch, for this member: its position is the - member's own. - recipe : solprop.backends.export.ExportRecipe - The conversion. - out : numpy.ndarray or None, optional - The destination; a new array by default. - - Returns - ------- - numpy.ndarray - The member's converted field. - """ - self._ledger.check_ticket(ticket) - check_member_ticket(ticket, self._member(member)) - recipe, weight = export_weight(self._problems[member], ticket.z, recipe) - field = self._fielded(ticket, member).require_field() - return apply_recipe(field, recipe, weight=weight, out=out) - - def noise_phase(self, member: int, ticket: ExportTicket) -> np.ndarray | None: - """Return one member's noise phase at a pending ticket. - - Parameters - ---------- - member : int - The member's position. - ticket : solprop.backends.events.ExportTicket - A ticket of the pending batch. - - Returns - ------- - numpy.ndarray or None - The phase, shape ``(n_modes, n_pol, n_omega)``, or ``None`` without noise. - """ - self._ledger.check_ticket(ticket) - check_member_ticket(ticket, self._member(member)) - phase = self._fielded(ticket, member).noise_phase - return None if phase is None else np.array(phase) - - def member_status(self, member: int) -> SessionStatus: - """Return one member's committed position, counters and outcome. - - Parameters - ---------- - member : int - The member's position. - - Returns - ------- - solprop.backends.session.SessionStatus - Its status; a member that ended reports its own outcome while the group - goes on. - """ - index = self._member(member) - outcome = self._outcomes[index] - state = self._ledger.state - if outcome is not None and state is not SessionState.CLOSED: - state = SessionState.FINISHED - return SessionStatus( - z=self._hosts[index].position, - plane_index=self._index, - attempts=self._attempts[index], - rejected=self._rejected[index], - state=state, - outcome=outcome, - ) - - def execution_record(self, member: int) -> Mapping[str, object]: - """Return one member's execution facts, with the group's strategy. - - Parameters - ---------- - member : int - The member's position. - - Returns - ------- - collections.abc.Mapping - Its backend provenance. - """ - return self._runner.member_metadata()[self._member(member)] - - def monitor_record(self, member: int) -> Mapping[str, object] | None: - """Return one member's boundary-monitor record. - - Parameters - ---------- - member : int - The member's position. - - Returns - ------- - collections.abc.Mapping or None - Its record as it closed or as it stands, or ``None`` when unwatched. - """ - return self._runner.member_records[self._member(member)] - - def close(self) -> None: - """Release every member and the runner; idempotent.""" - if self._ledger.close(): - self._runner.set_stop(None) - self._runner.close() - - def __enter__(self) -> "HostGroupSession": - """Return the group. - - Returns - ------- - HostGroupSession - This group. - """ - return self - - def __exit__( - self, - kind: type[BaseException] | None, - error: BaseException | None, - trace: TracebackType | None, - ) -> None: - """Close the group. - - Parameters - ---------- - kind : type or None - The exception type, if one is propagating. - error : BaseException or None - The exception, if one is propagating. - trace : types.TracebackType or None - Its traceback. - """ - del kind, error, trace - self.close() - - # -- internals ------------------------------------------------------------------ - - def _member(self, member: int) -> int: - """Return a valid member position.""" - if not 0 <= member < len(self._members): - msg = f"the group has {len(self._members)} members, not a member {member}" - raise SessionError(msg) - return member - - def _running(self) -> list[int]: - """Return the members that have not ended.""" - return [index for index, ended in enumerate(self._outcomes) if ended is None] - - def _chunks(self) -> list[tuple[BackendHistory, StepStats]]: - """Drain every member's attempts and rows since the previous window. - - - Returns: each member's attempts and rows (without a batch axis), in member - order. - """ - chunks: list[tuple[BackendHistory, StepStats]] = [] - for index in range(len(self._members)): - # One member at a time, each kept until an event delivers it: a later - # member's failure, or the statistics', ends the group with the attempts - # already drained delivered by the terminals. Each event drains once. - observation = self._members[index].observe(field=False) - self._attempts[index] += observation.n_steps - self._rejected[index] += observation.n_rejected - self._drained[index] = ( - observation.step_history, - observation.step_stats, - ) - chunks.append(self._drained[index]) - return chunks - - def _final_chunk(self, index: int) -> tuple[BackendHistory, StepStats] | None: - """Drain one member's attempts after a group-wide stop or failure. - - A member left in flight cannot be observed; the attempts it recorded before - the abandoned step are drained from its record instead - (:meth:`~solprop.backends.host.driver.HostDriver.drain_attempts`). - - - Returns: its attempts and rows, or ``None`` when its state cannot be read at - all. - """ - member = self._hosts[index] - try: - observed = ( - member.drain_attempts() - if member.in_flight is not None - else member.observe(field=False) - ) - except Exception: - return None - self._attempts[index] += observed.n_steps - self._rejected[index] += observed.n_rejected - return observed.step_history, observed.step_stats - - def _ticket(self, z: float | None = None) -> ExportTicket: - """Return an unbound ticket for a committed state of the current generation. - - - ``z``: the member's committed position, m; the window's end by default. - - Returns: the ticket, its receipt filled in when the batch is issued. - """ - return ExportTicket( - Receipt(self._ledger.session, 0), - self._generation, - self._z if z is None else z, - ) - - def _member_stopped( - self, index: int, chunk: tuple[BackendHistory, StepStats] - ) -> Terminal | None: - """Return a stopped member's terminal event, or ``None`` if it runs on. - - - ``chunk``: its attempts and rows since its previous event. - """ - stop = self._runner.member_stops[index] - if stop is None: - return None - self._outcomes[index] = Outcome.FAILED - cursor = self._hosts[index].position - return Terminal( - Outcome.FAILED, - cursor, - Eligibility.ELIGIBLE, - stop, - self._ticket(cursor), - *chunk, - ) - - def _launch(self) -> GroupBatch: - """Give each member its monitor and report the launch planes.""" - try: - self._runner.attach_monitors( - [request.boundary.monitor for request in self._requests] - ) - except Exception as error: - return self._ended(Outcome.FAILED, error) - return self._window(ObservationKind.LAUNCH, -1, EMPTY_SUMMARY) - - def _window( - self, kind: ObservationKind, plane: int, summary: StepSummary - ) -> GroupBatch: - """Report a window's end: each running member's plane, or its boundary stop.""" - try: - chunks = self._chunks() - stats = self._runner.stats(self._requests[0].observation.stats) - except Exception as error: - return self._ended(Outcome.FAILED, error) - events: list[tuple[Event, ...]] = [] - for index, chunk in enumerate(chunks): - if self._outcomes[index] is not None: - events.append(()) - continue - stopped = self._member_stopped(index, chunk) - if stopped is not None: - events.append((stopped,)) - continue - events.append( - ( - ObservationReady( - z=self._z, - kind=kind, - plane_index=plane, - history=chunk[0], - step_stats=chunk[1], - stats={ - name: np.asarray(value[index]) - for name, value in stats.items() - }, - summary=summary, - ticket=self._ticket(), - ), - ) - ) - if not self._running(): - # Every member ended at its own boundary: nothing is left to advance. - return self._issue(events, outcome=Outcome.COMPLETED) - return self._issue(events) - - def _complete(self) -> GroupBatch: - """Run each watched member's final check and report every outcome.""" - try: - chunks = self._chunks() - self._runner.finish_monitors() - except Exception as error: - return self._ended(Outcome.FAILED, error) - events: list[tuple[Event, ...]] = [] - for index, chunk in enumerate(chunks): - if self._outcomes[index] is not None: - events.append(()) - continue - stopped = self._member_stopped(index, chunk) - if stopped is not None: - events.append((stopped,)) - continue - self._outcomes[index] = Outcome.COMPLETED - events.append( - ( - Terminal( - Outcome.COMPLETED, - self._hosts[index].position, - Eligibility.ELIGIBLE, - None, - None, - *chunk, - ), - ) - ) - return self._issue(events, outcome=Outcome.COMPLETED) - - def _ended(self, outcome: Outcome, error: BaseException) -> GroupBatch: - """End every running member with a group-wide stop or failure. - - Members take each common step in turn, so after a failure partway through one - a member ahead of the failing one stands at the step's end, its step neither - validated nor recorded -- in flight, and so poisoned -- and the others at the - step's start; each reports its own position. - """ - self._generation += 1 - self._broken = True - chunks = [ - join_attempts( - [ - self._drained.get(index, (None, None)), - self._final_chunk(index) or (None, None), - ] - ) - for index in range(len(self._members)) - ] - events: list[tuple[Event, ...]] = [] - for index, chunk in enumerate(chunks): - if self._outcomes[index] is not None: - events.append(()) - continue - self._outcomes[index] = outcome - member = self._hosts[index] - poisoned = member.in_flight is not None - history, rows = chunk - cursor = member.position - events.append( - ( - Terminal( - outcome, - cursor, - Eligibility.POISONED if poisoned else Eligibility.ELIGIBLE, - error, - None if poisoned else self._ticket(cursor), - history, - rows, - ), - ) - ) - return self._issue(events, outcome=outcome, error=error) - - def _issue( - self, - members: list[tuple[Event, ...]], - *, - outcome: Outcome | None = None, - error: BaseException | None = None, - ) -> GroupBatch: - """Issue a window's events under a new receipt. - - - ``outcome``: the group's outcome, when the batch ends it. - """ - receipt = self._ledger.issue(outcome=outcome) - # Every drained attempt is delivered by this batch. - self._drained = {} - bound = tuple( - tuple(bind(event, receipt, index) for event in events) - for index, events in enumerate(members) - ) - return GroupBatch(receipt, bound, outcome, error) - - def _fielded(self, ticket: ExportTicket, member: int) -> Observation: - """Observe a member's field for a ticket once, shared by its exports. - - A window's fields are observed together, once; after a group-wide failure each - member is observed alone, since a member left in flight refuses observation. - """ - if self._observed_generation != ticket.generation: - self._observed = {} - self._observed_generation = ticket.generation - if member not in self._observed: - # The window's attempts were drained when it ended; nothing ran since. - if self._broken: - self._observed[member] = self._members[member].observe(field=True) - else: - self._observed.update( - enumerate(self._runner.observe_members(field=True)) - ) - return self._observed[member] - - -class HostPreparedGroup: - """A prepared group of reference members (SEP 47 section 6.7). - - Each :meth:`start` opens one :class:`HostGroupSession` over the members. - - Parameters - ---------- - members : collections.abc.Sequence of solprop.backends.protocol.Backend - One constructed reference backend per member, all of one backend; they stay - the caller's until a started group owns them. - problems : collections.abc.Sequence of solprop.translate.problem.PropagationProblem - Each member's independently translated problem. - requests : collections.abc.Sequence of solprop.translate.run_request.RunRequest - Each member's run request. - """ - - def __init__( - self, - members: Sequence[Backend], - problems: Sequence[PropagationProblem], - requests: Sequence[RunRequest], - ) -> None: - """Hold the members, their problems and their requests.""" - self._members = tuple(members) - self._problems = tuple(problems) - self._requests = tuple(requests) - - @property - def backend(self) -> str: # numpydoc ignore=RT01 - """Registered name of the backend that prepared it. - - The first member's registered name. - """ - return self._members[0].name - - def start( - self, starts: Sequence[Start], *, stop: StopFlag | None = None - ) -> HostGroupSession: - """Start the group over the reference's group runner. - - Parameters - ---------- - starts : collections.abc.Sequence of solprop.backends.session.Start - Each member's entrance; the group takes their fields. - stop : solprop.log.StopFlag or None, optional - A group-wide stop token. - - Returns - ------- - HostGroupSession - The started group. - """ - return HostGroupSession( - self._members, self._problems, self._requests, starts, stop=stop - ) diff --git a/src/solprop/backends/host/low_storage.py b/src/solprop/backends/host/low_storage.py index 9e81114fa..0f88f1b69 100644 --- a/src/solprop/backends/host/low_storage.py +++ b/src/solprop/backends/host/low_storage.py @@ -135,8 +135,7 @@ def replay_to(self, schedule: FixedSchedule, target: float) -> None: def replay_step(self, dz: float, end: float, slack: float) -> float: """Take one prescribed step from the backend's position and accept it. - The unit a lockstep batch advances each member by - (:class:`solprop.backends.host.group.HostGroup`), with + The unit a replay advances by, with :meth:`solprop.backends.host.adams.HostAdamsMarch.replay_step`'s signature. Parameters diff --git a/src/solprop/backends/low_storage.py b/src/solprop/backends/low_storage.py index 5096097bc..46b454daa 100644 --- a/src/solprop/backends/low_storage.py +++ b/src/solprop/backends/low_storage.py @@ -151,8 +151,8 @@ def schedule_key( ) -> float: """Return the table key of the schedule step from `z`, from :func:`table_steps`. - Found by position rather than by a step counter, which a lockstep member does not - advance (the reference's ``HostGroup`` keeps the group's). + Found by position rather than by a step counter, so that it needs no count of the + steps taken before. Parameters ---------- diff --git a/src/solprop/backends/numpy_ref/backend.py b/src/solprop/backends/numpy_ref/backend.py index a78794cce..3de4f9ed3 100644 --- a/src/solprop/backends/numpy_ref/backend.py +++ b/src/solprop/backends/numpy_ref/backend.py @@ -134,11 +134,11 @@ class NumpyRefBackend(HostDriver[Complex[np.ndarray, "n_batch n_modes n_pol n_om """Propagate one Kerr and plasma problem with interaction-picture DOPRI5. The oracle of ``docs/dev/backends.md`` section 2. It implements - :class:`solprop.backends.protocol.Backend` and steps a single problem - (``max_batch = 1``) on either grid: mode-averaged or multimode on the fixed - transverse quadrature, scalar or vector-isotropic, with the Kerr term, the delayed - Raman term and the plasma. Mode-averaged propagation is the one-node case of the - same pipeline and not a second code path. + :class:`solprop.backends.protocol.Backend` and steps a single problem on either + grid: mode-averaged or multimode on the fixed transverse quadrature, scalar or + vector-isotropic, with the Kerr term, the delayed Raman term and the plasma. + Mode-averaged propagation is the one-node case of the same pipeline and not a + second code path. **Refusals.** A problem is refused by name, with :class:`solprop.exceptions.BackendError`, when its flags declare a spectral @@ -212,7 +212,6 @@ class NumpyRefBackend(HostDriver[Complex[np.ndarray, "n_batch n_modes n_pol n_om reads_transverse_edge = True name = "numpy_ref" - max_batch = 1 # The oracle evaluates its stage tables and Adams bases with the uncompiled forms, # never with the compiled code it exists to check (SEP 29 section 6.6). helpers = PLAIN diff --git a/src/solprop/backends/numpy_ref/batch.py b/src/solprop/backends/numpy_ref/batch.py deleted file mode 100644 index 1835a7bfd..000000000 --- a/src/solprop/backends/numpy_ref/batch.py +++ /dev/null @@ -1,229 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""Evaluate reference Runge-Kutta stage arrays across a leading member axis.""" - -from collections.abc import Sequence -from typing import cast - -import numpy as np - -from solprop._helpers import PLAIN -from solprop.backends.host.driver import HostDriver -from solprop.backends.host.group import HostGroup, _refuse_invalid_norm -from solprop.backends.numpy_ref import passes -from solprop.backends.numpy_ref.backend import NumpyRefBackend -from solprop.backends.protocol import Backend, BatchBackend -from solprop.exceptions import BackendError - -__all__ = ["NumpyBatchBackend", "lockstep_runner"] - - -def lockstep_runner(owners: Sequence[Backend]) -> BatchBackend: - """Build the reference's lockstep runner for loaded members. - - What :func:`solprop.backends.registry.select_batch` returns for the reference. - - Parameters - ---------- - owners : collections.abc.Sequence of solprop.backends.protocol.Backend - Compatible, loaded ``numpy_ref`` members. - - Returns - ------- - solprop.backends.protocol.BatchBackend - :class:`NumpyBatchBackend`, or :class:`~solprop.backends.host.group.HostGroup` - when a member carries a coupled flow. - """ - hosts = cast("Sequence[HostDriver[object]]", owners) - if any(host._problem.linear.coupled_flow is not None for host in hosts): - # NumpyBatchBackend's stage arithmetic over the member axis applies neither a - # flow's action nor its explicit residual; a coupled member takes its own - # trial, flow included, member by member (solprop issue #241). - return HostGroup(hosts) - return NumpyBatchBackend(cast(Sequence[NumpyRefBackend], owners)) - - -class NumpyBatchBackend(HostGroup): - """Evaluate batch stage arithmetic with independently parameterised responses. - - Stage sums, input construction and the final update operate on arrays with a - leading member axis. Response evaluation retains each member's own transform, - material and statistics context. Norms are reduced within each member in the - same order as the singleton reference. - - Parameters - ---------- - members : sequence of solprop.backends.numpy_ref.NumpyRefBackend - Loaded reference workspaces with matching shapes, fixed schedules and - Runge-Kutta tableaus. Ownership transfers on successful construction. - - Raises - ------ - BackendError - If the fixed-schedule contract, backend or tableau differs between members. - """ - - helpers = PLAIN - - def __init__(self, members: Sequence[NumpyRefBackend]) -> None: - self._reference_members = tuple(members) - for member in self._reference_members: - if not isinstance(member, NumpyRefBackend): - raise BackendError("NumpyBatchBackend requires numpy_ref members") - # Before the lockstep contract, because this is a statement about the - # problem rather than about the group: this class reimplements the - # Runge-Kutta loop over a member axis and does **not** apply the flow - # action or the explicit residual, so a member carrying - # `linear.coupled_flow` would run, converge and propagate the diagonal - # half of an equation whose off-diagonal it silently dropped. A - # lockstep group is a sequence of single-trajectory members. - if member._problem.linear.coupled_flow is not None: - msg = ( - "the numpy_ref lockstep batch does not execute " - "linear.coupled_flow: it evaluates its own stage arithmetic " - "over the member axis and applies neither the flow action nor " - "its explicit residual, so a coupled member would propagate " - "only the diagonal half of its own equation. Run each member " - "on its own" - ) - raise BackendError(msg) - super().__init__([cast(HostDriver[object], member) for member in members]) - - def _trial_step(self, z: float, dz: float) -> tuple[float, tuple[object, ...]]: - """Evaluate vector stage arithmetic with independent member responses. - - - ``z``: start position, m. - - ``dz``: positive fixed step length, m. - - Returns: maximum diagnostic norm and member trial states. - """ - members = self._reference_members - state = np.concatenate([member._require_state() for member in members]) - tableau = self._stepper.tableau - positions = [z + dz, *(z + float(node) * dz for node in tableau.nodes)] - for member in members: - member._hoist(z) - member._stage_bundles(z, positions) - exponents = [member._exponents(z, dz) for member in members] - stages = [] - solution = np.zeros_like(state) - error = np.zeros_like(state) - for index, node in enumerate(tableau.nodes): - fraction = float(node) - combination = np.zeros_like(state) - for previous in range(index): - combination = passes.accumulate( - combination, - stages[previous], - float(tableau.matrix[index, previous]), - ) - bundles = [ - member._stage_scalars(z, z + fraction * dz) for member in members - ] - exponent = np.concatenate( - [ - function(fraction, bundle) - for function, bundle in zip(exponents, bundles, strict=True) - ] - ) - noises = [ - member._noise_at(bundle) - for member, bundle in zip(members, bundles, strict=True) - ] - if any(noise is None for noise in noises) and not all( - noise is None for noise in noises - ): - raise BackendError( - "reference batch members require compatible noise models" - ) - noise = ( - None - if noises[0] is None - else np.concatenate([one for one in noises if one is not None]) - ) - lab = passes.stage_input(state, combination, dz, np.exp(exponent), noise) - inverse = np.exp(-exponent) - stage = np.concatenate( - [ - member._nonlinear(lab[i : i + 1], bundles[i], inverse[i : i + 1]) - for i, member in enumerate(members) - ] - ) - stages.append(stage) - solution = passes.accumulate( - solution, stage, float(tableau.solution_weights[index]) - ) - error = passes.accumulate(error, stage, float(tableau.error_weights[index])) - propagator = np.exp( - np.concatenate( - [ - function(1.0, member._stage_scalars(z, z + dz)) - for function, member in zip(exponents, members, strict=True) - ] - ) - ) - advanced = passes.accept_step(state, propagator, dz, solution) - residual = propagator * (dz * error) - self._member_norms = tuple( - passes.error_norm( - residual[i : i + 1], - state[i : i + 1], - advanced[i : i + 1], - member._problem.grids.norm_mask, - member._stepper.controller, - ) - for i, member in enumerate(members) - ) - _refuse_invalid_norm(self._member_norms, "reference") - return max(self._member_norms), tuple( - advanced[i : i + 1] for i in range(len(members)) - ) - - def metadata(self) -> dict[str, object]: - """Record vector stage arithmetic and independent response workspaces. - - Returns - ------- - dict - Batch execution settings; no device-kernel fusion is claimed. - """ - return super().metadata() | {"batch_strategy": "numpy_stage_arrays"} - - def memory_ledger(self) -> dict[str, int]: - """Include transient array packing alongside the reference step peak. - - Returns - ------- - dict of str to int - Conservative peak workspace bytes. Existing member ledgers account - for stage stacks and accumulators; these entries cover concatenation - inputs, outputs and expression temporaries that coexist with them. - """ - if self._closed: - return {} - size = self.max_batch * self._problem.initial.field0.nbytes - return super().memory_ledger() | { - f"batch/{name}": size - for name in ( - "packed_state", - "combination", - "exponent", - "lab", - "inverse", - "packed_noise", - "advanced", - "residual", - "concatenation_input", - "accumulator_temporary", - "exponential_temporary", - "update_temporary", - ) - } - - def close(self) -> None: - """Release the reference member workspaces and common march state.""" - try: - super().close() - finally: - self._reference_members = () diff --git a/src/solprop/backends/protocol.py b/src/solprop/backends/protocol.py index e6032302f..ec7733dc5 100644 --- a/src/solprop/backends/protocol.py +++ b/src/solprop/backends/protocol.py @@ -27,7 +27,7 @@ import dataclasses import logging -from collections.abc import Mapping, Sequence +from collections.abc import Mapping from dataclasses import dataclass from typing import TYPE_CHECKING, Protocol, runtime_checkable @@ -36,7 +36,7 @@ from solprop._ownership import frozen_copy, hold from solprop._process import parallel_rows -from solprop.exceptions import BackendError, BoundaryError, BoundaryWarning +from solprop.exceptions import BackendError from solprop.log import ProgressReporter, StopFlag from solprop.monitor import BoundaryMonitor from solprop.noise import NoiseRealisation @@ -45,14 +45,13 @@ if TYPE_CHECKING: # The session module builds on this one's records, so its start is a forward name. - from solprop.backends.session import PreparedExecution, PreparedGroup, Start + from solprop.backends.session import PreparedExecution, Start from solprop.translate.problem import PropagationProblem from solprop.translate.run_request import RunRequest __all__ = [ "Backend", "BackendHistory", - "BatchBackend", "HostStepping", "Observation", "StepStats", @@ -619,9 +618,6 @@ class Backend(Protocol): ---------- name : str The registry name, for example ``"numpy_ref"``. - max_batch : int - Trajectories this backend steps at once: 1 for a backend that steps one - problem, the member count for a group runner. reads_transverse_edge : bool Whether it reads a free-space run's transverse edge (SEP 40 section 5.3), which a run with a requested real-space collar needs. @@ -635,11 +631,10 @@ class Backend(Protocol): >>> names[4:8] ['march_export_refusal', 'memory_ledger', 'metadata', 'prepare'] >>> names[8:] - ['prepare_group', 'request', 'timing_probe'] + ['request', 'timing_probe'] """ name: str - max_batch: int reads_transverse_edge: bool @property @@ -673,36 +668,6 @@ def prepare( """ ... - def prepare_group( - self, - members: "Sequence[Backend]", - problems: "Sequence[PropagationProblem]", - requests: "Sequence[RunRequest]", - ) -> "PreparedGroup": - """Prepare a group of compatible members of this backend (SEP 47 section 6.7). - - Called on the group's first member, ``members[0]``, so that the backend, not - the run layer, chooses the group it runs - (:func:`solprop.backends.sessions.start_group`). A backend that runs no group - raises :class:`~solprop.exceptions.BackendError` saying so. - - Parameters - ---------- - members : collections.abc.Sequence of Backend - One constructed backend per member, this one first, all of this backend, - holding no state yet. - problems : sequence of solprop.translate.problem.PropagationProblem - Each member's independently translated problem. - requests : sequence of solprop.translate.run_request.RunRequest - Each member's run request, with its own fresh boundary monitor. - - Returns - ------- - solprop.backends.session.PreparedGroup - The prepared group, whose ``start`` opens the backend's group session. - """ - ... - def metadata(self) -> dict[str, object]: """Return what this execution is, for the run's record. @@ -806,7 +771,7 @@ class HostStepping(Backend, Protocol): The reference (:class:`solprop.backends.host.driver.HostDriver`) loads, steps, observes and restores its state through these members, which its own session - (:class:`solprop.backends.host.session.HostSession`) and its lockstep group call. + (:class:`solprop.backends.host.session.HostSession`) calls. They are no part of :class:`Backend`: the native backend runs only in its native session and has none of them (SEP 47 section 6.8). A caller holding a :class:`Backend` it knows steps on the host narrows it with :func:`stepping`. @@ -1006,83 +971,6 @@ def restore_march(self, snapshot: MarchSnapshot) -> str | None: ... -@runtime_checkable -class BatchBackend(HostStepping, Protocol): - """Advance compatible loaded members and return their separate observations. - - Construct through :func:`solprop.backends.registry.select_batch` after loading - each member's initial state and noise through the ordinary backend seam. - Successful construction transfers ownership of those backends to the batch. - Their parameter tables may differ, but grids, fixed schedules, save planes and - statistics layouts must match. ``max_batch`` records the constructed count. - - ``observe_members`` replaces ``observe`` for batch output: each member keeps - its own error history and periodic rows. No device array crosses this interface. - The common maximum error norm is diagnostic and never changes a fixed schedule. - """ - - def observe_members(self, *, field: bool = True) -> tuple[Observation, ...]: - """Drain independently owned host observations in member order. - - Parameters - ---------- - field : bool, optional - Whether each member's field and noise phase cross to the host, as for - :meth:`solprop.backends.protocol.HostStepping.observe`. Default ``True``. - - Returns - ------- - tuple of Observation - Singleton field shapes, or no field, and each member's own diagnostic - history. - """ - ... - - def member_metadata(self) -> tuple[dict[str, object], ...]: - """Return resolved execution policies for every batch member. - - Returns - ------- - tuple of dict - Complete per-member backend provenance, including the batch strategy. - """ - ... - - def attach_monitors(self, monitors: Sequence[BoundaryMonitor | None]) -> None: - """Give each member its own boundary monitor, or none (SEP 21). - - Parameters - ---------- - monitors : collections.abc.Sequence - One monitor with nothing recorded, or ``None``, per member. - """ - ... - - @property - def member_stops( - self, - ) -> tuple[BoundaryError | BoundaryWarning | None, ...]: # numpydoc ignore=RT01 - """What stopped each member's watch, ``None`` where nothing did. - - A stop, or a warning raised as an error under an ``"error"`` filter. - """ - ... - - @property - def member_records( - self, - ) -> tuple[Mapping[str, object] | None, ...]: # numpydoc ignore=RT01 - """Each member's monitor record as it closed, ``None`` if unwatched.""" - ... - - def finish_monitors(self) -> None: - """Report each still-watched member's removed fraction at the run's end. - - A warning raised as an error fails that member alone (:attr:`member_stops`). - """ - ... - - def stepping(backend: Backend) -> HostStepping: """Return a backend as the host stepping seam it implements. diff --git a/src/solprop/backends/registry.py b/src/solprop/backends/registry.py index be73404d6..c1371ff67 100644 --- a/src/solprop/backends/registry.py +++ b/src/solprop/backends/registry.py @@ -28,7 +28,7 @@ from types import ModuleType from typing import Final, cast -from solprop.backends.protocol import Backend, BatchBackend +from solprop.backends.protocol import Backend from solprop.backends.session import ExecutionOptions from solprop.exceptions import BackendError from solprop.grid import TimeGrid @@ -46,7 +46,6 @@ "available", "resolve_name", "select", - "select_batch", "statistics_refusal", ] @@ -408,48 +407,6 @@ def select( return backend -def select_batch(owners: Sequence[Backend]) -> BatchBackend: - """Select batch arithmetic without substituting a different backend. - - This is the reference group's lockstep runner. The native backend runs its groups - through its own prepared group instead - (:func:`solprop.backends.sessions.start_group`; SEP 47 section 6.7), and is - refused here by name. - - Parameters - ---------- - owners : sequence of solprop.backends.protocol.Backend - Compatible, loaded member owners. - - Returns - ------- - BatchBackend - Common fixed march using the selected backend's arithmetic. - - Raises - ------ - BackendError - If the members are not of one backend, or their backend has no lockstep runner - (its groups start through ``start_group``). - """ - if not owners: - raise BackendError("Batch requires at least one loaded member") - if any(owner.name != owners[0].name for owner in owners): - raise BackendError("Batch refuses mixed backends") - name = owners[0].name - if name != "numpy_ref": - msg = ( - f"Batch has no runner for backend {name!r}: select_batch is the " - "reference's lockstep runner, and native runs its groups through its own " - "prepared group, which solprop.backends.sessions.start_group starts " - "(SEP 47 section 6.7)" - ) - raise BackendError(msg) - from solprop.backends.numpy_ref.batch import lockstep_runner # noqa: PLC0415 - - return lockstep_runner(owners) - - def _construct( name: str, problem: PropagationProblem, diff --git a/src/solprop/backends/session.py b/src/solprop/backends/session.py index 592bdb38e..4a8bffe5e 100644 --- a/src/solprop/backends/session.py +++ b/src/solprop/backends/session.py @@ -40,15 +40,6 @@ :meth:`RunSession.request_snapshot` latches a snapshot for the next eligible accepted endpoint (SEP 47 section 5.5). -A :class:`GroupSession` advances compatible trajectories through one common fixed -schedule, a window at a time, and reports each member's own events and outcome (SEP 47 -section 6.7). A backend prepares its own group the same way, from the group's first -member (:class:`PreparedGroup`):: - - prepared = members[0].prepare_group(members, problems, requests) - with prepared.start(starts, stop=token) as group: - ... - :class:`SessionLedger` is the lifecycle bookkeeping every Python session shares: receipts, the pending barrier, closing and poisoning. It holds no numerical state. """ @@ -70,7 +61,6 @@ from solprop.backends.events import ( EventBatch, ExportTicket, - GroupBatch, Outcome, Receipt, ) @@ -88,9 +78,7 @@ "DEFAULT_DEADLINE", "DEFAULT_WORK_LIMIT", "ExecutionOptions", - "GroupSession", "PreparedExecution", - "PreparedGroup", "RunSession", "SessionBackend", "SessionError", @@ -100,8 +88,6 @@ "SnapshotReceipt", "Start", "StopToken", - "check_group", - "check_member_ticket", "positive_count", "statistics_unavailable", ] @@ -268,71 +254,6 @@ def chunk(self) -> int | None: # numpydoc ignore=RT01 return None if self.node_chunk is None else operator.index(self.node_chunk) -def check_group( - members: Sequence[object], - problems: Sequence[PropagationProblem], - requests: Sequence[RunRequest], - starts: Sequence[Start], -) -> None: - """Refuse a group's inputs that no group implementation starts from. - - A group (:class:`GroupSession`) takes one problem, request and start per member, - and starts every member at its entrance, with no method history or monitor record - to continue (SEP 47 section 6.7). Every check reads its inputs alone, so a refused - group leaves the caller's starts and backends untouched. - - Parameters - ---------- - members : collections.abc.Sequence of object - Each member's backend. - problems : collections.abc.Sequence of solprop.translate.problem.PropagationProblem - Each member's problem. - requests : collections.abc.Sequence of solprop.translate.run_request.RunRequest - Each member's run request. - starts : collections.abc.Sequence of Start - Each member's start. - - Raises - ------ - SessionError - If the sequences differ in length or are empty, if a start is not a fresh - entrance whose launch plane is owed or was already used, or if two members - share a start or a backend. - solprop.exceptions.BackendError - If a member asks for statistics its problem does not carry - (:func:`statistics_unavailable`). - """ - count = len(members) - if count == 0 or not count == len(problems) == len(requests) == len(starts): - msg = ( - f"a group needs one problem, request and start per member, and got " - f"{count} members, {len(problems)} problems, {len(requests)} " - f"requests and {len(starts)} starts" - ) - raise SessionError(msg) - for problem, request in zip(problems, requests, strict=True): - stats = request.observation.stats - refused = statistics_unavailable(problem, (*stats.names, *stats.periodic)) - if refused is not None: - raise BackendError(refused) - for start in starts: - fresh = start.march is None and start.monitor is None - if not fresh or start.plane_index or not start.plane_pending: - msg = ( - "a group starts its members at their entrance, its launch plane owed, " - "with no method history or monitor record to continue" - ) - raise SessionError(msg) - if start.field is None: - msg = "this start was already used: a start is handed to one session" - raise SessionError(msg) - # One start or backend shared by two members would alias their state. - for given, name in ((starts, "start"), (members, "backend")): - if len({id(one) for one in given}) < count: - msg = f"each member of a group takes its own {name}" - raise SessionError(msg) - - _MODAL_ONLY = ( "omega0", "energy_window", @@ -417,29 +338,6 @@ def statistics_unavailable( return None -def check_member_ticket(ticket: ExportTicket, member: int) -> None: - """Refuse a group ticket presented for another member than the one it names. - - Parameters - ---------- - ticket : solprop.backends.events.ExportTicket - A ticket of a group's pending batch. - member : int - The member it is presented for. - - Raises - ------ - SessionError - If the ticket names another member, or none. - """ - if ticket.member != member: - msg = ( - f"the export ticket for z = {ticket.z!r} m is member {ticket.member}'s, " - f"not member {member}'s" - ) - raise SessionError(msg) - - def positive_count(name: str, value: object) -> int: """Return an integral, positive budget or chunk as an ``int``. @@ -811,180 +709,6 @@ def __exit__( ... -@runtime_checkable -class GroupSession(Protocol): - """Compatible trajectories advanced together through one common fixed schedule. - - A group request is a sequence of independently translated member problems that - pass the compatibility predicate a batched scan groups its points by; the - common schedule's maximum error norm is a diagnostic only (SEP 47 section 6.7). - Each :meth:`advance` runs every member still running through the next common - schedule window -- to the next save plane -- and reports each member's own - events (:class:`~solprop.backends.events.GroupBatch`):: - - with group: - while not group.finished: - batch = group.advance() - service(batch) # each member's planes and outcome - group.acknowledge(batch.receipt) - - **Failure.** A boundary error, or a boundary warning raised as an error, ends - that member alone with a :class:`~solprop.backends.events.Terminal`, and the - others go on. A non-finite error norm, a step floor, a trial exception or an - in-flight failure ends the group: every member still running ends with the same - error. Members are stepped in turn, so earlier members may already have advanced - the failed scheduled step: each terminal reports that member's actual committed - position and checkpoint eligibility, and no common cursor or rollback is - invented. A group-wide stop request ends every running member at a common - accepted endpoint. - """ - - @property - def n_members(self) -> int: # numpydoc ignore=RT01 - """Number of members.""" - ... - - @property - def finished(self) -> bool: # numpydoc ignore=RT01 - """Whether every member has ended.""" - ... - - @property - def closed(self) -> bool: # numpydoc ignore=RT01 - """Whether the group was closed.""" - ... - - def advance(self) -> GroupBatch: - """Run every running member through the next common window, and report it.""" - ... - - def acknowledge(self, receipt: Receipt) -> None: - """Release a window's batch and allow advancing past it. - - Parameters - ---------- - receipt : solprop.backends.events.Receipt - The batch's receipt. - """ - ... - - def export( - self, - member: int, - ticket: ExportTicket, - recipe: ExportRecipe, - out: Complex[np.ndarray, "n_modes n_pol n_omega"] | None = None, - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Fill a destination with one member's converted field at a pending ticket. - - Parameters - ---------- - member : int - The member's index, from zero. - ticket : solprop.backends.events.ExportTicket - The member's pending ticket. - recipe : solprop.backends.export.ExportRecipe - The conversion. - out : numpy.ndarray or None, optional - The destination; a new array by default. - - Returns - ------- - numpy.ndarray - The filled destination. - """ - ... - - def noise_phase(self, member: int, ticket: ExportTicket) -> np.ndarray | None: - """Return one member's noise phase at a pending ticket. - - Parameters - ---------- - member : int - The member's index, from zero. - ticket : solprop.backends.events.ExportTicket - The member's pending ticket. - - Returns - ------- - numpy.ndarray or None - The phase, or ``None`` without noise. - """ - ... - - def member_status(self, member: int) -> SessionStatus: - """Return one member's committed position, counters and outcome. - - Parameters - ---------- - member : int - The member's index, from zero. - - Returns - ------- - SessionStatus - The member's status. - """ - ... - - def execution_record(self, member: int) -> Mapping[str, object]: - """Return one member's execution facts. - - Parameters - ---------- - member : int - The member's index, from zero. - - Returns - ------- - collections.abc.Mapping - The member's execution record. - """ - ... - - def monitor_record(self, member: int) -> Mapping[str, object] | None: - """Return one member's boundary-monitor record, ``None`` when unwatched. - - Parameters - ---------- - member : int - The member's index, from zero. - - Returns - ------- - collections.abc.Mapping or None - The record. - """ - ... - - def close(self) -> None: - """Release every member's resources; idempotent.""" - ... - - def __enter__(self) -> "GroupSession": - """Return the group, for scoped ownership.""" - ... - - def __exit__( - self, - kind: type[BaseException] | None, - error: BaseException | None, - trace: TracebackType | None, - ) -> None: - """Close the group. - - Parameters - ---------- - kind : type or None - The type of the exception leaving the scope, if any. - error : BaseException or None - The exception, if any. - trace : types.TracebackType or None - Its traceback, if any. - """ - ... - - @runtime_checkable class PreparedExecution(Protocol): """A backend's lowering of one problem and request, reusable across sessions.""" @@ -1035,42 +759,6 @@ def close(self) -> None: ... -@runtime_checkable -class PreparedGroup(Protocol): - """A backend's preparation of a group of compatible members (SEP 47 section 6.7). - - The group's counterpart of :class:`PreparedExecution`: a backend returns it from - :meth:`~solprop.backends.protocol.Backend.prepare_group`, and its :meth:`start` - opens the backend's own :class:`GroupSession`, so that - :func:`solprop.backends.sessions.start_group` names no backend. - """ - - @property - def backend(self) -> str: # numpydoc ignore=RT01 - """Registered name of the backend that prepared it.""" - ... - - def start( - self, starts: Sequence[Start], *, stop: StopFlag | None = None - ) -> GroupSession: - """Start the group, each member from its entrance. - - Parameters - ---------- - starts : collections.abc.Sequence of Start - Each member's entrance, in member order; the group takes their fields. - stop : solprop.log.StopFlag or None, optional - A group-wide stop token. - - Returns - ------- - GroupSession - The started group, which owns the members once it is constructed; a start - that fails leaves them to the caller. - """ - ... - - class SessionBackend(Protocol): """A backend that prepares executions (SEP 47 section 6.1). diff --git a/src/solprop/backends/session_core.py b/src/solprop/backends/session_core.py index ea4b7ac14..e66a51b26 100644 --- a/src/solprop/backends/session_core.py +++ b/src/solprop/backends/session_core.py @@ -2,13 +2,12 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The building blocks the Python execution sessions share (SEP 47 sections 5 and 6.7). +"""The building blocks the Python execution sessions share (SEP 47 section 5). -The reference's sessions (:class:`solprop.backends.host.session.HostSession` and -:class:`solprop.backends.host.group_session.HostGroupSession`) run their own plane -schedule over their own driver, and compose the parts below, none of which names a -driver; the native backend's prepared execution (``solprop_native.session``) makes the -same preparation refusals: +The reference's session (:class:`solprop.backends.host.session.HostSession`) runs its +own plane schedule over its own driver, and composes the parts below, none of which +names a driver; the native backend's prepared execution (``solprop_native.session``) +makes the same preparation refusals: - :class:`AttemptCounter` forwards a driver's attempts to a progress listener and counts them, and :class:`YieldDue` reads that count and the clock for a bounded @@ -255,7 +254,7 @@ def merge_summaries(before: StepSummary | None, step: StepSummary) -> StepSummar ) -def bind(event: Event, receipt: Receipt, member: int | None = None) -> Event: +def bind(event: Event, receipt: Receipt) -> Event: """Return an event with its ticket bound to the batch that delivers it. Parameters @@ -264,8 +263,6 @@ def bind(event: Event, receipt: Receipt, member: int | None = None) -> Event: An event, with an unbound ticket or none. receipt : solprop.backends.events.Receipt The batch's receipt. - member : int or None, optional - The group member the ticket names; ``None`` for a lone session. Returns ------- @@ -277,7 +274,7 @@ def bind(event: Event, receipt: Receipt, member: int | None = None) -> Event: return event return dataclasses.replace( event, # pyright: ignore[reportArgumentType] - ticket=dataclasses.replace(ticket, receipt=receipt, member=member), + ticket=dataclasses.replace(ticket, receipt=receipt), ) diff --git a/src/solprop/backends/sessions.py b/src/solprop/backends/sessions.py index b3312fa77..37ad91adc 100644 --- a/src/solprop/backends/sessions.py +++ b/src/solprop/backends/sessions.py @@ -13,24 +13,14 @@ (``solprop_native.session.NativePrepared``) opens the native execution session (``solprop_native.session.NativeSession``), on a CPU or a device build alike, which refuses by name, before the start is loaded, what it does not run. - -:func:`start_group` is the door for a group of compatible members (SEP 47 section -6.7), through the same shape: the group's first member prepares the group, -``members[0].prepare_group(members, problems, requests).start(starts, ...)``, so a -backend chooses its group and nothing here names one either. The native backend's -(``solprop_native.group.NativePreparedGroup``) opens the native group session -(``solprop_native.group.NativeGroupSession``, one native session per member), on a CPU -or a device build, which refuses by name what it does not run -(``solprop_native.group.refusal``); the reference's opens its own group -(:class:`solprop.backends.host.group_session.HostGroupSession`). """ from __future__ import annotations -from collections.abc import Callable, Sequence +from collections.abc import Callable from typing import TYPE_CHECKING -from solprop.backends.session import GroupSession, RunSession, Start, check_group +from solprop.backends.session import RunSession, Start from solprop.backends.session_core import AttemptListener from solprop.log import StopFlag from solprop.translate.problem import PropagationProblem @@ -40,7 +30,7 @@ # The scripted drivers of the test suite stand in for a backend. from solprop.backends.protocol import Backend -__all__ = ["start_group", "start_session"] +__all__ = ["start_session"] def start_session( @@ -88,49 +78,3 @@ def start_session( return prepared.start( start, listener=listener, started=started, stop=stop, owns=owns ) - - -def start_group( - members: Sequence[Backend], - problems: Sequence[PropagationProblem], - requests: Sequence[RunRequest], - starts: Sequence[Start], - *, - stop: StopFlag | None = None, -) -> GroupSession: - """Start the group that advances compatible members through one fixed schedule. - - Parameters - ---------- - members : collections.abc.Sequence of solprop.backends.protocol.Backend - One constructed backend per member, all of one backend; the group owns them - once constructed, and a construction that fails leaves them to the caller. - problems : collections.abc.Sequence of solprop.translate.problem.PropagationProblem - Each member's independently translated problem. - requests : collections.abc.Sequence of solprop.translate.run_request.RunRequest - Each member's run request, with its own fresh boundary monitor. - starts : collections.abc.Sequence of solprop.backends.session.Start - Each member's entrance; the group takes their fields once constructed, and a - construction that fails leaves them to the caller. - stop : solprop.log.StopFlag or None, optional - A group-wide stop token. - - Returns - ------- - solprop.backends.session.GroupSession - The group the backend's prepared group opens - (:meth:`~solprop.backends.protocol.Backend.prepare_group`): the reference's - own group for reference members, and the native group session for native - members. - - Raises - ------ - solprop.backends.session.SessionError - If the sequences differ in length or are empty, if a start is not a fresh - entrance or was already used, or if two members share a start or a backend. - solprop.exceptions.BackendError - If the backend runs no group, or refuses this one. - """ - check_group(members, problems, requests, starts) - prepared = members[0].prepare_group(members, problems, requests) - return prepared.start(starts, stop=stop) diff --git a/src/solprop/driver/_scan_batch.py b/src/solprop/driver/_scan_batch.py deleted file mode 100644 index abf3acadb..000000000 --- a/src/solprop/driver/_scan_batch.py +++ /dev/null @@ -1,426 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""Coordinate backend-preserving batches and ordinary per-point scan captures. - -A batch of compatible points runs as one group (SEP 47 section 6.7): this module is the -group's service loop. It advances the group one common window at a time and saves each -member's planes to that member's own capture, under the ordinary single-point schema. -""" - -import dataclasses -import logging -import math -import time -import traceback -from collections.abc import Iterable, Iterator, Mapping, Sequence -from contextlib import ExitStack -from dataclasses import dataclass -from itertools import batched -from pathlib import Path -from tempfile import TemporaryDirectory - -from solprop.backends import select -from solprop.backends.events import GroupBatch, ObservationReady, Terminal -from solprop.backends.export import ExportRecipe -from solprop.backends.protocol import Backend -from solprop.backends.session import GroupSession, Start -from solprop.backends.sessions import start_group -from solprop.driver._scan_run import ( - _Capture, - _field_retention, - _Job, - _Work, - launch_statistics, -) -from solprop.driver.batch import BatchMember, compatible_groups, shared_table_bytes -from solprop.driver.executors.batch import Batch -from solprop.driver.executors.pool import _memory_limit, peak_rss -from solprop.driver.run import history_of -from solprop.driver.simulation import Simulation -from solprop.exceptions import DriverError -from solprop.output.metadata import RunMetadata -from solprop.output.provenance import BackendRecord -from solprop.output.records import SavedPlane, StepStats -from solprop.output.scan import PointResult -from solprop.processing.scans import _provenance - -logger = logging.getLogger(__name__) - - -@dataclass(frozen=True) -class _Prepared: - """Keep a job's one constructed simulation and its singleton hash record.""" - - job: _Job - simulation: Simulation - metadata: RunMetadata - - -_CONSUMER = ExportRecipe(power=True, optics=False) -"""The field a capture stores: output amplitudes in the internal FFT convention.""" - - -def _construct(simulation: Simulation, cleanup: ExitStack) -> Backend: - """Construct a member's selected backend with its cleanup registered.""" - owner = select( - simulation.settings.backend, - simulation.translate(), - simulation._run_request(), - grid=simulation.grid, - modes=simulation.modes, - profiles=simulation.profiles, - options=simulation.settings.execution_options(), - ) - cleanup.callback(owner.close) - return owner - - -def _prepare(job: _Job, work: _Work) -> _Prepared | PointResult: - """Validate a point's seed and hash once, before batch admission.""" - try: - simulation = work.simulation(job) - metadata = simulation.metadata() - digest = metadata.configuration_hash() - if job.cached_hash: - if job.cached_hash != digest: - return PointResult( - job.point.index, - "conflict", - digest, - metadata.to_json(), - error=f"point {job.point.index} has a different configuration", - metadata_arrays=metadata.record_arrays(), - ) - return PointResult(job.point.index, "skipped", configuration_hash=digest) - return _Prepared(job, simulation, metadata) - except Exception: - return work.failure(job, traceback.format_exc()) - - -def _admit(group: Sequence[_Prepared], work: _Work, executor: Batch) -> int: - """Probe member workspaces and admit a bounded group with twenty percent headroom. - - All translated tables and the writer already reside in the baseline RSS. Their - unique byte count is recorded, not added again. The first workspace uses the - larger of measured RSS and baseline plus its ledger; only subsequent workspaces - are additive. Two output copies cover capture consolidation and writer transfer. - """ - limit = _memory_limit() - if executor.memory_limit is not None: - limit = min(limit, executor.memory_limit) - baseline = peak_rss() - if baseline >= limit * 4 // 5: - raise DriverError("Batch memory budget cannot fit one member with headroom") - ledger = output = packing = 0 - device_free: int | None = None - for member in group: - simulation = member.simulation - problem = simulation.translate() - with ExitStack() as cleanup: - owner = _construct(simulation, cleanup) - statistics = launch_statistics(owner, problem) - ledger = max(ledger, sum(owner.memory_ledger().values())) - output = max(output, work._output_bytes(simulation, statistics)) - free = owner.available_device_memory() - if free is not None: - device_free = free if device_free is None else min(device_free, free) - field_bytes = math.prod(problem.shape) * 16 - # Construction briefly holds old member updates and their packed replacements. - # The reference also holds concatenated stage inputs and response outputs. - packing = max( - packing, - field_bytes * (20 if simulation.settings.backend == "numpy_ref" else 5) - + 3 - * math.prod(problem.shape[:-1]) - * math.ceil(problem.shape[-1] / 256) - * 8, - ) - measured = peak_rss() - first = max(measured, baseline + ledger) - available = limit * 4 // 5 - first + ledger - per_member = ledger + packing + 2 * output - count = min(len(group), max(0, available // max(1, per_member))) - host_count = count - if device_free is not None: - # The live probe is excluded from free bytes. Its complete ledger is a - # conservative bound on device ownership (it may include host buffers). - # Keep 20% of that allocation plus current free space unused. Counting - # all ledger bytes as device storage errs towards a smaller batch. - device_count = (4 * (device_free + ledger)) // (5 * max(1, ledger + packing)) - count = min(count, max(0, device_count)) - executor.budgets.append( - { - "limit": limit, - "baseline_rss": baseline, - "probe_rss": measured, - "member_ledger": ledger, - "member_output": output, - "member_packing_peak": packing, - "shared_table_bytes_in_baseline": shared_table_bytes( - member.simulation.translate() for member in group - ), - "requested": len(group), - "admitted": count, - "host_admitted": host_count, - "device_free_during_probe": device_free, - "device_member_upper_bound": ledger + packing - if device_free is not None - else None, - "estimated_peak": first - + (count - 1) * ledger - + count * (packing + 2 * output) - if count - else first, - "headroom_percent": 20, - } - ) - if count < 1: - raise DriverError("Batch memory budget cannot fit one member with headroom") - return count - - -def _plane( - session: GroupSession, - member: int, - event: ObservationReady, - *, - keep: bool, -) -> SavedPlane: - """Build the plane a member's capture stores from its observation. - - - Returns: the plane, its field in true-power amplitudes and the internal - convention. - """ - rows = event.step_stats - return SavedPlane( - z=event.z, - field=session.export(member, event.ticket, _CONSUMER) if keep else None, - stats=dict(event.stats), - step_history=history_of(event.history), - step_stats=StepStats(z=rows.z, step=rows.step, values=dict(rows.values)), - noise_phase=session.noise_phase(member, event.ticket) if keep else None, - ) - - -def _service( - session: GroupSession, - batch: GroupBatch, - captures: Sequence[_Capture], - errors: list[str], - *, - keep: bool, -) -> None: - """Save each running member's plane, and fail each member whose watch stopped it. - - A boundary stop ends its member alone, as a lone run of it would fail (SEP 21); - a group-wide failure is raised, and fails every member. - """ - if batch.error is not None: - raise batch.error - summary = next( - ( - event.summary - for event in _observations(batch) - if not event.summary.met_tolerance - ), - None, - ) - if summary is not None: - logger.warning( - "a batch step was too coarse for its scaled tolerance at " - "z = %.6e m: maximum member error norm %.3e against 1.0", - summary.z, - summary.max_norm, - ) - for index, events in enumerate(batch.members): - for event in events: - if isinstance(event, Terminal) and event.error is not None: - if not errors[index]: - errors[index] = "".join(traceback.format_exception(event.error)) - elif isinstance(event, ObservationReady) and not errors[index]: - try: - captures[index].save(_plane(session, index, event, keep=keep)) - except Exception: - errors[index] = traceback.format_exc() - - -def _observations(batch: GroupBatch) -> Iterator[ObservationReady]: - """Yield the save-plane observations of a window, in member order.""" - for events in batch.members: - for event in events: - if isinstance(event, ObservationReady) and event.plane_index >= 0: - yield event - - -def _run(group: Sequence[_Prepared], work: _Work) -> Iterator[PointResult]: - """Run one admitted group and preserve independently reduced point results.""" - started = time.perf_counter() - captures: list[_Capture] = [] - results: list[PointResult] = [] - errors = [""] * len(group) - records: Sequence[Mapping[str, object] | None] = [None] * len(group) - - def failed(index: int, error: str) -> PointResult: - """Retain available provenance when one member fails.""" - member = group[index] - capture = captures[index] if index < len(captures) else None - metadata = ( - capture.metadata - if capture is not None and capture.metadata is not None - else member.metadata - ) - return PointResult( - member.job.point.index, - "failed", - member.metadata.configuration_hash(), - metadata.to_json(), - reductions={ - r.name: _provenance(r, metadata=member.metadata) - for r in work.options.reductions - }, - error=error, - wall_time=time.perf_counter() - started, - n_steps=0 if capture is None else capture.steps, - n_rejected=0 if capture is None else capture.rejected, - boundary_monitor=records[index], - metadata_arrays=metadata.record_arrays(), - ) - - try: - with ExitStack() as cleanup: - problems = [member.simulation.translate() for member in group] - owners = [_construct(member.simulation, cleanup) for member in group] - # Each point watches its own window, as it would run alone (SEP 21). - session = start_group( - owners, - problems, - [ - member.simulation._run_request().for_run( - monitor=member.simulation._boundary_monitor() - ) - for member in group - ], - [Start.entrance(problem) for problem in problems], - ) - cleanup.callback(session.close) - launch = session.advance() - for index, member in enumerate(group): - # The monitors were attached first, so the record holds the launch's - # zeros; the point keeps the closing record instead. - backend = { - name: value - for name, value in session.execution_record(index).items() - if name != "boundary_monitor" - } - scratch = cleanup.enter_context( - TemporaryDirectory(prefix="solprop-batch-") - ) - capture = _Capture(work.options, member.simulation, Path(scratch)) - cleanup.callback(capture.close) - capture.open( - dataclasses.replace( - member.metadata, backend=BackendRecord.from_metadata(backend) - ) - ) - capture.retain( - _field_retention(capture).resolved(capture.count), - tuple(problems[index].shape), - ) - captures.append(capture) - # One scan's options and one group's planes: one rule for all its members. - batch = launch - plane = 0 - while True: - _service( - session, - batch, - captures, - errors, - keep=captures[0].retention.keeps(plane), - ) - session.acknowledge(batch.receipt) - if session.finished: - break - batch = session.advance() - plane += 1 - records = [session.monitor_record(index) for index in range(len(group))] - for index, (member, capture, error) in enumerate( - zip(group, captures, errors, strict=True) - ): - capture.close() - if error: - results.append(failed(index, error)) - continue - try: - arrays = capture.results() - if capture.metadata is None: - raise DriverError( - f"point {member.job.point.index} completed without " - "the run metadata its capture opened with" - ) - results.append( - PointResult( - member.job.point.index, - "done", - member.metadata.configuration_hash(), - capture.metadata.to_json(), - arrays, - { - r.name: _provenance(r, metadata=member.metadata) - for r in work.options.reductions - }, - wall_time=time.perf_counter() - started, - n_steps=capture.steps, - n_rejected=capture.rejected, - boundary_monitor=records[index], - metadata_arrays=capture.metadata.record_arrays(), - ) - ) - except Exception: - results.append(failed(index, traceback.format_exc())) - except Exception: - error = traceback.format_exc() - results = [failed(index, error) for index in range(len(group))] - yield from results - - -def _stopping(work: _Work) -> bool: - """Return whether the scan's stop flag is set.""" - return work.stop is not None and work.stop.is_set() - - -def execute( - jobs: Iterable[_Job], work: _Work, executor: Batch -) -> Iterator[PointResult]: - """Build bounded groups and execute their independently selected backend.""" - backend: str | None = None - for chunk in batched(jobs, executor.size, strict=False): - pending: dict[int, _Prepared] = {} - for job in chunk: - prepared = _prepare(job, work) - if isinstance(prepared, PointResult): - yield prepared - continue - selected = prepared.simulation.settings.backend - if backend is not None and selected != backend: - raise DriverError( - f"Batch refuses mixed backends {backend!r} and {selected!r}" - ) - backend = selected - pending[job.point.index] = prepared - members = (BatchMember(index, one.simulation) for index, one in pending.items()) - for compatible in compatible_groups(members, executor.size): - group = tuple(pending[member.index] for member in compatible) - if _stopping(work): - # Between groups (SEP 41, S17): a claimed group not yet run is given - # back, so a rerun computes it. - yield from (work.stopped(member.job) for member in group) - continue - count = _admit(group, work, executor) - for admitted in batched(group, count, strict=False): - if _stopping(work): - yield from (work.stopped(member.job) for member in admitted) - continue - yield from _run(admitted, work) diff --git a/src/solprop/driver/_scan_run.py b/src/solprop/driver/_scan_run.py index 64433999d..108a57db2 100644 --- a/src/solprop/driver/_scan_run.py +++ b/src/solprop/driver/_scan_run.py @@ -12,7 +12,7 @@ import math import time import traceback -from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence +from collections.abc import Callable, Iterator, Mapping, Sequence from dataclasses import dataclass, field from pathlib import Path from tempfile import TemporaryDirectory @@ -28,7 +28,7 @@ from solprop.backends.sessions import start_session from solprop.driver._scan_context import current_executor from solprop.driver._scan_model import Scan, ScanPoint, name_seed -from solprop.driver.executors import Batch, Executor, Local +from solprop.driver.executors import Executor, Local from solprop.driver.executors._request import ScanRequest from solprop.driver.executors.pool import PlaneScalars, peak_rss from solprop.driver.executors.queue import Queue, collect @@ -500,14 +500,6 @@ def stopped(self, job: _Job, wall_time: float = 0.0) -> PointResult: job.point.index, "stopped", error=STOPPED, wall_time=wall_time ) - def run_batch(self, jobs: Iterable[_Job], executor: Batch) -> Iterator[PointResult]: - """Delegate compatible jobs to the common lockstep scan driver.""" - from solprop.driver._scan_batch import ( # noqa: PLC0415 - shared worker types - execute, - ) - - yield from execute(jobs, self, executor) - def simulation(self, job: _Job) -> Simulation: """Construct a simulation and give its noise the point's seed. diff --git a/src/solprop/driver/batch.py b/src/solprop/driver/batch.py deleted file mode 100644 index d766553f3..000000000 --- a/src/solprop/driver/batch.py +++ /dev/null @@ -1,290 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""Prepare compatible fixed-schedule scan members without changing their backend.""" - -import dataclasses -from collections.abc import Iterable, Iterator, Mapping, Sequence -from dataclasses import dataclass - -import numpy as np - -from solprop._identity import text_digest -from solprop.backends.node_chunk import plan_node_chunk -from solprop.driver.simulation import Simulation -from solprop.exceptions import DriverError -from solprop.output.scan import _json -from solprop.translate.problem import PropagationProblem - -__all__ = [ - "BatchMember", - "compatible_groups", - "refuse_mixed_guides", - "shared_table_bytes", -] - - -@dataclass(frozen=True) -class BatchMember: - """Bind a global scan index to its independently translated simulation. - - Attributes - ---------- - index : int - Zero-based global scan index, retained after grouping and output splitting. - simulation : Simulation - Member with its own input, noise, parameter tables and backend selection. - """ - - index: int - simulation: Simulation - - -def _signature(member: BatchMember) -> str: - """Hash the execution layout while keeping member parameter tables independent.""" - simulation = member.simulation - backend = simulation.settings.backend - problem = simulation.translate() - request = simulation._run_request() - if problem.transform.geometry is not None: - raise DriverError("Batch currently requires fibre geometry") - if request.replay is None: - raise DriverError( - "Batch requires an explicit fixed schedule; discover and calibrate " - "with solprop.stepper before replay" - ) - transform = problem.transform - descriptor = { - "backend": backend, - "grid_kind": problem.grid_kind, - "shape": problem.shape, - "flags": problem.flags, - "noise_model": problem.initial.noise_model, - "grids": problem.grids, - "stepper": request.stepper, - "statistics": request.observation.stats, - "nodes": transform.n_nodes, - # Each member's planned chunk (SEP 47 section 6.5): members whose responses - # plan different chunks (Raman tensor weights, dispersive groups) do not - # share a lockstep group. - "node_chunk": plan_node_chunk( - problem, simulation.settings.execution_options() - ).chunk, - "transform_shape": transform.synthesis.shape, - "coarse_projection": transform.projection_coarse is not None, - "linear_structure": _structure(problem.linear), - "response_structure": _structure(problem.responses), - # The general modal route's narrow admission rule. Every other entry above - # describes an execution *layout*, and two different guides share all of it - # -- a 1.5 and a 1.6 um strand differ in no shape, no flag and no table - # extent -- so a general-guide group is separated by what the guides - # physically **are**: the table's three declared identities and its extents, - # the metric's kind, gauge and certificate, and the compiled responses' model - # and policy. Each is a scalar or a string, with the measured entries already - # quantised by `ModalTransformTables.identity`, so a re-translation on another - # BLAS does not split a batch that did not change. - "modal_identity": _modal_identity(problem), - } - return text_digest(_json(descriptor)) - - -def _modal_identity(problem: PropagationProblem) -> Mapping[str, object] | None: - """Describe which general modal guide a problem carries, or ``None`` for none. - - - Returns: the table, metric and response identities, all scalars and strings, or - ``None`` where the problem is not a general modal run at all. - """ - tables = problem.transform.modal_tables - if tables is None: - return None - metric = problem.linear.modal_metric - responses = problem.responses.regional_responses - return { - "tables": dict(tables.identity), - "metric": None - if metric is None - else { - "kind": metric.kind, - "gauge_id": metric.gauge_id, - "certificate_id": metric.certificate_id, - }, - "responses": None - if responses is None - else { - "model_id": responses.model_id, - "policy_id": responses.policy_id, - # The **whole** `(n_intervals, n_deg, n_responses)` array and not the - # `[0, 0]` row. Today's geometry is constant, so every interval and - # degree carries the same value and the row would separate the same - # guides; a z-varying `chi3` would make that silently false and two - # guides differing only away from the entrance would share a group. - "chi3": [float(one) for one in np.ravel(responses.chi3)], - "region": [int(one) for one in responses.response_region], - }, - } - - -def refuse_mixed_guides(problems: Sequence[PropagationProblem]) -> None: - """Refuse a formed group whose members are not the same general modal guide. - - The defence the descriptor cannot give. ``_signature`` separates two guides - into different groups, so this never fires on a group :func:`compatible_groups` - built; it fires on one assembled by hand or by a future grouping rule, where a - silently mixed group would propagate one guide's channels against another's - reference and nothing downstream would say so. - - Parameters - ---------- - problems : collections.abc.Sequence - The members' translated problems, in group order. - - Raises - ------ - DriverError - Naming the field at which two members part company. - """ - if not problems: - return - first = _modal_identity(problems[0]) - for index, problem in enumerate(problems[1:], start=1): - other = _modal_identity(problem) - if _json(other) == _json(first): - continue - which = "is a general modal guide and" if first is None else "differs from" - msg = ( - f"general-guide batch requires identical guide/table/gauge identity: " - f"member {index} {which} member 0. Members may differ in their launch " - "and their noise seed and in nothing else; run the others on their own " - "with Local or Pool" - ) - raise DriverError(msg) - - -def _structure(value: object) -> object: - """Describe table layouts without including their member-dependent values.""" - if isinstance(value, np.ndarray): - return (value.dtype.str, value.shape) - if dataclasses.is_dataclass(value) and not isinstance(value, type): - return { - "type": type(value).__qualname__, - "fields": { - field.name: _structure(getattr(value, field.name)) - for field in dataclasses.fields(value) - }, - } - if isinstance(value, Mapping): - return {key: _structure(item) for key, item in value.items()} - if isinstance(value, (tuple, list)): - return [_structure(item) for item in value] - if isinstance(value, (int, float, complex, np.generic)): - return value if isinstance(value, bool) else type(value).__name__ - return value - - -def compatible_groups( - members: Iterable[BatchMember], size: int -) -> Iterator[tuple[BatchMember, ...]]: - """Group adjacent compatible points with bounded resident translation products. - - Parameters - ---------- - members : iterable of BatchMember - Members in scan dispatch order. Their global indices are never renumbered. - size : int - Maximum positive number of members per group. - - Yields - ------ - tuple of BatchMember - A full batch, a group ended by a layout change, or the final partial batch. - - Raises - ------ - DriverError - If size is invalid, an index is negative, a member is unsupported, or a - formed group mixes general modal guides - (:func:`refuse_mixed_guides`, which every yielded group passes through). - """ - if isinstance(size, bool) or not isinstance(size, int) or size < 1: - raise DriverError("Batch size must be a positive integer") - current: list[BatchMember] = [] - signature = "" - backend: str | None = None - for member in members: - if member.index < 0: - raise DriverError("Batch indices must be nonnegative global indices") - selected = member.simulation.settings.backend - if backend is not None and selected != backend: - raise DriverError( - f"Batch refuses mixed backends {backend!r} and {selected!r}" - ) - backend = selected - key = _signature(member) - if current and key != signature: - yield _checked(current) - current = [] - current.append(member) - signature = key - if len(current) == size: - yield _checked(current) - current = [] - if current: - yield _checked(current) - - -def _checked(current: Sequence[BatchMember]) -> tuple[BatchMember, ...]: - """Return a formed group, refusing one whose members are not the same guide. - - Defence in depth, and the reason the manual can say a mixed general-guide - group is refused "at the driver and again at the backend": the guide identity - is in ``_signature``, so this never fires on a group this module built, - but a future grouping rule that dropped it would be caught here rather than - propagating one guide's channels against another's reference. The check is a - JSON comparison of identities the members' cached translations already - carry, so it costs nothing per group. - """ - refuse_mixed_guides([member.simulation.translate() for member in current]) - return tuple(current) - - -def shared_table_bytes(problems: Iterable[PropagationProblem]) -> int: - """Count host array storage once across shared translated member records. - - Parameters - ---------- - problems : iterable of PropagationProblem - Translations whose resident host allocations are being admitted. - - Returns - ------- - int - Unique backing-array bytes. This excludes native workspace and outputs, - which must be added from the backend ledger and retention plan separately. - """ - visited: set[int] = set() - storage: dict[int, int] = {} - - def _visit(value: object) -> None: - """Track backing allocations without recounting shared records or views.""" - if id(value) in visited: - return - visited.add(id(value)) - if isinstance(value, np.ndarray): - root = value - while isinstance(root.base, np.ndarray): - root = root.base - storage[id(root)] = root.nbytes - elif dataclasses.is_dataclass(value) and not isinstance(value, type): - for field in dataclasses.fields(value): - _visit(getattr(value, field.name)) - elif isinstance(value, Mapping): - for item in value.values(): - _visit(item) - elif isinstance(value, (tuple, list)): - for item in value: - _visit(item) - - for problem in problems: - _visit(problem) - return sum(storage.values()) diff --git a/src/solprop/driver/executors/__init__.py b/src/solprop/driver/executors/__init__.py index 62d3e39c3..9887de08b 100644 --- a/src/solprop/driver/executors/__init__.py +++ b/src/solprop/driver/executors/__init__.py @@ -7,13 +7,12 @@ from collections.abc import Callable, Iterable, Iterator from typing import Protocol, runtime_checkable -from solprop.driver.executors.batch import Batch from solprop.driver.executors.local import Local from solprop.driver.executors.pool import Pool from solprop.driver.executors.queue import Queue from solprop.driver.executors.slurm import Slurm -__all__ = ["Batch", "Executor", "Local", "Pool", "Queue", "Slurm"] +__all__ = ["Executor", "Local", "Pool", "Queue", "Slurm"] @runtime_checkable diff --git a/src/solprop/driver/executors/batch.py b/src/solprop/driver/executors/batch.py deleted file mode 100644 index 81656e650..000000000 --- a/src/solprop/driver/executors/batch.py +++ /dev/null @@ -1,73 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""Dispatch compatible scan members through their selected lockstep backend.""" - -from collections.abc import Callable, Iterable, Iterator -from dataclasses import dataclass, field -from typing import cast - -from solprop.exceptions import DriverError - -__all__ = ["Batch"] - - -@dataclass -class Batch: - """Run fixed-schedule scan batches in the calling process. - - The builder selects the backend. Compatible adjacent points share a fixed - march, while each retains its input, material tables, noise and statistics. - Smaller groups are used at layout boundaries and when memory requires them. - Adaptive simulations must first discover and calibrate a replay schedule. - - Attributes - ---------- - size : int - Positive maximum number of simultaneously advancing members. - memory_limit : int or None - Optional positive host-memory limit in bytes, further restricted by the - physical or scheduler allocation. Twenty percent remains as headroom. - budgets : list of dict - Admission calculations recorded for this invocation, in dispatch order. - Resolved backend policies and the actual batch size are stored per point. - """ - - size: int - memory_limit: int | None = None - budgets: list[dict[str, int | None]] = field(default_factory=list, init=False) - - def __post_init__(self) -> None: - """Reject invalid bounds before constructing any simulations.""" - for name, value in (("size", self.size), ("memory_limit", self.memory_limit)): - if value is None and name == "memory_limit": - continue - if isinstance(value, bool) or not isinstance(value, int) or value < 1: - raise DriverError(f"Batch {name} must be a positive integer") - - def run[T, R](self, points: Iterable[T], work: Callable[[T], R]) -> Iterator[R]: - """Execute scan work through its backend-preserving batch operation. - - Parameters - ---------- - points : iterable - Globally indexed scan jobs, consumed with bounded lookahead. - work : callable - Scan worker exposing the common driver's batch operation. - - Yields - ------ - object - Independently validated results, including failures and skipped points. - - Raises - ------ - DriverError - If work does not implement scan batching or a contract cannot execute. - """ - operation = getattr(work, "run_batch", None) - if not callable(operation): - raise DriverError("Batch requires run_scan work with a batch operation") - self.budgets.clear() - yield from cast(Iterator[R], operation(points, self)) diff --git a/src/solprop/driver/run.py b/src/solprop/driver/run.py index c35aa9c10..e5c8655e7 100644 --- a/src/solprop/driver/run.py +++ b/src/solprop/driver/run.py @@ -743,8 +743,8 @@ def open_run( """ # A session that holds its monitor from the start (the native session) reports # the launch's zeros here. The execution record carries the monitor instead - # (`_record_execution`), as a group's points do (`_scan_batch`); a scan writes the - # opening record into every point's metadata. + # (`_record_execution`); a scan writes the opening record into every point's + # metadata. executed = { name: value for name, value in backend.metadata().items() @@ -932,7 +932,7 @@ def _refuse_unrunnable( if refusal is not None: raise DriverError(refusal) # What the problem does not carry, refused here for every executor rather than at - # the first plane (SEP 47 section 6.3), as a preparation and a group refuse it. + # the first plane (SEP 47 section 6.3), as a preparation refuses it. refusal = statistics_unavailable(problem, [*spec.names, *spec.periodic]) if refusal is not None: raise BackendError(refusal) diff --git a/src/solprop/driver/scan.py b/src/solprop/driver/scan.py index 0e6fd1a68..aedbf9966 100644 --- a/src/solprop/driver/scan.py +++ b/src/solprop/driver/scan.py @@ -74,11 +74,11 @@ def run_scan( The scan's stop flag: any object with an ``is_set()`` method, such as a :class:`threading.Event` (SEP 41, S17). Once it is set no further point is dispatched; ``Local`` and ``Pool`` stop the points in flight within one step, - a ``Pool`` through a message on each busy worker's pipe; ``Batch`` stops - between groups. A stopped point is not committed, so a rerun computes it - again, and the scan returns normally, its file holding the points finished - before the stop; it logs at ``INFO`` that it stopped, and a scan reporter is - told ``"stopped"`` for each stopped point. ``Queue`` and ``Slurm`` refuse it. + a ``Pool`` through a message on each busy worker's pipe. A stopped point is + not committed, so a rerun computes it again, and the scan returns normally, + its file holding the points finished before the stop; it logs at ``INFO`` + that it stopped, and a scan reporter is told ``"stopped"`` for each stopped + point. ``Queue`` and ``Slurm`` refuse it. recipe : solprop.output.records.RecipeRecord or None, optional The recipe the scan was built from, which the scan file records once, so that it reopens with its setup (SEP 41, S2); :meth:`solprop.recipe.core.Recipe.scan` diff --git a/src/solprop/log.py b/src/solprop/log.py index b16d94dbf..2f3964bd2 100644 --- a/src/solprop/log.py +++ b/src/solprop/log.py @@ -464,8 +464,8 @@ class ScanReporter(Protocol): not; an exception from the scan propagates without it. The calls are made in the controlling process, in the thread that called ``run_scan``. When a point starts depends on the executor: ``Local`` at its build, ``Pool`` when the point is sent to - a worker, and ``Batch``, ``Queue`` and ``Slurm`` only when its result is collected, - just before :meth:`point_finished`. + a worker, and ``Queue`` and ``Slurm`` only when its result is collected, just + before :meth:`point_finished`. Subclass it, or :class:`NullScanReporter`, to inherit a no-op for each call you do not override. @@ -524,7 +524,7 @@ def point_reporter(self, index: int) -> ProgressReporter | None: the controller, which makes them on the reporter returned here as the messages arrive; each plane carries its position and the four scalars of its :class:`PlaneSummary`, never a field, and ``step``, on the hot path, is not - sent. ``Batch``, ``Queue`` and ``Slurm`` ask for none. + sent. ``Queue`` and ``Slurm`` ask for none. Parameters ---------- diff --git a/src/solprop/output/scan.py b/src/solprop/output/scan.py index b920e5098..f64a695c2 100644 --- a/src/solprop/output/scan.py +++ b/src/solprop/output/scan.py @@ -379,8 +379,8 @@ def commit(self, result: PointResult) -> None: self._layouts_stale() if not 0 <= result.index < len(_dataset(self.file, "points/index")): raise OutputError("result index is outside the scan") - # A committed point is the only copy of its arrays on the Local, Pool and - # Batch routes. A failure reported for one is a failure of this attempt to + # A committed point is the only copy of its arrays on the Local and Pool + # routes. A failure reported for one is a failure of this attempt to # re-derive it -- a builder that now raises, a worker that died -- and must # never publish over it or delete its staged group. if result.status == "failed" and self.state(result.index)[0] == "done": diff --git a/src/solprop/sol.py b/src/solprop/sol.py index 06df68d3f..d6f831c1f 100644 --- a/src/solprop/sol.py +++ b/src/solprop/sol.py @@ -41,7 +41,7 @@ import warnings from typing import cast -from solprop.driver.executors import Batch, Local, Pool, Queue, Slurm +from solprop.driver.executors import Local, Pool, Queue, Slurm from solprop.driver.interface import ( prop_capillary, prop_free, @@ -276,7 +276,6 @@ __all__ = [ "RDW", "ZDW", - "Batch", "BeamParams", "CWPulse", "CallbackOutput", diff --git a/src/solprop/stats.py b/src/solprop/stats.py index 6a1f59ae8..d1155fd31 100644 --- a/src/solprop/stats.py +++ b/src/solprop/stats.py @@ -2479,29 +2479,6 @@ def n_regions(self) -> int: # numpydoc ignore=RT01 """ return int(self.spectral_regions.shape[0]) - def same_tables(self, other: "StatsSpec") -> bool: - """Return whether another spec carries the same far-field tables. - - Parameters - ---------- - other : StatsSpec - The spec to compare, for example a lockstep batch member's. - - Returns - ------- - bool - True when both carry no apertures or the same apertures entry for entry, - and identical regions: a structural comparison. - """ - same_apertures = ( - other.apertures is None - if self.apertures is None - else self.apertures.same_as(other.apertures) - ) - return same_apertures and np.array_equal( - self.spectral_regions, other.spectral_regions - ) - @property def n_windows(self) -> int: # numpydoc ignore=RT01 """How many spectral windows the spec carries.""" diff --git a/src/solprop/translate/problem.py b/src/solprop/translate/problem.py index 46f247f69..488e77fcb 100644 --- a/src/solprop/translate/problem.py +++ b/src/solprop/translate/problem.py @@ -412,9 +412,7 @@ class Initial: ---------- field0 : numpy.ndarray Initial state, complex128, shape ``(n_modes, n_pol, n_omega)``, in the square - root of watts; possibly a read-only broadcast view, never written. A group of - trajectories is a sequence of problems, one per member (SEP 47 section 6.7), - never a leading axis here. + root of watts; possibly a read-only broadcast view, never written. noise0 : numpy.ndarray or None The shot-noise realisation in the same layout, or ``None``. What a backend does with it depends on ``noise_model``: an ``'input'`` draw is added once to @@ -536,7 +534,7 @@ class StepperSettings: landed on directly. 1 switches it off. schedule : solprop.stepper.schedule.FixedSchedule or None A fixed schedule to replay, whose edges must contain every save plane and hard - kink. ``None`` for an adaptive run; lockstep batches require one. + kink. ``None`` for an adaptive run. save_planes : numpy.ndarray Positions in z the driver will ask for, m, shape ``(n_z,)``, increasing. Steps land on them exactly; there is no dense output. @@ -2335,8 +2333,7 @@ def _state( """Bring an initial field to the canonical single-trajectory layout. The shape is checked here rather than by an annotation, so that a wrong rank is - reported by name in production too. A group of trajectories is a sequence of - problems (SEP 47 section 6.7), never a stacked field. + reported by name in production too. - Returns: the state, complex128, the problem's own: copied once here as :class:`Initial` holds it, so that it is not copied again there, and taken as it diff --git a/tests/backends/native_trace_marches.py b/tests/backends/native_trace_marches.py index 7384dfe5a..e690023d4 100644 --- a/tests/backends/native_trace_marches.py +++ b/tests/backends/native_trace_marches.py @@ -7,8 +7,8 @@ The native session runs the compiled Adams and Runge-Kutta marches (``adams_march.cpp``, ``rk_march.cpp``) to an event and holds their state natively. The decision-trace tests hold those marches to the reference's decisions on identical scripted readings -(``adams_traces.py``, ``rk_traces.py``): a scripted native march -(``_core.ScriptedMarch``, ``_core.ScriptedRkMarch``) is driven a call at a time over a +(``adams_traces.py``, ``rk_traces.py``): a scripted native march (the private test +module's ``ScriptedMarch``, ``ScriptedRkMarch``) is driven a call at a time over a scripted host backend, each call's attempts booked into the harness as the reference books its own. That driving loop is the adapter the native backend used before SEP 47 phase 5 moved every native run @@ -36,6 +36,7 @@ backend_module = pytest.importorskip("solprop_native.backend") session_module = pytest.importorskip("solprop_native.session") native = pytest.importorskip("solprop_native") +_testing = pytest.importorskip("solprop_native._core")._testing WATCH_POLICY_FIELDS = ( "split", @@ -78,7 +79,6 @@ _BUDGET = backend_module._BUDGET _DIVERGED = backend_module._DIVERGED _DENSE = backend_module._DENSE -_ResidentAdams = backend_module._ResidentAdams _envelope_errors = backend_module._envelope_errors _raise_rk = session_module._raise_rk @@ -410,11 +410,11 @@ def _native_run( return self._runner.run(state, bounds) native = self._driver._native_state with _envelope_errors(): - return native.adams_march_run(state, bounds) + return _testing.adams_march_run(native, state, bounds) def _synchronise(self, result: dict[str, Any]) -> None: """Adopt the state a native call handed back.""" - backend, engine = self._driver, self._engine + backend = self._driver state = result["state"] backend._z = float(state["z"]) backend._proposal = float(state["proposal"]) @@ -433,15 +433,6 @@ def _synchronise(self, result: dict[str, Any]) -> None: for name, value in state["ledger"].items(): setattr(ledger, name, int(value)) ledger.orders.extend(int(order) for order in result["orders"]) - if isinstance(engine, _ResidentAdams): - step = None - if result["stepped"]: - order = int(result["step_order"]) - nodes = [1.0, *(float(node) for node in result["step_nodes"][:order])] - step = (float(result["step_z"]), float(result["step_dz"]), nodes) - engine.march_stepped( - step, fused=self._fused, carrier=list(result["step_carrier"]) - ) class TraceRungeKuttaMarch(session_module._NativeRungeKuttaMarch): @@ -709,7 +700,7 @@ def _native_run( if self._runner is not None: return self._runner.run(state, bounds) with _envelope_errors(): - return self._driver._native_state.rk_march_run(state, bounds) + return _testing.rk_march_run(self._driver._native_state, state, bounds) def _raise(self, reason: int, result: dict[str, Any]) -> None: """Raise the error a call returned with, if any.""" diff --git a/tests/backends/test_backend_protocol.py b/tests/backends/test_backend_protocol.py index 1dfc70275..5bc32d094 100644 --- a/tests/backends/test_backend_protocol.py +++ b/tests/backends/test_backend_protocol.py @@ -389,7 +389,6 @@ class Stub: """The smallest object that satisfies the seam.""" name = "stub" - max_batch = 1 reads_transverse_edge = False in_flight = None closed = False @@ -405,9 +404,6 @@ def set_initial(self, field, noise, *, z=0.0, resume=False): def prepare(self, problem, request): return HostPrepared(self, problem, request) - def prepare_group(self, members, problems, requests): - raise BackendError("the stub runs no group") - def restore_call_ledgers(self, logical, atomic=None): return None @@ -478,7 +474,6 @@ def test_a_minimal_backend_satisfies_the_protocol(): def test_an_object_missing_a_method_is_not_a_backend(): class Partial: name = "partial" - max_batch = 1 def set_initial(self, field, noise): return None diff --git a/tests/backends/test_batch_lockstep.py b/tests/backends/test_batch_lockstep.py deleted file mode 100644 index 76aeb2292..000000000 --- a/tests/backends/test_batch_lockstep.py +++ /dev/null @@ -1,503 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""Check the reference's member-workspace lockstep group against independent fixed runs. - -A batch member and its solo run take one method on one fixed schedule, so they agree -within a rounding budget (SEP 25), not to the bit. The native backend's group is its -group session (``solprop_native.group``, ``tests/sessions/test_native_group.py``); its -members are held to the reference's lockstep group here, within the singleton ladder. -""" - -import dataclasses -import inspect -import math -from collections.abc import Sequence -from contextlib import ExitStack -from typing import Any, cast - -import numpy as np -import pytest - -from bounds import assert_within, gamma, ladder_bound -from solprop.backends import Backend, BatchBackend, select, select_batch -from solprop.backends.events import ObservationReady -from solprop.backends.export import ExportRecipe -from solprop.backends.host import group as group_module -from solprop.backends.host.driver import HostDriver -from solprop.backends.host.group import HostGroup -from solprop.backends.numpy_ref.batch import NumpyBatchBackend -from solprop.backends.session import Start -from solprop.backends.sessions import start_group -from solprop.driver import Simulation -from solprop.exceptions import BackendError, BoundaryError -from solprop.monitor import BoundaryCheck, BoundaryMonitor -from solprop.stats import StatsSpec -from solprop.stepper import LowStorageRungeKutta, Multistep, PIController -from solprop.stepper.runge_kutta import RungeKutta -from solprop.stepper.schedule import FixedSchedule - - -def simulation(index, backend, noise=None): - # The Runge-Kutta march's fused batch passes; an Adams batch is in - # tests/backends/test_exponential_march.py. - return Simulation.from_gnlse( - 0.11 * (index + 1), - 0.001, - [0.0, 0.0, -1.183e-26 * (index + 1)], - wavelength=835e-9, - wavelength_limits=(500e-9, 2e-6), - trange=1e-12, - width=100e-15, - peak_power=float(index + 1), - shape="sech", - save_planes=[0.0005, 0.001], - schedule=FixedSchedule.uniform( - 0.0, 0.001, 0.00025, save_planes=[0.0005, 0.001] - ), - stats=StatsSpec(names=("energy", "peak_power"), periodic=("energy",), period=2), - noise=noise, - seed=index + 13 if noise is not None else None, - backend=backend, - integrator=RungeKutta(), - absorber=False, - ) - - -def loaded(simulation, cleanup): - problem = simulation.translate() - run_request = simulation._run_request() - owner = select( - simulation.settings.backend, - problem, - run_request, - grid=simulation.grid, - modes=simulation.modes, - profiles=simulation.profiles, - ) - cleanup.callback(owner.close) - if owner.name == "native": - # The native backend loads a start only in its session (SEP 47). - return cast("Any", owner) - # The reference's own driver, which a group steps directly. - assert isinstance(owner, HostDriver) - owner.set_initial(problem.initial.field0, simulation.noise) - return cast("Any", owner) - - -STEPS = 4 -"""The fixed Runge-Kutta steps to the last plane.""" - -FIELD_BOUND = STEPS * 16 * np.finfo(float).eps -"""The singleton ladder's 16 eps a step: a member and its solo run take one method on -one schedule and differ by the order of their reductions alone.""" - - -def assert_observations_agree(actual, expected, rtol, bound=FIELD_BOUND): - """A member's observation against its solo run's: exact where it is structural. - - The position, the schedule and the acceptances are prescribed, so exact; the field - and the modified noise's phase are held to the run's relative `bound`; the error - norm, a defect over ``rtol``, to seven stages of that over ``rtol``; the statistics - rows, squares and their sums, to twice the bound and the sum's reduction. - """ - assert actual.z == expected.z - assert_within(actual.field, expected.field, bound, what="field") - if expected.noise_phase is None: - assert actual.noise_phase is None - else: - np.testing.assert_allclose( - actual.noise_phase, - expected.noise_phase, - rtol=0, - atol=bound * float(np.max(np.abs(expected.noise_phase), initial=1.0)), - ) - for name in ("z", "dz", "accepted"): - np.testing.assert_array_equal( - getattr(actual.step_history, name), getattr(expected.step_history, name) - ) - np.testing.assert_allclose( - actual.step_history.error_norm, - expected.step_history.error_norm, - rtol=0, - atol=7 * bound / rtol, - ) - np.testing.assert_array_equal(actual.step_stats.z, expected.step_stats.z) - np.testing.assert_array_equal(actual.step_stats.step, expected.step_stats.step) - assert actual.step_stats.values.keys() == expected.step_stats.values.keys() - for name in expected.step_stats.values: - np.testing.assert_allclose( - actual.step_stats.values[name], - expected.step_stats.values[name], - rtol=statistics_bound(actual.field, bound), - err_msg=name, - ) - - -def statistics_bound(field, bound=FIELD_BOUND): - """Twice the field's budget, for squares, and a reduction over the samples.""" - return 2 * bound + gamma(np.size(field)) - - -@pytest.mark.parametrize( - ("backend", "runner_factory"), - [ - ("numpy_ref", HostGroup), - ("numpy_ref", NumpyBatchBackend), - ("numpy_ref", select_batch), - ], -) -@pytest.mark.parametrize("count", [1, 3]) -@pytest.mark.parametrize("noise", [None, "input", "modified"]) -@pytest.mark.parametrize("weighted", [False, True]) -def test_lockstep_preserves_member_physics_noise_and_statistics( - backend, runner_factory, count, noise, weighted -): - with ExitStack() as cleanup: - simulations = [simulation(index, backend, noise) for index in range(count)] - if weighted: - for one in simulations: - one.settings = dataclasses.replace( - one.settings, - controller=dataclasses.replace( - cast("PIController", one.settings.controller), - weights=np.linspace(0.5, 1.5, one.grid.n_omega), - ), - ) - members = tuple(loaded(one, cleanup) for one in simulations) - independent = tuple(loaded(one, cleanup) for one in simulations) - runner = runner_factory(members) - cleanup.callback(runner.close) - spec = simulations[0]._run_request().observation.stats - rtol = cast("PIController", simulations[0].settings.controller).rtol - for target in (0.0, 0.0005, 0.001): - runner.propagate_to(target) - for owner in independent: - owner.propagate_to(target) - batched_stats = runner.stats(spec) - for index, (actual, owner) in enumerate( - zip(runner.observe_members(), independent, strict=True) - ): - expected = owner.observe() - assert_observations_agree(actual, expected, rtol) - for name, value in owner.stats(spec).items(): - np.testing.assert_allclose( - batched_stats[name][index], - value, - rtol=statistics_bound(expected.field), - err_msg=name, - ) - assert runner.metadata()["backend"] == backend - assert runner.metadata()["fused_batch_kernels"] is False - assert len(runner.member_metadata()) == count - assert sum(runner.memory_ledger().values()) > 0 - runner.close() - assert runner.memory_ledger() == {} - - -def test_lockstep_interleaves_members_at_each_fixed_step(monkeypatch): - visited = [] - with ExitStack() as cleanup: - members = tuple(loaded(simulation(i, "numpy_ref"), cleanup) for i in range(3)) - for index, owner in enumerate(members): - original = owner._trial_step - - def traced(z, dz, *, index=index, original=original): - visited.append((index, z, dz)) - return original(z, dz) - - monkeypatch.setattr(owner, "_trial_step", traced) - runner = HostGroup(members) - cleanup.callback(runner.close) - runner.propagate_to(0.001) - assert [index for index, _, _ in visited] == [0, 1, 2] * 4 - for start in range(0, len(visited), 3): - assert len({(z, dz) for _, z, dz in visited[start : start + 3]}) == 1 - - -def _native_group_fields(candidates, cleanup): - """Run native members through their group session; return each last field.""" - problems = [one.translate() for one in candidates] - owners = [ - select( - one.settings.backend, - problem, - one._run_request(), - grid=one.grid, - modes=one.modes, - profiles=one.profiles, - ) - for one, problem in zip(candidates, problems, strict=True) - ] - for owner in owners: - cleanup.callback(owner.close) - group = start_group( - owners, - problems, - [one._run_request() for one in candidates], - [ - Start.entrance(problem, noise=one.noise) - for one, problem in zip(candidates, problems, strict=True) - ], - ) - cleanup.callback(group.close) - last: list[np.ndarray | None] = [None] * len(candidates) - identity = ExportRecipe(power=False, optics=False) - while not group.finished: - batch = group.advance() - for member, events in enumerate(batch.members): - for event in events: - if isinstance(event, ObservationReady): - last[member] = np.array( - group.export(member, event.ticket, identity) - ) - group.acknowledge(batch.receipt) - return last - - -@pytest.mark.parametrize("noise", [None, "input", "modified"]) -def test_the_native_group_agrees_with_the_numpy_oracle(noise): - # The native group session's members against the reference's lockstep group, - # within the singleton ladder: the oracle the native lockstep batch was held to. - pytest.importorskip("solprop_native") - with ExitStack() as cleanup: - candidates = [simulation(index, "native", noise) for index in range(3)] - # The established singleton ladder allows 16 eps per step on the host, - # with seven FFT round trips per step in the predeclared device bound. - bound = ladder_bound( - "native", 4 * 16 * np.finfo(float).eps, candidates[0].grid.n_to, 4 * 7 - ) - assert bound > 0 - fields = _native_group_fields(candidates, cleanup) - reference = select_batch( - cast( - Sequence[Backend], - tuple( - loaded(simulation(i, "numpy_ref", noise), cleanup) for i in range(3) - ), - ) - ) - cleanup.callback(reference.close) - reference.propagate_to(0.001) - for ours, oracle in zip(fields, reference.observe_members(), strict=True): - assert ours is not None - expected = oracle.require_field() - relative = np.linalg.norm(ours - expected) / np.linalg.norm(expected) - assert relative < bound - - -def test_lockstep_refuses_mixed_backends(monkeypatch): - pytest.importorskip("solprop_native") - # Each copy's own refusals, which the test session's annotation hook would - # otherwise preempt: a member of the other family is not its driver type. - monkeypatch.setattr( - group_module, - "_validate_members", - inspect.unwrap(group_module._validate_members), - ) - with ExitStack() as cleanup: - members = tuple( - loaded(simulation(0, name), cleanup) for name in ("numpy_ref", "native") - ) - with pytest.raises(BackendError, match="mixed backends"): - inspect.unwrap(HostGroup.__init__)(HostGroup.__new__(HostGroup), members) - - -GROUPS = [ - pytest.param("numpy_ref", HostGroup, id="host"), - pytest.param("numpy_ref", select_batch, id="registry"), -] -"""The reference's group, built directly and through the registry's runner.""" - - -@pytest.mark.parametrize(("backend", "group"), GROUPS) -def test_lockstep_refuses_adaptive_schedule(backend, group): - one = simulation(0, backend) - one.settings = dataclasses.replace(one.settings, schedule=None) - with ExitStack() as cleanup: - owner = loaded(one, cleanup) - with pytest.raises(BackendError, match="explicit fixed schedule"): - group([owner]) - - -def test_lockstep_refuses_shared_history_observation_and_closes_members(): - with ExitStack() as cleanup: - owner = loaded(simulation(0, "numpy_ref"), cleanup) - runner = HostGroup([owner]) - with pytest.raises(BackendError, match="individual error histories"): - runner.observe() - runner.close() - runner.close() - with pytest.raises(BackendError, match="closed"): - owner.observe() - - -def test_a_field_free_observation_moves_no_field_and_keeps_each_member_s_record(): - # solprop #299: a scan that keeps no field of a plane asks for none. Each member's - # position, history and statistics are what the same march observes with its field. - backend = "numpy_ref" - spec = StatsSpec(names=("energy", "peak_power"), periodic=("energy",), period=2) - group = HostGroup - with ExitStack() as cleanup: - kept = group(tuple(loaded(simulation(i, backend), cleanup) for i in range(2))) - cleanup.callback(kept.close) - free = group(tuple(loaded(simulation(i, backend), cleanup) for i in range(2))) - cleanup.callback(free.close) - kept.propagate_to(0.0005) - free.propagate_to(0.0005) - for theirs, ours in zip( - kept.observe_members(), free.observe_members(field=False), strict=True - ): - assert theirs.field is not None - assert ours.field is None - assert ours.noise_phase is None - assert ours.z == theirs.z - np.testing.assert_array_equal(ours.step_history.z, theirs.step_history.z) - np.testing.assert_array_equal(ours.step_history.dz, theirs.step_history.dz) - np.testing.assert_array_equal( - ours.step_history.error_norm, theirs.step_history.error_norm - ) - np.testing.assert_array_equal(ours.step_stats.z, theirs.step_stats.z) - for name, row in theirs.step_stats.values.items(): - np.testing.assert_array_equal(ours.step_stats.values[name], row) - statistics = free.stats(spec) - assert statistics.keys() == kept.stats(spec).keys() - for name, value in kept.stats(spec).items(): - np.testing.assert_array_equal(statistics[name], value) - # A field after a field-free plane is the march's own, not a stale copy. - kept.propagate_to(0.001) - free.propagate_to(0.001) - last = free.observe_members() - for theirs, ours in zip(kept.observe_members(), last, strict=True): - np.testing.assert_array_equal(ours.field, theirs.field) - - -def test_lockstep_refuses_empty_members(): - with pytest.raises(BackendError, match="at least one member"): - HostGroup([]) - - -def test_batch_registry_adopts_members_and_exposes_independent_observations(): - with ExitStack() as cleanup: - members = tuple(loaded(simulation(i, "numpy_ref"), cleanup) for i in range(2)) - runner = select_batch(cast(Sequence[Backend], members)) - cleanup.callback(runner.close) - assert isinstance(runner, BatchBackend) - assert runner.max_batch == 2 - assert len(runner.observe_members()) == 2 - assert len(runner.member_metadata()) == 2 - - -@pytest.mark.parametrize(("backend", "group"), GROUPS) -def test_a_low_storage_group_stops_to_save_and_refuses_to_run_out(backend, group): - # Each member's own march takes the common step (SEP 24); every third step's end - # is saved (SEP 14 phase 3), so the group returns there, short of its target, and - # goes on from there. Past the schedule's last edge it cannot go. - simulations = [simulation(index, backend) for index in range(2)] - for one in simulations: - one.settings = dataclasses.replace( - one.settings, integrator=LowStorageRungeKutta(), step_planes=3 - ) - with ExitStack() as cleanup: - runner = group(tuple(loaded(one, cleanup) for one in simulations)) - cleanup.callback(runner.close) - runner.propagate_to(0.0005) - for target, reached in ((0.001, 0.00075), (0.001, 0.001)): - runner.propagate_to(target) - for member in runner.observe_members(field=False): - assert member.z == pytest.approx(reached, rel=1e-12) - with pytest.raises(BackendError, match=r"cannot reach z = 0\.00102 m"): - runner.propagate_to(0.00102) - - -@pytest.mark.parametrize(("backend", "group"), GROUPS) -def test_an_adams_group_names_the_member_behind_an_invalid_norm( - backend, group, monkeypatch -): - # Each Adams member replays the common step through its own march; a norm that - # the member's own step record refuses is refused with the member's index. - simulations = [simulation(index, backend) for index in range(2)] - for one in simulations: - one.settings = dataclasses.replace(one.settings, integrator=Multistep()) - with ExitStack() as cleanup: - members = tuple(loaded(one, cleanup) for one in simulations) - runner = group(members) - cleanup.callback(runner.close) - monkeypatch.setattr( - members[1]._adams, "replay_step", lambda dz, end, slack: math.nan - ) - with pytest.raises(BackendError, match="member 1 returned an invalid error"): - runner.propagate_to(0.0005) - - -@pytest.mark.parametrize(("backend", "group"), GROUPS) -def test_lockstep_gives_every_member_its_own_boundary_monitor(backend, group): - with ExitStack() as cleanup: - simulations = [simulation(index, backend) for index in range(2)] - members = tuple(loaded(one, cleanup) for one in simulations) - runner = group(members) - cleanup.callback(runner.close) - grid = simulations[0].grid - # The cheap members' window holds about 1e-5 of their energy in its guards, - # a field of 3e-3: a check at that budget watches them without a warning. - relaxed = BoundaryCheck(budget=1e-2) - runner.attach_monitor(BoundaryMonitor.build(grid, None, relaxed)) - runner.propagate_to(0.001) - monitors = [member._monitor for member in members] - assert monitors[0] is not monitors[1] - for monitor in monitors: - assert monitor is not None - planes = monitor.summary()["planes"] - assert isinstance(planes, dict) - assert planes["z"][-1] == pytest.approx(0.001) - - -@pytest.mark.parametrize(("backend", "group"), GROUPS) -def test_a_member_s_stop_ends_its_watch_alone(backend, group): - # A check strict enough to refuse any launch stops the first member before its - # first step; the second, unwatched, and the batch go on. - with ExitStack() as cleanup: - simulations = [simulation(index, backend) for index in range(2)] - members = tuple(loaded(one, cleanup) for one in simulations) - runner = group(members) - cleanup.callback(runner.close) - strict = BoundaryCheck(budget=1e-300, stop_factor=1.0) - runner.attach_monitors( - [BoundaryMonitor.build(simulations[0].grid, None, strict), None] - ) - runner.propagate_to(0.001) - runner.finish_monitors() - stopped, unwatched = runner.member_stops - assert isinstance(stopped, BoundaryError) - assert unwatched is None - assert members[0]._monitor is None - assert runner._z == pytest.approx(0.001) - - -@pytest.mark.parametrize(("backend", "group"), GROUPS) -def test_lockstep_refuses_a_monitor_per_member_miscount(backend, group): - with ExitStack() as cleanup: - members = tuple(loaded(simulation(i, backend), cleanup) for i in range(2)) - runner = group(members) - cleanup.callback(runner.close) - with pytest.raises(BackendError, match="1 boundary monitors for 2 members"): - runner.attach_monitors([None]) - - -def test_batch_registry_refuses_empty_and_mixed_owners(): - with pytest.raises(BackendError, match="at least one"): - select_batch([]) - pytest.importorskip("solprop_native") - with ExitStack() as cleanup: - members = tuple( - loaded(simulation(0, name), cleanup) for name in ("numpy_ref", "native") - ) - with pytest.raises(BackendError, match="mixed backends"): - select_batch(cast(Sequence[Backend], members)) - # The native backend's group is its own group session, with no runner. - with pytest.raises(BackendError, match="no runner for backend 'native'"): - select_batch(cast(Sequence[Backend], members[1:])) - # Each refusal leaves its members open, and the reference's where it was. - assert not any(member.closed for member in members) - assert members[0].observe().z == 0.0 diff --git a/tests/backends/test_batch_responses.py b/tests/backends/test_batch_responses.py deleted file mode 100644 index 3ea168d46..000000000 --- a/tests/backends/test_batch_responses.py +++ /dev/null @@ -1,248 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""Check batch isolation for the tiny modal, Raman and plasma response problems. - -The three problem builders below are backend-agnostic -:class:`~solprop.translate.problem.PropagationProblem` constructions, small enough -(``n_to <= 64``, eight fixed steps) that a batch and its members can be compared -directly on every backend the batch runner supports, within a rounding budget: the -reference's lockstep group. The native backend's group runs each member as its own -native session (``solprop_native.group``), held to the member run alone in -``tests/sessions/test_native_group.py``. -""" - -import dataclasses -import math -from contextlib import ExitStack - -import numpy as np -import pytest - -from backends import test_batch_lockstep as batch_tests -from bounds import EPS, gamma -from former_raman import FORMER_H2, former_response -from rate_oracles import AdkOracle, adk_oracle -from solprop.backends import select, select_batch -from solprop.backends.session import ExecutionOptions -from solprop.constants import AU_ENERGY -from solprop.grid import EnvelopeGrid, FieldGrid -from solprop.modes import MarcatiliMode, transverse_quadrature -from solprop.noise import modified_noise -from solprop.nonlinear.responses import KerrResponse, PlasmaResponse -from solprop.pulses import GaussianPulse -from solprop.stats import StatsSpec -from solprop.stepper import FixedSchedule, PIController -from solprop.translate.assembly import assemble - - -@pytest.fixture(params=["field", "envelope"]) -def modal_case(request): - # Same vacuum-index Kerr construction as test_polarised_runs, shortened only - # in its temporal unit-test grid. No gas-fit extrapolation or hidden warning. - grid_type = FieldGrid if request.param == "field" else EnvelopeGrid - grid = grid_type.from_limits(0.002, 800e-9, (300e-9, 2e-6), 8e-15) - modes = [MarcatiliMode(125e-6, m=m, cladding=1.45, loss=False) for m in (1, 2)] - pulse = GaussianPulse(wavelength=800e-9, fwhm=15e-15, energy=2e-6).build(grid) - return grid, modes, pulse - - -def modal_problem(case, route): - """Build the two-mode Kerr problem on one of the three component routes.""" - grid, modes, pulse = case - initial = np.repeat(pulse, 2, axis=0) / math.sqrt(2) - if route != "scalar": - initial = np.concatenate( - [ - math.cos(math.pi / 5) * initial, - math.sin(math.pi / 5) * np.exp(1j * math.pi / 3) * initial, - ], - axis=1, - ) - if route == "rows": - modes = [row for mode in modes for row in (mode, mode.rotated(math.pi / 2))] - initial = initial.reshape(4, 1, grid.n_omega) - return assemble( - grid, - modes, - [KerrResponse(chi3=1e-26, thg=grid.kind == "field")], - initial, - controller=PIController(rtol=1e-9, atol=1e-15), - density=1.0, - save_planes=[8e-4], - dz_init=1e-4, - dz_max=1e-4, - schedule=FixedSchedule.uniform(0.0, 8e-4, 1e-4), - quadrature=transverse_quadrature(modes, n_r=4, radial_rule="gauss"), - ) - - -def scalar_raman_problem(kind, with_plasma): - """Build the two-mode damped-oscillator Raman problem, optionally with plasma.""" - grid_type = FieldGrid if kind == "field" else EnvelopeGrid - # Plasma's two current streams require a sampled, certified temporal collar. - window = 400e-15 if with_plasma and kind == "field" else 8e-15 - grid = grid_type.from_limits(0.002, 800e-9, (300e-9, 2e-6), window) - modes = [MarcatiliMode(125e-6, m=m, cladding=1.45, loss=False) for m in (1, 2)] - pulse = GaussianPulse(wavelength=800e-9, fwhm=15e-15, energy=200e-6).build(grid) - initial = np.repeat(pulse, 2, axis=0) / math.sqrt(2) - responses = [ - KerrResponse(chi3=2e-52, thg=kind == "field"), - dataclasses.replace(former_response(FORMER_H2), thg=kind == "field"), - ] - if with_plasma: - # The potential-only ADK form solprop's former ``ADK("H2")`` took, on the - # former registry's potential, 0.5669 hartree (dc4ca0d): the batch compares - # with its members, so any fixed rate serves. - rate = AdkOracle("H2", 0.5669 * AU_ENERGY, 0, 1.0, hydrogenic=True) - responses.append(PlasmaResponse("H2", rate)) - problem, run_request = assemble( - grid, - modes, - responses, - initial, - density=1e24, - ionisation_field_range=(1e8, 8e10) if with_plasma else None, - controller=PIController(rtol=1e-9, atol=1e-15), - save_planes=[8e-7], - dz_init=1e-7, - dz_max=1e-7, - schedule=FixedSchedule.uniform(0.0, 8e-7, 1e-7), - quadrature=transverse_quadrature(modes, n_r=4, radial_rule="gauss"), - ) - return grid, problem, run_request - - -def scalar_plasma_problem(mode_count, preionisation, with_kerr): - """Build the argon plasma problem with per-species statistics to compare.""" - grid = FieldGrid.from_limits(0.002, 800e-9, (300e-9, 2e-6), 400e-15) - modes = [ - MarcatiliMode(125e-6, m=m, cladding=1.45, loss=False) - for m in range(1, mode_count + 1) - ] - pulse = GaussianPulse(wavelength=800e-9, fwhm=15e-15, energy=200e-6).build(grid) - initial = np.repeat(pulse, mode_count, axis=0) / math.sqrt(mode_count) - responses: list[PlasmaResponse | KerrResponse] = [ - PlasmaResponse("Ar", adk_oracle("Ar"), preionisation=preionisation) - ] - if with_kerr: - responses.append(KerrResponse(chi3=2e-52, thg=True)) - problem, run_request = assemble( - grid, - modes[0] if mode_count == 1 else modes, - responses, - initial, - controller=PIController(rtol=1e-9, atol=1e-15), - density=1e24, - ionisation_field_range=(1e8, 8e10), - save_planes=[8e-7], - dz_init=1e-7, - dz_max=1e-7, - schedule=FixedSchedule.uniform(0.0, 8e-7, 1e-7), - quadrature=None - if mode_count == 1 - else transverse_quadrature(modes, n_r=4, radial_rule="gauss"), - ) - return grid, problem, run_request - - -PARTIAL = ExecutionOptions(node_chunk=3) -"""Three-node chunks, which every multinode case's members and solo runs take.""" - - -def compare( - problem, - run_request, - grid, - backend, - *, - factory=select, - spec=None, - options: ExecutionOptions | None = PARTIAL, -): - if spec is None: - spec = StatsSpec(names=("energy", "peak_power"), periodic=("energy",), period=1) - run_request = run_request.for_run(stats=spec) - # A member and its solo run take one method on one fixed schedule: two steps of - # seven evaluations, each a transform's 32 eps a level and the plasma column's - # sums, gamma(12 n_to) (the band-rule ladder's count with a single tap). - n_to = problem.grids.n_to - bound = 2 * 7 * (32 * EPS * math.ceil(math.log2(n_to)) + gamma(12 * n_to)) - rtol = run_request.stepper.controller.rtol - with ExitStack() as cleanup: - members, independent = [], [] - for index in range(2): - draw = modified_noise( - grid, - np.random.default_rng(313 + index), - n_modes=problem.shape[0], - n_pol=problem.shape[1], - ) - initial = dataclasses.replace( - problem.initial, - field0=problem.initial.field0 * (1.0 + 0.125 * index), - noise0=draw.spectrum, - noise_model=draw.model, - ) - one = dataclasses.replace( - problem, - initial=initial, - flags=dataclasses.replace(problem.flags, has_noise=True), - ) - for destination in (members, independent): - owner = factory(backend, one, run_request, grid=grid, options=options) - cleanup.callback(owner.close) - owner.set_initial(initial.field0, draw) - destination.append(owner) - runner = select_batch(members) - cleanup.callback(runner.close) - for target in run_request.stepper.schedule.edges[1:3]: - runner.propagate_to(float(target)) - statistics = runner.stats(spec) - for index, (actual, owner) in enumerate( - zip(runner.observe_members(), independent, strict=True) - ): - owner.propagate_to(float(target)) - expected = owner.observe() - batch_tests.assert_observations_agree(actual, expected, rtol, bound) - for name, value in owner.stats(spec).items(): - np.testing.assert_allclose( - statistics[name][index], - value, - rtol=batch_tests.statistics_bound(expected.field, bound), - err_msg=name, - ) - runner.close() - assert runner.memory_ledger() == {} - - -@pytest.mark.parametrize("backend", ["numpy_ref"]) -@pytest.mark.parametrize("route", ["scalar", "product", "rows"]) -def test_modal_batches_preserve_members(modal_case, backend, route): - compare(*modal_problem(modal_case, route), modal_case[0], backend) - - -@pytest.mark.parametrize("backend", ["numpy_ref"]) -@pytest.mark.parametrize( - ("kind", "plasma"), [("envelope", False), ("field", False), ("field", True)] -) -def test_raman_and_plasma_batches_preserve_members(backend, kind, plasma): - grid, problem, run_request = scalar_raman_problem(kind, plasma) - compare(problem, run_request, grid, backend) - - -@pytest.mark.parametrize("backend", ["numpy_ref"]) -def test_plasma_batches_preserve_species_statistics(backend): - grid, problem, run_request = scalar_plasma_problem(2, 0.125, True) - compare( - problem, - run_request, - grid, - backend, - spec=StatsSpec( - names=("electron_density", "species_ionisation"), - periodic=("electron_density", "species_ionisation"), - period=1, - ), - ) diff --git a/tests/backends/test_batch_validation.py b/tests/backends/test_batch_validation.py deleted file mode 100644 index c5705352f..000000000 --- a/tests/backends/test_batch_validation.py +++ /dev/null @@ -1,250 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""Reject invalid batch contracts and isolate member failures at the shared boundary.""" - -import dataclasses -import inspect -import sys -from collections.abc import Sequence -from contextlib import ExitStack -from types import ModuleType -from typing import cast - -import numpy as np -import pytest - -from backends import test_batch_lockstep as fixtures -from scripted_driver import HostScriptedDriver -from solprop.backends import Backend, select_batch -from solprop.backends.host.group import HostGroup -from solprop.backends.numpy_ref import passes -from solprop.backends.numpy_ref.batch import NumpyBatchBackend -from solprop.exceptions import BackendError, ConvergenceError -from solprop.stats import StatsSpec -from solprop.stepper import FixedSchedule, Multistep, RungeKutta -from solprop.stepper.tableau import TSIT5 - -RUNNERS = [pytest.param(HostGroup, "numpy_ref", id="host")] -"""The reference's group over its members; the native backend's group is its group -session, validated in ``tests/sessions/test_native_group.py`` (SEP 47 phase 5).""" - - -def _members_of(name: str) -> None: - """Name the members' backend; every runner here is the reference's. - - Parameters - ---------- - name : str - The members' backend. - """ - assert name == "numpy_ref" - - -def test_batch_registry_has_no_native_runner_and_imports_nothing(monkeypatch): - # The native row names no lockstep runner (SEP 47 phase 5): the registry refuses - # a native member by name without importing the native package, untouched. - package = ModuleType("solprop_native") - monkeypatch.setitem(sys.modules, "solprop_native", package) - with ExitStack() as cleanup: - owner = fixtures.loaded(fixtures.simulation(0, "numpy_ref"), cleanup) - monkeypatch.setattr(owner, "name", "native") - with pytest.raises( - BackendError, - match=r"no runner for backend 'native': .* native runs its groups through " - r"its own prepared group, which solprop\.backends\.sessions\.start_group " - r"starts", - ): - select_batch(cast(Sequence[Backend], [owner])) - assert owner.observe().z == 0.0 - assert "solprop_native.batch" not in sys.modules - - -@pytest.mark.parametrize(("runner", "name"), RUNNERS) -@pytest.mark.parametrize( - "contract", ["tableau", "integrator", "schedule", "planes", "statistics"] -) -def test_batch_rejects_different_member_execution_contract(runner, name, contract): - _members_of(name) - first = fixtures.simulation(0, name) - second = fixtures.simulation(1, name) - changes = { - "tableau": {"integrator": RungeKutta(TSIT5)}, - "integrator": {"integrator": Multistep()}, - "schedule": {"schedule": FixedSchedule.uniform(0.0, 0.001, 0.000125)}, - "planes": {"save_planes": [0.001]}, - "statistics": {"stats": StatsSpec(names=("energy",))}, - } - second.settings = dataclasses.replace(second.settings, **changes[contract]) - with ExitStack() as cleanup: - members = [fixtures.loaded(one, cleanup) for one in (first, second)] - refused = "same integrator" if contract == "integrator" else "same" - with pytest.raises(BackendError, match=refused): - runner(members) - assert all(member.observe().z == 0.0 for member in members) - - -@pytest.mark.parametrize(("runner", "name"), RUNNERS) -@pytest.mark.parametrize("changed", ["mask", "shape", "advanced"]) -def test_batch_rejects_incompatible_or_advanced_members(runner, name, changed): - _members_of(name) - with ExitStack() as cleanup: - first, second = [ - fixtures.loaded(fixtures.simulation(i, name), cleanup) for i in range(2) - ] - problem = second._problem - if changed == "mask": - mask = problem.grids.norm_mask.copy() - mask[0] = not mask[0] - second._problem = dataclasses.replace( - problem, grids=dataclasses.replace(problem.grids, norm_mask=mask) - ) - elif changed == "shape": - second._problem = dataclasses.replace( - problem, - shape=(2, *problem.shape[1:]), - initial=dataclasses.replace( - problem.initial, field0=np.repeat(problem.initial.field0, 2, axis=0) - ), - ) # two modes where the first member has one - else: - second.propagate_to(0.0005) - with pytest.raises(BackendError, match=r"mask|shapes|entrance"): - runner([first, second]) - - -@pytest.mark.parametrize(("group", "name"), RUNNERS) -def test_batch_refuses_reloading_a_shared_field_and_mismatched_statistics( - monkeypatch, group, name -): - _members_of(name) - with ExitStack() as cleanup: - members = [ - fixtures.loaded(fixtures.simulation(i, name), cleanup) for i in range(2) - ] - runner = group(members) - cleanup.callback(runner.close) - with pytest.raises(BackendError, match="independently loaded"): - runner.set_initial(members[0]._problem.initial.field0, None) - monkeypatch.setattr(members[1], "stats", lambda spec: {"wrong": np.zeros(1)}) - with pytest.raises(BackendError, match="different statistic names"): - runner.stats(StatsSpec(names=("energy",))) - assert runner.available_device_memory() is None - - -@pytest.mark.parametrize("kind", ["common", "numpy"]) -@pytest.mark.parametrize("norm", [float("nan"), float("inf"), -1.0]) -def test_batch_names_the_member_behind_an_invalid_norm(monkeypatch, kind, norm): - # The same value refuses the member's own BackendHistory/StepSummary, so a - # singleton does not survive it either: what the batch owes its caller is the - # index of the point that produced it, not an anonymous history error. - with ExitStack() as cleanup: - name = "numpy_ref" - healthy = fixtures.loaded(fixtures.simulation(1, name), cleanup) - member = fixtures.loaded(fixtures.simulation(0, name), cleanup) - solo = fixtures.loaded(fixtures.simulation(0, name), cleanup) - if kind == "common": - for one in (member, solo): - monkeypatch.setattr( - one, "_trial_step", lambda z, dz, one=one: (norm, one._state) - ) - runner = HostGroup([healthy, member]) - else: - monkeypatch.setattr(passes, "error_norm", lambda *args: norm) - runner = select_batch(cast(Sequence[Backend], [healthy, member])) - cleanup.callback(runner.close) - offender = 0 if kind == "numpy" else 1 - with pytest.raises( - BackendError, match=f"member {offender} returned an invalid" - ): - runner.propagate_to(0.0005) - # The same member run alone is refused too: a non-finite norm at the step that - # produced it, by the replay that cannot reject it, and a negative one at the - # save plane, through the step record that cannot carry the value either. - refusal = ( - pytest.raises(BackendError, match="must be non-negative and finite") - if np.isfinite(norm) - else pytest.raises(ConvergenceError, match="non-finite error norm") - ) - with refusal: - solo.propagate_to(0.0005) - - -def test_reference_batch_refuses_mixed_noise_models(): - with ExitStack() as cleanup: - members = [ - fixtures.loaded(fixtures.simulation(i, "numpy_ref", noise), cleanup) - for i, noise in enumerate((None, "modified")) - ] - runner = select_batch(cast(Sequence[Backend], members)) - cleanup.callback(runner.close) - with pytest.raises(BackendError, match="compatible noise models"): - runner.propagate_to(0.0005) - - -def test_registry_refuses_unknown_backend_without_taking_ownership(monkeypatch): - with ExitStack() as cleanup: - owner = fixtures.loaded(fixtures.simulation(0, "numpy_ref"), cleanup) - monkeypatch.setattr(owner, "name", "future_backend") - with pytest.raises(BackendError, match="future_backend"): - select_batch(cast(Sequence[Backend], [owner])) - assert owner.observe().z == 0.0 - - -def test_batch_requires_complete_backend_protocol(): - simulation = fixtures.simulation(0, "numpy_ref") - owner = HostScriptedDriver(simulation.translate(), simulation._run_request()) - try: - owner.set_initial(simulation.translate().initial.field0, None) - with pytest.raises(BackendError, match="backend protocol"): - HostGroup([owner]) - finally: - owner.close() - - -def assert_family_refused(factory, wrong_backend): - """Assert a batch class refuses a member of another backend, untouched.""" - with ExitStack() as cleanup: - owner = fixtures.loaded(fixtures.simulation(0, wrong_backend), cleanup) - instance = factory.__new__(factory) - # Production does not install the test session's annotation hook. Exercise - # its explicit family refusal, which that hook would otherwise preempt. - initialize = inspect.unwrap(factory.__init__) - with pytest.raises(BackendError, match="requires"): - initialize(instance, [owner]) - # A native backend loads only in its session: it is left open. - assert not owner.closed - if wrong_backend != "native": - assert owner.observe().z == 0.0 - - -def test_the_reference_batch_checks_family_without_the_session_type_hook(): - pytest.importorskip("solprop_native") - assert_family_refused(NumpyBatchBackend, "native") - - -@pytest.mark.parametrize(("group", "name"), RUNNERS) -def test_batch_close_releases_other_members_when_one_close_fails( - monkeypatch, group, name -): - _members_of(name) - with ExitStack() as cleanup: - members = [ - fixtures.loaded(fixtures.simulation(i, name), cleanup) for i in range(2) - ] - runner = group(members) - close = cast(Backend, members[1]).close - - def failing_close(): - close() - raise BackendError("member cleanup failed") - - monkeypatch.setattr(members[1], "close", failing_close) - with pytest.raises(BackendError, match="cleanup failed"): - runner.close() - assert runner.memory_ledger() == {} - for member in members: - with pytest.raises(BackendError, match="closed"): - member.observe() - runner.close() diff --git a/tests/backends/test_compiled_multistep.py b/tests/backends/test_compiled_multistep.py index 3b18a7273..496a8f616 100644 --- a/tests/backends/test_compiled_multistep.py +++ b/tests/backends/test_compiled_multistep.py @@ -222,10 +222,17 @@ def assert_propagates_as_the_reference(backend_class, route): backend._staged_rows() state = backend._native_state stages = run_request.stepper.tableau.n_stages + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + rows = np.asarray( - state.adams_stage_scalars(0.0, SOURCE_AT)["phi_delta"], dtype=np.float64 + _testing.adams_stage_scalars(state, 0.0, SOURCE_AT)["phi_delta"], + dtype=np.float64, ).reshape(stages + 1, -1) - exponent = np.array(state.phase_sum_to_host(np.ascontiguousarray(rows[0]))) + exponent = np.array( + _testing.phase_sum_to_host(state, np.ascontiguousarray(rows[0])) + ) finally: backend.close() back = np.exp(exponent).reshape(reference_back.shape) diff --git a/tests/backends/test_driver.py b/tests/backends/test_driver.py index a4a65a67a..4aa3d721b 100644 --- a/tests/backends/test_driver.py +++ b/tests/backends/test_driver.py @@ -27,8 +27,7 @@ from scripted_driver import HostScriptedDriver from solprop.backends.host.driver import INITIAL_STEP_STATS_CAPACITY, HostDriver from solprop.backends.numpy_ref import NumpyRefBackend -from solprop.backends.numpy_ref.batch import NumpyBatchBackend -from solprop.backends.protocol import BatchBackend, StepStats +from solprop.backends.protocol import StepStats from solprop.exceptions import BackendError from solprop.log import BarReporter, LogReporter, NullReporter from solprop.noise import input_noise, modified_noise @@ -929,21 +928,13 @@ def test_a_trials_bundles_taken_together_are_kept_until_the_next_hoist(driver): def test_the_bundles_a_compiled_backend_packs_are_frozen(): - """The stage bundles, the march policy and the batch seam are the seam's literal. + """The stage bundles and the march policy are the seam's literal. A compiled backend is built against these names and shapes, and its build stays valid across solprop commits because this test, not a version pin, guards them: a change here is a change of the seam, which rewrites these literals and adds a release-note fragment in the same commit. """ - for name, signature in { - "observe_members": ( - "(self, *, field: bool = True) -> " - "tuple[solprop.backends.protocol.Observation, ...]" - ), - "member_metadata": "(self) -> tuple[dict[str, object], ...]", - }.items(): - assert str(inspect.signature(getattr(BatchBackend, name))) == signature, name assert tuple(f.name for f in dataclasses.fields(StageTerms)) == STAGE_TERMS_FIELDS assert ( tuple(f.name for f in dataclasses.fields(StageScalars)) == STAGE_SCALARS_FIELDS @@ -1001,12 +992,11 @@ def test_the_bundles_a_compiled_backend_packs_are_frozen(): """Every ``HostDriver`` hook a NumPy reference backend overrides (SEP 47 phase 2). The reference's own driver is no compiled seam, but its backends are written against -these signatures: a change here changes what ``numpy_ref`` and its group override, -in the same commit.""" +these signatures: a change here changes what ``numpy_ref`` overrides, in the same +commit.""" HOST_ATTRIBUTES = ( "helpers", - "max_batch", "name", "propagator_default", "reads_transverse_edge", @@ -1017,8 +1007,7 @@ def test_the_bundles_a_compiled_backend_packs_are_frozen(): def test_the_host_hooks_the_reference_overrides_are_frozen(): overridden = { name - for backend in (NumpyRefBackend, NumpyBatchBackend) - for owner in backend.__mro__ + for owner in NumpyRefBackend.__mro__ if owner.__module__.startswith("solprop.backends.numpy_ref") for name in vars(owner) if hasattr(HostDriver, name) and not name.startswith("__") diff --git a/tests/backends/test_exponential_march.py b/tests/backends/test_exponential_march.py index fd278a27b..c21dbe800 100644 --- a/tests/backends/test_exponential_march.py +++ b/tests/backends/test_exponential_march.py @@ -28,7 +28,6 @@ from solprop.backends.exponential import refuse_formulation from solprop.backends.host.adams import HostAdamsMarch from solprop.backends.host.driver import HostDriver -from solprop.backends.host.group import HostGroup from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.multistep import ( compensation_tables, @@ -413,41 +412,6 @@ def problem_of(integrator): assert_within(second, first, replay_bound(matched.request, schedule.n_steps)) -@pytest.mark.parametrize("method", FORMULATIONS, ids=["interaction", "exponential"]) -def test_a_lockstep_batch_steps_each_member_with_its_own_history( - narrow_grid, soliton_problem, method -): - length = SOLITON_PERIOD / 8 - schedule = FixedSchedule.uniform(0.0, length, length / 11, save_planes=[length]) - - def problem_of(order): - return soliton_problem( - narrow_grid, - order, - save_planes=[length], - schedule=schedule, - dz_max=length / 11, - dz_init=length / 11, - integrator=fixed(method), - ) - - singles = [run(*problem_of(order), grid=narrow_grid)[0] for order in (1, 2)] - members = [] - for order in (1, 2): - problem, run_request = problem_of(order) - member = NumpyRefBackend(problem, run_request, grid=narrow_grid) - member.set_initial(problem.initial.field0, None) - members.append(member) - runner = HostGroup(members) - runner.propagate_to(length) - observed = runner.observe_members() - runner.close() - # A member and its single run: one fixed-order method on one schedule. - bound = replay_bound(problem_of(1).request, 11) - for observation, single in zip(observed, singles, strict=True): - assert_within(observation.require_field()[0, 0], single, bound) - - @pytest.mark.parametrize("method", FORMULATIONS, ids=["interaction", "exponential"]) def test_a_rejected_trial_is_charged_and_leaves_the_history( narrow_grid, soliton_problem, method @@ -544,23 +508,9 @@ def scheduled(soliton_problem, grid, method, schedule, length, **overrides): ) -def lockstep_of(problems, grid): - """Return a lockstep runner over fresh reference members of `problems`. - - Each is a translation: a problem and its run's request. - """ - members = [] - for problem, run_request in problems: - member = NumpyRefBackend(problem, run_request, grid=grid) - member.set_initial(problem.initial.field0, None) - members.append(member) - return HostGroup(members) - - @pytest.mark.parametrize("method", FORMULATIONS, ids=["interaction", "exponential"]) -@pytest.mark.parametrize("batch", [False, True], ids=["single", "lockstep"]) def test_a_replayed_schedule_stops_to_save_and_refuses_to_run_out( - narrow_grid, soliton_problem, method, batch + narrow_grid, soliton_problem, method ): length = SOLITON_PERIOD / 8 schedule = FixedSchedule.uniform(0.0, length, length / 9) @@ -569,15 +519,12 @@ def start(**overrides): problem, run_request = scheduled( soliton_problem, narrow_grid, fixed(method), schedule, length, **overrides ) - if batch: - return lockstep_of([(problem, run_request)], narrow_grid) backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) backend.set_initial(problem.initial.field0, None) return backend def field_of(runner): - observed = runner.observe_members()[0] if batch else runner.observe() - return observed.field[0, 0, 0] + return runner.observe().field[0, 0, 0] # Every third step's end is saved: each call stops there, and the steps, so the # field, are those of the uninterrupted replay. @@ -618,17 +565,6 @@ def test_a_replayed_step_with_a_non_finite_norm_is_refused( backend.close() -def test_lockstep_members_must_share_the_integrator(narrow_grid, soliton_problem): - length = SOLITON_PERIOD / 8 - schedule = FixedSchedule.uniform(0.0, length, length / 9) - problems = [ - scheduled(soliton_problem, narrow_grid, method, schedule, length) - for method in FORMULATIONS - ] - with pytest.raises(BackendError, match="same integrator"): - lockstep_of(problems, narrow_grid) - - DRIVERS = pytest.mark.parametrize("driver", [HostDriver], ids=["host"]) """The reference's driver, whose default hooks refuse what it lacks.""" diff --git a/tests/backends/test_far_field_statistics.py b/tests/backends/test_far_field_statistics.py index 4b3499434..e516b5eab 100644 --- a/tests/backends/test_far_field_statistics.py +++ b/tests/backends/test_far_field_statistics.py @@ -13,20 +13,17 @@ import dataclasses import importlib.util import math -from contextlib import ExitStack import numpy as np import pytest from scipy import integrate -from backends import test_batch_lockstep as lockstep from backends.planar_cases import planar_case from bounds import EPS, assert_within, gamma from legacy_geometry import bare_absorber from sessions.runs import launch_statistics from solprop.backends import registry, select from solprop.backends import spatial as backend_spatial -from solprop.backends.host.group import HostGroup from solprop.backends.registry import statistics_refusal from solprop.backends.session import Start from solprop.backends.spatial import ( @@ -824,31 +821,25 @@ def test_the_tables_are_formed_once_and_reused(grid): assert fresh is not None and fresh is not own assert np.array_equal(fresh.distances, [0.5]) assert held.for_spec(StatsSpec(names=("energy",))) is None - modal = lockstep.simulation(0, "numpy_ref") + modal = Simulation.from_gnlse( + 0.11, + 0.001, + [0.0, 0.0, -1.183e-26], + wavelength=835e-9, + wavelength_limits=(500e-9, 2e-6), + trange=1e-12, + width=100e-15, + peak_power=1.0, + shape="sech", + backend="numpy_ref", + absorber=False, + ) with pytest.raises(OutputError, match="without spatial geometry"): FarFieldTables( modal.translate(), modal._run_request().observation.stats ).for_spec(StatsSpec(names=("beam_spectrum",))) -@pytest.mark.parametrize("table", ["apertures", "regions"]) -def test_lockstep_members_must_carry_equal_tables(table): - with ExitStack() as cleanup: - first, second = [ - lockstep.loaded(lockstep.simulation(index, "numpy_ref"), cleanup) - for index in range(2) - ] - change = ( - {"apertures": HOLES} - if table == "apertures" - else {"spectral_regions": QUADRANTS} - ) - stats = dataclasses.replace(second._request.observation.stats, **change) - second._request = second._request.for_run(stats=stats) - with pytest.raises(BackendError, match="same statistics request"): - HostGroup([first, second]) - - def test_a_run_records_every_far_field_statistic_at_every_plane(grid): space = FreeGrid(3e-4, 16, 3e-4, 16, collar_fraction=0.1) simulation = free_simulation( diff --git a/tests/backends/test_free_noise.py b/tests/backends/test_free_noise.py index a32613822..ec08b3461 100644 --- a/tests/backends/test_free_noise.py +++ b/tests/backends/test_free_noise.py @@ -87,7 +87,11 @@ def test_cartesian_modified_noise_enters_the_rotated_nonlinear_field( backend, problem.initial.field0, noise_spectrum(noise, problem.shape) ) native_trial(backend, position, 0.0) - actual = state.stage_to_host(0).reshape(expected.shape) + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + + actual = _testing.stage_to_host(state, 0).reshape(expected.shape) else: captured = [] nonlinear = backend._nonlinear diff --git a/tests/backends/test_host_ledgers.py b/tests/backends/test_host_ledgers.py index 9cd99071d..5455823a7 100644 --- a/tests/backends/test_host_ledgers.py +++ b/tests/backends/test_host_ledgers.py @@ -6,8 +6,8 @@ :meth:`solprop.backends.host.driver.HostDriver.restore_call_ledgers` restores the logical Adams counts every host driver keeps. Only the reference backend's TDSE binding -keeps atomic counts; any other host driver -- a lockstep group, or a stand-in -- is -refused them by name rather than silently dropping a budget a resume must honour. +keeps atomic counts; any other host driver, such as a stand-in, is refused them by name +rather than silently dropping a budget a resume must honour. """ import pytest diff --git a/tests/backends/test_low_storage.py b/tests/backends/test_low_storage.py index dba014e0a..b55975add 100644 --- a/tests/backends/test_low_storage.py +++ b/tests/backends/test_low_storage.py @@ -631,59 +631,6 @@ def test_planes_at_natural_steps_match_the_uninterrupted_run( ) -def test_a_lockstep_batch_matches_its_members_run_alone( - lifecycle, narrow_grid, scales, caplog -): - """Each member owns its march (section 6.5); the batch is its solo runs. - - The runner holds no march of its own, and its closing debug line still says the - run has no estimate rather than printing the members' 0.0 as a ratio. - """ - from solprop.backends.registry import select_batch # noqa: PLC0415 - - problem, run_request, length = lifecycle() - members, alone = [], [] - for factor in (1.0, 1.1): - member = dataclasses.replace( - problem, - initial=dataclasses.replace( - problem.initial, field0=problem.initial.field0 * factor - ), - ) - final, backend = run(member, run_request, narrow_grid) - backend.close() - alone.append(final) - loaded = NumpyRefBackend(member, run_request, grid=narrow_grid) - loaded.set_initial(member.initial.field0, None) - members.append(loaded) - runner = select_batch(members) - try: - with caplog.at_level(logging.DEBUG, logger=type(runner).__module__): - for plane in run_request.stepper.save_planes: - runner.propagate_to(float(plane)) - observed = runner.observe_members() - metadata = runner.member_metadata() - finally: - runner.close() - bound = rounding_bound(problem, run_request.stepper.schedule, scales) - for observation, expected, record in zip(observed, alone, metadata, strict=True): - assert observation.z == length - assert observation.step_history.n_steps == LIFECYCLE_STEPS - assert np.all(observation.step_history.error_norm == 0.0) - assert np.linalg.norm(observation.field - expected) <= bound * np.linalg.norm( - expected - ) - assert record["source_evaluations"] == 4 * LIFECYCLE_STEPS - ratios = [ - record.getMessage() - for record in caplog.records - if record.name == type(runner).__module__ - and "tolerance ratio" in record.getMessage() - ] - assert len(ratios) == len(run_request.stepper.save_planes) - assert all(line.endswith("not estimated (replayed schedule)") for line in ratios) - - @pytest.mark.parametrize("edge", ["plane", "mid-segment"]) def test_a_resume_at_an_edge_agrees_to_rounding(lifecycle, narrow_grid, scales, edge): """A resume rebuilds the flow table from its own first step (section 4.3). @@ -999,34 +946,6 @@ def test_an_abandoned_step_leaves_every_reader_refusing(lifecycle, narrow_grid, ) -def test_a_lockstep_member_left_in_flight_refuses_the_next_step(lifecycle, narrow_grid): - from solprop.backends.registry import select_batch # noqa: PLC0415 - - problem, run_request, length = lifecycle() - members = [] - for _ in range(2): - member = NumpyRefBackend(problem, run_request, grid=narrow_grid) - member.set_initial(problem.initial.field0, None) - members.append(member) - runner = select_batch(members) - abandon_after(members[1], 1) - with pytest.raises(AbandonedError): - runner.propagate_to(length / 2) - # Member 0 committed the shared step before member 1 was abandoned; the next call - # must refuse before stepping it again from there. - position, state = members[0]._z, members[0]._state.copy() - with pytest.raises(BackendError, match="abandoned in flight"): - runner.propagate_to(length / 2) - assert members[0]._z == position - assert np.array_equal(members[0]._state, state) - assert members[0].metadata()["source_evaluations"] == 4 - with pytest.raises(BackendError, match="abandoned in flight"): - runner.observe_members() - with pytest.raises(BackendError, match="abandoned in flight"): - runner.stats(StatsSpec(names=("energy",))) - runner.close() - - def test_a_diverged_state_stops_the_replay_in_flight(lifecycle, narrow_grid): """No estimate to watch: the accepted state's norm is the divergence check.""" problem, run_request, length = lifecycle() diff --git a/tests/backends/test_monitor_owner.py b/tests/backends/test_monitor_owner.py index 034a0fff6..457fd5bf3 100644 --- a/tests/backends/test_monitor_owner.py +++ b/tests/backends/test_monitor_owner.py @@ -5,11 +5,11 @@ """The native session's own boundary monitor against solprop's, on recorded readings. SEP 47 sections 4.3 and 6.4: the native session owns the boundary monitor -(``solprop_native._core.Monitor``, ``watch::Monitor``), and this harness replaces -``_verify_watch_of``'s runtime replay. Both monitors are fed the same recorded readings --- the launch, checked and skipped steps, saved planes, a resting collar, a resume -- -and must make exactly the same decisions: the cadence (``due``), each verdict, its -warning or stop and the amplitude its message names, the quiet collar and the split +(``watch::Monitor``, bound as the private test module's ``Monitor``), and this harness +replaces ``_verify_watch_of``'s runtime replay. Both monitors are fed the same recorded +readings -- the launch, checked and skipped steps, saved planes, a resting collar, a +resume -- and must make exactly the same decisions: the cadence (``due``), each verdict, +its warning or stop and the amplitude its message names, the quiet collar and the split collar's cap, so the proposals that follow are the same. Their records must agree too: exactly where the arithmetic is the same scalar sequence, and within a bound derived below where a reading's reduction is summed in another order. @@ -53,7 +53,7 @@ def _modules() -> tuple[Any, Any]: return ( - importlib.import_module("solprop_native._core"), + importlib.import_module("solprop_native._core")._testing, importlib.import_module("solprop_native._watch"), ) diff --git a/tests/backends/test_monitor_reduction.py b/tests/backends/test_monitor_reduction.py index 9ec3fd9b7..5a139323b 100644 --- a/tests/backends/test_monitor_reduction.py +++ b/tests/backends/test_monitor_reduction.py @@ -311,9 +311,13 @@ def test_a_reading_needs_a_monitor(backend: str) -> None: driver._boundary_energies(driver._require_state()) else: # The native state's own reduction, which its session reads at a check. - load_native(made, problem.initial.field0) + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + + state = load_native(made, problem.initial.field0) with pytest.raises(RuntimeError, match="no boundary monitor is bound"): - cast("Any", made)._native_state.monitor_reading() + _testing.monitor_reading(state) finally: made.close() diff --git a/tests/backends/test_monitor_watch.py b/tests/backends/test_monitor_watch.py index 23a9cea75..e9c5f8a1d 100644 --- a/tests/backends/test_monitor_watch.py +++ b/tests/backends/test_monitor_watch.py @@ -8,8 +8,9 @@ :class:`~solprop.monitor.BoundaryMonitor` will make of the reading: the split collar's new cap, the cadence, the quiet collar's verdict, a first warning or a stop. These tests hand the same readings to a real monitor and to the native predictions -(``solprop_native._core.watch_check``) and require the same verdict and the same state, -field by field, on drawn readings around every threshold and on the review's witnesses. +(``watch_check`` of ``solprop_native._core._testing``) and require the same verdict and +the same state, field by field, on drawn readings around every threshold and on the +review's witnesses. """ from __future__ import annotations @@ -37,8 +38,8 @@ STOP, WARN, QUIET, ERROR = 1, 2, 3, 5 -def _core() -> Any: - return importlib.import_module("solprop_native._core") +def _testing() -> Any: + return importlib.import_module("solprop_native._core")._testing def _monitor(*, split: bool, quiet: bool, budget: float = 1e-3) -> BoundaryMonitor: @@ -102,7 +103,7 @@ def _python(monitor: BoundaryMonitor, energies: BoundaryEnergies, z: float) -> i def _agree(monitor: BoundaryMonitor, energies: BoundaryEnergies, z: float) -> int: """Check one reading on both, require the same verdict and state; return it.""" - core = _core() + core = _testing() policy = monitor.watch_policy() before = monitor.watch_state() assert core.watch_due(policy, before, z) == monitor.due(z) @@ -210,4 +211,4 @@ def test_the_split_limit_is_the_crossing_s(): occupancy[0] = float.fromhex("0x1.0c6f8ba2f9813p-20") occupancy[1] = 1.0 for case in (occupancy, np.zeros(SPLIT_RATE_BUCKETS), np.ones(SPLIT_RATE_BUCKETS)): - assert _core().watch_split_limit(policy, case) == crossing.limit(case) + assert _testing().watch_split_limit(policy, case) == crossing.limit(case) diff --git a/tests/backends/test_native_dispersive_kerr.py b/tests/backends/test_native_dispersive_kerr.py index 63ceff8cb..985a7d0dc 100644 --- a/tests/backends/test_native_dispersive_kerr.py +++ b/tests/backends/test_native_dispersive_kerr.py @@ -58,6 +58,7 @@ from solprop.translate.stage import scalars solprop_native = pytest.importorskip("solprop_native") +_testing = pytest.importorskip("solprop_native._core")._testing NativeBackend = solprop_native.NativeBackend ON_DEVICE = solprop_native.build_info().device_backend != "none" @@ -131,11 +132,11 @@ def test_the_embedded_rule_is_finished_once_and_only_where_it_exists(evaluator): try: native_source(backend, case.problem.initial.field0) native = backend._native_state - fine = np.array(native.projected_to_host(False)) - landed = np.array(native.projected_to_host(True)) + fine = np.array(_testing.projected_to_host(native, False)) + landed = np.array(_testing.projected_to_host(native, True)) assert np.any(landed) - np.testing.assert_array_equal(native.projected_to_host(True), landed) - np.testing.assert_array_equal(native.projected_to_host(False), fine) + np.testing.assert_array_equal(_testing.projected_to_host(native, True), landed) + np.testing.assert_array_equal(_testing.projected_to_host(native, False), fine) finally: backend.close() radial_problem, radial_request, grid = radial(evaluator, envelope=False, thg=True) @@ -144,9 +145,9 @@ def test_the_embedded_rule_is_finished_once_and_only_where_it_exists(evaluator): try: native_source(backend, radial_problem.initial.field0) native = backend._native_state - before = np.array(native.projected_to_host(False)) + before = np.array(_testing.projected_to_host(native, False)) assert np.any(before) - np.testing.assert_array_equal(native.projected_to_host(False), before) + np.testing.assert_array_equal(_testing.projected_to_host(native, False), before) finally: backend.close() diff --git a/tests/backends/test_native_error_norm.py b/tests/backends/test_native_error_norm.py index 96f92ca9a..dd0737889 100644 --- a/tests/backends/test_native_error_norm.py +++ b/tests/backends/test_native_error_norm.py @@ -38,6 +38,7 @@ native = pytest.importorskip("solprop_native") core = pytest.importorskip("solprop_native._core") +_testing = pytest.importorskip("solprop_native._core")._testing STEP_RELATIVE = 16 * EPS """The one-step rung of ``accuracy.md`` section 7, relative to the state.""" @@ -87,7 +88,7 @@ def _operands(backend, reference, problem, run_request, dz): state = backend._native_state shape = (1, *problem.shape) stages = [ - np.asarray(state.stage_to_host(index)).reshape(shape) + np.asarray(_testing.stage_to_host(state, index)).reshape(shape) for index in range(len(tableau.nodes)) ] reference.set_initial(problem.initial.field0, None) @@ -219,7 +220,7 @@ def test_the_weighted_residual_divides_each_bin_before_the_norm( carried, rounding = _difference( stages, run_request.stepper.tableau.error_weights, propagator, dz ) - partials = backend._native_state.weighted_error(weights) + partials = _testing.weighted_error(backend._native_state, weights) got = math.sqrt(float(np.sum(partials))) finally: backend.close() @@ -298,13 +299,13 @@ def test_the_recycled_stage_is_the_one_it_replaces( native_trial(backend, z, dz) # Six evaluations: the first stage was not evaluated, it was recycled. assert state.rk_source_evaluations == before + 6 - recycled = np.asarray(state.stage_to_host(0)).copy() + recycled = np.asarray(_testing.stage_to_host(state, 0)).copy() # The same stage from scratch, at the same state and step. state.clear_fsal() before = state.rk_source_evaluations native_trial(backend, z, dz) assert state.rk_source_evaluations == before + 7 - fresh = np.asarray(state.stage_to_host(0)).copy() + fresh = np.asarray(_testing.stage_to_host(state, 0)).copy() gap = float(np.linalg.norm(recycled - fresh) / np.linalg.norm(fresh)) # The derivative's sensitivity to an elementwise relative perturbation of the # state, of the size and kind rounding makes: a measured conditioning estimate, @@ -316,7 +317,7 @@ def test_the_recycled_stage_is_the_one_it_replaces( field *= 1.0 + delta * np.exp(2j * np.pi * rng.random(field.shape)) load_native(backend, field, clear_fsal=False) native_trial(backend, z, dz) - moved = np.asarray(state.stage_to_host(0)) + moved = np.asarray(_testing.stage_to_host(state, 0)) sensitivity = float(np.linalg.norm(moved - fresh) / np.linalg.norm(fresh)) sensitivity /= delta finally: diff --git a/tests/backends/test_native_held_plasma.py b/tests/backends/test_native_held_plasma.py index 9c9779127..c7d633c31 100644 --- a/tests/backends/test_native_held_plasma.py +++ b/tests/backends/test_native_held_plasma.py @@ -25,6 +25,7 @@ from solprop.exceptions import BackendError native = pytest.importorskip("solprop_native") +_testing = pytest.importorskip("solprop_native._core")._testing pytestmark = [ pytest.mark.filterwarnings("ignore::solprop.exceptions.MaterialRangeWarning"), @@ -49,7 +50,7 @@ def test_the_held_current_lands_in_the_band_and_plans_once(name, rule): ledger = backend.memory_ledger() native_trial(backend, 0.0, 0.0, field=problem.initial.field0) native_trial(backend, 0.0, 0.0, field=np.zeros_like(problem.initial.field0)) - assert np.count_nonzero(backend._native_state.stage_to_host(0)) == 0 + assert np.count_nonzero(_testing.stage_to_host(backend._native_state, 0)) == 0 # A second evaluation neither plans nor grows a resident source buffer. assert backend.memory_ledger() == ledger finally: diff --git a/tests/backends/test_native_held_projection_budget.py b/tests/backends/test_native_held_projection_budget.py index 1528719b4..2f98961e8 100644 --- a/tests/backends/test_native_held_projection_budget.py +++ b/tests/backends/test_native_held_projection_budget.py @@ -37,6 +37,7 @@ from solprop.translate.plasma_integration import design_running_integral native = pytest.importorskip("solprop_native") +_testing = pytest.importorskip("solprop_native._core")._testing pytestmark = [ pytest.mark.filterwarnings("ignore::solprop.exceptions.MaterialRangeWarning"), @@ -145,7 +146,7 @@ def test_embedded_current_projection_accumulates_partial_chunks( backend = native.NativeBackend(problem, run_request, grid=grid, options=options) try: native_trial(backend, 0.0, 0.0, field=state) - raw = np.asarray(backend._native_state.projected_to_host(True)) + raw = np.asarray(_testing.projected_to_host(backend._native_state, True)) finally: backend.close() actual = raw.reshape(*expected.shape[:-1], grids.n_to // 2 + 1)[ diff --git a/tests/backends/test_native_march_traces.py b/tests/backends/test_native_march_traces.py index de32a3ac6..c96884622 100644 --- a/tests/backends/test_native_march_traces.py +++ b/tests/backends/test_native_march_traces.py @@ -5,10 +5,10 @@ """The native Adams march against the Python march's decision traces (SEP 39 7.1). The corpus of ``tests/data/adams_traces.json.gz`` was taken from the Python march before -SEP 39 refactored it. Here the same scenarios run through the native Adams record -driven a call at a time (``native_trace_marches.TraceAdamsMarch``) with the native -march's loop and decisions, its field arithmetic replaced by the script of norms -(``_core.ScriptedMarch``). Each call is bound to one attempt, so the state the adapter +SEP 39 refactored it. Here the same scenarios run through the native Adams record driven +a call at a time (``native_trace_marches.TraceAdamsMarch``) with the native march's loop +and decisions, its field arithmetic replaced by the script of norms (the private test +module's ``ScriptedMarch``). Each call is bound to one attempt, so the state the adapter adopts after each call is the state after that attempt, and every stencil, decision, proposal, order, landing, restart and ledger counter is compared exactly with the reference's. A second pass lets the calls run to their events with the production bound @@ -42,7 +42,7 @@ ) native = pytest.importorskip("solprop_native") -_core = pytest.importorskip("solprop_native._core") +_testing = pytest.importorskip("solprop_native._core")._testing from tests.backends.native_trace_marches import TraceAdamsMarch # noqa: E402 @@ -108,7 +108,7 @@ def run(self, state: dict[str, Any], bounds: dict[str, Any]) -> dict[str, Any]: replayed = FixedSchedule(np.array(schedule, dtype=np.float64)) steps = np.ascontiguousarray(replayed.steps, dtype=np.float64) edges = np.ascontiguousarray(replayed.edges, dtype=np.float64) - self.scripted = _core.ScriptedMarch( + self.scripted = _testing.ScriptedMarch( policy, self.norms, harness.scenario.carrier_rate or 0.0, steps, edges ) bounds = {**bounds, "max_attempts": harness.max_attempts} diff --git a/tests/backends/test_native_phi_moments.py b/tests/backends/test_native_phi_moments.py index 6a6d50d71..26f112794 100644 --- a/tests/backends/test_native_phi_moments.py +++ b/tests/backends/test_native_phi_moments.py @@ -33,6 +33,7 @@ natural_scale, ) from bounds import EPS +from sessions.runs import native_stage_rows from solprop.backends.exponential import MAX_PHI_ORDER from solprop.grid import EnvelopeGrid from solprop.nonlinear.gnlse import problem_from @@ -41,6 +42,7 @@ from solprop.translate.assembly import assemble native = pytest.importorskip("solprop_native") +_testing = pytest.importorskip("solprop_native._core")._testing VALUES = np.array([*ARGUMENTS, *SQUARING_EDGES]) """The arguments of ``test_exponential_weights.py``'s own kernel test.""" @@ -94,7 +96,7 @@ def read_moments(module, grid, values): payload = backend_module._lower( problem, run_request, backend_module._LowerPlan(terms=backend._terms) ) - arrays, material = backend._resident_arrays(0.0, 1e-3) + arrays, material = native_stage_rows(backend, 0.0, 1e-3) finally: backend.close() terms = np.zeros_like(payload.linear.phi_terms).reshape( @@ -123,7 +125,8 @@ def read_moments(module, grid, values): state.adams_rows_from_host("store", store) corrector = np.zeros((width, width)) corrector[1, k] = 1.0 - state.adams_exponential_trial( + _testing.adams_exponential_trial( + state, 1.0, np.arange(width - 1, dtype=np.uint64), np.zeros(1), @@ -143,8 +146,8 @@ def read_moments(module, grid, values): empty, empty, ) - state.adams_exponential_accept( - 1.0, width - 1, np.empty(0, dtype=np.uint64), False + _testing.adams_exponential_accept( + state, 1.0, width - 1, np.empty(0, dtype=np.uint64), False ) out[:, k] = np.asarray(state.field_to_host()).reshape(-1)[bins] finally: diff --git a/tests/backends/test_native_planar_statistics.py b/tests/backends/test_native_planar_statistics.py index a5d09158c..eb684c50a 100644 --- a/tests/backends/test_native_planar_statistics.py +++ b/tests/backends/test_native_planar_statistics.py @@ -42,6 +42,7 @@ ] solprop_native = pytest.importorskip("solprop_native") +_testing = pytest.importorskip("solprop_native._core")._testing NativeBackend = solprop_native.NativeBackend EPS = float(np.finfo(float).eps) @@ -173,7 +174,7 @@ def finished(problem, run_request, grid, rows, dz, options=None): backend = NativeBackend(problem, run_request, grid=grid, options=options) try: native = load_native(backend, problem.initial.field0, clear_fsal=False) - native.adopt(np.ascontiguousarray(rows.reshape(-1)), dz) + _testing.adopt(native, np.ascontiguousarray(rows.reshape(-1)), dz) actual = native.field_to_host().reshape(problem.shape) finally: backend.close() diff --git a/tests/backends/test_native_rk_rows.py b/tests/backends/test_native_rk_rows.py index df108580c..38c320e2b 100644 --- a/tests/backends/test_native_rk_rows.py +++ b/tests/backends/test_native_rk_rows.py @@ -40,6 +40,7 @@ native = pytest.importorskip("solprop_native") backend_module = pytest.importorskip("solprop_native.backend") core = pytest.importorskip("solprop_native._core") +_testing = pytest.importorskip("solprop_native._core")._testing ROWS = ( "gnlse", @@ -134,7 +135,9 @@ def test_the_native_flow_guards_refuse_as_the_host_s(route, monkeypatch): allowance = backend_module._flow_allowance(modes) section = int(scalars(problem, z, z + dz, helpers=backend.helpers).flow_section) fractions = np.array([*nodes, 1.0]) - measured = np.asarray(state.form_flow_actions(section, dz, fractions))[0] + measured = np.asarray( + _testing.form_flow_actions(state, section, dz, fractions) + )[0] if measured.size: halved = dataclasses.replace(flow, condition_bound=flow.condition_bound / 2) expected = _refusal( @@ -215,8 +218,9 @@ def _first_attempt(route: str, controller: PIController): old = math.sqrt(float(partials[0].sum())) new = math.sqrt(float(partials[1].sum())) weighted = np.asarray( - backend._native_state.weighted_error( - np.ascontiguousarray(controller.scale(old, new), dtype=np.float64) + _testing.weighted_error( + backend._native_state, + np.ascontiguousarray(controller.scale(old, new), dtype=np.float64), ) ) finally: diff --git a/tests/backends/test_native_rk_traces.py b/tests/backends/test_native_rk_traces.py index aa4ec28f8..6249b688d 100644 --- a/tests/backends/test_native_rk_traces.py +++ b/tests/backends/test_native_rk_traces.py @@ -36,7 +36,7 @@ "native" not in available(), reason="native is not installed" ) backend_module = pytest.importorskip("solprop_native.backend") -core = pytest.importorskip("solprop_native._core") +_testing = pytest.importorskip("solprop_native._core")._testing CORPUS = Path(__file__).parents[1] / "data" / "rk_traces.json.gz" @@ -122,7 +122,7 @@ def run_native(scenario: Scenario, max_attempts: int) -> dict[str, Any]: if schedule is not None: steps = np.ascontiguousarray(schedule.steps, dtype=np.float64) edges = np.ascontiguousarray(schedule.edges, dtype=np.float64) - runner = core.ScriptedRkMarch(policy, norms, scenario.h0 or 0.0, steps, edges) + runner = _testing.ScriptedRkMarch(policy, norms, scenario.h0 or 0.0, steps, edges) harness = _NativeHarness(scenario, runner) march = TraceRungeKuttaMarch(harness, runner=runner) march.MAX_ATTEMPTS = max_attempts diff --git a/tests/backends/test_native_stage_tables.py b/tests/backends/test_native_stage_tables.py index 0bbb757fc..5e6873d32 100644 --- a/tests/backends/test_native_stage_tables.py +++ b/tests/backends/test_native_stage_tables.py @@ -6,11 +6,11 @@ Where a resident trial's stage rows are one bundle repeated, the native state reads the scalar tables itself, uploaded once per run, and forms the trial's coefficient tables -and rate from its nodes (``_ResidentAdams.staged``), in either formulation. It performs -the reads of ``translate.stage.scalars`` by the same Clenshaw helper, in the same order, -so its scalars are solprop's exactly. The host-packed march these tables were measured -against bit for bit (SEP 39 section 4.9) was deleted with the inherited driver's -fallbacks in SEP 47's phase 5: every route the backend admits is staged. +and rate from its nodes (``engines::ResidentEngine``), in either formulation. It +performs the reads of ``translate.stage.scalars`` by the same Clenshaw helper, in the +same order, so its scalars are solprop's exactly. The host-packed march these tables +were measured against bit for bit (SEP 39 section 4.9) was deleted with the inherited +driver's fallbacks in SEP 47's phase 5: every route the backend admits is staged. """ import dataclasses @@ -21,6 +21,7 @@ import pytest from capability_routes import ROUTES +from sessions.runs import native_stage_rows from solprop.backends import available from solprop.stepper.multistep import Multistep from solprop.translate.linop import rate_weights @@ -33,6 +34,7 @@ native = pytest.importorskip("solprop_native") NativeBackend = native.NativeBackend NATIVE = pytest.importorskip("solprop_native._helpers").NATIVE +_testing = pytest.importorskip("solprop_native._core")._testing STAGED = ( "gnlse", @@ -89,7 +91,7 @@ def test_every_route_is_staged(route): backend = backend_of(simulation, problem, run_request) try: assert backend._adams is not None - assert backend._native_state.has_stage_tables() + assert _testing.has_stage_tables(backend._native_state) finally: backend.close() @@ -103,7 +105,7 @@ def test_the_native_stage_scalars_are_solprop_s_bundle(route): stages = run_request.stepper.tableau.n_stages for z0, z1 in positions(problem, run_request): backend._hoist(z0) - arrays, material = backend._resident_arrays(z0, z1) + arrays, material = native_stage_rows(backend, z0, z1) expected = dict( zip( ( @@ -130,7 +132,7 @@ def test_the_native_stage_scalars_are_solprop_s_bundle(route): "flow_weights": material.get("flow_weights", np.empty(0)), "transform_weights": material.get("transform_weights", np.empty(0)), } - found = state.adams_stage_scalars(z0, z1) + found = _testing.adams_stage_scalars(state, z0, z1) for name, values in expected.items(): flat = np.asarray(values, dtype=np.float64).reshape(-1) assert np.array_equal(np.asarray(found[name]), flat), (name, z0, z1) @@ -151,7 +153,7 @@ def test_the_native_rate_is_read_on_the_closing_side(): probes = [*edges, *np.linspace(edges[0], edges[-1], 11)] for z in probes: expected = rate_weights(linear, z, before=True, helpers=NATIVE) - found = backend._native_state.adams_stage_rate(float(z)) + found = _testing.adams_stage_rate(backend._native_state, float(z)) assert np.array_equal(np.asarray(found), expected), z finally: backend.close() diff --git a/tests/backends/test_native_stash_and_saving.py b/tests/backends/test_native_stash_and_saving.py index b3487fcb2..611840b76 100644 --- a/tests/backends/test_native_stash_and_saving.py +++ b/tests/backends/test_native_stash_and_saving.py @@ -65,6 +65,7 @@ ] solprop_native = pytest.importorskip("solprop_native") +_testing = pytest.importorskip("solprop_native._core")._testing NativeBackend = solprop_native.NativeBackend NAMES = ("electron_density", "peak_ionisation_rate") @@ -195,7 +196,7 @@ def step_by_step(backend, problem, run_request, *, recycle): state.rk_trial(float(z), dz, nodes, prepare_only=False) state.finish(dz) if recycle: - state.promote_fsal() + _testing.promote_fsal(state) else: state.clear_fsal() field = np.asarray(state.field_to_host()).reshape(problem.shape).copy() diff --git a/tests/backends/test_native_strict_witness.py b/tests/backends/test_native_strict_witness.py index bc8d3af4d..0b4ca65ab 100644 --- a/tests/backends/test_native_strict_witness.py +++ b/tests/backends/test_native_strict_witness.py @@ -38,7 +38,7 @@ def test_the_strict_files_round_every_operation_where_the_build_fuses(): - control, *probes = native._core.strict_witness( # pyright: ignore[reportPrivateUsage] + control, *probes = native._core._testing.strict_witness( # pyright: ignore[reportPrivateUsage] FACTOR_A, FACTOR_B, ADDEND ) assert probes == [0.0] * 9, "a strict file's product and sum were fused" diff --git a/tests/backends/test_native_vector_math.py b/tests/backends/test_native_vector_math.py index 8e1d8d8af..f89f0feb9 100644 --- a/tests/backends/test_native_vector_math.py +++ b/tests/backends/test_native_vector_math.py @@ -29,7 +29,7 @@ import pytest native = pytest.importorskip("solprop_native") -core = native._core # pyright: ignore[reportPrivateUsage] - the layer's test bindings +core = native._core._testing # pyright: ignore[reportPrivateUsage] - the layer's test bindings EPS = np.finfo(np.float64).eps TINY = np.finfo(np.float64).smallest_subnormal diff --git a/tests/backends/test_native_widths.py b/tests/backends/test_native_widths.py index 92921f94f..45b974edb 100644 --- a/tests/backends/test_native_widths.py +++ b/tests/backends/test_native_widths.py @@ -274,6 +274,10 @@ def _field_for(route, grid, problem): def _check_fluence(monkeypatch, route, kind): + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + grid, problem, run_request = _route(route, kind) field = _field_for(route, grid, problem) held = {} @@ -289,7 +293,7 @@ def capture(geometry, fluence, budget, axis): backend = select("native", problem, run_request, grid=grid) try: state = load_native(backend, field, clear_fsal=False) - packed = np.ravel(state.spatial_statistics(16, 0.5 * EPS0 * C, 0.0)) + packed = np.ravel(_testing.spatial_statistics(state, 16, 0.5 * EPS0 * C, 0.0)) finally: backend.close() n_nodes = problem.transform.n_nodes @@ -338,13 +342,17 @@ def test_a_plane_s_moments_bound_the_refusal_as_its_fluence_does(route, kind): # What a plane's refusal scales by is in its moments, and its width comes out the # same whatever that is unless a negative lobe is near it: flag 16's value is held # to the reference's, so flag 32's is held to that. + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + grid, problem, run_request = _route(route, kind) field = _field_for(route, grid, problem) backend = select("native", problem, run_request, grid=grid) try: state = load_native(backend, field, clear_fsal=False) - fluence = np.ravel(state.spatial_statistics(16, 0.5 * EPS0 * C, 0.0)) - moments = np.ravel(state.spatial_statistics(32, 0.5 * EPS0 * C, 0.0)) + fluence = np.ravel(_testing.spatial_statistics(state, 16, 0.5 * EPS0 * C, 0.0)) + moments = np.ravel(_testing.spatial_statistics(state, 32, 0.5 * EPS0 * C, 0.0)) finally: backend.close() n_nodes = problem.transform.n_nodes @@ -507,6 +515,10 @@ def test_a_negative_lobe_is_refused_on_both(): @native_only def test_the_native_trace_needs_a_held_plane_and_real_rings(): + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + grid, problem, run_request = _route("plane") backend = select("native", problem, run_request, grid=grid) no_rings = np.empty(0) @@ -514,20 +526,20 @@ def test_the_native_trace_needs_a_held_plane_and_real_rings(): try: state = load_native(backend, problem.initial.field0, clear_fsal=False) with pytest.raises(RuntimeError, match="follows the call that holds it"): - state.plane_fluence_trace( - 0.0, 0.0, 1.0, 1.0, 1.0, 1.0, 0, no_rings, no_rings + _testing.plane_fluence_trace( + state, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0, 0, no_rings, no_rings ) with pytest.raises(ValueError, match="invalid spatial statistic flags"): - state.spatial_statistics(64, factor, 0.0) - np.ravel(state.spatial_statistics(32, factor, 0.0)) + _testing.spatial_statistics(state, 64, factor, 0.0) + np.ravel(_testing.spatial_statistics(state, 32, factor, 0.0)) with pytest.raises(ValueError, match="invalid fluence rings"): - state.plane_fluence_trace( - 0.0, 0.0, 0.0, 1.0, 1.0, 1.0, 0, no_rings, no_rings + _testing.plane_fluence_trace( + state, 0.0, 0.0, 0.0, 1.0, 1.0, 1.0, 0, no_rings, no_rings ) - np.ravel(state.spatial_statistics(32, factor, 0.0)) + np.ravel(_testing.spatial_statistics(state, 32, factor, 0.0)) with pytest.raises(ValueError, match="one-dimensional"): - state.plane_fluence_trace( - 0.0, 0.0, 1.0, 1.0, 1.0, 1.0, 1, np.ones((1, 8)), np.ones((1, 8)) + _testing.plane_fluence_trace( + state, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0, 1, np.ones((1, 8)), np.ones((1, 8)) ) finally: backend.close() @@ -535,12 +547,16 @@ def test_the_native_trace_needs_a_held_plane_and_real_rings(): @native_only def test_a_line_has_no_plane_moments(): + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + grid, problem, run_request = _route("line") backend = select("native", problem, run_request, grid=grid) try: state = load_native(backend, problem.initial.field0, clear_fsal=False) with pytest.raises(ValueError, match="need a Cartesian plane"): - state.spatial_statistics(32, 0.5 * EPS0 * C, 0.0) + _testing.spatial_statistics(state, 32, 0.5 * EPS0 * C, 0.0) finally: backend.close() @@ -722,8 +738,8 @@ def _profiles(rng): def test_the_native_radial_widths_are_solprop_s_to_the_bit(): """The radial widths ported operation for operation: NumPy's pairwise sums, the crossings' interpolation, the hollow and the uncrossed profiles.""" - from solprop_native import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] - _core, + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, ) from solprop.spatial import radial_fluence_widths # noqa: PLC0415 @@ -735,14 +751,14 @@ def test_the_native_radial_widths_are_solprop_s_to_the_bit(): for fluence, axis in cases: arguments = (radius[:size], fluence[:size], weights[:size], axis) want = radial_fluence_widths(*arguments) - got = _core.radial_fluence_widths(*arguments, math.exp(-2)) + got = _testing.radial_fluence_widths(*arguments, math.exp(-2)) np.testing.assert_array_equal(got, want, err_msg=f"{size} samples") @native_only def test_the_native_radial_widths_refuse_what_solprop_s_refuse(): - from solprop_native import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] - _core, + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, ) from solprop.spatial import radial_fluence_widths # noqa: PLC0415 @@ -758,13 +774,15 @@ def test_the_native_radial_widths_refuse_what_solprop_s_refuse(): with pytest.raises(GridError, match="radial fluence widths require") as want: radial_fluence_widths(radius, fluence, weights, axis) with pytest.raises(ValueError, match="radial fluence widths require") as got: - _core.radial_fluence_widths(radius, fluence, weights, axis, math.exp(-2)) + _testing.radial_fluence_widths(radius, fluence, weights, axis, math.exp(-2)) assert str(got.value) == str(want.value) huge = np.full(3, 1e300) with pytest.raises(GridError, match="not representable"): radial_fluence_widths(radius * 1e200, huge, weights, 1e300) with pytest.raises(ValueError, match="not representable"): - _core.radial_fluence_widths(radius * 1e200, huge, weights, 1e300, math.exp(-2)) + _testing.radial_fluence_widths( + radius * 1e200, huge, weights, 1e300, math.exp(-2) + ) X86_64 = platform.machine().lower() in {"x86_64", "amd64"} @@ -814,8 +832,8 @@ def test_the_unfused_interp_is_numpy_s_on_x86_64(): def test_the_native_line_widths_are_solprop_s_to_the_bit(monkeypatch): """A line's centroid, moment and two-sided average, ``numpy.interp`` included: to the bit on x86-64, and to the unfused rule wherever NumPy's own may fuse.""" - from solprop_native import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] - _core, + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, ) from solprop.spatial import _line_fluence_widths # noqa: PLC0415 @@ -836,12 +854,12 @@ def test_the_native_line_widths_are_solprop_s_to_the_bit(monkeypatch): samples = np.exp(-2 * ((x - centre) / waist) ** 2) samples = samples / np.max(samples) want = _line_fluence_widths(x, samples) - got = _core.line_fluence_widths(x, samples, math.exp(-2)) + got = _testing.line_fluence_widths(x, samples, math.exp(-2)) np.testing.assert_array_equal(got, want, err_msg=f"{n} {centre} {waist}") noisy = rng.uniform(0.0, 1.0, n) noisy = noisy / np.max(noisy) np.testing.assert_array_equal( - _core.line_fluence_widths(x, noisy, math.exp(-2)), + _testing.line_fluence_widths(x, noisy, math.exp(-2)), _line_fluence_widths(x, noisy), ) @@ -876,9 +894,11 @@ def test_a_profile_s_native_widths_refuse_as_the_host_s_do(monkeypatch, route): for a value that is not finite, each through ``translated`` as the plan raises it.""" from solprop_native import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] - _core, _statistics, ) + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) host_interp(monkeypatch) grid, problem, run_request = _radial_route() if route == "radial" else _route(route) @@ -908,12 +928,12 @@ def both(profile): want = host_spatial.signed_fluence_widths(geometry, profile, budget, axis) except (BackendError, GridError) as error: with pytest.raises(ValueError) as caught: - _core.fluence_block_widths(plan, block) + _testing.fluence_block_widths(plan, block) raised = _statistics.translated(caught.value) assert type(raised) is type(error) assert str(raised) == str(error) return type(error) - np.testing.assert_array_equal(_core.fluence_block_widths(plan, block), want) + np.testing.assert_array_equal(_testing.fluence_block_widths(plan, block), want) return None assert both(fluence) is None diff --git a/tests/backends/test_native_z_table.py b/tests/backends/test_native_z_table.py index ef542d706..90783055d 100644 --- a/tests/backends/test_native_z_table.py +++ b/tests/backends/test_native_z_table.py @@ -24,11 +24,13 @@ from backends.session_rows import Z_TABLE_LENGTH as LENGTH from bounds import EPS from march_bounds import FIXED_ORDER +from sessions.runs import native_rate_weights from solprop.exceptions import BackendError from solprop.translate.linop import phi_rate native = pytest.importorskip("solprop_native") backend_module = pytest.importorskip("solprop_native.backend") +_testing = pytest.importorskip("solprop_native._core")._testing NativeBackend = native.NativeBackend @@ -88,7 +90,7 @@ def test_the_phase_sum_of_two_slots_is_the_tables_difference(tabulated, field_gr slot_of = tables.load([z0, z1]) row = tables.phi_row(slot_of, z0, z1) assert sorted(row[row != 0].tolist()) == [-1.0, 1.0] - got = native_state.phase_sum_to_host(row).reshape(phi.value_shape) + got = _testing.phase_sum_to_host(native_state, row).reshape(phi.value_shape) want = phi(z1) - phi(z0) # Two evaluations on each side, each within its budget, and one rounding of # the difference each. @@ -100,7 +102,9 @@ def test_the_phase_sum_of_two_slots_is_the_tables_difference(tabulated, field_gr bundle = backend._stage_scalars(z0, z1) assert np.array_equal(backend._delta_phi(bundle).reshape(got.shape), got) # A step of no length weighs both slots by zero: an exact zero, structural. - still = native_state.phase_sum_to_host(tables.phi_row(slot_of, z1, z1)) + still = _testing.phase_sum_to_host( + native_state, tables.phi_row(slot_of, z1, z1) + ) assert not np.any(still) finally: backend.close() @@ -116,7 +120,7 @@ def test_the_rate_slot_holds_the_derivative_table(tabulated, field_grid): rate = tabulated.problem.linear.rate edge = float(rate.breakpoints[1]) for z, before in ((edge, True), (edge, False), (0.5 * LENGTH, True)): - row = backend._rate_weights(z, before=before) + row = native_rate_weights(backend, z, before=before) assert row.tolist() == [0.0] * tables.slots + [1.0] got = backend._native_state.table_terms_to_host("phi", tables.rate_slot) want = phi_rate(tabulated.problem.linear, z, before=before) diff --git a/tests/backends/test_numpy_ref_backend.py b/tests/backends/test_numpy_ref_backend.py index 958c2754a..08b039942 100644 --- a/tests/backends/test_numpy_ref_backend.py +++ b/tests/backends/test_numpy_ref_backend.py @@ -162,7 +162,7 @@ def test_the_backend_satisfies_the_seam( problem, run_request = linear_problem(narrow_grid, save_planes=[LENGTH]) backend = backend_class(problem, run_request) assert isinstance(backend, Backend) - assert (backend.name, backend.max_batch) == (backend_name, 1) + assert backend.name == backend_name backend.close() diff --git a/tests/backends/test_numpy_ref_multimode.py b/tests/backends/test_numpy_ref_multimode.py index 1393bb153..893565534 100644 --- a/tests/backends/test_numpy_ref_multimode.py +++ b/tests/backends/test_numpy_ref_multimode.py @@ -133,7 +133,11 @@ def scored_alarm(backend): """ if backend.name == "numpy_ref": return backend._alarm - return backend._native_state.quadrature_error + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + + return _testing.quadrature_error(backend._native_state) ALARM = ("quadrature_error",) diff --git a/tests/backends/test_on_axis_statistics.py b/tests/backends/test_on_axis_statistics.py index 860090c0c..68cb92091 100644 --- a/tests/backends/test_on_axis_statistics.py +++ b/tests/backends/test_on_axis_statistics.py @@ -560,6 +560,10 @@ def test_the_native_axis_row_leaves_the_state_on_the_device(grid, table, radial_ def test_the_native_row_refuses_a_matrix_that_is_not_one_or_two_rows(grid, table): + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + pytest.importorskip("solprop_native") mode = argon() rule = transverse_quadrature([mode], n_r=5, radial_rule="field_scale") @@ -569,12 +573,12 @@ def test_the_native_row_refuses_a_matrix_that_is_not_one_or_two_rows(grid, table ) as backend: state = backend._native_state # pyright: ignore[reportAttributeAccessIssue] with pytest.raises(RuntimeError, match="no initial field"): - state.axis_spectrum(np.ones((1, 1))) + _testing.axis_spectrum(state, np.ones((1, 1))) load_native(backend, problem.initial.field0, clear_fsal=False) with pytest.raises(ValueError, match="at most two rows"): - state.axis_spectrum(np.ones((3, 1))) + _testing.axis_spectrum(state, np.ones((3, 1))) with pytest.raises(ValueError, match="two-dimensional"): - state.axis_spectrum(np.ones(1)) + _testing.axis_spectrum(state, np.ones(1)) def test_a_host_backend_s_axis_scan_needs_the_field(grid, table): diff --git a/tests/backends/test_optmat_cases.py b/tests/backends/test_optmat_cases.py index 0c66a3e2d..3082b3077 100644 --- a/tests/backends/test_optmat_cases.py +++ b/tests/backends/test_optmat_cases.py @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""What the optmat cases need beyond the parity ladder: a batch and native's ledger. +"""What the optmat cases need beyond the parity ladder: native's ledger. The ladder itself -- every case on native against ``numpy_ref``, rung by rung, with what each case carries -- is the catalogue's (``tests/backends/optmat_rows.py``). @@ -11,7 +11,6 @@ import numpy as np import pytest -from backends.test_batch_responses import compare from bounds import EPS, assert_within from builders import launch_derivative from optmat_parity_cases import build_case @@ -19,17 +18,6 @@ from solprop.backends.numpy_ref.passes import apply_hard_mask -@pytest.mark.medium -@pytest.mark.parametrize("name", ["n2_field", "ar_envelope"]) -def test_a_batch_equals_its_members(name): - # Within the rounding budget tests/backends/test_batch_responses.py holds its own - # cases to: a lockstep batch's members run the same arithmetic as independent - # runs. The reference's lockstep group: the native group runs each member as its - # own native session (SEP 47 phase 5), with no shared arithmetic to check. - case = build_case(name) - compare(case.problem, case.run_request, case.grid, "numpy_ref", options=None) - - @pytest.mark.medium def test_native_holds_every_row_of_the_composition_leaf(): # The rows are a view of n_terms x 2 n_to doubles and the per-stage decay rates diff --git a/tests/backends/test_polarised_runs.py b/tests/backends/test_polarised_runs.py index 823d33c4c..626eca5c9 100644 --- a/tests/backends/test_polarised_runs.py +++ b/tests/backends/test_polarised_runs.py @@ -160,7 +160,11 @@ def problem_derivative(backend_class, problem, run_request, grid, modes): # the native state's own trial (``rk_trial`` on the uploaded stage tables), # loaded with the launch. native_trial(backend, 0.0, LENGTH / 8, field=problem.initial.field0) - derivative = np.asarray(backend._native_state.stage_to_host(0)) + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + + derivative = np.asarray(_testing.stage_to_host(backend._native_state, 0)) return derivative.reshape(2, -1) finally: backend.close() diff --git a/tests/backends/test_radial_absorber.py b/tests/backends/test_radial_absorber.py index 1e58a0da9..d8f4d0040 100644 --- a/tests/backends/test_radial_absorber.py +++ b/tests/backends/test_radial_absorber.py @@ -126,9 +126,13 @@ def test_spatial_absorber_derivative_matches_independent_bessel_operator( # The native state's own trial (``rk_trial`` on the uploaded stage # tables), loaded with the launch: its first stage is N(E, z=0). native_trial(backend, 0.0, LENGTH / 8, field=problem.initial.field0) - measured = np.asarray(backend._native_state.stage_to_host(0)).reshape( - start.shape + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, ) + + measured = np.asarray( + _testing.stage_to_host(backend._native_state, 0) + ).reshape(start.shape) assert_allclose(measured[:, :, index], expected, rtol=0, atol=bound) record_metric( request, diff --git a/tests/backends/test_radial_nonlinear.py b/tests/backends/test_radial_nonlinear.py index 60d13cb2d..d477303b5 100644 --- a/tests/backends/test_radial_nonlinear.py +++ b/tests/backends/test_radial_nonlinear.py @@ -129,7 +129,13 @@ def _native_first_stage(backend, problem): uploaded stage tables), loaded with the launch, as the backend's march takes it. """ native_trial(backend, 0.0, 0.0, field=problem.initial.field0) - return np.asarray(backend._native_state.stage_to_host(0)).reshape(problem.shape) + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + + return np.asarray(_testing.stage_to_host(backend._native_state, 0)).reshape( + problem.shape + ) def test_radial_vector_raman_keeps_the_named_refusal(spatial_backend_class): diff --git a/tests/backends/test_reference_independence.py b/tests/backends/test_reference_independence.py index 3fbe7cde5..ace200218 100644 --- a/tests/backends/test_reference_independence.py +++ b/tests/backends/test_reference_independence.py @@ -5,9 +5,8 @@ """The NumPy reference runs on its own host machinery. SEP 47 section 6.6: the reference session is built independently of the native -backend. The reference's marches and its group are the host copies, and the run layer -serves a reference backend with the host session and a reference group with the host -group session. +backend. The reference's marches are the host copies, and the run layer serves a +reference backend with the host session. """ from contextlib import closing @@ -16,26 +15,20 @@ from solprop.backends.host.adams import HostAdamsMarch from solprop.backends.host.driver import HostDriver -from solprop.backends.host.group import HostGroup -from solprop.backends.host.group_session import HostGroupSession from solprop.backends.host.low_storage import HostLowStorageMarch from solprop.backends.host.session import HostSession from solprop.backends.numpy_ref import NumpyRefBackend -from solprop.backends.numpy_ref.batch import NumpyBatchBackend from solprop.backends.session import Start -from solprop.backends.sessions import start_group, start_session +from solprop.backends.sessions import start_session from solprop.exceptions import BackendError from solprop.stepper import FixedSchedule, LowStorageRungeKutta, Multistep -@pytest.mark.parametrize("backend", [NumpyRefBackend, NumpyBatchBackend]) -def test_a_reference_backend_inherits_the_host_driver(backend): - assert issubclass(backend, HostDriver) +def test_the_reference_backend_inherits_the_host_driver(): + assert issubclass(NumpyRefBackend, HostDriver) -def test_the_reference_marches_and_groups_with_the_host_copies( - soliton_problem, narrow_grid -): +def test_the_reference_marches_with_the_host_copies(soliton_problem, narrow_grid): length = 1e-3 schedule = FixedSchedule.uniform(0.0, length, length / 4, save_planes=[length]) marches = { @@ -56,18 +49,6 @@ def test_the_reference_marches_and_groups_with_the_host_copies( NumpyRefBackend(problem, run_request, grid=narrow_grid) ) as backend: assert type(getattr(backend, attribute)) is march - problem, run_request = soliton_problem( - narrow_grid, - 1, - save_planes=[length], - schedule=schedule, - dz_max=length / 4, - dz_init=length / 4, - ) - member = NumpyRefBackend(problem, run_request, grid=narrow_grid) - member.set_initial(problem.initial.field0, None) - with closing(NumpyBatchBackend([member])) as group: - assert isinstance(group, HostGroup) def test_the_run_layer_serves_the_reference_with_the_host_session( @@ -80,27 +61,6 @@ def test_the_run_layer_serves_the_reference_with_the_host_session( assert type(session) is HostSession -def test_the_run_layer_serves_a_reference_group_with_the_host_group_session( - soliton_problem, narrow_grid -): - length = 1e-3 - schedule = FixedSchedule.uniform(0.0, length, length / 4, save_planes=[length]) - problem, run_request = soliton_problem( - narrow_grid, - 1, - save_planes=[length], - schedule=schedule, - dz_max=length / 4, - dz_init=length / 4, - ) - members = [NumpyRefBackend(problem, run_request, grid=narrow_grid)] - with start_group( - members, [problem], [run_request], [Start.entrance(problem)] - ) as group: - assert type(group) is HostGroupSession - assert isinstance(getattr(group, "_runner"), NumpyBatchBackend) # noqa: B009 - - def test_an_injected_adams_engine_is_gated_and_checked_as_the_bridge_s( soliton_problem, narrow_grid ): diff --git a/tests/backends/test_registry.py b/tests/backends/test_registry.py index 2fa6c3cc7..d6687107a 100644 --- a/tests/backends/test_registry.py +++ b/tests/backends/test_registry.py @@ -142,7 +142,8 @@ def test_select_builds_the_reference_backend(linear_problem, narrow_grid, caplog backend = select("numpy_ref", problem, run_request, grid=narrow_grid) assert isinstance(backend, NumpyRefBackend) assert isinstance(backend, Backend) - assert (backend.name, backend.max_batch) == ("numpy_ref", 1) + assert backend.name == "numpy_ref" + assert backend.available_device_memory() is None backend.close() assert caplog.messages == ["Using numpy_ref backend"] @@ -153,7 +154,7 @@ def test_select_builds_the_installed_native_backend(linear_problem, narrow_grid) pytest.skip("the optional solprop-native package is not installed") problem, run_request = linear_problem(narrow_grid, save_planes=[LENGTH]) backend = select("native", problem, run_request, grid=narrow_grid) - assert (backend.name, backend.max_batch) == ("native", 1) + assert backend.name == "native" backend.close() diff --git a/tests/backends/test_transverse_owner.py b/tests/backends/test_transverse_owner.py index 54290dabe..80b8c73bd 100644 --- a/tests/backends/test_transverse_owner.py +++ b/tests/backends/test_transverse_owner.py @@ -5,8 +5,8 @@ """The native session's own transverse edge against solprop's, on recorded readings. SEP 47 sections 4.3 and 6.4 and the maintainer's decision 4 at its acceptance: the -native session owns a free-space run's transverse edge (``transverse::Edge``, -``solprop_native._core.TransverseEdge``) with every decision and record. Both edges are +native session owns a free-space run's transverse edge (``transverse::Edge``, the +private test module's ``TransverseEdge``) with every decision and record. Both edges are fed the same recorded readings -- the launch with its clip, noise and schedule, reads on and off their spacing, a collar's current at every step, a plane re-read, a resume -- and must make exactly the same decisions: every warning and stop, in order and in @@ -56,7 +56,7 @@ def _modules() -> tuple[Any, Any]: return ( - importlib.import_module("solprop_native._core"), + importlib.import_module("solprop_native._core")._testing, importlib.import_module("solprop_native._transverse"), ) diff --git a/tests/backends/test_vector_raman_routes.py b/tests/backends/test_vector_raman_routes.py index db0aef600..58ff0d3b6 100644 --- a/tests/backends/test_vector_raman_routes.py +++ b/tests/backends/test_vector_raman_routes.py @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""Exercise tensor histories through local profiles, spatial transforms and batches. +"""Exercise tensor histories through local profiles and spatial transforms. On the modal routes -- a mode whose direction depends on position, and two envelope plasma populations with a Raman kernel each -- native's first stage and two fixed steps @@ -18,16 +18,13 @@ from backends.host_cases_envelope_plasma import geometry_options from backends.ladder_rows import DIRECTIONS -from backends.test_batch_responses import compare from sessions.runs import run as session_run from solprop.backends.session import ExecutionOptions from solprop.exceptions import TranslationError from vector_raman_cases import ( - CHUNK, direction_translation, raman_populations, spatial_tails, - vector_translation, ) @@ -71,15 +68,6 @@ def test_raman_acts_on_synthesised_position_dependent_direction( ) -@pytest.mark.medium -@pytest.mark.parametrize("family", ["field_real", "field_analytic", "envelope"]) -def test_vector_fixed_batches_preserve_modified_noise_members(family): - # The reference's lockstep group; the native group runs each member as its own - # native session (SEP 47 phase 5), with no shared arithmetic to check. - problem, run_request, grid, _ = vector_translation(family, steps=2) - compare(problem, run_request, grid, "numpy_ref", options=CHUNK) - - @pytest.mark.medium @pytest.mark.parametrize( ("geometry", "varying_density"), diff --git a/tests/builders.py b/tests/builders.py index 4c6376ab4..281facc7d 100644 --- a/tests/builders.py +++ b/tests/builders.py @@ -13,17 +13,24 @@ import sys import textwrap from pathlib import Path -from typing import Any +from typing import Any, Literal import numpy as np +from legacy_geometry import LEGACY_GRID, bare_absorber +from march_bounds import FIXED_ORDER from solprop.backends.numpy_ref import NumpyRefBackend -from solprop.grid import TimeGrid +from solprop.driver import Simulation +from solprop.driver.scan import ScanPoint +from solprop.grid import EnvelopeGrid, TimeGrid +from solprop.stats import StatsSpec +from solprop.stepper import FixedSchedule from solprop.translate.problem import PropagationProblem from solprop.translate.run_request import RunRequest __all__ = [ "HASH_PROBE", + "fixed_fibre_point", "launch_derivative", "numpy_ref_launch_derivative", "run_python", @@ -85,3 +92,39 @@ def run_python(path: Path) -> "subprocess.CompletedProcess[str]": ) assert result.returncode == 0, result.stderr return result + + +def fixed_fibre_point( + point: ScanPoint, + backend: str = "numpy_ref", + noise: Literal["input", "modified"] = "modified", +) -> Simulation: + """Build a scan point's millimetre of fibre on a fixed four-step schedule. + + The point's index scales the nonlinearity, the dispersion and the peak power; its + seed draws the noise. The former grid without a collar: a short fixed schedule is + refused beside the default collar, and the scan tests that build it are about + scans, not boundaries. + """ + grid = EnvelopeGrid.from_limits(0.001, 835e-9, (500e-9, 2e-6), 1e-12, **LEGACY_GRID) + return Simulation.from_gnlse( + 0.11 * (point.index + 1), + 0.001, + [0.0, 0.0, -1.183e-26 * (point.index + 1)], + wavelength=835e-9, + grid=grid, + absorber=bare_absorber(grid), + width=100e-15, + peak_power=float(point.index + 1), + shape="sech", + save_planes=[0.0005, 0.001], + schedule=FixedSchedule.uniform( + 0.0, 0.001, 0.00025, save_planes=[0.0005, 0.001] + ), + stats=StatsSpec(names=("energy", "peak_power"), periodic=("energy",), period=2), + noise=noise, + seed=point.seed, + # The fixed order leaves no controller decision on the prescribed schedule. + integrator=FIXED_ORDER, + backend=backend, + ) diff --git a/tests/data/shard_weights.json b/tests/data/shard_weights.json index cd1e54cbf..001774240 100644 --- a/tests/data/shard_weights.json +++ b/tests/data/shard_weights.json @@ -191,9 +191,6 @@ "tests/backends/test_admission.py": 5.6, "tests/backends/test_backend_ladder.py": 3.8, "tests/backends/test_backend_protocol.py": 0.1, - "tests/backends/test_batch_lockstep.py": 7.6, - "tests/backends/test_batch_responses.py": 1.3, - "tests/backends/test_batch_validation.py": 1.0, "tests/backends/test_carrier_frame.py": 126.9, "tests/backends/test_collar_diagnostic.py": 1.4, "tests/backends/test_compiled_multistep.py": 43.8, @@ -342,7 +339,6 @@ "tests/driver/test_abandoned_step.py": 2.5, "tests/driver/test_absorber_keywords.py": 1.6, "tests/driver/test_backend_default.py": 8.4, - "tests/driver/test_batch.py": 1.2, "tests/driver/test_capillary_components.py": 50.9, "tests/driver/test_coherent_capillary.py": 244.1, "tests/driver/test_coherent_wall_phase.py": 1.6, @@ -411,7 +407,6 @@ "tests/driver/test_run.py": 2.6, "tests/driver/test_runner.py": 22.1, "tests/driver/test_scaffold.py": 1.0, - "tests/driver/test_scan_batch.py": 51.1, "tests/driver/test_scan_derived_noise.py": 96.2, "tests/driver/test_scan_field_retention.py": 4.0, "tests/driver/test_scan_kept_backend.py": 13.8, @@ -614,10 +609,7 @@ "tests/service/test_waveguide.py": 24.9, "tests/sessions/test_conformance.py": 41.8, "tests/sessions/test_destination_export.py": 8.2, - "tests/sessions/test_group.py": 3.1, - "tests/sessions/test_group_seam.py": 0.0, "tests/sessions/test_host_seams.py": 0.1, - "tests/sessions/test_native_group.py": 5.5, "tests/sessions/test_native_load.py": 0.2, "tests/sessions/test_native_monitor_cap.py": 0.3, "tests/sessions/test_native_quadrature_alarm.py": 1.0, diff --git a/tests/driver/test_abandoned_step.py b/tests/driver/test_abandoned_step.py index d7052a224..08aac6dad 100644 --- a/tests/driver/test_abandoned_step.py +++ b/tests/driver/test_abandoned_step.py @@ -153,8 +153,12 @@ def _abandon_natively(monkeypatch, *, after: int) -> None: prepare = session._prepare def arming(self, backend, start): + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + prepared = prepare(self, backend, start) - backend._native_state.adams_march_fault("trial", after, "backend") + _testing.adams_march_fault(backend._native_state, "trial", after, "backend") return prepared monkeypatch.setattr(session, "_prepare", arming) diff --git a/tests/driver/test_batch.py b/tests/driver/test_batch.py deleted file mode 100644 index abac79cf7..000000000 --- a/tests/driver/test_batch.py +++ /dev/null @@ -1,247 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""Check common batch preparation independently of native execution.""" - -import dataclasses - -import numpy as np -import pytest -from jaxtyping import TypeCheckError - -from driver.test_scans import build_point -from runtime_types import requires_typecheck, unchecked -from solprop.backends.node_chunk import NodeChunkPlan, plan_node_chunk -from solprop.backends.session import ExecutionOptions -from solprop.driver import batch as batch_module -from solprop.driver.batch import ( - BatchMember, - _structure, - compatible_groups, - refuse_mixed_guides, - shared_table_bytes, -) -from solprop.driver.scan import Scan -from solprop.driver.simulation import Simulation -from solprop.exceptions import BackendError, DriverError -from solprop.grid import RadialGrid -from solprop.pulses import GaussianPulse, SpatialPulse -from solprop.spatial import SpatialMedium -from solprop.stats import StatsSpec -from solprop.stepper.runge_kutta import RungeKutta -from solprop.stepper.schedule import FixedSchedule - - -def member(index, power=1.0, backend="native", fixed=True, **settings): - simulation = build_point(Scan("fixture", power=[power]).point(0)) - schedule = ( - FixedSchedule.uniform( - 0.0, - simulation.grid.length, - 0.00025, - save_planes=simulation.settings.save_planes, - ) - if fixed - else None - ) - simulation.settings = dataclasses.replace( - simulation.settings, backend=backend, schedule=schedule, **settings - ) - return BatchMember(index, simulation) - - -def test_batch_groups_keep_global_indices_and_partial_tail(): - members = [member(i, float(i + 1)) for i in (7, 9, 12, 15, 20)] - groups = list(compatible_groups(members, 2)) - assert [[m.index for m in group] for group in groups] == [[7, 9], [12, 15], [20]] - assert all( - m.simulation.settings.backend == "native" for group in groups for m in group - ) - - -def test_batch_groups_do_not_build_past_a_full_group(): - built = [] - - def points(): - for index in range(5): - built.append(index) - yield member(index) - - groups = compatible_groups(points(), 2) - assert [point.index for point in next(groups)] == [0, 1] - assert built == [0, 1] - assert [point.index for point in next(groups)] == [2, 3] - assert built == [0, 1, 2, 3] - assert [point.index for point in next(groups)] == [4] - - -# Each row is a set of members (built when the test runs) and a group size that -# `compatible_groups` refuses, with the exact match. -GROUP_REFUSALS = [ - (lambda: [member(-1)], 2, "nonnegative global indices"), - ( - lambda: [member(0, backend="numpy_ref"), member(1, backend="native")], - 2, - "mixed backends", - ), - (lambda: [member(0, fixed=False)], 2, "explicit fixed schedule"), - *((lambda: [], size, "positive integer") for size in (0, -1, True)), -] - - -@pytest.mark.parametrize(("members", "size", "message"), GROUP_REFUSALS) -def test_batch_groups_refuse_an_unbatchable_request(members, size, message): - with pytest.raises(DriverError, match=message): - list(compatible_groups(members(), size)) - - -def test_batch_different_schedule_starts_a_separate_group(): - first, second = member(4), member(6) - second.simulation.settings = dataclasses.replace( - second.simulation.settings, - schedule=FixedSchedule.uniform( - 0.0, - second.simulation.grid.length, - 0.000125, - save_planes=second.simulation.settings.save_planes, - ), - ) - assert [len(group) for group in compatible_groups([first, second], 4)] == [1, 1] - - -def test_batch_groups_by_the_planned_node_chunk_not_the_budget(monkeypatch): - """A lockstep group shares one node chunk, whatever budgets planned it (SEP 47).""" - budgets = [None, None, 2**30, 2**31] - members = [ - member(index, float(index + 1), node_budget=budget) - for index, budget in enumerate(budgets) - ] - chunks = { - budget: plan_node_chunk( - members[0].simulation.translate(), ExecutionOptions(node_budget=budget) - ).chunk - for budget in budgets - } - # The fixture's chunk is its whole node set at each budget: one group. - assert len(set(chunks.values())) == 1 - assert [len(group) for group in compatible_groups(members, 4)] == [4] - - def planned(problem, options): - """Plan a chunk that differs where the budget does, as responses can.""" - chunk = 1 if options.node_budget is None else 2 - return NodeChunkPlan(chunk, options.node_budget or 1, "default") - - monkeypatch.setattr(batch_module, "plan_node_chunk", planned) - groups = compatible_groups(members, 4) - assert [[one.index for one in group] for group in groups] == [[0, 1], [2, 3]] - - -@pytest.mark.parametrize("backend", ["jax", "numba", "unregistered_backend"]) -def test_batch_refuses_unsupported_backends_by_name(backend): - # A name that is neither backend is refused by the registry when the member's - # settings are built (ADR-077), so no batch is ever formed for it. - with pytest.raises(BackendError, match=rf"^'{backend}' is not a backend"): - member(0, backend=backend, integrator=RungeKutta()) - - -@pytest.mark.parametrize("backend", ["numpy_ref", "native"]) -def test_batch_prepares_each_backend_without_changing_selection(backend): - points = [member(0, backend=backend), member(1, backend=backend)] - assert list(compatible_groups(points, 2)) == [tuple(points)] - assert all(point.simulation.settings.backend == backend for point in points) - - -def test_batch_refuses_spatial_geometry_before_selecting_a_backend(): - base = member(0, backend="numpy_ref").simulation - simulation = Simulation.from_free( - base.grid, - RadialGrid(0.6e-3, 8), - SpatialMedium(), - [], - SpatialPulse( - GaussianPulse(wavelength=835e-9, fwhm=100e-15, energy=1e-9), 60e-6 - ), - settings=dataclasses.replace( - base.settings, - stats=StatsSpec(names=("energy",)), - shock=True, - prefactor_index=None, - ), - noise=None, - ) - with pytest.raises(DriverError, match="fibre geometry"): - list(compatible_groups([BatchMember(0, simulation)], 2)) - - -def test_a_native_batch_groups_z_table_members(): - # The native backend's CPU build evaluates the z table itself (SEP 29 section - # 6.6), so grouping no longer refuses it; a device build refuses at construction. - point = member(0) - problem = point.simulation.translate() - point.simulation._problem = dataclasses.replace( - problem, - linear=dataclasses.replace( - problem.linear, phi_representation="table", phi_constant=None - ), - ) - assert [ - [one.index for one in group] for group in compatible_groups([point], 2) - ] == [[0]] - - -@requires_typecheck -@pytest.mark.parametrize("size", [1.5]) -def test_batch_size_rejects_fractional_type(size): - with pytest.raises(TypeCheckError, match="size"): - list(compatible_groups([], size)) - - -def test_batch_memory_counts_shared_tables_once(): - simulation = member(0).simulation - first = simulation.translate() - field = first.initial.field0 * 1.25 - second = simulation.with_input(field).translate() - single = shared_table_bytes([first]) - assert shared_table_bytes([first, first]) == single - assert shared_table_bytes([first, second]) == single + field.nbytes - np.testing.assert_array_equal(second.initial.field0, field) - - -def test_named_table_layouts_ignore_values_but_preserve_names_and_shapes(): - first = {"rate": np.zeros(3), "enabled": True} - second = {"rate": np.ones(3), "enabled": True} - assert _structure(first) == _structure(second) - assert _structure(first) != _structure({"rate": np.ones(4), "enabled": True}) - assert _structure(first) != _structure({"other_rate": np.zeros(3), "enabled": True}) - - -def test_a_group_with_no_members_or_no_guide_has_nothing_to_disagree_about(): - """`refuse_mixed_guides` passes what it has no complaint about. - - Nothing to compare, and members that carry no general modal guide at all -- every - ordinary batch -- are the two cases it must let through, so that the refusal is - about guides and not about batches. - """ - refuse_mixed_guides([]) - ordinary = [member(index).simulation.translate() for index in range(2)] - refuse_mixed_guides(ordinary) - - -def test_shared_bytes_count_mapped_arrays_once_through_their_views(): - """A record's mapping of arrays counts each backing allocation once. - - Translated records hold tables in mappings as well as fields and sequences; a - view of an array counts as its base, and the same base reached twice once. - """ - - @dataclasses.dataclass - class Record: - tables: dict[str, np.ndarray] - views: tuple[np.ndarray, ...] - - base = np.zeros(64) - other = np.zeros(32) - record = Record({"base": base, "slice": base[:8], "other": other}, (base[::2],)) - counted = unchecked(shared_table_bytes)([record]) # any translated record - assert counted == base.nbytes + other.nbytes diff --git a/tests/driver/test_coherent_capillary.py b/tests/driver/test_coherent_capillary.py index 2bd4dfe17..036c67d07 100644 --- a/tests/driver/test_coherent_capillary.py +++ b/tests/driver/test_coherent_capillary.py @@ -51,7 +51,7 @@ legacy_gnlse, legacy_simulation, ) -from march_bounds import FIXED_ORDER, assert_points_matched +from march_bounds import FIXED_ORDER from modal_provider_cases import GENERAL_Z_END, general_grid, general_guide from solprop.backends import available from solprop.backends.numpy_ref import NumpyRefBackend @@ -62,8 +62,6 @@ from solprop.boundaries import absorber from solprop.constants import EPS0, C from solprop.driver import Simulation, prop_capillary -from solprop.driver.executors import Batch, Local -from solprop.driver.scan import Scan, run_scan from solprop.exceptions import ( AdiabaticTaperWarning, BackendError, @@ -3133,38 +3131,3 @@ def test_the_validity_ratios_are_admitted_and_recorded_over_the_scored_band(): ) with pytest.raises(ModeError, match=r"transverse_ratio is 0\.31.* above the 0\.25"): _taper_note_bore(40).translate() - - -def _reference_scan_point(point): - """Return one point of a power scan of the scalar wall, on the reference.""" - return capillary( - wall=CoherentWall(), backend="numpy_ref", energy=1e-9 * point.values["power"] - ) - - -def test_a_batched_reference_scan_of_coupled_flows_runs_as_the_local_loop(tmp_path): - """The reference's lockstep runner takes coupled members one by one (#241). - - Its member-axis batch applies neither half of a flow, so the runner gives coupled - members the member-by-member group, each its own trial, flow included: every point - is the local loop's to the matched-march bound (SEP 25). - """ - scan = Scan("coupled", power=[1.0, 2.0]) - local = run_scan( - scan, - _reference_scan_point, - output=tmp_path / "local.h5", - executor=Local(), - progress="none", - ) - batched = run_scan( - scan, - _reference_scan_point, - output=tmp_path / "batch.h5", - executor=Batch(2), - progress="none", - ) - assert local.status.tolist() == batched.status.tolist() == ["done"] * 2 - assert_points_matched( - batched, local, scan, _reference_scan_point, what="batch member" - ) diff --git a/tests/driver/test_envelope_plasma.py b/tests/driver/test_envelope_plasma.py index f6aa42bd7..c5a53d44a 100644 --- a/tests/driver/test_envelope_plasma.py +++ b/tests/driver/test_envelope_plasma.py @@ -4,10 +4,7 @@ """Exercise envelope plasma through constructors, material updates and saved runs.""" -from collections.abc import Mapping from dataclasses import replace -from functools import partial -from typing import cast import numpy as np import pytest @@ -16,16 +13,12 @@ from driver.test_resume import run_until from march_bounds import ( FIXED_ORDER, - PRESCRIBED, STATISTIC_FACTOR, - assert_stored_matched, simulation_bound, ) from rate_oracles import AdkOracle, adk_oracle from solprop.boundaries import absorber from solprop.driver import Simulation -from solprop.driver.executors import Batch, Local -from solprop.driver.scan import Scan, run_scan from solprop.exceptions import MaterialError, MaterialRangeWarning from solprop.modes import MarcatiliMode from solprop.nonlinear import EnvelopePlasmaResponse, responses_for @@ -312,56 +305,3 @@ def test_modified_noise_plasma_statistics_scan_the_committed_field( budget *= max(1.0, rate_log_sensitivity(rate, smallest, (1e7, 1e12))) assert budget < 2.26e-5 / 10 np.testing.assert_allclose(value, reference, rtol=0, atol=budget * scale) - - -def scan_point(point, backend): - return build( - backend=backend, - energy=1e-5 * point.values["scale"], - noise="modified", - seed=point.seed, - ) - - -# A native lockstep batch replays its Adams members on solprop's march, with the -# warning native/tests/test_batch.py asserts (SEP 39). -@pytest.mark.filterwarnings("ignore::solprop.exceptions.HostMarchWarning") -@pytest.mark.medium -@pytest.mark.parametrize("backend", ["numpy_ref", "native"]) -def test_envelope_scan_batches_match_singletons_and_partial_tail(tmp_path, backend): - scan = Scan("envelope", base_seed=711, scale=[0.8, 1.0, 1.1]) - builder = partial(scan_point, backend=backend) - options = {"fields": "planes", "field_planes": [-1], "progress": "none"} - single = run_scan( - scan, builder, output=tmp_path / "single.h5", executor=Local(), **options - ) - batch = run_scan( - scan, builder, output=tmp_path / "batch.h5", executor=Batch(2), **options - ) - assert single.status.tolist() == batch.status.tolist() == ["done"] * 3 - for point in scan.points(): - actual, expected = batch.point(point.index), single.point(point.index) - assert ( - cast(Mapping, actual["metadata"])["configuration"] - == cast(Mapping, expected["metadata"])["configuration"] - ) - arrays = { - name: np.asarray(value) - for name, value in expected.items() - if name != "metadata" - } - # A batch member is its singleton's march, to the march's rounding budget; a - # rate statistic moves by its sensitivity `d ln W / d ln F` times the field. - factors = { - name: STATISTIC_FACTOR * max(1.0, peak_rate_sensitivity(value)) - for name, value in arrays.items() - if any(rate in name for rate in RATE_STATISTICS) and np.any(value) - } - assert_stored_matched( - arrays, - {name: value for name, value in actual.items() if name != "metadata"}, - simulation_bound(builder(point), backend=backend), - exact=PRESCRIBED, - factors=factors, - what=f"batch member {point.index}", - ) diff --git a/tests/driver/test_field_free_planes.py b/tests/driver/test_field_free_planes.py index 538c2f31f..e4da92f0d 100644 --- a/tests/driver/test_field_free_planes.py +++ b/tests/driver/test_field_free_planes.py @@ -536,10 +536,3 @@ def test_an_observation_refuses_a_noise_phase_without_its_field(): Observation(0.0, None, np.zeros((1, 1, 4)), history, 0, 0) with pytest.raises(BackendError, match="n_steps is 1"): Observation(0.0, None, None, history, 1, 0) - - -def test_a_lockstep_batch_still_refuses_a_shared_observation(): - from solprop.backends.host.group import HostGroup # noqa: PLC0415 - - with pytest.raises(BackendError, match="observe_members"): - HostGroup.observe(object.__new__(HostGroup), field=False) diff --git a/tests/driver/test_general_modal.py b/tests/driver/test_general_modal.py index 5d4854837..569528d74 100644 --- a/tests/driver/test_general_modal.py +++ b/tests/driver/test_general_modal.py @@ -23,12 +23,9 @@ and recorded beside the comparison rather than folded into it. """ -import copy import dataclasses import inspect from collections.abc import Mapping -from contextlib import ExitStack -from types import SimpleNamespace from typing import Any, cast import numpy as np @@ -39,7 +36,6 @@ from legacy_geometry import LEGACY_GRID from march_bounds import ( FIXED_ORDER, - STATISTIC_FACTOR, assert_matched, simulation_bound, ) @@ -51,22 +47,11 @@ ) from solprop import fourier from solprop.backends import select -from solprop.backends.host.group import HostGroup, _general_leaves -from solprop.backends.numpy_ref.batch import NumpyBatchBackend from solprop.backends.protocol import stepping from solprop.backends.session import Start -from solprop.backends.sessions import start_group from solprop.constants import ROOM_TEMPERATURE, C from solprop.coupling import CouplingModel, CouplingReport from solprop.driver import Simulation, prop_gnlse, prop_waveguide -from solprop.driver import batch as batch_module -from solprop.driver.batch import ( - BatchMember, - _modal_identity, - compatible_groups, - refuse_mixed_guides, -) -from solprop.driver.executors import Batch from solprop.driver.inputs import _shot_noise from solprop.driver.routes.general import ( GAS_KEYWORD_DEFAULTS, @@ -76,7 +61,6 @@ _refuse_gas_keywords, ) from solprop.driver.run import run_problem -from solprop.driver.scan import Scan, run_scan from solprop.exceptions import ( BackendError, DriverError, @@ -94,7 +78,6 @@ from solprop.output.memory import MemoryOutput from solprop.physdata import n2_from_chi3 from solprop.physdata.sellmeier import gamma as gas_susceptibility -from solprop.processing import scans from solprop.pulses import GaussianPulse, PlanarPulse, SpatialPulse from solprop.stats import StatsSpec, analytic_field, energy, physical_energy from solprop.stepper import FixedSchedule, Multistep @@ -946,11 +929,11 @@ def test_the_same_seed_gives_the_same_realisation_and_the_same_run(guide, grid): energy-normalised true-power amplitude, so the existing draw is added to the state as it stands. Nothing multiplies it by an index. """ - # On the batch door's prescribed schedule at a fixed order, so the two runs of one - # seed are one discrete march with the same stored realisation (SEP 25 4.5). - first = batched_run(guide, grid, noise="input", seed=17) - again = batched_run(guide, grid, noise="input", seed=17) - other = batched_run(guide, grid, noise="input", seed=18) + # On a prescribed schedule at a fixed order, so the two runs of one seed are one + # discrete march with the same stored realisation (SEP 25 4.5). + first = fixed_run(guide, grid, noise="input", seed=17) + again = fixed_run(guide, grid, noise="input", seed=17) + other = fixed_run(guide, grid, noise="input", seed=18) assert first.noise is not None and again.noise is not None assert other.noise is not None assert np.array_equal(first.noise.spectrum, again.noise.spectrum) @@ -1200,9 +1183,9 @@ def test_a_record_that_misnames_the_basis_is_refused_at_the_run_loop( def test_an_hdf5_file_carries_the_labels_and_the_identities(guide, grid, tmp_path): """The run record admits a general modal run at the run loop's own door. - The other three doors -- `MemoryOutput.to_file`, a scan point's capture and - its spool, and the batch member that stays refused -- belong to the file and - are in `tests/output/test_modal_resume.py` and below. + The other doors -- `MemoryOutput.to_file`, and a scan point's capture and its + spool -- belong to the file and are in `tests/output/test_modal_resume.py` and + below. """ path = tmp_path / "general.h5" simulation = build(guide, grid) @@ -1216,25 +1199,25 @@ def test_an_hdf5_file_carries_the_labels_and_the_identities(guide, grid, tmp_pat assert stored.configuration_hash() == simulation.metadata().configuration_hash() -# --------------------------------------------------------------- the batch door +# ------------------------------------------------------------ a fixed schedule -BATCH_Z = GENERAL_Z_END / 10 -"""Length a batched general modal test propagates, m: a tenth of the cap.""" +FIXED_Z = GENERAL_Z_END / 10 +"""Length a fixed-schedule general modal test propagates, m: a tenth of the cap.""" -def batched_run(guide, grid, **overrides): +def fixed_run(guide, grid, **overrides): """Return a general modal simulation on an explicit fixed schedule.""" - schedule = FixedSchedule.uniform(0.0, BATCH_Z, BATCH_Z / 4, save_planes=[BATCH_Z]) + schedule = FixedSchedule.uniform(0.0, FIXED_Z, FIXED_Z / 4, save_planes=[FIXED_Z]) settings = { "wavelength": PULSE["wavelength"], "fwhm": PULSE["fwhm"], "shape": PULSE["shape"], "energy": PULSE["energy"], "schedule": schedule, - # No order choice on the prescribed schedule: a member and its solo run are - # one discrete march (SEP 25 4.4). + # No order choice on the prescribed schedule: two runs of it are one discrete + # march (SEP 25 4.4). "integrator": FIXED_ORDER, - "save_planes": [BATCH_Z], + "save_planes": [FIXED_Z], "backend": "numpy_ref", } simulation = Simulation.from_waveguide( @@ -1253,259 +1236,6 @@ def batched_run(guide, grid, **overrides): return simulation -@pytest.mark.medium -@pytest.mark.parametrize("runner_factory", [HostGroup, NumpyBatchBackend]) -def test_a_general_guide_batch_is_what_its_members_run_alone( - guide, grid, runner_factory -): - """The batch door: two launches, one guide, each its own solo march. - - The narrow admission rule is that a general-guide batch shares the guide, the table - and the gauge and its members differ in their launch and their noise seed alone. - What makes that safe is that the route's source pass already sees one member's - state: the lockstep runner hands each member its own singleton row, so nothing in - the pass had to loop. Each member is its solo run's discrete march, so the two - agree within that march's rounding budget (SEP 25: batch membership is not - promised bitwise). - """ - with ExitStack() as cleanup: - simulations = [ - batched_run(guide, grid, energy=energy, noise="input", seed=13 + index) - for index, energy in enumerate((1e-12, 2e-12)) - ] - members, alone = [], [] - for simulation in simulations: - problem = simulation.translate() - run_request = simulation._run_request() - for bucket in (members, alone): - backend = select("numpy_ref", problem, run_request, grid=grid) - cleanup.callback(backend.close) - stepping(backend).set_initial(problem.initial.field0, simulation.noise) - bucket.append(backend) - runner = runner_factory(members) - cleanup.callback(runner.close) - runner.propagate_to(BATCH_Z) - for owner in alone: - owner.propagate_to(BATCH_Z) - spec = simulations[0]._run_request().observation.stats - batched_stats = runner.stats(spec) - bounds = [simulation_bound(simulation) for simulation in simulations] - for index, (observed, owner) in enumerate( - zip(runner.observe_members(), alone, strict=True) - ): - solo = owner.observe() - bound = bounds[index] - assert_matched(observed.field, solo.field, bound, what="field") - assert_matched( - observed.noise_phase, solo.noise_phase, bound, what="noise phase" - ) - for name, value in owner.stats(spec).items(): - assert_matched( - batched_stats[name][index], - value, - STATISTIC_FACTOR * bound, - what=name, - ) - # The two launches really are different, far beyond the budget, so the - # agreement above is a statement and not a tautology. - first, second = (one.observe().require_field() for one in alone) - assert departure(second, first) > 100 * max(bounds) - - -def test_two_guides_never_share_a_batch_group(guide, grid): - """The descriptor separates them, and the runner refuses a mixed group anyway. - - Two strands of different radius share every entry a structural signature would hash - -- shape, flags, table extents, response structure. It is `modal_tables.identity` - that separates them, with the metric's gauge and the responses' model beside it; and - because a descriptor is only as good as what it names, the group a caller assembles - by hand is refused by name at the driver and again at the backend. - """ - one = BatchMember(0, batched_run(guide, grid)) - other = BatchMember(1, batched_run(general_guide(grid=grid, radius=1.6e-6), grid)) - same = BatchMember(2, batched_run(guide, grid, energy=2e-12)) - # Different guides: two groups of one. The same guide with another launch: - # one group of two, which is exactly the admitted difference. - assert [len(group) for group in compatible_groups([one, other], 4)] == [1, 1] - assert [len(group) for group in compatible_groups([one, same], 4)] == [2] - problems = [member.simulation.translate() for member in (one, other)] - requests = [member.simulation._run_request() for member in (one, other)] - with pytest.raises(DriverError, match="identical guide/table/gauge identity"): - refuse_mixed_guides(problems) - # And a general guide beside a run that is not one is named the same way. - with pytest.raises(DriverError, match="identical guide/table/gauge identity"): - refuse_mixed_guides([problems[0], ordinary_simulation(("energy",)).translate()]) - with ExitStack() as cleanup: - loaded = [] - for problem, run_request in zip(problems, requests, strict=True): - backend = select("numpy_ref", problem, run_request, grid=grid) - cleanup.callback(backend.close) - stepping(backend).set_initial(problem.initial.field0, None) - loaded.append(backend) - with pytest.raises(BackendError, match="identical guide/table/gauge identity"): - HostGroup(loaded) - - -def test_the_native_group_refuses_two_guides_too(guide, grid): - """The native group session refuses the same group, before any member starts.""" - pytest.importorskip("solprop_native") - runs = [ - batched_run(one, grid) - for one in (guide, general_guide(grid=grid, radius=1.6e-6)) - ] - with ExitStack() as cleanup: - owners, problems, requests = [], [], [] - for run in runs: - problem, run_request = run.translate(), run._run_request() - backend = select("native", problem, run_request, grid=grid) - cleanup.callback(backend.close) - owners.append(backend) - problems.append(problem) - requests.append(run_request) - with pytest.raises(BackendError, match="identical guide/table/gauge identity"): - start_group( - owners, - problems, - requests, - [Start.entrance(problem) for problem in problems], - ) - - -def _with_flow(problem, flow): - """Return the problem with a stand-in coupled flow, past the operator's checks.""" - linear = copy.copy(problem.linear) - object.__setattr__(linear, "coupled_flow", flow) - return dataclasses.replace(problem, linear=linear) - - -def test_the_native_group_compares_a_guide_s_flow_as_the_reference(guide, grid): - """The native group admits coupled flows, so its guide check's flow component is - live: it reads the reference group's leaves (``_general_leaves``), the flow's - gauge, certificate and section methods included, and compares flows by value.""" - group = pytest.importorskip("solprop_native.group") - problem = batched_run(guide, grid).translate() - assert problem.transform.modal_tables is not None - one, same, other = ( - _with_flow( - problem, - SimpleNamespace( - gauge_id="lab", certificate_id=certificate, section_methods=methods - ), - ) - for certificate, methods in ( - ("one", ("constant_schur",)), - ("one", ("constant_schur",)), - ("one", ("frozen_residual",)), - ) - ) - for candidate in (problem, one, same, other): - assert group._guide(candidate) == _general_leaves(candidate) - assert group._guide(one) == group._guide(same) - assert group._guide(one) != group._guide(other) - assert group._guide(one) != group._guide(problem) - - -def test_the_driver_refuses_a_mixed_group_before_a_backend_is_reached( - guide, grid, monkeypatch -): - """`refuse_mixed_guides` runs on the driver's own grouping path. - - Defence in depth, and what makes "refused at the driver and again at the - backend" a true sentence rather than a description of a function nothing - called. `compatible_groups` separates two guides by signature, so the - refusal never fires on a group it built; a grouping rule that stopped naming - the guide identity would silently put two guides in one group, and before - this nothing between there and the backend would notice. The signature is - blinded here to produce exactly that state, and the group is refused where - it is formed -- no backend is constructed at all. - """ - one = BatchMember(0, batched_run(guide, grid)) - other = BatchMember(1, batched_run(general_guide(grid=grid, radius=1.6e-6), grid)) - monkeypatch.setattr(batch_module, "_signature", lambda member: "one-layout") - with pytest.raises(DriverError, match="identical guide/table/gauge identity"): - list(compatible_groups([one, other], 4)) - # And the same blinded signature passes a group that really is one guide, so - # the refusal above is the guide identity and not the blinding. - same = BatchMember(2, batched_run(guide, grid, energy=2e-12)) - assert [len(group) for group in compatible_groups([one, same], 4)] == [2] - - -def test_a_linear_general_guide_groups_by_what_it_does_not_declare(guide, grid): - """A guide whose regions are all linear has no response leaf to describe. - - The descriptor's `responses` entry is then `None`, and two linear members of - the same guide still group; a linear guide and a responding one never do, - which is the same physical distinction as two different radii. - """ - linear = general_guide(grid=grid, chi3=None) - members = [ - BatchMember(0, batched_run(linear, grid)), - BatchMember(1, batched_run(linear, grid, energy=2e-12)), - ] - assert [len(group) for group in compatible_groups(members, 4)] == [2] - identity = _modal_identity(members[0].simulation.translate()) - assert identity is not None - assert identity["responses"] is None - assert identity["metric"] is not None - mixed = [members[0], BatchMember(2, batched_run(guide, grid))] - assert [len(group) for group in compatible_groups(mixed, 4)] == [1, 1] - with pytest.raises(DriverError, match="identical guide/table/gauge identity"): - refuse_mixed_guides([one.simulation.translate() for one in mixed]) - - -@pytest.mark.medium -def test_a_general_guide_batch_isolates_and_retries_a_failed_member( - guide, grid, tmp_path -): - """One member fails, the others complete, and a retry recovers it. - - The failure/recovery half of the batch admission rule: no averaging hides - a member, the failed point keeps its own provenance -- its configuration hash - and its seed -- and writes no arrays, and `retry_failed=True` finishes it once - the cause is gone. - """ - scan = Scan("batch", base_seed=772, energy=[1e-12, 2e-12, 3e-12]) - fail = [True] - - def reduce(output): - assert output.metadata is not None and output.metadata.modal is not None - noise = output.metadata.noise - if fail[0] and noise is not None and noise.seed == scan.point(1).seed: - raise RuntimeError("deliberate member reduction failure") - return np.asarray(output["stats/physical_energy"][-1].sum()) - - def builder(point): - return batched_run( - guide, - grid, - energy=float(point.values["energy"]), - noise="input", - seed=point.seed, - ) - - options = { - "output": tmp_path / "batch.h5", - "executor": Batch(3), - "reductions": [scans.custom("captured", reduce, (), "J")], - "progress": "none", - } - result = run_scan(scan, builder, **options) - assert result.status.tolist() == ["done", "failed", "done"] - assert "deliberate member reduction failure" in str(result.point(1)["error"]) - assert len(str(result.point(1)["configuration_hash"])) == 64 - assert not any(name.startswith("fields/") for name in result.point(1)) - # And it really was one batch of three, not three points that fell back to - # running on their own: the failure test would pass either way otherwise. - metadata = cast("Mapping", result.point(1)["metadata"]) - assert metadata["backend"]["settings"]["batch_size"] == 3 - assert metadata["modal"] is not None - fail[0] = False - assert ( - run_scan(scan, builder, retry_failed=True, **options).status.tolist() - == ["done"] * 3 - ) - - # --------------------------------------------------- the two end-to-end systems WEAK = { diff --git a/tests/driver/test_moving_guide.py b/tests/driver/test_moving_guide.py index 31b6e5479..8d0d06779 100644 --- a/tests/driver/test_moving_guide.py +++ b/tests/driver/test_moving_guide.py @@ -51,11 +51,9 @@ ) from solprop.backends import select from solprop.backends.numpy_ref.backend import NumpyRefBackend -from solprop.backends.numpy_ref.batch import NumpyBatchBackend from solprop.constants import C from solprop.driver import Simulation, prop_gnlse from solprop.exceptions import ( - BackendError, DriverError, ModeError, OutputError, @@ -212,22 +210,6 @@ def test_both_backends_admit_moving_maps(kinked_problem): select("native", problem, run_request, grid=simulation.grid).close() -def test_a_lockstep_batch_refuses_a_moving_guide(kinked_problem): - """The batch applies neither half of a flow, so a member carrying one is refused.""" - simulation, problem = kinked_problem - run_request = simulation._run_request() - member = NumpyRefBackend( - problem, - run_request, - grid=simulation.grid, - modes=list(simulation.modes), - profiles=None, - ) - with pytest.raises(BackendError, match="lockstep batch does not execute"): - NumpyBatchBackend([member]) - member.close() - - def test_the_modified_noise_model_is_refused_beside_a_moving_guide(kinked): """A kept-apart draw's transport through the moving flow is not measured. diff --git a/tests/driver/test_native_coupled_flow.py b/tests/driver/test_native_coupled_flow.py index 166bfe81c..8069bfb93 100644 --- a/tests/driver/test_native_coupled_flow.py +++ b/tests/driver/test_native_coupled_flow.py @@ -15,8 +15,8 @@ The strong cases' ten fixed steps against the reference are rows of the case catalogue (``tests/backends/flow_rows.py``, ``coupled flow ...``), which also guard the flow. What stays here: the split block's run, which is adaptive (#809); the actions' formation -on either route; the refusal of a step past the certificate; a native group, a batched -scan and the ledger; the entry point's ``auto`` run; and the thread count. +on either route; the refusal of a step past the certificate; the ledger; the entry +point's ``auto`` run; and the thread count. """ import subprocess @@ -49,7 +49,6 @@ ) from driver.test_coherent_capillary import run_capillary from flow_parity import UNIT, formation_bound -from march_bounds import assert_points_matched from modal_provider_cases import ( general_grid, split_guide, @@ -57,9 +56,6 @@ from sessions.runs import bare, final_field from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.registry import available -from solprop.backends.session import Start -from solprop.driver.executors import Batch, Local -from solprop.driver.scan import Scan, run_scan from solprop.exceptions import ( BackendError, GrazingIncidenceWarning, @@ -125,6 +121,10 @@ def test_the_flow_s_native_actions_are_the_reference_s_within_the_formation_boun takes the eigenbasis; the second route sets the eigenbasis limit to zero so that every bin is formed by the native scaling and squaring. """ + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + # Optional wheel: absent from the base environment. from solprop_native.backend import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] _host_flow, @@ -158,9 +158,11 @@ def test_the_flow_s_native_actions_are_the_reference_s_within_the_formation_boun native = backend._native_state shape = (fractions.size, -1, reference.n_modes, reference.n_modes) for section in range(reference.frozen.shape[0]): - measured = native.form_flow_actions(section, dz, fractions)[0] - forward = native.flow_actions_to_host(inverse=False).reshape(shape) - inverse = native.flow_actions_to_host(inverse=True).reshape(shape) + measured = _testing.form_flow_actions(native, section, dz, fractions)[0] + forward = _testing.flow_actions_to_host(native, inverse=False).reshape( + shape + ) + inverse = _testing.flow_actions_to_host(native, inverse=True).reshape(shape) for slot, fraction in enumerate(fractions): if fraction == 0.0: continue @@ -206,68 +208,6 @@ def test_a_step_longer_than_the_certificate_is_refused_by_name_on_native(): final_field(backend, problem, bare(run_request), ended=True, owns=True) -def test_a_native_group_admits_a_coupled_flow(): - """A coupled flow runs in a native group (SEP 47 section 6.7): each member's flow - is its own session's, so nothing of its step is fused. The members' numerics are - held to their lone sessions in ``native/tests/test_coupled_flow.py``.""" - from solprop_native.group import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] - NativeGroupSession, - refusal, - ) - - from solprop.backends.sessions import start_group # noqa: PLC0415 - - simulation = capillary(wall=CoherentWall(), energy=ENERGY, pressure=PRESSURE) - problem, request = simulation.translate(), simulation._run_request() - problems, requests = [problem] * 2, [request] * 2 - starts = [Start.entrance(problem) for _ in range(2)] - assert refusal(problems, requests, starts) is None - members = [ - native_class()( - problem, - request, - grid=simulation.grid, - modes=simulation.modes, - profiles=simulation.profiles, - ) - for _ in range(2) - ] - group = start_group(members, problems, requests, starts) - try: - assert isinstance(group, NativeGroupSession) - finally: - group.close() - - -def _scan_point(point): - """Return one point of a power scan of the scalar wall, natively.""" - return capillary( - wall=CoherentWall(), backend="native", energy=1e-9 * point.values["power"] - ) - - -def test_a_batched_scan_of_coupled_flows_runs_as_the_local_loop(tmp_path): - """A batched scan groups coupled-flow points into one native group, and each - point is the local loop's to the matched-march bound (SEP 25).""" - scan = Scan("coupled", power=[1.0, 2.0]) - local = run_scan( - scan, - _scan_point, - output=tmp_path / "local.h5", - executor=Local(), - progress="none", - ) - batched = run_scan( - scan, - _scan_point, - output=tmp_path / "batch.h5", - executor=Batch(2), - progress="none", - ) - assert local.status.tolist() == batched.status.tolist() == ["done"] * 2 - assert_points_matched(batched, local, scan, _scan_point, what="batch member") - - def test_the_flow_s_ledger_rows_are_its_views_and_zero_elsewhere(): """Every persistent flow View appears in the ledger at its real byte cost.""" case = taper_gradient() diff --git a/tests/driver/test_native_flow_marches.py b/tests/driver/test_native_flow_marches.py index c7f66d3d2..7b58a9165 100644 --- a/tests/driver/test_native_flow_marches.py +++ b/tests/driver/test_native_flow_marches.py @@ -36,6 +36,7 @@ native = pytest.importorskip("solprop_native") backend_module = pytest.importorskip("solprop_native.backend") +_testing = pytest.importorskip("solprop_native._core")._testing pytestmark = [ pytest.mark.filterwarnings(f"ignore::{category.__module__}.{category.__name__}") @@ -109,9 +110,9 @@ def test_the_flow_s_actions_are_the_reference_s_within_the_formation_bound( state = backend._native_state shape = (fractions.size, -1, reference.n_modes, reference.n_modes) for section in range(reference.frozen.shape[0]): - measured = state.form_flow_actions(section, dz, fractions)[0] - forward = state.flow_actions_to_host(inverse=False).reshape(shape) - inverse = state.flow_actions_to_host(inverse=True).reshape(shape) + measured = _testing.form_flow_actions(state, section, dz, fractions)[0] + forward = _testing.flow_actions_to_host(state, inverse=False).reshape(shape) + inverse = _testing.flow_actions_to_host(state, inverse=True).reshape(shape) for slot, fraction in enumerate(fractions): if fraction == 0.0: continue @@ -202,11 +203,11 @@ def test_the_formed_actions_are_the_reference_s_on_either_route( backend = native.NativeBackend(problem, run_request, grid=simulation.grid) try: state = backend._native_state - state.form_flow_actions(0, length, fractions) - forward = state.flow_actions_to_host(inverse=False).reshape( + _testing.form_flow_actions(state, 0, length, fractions) + forward = _testing.flow_actions_to_host(state, inverse=False).reshape( count, n_active, n_modes, n_modes ) - inverse = state.flow_actions_to_host(inverse=True).reshape( + inverse = _testing.flow_actions_to_host(state, inverse=True).reshape( count, n_active, n_modes, n_modes ) finally: diff --git a/tests/driver/test_native_flow_pathological.py b/tests/driver/test_native_flow_pathological.py index 012089526..691cf209f 100644 --- a/tests/driver/test_native_flow_pathological.py +++ b/tests/driver/test_native_flow_pathological.py @@ -60,6 +60,7 @@ solprop_native = pytest.importorskip("solprop_native") NativeBackend = solprop_native.NativeBackend native_backend = pytest.importorskip("solprop_native.backend") +_testing = pytest.importorskip("solprop_native._core")._testing def scalar_case(): @@ -95,10 +96,12 @@ def formed(monkeypatch, problem, run_request, grid, held, dz): n_modes = held.vectors.shape[-1] tableau = run_request.stepper.tableau fractions = np.array([*(float(node) for node in tableau.nodes), 1.0]) - measured = np.asarray(native.form_flow_actions(0, dz, fractions)[0]) + measured = np.asarray(_testing.form_flow_actions(native, 0, dz, fractions)[0]) shape = (fractions.size, -1, n_modes, n_modes) - forward = native.flow_actions_to_host(inverse=False).reshape(shape)[-1] - inverse = native.flow_actions_to_host(inverse=True).reshape(shape)[-1] + forward = _testing.flow_actions_to_host(native, inverse=False).reshape(shape)[ + -1 + ] + inverse = _testing.flow_actions_to_host(native, inverse=True).reshape(shape)[-1] return forward, inverse, measured finally: backend.close() diff --git a/tests/driver/test_native_flow_session.py b/tests/driver/test_native_flow_session.py index a0fdb75f1..23d388805 100644 --- a/tests/driver/test_native_flow_session.py +++ b/tests/driver/test_native_flow_session.py @@ -54,7 +54,15 @@ ten_step_bound, ) from sessions.executors import IDENTITY, Started, drive, entrance -from sessions.runs import bare, final_field, load_native, to_planes +from sessions.runs import ( + bare, + final_field, + load_native, + native_adams_rows, + native_adams_start, + native_exponential_trial, + to_planes, +) from sessions.runs import run as run_session from solprop.backends.events import ObservationReady, Outcome from solprop.backends.exponential import carrier_reference @@ -93,6 +101,7 @@ NativeBackend = pytest.importorskip("solprop_native").NativeBackend DEVICE = pytest.importorskip("solprop_native").build_info().device_backend != "none" +_testing = pytest.importorskip("solprop_native._core")._testing """Whether the installed build executes on an accelerator, which holds no host channel rows and refuses the carrier frame.""" @@ -330,10 +339,10 @@ def test_a_bin_off_the_route_past_thirty_squarings_is_refused_by_name( def _resident(simulation: Simulation, problem: Any, request: Any) -> Any: """Return a native backend whose resident Adams engine can take a trial directly. - The engine's trial (``_ResidentAdams.exponential_trial``) is called with no march - around it, as solprop's host march called it before SEP 47 phase 5 retired that - march: the state is the launch, loaded into the native state, and every history - row holds the launch's sample (the engine's own ``start``), so a trial of any + The engine's trial (:func:`sessions.runs.native_exponential_trial`, the private + test module's ``adams_exponential_trial_at``) is taken with no march around it: + the state is the launch, loaded into the native state, and every history row holds + the launch's sample (:func:`sessions.runs.native_adams_start`), so a trial of any order reads a full, finite history. A trial's flow and moments depend on its step, its width and the operator alone, not on the history it reads. """ @@ -348,10 +357,10 @@ def _resident(simulation: Simulation, problem: Any, request: Any) -> Any: assert type(engine).__name__ == "_ResidentAdams" field = np.ascontiguousarray(problem.initial.field0, dtype=np.complex128) load_native(backend, field, clear_fsal=False) - engine.start(0.0) + native_adams_start(backend, 0.0) rows = { name: np.broadcast_to(row[:1], row.shape).copy() - for name, row in engine.snapshot_rows().items() + for name, row in native_adams_rows(backend).items() } engine.load_rows(rows, engine.shape) return backend @@ -384,22 +393,23 @@ def _block_departure( """ engine, state = backend._resident, backend._native_state nodes, slots = _stencil(order) - norms = engine.exponential_trial(z, dz, nodes, slots, order, [order]) + norms, shift = native_exponential_trial( + backend, z, dz, nodes, slots, order, [order] + ) assert np.all(np.isfinite(norms)) count = trial_tables( - nodes, order, [order], compensated=engine.compensated, helpers=engine.helpers + nodes, order, [order], compensated=engine.compensated, helpers=backend.helpers )[1].shape[0] - shift = engine._trial_carrier assert bool(shift.size) is carrier expected = coupled_moments( - state.adams_exponent_to_host().reshape(1, *shape), + _testing.adams_exponent_to_host(state).reshape(1, *shape), count, block, dz, carrier=np.full((1, 1, 1, 1), 1j * float(shift[0])) if carrier else None, ) active = int(np.count_nonzero(block.active)) - native = state.adams_block_to_host().reshape(-1, active, shape[0], shape[0]) + native = _testing.adams_block_to_host(state).reshape(-1, active, shape[0], shape[0]) pairs = [(native[0], expected.flow_matrix)] + [ (native[k + 1], expected.matrices[k]) for k in range(count) ] @@ -537,15 +547,15 @@ def test_a_carry_past_thirty_squarings_is_refused_and_keeps_the_state( engine, state = backend._resident, backend._native_state assert engine.compensated dz = float(steps[0]) - field, rows = state.field_to_host().copy(), engine.snapshot_rows() + field, rows = state.field_to_host().copy(), native_adams_rows(backend) nodes, slots = _stencil(2) with pytest.raises(BackendError, match="a history sample's carry"): - engine.exponential_trial(dz, dz, nodes, slots, 2, [2]) + native_exponential_trial(backend, dz, dz, nodes, slots, 2, [2]) assert state.field_to_host().tobytes() == field.tobytes() - for name, row in engine.snapshot_rows().items(): + for name, row in native_adams_rows(backend).items(): assert row.tobytes() == rows[name].tobytes(), name nodes, slots = _stencil(1) - norms = engine.exponential_trial(dz, dz, nodes, slots, 1, [1]) + norms, _ = native_exponential_trial(backend, dz, dz, nodes, slots, 1, [1]) assert np.all(np.isfinite(norms)) finally: backend.close() diff --git a/tests/driver/test_native_march_lifecycle.py b/tests/driver/test_native_march_lifecycle.py index 61101ee41..e41bce8c2 100644 --- a/tests/driver/test_native_march_lifecycle.py +++ b/tests/driver/test_native_march_lifecycle.py @@ -57,6 +57,7 @@ backend_module = pytest.importorskip("solprop_native.backend") NativeAdamsMarch = backend_module._NativeAdamsMarch NativeSession = pytest.importorskip("solprop_native.session").NativeSession +_testing = pytest.importorskip("solprop_native._core")._testing def with_fault(monkeypatch, stage: str, after: int, category: str) -> list[Any]: @@ -69,7 +70,9 @@ def with_fault(monkeypatch, stage: str, after: int, category: str) -> list[Any]: def arming(self): configure(self) if not armed: - self._backend._native_state.adams_march_fault(stage, after, category) + _testing.adams_march_fault( + self._backend._native_state, stage, after, category + ) armed.append(self) monkeypatch.setattr(NativeAdamsMarch, "_configure", arming) diff --git a/tests/driver/test_native_moving_guide_bound.py b/tests/driver/test_native_moving_guide_bound.py index c86322f27..4c721d806 100644 --- a/tests/driver/test_native_moving_guide_bound.py +++ b/tests/driver/test_native_moving_guide_bound.py @@ -32,7 +32,7 @@ bound_kinked, bound_step_problem, ) -from sessions.runs import load_native +from sessions.runs import load_native, native_adams_rows, native_adams_start from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.backend import _general_maps from solprop.stepper import Multistep @@ -87,8 +87,8 @@ def source_at(implementation, problem, run_request, grid, positions): sources = [] for z in positions: load_native(backend, state, clear_fsal=False) - engine.start(float(z)) - sources.append(np.array(engine.snapshot_rows()["store"][0])) + native_adams_start(backend, float(z)) + sources.append(np.array(native_adams_rows(backend)["store"][0])) return sources finally: backend.close() diff --git a/tests/driver/test_native_rk_march.py b/tests/driver/test_native_rk_march.py index 2047b254d..11f5f5c25 100644 --- a/tests/driver/test_native_rk_march.py +++ b/tests/driver/test_native_rk_march.py @@ -46,6 +46,7 @@ "native" not in available(), reason="native is not installed" ) backend_module = pytest.importorskip("solprop_native.backend") +_testing = pytest.importorskip("solprop_native._core")._testing ROUTED = ( "gnlse", @@ -175,7 +176,9 @@ def test_a_z_table_s_staged_trial_is_the_host_packed_trial(): for z in (0.0, 0.37 * end, 0.8 * end): dz = 0.01 * end staged = native_trial(backend, z, dz) - stages = [np.array(state.stage_to_host(i)) for i in range(len(nodes))] + stages = [ + np.array(_testing.stage_to_host(state, i)) for i in range(len(nodes)) + ] held = anchor(problem, z, helpers=backend.helpers) *bundles, whole = scalars_at( problem, @@ -185,10 +188,10 @@ def test_a_z_table_s_staged_trial_is_the_host_packed_trial(): helpers=backend.helpers, ) arrays, material = backend._trial_arrays(bundles, whole) - packed = np.asarray(state.trial_step(dz, *arrays, material)) + packed = np.asarray(_testing.trial_step(state, dz, *arrays, material)) assert staged.tobytes() == packed.tobytes(), z for index, stage in enumerate(stages): - assert np.array(state.stage_to_host(index)).tobytes() == ( + assert np.array(_testing.stage_to_host(state, index)).tobytes() == ( stage.tobytes() ), (z, index) assert np.max(np.abs(stages[-1])) > 0.0 diff --git a/tests/driver/test_native_z_table.py b/tests/driver/test_native_z_table.py index 0635ce503..66eaf4105 100644 --- a/tests/driver/test_native_z_table.py +++ b/tests/driver/test_native_z_table.py @@ -9,7 +9,7 @@ (``taper_coupling=False``), whose expansion does not resolve the kinked taper; a radial run through three species on independent density paths, more than the two-parameter expansion takes; optmat's dry air falling to vacuum, three populations on -a modal guide; and a ``Batch`` of moving-dispersion fibres. The moving dispersion and +a modal guide; and moving-dispersion fibres of three areas. The moving dispersion and the temperature-path fill are in ``tests/driver/test_specified_paths.py`` and ``tests/driver/test_temperature_paths.py``, a forced table and a table prefactor in ``tests/backends/test_native_z_table.py``. Ten fixed steps of each march, the native @@ -21,8 +21,6 @@ import copy import dataclasses import warnings -from contextlib import ExitStack -from typing import Any import numpy as np import pytest @@ -39,12 +37,6 @@ simulation_bound, ) from optmat_parity_cases import variant -from solprop.backends import select -from solprop.backends.events import ObservationReady -from solprop.backends.export import ExportRecipe -from solprop.backends.protocol import stepping -from solprop.backends.session import Start -from solprop.backends.sessions import start_group from solprop.driver import Simulation, SimulationSettings from solprop.exceptions import MaterialRangeWarning from solprop.grid import EnvelopeGrid, FieldGrid, RadialGrid @@ -191,7 +183,7 @@ def test_dry_air_falling_to_vacuum(integrator): def fibre(index, backend): - """Return member `index` of a moving-dispersion batch, its own area and power.""" + """Return the moving-dispersion fibre `index`, its own area and power.""" grid = EnvelopeGrid.from_limits(FIBRE_LENGTH, 835e-9, (600e-9, 1300e-9), 2e-12) schedule = FixedSchedule.uniform( 0.0, FIBRE_LENGTH, FIBRE_LENGTH / 4, save_planes=[FIBRE_LENGTH] @@ -213,72 +205,10 @@ def fibre(index, backend): ) -def loaded(simulation, cleanup): - """Return the simulation's backend, loaded at the entrance and closed at exit.""" - problem = simulation.translate() - run_request = simulation._run_request() - owner = select( - simulation.settings.backend, - problem, - run_request, - grid=simulation.grid, - modes=simulation.modes, - profiles=simulation.profiles, - ) - cleanup.callback(owner.close) - stepping(owner).set_initial(problem.initial.field0, simulation.noise) - return owner - - -def test_a_batch_of_z_table_members(): - # The native group runs each member's native session on its own tables (SEP 47 - # section 6.7), each member within the march's bound of the reference. - identity = ExportRecipe(power=False, optics=False) - with ExitStack() as cleanup: - members = [fibre(index, "native") for index in range(3)] - problems = [one.translate() for one in members] - assert not problems[0].device_ready - owners = [ - select( - one.settings.backend, - problem, - one._run_request(), - grid=one.grid, - modes=one.modes, - profiles=one.profiles, - ) - for one, problem in zip(members, problems, strict=True) - ] - for owner in owners: - cleanup.callback(owner.close) - group = start_group( - owners, - problems, - [one._run_request() for one in members], - [Start.entrance(problem) for problem in problems], - ) - cleanup.callback(group.close) - assert type(group).__name__ == "NativeGroupSession" - fields: dict[int, np.ndarray] = {} - while not group.finished: - batch = group.advance() - for index, events in enumerate(batch.members): - for event in events: - if isinstance(event, ObservationReady): - fields[index] = np.array( - group.export(index, event.ticket, identity) - ) - group.acknowledge(batch.receipt) - for index, member in enumerate(members): - reference: Any = loaded(on(member, "numpy_ref"), cleanup) - reference.propagate_to(FIBRE_LENGTH) - bound = simulation_bound(member, backend="native") - assert_matched( - fields[index], - reference.observe().require_field(), - bound, - what=f"member {index}", - ) +@pytest.mark.parametrize("index", range(3)) +def test_moving_dispersion_fibres_on_the_z_table(index): + # Each fibre's own tables, each within the march's bound of the reference. + assert_native_matches(fibre(index, "numpy_ref")) DENSE = pytest.mark.parametrize( diff --git a/tests/driver/test_run.py b/tests/driver/test_run.py index 85d877505..af0319d2e 100644 --- a/tests/driver/test_run.py +++ b/tests/driver/test_run.py @@ -33,7 +33,7 @@ from solprop.backends.session import Start from solprop.driver import Simulation, SimulationSettings, metadata_for, run_problem from solprop.driver.run import history_of, plane_from_observation -from solprop.exceptions import BackendError, DriverError +from solprop.exceptions import DriverError from solprop.grid import EnvelopeGrid from solprop.log import NullReporter from solprop.nonlinear.gnlse import problem_from @@ -136,7 +136,6 @@ class NullBackend: """ name = "null" - max_batch = 1 reads_transverse_edge = False in_flight = None @@ -165,9 +164,6 @@ def prepare(self, problem, request): # Every refusal this double reaches fires before the run is prepared. raise AssertionError("the null backend prepares no run") - def prepare_group(self, members, problems, requests): - raise BackendError("the null backend runs no group") - def set_initial(self, field, noise, *, z=0.0, resume=False): pass diff --git a/tests/driver/test_scan_batch.py b/tests/driver/test_scan_batch.py deleted file mode 100644 index e19d7e60b..000000000 --- a/tests/driver/test_scan_batch.py +++ /dev/null @@ -1,472 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""Exercise public batch dispatch with ordinary scan output and member provenance.""" - -import contextlib -import json -from collections.abc import Mapping -from functools import partial -from typing import Literal, cast - -import h5py -import numpy as np -import pytest - -from legacy_geometry import LEGACY_GRID, bare_absorber -from march_bounds import FIXED_ORDER, assert_points_matched -from solprop.backends.host.driver import HostDriver -from solprop.backends.host.group import HostGroup -from solprop.backends.numpy_ref.backend import NumpyRefBackend -from solprop.backends.numpy_ref.batch import NumpyBatchBackend -from solprop.backends.registry import resolve_name -from solprop.driver import Simulation, _scan_batch -from solprop.driver._scan_run import launch_statistics -from solprop.driver.executors import Batch, Local -from solprop.driver.scan import Scan, run_scan -from solprop.exceptions import DriverError, OutputError -from solprop.grid import EnvelopeGrid -from solprop.output.hdf5 import _dataset -from solprop.processing import scans -from solprop.stats import StatsSpec -from solprop.stepper import FixedSchedule - - -def build(point, backend="numpy_ref", noise: Literal["input", "modified"] = "modified"): - # The former grid without a collar: a short fixed schedule is refused beside the - # default collar, and these tests are about batched scans, not boundaries. - grid = EnvelopeGrid.from_limits(0.001, 835e-9, (500e-9, 2e-6), 1e-12, **LEGACY_GRID) - return Simulation.from_gnlse( - 0.11 * (point.index + 1), - 0.001, - [0.0, 0.0, -1.183e-26 * (point.index + 1)], - wavelength=835e-9, - grid=grid, - absorber=bare_absorber(grid), - width=100e-15, - peak_power=float(point.index + 1), - shape="sech", - save_planes=[0.0005, 0.001], - schedule=FixedSchedule.uniform( - 0.0, 0.001, 0.00025, save_planes=[0.0005, 0.001] - ), - stats=StatsSpec(names=("energy", "peak_power"), periodic=("energy",), period=2), - noise=noise, - seed=point.seed, - # The fixed order leaves no controller decision on the prescribed schedule, so - # a batch member and its solo run are one discrete march (SEP 25 4.4). - integrator=FIXED_ORDER, - backend=backend, - ) - - -def test_a_field_reduction_without_kept_fields_matches_local_in_a_batch(tmp_path): - """A batched point's field capture has the trajectory's shape, every axis of it. - - The capture is retained at ``problem.shape``, ``(n_modes, n_pol, n_omega)``: one - axis short and a field reduction refuses the plane it is handed (SEP 47 section - 6.2 removed the batch axis that slice once dropped). - """ - scan = Scan("batch", base_seed=772, power=[1.0, 2.0]) - options = { - "fields": "none", - "progress": "none", - "reductions": [scans.field_at_plane()], - } - reference = run_scan( - scan, build, output=tmp_path / "local.h5", executor=Local(), **options - ) - result = run_scan( - scan, build, output=tmp_path / "batch.h5", executor=Batch(2), **options - ) - assert reference.status.tolist() == result.status.tolist() == ["done"] * 2 - for point in scan.points(): - shape = build(point).translate().shape - reduced = np.asarray(result.point(point.index)["reduced/field_at_plane"]) - assert reduced.shape[-3:] == shape - assert_points_matched(result, reference, scan, build, what="batch member") - - -@pytest.mark.parametrize("backend", ["numpy_ref", "native", "auto"]) -@pytest.mark.parametrize("size", [1, 2, 3]) -def test_batch_scan_matches_local_with_partial_groups(tmp_path, backend, size): - if backend == "native": - pytest.importorskip("solprop_native") - scan = Scan("batch", base_seed=772, power=[1.0, 2.0, 3.0]) - builder = partial(build, backend=backend) - executor = Batch(size) - options = { - "fields": "planes", - "field_planes": [-1], - "progress": "none", - "reductions": [scans.peak_power()], - } - reference = run_scan( - scan, builder, output=tmp_path / "local.h5", executor=Local(), **options - ) - result = run_scan( - scan, builder, output=tmp_path / "batch.h5", executor=executor, **options - ) - assert result.status.tolist() == ["done"] * 3 - # Not bitwise: a batch's lockstep reductions and thread layout may order sums - # differently from the member run alone. - assert_points_matched(result, reference, scan, builder, what="batch member") - assert executor.budgets - for budget in executor.budgets: - admitted, peak, limit = ( - budget["admitted"], - budget["estimated_peak"], - budget["limit"], - ) - assert admitted is not None and admitted >= 1 - assert peak is not None and limit is not None - assert peak <= limit * 4 // 5 - with h5py.File(tmp_path / "batch.h5", "r") as file: - for index in range(3): - recorded = json.loads(_dataset(file, "points/backend")[index]) - assert recorded["name"] == resolve_name(backend) - assert recorded["settings"]["batch_size"] <= size - run_scan(scan, builder, output=tmp_path / "batch.h5", executor=executor, **options) - assert executor.budgets == [] - - -@pytest.mark.parametrize("noise", ["input", "modified"]) -def test_a_noisy_native_batch_runs_in_the_native_group(tmp_path, noise): - """A Batch scan's noisy native members run in the native group session (SEP 47 - section 6.7): each member's noise phase, which its plane stores, is its own - session's, the same as its point run alone; its fields agree with it. - """ - pytest.importorskip("solprop_native") - scan = Scan("batch", base_seed=772, power=[1.0, 2.0]) - builder = partial(build, backend="native", noise=noise) - reference = run_scan( - scan, - builder, - output=tmp_path / "local.h5", - executor=Local(), - fields="all", - progress="none", - ) - result = run_scan( - scan, - builder, - output=tmp_path / "batch.h5", - executor=Batch(2), - fields="all", - progress="none", - ) - assert result.status.tolist() == ["done"] * 2 - assert_points_matched(result, reference, scan, builder, what="batch member") - with ( - h5py.File(tmp_path / "local.h5", "r") as alone, - h5py.File(tmp_path / "batch.h5", "r") as batch, - ): - expected = np.asarray(alone["fields/noise_phase"]) - found = np.asarray(batch["fields/noise_phase"]) - assert found.tobytes() == expected.tobytes() - assert not np.array_equal(found[0], found[1]) - for index in range(2): - recorded = json.loads(_dataset(batch, "points/backend")[index]) - assert recorded["settings"]["batch_strategy"] == "native_group_session" - - -@pytest.mark.parametrize("size", [0, -1, True]) -def test_batch_rejects_invalid_size(size): - with pytest.raises(DriverError, match="positive integer"): - Batch(size) - - -def test_batch_rejects_non_scan_work(): - with pytest.raises(DriverError, match="run_scan"): - list(Batch(2).run([1], lambda value: value)) - - -def test_batch_refuses_memory_before_backend_construction(tmp_path, monkeypatch): - constructed = [] - monkeypatch.setattr( - _scan_batch, "_construct", lambda *args: constructed.append(args) - ) - scan = Scan("batch", base_seed=772, power=[1.0]) - with pytest.raises(DriverError, match="cannot fit one member"): - run_scan( - scan, - build, - output=tmp_path / "batch.h5", - executor=Batch(2, 1), - progress="none", - ) - assert constructed == [] - - -def test_batch_refuses_mixed_backend_scan(tmp_path): - def mixed(point): - return build(point, "numpy_ref" if point.index == 0 else "native") - - scan = Scan("batch", base_seed=772, power=[1.0, 2.0]) - with pytest.raises(DriverError, match="mixed backends"): - run_scan( - scan, - mixed, - output=tmp_path / "batch.h5", - executor=Batch(2), - progress="none", - ) - - -@pytest.mark.parametrize("free_fraction", [0, 1]) -def test_batch_device_budget_refuses_or_splits_before_group_allocation( - tmp_path, monkeypatch, free_fraction -): - monkeypatch.setattr( - NumpyRefBackend, - "available_device_memory", - lambda self: free_fraction * sum(self.memory_ledger().values()), - ) - scan = Scan("device_budget", base_seed=313, power=[1.0, 2.0, 3.0]) - executor = Batch(3) - options = { - "output": tmp_path / "budget.h5", - "executor": executor, - "progress": "none", - } - if free_fraction == 0: - with pytest.raises(DriverError, match="cannot fit one member"): - run_scan(scan, build, **options) - assert executor.budgets[0]["admitted"] == 0 - else: - result = run_scan(scan, build, **options) - assert result.status.tolist() == ["done"] * 3 - assert executor.budgets[0]["admitted"] == 1 - assert executor.budgets[0]["host_admitted"] == 3 - - -def _total_energy(output): - return np.asarray(output["stats/energy"][-1].sum()) - - -# Three planes: the entrance and two more. A built-in reduction of a field reads its -# target plane, and a custom one reads every plane unless it says it reads none. -FIELDS_ASKED = { - "no field": ({"fields": "none"}, [False, False, False]), - "one plane": ({"fields": "planes", "field_planes": [-1]}, [False, False, True]), - "the entrance": ({"fields": "planes", "field_planes": [0]}, [True, False, False]), - "every plane": ({"fields": "all"}, [True, True, True]), - "a built-in's plane": ( - {"fields": "none", "reductions": [scans.peak_power(plane=1)]}, - [False, True, False], - ), - "a custom reduction": ( - { - "fields": "none", - "reductions": [scans.custom("energy", _total_energy, (), "J")], - }, - [True, True, True], - ), - "a statistics reduction": ( - { - "fields": "none", - "reductions": [ - scans.custom("energy", _total_energy, (), "J", reads_fields=False) - ], - }, - [False, False, False], - ), -} - - -@pytest.mark.parametrize("backend", ["numpy_ref", "native"]) -@pytest.mark.parametrize( - ("options", "asked"), FIELDS_ASKED.values(), ids=FIELDS_ASKED.keys() -) -def test_a_batch_asks_its_members_only_for_the_fields_the_scan_reads( - tmp_path, monkeypatch, backend, options, asked -): - # solprop #299: a plane no one reads moves no member's field, and what the scan - # stores is what the same points store run alone, under the same rule. - if backend == "native": - pytest.importorskip("solprop_native") - scan = Scan("field_free", base_seed=772, power=[1.0, 2.0, 3.0]) - builder = partial(build, backend=backend) - keywords = {"progress": "none", **options} - reference = run_scan( - scan, builder, output=tmp_path / "local.h5", executor=Local(), **keywords - ) - fields = [] - # The reference's group; a native group has no member-axis observation. - - def spy(self, *, field=True, original=HostGroup.observe_members): - fields.append(field) - return original(self, field=field) - - monkeypatch.setattr(HostGroup, "observe_members", spy) - crossed = [] - - # Every member observation of the reference's driver, through the group or - # alone; the native session never observes through a driver. - def observed(self, *, field=True, original=HostDriver.observe): - crossed.append(field) - return original(self, field=field) - - monkeypatch.setattr(HostDriver, "observe", observed) - exported = [] - if backend == "native": - # The noisy native members run in the native group session (SEP 47 section - # 6.7), each member's field exported through its own native session. - group = pytest.importorskip("solprop_native.group").NativeGroupSession - - def exporting(self, member, ticket, recipe, out=None, original=group.export): - exported.append(member) - return original(self, member, ticket, recipe, out) - - monkeypatch.setattr(group, "export", exporting) - result = run_scan( - scan, builder, output=tmp_path / "batch.h5", executor=Batch(3), **keywords - ) - assert result.status.tolist() == ["done"] * 3 - # The group drains each member's attempts field-free, member by member, and - # fetches the members' fields of a plane only when the scan reads it. - if backend == "native": - assert fields == [] - assert crossed.count(True) == 0 - assert sorted(exported) == sorted([0, 1, 2] * sum(asked)) - else: - assert fields == [True] * sum(asked) - assert crossed.count(True) == 3 * sum(asked) - assert_points_matched(result, reference, scan, builder, what="batch member") - - -def test_batch_custom_reducer_failure_isolated_and_retryable(tmp_path): - scan = Scan("batch", base_seed=772, power=[1.0, 2.0, 3.0]) - fail = [True] - - def reduce(output): - assert output.n_saved == 3 - assert output.fields().shape[0] == 3 - assert output.metadata is not None - assert output.metadata.noise is not None - if fail[0] and output.metadata.noise.seed == scan.point(1).seed: - raise RuntimeError("deliberate member reduction failure") - return np.asarray(output["stats/energy"][-1].sum()) - - options = { - "output": tmp_path / "batch.h5", - "executor": Batch(3), - "reductions": [scans.custom("energy", reduce, (), "J")], - "progress": "none", - } - result = run_scan(scan, build, **options) - assert result.status.tolist() == ["done", "failed", "done"] - assert "deliberate member reduction failure" in str(result.point(1)["error"]) - failed = result.point(1) - assert len(str(failed["configuration_hash"])) == 64 - metadata = cast(Mapping, failed["metadata"]) - assert metadata["noise"]["seed"] == scan.point(1).seed - assert metadata["backend"]["settings"]["batch_size"] == 3 - assert not any(name.startswith(("fields/", "stats/")) for name in failed) - assert "fields/values" not in result.point(0) - fail[0] = False - result = run_scan(scan, build, retry_failed=True, **options) - assert result.status.tolist() == ["done"] * 3 - - -def test_batch_plane_capture_failure_isolated_before_later_planes( - tmp_path, monkeypatch -): - scan = Scan("capture_failure", base_seed=772, power=[1.0, 2.0, 3.0]) - original = _scan_batch._Capture.save - calls = [] - - def capture(self, plane): - assert self.metadata is not None and self.metadata.noise is not None - seed = self.metadata.noise.seed - calls.append(seed) - if seed == scan.point(1).seed: - raise OutputError("member capture unavailable") - return original(self, plane) - - monkeypatch.setattr(_scan_batch._Capture, "save", capture) - result = run_scan( - scan, build, output=tmp_path / "scan.h5", executor=Batch(3), progress="none" - ) - assert result.status.tolist() == ["done", "failed", "done"] - assert calls.count(scan.point(1).seed) == 1 - assert calls.count(scan.point(0).seed) == 3 - assert "member capture unavailable" in str(result.point(1)["error"]) - - -def test_batch_march_failure_preserves_each_members_provenance(tmp_path, monkeypatch): - def failed(*args): - raise RuntimeError("batch execution unavailable") - - monkeypatch.setattr(NumpyBatchBackend, "propagate_to", failed) - scan = Scan("march_failure", base_seed=772, power=[1.0, 2.0]) - result = run_scan( - scan, build, output=tmp_path / "scan.h5", executor=Batch(2), progress="none" - ) - assert result.status.tolist() == ["failed", "failed"] - for point in scan.points(): - stored = result.point(point.index) - assert "batch execution unavailable" in str(stored["error"]) - assert cast(Mapping, stored["metadata"])["noise"]["seed"] == point.seed - assert not any(isinstance(value, np.ndarray) for value in stored.values()) - - -def test_batch_builder_failure_does_not_discard_successful_members(tmp_path): - def builder(point): - if point.index == 1: - raise RuntimeError("point construction unavailable") - return build(point) - - scan = Scan("builder_failure", base_seed=772, power=[1.0, 2.0, 3.0]) - result = run_scan( - scan, builder, output=tmp_path / "scan.h5", executor=Batch(3), progress="none" - ) - assert result.status.tolist() == ["done", "failed", "done"] - - -def test_batch_requires_the_metadata_its_capture_opened_with(tmp_path, monkeypatch): - original = _scan_batch._Capture.close - - def closed(self): - original(self) - self._metadata = None - - monkeypatch.setattr(_scan_batch._Capture, "close", closed) - scan = Scan("no_metadata", base_seed=772, power=[1.0, 2.0]) - result = run_scan( - scan, build, output=tmp_path / "scan.h5", executor=Batch(2), progress="none" - ) - assert result.status.tolist() == ["failed", "failed"] - assert "without the run metadata" in str(result.point(0)["error"]) - - -def test_batch_refuses_changed_configuration_of_completed_point(tmp_path): - scan = Scan("changed", base_seed=772, power=[1.0]) - options = {"output": tmp_path / "scan.h5", "executor": Batch(2), "progress": "none"} - run_scan(scan, build, **options) - - def changed(point): - simulation = build(point) - return simulation.with_input(simulation.translate().initial.field0 * 2) - - with pytest.raises(OutputError, match="different configuration"): - run_scan(scan, changed, **options) - - -def test_a_probe_whose_launch_fails_raises_the_launch_s_own_error(monkeypatch): - # A probe's launch statistics that fail end its session with a failed terminal: - # the probe raises that error, never a bare assertion. - simulation = build(Scan("probe", base_seed=772, power=[1.0]).point(0)) - problem = simulation.translate() - - def broken(self, spec): - raise OutputError("manufactured launch statistics failure") - - monkeypatch.setattr(NumpyRefBackend, "stats", broken) - backend = _scan_batch._construct(simulation, contextlib.ExitStack()) - try: - with pytest.raises(OutputError, match="manufactured launch statistics"): - launch_statistics(backend, problem) - finally: - backend.close() diff --git a/tests/driver/test_scan_derived_noise.py b/tests/driver/test_scan_derived_noise.py index 01b5e4966..43a2e2451 100644 --- a/tests/driver/test_scan_derived_noise.py +++ b/tests/driver/test_scan_derived_noise.py @@ -22,7 +22,7 @@ ) from solprop.driver import Simulation, SimulationSettings from solprop.driver._scan_model import name_seed -from solprop.driver.executors import Batch, Local, Pool, pool +from solprop.driver.executors import Local, Pool, pool from solprop.driver.scan import Scan, run_scan from solprop.exceptions import OutputError from solprop.grid import EnvelopeGrid, RadialGrid @@ -99,7 +99,7 @@ def fresh(point): def fibre(**overrides): - """Return a fibre whose batch members and solo runs are one discrete march.""" + """Return a fibre on a fixed schedule at a fixed order: one discrete march.""" # The former grid without a collar, which a short fixed schedule is refused beside. grid = EnvelopeGrid.from_limits(FIBRE, 835e-9, (500e-9, 2e-6), 1e-12, **LEGACY_GRID) return Simulation.from_gnlse( @@ -283,38 +283,6 @@ def test_the_recipe_matches_points_built_from_nothing(tmp_path): ) -def test_one_object_under_batch_matches_local_member_for_member(tmp_path): - scan = Scan("trials", trial=[0, 1, 2]) - one_object.cache_clear() - reference = run_scan( - scan, - shared, - executor=Local(), - output=tmp_path / "local.h5", - fields="all", - progress="none", - ) - one_object.cache_clear() - result = run_scan( - scan, - shared, - executor=Batch(3), - output=tmp_path / "batch.h5", - fields="all", - progress="none", - ) - assert result.status.tolist() == ["done"] * 3 - launches = [ - cast("np.ndarray", result.point(index)["fields/values"])[0] - for index in range(3) - ] - assert not np.array_equal(launches[0], launches[1]) - assert_points_matched(result, reference, scan, shared, what="batch member") - assert recorded_seeds(tmp_path / "batch.h5") == recorded_seeds( - tmp_path / "local.h5" - ) - - def test_a_scan_leaves_the_builders_object_as_it_is(tmp_path): one_object.cache_clear() built = one_object() diff --git a/tests/driver/test_scan_kept_backend.py b/tests/driver/test_scan_kept_backend.py index f6a8e9865..3b973da3e 100644 --- a/tests/driver/test_scan_kept_backend.py +++ b/tests/driver/test_scan_kept_backend.py @@ -19,7 +19,7 @@ from legacy_geometry import LEGACY_GRID, bare_absorber from march_bounds import FIXED_ORDER, assert_points_matched -from solprop.driver import Simulation, _scan_batch, _scan_run, runner, simulation +from solprop.driver import Simulation, _scan_run, runner, simulation from solprop.driver.executors import Local, Pool from solprop.driver.scan import Scan, run_scan from solprop.grid import EnvelopeGrid @@ -192,7 +192,7 @@ def test_a_failed_point_takes_the_kept_backend_with_it( builder = partial(with_pulse, base()) reference = run_scan(SCAN, builder, output=tmp_path / "alone.h5", **OPTIONS) made.clear() - original = _scan_batch._Capture.save + original = _scan_run._Capture.save def capture(self, plane): if self.metadata.noise.seed == SCAN.point(1).seed: @@ -200,7 +200,7 @@ def capture(self, plane): original(self, plane) with monkeypatch.context() as patched: - patched.setattr(_scan_batch._Capture, "save", capture) + patched.setattr(_scan_run._Capture, "save", capture) result = run_scan(SCAN, builder, output=tmp_path / "scan.h5", **OPTIONS) assert result.status.tolist() == ["done", "failed", "done"] assert "deliberate capture failure" in str(result.point(1)["error"]) diff --git a/tests/driver/test_scan_slurm.py b/tests/driver/test_scan_slurm.py index b94c6e5e4..600b21b8a 100644 --- a/tests/driver/test_scan_slurm.py +++ b/tests/driver/test_scan_slurm.py @@ -15,7 +15,7 @@ import pytest import solprop.scan as cli -from driver.test_scan_batch import build +from builders import fixed_fibre_point as build from solprop.driver.executors import Local from solprop.driver.executors._request import ScanRequest from solprop.driver.executors.pool import Pool diff --git a/tests/driver/test_scan_stop_progress.py b/tests/driver/test_scan_stop_progress.py index ad7094f3a..a869b7d59 100644 --- a/tests/driver/test_scan_stop_progress.py +++ b/tests/driver/test_scan_stop_progress.py @@ -20,9 +20,8 @@ from march_bounds import FIXED_ORDER from solprop.backends.registry import available from solprop.backends.session import DEFAULT_WORK_LIMIT -from solprop.driver import _scan_batch from solprop.driver._scan_run import _collect, _Job, _Options, _ScanEvents, _Work -from solprop.driver.executors import Batch, Local, Queue, Slurm, pool +from solprop.driver.executors import Local, Queue, Slurm, pool from solprop.driver.executors.pool import PlaneScalars, Pool, _Channel, _WorkerReporter from solprop.driver.scan import Scan, run_scan from solprop.driver.simulation import Simulation @@ -411,69 +410,6 @@ def test_pool_stop_message_stops_the_point_in_flight(tmp_path): assert error.flag is flag -def test_batch_stops_between_groups(tmp_path): - scan = Scan("batch_stop", power=[1.0, 2.0, 3.0]) - flag = threading.Event() - reporter = StopAfterPoint(flag, index=0) - output = run_scan( - scan, - build_point, - output=tmp_path / "scan.h5", - executor=Batch(1), - progress=reporter, - stop=flag, - ) - assert output.status.tolist() == ["done", "todo", "todo"] - assert reporter.finished() == [(0, "done")] - # A batch reports a point's start only as its result is collected. - assert reporter.calls[1:3] == [ - ("point_started", 0), - ("point_finished", 0, "done", reporter.calls[2][3]), - ] - rerun = run_scan(scan, build_point, output=tmp_path / "scan.h5", executor=Batch(1)) - assert rerun.status.tolist() == ["done", "done", "done"] - - -def test_batch_gives_back_a_claimed_group_it_did_not_run(tmp_path): - flag = threading.Event() - - def build(point): - # The second member is built after the first: the flag is set before the - # group they form would run. - if point.index == 1: - flag.set() - return build_point(point) - - reporter = Recorder(watch=False) - output = run_scan( - Scan("batch_group", power=[1.0, 2.0]), - build, - output=tmp_path / "scan.h5", - executor=Batch(2), - progress=reporter, - stop=flag, - ) - assert output.status.tolist() == ["todo", "todo"] - assert reporter.finished() == [(0, "stopped"), (1, "stopped")] - - -def test_batch_stops_between_the_admitted_parts_of_a_group(tmp_path, monkeypatch): - # Admission splits a compatible group when memory holds fewer members at once. - monkeypatch.setattr(_scan_batch, "_admit", lambda group, work, executor: 1) - flag = threading.Event() - reporter = StopAfterPoint(flag, index=0) - output = run_scan( - Scan("batch_parts", power=[1.0, 2.0]), - build_point, - output=tmp_path / "scan.h5", - executor=Batch(2), - progress=reporter, - stop=flag, - ) - assert output.status.tolist() == ["done", "todo"] - assert reporter.finished() == [(0, "done"), (1, "stopped")] - - @pytest.mark.skipif( sys.platform == "win32", reason="the Queue and Slurm executors are POSIX only" ) diff --git a/tests/driver/test_scan_worker_validation.py b/tests/driver/test_scan_worker_validation.py index 70e13720f..053a049c3 100644 --- a/tests/driver/test_scan_worker_validation.py +++ b/tests/driver/test_scan_worker_validation.py @@ -13,9 +13,18 @@ import numpy as np import pytest -from driver.test_scan_batch import build +from builders import fixed_fibre_point as build +from solprop.backends.numpy_ref.backend import NumpyRefBackend +from solprop.backends.registry import select from solprop.driver import Simulation, _scan_run -from solprop.driver._scan_run import _Capture, _checked, _Job, _Options, _Work +from solprop.driver._scan_run import ( + _Capture, + _checked, + _Job, + _Options, + _Work, + launch_statistics, +) from solprop.driver.scan import Scan, run_scan from solprop.exceptions import DriverError, OutputError from solprop.output.records import SavedPlane @@ -246,3 +255,27 @@ def test_admission_counts_every_mode_of_a_retained_and_reduced_field(): build, _Options((scans.field_at_plane(),), "none", (), "none"), "worker" ) assert reduced._output_bytes(simulation, {}) == plane + count * 8 + + +def test_a_probe_whose_launch_fails_raises_the_launch_s_own_error(point, monkeypatch): + # A probe's launch statistics that fail end its session with a failed terminal: + # the probe raises that error, never a bare assertion. + simulation = build(point) + problem = simulation.translate() + + def broken(self, spec): + raise OutputError("manufactured launch statistics failure") + + monkeypatch.setattr(NumpyRefBackend, "stats", broken) + backend = select( + "numpy_ref", + problem, + simulation._run_request(), + grid=simulation.grid, + modes=simulation.modes, + ) + try: + with pytest.raises(OutputError, match="manufactured launch statistics"): + launch_statistics(backend, problem) + finally: + backend.close() diff --git a/tests/driver/test_scans.py b/tests/driver/test_scans.py index 84845f66f..e26d2d7b2 100644 --- a/tests/driver/test_scans.py +++ b/tests/driver/test_scans.py @@ -26,7 +26,7 @@ from solprop import _process from solprop.driver._scan_context import _EXECUTOR from solprop.driver._scan_model import name_seed -from solprop.driver.executors import Batch, Local, pool +from solprop.driver.executors import Local, pool from solprop.driver.executors.pool import MemoryBudget, Pool from solprop.driver.scan import Scan, run_scan from solprop.driver.simulation import Simulation @@ -202,8 +202,8 @@ def test_scan_equals_single_points_and_reruns_skip(tmp_path, executor): @pytest.mark.parametrize( "executor", - [Local(), pytest.param(Pool(2), marks=pytest.mark.medium), Batch(2)], - ids=["local", "pool", "batch"], + [Local(), pytest.param(Pool(2), marks=pytest.mark.medium)], + ids=["local", "pool"], ) def test_a_rerun_with_the_same_record_skips_and_any_change_conflicts( tmp_path, executor diff --git a/tests/driver/test_split_block.py b/tests/driver/test_split_block.py index 85ed62ae9..25d6ea51e 100644 --- a/tests/driver/test_split_block.py +++ b/tests/driver/test_split_block.py @@ -38,10 +38,8 @@ split_guide, ) from solprop.backends.numpy_ref.backend import NumpyRefBackend -from solprop.backends.numpy_ref.batch import NumpyBatchBackend from solprop.constants import C from solprop.exceptions import ( - BackendError, DriverError, OutputError, SolpropWarning, @@ -440,23 +438,6 @@ def test_zdw_is_withheld_on_a_split_block_and_admitted_on_the_plain_route( assert withheld_from(unlisted) == () -def test_a_lockstep_batch_refuses_a_member_carrying_a_coupled_flow(rotated, grid): - """The batch reimplements the step loop and applies neither half of the flow.""" - simulation = guide_simulation(rotated, grid) - problem = simulation.translate() - run_request = simulation._run_request() - member = NumpyRefBackend( - problem, - run_request, - grid=simulation.grid, - modes=list(simulation.modes), - profiles=None, - ) - with pytest.raises(BackendError, match="lockstep batch does not execute"): - NumpyBatchBackend([member]) - member.close() - - def test_a_coupled_block_names_a_reference_outside_its_channels(rotated): """The block is measured against one of the table's own channels.""" with pytest.raises(TranslationError, match="relative to one of the table's"): diff --git a/tests/driver/test_vector_raman_output.py b/tests/driver/test_vector_raman_output.py index e1aee415f..20c1b9a77 100644 --- a/tests/driver/test_vector_raman_output.py +++ b/tests/driver/test_vector_raman_output.py @@ -12,16 +12,11 @@ FIXED_ORDER, STATISTIC_FACTOR, assert_matched, - assert_points_matched, simulation_bound, ) from solprop.driver import Simulation, SimulationSettings -from solprop.driver.executors import Batch, Local -from solprop.driver.scan import Scan, run_scan -from solprop.fourier import to_internal from solprop.noise import input_noise, modified_noise from solprop.output.hdf5 import resume -from solprop.polarisation import horizontal, rotate, waveplate from solprop.stats import StatsSpec from vector_raman_cases import raman_response, vector_translation @@ -93,56 +88,3 @@ def simulation(): assert metadata.schema_version == 2 record = repr(metadata.configuration) assert "tensor_terms" in record and "rank2" in record and "isotropic" in record - - -# A native lockstep batch replays its Adams members on solprop's march, with the -# warning native/tests/test_batch.py asserts (SEP 39). -@pytest.mark.filterwarnings("ignore::solprop.exceptions.HostMarchWarning") -@pytest.mark.medium -@pytest.mark.parametrize("backend", ["numpy_ref", "native"]) -def test_jones_tensor_scan_batches_match_singletons_with_a_partial_group( - tmp_path, backend -): - if backend == "native": - pytest.importorskip("solprop_native") - problem, run_request, grid, modes = vector_translation(steps=2) - schedule, controller = run_request.stepper.schedule, run_request.stepper.controller - - def build(point): - jones = to_internal( - rotate(waveplate(np.pi / 2), float(point.values["angle"])) @ horizontal() - ) - initial = problem.initial.field0[:, :1] * jones[None, :, None] - return Simulation( - grid, - modes, - [raman_response("H2", thg=False)], - initial, - settings=SimulationSettings( - backend=backend, - density=1e25, - save_planes=[grid.length], - schedule=schedule, - integrator=FIXED_ORDER, - dz_init=grid.length / 2, - dz_max=grid.length / 2, - controller=controller, - stats=StatsSpec(names=("energy",)), - ), - ) - - scan = Scan("vector Raman Jones scan", angle=[0.0, np.pi / 8, np.pi / 4]) - outputs = [ - run_scan( - scan, - build, - output=tmp_path / f"{name}.h5", - executor=executor, - fields="planes", - field_planes=[-1], - progress="none", - ) - for name, executor in (("local", Local()), ("batch", Batch(2))) - ] - # A batch member is its singleton's march: within its rounding budget. - assert_points_matched(outputs[1], outputs[0], scan, build, what="batch member") diff --git a/tests/parity_ladder.py b/tests/parity_ladder.py index 6bcc64a68..f0c30d36a 100644 --- a/tests/parity_ladder.py +++ b/tests/parity_ladder.py @@ -331,9 +331,15 @@ def projected(backend_class: type, built: Built) -> list[np.ndarray | None]: if backend.name == "native": native_source(backend, problem.initial.field0) native = backend._native_state + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + return [ - np.array(native.projected_to_host(False)), - np.array(native.projected_to_host(True)) if embedded(problem) else None, + np.array(_testing.projected_to_host(native, False)), + np.array(_testing.projected_to_host(native, True)) + if embedded(problem) + else None, ] forward = np.fft.rfft if problem.grid_kind == "field" else np.fft.fft # The launch native loads (:func:`masked_launch`). diff --git a/tests/sessions/runs.py b/tests/sessions/runs.py index 5ed874cf6..75a434561 100644 --- a/tests/sessions/runs.py +++ b/tests/sessions/runs.py @@ -28,7 +28,10 @@ - :func:`load_native`, :func:`native_trial`, :func:`native_source`, :func:`bind_native_monitor` and :func:`native_reading` reach a native backend's state (``solprop_native._core.State``) for the kernel-level checks, as the native - session's march does. + session's march does; :func:`native_stage_rows` and :func:`native_rate_weights` + pack a trial's host rows, and :func:`native_adams_start`, :func:`native_adams_rows` + and :func:`native_exponential_trial` reach its resident Adams history, through the + private test module (``solprop_native._core._testing``). ``native/tests/session_runs.py`` is the native test root's copy of the same names. """ @@ -55,6 +58,7 @@ from solprop.driver import Simulation from solprop.monitor import BoundaryEnergies, BoundaryMonitor from solprop.stats import StatsSpec +from solprop.translate.linop import rate_weights from solprop.translate.problem import PropagationProblem from solprop.translate.run_request import RunRequest @@ -70,8 +74,13 @@ "launch_statistics", "launched", "load_native", + "native_adams_rows", + "native_adams_start", + "native_exponential_trial", + "native_rate_weights", "native_reading", "native_source", + "native_stage_rows", "native_trial", "run", "run_error", @@ -816,9 +825,13 @@ def native_source(backend: Any, field: np.ndarray, z: float = 0.0) -> np.ndarray numpy.ndarray The source, shape ``(1, n_modes, n_pol, n_omega)`` as the reference's. """ + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + state = load_native(backend, field) native_trial(backend, z, 0.0) - return np.array(state.stage_to_host(0)).reshape(1, *np.shape(field)) + return np.array(_testing.stage_to_host(state, 0)).reshape(1, *np.shape(field)) def bind_native_monitor( @@ -888,9 +901,15 @@ def native_reading( solprop.monitor.BoundaryEnergies The reading. """ + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + if field is not None: load_native(backend, field) - reading = np.asarray(backend._native_state.monitor_reading(), dtype=np.float64) + reading = np.asarray( + _testing.monitor_reading(backend._native_state), dtype=np.float64 + ) reading = reading.reshape(-1) found = reading[6:10].copy() if monitor.split else None occupancy = None @@ -903,3 +922,212 @@ def native_reading( found=found, occupancy=occupancy, ) + + +def native_stage_rows( + backend: Any, anchor: float, position: float +) -> tuple[tuple[np.ndarray, ...], dict[str, Any]]: + """Return the host-packed rows of a trial whose every stage reads `position`. + + The arrays a resident Adams trial took before the native march formed its rows + from the uploaded stage tables (SEP 39): the bundle at `position`, anchored at + `anchor`, repeated over the tableau's stages, through the backend's own packing + (``NativeBackend._trial_arrays``), with a coupled flow's section and a + frozen-residual flow's weights. The tests hold the native evaluation to them. + + Parameters + ---------- + backend : solprop_native.NativeBackend + The constructed backend. + anchor : float + The step's anchor, m. + position : float + Where every stage reads its scalars, m. + + Returns + ------- + tuple + The seven row arrays (``phi_delta`` to ``raman_rates``) and the material + record. + """ + bundle = backend._stage_scalars(anchor, position) + stages = backend.request.stepper.tableau.n_stages + arrays, material = backend._trial_arrays([bundle] * stages, bundle) + flow = backend._flow + if flow is not None: + material |= { + "flow_section": bundle.flow_section, + "flow_weights": np.empty(0, dtype=np.float64) + if flow.residual_terms is None + else np.ascontiguousarray( + np.tile(bundle.flow_weights, stages), dtype=np.float64 + ), + } + return arrays, material + + +def native_rate_weights(backend: Any, z: float, *, before: bool = False) -> np.ndarray: + """Return ``D(z)``'s weights over a native backend's ``Phi`` terms (SEP 16). + + solprop's :func:`~solprop.translate.linop.rate_weights` for a constant or an + expansion; for a z table, the rate table evaluated natively into its slot + (``table_rate_at``, SEP 29 G1), one at that slot. + + Parameters + ---------- + backend : solprop_native.NativeBackend + The constructed backend. + z : float + Position, m. + before : bool, optional + Read an interior breakpoint from the interval ending there. + + Returns + ------- + numpy.ndarray + The weights, float64. + """ + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + + tables = backend._z_tables + if tables is not None and tables.phi: + _testing.table_rate_at(backend._native_state, float(z), before) + rate = np.zeros(tables.n_phi) + rate[tables.rate_slot] = 1.0 + return rate + linear = backend._problem.linear + weights = rate_weights(linear, z, before=before, helpers=backend.helpers) + return np.ascontiguousarray(weights, dtype=np.float64) + + +def native_adams_start(backend: Any, z: float) -> None: + """Evaluate a native backend's first Adams sample at its loaded state, into row 0. + + The native march's start-up (``engines::ResidentEngine``) taken alone, for the + kernel-level checks that read one source sample: every stage row at `z` + (:func:`native_stage_rows`) and, for a compensated history, the state and rate + read on the far side of a kink (:func:`native_rate_weights`). + + Parameters + ---------- + backend : solprop_native.NativeBackend + The constructed backend, under an Adams method, its state loaded + (:func:`load_native`). + z : float + The state's position, m. + """ + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + from solprop_native.backend import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] + _envelope_errors, + ) + + state = backend._native_state + backend._hoist(z) + arrays, material = native_stage_rows(backend, z, z) + with _envelope_errors(): + _testing.adams_start(state, 0, *arrays, material=material) + if backend._resident.compensated: + _testing.adams_compensation_start(state, 0, native_rate_weights(backend, z)) + + +def native_adams_rows(backend: Any) -> dict[str, np.ndarray]: + """Return host copies of a native backend's Adams history rows, losslessly. + + Parameters + ---------- + backend : solprop_native.NativeBackend + The constructed backend, under an Adams method. + + Returns + ------- + dict of str to numpy.ndarray + Each row the engine keeps, ``(n_slots, 1, n_modes, n_pol, n_omega)``, as a + snapshot holds it. + """ + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + + state = backend._native_state + engine = backend._resident + expected = (engine.n_slots, *engine.shape) + return { + name: _testing.adams_rows_to_host(state, name).reshape(expected) + for name in state.adams_row_names() + } + + +def native_exponential_trial( + backend: Any, + z: float, + dz: float, + nodes: Sequence[float], + slots: np.ndarray, + order: int, + orders: Sequence[int], +) -> tuple[np.ndarray, np.ndarray]: + """Take one exponential Adams trial on a native backend's resident history. + + The native march's trial (``engines::ResidentEngine``) taken alone: the tables, the + stage scalars and the rate formed natively from the nodes, under the run's carrier + frame, whose packed shift and rotations are formed here as the march forms them. + + Parameters + ---------- + backend : solprop_native.NativeBackend + The constructed backend, under the exponential formulation. + z : float + The step's anchor, m. + dz : float + The step, m. + nodes : sequence of float + The history's nodes ``theta``, newest first. + slots : numpy.ndarray + The history rows the nodes name. + order : int + The corrector's order. + orders : sequence of int + The orders whose defects the trial scores. + + Returns + ------- + tuple of numpy.ndarray + The scored norms, and the packed carrier frame, empty without one. + """ + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + from solprop_native.backend import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] + _envelope_errors, + ) + + engine = backend._resident + rows = max(orders) + carrier = np.empty(0, dtype=np.float64) + reference = engine.carrier + if reference is not None and reference.active: + # (Im sigma, Re f_0, Im f_0, ...), f_t = exp(sigma (1 - theta_t)), over the + # rows read; sigma is the reference element's chord over the step (SEP 35). + shift = float(np.imag(reference.chord.exponent(z, z + dz))[0]) + spans = 1.0 - np.asarray(nodes[:rows], dtype=np.float64) + carrier = np.empty(1 + 2 * rows, dtype=np.float64) + carrier[0] = shift + carrier[1::2] = np.cos(shift * spans) + carrier[2::2] = np.sin(shift * spans) + with _envelope_errors(): + norms = _testing.adams_exponential_trial_at( + backend._native_state, + z, + dz, + np.asarray(nodes, dtype=np.float64), + np.ascontiguousarray(slots[: max(rows, order)], dtype=np.uint64), + order, + list(orders), + engine.compensated, + carrier, + ) + return np.asarray(norms, dtype=np.float64).reshape(-1), carrier diff --git a/tests/sessions/test_group.py b/tests/sessions/test_group.py deleted file mode 100644 index ac98ed277..000000000 --- a/tests/sessions/test_group.py +++ /dev/null @@ -1,946 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""The group protocol (SEP 47 section 6.7), on the reference's group and the native one. - -A group advances compatible members through one fixed schedule, one common window per -save plane, and reports each member's own events. A boundary stop ends its member -alone; a non-finite norm, a trial exception or an in-flight failure ends the group, -and each member then reports its own committed position and checkpoint eligibility: -members are stepped in turn, so one ahead of the failing member has already advanced -past the failed step. - -The conformance tests run on both backends: ``numpy_ref``, whose group is its own over -its lockstep runner (:class:`~solprop.backends.host.group_session.HostGroupSession`), -and ``native``, whose group is the native group session -(:class:`solprop_native.group.NativeGroupSession`, one native session per member). -The failures that reach into the reference's Python march to inject a fault are the -reference's alone; the native group's own failure positions, with natively injected -faults, are in ``test_native_group.py``. -""" - -import warnings -from collections.abc import Sequence -from contextlib import ExitStack -from dataclasses import dataclass -from typing import Any, cast - -import numpy as np -import pytest - -from bounds import assert_within -from driver.test_field_free_planes import cartesian -from march_bounds import FIXED_ORDER -from solprop.backends import select -from solprop.backends.events import ( - Eligibility, - GroupBatch, - ObservationKind, - ObservationReady, - Outcome, - Terminal, -) -from solprop.backends.export import ExportRecipe -from solprop.backends.session import ( - GroupSession, - SessionError, - SessionState, - Start, - StopToken, -) -from solprop.backends.sessions import start_group, start_session -from solprop.driver import Simulation -from solprop.exceptions import ( - BackendError, - BoundaryError, - BoundaryWarning, - StopRequested, -) -from solprop.log import StopFlag -from solprop.monitor import BoundaryCheck, BoundaryMonitor -from solprop.stats import StatsSpec -from solprop.stepper.runge_kutta import RungeKutta -from solprop.stepper.schedule import FixedSchedule - -PLANES = (0.0005, 0.001) -"""The save planes, m: four fixed steps of 0.25 mm, two per window.""" - -STEP = 0.00025 -"""The fixed step, m.""" - -FIELD_BOUND = 4 * 16 * np.finfo(float).eps -"""The singleton ladder's 16 eps a step over four steps: a member and its lone run take -one method on one schedule and differ by the order of their reductions alone -(``tests/backends/test_batch_lockstep.py``).""" - -IDENTITY = ExportRecipe(power=False, optics=False) -CONSUMER = ExportRecipe(power=True, optics=False) - -BACKENDS = ["numpy_ref", "native"] - -STRATEGIES = { - "numpy_ref": "numpy_stage_arrays", - "native": "native_group_session", -} -"""Each group, as its members' execution records name it.""" - -GROUPS = BACKENDS -"""Every group implementation: the reference's and the native group session.""" - -LOCKSTEP = ["numpy_ref"] -"""The groups over a lockstep runner, whose runner and Python march a test patches: -the reference's alone; the native group's failures are injected natively -(``test_native_group.py``).""" - - -def member( - index: int, backend: str, integrator: Any = None, **overrides: Any -) -> Simulation: - """Return one member: a soliton-order pulse on its own fibre, on the schedule. - - `overrides` replace any of the member's settings (``Simulation.from_gnlse``). - """ - settings: dict[str, Any] = { - "wavelength": 835e-9, - "wavelength_limits": (500e-9, 2e-6), - "trange": 1e-12, - "width": 100e-15, - "peak_power": float(index + 1), - "shape": "sech", - "save_planes": list(PLANES), - "schedule": FixedSchedule.uniform(0.0, PLANES[-1], STEP, save_planes=PLANES), - "stats": StatsSpec( - names=("energy", "peak_power"), periodic=("energy",), period=2 - ), - "noise": None, - "backend": backend, - "integrator": RungeKutta() if integrator is None else integrator, - "absorber": False, - } - return Simulation.from_gnlse( - 0.11 * (index + 1), - PLANES[-1], - [0.0, 0.0, -1.183e-26 * (index + 1)], - **(settings | overrides), - ) - - -def constructed(simulation: Simulation, cleanup: ExitStack) -> Any: - """Return a member's backend, constructed and holding no state.""" - owner = select( - simulation.settings.backend, - simulation.translate(), - simulation._run_request(), - grid=simulation.grid, - modes=simulation.modes, - profiles=simulation.profiles, - ) - cleanup.callback(owner.close) - return owner - - -def group_of( - simulations: Sequence[Simulation], - cleanup: ExitStack, - *, - monitors: Sequence[BoundaryMonitor | None] | None = None, - stop: StopFlag | None = None, -) -> tuple[GroupSession, list[Any]]: - """Start a group of members at their entrances; return it and its members.""" - problems = [one.translate() for one in simulations] - owners = [constructed(one, cleanup) for one in simulations] - watched = monitors if monitors is not None else [None] * len(problems) - group = start_group( - owners, - problems, - [ - one._run_request().for_run(monitor=monitor) - for one, monitor in zip(simulations, watched, strict=True) - ], - [Start.entrance(problem) for problem in problems], - stop=stop, - ) - cleanup.callback(group.close) - return group, owners - - -def drive(group: GroupSession) -> list[GroupBatch]: - """Advance a group to its end, acknowledging each window; return every batch.""" - batches = [] - while not group.finished: - batch = group.advance() - batches.append(batch) - group.acknowledge(batch.receipt) - return batches - - -def available(backend: str) -> None: - """Skip the native executor where its package is not installed.""" - if backend == "native": - pytest.importorskip("solprop_native") - - -@pytest.mark.parametrize("backend", GROUPS) -def test_a_group_reports_each_member_s_planes_as_its_lone_run_does(backend): - available(backend) - simulations = [member(index, backend) for index in range(2)] - with ExitStack() as cleanup: - group, _ = group_of(simulations, cleanup) - assert group.n_members == 2 - fields: list[list[np.ndarray]] = [[], []] - windows: list[list[ObservationKind]] = [] - batches = [] - while not group.finished: - batch = group.advance() - batches.append(batch) - kinds = [] - for index, events in enumerate(batch.members): - for event in events: - if isinstance(event, ObservationReady): - kinds.append(event.kind) - fields[index].append( - group.export(index, event.ticket, IDENTITY).copy() - ) - # One member's own attempts: each window's chunk, once. - assert event.history.n_steps == ( - 0 if event.plane_index < 0 else 2 - ) - windows.append(kinds) - group.acknowledge(batch.receipt) - last = batches[-1] - assert last.outcome is Outcome.COMPLETED - assert last.error is None - assert all( - isinstance(events[0], Terminal) and events[0].outcome is Outcome.COMPLETED - for events in last.members - ) - for index in range(2): - status = group.member_status(index) - assert status.outcome is Outcome.COMPLETED - assert status.z == pytest.approx(PLANES[-1]) - assert status.attempts == 4 - record = group.execution_record(index) - assert record["batch_size"] == 2 - assert record["batch_strategy"] == STRATEGIES[backend] - assert windows[:3] == [ - [ObservationKind.LAUNCH] * 2, - [ObservationKind.PLANE] * 2, - [ObservationKind.PLANE] * 2, - ] - for index, simulation in enumerate(simulations): - problem = simulation.translate() - run_request = simulation._run_request() - with ExitStack() as cleanup: - owner = constructed(simulation, cleanup) - lone = start_session(owner, problem, run_request, Start.entrance(problem)) - cleanup.callback(lone.close) - alone = [] - while not lone.finished: - batch = lone.advance() - for event in batch.events: - if isinstance(event, ObservationReady): - alone.append(lone.export(event.ticket, IDENTITY).copy()) - lone.acknowledge(batch.receipt) - assert len(alone) == len(fields[index]) == 3 - for grouped, solo in zip(fields[index], alone, strict=True): - assert_within(grouped, solo, FIELD_BOUND, what=f"member {index}") - - -@pytest.mark.parametrize("backend", GROUPS) -def test_a_group_s_receipts_and_tickets_follow_the_session_lifecycle(backend): - available(backend) - with ExitStack() as cleanup: - group, _ = group_of([member(index, backend) for index in range(2)], cleanup) - launch = group.advance() - with pytest.raises(SessionError, match="acknowledge the pending batch"): - group.advance() - (event,) = launch.members[0] - assert isinstance(event, ObservationReady) - group.acknowledge(launch.receipt) - with pytest.raises(SessionError, match="not the pending batch"): - group.acknowledge(launch.receipt) - with pytest.raises(SessionError, match="has expired"): - group.export(0, event.ticket, IDENTITY) - batch = group.advance() - (plane,) = batch.members[0] - assert isinstance(plane, ObservationReady) - with pytest.raises(SessionError, match="not a member 2"): - group.export(2, plane.ticket, IDENTITY) - # Every member's ticket names one batch and one generation: each names its - # member too, and another member's is refused. - (other,) = batch.members[1] - assert isinstance(other, ObservationReady) - assert (plane.ticket.member, other.ticket.member) == (0, 1) - with pytest.raises(SessionError, match="member 0's, not member 1's"): - group.export(1, plane.ticket, IDENTITY) - with pytest.raises(SessionError, match="member 1's, not member 0's"): - group.noise_phase(0, other.ticket) - group.acknowledge(batch.receipt) - group.close() - assert group.closed - assert group.member_status(0).state is SessionState.CLOSED - group.close() - - -@pytest.mark.parametrize("backend", GROUPS) -def test_a_group_starts_its_members_fresh_and_one_start_each(backend): - available(backend) - simulations = [member(index, backend) for index in range(2)] - problems = [one.translate() for one in simulations] - with ExitStack() as cleanup: - owners = [constructed(one, cleanup) for one in simulations] - requests = [one._run_request() for one in simulations] - with pytest.raises(SessionError, match="one problem, request and start"): - start_group(owners, problems, requests, [Start.entrance(problems[0])]) - resumed = Start.entrance(problems[1]) - resumed.plane_index = 1 - with pytest.raises(SessionError, match="at their entrance"): - start_group( - owners, problems, requests, [Start.entrance(problems[0]), resumed] - ) - # The launch plane is owed: a start that has observed it is not an entrance. - observed = Start.entrance(problems[1]) - observed.plane_pending = False - with pytest.raises(SessionError, match="its launch plane owed"): - start_group( - owners, problems, requests, [Start.entrance(problems[0]), observed] - ) - - -def untouched(starts: Sequence[Start], owners: Sequence[Any]) -> list[bool]: - """Return whether each start keeps its field; assert every owner is still open.""" - assert not any(owner.closed for owner in owners) - return [start.field is not None for start in starts] - - -@pytest.mark.parametrize("backend", GROUPS) -def test_a_refused_group_leaves_the_caller_its_starts_and_backends(backend): - available(backend) - halved = FixedSchedule.uniform(0.0, PLANES[-1], STEP / 2, save_planes=PLANES) - simulations = [member(0, backend), member(1, backend, schedule=halved)] - problems = [one.translate() for one in simulations] - requests = [one._run_request() for one in simulations] - with ExitStack() as cleanup: - owners = [constructed(one, cleanup) for one in simulations] - starts = [Start.entrance(problem) for problem in problems] - with pytest.raises(BackendError, match="schedule"): - start_group(owners, problems, requests, starts) - assert untouched(starts, owners) == [True, True] - # A start already handed to a session is refused before any member loads. - starts[1].take_field() - with pytest.raises(SessionError, match="already used"): - start_group(owners, problems, requests, starts) - assert untouched(starts, owners) == [True, False] - # One start or backend for two members would alias their state. - problems, requests = problems[:1] * 2, requests[:1] * 2 - with pytest.raises(SessionError, match="its own start"): - start_group(owners[:1] * 2, problems, requests, starts[:1] * 2) - with pytest.raises(SessionError, match="its own backend"): - fresh = [starts[0], Start.entrance(problems[0])] - start_group(owners[:1] * 2, problems, requests, fresh) - assert untouched(starts, owners) == [True, False] - - -@pytest.mark.parametrize("backend", GROUPS) -def test_a_group_whose_later_member_fails_to_start_can_be_retried(backend, monkeypatch): - available(backend) - simulations = [member(index, backend) for index in range(2)] - problems = [one.translate() for one in simulations] - requests = [one._run_request() for one in simulations] - if backend == "native": - from solprop_native.session import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] - NativeSession, - ) - - constructed_sessions: list[Any] = [] - - def second_fails(*args: Any, **kwargs: Any) -> Any: - if constructed_sessions: - raise BackendError("injected: the second member cannot start") - constructed_sessions.append(NativeSession(*args, **kwargs)) - return constructed_sessions[-1] - - monkeypatch.setattr("solprop_native.group.NativeSession", second_fails) - else: - - def refused(members: Any) -> Any: - raise BackendError("injected: the runner refuses the group") - - monkeypatch.setattr("solprop.backends.registry.select_batch", refused) - with ExitStack() as cleanup: - owners = [constructed(one, cleanup) for one in simulations] - starts = [Start.entrance(problem) for problem in problems] - with pytest.raises(BackendError, match="injected"): - start_group(owners, problems, requests, starts) - assert untouched(starts, owners) == [True, True] - monkeypatch.undo() - # The same starts and backends start the group, which takes and owns them. - group = start_group(owners, problems, requests, starts) - cleanup.callback(group.close) - assert [start.field for start in starts] == [None, None] - drive(group) - group.close() - assert all(owner.closed for owner in owners) - - -@pytest.mark.parametrize("backend", GROUPS) -def test_a_schedule_past_the_last_plane_completes_without_a_step(backend): - # The completion takes no step, whatever the schedule holds beyond the last plane, - # so a stop requested after the last plane finds no step to stop at: the members - # complete there, as each would run alone. - available(backend) - schedule = FixedSchedule.uniform(0.0, 2 * PLANES[-1], STEP, save_planes=PLANES) - simulations = [member(index, backend, schedule=schedule) for index in range(2)] - token = StopToken() - with ExitStack() as cleanup: - group, _ = group_of(simulations, cleanup, stop=token) - for _ in range(len(PLANES) + 1): - window = group.advance() - group.acknowledge(window.receipt) - token.set() - completion = group.advance() - group.acknowledge(completion.receipt) - assert group.finished - assert completion.outcome is Outcome.COMPLETED - for events in completion.members: - (terminal,) = events - assert isinstance(terminal, Terminal) - assert terminal.outcome is Outcome.COMPLETED - assert terminal.z == pytest.approx(PLANES[-1]) - assert terminal.history is not None - assert terminal.history.n_steps == 0 - - -@pytest.mark.parametrize("backend", GROUPS) -def test_a_boundary_stop_ends_its_member_alone_and_the_others_go_on(backend): - # A check strict enough to refuse any launch stops the first member at once; the - # second, unwatched, runs the whole schedule (SEP 21). The reference's group - # attaches the monitors before the launch plane, as the batched scan always did, - # so the stop ends the launch window; a native member commits its launch plane - # first and its monitor then judges the launch (SEP 47 section 5.3's start), so - # the stop ends the next window, still at the launch. - available(backend) - simulations = [member(index, backend) for index in range(2)] - strict = BoundaryCheck(budget=1e-300, stop_factor=1.0) - with ExitStack() as cleanup: - group, _ = group_of( - simulations, - cleanup, - monitors=[BoundaryMonitor.build(simulations[0].grid, None, strict), None], - ) - batches = drive(group) - ended = next( - window - for window, batch in enumerate(batches) - if any(isinstance(event, Terminal) for event in batch.members[0]) - ) - (stopped,) = batches[ended].members[0] - assert isinstance(stopped, Terminal) - assert stopped.outcome is Outcome.FAILED - assert isinstance(stopped.error, BoundaryError) - assert stopped.eligibility is Eligibility.ELIGIBLE - assert (ended, stopped.z) == (1 if backend == "native" else 0, 0.0) - # The stopped member reports nothing more; the other saves every plane. - assert all(batch.members[0] == () for batch in batches[ended + 1 :]) - planes = [ - event - for batch in batches - for event in batch.members[1] - if isinstance(event, ObservationReady) - ] - assert [event.plane_index for event in planes] == [-1, 0, 1] - assert batches[-1].outcome is Outcome.COMPLETED - assert batches[-1].error is None - assert group.member_status(0).outcome is Outcome.FAILED - assert group.member_status(1).outcome is Outcome.COMPLETED - assert group.monitor_record(0) is not None - assert group.monitor_record(1) is None - - -@pytest.mark.parametrize("backend", LOCKSTEP) -def test_a_non_finite_norm_poisons_every_member_that_stepped(backend, monkeypatch): - available(backend) - # Each Adams member's march takes the replayed step before the group judges the - # norms; a refused norm leaves every member's state past its last recorded step, - # perhaps not finite: none can be resumed there (SEP 47 section 6.7). - simulations = [member(index, backend, FIXED_ORDER) for index in range(3)] - with ExitStack() as cleanup: - group, owners = group_of(simulations, cleanup) - march = owners[1]._adams - replay = march.replay_step - calls = [0] - - def poisoned(dz, end, slack): - calls[0] += 1 - norm = replay(dz, end, slack) - return float("nan") if calls[0] == 3 else norm - - monkeypatch.setattr(march, "replay_step", poisoned) - batches = drive(group) - ended = batches[-1] - assert ended.outcome is Outcome.FAILED - assert isinstance(ended.error, BackendError) - assert "member 1" in str(ended.error) - # The third step opens the second window and ends at 0.75 mm, where each march - # stands with its step unrecorded. - for events in ended.members: - (terminal,) = events - assert isinstance(terminal, Terminal) - assert terminal.outcome is Outcome.FAILED - assert terminal.error is ended.error - assert terminal.z == pytest.approx(PLANES[0] + STEP) - assert terminal.eligibility is Eligibility.POISONED - assert terminal.ticket is None - - -@pytest.mark.parametrize("backend", LOCKSTEP) -def test_a_trial_failure_partway_reports_each_member_s_own_position( - backend, monkeypatch -): - available(backend) - # Members take a replayed step in turn, so a failure in the second leaves the first - # stepped but unrecorded -- its march past the step, in flight, poisoned -- and - # the second and third untouched at the step's start: no common cursor or - # rollback is invented (SEP 47 section 6.7). - simulations = [member(index, backend, FIXED_ORDER) for index in range(3)] - with ExitStack() as cleanup: - group, owners = group_of(simulations, cleanup) - march = owners[1]._adams - replay = march.replay_step - calls = [0] - - def failing(dz, end, slack): - calls[0] += 1 - if calls[0] == 3: - msg = "a manufactured trial failure" - raise RuntimeError(msg) - return replay(dz, end, slack) - - monkeypatch.setattr(march, "replay_step", failing) - batches = drive(group) - ended = batches[-1] - assert ended.outcome is Outcome.FAILED - assert isinstance(ended.error, RuntimeError) - terminals = [events[0] for events in ended.members] - assert all(isinstance(terminal, Terminal) for terminal in terminals) - assert all(terminal.error is ended.error for terminal in terminals) # pyright: ignore[reportAttributeAccessIssue] - # The failed step is the third, from the first plane to 0.75 mm. - assert [terminal.z for terminal in terminals] == pytest.approx( - [PLANES[0] + STEP, PLANES[0], PLANES[0]] - ) # pyright: ignore[reportAttributeAccessIssue] - assert [terminal.eligibility for terminal in terminals] == [ # pyright: ignore[reportAttributeAccessIssue] - Eligibility.POISONED, - Eligibility.ELIGIBLE, - Eligibility.ELIGIBLE, - ] - assert terminals[0].ticket is None # pyright: ignore[reportAttributeAccessIssue] - assert terminals[1].ticket is not None # pyright: ignore[reportAttributeAccessIssue] - - -@pytest.mark.parametrize("backend", LOCKSTEP) -def test_an_in_flight_failure_poisons_its_member_alone(backend, monkeypatch): - available(backend) - # An in-place step abandoned partway leaves no valid state for its member, which - # cannot be checkpointed; the member after it, not yet stepped, can be. - simulations = [member(index, backend, FIXED_ORDER) for index in range(2)] - with ExitStack() as cleanup: - group, owners = group_of(simulations, cleanup) - march = owners[0]._adams - - def abandoned(dz, end, slack): - owners[0]._in_flight = (owners[0]._z, dz) - msg = "a manufactured in-flight failure" - raise RuntimeError(msg) - - monkeypatch.setattr(march, "replay_step", abandoned) - launch = group.advance() - group.acknowledge(launch.receipt) - ended = group.advance() - poisoned, untouched = (events[0] for events in ended.members) - assert isinstance(poisoned, Terminal) and isinstance(untouched, Terminal) - assert poisoned.eligibility is Eligibility.POISONED - assert poisoned.ticket is None - assert poisoned.z == 0.0 - assert untouched.eligibility is Eligibility.ELIGIBLE - assert untouched.ticket is not None - assert untouched.ticket.z == untouched.z == 0.0 - # The untouched member can still be checkpointed where it stands. - field = group.export(1, untouched.ticket, IDENTITY) - assert np.all(np.isfinite(field)) - group.acknowledge(ended.receipt) - assert group.finished - - -def assert_drained_after_failure(group, ended): - """A failed window's terminals deliver its two fixed steps, once, at its plane.""" - assert ended.outcome is Outcome.FAILED - assert isinstance(ended.error, RuntimeError) - for index, events in enumerate(ended.members): - (terminal,) = events - assert isinstance(terminal, Terminal) - assert terminal.history is not None - # The first window's two fixed steps, delivered once. - assert terminal.history.n_steps == 2 - assert group.member_status(index).attempts == 2 - assert terminal.z == pytest.approx(PLANES[0]) - assert terminal.eligibility is Eligibility.ELIGIBLE - - -@pytest.mark.parametrize("backend", LOCKSTEP) -def test_a_window_s_failure_delivers_the_attempts_it_drained(backend, monkeypatch): - available(backend) - # The statistics fail after each member's attempts of the window were drained: - # each terminal delivers them, and the status counts no attempt it did not. - with ExitStack() as cleanup: - group, owners = group_of( - [member(index, backend) for index in range(2)], cleanup - ) - launch = group.advance() - group.acknowledge(launch.receipt) - - def broken(self, spec): - msg = "manufactured statistics failure" - raise RuntimeError(msg) - - monkeypatch.setattr(type(owners[0]), "stats", broken) - ended = group.advance() - assert_drained_after_failure(group, ended) - group.acknowledge(ended.receipt) - - -@pytest.mark.parametrize("backend", GROUPS) -def test_a_group_wide_stop_ends_every_member_at_a_common_endpoint(backend): - available(backend) - token = StopToken() - with ExitStack() as cleanup: - group, _ = group_of( - [member(index, backend) for index in range(2)], cleanup, stop=token - ) - launch = group.advance() - group.acknowledge(launch.receipt) - token.set() - stopped = group.advance() - group.acknowledge(stopped.receipt) - assert group.finished - assert stopped.outcome is Outcome.STOPPED - for events in stopped.members: - (terminal,) = events - assert isinstance(terminal, Terminal) - assert terminal.outcome is Outcome.STOPPED - assert terminal.z == 0.0 - assert terminal.eligibility is Eligibility.ELIGIBLE - assert isinstance(terminal.error, StopRequested) - - -def runner_of(group: GroupSession) -> Any: - """Return the lockstep runner a group drives, whose class a test patches.""" - return cast("Any", group)._runner - - -@dataclass -class FinalWarning(BoundaryMonitor): - """A boundary monitor whose final check warns, as a removed fraction over budget.""" - - def finish(self) -> None: - """Warn as the end-of-run check does when the collar removed too much.""" - warnings.warn( - BoundaryWarning("a manufactured final warning", parameter="boundary_check"), - stacklevel=2, - ) - - -def final_warning(simulation: Simulation) -> FinalWarning: - """Return a fresh :class:`FinalWarning` for a member's grid.""" - built = BoundaryMonitor.build(simulation.grid, None, BoundaryCheck()) - return FinalWarning( - built.check, - built.weights, - built.kind, - built.columns, - built.split, - built.interval, - ) - - -@pytest.mark.parametrize("backend", GROUPS) -def test_a_group_closes_with_its_scope(backend): - available(backend) - simulations = [member(index, backend) for index in range(2)] - with ExitStack() as cleanup: - group, _ = group_of(simulations, cleanup) - with group as scoped: - assert scoped is group - scoped.acknowledge(scoped.advance().receipt) - assert group.closed - assert group.member_status(1).state is SessionState.CLOSED - - -@pytest.mark.parametrize("backend", GROUPS) -def test_a_spatial_group_exports_its_field_measure_and_each_member_s_noise(backend): - # A spatial route's field measure is already the stored quantity: a true-power - # recipe exports it unscaled, and each member carries its own noise realisation. - available(backend) - simulations = [cartesian(backend, noise=True) for _ in range(2)] - with ExitStack() as cleanup: - group, _ = group_of(simulations, cleanup) - launch = group.advance() - for index, events in enumerate(launch.members): - (event,) = events - assert isinstance(event, ObservationReady) - field = np.array(group.export(index, event.ticket, IDENTITY)) - measured = group.export(index, event.ticket, CONSUMER) - assert measured.tobytes() == field.tobytes() - phase = group.noise_phase(index, event.ticket) - assert phase is not None - assert phase.shape == field.shape - assert np.all(np.isfinite(phase)) - group.acknowledge(launch.receipt) - - -@pytest.mark.parametrize("backend", GROUPS) -def test_a_noise_free_member_has_no_noise_phase(backend): - available(backend) - with ExitStack() as cleanup: - group, _ = group_of([member(index, backend) for index in range(2)], cleanup) - launch = group.advance() - (event,) = launch.members[1] - assert isinstance(event, ObservationReady) - assert group.noise_phase(1, event.ticket) is None - group.acknowledge(launch.receipt) - - -@pytest.mark.parametrize("backend", LOCKSTEP) -def test_a_launch_the_runner_cannot_watch_fails_every_member_at_the_entrance( - backend, monkeypatch -): - available(backend) - with ExitStack() as cleanup: - group, _ = group_of([member(index, backend) for index in range(2)], cleanup) - - def refused(self, monitors): - msg = "manufactured monitor attachment failure" - raise RuntimeError(msg) - - monkeypatch.setattr(type(runner_of(group)), "attach_monitors", refused) - ended = group.advance() - group.acknowledge(ended.receipt) - assert group.finished - assert ended.outcome is Outcome.FAILED - assert isinstance(ended.error, RuntimeError) - for events in ended.members: - (terminal,) = events - assert isinstance(terminal, Terminal) - assert terminal.error is ended.error - assert terminal.z == 0.0 - assert terminal.eligibility is Eligibility.ELIGIBLE - assert terminal.ticket is not None - - -@pytest.mark.parametrize("backend", LOCKSTEP) -def test_a_window_s_statistics_failure_delivers_the_attempts_it_drained( - backend, monkeypatch -): - # The group's statistics fail at the window's end, after each member's attempts - # of the window were drained: each terminal delivers them, once. - available(backend) - with ExitStack() as cleanup: - group, _ = group_of([member(index, backend) for index in range(2)], cleanup) - launch = group.advance() - group.acknowledge(launch.receipt) - - def broken(self, spec): - msg = "manufactured group statistics failure" - raise RuntimeError(msg) - - monkeypatch.setattr(type(runner_of(group)), "stats", broken) - ended = group.advance() - group.acknowledge(ended.receipt) - assert_drained_after_failure(group, ended) - - -@pytest.mark.parametrize("backend", LOCKSTEP) -def test_a_member_unreadable_after_a_failure_still_reports_its_terminal( - backend, monkeypatch -): - # After a group-wide failure each member is drained alone; one whose state cannot - # be read delivers no attempts, and the others' terminals are unaffected. - available(backend) - with ExitStack() as cleanup: - group, owners = group_of( - [member(index, backend) for index in range(2)], cleanup - ) - launch = group.advance() - group.acknowledge(launch.receipt) - - def failed(self, target): - msg = "manufactured window failure" - raise RuntimeError(msg) - - def unreadable(*, field=True): - msg = "manufactured unreadable member" - raise RuntimeError(msg) - - monkeypatch.setattr(type(runner_of(group)), "propagate_to", failed) - monkeypatch.setattr(owners[1], "observe", unreadable) - ended = group.advance() - group.acknowledge(ended.receipt) - assert ended.outcome is Outcome.FAILED - terminals = [events[0] for events in ended.members] - assert all(isinstance(terminal, Terminal) for terminal in terminals) - for terminal in terminals: - assert isinstance(terminal, Terminal) - assert terminal.error is ended.error - assert terminal.z == 0.0 - assert terminal.history is not None - assert terminal.history.n_steps == 0 - - -@pytest.mark.parametrize("backend", GROUPS) -def test_a_group_whose_members_all_stop_at_their_launch_completes(backend): - # Every member ends at its own boundary at the launch: nothing is left to advance. - # A native member's monitor judges its launch after the launch plane, one window - # on (SEP 47 section 5.3). - available(backend) - simulations = [member(index, backend) for index in range(2)] - strict = BoundaryCheck(budget=1e-300, stop_factor=1.0) - with ExitStack() as cleanup: - group, _ = group_of( - simulations, - cleanup, - monitors=[ - BoundaryMonitor.build(one.grid, None, strict) for one in simulations - ], - ) - batches = drive(group) - assert len(batches) == (2 if backend == "native" else 1) - batch = batches[-1] - assert batch.outcome is Outcome.COMPLETED - assert batch.error is None - for events in batch.members: - (stopped,) = events - assert stopped.z == 0.0 - assert isinstance(stopped, Terminal) - assert stopped.outcome is Outcome.FAILED - assert isinstance(stopped.error, BoundaryError) - assert stopped.eligibility is Eligibility.ELIGIBLE - - -@pytest.mark.parametrize("backend", GROUPS) -def test_a_group_wide_stop_reports_nothing_more_for_a_member_already_ended(backend): - available(backend) - simulations = [member(index, backend) for index in range(2)] - strict = BoundaryCheck(budget=1e-300, stop_factor=1.0) - token = StopToken() - with ExitStack() as cleanup: - group, _ = group_of( - simulations, - cleanup, - monitors=[BoundaryMonitor.build(simulations[0].grid, None, strict), None], - stop=token, - ) - launch = group.advance() - if backend == "native": - # The launch plane first, then the monitor's launch judgement. - group.acknowledge(launch.receipt) - launch = group.advance() - (refused,) = launch.members[0] - assert isinstance(refused, Terminal) - assert isinstance(refused.error, BoundaryError) - group.acknowledge(launch.receipt) - token.set() - stopped = group.advance() - group.acknowledge(stopped.receipt) - assert group.finished - assert stopped.outcome is Outcome.STOPPED - assert stopped.members[0] == () - (terminal,) = stopped.members[1] - assert isinstance(terminal, Terminal) - assert terminal.outcome is Outcome.STOPPED - assert group.member_status(0).outcome is Outcome.FAILED - assert group.member_status(1).outcome is Outcome.STOPPED - - -@pytest.mark.parametrize("backend", LOCKSTEP) -def test_a_failed_final_check_ends_the_group_failed(backend, monkeypatch): - available(backend) - with ExitStack() as cleanup: - group, _ = group_of([member(index, backend) for index in range(2)], cleanup) - - def broken(self): - msg = "manufactured final check failure" - raise RuntimeError(msg) - - monkeypatch.setattr(type(runner_of(group)), "finish_monitors", broken) - batches = drive(group) - ended = batches[-1] - assert ended.outcome is Outcome.FAILED - assert isinstance(ended.error, RuntimeError) - for events in ended.members: - (terminal,) = events - assert isinstance(terminal, Terminal) - assert terminal.outcome is Outcome.FAILED - assert terminal.z == pytest.approx(PLANES[-1]) - assert terminal.eligibility is Eligibility.ELIGIBLE - - -@pytest.mark.parametrize("backend", LOCKSTEP) -def test_a_final_warning_raised_as_an_error_fails_its_member_alone(backend): - # A run of the member alone would fail at its final check; in a group it fails - # that member, and the other completes (SEP 21). The tight window's own warnings - # are not what is tested. - available(backend) - simulations = [member(index, backend) for index in range(2)] - with ExitStack() as cleanup, warnings.catch_warnings(): - warnings.simplefilter("ignore", BoundaryWarning) - warnings.filterwarnings( - "error", ".*a manufactured final warning", BoundaryWarning - ) - group, _ = group_of( - simulations, cleanup, monitors=[final_warning(simulations[0]), None] - ) - batches = drive(group) - last = batches[-1] - assert last.outcome is Outcome.COMPLETED - (failed,) = last.members[0] - assert isinstance(failed, Terminal) - assert failed.outcome is Outcome.FAILED - assert isinstance(failed.error, BoundaryWarning) - assert failed.eligibility is Eligibility.ELIGIBLE - assert failed.z == pytest.approx(PLANES[-1]) - (completed,) = last.members[1] - assert isinstance(completed, Terminal) - assert completed.outcome is Outcome.COMPLETED - - -@pytest.mark.parametrize("backend", LOCKSTEP) -def test_a_final_warning_raised_as_an_error_fails_the_member_s_lone_run(backend): - # The lone counterpart of the test above: the member's own session fails at its - # final check, at the run's end, with its state eligible for a checkpoint. - available(backend) - simulation = member(0, backend) - problem = simulation.translate() - with ExitStack() as cleanup, warnings.catch_warnings(): - warnings.simplefilter("ignore", BoundaryWarning) - warnings.filterwarnings( - "error", ".*a manufactured final warning", BoundaryWarning - ) - lone = start_session( - constructed(simulation, cleanup), - problem, - simulation._run_request().for_run(monitor=final_warning(simulation)), - Start.entrance(problem), - owns=False, - ) - cleanup.callback(lone.close) - batch = None - while not lone.finished: - batch = lone.advance() - lone.acknowledge(batch.receipt) - assert batch is not None - (failed,) = batch.events - assert isinstance(failed, Terminal) - assert failed.outcome is Outcome.FAILED - assert isinstance(failed.error, BoundaryWarning) - assert failed.eligibility is Eligibility.ELIGIBLE - assert failed.z == pytest.approx(PLANES[-1]) diff --git a/tests/sessions/test_group_seam.py b/tests/sessions/test_group_seam.py deleted file mode 100644 index c916d9347..000000000 --- a/tests/sessions/test_group_seam.py +++ /dev/null @@ -1,49 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""A group starts through its backend's own ``prepare_group`` (SEP 47 section 6.7). - -:func:`solprop.backends.sessions.start_group` asks the members' backend to prepare the -group, so a backend that runs no group refuses it there, before any member is loaded. -""" - -from contextlib import ExitStack - -import pytest - -from sessions.test_group import member -from solprop.backends.numpy_ref import NumpyRefBackend -from solprop.backends.registry import select -from solprop.backends.session import Start -from solprop.backends.sessions import start_group -from solprop.exceptions import BackendError - - -def test_a_backend_that_runs_no_group_refuses_it_at_the_door(monkeypatch): - def refused(self, members, problems, requests): - raise BackendError("the reference runs no group") - - monkeypatch.setattr(NumpyRefBackend, "prepare_group", refused) - simulations = [member(index, "numpy_ref") for index in range(2)] - problems = [one.translate() for one in simulations] - with ExitStack() as cleanup: - owners = [] - for simulation in simulations: - owner = select( - "numpy_ref", - simulation.translate(), - simulation._run_request(), - grid=simulation.grid, - modes=simulation.modes, - profiles=simulation.profiles, - ) - cleanup.callback(owner.close) - owners.append(owner) - with pytest.raises(BackendError, match="the reference runs no group"): - start_group( - owners, - problems, - [one._run_request() for one in simulations], - [Start.entrance(problem) for problem in problems], - ) diff --git a/tests/sessions/test_native_group.py b/tests/sessions/test_native_group.py deleted file mode 100644 index dcdd3f550..000000000 --- a/tests/sessions/test_native_group.py +++ /dev/null @@ -1,916 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""The native group session (SEP 47 section 6.7): members it admits, and how they end. - -:class:`solprop_native.group.NativeGroupSession` marches each member through the -common fixed schedule in its own native session, in rounds of common steps -(:data:`solprop_native.group.ROUND_STEPS`). A member's trajectory is its lone native -session's: these tests hold each member to the same problem run alone through the -native session -- the same fields, statistics, attempts and rows, bit for bit at one -thread. A -failure is injected natively (``adams_march_fault``) to place the group's failures: a -member ahead of the failing one in its round has committed and recorded its steps, and -each member ends at its own committed position. The protocol's conformance tests, -which the reference's group passes too, are in ``test_group.py``. -""" - -import dataclasses -import os -import warnings -from collections.abc import Mapping, Sequence -from contextlib import ExitStack -from typing import Any, cast - -import numpy as np -import pytest - -from march_bounds import FIXED_ORDER -from sessions.executors import Started, skip_device_refused -from sessions.executors import drive as drive_session -from sessions.test_group import ( - IDENTITY, - PLANES, - STEP, - constructed, - drive, - group_of, - member, -) -from solprop.backends.events import ( - Eligibility, - EventBatch, - GroupBatch, - ObservationReady, - Outcome, - Terminal, -) -from solprop.backends.session import SessionError, Start -from solprop.backends.sessions import start_group -from solprop.exceptions import BackendError, BoundaryWarning, StopRequested -from solprop.monitor import BoundaryCheck, BoundaryMonitor -from solprop.stepper import Multistep -from solprop.stepper.low_storage import LowStorageRungeKutta -from solprop.stepper.schedule import FixedSchedule - -group_module = pytest.importorskip("solprop_native.group") - -INTEGRATORS = { - "runge_kutta": None, - "adams_fixed_order": FIXED_ORDER, - "adams": Multistep(), - "low_storage": LowStorageRungeKutta(), -} -"""The marches a native group runs: each member's own, natively.""" - - -def _one_thread() -> bool: - """Return whether the native backend runs one thread, as the default lane sets it. - - Returns - ------- - bool - True when ``SOLPROP_NATIVE_THREADS`` or ``SOLPROP_THREADS`` is ``"1"``. - """ - return "1" in { - os.environ.get("SOLPROP_NATIVE_THREADS"), - os.environ.get("SOLPROP_THREADS"), - } - - -def _started( - simulations: Sequence[Any], - cleanup: ExitStack, - *, - faults: Mapping[int, tuple[int, str]] | None = None, -) -> Any: - """Start a group of members, arming native faults first; return the group. - - Parameters - ---------- - simulations : sequence of solprop.driver.Simulation - The members. - cleanup : contextlib.ExitStack - Owner of the backends and the group. - faults : collections.abc.Mapping or None, optional - Per member, how many runs of a march stage succeed and the stage that then - fails (``adams_march_fault``, a backend failure). - - Returns - ------- - solprop.backends.session.GroupSession - The started group. - """ - problems = [one.translate() for one in simulations] - owners = [constructed(one, cleanup) for one in simulations] - for index, (after, stage) in (faults or {}).items(): - owners[index]._native_state.adams_march_fault(stage, after, "backend") - requests = [one._run_request() for one in simulations] - starts = [Start.entrance(problem) for problem in problems] - group = start_group(owners, problems, requests, starts) - cleanup.callback(group.close) - return group - - -def _record(group: Any) -> list[list[dict[str, Any]]]: - """Drive a group to its end; return each member's planes as plain arrays. - - Parameters - ---------- - group : solprop.backends.session.GroupSession - A started group. - - Returns - ------- - list - Per member, per plane: the field, the plane statistics, the attempts and the - periodic rows. - """ - planes: list[list[dict[str, Any]]] = [[] for _ in range(group.n_members)] - while not group.finished: - batch = group.advance() - for index, events in enumerate(batch.members): - for event in events: - if isinstance(event, ObservationReady): - history, rows = event.history, event.step_stats - planes[index].append( - { - "field": np.array( - group.export(index, event.ticket, IDENTITY) - ), - "stats": {k: np.asarray(v) for k, v in event.stats.items()}, - "attempts": np.stack( - [history.z, history.dz, history.error_norm] - ), - "accepted": history.accepted.copy(), - "row_z": rows.z.copy(), - "row_step": rows.step.copy(), - "rows": {k: v.copy() for k, v in rows.values.items()}, - } - ) - group.acknowledge(batch.receipt) - return planes - - -def _lone(simulation: Any) -> list[dict[str, Any]]: - """Run one member alone through the native session; record it as :func:`_record`. - - Parameters - ---------- - simulation : solprop.driver.Simulation - The member. - - Returns - ------- - list - Per plane: the field, the plane statistics, the attempts, the periodic rows and - the noise phase. - """ - from solprop_native.session import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] - NativeSession, - ) - - problem = simulation.translate() - session = NativeSession( - problem, - simulation._run_request(), - Start.entrance(problem), - grid=simulation.grid, - modes=simulation.modes, - profiles=simulation.profiles, - ) - planes: list[dict[str, Any]] = [] - try: - while not session.finished: - batch = session.advance() - for event in batch.events: - if isinstance(event, ObservationReady): - history, rows = event.history, event.step_stats - phase = session.noise_phase(event.ticket) - planes.append( - { - "field": np.array(session.export(event.ticket, IDENTITY)), - "stats": {k: np.asarray(v) for k, v in event.stats.items()}, - "attempts": np.stack( - [history.z, history.dz, history.error_norm] - ), - "accepted": history.accepted.copy(), - "row_z": rows.z.copy(), - "row_step": rows.step.copy(), - "rows": {k: v.copy() for k, v in rows.values.items()}, - "phase": None if phase is None else np.array(phase), - } - ) - session.acknowledge(batch.receipt) - finally: - session.close() - return planes - - -def _same(left: Any, right: Any) -> bool: - """Return whether two recorded values agree exactly, nested containers included. - - Parameters - ---------- - left, right : object - Arrays, or dicts of them. - - Returns - ------- - bool - True when every array is bitwise equal. - """ - if isinstance(left, dict): - return left.keys() == right.keys() and all( - _same(left[key], right[key]) for key in left - ) - return bool(np.array_equal(left, right)) - - -@pytest.mark.parametrize("name", sorted(INTEGRATORS)) -def test_a_native_member_marches_as_its_lone_session_bit_for_bit(name): - """Each member's fields, statistics, attempts and rows are its lone native - session's exactly: the group marches each member alone through its own native - session, in one operation order (structural identity, one thread). - """ - if not _one_thread(): - pytest.skip( - "a native run on several threads may vary its reduction order; the " - "default lane runs one (SOLPROP_NATIVE_THREADS=1)" - ) - integrator = INTEGRATORS[name] - with ExitStack() as cleanup: - simulations = [member(index, "native", integrator) for index in range(3)] - group = _started(simulations, cleanup) - assert isinstance(group, group_module.NativeGroupSession) - native = _record(group) - alone = [_lone(member(index, "native", integrator)) for index in range(3)] - for index, (ours, theirs) in enumerate(zip(native, alone, strict=True)): - assert len(ours) == len(theirs) == len(PLANES) + 1 - for plane, (one, other) in enumerate(zip(ours, theirs, strict=True)): - for key in one: - assert _same(one[key], other[key]), (index, plane, key) - # The members differ: each is its own problem, not one copied. - assert not _same(native[0][-1]["field"], native[1][-1]["field"]) - - -def test_the_execution_record_names_the_group_and_keeps_the_session_s_counters(): - with ExitStack() as cleanup: - group = _started([member(index, "native") for index in range(2)], cleanup) - drive(group) - record = group.execution_record(1) - assert record["backend"] == "native" - assert record["batch_size"] == 2 - assert record["batch_strategy"] == "native_group_session" - assert record["fused_batch_kernels"] is False - counters = record["native_session"] - assert isinstance(counters, dict) - # The launch, two planes and the completion: one native batch each. - assert counters["batches"] == len(PLANES) + 2 - - -@pytest.mark.parametrize(("rounds", "ahead"), [(256, PLANES[1]), (1, PLANES[0] + STEP)]) -def test_a_trial_failure_ends_the_group_at_each_member_s_own_position( - monkeypatch, rounds, ahead -): - """The second member's third trial fails, opening the second window. The first - member took its turn first: with the default rounds it ran the whole window, with - rounds of one step only the failed step, and in both it committed and recorded what - it ran -- eligible where it stands, unlike a lockstep group's stepped but - unrecorded member. The failing member keeps its committed state; the third never - took its turn (SEP 47 section 6.7). - """ - monkeypatch.setattr(group_module, "ROUND_STEPS", rounds) - simulations = [member(index, "native", FIXED_ORDER) for index in range(3)] - with ExitStack() as cleanup: - group = _started(simulations, cleanup, faults={1: (2, "trial")}) - for _ in range(2): # the launch and the first plane - window = group.advance() - assert window.outcome is None - group.acknowledge(window.receipt) - ended = group.advance() - assert ended.outcome is Outcome.FAILED - assert ended.error is not None - terminals = [events[0] for events in ended.members] - assert all(isinstance(terminal, Terminal) for terminal in terminals) - assert all(terminal.error is ended.error for terminal in terminals) - assert [terminal.z for terminal in terminals] == pytest.approx( - [ahead, PLANES[0], PLANES[0]] - ) - assert all( - terminal.eligibility is Eligibility.ELIGIBLE for terminal in terminals - ) - assert [terminal.history.n_steps for terminal in terminals] == [ - round((ahead - PLANES[0]) / STEP), - 0, - 0, - ] - # Each member can be checkpointed where it stands, the first past the others. - for index, terminal in enumerate(terminals): - assert terminal.ticket is not None - field = group.export(index, terminal.ticket, IDENTITY) - assert np.all(np.isfinite(field)) - status = group.member_status(index) - assert status.outcome is Outcome.FAILED - assert status.z == pytest.approx(terminal.z) - - -def test_an_in_flight_failure_poisons_its_member_alone(): - """A low-storage step overwrites the state in place: abandoned partway, its member - has no state to checkpoint; the member after it, not yet stepped, does. - """ - simulations = [ - member(index, "native", LowStorageRungeKutta()) for index in range(2) - ] - with ExitStack() as cleanup: - group = _started(simulations, cleanup, faults={0: (0, "trial")}) - launch = group.advance() - group.acknowledge(launch.receipt) - ended = group.advance() - poisoned, untouched = (events[0] for events in ended.members) - assert isinstance(poisoned, Terminal) - assert isinstance(untouched, Terminal) - assert poisoned.eligibility is Eligibility.POISONED - assert poisoned.ticket is None - assert poisoned.z == 0.0 - assert untouched.eligibility is Eligibility.ELIGIBLE - assert untouched.ticket is not None - assert untouched.error is poisoned.error is ended.error - field = group.export(1, untouched.ticket, IDENTITY) - assert np.all(np.isfinite(field)) - group.acknowledge(ended.receipt) - assert group.finished - - -class _StopAfter: - """A stop flag that is set from its `polls`-th poll on. - - Parameters - ---------- - polls : int - The poll at which it is first set. - """ - - def __init__(self, polls: int) -> None: - self.polls = polls - self.count = 0 - - def is_set(self) -> bool: - """Return whether the flag is set, counting the poll.""" - self.count += 1 - return self.count >= self.polls - - -def test_a_group_wide_stop_ends_every_member_at_the_common_step_between_rounds( - monkeypatch, -): - """With rounds of one step, the stop polled before the window's second round ends - every member one step into the window: a common accepted endpoint, each eligible. - """ - monkeypatch.setattr(group_module, "ROUND_STEPS", 1) - stop = _StopAfter(2) - with ExitStack() as cleanup: - group, _ = group_of( - [member(index, "native") for index in range(3)], cleanup, stop=stop - ) - launch = group.advance() - group.acknowledge(launch.receipt) - assert stop.count == 0 # the launch takes no step and polls no stop - stopped = group.advance() - assert stopped.outcome is Outcome.STOPPED - assert isinstance(stopped.error, StopRequested) - for index, events in enumerate(stopped.members): - (terminal,) = events - assert isinstance(terminal, Terminal) - assert terminal.outcome is Outcome.STOPPED - assert terminal.z == pytest.approx(STEP) - assert terminal.history is not None - assert terminal.history.n_steps == 1 - assert terminal.ticket is not None - assert np.all(np.isfinite(group.export(index, terminal.ticket, IDENTITY))) - group.acknowledge(stopped.receipt) - assert group.finished - - -def _warned(batches: Sequence[GroupBatch]) -> Terminal | None: - """Return the first member's terminal event, if it ended before the group did. - - Parameters - ---------- - batches : sequence of solprop.backends.events.GroupBatch - Every window. - - Returns - ------- - solprop.backends.events.Terminal or None - Its terminal event. - """ - for batch in batches: - for event in batch.members[0]: - if isinstance(event, Terminal): - return event - return None - - -def test_a_boundary_warning_raised_as_an_error_ends_its_member_alone(): - """A warning a member's monitor issues is served by the group at its barrier: under - an ``"error"`` filter it ends that member alone, at the warning's committed - position, eligible; the other member, unwatched, runs the whole schedule. - """ - simulations = [member(index, "native") for index in range(2)] - # A budget every launch exceeds, and a stop no guard reaches: a warning, no stop. - noisy = BoundaryCheck(budget=1e-300, stop_factor=1e300) - monitors = [BoundaryMonitor.build(simulations[0].grid, None, noisy), None] - with ExitStack() as cleanup, warnings.catch_warnings(): - warnings.simplefilter("error", BoundaryWarning) - group, _ = group_of(simulations, cleanup, monitors=monitors) - batches = drive(group) - ended = _warned(batches) - assert ended is not None - assert ended.outcome is Outcome.FAILED - assert isinstance(ended.error, BoundaryWarning) - assert ended.eligibility is Eligibility.ELIGIBLE - assert ended.z == 0.0 - assert batches[-1].outcome is Outcome.COMPLETED - assert batches[-1].error is None - assert group.member_status(1).outcome is Outcome.COMPLETED - assert group.monitor_record(0) is not None - # Allowed, the warning leaves its member running to the end. - with ExitStack() as cleanup, pytest.warns(BoundaryWarning): - group, _ = group_of( - [member(index, "native") for index in range(2)], - cleanup, - monitors=[BoundaryMonitor.build(simulations[0].grid, None, noisy), None], - ) - batches = drive(group) - assert _warned(batches[:-1]) is None - assert group.member_status(0).outcome is Outcome.COMPLETED - - -def _requests(simulations: Sequence[Any]) -> tuple[list[Any], list[Any], list[Any]]: - """Return the members' problems, run requests and starts. - - Parameters - ---------- - simulations : sequence of solprop.driver.Simulation - The members. - - Returns - ------- - tuple - Their problems, requests and starts. - """ - problems = [one.translate() for one in simulations] - return ( - problems, - [one._run_request() for one in simulations], - [Start.entrance(problem) for problem in problems], - ) - - -def test_the_native_group_refuses_by_name_what_it_does_not_run(): - simulations = [member(index, "native") for index in range(2)] - problems, requests, starts = _requests(simulations) - assert group_module.refusal(problems, requests, starts) is None - adaptive = dataclasses.replace(requests[1], replay=None) - assert ( - "an adaptive march: a group replays one common fixed schedule (member 1)" - in group_module.refusal(problems, [requests[0], adaptive], starts) - ) - stepped = dataclasses.replace( - requests[0], - observation=dataclasses.replace(requests[0].observation, step_planes=1), - ) - assert ( - "step planes, which a group's save-plane windows do not observe (member 0)" - in group_module.refusal(problems, [stepped, requests[1]], starts) - ) - finer = member( - 1, - "native", - schedule=FixedSchedule.uniform(0.0, PLANES[-1], STEP / 2, save_planes=PLANES), - ) - assert "member 1, which does not share member 0's schedule" in ( - group_module.refusal( - [problems[0], finer.translate()], - [requests[0], finer._run_request()], - starts, - ) - ) - with ExitStack() as cleanup: - owners = [constructed(one, cleanup) for one in simulations] - with pytest.raises( - BackendError, match=r"does not run an adaptive march.*\(member 1\)" - ): - group_module.NativeGroupSession( - owners, problems, [requests[0], adaptive], starts - ) - reference = [ - constructed(member(index, "numpy_ref"), cleanup) for index in range(2) - ] - with pytest.raises(BackendError, match="takes native backends"): - group_module.NativeGroupSession(reference, problems, requests, starts) - - -@pytest.mark.parametrize("name", ["runge_kutta", "adams_fixed_order"]) -@pytest.mark.parametrize("noise", ["input", "modified"]) -def test_a_noisy_group_marches_as_its_lone_sessions_bit_for_bit(noise, name): - """Each member carries its own realisation, seeded per member, and its own - propagator: the door starts the native group, whose members' noise phases are - their lone sessions', and on one thread each member's fields, statistics, - attempts and rows are its lone session's exactly. - """ - integrator = INTEGRATORS[name] - - def members() -> list[Any]: - return [ - member(index, "native", integrator, noise=noise, seed=11 + index) - for index in range(2) - ] - - with ExitStack() as cleanup: - simulations = members() - problems, requests, starts = _requests(simulations) - assert all(one.initial.noise_model == noise for one in problems) - assert group_module.refusal(problems, requests, starts) is None - group = _started(simulations, cleanup) - assert isinstance(group, group_module.NativeGroupSession) - found: list[list[np.ndarray]] = [[] for _ in range(group.n_members)] - native: list[list[dict[str, Any]]] = [[] for _ in range(group.n_members)] - while not group.finished: - batch = group.advance() - for index, events in enumerate(batch.members): - for event in events: - if isinstance(event, ObservationReady): - phase = group.noise_phase(index, event.ticket) - assert phase is not None - found[index].append(np.array(phase)) - native[index].append( - { - "field": np.array( - group.export(index, event.ticket, IDENTITY) - ), - "stats": { - k: np.asarray(v) for k, v in event.stats.items() - }, - "accepted": event.history.accepted.copy(), - } - ) - group.acknowledge(batch.receipt) - alone = [_lone(one) for one in members()] - for index in range(2): - assert len(found[index]) == len(alone[index]) == len(PLANES) + 1 - for got, expected in zip(found[index], alone[index], strict=True): - assert got.tobytes() == expected["phase"].tobytes(), index - # Each member's propagator is its own, so is its phase. - assert not np.array_equal(found[0][-1], found[1][-1]) - if not _one_thread(): - pytest.skip( - "the noise phases agree; the members are compared bit for bit on one " - "thread (SOLPROP_THREADS=1), where the reductions' order is fixed" - ) - for index, (one, other) in enumerate(zip(native, alone, strict=True)): - for plane, (left, right) in enumerate(zip(one, other, strict=True)): - for key in left: - assert _same(left[key], right[key]), (index, plane, key) - - -def _noisy_members(kind: str) -> list[Any]: - """Return two seeded noisy members on a common fixed schedule. - - ``"edge"``: a radial run with the input noise beside its transverse edge and a - requested collar; ``"table"``: a linear walk-off with the modified noise, whose - propagator phase is a z table. - """ - from backends.test_transverse_backends import ( # noqa: PLC0415 - beside its use - radial_collar, - ) - from driver.test_specified_paths import LENGTH # noqa: PLC0415 - from sessions.test_native_session_history import _walkoff # noqa: PLC0415 - from solprop.stepper import RungeKutta # noqa: PLC0415 - - members = [] - for index in range(2): - if kind == "edge": - simulation = radial_collar( - "native", RungeKutta(), noise="input", seed=5 + index - ) - length = 2e-3 - planes = [length / 2, length] - else: - simulation = _walkoff("modified", RungeKutta(), seed=3 + index) - length = LENGTH - planes = [length / 3, 2 * length / 3, length] - simulation.settings = dataclasses.replace( - simulation.settings, - controller=None, - save_planes=planes, - schedule=FixedSchedule.uniform( - 0.0, length, length / 64, save_planes=planes - ), - ) - members.append(simulation) - return members - - -def _alone(simulation: Any) -> tuple[list[dict[str, Any]], Any]: - """Run one member alone through the native session; return its planes, record.""" - from solprop_native.session import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] - NativeSession, - ) - - problem = simulation.translate() - request = simulation._run_request().for_run(monitor=simulation._boundary_monitor()) - session = NativeSession( - problem, - request, - Start.entrance(problem), - grid=simulation.grid, - modes=simulation.modes, - profiles=simulation.profiles, - ) - planes: list[dict[str, Any]] = [] - - def observe(one: Any, batch: Any) -> None: - for event in batch.events: - if isinstance(event, ObservationReady): - planes.append( - { - "field": np.array(one.export(event.ticket, IDENTITY)), - "phase": np.array(one.noise_phase(event.ticket)), - } - ) - - try: - with warnings.catch_warnings(): - warnings.simplefilter("ignore", BoundaryWarning) - drive_session(Started(session), between=observe) - return planes, session.monitor_record() - finally: - session.close() - - -@pytest.mark.parametrize("kind", ["edge", "table"]) -def test_a_noisy_edge_or_z_table_member_runs_in_the_native_group(kind): - """The input noise beside a transverse edge, and a noise model on a z table, run in - the native group: each member's noise phases are its lone native session's, and on - one thread its fields and its boundary-monitor record too. - """ - simulations = _noisy_members(kind) - problems, _, starts = _requests(simulations) - requests = [ - one._run_request().for_run(monitor=one._boundary_monitor()) - for one in simulations - ] - skip_device_refused(problems[0]) - assert group_module.refusal(problems, requests, starts) is None - found: list[list[dict[str, Any]]] = [[], []] - with ExitStack() as cleanup: - owners = [constructed(one, cleanup) for one in simulations] - group = start_group(owners, problems, requests, starts) - cleanup.callback(group.close) - assert isinstance(group, group_module.NativeGroupSession) - with warnings.catch_warnings(): - warnings.simplefilter("ignore", BoundaryWarning) - while not group.finished: - batch = group.advance() - for index, events in enumerate(batch.members): - for event in events: - if isinstance(event, ObservationReady): - found[index].append( - { - "field": np.array( - group.export(index, event.ticket, IDENTITY) - ), - "phase": np.array( - group.noise_phase(index, event.ticket) - ), - } - ) - group.acknowledge(batch.receipt) - records = [group.monitor_record(index) for index in range(2)] - alone = [_alone(one) for one in simulations] - for index, (planes, (expected, _)) in enumerate(zip(found, alone, strict=True)): - assert len(planes) == len(expected) > 2 - for one, other in zip(planes, expected, strict=True): - assert one["phase"].tobytes() == other["phase"].tobytes(), index - if kind == "edge": - for record in records: - assert record is not None - edge = cast("Mapping[str, Any]", record["transverse"]) - assert edge["noise_allowance"] > 0.0 - if not _one_thread(): - pytest.skip( - "the noise phases agree; the members are compared bit for bit on one " - "thread (SOLPROP_THREADS=1), where the reductions' order is fixed" - ) - for index, (planes, (expected, record)) in enumerate( - zip(found, alone, strict=True) - ): - assert records[index] == record - for one, other in zip(planes, expected, strict=True): - assert one["field"].tobytes() == other["field"].tobytes(), index - - -def test_a_group_the_native_group_does_not_run_is_refused_at_the_door(): - """An adaptive group is refused by name through the door, before any member - session starts: a group is one common fixed schedule (SEP 47 section 6.7), and - no other native group stands behind it.""" - simulations = [member(index, "native", schedule=None) for index in range(2)] - problems, requests, starts = _requests(simulations) - assert "an adaptive march" in ( - group_module.refusal(problems, requests, starts) or "" - ) - with ExitStack() as cleanup: - owners = [constructed(one, cleanup) for one in simulations] - with pytest.raises( - BackendError, - match=r"native group session does not run an adaptive march.*\(member 0\)", - ): - start_group(owners, problems, requests, starts) - # Nothing was started: the members are still unloaded. - assert all(owner._loaded is None for owner in owners) - - -def _terminals(batch: GroupBatch) -> list[Terminal]: - """Return each member's one event of a batch that ended the group, checked typed. - - Parameters - ---------- - batch : solprop.backends.events.GroupBatch - The batch. - - Returns - ------- - list of solprop.backends.events.Terminal - Each member's terminal event. - """ - terminals = [] - for events in batch.members: - (terminal,) = events - assert isinstance(terminal, Terminal) - terminals.append(terminal) - return terminals - - -def _steps(terminal: Terminal) -> int: - """Return the attempts a terminal event delivers.""" - assert terminal.history is not None - return terminal.history.n_steps - - -class _ManufacturedError(RuntimeError): - """What a patched member session raises or reports.""" - - -def _failing_at_launch(session: Any, error: BaseException) -> Any: - """Return a member session's ``advance`` whose launch reports a failure. - - Parameters - ---------- - session : solprop_native.session.NativeSession - The member's session. - error : BaseException - The failure its launch reports. - - Returns - ------- - callable - The patched ``advance``: the launch batch, its observation replaced by a - failed terminal event at the entrance, eligible, with the launch's ticket. - """ - advance = session.advance - - def failed(**limits: Any) -> EventBatch: - batch = advance(**limits) - (launch,) = batch.events - assert isinstance(launch, ObservationReady) - return EventBatch( - batch.receipt, - ( - Terminal( - Outcome.FAILED, - launch.z, - Eligibility.ELIGIBLE, - error, - launch.ticket, - launch.history, - launch.step_stats, - ), - ), - ) - - return failed - - -def test_a_failure_at_launch_poisons_the_members_that_never_launched(monkeypatch): - """The second of three members fails at its launch: the first launched and can be - checkpointed at its entrance; the third never launched, holds no batch of its own - to export from, and so claims no checkpoint (a terminal event without a ticket is - poisoned). - """ - error = _ManufacturedError("a manufactured launch failure") - with ExitStack() as cleanup: - group, _ = group_of([member(index, "native") for index in range(3)], cleanup) - session = cast("Any", group)._sessions[1] - monkeypatch.setattr(session, "advance", _failing_at_launch(session, error)) - ended = group.advance() - assert ended.outcome is Outcome.FAILED - assert ended.error is error - terminals = _terminals(ended) - assert all(terminal.error is error for terminal in terminals) - assert all(terminal.z == 0.0 for terminal in terminals) - assert [terminal.eligibility for terminal in terminals] == [ - Eligibility.ELIGIBLE, - Eligibility.ELIGIBLE, - Eligibility.POISONED, - ] - for index, terminal in enumerate(terminals): - assert (terminal.ticket is None) is (index == 2) - if terminal.ticket is not None: - assert terminal.ticket.member == index - field = group.export(index, terminal.ticket, IDENTITY) - assert np.all(np.isfinite(field)) - group.acknowledge(ended.receipt) - assert group.finished - - -class _Raising: - """A member session's ``advance`` that raises on its `call`-th call. - - Parameters - ---------- - session : solprop_native.session.NativeSession - The member's session. - call : int - The call that raises. - error : BaseException - What it raises. - """ - - def __init__(self, session: Any, call: int, error: BaseException) -> None: - self.advance = session.advance - self.call = call - self.error = error - self.calls = 0 - - def __call__(self, **limits: Any) -> EventBatch: - """Advance the session, or raise on the chosen call.""" - self.calls += 1 - if self.calls == self.call: - raise self.error - return self.advance(**limits) - - -@pytest.mark.parametrize("kind", ["exception", "interrupt"]) -def test_an_exception_escaping_a_member_ends_the_group_with_its_chunks( - monkeypatch, kind -): - """With rounds of one step, the second member's call raises in the window's second - round, after it acknowledged its batch: the group ends failed, delivering each - member's attempts so far. The first member reached the plane, the third stands one - step in; the second has no batch of its own pending, so claims no checkpoint. An - interrupt propagates, the group's failed batch left pending: it advances no more. - """ - # Made here, not in the parameters: a raised exception's traceback holds the - # group's frames, which must not outlive the test. - error: BaseException = ( - _ManufacturedError("escaped") if kind == "exception" else KeyboardInterrupt() - ) - monkeypatch.setattr(group_module, "ROUND_STEPS", 1) - with ExitStack() as cleanup: - group, _ = group_of([member(index, "native") for index in range(3)], cleanup) - session = cast("Any", group)._sessions[1] - # The launch, the window's first step, then the failing call. - monkeypatch.setattr(session, "advance", _Raising(session, 3, error)) - launch = group.advance() - group.acknowledge(launch.receipt) - if isinstance(error, KeyboardInterrupt): - with pytest.raises(KeyboardInterrupt): - group.advance() - with pytest.raises(SessionError, match="acknowledge the pending batch"): - group.advance() - return - ended = group.advance() - assert ended.outcome is Outcome.FAILED - assert ended.error is error - terminals = _terminals(ended) - assert all(terminal.error is error for terminal in terminals) - assert [terminal.z for terminal in terminals] == pytest.approx( - [PLANES[0], STEP, STEP] - ) - assert [_steps(terminal) for terminal in terminals] == [2, 1, 1] - assert [terminal.eligibility for terminal in terminals] == [ - Eligibility.ELIGIBLE, - Eligibility.POISONED, - Eligibility.ELIGIBLE, - ] - for index in (0, 2): - ticket = terminals[index].ticket - assert ticket is not None - assert np.all(np.isfinite(group.export(index, ticket, IDENTITY))) - group.acknowledge(ended.receipt) - assert group.finished - with pytest.raises(SessionError, match="has ended"): - group.advance() diff --git a/tests/sessions/test_native_session.py b/tests/sessions/test_native_session.py index 3a8d0c6cd..855abe305 100644 --- a/tests/sessions/test_native_session.py +++ b/tests/sessions/test_native_session.py @@ -61,6 +61,7 @@ from solprop.translate.problem import Translation native_session = pytest.importorskip("solprop_native.session") +_testing = pytest.importorskip("solprop_native._core")._testing LENGTH = PLANES[-1] @@ -460,7 +461,7 @@ def test_a_session_leases_its_state_exclusively(): assert backend is not None state = backend._native_state # pyright: ignore[reportPrivateUsage] with pytest.raises(RuntimeError, match="leased"): - state.rk_march_run({}, {}) + _testing.rk_march_run(state, {}, {}) session.close() @@ -535,8 +536,8 @@ def test_the_native_export_is_apply_recipe_to_the_bit(): "set_initial": lambda state, n: state.set_initial( np.zeros(n, np.complex128), np.empty(0, np.complex128) ), - "rk_march_run": lambda state, n: state.rk_march_run({}, {}), - "adams_march_run": lambda state, n: state.adams_march_run({}, {}), + "rk_march_run": lambda state, n: _testing.rk_march_run(state, {}, {}), + "adams_march_run": lambda state, n: _testing.adams_march_run(state, {}, {}), "table_slots": lambda state, n: state.table_slots(False, False, 1, False), "rk_weights_configure": lambda state, n: state.rk_weights_configure([1.0]), "low_storage_configure": lambda state, n: state.low_storage_configure( @@ -545,17 +546,17 @@ def test_the_native_export_is_apply_recipe_to_the_bit(): "flow_guard_configure": lambda state, n: state.flow_guard_configure( [1.0], [1.0], 1.0, 1, 1.0 ), - "adams_march_fault": lambda state, n: state.adams_march_fault( - "trial", 0, "backend" + "adams_march_fault": lambda state, n: _testing.adams_march_fault( + state, "trial", 0, "backend" ), "field_to_host": lambda state, n: state.field_to_host(), - "statistics": lambda state, n: state.statistics( - 2, np.empty(0), np.empty(0), 0.0, 1.0, 0.0, 1.0, np.empty(0) + "statistics": lambda state, n: _testing.statistics( + state, 2, np.empty(0), np.empty(0), 0.0, 1.0, 0.0, 1.0, np.empty(0) ), "finish": lambda state, n: state.finish(1e-6), - "promote_fsal": lambda state, n: state.promote_fsal(), + "promote_fsal": lambda state, n: _testing.promote_fsal(state), "clear_fsal": lambda state, n: state.clear_fsal(), - "monitor_reading": lambda state, n: state.monitor_reading(), + "monitor_reading": lambda state, n: _testing.monitor_reading(state), "quadrature_peak": lambda state, n: state.quadrature_peak(), } """Methods of a leased state that mutate it or read its live field or workspace.""" @@ -582,7 +583,7 @@ def test_a_leased_state_refuses_every_live_use(name): session.close() # Closed, the session released its lease. with pytest.raises(Exception) as caught: - state.rk_march_run({}, {}) + _testing.rk_march_run(state, {}, {}) assert "leased" not in str(caught.value) diff --git a/tests/sessions/test_native_session_axis_plasma.py b/tests/sessions/test_native_session_axis_plasma.py index d5874363b..bc0b93c5c 100644 --- a/tests/sessions/test_native_session_axis_plasma.py +++ b/tests/sessions/test_native_session_axis_plasma.py @@ -22,7 +22,7 @@ import dataclasses import math import warnings -from contextlib import ExitStack, closing +from contextlib import closing import numpy as np import pytest @@ -207,7 +207,9 @@ def _plan(grid, modes, problem, request, names, seen): with closing(select("native", problem, run, grid=grid, modes=modes)) as backend: for record in seen: state = load_native(backend, record.field, clear_fsal=False) - values = lowering.unpack(state.planned_statistics(lowering.plan, record.z)) + values = lowering.unpack( + _testing.planned_statistics(state, lowering.plan, record.z) + ) out.append({name: np.asarray(value) for name, value in values.items()}) return out @@ -348,56 +350,4 @@ def test_an_envelope_s_y_row_on_a_one_component_scan_opens_the_native_session(): assert type(session) is native_session.NativeSession -def _group_planes(group): - """Drive a group to its end; return each member's observations.""" - planes = [[] for _ in range(group.n_members)] - while not group.finished: - batch = group.advance() - for index, events in enumerate(batch.members): - for event in events: - if isinstance(event, ObservationReady): - field = np.array(group.export(index, event.ticket, RAW)) - stats = {k: np.asarray(v) for k, v in event.stats.items()} - planes[index].append(_Seen(event.z, stats, field)) - elif isinstance(event, Terminal): - assert event.error is None, event.error - group.acknowledge(batch.receipt) - return planes - - -def test_a_native_group_scans_an_envelope_s_y_row(): - """A group of such members opens the native group, whose members' statistics are - the host's scan of the row on each member's own field, and the reference's, to the - node scans' parity tolerance.""" - from solprop.backends.session import Start # noqa: PLC0415 - from solprop.backends.sessions import start_group # noqa: PLC0415 - - group_module = pytest.importorskip("solprop_native.group") - names = ON_AXIS_PLASMA_STATISTICS - built = [_envelope_y_row() for _ in range(2)] - problems = [problem for _, _, problem, _ in built] - requests = [request.for_run(stats=StatsSpec(names=names)) for *_, request in built] - starts = [Start.entrance(problem) for problem in problems] - with ExitStack() as cleanup: - owners = [ - cleanup.enter_context( - closing(select("native", problem, run, grid=grid, modes=modes)) - ) - for (grid, modes, problem, _), run in zip(built, requests, strict=True) - ] - assert group_module.refusal(problems, requests, starts) is None - group = start_group(owners, problems, requests, starts) - cleanup.callback(group.close) - assert type(group) is group_module.NativeGroupSession - recorded = _group_planes(group) - for index, ours in enumerate(recorded): - grid, modes, problem, request = built[index] - planned = _plan(grid, modes, problem, request, names, ours) - reference = _reference(grid, modes, problem, request, names, ours) - assert len(ours) == len(planned) == 3 - for mine, other, want in zip(ours, planned, reference, strict=True): - for name in names: - what = f"member {index} {name} at {mine.z}" - got = mine.stats[name] - _within(got, np.asarray(other[name]), f"{what} (plan)") - _within(got, want[name], f"{what} (numpy_ref)") +_testing = pytest.importorskip("solprop_native._core")._testing diff --git a/tests/sessions/test_native_session_device.py b/tests/sessions/test_native_session_device.py index 87aa1ef39..a211f2a84 100644 --- a/tests/sessions/test_native_session_device.py +++ b/tests/sessions/test_native_session_device.py @@ -8,22 +8,19 @@ device build runs -- Adams and the embedded Runge-Kutta tableaux, adaptive and replayed, the low-storage replay, dense output, the radial, Cartesian, line and planar spatial routes with their fluence widths, a free-space run's transverse edge and a -collar's current, the input and modified noise models, a coupled flow wider than 16 -channels or off its eigenbasis route, and fixed-schedule groups (the native group -session, one native session per member). Since phase 5 deleted the transitional bridge +collar's current, the input and modified noise models, and a coupled flow wider than +16 channels or off its eigenbasis route. Since phase 5 deleted the transitional bridge it was first held to bit for bit, each feature runs on the device in the native session and is held to the NumPy reference session on the same problem within the CPU suite's budgets (``test_native_session.py``'s :func:`assert_meets_reference`, the transverse suite's decisions), and to itself: a repeated run on the device is the same bits, as on a CPU build's one thread, its decisions made on the host from the same device -reductions. A group's member is its lone session's. The session crosses the field to -the host only for an export. +reductions. The session crosses the field to the host only for an export. """ from __future__ import annotations import warnings -from contextlib import ExitStack from typing import TYPE_CHECKING, Any import numpy as np @@ -44,9 +41,6 @@ fibre, window, ) -from sessions.test_group import PLANES as GROUP_PLANES -from sessions.test_group import member -from sessions.test_native_group import INTEGRATORS, _lone, _record, _same, _started from sessions.test_native_session import ( CASES, DENSE, @@ -82,7 +76,6 @@ from solprop.translate.run_request import RunRequest native_session = pytest.importorskip("solprop_native.session") -native_group = pytest.importorskip("solprop_native.group") pytestmark = pytest.mark.gpu @@ -345,25 +338,6 @@ def test_a_wide_or_off_route_coupled_flow_repeats_itself_on_the_device(kind): assert_same_run(run, baseline) -@pytest.mark.parametrize("name", sorted(INTEGRATORS)) -def test_a_native_group_member_is_its_lone_session_on_the_device(name): - """A group of three fixed-schedule members on each march, in the native group - session -- one native session per member on the device -- and each member alone in - its native session: each member's fields, statistics, attempts and rows the same, - bitwise.""" - with ExitStack() as cleanup: - simulations = [member(index, "native", INTEGRATORS[name]) for index in range(3)] - group = _started(simulations, cleanup) - assert isinstance(group, native_group.NativeGroupSession) - native = _record(group) - alone = [_lone(member(index, "native", INTEGRATORS[name])) for index in range(3)] - for index, (ours, theirs) in enumerate(zip(native, alone, strict=True)): - assert len(ours) == len(theirs) == len(GROUP_PLANES) + 1 - for plane, (one, other) in enumerate(zip(ours, theirs, strict=True)): - for key in one: - assert _same(one[key], other[key]), (index, plane, key) - - def test_the_production_door_serves_the_device_matrix_natively(): """SEP 47 phase 4: on a device build ``start_session`` serves an admitted run in the native session -- dense output and the low-storage replay among them.""" diff --git a/tests/sessions/test_native_session_history.py b/tests/sessions/test_native_session_history.py index 098f0e430..f954b8d5e 100644 --- a/tests/sessions/test_native_session_history.py +++ b/tests/sessions/test_native_session_history.py @@ -64,6 +64,7 @@ native_session = pytest.importorskip("solprop_native.session") native_backend = pytest.importorskip("solprop_native.backend") +_testing = pytest.importorskip("solprop_native._core")._testing LENGTH = PLANES[-1] @@ -501,7 +502,7 @@ def _armed(monkeypatch, stage: str, after: int, category: str) -> None: def arming(self) -> None: configure(self) - self._backend._native_state.adams_march_fault(stage, after, category) + _testing.adams_march_fault(self._backend._native_state, stage, after, category) monkeypatch.setattr(march, "_configure", arming) diff --git a/tests/sessions/test_native_session_low_storage.py b/tests/sessions/test_native_session_low_storage.py index be23d294c..83beca03e 100644 --- a/tests/sessions/test_native_session_low_storage.py +++ b/tests/sessions/test_native_session_low_storage.py @@ -53,6 +53,7 @@ native_session = pytest.importorskip("solprop_native.session") _counters = pytest.importorskip("solprop_native._counters") +_testing = pytest.importorskip("solprop_native._core")._testing LENGTH = PLANES[-1] STEPS = 40 @@ -133,7 +134,9 @@ def __init__(self, *args: Any, after: int, **kwargs: Any) -> None: def _prepare(self, backend, start): """Prepare as the session does, then arm the native failure.""" prepared = super()._prepare(backend, start) - backend._native_state.adams_march_fault("trial", self._after, "backend") + _testing.adams_march_fault( + backend._native_state, "trial", self._after, "backend" + ) return prepared diff --git a/tests/sessions/test_native_session_monitor.py b/tests/sessions/test_native_session_monitor.py index da0203b5c..c768e3ce0 100644 --- a/tests/sessions/test_native_session_monitor.py +++ b/tests/sessions/test_native_session_monitor.py @@ -47,6 +47,7 @@ trace, ) from solprop.backends.events import ( + Eligibility, EventBatch, ObservationReady, Outcome, @@ -391,6 +392,9 @@ def test_a_raised_final_warning_is_a_failure_with_its_field(): reference, native = _both(lambda: walker(0.9e-12, check=check), error=True) terminal = reference.run.terminal assert terminal.outcome is Outcome.FAILED + # The final check runs at the run's end, after its last plane: the committed state + # there stays eligible for a checkpoint. + assert terminal.eligibility is Eligibility.ELIGIBLE assert native.raised is not None assert terminal.error is not None assert type(native.raised[1]) is type(terminal.error) diff --git a/tests/sessions/test_native_session_statistics.py b/tests/sessions/test_native_session_statistics.py index 90aa1c80c..da815e221 100644 --- a/tests/sessions/test_native_session_statistics.py +++ b/tests/sessions/test_native_session_statistics.py @@ -21,6 +21,7 @@ """ import dataclasses +import functools import math import re @@ -54,8 +55,8 @@ native_session = pytest.importorskip("solprop_native.session") native_statistics = pytest.importorskip("solprop_native._statistics") +_testing = pytest.importorskip("solprop_native._core")._testing from solprop_native import ( # noqa: E402 # pyright: ignore[reportMissingImports] - _core, _counters, ) @@ -350,7 +351,7 @@ def test_the_native_width_is_solprop_s_crossing_to_the_bit(outer): for trace in traces: start, end = _half_max_range(t, trace, outer=outer) expected = end - start - got = _core.half_width(t, trace, outer) + got = _testing.half_width(t, trace, outer) if math.isnan(expected): assert math.isnan(got) else: @@ -588,7 +589,7 @@ def test_a_native_plan_refusal_is_the_reference_s_exception(): state = load_native(backend, problem.initial.field0, clear_fsal=False) with pytest.raises(SolpropError) as caught: try: - state.planned_statistics(lowering.plan, far) + _testing.planned_statistics(state, lowering.plan, far) except (ValueError, IndexError, RuntimeError) as error: raise native_statistics.translated(error) from error finally: @@ -861,11 +862,16 @@ def _host_widths(problem, run_request, grid, record, monkeypatch): # The record's exported state, loaded into the native state itself. state = load_native(backend, record.field, clear_fsal=False) packed = np.ravel( - state.spatial_statistics(32 if plane else 16, 0.5 * EPS0 * C, record.z) + _testing.spatial_statistics( + state, 32 if plane else 16, 0.5 * EPS0 * C, record.z + ) ) if plane: return plane_fluence_widths( - geometry, packed, n_terms, state.plane_fluence_trace + geometry, + packed, + n_terms, + functools.partial(_testing.plane_fluence_trace, state), ) count = problem.transform.n_nodes budget = fluence_budget(np.full(count, packed[count + 1]), n_terms) diff --git a/tests/sessions/test_prepare.py b/tests/sessions/test_prepare.py index cf132df64..5d2565632 100644 --- a/tests/sessions/test_prepare.py +++ b/tests/sessions/test_prepare.py @@ -16,16 +16,13 @@ from scripted_driver import HostScriptedDriver from sessions.executors import fibre, soliton, window -from solprop.backends.host.group_session import HostPreparedGroup from solprop.backends.host.session import HostPrepared, HostSession from solprop.backends.protocol import Backend from solprop.backends.registry import available, select from solprop.backends.session import ( PreparedExecution, - PreparedGroup, SessionError, Start, - check_group, ) from solprop.backends.sessions import start_session from solprop.exceptions import BackendError @@ -69,18 +66,6 @@ def test_a_closed_reference_preparation_closes_its_backend_and_refuses_to_start( prepared.start(Start.entrance(problem)) -def test_the_reference_prepares_its_own_group(): - problem, request = soliton() - backend = _select("numpy_ref", problem, request) - try: - prepared = backend.prepare_group([backend], [problem], [request]) - assert type(prepared) is HostPreparedGroup - assert isinstance(prepared, PreparedGroup) - assert prepared.backend == "numpy_ref" - finally: - backend.close() - - @NATIVE def test_a_native_backend_prepares_the_native_session(): from solprop_native.session import ( # noqa: PLC0415 - optional # pyright: ignore[reportMissingImports] @@ -233,17 +218,6 @@ def test_the_run_layer_refuses_it_before_a_session_starts(names, match): simulation.run() -def test_a_group_refuses_it_for_any_member(): - from solprop.stats import StatsSpec # noqa: PLC0415 - - problem, request = soliton() - run = request.for_run(stats=StatsSpec(names=("plasma_work_defect",))) - entrance = Start.entrance(problem) - with pytest.raises(BackendError, match="field-grid plasma column"): - members, starts = [object(), object()], [entrance, Start.entrance(problem)] - check_group(members, [problem, problem], [request, run], starts) - - def test_a_spatial_route_refuses_a_modal_statistic_on_every_executor(): from backends.test_native_widths import _simulation # noqa: PLC0415 from solprop.grid import FreeGrid # noqa: PLC0415 diff --git a/tests/stepper/test_low_storage.py b/tests/stepper/test_low_storage.py index 1a3bcdc6d..a6a5e1bdb 100644 --- a/tests/stepper/test_low_storage.py +++ b/tests/stepper/test_low_storage.py @@ -26,7 +26,7 @@ def test_the_specification_names_and_counts_itself(): assert method.name == "low-storage-rk4ip" assert (method.order, method.evaluations) == (4, 4) assert method.real_stability_interval == LOW_STORAGE_REAL_INTERVAL == 2.785 - # Frozen, and equal by value: a lockstep batch compares members' integrators. + # Frozen, and equal by value: two runs compare their integrators. assert method == LowStorageRungeKutta(scheme="rk4ip") with pytest.raises(dataclasses.FrozenInstanceError): method.scheme = "rk4ip" # type: ignore[misc] diff --git a/tests/stepper/test_schedule.py b/tests/stepper/test_schedule.py index 78e037dd9..4716a6a06 100644 --- a/tests/stepper/test_schedule.py +++ b/tests/stepper/test_schedule.py @@ -413,8 +413,8 @@ def test_step_target_validation_rejects_a_broken_set(overrides, message): @pytest.mark.parametrize("factor", [0.37, 0.5, 1.7, 3.0]) def test_rescaling_the_same_schedule_twice_is_bitwise_identical(factor): # Replaying a scaled schedule has to be a replay, not an approximation: every - # ensemble member and every batch lane in lockstep must take exactly the same - # steps, or the numerical error stops being a common systematic. + # ensemble member must take exactly the same steps, or the numerical error stops + # being a common systematic. schedule = FixedSchedule(np.array([0.4, 0.4, 0.2, 0.13, 0.07])) first = schedule.rescaled(factor) second = FixedSchedule(np.array([0.4, 0.4, 0.2, 0.13, 0.07])).rescaled(factor) diff --git a/tests/test_benchmark_sessions.py b/tests/test_benchmark_sessions.py index 98cc4c801..5722606a0 100644 --- a/tests/test_benchmark_sessions.py +++ b/tests/test_benchmark_sessions.py @@ -7,7 +7,7 @@ Each case of the ``sep47`` set runs once, briefly, with the native adapter's structural counters on (``benchmarks.worker.measure(count_events=True)``), and its counts must show the events it was declared for: a statistics row at every accepted step, snapshots -serviced, a group's common steps, the native march of a coupled flow. Every run is +serviced, the native march of a coupled flow. Every run is served by the native execution session, as in production (SEP 47 section 7.3). """ @@ -35,7 +35,6 @@ "snapshots_every", "with_input_repeat", "scan_local", - "group_batch", ) @@ -81,7 +80,6 @@ def test_the_set_holds_the_matrix_and_keeps_older_digests(): {"workload": "absent"}, {"output": "disk"}, {"fields": "some"}, - {"workload": "group"}, {"snapshots": 1}, ], ) @@ -96,9 +94,6 @@ def test_field_free_and_scanned_cases_build_their_retention(): # A scan's points keep the default; run_scan sets what the scan keeps. scanned = build(CASES["scan_local"].configuration("default", 1)) assert scanned.settings.fields == "all" - group = build(CASES["group_batch"].configuration("default", 1)) - assert group.settings.schedule is not None - assert group.settings.schedule.n_steps == 10 snapshots = build(CASES["snapshots_every"].configuration("default", 1)) assert snapshots.settings.step_planes == 1 @@ -161,7 +156,7 @@ def test_snapshot_cases_service_what_they_ask_for(name, every, tmp_path): # A registered benchmark case propagated: the harness's real-case runs are slow # (testing.md section 2); its logic is tested in the default lane. @pytest.mark.slow -def test_repeated_inputs_scans_and_groups_run_their_members(tmp_path): +def test_repeated_inputs_and_scans_run_their_members(tmp_path): _, run, counts = counted("with_input_repeat", tmp_path) assert run["runs"] == 3 assert run["finite"] is True @@ -189,25 +184,6 @@ def test_repeated_inputs_scans_and_groups_run_their_members(tmp_path): # A field-free scan's members never copy a field to the host. assert counts["field_crossings"] == {} assert counts["field_bytes"] == 0 - _, run, counts = counted("group_batch", tmp_path / "group", fraction=0.5) - schedule = build(CASES["group_batch"].configuration("default", 1, "native", 0.5)) - assert schedule.settings.schedule is not None - steps = schedule.settings.schedule.n_steps - assert counts["group_steps"] == steps > 1 - # The native group session: each member's native session returns at its launch, - # at each plane and at its end, its steps native; and each point's resource - # probe, a native session of its own, at its launch. - planes = len(schedule.settings.save_planes) - assert counts["native_returns"] == { - "session_observation": 4 * (planes + 1) + 4, - "session_terminal": 4, - } - assert counts["field_loads"] == {"start": 8} - assert counts["field_crossings"] == {} - assert counts["attempts"] == counts["accepted"] == 4 * steps - assert counts["host_attempts"] == 0 - # Batch watches no point's run: its steps are uncounted, not zero. - assert (run["accepted"], run["rejected"], run["finite"]) == (None, None, True) def test_counters_attribute_a_host_step_to_the_work_due_on_it(): diff --git a/tests/test_far_field_statistics.py b/tests/test_far_field_statistics.py index 4c5ccf789..2b37c247d 100644 --- a/tests/test_far_field_statistics.py +++ b/tests/test_far_field_statistics.py @@ -936,9 +936,6 @@ def test_a_spec_refuses_a_missing_or_malformed_table(): StatsSpec(names=("beam_spectrum",), periodic=("beam_spectrum",)) spec = StatsSpec(names=("energy",), apertures=apertures()) assert (spec.n_apertures, spec.n_regions, StatsSpec().n_apertures) == (1, 0, 0) - assert spec.same_tables(StatsSpec(apertures=apertures())) - assert not spec.same_tables(StatsSpec()) - assert not StatsSpec().same_tables(spec) def test_collect_refuses_the_operator_statistics_and_non_cartesian_grids(grid): diff --git a/tests/test_monitor.py b/tests/test_monitor.py index 6d3af8b31..c39296d57 100644 --- a/tests/test_monitor.py +++ b/tests/test_monitor.py @@ -29,11 +29,11 @@ from solprop.backends.ledger import CallLedger from solprop.backends.registry import available from solprop.constants import C -from solprop.driver import Simulation, SimulationSettings, _scan_batch, prop_gnlse -from solprop.driver.executors import Batch, Local +from solprop.driver import Simulation, SimulationSettings, prop_gnlse +from solprop.driver.executors import Local from solprop.driver.scan import Scan, ScanPoint, run_scan from solprop.driver.session_loop import _earlier_execution -from solprop.exceptions import BackendError, BoundaryError, BoundaryWarning, OutputError +from solprop.exceptions import BackendError, BoundaryError, BoundaryWarning from solprop.grid import EnvelopeGrid, FieldGrid, RadialGrid from solprop.log import NullReporter from solprop.monitor import ( @@ -647,8 +647,8 @@ def test_only_the_quiet_collar_is_part_of_the_resume_key() -> None: def _walking_point(point: ScanPoint) -> Simulation: """Return a scan point whose pulse walks ``drift`` windows over the fibre. - On a fixed schedule, as a batch needs, and without a collar, so that light that - walks out of the window wraps into the opposite guard. + On a fixed schedule, and without a collar, so that light that walks out of the + window wraps into the opposite guard. """ trange = 3 * TRANGE grid = EnvelopeGrid.from_limits( @@ -669,53 +669,23 @@ def _walking_point(point: ScanPoint) -> Simulation: ) # fmt: skip -def test_a_batched_scan_fails_the_point_a_lone_run_fails(tmp_path: Path) -> None: - # Each batch member watches its own window: the point whose pulse walks out is - # stopped and failed, the other completes, as the points run one by one. - scan = Scan("walk", drift=[0.0, 0.9]) - for name, executor in (("local", Local()), ("batch", Batch(2))): - path = tmp_path / f"{name}.h5" - with warnings.catch_warnings(): - warnings.simplefilter("ignore", BoundaryWarning) - output = run_scan( - scan, _walking_point, executor=executor, output=path, progress="none" - ) - assert output.status.tolist() == ["done", "failed"], name - error = str(read_point(path, 1)["error"]) - assert "BoundaryError" in error, name - assert "could not be persisted" not in error, name - - -def test_a_batched_point_keeps_its_first_failure_when_its_boundary_stops_it_later( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch -) -> None: - # The walking point's capture fails at its launch plane; its boundary stop later - # in the same group is a second failure, and the point keeps the first. - original = _scan_batch._Capture.save - order: list[int] = [] - - def capture(self: Any, plane: Any) -> None: - if id(self) not in order: - order.append(id(self)) - if order.index(id(self)) == 1: - raise OutputError("member capture unavailable") - original(self, plane) - - monkeypatch.setattr(_scan_batch._Capture, "save", capture) - path = tmp_path / "batch.h5" +def test_a_scan_fails_the_point_whose_boundary_stops_it(tmp_path: Path) -> None: + # Each point watches its own window: the point whose pulse walks out is stopped + # and failed, and the other completes. + path = tmp_path / "local.h5" with warnings.catch_warnings(): warnings.simplefilter("ignore", BoundaryWarning) output = run_scan( Scan("walk", drift=[0.0, 0.9]), _walking_point, - executor=Batch(2), + executor=Local(), output=path, progress="none", ) assert output.status.tolist() == ["done", "failed"] error = str(read_point(path, 1)["error"]) - assert "member capture unavailable" in error - assert "BoundaryError" not in error + assert "BoundaryError" in error + assert "could not be persisted" not in error def test_without_a_check_nothing_is_watched() -> None: @@ -1578,50 +1548,39 @@ def test_a_scan_point_keeps_its_closing_monitor_record( pytest.skip(f"{backend} is not installed") scan = Scan("walk", drift=[0.0, 0.4, 1.2]) build = functools.partial(_walking_watched_point, backend=backend) - for name, executor in (("local", Local()), ("batch", Batch(3))): - path = tmp_path / f"{name}.h5" - with warnings.catch_warnings(): - warnings.simplefilter("ignore", BoundaryWarning) - run_scan( - scan, - build, - executor=executor, - output=path, - progress="none", - ) - for index in range(3): - found = read_point(path, index) - opened = cast("dict[str, Any]", found["metadata"])["backend"] - assert "boundary_monitor" not in opened.get("settings", {}), name - record = cast("dict[str, Any]", found["boundary_monitor"]) - assert "planes" not in record, name - assert record["steps"] > 0, name - stopped = cast("dict[str, Any]", read_point(path, 2)["boundary_monitor"]) - assert stopped["guard_high_max"] > 0.0 or stopped["guard_low_max"] > 0.0 + path = tmp_path / "local.h5" + with warnings.catch_warnings(): + warnings.simplefilter("ignore", BoundaryWarning) + run_scan(scan, build, executor=Local(), output=path, progress="none") + for index in range(3): + found = read_point(path, index) + opened = cast("dict[str, Any]", found["metadata"])["backend"] + assert "boundary_monitor" not in opened.get("settings", {}) + record = cast("dict[str, Any]", found["boundary_monitor"]) + assert "planes" not in record + assert record["steps"] > 0 + stopped = cast("dict[str, Any]", read_point(path, 2)["boundary_monitor"]) + assert stopped["guard_high_max"] > 0.0 or stopped["guard_low_max"] > 0.0 def test_a_warning_raised_as_an_error_fails_its_own_point_alone( tmp_path: Path, ) -> None: - scan = Scan("walk", drift=[0.0, 0.4, 1.2]) - statuses = {} - for name, executor in (("local", Local()), ("batch", Batch(3))): - path = tmp_path / f"{name}.h5" - with warnings.catch_warnings(): - warnings.simplefilter("error", BoundaryWarning) - output = run_scan( - scan, - _walking_watched_point, - executor=executor, - output=path, - progress="none", - ) - statuses[name] = output.status.tolist() - assert statuses[name][0] == "done", name - for index in (1, 2): - if statuses[name][index] == "failed": - assert "Boundary" in str(read_point(path, index)["error"]), name - assert statuses["batch"] == statuses["local"] + path = tmp_path / "local.h5" + with warnings.catch_warnings(): + warnings.simplefilter("error", BoundaryWarning) + output = run_scan( + Scan("walk", drift=[0.0, 0.4, 1.2]), + _walking_watched_point, + executor=Local(), + output=path, + progress="none", + ) + statuses = output.status.tolist() + assert statuses[0] == "done" + for index in (1, 2): + if statuses[index] == "failed": + assert "Boundary" in str(read_point(path, index)["error"]) @pytest.mark.parametrize("backend", ["numpy_ref", "native"]) diff --git a/tests/vector_raman_cases.py b/tests/vector_raman_cases.py index 735a46779..5be24742e 100644 --- a/tests/vector_raman_cases.py +++ b/tests/vector_raman_cases.py @@ -149,7 +149,11 @@ def result(backend_class, problem, run_request, grid, modes, options=CHUNK): backend._staged_rows() state = load_native(backend, problem.initial.field0, clear_fsal=False) native_trial(backend, 0.0, LENGTH / 8) - rhs = np.array(state.stage_to_host(0)) + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + + rhs = np.array(_testing.stage_to_host(state, 0)) run = run_session(backend, problem, run_request, owns=False) (final, state), *_ = reversed(saved(run)) assert final.z == LENGTH diff --git a/uv.lock b/uv.lock index 8b9032039..a21e7ebc4 100644 --- a/uv.lock +++ b/uv.lock @@ -1654,7 +1654,7 @@ dev = [ { name = "drawsvg", specifier = ">=2.4" }, { name = "hypothesis" }, { name = "myst-parser" }, - { name = "nanobind", specifier = ">=2.9" }, + { name = "nanobind", specifier = "==3.1.0" }, { name = "numpydoc", specifier = ">=1.9" }, { name = "poethepoet" }, { name = "pre-commit" },