From 56101a6075e996250d3dfc3c8b69c6d68a812db5 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 03:12:20 +0000 Subject: [PATCH 01/14] refactor(numpy_ref): workspace, engines and marches that own their state SEP 52 phase 3, step 1 of 2. NumpyWorkspace (numpy_ref/workspace.py) holds the state and every state-sized operation that NumpyRefBackend and HostDriver held: load, the stage scalars and the sources, the finish (which returns the split collar's sums, taken on the masked field before the split, in an AcceptRecord), the mask, the statistics, the boundary and edge readings, the quadrature alarm as a reading, the host source's reservation, the memory ledger. The `_adams_*` hooks become its march-neutral operations (source, lab_source, propagator, coupled_block). The engines implement the protocols of solprop.backends.engines over it: NumpyRungeKutta keeps its trial and commits only at accept; HostLowStorage is the same protocol with the destructive trial (in flight from trial to accept, the stiffness in its AcceptRecord); HostHistory takes the retained entries at accept, and the TDSE reservation as begin_attempt/end_attempt. The marches own their state: RungeKuttaMarch (new), HostAdamsMarch and HostLowStorageMarch each keep position, proposal, cursor and norms in a MarchState and ask the driver only through the narrow MarchHost. HostDriver keeps the scheduling and accumulates the split sums from each AcceptRecord. No number moves: the pinned corpus passes unchanged and its numpy_ref arrays are bitwise those of the parent commit on this build; the decision traces pass unchanged. Tests that called the moved private methods use the workspace and the engines; the trace harnesses and the scripted driver drive the new marches. Co-Authored-By: Claude Opus 5.5 --- docs/dev/figures/backends.svg | 73 +- docs/dev/figures/build.py | 27 +- docs/dev/figures/layers.svg | 16 +- native/tests/plasma_bounds.py | 16 +- native/tests/test_backend.py | 6 +- native/tests/test_band_column_budget.py | 12 +- native/tests/test_band_pathological.py | 8 +- native/tests/test_band_plasma.py | 10 +- native/tests/test_band_statistics_per_node.py | 6 +- native/tests/test_band_stress.py | 14 +- native/tests/test_coupled_flow.py | 2 +- native/tests/test_dispersive.py | 4 +- native/tests/test_envelope_plasma.py | 4 +- native/tests/test_envelope_subnormal.py | 8 +- native/tests/test_radial.py | 6 +- src/solprop/backends/host/adams.py | 716 ++-- src/solprop/backends/host/driver.py | 1198 ++---- src/solprop/backends/host/low_storage.py | 220 +- src/solprop/backends/host/marches.py | 188 + src/solprop/backends/host/runge_kutta.py | 289 ++ src/solprop/backends/low_storage.py | 257 +- src/solprop/backends/numpy_ref/backend.py | 2788 +------------- src/solprop/backends/numpy_ref/engines.py | 280 ++ src/solprop/backends/numpy_ref/multistep.py | 555 ++- src/solprop/backends/numpy_ref/workspace.py | 3370 +++++++++++++++++ tests/backends/adams_traces.py | 133 +- tests/backends/free_rows.py | 2 +- tests/backends/general_rows.py | 2 +- tests/backends/native_mixture_launch_probe.py | 7 +- tests/backends/rk_traces.py | 114 +- tests/backends/session_rows.py | 8 +- tests/backends/synthetic_leaf_cases.py | 6 +- tests/backends/test_backend_ladder.py | 1 - tests/backends/test_carrier_frame.py | 10 +- tests/backends/test_compiled_multistep.py | 2 +- tests/backends/test_dispersive_kerr.py | 8 +- tests/backends/test_dispersive_kerr_routes.py | 2 +- tests/backends/test_driver.py | 142 +- tests/backends/test_envelope_plasma_host.py | 8 +- tests/backends/test_exponential_coupled.py | 3 +- tests/backends/test_exponential_march.py | 34 +- tests/backends/test_exponential_routes.py | 4 +- tests/backends/test_exponential_varying.py | 3 +- tests/backends/test_free_absorber.py | 2 +- tests/backends/test_free_boundaries.py | 6 +- tests/backends/test_free_noise.py | 13 +- tests/backends/test_general_modal.py | 2 +- tests/backends/test_held_plasma_routes.py | 23 +- tests/backends/test_kperp_collar.py | 8 +- tests/backends/test_low_storage.py | 105 +- tests/backends/test_mixture_statistics.py | 2 +- tests/backends/test_monitor_reduction.py | 2 +- tests/backends/test_multistep_march.py | 4 +- tests/backends/test_native_error_norm.py | 13 +- .../test_native_held_projection_budget.py | 14 +- .../backends/test_native_mixture_fractions.py | 12 +- .../backends/test_native_planar_statistics.py | 4 +- tests/backends/test_node_chunk.py | 2 +- tests/backends/test_numpy_mixture_raman.py | 24 +- tests/backends/test_numpy_ref_backend.py | 14 +- tests/backends/test_numpy_ref_multimode.py | 14 +- tests/backends/test_numpy_ref_plasma.py | 10 +- tests/backends/test_numpy_ref_raman.py | 25 +- tests/backends/test_on_axis_statistics.py | 13 +- tests/backends/test_optmat_cases.py | 4 +- tests/backends/test_polarised_runs.py | 6 +- tests/backends/test_radial_absorber.py | 6 +- tests/backends/test_records.py | 2 +- tests/backends/test_reference_independence.py | 21 +- tests/backends/test_source_evaluations.py | 13 +- tests/backends/test_tdse_native.py | 10 +- tests/backends/test_vector_raman.py | 19 +- tests/builders.py | 18 +- tests/driver/test_abandoned_step.py | 6 +- tests/driver/test_coherent_capillary.py | 2 +- tests/driver/test_estimate.py | 10 +- tests/driver/test_field_free_planes.py | 11 +- tests/driver/test_grin_system.py | 2 +- tests/driver/test_native_coupled_flow.py | 2 +- tests/driver/test_native_flow_marches.py | 2 +- tests/driver/test_native_flow_pathological.py | 5 +- tests/driver/test_native_flow_refusals.py | 2 +- tests/driver/test_native_moving_guide.py | 6 +- .../driver/test_native_moving_guide_bound.py | 4 +- tests/driver/test_plane_adoption.py | 4 +- tests/driver/test_plasma_band_propagation.py | 4 +- tests/driver/test_resume.py | 4 +- tests/driver/test_resume_history.py | 5 +- tests/driver/test_runner.py | 4 +- tests/driver/test_snapshots.py | 2 +- tests/flow_parity.py | 10 +- tests/general_parity.py | 2 +- tests/march_bounds.py | 6 +- tests/monitor_cases.py | 3 +- .../test_kerr_coefficient_per_true_watt.py | 2 +- tests/parity_ladder.py | 8 +- tests/scripted_driver.py | 43 +- tests/sessions/executors.py | 13 +- tests/sessions/test_native_load.py | 4 +- tests/test_transverse_reads.py | 13 +- tests/translate/test_operator_settings.py | 11 +- tests/vector_raman_cases.py | 6 +- tests/wall_gas_cases.py | 4 +- 103 files changed, 6144 insertions(+), 5029 deletions(-) create mode 100644 src/solprop/backends/host/marches.py create mode 100644 src/solprop/backends/host/runge_kutta.py create mode 100644 src/solprop/backends/numpy_ref/engines.py create mode 100644 src/solprop/backends/numpy_ref/workspace.py diff --git a/docs/dev/figures/backends.svg b/docs/dev/figures/backends.svg index ac542c1ef..fc85044a4 100644 --- a/docs/dev/figures/backends.svg +++ b/docs/dev/figures/backends.svg @@ -1,6 +1,6 @@ + width="1200" height="733.0" viewBox="0 0 1200 733.0"> - + 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. @@ -94,23 +94,25 @@ text { font-family: Inter, "Helvetica Neue", Helvetica, Arial, sans-serif; fill: 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 + +HostDriver (the reference's scheduler) +the planes and the halts +propagate_to · _natural_stop · request_halt +the replay's cursor +_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 boundary monitor +attach_monitor · _absorb · _boundary_energies +the caps a march asks for +_quiet_capped · _transverse_capped +the march's state, read +_z · _proposal · _schedule_index + the stepper it drives stepper.tableau DOPRI5, Tsit5, the order-condition checks @@ -119,27 +121,26 @@ text { font-family: Inter, "Helvetica Neue", Helvetica, Arial, sans-serif; fill: 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. +the quadrature alarm +_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 +NumpyWorkspace · engines · marches + + + +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 +NumpyWorkspace · engines · marches +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 5ad7b7a1e..a4dc4c9b2 100644 --- a/docs/dev/figures/build.py +++ b/docs/dev/figures/build.py @@ -745,6 +745,8 @@ class Layer(NamedTuple): "backends/host/", ( "driver", + "marches", + "runge_kutta", "adams", "low_storage", "session", @@ -754,6 +756,8 @@ class Layer(NamedTuple): "backends/numpy_ref/", ( "backend", + "workspace", + "engines", "passes", "multistep", "populations", @@ -1250,20 +1254,15 @@ class Pass(NamedTuple): `HostStepping`'s, which its session drives.""" DRIVER_PARTS = ( - ("the march and the landing", ("_march_to",)), - ("the replay", ("_replay_to", "_schedule_index_at")), + ("the planes and the halts", ("propagate_to", "_natural_stop", "request_halt")), + ("the replay's cursor", ("_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"), - ), - ( - "what a backend supplies", - ("_trial_step", "_apply_mask", "_finish", "_begin_plane", "_on_accepted_step"), - ), + ("the boundary monitor", ("attach_monitor", "_absorb", "_boundary_energies")), + ("the caps a march asks for", ("_quiet_capped", "_transverse_capped")), + ("the march's state, read", ("_z", "_proposal", "_schedule_index")), + ("the quadrature alarm", ("_begin_plane", "_on_accepted_step")), ) """What `backends/host/driver.py` owns, and the `HostDriver` members of each part.""" @@ -2555,8 +2554,8 @@ def _step_panel( _text(drawing, line, x + PAD + 8, cursor, size=SMALL_SIZE, klass="dim") -BACKEND_OVERRIDES = ("_trial_step", "_apply_mask", "_finish", "_observed_field") -"""What a reference backend supplies to `HostDriver`, and nothing else of the loop.""" +BACKEND_OVERRIDES = ("NumpyWorkspace", "engines", "marches") +"""What the reference backend supplies to `HostDriver`, and nothing else of the loop.""" DEVICE_SLOT = ( "solprop-native distribution, native/", @@ -2660,7 +2659,7 @@ def backends() -> drawsvg.Drawing: _table( drawing, Slot(MARGIN, y, left_width), - "HostDriver (the reference's step loop)", + "HostDriver (the reference's scheduler)", driver_rows, 168, Paint("fill-d", "ink-d"), diff --git a/docs/dev/figures/layers.svg b/docs/dev/figures/layers.svg index ef64aef0c..213904bc5 100644 --- a/docs/dev/figures/layers.svg +++ b/docs/dev/figures/layers.svg @@ -189,15 +189,15 @@ text { font-family: Inter, "Helvetica Neue", Helvetica, Arial, sans-serif; fill: exponential · low_storage · session events · export · session_core sessions - + backends/host/ -driver · adams · low_storage -session - -backends/numpy_ref/ -backend · passes · multistep -populations · envelope_plasma -general_modal +driver · marches · runge_kutta +adams · low_storage · session + +backends/numpy_ref/ +backend · workspace · engines +passes · multistep · populations +envelope_plasma · general_modal D diff --git a/native/tests/plasma_bounds.py b/native/tests/plasma_bounds.py index a0b2882b2..6ca7f773a 100644 --- a/native/tests/plasma_bounds.py +++ b/native/tests/plasma_bounds.py @@ -242,8 +242,8 @@ def node_field_error( size = grids.n_to * transform.n_nodes return np.full(fields.shape, fft_bound(size) * float(np.linalg.norm(fields))) state = reference._require_state() # pyright: ignore[reportPrivateUsage] - kind = reference._kind # pyright: ignore[reportPrivateUsage] - bundle = reference._stage_scalars(0.0, 0.0) # pyright: ignore[reportPrivateUsage] + kind = reference.workspace._kind # pyright: ignore[reportPrivateUsage] + bundle = reference.workspace.stage_scalars(0.0, 0.0) # pyright: ignore[reportPrivateUsage] taper = float(bundle.taper_scale) modal = np.real_if_close( passes.to_time(state, grids.crop_index, grids.n_to, kind=kind) @@ -386,8 +386,8 @@ def stage_error( * float(np.max(abs(prefactor * window))) * float(np.max(joined)) ) - bundle = reference._stage_scalars(0.0, 0.0) # pyright: ignore[reportPrivateUsage] - prefactor = reference._prefactor(bundle) # pyright: ignore[reportPrivateUsage] + bundle = reference.workspace.stage_scalars(0.0, 0.0) # pyright: ignore[reportPrivateUsage] + prefactor = reference.workspace.prefactor(bundle) # pyright: ignore[reportPrivateUsage] n_nodes, n_pol_node, n_omega = nodes.shape columns = nodes.reshape( n_nodes * transform.n_pol, n_pol_node // transform.n_pol, n_omega @@ -410,15 +410,15 @@ def plasma_stage_bound( reference = NumpyRefBackend(problem, run_request, grid=grid) try: reference.set_initial(problem.initial.field0, None) - reference._hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe + reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe state = reference._require_state() # pyright: ignore[reportPrivateUsage] - bundle = reference._stage_scalars(0.0, 0.0) # pyright: ignore[reportPrivateUsage] - stage = reference._nonlinear( # pyright: ignore[reportPrivateUsage] + bundle = reference.workspace.stage_scalars(0.0, 0.0) # pyright: ignore[reportPrivateUsage] + stage = reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] state, bundle, np.ones(problem.shape, complex) ) fields = np.real( np.concatenate( - list(reference._plasma_nodes(state)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] ) ) field_error = node_field_error(reference, problem, fields) diff --git a/native/tests/test_backend.py b/native/tests/test_backend.py index bc2c258d2..93fc19ee9 100644 --- a/native/tests/test_backend.py +++ b/native/tests/test_backend.py @@ -886,11 +886,11 @@ def test_packed_real_blas_radial_envelope_matches_the_reference_when_eligible() reference = NumpyRefBackend(problem, run_request, grid=grid) try: reference.set_initial(problem.initial.field0, None) - reference._hoist(0.0) # pyright: ignore[reportPrivateUsage] + reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] expected = np.asarray( - reference._nonlinear( # pyright: ignore[reportPrivateUsage] + reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] reference._require_state(), # pyright: ignore[reportPrivateUsage] - reference._stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] + reference.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] np.ones(problem.shape, complex), ) ) diff --git a/native/tests/test_band_column_budget.py b/native/tests/test_band_column_budget.py index 57c693b5a..015075328 100644 --- a/native/tests/test_band_column_budget.py +++ b/native/tests/test_band_column_budget.py @@ -227,10 +227,10 @@ def stages( reference = NumpyRefBackend(problem, run_request, grid=GRID) try: reference.set_initial(problem.initial.field0, None) - reference._hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe - expected = reference._nonlinear( # pyright: ignore[reportPrivateUsage] + reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe + expected = reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] reference._require_state(), # pyright: ignore[reportPrivateUsage] - reference._stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] + reference.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] np.ones(problem.shape, complex), ) finally: @@ -275,12 +275,12 @@ def launch_fraction_bound( reference = NumpyRefBackend(problem, run_request, grid=GRID) try: reference.set_initial(problem.initial.field0, None) - reference._hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe + reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe state = reference._require_state() # pyright: ignore[reportPrivateUsage] - bundle = reference._stage_scalars(0.0, 0.0) # pyright: ignore[reportPrivateUsage] + bundle = reference.workspace.stage_scalars(0.0, 0.0) # pyright: ignore[reportPrivateUsage] fields = np.real( np.concatenate( - list(reference._plasma_nodes(state)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] ) ) field_error = node_field_error(reference, problem, fields) diff --git a/native/tests/test_band_pathological.py b/native/tests/test_band_pathological.py index 29d4fc6a0..ae6086c6c 100644 --- a/native/tests/test_band_pathological.py +++ b/native/tests/test_band_pathological.py @@ -172,7 +172,7 @@ def synthesised( state = reference._require_state() # pyright: ignore[reportPrivateUsage] return np.real( np.concatenate( - list(reference._plasma_nodes(state)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] ) ) finally: @@ -186,10 +186,10 @@ def source_of_reference( reference = NumpyRefBackend(problem, run_request, grid=grid) try: reference.set_initial(problem.initial.field0, None) - reference._hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe - return reference._nonlinear( # pyright: ignore[reportPrivateUsage] + reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe + return reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] reference._require_state(), # pyright: ignore[reportPrivateUsage] - reference._stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] + reference.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] np.ones(problem.shape, complex), ) finally: diff --git a/native/tests/test_band_plasma.py b/native/tests/test_band_plasma.py index 76eaa583b..570792e2a 100644 --- a/native/tests/test_band_plasma.py +++ b/native/tests/test_band_plasma.py @@ -433,10 +433,10 @@ def test_one_evaluation_matches_the_reference() -> None: reference = NumpyRefBackend(problem, run_request, grid=grid) try: reference.set_initial(problem.initial.field0, None) - reference._hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe - expected = reference._nonlinear( # pyright: ignore[reportPrivateUsage] + reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe + expected = reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] reference._require_state(), # pyright: ignore[reportPrivateUsage] - reference._stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] + reference.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] np.ones(problem.shape, complex), ) finally: @@ -483,10 +483,10 @@ def test_every_stage_of_a_trial_matches_the_reference( reference = NumpyRefBackend(problem, run_request, grid=grid) try: reference.set_initial(problem.initial.field0, None) - reference._trial_step(0.0, dz) # pyright: ignore[reportPrivateUsage] - oracle + reference._runge_kutta_engine.trial(0.0, dz) # pyright: ignore[reportPrivateUsage] - oracle expected = [ np.asarray(stage) - for stage in reference._last_stages # pyright: ignore[reportPrivateUsage] + for stage in reference._runge_kutta_engine.stages # pyright: ignore[reportPrivateUsage] ] finally: reference.close() diff --git a/native/tests/test_band_statistics_per_node.py b/native/tests/test_band_statistics_per_node.py index 48cf0b901..1007615bd 100644 --- a/native/tests/test_band_statistics_per_node.py +++ b/native/tests/test_band_statistics_per_node.py @@ -146,7 +146,7 @@ def fields_of( state = reference._require_state() # pyright: ignore[reportPrivateUsage] return np.real( np.concatenate( - list(reference._plasma_nodes(state)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] ) ) finally: @@ -171,10 +171,10 @@ def node_fields_and_error( try: reference.set_initial(problem.initial.field0, None) state = reference._require_state() # pyright: ignore[reportPrivateUsage] - reference._hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe + reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe fields = np.real( np.concatenate( - list(reference._plasma_nodes(state)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] ) ) return fields, node_field_error(reference, problem, fields) diff --git a/native/tests/test_band_stress.py b/native/tests/test_band_stress.py index 69af69c62..f00fe9523 100644 --- a/native/tests/test_band_stress.py +++ b/native/tests/test_band_stress.py @@ -201,7 +201,7 @@ def node_fields( reference.set_initial(problem.initial.field0, None) state = reference._require_state() # pyright: ignore[reportPrivateUsage] return np.concatenate( - list(reference._plasma_nodes(state)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] ) finally: reference.close() @@ -273,10 +273,10 @@ def test_one_evaluation_matches_the_reference(kind: str) -> None: reference = NumpyRefBackend(problem, run_request, grid=grid) try: reference.set_initial(problem.initial.field0, None) - reference._hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe - expected = reference._nonlinear( # pyright: ignore[reportPrivateUsage] + reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe + expected = reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] reference._require_state(), # pyright: ignore[reportPrivateUsage] - reference._stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] + reference.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] np.ones(problem.shape, complex), ) finally: @@ -328,12 +328,12 @@ def test_the_launch_exposure_is_within_its_scan_bound(kind: str) -> None: reference = NumpyRefBackend(problem, run_request, grid=grid) try: reference.set_initial(problem.initial.field0, None) - reference._hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe + reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe state = reference._require_state() # pyright: ignore[reportPrivateUsage] - bundle = reference._stage_scalars(0.0, 0.0) # pyright: ignore[reportPrivateUsage] + bundle = reference.workspace.stage_scalars(0.0, 0.0) # pyright: ignore[reportPrivateUsage] fields = np.real( np.concatenate( - list(reference._plasma_nodes(state)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] ) ) field_error = node_field_error(reference, problem, fields) diff --git a/native/tests/test_coupled_flow.py b/native/tests/test_coupled_flow.py index 8f2068498..4a8382e93 100644 --- a/native/tests/test_coupled_flow.py +++ b/native/tests/test_coupled_flow.py @@ -30,7 +30,7 @@ import pytest from session_runs import run as run_session from solprop.backends.numpy_ref import NumpyRefBackend -from solprop.backends.numpy_ref.backend import ( +from solprop.backends.numpy_ref.workspace import ( _coupled_flow_maps, # pyright: ignore[reportPrivateUsage] _flow_action, # pyright: ignore[reportPrivateUsage] ) diff --git a/native/tests/test_dispersive.py b/native/tests/test_dispersive.py index d14803a95..04a25c61e 100644 --- a/native/tests/test_dispersive.py +++ b/native/tests/test_dispersive.py @@ -326,8 +326,8 @@ def test_one_evaluation_matches_the_reference(evaluator: str, thg: bool) -> None spectra.append(_testing.projected_to_host(state, False)) else: backend.set_initial(problem.initial.field0, None) - backend._adams_lab_source(problem.initial.field0, 0.0) # pyright: ignore[reportPrivateUsage] - projected = np.asarray(backend._last_projected) # pyright: ignore[reportPrivateUsage] + backend.workspace.lab_source(problem.initial.field0, 0.0) + projected = np.asarray(backend.workspace._last_projected) # pyright: ignore[reportPrivateUsage] spectra.append(np.asarray(np.fft.rfft(projected, axis=-1))) finally: backend.close() diff --git a/native/tests/test_envelope_plasma.py b/native/tests/test_envelope_plasma.py index 28af8e818..881fa46c7 100644 --- a/native/tests/test_envelope_plasma.py +++ b/native/tests/test_envelope_plasma.py @@ -180,9 +180,9 @@ def test_envelope_current_streams_use_large_radial_projection() -> None: ) try: reference.set_initial(problem.initial.field0, None) - expected = reference._nonlinear( # pyright: ignore[reportPrivateUsage] + expected = reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] problem.initial.field0, - reference._stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] + reference.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] np.ones(problem.shape, complex), ) state = load_native(actual, problem.initial.field0, clear_fsal=False) diff --git a/native/tests/test_envelope_subnormal.py b/native/tests/test_envelope_subnormal.py index 627f201d1..3c0589c8b 100644 --- a/native/tests/test_envelope_subnormal.py +++ b/native/tests/test_envelope_subnormal.py @@ -127,10 +127,10 @@ def evaluate( 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 - stage = backend._nonlinear( # pyright: ignore[reportAttributeAccessIssue, reportPrivateUsage, reportUnknownMemberType, reportUnknownVariableType] + backend.workspace.hoist(0.0) + stage = backend.workspace.nonlinear( # pyright: ignore[reportAttributeAccessIssue, reportPrivateUsage, reportUnknownMemberType, reportUnknownVariableType] backend._require_state(), # pyright: ignore[reportArgumentType, reportPrivateUsage] - backend._stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] + backend.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportAttributeAccessIssue] np.ones(problem.shape, complex), ) return stage, statistics # pyright: ignore[reportUnknownVariableType] @@ -147,7 +147,7 @@ def node_magnitude( reference.set_initial(problem.initial.field0, None) state = reference._require_state() # pyright: ignore[reportPrivateUsage] nodes = np.concatenate( - list(reference._plasma_nodes(state)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] ) return float(np.max(np.abs(nodes))) finally: diff --git a/native/tests/test_radial.py b/native/tests/test_radial.py index 2bfcebda4..76a85e414 100644 --- a/native/tests/test_radial.py +++ b/native/tests/test_radial.py @@ -108,11 +108,11 @@ def test_radial_partial_chunks_preserve_the_reference_source( reference = NumpyRefBackend(problem, run_request, grid=grid, options=options) try: reference.set_initial(problem.initial.field0, None) - reference._hoist(0.0) # pyright: ignore[reportPrivateUsage] + reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] expected = np.asarray( - reference._nonlinear( # pyright: ignore[reportPrivateUsage] + reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] reference._require_state(), # pyright: ignore[reportPrivateUsage] - reference._stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] + reference.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] np.ones(problem.shape, complex), ) ) diff --git a/src/solprop/backends/host/adams.py b/src/solprop/backends/host/adams.py index f202b5a0d..e79683c08 100644 --- a/src/solprop/backends/host/adams.py +++ b/src/solprop/backends/host/adams.py @@ -2,14 +2,16 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The reference's interaction-picture Adams march (SEP 13, SEP 14, SEP 47). - -The controller, history, ledger and lifecycle of :class:`HostAdamsMarch`, the NumPy -reference's own since SEP 47 phase 2 (the shared march it was copied from is deleted -with the native backend's step driver, phase 5). The state-sized arithmetic is the -shared stateless code (:mod:`solprop.backends.host`): the march hands every operation -of its fused and exponential paths to the host engine -(:class:`solprop.backends.numpy_ref.multistep.HostHistory`). The decisions are +"""The reference's Adams march (SEP 13, SEP 14, SEP 39, SEP 52). + +The controller, history, ledger and lifecycle of :class:`HostAdamsMarch`, over the +engine protocol (:class:`solprop.backends.engines.AdamsEngine`) that native's +``march::Engine`` mirrors: the reference's engine is +:class:`solprop.backends.numpy_ref.multistep.HostHistory`. The march holds its own +state -- position, proposal, replay cursor and accepted norms +(:class:`~solprop.backends.host.marches.MarchState`), the history's entries, the order, +the rejections and the call ledger -- and asks its session only through +:class:`~solprop.backends.host.marches.MarchHost`. The decisions are :mod:`solprop.backends.adams_core`'s functions of one policy record. The method, its lifecycle and its numbers are those of @@ -17,108 +19,104 @@ """ import math -from collections.abc import Iterator +from collections import deque +from collections.abc import Callable, Iterator, Mapping from contextlib import contextmanager -from typing import Any, Literal, cast +from typing import Any, cast import numpy as np from solprop._interrupts import committing from solprop.backends import adams_core -from solprop.backends.exponential import CarrierReference -from solprop.backends.host.driver import HostDriver, reached, replay_tolerance -from solprop.backends.ledger import CallLedger, Derivative -from solprop.backends.numpy_ref.multistep import ( - AdamsEngine, - AdamsKernels, - ExponentialKernels, - HostHistory, -) -from solprop.backends.records import adams_policy +from solprop.backends.engines import AdamsEngine, AttemptOutcome, HistoryEntry +from solprop.backends.host.marches import MarchHost, MarchState +from solprop.backends.ledger import CallLedger from solprop.exceptions import BackendError, ConvergenceError, ResponseBudgetError from solprop.output.records import MarchSnapshot from solprop.stepper.controller import limit_step from solprop.stepper.multistep import MarchPolicy, Multistep -from solprop.stepper.schedule import FixedSchedule, landing +from solprop.stepper.schedule import FixedSchedule, landing, reached, replay_tolerance __all__ = ["HostAdamsMarch"] class HostAdamsMarch: - """March a reference backend's state with an interaction-picture Adams method. + """March a state with an Adams method over an engine. Parameters ---------- - backend : solprop.backends.host.driver.HostDriver - The backend whose state, source evaluation and propagators are used. It owns - the step history and the statistics rows; this object owns the derivative - history and the call ledger. + engine : solprop.backends.engines.AdamsEngine + The engine that holds the history's rows. Beside the protocol, the march's + dense observation calls its ``hold``, ``restore`` and ``observe``, a load its + ``reset``, and a snapshot its ``n_slots``, ``snapshot_rows``, + ``snapshot_nbytes`` and ``load_rows``; SEP 52 moves those to the session. method : solprop.stepper.multistep.Multistep The method. - compensation : {'transported', 'untransported'}, optional - How a varying operator's linear compensation is integrated (SEP 16 Q8): - ``"transported"``, the delivered treatment, or ``"untransported"``, kept as a - test witness only. - engine : object, optional - An :class:`~solprop.backends.numpy_ref.multistep.AdamsEngine`; ``None``, the - default, takes the host engine - (:class:`~solprop.backends.numpy_ref.multistep.HostHistory`) over the backend's - hooks. A scripted engine drives the controller alone, for the decision traces - of SEP 39 section 7.1. Typed ``object`` because the engine protocol is - structural and not checkable at run time; the members the path calls are - checked here instead. + host : solprop.backends.host.marches.MarchHost + The session the march reports to. + policy : solprop.stepper.multistep.MarchPolicy + Every number the controller and the landings read (SEP 39 section 4.2). + field : callable + Returns the committed state, for a snapshot and a budget's error. + schedule : solprop.stepper.schedule.FixedSchedule or None, optional + The schedule to replay, or ``None`` to step adaptively. + interpolate : bool, optional + Whether the run interpolates its planes (ADR-036, ADR-039). + shape : tuple of int, optional + The state's shape, which a snapshot's is checked against. + proposal : float, optional + The first proposal, m. + lag : int, optional + The lag of the controller whose norms a replay keeps. + name : str, optional + The backend's name, for messages. + + Attributes + ---------- + state : solprop.backends.host.marches.MarchState + The march's position, proposal, cursor and accepted norms. + ledger : solprop.backends.ledger.CallLedger + The run's call counts. Raises ------ solprop.exceptions.BackendError - If `engine` lacks a member its path calls. + If `engine` lacks a member the march calls. """ def __init__( self, - backend: HostDriver[Any], + engine: object, method: Multistep, + host: object, *, - compensation: Literal["transported", "untransported"] = "transported", - engine: object = None, + policy: MarchPolicy, + field: Callable[[], np.ndarray], + schedule: FixedSchedule | None = None, + interpolate: bool = False, + shape: tuple[int, ...] = (), + proposal: float = 0.0, + lag: int = 1, + name: str = "numpy_ref", ) -> None: - """Hold the backend and start with no history.""" - self._backend = backend + """Hold the engine and start with no history.""" + _check_engine(engine) + self._engine: AdamsEngine = cast("AdamsEngine", engine) self._method = method - # Whether the run interpolates its planes, and with what (ADR-036, ADR-039). - self._interpolate = backend._stepper.interpolate_planes - self._kernels = AdamsKernels(helpers=backend.helpers) - # SEP 16's exponential formulation keeps untransported samples in the same - # store and shares everything else: the lifecycle, the controller, the ledger. - self._exponential: ExponentialKernels | None = None - if method.formulation == "exponential": - self._exponential = ExponentialKernels(helpers=backend.helpers) - # Every state-sized operation goes to an engine (SEP 16 phase 3b), the host - # one unless a scripted engine is given. - if engine is not None: - _check_engine(engine, exponential=self._exponential is not None) - self._engine: AdamsEngine = cast("AdamsEngine", engine) - else: - self._engine = HostHistory( - backend, method, self._kernels, self._exponential, compensation - ) - self._history: list[Derivative] = [] + self._host = cast("MarchHost", host) + self._policy = policy + self._field = field + self._schedule = schedule + self._interpolate = interpolate + self._shape = shape + self._name = name + self.state = MarchState(z=0.0, proposal=proposal, norms=deque(maxlen=lag + 2)) + self._history: list[HistoryEntry] = [] self._rejections = 0 self._last_rejected = False self._order = 1 if method.variable_order else method.order self._ahead: tuple[float, object] | None = None self.ledger = CallLedger() - # Every number the controller and the landings read, from one record (SEP 39 - # section 4.2); the decisions are `adams_core`'s functions of it. An in-stage - # temporal collar's largest rate, the one stiff term the exponential history - # integrates, bounds each order's stable step there (`_choose_order`). - carrier = self._engine.carrier - self._policy: MarchPolicy = adams_policy( - backend._problem, - backend._stepper, - method, - carrier=isinstance(carrier, CarrierReference) and carrier.active, - ) # Whether the stages left a quiet collar out at the last attempt: the step # after it returns is held to the collar's stable step (`_collar_reentry`). self._collar_was_quiet = False @@ -126,26 +124,49 @@ def __init__( # recorded (`_propose`, `_reject`, `_raise_floor`). self._floor: ConvergenceError | None = None - def reset(self) -> None: - """Forget the history: the state was loaded or changed outside the march.""" - self._history = [] - self._rejections = 0 - self._engine.reset() - self._ahead = None + @property + def holding(self) -> bool: # numpydoc ignore=RT01 + """Whether a dense observation holds the state at a plane, the march ahead.""" + return self._ahead is not None - def begin_run(self) -> None: - """Start a run's accounting afresh: the ledger and the last attempt's flags. + def load(self, z: float, proposal: float, cursor: int) -> None: + """Start a run afresh at a loaded position. - Called by :meth:`~solprop.backends.host.driver.HostDriver.set_initial`, so that - a backend loaded for another run counts that run's calls alone and chooses its + The history and the held trial are forgotten, and the run's accounting starts + afresh -- the ledger, the last rejection and the collar's flag -- so that a + backend loaded for another run counts that run's calls alone and chooses its first order and step as a fresh backend would (SEP 22 section 4.7, SEP 39 - R9): the last rejection and the collar's flag are cleared. A resume restores - its persisted ledger and flags afterwards. + R9). A resume restores its persisted ledger and flags afterwards. + + Parameters + ---------- + z : float + The position, m. + proposal : float + The first proposal, m. + cursor : int + The replay cursor at `z`. """ + self.state.load(z, proposal, cursor) self.ledger = CallLedger() self._last_rejected = False self._collar_was_quiet = False self._floor = None + self._history = [] + self._rejections = 0 + self._engine.reset() # pyright: ignore[reportAttributeAccessIssue] + self._ahead = None + + def restore_ledger(self, logical: Mapping[str, object]) -> None: + """Continue a resumed run's cumulative call counts. + + Parameters + ---------- + logical : collections.abc.Mapping + The persisted logical counts + (:meth:`solprop.backends.ledger.CallLedger.to_record`). + """ + self.ledger = CallLedger.from_record(logical) def snapshot(self) -> MarchSnapshot | None: """Return the march's state at its accepted position, for a resume. @@ -158,19 +179,19 @@ def snapshot(self) -> MarchSnapshot | None: """ if not self._history or self._ahead is not None: return None - export = self._engine.snapshot_rows - backend = self._backend + export = self._engine.snapshot_rows # pyright: ignore[reportAttributeAccessIssue] + state = self.state return MarchSnapshot( - z=float(backend._z), - state=np.array(backend._adams_state(), dtype=np.complex128, copy=True), - proposal=float(backend._proposal), + z=float(state.z), + state=np.array(self._field(), dtype=np.complex128, copy=True), + proposal=float(state.proposal), method=repr(self._method), order=int(self._order), rejections=int(self._rejections), last_rejected=bool(self._last_rejected), positions=np.array([entry.z for entry in self._history], dtype=np.float64), identities=tuple(entry.identity for entry in self._history), - slots=np.array([entry.slot for entry in self._history], dtype=np.int64), + slots=np.array([entry.row for entry in self._history], dtype=np.int64), rows=export(), collar_was_quiet=self._collar_was_quiet, history_key=self._method.history_key, @@ -187,18 +208,16 @@ def snapshot_nbytes(self) -> int | None: """ if not self._history or self._ahead is not None: return None - state = ( - math.prod(self._backend._problem.shape) * np.dtype(np.complex128).itemsize - ) - return state + self._engine.snapshot_nbytes() + state = math.prod(self._shape) * np.dtype(np.complex128).itemsize + return state + self._engine.snapshot_nbytes() # pyright: ignore[reportAttributeAccessIssue] - def load(self, snapshot: MarchSnapshot) -> str | None: - """Continue from a snapshot taken where the backend's state now stands. + def load_snapshot(self, snapshot: MarchSnapshot) -> str | None: + """Continue from a snapshot taken where the march now stands. - The backend has been loaded at the snapshot's position; this installs the - accepted state exactly as it was held, the history, the order, the rejection - count and the proposed step, so that the march goes on as the uninterrupted - one would have. Nothing is changed when the snapshot cannot be used. + The state was loaded at the snapshot's position; this installs the accepted + state exactly as it was held, the history, the order, the rejection count and + the proposed step, so that the march goes on as the uninterrupted one would + have. Nothing is changed when the snapshot cannot be used. Parameters ---------- @@ -210,18 +229,18 @@ def load(self, snapshot: MarchSnapshot) -> str | None: str or None ``None`` when the history was continued, otherwise why it starts afresh. """ - backend = self._backend reason = self._refusal(snapshot) if reason is not None: return reason - load_rows = self._engine.load_rows + engine = cast("Any", self._engine) try: - load_rows(snapshot.rows, backend._problem.shape) + engine.load_rows(snapshot.rows, self._shape) except BackendError as error: return str(error) - backend._adams_restore(snapshot.z, np.array(snapshot.state, copy=True)) + self.state.z = snapshot.z + engine.restore(snapshot.z, np.array(snapshot.state, copy=True)) self._history = [ - Derivative(float(z), self._engine.value(int(slot)), identity, int(slot)) + HistoryEntry(float(z), cast("Any", identity), int(slot)) for z, identity, slot in zip( snapshot.positions, snapshot.identities, snapshot.slots, strict=True ) @@ -231,15 +250,13 @@ def load(self, snapshot: MarchSnapshot) -> str | None: self._last_rejected = snapshot.last_rejected self._collar_was_quiet = snapshot.collar_was_quiet self._ahead = None - backend._proposal = snapshot.proposal + self.state.proposal = snapshot.proposal return None def _refusal(self, snapshot: MarchSnapshot) -> str | None: - """Return why a snapshot cannot continue this march, or ``None``. - - - Returns: the reason, or ``None`` when the snapshot fits. - """ - backend = self._backend + """Return why a snapshot cannot continue this march, or ``None``.""" + z = self.state.z + n_slots = cast("Any", self._engine).n_slots checks = ( ( snapshot.history_key != self._method.history_key, @@ -247,12 +264,12 @@ def _refusal(self, snapshot: MarchSnapshot) -> str | None: f"this run steps with {self._method.history_key}", ), ( - snapshot.z != backend._z, + snapshot.z != z, f"the snapshot is at z = {snapshot.z!r} m and the run resumes at " - f"z = {backend._z!r} m", + f"z = {z!r} m", ), ( - snapshot.state.shape != tuple(backend._problem.shape), + snapshot.state.shape != tuple(self._shape), f"the snapshot's state has shape {snapshot.state.shape}", ), ( @@ -263,11 +280,7 @@ def _refusal(self, snapshot: MarchSnapshot) -> str | None: "the snapshot's newest sample is not at its position", ), ( - bool( - np.any( - (snapshot.slots < 0) | (snapshot.slots >= self._engine.n_slots) - ) - ), + bool(np.any((snapshot.slots < 0) | (snapshot.slots >= n_slots))), "the snapshot's history names no row of this engine", ), ) @@ -275,8 +288,18 @@ def _refusal(self, snapshot: MarchSnapshot) -> str | None: # --- the march -------------------------------------------------------------------- + def advance(self, target: float) -> None: + """Step towards `target`: the schedule's replay, or adaptively. + + Parameters + ---------- + target : float + The position to reach, m. + """ + self.march_to(target) + def march_to(self, target: float) -> None: - """Step the backend's state adaptively to `target`, landing on it exactly. + """Step adaptively to `target`, landing on it exactly, or replay towards it. Parameters ---------- @@ -288,49 +311,45 @@ def march_to(self, target: float) -> None: ConvergenceError If the proposal falls below the contract's ``dz_min``. """ - backend = self._backend - settings = backend._stepper - dense = self._interpolate + host, state, engine = self._host, self.state, cast("Any", self._engine) if self._ahead is not None: # The march is ahead of the last observation; resume it there. - self._engine.restore(*self._ahead) + z, held = self._ahead + engine.restore(z, held) + state.z = z self._ahead = None - if backend._natural_stop_due(target): + if host.natural_stop_due(target): return - if settings.schedule is not None: - self._replay_to(settings.schedule, target) + if self._schedule is not None: + self._replay_to(self._schedule, target) return targets = adams_core.targets(self._policy, target) - while not reached(backend._z, target): - backend._poll_stop() - self._afford() - with _trial(backend): + while not reached(state.z, target): + host.poll_stop() + with self._attempt_scope() as attempt: if not self._history: self._start() proposal = self._collar_reentry( - backend._split_capped( - backend._transverse_capped( - self._quiet_capped(self._capped(backend._proposal)) - ) - ) + host.cap(self._capped(state.proposal), state.z) ) - stop = landing(backend._z, proposal, targets) + stop = landing(state.z, proposal, targets) dz, end, kink = adams_core.approach( - self._policy, backend._z, stop, targets, target + self._policy, state.z, stop, targets, target ) # The accepted step moves the position with the state, and restarts # the history at a kink, in one commit (`_land`). accepted, norm = self._attempt(dz, landing=(end, kink)) - backend._record(end, dz, norm, accepted) - self._raise_floor() - if accepted: - backend._take_step_stats() - if backend._natural_stop(target): - return - if dense and backend._z > target: - self._ahead = (backend._z, self._engine.hold()) - backend._state = cast("Any", self._observe(target)) - backend._z = target + host.record(end, dz, norm, accepted) + self._end(attempt, accepted=accepted) + if accepted: + host.stepped() + if host.natural_stop(target): + return + if self._interpolate and state.z > target: + observed = engine.observe(target) + self._ahead = (state.z, engine.hold()) + engine.restore(target, observed) + state.z = target self.ledger.dense_observations += 1 def _replay_to(self, schedule: FixedSchedule, target: float) -> None: @@ -341,31 +360,29 @@ def _replay_to(self, schedule: FixedSchedule, target: float) -> None: while the predictor-corrector estimate is still computed and recorded, so a schedule too coarse for its tolerance is reported rather than silent. The order is chosen by the same rule as an adaptive run's, from the same - estimates; with no rejection it never has to wait a step to rise, so a replay - of an adaptive run's steps can choose differently where that run rejected, - while a replay of a replay is identical. A hard kink, an edge of the schedule, - restarts the history as it does in an adaptive run. + estimates. A hard kink, an edge of the schedule, restarts the history as it + does in an adaptive run. - ``target``: position to reach, m. """ - backend = self._backend + host, state = self._host, self.state edges = schedule.edges slack = replay_tolerance(schedule, target) - while ( - backend._schedule_index < schedule.n_steps and backend._z < target - slack - ): - backend._poll_stop() - dz = float(schedule.steps[backend._schedule_index]) - end = float(edges[backend._schedule_index + 1]) - norm = self.replay_step(dz, end, slack) - backend._schedule_index += 1 - backend._record(end, dz, norm, accepted=True) - backend._accepted_norms.append(norm) + while state.cursor < schedule.n_steps and state.z < target - slack: + host.poll_stop() + dz = float(schedule.steps[state.cursor]) + end = float(edges[state.cursor + 1]) + with self._attempt_scope() as attempt: + norm = self.replay_step(dz, end, slack) + state.cursor += 1 + host.record(end, dz, norm, accepted=True) + attempt.end(AttemptOutcome.ACCEPTED) + state.norms.append(norm) self._raise_floor() - backend._take_step_stats() - if backend._natural_stop(target): + host.stepped() + if host.natural_stop(target): return - if backend._z < target - slack: + if state.z < target - slack: msg = ( f"the replayed schedule ends at {float(schedule.z_end):.6g} m and " f"cannot reach z = {target:.6g} m" @@ -373,10 +390,11 @@ def _replay_to(self, schedule: FixedSchedule, target: float) -> None: raise BackendError(msg) def replay_step(self, dz: float, end: float, slack: float) -> float: - """Take one prescribed step from the backend's position and accept it. + """Take one prescribed step from the march's position and accept it. - 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. + The unit a replay advances by: the startup of an empty history, the step and, + when `end` is a hard kink, the restart. Called inside an attempt, whose + reservation the caller opened. Parameters ---------- @@ -398,68 +416,103 @@ def replay_step(self, dz: float, end: float, slack: float) -> float: If the norm is not finite: the field has diverged, and a replay cannot reject the step. """ - self._afford() - with _trial(self._backend): - if not self._history: - self._start() - kink = adams_core.replay_kink(self._policy, end, slack) - _, norm = self._attempt(dz, fixed=True, landing=(end, kink)) - if not math.isfinite(norm): - msg = ( - f"{self._backend.name}: a replayed {self._method.name} step of " - f"{dz:.4g} m ending at z = {end:.6g} m has a non-finite error norm " - f"({norm!r}): the field has diverged. A replayed schedule takes " - "its steps as given and cannot reject one, so a step beyond an " - "explicit stability limit -- the in-stage temporal collar's or a " - "coupled flow's advisory step -- grows until it overflows; the " - "translation refuses a declared step past the collar's limit and " - "warns on one past the flow's. Take shorter steps, or let the " - "controller choose them" - ) - raise ConvergenceError(msg) + if not self._history: + self._start() + kink = adams_core.replay_kink(self._policy, end, slack) + _, norm = self._attempt(dz, fixed=True, landing=(end, kink)) + if not math.isfinite(norm): + msg = ( + f"{self._name}: a replayed {self._method.name} step of " + f"{dz:.4g} m ending at z = {end:.6g} m has a non-finite error norm " + f"({norm!r}): the field has diverged. A replayed schedule takes " + "its steps as given and cannot reject one, so a step beyond an " + "explicit stability limit -- the in-stage temporal collar's or a " + "coupled flow's advisory step -- grows until it overflows; the " + "translation refuses a declared step past the collar's limit and " + "warns on one past the flow's. Take shorter steps, or let the " + "controller choose them" + ) + raise ConvergenceError(msg) return norm - def _observe(self, position: float) -> object: - """Return the field at `position` inside the last accepted step. + def _end(self, attempt: "_Attempt", *, accepted: bool) -> None: + """End a recorded attempt with its decision, then raise a floor it fell below. + + As native's march does (``adams_march.cpp``): an accepted attempt ends first, + and a failure there is the run's error, its step committed; a rejected + attempt's floor is the run's error, and a failure of its end rides on it as a + note (SEP 49 section 6.3, issue #651). + """ + if accepted: + attempt.end(AttemptOutcome.ACCEPTED) + self._raise_floor() + return + error, self._floor = self._floor, None + if error is None: + attempt.end(AttemptOutcome.REJECTED) + return + try: + attempt.end(AttemptOutcome.REJECTED) + except Exception as cleanup: + error.add_note(f"releasing the source reservation failed: {cleanup}") + raise error - Interpolated and carried to `position` by the exact linear flow (SEP 13 - section 6.4, SEP 16 section 4.3); never a history point, and no source call. + @contextmanager + def _attempt_scope(self) -> Iterator["_Attempt"]: + """Open an attempt with its host-source reservation; end it on every exit. - - ``position``: the observation, m, inside the last accepted step. + The budget is checked and the reservation made before the attempt's first + evaluation (SEP 49 section 6.2). An attempt the body does not end -- a + failure, a floor, a diverged replay -- ends abandoned, which only releases + what it reserved; that release's own failure is attached to the error as a + note, never raised in its place (SEP 49 section 6.3). """ - return self._engine.observe(position) + attempt = _Attempt(self._engine) + self._afford(attempt) + try: + yield attempt + except BaseException as error: + if attempt.open: + try: + attempt.end(AttemptOutcome.ABANDONED) + except Exception as cleanup: + error.add_note( + f"releasing the source reservation failed: {cleanup}" + ) + raise - def _afford(self) -> None: + def _afford(self, attempt: "_Attempt") -> None: """Refuse a trial the call budget cannot pay for, before any call is made.""" self._raise_floor() budget = self._policy.max_calls cost = (0 if self._history else 1) + 1 spent = self.ledger.total - backend = self._backend + z = self.state.z if budget is not None and spent + cost > budget: - raise self._budget_error(cost) - backend._reserve_source_calls(cost) - - def _budget_error(self, cost: int) -> ResponseBudgetError: - """Return the error of a trial the call budget cannot pay for.""" - backend = self._backend - spent = self.ledger.total - msg = ( - f"the source-call budget of {self._policy.max_calls} is spent ({spent} " - f"charged) at z = {backend._z:.6g} m: the next trial needs {cost}; " - "the run stops at its last accepted step, unfinished" - ) - return ResponseBudgetError( - msg, z=backend._z, field=backend._adams_state().copy(), calls=spent - ) + msg = ( + f"the source-call budget of {budget} is spent ({spent} charged) at " + f"z = {z:.6g} m: the next trial needs {cost}; the run stops at its " + "last accepted step, unfinished" + ) + raise ResponseBudgetError(msg, z=z, field=self._field().copy(), calls=spent) + try: + attempt.begin(cost) + except ResponseBudgetError as error: + raise ResponseBudgetError( + "the TDSE atomic-call budget cannot reserve the next trial " + f"at z = {z:.6g} m ({error.calls} charged); " + "the run stops at its last accepted step, unfinished", + z=z, + field=self._field().copy(), + calls=error.calls, + ) from None def _start(self) -> None: """Evaluate the source at the accepted field to (re)start the history.""" - backend = self._backend - z = backend._z + z = self.state.z self.ledger.startup += 1 - value = self._engine.start(z) - self._history = [Derivative(z, value, "accepted", 0)] + self._engine.start(z) + self._history = [HistoryEntry(z, "accepted", 0)] self._order = 1 if self._policy.variable_order else self._policy.order def _capped(self, proposal: float) -> float: @@ -468,37 +521,16 @@ def _capped(self, proposal: float) -> float: Under a carrier frame no step covers more than :data:`~solprop.stepper.multistep.CARRIER_PHASE_CAP` of carrier phase (SEP 35 section 6.4), measured by one chord of the reference element's operator over - the proposal (:class:`CarrierChord`) - (:func:`~solprop.backends.adams_core.carrier_capped`). Applied before the - landing rule, so a shortened step is not a landing; a fixed schedule's replay - is not capped. + the proposal (:func:`~solprop.backends.adams_core.carrier_capped`). Applied + before the landing rule, so a shortened step is not a landing; a fixed + schedule's replay is not capped. - ``proposal``: the controller's proposal, m. - - Returns: the proposal, or the shorter step the cap allows, m. """ if not self._policy.carrier: return proposal - carrier = cast("CarrierReference", self._engine.carrier) return adams_core.carrier_capped( - self._policy, self._backend._z, proposal, carrier.chord_phase - ) - - def _quiet_capped(self, proposal: float) -> float: - """Return the proposal held to the monitor's interval while the collar rests. - - :func:`~solprop.backends.adams_core.quiet_capped` of the backend's collar and - monitor, the rule of the driver's own ``_quiet_capped``. - - - ``proposal``: the controller's proposal, m. - - Returns: the proposal, or the monitor's interval while the collar is left out, - m. - """ - backend = self._backend - monitor = backend._monitor - return adams_core.quiet_capped( - proposal, - quiet=backend._collar_quiet, - interval=None if monitor is None else monitor.interval, + self._policy, self.state.z, proposal, self._engine.chord_phase ) def _attempt( @@ -510,7 +542,6 @@ def _attempt( ) -> tuple[bool, float]: """Try one step of length `dz` and commit it if accepted. - - ``dz``: the step, m. - ``fixed``: whether the step is a prescribed schedule's, accepted whatever its norm. - ``landing``: where an accepted step ends, m, and whether that is a hard kink, @@ -518,63 +549,23 @@ def _attempt( nothing. - Returns: whether the step was accepted, and its scaled error norm. """ - if self._exponential is not None: - return self._attempt_exponential(dz, fixed=fixed, landing=landing) - return self._attempt_fused(dz, fixed=fixed, landing=landing) - - def _attempt_fused( - self, - dz: float, - *, - fixed: bool = False, - landing: tuple[float, bool] | None = None, - ) -> tuple[bool, float]: - """Try one step of the one-order-higher PEC family on the fused path. - - The arithmetic of :meth:`_attempt`, :meth:`_correct`, :meth:`_commit` and - :meth:`_next_order` for this family, in the engine's passes - (:meth:`HostHistory.fused_trial`): the defects of the neighbouring orders are - scored in the same pass as the step's own, before the decision. - - - ``dz``: the step, m. - - ``landing``: where an accepted step ends and whether it is a hard kink - (:meth:`_attempt`). - - Returns: whether the step was accepted, and its scaled error norm. - """ - z, nodes, slots, order, orders = self._stencil(dz) - self.ledger.predictor += 1 - norms = self._engine.fused_trial(z, dz, nodes, slots, order, orders) - return self._decide(dz, order, orders, norms, fixed=fixed, landing=landing) - - def _stencil( - self, dz: float - ) -> tuple[float, list[float], np.ndarray, int, list[int]]: - """Return a trial's anchor, nodes, rows, order and scored orders. - - :func:`~solprop.backends.adams_core.stencil` of the history. - - - ``dz``: the step, m. - - Returns: the anchor, m; the history's normalised positions and store rows, - newest first; the step's order; and the orders scored, its own first. - """ - z = self._backend._z - history = self._history stencil = adams_core.stencil( self._policy, - z, + self.state.z, dz, - [entry.z for entry in history], - [entry.slot for entry in history], + [entry.z for entry in self._history], + [entry.row for entry in self._history], self._order, last_rejected=self._last_rejected, ) - return z, stencil.nodes, stencil.rows, stencil.order, stencil.orders + self.ledger.predictor += 1 + norms = self._engine.trial(self.state.z, dz, stencil) + return self._decide(dz, stencil, norms, fixed=fixed, landing=landing) def _decide( self, dz: float, - order: int, - orders: list[int], + stencil: adams_core.Stencil, norms: np.ndarray, *, fixed: bool, @@ -584,12 +575,11 @@ def _decide( The new sample takes the oldest row past the method's need. - - ``dz``: the step, m. - ``landing``: where an accepted step ends and whether it is a hard kink (:meth:`_attempt`). - Returns: whether the step was accepted, and its scaled error norm. """ - backend, policy, engine = self._backend, self._policy, self._engine + policy, engine, order = self._policy, self._engine, stencil.order norm = float(norms[0]) if not norm <= 1.0 and not (fixed and math.isfinite(norm)): self.ledger.rejected += 1 @@ -599,25 +589,20 @@ def _decide( # raised at once. self._raise_floor() return False, norm - z = backend._z + z = self.state.z keep = self._history[-policy.order :] if policy.order else [] - used = {entry.slot for entry in keep} - free = next(slot for slot in range(engine.n_slots) if slot not in used) - rows = np.array([entry.slot for entry in keep], dtype=np.int64) + used = {entry.row for entry in keep} + n_slots = cast("Any", engine).n_slots + free = next(slot for slot in range(n_slots) if slot not in used) with committing(): - if self._exponential is None: - engine.fused_accept(rows, free, interpolate=self._interpolate) - else: - engine.exponential_accept(rows, free, interpolate=self._interpolate) - self._history = [ - *keep, - Derivative(z + dz, engine.value(free), "predicted", free), - ] + record = engine.accept(dz, free, stencil, keep) + self._host.absorb(record) + self._history = [*keep, HistoryEntry(z + dz, "predicted", free)] self.ledger.accepted_steps += 1 self._rejections = 0 self.ledger.orders.append(order) next_order, control = self._choose_order( - order, dict(zip(orders, norms.tolist(), strict=True)), dz + order, dict(zip(stencil.orders, norms.tolist(), strict=True)), dz ) self._last_rejected = False self._land(z, dz, landing) @@ -636,14 +621,10 @@ def _propose(self, dz: float, factor: float) -> None: the order have moved, so that a run stopped by the floor leaves the state of the step it accepted at that step's end (SEP 39 section 4.4). The floor is raised once the march has recorded the step (:meth:`_raise_floor`). - - - ``dz``: the accepted step, m. """ policy = self._policy try: - self._backend._proposal = limit_step( - dz, factor, policy.dz_min, policy.dz_max - ) + self.state.proposal = limit_step(dz, factor, policy.dz_min, policy.dz_max) except ConvergenceError as error: self._floor = error @@ -659,55 +640,24 @@ def _raise_floor(self) -> None: raise error def _land(self, z: float, dz: float, landing: tuple[float, bool] | None) -> None: - """Move the backend to an accepted step's end, restarting at a kink. + """Move to an accepted step's end, restarting at a kink. Called inside the commit that installed the step's state, so that the state and its position change together whatever interrupts the march afterwards. - - - ``z``: the step's start, m. - - ``dz``: the step, m. - - ``landing``: where it ends and whether that is a hard kink (:meth:`_attempt`). """ end, kink = (z + dz, False) if landing is None else landing - self._backend._z = end + self.state.z = end if kink: self._history = [] self.ledger.restarts += 1 - def _attempt_exponential( - self, - dz: float, - *, - fixed: bool = False, - landing: tuple[float, bool] | None = None, - ) -> tuple[bool, float]: - """Try one exponential Adams step and commit it if accepted (SEP 16). - - The controller of :meth:`_attempt_fused` with the engine's exponential trial - (:meth:`HostHistory.exponential_trial`): untransported samples, integrated - exactly against the step's flow; an accepted step re-anchors nothing. - - - ``dz``: the step, m. - - ``landing``: where an accepted step ends and whether it is a hard kink - (:meth:`_attempt`). - - Returns: whether the step was accepted, and its scaled error norm. - """ - z, nodes, slots, order, orders = self._stencil(dz) - self.ledger.predictor += 1 - norms = self._engine.exponential_trial(z, dz, nodes, slots, order, orders) - return self._decide(dz, order, orders, norms, fixed=fixed, landing=landing) - def _collar_reentry(self, proposal: float) -> float: """Return the proposal held to the collar's stable step as its term returns. :func:`~solprop.backends.adams_core.collar_reentry`, recording the collar's flag at this attempt. - - - ``proposal``: the controller's proposal, m. - - Returns: the proposal, or the collar's stable step when the term has just - returned, m. """ - quiet = self._backend._collar_quiet + quiet = self._host.collar_quiet capped = adams_core.collar_reentry( self._policy, proposal, @@ -730,12 +680,9 @@ def _choose_order( by rounding -- runs a rounding apart settled in different orders, with calls 40 % apart. The cap weighs the choice only; the step is the chosen order's defect's, as before. - - - ``dz``: the accepted step, m. - - Returns: the order and the norm the next step is controlled with. """ stored, control, norm = adams_core.choose_order( - self._policy, current, scores, dz, quiet=self._backend._collar_quiet + self._policy, current, scores, dz, quiet=self._host.collar_quiet ) self._order = stored return control, norm @@ -746,15 +693,9 @@ def _reject(self, dz: float, norm: float, order: int) -> None: :func:`~solprop.backends.adams_core.rejection`: a rejection leaves the accepted history untouched, and after :data:`~solprop.stepper.multistep.RESTART_AFTER` in a row the method restarts - at order one from the accepted state, paying one startup call. - - A proposal below the floor is left as it was, and the floor is raised once the - march has recorded the rejected attempt (:meth:`_raise_floor`), so that the - completed trial has its row (issue #651), as an accepted step's floor is - (:meth:`_propose`). - - - ``dz``: the rejected step, m. - - ``norm``: its scaled defect, possibly not finite. + at order one from the accepted state, paying one startup call. A proposal + below the floor is left as it was, and the floor is raised once the march has + recorded the rejected attempt (:meth:`_raise_floor`; issue #651). """ policy = self._policy self.ledger.rejected_steps += 1 @@ -767,50 +708,53 @@ def _reject(self, dz: float, norm: float, order: int) -> None: self._history = [] self.ledger.failure_restarts += 1 try: - self._backend._proposal = limit_step( + self.state.proposal = limit_step( dz, outcome.factor, policy.dz_min, policy.dz_max ) except ConvergenceError as error: self._floor = error +class _Attempt: + """An attempt's source reservation, ended exactly once (native ``Attempt``).""" + + def __init__(self, engine: object) -> None: + self._engine = cast("AdamsEngine", engine) + self.open = False + + def begin(self, cost: int) -> None: + """Reserve the attempt's calls; the attempt is open from here.""" + self._engine.begin_attempt(cost) + self.open = True + + def end(self, outcome: AttemptOutcome) -> None: + """End with the decision; closed first, so a failure here is not abandoned.""" + self.open = False + self._engine.end_attempt(outcome) + + _ENGINE_MEMBERS = ( + "start", + "trial", + "accept", + "chord_phase", + "step_carrier", + "begin_attempt", + "end_attempt", + "reading", "n_slots", - "carrier", - "dense", "reset", "hold", "restore", - "start", - "value", "observe", ) -"""What every march path asks of an engine, beside its own trial and acceptance.""" - - -@contextmanager -def _trial(backend: HostDriver) -> Iterator[None]: - """Release a trial's unused source reservation on every exit (SEP 49, 6.3). - - A failure's own error stays the one raised: a release that fails after it is - attached to it as a note, never raised in its place. - """ - try: - yield - except BaseException as error: - try: - backend._release_source_calls() - except Exception as cleanup: - error.add_note(f"releasing the source reservation failed: {cleanup}") - raise - backend._release_source_calls() +"""What the march asks of an engine: the protocol, and the members that move to the +session with SEP 52's step 2.""" -def _check_engine(engine: object, *, exponential: bool) -> None: - """Refuse an injected engine that lacks a member its path calls.""" - family = "exponential" if exponential else "fused" - wanted = (*_ENGINE_MEMBERS, f"{family}_trial", f"{family}_accept") - missing = [name for name in wanted if not hasattr(engine, name)] +def _check_engine(engine: object) -> None: + """Refuse an engine that lacks a member the march calls.""" + missing = [name for name in _ENGINE_MEMBERS if not hasattr(engine, name)] if missing: - msg = f"an Adams engine for the {family} path lacks {', '.join(missing)}" + msg = f"an Adams engine lacks {', '.join(missing)}" raise BackendError(msg) diff --git a/src/solprop/backends/host/driver.py b/src/solprop/backends/host/driver.py index 0c406b8e0..60cfc54ac 100644 --- a/src/solprop/backends/host/driver.py +++ b/src/solprop/backends/host/driver.py @@ -2,41 +2,39 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The reference's step loop, with the kernels left abstract (SEP 47). - -March, replay, landing, controller bookkeeping, history, the noise model and the seam's -``set_initial``/``propagate_to``/``observe``/``close`` do not depend on how a stage is -evaluated: they touch the state and ``HostDriver._trial_step`` and nothing -else. Written once here, they are the step control of every NumPy reference backend. - -**The reference owns this loop** since SEP 47 phase 2: :class:`HostDriver` began as a -copy of the step driver the native backend inherited until phase 5, and shares only -stateless numerical modules -- the controller cores, tableaux, coefficient evaluation, -stage tables and host engines -- with the native backend. Its decisions on identical -inputs are the native marches' (the decision traces of ``tests/backends``). -What a backend supplies is ``_trial_step``, ``_apply_mask`` and ``stats``, plus -``_finish`` when it has boundary treatments of its own; two optional hooks, -``_begin_plane`` and ``_on_accepted_step``, are where a backend scores whatever a plane -or an accepted step leaves behind. The march owns the periodic statistics schedule. -Its default storage hooks call ``stats`` and retain host rows. +"""The reference's scheduler: planes, halts, records and the seam (SEP 47, SEP 52). + +:class:`HostDriver` schedules the reference's run: the save planes and step planes, +the halts and yields of its session, the step history, the periodic statistics rows, +the boundary monitor's and the transverse edge's checks, the noise load and the seam's +``set_initial``/``propagate_to``/``observe``. It computes nothing state-sized: the +state and its operations are a workspace's +(:class:`~solprop.backends.numpy_ref.workspace.NumpyWorkspace`), and each method's +march (:class:`~solprop.backends.host.runge_kutta.RungeKuttaMarch`, +:class:`~solprop.backends.host.adams.HostAdamsMarch`, +:class:`~solprop.backends.host.low_storage.HostLowStorageMarch`) holds its own +position, proposal and history, steps through its engine and asks the driver only +through the narrow :class:`~solprop.backends.host.marches.MarchHost`. A subclass +supplies the workspace, the engines and the marches. SEP 52 moves this scheduling into +the reference's session and deletes the driver. """ import dataclasses import logging import math import time -from abc import ABC, abstractmethod -from collections import deque +from abc import ABC from collections.abc import Callable, Mapping, Sequence -from typing import TYPE_CHECKING, TypeVar, cast +from typing import TYPE_CHECKING, Protocol, TypeVar, cast import numpy as np from jaxtyping import Complex, Float from solprop._helpers import PLAIN, Helpers -from solprop._interrupts import committing, poll +from solprop._interrupts import poll from solprop._ownership import hold -from solprop.backends import rk_core +from solprop.backends.engines import AcceptRecord, RungeKuttaEngine +from solprop.backends.host.marches import MarchState, in_flight_refusal from solprop.backends.node_chunk import NodeChunkPlan, plan_node_chunk from solprop.backends.protocol import ( Backend, @@ -46,21 +44,16 @@ StepSummary, TimingProbe, ) -from solprop.backends.records import ( - RungeKuttaPolicy, - collar_rests, - runge_kutta_policy, -) +from solprop.backends.records import collar_rests from solprop.backends.session import ( ExecutionOptions, PreparedExecution, Start, ) -from solprop.exceptions import BackendError, BoundaryError, ConvergenceError +from solprop.exceptions import BackendError, BoundaryError from solprop.grid import TimeGrid from solprop.log import NOT_ESTIMATED, NullReporter, ProgressReporter, StopFlag from solprop.modes.protocol import Mode -from solprop.modes.quadrature import mode_matrix, on_axis_rule from solprop.monitor import BoundaryEnergies, BoundaryMonitor from solprop.noise import NoiseRealisation from solprop.output.records import MarchSnapshot @@ -69,34 +62,20 @@ from solprop.stepper.controller import ControlRecord from solprop.stepper.low_storage import LowStorageRungeKutta from solprop.stepper.schedule import ( - FixedSchedule, - StepTargets, - landing, reached, replay_tolerance, ) -from solprop.stepper.tableau import extension_coefficients, extension_value -from solprop.translate.linop import delta_phi, unitary_phase -from solprop.translate.masks import noise_spectrum +from solprop.translate.modal import QUADRATURE_ALARM, warn_quadrature from solprop.translate.plasma_source import plasma_source_record from solprop.translate.problem import PropagationProblem, PropagatorMode -from solprop.translate.responses import prefactor_at from solprop.translate.routes import transverse_of from solprop.translate.run_request import RunRequest -from solprop.translate.stage import ( - StageScalars, - anchor, - combine, - scalars, - scalars_at, - terms, -) -from solprop.translate.tdse import TDSEPurpose -from solprop.transverse_monitor import TransverseEdge, _EdgeReading if TYPE_CHECKING: from solprop.backends.host.adams import HostAdamsMarch from solprop.backends.host.low_storage import HostLowStorageMarch + from solprop.backends.numpy_ref.engines import NumpyRungeKutta + from solprop.backends.numpy_ref.workspace import NumpyWorkspace __all__ = [ "INITIAL_STEP_STATS_CAPACITY", @@ -212,7 +191,7 @@ class _TrialProbe: """Single trials of a loaded :class:`HostDriver`, committing nothing (SEP 47 6.6). The :class:`solprop.backends.protocol.TimingProbe` this driver returns. A - Runge-Kutta trial (:meth:`HostDriver._trial_step`) leaves the loaded state, the + Runge-Kutta trial (the driver's Runge-Kutta engine) leaves the loaded state, the position and the history alone. The low-storage march has no separate trial: its step advances the discarded registers in place and leaves no trial field. @@ -227,7 +206,7 @@ def __init__( """Hold the loaded driver; no trial is taken yet.""" self._driver = driver self._z, self._index = start - self._trial: tuple[object, float] | None = None + self._length: float | None = None def trial(self, z: float | None = None, dz: float | None = None) -> None: """Take one trial step and keep its end state for :meth:`field`. @@ -244,18 +223,19 @@ def trial(self, z: float | None = None, dz: float | None = None) -> None: assert schedule is not None # the translation refuses the march without one index = min(self._index, schedule.n_steps - 1) length = float(schedule.steps[index]) if dz is None else float(dz) - march.engine.step(start, length) + cast("RungeKuttaEngine", march.engine).trial(start, length) return length = float(driver._stepper.dz_init) if dz is None else float(dz) - _, state = driver._trial_step(start, length) - self._trial = (state, length) + driver._runge_kutta_engine.trial(start, length) + self._length = length def field(self) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: """Return the last trial's end state on the host, as a kept step would be. The trial's state after the accepted-step boundary treatments (the band mask, - and the split-step absorber where it runs). A host trial is a new array beside - the loaded state, so finishing it leaves the loaded state alone. + and the split-step absorber where it runs). A trial is held beside the loaded + state, so finishing it leaves the loaded state alone, and no monitor is bound, + so the finish takes no split sums. - Returns: an owning copy, internal units and the FFT convention, shape ``(n_modes, n_pol, n_omega)``. @@ -267,29 +247,84 @@ def field(self) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: "field to read back" ) raise BackendError(msg) - if self._trial is None: + if self._length is None: raise BackendError("take a trial before reading its field") - state, length = self._trial - field = np.array(driver._observed_field(driver._finish(state, length))) - self._trial = None - return field + engine = driver._runge_kutta_engine + finished, _ = driver._workspace.finish(engine.trial_state, self._length) + self._length = None + return np.array(finished) -class HostDriver[_StateT](ABC): # noqa: UP049 - the protected state type is private - """The interaction-picture step loop, with the stage evaluation left to a subclass. +class _SessionHooks: + """The driver as its marches' :class:`~solprop.backends.host.marches.MarchHost`. + + The narrow calls a march makes of the session that schedules it, forwarded to the + driver's own bookkeeping, so that no march reads or writes the driver's fields. + """ + + def __init__(self, driver: "HostDriver[object]") -> None: + self._driver = driver + + @property + def collar_quiet(self) -> bool: + """Whether the stages leave a quiet in-stage temporal collar out.""" + return self._driver._collar_quiet + + def poll_stop(self) -> None: + """Raise when the run's stop flag is set.""" + self._driver._poll_stop() + + def cap(self, proposal: float, z: float) -> float: + """Hold a proposal to the quiet collar's, the edge's and the split's limits.""" + driver = self._driver + return driver._split_capped( + driver._transverse_capped(driver._quiet_capped(proposal), z) + ) + + def record(self, end: float, dz: float, norm: float, accepted: bool) -> None: + """Record one attempt.""" + self._driver._record(end, dz, norm, accepted) + + def absorb(self, record: AcceptRecord) -> None: + """Accumulate an accepted step's split collar's sums.""" + self._driver._absorb(record) + + def stepped(self) -> None: + """Account the step just committed.""" + self._driver._take_step_stats() + + def natural_stop(self, target: float) -> bool: + """Count an accepted step; return whether to stop at its end.""" + return self._driver._natural_stop(target) + + def natural_stop_due(self, target: float) -> bool: + """Return whether the march returns where it stands.""" + return self._driver._natural_stop_due(target) + + +class _March(Protocol): + """What the driver asks of whichever march its run steps with.""" + + state: MarchState + + @property + def holding(self) -> bool: ... - A subclass supplies ``_trial_step`` and ``_apply_mask`` and gets the whole of - :class:`solprop.backends.protocol.Backend`'s marching behaviour: adaptive stepping - with the controller of ``docs/dev/stepper.md`` section 3, replay of a contract's - fixed schedule, landing exactly on save planes and hard kinks, the step history, and - both noise models, ``input`` and ``modified``. + def load(self, z: float, proposal: float, cursor: int) -> None: ... - **The controller's state is its own proposal**, never the clipped or stretched step - that was executed, and what the history and a rejection see is the norm the proposal - would have scored while what decides acceptance is the error the executed step - committed. Both are section 3's, and both matter: the first costs a run hundreds of - steps if it is got wrong, the second throws away short landing steps that were - accurate. + def advance(self, target: float) -> None: ... + + +class HostDriver[_StateT](ABC): # noqa: UP049 - the protected state type is private + """The reference's scheduler, with the workspace and the marches left to a subclass. + + A subclass supplies the workspace (``_workspace``), the Runge-Kutta engine the + timing probe uses (``_runge_kutta_engine``) and the march its run steps with + (``_march``, with ``_adams`` or ``_low_storage`` set when it is that march), each + march reporting to the driver's hooks (``_hooks``). The driver gives them the whole + of :class:`solprop.backends.protocol.Backend`'s marching behaviour: the save planes + and step planes, the halts and yields, the step history, the statistics rows, the + boundary monitor and the transverse edge, and both noise models' loads. Parameters ---------- @@ -356,45 +391,17 @@ def __init__( self._chunk_plan: NodeChunkPlan = plan_node_chunk(problem, self._options) self._adams: HostAdamsMarch | None = None # The low-storage march (SEP 24), set at construction by a backend that - # executes it, and the step it has left in flight: from the step's start to - # its commit the state, accepted in place, is neither end of the step. + # executes it; its engine owns the flag of a step left in flight. self._low_storage: HostLowStorageMarch | None = None - self._in_flight: tuple[float, float] | None = None - # The fixed arrays of the seam's device form, held for the whole run; the - # weights that multiply them are a bundle of host floats per stage. - self._terms = terms(problem) - # Hoisted per step by `_hoist`; the entrance's until the first step asks. - self._anchor = anchor(problem, 0.0, helpers=self.helpers) - # A step's bundles taken together by `_stage_bundles`, by anchor and - # position; `_hoist` drops them. - self._prepared: dict[tuple[float, float], StageScalars] = {} self._grid = grid self._modes = modes - self._on_axis: Float[np.ndarray, "n_rows n_modes"] | None = None - # The on-axis plasma scans actually run (SEP 19), so that a test can see that - # a rule with a node on the axis supplies that row instead of a fresh scan. - self.axis_scans = 0 - self._axis_node: int | None = None - self._axis_node_known = False self._profiles = profiles self._logger = logging.getLogger(type(self).__module__) - self._state: _StateT | None = None - self._noise: Complex[np.ndarray, "n_modes n_pol n_omega"] | None = None - self._z = 0.0 - self._proposal = self._stepper.dz_init - self._clean_columns: Float[np.ndarray, " n_columns"] | None = None - self._schedule_index = 0 self._closed = False - # The controller reads one norm a fixed lag back, and the one before it - # (`PIController.propose`): a run keeps only those, not one per step. - self._accepted_norms: deque[float] = deque( - maxlen=self._stepper.controller.lag + 2 - ) - # Dense output (SEP 14 phase 3): the last accepted step that crossed a plane, - # as its anchor, length and extension coefficients, and the march's own - # position and host state while an interpolated plane is observed. - self._dense_step: tuple[float, float, list[np.ndarray]] | None = None - self._dense_ahead: tuple[float, np.ndarray] | None = None + # The marches' narrow view of the driver (SEP 52 section 5.2). + self._hooks = _SessionHooks(cast("HostDriver[object]", self)) + # Whether the plane's quadrature alarm was reported (warned once per plane). + self._alarm_reported = False # Natural-step saving (SEP 14 phase 3): accepted steps since the load, and # whether a step that crossed a densely observed plane ends on a step to save. self._natural_count = 0 @@ -419,214 +426,38 @@ def __init__( self._row_period = spec.period self._accepted_steps = 0 self._rows = _StepStatsBuffer() - # Field-free planes at which the spatial collar diagnostic was not evaluated - # since the load (SEP 22, Q2), recorded in `metadata` and logged once. - # Physical RK source dispatches, including rejected trials and excluding - # recycled stages. SEP 30 records work rather than estimating it from steps. - self._rk_source_evaluations = 0 # --- what a subclass supplies ----------------------------------------------- - @abstractmethod - def _trial_step(self, z: float, dz: float) -> tuple[float, _StateT]: - """Take one interaction-picture Runge-Kutta step and score it. - - - ``z``: position at the start of the step, m. - - ``dz``: length of the trial step, m, positive. - - Returns: the scaled error norm and the state at the end of the step. The state - is *raw*: the boundary treatments of :meth:`_finish` are applied by the march, - and only to a step it keeps. - """ - - @abstractmethod - def _apply_mask( - self, state: Complex[np.ndarray, "n_modes n_pol n_omega"] - ) -> _StateT: - """Apply the hard band mask to a state that has not been through a step. - - :meth:`HostDriver.set_initial` masks the state it is given, as the scaffold - does, and that is the only place the driver needs the mask on its own. - - - ``state``: the state in the canonical layout. - """ - - def _finish( - self, - state: _StateT, - dz: float, - ) -> _StateT: - """Apply the once-per-accepted-step boundary treatments to a kept step. - - The hard band mask, and the temporal absorber when the ``"split_step"`` absorber - scheme is active, followed by the mask again: its product in time spreads - content into every bin, so the band is imposed last. Called by the march and - by the replay on the state they are about to adopt, never on one they are - about to throw away: a rejected step would otherwise pay the absorber's - transform pair for a result nobody reads. While a monitor of that scheme is - attached, a backend's split also adds what it takes to the monitor's next - reading (:attr:`_split_removed`, :meth:`_boundary_energies`), at every - accepted step, and keeps the energies of the power it found - (:attr:`_split_found`), which the occupancies are judged on. - - - ``state``: the state at the end of an accepted step, in the canonical layout. - - ``dz``: the length of that step, m, which the absorber's rate needs. - """ - del dz - return self._apply_mask( - cast(Complex[np.ndarray, "n_modes n_pol n_omega"], state) - ) - - 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. - """ - raise NotImplementedError - - def _release_source_calls(self) -> None: - """Release the unused part of an external source-call reservation.""" - raise NotImplementedError - - def _adams_source( - self, - lab: Complex[np.ndarray, "n_modes n_pol n_omega"], - anchor: float, - position: float, - *, - purpose: TDSEPurpose = "predictor", - ) -> tuple[ - Complex[np.ndarray, "n_modes n_pol n_omega"], - Complex[np.ndarray, "n_modes n_pol n_omega"], - ]: - """Evaluate the source once for the low-call Adams march (SEP 13, SEP 14). - - The one expensive evaluation of an Adams step: the nonlinear source at a - lab-frame field, with the run's noise and in-stage absorber, returned in the - interaction frame of the step's anchor. A backend that executes - :class:`~solprop.stepper.multistep.Multistep` overrides this and - :meth:`_adams_propagator`; the default refuses, naming the backend. - - - ``lab``: the lab-frame field at `position`, in the canonical layout. - - ``anchor``, ``position``: the step's anchor and the evaluation position, m. - - ``purpose``: Atomic-call accounting label; ignored when no atomic service is - bound. - - Returns: ``U(anchor, position) N(lab, position)`` and ``U(position, anchor)``, - with ``U(z_2, z_1) = exp(Phi(z_2) - Phi(z_1))``. - """ - del lab, anchor, position, purpose - msg = f"{self.name} does not execute the low-call Adams integrator" - raise BackendError(msg) - - def _adams_lab_source( - self, - lab: Complex[np.ndarray, "n_modes n_pol n_omega"], - position: float, - *, - purpose: TDSEPurpose = "predictor", - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Evaluate the source once, untransported, for exponential Adams (SEP 16). - - The complete source assembly ``F`` -- the nonlinear response, the run's noise - draw at `position`'s absolute phase and the in-stage absorbers -- at a - lab-frame field, returned in the lab frame with no propagator applied: the - sample the exponential formulation integrates against the linear flow. A - backend that executes that formulation overrides this; the default refuses, - naming the backend. - - - ``lab``: the lab-frame field at `position`, in the canonical layout. - - ``position``: the evaluation position, m. - - ``purpose``: Atomic-call accounting label; ignored when no atomic service is - bound. - """ - del lab, position, purpose - msg = ( - f"{self.name} does not execute the exponential Adams formulation; use " - "Multistep(formulation='interaction') or numpy_ref" - ) - raise BackendError(msg) - - def _adams_block(self, z: float, dz: float) -> object: - """Return the frozen coupled block of a step from `z`, or ``None`` (SEP 16). - - The exponential formulation steps a coupled flow's constant-Schur and - frozen-residual sections against the reference ``(Delta Phi / h) I + G_s`` - (SEP 16 section 4.5), with ``G_s`` the frozen block of the section the step is - anchored in. ``None``, the default, is a problem with no coupled flow; a - backend that holds one returns its - :class:`~solprop.backends.numpy_ref.multistep.CoupledBlock`. - - - ``z``: where the step starts, m. - - ``dz``: the step, m. - - Returns: the step's ``CoupledBlock``, or ``None``. - """ - del z, dz - return None - - def _adams_propagator( - self, anchor: float, position: float - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Return the linear propagator of an Adams step, ``U(position, anchor)``. - - - ``anchor``, ``position``: the step's anchor and its end, m. - - Returns: ``exp(Phi(position) - Phi(anchor))`` in the canonical layout, an - array the caller owns. - """ - bundle = self._stage_scalars(anchor, position) - return np.exp(self._delta_phi(bundle)) - - def _adams_state(self) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Return the accepted state as the Adams march reads it, a host array. + _workspace: "NumpyWorkspace" + """The state and every state-sized operation on it.""" - The default is the protected state itself; a backend whose state lives - elsewhere returns a host copy it keeps current through :meth:`_adams_adopt`. + _runge_kutta_engine: "NumpyRungeKutta" + """The Runge-Kutta engine: the Runge-Kutta march's and the timing probe's.""" - - Returns: the accepted state in the canonical layout. - """ - return cast(Complex[np.ndarray, "n_modes n_pol n_omega"], self._require_state()) + _march: _March + """The march the run steps with.""" - def _adams_adopt( - self, advanced: Complex[np.ndarray, "n_modes n_pol n_omega"], dz: float - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Adopt an accepted Adams step: its boundary treatments, then the state. - - - ``dz``: the step, m, which the split-step absorber needs. - """ - finished = self._finish(cast(_StateT, advanced), dz) - self._state = finished - return cast(Complex[np.ndarray, "n_modes n_pol n_omega"], finished) - - def _adams_restore( - self, z: float, state: Complex[np.ndarray, "n_modes n_pol n_omega"] - ) -> None: - """Restore an accepted Adams state after interpolation or a failed correction. - - - ``z``: the position of the accepted state, m. - """ - self._z = z - self._state = cast(_StateT, state) - - def _observed_field( - self, state: _StateT - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Return an owning host view of a backend's protected state. + @property + def _z(self) -> float: + """Return the march's position, m.""" + return self._march.state.z - Array-backed CPU implementations use the identity. A device backend overrides - this hook to synchronize and copy without teaching the shared march its state - representation. + @property + def _proposal(self) -> float: + """Return the march's proposal, m.""" + return self._march.state.proposal - - Returns: an owning host ``complex128`` field in canonical layout. - """ - return cast(Complex[np.ndarray, "n_modes n_pol n_omega"], state) + @property + def _schedule_index(self) -> int: + """Return the march's replay cursor.""" + return self._march.state.cursor - @abstractmethod def stats(self, spec: StatsSpec) -> dict[str, np.ndarray]: - """Compute the requested statistics in one fused pass. + """Compute the requested statistics of the state in one fused pass. - Declared here, not only on - :class:`solprop.backends.protocol.Backend`, because the shared step loop calls - it through the default row-storage hook. A device backend shares its statistic - evaluator between this method and its device row-storage hook. + Called by the session at a plane and by the step loop's row storage, at the + march's position. Parameters ---------- @@ -638,13 +469,21 @@ def stats(self, spec: StatsSpec) -> dict[str, np.ndarray]: dict Small host arrays keyed by statistic name. """ + self._require_state() + return self._workspace.stats(spec, self._z) - def _on_accepted_step(self) -> None: # noqa: B027 - optional by design + def _on_accepted_step(self) -> None: """Score whatever an accepted step leaves behind, before the next is proposed. - The quadrature alarm is scored here, from buffers the last stage left behind. - The default does nothing. + The quadrature alarm is scored here, from buffers the last stage left behind, + and a value above :data:`~solprop.translate.modal.QUADRATURE_ALARM` is + reported once per plane. It is a statistic and a warning, never a controller + input. """ + value, z = self._workspace.score_quadrature() + if value > QUADRATURE_ALARM and not self._alarm_reported: + self._alarm_reported = True + warn_quadrature(value, z) def _reset_step_stats(self, *, release: bool) -> None: """Discard periodic rows at a load or at the start of a plane. @@ -687,7 +526,9 @@ def _propagator_mode(self) -> PropagatorMode: resolved to :attr:`propagator_default`. """ asked = self._stepper.propagator_mode - if asked == "auto" and self._low_storage is not None: + if asked == "auto" and isinstance( + self._stepper.integrator, LowStorageRungeKutta + ): # One volume of exp(h D / 2) reused while the step holds is the cheaper # flow on a CPU; a varying operator changes it every step (SEP 24 # section 4.3). @@ -792,7 +633,7 @@ def metadata(self) -> dict[str, object]: if self._low_storage is not None: record["source_evaluations"] = self._low_storage.source_evaluations elif self._adams is None: - record["source_evaluations"] = self._rk_source_evaluations + record["source_evaluations"] = self._runge_kutta_engine.evaluations if self._monitor is not None: record["boundary_monitor"] = self._monitor.summary() return record @@ -872,7 +713,7 @@ def restore_march(self, snapshot: MarchSnapshot) -> str | None: if self._adams is None: march = "low-storage" if self._low_storage is not None else "Runge-Kutta" return f"the run steps with the {march} march, which keeps no history" - return self._adams.load(snapshot) + return self._adams.load_snapshot(snapshot) def restore_call_ledgers( self, logical: Mapping[str, object], atomic: Mapping[str, object] | None = None @@ -902,113 +743,10 @@ def restore_call_ledgers( f"{self.name} does not restore atomic response call ledgers" ) if logical and self._adams is not None: - # The march imports its driver, so the ledger type is loaded only when - # a constructed backend restores a saved run. - from solprop.backends.ledger import CallLedger # noqa: PLC0415 - - self._adams.ledger = CallLedger.from_record(logical) + self._adams.restore_ledger(logical) # --- the per-stage bundle ------------------------------------------------------ - def _hoist(self, z0: float) -> None: - """Evaluate once per step what every stage of it subtracts. - - ``Phi`` is cumulative, so each stage's increment is against the same anchor. - On the RDW gradient the Clenshaw pass over the scalar tables is the largest - part of what the host does per step, and this is a sixth of it. - - - ``z0``: the step's anchor, m. - """ - self._anchor = anchor(self._problem, z0, helpers=self.helpers) - self._prepared.clear() - - def _stage_bundles( - self, z0: float, positions: Sequence[float] - ) -> tuple[StageScalars, ...]: - """Return the host scalars of several stages of one step, taken together. - - A trial knows all its stage positions before its first stage, and reading each - scalar table once over all of them (:func:`solprop.translate.stage.scalars_at`) - costs a Python call and a Clenshaw dispatch per table rather than per table and - position. The bundles equal :meth:`_stage_scalars`'s bit for bit, and are kept - until the next :meth:`_hoist`: a later :meth:`_stage_scalars` at the same anchor - and position returns the kept bundle, so a step loop written one stage at a - time takes them without change. Bundles of several anchors are kept side by - side (kernel schema 29): the low-storage march's hooks read each of its three - positions as its own anchor. A caller passes only positions the trial will - evaluate. - - - ``z0``: the step's anchor, m. - - ``positions``: the stages' positions, m. - """ - prepared = self._prepared - missing = [z1 for z1 in dict.fromkeys(positions) if (z0, z1) not in prepared] - if missing: - held = self._anchor if self._anchor.z == z0 else None - for bundle in scalars_at( - self._problem, z0, missing, at=held, helpers=self.helpers - ): - prepared[z0, bundle.z1] = bundle - return tuple(prepared[z0, z1] for z1 in positions) - - def _stage_scalars(self, z0: float, z1: float) -> StageScalars: - """Return the host scalars of one stage, from the anchor to the node. - - The anchor's own weights come from :meth:`_hoist` when the caller has already - taken them for this step, and are evaluated here otherwise. A bundle - :meth:`_stage_bundles` took for this anchor and position is returned as kept. - - - ``z0``: the step's anchor, m. - - ``z1``: the stage's position, m. - """ - kept = self._prepared.get((z0, z1)) - if kept is not None: - return kept - held = self._anchor if self._anchor.z == z0 else None - return scalars(self._problem, z0, z1, at=held, helpers=self.helpers) - - def _delta_phi( - self, bundle: StageScalars - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Return the stage's propagator exponent from the bundle. - - One linear combination of the terms this backend holds over the bundle's - floats. A problem that took the z table has no such form and falls back to - ``delta_phi``; a compiled backend that holds the table itself overrides this - with its own evaluation. - """ - if bundle.phi_delta is None or self._terms.phi is None: - return delta_phi( - self._problem.linear, bundle.z0, bundle.z1, helpers=self.helpers - ) - return combine(bundle.phi_delta, self._terms.phi) - - def _prefactor( - self, bundle: StageScalars - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Return the response prefactor at the stage's position, from the bundle. - - - Returns: the prefactor times the crop scale, in m/(V s) per unit polarisation. - """ - if bundle.prefactor is None or self._terms.prefactor is None: - return prefactor_at( - self._problem.responses, bundle.z1, helpers=self.helpers - ) - return combine(bundle.prefactor, self._terms.prefactor) - - def _unitary_phase( - self, bundle: StageScalars - ) -> Float[np.ndarray, "n_modes n_pol n_omega"]: - """Return ``Im Phi`` at the stage's position, from the same terms. - - An expansion of ``Phi`` is cumulative and vanishes at the start of the range, - so its value at a position is the bundle's ``phi_at`` against the same arrays - and the noise costs no second representation. - """ - if bundle.phi_at is None or self._terms.phi is None: - return unitary_phase(self._problem.linear, bundle.z1) - return np.imag(combine(bundle.phi_at, self._terms.phi)) - # --- the seam ---------------------------------------------------------------- def set_initial( @@ -1083,29 +821,14 @@ def set_initial( ) raise BackendError(msg) position = self._checked_position(float(z)) - drawn = self._noise_field(noise) - model = self._problem.initial.noise_model - self._clean_columns = None - if ( - model == "input" - and drawn is not None - and not resume - and position == self._problem.initial.z - ): - if transverse_of(self._problem.route) is not None: - self._clean_columns = _clean_launch_columns( - values, drawn, self._problem.grids.active_mask - ) - values = values + drawn - self._state = self._apply_mask(values) - self._noise = drawn if model == "modified" else None - # The input draw rides in the state, a resumed one's too; the boundary monitor - # reads it as the vacuum floor beneath the light it judges (SEP 21, Q24). - self._input_floor = drawn if model == "input" else None - self._z = position - self._proposal = self._stepper.dz_init - self._schedule_index = self._schedule_index_at(position) - self._accepted_norms.clear() + cursor = self._schedule_index_at(position) + self._workspace.load(values, noise, z=position, resume=resume) + # The march starts afresh: its position, proposal, cursor and norms, and the + # rest of what it reads, as a fresh backend holds it (SEP 22 4.7) -- a dense + # observation's look-ahead, an Adams march's ledger and last-rejection flag, + # a low-storage march's count and a step it left in flight. + self._march.load(position, self._stepper.dz_init, cursor) + self._alarm_reported = False self._history = [] self._natural_count = 0 self._natural_due = False @@ -1121,17 +844,6 @@ def set_initial( # multiple of the period. Said in `docs/guide/results/statistics.md`. self._accepted_steps = 0 self._reset_step_stats(release=True) - # The rest of what a march reads, as a fresh backend holds it (SEP 22 4.7). - self._dense_step = None - self._dense_ahead = None - if self._adams is not None: - self._adams.begin_run() - self._in_flight = None - self._rk_source_evaluations = 0 - if self._low_storage is not None: - self._low_storage.reset() - # Its count is the loaded run's, as the Adams ledger is (SEP 22 4.7). - self._low_storage.source_evaluations = 0 # A boundary monitor watches one run: the next attaches its own or none, and # a collar the last one rested goes back into the stages (SEP 21). self._monitor = None @@ -1226,23 +938,10 @@ def propagate_to(self, z: float) -> StepSummary: self._reset_step_stats(release=False) self._begin_plane() self._halted = False - schedule = self._stepper.schedule - if self._low_storage is not None: - # The low-storage march replays only (SEP 24); the translation refused - # it without a schedule. - assert schedule is not None - self._low_storage.replay_to(schedule, target) - # An Adams march replays a schedule itself, with its own history and ledger. - elif schedule is not None and self._adams is None: - self._replay_to(schedule, target) - else: - self._march_to(target) - if ( - self._natural_due - and reached(self._z, target) - and self._dense_ahead is None - and (self._adams is None or self._adams._ahead is None) - ): + # Each march replays a schedule or steps adaptively itself; the low-storage + # march replays only (SEP 24). + self._march.advance(target) + if self._natural_due and reached(self._z, target) and not self._march.holding: # The step owed as a step plane ends on the target itself, whose plane # observes it: it is not observed a second time there (`_natural_stop`). self._natural_due = False @@ -1319,7 +1018,7 @@ def observe(self, *, field: bool = True) -> Observation: """ state = self._require_state() history = _history_record(self._history) - whole = self._observed_field(state) if field else None + whole = cast("np.ndarray", state) if field else None if whole is not None: # The state itself, frozen as an observed array always was so that the # next step replaces it rather than accepting in place, and held, so the @@ -1330,7 +1029,7 @@ def observe(self, *, field: bool = True) -> Observation: plane = Observation( z=self._z, field=whole, - noise_phase=self._noise_phase() if field else None, + noise_phase=self._workspace.noise_phase(self._z) if field else None, step_history=history, n_steps=history.n_steps, n_rejected=history.n_rejected, @@ -1347,7 +1046,11 @@ def in_flight(self) -> tuple[float, float] | None: # numpydoc ignore=RT01 The step's start and length, m, while the state is neither of its ends (``solprop.backends.low_storage``). """ - return self._in_flight + return self._abandoned() + + def _abandoned(self) -> tuple[float, float] | None: + """Return the step a failure left in flight, or ``None``: the march's.""" + return None if self._low_storage is None else self._low_storage.in_flight @property def position(self) -> float: # numpydoc ignore=RT01 @@ -1371,12 +1074,10 @@ def halted(self) -> bool: # numpydoc ignore=RT01 def holding_plane(self) -> bool: # numpydoc ignore=RT01 """Whether a dense observation holds the state between endpoints. - True while this driver's own (a Runge-Kutta march's) or its Adams march's - observation holds an interpolated plane, the march ahead of it. + True while the march's dense observation holds an interpolated plane, the + march ahead of it. """ - return self._dense_ahead is not None or ( - self._adams is not None and self._adams._ahead is not None - ) + return self._march.holding def drain_attempts(self) -> Observation: """Drain the attempts recorded since the last observation, with no field. @@ -1434,222 +1135,13 @@ def timing_probe(self, start: Start) -> TimingProbe: # --- the step loop ------------------------------------------------------------- - def _begin_plane(self) -> None: # noqa: B027 - optional by design + def _begin_plane(self) -> None: """Reset whatever describes only the steps of the plane about to be taken. - The default does nothing; a backend that warns once per plane clears its latch - here. + The quadrature alarm and its latch, so that each plane reports its own. """ - - def _march_to(self, target: float) -> None: - """Step adaptively to a position, landing on it exactly. - - - ``target``: position to reach, m. - """ - policy = self._controller_policy() - dense = policy.interpolate - if dense and self._dense_ahead is not None: - # The march is ahead of the last interpolated plane; resume it there. - self._adams_restore(*self._dense_ahead) - self._dense_ahead = None - if self._natural_stop_due(target): - return - # The policy's landings (SEP 45 section 4.2): only the operator table's two - # ends bound a step without the interval cap (SEP 14 section 4.1), and dense - # output steps across the save planes, still landing on the end of the run and - # the hard kinks (SEP 14 section 4.3). - targets = StepTargets( - save_planes=np.asarray(policy.save_planes, dtype=np.float64), - hard_kinks=np.asarray(policy.hard_kinks, dtype=np.float64), - breakpoints=np.asarray(policy.breakpoints, dtype=np.float64), - dz_max=policy.dz_max, - z_end=policy.z_end if dense else target, - stretch=policy.stretch, - ) - while not reached(self._z, target): - self._poll_stop() - # The controller's state is its own proposal, never the clipped or - # stretched step that was executed: otherwise every save plane restarts it - # from a sliver and it regrows at the growth cap, which over two hundred - # planes costs more steps than the run needs between them (stepper.md 3). - stop = landing( - self._z, - self._split_capped( - self._transverse_capped(self._quiet_capped(self._proposal)) - ), - targets, - ) - norm, advanced = self._trial_step(self._z, stop.dz) - # What the controller learns from, and what a rejection is scaled by, is the - # norm the *proposal* would have scored; what decides acceptance, and what - # the history records, is the error the executed step actually committed, - # so a short landing step that was accurate is neither thrown away nor - # written up as a failure. - equivalent, accepted = rk_core.decide(policy, norm, stop.dz, self._proposal) - # A landing snaps to its target rather than accumulating z + dz, so that a - # save plane is hit exactly however many steps have gone before. - end = stop.z_target if stop.z_target is not None else self._z + stop.dz - self._record(end, stop.dz, norm, accepted) - if accepted: - if dense and not reached(target, end): - # The step crosses the plane: hold its extension for the - # observation, and for any later plane it also crosses. - self._dense_step = self._dense_record(self._z, stop.dz) - finished = self._finish(advanced, stop.dz) - with committing(): - self._state = finished - self._z = end - self._accepted_norms.append(equivalent) - if policy.auto_init and len(self._accepted_norms) == 1: - self._start_up(equivalent) - # The next proposal grows or shrinks once per accepted step, from the - # history the step completed. A rejected step is retried at the step - # rejection_factor left: applying this factor again there undid the - # shrink, and with a growth cap above about 1.27 a step whose norm sat - # just above one was rejected unchanged forever. - self._proposal = rk_core.propose( - policy, self._proposal, self._accepted_norms - ) - self._take_step_stats() - if self._natural_stop(target): - return - else: - self._proposal = rk_core.reject(policy, self._proposal, equivalent) - - if dense and not reached(target, self._z): - self._observe_inside(target) - - def _dense_record( - self, z: float, dz: float - ) -> tuple[float, float, list[np.ndarray]]: - """Contract an accepted step into its continuous extension's coefficients. - - Called before the step's state is adopted. With ``v0`` the state at the step's - anchor, ``k_i`` its stage derivatives in the anchor's frame and ``v1 = v0 + h - sum_i b_i k_i``, the coefficients are DOPRI5's (Hairer, Noersett and Wanner, - II.6): ``v0``, ``v1 - v0``, ``h k1 - (v1 - v0)``, ``(v1 - v0) - h k7 - - (h k1 - (v1 - v0))`` and ``h sum_i d_i k_i``. - - - ``z``: the step's anchor, m. - - ``dz``: the step, m. - - Returns: the anchor, the step and the five coefficients, host arrays. - """ - start = self._observed_field(cast(_StateT, self._state)).reshape( - self._problem.shape - ) - coefficients = extension_coefficients( - self._stepper.tableau, start, self._dense_stages(), dz - ) - return z, dz, coefficients - - def _observe_inside(self, position: float) -> None: - """Make the state the interpolated field at `position` and hold the march's. - - - ``position``: the plane, m, inside the last accepted step. - """ - assert self._dense_step is not None - z, dz, coefficients = self._dense_step - start = coefficients[0] - value = extension_value(coefficients, (position - z) / dz) - # A bin the linear flow attenuates or amplifies by more than an e-fold over the - # step -- the spectral collar's, outside the controlled band -- has an - # interaction-picture derivative growing exponentially across it, which no - # polynomial in theta follows: interpolated there it returns orders of - # magnitude more than the field. Its source is negligible beside its own loss, - # so the anchor's linear flow is its honest value. - stiff = np.abs(np.real(self._delta_phi(self._stage_scalars(z, z + dz)))) > 1.0 - value = np.where(stiff, start, value) - self._dense_ahead = ( - self._z, - self._observed_field(cast(_StateT, self._state)).reshape( - self._problem.shape - ), - ) - self._state = self._apply_mask(self._adams_propagator(z, position) * value) - self._z = position - - def _dense_stages(self) -> list[np.ndarray]: - """Return the last accepted step's stage derivatives, host arrays. - - In the step's anchor frame and the canonical layout, one per tableau stage. A - backend that observes densely overrides this; the default refuses. - """ - msg = f"{self.name} does not observe densely" - raise BackendError(msg) - - def _controller_policy(self) -> RungeKuttaPolicy: - """Return the Runge-Kutta march's controller and landing policy (SEP 45).""" - return runge_kutta_policy(self._problem, self._stepper) - - def _start_up(self, norm: float) -> None: - """Take the step after the first from the first step's own estimate. - - The first proposal is a guess; its scaled norm says how far it is from the - tolerance. The next proposal is the deadbeat step that norm implies, at most - :data:`~solprop.stepper.controller.START_GROWTH` times the first, and the - history is told the norm the first step would have scored at that length, so - the lagged controller does not apply the guess's margin a second time (SEP 14 - section 4.2). A resumed run starts afresh and takes the rule again. - - A norm small enough to meet the cap says only that the guess was far inside - the tolerance; it is often round-off, which differs between backends. Rescaled - into the history it would steer every later step by that round-off, so the - history records zero instead -- no estimate -- and the backends take the same - steps. - """ - self._proposal, self._accepted_norms[-1] = rk_core.start_up( - self._controller_policy(), self._proposal, norm - ) - - def _replay_to(self, schedule: FixedSchedule, target: float) -> None: - """Replay the contract's fixed schedule to a position. - - A replay takes its steps as given and never rejects, but the embedded estimate - costs nothing extra and is computed and recorded every step, so that a schedule - too coarse for its tolerance is reported rather than silent - (``docs/dev/stepper.md`` section 8). The position is read off the schedule's - edges rather than accumulated, so every save plane is hit exactly -- which - :meth:`~solprop.translate.problem.PropagationProblem.validate` has already - checked the schedule can do. - - - ``target``: position to reach, m. - """ - edges = schedule.edges - slack = replay_tolerance(schedule, target) - while self._schedule_index < schedule.n_steps and self._z < target - slack: - self._poll_stop() - dz = float(schedule.steps[self._schedule_index]) - norm, advanced = self._trial_step(self._z, dz) - if not math.isfinite(norm): - msg = ( - f"{self.name}: replayed step {self._schedule_index + 1} of " - f"{schedule.n_steps}, {dz:.4g} m from z = {self._z:.6g} m, has a " - f"non-finite error norm ({norm!r}): the field has diverged. A " - "replayed schedule takes its steps as given and cannot reject " - "one, so a step beyond an explicit stability limit -- the " - "in-stage temporal collar's or a coupled flow's advisory step -- " - "grows until it overflows; the translation refuses a declared step " - "past the collar's limit and warns on one past the flow's. Take " - "shorter steps, or let the controller choose them" - ) - raise ConvergenceError(msg) - end = float(edges[self._schedule_index + 1]) - finished = self._finish(advanced, dz) - with committing(): - self._state = finished - self._schedule_index += 1 - self._z = end - self._record(self._z, dz, norm, accepted=True) - self._accepted_norms.append(norm) - 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) + self._workspace.reset_quadrature() + self._alarm_reported = False def _natural_stop(self, target: float) -> bool: """Count an accepted step; return whether to stop at its end to save it. @@ -1757,20 +1249,17 @@ def _natural_stop_due(self, target: float) -> bool: _monitor: BoundaryMonitor | None = None """The run's boundary monitor (SEP 21), fed every committed step; ``None``.""" - _input_floor: Complex[np.ndarray, "n_modes n_pol n_omega"] | None = None - """The input-noise draw the launch carries, the monitor's floor; ``None``.""" - _split_removed: float = 0.0 """What the ``"split_step"`` collar took at the accepted steps since the monitor's last reading, in its units (:attr:`solprop.monitor.BoundaryEnergies.removed`): - a host backend's :meth:`_finish` adds to it while a monitor of that scheme is - attached (:attr:`_split_monitor`), and :meth:`_boundary_energies` drains it.""" + each accepted step's :class:`~solprop.backends.engines.AcceptRecord` adds to it + (:meth:`_absorb`) and :meth:`_boundary_energies` drains it.""" _split_found: Float[np.ndarray, " 4"] | None = None """The energy and the guards' and collar's energies of the power the last accepted step's split found (:attr:`solprop.monitor.BoundaryEnergies.found`), which the - monitor judges the occupancies on: set by a host backend's :meth:`_finish` with - :attr:`_split_removed`, and ``None`` before the first such step.""" + monitor judges the occupancies on: the latest accepted step's, and ``None`` before + the first such step.""" reads_transverse_edge: bool = False """Whether this backend reads a free-space run's transverse edge on the host @@ -1815,23 +1304,23 @@ def attach_monitor(self, monitor: BoundaryMonitor) -> None: monitor.crossing = self._problem.split_crossing self._monitor = monitor self._bind_monitor(monitor) + workspace = self._workspace # The noise draw is a host array already, read once. monitor.launch( - self._boundary_energies(self._require_state()), + self._boundary_energies(), self._z, - floor=self._input_floor, + floor=workspace.input_floor, ) self._set_collar_quiet(monitor.collar_quiet) # A resumed fixed schedule is held to the state it resumes from at once. self._refuse_scheduled_crossing(monitor) edge = monitor.transverse if edge is not None: - floor = self._input_floor + floor = workspace.input_floor schedule = self._stepper.schedule - state = self._require_state() + self._require_state() edge.launch( - self._edge_reading( - state, + workspace.edge_reading( edge, # A resumed launch reads no share, but continues the current. full=not edge.resumed, @@ -1839,7 +1328,7 @@ def attach_monitor(self, monitor: BoundaryMonitor) -> None: ), self._z, noise=None if floor is None else np.asarray(floor), - clean_columns=self._edge_clean_columns(edge), + clean_columns=workspace.clean_columns(edge), steps=None if schedule is None else np.asarray(schedule.steps), reads=self.reads_transverse_edge, declared=_declared_discard(self._problem), @@ -1861,9 +1350,8 @@ def _read_transverse(self, monitor: BoundaryMonitor, *, plane: bool) -> None: accumulate = edge.every_step and not plane if not (read or accumulate): return - reading = self._edge_reading( - self._require_state(), edge, faces=read, current=accumulate - ) + self._require_state() + reading = self._workspace.edge_reading(edge, faces=read, current=accumulate) if accumulate: assert reading.current is not None edge.step(reading.current, self._z) @@ -1888,51 +1376,6 @@ def edge_memory(self, space: object) -> int: del space return 0 - def _edge_reading( - self, - state: _StateT, - edge: TransverseEdge, - *, - faces: bool = True, - current: bool = False, - full: bool = False, - ) -> _EdgeReading: - """Return what the transverse edge asks of a state (SEP 44). - - The default reduces a host copy of the field, the reference - (``_HostEdgeReduction``); a backend whose state - lives elsewhere reduces it there and returns the numbers, without a copy of it. - - - ``full``: whether every node is wanted, not only the rows a read uses. - """ - return edge.reduction.reading( - np.asarray(self._observed_field(state)), - faces=faces, - current=current, - full=full, - ) - - def _edge_clean_columns( - self, edge: TransverseEdge - ) -> Float[np.ndarray, " n_columns"] | None: - """Return each column's launched energy without the input noise, or ``None``. - - What the safety ramp is judged on, so a run with no ramp needs none. It is - formed where the load has both parts, which needs no state on the host. Only a - resume that found no record of the monitor has none, and then the state has to - cross once. - - - Returns: the unweighted energies, or ``None`` with no noise, no ramp or on a - resumed launch. - """ - floor = self._input_floor - if floor is None or edge.resumed or edge.design is None: - return None - if self._clean_columns is not None: - return self._clean_columns - state = np.asarray(self._observed_field(self._require_state())) - return edge.reduction.column_power(state - np.asarray(floor)) - def _next_step(self) -> float: """Return the step the march takes next, m. @@ -1949,7 +1392,7 @@ def _next_step(self) -> float: return 0.0 return float(schedule.steps[self._schedule_index]) - def _transverse_capped(self, proposal: float) -> float: + def _transverse_capped(self, proposal: float, z: float) -> float: """Return the proposal, held to the transverse edge's read spacing (SEP 40 5.3). A low-source run commits long steps, and light could cross the edge unseen @@ -1957,13 +1400,14 @@ def _transverse_capped(self, proposal: float) -> float: made to land on a read: the edge is read before a step would pass one. - ``proposal``: the controller's proposal, m. + - ``z``: where the step starts, m. - Returns: the proposal, or the read spacing, m. """ monitor = self._monitor edge = None if monitor is None else monitor.transverse if edge is None: return proposal - return min(proposal, edge.ceiling(self._z)) + return min(proposal, edge.ceiling(z)) def _split_capped(self, proposal: float) -> float: """Return the proposal, held to the split collar's crossing limit. @@ -1980,55 +1424,50 @@ def _split_capped(self, proposal: float) -> float: return proposal if monitor is None else min(proposal, monitor.step_cap) def _bind_monitor(self, monitor: BoundaryMonitor | None) -> None: - """Prepare to read a boundary monitor's energies, or stop reading them. + """Read a boundary monitor's energies from now on, or stop reading them. Called when a monitor is attached, with nothing yet taken by a split, and - with ``None`` when a state is loaded. The default keeps its reading on the - host; a backend whose state lives elsewhere overrides this to hold the - monitor's weights (:attr:`solprop.monitor.BoundaryMonitor.weights`, and the - columns' quadrature) where it reduces, and to add each accepted step's split - removal there from now on (:meth:`_boundary_energies`). + with ``None`` when a state is loaded: either empties the split collar's + accumulator (SEP 52 section 5.2), and the workspace takes the split's sums at + each accepted step's finish while a monitor of that scheme is bound. - ``monitor``: the run's monitor, or ``None`` to stop. """ - del monitor self._split_removed = 0.0 self._split_found = None + self._workspace.bind_monitor(monitor) - @property - def _split_monitor(self) -> BoundaryMonitor | None: - """Return the monitor a host backend's finish adds the split's removal for. + def _absorb(self, record: AcceptRecord) -> None: + """Accumulate an accepted step's split collar's sums (SEP 52 section 5.2). - - Returns: the attached monitor under the ``"split_step"`` scheme, else - ``None``. + The removal adds over every accepted step since the previous check, which the + next reading drains; the found occupancies are the latest accepted step's. A + step that took no split sums -- no collar of that scheme, or no monitor -- + leaves both as they were. """ - monitor = self._monitor - return monitor if monitor is not None and monitor.split else None + if record.found is not None: + self._split_removed += record.removed + self._split_found = record.found - def _boundary_energies(self, state: _StateT) -> BoundaryEnergies: - """Return the boundary monitor's reading of a state (SEP 21, ADR-057). + def _boundary_energies(self) -> BoundaryEnergies: + """Return the boundary monitor's reading of the state (SEP 21, ADR-057). - The state's energy and its four weighted energies - (:class:`solprop.monitor.BoundaryEnergies`), what the split collar took at - the accepted steps since the previous reading, which this drains, and the - energies of the power the last step's split found. The default - reduces on the host (:meth:`solprop.monitor.BoundaryMonitor.energies`), the - reference; a backend whose state lives elsewhere reduces it there and returns - the five numbers, without a copy of the field. + The workspace's reading of the committed state (its energy, its four weighted + energies and its occupancy), with what the split collar took at the accepted + steps since the previous reading, which this drains, and the energies of the + power the last step's split found. """ monitor = self._monitor if monitor is None: raise BackendError(f"{self.name}: no boundary monitor is attached") removed, self._split_removed = self._split_removed, 0.0 - field = self._observed_field(state) - crossing = monitor.crossing - return dataclasses.replace( - monitor.energies(field), + reading = self._workspace.reading() + return BoundaryEnergies( + total=reading.total, + regions=reading.regions, removed=removed, found=self._split_found, - occupancy=None - if crossing is None - else crossing.occupancy(field, monitor.columns), + occupancy=reading.occupancy, ) def _check_boundaries( @@ -2039,9 +1478,10 @@ def _check_boundaries( - ``plane``: true for a saved plane's check of a step the monitor already skipped. """ + self._require_state() self._check_at( monitor, - self._boundary_energies(self._require_state()), + self._boundary_energies(), self._z, self._schedule_index, plane=plane, @@ -2119,6 +1559,7 @@ def _set_collar_quiet(self, quiet: bool) -> None: self._monitor.note_collar(quiet) if quiet != self._collar_quiet: self._collar_quiet = quiet + self._workspace.collar_quiet = quiet self._collar_changed() def _quiet_capped(self, proposal: float) -> float: @@ -2171,12 +1612,12 @@ def _monitor_plane(self) -> None: def _take_step_stats(self) -> None: """Record one statistics row when this accepted step is the period-th. - Called from the two step loops **after** ``_finish`` and after ``self._z`` is - advanced, which is the only point at which both describe the step just - committed: ``_march_to`` records the attempt before it finishes the state and - ``_replay_to`` after, so anything reading ``self._state`` or ``self._z`` from - inside ``_on_accepted_step`` would be one accepted step stale on an adaptive run - and correct on a replayed one. + Called by every march (:meth:`_SessionHooks.stepped`) **after** the engine's + accept and after the march's position is advanced, which is the only point at + which both describe the step just committed: an adaptive march records the + attempt before it accepts and a replay after, so anything reading the state or + the position from inside ``_on_accepted_step`` would be one accepted step stale + on an adaptive run and correct on a replayed one. The row is :meth:`stats` of the periodic subset, so there is exactly one implementation of every statistic and a row taken at a save plane is bitwise @@ -2234,169 +1675,17 @@ def _record(self, z: float, dz: float, norm: float, accepted: bool) -> None: # --- noise --------------------------------------------------------------------- - def _noise_field( - self, noise: NoiseRealisation | None - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"] | None: - """Return the noise realisation to carry, in the canonical layout. - - - Returns: the noise spectrum, or ``None`` when no noise model is active. - """ - if self._problem.initial.noise_model == "none": - return None - if noise is not None: - return noise_spectrum(noise, self._problem.shape) - return self._problem.initial.noise0 - - def _noise_at( - self, bundle: StageScalars - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"] | None: - """Return the shot-noise field advanced to a stage's position. - - ``N(z) = N0 exp(i Im Phi(omega, z))``: dispersion yes, loss and gain no, from - the same terms as the linear flow, so the noise costs one multiply-add per - element per stage and no transform. - - - Returns: the advanced noise, or ``None`` when the modified model is not in - use. - """ - if self._noise is None: - return None - return self._noise * np.exp(1j * self._unitary_phase(bundle)) - - def _noise_phase( - self, - ) -> Float[np.ndarray, "n_modes n_pol n_omega"] | None: - """Return ``Im Phi`` at the current position, or ``None`` without a noise model. - - - Returns: the phase in radians, in the canonical layout. - """ - if self._problem.initial.noise_model == "none": - return None - phase = self._unitary_phase(self._stage_scalars(self._z, self._z)) - return np.ascontiguousarray(np.broadcast_to(phase, self._problem.shape)) - # --- guards -------------------------------------------------------------------- - def _axis_statistics( - self, - field: Complex[np.ndarray, "n_modes n_pol n_omega"] | None, - scan: tuple[np.ndarray, np.ndarray] | None, - ) -> dict[str, np.ndarray]: - """Return the four on-axis plasma statistics of the state (SEP 19). - - A rule with a node on the axis hands over that node's row from this - observation's node scan; otherwise the axis row is scanned once - (:func:`solprop.backends.numpy_ref.populations.axis_populations`). - - - ``field``: the state at this plane, shape (n_modes, n_pol, n_omega), or - ``None`` from a backend whose :meth:`_axis_row_populations` reads its own - state. - - ``scan``: this observation's channel fractions and peak rates at every node, - when the node statistics already scanned them. - - Returns: the four ``on_axis_*`` statistics. - """ - if self._modes is None: - msg = ( - "the on-axis plasma statistics need the mode set, which the kernel " - "contract does not carry; construct the backend with " - f"select({self.name!r}, problem, request, modes=modes)" - ) - raise BackendError(msg) - from solprop.backends.populations import ( # noqa: PLC0415 - a cycle - axis_node, - axis_statistics, - ) - - if not self._axis_node_known: - self._axis_node_known = True - self._axis_node = axis_node( - self._problem, - mode_matrix( - self._modes, - on_axis_rule(self._modes[0].dimlimits(0.0)[0]), - 0.0, - components=("x", "y"), - ).synthesis, - ) - if scan is not None and self._axis_node is not None: - fractions, peaks = scan - node = self._axis_node - return axis_statistics( - self._problem, self._z, fractions[:, node], peaks[:, node] - ) - self.axis_scans += 1 - fractions, peaks = self._axis_row_populations( - field, self._on_axis_synthesis(self._modes) - ) - return axis_statistics(self._problem, self._z, fractions, peaks) - - def _axis_row_populations( - self, - field: Complex[np.ndarray, "n_modes n_pol n_omega"] | None, - axis: Float[np.ndarray, "n_rows n_modes"], - ) -> tuple[Float[np.ndarray, " n_channels"], Float[np.ndarray, " n_channels"]]: - """Scan this plane's axis row: one row, every channel. - - A device backend overrides this hook to read only the row from its state. - - - ``axis``: the mode set's synthesis on the axis at this position - (:meth:`_on_axis_synthesis`). - - Returns: the final ionised fraction and the largest rate on the axis, per - channel. - """ - if field is None: - raise BackendError("the on-axis statistics scan needs the field") - from solprop.backends.numpy_ref.populations import ( # noqa: PLC0415 - a cycle - axis_populations, - ) - - return axis_populations(self._problem, field, self._z, axis) - - def _on_axis_synthesis( - self, modes: Sequence[Mode] - ) -> Float[np.ndarray, "n_rows n_modes"]: - """Return the mode set's synthesis matrix on the axis, at the current position. - - Built once at ``z = 0`` and rescaled by the transform's own taper factor: the - axis is the single node ``r = 0`` of - :func:`solprop.modes.quadrature.on_axis_rule`, so the law that rescales the - transform's matrices -- a scale-invariant profile goes as ``1/a`` and its - normalisation as ``a^2`` -- applies to it exactly, and a set that is neither - constant nor scale invariant never reaches a backend (``translate.modal``). - Rebuilding the matrix at every call was what kept ``peak_intensity`` out of the - between-planes channel. - - - Returns: shape ``(n_rows, n_modes)``, one row per Cartesian component on the - axis. - """ - if self._on_axis is None: - rule = on_axis_rule(modes[0].dimlimits(0.0)[0]) - matrices = mode_matrix(modes, rule, 0.0, components=("x", "y")) - self._on_axis = np.ascontiguousarray(matrices.synthesis) - taper = self._problem.transform.taper_scale - if taper is None: - return self._on_axis - return self._on_axis * float(taper(self._z)) - - def _require_grid(self) -> TimeGrid: - """Return the grid the state lives on, or say why statistics cannot be taken.""" - if self._grid is None: - msg = ( - "statistics need the grid the state lives on, which the kernel " - f"contract does not carry; construct the backend with select(" - f"{self.name!r}, problem, request, grid=grid)" - ) - raise BackendError(msg) - return self._grid - def _require_state(self) -> _StateT: """Return the current state, refusing a closed or unloaded backend.""" self._check_open() - if self._state is None: + state = self._workspace.state + if state is None: msg = "no initial state: call set_initial before propagating or observing" raise BackendError(msg) self._refuse_in_flight() - return self._state + return cast("_StateT", state) def _refuse_in_flight(self) -> None: """Refuse every entry that reads or advances a state left between two steps. @@ -2406,16 +1695,9 @@ def _refuse_in_flight(self) -> None: end, so an exception or a signal between them leaves nothing a reader may use and nothing a march may continue from. Only :meth:`set_initial` clears it. """ - if self._in_flight is None: - return - z, dz = self._in_flight - msg = ( - f"{self.name}: the low-storage step of {dz:.6g} m from z = {z:.6g} m was " - "abandoned in flight, and the state it was accepting in place holds " - "neither end of the step; load a state with set_initial (resume from the " - "last saved plane) before observing or propagating again" - ) - raise BackendError(msg) + pending = self._abandoned() + if pending is not None: + raise BackendError(in_flight_refusal(self.name, *pending)) @property def closed(self) -> bool: # numpydoc ignore=RT01 @@ -2486,24 +1768,6 @@ def _check_target(self, target: float) -> None: raise BackendError(msg) -def _clean_launch_columns( - field: Complex[np.ndarray, "n_modes n_pol n_omega"], - noise: Complex[np.ndarray, "n_modes n_pol n_omega"], - active: np.ndarray, -) -> Float[np.ndarray, " n_modes"]: - """Return each column's energy in a masked launch, less the input noise it carries. - - That is ``mask(field + noise) - noise``: the launch on the active band, and the - noise alone off it, as a supplied realisation needn't be masked. Formed from the - parts, so that no state has to come back from where it lives to subtract the noise. - - - ``active``: the active band's mask, shape ``(n_omega,)``. - """ - inside = np.abs(field[..., active]) ** 2 - outside = np.abs(noise[..., ~active]) ** 2 - return np.sum(inside, axis=(1, 2)) + np.sum(outside, axis=(1, 2)) - - def _declared_discard(problem: PropagationProblem) -> bool: """Return whether a run declared content above ``discard_above`` (SEP 40 5.3). diff --git a/src/solprop/backends/host/low_storage.py b/src/solprop/backends/host/low_storage.py index 0f88f1b69..8a5621c53 100644 --- a/src/solprop/backends/host/low_storage.py +++ b/src/solprop/backends/host/low_storage.py @@ -2,26 +2,29 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The reference's low-storage interaction-picture RK4 march (SEP 24, SEP 47). - -:class:`HostLowStorageMarch` replays a prescribed schedule and accepts each step in -place, through the host engine (:class:`solprop.backends.low_storage.HostLowStorage`), -which holds the registers and makes the step's four passes. It is the NumPy -reference's own since SEP 47 phase 2, sharing only the stateless engine; the native -session replays the march natively. The method, the register form and the in-flight -contract are those of :mod:`solprop.backends.low_storage`'s module documentation. +"""The reference's low-storage interaction-picture RK4 march (SEP 24, SEP 52). + +:class:`HostLowStorageMarch` replays a prescribed schedule through a +:class:`~solprop.backends.engines.RungeKuttaEngine` with the documented destructive +trial: the reference's is :class:`solprop.backends.low_storage.HostLowStorage`, which +holds the registers and makes the step's four passes. The engine owns the in-flight +flag and the finish; the march owns the committed position, in its own +:class:`~solprop.backends.host.marches.MarchState`, and the count of committed source +evaluations. The method, the register form and the in-flight contract are those of +:mod:`solprop.backends.low_storage`'s module documentation. """ import logging import math -from typing import Any +from collections import deque +from typing import cast from solprop._interrupts import committing -from solprop.backends.host.driver import HostDriver, replay_tolerance -from solprop.backends.low_storage import HostLowStorage +from solprop.backends.engines import RungeKuttaEngine +from solprop.backends.host.marches import MarchHost, MarchState, in_flight_refusal from solprop.exceptions import BackendError, ConvergenceError from solprop.stepper.low_storage import LowStorageRungeKutta -from solprop.stepper.schedule import FixedSchedule +from solprop.stepper.schedule import FixedSchedule, replay_tolerance __all__ = ["HostLowStorageMarch"] @@ -31,59 +34,103 @@ class HostLowStorageMarch: """Replay a schedule with the low-storage RK4IP march, accepting in place. - Follows :class:`solprop.backends.host.adams.HostAdamsMarch`: it owns its registers - through an engine and replays a prescribed schedule, which is the only thing it - does (SEP 24 section 6.2). Each step calls the engine, applies the backend's - ``_finish`` (the hard band mask, and the split-step collar where chosen) and moves - the position in one commit, then records the step through the backend. + It replays a prescribed schedule, which is the only thing it does (SEP 24 section + 6.2). Each step's trial overwrites the state; the accept finishes it (the hard band + mask, and the split-step collar where chosen) and the march moves its position in + the same commit, then records the step through its session. Parameters ---------- - backend : solprop.backends.host.driver.HostDriver - The backend whose state is marched; it owns the step history and the - statistics rows. + engine : solprop.backends.engines.RungeKuttaEngine + The engine; beside the protocol, a load calls its ``reset``. method : solprop.stepper.low_storage.LowStorageRungeKutta The march. + host : solprop.backends.host.marches.MarchHost + The session the march reports to. + schedule : solprop.stepper.schedule.FixedSchedule + The schedule it replays. + proposal : float + The proposal it keeps, m, which a replay never updates. + lag : int, optional + The lag of the controller whose norms the replay keeps. + name : str, optional + The backend's name, for messages. Attributes ---------- + state : solprop.backends.host.marches.MarchState + The march's position, proposal, cursor and accepted norms. source_evaluations : int - Source evaluations of the committed steps since the state was last loaded - (``HostDriver.set_initial``, which sets it to zero), four a step: a physical - count, never a logical response call (SEP 24 section 5). A step that did not - commit -- abandoned in flight, or diverged -- adds none. + Source evaluations of the committed steps since the state was last loaded, + four a step: a physical count, never a logical response call (SEP 24 section + 5). A step that did not commit -- abandoned in flight, or diverged -- adds none. Notes ----- The march has no error estimate to warn on. It logs a warning, once per call of - :meth:`replay_to`, when the engine's stiffness indicator passes RK4's + :meth:`replay_to`, when an accepted step's stiffness indicator + (:attr:`~solprop.backends.engines.AcceptRecord.stiffness`) passes RK4's negative-real stability interval (:data:`~solprop.stepper.low_storage.LOW_STORAGE_REAL_INTERVAL`): an explicitly integrated damping term the translation cannot bound in advance -- plasma loss -- is then near the step's stability limit. """ - def __init__(self, backend: HostDriver[Any], method: LowStorageRungeKutta) -> None: - """Hold the backend and its engine.""" - self._backend = backend + def __init__( + self, + engine: object, + method: LowStorageRungeKutta, + host: object, + *, + schedule: FixedSchedule, + proposal: float, + lag: int = 1, + name: str = "numpy_ref", + ) -> None: + """Hold the engine; the march stands at the entrance.""" + self._engine = cast("RungeKuttaEngine", engine) self._method = method + self._host = cast("MarchHost", host) + self._schedule = schedule + self._name = name self._warned = False - # The host engine is the oracle (SEP 24 section 6.5). - self._engine = HostLowStorage(backend, method) + # The step whose trial the engine left in flight, while it is. + self._pending: tuple[float, float] | None = None + self.state = MarchState(z=0.0, proposal=proposal, norms=deque(maxlen=lag + 2)) self.source_evaluations = 0 @property - def engine(self) -> HostLowStorage: # numpydoc ignore=RT01 + def engine(self) -> object: # numpydoc ignore=RT01 """Engine that holds the registers.""" return self._engine - def reset(self) -> None: - """Forget what the engine holds: the state was loaded outside the march.""" - self._engine.reset() + @property + def holding(self) -> bool: # numpydoc ignore=RT01 + """Whether a dense observation holds a plane; never, on this march.""" + return False + + @property + def in_flight(self) -> tuple[float, float] | None: # numpydoc ignore=RT01 + """The step a failure left in flight, its start and length, m; or ``None``.""" + return self._pending if self._engine.in_flight else None + + def load(self, z: float, proposal: float, cursor: int) -> None: + """Start afresh at a loaded position; a step left in flight is cleared. - def close(self) -> None: - """Release the engine's registers and table, with the backend's buffers.""" - self._engine.close() + Parameters + ---------- + z : float + The position, m. + proposal : float + The proposal, m. + cursor : int + The replay cursor at `z`. + """ + self.state.load(z, proposal, cursor) + self._engine.reset() # pyright: ignore[reportAttributeAccessIssue] + self._pending = None + # Its count is the loaded run's, as the Adams ledger is (SEP 22 4.7). + self.source_evaluations = 0 def snapshot(self) -> None: """Return nothing for a resume to continue: the march keeps no history. @@ -93,6 +140,27 @@ def snapshot(self) -> None: """ return + def refusal(self) -> str | None: + """Return why the state cannot be read or advanced, or ``None``. + + Returns + ------- + str or None + The message of a step left in flight, or ``None``. + """ + pending = self.in_flight + return None if pending is None else in_flight_refusal(self._name, *pending) + + def advance(self, target: float) -> None: + """Replay the schedule towards `target`. + + Parameters + ---------- + target : float + The position to reach, m. + """ + self.replay_to(self._schedule, target) + def replay_to(self, schedule: FixedSchedule, target: float) -> None: """Replay the schedule's steps to `target`, mirroring the Adams replay. @@ -108,24 +176,22 @@ def replay_to(self, schedule: FixedSchedule, target: float) -> None: BackendError If the schedule runs out before the target is reached. """ - backend = self._backend + host, state = self._host, self.state edges = schedule.edges slack = replay_tolerance(schedule, target) self._warned = False - while ( - backend._schedule_index < schedule.n_steps and backend._z < target - slack - ): - backend._poll_stop() - dz = float(schedule.steps[backend._schedule_index]) - end = float(edges[backend._schedule_index + 1]) + while state.cursor < schedule.n_steps and state.z < target - slack: + host.poll_stop() + dz = float(schedule.steps[state.cursor]) + end = float(edges[state.cursor + 1]) norm = self.replay_step(dz, end, slack) - backend._schedule_index += 1 - backend._record(end, dz, norm, accepted=True) - backend._accepted_norms.append(norm) - backend._take_step_stats() - if backend._natural_stop(target): + state.cursor += 1 + host.record(end, dz, norm, accepted=True) + state.norms.append(norm) + host.stepped() + if host.natural_stop(target): return - if backend._z < target - slack: + if state.z < target - slack: msg = ( f"the replayed schedule ends at {float(schedule.z_end):.6g} m and " f"cannot reach z = {target:.6g} m" @@ -133,7 +199,7 @@ def replay_to(self, schedule: FixedSchedule, target: float) -> None: raise BackendError(msg) def replay_step(self, dz: float, end: float, slack: float) -> float: - """Take one prescribed step from the backend's position and accept it. + """Take one prescribed step from the march's position and accept it. The unit a replay advances by, with :meth:`solprop.backends.host.adams.HostAdamsMarch.replay_step`'s signature. @@ -162,40 +228,18 @@ def replay_step(self, dz: float, end: float, slack: float) -> float: cannot reject the step. Raised in flight, so the state is lost with it. """ del slack - backend = self._backend - backend._refuse_in_flight() - z = backend._z - backend._in_flight = (z, dz) + refusal = self.refusal() + if refusal is not None: + raise BackendError(refusal) + state = self.state + z = state.z + self._pending = (z, dz) # The host passes are Python calls a signal may interrupt (the engine is not # atomic): an interrupted step stays in flight, and only the move commits. - squared = self._engine.step(z, dz) - finished = self._accept(z, dz, squared) - with committing(): - self._move(finished, end) - self._check_stiffness(z, dz) - return 0.0 - - def _move(self, finished: object, end: float) -> None: - """Make the finished state the backend's at the step's end; clear the flag. - - - ``end``: the schedule's edge the step ends on, m. - """ - backend = self._backend - backend._state = finished - backend._z = end - backend._in_flight = None - self.source_evaluations += self._method.evaluations - - def _accept(self, z: float, dz: float, squared: float) -> object: - """Refuse a diverged step, or apply the backend's finish to the state. - - - ``z``: where the step started, m. - - ``dz``: the step, m. - """ - backend = self._backend + squared = self._engine.trial(z, dz) if not math.isfinite(squared): msg = ( - f"{backend.name}: a replayed {self._method.name} step of {dz:.4g} m " + f"{self._name}: a replayed {self._method.name} step of {dz:.4g} m " f"from z = {z:.6g} m ended in a non-finite state: the field has " "diverged. A replayed schedule takes its steps as given and cannot " "reject one, so a step beyond an explicit stability limit -- the " @@ -204,15 +248,21 @@ def _accept(self, z: float, dz: float, squared: float) -> object: "accepted in place and is lost; take shorter steps" ) raise ConvergenceError(msg) - return backend._finish(backend._state, dz) + with committing(): + record = self._engine.accept(dz) + state.z = end + self._pending = None + self.source_evaluations += self._method.evaluations + self._host.absorb(record) + self._check_stiffness(z, dz, record.stiffness) + return 0.0 - def _check_stiffness(self, z: float, dz: float) -> None: + def _check_stiffness(self, z: float, dz: float, stiffness: float) -> None: """Warn, once per replay, when a step's stiffness passes RK4's interval. - ``z``: where the step started, m. - ``dz``: the step, m. """ - stiffness = self._engine.stiffness interval = self._method.real_stability_interval if self._warned or not stiffness > interval: return @@ -223,7 +273,7 @@ def _check_stiffness(self, z: float, dz: float) -> None: "explicitly integrated damping term (plasma loss, an in-stage collar) is " "near the step's stability limit and may make the replay diverge. Take " "shorter steps", - self._backend.name, + self._name, self._method.name, stiffness, interval, diff --git a/src/solprop/backends/host/marches.py b/src/solprop/backends/host/marches.py new file mode 100644 index 000000000..7da300049 --- /dev/null +++ b/src/solprop/backends/host/marches.py @@ -0,0 +1,188 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""What every reference march holds, and what it asks of its session (SEP 52). + +A march -- :class:`~solprop.backends.host.runge_kutta.RungeKuttaMarch`, +:class:`~solprop.backends.host.adams.HostAdamsMarch` or +:class:`~solprop.backends.host.low_storage.HostLowStorageMarch` -- keeps its +position, proposal, replay cursor and accepted norms in a :class:`MarchState` of its +own, hands every state-sized operation to its engine +(:mod:`solprop.backends.engines`) and asks the session only through the narrow +:class:`MarchHost`: whether to stop, how far a step may go, and what to record when an +attempt ends. It touches no other object's fields; the session reads its state. +""" + +from collections import deque +from dataclasses import dataclass, field +from typing import Protocol + +from solprop.backends.engines import AcceptRecord + +__all__ = ["MarchHost", "MarchState", "in_flight_refusal"] + + +@dataclass(eq=False) +class MarchState: + """A march's position, proposal, replay cursor and accepted norms (SEP 45 4.2). + + Attributes + ---------- + z : float + The committed state's position, m; while a dense observation holds a plane, + the plane's. + proposal : float + The controller's proposal, m: its own state, never the executed step. + cursor : int + A replay's next step: how many steps of the schedule are consumed. + norms : collections.deque + The accepted steps' norms the controller reads, oldest first, at most its + lag and two more. + """ + + z: float + proposal: float + cursor: int = 0 + norms: deque[float] = field(default_factory=deque) + + def load(self, z: float, proposal: float, cursor: int) -> None: + """Start afresh at a loaded position. + + Parameters + ---------- + z : float + The position, m. + proposal : float + The first proposal, m. + cursor : int + The replay cursor at `z`. + """ + self.z = z + self.proposal = proposal + self.cursor = cursor + self.norms.clear() + + +class MarchHost(Protocol): + """What a march asks of the session that schedules it. + + The reference's step driver implements it today; SEP 52 moves it into the + reference's session. + """ + + @property + def collar_quiet(self) -> bool: # numpydoc ignore=RT01 + """Whether the stages leave a quiet in-stage temporal collar out (SEP 21).""" + ... + + def poll_stop(self) -> None: + """Raise when the run's stop flag is set; called before every attempt.""" + ... + + def cap(self, proposal: float, z: float) -> float: + """Return a proposal held to the boundary monitor's and the edge's limits. + + Parameters + ---------- + proposal : float + The controller's proposal, m. + z : float + Where the step starts, m. + + Returns + ------- + float + The proposal, or the quiet collar's interval, the transverse edge's read + spacing or the split collar's crossing limit when shorter, m. + """ + ... + + def record(self, end: float, dz: float, norm: float, accepted: bool) -> None: + """Record one attempt in the history since the last observation. + + Parameters + ---------- + end : float + The attempt's end, m. + dz : float + Its length, m. + norm : float + The scaled error norm as executed. + accepted : bool + Whether it was accepted. + """ + ... + + def absorb(self, record: AcceptRecord) -> None: + """Accumulate an accepted step's split collar's sums (SEP 52 section 5.2). + + Parameters + ---------- + record : solprop.backends.engines.AcceptRecord + What the step's finish reported. + """ + ... + + def stepped(self) -> None: + """Account the step just committed: the monitor and the statistics row.""" + ... + + def natural_stop(self, target: float) -> bool: + """Count an accepted step; return whether to stop at its end. + + Parameters + ---------- + target : float + The position the call is stepping to, m. + + Returns + ------- + bool + Whether a step plane or a halt stops the march here. + """ + ... + + def natural_stop_due(self, target: float) -> bool: + """Return whether a step to save, or a halt, ends the march where it stands. + + Parameters + ---------- + target : float + The position the call is stepping to, m. + + Returns + ------- + bool + Whether the march returns at once. + """ + ... + + +def in_flight_refusal(name: str, z: float, dz: float) -> str: + """Return why a state a low-storage step left in flight cannot be used. + + The step accepts in place (SEP 24 section 6.2): from its start to its commit the + state is neither the step's start nor its end, so an exception or a signal between + them leaves nothing a reader may use and nothing a march may continue from. + + Parameters + ---------- + name : str + The backend's name. + z : float + Where the step started, m. + dz : float + The step, m. + + Returns + ------- + str + The message. + """ + return ( + f"{name}: the low-storage step of {dz:.6g} m from z = {z:.6g} m was " + "abandoned in flight, and the state it was accepting in place holds " + "neither end of the step; load a state with set_initial (resume from the " + "last saved plane) before observing or propagating again" + ) diff --git a/src/solprop/backends/host/runge_kutta.py b/src/solprop/backends/host/runge_kutta.py new file mode 100644 index 000000000..1e0e2b0e9 --- /dev/null +++ b/src/solprop/backends/host/runge_kutta.py @@ -0,0 +1,289 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""The reference's Runge-Kutta march, adaptive and replayed (SEP 45, SEP 52). + +:class:`RungeKuttaMarch` holds the march's state (:class:`~solprop.backends.host. +marches.MarchState`) and makes its decisions with :mod:`solprop.backends.rk_core`'s +functions of one policy record; every state-sized operation is its engine's +(:class:`~solprop.backends.engines.RungeKuttaEngine`). It is the counterpart of +native's ``rk_march.cpp``, whose decisions on identical inputs are its own (the +decision traces of ``tests/backends``). + +**The controller's state is its own proposal**, never the clipped or stretched step +that was executed, and what the history and a rejection see is the norm the proposal +would have scored while what decides acceptance is the error the executed step +committed (``docs/dev/stepper.md`` section 3). +""" + +import math +from collections import deque +from typing import cast + +import numpy as np + +from solprop._interrupts import committing +from solprop.backends import rk_core +from solprop.backends.engines import RungeKuttaEngine +from solprop.backends.host.marches import MarchHost, MarchState +from solprop.backends.records import RungeKuttaPolicy +from solprop.exceptions import BackendError, ConvergenceError +from solprop.stepper.schedule import ( + FixedSchedule, + StepTargets, + landing, + reached, + replay_tolerance, +) + +__all__ = ["RungeKuttaMarch"] + + +class RungeKuttaMarch: + """Step a state adaptively, or replay a schedule, with an embedded pair. + + Parameters + ---------- + engine : solprop.backends.engines.RungeKuttaEngine + The engine; beside the protocol, the march's dense observation calls its + ``hold``, ``restore`` and ``observe``, and a load its ``reset``. + policy : solprop.backends.records.RungeKuttaPolicy + The controller and the landings. + host : solprop.backends.host.marches.MarchHost + The session the march reports to. + schedule : solprop.stepper.schedule.FixedSchedule or None + The schedule to replay, or ``None`` to step adaptively. + proposal : float + The first proposal, m. + name : str, optional + The backend's name, for messages. + + Attributes + ---------- + state : solprop.backends.host.marches.MarchState + The march's position, proposal, cursor and accepted norms. + """ + + def __init__( + self, + engine: object, + policy: RungeKuttaPolicy, + host: object, + *, + schedule: FixedSchedule | None, + proposal: float, + name: str = "numpy_ref", + ) -> None: + """Hold the engine and the policy; the march stands at the entrance.""" + self._engine = cast("RungeKuttaEngine", engine) + self._policy = policy + self._host = cast("MarchHost", host) + self._schedule = schedule + self._name = name + self.state = MarchState( + z=0.0, proposal=proposal, norms=deque(maxlen=policy.controller.lag + 2) + ) + # The march's own position and state while an interpolated plane is observed. + self._ahead: tuple[float, object] | None = None + + @property + def holding(self) -> bool: # numpydoc ignore=RT01 + """Whether a dense observation holds the state at a plane, the march ahead.""" + return self._ahead is not None + + def load(self, z: float, proposal: float, cursor: int) -> None: + """Start afresh at a loaded position. + + Parameters + ---------- + z : float + The position, m. + proposal : float + The first proposal, m. + cursor : int + The replay cursor at `z`. + """ + self.state.load(z, proposal, cursor) + self._ahead = None + self._engine.reset() # pyright: ignore[reportAttributeAccessIssue] + + def advance(self, target: float) -> None: + """Replay the schedule, or step adaptively, towards `target`. + + Parameters + ---------- + target : float + The position to reach, m. + """ + if self._schedule is not None: + self.replay_to(self._schedule, target) + else: + self.march_to(target) + + def march_to(self, target: float) -> None: + """Step adaptively to `target`, landing on it exactly. + + Parameters + ---------- + target : float + The position to reach, m. + + Raises + ------ + ConvergenceError + If the controller asks for a step below the policy's floor. + """ + policy, host, state, engine = self._policy, self._host, self.state, self._engine + dense = policy.interpolate + if dense and self._ahead is not None: + # The march is ahead of the last interpolated plane; resume it there. + z, held = self._ahead + engine.restore(z, held) # pyright: ignore[reportAttributeAccessIssue] + state.z = z + self._ahead = None + if host.natural_stop_due(target): + return + # The policy's landings (SEP 45 section 4.2): only the operator table's two + # ends bound a step without the interval cap (SEP 14 section 4.1), and dense + # output steps across the save planes, still landing on the end of the run and + # the hard kinks (SEP 14 section 4.3). + targets = StepTargets( + save_planes=np.asarray(policy.save_planes, dtype=np.float64), + hard_kinks=np.asarray(policy.hard_kinks, dtype=np.float64), + breakpoints=np.asarray(policy.breakpoints, dtype=np.float64), + dz_max=policy.dz_max, + z_end=policy.z_end if dense else target, + stretch=policy.stretch, + ) + while not reached(state.z, target): + host.poll_stop() + # The controller's state is its own proposal, never the clipped or + # stretched step that was executed: otherwise every save plane restarts it + # from a sliver and it regrows at the growth cap, which over two hundred + # planes costs more steps than the run needs between them (stepper.md 3). + stop = landing(state.z, host.cap(state.proposal, state.z), targets) + norm = engine.trial(state.z, stop.dz) + # What the controller learns from, and what a rejection is scaled by, is the + # norm the *proposal* would have scored; what decides acceptance, and what + # the history records, is the error the executed step actually committed, + # so a short landing step that was accurate is neither thrown away nor + # written up as a failure. + equivalent, accepted = rk_core.decide(policy, norm, stop.dz, state.proposal) + # A landing snaps to its target rather than accumulating z + dz, so that a + # save plane is hit exactly however many steps have gone before. + end = stop.z_target if stop.z_target is not None else state.z + stop.dz + host.record(end, stop.dz, norm, accepted) + if accepted: + if dense and not reached(target, end): + # The step crosses the plane: hold its extension for the + # observation, and for any later plane it also crosses. + engine.extend(state.z, stop.dz) + with committing(): + record = engine.accept(stop.dz) + state.z = end + host.absorb(record) + state.norms.append(equivalent) + if policy.auto_init and len(state.norms) == 1: + self._start_up(equivalent) + # The next proposal grows or shrinks once per accepted step, from the + # history the step completed. A rejected step is retried at the step + # rejection_factor left: applying this factor again there undid the + # shrink, and with a growth cap above about 1.27 a step whose norm sat + # just above one was rejected unchanged forever. + state.proposal = rk_core.propose(policy, state.proposal, state.norms) + host.stepped() + if host.natural_stop(target): + return + else: + state.proposal = rk_core.reject(policy, state.proposal, equivalent) + if dense and not reached(target, state.z): + self._observe_inside(target) + + def _observe_inside(self, position: float) -> None: + """Make the state the interpolated field at `position` and hold the march's. + + - ``position``: the plane, m, inside the last accepted step. + """ + engine, state = self._engine, self.state + observed = engine.observe(position) # pyright: ignore[reportAttributeAccessIssue] + self._ahead = (state.z, engine.hold()) # pyright: ignore[reportAttributeAccessIssue] + engine.restore(position, observed) # pyright: ignore[reportAttributeAccessIssue] + state.z = position + + def _start_up(self, norm: float) -> None: + """Take the step after the first from the first step's own estimate. + + The first proposal is a guess; its scaled norm says how far it is from the + tolerance. The next proposal is the deadbeat step that norm implies, at most + :data:`~solprop.stepper.controller.START_GROWTH` times the first, and the + history is told the norm the first step would have scored at that length, so + the lagged controller does not apply the guess's margin a second time (SEP 14 + section 4.2). A norm small enough to meet the cap is recorded as zero, no + estimate, so that round-off does not steer the later steps. + """ + state = self.state + state.proposal, state.norms[-1] = rk_core.start_up( + self._policy, state.proposal, norm + ) + + def replay_to(self, schedule: FixedSchedule, target: float) -> None: + """Replay a fixed schedule to `target`. + + A replay takes its steps as given and never rejects, but the embedded estimate + costs nothing extra and is computed and recorded every step, so that a schedule + too coarse for its tolerance is reported rather than silent + (``docs/dev/stepper.md`` section 8). The position is read off the schedule's + edges rather than accumulated, so every save plane is hit exactly. + + Parameters + ---------- + schedule : solprop.stepper.schedule.FixedSchedule + The schedule. + target : float + The position to reach, m. + + Raises + ------ + ConvergenceError + If a replayed step's error norm is not finite. + BackendError + If the schedule ends before `target`. + """ + host, state, engine = self._host, self.state, self._engine + edges = schedule.edges + slack = replay_tolerance(schedule, target) + while state.cursor < schedule.n_steps and state.z < target - slack: + host.poll_stop() + dz = float(schedule.steps[state.cursor]) + norm = engine.trial(state.z, dz) + if not math.isfinite(norm): + msg = ( + f"{self._name}: replayed step {state.cursor + 1} of " + f"{schedule.n_steps}, {dz:.4g} m from z = {state.z:.6g} m, has a " + f"non-finite error norm ({norm!r}): the field has diverged. A " + "replayed schedule takes its steps as given and cannot reject " + "one, so a step beyond an explicit stability limit -- the " + "in-stage temporal collar's or a coupled flow's advisory step -- " + "grows until it overflows; the translation refuses a declared step " + "past the collar's limit and warns on one past the flow's. Take " + "shorter steps, or let the controller choose them" + ) + raise ConvergenceError(msg) + end = float(edges[state.cursor + 1]) + with committing(): + record = engine.accept(dz) + state.cursor += 1 + state.z = end + host.absorb(record) + host.record(state.z, dz, norm, accepted=True) + state.norms.append(norm) + host.stepped() + if host.natural_stop(target): + return + if state.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) diff --git a/src/solprop/backends/low_storage.py b/src/solprop/backends/low_storage.py index 81ffdbbd1..22d398350 100644 --- a/src/solprop/backends/low_storage.py +++ b/src/solprop/backends/low_storage.py @@ -38,16 +38,17 @@ **The march** (the reference's :class:`solprop.backends.host.low_storage.HostLowStorageMarch`; the native session's replay) replays a prescribed schedule and never rejects, so it accepts each step in -place: from the step's start to its commit the backend is *in flight* -(``HostDriver._in_flight``) and every entry that reads or advances the state refuses -it, until a load replaces the state (SEP 24 section 6.2, ADR-050). It records no error -estimate: the step history's norm is 0.0, "not estimated" (section 6.3). Divergence is -detected on the accepted state's norm instead. - -**The engine** holds the registers and makes the passes (:class:`LowStorageEngine`); the -native backend keeps its own where its state lives (``_ResidentLowStorage``). -:class:`HostLowStorage` is the host engine and the oracle, over the backend's -``_adams_lab_source`` and ``_adams_propagator``. The engines and the table keys +place: from the start of the step's trial to its accept the engine is *in flight* +and every entry that reads or advances the state refuses it, until a load replaces the +state (SEP 24 section 6.2, ADR-050). It records no error estimate: the step history's +norm is 0.0, "not estimated" (section 6.3). Divergence is detected on the accepted +state's norm instead. + +**The engine** holds the registers and makes the passes: it is a +:class:`~solprop.backends.engines.RungeKuttaEngine` with the documented destructive +trial (SEP 52 section 5.2), as native's low-storage engine is. +:class:`HostLowStorage` is the host engine and the oracle, over the workspace's +``lab_source`` and ``propagator``. The engines and the table keys (:func:`table_steps`, :func:`schedule_key`) are stateless numerical code the reference and the native backend share (SEP 47 Part III decision 5). @@ -63,18 +64,21 @@ import logging import math -from typing import Any, Protocol, cast, runtime_checkable +from typing import TYPE_CHECKING import numpy as np from jaxtyping import Complex, Float -from solprop.backends.host.driver import HostDriver +from solprop.backends.engines import AcceptRecord, BoundaryReading +from solprop.exceptions import BackendError from solprop.stepper.low_storage import LowStorageRungeKutta from solprop.stepper.schedule import LANDING_ULPS, FixedSchedule +if TYPE_CHECKING: + from solprop.backends.numpy_ref.workspace import NumpyWorkspace + __all__ = [ "HostLowStorage", - "LowStorageEngine", "schedule_key", "table_steps", ] @@ -174,70 +178,22 @@ def schedule_key( return float(keys[min(max(index, 0), keys.size - 1)]) -@runtime_checkable -class LowStorageEngine(Protocol): - """What a low-storage march asks of the engine that holds its registers. - - Part of the kernel seam (schema 29): the march keeps the schedule, the commit and - the records; an engine keeps the registers and the flow table and does every - state-sized operation of a step. :class:`HostLowStorage` is the reference. SEP 52's - phase 3 replaces it with :class:`solprop.backends.engines.RungeKuttaEngine`, which - the native low-storage engine already implements. - """ - - stiffness: float - """``h rho`` of the last completed step (SEP 24 section 6.3), or NaN where the - engine does not form it: the march warns when it passes RK4's stability interval.""" - - atomic: bool - """Whether :meth:`step` is one native call that no signal interrupts (schema 32). - - A signal's Python handler runs at the first bytecode after such a call returns, - which is before the commit, so the march then takes the step, the backend's - ``_finish`` and the position move in one ``committing()`` block (SEP 24 section - 6.7): only a native exception can abandon the step in flight. An engine whose step - runs Python between its passes is not atomic, and a signal there abandons the step - at once rather than waiting up to a step for the commit (section 6.2, Q6).""" - - def step(self, z: float, dz: float) -> float: - """Take one step in place, leaving the raw accepted state in the backend. - - Parameters - ---------- - z : float - Where the step starts, m. - dz : float - The step, m, positive. - - Returns - ------- - float - The accepted state's squared norm over the norm mask, before the boundary - treatments, in the state's units squared; not finite when the field has - diverged. - """ - ... - - def reset(self) -> None: - """Forget what a step left behind: the state was loaded outside the march.""" - ... - - def close(self) -> None: - """Release the registers and the flow table; the engine is not used again.""" - ... - - class HostLowStorage: """The host engine: the four register passes over host arrays (SEP 24 6.5). - The backend's state is the register ``A`` and is updated in place; ``B`` and ``C`` - are this engine's host arrays, allocated at the first step. Each pass makes one - source evaluation through ``HostDriver._adams_lab_source`` (the complete source, - the noise draw advanced to the pass's position and the in-stage absorbers - included) and takes ``P`` and ``Q`` from ``HostDriver._adams_propagator`` or the + The workspace's state is the register ``A`` and is updated in place by the + trial; ``B`` and ``C`` are this engine's host arrays, allocated at the first step. + Each pass makes one source evaluation through the workspace's ``lab_source`` (the + complete source, the noise draw advanced to the pass's position and the in-stage + absorbers included) and takes ``P`` and ``Q`` from its ``propagator`` or the table, allocating transients as the reference does. The step's three positions are known before its first pass, so their host scalars are read together - (``HostDriver._stage_bundles``) and the hooks take the kept bundles. + (``stage_bundles``) and the evaluations take the kept bundles. + + **The commit contract** (SEP 52 section 5.2): :meth:`trial` overwrites the state, + and from its start until :meth:`accept` returns the engine is :attr:`in_flight`. + An exception or a non-finite result in that interval leaves no committed state at + that position; only :meth:`reset`, at a load, clears the flag. **The flows.** ``"tabulate"`` on a constant operator holds one volume, ``exp(h_t D / 2)``, built at the first step after a load and reused while the @@ -265,20 +221,22 @@ class HostLowStorage: Parameters ---------- - backend : solprop.backends.host.driver.HostDriver - The reference backend whose state, hooks and boundary treatments are used; its - state is a host array in the canonical layout. The native bridge keeps its - registers resident and never takes this engine (SEP 47 phase 2). + workspace : solprop.backends.numpy_ref.workspace.NumpyWorkspace + The reference's workspace, whose state, evaluations and finish are used. The + native session keeps its registers resident and never takes this engine. method : solprop.stepper.low_storage.LowStorageRungeKutta The march. + schedule : solprop.stepper.schedule.FixedSchedule or None + The replayed schedule, whose runs key the flow table; ``None`` only for an + engine that never tabulates. + propagator_mode : {'tabulate', 'recompute'} + Whether the step's flows are held for it. Attributes ---------- stiffness : float - ``h rho`` of the last completed step, dimensionless; NaN before one, or when + ``h rho`` of the last completed trial, dimensionless; NaN before one, or when ``F2 - g1`` vanished on the norm mask. - atomic : bool - Always ``False``: the passes are Python calls a signal may interrupt. Notes ----- @@ -287,23 +245,40 @@ class HostLowStorage: memory ledger, and :meth:`close` releases them. """ - def __init__(self, backend: HostDriver[Any], method: LowStorageRungeKutta) -> None: - """Hold the backend with no registers yet.""" - self._backend = backend + def __init__( + self, + workspace: "NumpyWorkspace", + method: LowStorageRungeKutta, + schedule: FixedSchedule | None, + propagator_mode: str, + ) -> None: + """Hold the workspace with no registers yet.""" + self._workspace = workspace self._method = method + self._schedule = schedule + self._propagator_mode = propagator_mode self._accumulator: _State | None = None self._stage: _State | None = None self._table: _State | None = None self._table_step = math.nan self._keys: tuple[np.ndarray, np.ndarray] | None = None + self._in_flight = False self.stiffness = math.nan - self.atomic = False + + @property + def in_flight(self) -> bool: # numpydoc ignore=RT01 + """Whether a trial overwrote the state and its accept has not returned.""" + return self._in_flight def reset(self) -> None: - """Drop the flow table, which a resume builds again from its own first step.""" + """Drop the flow table and a step left in flight: a state was loaded. + + A resume builds the table again from its own first step. + """ self._table = None self._table_step = math.nan self.stiffness = math.nan + self._in_flight = False def close(self) -> None: """Release the registers and the flow table.""" @@ -326,8 +301,10 @@ def held(self) -> dict[str, int]: "propagators": _bytes(self._table), } - def step(self, z: float, dz: float) -> float: - """Take one RK4IP step in the four passes of the register form. + def trial(self, z: float, dz: float) -> float: + """Take one RK4IP step in place, in the four passes of the register form. + + The engine is in flight from here until :meth:`accept` returns. Parameters ---------- @@ -339,46 +316,102 @@ def step(self, z: float, dz: float) -> float: Returns ------- float - The accepted state's squared norm over the norm mask, before the boundary - treatments. + 0.0, "not estimated"; or, when the field has diverged, the accepted + state's non-finite squared norm over the norm mask. + """ + workspace = self._workspace + state = workspace.committed() + self._in_flight = True + squared = self._step(state, z, dz) + return squared if not math.isfinite(squared) else 0.0 + + def accept(self, dz: float) -> AcceptRecord: + """Finish the state the trial left and commit it; the step leaves flight. + + Parameters + ---------- + dz : float + The step, m, which the split collar's rate needs. + + Returns + ------- + solprop.backends.engines.AcceptRecord + The stiffness indicator and the finish's split collar's sums. """ - backend = self._backend + workspace = self._workspace + finished, record = workspace.finish(workspace.committed(), dz) + workspace.install(finished) + self._in_flight = False + return AcceptRecord( + stiffness=self.stiffness, removed=record.removed, found=record.found + ) + + def extend(self, z: float, dz: float) -> None: + """Refuse: the low-storage march replays and observes no plane densely. + + Parameters + ---------- + z : float + Where the step started, m. + dz : float + The step, m. + + Raises + ------ + BackendError + Always. + """ + del z, dz + raise BackendError("the low-storage engine holds no dense extension") + + def reading(self) -> BoundaryReading: + """Return the committed state's boundary reading. + + Returns + ------- + solprop.backends.engines.BoundaryReading + The workspace's reading. + """ + return self._workspace.reading() + + def _step(self, state: _State, z: float, dz: float) -> float: + """Take the step's four passes on `state`; return its squared norm.""" + workspace = self._workspace midpoint, end = z + 0.5 * dz, z + dz first, second = self._flows(z, dz) - mask = backend._problem.grids.norm_mask - state = cast("_State", backend._state) + mask = workspace.problem.grids.norm_mask # Pass 1: F1 at z_n; A <- P A, g <- P S, B <- A + h/6 g, C <- A + h/2 g. - source = backend._adams_lab_source(state, z) - flow = backend._adams_propagator(z, midpoint) if first is None else first + source = workspace.lab_source(state, z) + flow = workspace.propagator(z, midpoint) if first is None else first if state.flags.writeable: np.multiply(state, flow, out=state) else: # An observation holds the accepted state read-only; it keeps its own. state = flow * state - backend._state = state + workspace.install(state) slope = flow * source accumulator, stage = self._registers(state) np.add(state, (dz / 6.0) * slope, out=accumulator) np.add(state, (0.5 * dz) * slope, out=stage) # Pass 2: F2 at z_m; B <- B + h/3 S, C <- A + h/2 S. - source = backend._adams_lab_source(stage, midpoint) + source = workspace.lab_source(stage, midpoint) lower = _masked_norm(source - slope, mask) accumulator += (dz / 3.0) * source np.add(state, (0.5 * dz) * source, out=stage) previous = source # Pass 3: F3 at z_m; B <- B + h/3 S, C <- Q (A + h S). - source = backend._adams_lab_source(stage, midpoint) + source = workspace.lab_source(stage, midpoint) upper = _masked_norm(source - previous, mask) accumulator += (dz / 3.0) * source - flow = backend._adams_propagator(midpoint, end) if second is None else second + flow = workspace.propagator(midpoint, end) if second is None else second np.multiply(flow, state + dz * source, out=stage) # Pass 4: F4 at z_n + h; A <- Q B + h/6 S. - source = backend._adams_lab_source(stage, end) - flow = backend._adams_propagator(midpoint, end) if second is None else second + source = workspace.lab_source(stage, end) + flow = workspace.propagator(midpoint, end) if second is None else second np.multiply(flow, accumulator, out=state) state += (dz / 6.0) * source self.stiffness = 2.0 * upper / lower if lower > 0.0 else math.nan @@ -394,35 +427,35 @@ def _flows(self, z: float, dz: float) -> tuple[_State | None, _State | None]: constant operator, the pair on a varying one -- or ``None`` each when recomputed in the finishes that apply them. """ - backend = self._backend + workspace = self._workspace midpoint, end = z + 0.5 * dz, z + dz - tabulating = backend._propagator_mode == "tabulate" - table = tabulating and backend._problem.flags.constant_linop - backend._hoist(z) + tabulating = self._propagator_mode == "tabulate" + table = tabulating and workspace.problem.flags.constant_linop + workspace.hoist(z) # Each evaluation reads its position as its own anchor and each flow its # interval, so the anchors' bundles are read here, once each. - backend._stage_bundles(z, [z] if table else [z, midpoint]) - backend._stage_bundles(midpoint, [midpoint] if table else [midpoint, end]) - backend._stage_bundles(end, [end]) + workspace.stage_bundles(z, [z] if table else [z, midpoint]) + workspace.stage_bundles(midpoint, [midpoint] if table else [midpoint, end]) + workspace.stage_bundles(end, [end]) if table: if self._keys is None: - schedule = backend._stepper.schedule + schedule = self._schedule assert schedule is not None # the translation refused it without one self._keys = (table_steps(schedule), schedule.edges) key = schedule_key(*self._keys, z, dz) if self._table is None or key != self._table_step: # From the operator's origin, where a constant operator's increment is # the half step itself, not fl(z + h/2) - z (class docstring). - origin = backend._problem.linear.z_span[0] + origin = workspace.problem.linear.z_span[0] half = origin + 0.5 * key - backend._stage_bundles(origin, [half]) - self._table = backend._adams_propagator(origin, half) + workspace.stage_bundles(origin, [half]) + self._table = workspace.propagator(origin, half) self._table_step = key return self._table, self._table if tabulating: return ( - backend._adams_propagator(z, midpoint), - backend._adams_propagator(midpoint, end), + workspace.propagator(z, midpoint), + workspace.propagator(midpoint, end), ) return None, None diff --git a/src/solprop/backends/numpy_ref/backend.py b/src/solprop/backends/numpy_ref/backend.py index ffdb4de6f..94e23a878 100644 --- a/src/solprop/backends/numpy_ref/backend.py +++ b/src/solprop/backends/numpy_ref/backend.py @@ -2,106 +2,51 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The reference backend: the step loop, the seam and the refusals. - -One :class:`NumpyRefBackend` steps one mode-averaged problem with the Kerr term, in -plain NumPy, calling the named passes of :mod:`solprop.backends.numpy_ref.passes` in the -order of ``docs/dev/architecture.md`` section 8. The step control follows -``docs/dev/stepper.md`` section 3 exactly: the controller's *proposal* is its state, the -executed step's own norm decides acceptance and is what the history records, and the -equivalent norm of the proposal is what the controller and a rejection see. - -The contract is consumed only through its evaluation functions -- -:func:`solprop.translate.linop.delta_phi`, -:func:`solprop.translate.linop.unitary_phase`, -:func:`solprop.translate.responses.prefactor_at`, and the scalar tables -``responses.density`` and ``transform.taper_scale`` -- never through the coefficient -arrays, so the representation of the z tables can change without touching a backend. +"""The reference backend: its lowering, its marches and the refusals (SEP 52). + +One :class:`NumpyRefBackend` steps one problem in plain NumPy. It builds the +workspace that holds the state and does every state-sized operation +(:class:`~solprop.backends.numpy_ref.workspace.NumpyWorkspace`), the engines a march +asks of it (:class:`~solprop.backends.numpy_ref.engines.NumpyRungeKutta`, +:class:`~solprop.backends.numpy_ref.multistep.HostHistory`, +:class:`~solprop.backends.low_storage.HostLowStorage`) and the run's march, and keeps +``prepare``, the metadata, the memory ledger, the timing probe and ``close``. The step +control follows ``docs/dev/stepper.md`` section 3 exactly: the controller's +*proposal* is its state, the executed step's own norm decides acceptance and is what +the history records, and the equivalent norm of the proposal is what the controller +and a rejection see. """ -import collections -import dataclasses -import functools import logging -import math -from collections.abc import Callable, Iterator, Mapping, Sequence -from dataclasses import dataclass +from collections.abc import Mapping, Sequence +from typing import Literal import numpy as np -from jaxtyping import Bool, Complex, Float, Inexact, Num +from jaxtyping import Complex -from solprop._helpers import PLAIN -from solprop.backends import tdse_source -from solprop.backends.exponential import refuse_carrier_frame, refuse_formulation +from solprop.backends.exponential import ( + CarrierReference, + refuse_carrier_frame, + refuse_formulation, +) from solprop.backends.host.driver import HostDriver from solprop.backends.host.low_storage import HostLowStorageMarch -from solprop.backends.memory import adams_memory, reference_base_memory -from solprop.backends.node_chunk import ( - NodeChunkPlan, - general_planned_chunk, - plan_node_chunk, -) -from solprop.backends.numpy_ref import passes -from solprop.backends.numpy_ref.envelope_plasma import ( - envelope_populations, - envelope_sources, +from solprop.backends.host.runge_kutta import RungeKuttaMarch +from solprop.backends.low_storage import HostLowStorage +from solprop.backends.numpy_ref.engines import NumpyRungeKutta +from solprop.backends.numpy_ref.workspace import ( + BlockResidual, + NumpyWorkspace, + SourceTables, ) -from solprop.backends.numpy_ref.general_modal import ( - GeneralMaps, - general_memory, - general_source, -) -from solprop.backends.populations import axis_refusal, population_statistics +from solprop.backends.records import adams_policy, runge_kutta_policy from solprop.backends.session import ExecutionOptions -from solprop.backends.spatial import ( - FarFieldTables, - collect_spatial, - radial_absorber_matrix, - slab_columns, - slab_rows, - slab_synthesis, -) -from solprop.constants import EPS0, C -from solprop.exceptions import BackendError, ResponseBudgetError -from solprop.fourier import GridKind +from solprop.exceptions import BackendError from solprop.grid import TimeGrid from solprop.modes.protocol import Mode -from solprop.noise import NoiseRealisation -from solprop.output.capability import ( - declared_capability, - refusal_for, - withheld_accessors, -) -from solprop.output.records import SavedPlane from solprop.profiles import ZProfile -from solprop.stats import ( - _POYNTING_STATISTICS, - CATALOGUE, - METRIC_WEIGHTED_STATISTICS, - ON_AXIS_PLASMA_STATISTICS, - PLASMA_INTEGRATION_STATISTICS, - WEIGHT_DEPENDENT_STATISTICS, - StatsSpec, - _poynting_statistics, - analytic_field, - collect, - weight_refusal_for, -) from solprop.stepper.low_storage import LowStorageRungeKutta from solprop.stepper.multistep import Multistep -from solprop.translate.coupled import ( - CoupledFlowFactors, - coupled_flow_factors, - metric_at, -) -from solprop.translate.general import ( - node_delayed_maps, - node_kerr_form, - node_kerr_tensor, -) -from solprop.translate.linop import power_weight_at -from solprop.translate.modal import QUADRATURE_ALARM, warn_quadrature -from solprop.translate.plasma_source import _BENCHMARK_GATED from solprop.translate.problem import ( MAX_N_POL, PropagationProblem, @@ -112,18 +57,11 @@ GeneralRoute, ModalRoute, SpatialRoute, - flux_of, route_name, tdse_descriptor, - tdse_of, ) from solprop.translate.run_request import RunRequest -from solprop.translate.spatial import separable_values -from solprop.translate.stage import StageScalars, combine -from solprop.translate.tdse import AtomicCallLedger, TDSEBinding, TDSEPurpose -from solprop.translate.tdse_source import ( - TDSE_UNAVAILABLE_STATISTICS, -) +from solprop.translate.tdse import TDSEBinding __all__ = ["BlockResidual", "NumpyRefBackend", "SourceTables"] @@ -214,7 +152,7 @@ class NumpyRefBackend(HostDriver[Complex[np.ndarray, "n_modes n_pol n_omega"]]): name = "numpy_ref" # 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 + helpers = NumpyWorkspace.helpers # The reference forms `exp(+dPhi)` and `exp(-dPhi)` afresh at every stage, so # keeping the six distinct exponents of a step is worth its memory here where it is # not on a backend that takes both signs from one transcendental. @@ -238,84 +176,51 @@ def __init__( raise BackendError( "TDSE problems require an explicit host response binding" ) - self._tdse_binding = tdse_binding - self._tdse_last_purpose: TDSEPurpose | None = None - self._tdse_last_z: float | None = None - self._tdse_last_projection: dict[str, object] | None = None super().__init__( problem, request, grid=grid, modes=modes, profiles=profiles, options=options ) - self._statistics_power_weight = np.empty( - problem.shape if problem.transform.geometry is None else (0,) - ) - # Formed once, so a geometry the far-field statistics refuse is refused here, - # before any step (SEP 23 section 6). - self._far_field = FarFieldTables(problem, request.observation.stats) - self._gated_plasma = _BENCHMARK_GATED.get() - self._last_plasma: ( - tuple[np.ndarray, np.ndarray, np.ndarray | None, np.ndarray | None] | None - ) = None - self._kind: GridKind = problem.grid_kind - self._tables = SourceTables.of(problem) - self._carrier = _harmonic_carrier(problem) - self._embedded = _embedded_projection(problem) - self._general = _general_maps(problem, self._chunk_plan) - self._general_responds = self._general is not None and ( - bool(np.any(self._general.tensor)) or self._general.dispersive is not None - ) - self._flow = _coupled_flow_maps(problem) - self._block_residual: BlockResidual | None = None - self._flow_cache: ( - tuple[ - tuple[int, float], - dict[float, tuple[np.ndarray | None, np.ndarray | None]], - ] - | None - ) = None - self._last_projected: Num[np.ndarray, "n_modes n_pol n_to"] | None = None - self._last_coarse: Num[np.ndarray, "n_modes n_pol n_to"] | None = None - self._last_bundle: StageScalars | None = None - self._last_envelope: ( - tuple[np.ndarray, np.ndarray, np.ndarray | None, np.ndarray | None] | None - ) = None - self._raman_rates: tuple[float, ...] | None = None - self._raman_densities: tuple[float, ...] | None = None - self._raman_kernel: Complex[np.ndarray, "... n_omega_doubled"] | None = None - self._raman_transforms = 0 - self._alarm = math.nan - self._alarm_reported = False - # ADR-025's in-stage scheme is a second term on every stage rather than a - # factor on the accepted state, so a problem that has no response at all still - # has a derivative when it is active. - self._spatial_absorber = radial_absorber_matrix( - problem.transform, problem.grids.pad_scale - ) - self._in_stage_absorber = bool(self._spatial_absorber.size) or ( - problem.responses.temporal_absorber_fine is not None - and problem.responses.absorber_scheme == "nonlinear" - ) - geometry = problem.transform.geometry - if geometry is not None and geometry.kind in ("free", "slab"): - self._in_stage_absorber |= bool(np.any(geometry.absorber_rate)) - integrator = self._stepper.integrator - self._adams = None + self._workspace = NumpyWorkspace( + problem, + request, + chunk_plan=self._chunk_plan, + propagator_mode=self._propagator_mode, + grid=grid, + modes=modes, + profiles=profiles, + tdse_binding=tdse_binding, + name=self.name, + ) + stepper = self._stepper + self._runge_kutta_engine = self._runge_kutta(self._workspace) + integrator = stepper.integrator if isinstance(integrator, Multistep): - # The march's engine reads this package's passes, so it is imported when - # a run asks for it rather than with the package. - from solprop.backends.host.adams import HostAdamsMarch # noqa: PLC0415 - - self._adams = HostAdamsMarch(self, integrator) + self._use_adams(integrator) elif isinstance(integrator, LowStorageRungeKutta): # The host engine is the oracle (SEP 24 section 6.5). - self._low_storage = HostLowStorageMarch(self, integrator) - self._adams_held: ( - tuple[float, float, StageScalars, Complex[np.ndarray, ...]] | None - ) = None - # The lab-frame source's unit "propagator": one element broadcast to the state's - # shape, so it holds no volume beside the state. - self._lab_frame = np.broadcast_to( - np.ones((), dtype=np.complex128), problem.shape - ) + schedule = stepper.schedule + assert schedule is not None # the translation refused it without one + engine = HostLowStorage( + self._workspace, integrator, schedule, self._propagator_mode + ) + self._low_storage = HostLowStorageMarch( + engine, + integrator, + self._hooks, + schedule=schedule, + proposal=stepper.dz_init, + lag=stepper.controller.lag, + name=self.name, + ) + self._march = self._low_storage + else: + self._march = RungeKuttaMarch( + self._runge_kutta_engine, + runge_kutta_policy(problem, stepper), + self._hooks, + schedule=stepper.schedule, + proposal=stepper.dz_init, + name=self.name, + ) if logger.isEnabledFor(logging.DEBUG): logger.debug( "numpy_ref: %s grid, shape %s, %d Phi intervals, %s propagators, " @@ -324,522 +229,77 @@ def __init__( problem.shape, problem.linear.n_intervals, self._propagator_mode, - "replayed" if self._stepper.schedule is not None else "adaptive", - ) - - def _envelope_sources( - self, field_t: Complex[np.ndarray, "n_nodes n_pol n_to"], bundle: StageScalars - ) -> tuple[ - Complex[np.ndarray, "n_nodes n_pol n_to"], - Complex[np.ndarray, "n_nodes n_pol n_to"], - ]: - """Return the envelope-grid plasma's windowed drive and loss at some nodes. - - - ``field_t``: the field at the nodes, V/m. - """ - envelope = self._problem.responses.envelope_plasma - assert envelope is not None - return envelope_sources( - field_t, - envelope, - bundle, - self._problem.grids.dt_fine, - self._tables.t_window, - ) - - def _envelope_populations( - self, - nodes: Complex[np.ndarray, "n_nodes n_pol n_to"], - initials: tuple[float, ...], - ) -> tuple[np.ndarray, np.ndarray]: - """Return each envelope channel's final fraction and peak rate at the nodes. - - - ``nodes``: the physical envelope at the nodes, V/m. - """ - envelope = self._problem.responses.envelope_plasma - assert envelope is not None - return envelope_populations( - nodes, envelope, initials, self._problem.grids.dt_fine - ) - - def _error_norm( - self, - error: Complex[np.ndarray, "n_modes n_pol n_omega"], - state: Complex[np.ndarray, "n_modes n_pol n_omega"], - advanced: Complex[np.ndarray, "n_modes n_pol n_omega"], - ) -> float: - """Return the controller's scaled norm of a trial step's embedded difference.""" - return passes.error_norm( - error, - state, - advanced, - self._problem.grids.norm_mask, - self._stepper.controller, - ) - - def stats(self, spec: StatsSpec) -> dict[str, np.ndarray]: - """Collect the requested statistics at the current position. - - The statistics of the saved field go to :func:`solprop.stats.collect`; there is - exactly one definition of each in the package and that is it. The statistics - :class:`solprop.stats.StatDefinition` marks ``backend`` are of quantities a - saved plane does not carry -- the electron density, the peak ionisation rate, - the on-axis intensity, the quadrature error -- and are formed here from the - backend's own buffers. - - Parameters - ---------- - spec : solprop.stats.StatsSpec - Which statistics and which windows. - - Returns - ------- - dict - Small host arrays keyed by statistic name. - """ - state = self._require_state() - grid = self._require_grid() - if self._tdse_binding is not None: - unavailable = TDSE_UNAVAILABLE_STATISTICS.intersection(spec.names) - if unavailable: - raise BackendError( - f"TDSE does not define legacy statistics {sorted(unavailable)}" - ) - # Before the spatial branch: a spatial run asked for a - # general name would otherwise reach `collect_spatial` and be answered from a - # geometry that carries no certified metric at all. - _refuse_inadmissible(self._problem, spec) - if self._problem.transform.geometry is not None: - response_names = ( - {"electron_density", "peak_ionisation_rate", "quadrature_error"} - | set(PLASMA_INTEGRATION_STATISTICS) - | {name for name in CATALOGUE if name.startswith("species_")} - ) - spatial_spec = dataclasses.replace( - spec, - names=tuple(name for name in spec.names if name not in response_names), - periodic=(), - ) - tables = self._far_field.for_spec(spatial_spec) - spatial = collect_spatial( - spatial_spec, - grid, - self._problem.transform, - state, - z=self._z, - flux=flux_of(self._problem.route), - profiles=self._profiles, - tables=tables, - operator=self._problem.linear.separable, - node_chunk=self.node_chunk, - ) - return { - name: np.array(spatial[name]) for name in spatial_spec.names - } | self._backend_statistics( - tuple(name for name in spec.names if name in response_names), state - ) - # The weight is a Chebyshev evaluation per column, which is the whole of what - # the Poynting weighting adds to a statistics call on a CPU (0.053 ms of - # 0.056 ms on the reduced-M2 case), so a spec that asks for none of the - # Poynting statistics -- a periodic plasma subset, say -- never - # evaluates it. - needed = bool(set(spec.names) & WEIGHT_DEPENDENT_STATISTICS) - if needed: - np.copyto( - self._statistics_power_weight, power_weight_at(self._problem, self._z) - ) - weight_refusal = weight_refusal_for(spec.names, self._statistics_power_weight) - if weight_refusal is not None: - raise BackendError(weight_refusal) - weighted = needed and not np.all(self._statistics_power_weight == 1.0) - power_names = tuple( - name for name in spec.names if weighted and name in _POYNTING_STATISTICS - ) - axis = None - if "peak_intensity" in power_names: - if self._modes is None: - msg = "the peak on-axis intensity needs the mode set" - raise BackendError(msg) - axis = self._on_axis_synthesis(self._modes) - power_values = ( - _poynting_statistics(spec, grid, state, self._statistics_power_weight, axis) - if weighted - else {} - ) - owned = tuple( - name - for name in spec.names - if CATALOGUE[name].backend and name not in power_names - ) - delegated = dataclasses.replace( - spec, - names=tuple( - name - for name in spec.names - if name not in owned and name not in power_names - ), - periodic=tuple( - name - for name in spec.periodic - if name not in owned and name not in power_names - ), - ) - # The basis metric at this plane: the - # statistics of `METRIC_WEIGHTED_STATISTICS` are functionals of the physical - # same-frequency flux `a.H W a`, and on a declared change of basis W is not - # the identity. `metric_at` returns None for an identity metric, which is - # the statistics' own bitwise-unchanged path, so an ordinary run pays - # nothing. - metric = ( - metric_at(self._problem.linear.modal_metric, self._z) - if set(delegated.names) & METRIC_WEIGHTED_STATISTICS - else None - ) - collected = collect( - delegated, - grid, - SavedPlane(z=self._z, field=state), - modes=self._modes, - profiles=self._profiles, - metric=metric, - ) - values = {name: np.array(collected[name]) for name in delegated.names} - values.update({name: np.array(power_values[name]) for name in power_names}) - return values | self._backend_statistics(owned, state) - - def _backend_statistics( - self, - names: tuple[str, ...], - state: Complex[np.ndarray, "n_modes n_pol n_omega"], - ) -> dict[str, np.ndarray]: - """Share each fresh envelope population scan among the requested statistics. - - - ``state``: accepted state at this plane. - - Returns: requested values, with no retained field cache. - """ - population_names = ( - tuple( - name - for name in names - if name.startswith("species_") - or name in ("electron_density", "peak_ionisation_rate") - ) - if self._problem.responses.envelope_plasma is not None - else () - ) - integration_names = tuple( - name for name in names if name in PLASMA_INTEGRATION_STATISTICS - ) - axis_names = tuple(name for name in names if name in ON_AXIS_PLASMA_STATISTICS) - if axis_names and not population_names: - # The species statistics are the node scan of `_species_statistics` on - # every route, so sharing one scan with the on-axis statistics changes - # none of their values and lets a node on the axis supply its row. - population_names = tuple( - name for name in names if name.startswith("species_") - ) - # Node scans of this observation only: a rule with a node on the axis hands - # its row to the on-axis statistics, and nothing outlives the call, so no - # stale stage or rejected step can be reused. - scans: list[tuple[np.ndarray, np.ndarray]] = [] - result = { - name: self._backend_stat(name, state) - for name in names - if name not in population_names - and name not in integration_names - and name not in axis_names - } - if integration_names: - diagnostics = self._integration_diagnostics(state) - result.update( - {name: np.array(diagnostics[name]) for name in integration_names} - ) - if population_names: - species = self._species_statistics(state, scans) - result.update({name: np.array(species[name]) for name in population_names}) - if axis_names: - axis = self._axis_statistics(state, scans[0] if scans else None) - result.update({name: np.array(axis[name]) for name in axis_names}) - return result - - def _backend_stat( - self, - name: str, - state: Complex[np.ndarray, "n_modes n_pol n_omega"], - ) -> np.ndarray: - """Compute one backend-owned statistic.""" - if name == "quadrature_error": - return np.full((), self._alarm) - if name == "peak_intensity": - return np.array(self._peak_intensity(state)) - if ( - name.startswith("species_") - or self._problem.flags.n_channels > 1 - or self._problem.responses.envelope_plasma is not None - ): - return np.array(self._species_statistics(state)[name]) - return np.array(self._ionisation(state)[0 if name == "electron_density" else 1]) - - def _species_statistics( - self, - field: Complex[np.ndarray, "n_modes n_pol n_omega"], - scans: list[tuple[np.ndarray, np.ndarray]] | None = None, - ) -> dict[str, np.ndarray]: - """Evaluate independent populations on the actual nonlinear nodes. - - - ``scans``: where to leave this observation's channel fractions and peak rates - at every node, for the on-axis statistics to reuse. - - Returns: the five species statistics and the two total plasma statistics. - """ - responses = self._problem.responses - transform, grids = self._problem.transform, self._problem.grids - channels = responses.population_channels - if channels: - if transform.geometry is not None and transform.geometry.kind == "free": - nx, ny = transform.geometry.shape - physical = np.fft.ifft2( - field.reshape(ny, nx, *field.shape[1:]), axes=(0, 1) - ).reshape(field.shape) - nodes = passes.to_time( - physical * grids.pad_scale, - grids.crop_index, - grids.n_to, - kind=self._kind, - ) - elif transform.geometry is not None and transform.geometry.kind == "slab": - # The slab synthesis carries the pad scale already. - nodes = passes.to_time( - slab_synthesis(transform, field), - grids.crop_index, - grids.n_to, - kind=self._kind, - ) - else: - nodes = self._nodes_at(field) - if responses.envelope_plasma is not None: - fractions, peaks = self._envelope_populations( - nodes, tuple(float(c.preionisation(self._z)) for c in channels) - ) - if scans is not None: - scans.append((fractions, peaks)) - return population_statistics(self._problem, self._z, fractions, peaks) - rates, population = passes.plasma_channel_fractions( - nodes, - responses.plasma_channels, - tuple(float(c.preionisation(self._z)) for c in channels), - grids.dt_fine, - responses.plasma_integral, - ) - if scans is not None: - scans.append((population[:, :, -1], rates.max(axis=-1))) - return population_statistics( - self._problem, self._z, population[:, :, -1], rates.max(axis=-1) - ) - empty = np.zeros((0, transform.n_nodes)) - return population_statistics(self._problem, self._z, empty, empty) - - def _integration_diagnostics( - self, field: Complex[np.ndarray, "n_modes n_pol n_omega"] - ) -> dict[str, np.ndarray]: - """Return the plasma column's integration diagnostics at this plane (SEP 18). - - The undershoot of the exposure increments, the relative work defect of the - loss current and the boundary level of the free-current integrand, over every - node and field plasma channel - (:data:`solprop.stats.PLASMA_INTEGRATION_STATISTICS`). - - - Returns: the three statistics, each zero-dimensional and dimensionless. - """ - responses = self._problem.responses - channels = responses.plasma_channels - if not channels: - msg = ( - "the plasma integration diagnostics read the field-grid plasma " - "column, and this problem carries none" - ) - raise BackendError(msg) - initial = tuple(float(channel.preionisation(self._z)) for channel in channels) - parts = np.zeros(6) - for nodes in self._plasma_nodes(field): - parts = np.maximum( - parts, - passes.plasma_integration_diagnostics( - nodes, - channels, - initial, - self._problem.grids.dt_fine, - responses.plasma_integral, - ), - ) - undershoot, defect, boundary = passes.plasma_integration_statistics(parts) - return { - "plasma_undershoot": np.asarray(undershoot), - "plasma_work_defect": np.asarray(defect), - "plasma_boundary_level": np.asarray(boundary), - } - - def _plasma_nodes( - self, field: Complex[np.ndarray, "n_modes n_pol n_omega"] - ) -> Iterator[Float[np.ndarray, "n_nodes_chunk n_pol n_to"]]: - """Yield the real node fields the plasma column is evaluated on, by chunk. - - The same synthesis as :meth:`_ionisation`: the physical nodes of a separable - geometry, chunk by chunk, or the modal quadrature nodes at once. - - - Yields: node fields on the fine time grid, V/m. - """ - grids = self._problem.grids - if self._problem.linear.separable is None: - yield self._nodes_at(field) - return - geometry = self._problem.transform.geometry - assert geometry is not None - nx, ny = geometry.shape - physical = ( - slab_synthesis(self._problem.transform, field) / grids.pad_scale - if geometry.kind == "slab" - else np.fft.ifft2( - field.reshape(ny, nx, *field.shape[1:]), axes=(0, 1) - ).reshape(field.shape) - ) - chunk = self.node_chunk - for first in range(0, len(physical), chunk): - yield passes.to_time( - physical[first : first + chunk] * grids.pad_scale, - grids.crop_index, - grids.n_to, - kind=self._kind, + "replayed" if stepper.schedule is not None else "adaptive", ) - def _ionisation( - self, - field: Complex[np.ndarray, "n_modes n_pol n_omega"], - ) -> tuple[np.ndarray, np.ndarray]: - """Return the electron density and the peak ionisation rate at this plane. - - Both are read at the **node of largest ionised fraction**, which is where the - plasma the run carries is densest and the only node either number can honestly - describe; for a mode-averaged run that is the one node. The axis is not a - quadrature node at all and is not where the polarisation was evaluated, so the - field is not re-synthesised there. - - The electron density is ``density(z)`` times the fraction at the **end** of the - window: what the pulse leaves behind, not what it reaches in passing. - - - Returns: the electron density in m^-3 and the peak rate in s^-1, both - zero-dimensional. - """ - responses = self._problem.responses - plasma = responses.plasma_coefficients - if plasma is None: - msg = ( - "the electron density and the peak ionisation rate need a compiled " - "plasma response, and this problem declares none" - ) - raise BackendError(msg) - if self._problem.linear.separable is not None: - geometry = self._problem.transform.geometry - assert geometry is not None - nx, ny = geometry.shape - physical = ( - # The slab synthesis carries the pad scale, multiplied back below. - slab_synthesis(self._problem.transform, field) - / self._problem.grids.pad_scale - if geometry.kind == "slab" - else np.fft.ifft2( - field.reshape(ny, nx, *field.shape[1:]), axes=(0, 1) - ).reshape(field.shape) - ) - largest, peak = -1.0, 0.0 - grids = self._problem.grids - chunk = self.node_chunk - for first in range(0, len(physical), chunk): - nodes = passes.to_time( - physical[first : first + chunk] * grids.pad_scale, - grids.crop_index, - grids.n_to, - kind=self._kind, - ) - rate = passes.ionisation_rate(nodes, plasma.rate) - fraction, _ = passes.plasma_scan( - nodes, - rate, - plasma, - preionisation=float(plasma.preionisation(self._z)), - dt=grids.dt_fine, - integral=responses.plasma_integral, - ) - densest = int(np.argmax(fraction[:, -1])) - if fraction[densest, -1] > largest: - largest = float(fraction[densest, -1]) - peak = float(np.max(rate[densest])) - return np.asarray(float(plasma.density(self._z)) * largest), np.asarray( - peak - ) - nodes = self._nodes_at(field) - rate = passes.ionisation_rate(nodes, plasma.rate) - fraction, _ = passes.plasma_scan( - nodes, - rate, - plasma, - preionisation=float(plasma.preionisation(self._z)), - dt=self._problem.grids.dt_fine, - integral=responses.plasma_integral, - ) - densest = int(np.argmax(fraction[:, -1])) - density = float(plasma.density(self._z)) * float(fraction[densest, -1]) - return np.asarray(density), np.asarray(float(np.max(rate[densest]))) + def _runge_kutta(self, workspace: NumpyWorkspace) -> NumpyRungeKutta: + """Return the Runge-Kutta engine over the workspace; a test may script one.""" + return NumpyRungeKutta(workspace, self._stepper.tableau) - def _peak_intensity( + def _use_adams( self, - field: Complex[np.ndarray, "n_modes n_pol n_omega"], - ) -> np.ndarray: - """Return the largest intensity on the axis of the waveguide, in W/m^2. - - ``eps0 c/2 max_t sum_c |E_{a,c}(0, t)|^2`` with the analytic field synthesised - at ``r = 0`` from the modes' own profiles, both Cartesian components. The axis - is not a quadrature node, so the mode fields are evaluated there rather than - interpolated, and both components are taken so that the answer does not depend - on which one the transform resolves or the state carries. One definition for - every run: a mode-averaged run synthesises its one mode the same way, which is - ``P / A_eff`` for a top-hat profile and the true on-axis value for a real one - -- 1.77 times the average for HE_11, so ``P / A_eff`` would under-report it by - that factor. The on-axis matrix is built once and rescaled with the taper - (:meth:`_on_axis_synthesis`), which is what makes this statistic cheap enough - for the between-planes channel. - """ - if self._modes is None: - msg = ( - "the peak on-axis intensity needs the mode set, which the kernel " - "contract does not carry; construct the backend with " - "NumpyRefBackend(problem, request, modes=modes)" - ) - raise BackendError(msg) - analytic = analytic_field(self._require_grid(), field) - columns = np.tensordot( - self._on_axis_synthesis(self._modes), analytic, axes=([1], [0]) - ) - power = np.sum(np.abs(columns) ** 2, axis=tuple(range(columns.ndim - 1))) - return np.asarray(0.5 * EPS0 * C * float(np.max(power))) - - def _nodes_at( - self, - field: Complex[np.ndarray, "n_modes n_pol n_omega"], - ) -> Num[np.ndarray, "n_nodes n_components n_to"]: - """Return the physical field at every quadrature node on the fine time grid. - - - Returns: the field in V/m, shape ``(n_nodes, n_components, n_to)``. Here - ``n_components = transform.n_pol * n_pol`` counts physical components, - independently of the state's polarisation axis. - """ - grids, transform = self._problem.grids, self._problem.transform - taper = ( - 1.0 - if transform.taper_scale is None - else float(transform.taper_scale(self._z)) - ) - modal_t = passes.to_time(field, grids.crop_index, grids.n_to, kind=self._kind) - return passes.synthesise(modal_t, transform.synthesis, taper, transform.n_pol) + method: Multistep, + compensation: Literal["transported", "untransported"] = "transported", + ) -> None: + """Build the Adams engine and march, and step the run with them. + + - ``compensation``: how a varying operator's linear compensation is integrated + (SEP 16 Q8): ``"transported"``, the delivered treatment, or + ``"untransported"``, kept as a test witness only. + """ + # The engine reads this package's passes, so it is imported when a run asks + # for it rather than with the package. + from solprop.backends.host.adams import HostAdamsMarch # noqa: PLC0415 + from solprop.backends.numpy_ref.multistep import ( # noqa: PLC0415 + AdamsKernels, + ExponentialKernels, + HostHistory, + ) + + stepper = self._stepper + interpolate = bool(stepper.interpolate_planes) + engine = HostHistory( + self._workspace, + method, + AdamsKernels(helpers=self.helpers), + # SEP 16's exponential formulation keeps untransported samples in the same + # store and shares everything else: the lifecycle, the controller, the + # ledger. + ExponentialKernels(helpers=self.helpers) + if method.formulation == "exponential" + else None, + compensation, + interpolate=interpolate, + ) + carrier = engine.carrier + # Every number the controller and the landings read, from one record (SEP 39 + # section 4.2). An in-stage temporal collar's largest rate, the one stiff + # term the exponential history integrates, bounds each order's stable step. + policy = adams_policy( + self._problem, + stepper, + method, + carrier=isinstance(carrier, CarrierReference) and carrier.active, + ) + self._adams = HostAdamsMarch( + engine, + method, + self._hooks, + policy=policy, + field=self._workspace.committed, + schedule=stepper.schedule, + interpolate=interpolate, + shape=self._problem.shape, + proposal=stepper.dz_init, + lag=stepper.controller.lag, + name=self.name, + ) + self._march = self._adams + + @property + def workspace(self) -> NumpyWorkspace: # numpydoc ignore=RT01 + """The workspace: the state and every state-sized operation on it.""" + return self._workspace def metadata(self) -> dict[str, object]: """Return execution facts and cumulative logical and atomic call ledgers. @@ -851,18 +311,7 @@ def metadata(self) -> dict[str, object]: labelled and is never reported as an accepted-field diagnostic. """ record = super().metadata() - if self._gated_plasma: - record["_benchmark_plasma_source"] = "gated_nonresumable" - record["plasma_source"] = {"form": "gated_benchmark", "resumable": False} - if self._tdse_binding is not None: - record["atomic_calls"] = dataclasses.asdict(self._tdse_binding.ledger) - record["tdse_execution"] = dict(self._tdse_binding.metadata()) - record["tdse_last_evaluation"] = { - "purpose": self._tdse_last_purpose, - "z": self._tdse_last_z, - "projection": self._tdse_last_projection, - } - record["tdse_source"] = tdse_source.source_record(self._problem) + record.update(self._workspace.metadata()) return record def restore_call_ledgers( @@ -884,1446 +333,30 @@ def restore_call_ledgers( """ super().restore_call_ledgers(logical) if atomic: - if self._tdse_binding is None: - raise BackendError("atomic call ledger requires a TDSE binding") - self._tdse_binding.restore_ledger(AtomicCallLedger.from_record(atomic)) + self._workspace.restore_atomic_ledger(atomic) def memory_ledger(self) -> dict[str, int]: """Return the size of every buffer the backend works in, in bytes. - The reference backend allocates its stage and transform buffers per pass instead - of keeping a preallocated pool, so this reports what one step has resident at - its peak -- which is what the optimised backends hold for the whole run, and - what the budget of ``docs/dev/architecture.md`` section 8 is measured against. - Every buffer is named even when it is empty. - - The space-domain entries are sized by - :attr:`~solprop.backends.host.driver.HostDriver.node_chunk` and not by the - node count, which is the whole point of the chunk loop (``architecture.md`` - section 13): holding ``(n_to, n_pol n_nodes)`` for every node at once would be - 210 MB against 45 MB on the comb-to-continuum target. + The workspace's (:meth:`NumpyWorkspace.memory_ledger`): what one step has + resident at its peak, every buffer named even when it is empty. Returns ------- dict Buffer name to bytes. """ - problem = self._problem - distinct = int(np.unique(np.append(self._stepper.tableau.nodes, 1.0)).size) - general: dict[str, int] = dict.fromkeys(_GENERAL_LEDGER_ROWS, 0) - if self._general is not None: - # The route exists exactly when the tables do (`_general_maps`). - tables = problem.transform.modal_tables - assert tables is not None - general = general_memory(self._general, tables, problem.grids.n_to) - ledger = adams_memory(problem, self._stepper) | { - # The rows' one definition, in `solprop.backends.memory`. - **reference_base_memory( - problem, - self._stepper, - tabulating=self._propagator_mode == "tabulate", - embedded=self._embedded is not None, - noise=self._noise is not None, - statistics_weight=self._statistics_power_weight.nbytes, - spatial_absorber=self._spatial_absorber.nbytes, - node_chunk=self.node_chunk, - ), - # The coupled flow's own resident arrays: the frozen block of every - # section with its Schur factors, the residual's terms, and the one - # forward/inverse action pair held for the section and length last seen. - # All of them are on the active bins alone. - "coupled_flow_factors": 0 - if self._flow is None - else self._flow.vectors.nbytes - + self._flow.triangular.nbytes - + self._flow.frozen.nbytes, - "coupled_flow_residual_terms": 0 - if self._flow is None or self._flow.residual_terms is None - else self._flow.residual_terms.nbytes, - "coupled_flow_actions": 0 - if self._flow is None - else 2 * distinct * self._flow.frozen[0].nbytes, - # The general modal route's buffers are its own: the two execution maps, - # the per-node tensor and the record's resident E/H reference are - # whole-problem allocations no chunk shrinks, and its chunk buffers are - # three components wide and complex on a grid where the legacy ones are - # one or two and real. Every row is zero on every - # other route. - **general, - # A low-storage march's state at its last field-free plane (SEP 22, Q14), - # held from the first such plane; the admission charges it beforehand. - **( - {} - if self._tdse_binding is None - else { - f"tdse_{name}": size - for name, size in self._tdse_binding.memory_ledger().items() - } - ), - } - if self._gated_plasma: - for name in ledger: - if ( - name.startswith("held_current_") - and name != "held_current_derivative" - ): - ledger[name] = 0 - return ledger + return self._workspace.memory_ledger() def close(self) -> None: """Release the buffers. Idempotent.""" - self._state = None - self._noise = None - self._raman_kernel = None - self._last_plasma = None - self._spatial_absorber = np.empty((0, 0)) - self._raman_rates = None - self._raman_densities = None - self._flow_cache = None - self._statistics_power_weight = np.empty(0) - self._adams_held = None + self._workspace.close() if self._low_storage is not None: - self._low_storage.close() + engine = self._low_storage.engine + assert isinstance(engine, HostLowStorage) + engine.close() self._closed = True - def set_initial( - self, - field: Complex[np.ndarray, "n_modes n_pol n_omega"], - noise: NoiseRealisation | None, - *, - z: float = 0.0, - resume: bool = False, - ) -> None: - """Load a state; an Adams march restarts its history from it. - - Parameters - ---------- - field : numpy.ndarray - The state, shape ``(n_modes, n_pol, n_omega)``. - noise : solprop.noise.NoiseRealisation or None - The realisation to carry, or ``None`` for the problem's own. - z : float, optional - The position the state belongs to, m; positive for a resume, which starts - the history afresh unless - :meth:`~solprop.backends.host.driver.HostDriver.restore_march` then - continues it. - resume : bool, optional - Whether `field` came back from a saved plane, and so never takes the - ``input`` draw. - """ - super().set_initial(field, noise, z=z, resume=resume) - # The entrance plane's quadrature_error is read before any march: the alarm - # of a previous run on this backend is not its (SEP 22 section 4.7). - self._alarm = math.nan - self._alarm_reported = False - if self._adams is not None: - self._adams.reset() - - def _march_to(self, target: float) -> None: - """Step to `target` with the Adams method when one is set, else Runge-Kutta. - - - ``target``: position to reach, m. - """ - if self._adams is None: - super()._march_to(target) - else: - self._adams.march_to(target) - - def _reserve_source_calls(self, count: int) -> None: - """Reserve every atomic chunk required by one complete Adams trial.""" - binding = self._tdse_binding - if binding is None: - return - try: - binding.reserve(count) - except ResponseBudgetError as error: - raise ResponseBudgetError( - "the TDSE atomic-call budget cannot reserve the next trial " - f"at z = {self._z:.6g} m ({error.calls} charged); " - "the run stops at its last accepted step, unfinished", - z=self._z, - field=self._adams_state().copy(), - calls=error.calls, - ) from None - - def _release_source_calls(self) -> None: - """Release unused atomic reservations after a completed or failed trial.""" - if self._tdse_binding is not None: - self._tdse_binding.release_reservation() - - def _adams_source( - self, - lab: Complex[np.ndarray, "n_modes n_pol n_omega"], - anchor: float, - position: float, - *, - purpose: TDSEPurpose = "predictor", - ) -> tuple[ - Complex[np.ndarray, "n_modes n_pol n_omega"], - Complex[np.ndarray, "n_modes n_pol n_omega"], - ]: - """Evaluate the source once through the reference passes. - - - ``anchor``, ``position``: the step's anchor and the evaluation position, m. - - ``purpose``: Atomic-call accounting label; ignored when no atomic service is - bound. - - Returns: ``U(anchor, position) N(lab, position)`` and ``U(position, anchor)``. - """ - held = self._adams_held - if held is not None and held[0] == anchor and held[1] == position: - bundle, propagator = held[2], held[3] - else: - bundle = self._stage_scalars(anchor, position) - propagator = np.exp(self._delta_phi(bundle)) - self._adams_held = None - noise = self._noise_at(bundle) - field_in = lab if noise is None else lab + noise - if self._tdse_binding is not None: - return ( - self._nonlinear(field_in, bundle, 1.0 / propagator, purpose=purpose), - propagator, - ) - return self._nonlinear(field_in, bundle, 1.0 / propagator), propagator - - def _dense_stages(self) -> list[np.ndarray]: - """Return the last trial's stage derivatives, in its anchor's frame. - - - Returns: one per tableau stage, in the canonical layout. - """ - return list(self._last_stages) - - def _adams_block(self, z: float, dz: float) -> object: - """Return the frozen block of the section a step from `z` is anchored in. - - - ``z``: where the step starts, m. - - ``dz``: the step, m. - - Returns: the step's - :class:`~solprop.backends.numpy_ref.multistep.CoupledBlock`, or ``None`` - without a coupled flow. - """ - from solprop.backends.numpy_ref.multistep import ( # noqa: PLC0415 - cycle - CoupledBlock, - ) - - flow = self._flow - if flow is None: - return None - bundle = self._stage_scalars(z, z + dz) - section = bundle.flow_section - assert section is not None - residual = None - if flow.residual_terms is not None: - if self._block_residual is None: - self._block_residual = BlockResidual(flow) - residual = functools.partial(self._block_residual, section) - return CoupledBlock( - active=flow.active, - vectors=flow.vectors[section], - triangular=flow.triangular[section], - section=section, - end_weights=bundle.flow_weights, - residual=residual, - ) - - def _adams_lab_source( - self, - lab: Complex[np.ndarray, "n_modes n_pol n_omega"], - position: float, - *, - purpose: TDSEPurpose = "predictor", - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Evaluate the source once through the reference passes, untransported. - - The same passes as :meth:`_adams_source`, with the stage's inverse propagator - replaced by ones: a multiplication by one is exact, so the sample is the - lab-frame source bit for bit, and every route's evaluation stays the one the - Runge-Kutta march uses. - - `lab` is taken as given: it is not masked to the active band, as - :meth:`set_initial` masks the state it loads. On a masked field the sample - equals the hoisted first stage at the same position bit for bit; a field with - content outside the band (an unmasked launch) is another input, whose source - differs by what that content makes (4.3e-13 of the peak on the optmat argon - capillary). The stage scalars at ``(position, position)`` do not depend on the - anchor last hoisted: a held anchor is reused only at its own position. - - - ``position``: the evaluation position, m. - - ``purpose``: Atomic-call accounting label; ignored when no atomic service is - bound. - """ - bundle = self._stage_scalars(position, position) - noise = self._noise_at(bundle) - field_in = lab if noise is None else lab + noise - if self._tdse_binding is not None: - return self._nonlinear(field_in, bundle, self._lab_frame, purpose=purpose) - return self._nonlinear(field_in, bundle, self._lab_frame) - - def _adams_propagator( - self, anchor: float, position: float - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Return ``U(position, anchor)``, held for the Adams step's source call. - - Only an Adams march reads it back (:meth:`_adams_source`), so only an Adams - run holds it: the low-storage march applies its flows at once, and a held one - would be a volume its ledger does not name. - - - ``anchor``, ``position``: the step's anchor and its end, m. - """ - bundle = self._stage_scalars(anchor, position) - propagator = np.exp(self._delta_phi(bundle)) - if self._adams is not None: - self._adams_held = (anchor, position, bundle, propagator) - return propagator - - def _trial_step( - self, z: float, dz: float - ) -> tuple[float, Complex[np.ndarray, "n_modes n_pol n_omega"]]: - """Take one interaction-picture Runge-Kutta step and score it. - - Every stage is evaluated. The tableau's first-same-as-last property would let - the last stage of one step serve as the first of the next, after rebasing it by - ``exp(dPhi)`` because the interaction picture is re-anchored every step; the - reference backend does not take that saving, so that no stage it uses depends on - the bookkeeping of the step before (``docs/dev/stepper.md`` section 10, trap - 10). A coupled flow would need the analogous certified forward action of its - own to reuse a stage, so the saving stays refused there too, and is **absent** - here rather than skipped by a flag. - - A problem carrying ``linear.coupled_flow`` multiplies each stage's scalar - propagator by the section's Schur matrix-function action. The two factors - commute -- the cumulative diagonal beside a coupled flow is required to be a - multiple of the identity (:func:`_refuse_flow_problem`) -- so their product is - the flow of the sum, exactly, and the shared scalar stays analytically - integrated in ``Phi``. - - A ``"frozen_residual"`` flow adds the **explicit residual** - ``R_s(z) = D(z) - D(z_s) + H(z) - H(z_s) - C(z)`` to each stage's lab-frame - source, before the interaction picture's own factors carry it back, so it is - integrated by the embedded Runge-Kutta pair exactly as the material response - is. Freezing is then a rearrangement of the original equation and not a - second-order approximation: whatever block the exponential carries, the - residual is the rest of the generator. - - - ``z``: position at the start of the step, m. - - ``dz``: length of the trial step, m, positive. - - Returns: the scaled error norm and the state at the end of the step. - """ - state = self._require_state() - self._hoist(z) - tableau = self._stepper.tableau - # The whole step and every stage, read together: each table once. - self._stage_bundles( - z, [z + dz, *(z + float(node) * dz for node in tableau.nodes)] - ) - exponents = self._exponents(z, dz) - step = self._stage_scalars(z, z + dz) - actions = self._flow_actions(step.flow_section, dz) - stages: list[Complex[np.ndarray, "n_modes n_pol n_omega"]] = [] - 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]), - ) - bundle = self._stage_scalars(z, z + fraction * dz) - exponent = exponents(fraction, bundle) - forward, inverse = actions(fraction) - lab = passes.stage_input( - self._channels(state, forward), - self._channels(combination, forward), - dz, - np.exp(exponent), - self._noise_at(bundle), - ) - back = np.exp(-exponent) - self._rk_source_evaluations += 1 - drive = self._nonlinear(lab, bundle, back) - residual = self._residual(lab, step.flow_section, bundle) - if residual is not None: - drive = drive + back * residual - stage = self._channels(drive, inverse) - stages.append(stage) - solution = passes.accumulate( - solution, stage, float(tableau.solution_weights[index]) - ) - error = passes.accumulate(error, stage, float(tableau.error_weights[index])) - # Kept for the continuous extension of an accepted step (SEP 14 phase 3). - self._last_stages = stages - propagator = np.exp(exponents(1.0, step)) - whole = actions(1.0)[0] - advanced = passes.accept_step( - self._channels(state, whole), - propagator, - dz, - self._channels(solution, whole), - ) - # The embedded difference is carried to the end of the step by the same - # exponential as the solution, so the norm scales the local error of the - # propagated state rather than of the interaction variable. - norm = self._error_norm( - propagator * (dz * self._channels(error, whole)), state, advanced - ) - return norm, advanced - - def _channels( - self, - values: Complex[np.ndarray, "n_modes n_pol n_omega"], - action: Complex[np.ndarray, "n_active_c n_modes_c_out n_modes_c_in"] | None, - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Mix the channel axis by one coupled-flow action, or return the values. - - - ``values``: any array of the state's layout. - - ``action``: the action on the active bins, or ``None`` for a problem with no - coupled flow, which is every route but the coherent wall. - """ - if self._flow is None or action is None: - return values - return _apply_flow(values, action, self._flow.active) - - def _residual( - self, - lab: Complex[np.ndarray, "n_modes n_pol n_omega"], - section: int, - bundle: StageScalars, - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"] | None: - """Return the explicit residual's lab-frame source term, or nothing. - - ``None`` for every problem but a ``"frozen_residual"`` coupled flow: the - constant section has an identically zero residual and is not - multiplied by one, so its arithmetic is bit for bit what it was. - - - Returns: ``R_s(z_1) u`` in the state's layout, or ``None``. - """ - flow = self._flow - if flow is None or flow.residual_terms is None: - return None - assert bundle.flow_weights is not None - return _residual_drive( - lab, - _residual_action(flow, section, bundle.flow_weights), - flow.active, - flow.residual_bins, - ) - - def _flow_actions( - self, section: int, dz: float - ) -> Callable[ - [float], - tuple[ - Complex[np.ndarray, "n_active_a n_modes_a_out n_modes_a_in"] | None, - Complex[np.ndarray, "n_active_b n_modes_b_out n_modes_b_in"] | None, - ], - ]: - """Return the memoised forward and inverse flow actions of one step. - - The generator is **frozen** across the step -- at the midpoint of the section - the step's anchor lies in -- so an action depends on the stage fraction only - through the length ``c_i h`` it covers, and the six distinct DOPRI5 fractions - need at most six pairs; the tableau uses the last one twice and the zero - fraction is the identity. The whole step's pair is checked against that - section's declared conditioning row, which bounds every shorter one because - ``exp(c dz (mu_max - mu_min))`` increases with ``c``. - - The pairs also survive **between** steps, for the one section and trial length - last seen: a fixed schedule and an accepted adaptive step both repeat their - ``dz``, and an action that depends on nothing but ``dz`` and a frozen generator - is then the same matrix. Exactly one pair of them is held, so what a step has - resident at its peak -- which is what :meth:`memory_ledger` reports -- is - unchanged, and a step that crosses into the next section rebuilds, which is a - cache invalidation at the section edge and is what makes the edge a kink of - the flow (``docs/dev/stepper.md`` section 2). The conditioning of a held - length was measured when it was built. - - - ``dz``: length of the trial step, m. - - Returns: ``fraction -> (U, U^-1)``, each ``None`` when no coupled flow is - carried. - """ - flow = self._flow - if flow is None: - return lambda fraction: (None, None) # noqa: ARG005 - held = self._flow_cache - key = (section, dz) - cache: dict[float, tuple[np.ndarray | None, np.ndarray | None]] = ( - held[1] if held is not None and held[0] == key else {} - ) - self._flow_cache = (key, cache) - - def action( - fraction: float, - ) -> tuple[np.ndarray | None, np.ndarray | None]: - """Return the pair at a stage fraction, computing it at most once. - - - ``fraction``: the tableau node ``c_i``, dimensionless, in ``[0, 1]``. - - Returns: the forward and inverse actions, or ``(None, None)`` at fraction - zero, where both are the identity. - """ - if fraction == 0.0: - return None, None - if fraction not in cache: - pair = _flow_action(flow, section, fraction * dz) - if fraction == 1.0: - _check_flow_conditioning(flow, section, pair, dz) - cache[fraction] = pair - return cache[fraction] - - return action - - def _apply_mask( - self, state: Complex[np.ndarray, "n_modes n_pol n_omega"] - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Zero the state outside the active band. - - - ``state``: the state in the canonical layout. - """ - return passes.apply_hard_mask(state, self._problem.grids.active_mask) - - def _begin_plane(self) -> None: - """Forget the last plane's quadrature alarm, so each plane reports its own.""" - self._alarm = math.nan - self._alarm_reported = False - - def _on_accepted_step(self) -> None: - """Score the quadrature alarm from what the last stage left behind.""" - self._update_alarm() - - def _record(self, z: float, dz: float, norm: float, accepted: bool) -> None: - """Record one attempt, and tell an atomic binding the trial's outcome. - - Every attempt of the Adams march opens one trial with its reservation - (:meth:`_reserve_source_calls`) and ends here, accepted or rejected, so an - archive can label a rejected trial's evaluations (SEP 20 section 5.8). A - replayed step is recorded after its reservation is released; it is still - the latest trial. Nothing about the step or its accounting changes. - - - ``z``: position at the end of the step, m. - - ``dz``: length of the step, m. - """ - super()._record(z, dz, norm, accepted) - if self._tdse_binding is not None: - self._tdse_binding.record_trial(accepted=accepted) - - def _finish( - self, - state: Complex[np.ndarray, "n_modes n_pol n_omega"], - dz: float, - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Apply the once-per-accepted-step boundary treatments to a kept step. - - - ``dz``: length of the step, m. - - Returns: the state with the hard band mask and, when one is present, the - temporal absorber applied. The ``"split_step"`` absorber is followed by the - mask, so the accepted state never holds content outside the active band. - """ - masked = self._apply_mask(state) - responses = self._problem.responses - rate = responses.temporal_absorber - if rate is None or responses.absorber_scheme != "split_step": - # Either there is no collar, or ADR-025's other scheme applied it inside - # every stage, where it is already in the accepted state. - return masked - if (monitor := self._split_monitor) is not None: - # The time factor acts alike on every column of any transverse basis, so - # the stored state's power is what the split takes of, wherever it acts. - # What it finds is what the occupancies are judged on. - sums = monitor.split_sums(self._observed_field(masked), dz) - self._split_removed += float(sums[0]) - self._split_found = sums[1:] - geometry = self._problem.transform.geometry - if geometry is not None and geometry.kind == "slab": - # A (p, y) row is a modal amplitude whose time signal is a real field's, - # and the rate is the same at every node, so it is applied row by row. - transform = self._problem.transform - physical = slab_rows(transform, masked) - chunk = self.node_chunk - for first in range(0, len(physical), chunk): - rows = slice(first, first + chunk) - physical[rows] = passes.apply_temporal_rate( - physical[rows], rate, dz, kind=self._kind - ) - return self._apply_mask(slab_columns(transform, physical)) - if geometry is not None and geometry.kind == "free": - nx, ny = geometry.shape - shape = (ny, nx, *masked.shape[1:]) - physical = np.fft.ifft2(masked.reshape(shape), axes=(0, 1)).reshape( - masked.shape - ) - chunk = self.node_chunk - for first in range(0, len(physical), chunk): - rows = slice(first, first + chunk) - physical[rows] = passes.apply_temporal_rate( - physical[rows], rate, dz, kind=self._kind - ) - result = np.fft.fft2(physical.reshape(shape), axes=(0, 1)).reshape( - masked.shape - ) - return self._apply_mask(result) - # The product in time spreads content across every bin, the DC among them, so - # the band is imposed again after it, as the in-stage term is masked. - return self._apply_mask( - passes.apply_temporal_rate(masked, rate, dz, kind=self._kind) - ) - - def _update_alarm(self) -> None: - """Score the quadrature from the last stage of an accepted step. - - The relative difference between the projections of the same node polarisation - with the Kronrod rule and with its embedded Gauss subset, at the cost of one - extra forward transform per accepted step rather than a whole second evaluation - of the transform. - It is a **statistic and a warning, never a controller input**: a - quadrature too coarse for the integrand is a modelling error the step size - cannot fix, and feeding it to the controller would only shrink the step until - the run stopped. - - The value is ``nan`` when the rule has no embedded pair, because the difference - is then identically zero and reading that as convergence would be wrong; and - ``nan`` where the polarisation itself vanishes, at a true vacuum end, because a - relative measure of nothing says nothing. - """ - if ( - self._last_coarse is None - or self._last_projected is None - or self._last_bundle is None - ): - self._alarm = math.nan - return - grids = self._problem.grids - weight = self._prefactor(self._last_bundle) * self._tables.omega_window - fine = weight * passes.to_frequency( - self._last_projected, grids.crop_index, kind=self._kind - ) - coarse = weight * passes.to_frequency( - self._last_coarse, grids.crop_index, kind=self._kind - ) - if self._last_envelope is not None: - assembly = self._problem.responses.envelope_plasma - assert assembly is not None - drive, loss, coarse_drive, coarse_loss = self._last_envelope - assert coarse_drive is not None and coarse_loss is not None - for factor, full, reduced in ( - (assembly.factors.drude, drive, coarse_drive), - (assembly.factors.loss, loss, coarse_loss), - ): - fine += ( - weight - * factor - * passes.to_frequency(full, grids.crop_index, kind=self._kind) - ) - coarse += ( - weight - * factor - * passes.to_frequency(reduced, grids.crop_index, kind=self._kind) - ) - if self._last_plasma is not None: - gated, edge, coarse_gated, coarse_edge = self._last_plasma - assert coarse_gated is not None and coarse_edge is not None - fine += weight * self._held_streams(gated, edge) - coarse += weight * self._held_streams(coarse_gated, coarse_edge) - scale = float(np.linalg.norm(fine)) - self._alarm = ( - math.nan if scale == 0.0 else float(np.linalg.norm(coarse - fine) / scale) - ) - if self._alarm > QUADRATURE_ALARM and not self._alarm_reported: - self._alarm_reported = True - warn_quadrature(self._alarm, self._last_bundle.z1) - - def _nonlinear( - self, - lab: Complex[np.ndarray, "n_modes n_pol n_omega"], - bundle: StageScalars, - inverse_propagator: Complex[np.ndarray, "n_modes n_pol n_omega"], - *, - purpose: TDSEPurpose = "predictor", - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Evaluate one stage derivative through the transform passes. - - The pipeline of ``architecture.md`` section 8 for any node count: one batched - inverse transform of every modal column, then, per chunk of - :attr:`node_chunk` nodes, the synthesis GEMM, the fused response pass and - the projection GEMM accumulated over the chunks, then one batched forward - transform, the crop and the prefactor. Mode-averaged propagation is the - one-node, one-column case of exactly this code. - """ - responses = self._problem.responses - grids = self._problem.grids - if self._tdse_binding is not None: - return self._nonlinear_tdse(lab, bundle, inverse_propagator, purpose) - if self._problem.linear.separable is not None: - geometry = self._problem.transform.geometry - evaluate = ( - self._nonlinear_slab - if geometry is not None and geometry.kind == "slab" - else self._nonlinear_free - ) - return evaluate(lab, bundle, inverse_propagator) - if self._general is not None: - return self._nonlinear_general(lab, bundle, inverse_propagator) - if len(responses.response_order) == 1: - # Nothing but the accumulation was compiled, so the polarisation is - # identically zero and the step is the exact linear flow. Running the - # transforms to multiply by nothing would only add round-off -- unless - # ADR-025's in-stage absorber is active, which is a term of its own and - # would otherwise be dropped from a problem that has no response at all. - if not self._in_stage_absorber: - return np.zeros_like(lab) - alone = passes.to_time(lab, grids.crop_index, grids.n_to, kind=self._kind) - return passes.stage_output( - np.zeros_like(lab), - np.zeros_like(lab), - self._tables.omega_window, - inverse_propagator, - self._absorber_term(alone, may_quiet=True), - ) - modal_t = passes.to_time(lab, grids.crop_index, grids.n_to, kind=self._kind) - geometry = self._problem.transform.geometry - if ( - geometry is not None - and geometry.kind == "radial" - and bool(responses.plasma_channels) - and not self._gated_plasma - ): - spectrum = self._radial_plasma_spectrum(modal_t, bundle) - else: - projected, coarse = self._over_nodes(modal_t, bundle) - self._last_projected = projected - self._last_coarse = coarse - self._last_bundle = bundle - spectrum = passes.to_frequency(projected, grids.crop_index, kind=self._kind) - if self._last_plasma is not None: - gated, edge, _, _ = self._last_plasma - spectrum += self._held_streams(gated, edge) - if responses.envelope_plasma is not None: - assert self._last_envelope is not None - drive, loss, _, _ = self._last_envelope - factors = responses.envelope_plasma.factors - spectrum += factors.drude * passes.to_frequency( - drive, grids.crop_index, kind=self._kind - ) - spectrum += factors.loss * passes.to_frequency( - loss, grids.crop_index, kind=self._kind - ) - return passes.stage_output( - spectrum, - self._prefactor(bundle), - self._tables.omega_window, - inverse_propagator, - self._absorber_term(modal_t, may_quiet=True), - ) - - def _nonlinear_tdse( - self, - lab: Complex[np.ndarray, "n_modes n_pol n_omega"], - bundle: StageScalars, - inverse_propagator: Complex[np.ndarray, "n_modes n_pol n_omega"], - purpose: TDSEPurpose, - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Evaluate the declared atomic binding and combine independent P/J sources. - - Steps 1 to 4 are :mod:`solprop.backends.tdse_source`'s, shared with native; - the stage output is this backend's own. - """ - problem = self._problem - grids = problem.grids - binding = self._tdse_binding - assert binding is not None and tdse_of(problem.route) is not None - modal_t = passes.to_time(lab, grids.crop_index, grids.n_to, kind="field") - fields = tdse_source.node_fields(problem, lab, bundle) - result = binding.evaluate( - fields, z=bundle.z1, purpose=purpose, density=bundle.density - ) - polarisation, current = tdse_source.atomic_sources( - fields, result, problem, bundle - ) - source, projection = tdse_source.project_atomic_sources( - polarisation, - current, - result, - problem, - bundle, - self._prefactor(bundle), - edge=tdse_source.atomic_edge_source(result, problem, bundle), - ) - self._tdse_last_purpose, self._tdse_last_z = purpose, bundle.z1 - self._tdse_last_projection = projection - return passes.stage_output( - source, - np.ones_like(source), - grids.omega_window, - inverse_propagator, - self._absorber_term(modal_t), - ) - - def _nonlinear_general( - self, - lab: Complex[np.ndarray, "n_modes n_pol n_omega"], - bundle: StageScalars, - inverse_propagator: Complex[np.ndarray, "n_modes n_pol n_omega"], - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Evaluate one stage derivative through a general modal guide's maps. - - The route's own execution path, in - :mod:`solprop.backends.numpy_ref.general_modal`, beside the fused pass and - not an extension of it. The synthesis is a complex - frequency-dependent map of three Cartesian components, so it happens in the - frequency domain and the field a response sees is the analytic signal. What - is shared with the legacy path is everything after the projection -- the - prefactor, which is the crop scale alone here, the spectral collar, the - in-stage absorber and the return to the interaction picture. - - The quadrature alarm is not scored on this route: the general node rule has - no embedded coarse pair, and a difference that is identically zero read as - convergence would be wrong, as for any unpaired rule. - - A guide with no responding region is short-circuited, as the legacy path - short-circuits a problem whose `response_order` is the accumulation alone. - """ - assert self._general is not None - grids = self._problem.grids - # A guide whose every material region is linear has an identically zero - # tensor, so the source is zero for every state and every position: the - # synthesis, the 3 x n_nodes transforms, the contraction and the projection - # would spend a tenth of a second per step producing it (measured 108 ms on - # the 288-node strand). ADR-025's in-stage absorber is a term of its own and - # is not dropped with it. - spectrum = ( - general_source( - lab, - self._general, - grids.crop_index, - n_to=grids.n_to, - pad_scale=grids.pad_scale, - transform_weights=bundle.transform_weights, - dispersive_densities=bundle.dispersive_kerr_densities, - ) - if self._general_responds - else np.zeros_like(lab) - ) - absorber = None - if self._in_stage_absorber: - absorber = self._absorber_term( - passes.to_time(lab, grids.crop_index, grids.n_to, kind=self._kind) - ) - return passes.stage_output( - spectrum, - self._prefactor(bundle), - grids.omega_window, - inverse_propagator, - absorber, - ) - - def _column_sources( - self, - field_t: np.ndarray, - bundle: StageScalars, - raman: np.ndarray | None, - ) -> passes.NonlinearSources: - """Evaluate one column; the historical integral is benchmark-only. - - - ``field_t``: physical node fields in V/m, with time last. - - ``raman``: damped Raman convolution spectrum, when required by the response. - - Returns: the collared local polarisation in C/m² and the ungated current in - A/m². - """ - responses, grids = self._problem.responses, self._problem.grids - sources = passes.nonlinear_sources( - field_t, - responses, - self._tables.t_window, - kind=self._kind, - density=bundle.density, - preionisation=bundle.preionisation, - dt=grids.dt_fine, - carrier=self._carrier, - raman_spectrum=raman, - scalars=bundle, - ) - if not self._gated_plasma or sources.current is None: - return sources - return passes.NonlinearSources( - sources.polarisation - + self._tables.t_window - * responses.plasma_integral.integrate(sources.current, grids.dt_fine), - None, - ) - - def _held_streams(self, gated: np.ndarray, edge: np.ndarray) -> np.ndarray: - """Transform and combine the current products in polarisation units. - - - ``gated``, ``edge``: fine-time ``gJ`` and ``g'J`` rows, optionally projected - before this call. - - Returns: cropped raw-DFT polarisation-equivalent source, zero on inactive - bins. - """ - grids = self._problem.grids - return passes.held_plasma_spectrum( - gated, edge, grids.omega, grids.crop_index, grids.active_mask - ) - - def _held_current(self, current: np.ndarray) -> np.ndarray: - """Form and transform the two collared products of a nodal current. - - - ``current``: the ungated nodal current in A/m², fine time last. - - Returns: cropped raw-DFT polarisation-equivalent source at the nodes. - """ - return self._held_streams( - self._tables.t_window * current, self._tables.t_window_derivative * current - ) - - def _radial_plasma_spectrum( - self, - modal_t: np.ndarray, - bundle: StageScalars, - ) -> np.ndarray: - """Transform three nodal streams, combine, then project once in frequency.""" - problem = self._problem - transform, grids = problem.transform, problem.grids - spectrum = np.zeros(problem.shape, dtype=np.complex128) - raman = self._raman_spectrum(bundle.raman_rates, bundle.raman_densities) - for first in range(0, transform.n_nodes, self.node_chunk): - rows = slice( - first * transform.n_pol, - (first + self.node_chunk) * transform.n_pol, - ) - field = passes.synthesise( - modal_t, - self._tables.synthesis[rows], - bundle.taper_scale, - transform.n_pol, - ) - sources = self._column_sources(field, bundle, raman) - assert sources.current is not None - nodal = passes.to_frequency( - sources.polarisation, grids.crop_index, kind="field" - ) - nodal += self._held_current(sources.current) - spectrum += passes.project( - nodal, - self._tables.projection[:, rows], - bundle.taper_scale, - transform.n_pol, - ) - return spectrum - - def _nonlinear_free( - self, - lab: np.ndarray, - bundle: StageScalars, - inverse_propagator: np.ndarray, - ) -> np.ndarray: - """Apply transverse FFTs before bounded temporal response transforms. - - - ``lab``: Lab-frame stage spectrum. - """ - problem = self._problem - transform, grids, responses = ( - problem.transform, - problem.grids, - problem.responses, - ) - geometry = transform.geometry - if geometry is None: - msg = "Cartesian nonlinear evaluation requires spatial geometry" - raise BackendError(msg) - shape = (geometry.shape[1], geometry.shape[0], *lab.shape[1:]) - result = np.zeros_like(lab) - if len(responses.response_order) == 1 and not self._in_stage_absorber: - return result - scratch = np.empty_like(lab) - if len(responses.response_order) > 1: - scratch.reshape(shape)[...] = np.fft.ifft2(lab.reshape(shape), axes=(0, 1)) - raman = self._raman_spectrum(bundle.raman_rates, bundle.raman_densities) - for first in range(0, transform.n_nodes, self.node_chunk): - rows = slice(first, first + self.node_chunk) - field_t = grids.pad_scale * passes.to_time( - scratch[rows], grids.crop_index, grids.n_to, kind=self._kind - ) - sources = self._column_sources(field_t, bundle, raman) - polarisation_t = sources.polarisation - scratch[rows] = passes.to_frequency( - polarisation_t, grids.crop_index, kind=self._kind - ) - if sources.current is not None: - scratch[rows] += self._held_current(sources.current) - if responses.envelope_plasma is not None: - drive, loss = self._envelope_sources(field_t, bundle) - factors = responses.envelope_plasma.factors - scratch[rows] += factors.drude * passes.to_frequency( - drive, grids.crop_index, kind=self._kind - ) - scratch[rows] += factors.loss * passes.to_frequency( - loss, grids.crop_index, kind=self._kind - ) - view = scratch.reshape(shape) - view[...] = np.fft.fft2(view, axes=(0, 1)) - data = problem.linear.separable - assert data is not None - for first in range(0, transform.n_nodes, self.node_chunk): - rows = slice(first, first + self.node_chunk) - _, prefactor = separable_values(data, rows) - result[rows] = prefactor * self._tables.omega_window * scratch[rows] - if self._in_stage_absorber: - # The rate is additive to the normalised material term. Reusing the - # transverse scratch avoids a second retained physical spectral volume. - scratch.reshape(shape)[...] = np.fft.ifft2(lab.reshape(shape), axes=(0, 1)) - temporal = self._tables.temporal_rate - timed = temporal is not None and responses.absorber_scheme == "nonlinear" - for first in range(0, transform.n_nodes, self.node_chunk): - rows = slice(first, first + self.node_chunk) - rate = geometry.absorber_rate[rows, None, None] - if not timed: - # A rate of the node alone commutes with the temporal transforms: - # a spatial-only pass needs no temporal pair (SEP 40 section 4.7). - scratch[rows] = -0.5 * rate * scratch[rows] - continue - field_t = passes.to_time( - scratch[rows], grids.crop_index, grids.n_to, kind=self._kind - ) - scratch[rows] = passes.to_frequency( - -0.5 * (rate + temporal) * field_t, - grids.crop_index, - kind=self._kind, - ) - view = scratch.reshape(shape) - view[...] = np.fft.fft2(view, axes=(0, 1)) - result += grids.active_mask * scratch - return result * inverse_propagator - - def _nonlinear_slab( - self, - lab: np.ndarray, - bundle: StageScalars, - inverse_propagator: np.ndarray, - ) -> np.ndarray: - """Evaluate one hybrid planar stage: slab synthesis in x, an FFT in y. - - The ``(p, k_y)`` columns go to ``(p, y)`` rows by the inverse DFT in y, and - the rows to time -- a row is a slab amplitude, whose time signal is a real - field's on a field grid -- so that, as on the modal route, only ``n_p * n_y`` - temporal transforms are taken each way. In time, the slab synthesis (which - carries the pad scale) gives the field at the ``(x, y)`` nodes, the responses - are the Cartesian ones node by node, and the slab rule's dual basis projects - the polarisation back onto the rows; the rows return to frequency and to - ``(p, k_y)``, and each column takes its own prefactor from the separable leaf - (kernel schema 15). The y collar's in-stage rate depends on y alone, so it - acts on the rows directly. - - - ``lab``: Lab-frame stage spectrum. - """ - problem = self._problem - transform, grids, responses = ( - problem.transform, - problem.grids, - problem.responses, - ) - geometry = transform.geometry - assert geometry is not None - result = np.zeros_like(lab) - if len(responses.response_order) == 1 and not self._in_stage_absorber: - return result - n_x, n_y = geometry.shape - n_p = transform.synthesis.shape[1] - rows_f = slab_rows(transform, lab) - temporal = responses.temporal_absorber_fine - timed = temporal is not None and responses.absorber_scheme == "nonlinear" - rows_t = ( - passes.to_time(rows_f, grids.crop_index, grids.n_to, kind=self._kind) - if len(responses.response_order) > 1 or timed - else None - ) - if len(responses.response_order) > 1: - assert rows_t is not None - raman = self._raman_spectrum(bundle.raman_rates, bundle.raman_densities) - envelope = responses.envelope_plasma is not None - plasma = bool(responses.plasma_channels) and not self._gated_plasma - projected = np.zeros_like(rows_t) - # The envelope plasma's Drude drive and loss current, projected as the - # polarisation is; empty unless the response is present. - drives = [ - np.zeros_like(rows_t) for _ in range(2 if envelope or plasma else 0) - ] - # Whole y rows at a time, as many as the node chunk holds. - block = max(1, self.node_chunk // n_x) - for first in range(0, n_y, block): - rows = slice(first * n_p, min(first + block, n_y) * n_p) - count = (rows.stop - rows.start) // n_p - field_t = np.matmul( - transform.synthesis, rows_t[rows].reshape(count, n_p, -1) - ).reshape(count * n_x, *rows_t.shape[1:]) - sources = self._column_sources(field_t, bundle, raman) - current = sources.current - source_rows = [sources.polarisation] - if envelope: - assert responses.envelope_plasma is not None - source_rows.extend( - envelope_sources( - field_t, - responses.envelope_plasma, - bundle, - grids.dt_fine, - grids.t_window_fine, - ) - ) - if current is not None: - source_rows.extend( - ( - grids.t_window_fine * current, - grids.t_window_fine_derivative * current, - ) - ) - for target, source in zip( - (projected, *drives), source_rows, strict=True - ): - target[rows] = np.matmul( - transform.projection, source.reshape(count, n_x, -1) - ).reshape(count * n_p, *rows_t.shape[1:]) - spectrum = passes.to_frequency(projected, grids.crop_index, kind=self._kind) - if envelope: - assert responses.envelope_plasma is not None - factors = responses.envelope_plasma.factors - spectrum += factors.drude * passes.to_frequency( - drives[0], grids.crop_index, kind=self._kind - ) - spectrum += factors.loss * passes.to_frequency( - drives[1], grids.crop_index, kind=self._kind - ) - if plasma: - spectrum += self._held_streams(drives[0], drives[1]) - columns = slab_columns(transform, spectrum) - data = problem.linear.separable - assert data is not None - for first in range(0, transform.n_modes, self.node_chunk): - rows = slice(first, first + self.node_chunk) - _, prefactor = separable_values(data, rows) - result[rows] = prefactor * grids.omega_window * columns[rows] - if self._in_stage_absorber: - result += self._slab_absorber(rows_f, rows_t) - return result * inverse_propagator - - def _slab_absorber( - self, - rows_f: Complex[np.ndarray, "n_modes n_pol n_omega"], - rows_t: Inexact[np.ndarray, "n_modes n_pol n_to"] | None, - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Return the planar in-stage collar's term on the ``(p, k_y)`` columns. - - The collar's rate depends on y alone, so it acts on the ``(p, y)`` rows. With - no temporal rate in-stage it commutes with the temporal transforms, and the - pass needs no temporal pair (SEP 40 section 4.7). - - - ``rows_t``: the same rows in time; required when a temporal rate applies - in-stage. - """ - problem = self._problem - transform, grids, responses = ( - problem.transform, - problem.grids, - problem.responses, - ) - geometry = transform.geometry - assert geometry is not None - n_x, n_y = geometry.shape - n_p = transform.synthesis.shape[1] - rate = np.repeat(geometry.absorber_rate.reshape(n_y, n_x)[:, 0], n_p)[ - :, None, None - ] - temporal = responses.temporal_absorber_fine - if temporal is not None and responses.absorber_scheme == "nonlinear": - assert rows_t is not None - term = passes.to_frequency( - -0.5 * (rate + temporal) * rows_t, grids.crop_index, kind=self._kind - ) - else: - term = -0.5 * rate * rows_f - return grids.active_mask * slab_columns(transform, term) - - def _absorber_term( - self, - modal_t: Inexact[np.ndarray, "n_modes n_pol n_to"], - *, - may_quiet: bool = False, - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"] | None: - """Return the in-stage absorber's contribution, or ``None`` in the other scheme. - - On the modal stage (`may_quiet`) a temporal collar alone is left out while the - boundary monitor finds it quiet (SEP 21): the term is then below - :data:`solprop.monitor.QUIET`, and its transform is the stage's largest cost - after the response's. - - - Returns: the absorber's term on the coarse grid, or ``None`` when the - ``"split_step"`` scheme is active and the rate is applied to the state after - the step instead. - """ - rate = self._tables.temporal_rate - if not self._in_stage_absorber: - return None - if may_quiet and self._collar_quiet and not self._spatial_absorber.size: - return None - grids = self._problem.grids - term = np.zeros_like(modal_t) - if rate is not None and self._problem.responses.absorber_scheme == "nonlinear": - term = -0.5 * rate * modal_t - if self._spatial_absorber.size: - term = term + ( - self._spatial_absorber @ modal_t.reshape(modal_t.shape[0], -1) - ).reshape(modal_t.shape) - return ( - passes.to_frequency(term, grids.crop_index, kind=self._kind) - * grids.active_mask - ) - - def _over_nodes( - self, - modal_t: Inexact[np.ndarray, "n_modes n_pol n_to"], - bundle: StageScalars, - ) -> tuple[ - Num[np.ndarray, "n_modes n_pol n_to"], - Num[np.ndarray, "n_modes_c n_pol_c n_to_c"] | None, - ]: - """Run the response pass over the quadrature in chunks and project it back. - - The chunk loop of ``architecture.md`` section 13: the space-domain buffers are - sized by :attr:`node_chunk` and not by the node count, so a chunk of one - and a chunk of every node differ only in round-off. The embedded coarse rule is - projected in the same loop, from the same node polarisation, because that is - what makes the quadrature alarm free: the two rules share every node the coarse - one has. - - - Returns: the modal polarisation on the fine time grid, and the same under the - embedded coarse rule, or ``None`` when the quadrature has no embedded pair - and the estimate would be identically zero. - """ - responses, grids = self._problem.responses, self._problem.grids - transform = self._problem.transform - taper = bundle.taper_scale - # Once per stage rather than once per chunk: the kernel spectrum does not depend - # on the nodes, and along a gradient it is one real transform of 2 n_to against - # n_modes n_pol transforms of n_to that the stage costs anyway. - raman = self._raman_spectrum(bundle.raman_rates, bundle.raman_densities) - n_pol = transform.n_pol - projected = np.zeros( - (transform.n_modes, self._problem.shape[1], grids.n_to), - dtype=modal_t.dtype, - ) - coarse = None if self._embedded is None else np.zeros_like(projected) - envelope = self._problem.responses.envelope_plasma - envelope_projected = ( - None - if envelope is None - else ( - np.zeros_like(projected), - np.zeros_like(projected), - None if coarse is None else np.zeros_like(coarse), - None if coarse is None else np.zeros_like(coarse), - ) - ) - plasma_projected = ( - ( - np.zeros_like(projected), - np.zeros_like(projected), - None if coarse is None else np.zeros_like(coarse), - None if coarse is None else np.zeros_like(coarse), - ) - if bool(responses.plasma_channels) and not self._gated_plasma - else None - ) - for first in range(0, transform.n_nodes, self.node_chunk): - rows = slice(first * n_pol, (first + self.node_chunk) * n_pol) - field_t = passes.synthesise( - modal_t, self._tables.synthesis[rows], taper, n_pol - ) - sources = self._column_sources(field_t, bundle, raman) - polarisation_t = sources.polarisation - projected = projected + passes.project( - polarisation_t, self._tables.projection[:, rows], taper, n_pol - ) - if coarse is not None and self._embedded is not None: - coarse = coarse + passes.project( - polarisation_t, self._embedded[:, rows], taper, n_pol - ) - if sources.current is not None and plasma_projected is not None: - gated, edge, coarse_gated, coarse_edge = plasma_projected - for target, reduced, window in ( - (gated, coarse_gated, self._tables.t_window), - (edge, coarse_edge, self._tables.t_window_derivative), - ): - current = window * sources.current - target[...] += passes.project( - current, self._tables.projection[:, rows], taper, n_pol - ) - if reduced is not None and self._embedded is not None: - reduced[...] += passes.project( - current, self._embedded[:, rows], taper, n_pol - ) - if envelope is not None and envelope_projected is not None: - drive, loss = self._envelope_sources(field_t, bundle) - full_drive, full_loss, coarse_drive, coarse_loss = envelope_projected - full_drive += passes.project( - drive, self._tables.projection[:, rows], taper, n_pol - ) - full_loss += passes.project( - loss, self._tables.projection[:, rows], taper, n_pol - ) - if ( - self._embedded is not None - and coarse_drive is not None - and coarse_loss is not None - ): - coarse_drive += passes.project( - drive, self._embedded[:, rows], taper, n_pol - ) - coarse_loss += passes.project( - loss, self._embedded[:, rows], taper, n_pol - ) - self._last_plasma = plasma_projected - self._last_envelope = envelope_projected - return projected, coarse - - def _raman_spectrum( - self, rates: tuple[float, ...], densities: tuple[float, ...] = () - ) -> Complex[np.ndarray, "... n_omega_doubled"] | None: - """Return the damped Raman kernel spectrum for a set of rates, anew. - - Memoised on the **decay rates** rather than on the density, because the rates - are what the spectrum depends on: a glass's are zero at every density, so its - kernel is transformed once for the whole run, and a molecular gas on a gradient - presents new rates at every stage and is transformed once per stage. Only the - most recent set is kept, which is the right choice here -- a growing cache would - hold thousands of spectra and hit none. - - - ``rates``: the decay rate of each term at the stage's position, s^-1, off the - bundle. - - ``densities``: component amplitude densities in m^-3, in Raman-component - order. Multiple components include every amplitude in the cache key; one keeps - density outside the convolution and retains the original arithmetic. - - Returns: the spectrum of shape ``(n_to + 1,)``, or ``None`` when no Raman - kernel was compiled. - """ - components = self._problem.responses.raman_terms - if not components: - return None - amplitudes = densities if len(components) > 1 else () - if ( - self._raman_kernel is None - or self._raman_rates != rates - or self._raman_densities != amplitudes - ): - if self._problem.transform.n_pol * self._problem.shape[1] == 2: - self._raman_kernel = passes.tensor_raman_spectrum( - components, - rates, - densities if len(components) > 1 else (1.0,), - self._problem.grids.dt_fine, - ) - elif len(components) == 1: - compiled = components[0] - self._raman_kernel = passes.raman_spectrum( - compiled.undamped, - rates, - compiled.fraction, - self._problem.grids.dt_fine, - ) - else: - self._raman_kernel = passes.mixture_raman_spectrum( - components, rates, densities, self._problem.grids.dt_fine - ) - self._raman_rates = rates - self._raman_densities = amplitudes - self._raman_transforms += 1 - return self._raman_kernel - - def _exponents( - self, z: float, dz: float - ) -> Callable[[float, StageScalars], Complex[np.ndarray, "n_modes n_pol n_omega"]]: - """Return the memoised ``dPhi`` of a step, keyed by the stage fraction. - - The anchor is hoisted once per step and each exponent is evaluated once and - negated for the inverse, never evaluated forward and backward independently - (``docs/dev/stepper.md`` section 4). ``propagator_mode`` decides whether the - exponents are kept for the whole step or evaluated per stage; the exponent - itself is one linear combination of the terms over the bundle's weights, - whatever the representation (:mod:`solprop.translate.stage`). - - - ``z``: position at the start of the step, m. - - ``dz``: length of the step, m. - - Returns: ``(fraction, bundle) -> dPhi``, of the state's broadcast shape. - """ - del z, dz - if self._propagator_mode == "recompute": - return lambda fraction, bundle: self._delta_phi(bundle) # noqa: ARG005 - cache: dict[float, Complex[np.ndarray, "n_modes n_pol n_omega"]] = {} - - def exponent( - fraction: float, bundle: StageScalars - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Return ``dPhi`` at a stage fraction, computing it at most once. - - - ``fraction``: the tableau node ``c_i``, dimensionless, in ``[0, 1]``. - """ - if fraction not in cache: - cache[fraction] = self._delta_phi(bundle) - return cache[fraction] - - return exponent - - -@dataclass(frozen=True) -class SourceTables: - """The problem's tables a source evaluation multiplies by. - - The arrays the passes read, gathered once from the problem. - - Attributes - ---------- - synthesis : numpy.ndarray - ``transform.synthesis``. - projection : numpy.ndarray - ``transform.projection``. - t_window : numpy.ndarray - ``grids.t_window_fine``. - t_window_derivative : numpy.ndarray - ``grids.t_window_fine_derivative``. - omega_window : numpy.ndarray - ``grids.omega_window``. - temporal_rate : numpy.ndarray or None - ``responses.temporal_absorber_fine``. - """ - - synthesis: Float[np.ndarray, "n_rows n_modes_s"] - projection: Float[np.ndarray, "n_modes n_columns"] - t_window: Float[np.ndarray, " n_to"] - t_window_derivative: Float[np.ndarray, " n_to"] - omega_window: Float[np.ndarray, " n_omega"] - temporal_rate: Float[np.ndarray, " n_to"] | None - - @classmethod - def of(cls, problem: PropagationProblem) -> "SourceTables": - """Return the problem's own tables. - - Parameters - ---------- - problem : solprop.translate.problem.PropagationProblem - The problem. - - Returns - ------- - SourceTables - References to its arrays, uncopied. - """ - grids = problem.grids - return cls( - problem.transform.synthesis, - problem.transform.projection, - grids.t_window_fine, - grids.t_window_fine_derivative, - grids.omega_window, - problem.responses.temporal_absorber_fine, - ) - def _refuse_adams(problem: PropagationProblem, stepper: StepperSettings) -> None: """Refuse what the Adams march does not execute (SEP 13 sections 2 and 6.2). @@ -2395,530 +428,3 @@ def _refuse_unsupported(problem: PropagationProblem, stepper: StepperSettings) - "and not to both, so this problem would count them twice" ) raise BackendError(msg) - - -_GENERAL_LEDGER_ROWS = ( - "general_synthesis", - "general_projection", - "general_stage_maps", - "general_tensor", - "general_electric", - "general_magnetic", - "general_backward_electric", - "general_backward_magnetic", - "general_reciprocal_gram", - "general_coordinate_dual", - "general_scaled_state", - "general_node_spectrum", - "general_node_field", - "general_node_pair", - "general_node_weighted", - "general_node_polarisation", - "general_node_source", - "general_node_drive", - "general_node_histories", - "general_node_drive_spectrum", - "general_node_delayed", - "general_delayed_tensor", - "general_delayed_spectrum", -) -"""The ledger rows of the general modal route, named even when they are empty. - -``memory_ledger`` names every buffer on every route, so a problem that is not a -general modal guide reports these as zero rather than omitting them -(:func:`solprop.backends.numpy_ref.general_modal.general_memory` fills them). -""" - - -def _refuse_inadmissible(problem: PropagationProblem, spec: StatsSpec) -> None: - """Refuse a statistic this problem's basis does not define, by name. - - The second door of the accessor whitelist (:mod:`solprop.output.capability`), - after the run loop's own admission: a caller may build a backend and ask it for - statistics directly, and a general guide's static synthesis matrix is a checked - **zero** placeholder, so an on-axis intensity taken from one would be zero - rather than obviously wrong. - """ - refusal = refusal_for( - declared_capability( - general_modal=problem.transform.modal_tables is not None, - spatial=problem.transform.geometry is not None, - ), - spec.names, - withheld=withheld_accessors( - general_modal=problem.transform.modal_tables is not None, - coupled_flow=problem.linear.coupled_flow is not None, - ), - ) - if refusal is not None: - raise BackendError(refusal) - refusal = axis_refusal(problem, spec.names) - if refusal is not None: - raise BackendError(refusal) - - -def _general_maps( - problem: PropagationProblem, plan: NodeChunkPlan | None = None -) -> GeneralMaps | None: - """Derive the general modal route's maps, or return ``None`` for another route. - - The maps are read out of the leaves once, here, because the route propagates - constant geometry: one interval of one Chebyshev degree along z, so there is - nothing to evaluate per stage. The chunk is the backend's own memory strategy - within the plan's budget, or the plan's exact chunk when one was forced. - - - ``plan``: the backend's node-chunk plan; ``None`` plans the automatic one. - - Returns: the derived maps, or ``None`` when the problem carries no modal tables. - """ - tables = problem.transform.modal_tables - if tables is None: - return None - assert tables.synthesis is not None and tables.projection is not None - chunk = general_planned_chunk( - problem, plan_node_chunk(problem) if plan is None else plan - ) - regional = problem.responses.regional_responses - owner, delayed_tensor, delayed_spectrum = node_delayed_maps(tables, regional) - moving = tables.synthesis.shape[0] * tables.synthesis.shape[1] > 1 - maps = GeneralMaps( - tables.synthesis[0, 0], - tables.projection[0, 0], - node_kerr_tensor(tables, regional), - tables.source_frequency_factor, - chunk, - node_kerr_form(regional), - owner, - delayed_tensor, - delayed_spectrum, - # A moving guide's coefficients, flattened over (n_intervals, n_deg) in the - # order the stage bundle's transform_weights are. - tables.synthesis.reshape(-1, *tables.synthesis.shape[2:]) if moving else None, - tables.projection.reshape(-1, *tables.projection.shape[2:]) if moving else None, - problem.responses.dispersive_kerr, - None if problem.responses.dispersive_kerr is None else tables.region_index, - ) - logger.debug( - "numpy_ref general modal route: %d channels on %d nodes, chunk %d, " - "%d fine bins, gauge %s, %s cubic, %d delayed term(s)", - maps.n_modes, - maps.n_nodes, - maps.node_chunk, - int(tables.omega_fine.size), - tables.gauge_id, - maps.form, - maps.n_terms, - ) - return maps - - -@dataclass(frozen=True) -class _CoupledFlow(CoupledFlowFactors): - """What ``numpy_ref`` holds to execute one coherent block, frozen per section. - - The shared factors (:class:`~solprop.translate.coupled.CoupledFlowFactors`, which - native reads too), with the section axis leading and only the bins the generator - is non-zero at held: the rest of the band has an identity action and the state is - masked to zero there anyway. - - A ``"constant_schur"`` leaf is the one-section case with no residual at all, and - goes through exactly the constant-section arithmetic. A ``"frozen_residual"`` leaf - adds `residual_terms`: the coefficients of ``G(z) - C(z)`` along z, flattened over - ``(n_intervals, n_deg)`` in that order, so that the stage bundle's - ``flow_weights`` combine them into ``G(z_1) - C(z_1)`` exactly as ``phi_delta`` - combines the terms of ``dPhi`` (``docs/dev/kernel-contract.md`` section 1). The - explicit residual is that combination minus the frozen block of the step's own - section. It is applied only on `residual_bins`, the active bins of the requested - band; in the spectral collar outside them the frozen flow alone carries the state - (``docs/guide/waveguides/general-modal.md``). - - Attributes - ---------- - residual_bins : numpy.ndarray - Which bins the explicit residual is applied at, bool, shape ``(n_omega,)``: - `active` and the problem's ``grids.inband_mask``, the requested band: in the - collar beyond it the wall model is outside its validity, and the residual is - left out whether or not the error norm scores there. - n_modes : int - Channels the block couples. - """ - - residual_bins: Bool[np.ndarray, " n_omega_scored"] - n_modes: int - - -_TAYLOR_ORDER = 16 -"""Degree of the Taylor series a scaled triangular exponential is summed to. - -Scaling brings the row-sum norm below :data:`_TAYLOR_SCALE`, so the truncated tail is -at most ``_TAYLOR_SCALE**(n+1)/(n+1)!``, which is 2.1e-20 at this degree -- below the -rounding of the squarings that follow it and of the two unitary products around it. -The alternative, a Pade approximant, buys a lower degree at the cost of a solve per -frequency; the oracle takes the series (``docs/dev/architecture.md`` section 3: -physics and reference code carry no performance tricks). -""" - -_TAYLOR_SCALE = 0.5 -"""Row-sum norm a block is scaled below before the series is summed.""" - -_MAX_FLOW_SQUARINGS = 30 -"""Largest number of squarings a flow action may need before it is refused. - -``2**30`` times the scale is a step whose own generator spans 21 orders of magnitude -in the exponent; a problem that needs it has not been certified by anything the -translation layer measured. -""" - - -def _flow_squarings(largest: float, *, backend: str = "numpy_ref") -> int: - """Return how many squarings an exponent of this row-sum norm needs, or refuse. - - The count brings the norm below :data:`_TAYLOR_SCALE`; past - :data:`_MAX_FLOW_SQUARINGS` the step is refused, as the compiled backends refuse it - whichever route forms their actions. - """ - squarings = 0 - if largest > _TAYLOR_SCALE: - squarings = math.ceil(math.log2(largest / _TAYLOR_SCALE)) - if squarings > _MAX_FLOW_SQUARINGS: - msg = ( - f"{backend} cannot take a coupled flow action whose exponent has row-sum " - f"norm {largest:.4g}: it would need {squarings} squarings, above the " - f"{_MAX_FLOW_SQUARINGS} this backend admits. Cap dz_max" - ) - raise BackendError(msg) - return squarings - - -def _triangular_exponential( - blocks: Complex[np.ndarray, "n_active_e n_modes_e_out n_modes_e_in"], - *, - backend: str = "numpy_ref", -) -> Complex[np.ndarray, "n_active_x n_modes_x_out n_modes_x_in"]: - """Return ``exp(A)`` for a stack of blocks, by scaling, a series and squaring. - - - Returns: ``exp(A)`` in the same layout. - """ - largest = float(np.max(np.sum(abs(blocks), axis=-1), initial=0.0)) - squarings = _flow_squarings(largest, backend=backend) - scaled = blocks / float(2**squarings) - identity = np.broadcast_to( - np.eye(blocks.shape[1], dtype=np.complex128), blocks.shape - ) - series = identity.copy() - for term in range(_TAYLOR_ORDER, 0, -1): - series = identity + scaled @ series / term - for _ in range(squarings): - series = series @ series - return series - - -def _flow_action( - flow: _CoupledFlow, section: int, length: float, *, backend: str = "numpy_ref" -) -> tuple[ - Complex[np.ndarray, "n_active_f n_modes_f_out n_modes_f_in"], - Complex[np.ndarray, "n_active_i n_modes_i_out n_modes_i_in"], -]: - """Return the forward and inverse flow actions of one section over one length. - - ``U = Z exp(l T) Z^H`` and ``U^-1 = Z exp(-l T) Z^H``: the inverse is the matrix - function of the negated exponent, never a numerical inverse of ``U``, so the - interaction picture's backward action is as accurate as its forward one and does - not inherit the conditioning of a solve (``docs/dev/stepper.md`` section 4: no - unbounded inverse propagation). - - - ``length``: distance in m, positive for the forward action. - """ - vectors = flow.vectors[section] - exponent = float(length) * flow.triangular[section] - adjoint = np.conj(np.swapaxes(vectors, -1, -2)) - forward = vectors @ _triangular_exponential(exponent, backend=backend) @ adjoint - inverse = vectors @ _triangular_exponential(-exponent, backend=backend) @ adjoint - return forward, inverse - - -def _residual_action( - flow: _CoupledFlow, section: int, weights: Float[np.ndarray, " n_flow_terms"] -) -> Complex[np.ndarray, "n_active_r n_modes_r_out n_modes_r_in"]: - """Return the explicit residual of one stage, ``R_s(z_1)``, on the active bins. - - ``R_s(z) = D(z) - D(z_s) + H(z) - H(z_s) - C(z)``, evaluated as one linear - combination of the held terms over the bundle's weights minus the frozen block of - the **step's** section. The weights are zero outside the section containing the - stage's own position, so no section's expansion is extrapolated; the frozen block - is the step's, because the exponential the interaction picture is built on is, and - freezing is a rearrangement of the same equation whichever block it names. - - - Returns: the residual in 1/m, shape ``(n_active, n_modes, n_modes)``. - """ - assert flow.residual_terms is not None - return combine(weights, flow.residual_terms) - flow.frozen[section] - - -class BlockResidual: - """``R_s(z) state`` for a held flow's positions (SEP 16 phases 5 and 6). - - A history sample's residual is formed against the section of every trial it serves, - about six; its action depends only on the section and the sample's flow weights, so - each pair's action is formed once and kept, the least recently used dropped first: - each trial's endpoint, at a new position, is used once. - - Parameters - ---------- - flow : _CoupledFlow - The held flow. - """ - - _KEPT = 64 - """Most actions kept: well above a history's samples times the sections it spans.""" - - def __init__(self, flow: _CoupledFlow) -> None: - """Hold the flow, with no action formed yet.""" - self._flow = flow - self._actions: collections.OrderedDict[tuple[int, bytes], np.ndarray] = ( - collections.OrderedDict() - ) - - def __call__( - self, - section: int, - state: Complex[np.ndarray, "n_modes n_pol n_omega"], - weights: Float[np.ndarray, " n_flow_terms"], - ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Return ``R_s(z) state`` for the flow weights of a position. - - Parameters - ---------- - section : int - The step's section, whose frozen block the residual is relative to. - state : numpy.ndarray - The state the residual acts on. - weights : numpy.ndarray - The flow's term weights at the position. - - Returns - ------- - numpy.ndarray - The residual's term, zero off the scored active bins. - """ - key = (section, np.ascontiguousarray(weights).tobytes()) - action = self._actions.get(key) - if action is None: - if len(self._actions) >= self._KEPT: - self._actions.popitem(last=False) - action = _residual_action(self._flow, section, weights) - self._actions[key] = action - else: - self._actions.move_to_end(key) - flow = self._flow - return _residual_drive(state, action, flow.active, flow.residual_bins) - - -def _residual_drive( - lab: Complex[np.ndarray, "n_modes n_pol n_omega"], - action: Complex[np.ndarray, "n_active_d n_modes_d_out n_modes_d_in"], - active: Bool[np.ndarray, " n_omega"], - scored: Bool[np.ndarray, " n_omega_scored"], -) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Return the explicit residual's contribution to one stage's lab-frame source. - - Unlike :func:`_apply_flow`, which *transforms* a state and therefore leaves the - bins it does not cover alone, this **adds a term** and is exactly zero off them: - the residual is zero at every bin the wall formula was never evaluated at, and a - copy of the state there would enter the source as a derivative of its own size. - - It is also zero on the active bins the error norm does not score, the spectral - collar. There the residual can reach a spectral radius the - embedded pair is unstable at, at steps the in-band error allows, and nothing - would see the growth; the frozen flow, exact at any step, carries those bins - alone. The block is diagonal in frequency, so no in-band bin reads them through - it; only the nonlinear source couples them in, at the size of the collar's - content. - - - ``action``: ``R_s(z_1)`` on the active bins, 1/m. - - Returns: ``R_s(z_1) u`` in the state's layout, zero off the scored active bins. - """ - drive = np.zeros_like(lab) - drive[:, :, scored] = np.einsum( - "wij,jpw->ipw", action[scored[active]], lab[:, :, scored] - ) - return drive - - -def _apply_flow( - state: Complex[np.ndarray, "n_modes n_pol n_omega"], - action: Complex[np.ndarray, "n_active_a n_modes_a_out n_modes_a_in"], - active: Bool[np.ndarray, " n_omega"], -) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Apply a per-frequency channel action to the canonical state. - - The identity case is the caller's: a problem with no coupled flow, or the zero - stage fraction, never reaches here. - - - ``state``: the state, or any array of its layout. - - Returns: the state with its channel axis mixed on the active bins and untouched - off them, where the block is zero and the action is the identity. - """ - carried = state.copy() - carried[:, :, active] = np.einsum("wij,jpw->ipw", action, state[:, :, active]) - return carried - - -def _check_flow_conditioning( - flow: _CoupledFlow, - section: int, - pair: tuple[ - Complex[np.ndarray, "n_active_p n_modes_p_out n_modes_p_in"], - Complex[np.ndarray, "n_active_q n_modes_q_out n_modes_q_in"], - ], - dz: float, - *, - backend: str = "numpy_ref", -) -> None: - """Refuse a step whose flow action exceeds the leaf's declared conditioning. - - The certificate row the translation layer declared is - ``exp(dz_max (mu_max - mu_min))``, a bound on ``norm(U)_2 norm(U^-1)_2``; here the - two spectral norms are **measured**, from the singular values of the actual - action, and compared with it. That is the point of a certificate: the row is a - claim the executor checks rather than a number it trusts, and a step longer than - the ``dz_max`` the row was declared over is exactly what this catches. - - The inverse is what the interaction picture carries the nonlinear source back by, - so an unbounded one is an unbounded amplification of that source (the - ``norm(g(b) - V^-1 N(V b))`` inequality). Local re-anchoring is what keeps it - bounded at all: the picture is re-anchored at every accepted step, so no inverse - action is ever taken over more than one of them. - - - ``pair``: the forward and inverse actions over the whole step. - - ``dz``: length of the step, m, used in the refusal. - """ - forward, inverse = pair - if not forward.size: - return - measured = np.linalg.norm(forward, ord=2, axis=(-2, -1)) * np.linalg.norm( - inverse, ord=2, axis=(-2, -1) - ) - _refuse_flow_conditioning(flow, section, measured, dz, backend=backend) - - -def _refuse_flow_conditioning( - flow: _CoupledFlow, - section: int, - measured: Float[np.ndarray, " n_active_m"], - dz: float, - *, - backend: str = "numpy_ref", -) -> None: - """Refuse a step whose measured ``norm(U) norm(U^-1)`` exceeds the certificate. - - The decision of :func:`_check_flow_conditioning`, on a measurement made - elsewhere: a compiled backend measures the two spectral norms in its own - kernels and hands the per-bin products here, so every backend - compares them with the declared row by the same allowance and refuses in the same - words. - - - ``dz``: length of the step, m, used in the refusal. - """ - declared = flow.condition_bound[section] - # A bin whose block is normal has a bound of exactly one and a measured product - # that is one to within the rounding of two spectral norms; the allowance is that - # rounding and nothing more, because the bound is a true bound on the exact - # action and any excess above it is arithmetic. - allowance = 1.0 + 64.0 * flow.n_modes * float(np.finfo(float).eps) - excess = measured / (declared * allowance) - worst = int(np.argmax(excess)) - if excess[worst] > 1.0: - msg = ( - # Enough digits, and the ratio itself: the two quantities differ by as - # little as 1e-13 at the step that first exceeds the bound, and `.4g` - # printed both as the same number with no excess to read. - f"{backend} measured a coupled flow conditioning of " - f"{float(measured[worst]):.12g} over a step of {dz:.4g} m, above the " - f"{float(declared[worst]):.12g} the certificate declares at " - f"active bin {worst} of section {section} -- exceeding it by a factor " - f"{float(excess[worst]):.12g} of the rounding allowance: the inverse " - "action carries the nonlinear source back by the measured factor. Lower " - "dz_max, which is what the bound was declared over" - ) - raise BackendError(msg) - - -def _coupled_flow_maps(problem: PropagationProblem) -> _CoupledFlow | None: - """Decompose the coupled flow this backend will execute, once. - - - Returns: the Schur factors and the certificate, or ``None`` for a problem carrying - no coupled flow. - """ - flow = problem.linear.coupled_flow - if flow is None: - return None - assert flow.generator is not None - factors = coupled_flow_factors(flow) - active, residual = factors.active, factors.residual_terms - sections = len(flow.section_methods) - held = _CoupledFlow( - **vars(factors), - residual_bins=active & problem.grids.inband_mask, - n_modes=flow.n_modes, - ) - logger.debug( - "coupled flow: %d channel(s) on %d of %d bins over %d section(s), %s, largest " - "declared conditioning %.3e, largest declared residual %.3e 1/m, largest " - "declared representation error %.3e", - held.n_modes, - int(np.count_nonzero(active)), - len(active), - sections, - "no explicit residual" if residual is None else f"{residual.shape[0]} terms", - float(np.max(held.condition_bound, initial=1.0)), - float(np.max(flow.residual_norm_bound)), - float(np.max(flow.generator_error)), - ) - return held - - -def _harmonic_carrier( - problem: PropagationProblem, -) -> Complex[np.ndarray, " n_to"] | None: - """Return ``exp(2 i omega_0 t)`` on the fine grid when the harmonic is radiated. - - The envelope-grid third-harmonic term needs the carrier the coarse grid does not - resolve. Until contract version 3 the contract carried neither it nor a fine time - axis and a backend built it from ``omega0``, ``n_to`` and ``dt_fine`` -- one piece - of physics inside a backend, against ``docs/dev/architecture.md`` section 3, which - is why it now arrives as ``grids.carrier_2w0``. The sign is the FFT convention's - (``docs/guide/media/nonlinear.md``). ``validate`` refuses a harmonic term without - the carrier, so only a hand-built problem reaches the refusal here. - - - Returns: the carrier of shape ``(n_to,)``, or ``None`` when no harmonic term is - present. - """ - if not problem.responses.harmonic_carrier: - return None - if problem.grids.carrier_2w0 is None: - msg = ( - "a third-harmonic Kerr term is compiled and grids.carrier_2w0 is absent; " - "the envelope's harmonic sits an offset 2 omega_0 from its carrier and the " - "response pass cannot place it without the factor" - ) - raise BackendError(msg) - return problem.grids.carrier_2w0 - - -def _embedded_projection( - problem: PropagationProblem, -) -> Float[np.ndarray, "n_modes n_columns"] | None: - """Return the embedded coarse-rule projection, when the quadrature has one. - - ``transform.projection_coarse`` equals ``transform.projection`` when the rule has no - embedded pair, in which case the difference of the two projections is identically - zero and reading it as convergence would be wrong - (:class:`solprop.modes.quadrature.ModeMatrices`). The alarm reports ``nan`` there - instead, and the second projection is not computed at all. - - - Returns: the coarse projection, or ``None`` when it is the fine one. - """ - transform = problem.transform - if np.array_equal(transform.projection, transform.projection_coarse): - return None - return transform.projection_coarse diff --git a/src/solprop/backends/numpy_ref/engines.py b/src/solprop/backends/numpy_ref/engines.py new file mode 100644 index 000000000..e9e9b3776 --- /dev/null +++ b/src/solprop/backends/numpy_ref/engines.py @@ -0,0 +1,280 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""The reference's Runge-Kutta engine over its workspace (SEP 52 section 5.2). + +:class:`NumpyRungeKutta` is the reference's +:class:`~solprop.backends.engines.RungeKuttaEngine`, the counterpart of native's +``engines::ResidentRungeKutta``: it forms an interaction-picture embedded Runge-Kutta +trial from the workspace's committed state and keeps the trial's stages and end state +until :meth:`~NumpyRungeKutta.accept` finishes and commits it. A rejected trial leaves +the committed state as it was. The reference's other engines are the low-storage step +(:class:`solprop.backends.low_storage.HostLowStorage`) and the Adams history +(:class:`solprop.backends.numpy_ref.multistep.HostHistory`). +""" + +import numpy as np +from jaxtyping import Complex + +from solprop.backends.engines import AcceptRecord, BoundaryReading +from solprop.backends.numpy_ref import passes +from solprop.backends.numpy_ref.workspace import NumpyWorkspace +from solprop.exceptions import BackendError +from solprop.stepper.tableau import ( + Tableau, + extension_coefficients, + extension_value, +) + +__all__ = ["NumpyRungeKutta"] + +_State = Complex[np.ndarray, "n_modes n_pol n_omega"] + + +class NumpyRungeKutta: + """The interaction-picture embedded Runge-Kutta trial over a workspace. + + Every stage is evaluated. The tableau's first-same-as-last property would let the + last stage of one step serve as the first of the next, after rebasing it by + ``exp(dPhi)`` because the interaction picture is re-anchored every step; the + reference does not take that saving, so that no stage it uses depends on the + bookkeeping of the step before (``docs/dev/stepper.md`` section 10, trap 10). + + Parameters + ---------- + workspace : solprop.backends.numpy_ref.workspace.NumpyWorkspace + The workspace whose state is stepped. + tableau : solprop.stepper.tableau.Tableau + The embedded pair. + + Attributes + ---------- + evaluations : int + Physical source evaluations of the trials since :meth:`reset`, rejected trials + included (SEP 30 records work rather than estimating it from steps). + """ + + def __init__(self, workspace: NumpyWorkspace, tableau: Tableau) -> None: + """Hold the workspace; no trial is held yet.""" + self._workspace = workspace + self._tableau = tableau + self._trial: tuple[_State, list[_State]] | None = None + self._extension: tuple[float, float, list[np.ndarray]] | None = None + self.evaluations = 0 + + def reset(self) -> None: + """Forget the held trial and extension and the count: a state was loaded.""" + self._trial = None + self._extension = None + self.evaluations = 0 + + @property + def in_flight(self) -> bool: # numpydoc ignore=RT01 + """Whether a trial overwrote the committed state; never, on this engine.""" + return False + + @property + def trial_state(self) -> _State: # numpydoc ignore=RT01 + """The held trial's raw end state, before the accepted step's finish.""" + if self._trial is None: + raise BackendError("take a trial before reading its state") + return self._trial[0] + + @property + def stages(self) -> list[_State]: # numpydoc ignore=RT01 + """The held trial's stage derivatives, in its anchor's frame.""" + if self._trial is None: + raise BackendError("take a trial before reading its stages") + return list(self._trial[1]) + + def trial(self, z: float, dz: float) -> float: + """Form a trial from the committed state at `z` over `dz`; return its norm. + + A problem carrying ``linear.coupled_flow`` multiplies each stage's scalar + propagator by the section's Schur matrix-function action; the two factors + commute, so their product is the flow of the sum. A ``"frozen_residual"`` flow + adds the explicit residual to each stage's lab-frame source, before the + interaction picture's own factors carry it back, so it is integrated by the + embedded pair exactly as the material response is. + + Parameters + ---------- + z : float + Where the trial starts, m. + dz : float + The step, m, positive. + + Returns + ------- + float + The scaled error norm of the step's embedded difference. + """ + workspace = self._workspace + state = workspace.committed() + workspace.hoist(z) + tableau = self._tableau + # The whole step and every stage, read together: each table once. + workspace.stage_bundles( + z, [z + dz, *(z + float(node) * dz for node in tableau.nodes)] + ) + exponents = workspace.exponents(z, dz) + step = workspace.stage_scalars(z, z + dz) + actions = workspace.flow_actions(step.flow_section, dz) + stages: list[_State] = [] + 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]), + ) + bundle = workspace.stage_scalars(z, z + fraction * dz) + exponent = exponents(fraction, bundle) + forward, inverse = actions(fraction) + lab = passes.stage_input( + workspace.channels(state, forward), + workspace.channels(combination, forward), + dz, + np.exp(exponent), + workspace.noise_at(bundle), + ) + back = np.exp(-exponent) + self.evaluations += 1 + drive = workspace.nonlinear(lab, bundle, back) + residual = workspace.residual(lab, step.flow_section, bundle) + if residual is not None: + drive = drive + back * residual + stage = workspace.channels(drive, inverse) + 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(exponents(1.0, step)) + whole = actions(1.0)[0] + advanced = passes.accept_step( + workspace.channels(state, whole), + propagator, + dz, + workspace.channels(solution, whole), + ) + # The embedded difference is carried to the end of the step by the same + # exponential as the solution, so the norm scales the local error of the + # propagated state rather than of the interaction variable. + norm = workspace.error_norm( + propagator * (dz * workspace.channels(error, whole)), state, advanced + ) + # Kept for the accept, and for the continuous extension of an accepted step + # (SEP 14 phase 3). + self._trial = (advanced, stages) + return norm + + def accept(self, dz: float) -> AcceptRecord: + """Finish the held trial and commit it as the workspace's state. + + Parameters + ---------- + dz : float + The accepted step, m. + + Returns + ------- + solprop.backends.engines.AcceptRecord + The finish's split collar's sums. + """ + finished, record = self._workspace.finish(self.trial_state, dz) + self._workspace.install(finished) + return record + + def extend(self, z: float, dz: float) -> None: + """Hold the held trial's continuous extension, before it is accepted. + + With ``v0`` the state at the step's anchor, ``k_i`` its stage derivatives in + the anchor's frame and ``v1 = v0 + h sum_i b_i k_i``, the coefficients are + DOPRI5's (Hairer, Noersett and Wanner, II.6): ``v0``, ``v1 - v0``, ``h k1 - (v1 + - v0)``, ``(v1 - v0) - h k7 - (h k1 - (v1 - v0))`` and ``h sum_i d_i k_i``. + + Parameters + ---------- + z : float + Where the trial started, m. + dz : float + The step, m. + """ + workspace = self._workspace + start = workspace.committed().reshape(workspace.problem.shape) + coefficients = extension_coefficients(self._tableau, start, self.stages, dz) + self._extension = (z, dz, coefficients) + + def observe(self, position: float) -> _State: + """Return the masked field at `position` inside the held extension's step. + + Interpolated by the continuous extension and carried to `position` by the + exact linear flow; no source is evaluated. + + Parameters + ---------- + position : float + The plane, m, inside the extended step. + + Returns + ------- + numpy.ndarray + The field in the state's layout. + """ + if self._extension is None: + raise BackendError("no accepted step is held for a dense observation") + workspace = self._workspace + z, dz, coefficients = self._extension + start = coefficients[0] + value = extension_value(coefficients, (position - z) / dz) + # A bin the linear flow attenuates or amplifies by more than an e-fold over the + # step -- the spectral collar's, outside the controlled band -- has an + # interaction-picture derivative growing exponentially across it, which no + # polynomial in theta follows: interpolated there it returns orders of + # magnitude more than the field. Its source is negligible beside its own loss, + # so the anchor's linear flow is its honest value. + stiff = ( + np.abs(np.real(workspace.delta_phi(workspace.stage_scalars(z, z + dz)))) + > 1.0 + ) + value = np.where(stiff, start, value) + return workspace.mask(workspace.propagator(z, position) * value) + + def hold(self) -> object: + """Return the committed state, to restore after a dense observation. + + Returns + ------- + object + The workspace's state array. + """ + return self._workspace.committed() + + def restore(self, z: float, held: object) -> None: + """Make a held or observed state the workspace's committed state. + + Parameters + ---------- + z : float + Its position, m. + held : object + The array. + """ + del z + self._workspace.install(held) # pyright: ignore[reportArgumentType] + + def reading(self) -> BoundaryReading: + """Return the committed state's boundary reading. + + Returns + ------- + solprop.backends.engines.BoundaryReading + The workspace's reading. + """ + return self._workspace.reading() diff --git a/src/solprop/backends/numpy_ref/multistep.py b/src/solprop/backends/numpy_ref/multistep.py index fe3c2805e..47e8664de 100644 --- a/src/solprop/backends/numpy_ref/multistep.py +++ b/src/solprop/backends/numpy_ref/multistep.py @@ -44,21 +44,27 @@ import logging import math -from collections.abc import Callable, Mapping +from collections.abc import Callable, Mapping, Sequence from dataclasses import dataclass, field -from typing import Any, Literal, Protocol, cast +from typing import TYPE_CHECKING, Any, Literal, cast import numpy as np -from jaxtyping import Complex +from jaxtyping import Bool, Complex, Float from scipy.linalg import expm from solprop._helpers import PLAIN, Helpers +from solprop.backends.adams_core import Stencil +from solprop.backends.engines import ( + AcceptRecord, + AttemptOutcome, + BoundaryReading, + HistoryEntry, +) from solprop.backends.exponential import ( CarrierReference, carrier_reference, phi_functions, ) -from solprop.backends.host.driver import HostDriver from solprop.backends.ledger import source_absent from solprop.backends.numpy_ref import passes from solprop.exceptions import BackendError @@ -69,8 +75,11 @@ ) from solprop.translate.linop import phi_rate +if TYPE_CHECKING: + from solprop.backends.numpy_ref.workspace import NumpyWorkspace + from solprop.stepper.controller import PIController + __all__ = [ - "AdamsEngine", "AdamsKernels", "CoupledBlock", "CoupledExponentialKernels", @@ -1262,253 +1271,25 @@ def observation( return [1.0, *self.nodes[:order]], [self.endpoint.copy(), *history] -class AdamsEngine(Protocol): - """What an Adams march asks of the engine that holds its history (SEP 16). - - The march keeps the controller; an engine keeps the history's rows and does every - state-sized operation, so that a backend can keep them where its state lives. - :class:`HostHistory` is the reference; ``docs/dev/stepper.md`` states the contract. - SEP 52's phase 3 replaces it with :class:`solprop.backends.engines.AdamsEngine`, - which mirrors the native ``march::Engine``. - """ - - dense: Any - """The interaction formulation's last accepted step (a ``_DenseStep`` or ``None``), - for observation.""" - - compensated: bool - """Whether trials carry a varying operator's linear compensation (SEP 16 4.2).""" - - carrier: CarrierReference | None - """The run's carrier frame (SEP 35), or ``None`` when off; an exponential trial - removes its phase from the samples it reads.""" - - @property - def n_slots(self) -> int: # numpydoc ignore=RT01 - """The history store's rows.""" - ... - - def reset(self) -> None: - """Forget the last accepted step and any trial in flight.""" - ... - - def hold(self) -> object: - """Return the accepted state, to restore after a dense observation. - - Returns - ------- - object - A handle :meth:`restore` takes. - """ - ... - - def restore(self, z: float, held: object) -> None: - """Make a held accepted state current again at `z`. - - Parameters - ---------- - z : float - Its position, m. - held : object - What :meth:`hold` returned. - """ - ... - - def start(self, z: float) -> _State | None: - """Evaluate the history's first sample at the accepted state into row zero. - - Parameters - ---------- - z : float - The accepted position, m. - - Returns - ------- - numpy.ndarray or None - The sample on the host, or ``None`` when the rows are resident. - """ - ... - - def value(self, slot: int) -> _State | None: - """Return a store row on the host, or ``None`` when the rows are resident. - - Parameters - ---------- - slot : int - The row. - - Returns - ------- - numpy.ndarray or None - The row, or ``None``. - """ - ... - - def fused_trial( # noqa: PLR0917 - called positionally - self, - z: float, - dz: float, - nodes: list[float], - slots: np.ndarray, - order: int, - orders: list[int], - ) -> np.ndarray: - """Form an interaction-formulation trial; return its scored norms. - - Parameters - ---------- - z, dz : float - The anchor and the step, m. - nodes : list of float - The history's normalised positions, newest first. - slots : numpy.ndarray - Their store rows, ``int64``. - order : int - The step's order. - orders : list of int - The orders scored, the step's own first. - - Returns - ------- - numpy.ndarray - One scaled norm per scored order. - """ - ... - - def fused_accept(self, keep: np.ndarray, free: int, *, interpolate: bool) -> None: - """Adopt the held interaction-formulation trial. - - Parameters - ---------- - keep : numpy.ndarray - The history rows kept, ``int64``. - free : int - The row the new sample takes. - interpolate : bool - Whether the step's interpolant is kept for dense observation. - """ - ... - - def exponential_trial( # noqa: PLR0917 - called positionally - self, - z: float, - dz: float, - nodes: list[float], - slots: np.ndarray, - order: int, - orders: list[int], - ) -> np.ndarray: - """Form an exponential trial; return its scored norms. - - Parameters - ---------- - z, dz : float - The anchor and the step, m. - nodes : list of float - The history's normalised positions, newest first. - slots : numpy.ndarray - Their store rows, ``int64``. - order : int - The step's order. - orders : list of int - The orders scored, the step's own first. - - Returns - ------- - numpy.ndarray - One scaled norm per scored order. - """ - ... - - def exponential_accept( - self, keep: np.ndarray, free: int, *, interpolate: bool - ) -> None: - """Adopt the held exponential trial. - - Parameters - ---------- - keep : numpy.ndarray - The history rows kept, ``int64``. - free : int - The row the new sample takes. - interpolate : bool - Whether the step's interpolant is kept for dense observation. - """ - ... - - def snapshot_rows(self) -> dict[str, np.ndarray]: - """Return host copies of the rows a resume needs to continue the history. - - Returns - ------- - dict - The rows by name, each ``(n_slots, *shape)``, in the engine's own names - (``HostHistory.snapshot_rows`` states the host engine's). - """ - ... - - def snapshot_nbytes(self) -> int: - """Return the bytes :meth:`snapshot_rows` would copy, copying nothing. - - Returns - ------- - int - The size of every row. - """ - ... - - def load_rows(self, rows: Mapping[str, np.ndarray], shape: tuple[int, ...]) -> None: - """Install rows :meth:`snapshot_rows` returned, refusing rows it does not keep. - - Parameters - ---------- - rows : collections.abc.Mapping - The rows, by name. - shape : tuple of int - The state's shape. - - Raises - ------ - BackendError - If the rows are another engine's, missing, or of the wrong shape; nothing - is installed then. - """ - ... - - def observe(self, position: float) -> object: - """Return the masked field at `position` inside the last accepted step. - - Parameters - ---------- - position : float - The observation, m. - - Returns - ------- - object - The field, as the backend holds a state. - """ - ... - - class HostHistory: """The Adams history and its field arithmetic, on host arrays (SEP 16 phase 3b). - The march (:class:`~solprop.backends.host.adams.HostAdamsMarch`) keeps the - controller -- the orders, the slots, rejection, - restarts, the budget and the ledger -- and hands every state-sized operation to an - engine: the startup sample, a trial's predictor, source, corrector and defect - norms, the adoption and transport of an accepted step, and dense observation. This - engine holds the history in a NumPy store and applies the given kernels; a backend - may supply its own, as the native backend keeps the history resident in its - state (``_ResidentAdams``). Between a trial and its acceptance the engine - holds the trial; nothing else is carried across calls but the store and the last - accepted step for dense observation. + The reference's :class:`~solprop.backends.engines.AdamsEngine` (native's + ``march::Engine``, SEP 52 section 5.2). The march + (:class:`~solprop.backends.host.adams.HostAdamsMarch`) keeps the controller -- the + orders, the entries, rejection, restarts, the budget and the ledger -- and hands + every state-sized operation to this engine over the workspace: the startup sample, + a trial's predictor, source, corrector and defect norms, and the adoption and + transport of an accepted step. The engine holds the history's rows in a NumPy + store; between a trial and its acceptance it holds the trial. Beside the protocol + it still holds the last accepted step for dense observation (:meth:`hold`, + :meth:`restore`, :meth:`observe`) and the rows a snapshot carries, which SEP 52 + moves to the session. Parameters ---------- - backend : solprop.backends.host.driver.HostDriver - The backend whose state, source evaluation and propagators are used. + workspace : solprop.backends.numpy_ref.workspace.NumpyWorkspace + The workspace whose state, source evaluation and propagators are used. method : solprop.stepper.multistep.Multistep The method. kernels : AdamsKernels @@ -1517,23 +1298,29 @@ class HostHistory: The exponential formulation's arithmetic, ``None`` for the interaction one. compensation : {'transported', 'untransported'} A varying operator's compensation treatment (SEP 16 Q8). + interpolate : bool, optional + Whether an accepted step keeps its interpolant for dense observation. """ def __init__( self, - backend: HostDriver[Any], + workspace: "NumpyWorkspace", method: Multistep, kernels: AdamsKernels, exponential: ExponentialKernels | None, compensation: Literal["transported", "untransported"], + *, + interpolate: bool = False, ) -> None: - """Hold the backend, the kernels and an empty store.""" - self._backend = backend + """Hold the workspace, the kernels and an empty store.""" + self._workspace = workspace self._method = method self._kernels = kernels self._exponential = exponential self._compensation = compensation - linear = backend._problem.linear + self._interpolate = interpolate + self._controller = workspace.stepper.controller + linear = workspace.problem.linear # SEP 16 phase 4: a varying operator's linear compensation, integrated in the # reference flow's frame (Q8); the untransported treatment is a test witness. # A structurally absent source takes the exact chord instead (section 4.2). @@ -1545,7 +1332,7 @@ def __init__( residual or ( linear.phi_representation in ("expansion", "table") - and not source_absent(backend._problem) + and not source_absent(workspace.problem) ) ) if self.compensated and flow is not None and compensation != "transported": @@ -1564,12 +1351,16 @@ def __init__( # it reads, from a reference fixed for the run; None when off. An inert one # (sigma = 0) takes the unshifted arithmetic exactly. self.carrier: CarrierReference | None = ( - None if exponential is None else carrier_reference(backend._problem, method) + None + if exponential is None + else carrier_reference(workspace.problem, method) ) if self.carrier is not None: logger.info( "carrier frame %r: %s", self.carrier.policy, self.carrier.reason ) + # The last exponential trial's carrier shift and row rotations (SEP 35). + self._carrier_rows: tuple[np.ndarray, np.ndarray] | None = None def reset(self) -> None: """Forget the last accepted step and any trial in flight.""" @@ -1593,7 +1384,7 @@ def hold(self) -> object: object The backend's host copy of the accepted state. """ - return self._backend._adams_state() + return self._workspace.committed() def restore(self, z: float, held: object) -> None: """Make a held accepted state current again at `z`. @@ -1605,33 +1396,29 @@ def restore(self, z: float, held: object) -> None: held : object What :meth:`hold` returned. """ - self._backend._adams_restore(z, cast("_State", held)) + del z + self._workspace.install(cast("_State", held)) # --- startup ---------------------------------------------------------------------- - def start(self, z: float) -> _State: + def start(self, z: float) -> None: """Evaluate the source at the accepted state, the history's first sample. - The sample goes to the store's row zero. + The sample goes to the store's row zero: the transported source in the + interaction formulation, the untransported one in the exponential formulation. Parameters ---------- z : float The accepted position, m. - - Returns - ------- - numpy.ndarray - The sample: the transported source in the interaction formulation, the - untransported one in the exponential formulation. """ - backend = self._backend - state = backend._adams_state() - backend._hoist(z) + workspace = self._workspace + state = workspace.committed() + workspace.hoist(z) if self._exponential is not None: - value = backend._adams_lab_source(state, z, purpose="startup") + value = workspace.lab_source(state, z, purpose="startup") else: - value, _ = backend._adams_source(state, z, z, purpose="startup") + value, _ = workspace.source(state, z, z, purpose="startup") if self._store is None or self._store.shape[1:] != value.shape: # Zeroed, not empty: the rows a short history has not reached go into a # resume snapshot as they are, and a file has to be reproducible. @@ -1646,13 +1433,147 @@ def start(self, z: float) -> _State: # that restarted the history. self._states[0] = state self._rates[0] = phi_rate( - backend._problem.linear, z, helpers=backend.helpers + workspace.problem.linear, z, helpers=workspace.helpers ) # A frozen-residual flow's weights at the sample, on the far side too. - start = cast("CoupledBlock | None", backend._adams_block(z, 0.0)) + start = cast("CoupledBlock | None", workspace.coupled_block(z, 0.0)) self._weights = [None] * self.n_slots self._weights[0] = None if start is None else start.end_weights - return self._store[0] + + # --- the protocol's trial and accept ------------------------------------------- + + def trial( + self, z: float, dz: float, stencil: Stencil + ) -> Float[np.ndarray, " n_orders"]: + """Form a trial from `z` over `dz`; return its scored orders' norms. + + The method's own formulation's trial (:meth:`fused_trial`, + :meth:`exponential_trial`), held for :meth:`accept`. + + Parameters + ---------- + z : float + Where the trial starts, m. + dz : float + The step, m. + stencil : solprop.backends.adams_core.Stencil + The history's nodes and rows, newest first, and the orders scored. + + Returns + ------- + numpy.ndarray + One scaled norm per scored order, the step's own first. + """ + trial = ( + self.fused_trial if self._exponential is None else self.exponential_trial + ) + return trial(z, dz, stencil.nodes, stencil.rows, stencil.order, stencil.orders) + + def accept( + self, dz: float, free: int, stencil: Stencil, kept: Sequence[HistoryEntry] + ) -> AcceptRecord: + """Adopt the held trial; the new sample takes row `free`. + + Parameters + ---------- + dz : float + The accepted step, m. + free : int + The history row the new sample takes. + stencil : solprop.backends.adams_core.Stencil + The trial's stencil. + kept : collections.abc.Sequence of solprop.backends.engines.HistoryEntry + The history the step keeps, oldest first, which the interaction + formulation transports. + + Returns + ------- + solprop.backends.engines.AcceptRecord + The finish's split collar's sums. + """ + del dz, stencil # the held trial carries both + rows = np.array([entry.row for entry in kept], dtype=np.int64) + adopt = ( + self.fused_accept if self._exponential is None else self.exponential_accept + ) + return adopt(rows, free, interpolate=self._interpolate) + + def chord_phase(self, z1: float, z2: float) -> float: + """Return the carrier chord's largest phase over ``[z1, z2]``. + + Parameters + ---------- + z1, z2 : float + The interval, m. + + Returns + ------- + float + The phase, rad; 0.0 without a carrier frame. + """ + carrier = self.carrier + return 0.0 if carrier is None else carrier.chord_phase(z1, z2) + + def step_carrier(self, order: int) -> Float[np.ndarray, " n_rotations"]: + """Return the last trial's carrier rotations over its `order` newest rows. + + Packed as native's are: the shift's imaginary part, then each row's rotation as + its real and imaginary parts. + + Parameters + ---------- + order : int + The rows the dense observation's formula reads. + + Returns + ------- + numpy.ndarray + The rotations, empty without an active carrier frame. + """ + if self._carrier_rows is None: + return np.zeros(0) + shift, factors = self._carrier_rows + rows = [float(np.imag(shift).reshape(-1)[0])] + for factor in factors[:order]: + value = complex(np.asarray(factor).reshape(-1)[0]) + rows += [value.real, value.imag] + return np.array(rows) + + def begin_attempt(self, cost: int) -> None: + """Reserve the attempt's host-source calls (SEP 49 section 6.2). + + Parameters + ---------- + cost : int + The attempt's logical response calls. + """ + self._workspace.reserve_calls(cost) + + def end_attempt(self, outcome: AttemptOutcome) -> None: + """Release the reservation's rest and record a decided attempt's outcome. + + Parameters + ---------- + outcome : solprop.backends.engines.AttemptOutcome + How the attempt ended; an abandoned one only releases. + """ + try: + if outcome != AttemptOutcome.ABANDONED: + self._workspace.record_trial( + accepted=outcome == AttemptOutcome.ACCEPTED + ) + finally: + self._workspace.release_calls() + + def reading(self) -> BoundaryReading: + """Return the committed state's boundary reading. + + Returns + ------- + solprop.backends.engines.BoundaryReading + The workspace's reading. + """ + return self._workspace.reading() # --- the interaction formulation's fused path ------------------------------------- @@ -1690,18 +1611,18 @@ def fused_trial( # noqa: PLR0917 - called positionally numpy.ndarray One scaled norm per scored order. """ - backend, kernels = self._backend, self._kernels + workspace, kernels = self._workspace, self._kernels store = self._store assert store is not None - state = backend._adams_state() - backend._hoist(z) - propagator = backend._adams_propagator(z, z + dz) + state = workspace.committed() + workspace.hoist(z) + propagator = workspace.propagator(z, z + dz, hold=True) predictor = kernels.weights(nodes[:order]) lab = kernels.predict(state, propagator, store, slots[:order], predictor, dz) - source, _ = backend._adams_source(lab, z, z + dz, purpose="predictor") + source, _ = workspace.source(lab, z, z + dz, purpose="predictor") rows, corrector = _defect_rows(kernels, nodes, orders) width = rows.shape[1] - mask = backend._problem.grids.norm_mask + mask = workspace.problem.grids.norm_mask advanced, norms = kernels.correct( state, propagator, @@ -1712,7 +1633,7 @@ def fused_trial( # noqa: PLR0917 - called positionally rows, dz, mask, - _divisor(backend, state), + _divisor(mask, self._controller, state), ) self._fused_trial = _FusedTrial( z=z, @@ -1727,7 +1648,9 @@ def fused_trial( # noqa: PLR0917 - called positionally ) return norms - def fused_accept(self, keep: np.ndarray, free: int, *, interpolate: bool) -> None: + def fused_accept( + self, keep: np.ndarray, free: int, *, interpolate: bool + ) -> AcceptRecord: """Adopt the held fused trial: the state, its interpolant, the new sample. Parameters @@ -1738,12 +1661,17 @@ def fused_accept(self, keep: np.ndarray, free: int, *, interpolate: bool) -> Non The row the new sample takes. interpolate : bool Whether the step's interpolant is kept for dense observation. + + Returns + ------- + solprop.backends.engines.AcceptRecord + The finish's split collar's sums. """ trial = self._fused_trial store = self._store assert trial is not None and store is not None self._fused_trial = None - self._backend._adams_adopt(trial.advanced, trial.dz) + record = self._adopt(trial.advanced, trial.dz) order = trial.order if interpolate: # Copied before the transport re-anchors the rows in place: the step's own @@ -1760,6 +1688,13 @@ def fused_accept(self, keep: np.ndarray, free: int, *, interpolate: bool) -> Non slopes=slopes, ) self._kernels.transport(store, keep, trial.propagator, free, trial.source) + return record + + def _adopt(self, advanced: _State, dz: float) -> AcceptRecord: + """Finish an accepted step's state and commit it as the workspace's.""" + finished, record = self._workspace.finish(advanced, dz) + self._workspace.install(finished) + return record def value(self, slot: int) -> _State: """Return a store row, for the history entry that names it. @@ -1842,7 +1777,7 @@ def load_rows(self, rows: Mapping[str, np.ndarray], shape: tuple[int, ...]) -> N ) foreign = sorted(set(rows) - kept) if foreign: - name = self._backend.name + name = self._workspace.name if "applied" in foreign: msg = ( f"the {name} backend cannot continue this Adams history: the " @@ -1915,22 +1850,22 @@ def exponential_trial( # noqa: PLR0917 - called positionally numpy.ndarray One scaled norm per scored order. """ - backend, kernels = self._backend, self._exponential + workspace, kernels = self._workspace, self._exponential assert kernels is not None store = self._store assert store is not None - state = backend._adams_state() - backend._hoist(z) + state = workspace.committed() + workspace.hoist(z) width = 1 + max(orders) # The exponent is the backend's own increment of Phi over the step, so the # flow below is exactly the propagator the interaction formulation applies. # Copied: a z table's host evaluator returns its own reused buffer, which the # source evaluation writes again. - exponent = np.array(backend._delta_phi(backend._stage_scalars(z, z + dz))) + exponent = np.array(workspace.delta_phi(workspace.stage_scalars(z, z + dz))) # A coupled section's step (SEP 16 phase 5): its flow and moments are matrix # functions of the frozen block on the bins that carry one, applied by the # reference passes. - block = cast("CoupledBlock | None", backend._adams_block(z, dz)) + block = cast("CoupledBlock | None", workspace.coupled_block(z, dz)) # SEP 35 section 4.1: with F(z_n + s) = exp(-sigma (1 - s/h)) G(s), the # step interpolates G_j = exp(sigma (1 - theta_j)) F_j and integrates it # against the moments at x - sigma; exact for any sigma, the flow untouched. @@ -1952,7 +1887,9 @@ def exponential_trial( # noqa: PLR0917 - called positionally moments, store, rows_read[:order], - lagrange_coefficients(nodes[:order], check=False, helpers=backend.helpers), + lagrange_coefficients( + nodes[:order], check=False, helpers=workspace.helpers + ), dz, **rotation, ) @@ -1964,13 +1901,15 @@ def exponential_trial( # noqa: PLR0917 - called positionally if shift is not None: compensation.rotate(shift) lab = lab + compensation.predictor(order) - source = backend._adams_lab_source(lab, z + dz, purpose="predictor") - corrector = _exponential_corrector(nodes, order, width, helpers=backend.helpers) + source = workspace.lab_source(lab, z + dz, purpose="predictor") + corrector = _exponential_corrector( + nodes, order, width, helpers=workspace.helpers + ) rows = kernels.defect_rows(nodes, orders, width) extra = None if compensation is not None: rate = phi_rate( - backend._problem.linear, z + dz, before=True, helpers=backend.helpers + workspace.problem.linear, z + dz, before=True, helpers=workspace.helpers ) residual = None if block is not None and block.residual is not None: @@ -1979,7 +1918,7 @@ def exponential_trial( # noqa: PLR0917 - called positionally compensation.add_endpoint(rate, lab, residual) self._trial_weights = None if block is None else block.end_weights extra = (compensation.corrector(order), compensation.defects(orders)) - mask = backend._problem.grids.norm_mask + mask = workspace.problem.grids.norm_mask advanced, norms = kernels.correct( state, flow, @@ -1991,7 +1930,7 @@ def exponential_trial( # noqa: PLR0917 - called positionally rows, dz, mask, - _divisor(backend, state), + _divisor(mask, self._controller, state), extra, **({} if factors is None else {"factors": factors}), ) @@ -2010,11 +1949,14 @@ def exponential_trial( # noqa: PLR0917 - called positionally shift=shift, factors=factors, ) + self._carrier_rows = ( + None if shift is None or factors is None else (shift, factors) + ) return norms def exponential_accept( self, keep: np.ndarray, free: int, *, interpolate: bool - ) -> None: + ) -> AcceptRecord: """Adopt the held exponential trial; the new sample takes row `free`. Parameters @@ -2025,13 +1967,18 @@ def exponential_accept( The row the new sample takes. interpolate : bool Whether the step's interpolant is kept for dense observation. + + Returns + ------- + solprop.backends.engines.AcceptRecord + The finish's split collar's sums. """ del keep # untransported samples are never re-anchored trial = self._exponential_trial store = self._store assert trial is not None and store is not None self._exponential_trial = None - self._backend._adams_adopt(trial.advanced, trial.dz) + record = self._adopt(trial.advanced, trial.dz) z, dz, order, slots = trial.z, trial.dz, trial.order, trial.slots compensation = trial.compensation if interpolate: @@ -2068,6 +2015,7 @@ def exponential_accept( self._rates[free] = compensation.endpoint_rate # One entry per slot, set with the startup sample or a resumed history. self._weights[free] = self._trial_weights + return record def _history_terms( self, exponent: _State, dz: float, slots: np.ndarray @@ -2124,7 +2072,7 @@ def _compensation_terms( # noqa: PLR0917 - called positionally carried=carried, dz=dz, treatment=self._compensation, - helpers=self._backend.helpers, + helpers=self._workspace.helpers, ) # --- dense observation ------------------------------------------------------------ @@ -2147,18 +2095,20 @@ def observe(self, position: float) -> object: return self._observe_exponential(position) step = cast("_DenseStep | None", self.dense) assert step is not None - backend = self._backend + workspace = self._workspace theta = (position - step.z) / step.dz weights = integrated_weights( - step.nodes, theta, check=False, helpers=backend.helpers + step.nodes, theta, check=False, helpers=workspace.helpers ) value = step.start + _combine(weights, step.slopes, step.dz) # A bin the linear flow changes by more than an e-fold over the step (the # spectral collar's) takes the anchor's linear flow: no polynomial follows its # exponentially growing derivative (as for the Runge-Kutta extension). - exponent = backend._delta_phi(backend._stage_scalars(step.z, step.z + step.dz)) + exponent = workspace.delta_phi( + workspace.stage_scalars(step.z, step.z + step.dz) + ) value = np.where(np.abs(np.real(exponent)) > 1.0, step.start, value) - return backend._apply_mask(backend._adams_propagator(step.z, position) * value) + return workspace.mask(workspace.propagator(step.z, position, hold=True) * value) def _observe_exponential(self, position: float) -> object: """Return the field at `position` inside the last accepted exponential step. @@ -2177,7 +2127,7 @@ def _observe_exponential(self, position: float) -> object: step = self._exponential_dense assert step is not None # One evaluation per plane: the reference passes serve every backend. - helpers = self._backend.helpers + helpers = self._workspace.helpers kernels = ExponentialKernels(helpers=helpers) xi = (position - step.z) / step.dz count = step.coefficients.shape[1] @@ -2211,7 +2161,7 @@ def _observe_exponential(self, position: float) -> object: ) damped = np.real(step.exponent) < -1.0 value = np.where(damped, np.exp(xi * step.exponent) * step.start, value) - return self._backend._apply_mask(value) + return self._workspace.mask(value) def _trial_propagators( # noqa: PLR0917 - called positionally @@ -2282,7 +2232,8 @@ def _rows_read( def _divisor( - backend: HostDriver[Any], + mask: Bool[np.ndarray, " n_omega"], + controller: "PIController", state: _State, ) -> np.ndarray: """Return the defect norm's scale per bin, the accepted state's before the step. @@ -2296,8 +2247,6 @@ def _divisor( - Returns: the scale of every bin, shape ``(n_omega,)``. """ - mask = backend._problem.grids.norm_mask - controller = backend._stepper.controller magnitude = float(np.linalg.norm(state[..., mask])) scale = controller.scale(magnitude, magnitude) return ( diff --git a/src/solprop/backends/numpy_ref/workspace.py b/src/solprop/backends/numpy_ref/workspace.py new file mode 100644 index 000000000..3ca1f31a3 --- /dev/null +++ b/src/solprop/backends/numpy_ref/workspace.py @@ -0,0 +1,3370 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""The reference's workspace: its state and every state-sized operation (SEP 52). + +:class:`NumpyWorkspace` holds one run's state and the problem's tables, and does every +operation a march, an engine or the session asks of the state: loading it, the stage +scalars and the source, the accepted step's finish, the band mask, the statistics, the +boundary monitor's and the transverse edge's readings, the quadrature alarm and the +host source's reservation. It holds no march state -- no position, proposal, history +or ledger -- and is reused across a scan's points, a load replacing its state. The +engines (:mod:`solprop.backends.numpy_ref.engines`, +:class:`~solprop.backends.numpy_ref.multistep.HostHistory`, +:class:`~solprop.backends.low_storage.HostLowStorage`) are what the marches ask of it. + +The contract is consumed only through its evaluation functions -- +:func:`solprop.translate.linop.delta_phi`, +:func:`solprop.translate.linop.unitary_phase`, +:func:`solprop.translate.responses.prefactor_at`, and the scalar tables +``responses.density`` and ``transform.taper_scale`` -- never through the coefficient +arrays, so the representation of the z tables can change without touching a backend. +""" + +import collections +import dataclasses +import functools +import logging +import math +from collections.abc import Callable, Iterator, Mapping, Sequence +from dataclasses import dataclass + +import numpy as np +from jaxtyping import Bool, Complex, Float, Inexact, Num + +from solprop._helpers import PLAIN, Helpers +from solprop.backends import tdse_source +from solprop.backends.engines import AcceptRecord, BoundaryReading +from solprop.backends.memory import adams_memory, reference_base_memory +from solprop.backends.node_chunk import ( + NodeChunkPlan, + general_planned_chunk, + plan_node_chunk, +) +from solprop.backends.numpy_ref import passes +from solprop.backends.numpy_ref.envelope_plasma import ( + envelope_populations, + envelope_sources, +) +from solprop.backends.numpy_ref.general_modal import ( + GeneralMaps, + general_memory, + general_source, +) +from solprop.backends.populations import axis_refusal, population_statistics +from solprop.backends.spatial import ( + FarFieldTables, + collect_spatial, + radial_absorber_matrix, + slab_columns, + slab_rows, + slab_synthesis, +) +from solprop.constants import EPS0, C +from solprop.exceptions import BackendError +from solprop.fourier import GridKind +from solprop.grid import TimeGrid +from solprop.modes.protocol import Mode +from solprop.modes.quadrature import mode_matrix, on_axis_rule +from solprop.monitor import BoundaryMonitor +from solprop.noise import NoiseRealisation +from solprop.output.capability import ( + declared_capability, + refusal_for, + withheld_accessors, +) +from solprop.output.records import SavedPlane +from solprop.profiles import ZProfile +from solprop.stats import ( + _POYNTING_STATISTICS, + CATALOGUE, + METRIC_WEIGHTED_STATISTICS, + ON_AXIS_PLASMA_STATISTICS, + PLASMA_INTEGRATION_STATISTICS, + WEIGHT_DEPENDENT_STATISTICS, + StatsSpec, + _poynting_statistics, + analytic_field, + collect, + weight_refusal_for, +) +from solprop.translate.coupled import ( + CoupledFlowFactors, + coupled_flow_factors, + metric_at, +) +from solprop.translate.general import ( + node_delayed_maps, + node_kerr_form, + node_kerr_tensor, +) +from solprop.translate.linop import delta_phi, power_weight_at, unitary_phase +from solprop.translate.masks import noise_spectrum +from solprop.translate.plasma_source import _BENCHMARK_GATED +from solprop.translate.problem import ( + PropagationProblem, + PropagatorMode, + StepperSettings, +) +from solprop.translate.responses import prefactor_at +from solprop.translate.routes import ( + flux_of, + tdse_of, + transverse_of, +) +from solprop.translate.run_request import RunRequest +from solprop.translate.spatial import separable_values +from solprop.translate.stage import ( + StageScalars, + anchor, + combine, + scalars, + scalars_at, + terms, +) +from solprop.translate.tdse import AtomicCallLedger, TDSEBinding, TDSEPurpose +from solprop.translate.tdse_source import ( + TDSE_UNAVAILABLE_STATISTICS, +) +from solprop.transverse_monitor import TransverseEdge, _EdgeReading + +__all__ = ["BlockResidual", "NumpyWorkspace", "SourceTables"] + +logger = logging.getLogger(__name__) + +_State = Complex[np.ndarray, "n_modes n_pol n_omega"] + + +class NumpyWorkspace: + """The reference's state and every state-sized operation on it (SEP 52 section 5.1). + + Built once per backend from the validated problem and request, and reused for every + run the backend serves: :meth:`load` replaces the state and everything that + describes it. It keeps no march state. The engines read and write the state only + through these operations, and the session (today the backend's step driver) reads + the statistics and the boundary readings from them. + + Parameters + ---------- + problem : solprop.translate.problem.PropagationProblem + The validated problem. + request : solprop.translate.run_request.RunRequest + Its run's request: the stepper's tableau and controller, which the trials read, + and the statistics, whose far-field tables are formed here. + chunk_plan : solprop.backends.node_chunk.NodeChunkPlan + The node chunk the response passes hold at once. + propagator_mode : {'tabulate', 'recompute'} + The resolved propagator mode: whether a step's exponents are kept for the step. + grid : solprop.grid.TimeGrid, optional + The grid the state lives on, which the statistics need. + modes : collections.abc.Sequence, optional + The propagated modes, in state order, for the statistics that need them. + profiles : collections.abc.Mapping, optional + The z-profiles keyed by statistic name. + tdse_binding : solprop.translate.tdse.TDSEBinding, optional + The host response binding a TDSE problem declares; ``None`` otherwise. + name : str, optional + The backend's name, for messages. + + Attributes + ---------- + collar_quiet : bool + Whether the modal stage leaves a quiet in-stage temporal collar out (SEP 21): + set by the session from the boundary monitor, read by every stage. + axis_scans : int + The on-axis plasma scans actually run (SEP 19), so that a test can see that a + rule with a node on the axis supplies that row instead of a fresh scan. + helpers : solprop._helpers.Helpers + The uncompiled stage-table and Adams-basis evaluations, ``PLAIN`` (SEP 29 + section 6.6). + """ + + helpers: Helpers = PLAIN + + def __init__( + self, + problem: PropagationProblem, + request: RunRequest, + *, + chunk_plan: NodeChunkPlan, + propagator_mode: PropagatorMode, + grid: TimeGrid | None = None, + modes: Sequence[Mode] | None = None, + profiles: Mapping[str, ZProfile] | None = None, + tdse_binding: TDSEBinding | None = None, + name: str = "numpy_ref", + ) -> None: + """Gather the problem's tables; no state is loaded yet.""" + self.name = name + self._problem = problem + self._stepper = request.stepper + self._chunk_plan = chunk_plan + self._propagator_mode = propagator_mode + self._grid = grid + self._modes = modes + self._profiles = profiles + self._state: _State | None = None + self._noise: _State | None = None + # The input draw rides in the state, a resumed one's too; the boundary monitor + # reads it as the vacuum floor beneath the light it judges (SEP 21, Q24). + self._input_floor: _State | None = None + self._clean_columns: Float[np.ndarray, " n_columns"] | None = None + self._monitor: BoundaryMonitor | None = None + self.collar_quiet = False + # The fixed arrays of the seam's device form, held for the whole run; the + # weights that multiply them are a bundle of host floats per stage. + self._terms = terms(problem) + # Hoisted per step by `hoist`; the entrance's until the first step asks. + self._anchor = anchor(problem, 0.0, helpers=self.helpers) + # A step's bundles taken together by `stage_bundles`, by anchor and position; + # `hoist` drops them. + self._prepared: dict[tuple[float, float], StageScalars] = {} + self._on_axis: Float[np.ndarray, "n_rows n_modes"] | None = None + self.axis_scans = 0 + self._axis_node: int | None = None + self._axis_node_known = False + self._tdse_binding = tdse_binding + self._tdse_last_purpose: TDSEPurpose | None = None + self._tdse_last_z: float | None = None + self._tdse_last_projection: dict[str, object] | None = None + self._gather(problem, request) + + def _gather(self, problem: PropagationProblem, request: RunRequest) -> None: + """Gather the tables and caches the stages and the statistics read.""" + self._statistics_power_weight = np.empty( + problem.shape if problem.transform.geometry is None else (0,) + ) + # Formed once, so a geometry the far-field statistics refuse is refused here, + # before any step (SEP 23 section 6). + self._far_field = FarFieldTables(problem, request.observation.stats) + self._gated_plasma = _BENCHMARK_GATED.get() + self._last_plasma: ( + tuple[np.ndarray, np.ndarray, np.ndarray | None, np.ndarray | None] | None + ) = None + self._kind: GridKind = problem.grid_kind + self._tables = SourceTables.of(problem) + self._carrier = _harmonic_carrier(problem) + self._embedded = _embedded_projection(problem) + self._general = _general_maps(problem, self._chunk_plan) + self._general_responds = self._general is not None and ( + bool(np.any(self._general.tensor)) or self._general.dispersive is not None + ) + self._flow = _coupled_flow_maps(problem) + self._block_residual: BlockResidual | None = None + self._flow_cache: ( + tuple[ + tuple[int, float], + dict[float, tuple[np.ndarray | None, np.ndarray | None]], + ] + | None + ) = None + self._last_projected: Num[np.ndarray, "n_modes n_pol n_to"] | None = None + self._last_coarse: Num[np.ndarray, "n_modes n_pol n_to"] | None = None + self._last_bundle: StageScalars | None = None + self._last_envelope: ( + tuple[np.ndarray, np.ndarray, np.ndarray | None, np.ndarray | None] | None + ) = None + self._raman_rates: tuple[float, ...] | None = None + self._raman_densities: tuple[float, ...] | None = None + self._raman_kernel: Complex[np.ndarray, "... n_omega_doubled"] | None = None + self._raman_transforms = 0 + self._alarm = math.nan + self._alarm_reported = False + # ADR-025's in-stage scheme is a second term on every stage rather than a + # factor on the accepted state, so a problem that has no response at all still + # has a derivative when it is active. + self._spatial_absorber = radial_absorber_matrix( + problem.transform, problem.grids.pad_scale + ) + self._in_stage_absorber = bool(self._spatial_absorber.size) or ( + problem.responses.temporal_absorber_fine is not None + and problem.responses.absorber_scheme == "nonlinear" + ) + geometry = problem.transform.geometry + if geometry is not None and geometry.kind in ("free", "slab"): + self._in_stage_absorber |= bool(np.any(geometry.absorber_rate)) + self._held: ( + tuple[float, float, StageScalars, Complex[np.ndarray, ...]] | None + ) = None + # The lab-frame source's unit "propagator": one element broadcast to the state's + # shape, so it holds no volume beside the state. + self._lab_frame = np.broadcast_to( + np.ones((), dtype=np.complex128), problem.shape + ) + + # --- the state --------------------------------------------------------------- + + @property + def problem(self) -> PropagationProblem: # numpydoc ignore=RT01 + """The problem the workspace was built for.""" + return self._problem + + @property + def stepper(self) -> StepperSettings: # numpydoc ignore=RT01 + """The run's stepper settings: the tableau, controller and schedule.""" + return self._stepper + + @property + def node_chunk(self) -> int: # numpydoc ignore=RT01 + """The nodes a response pass holds at once.""" + return self._chunk_plan.chunk + + @property + def state(self) -> _State | None: # numpydoc ignore=RT01 + """The committed state, internal units and FFT convention; ``None`` unloaded.""" + return self._state + + @property + def noise(self) -> _State | None: # numpydoc ignore=RT01 + """The ``modified`` noise model's realisation, or ``None`` with any other.""" + return self._noise + + @property + def input_floor(self) -> _State | None: # numpydoc ignore=RT01 + """The ``input`` noise draw the state carries (the monitor's floor), or None.""" + return self._input_floor + + @property + def quadrature(self) -> float: # numpydoc ignore=RT01 + """The quadrature alarm of the plane's last accepted step; NaN without one.""" + return self._alarm + + def load( + self, + field: _State, + noise: NoiseRealisation | None, + *, + z: float, + resume: bool, + ) -> None: + """Load a state and its noise realisation, masked to the active band. + + The ``input`` noise model's draw is added at the run's launch, never on a + resume; the ``modified`` model keeps it apart and adds it at every stage. The + quadrature alarm of a previous run is forgotten (SEP 22 section 4.7). + + Parameters + ---------- + field : numpy.ndarray + The state, ``complex128``, shape ``(n_modes, n_pol, n_omega)``, which the + caller has checked against the problem's. + noise : solprop.noise.NoiseRealisation or None + The realisation to carry, or ``None`` for the problem's own. + z : float + The position the state belongs to, m, inside the operator table. + resume : bool + Whether `field` came back from a saved plane, and so never takes the + ``input`` draw. + """ + values = field + drawn = self._noise_field(noise) + model = self._problem.initial.noise_model + self._clean_columns = None + if ( + model == "input" + and drawn is not None + and not resume + and z == self._problem.initial.z + ): + if transverse_of(self._problem.route) is not None: + self._clean_columns = _clean_launch_columns( + values, drawn, self._problem.grids.active_mask + ) + values = values + drawn + self._state = self.mask(values) + self._noise = drawn if model == "modified" else None + self._input_floor = drawn if model == "input" else None + self._alarm = math.nan + + def install(self, state: _State) -> None: + """Make an array the committed state, as it is. + + A dense observation's interpolated field and the accepted state it restores + afterwards, and a resumed snapshot's state, go in here; nothing is masked. + + Parameters + ---------- + state : numpy.ndarray + The state, shape ``(n_modes, n_pol, n_omega)``. + """ + self._state = state + + def bind_monitor(self, monitor: BoundaryMonitor | None) -> None: + """Read a boundary monitor's energies from now on, or stop with ``None``. + + A monitor of the ``"split_step"`` scheme also has each accepted step's + :meth:`finish` take the split collar's sums. + + Parameters + ---------- + monitor : solprop.monitor.BoundaryMonitor or None + The run's monitor. + """ + self._monitor = monitor + + def reading(self) -> BoundaryReading: + """Return the boundary monitor's reading of the committed state (SEP 21). + + The state's energy, its four weighted energies and, under a split collar's + crossing limit, its occupancy; the split's own sums travel in each step's + :class:`~solprop.backends.engines.AcceptRecord`. + + Returns + ------- + solprop.backends.engines.BoundaryReading + The reading. + + Raises + ------ + BackendError + If no monitor is bound or no state is loaded. + """ + monitor = self._monitor + if monitor is None: + raise BackendError(f"{self.name}: no boundary monitor is attached") + field = self.committed() + energies = monitor.energies(field) + crossing = monitor.crossing + return BoundaryReading( + total=energies.total, + regions=energies.regions, + occupancy=None + if crossing is None + else crossing.occupancy(field, monitor.columns), + ) + + def edge_reading( + self, + edge: TransverseEdge, + *, + faces: bool = True, + current: bool = False, + full: bool = False, + ) -> _EdgeReading: + """Return what the transverse edge asks of the committed state (SEP 44). + + Parameters + ---------- + edge : solprop.transverse_monitor.TransverseEdge + The run's edge. + faces : bool, optional + Whether the faces are read. + current : bool, optional + Whether a collar's inward current is wanted. + full : bool, optional + Whether every node is wanted, not only the rows a read uses. + + Returns + ------- + object + The edge's reading of the host state. + """ + return edge.reduction.reading( + np.asarray(self.committed()), + faces=faces, + current=current, + full=full, + ) + + def clean_columns( + self, edge: TransverseEdge + ) -> Float[np.ndarray, " n_columns"] | None: + """Return each column's launched energy without the input noise, or ``None``. + + What the safety ramp is judged on, so a run with no ramp needs none. It is + formed where the load has both parts; only a resume that found no record of + the monitor has none, and then it is formed from the state. + + Parameters + ---------- + edge : solprop.transverse_monitor.TransverseEdge + The run's edge. + + Returns + ------- + numpy.ndarray or None + The unweighted energies, or ``None`` with no noise, no ramp or on a resumed + launch. + """ + floor = self._input_floor + if floor is None or edge.resumed or edge.design is None: + return None + if self._clean_columns is not None: + return self._clean_columns + state = np.asarray(self.committed()) + return edge.reduction.column_power(state - np.asarray(floor)) + + def mask(self, state: _State) -> _State: + """Zero a state outside the active band. + + Parameters + ---------- + state : numpy.ndarray + A state, shape ``(n_modes, n_pol, n_omega)``. + + Returns + ------- + numpy.ndarray + A new masked array. + """ + return passes.apply_hard_mask(state, self._problem.grids.active_mask) + + def committed(self) -> _State: + """Return the committed state, refusing an unloaded workspace. + + Returns + ------- + numpy.ndarray + The state itself, not a copy. + + Raises + ------ + BackendError + If no state is loaded. + """ + if self._state is None: + msg = "no initial state: call set_initial before propagating or observing" + raise BackendError(msg) + return self._state + + # --- the host source (SEP 49) --------------------------------------------------- + + def reserve_calls(self, count: int) -> None: + """Reserve a whole trial's host-source calls before its first evaluation. + + Parameters + ---------- + count : int + The trial's logical response calls. + + Raises + ------ + solprop.exceptions.ResponseBudgetError + If the bound source's budget cannot pay for them. + """ + if self._tdse_binding is not None: + self._tdse_binding.reserve(count) + + def release_calls(self) -> None: + """Release the unspent part of a trial's reservation.""" + if self._tdse_binding is not None: + self._tdse_binding.release_reservation() + + def record_trial(self, *, accepted: bool) -> None: + """Tell the bound source how the last reserved trial ended (SEP 20 5.8). + + Parameters + ---------- + accepted : bool + Whether it was accepted. + """ + if self._tdse_binding is not None: + self._tdse_binding.record_trial(accepted=accepted) + + def restore_atomic_ledger(self, atomic: Mapping[str, object]) -> None: + """Restore a resumed run's atomic call counts into the bound source. + + Parameters + ---------- + atomic : collections.abc.Mapping + The persisted counts. + + Raises + ------ + BackendError + If no host source is bound. + """ + if self._tdse_binding is None: + raise BackendError("atomic call ledger requires a TDSE binding") + self._tdse_binding.restore_ledger(AtomicCallLedger.from_record(atomic)) + + def metadata(self) -> dict[str, object]: + """Return the workspace's execution facts for the run's record. + + Returns + ------- + dict + The benchmark-gated plasma source's form and, with a host source, its + ledger, execution and last evaluation; JSON-serialisable. + """ + record: dict[str, object] = {} + if self._gated_plasma: + record["_benchmark_plasma_source"] = "gated_nonresumable" + record["plasma_source"] = {"form": "gated_benchmark", "resumable": False} + if self._tdse_binding is not None: + record["atomic_calls"] = dataclasses.asdict(self._tdse_binding.ledger) + record["tdse_execution"] = dict(self._tdse_binding.metadata()) + record["tdse_last_evaluation"] = { + "purpose": self._tdse_last_purpose, + "z": self._tdse_last_z, + "projection": self._tdse_last_projection, + } + record["tdse_source"] = tdse_source.source_record(self._problem) + return record + + # --- the quadrature alarm -------------------------------------------------------- + + def reset_quadrature(self) -> None: + """Forget the alarm, so that the next plane reports its own.""" + self._alarm = math.nan + + def hoist(self, z0: float) -> None: + """Evaluate once per step what every stage of it subtracts. + + ``Phi`` is cumulative, so each stage's increment is against the same anchor. + On the RDW gradient the Clenshaw pass over the scalar tables is the largest + part of what the host does per step, and this is a sixth of it. The bundles + :meth:`stage_bundles` kept are dropped. + + Parameters + ---------- + z0 : float + The step's anchor, m. + """ + self._anchor = anchor(self._problem, z0, helpers=self.helpers) + self._prepared.clear() + + def stage_bundles( + self, z0: float, positions: Sequence[float] + ) -> tuple[StageScalars, ...]: + """Return the host scalars of several stages of one step, taken together. + + A trial knows all its stage positions before its first stage, and reading each + scalar table once over all of them (:func:`solprop.translate.stage.scalars_at`) + costs a Python call and a Clenshaw dispatch per table rather than per table and + position. The bundles equal :meth:`stage_scalars`'s bit for bit, and are kept + until the next :meth:`hoist`: a later :meth:`stage_scalars` at the same anchor + and position returns the kept bundle, so a step loop written one stage at a + time takes them without change. Bundles of several anchors are kept side by + side (kernel schema 29): the low-storage engine reads each of its three + positions as its own anchor. A caller passes only positions the trial will + evaluate. + + Parameters + ---------- + z0 : float + The step's anchor, m. + positions : collections.abc.Sequence of float + The stages' positions, m. + + Returns + ------- + tuple of solprop.translate.stage.StageScalars + One bundle per position, in order. + """ + prepared = self._prepared + missing = [z1 for z1 in dict.fromkeys(positions) if (z0, z1) not in prepared] + if missing: + held = self._anchor if self._anchor.z == z0 else None + for bundle in scalars_at( + self._problem, z0, missing, at=held, helpers=self.helpers + ): + prepared[z0, bundle.z1] = bundle + return tuple(prepared[z0, z1] for z1 in positions) + + def stage_scalars(self, z0: float, z1: float) -> StageScalars: + """Return the host scalars of one stage, from the anchor to the node. + + The anchor's own weights come from :meth:`hoist` when the caller has already + taken them for this step, and are evaluated here otherwise. A bundle + :meth:`stage_bundles` took for this anchor and position is returned as kept. + + Parameters + ---------- + z0 : float + The step's anchor, m. + z1 : float + The stage's position, m. + + Returns + ------- + solprop.translate.stage.StageScalars + The bundle. + """ + kept = self._prepared.get((z0, z1)) + if kept is not None: + return kept + held = self._anchor if self._anchor.z == z0 else None + return scalars(self._problem, z0, z1, at=held, helpers=self.helpers) + + def delta_phi( + self, bundle: StageScalars + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: + """Return the stage's propagator exponent from the bundle. + + One linear combination of the terms the workspace holds over the bundle's + floats. A problem that took the z table has no such form and falls back to + :func:`solprop.translate.linop.delta_phi`. + + Parameters + ---------- + bundle : solprop.translate.stage.StageScalars + The stage's scalars. + + Returns + ------- + numpy.ndarray + ``Phi(z1) - Phi(z0)`` in the state's layout. + """ + if bundle.phi_delta is None or self._terms.phi is None: + return delta_phi( + self._problem.linear, bundle.z0, bundle.z1, helpers=self.helpers + ) + return combine(bundle.phi_delta, self._terms.phi) + + def prefactor( + self, bundle: StageScalars + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: + """Return the response prefactor at the stage's position, from the bundle. + + Parameters + ---------- + bundle : solprop.translate.stage.StageScalars + The stage's scalars. + + Returns + ------- + numpy.ndarray + The prefactor times the crop scale, in m/(V s) per unit polarisation. + """ + if bundle.prefactor is None or self._terms.prefactor is None: + return prefactor_at( + self._problem.responses, bundle.z1, helpers=self.helpers + ) + return combine(bundle.prefactor, self._terms.prefactor) + + def unitary_phase( + self, bundle: StageScalars + ) -> Float[np.ndarray, "n_modes n_pol n_omega"]: + """Return ``Im Phi`` at the stage's position, from the same terms. + + An expansion of ``Phi`` is cumulative and vanishes at the start of the range, + so its value at a position is the bundle's ``phi_at`` against the same arrays + and the noise costs no second representation. + + Parameters + ---------- + bundle : solprop.translate.stage.StageScalars + The stage's scalars. + + Returns + ------- + numpy.ndarray + The phase, rad, in the state's layout. + """ + if bundle.phi_at is None or self._terms.phi is None: + return unitary_phase(self._problem.linear, bundle.z1) + return np.imag(combine(bundle.phi_at, self._terms.phi)) + + def _noise_field( + self, noise: NoiseRealisation | None + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"] | None: + """Return the noise realisation to carry, in the canonical layout. + + - Returns: the noise spectrum, or ``None`` when no noise model is active. + """ + if self._problem.initial.noise_model == "none": + return None + if noise is not None: + return noise_spectrum(noise, self._problem.shape) + return self._problem.initial.noise0 + + def noise_at( + self, bundle: StageScalars + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"] | None: + """Return the shot-noise field advanced to a stage's position. + + ``N(z) = N0 exp(i Im Phi(omega, z))``: dispersion yes, loss and gain no, from + the same terms as the linear flow, so the noise costs one multiply-add per + element per stage and no transform. + + Parameters + ---------- + bundle : solprop.translate.stage.StageScalars + The stage's scalars. + + Returns + ------- + numpy.ndarray or None + The advanced noise, or ``None`` when the modified model is not in use. + """ + if self._noise is None: + return None + return self._noise * np.exp(1j * self.unitary_phase(bundle)) + + def noise_phase( + self, z: float + ) -> Float[np.ndarray, "n_modes n_pol n_omega"] | None: + """Return ``Im Phi`` at a position, or ``None`` without a noise model. + + Parameters + ---------- + z : float + The position, m. + + Returns + ------- + numpy.ndarray or None + The phase in radians, in the state's layout. + """ + if self._problem.initial.noise_model == "none": + return None + phase = self.unitary_phase(self.stage_scalars(z, z)) + return np.ascontiguousarray(np.broadcast_to(phase, self._problem.shape)) + + def source( + self, + lab: Complex[np.ndarray, "n_modes n_pol n_omega"], + anchor: float, + position: float, + *, + purpose: TDSEPurpose = "predictor", + ) -> tuple[ + Complex[np.ndarray, "n_modes n_pol n_omega"], + Complex[np.ndarray, "n_modes n_pol n_omega"], + ]: + """Evaluate the source once, in the interaction frame of a step's anchor. + + The one expensive evaluation of an interaction-formulation Adams step: the + nonlinear source at a lab-frame field, with the run's noise and in-stage + absorber. A propagator :meth:`propagator` held for the same pair is reused. + + Parameters + ---------- + lab : numpy.ndarray + The lab-frame field at `position`, in the state's layout. + anchor, position : float + The step's anchor and the evaluation position, m. + purpose : {'startup', 'predictor', 'corrected', 'diagnostic'}, optional + The host source's accounting label; ignored when none is bound. + + Returns + ------- + numpy.ndarray + ``U(anchor, position) N(lab, position)``. + numpy.ndarray + ``U(position, anchor)``, with ``U(z_2, z_1) = exp(Phi(z_2) - Phi(z_1))``. + """ + held = self._held + if held is not None and held[0] == anchor and held[1] == position: + bundle, propagator = held[2], held[3] + else: + bundle = self.stage_scalars(anchor, position) + propagator = np.exp(self.delta_phi(bundle)) + self._held = None + noise = self.noise_at(bundle) + field_in = lab if noise is None else lab + noise + if self._tdse_binding is not None: + return ( + self.nonlinear(field_in, bundle, 1.0 / propagator, purpose=purpose), + propagator, + ) + return self.nonlinear(field_in, bundle, 1.0 / propagator), propagator + + def coupled_block(self, z: float, dz: float) -> object: + """Return the frozen block of the section a step from `z` is anchored in. + + The exponential formulation steps a coupled flow's constant-Schur and + frozen-residual sections against the reference ``(Delta Phi / h) I + G_s`` + (SEP 16 section 4.5), with ``G_s`` the frozen block of the step's section. + + Parameters + ---------- + z : float + Where the step starts, m. + dz : float + The step, m. + + Returns + ------- + object + The step's :class:`~solprop.backends.numpy_ref.multistep.CoupledBlock`, + or ``None`` without a coupled flow. + """ + from solprop.backends.numpy_ref.multistep import ( # noqa: PLC0415 - cycle + CoupledBlock, + ) + + flow = self._flow + if flow is None: + return None + bundle = self.stage_scalars(z, z + dz) + section = bundle.flow_section + assert section is not None + residual = None + if flow.residual_terms is not None: + if self._block_residual is None: + self._block_residual = BlockResidual(flow) + residual = functools.partial(self._block_residual, section) + return CoupledBlock( + active=flow.active, + vectors=flow.vectors[section], + triangular=flow.triangular[section], + section=section, + end_weights=bundle.flow_weights, + residual=residual, + ) + + def lab_source( + self, + lab: Complex[np.ndarray, "n_modes n_pol n_omega"], + position: float, + *, + purpose: TDSEPurpose = "predictor", + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: + """Evaluate the source once, untransported, at a lab-frame field. + + The same passes as :meth:`source`, with the stage's inverse propagator + replaced by ones: a multiplication by one is exact, so the sample is the + lab-frame source bit for bit, and every route's evaluation stays the one the + Runge-Kutta trial uses. The sample the exponential formulation and the + low-storage step integrate. + + `lab` is taken as given: it is not masked to the active band, as + :meth:`load` masks the state it loads. On a masked field the sample equals the + hoisted first stage at the same position bit for bit; a field with content + outside the band (an unmasked launch) is another input, whose source differs by + what that content makes (4.3e-13 of the peak on the optmat argon capillary). + The stage scalars at ``(position, position)`` do not depend on the anchor last + hoisted: a held anchor is reused only at its own position. + + Parameters + ---------- + lab : numpy.ndarray + The lab-frame field at `position`, in the state's layout. + position : float + The evaluation position, m. + purpose : {'startup', 'predictor', 'corrected', 'diagnostic'}, optional + The host source's accounting label; ignored when none is bound. + + Returns + ------- + numpy.ndarray + The complete source ``F`` in the lab frame. + """ + bundle = self.stage_scalars(position, position) + noise = self.noise_at(bundle) + field_in = lab if noise is None else lab + noise + if self._tdse_binding is not None: + return self.nonlinear(field_in, bundle, self._lab_frame, purpose=purpose) + return self.nonlinear(field_in, bundle, self._lab_frame) + + def propagator( + self, anchor: float, position: float, *, hold: bool = False + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: + """Return the linear propagator ``U(position, anchor)``. + + Only the Adams engine holds it for the step's source call (:meth:`source`): the + low-storage engine applies its flows at once, and a held one would be a volume + its ledger does not name. + + Parameters + ---------- + anchor, position : float + The step's anchor and its end, m. + hold : bool, optional + Whether to keep it for the next :meth:`source` at the same pair. + + Returns + ------- + numpy.ndarray + ``exp(Phi(position) - Phi(anchor))`` in the state's layout, an array the + caller owns. + """ + bundle = self.stage_scalars(anchor, position) + propagator = np.exp(self.delta_phi(bundle)) + if hold: + self._held = (anchor, position, bundle, propagator) + return propagator + + def channels( + self, + values: Complex[np.ndarray, "n_modes n_pol n_omega"], + action: Complex[np.ndarray, "n_active_c n_modes_c_out n_modes_c_in"] | None, + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: + """Mix the channel axis by one coupled-flow action, or return the values. + + Parameters + ---------- + values : numpy.ndarray + Any array of the state's layout. + action : numpy.ndarray or None + The action on the active bins, or ``None`` for a problem with no coupled + flow, which is every route but the coherent wall. + + Returns + ------- + numpy.ndarray + The mixed values, or `values` itself. + """ + if self._flow is None or action is None: + return values + return _apply_flow(values, action, self._flow.active) + + def residual( + self, + lab: Complex[np.ndarray, "n_modes n_pol n_omega"], + section: int, + bundle: StageScalars, + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"] | None: + """Return the explicit residual's lab-frame source term, or nothing. + + ``None`` for every problem but a ``"frozen_residual"`` coupled flow: the + constant section has an identically zero residual and is not multiplied by + one, so its arithmetic is bit for bit what it was. + + Parameters + ---------- + lab : numpy.ndarray + The stage's lab-frame field. + section : int + The step's flow section. + bundle : solprop.translate.stage.StageScalars + The stage's scalars, with the section's weights. + + Returns + ------- + numpy.ndarray or None + ``R_s(z_1) u`` in the state's layout, or ``None``. + """ + flow = self._flow + if flow is None or flow.residual_terms is None: + return None + assert bundle.flow_weights is not None + return _residual_drive( + lab, + _residual_action(flow, section, bundle.flow_weights), + flow.active, + flow.residual_bins, + ) + + def flow_actions( + self, section: int, dz: float + ) -> Callable[ + [float], + tuple[ + Complex[np.ndarray, "n_active_a n_modes_a_out n_modes_a_in"] | None, + Complex[np.ndarray, "n_active_b n_modes_b_out n_modes_b_in"] | None, + ], + ]: + """Return the memoised forward and inverse flow actions of one step. + + The generator is **frozen** across the step -- at the midpoint of the section + the step's anchor lies in -- so an action depends on the stage fraction only + through the length ``c_i h`` it covers, and the six distinct DOPRI5 fractions + need at most six pairs; the tableau uses the last one twice and the zero + fraction is the identity. The whole step's pair is checked against that + section's declared conditioning row, which bounds every shorter one because + ``exp(c dz (mu_max - mu_min))`` increases with ``c``. + + The pairs also survive **between** steps, for the one section and trial length + last seen: a fixed schedule and an accepted adaptive step both repeat their + ``dz``, and an action that depends on nothing but ``dz`` and a frozen generator + is then the same matrix. Exactly one pair of them is held, so what a step has + resident at its peak -- which is what :meth:`memory_ledger` reports -- is + unchanged, and a step that crosses into the next section rebuilds, which is a + cache invalidation at the section edge and is what makes the edge a kink of + the flow (``docs/dev/stepper.md`` section 2). The conditioning of a held + length was measured when it was built. + + Parameters + ---------- + section : int + The section the step's anchor lies in. + dz : float + The length of the trial step, m. + + Returns + ------- + callable + ``fraction -> (U, U^-1)``, each ``None`` when no coupled flow is carried. + """ + flow = self._flow + if flow is None: + return lambda fraction: (None, None) # noqa: ARG005 + held = self._flow_cache + key = (section, dz) + cache: dict[float, tuple[np.ndarray | None, np.ndarray | None]] = ( + held[1] if held is not None and held[0] == key else {} + ) + self._flow_cache = (key, cache) + + def _action( + fraction: float, + ) -> tuple[np.ndarray | None, np.ndarray | None]: + """Return the pair at a stage fraction, computing it at most once. + + - ``fraction``: the tableau node ``c_i``, dimensionless, in ``[0, 1]``. + - Returns: the forward and inverse actions, or ``(None, None)`` at fraction + zero, where both are the identity. + """ + if fraction == 0.0: + return None, None + if fraction not in cache: + pair = _flow_action(flow, section, fraction * dz) + if fraction == 1.0: + _check_flow_conditioning(flow, section, pair, dz) + cache[fraction] = pair + return cache[fraction] + + return _action + + def finish( + self, + state: Complex[np.ndarray, "n_modes n_pol n_omega"], + dz: float, + ) -> tuple[Complex[np.ndarray, "n_modes n_pol n_omega"], AcceptRecord]: + """Apply the once-per-accepted-step boundary treatments to a kept step. + + The hard band mask and, when the ``"split_step"`` absorber scheme is active, + the temporal collar, followed by the mask again: its product in time spreads + content into every bin, so the band is imposed last. Applied only to a step + that is kept, never to one about to be thrown away. While a monitor of that + scheme is bound, the split collar's sums are taken here from the masked field + **before** the split, the field the removal and the occupancies describe + (SEP 52 section 4): what the split removes, ``P (1 - exp(-alpha h))``, and + the energies of ``P exp(-alpha h / 2)``. + + Parameters + ---------- + state : numpy.ndarray + The state at the end of an accepted step, shape ``(n_modes, n_pol, + n_omega)``; not modified. + dz : float + The length of that step, m, which the collar's rate needs. + + Returns + ------- + numpy.ndarray + The finished state, a new array. + solprop.backends.engines.AcceptRecord + The split collar's sums; the defaults (nothing removed, nothing found) + without a split collar or a bound monitor of its scheme. + """ + masked = self.mask(state) + responses = self._problem.responses + rate = responses.temporal_absorber + if rate is None or responses.absorber_scheme != "split_step": + # Either there is no collar, or ADR-025's other scheme applied it inside + # every stage, where it is already in the accepted state. + return masked, AcceptRecord() + record = AcceptRecord() + monitor = self._monitor + if monitor is not None and monitor.split: + # The time factor acts alike on every column of any transverse basis, so + # the stored state's power is what the split takes of, wherever it acts. + # What it finds is what the occupancies are judged on. + sums = monitor.split_sums(masked, dz) + record = AcceptRecord(removed=float(sums[0]), found=sums[1:]) + return self._split(masked, rate, dz), record + + def _split( + self, + masked: Complex[np.ndarray, "n_modes n_pol n_omega"], + rate: np.ndarray, + dz: float, + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: + """Apply the split temporal collar to a masked state, and the mask after it.""" + geometry = self._problem.transform.geometry + if geometry is not None and geometry.kind == "slab": + # A (p, y) row is a modal amplitude whose time signal is a real field's, + # and the rate is the same at every node, so it is applied row by row. + transform = self._problem.transform + physical = slab_rows(transform, masked) + chunk = self.node_chunk + for first in range(0, len(physical), chunk): + rows = slice(first, first + chunk) + physical[rows] = passes.apply_temporal_rate( + physical[rows], rate, dz, kind=self._kind + ) + return self.mask(slab_columns(transform, physical)) + if geometry is not None and geometry.kind == "free": + nx, ny = geometry.shape + shape = (ny, nx, *masked.shape[1:]) + physical = np.fft.ifft2(masked.reshape(shape), axes=(0, 1)).reshape( + masked.shape + ) + chunk = self.node_chunk + for first in range(0, len(physical), chunk): + rows = slice(first, first + chunk) + physical[rows] = passes.apply_temporal_rate( + physical[rows], rate, dz, kind=self._kind + ) + result = np.fft.fft2(physical.reshape(shape), axes=(0, 1)).reshape( + masked.shape + ) + return self.mask(result) + # The product in time spreads content across every bin, the DC among them, so + # the band is imposed again after it, as the in-stage term is masked. + return self.mask(passes.apply_temporal_rate(masked, rate, dz, kind=self._kind)) + + def score_quadrature(self) -> tuple[float, float]: + """Score the quadrature from the last stage of an accepted step. + + The relative difference between the projections of the same node polarisation + with the Kronrod rule and with its embedded Gauss subset, at the cost of one + extra forward transform per accepted step rather than a whole second evaluation + of the transform. + It is a **statistic and a warning, never a controller input**: a + quadrature too coarse for the integrand is a modelling error the step size + cannot fix, and feeding it to the controller would only shrink the step until + the run stopped. + + The value is ``nan`` when the rule has no embedded pair, because the difference + is then identically zero and reading that as convergence would be wrong; and + ``nan`` where the polarisation itself vanishes, at a true vacuum end, because a + relative measure of nothing says nothing. The session reports a value above + :data:`~solprop.translate.modal.QUADRATURE_ALARM` once per plane, and the + ``quadrature_error`` statistic reads it (:attr:`quadrature`). + + Returns + ------- + float + The alarm, dimensionless, or NaN. + float + Where the last stage was evaluated, m, or NaN without one. + """ + if ( + self._last_coarse is None + or self._last_projected is None + or self._last_bundle is None + ): + self._alarm = math.nan + return self._alarm, math.nan + grids = self._problem.grids + weight = self.prefactor(self._last_bundle) * self._tables.omega_window + fine = weight * passes.to_frequency( + self._last_projected, grids.crop_index, kind=self._kind + ) + coarse = weight * passes.to_frequency( + self._last_coarse, grids.crop_index, kind=self._kind + ) + if self._last_envelope is not None: + assembly = self._problem.responses.envelope_plasma + assert assembly is not None + drive, loss, coarse_drive, coarse_loss = self._last_envelope + assert coarse_drive is not None and coarse_loss is not None + for factor, full, reduced in ( + (assembly.factors.drude, drive, coarse_drive), + (assembly.factors.loss, loss, coarse_loss), + ): + fine += ( + weight + * factor + * passes.to_frequency(full, grids.crop_index, kind=self._kind) + ) + coarse += ( + weight + * factor + * passes.to_frequency(reduced, grids.crop_index, kind=self._kind) + ) + if self._last_plasma is not None: + gated, edge, coarse_gated, coarse_edge = self._last_plasma + assert coarse_gated is not None and coarse_edge is not None + fine += weight * self._held_streams(gated, edge) + coarse += weight * self._held_streams(coarse_gated, coarse_edge) + scale = float(np.linalg.norm(fine)) + self._alarm = ( + math.nan if scale == 0.0 else float(np.linalg.norm(coarse - fine) / scale) + ) + return self._alarm, self._last_bundle.z1 + + def _envelope_sources( + self, field_t: Complex[np.ndarray, "n_nodes n_pol n_to"], bundle: StageScalars + ) -> tuple[ + Complex[np.ndarray, "n_nodes n_pol n_to"], + Complex[np.ndarray, "n_nodes n_pol n_to"], + ]: + """Return the envelope-grid plasma's windowed drive and loss at some nodes. + + - ``field_t``: the field at the nodes, V/m. + """ + envelope = self._problem.responses.envelope_plasma + assert envelope is not None + return envelope_sources( + field_t, + envelope, + bundle, + self._problem.grids.dt_fine, + self._tables.t_window, + ) + + def _envelope_populations( + self, + nodes: Complex[np.ndarray, "n_nodes n_pol n_to"], + initials: tuple[float, ...], + ) -> tuple[np.ndarray, np.ndarray]: + """Return each envelope channel's final fraction and peak rate at the nodes. + + - ``nodes``: the physical envelope at the nodes, V/m. + """ + envelope = self._problem.responses.envelope_plasma + assert envelope is not None + return envelope_populations( + nodes, envelope, initials, self._problem.grids.dt_fine + ) + + def error_norm( + self, + error: Complex[np.ndarray, "n_modes n_pol n_omega"], + state: Complex[np.ndarray, "n_modes n_pol n_omega"], + advanced: Complex[np.ndarray, "n_modes n_pol n_omega"], + ) -> float: + """Return the controller's scaled norm of a trial step's embedded difference. + + Parameters + ---------- + error : numpy.ndarray + The embedded difference, carried to the step's end. + state : numpy.ndarray + The state before the step. + advanced : numpy.ndarray + The state after it. + + Returns + ------- + float + The scaled norm. + """ + return passes.error_norm( + error, + state, + advanced, + self._problem.grids.norm_mask, + self._stepper.controller, + ) + + def stats(self, spec: StatsSpec, z: float) -> dict[str, np.ndarray]: + """Collect the requested statistics of the committed state at a position. + + The statistics of the saved field go to :func:`solprop.stats.collect`; there is + exactly one definition of each in the package and that is it. The statistics + :class:`solprop.stats.StatDefinition` marks ``backend`` are of quantities a + saved plane does not carry -- the electron density, the peak ionisation rate, + the on-axis intensity, the quadrature error -- and are formed here from the + workspace's own buffers. + + Parameters + ---------- + spec : solprop.stats.StatsSpec + Which statistics and which windows. + z : float + The committed state's position, m. + + Returns + ------- + dict + Small host arrays keyed by statistic name. + """ + state = self.committed() + grid = self._require_grid() + if self._tdse_binding is not None: + unavailable = TDSE_UNAVAILABLE_STATISTICS.intersection(spec.names) + if unavailable: + raise BackendError( + f"TDSE does not define legacy statistics {sorted(unavailable)}" + ) + # Before the spatial branch: a spatial run asked for a + # general name would otherwise reach `collect_spatial` and be answered from a + # geometry that carries no certified metric at all. + _refuse_inadmissible(self._problem, spec) + if self._problem.transform.geometry is not None: + response_names = ( + {"electron_density", "peak_ionisation_rate", "quadrature_error"} + | set(PLASMA_INTEGRATION_STATISTICS) + | {name for name in CATALOGUE if name.startswith("species_")} + ) + spatial_spec = dataclasses.replace( + spec, + names=tuple(name for name in spec.names if name not in response_names), + periodic=(), + ) + tables = self._far_field.for_spec(spatial_spec) + spatial = collect_spatial( + spatial_spec, + grid, + self._problem.transform, + state, + z=z, + flux=flux_of(self._problem.route), + profiles=self._profiles, + tables=tables, + operator=self._problem.linear.separable, + node_chunk=self.node_chunk, + ) + return { + name: np.array(spatial[name]) for name in spatial_spec.names + } | self._backend_statistics( + tuple(name for name in spec.names if name in response_names), state, z + ) + # The weight is a Chebyshev evaluation per column, which is the whole of what + # the Poynting weighting adds to a statistics call on a CPU (0.053 ms of + # 0.056 ms on the reduced-M2 case), so a spec that asks for none of the + # Poynting statistics -- a periodic plasma subset, say -- never + # evaluates it. + needed = bool(set(spec.names) & WEIGHT_DEPENDENT_STATISTICS) + if needed: + np.copyto(self._statistics_power_weight, power_weight_at(self._problem, z)) + weight_refusal = weight_refusal_for(spec.names, self._statistics_power_weight) + if weight_refusal is not None: + raise BackendError(weight_refusal) + weighted = needed and not np.all(self._statistics_power_weight == 1.0) + power_names = tuple( + name for name in spec.names if weighted and name in _POYNTING_STATISTICS + ) + axis = None + if "peak_intensity" in power_names: + if self._modes is None: + msg = "the peak on-axis intensity needs the mode set" + raise BackendError(msg) + axis = self._on_axis_synthesis(self._modes, z) + power_values = ( + _poynting_statistics(spec, grid, state, self._statistics_power_weight, axis) + if weighted + else {} + ) + owned = tuple( + name + for name in spec.names + if CATALOGUE[name].backend and name not in power_names + ) + delegated = dataclasses.replace( + spec, + names=tuple( + name + for name in spec.names + if name not in owned and name not in power_names + ), + periodic=tuple( + name + for name in spec.periodic + if name not in owned and name not in power_names + ), + ) + # The basis metric at this plane: the + # statistics of `METRIC_WEIGHTED_STATISTICS` are functionals of the physical + # same-frequency flux `a.H W a`, and on a declared change of basis W is not + # the identity. `metric_at` returns None for an identity metric, which is + # the statistics' own bitwise-unchanged path, so an ordinary run pays + # nothing. + metric = ( + metric_at(self._problem.linear.modal_metric, z) + if set(delegated.names) & METRIC_WEIGHTED_STATISTICS + else None + ) + collected = collect( + delegated, + grid, + SavedPlane(z=z, field=state), + modes=self._modes, + profiles=self._profiles, + metric=metric, + ) + values = {name: np.array(collected[name]) for name in delegated.names} + values.update({name: np.array(power_values[name]) for name in power_names}) + return values | self._backend_statistics(owned, state, z) + + def _backend_statistics( + self, + names: tuple[str, ...], + state: Complex[np.ndarray, "n_modes n_pol n_omega"], + z: float, + ) -> dict[str, np.ndarray]: + """Share each fresh envelope population scan among the requested statistics. + + - ``state``: accepted state at this plane. + - Returns: requested values, with no retained field cache. + """ + population_names = ( + tuple( + name + for name in names + if name.startswith("species_") + or name in ("electron_density", "peak_ionisation_rate") + ) + if self._problem.responses.envelope_plasma is not None + else () + ) + integration_names = tuple( + name for name in names if name in PLASMA_INTEGRATION_STATISTICS + ) + axis_names = tuple(name for name in names if name in ON_AXIS_PLASMA_STATISTICS) + if axis_names and not population_names: + # The species statistics are the node scan of `_species_statistics` on + # every route, so sharing one scan with the on-axis statistics changes + # none of their values and lets a node on the axis supply its row. + population_names = tuple( + name for name in names if name.startswith("species_") + ) + # Node scans of this observation only: a rule with a node on the axis hands + # its row to the on-axis statistics, and nothing outlives the call, so no + # stale stage or rejected step can be reused. + scans: list[tuple[np.ndarray, np.ndarray]] = [] + result = { + name: self._backend_stat(name, state, z) + for name in names + if name not in population_names + and name not in integration_names + and name not in axis_names + } + if integration_names: + diagnostics = self._integration_diagnostics(state, z) + result.update( + {name: np.array(diagnostics[name]) for name in integration_names} + ) + if population_names: + species = self._species_statistics(state, z, scans) + result.update({name: np.array(species[name]) for name in population_names}) + if axis_names: + axis = self._axis_statistics(state, scans[0] if scans else None, z) + result.update({name: np.array(axis[name]) for name in axis_names}) + return result + + def _backend_stat( + self, + name: str, + state: Complex[np.ndarray, "n_modes n_pol n_omega"], + z: float, + ) -> np.ndarray: + """Compute one backend-owned statistic.""" + if name == "quadrature_error": + return np.full((), self._alarm) + if name == "peak_intensity": + return np.array(self._peak_intensity(state, z)) + if ( + name.startswith("species_") + or self._problem.flags.n_channels > 1 + or self._problem.responses.envelope_plasma is not None + ): + return np.array(self._species_statistics(state, z)[name]) + return np.array( + self._ionisation(state, z)[0 if name == "electron_density" else 1] + ) + + def _species_statistics( + self, + field: Complex[np.ndarray, "n_modes n_pol n_omega"], + z: float, + scans: list[tuple[np.ndarray, np.ndarray]] | None = None, + ) -> dict[str, np.ndarray]: + """Evaluate independent populations on the actual nonlinear nodes. + + - ``scans``: where to leave this observation's channel fractions and peak rates + at every node, for the on-axis statistics to reuse. + - Returns: the five species statistics and the two total plasma statistics. + """ + responses = self._problem.responses + transform, grids = self._problem.transform, self._problem.grids + channels = responses.population_channels + if channels: + if transform.geometry is not None and transform.geometry.kind == "free": + nx, ny = transform.geometry.shape + physical = np.fft.ifft2( + field.reshape(ny, nx, *field.shape[1:]), axes=(0, 1) + ).reshape(field.shape) + nodes = passes.to_time( + physical * grids.pad_scale, + grids.crop_index, + grids.n_to, + kind=self._kind, + ) + elif transform.geometry is not None and transform.geometry.kind == "slab": + # The slab synthesis carries the pad scale already. + nodes = passes.to_time( + slab_synthesis(transform, field), + grids.crop_index, + grids.n_to, + kind=self._kind, + ) + else: + nodes = self._nodes_at(field, z) + if responses.envelope_plasma is not None: + fractions, peaks = self._envelope_populations( + nodes, tuple(float(c.preionisation(z)) for c in channels) + ) + if scans is not None: + scans.append((fractions, peaks)) + return population_statistics(self._problem, z, fractions, peaks) + rates, population = passes.plasma_channel_fractions( + nodes, + responses.plasma_channels, + tuple(float(c.preionisation(z)) for c in channels), + grids.dt_fine, + responses.plasma_integral, + ) + if scans is not None: + scans.append((population[:, :, -1], rates.max(axis=-1))) + return population_statistics( + self._problem, z, population[:, :, -1], rates.max(axis=-1) + ) + empty = np.zeros((0, transform.n_nodes)) + return population_statistics(self._problem, z, empty, empty) + + def _integration_diagnostics( + self, field: Complex[np.ndarray, "n_modes n_pol n_omega"], z: float + ) -> dict[str, np.ndarray]: + """Return the plasma column's integration diagnostics at this plane (SEP 18). + + The undershoot of the exposure increments, the relative work defect of the + loss current and the boundary level of the free-current integrand, over every + node and field plasma channel + (:data:`solprop.stats.PLASMA_INTEGRATION_STATISTICS`). + + - Returns: the three statistics, each zero-dimensional and dimensionless. + """ + responses = self._problem.responses + channels = responses.plasma_channels + if not channels: + msg = ( + "the plasma integration diagnostics read the field-grid plasma " + "column, and this problem carries none" + ) + raise BackendError(msg) + initial = tuple(float(channel.preionisation(z)) for channel in channels) + parts = np.zeros(6) + for nodes in self._plasma_nodes(field, z): + parts = np.maximum( + parts, + passes.plasma_integration_diagnostics( + nodes, + channels, + initial, + self._problem.grids.dt_fine, + responses.plasma_integral, + ), + ) + undershoot, defect, boundary = passes.plasma_integration_statistics(parts) + return { + "plasma_undershoot": np.asarray(undershoot), + "plasma_work_defect": np.asarray(defect), + "plasma_boundary_level": np.asarray(boundary), + } + + def _plasma_nodes( + self, field: Complex[np.ndarray, "n_modes n_pol n_omega"], z: float + ) -> Iterator[Float[np.ndarray, "n_nodes_chunk n_pol n_to"]]: + """Yield the real node fields the plasma column is evaluated on, by chunk. + + The same synthesis as :meth:`_ionisation`: the physical nodes of a separable + geometry, chunk by chunk, or the modal quadrature nodes at once. + + - Yields: node fields on the fine time grid, V/m. + """ + grids = self._problem.grids + if self._problem.linear.separable is None: + yield self._nodes_at(field, z) + return + geometry = self._problem.transform.geometry + assert geometry is not None + nx, ny = geometry.shape + physical = ( + slab_synthesis(self._problem.transform, field) / grids.pad_scale + if geometry.kind == "slab" + else np.fft.ifft2( + field.reshape(ny, nx, *field.shape[1:]), axes=(0, 1) + ).reshape(field.shape) + ) + chunk = self.node_chunk + for first in range(0, len(physical), chunk): + yield passes.to_time( + physical[first : first + chunk] * grids.pad_scale, + grids.crop_index, + grids.n_to, + kind=self._kind, + ) + + def _ionisation( + self, + field: Complex[np.ndarray, "n_modes n_pol n_omega"], + z: float, + ) -> tuple[np.ndarray, np.ndarray]: + """Return the electron density and the peak ionisation rate at this plane. + + Both are read at the **node of largest ionised fraction**, which is where the + plasma the run carries is densest and the only node either number can honestly + describe; for a mode-averaged run that is the one node. The axis is not a + quadrature node at all and is not where the polarisation was evaluated, so the + field is not re-synthesised there. + + The electron density is ``density(z)`` times the fraction at the **end** of the + window: what the pulse leaves behind, not what it reaches in passing. + + - Returns: the electron density in m^-3 and the peak rate in s^-1, both + zero-dimensional. + """ + responses = self._problem.responses + plasma = responses.plasma_coefficients + if plasma is None: + msg = ( + "the electron density and the peak ionisation rate need a compiled " + "plasma response, and this problem declares none" + ) + raise BackendError(msg) + if self._problem.linear.separable is not None: + geometry = self._problem.transform.geometry + assert geometry is not None + nx, ny = geometry.shape + physical = ( + # The slab synthesis carries the pad scale, multiplied back below. + slab_synthesis(self._problem.transform, field) + / self._problem.grids.pad_scale + if geometry.kind == "slab" + else np.fft.ifft2( + field.reshape(ny, nx, *field.shape[1:]), axes=(0, 1) + ).reshape(field.shape) + ) + largest, peak = -1.0, 0.0 + grids = self._problem.grids + chunk = self.node_chunk + for first in range(0, len(physical), chunk): + nodes = passes.to_time( + physical[first : first + chunk] * grids.pad_scale, + grids.crop_index, + grids.n_to, + kind=self._kind, + ) + rate = passes.ionisation_rate(nodes, plasma.rate) + fraction, _ = passes.plasma_scan( + nodes, + rate, + plasma, + preionisation=float(plasma.preionisation(z)), + dt=grids.dt_fine, + integral=responses.plasma_integral, + ) + densest = int(np.argmax(fraction[:, -1])) + if fraction[densest, -1] > largest: + largest = float(fraction[densest, -1]) + peak = float(np.max(rate[densest])) + return np.asarray(float(plasma.density(z)) * largest), np.asarray(peak) + nodes = self._nodes_at(field, z) + rate = passes.ionisation_rate(nodes, plasma.rate) + fraction, _ = passes.plasma_scan( + nodes, + rate, + plasma, + preionisation=float(plasma.preionisation(z)), + dt=self._problem.grids.dt_fine, + integral=responses.plasma_integral, + ) + densest = int(np.argmax(fraction[:, -1])) + density = float(plasma.density(z)) * float(fraction[densest, -1]) + return np.asarray(density), np.asarray(float(np.max(rate[densest]))) + + def _peak_intensity( + self, + field: Complex[np.ndarray, "n_modes n_pol n_omega"], + z: float, + ) -> np.ndarray: + """Return the largest intensity on the axis of the waveguide, in W/m^2. + + ``eps0 c/2 max_t sum_c |E_{a,c}(0, t)|^2`` with the analytic field synthesised + at ``r = 0`` from the modes' own profiles, both Cartesian components. The axis + is not a quadrature node, so the mode fields are evaluated there rather than + interpolated, and both components are taken so that the answer does not depend + on which one the transform resolves or the state carries. One definition for + every run: a mode-averaged run synthesises its one mode the same way, which is + ``P / A_eff`` for a top-hat profile and the true on-axis value for a real one + -- 1.77 times the average for HE_11, so ``P / A_eff`` would under-report it by + that factor. The on-axis matrix is built once and rescaled with the taper + (:meth:`_on_axis_synthesis`), which is what makes this statistic cheap enough + for the between-planes channel. + """ + if self._modes is None: + msg = ( + "the peak on-axis intensity needs the mode set, which the kernel " + "contract does not carry; construct the backend with " + "NumpyRefBackend(problem, request, modes=modes)" + ) + raise BackendError(msg) + analytic = analytic_field(self._require_grid(), field) + columns = np.tensordot( + self._on_axis_synthesis(self._modes, z), analytic, axes=([1], [0]) + ) + power = np.sum(np.abs(columns) ** 2, axis=tuple(range(columns.ndim - 1))) + return np.asarray(0.5 * EPS0 * C * float(np.max(power))) + + def _nodes_at( + self, + field: Complex[np.ndarray, "n_modes n_pol n_omega"], + z: float, + ) -> Num[np.ndarray, "n_nodes n_components n_to"]: + """Return the physical field at every quadrature node on the fine time grid. + + - Returns: the field in V/m, shape ``(n_nodes, n_components, n_to)``. Here + ``n_components = transform.n_pol * n_pol`` counts physical components, + independently of the state's polarisation axis. + """ + grids, transform = self._problem.grids, self._problem.transform + taper = ( + 1.0 if transform.taper_scale is None else float(transform.taper_scale(z)) + ) + modal_t = passes.to_time(field, grids.crop_index, grids.n_to, kind=self._kind) + return passes.synthesise(modal_t, transform.synthesis, taper, transform.n_pol) + + def _axis_statistics( + self, + field: Complex[np.ndarray, "n_modes n_pol n_omega"] | None, + scan: tuple[np.ndarray, np.ndarray] | None, + z: float, + ) -> dict[str, np.ndarray]: + """Return the four on-axis plasma statistics of the state (SEP 19). + + A rule with a node on the axis hands over that node's row from this + observation's node scan; otherwise the axis row is scanned once + (:func:`solprop.backends.numpy_ref.populations.axis_populations`). + + - ``field``: the state at this plane, shape (n_modes, n_pol, n_omega), or + ``None`` from a backend whose :meth:`_axis_row_populations` reads its own + state. + - ``scan``: this observation's channel fractions and peak rates at every node, + when the node statistics already scanned them. + - Returns: the four ``on_axis_*`` statistics. + """ + if self._modes is None: + msg = ( + "the on-axis plasma statistics need the mode set, which the kernel " + "contract does not carry; construct the backend with " + f"select({self.name!r}, problem, request, modes=modes)" + ) + raise BackendError(msg) + from solprop.backends.populations import ( # noqa: PLC0415 - a cycle + axis_node, + axis_statistics, + ) + + if not self._axis_node_known: + self._axis_node_known = True + self._axis_node = axis_node( + self._problem, + mode_matrix( + self._modes, + on_axis_rule(self._modes[0].dimlimits(0.0)[0]), + 0.0, + components=("x", "y"), + ).synthesis, + ) + if scan is not None and self._axis_node is not None: + fractions, peaks = scan + node = self._axis_node + return axis_statistics(self._problem, z, fractions[:, node], peaks[:, node]) + self.axis_scans += 1 + fractions, peaks = self._axis_row_populations( + field, self._on_axis_synthesis(self._modes, z), z + ) + return axis_statistics(self._problem, z, fractions, peaks) + + def _axis_row_populations( + self, + field: Complex[np.ndarray, "n_modes n_pol n_omega"] | None, + axis: Float[np.ndarray, "n_rows n_modes"], + z: float, + ) -> tuple[Float[np.ndarray, " n_channels"], Float[np.ndarray, " n_channels"]]: + """Scan this plane's axis row: one row, every channel. + + - ``axis``: the mode set's synthesis on the axis at this position + (:meth:`_on_axis_synthesis`). + - Returns: the final ionised fraction and the largest rate on the axis, per + channel. + """ + if field is None: + raise BackendError("the on-axis statistics scan needs the field") + from solprop.backends.numpy_ref.populations import ( # noqa: PLC0415 - a cycle + axis_populations, + ) + + return axis_populations(self._problem, field, z, axis) + + def _on_axis_synthesis( + self, modes: Sequence[Mode], z: float + ) -> Float[np.ndarray, "n_rows n_modes"]: + """Return the mode set's synthesis matrix on the axis, at the current position. + + Built once at ``z = 0`` and rescaled by the transform's own taper factor: the + axis is the single node ``r = 0`` of + :func:`solprop.modes.quadrature.on_axis_rule`, so the law that rescales the + transform's matrices -- a scale-invariant profile goes as ``1/a`` and its + normalisation as ``a^2`` -- applies to it exactly, and a set that is neither + constant nor scale invariant never reaches a backend (``translate.modal``). + Rebuilding the matrix at every call was what kept ``peak_intensity`` out of the + between-planes channel. + + - Returns: shape ``(n_rows, n_modes)``, one row per Cartesian component on the + axis. + """ + if self._on_axis is None: + rule = on_axis_rule(modes[0].dimlimits(0.0)[0]) + matrices = mode_matrix(modes, rule, 0.0, components=("x", "y")) + self._on_axis = np.ascontiguousarray(matrices.synthesis) + taper = self._problem.transform.taper_scale + if taper is None: + return self._on_axis + return self._on_axis * float(taper(z)) + + def _require_grid(self) -> TimeGrid: + """Return the grid the state lives on, or say why statistics cannot be taken.""" + if self._grid is None: + msg = ( + "statistics need the grid the state lives on, which the kernel " + f"contract does not carry; construct the backend with select(" + f"{self.name!r}, problem, request, grid=grid)" + ) + raise BackendError(msg) + return self._grid + + def nonlinear( + self, + lab: Complex[np.ndarray, "n_modes n_pol n_omega"], + bundle: StageScalars, + inverse_propagator: Complex[np.ndarray, "n_modes n_pol n_omega"], + *, + purpose: TDSEPurpose = "predictor", + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: + """Evaluate one stage derivative through the transform passes. + + The pipeline of ``architecture.md`` section 8 for any node count: one batched + inverse transform of every modal column, then, per chunk of + :attr:`node_chunk` nodes, the synthesis GEMM, the fused response pass and + the projection GEMM accumulated over the chunks, then one batched forward + transform, the crop and the prefactor. Mode-averaged propagation is the + one-node, one-column case of exactly this code. + + Parameters + ---------- + lab : numpy.ndarray + The stage's lab-frame field, in the state's layout. + bundle : solprop.translate.stage.StageScalars + The stage's scalars. + inverse_propagator : numpy.ndarray + The factor that carries the derivative back to the step's anchor. + purpose : {'startup', 'predictor', 'corrected', 'diagnostic'}, optional + The host source's accounting label; ignored when none is bound. + + Returns + ------- + numpy.ndarray + The stage derivative in the anchor's frame. + """ + responses = self._problem.responses + grids = self._problem.grids + if self._tdse_binding is not None: + return self._nonlinear_tdse(lab, bundle, inverse_propagator, purpose) + if self._problem.linear.separable is not None: + geometry = self._problem.transform.geometry + evaluate = ( + self._nonlinear_slab + if geometry is not None and geometry.kind == "slab" + else self._nonlinear_free + ) + return evaluate(lab, bundle, inverse_propagator) + if self._general is not None: + return self._nonlinear_general(lab, bundle, inverse_propagator) + if len(responses.response_order) == 1: + # Nothing but the accumulation was compiled, so the polarisation is + # identically zero and the step is the exact linear flow. Running the + # transforms to multiply by nothing would only add round-off -- unless + # ADR-025's in-stage absorber is active, which is a term of its own and + # would otherwise be dropped from a problem that has no response at all. + if not self._in_stage_absorber: + return np.zeros_like(lab) + alone = passes.to_time(lab, grids.crop_index, grids.n_to, kind=self._kind) + return passes.stage_output( + np.zeros_like(lab), + np.zeros_like(lab), + self._tables.omega_window, + inverse_propagator, + self._absorber_term(alone, may_quiet=True), + ) + modal_t = passes.to_time(lab, grids.crop_index, grids.n_to, kind=self._kind) + geometry = self._problem.transform.geometry + if ( + geometry is not None + and geometry.kind == "radial" + and bool(responses.plasma_channels) + and not self._gated_plasma + ): + spectrum = self._radial_plasma_spectrum(modal_t, bundle) + else: + projected, coarse = self._over_nodes(modal_t, bundle) + self._last_projected = projected + self._last_coarse = coarse + self._last_bundle = bundle + spectrum = passes.to_frequency(projected, grids.crop_index, kind=self._kind) + if self._last_plasma is not None: + gated, edge, _, _ = self._last_plasma + spectrum += self._held_streams(gated, edge) + if responses.envelope_plasma is not None: + assert self._last_envelope is not None + drive, loss, _, _ = self._last_envelope + factors = responses.envelope_plasma.factors + spectrum += factors.drude * passes.to_frequency( + drive, grids.crop_index, kind=self._kind + ) + spectrum += factors.loss * passes.to_frequency( + loss, grids.crop_index, kind=self._kind + ) + return passes.stage_output( + spectrum, + self.prefactor(bundle), + self._tables.omega_window, + inverse_propagator, + self._absorber_term(modal_t, may_quiet=True), + ) + + def _nonlinear_tdse( + self, + lab: Complex[np.ndarray, "n_modes n_pol n_omega"], + bundle: StageScalars, + inverse_propagator: Complex[np.ndarray, "n_modes n_pol n_omega"], + purpose: TDSEPurpose, + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: + """Evaluate the declared atomic binding and combine independent P/J sources. + + Steps 1 to 4 are :mod:`solprop.backends.tdse_source`'s, shared with native; + the stage output is this backend's own. + """ + problem = self._problem + grids = problem.grids + binding = self._tdse_binding + assert binding is not None and tdse_of(problem.route) is not None + modal_t = passes.to_time(lab, grids.crop_index, grids.n_to, kind="field") + fields = tdse_source.node_fields(problem, lab, bundle) + result = binding.evaluate( + fields, z=bundle.z1, purpose=purpose, density=bundle.density + ) + polarisation, current = tdse_source.atomic_sources( + fields, result, problem, bundle + ) + source, projection = tdse_source.project_atomic_sources( + polarisation, + current, + result, + problem, + bundle, + self.prefactor(bundle), + edge=tdse_source.atomic_edge_source(result, problem, bundle), + ) + self._tdse_last_purpose, self._tdse_last_z = purpose, bundle.z1 + self._tdse_last_projection = projection + return passes.stage_output( + source, + np.ones_like(source), + grids.omega_window, + inverse_propagator, + self._absorber_term(modal_t), + ) + + def _nonlinear_general( + self, + lab: Complex[np.ndarray, "n_modes n_pol n_omega"], + bundle: StageScalars, + inverse_propagator: Complex[np.ndarray, "n_modes n_pol n_omega"], + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: + """Evaluate one stage derivative through a general modal guide's maps. + + The route's own execution path, in + :mod:`solprop.backends.numpy_ref.general_modal`, beside the fused pass and + not an extension of it. The synthesis is a complex + frequency-dependent map of three Cartesian components, so it happens in the + frequency domain and the field a response sees is the analytic signal. What + is shared with the legacy path is everything after the projection -- the + prefactor, which is the crop scale alone here, the spectral collar, the + in-stage absorber and the return to the interaction picture. + + The quadrature alarm is not scored on this route: the general node rule has + no embedded coarse pair, and a difference that is identically zero read as + convergence would be wrong, as for any unpaired rule. + + A guide with no responding region is short-circuited, as the legacy path + short-circuits a problem whose `response_order` is the accumulation alone. + """ + assert self._general is not None + grids = self._problem.grids + # A guide whose every material region is linear has an identically zero + # tensor, so the source is zero for every state and every position: the + # synthesis, the 3 x n_nodes transforms, the contraction and the projection + # would spend a tenth of a second per step producing it (measured 108 ms on + # the 288-node strand). ADR-025's in-stage absorber is a term of its own and + # is not dropped with it. + spectrum = ( + general_source( + lab, + self._general, + grids.crop_index, + n_to=grids.n_to, + pad_scale=grids.pad_scale, + transform_weights=bundle.transform_weights, + dispersive_densities=bundle.dispersive_kerr_densities, + ) + if self._general_responds + else np.zeros_like(lab) + ) + absorber = None + if self._in_stage_absorber: + absorber = self._absorber_term( + passes.to_time(lab, grids.crop_index, grids.n_to, kind=self._kind) + ) + return passes.stage_output( + spectrum, + self.prefactor(bundle), + grids.omega_window, + inverse_propagator, + absorber, + ) + + def _column_sources( + self, + field_t: np.ndarray, + bundle: StageScalars, + raman: np.ndarray | None, + ) -> passes.NonlinearSources: + """Evaluate one column; the historical integral is benchmark-only. + + - ``field_t``: physical node fields in V/m, with time last. + - ``raman``: damped Raman convolution spectrum, when required by the response. + - Returns: the collared local polarisation in C/m² and the ungated current in + A/m². + """ + responses, grids = self._problem.responses, self._problem.grids + sources = passes.nonlinear_sources( + field_t, + responses, + self._tables.t_window, + kind=self._kind, + density=bundle.density, + preionisation=bundle.preionisation, + dt=grids.dt_fine, + carrier=self._carrier, + raman_spectrum=raman, + scalars=bundle, + ) + if not self._gated_plasma or sources.current is None: + return sources + return passes.NonlinearSources( + sources.polarisation + + self._tables.t_window + * responses.plasma_integral.integrate(sources.current, grids.dt_fine), + None, + ) + + def _held_streams(self, gated: np.ndarray, edge: np.ndarray) -> np.ndarray: + """Transform and combine the current products in polarisation units. + + - ``gated``, ``edge``: fine-time ``gJ`` and ``g'J`` rows, optionally projected + before this call. + - Returns: cropped raw-DFT polarisation-equivalent source, zero on inactive + bins. + """ + grids = self._problem.grids + return passes.held_plasma_spectrum( + gated, edge, grids.omega, grids.crop_index, grids.active_mask + ) + + def _held_current(self, current: np.ndarray) -> np.ndarray: + """Form and transform the two collared products of a nodal current. + + - ``current``: the ungated nodal current in A/m², fine time last. + - Returns: cropped raw-DFT polarisation-equivalent source at the nodes. + """ + return self._held_streams( + self._tables.t_window * current, self._tables.t_window_derivative * current + ) + + def _radial_plasma_spectrum( + self, + modal_t: np.ndarray, + bundle: StageScalars, + ) -> np.ndarray: + """Transform three nodal streams, combine, then project once in frequency.""" + problem = self._problem + transform, grids = problem.transform, problem.grids + spectrum = np.zeros(problem.shape, dtype=np.complex128) + raman = self._raman_spectrum(bundle.raman_rates, bundle.raman_densities) + for first in range(0, transform.n_nodes, self.node_chunk): + rows = slice( + first * transform.n_pol, + (first + self.node_chunk) * transform.n_pol, + ) + field = passes.synthesise( + modal_t, + self._tables.synthesis[rows], + bundle.taper_scale, + transform.n_pol, + ) + sources = self._column_sources(field, bundle, raman) + assert sources.current is not None + nodal = passes.to_frequency( + sources.polarisation, grids.crop_index, kind="field" + ) + nodal += self._held_current(sources.current) + spectrum += passes.project( + nodal, + self._tables.projection[:, rows], + bundle.taper_scale, + transform.n_pol, + ) + return spectrum + + def _nonlinear_free( + self, + lab: np.ndarray, + bundle: StageScalars, + inverse_propagator: np.ndarray, + ) -> np.ndarray: + """Apply transverse FFTs before bounded temporal response transforms. + + - ``lab``: Lab-frame stage spectrum. + """ + problem = self._problem + transform, grids, responses = ( + problem.transform, + problem.grids, + problem.responses, + ) + geometry = transform.geometry + if geometry is None: + msg = "Cartesian nonlinear evaluation requires spatial geometry" + raise BackendError(msg) + shape = (geometry.shape[1], geometry.shape[0], *lab.shape[1:]) + result = np.zeros_like(lab) + if len(responses.response_order) == 1 and not self._in_stage_absorber: + return result + scratch = np.empty_like(lab) + if len(responses.response_order) > 1: + scratch.reshape(shape)[...] = np.fft.ifft2(lab.reshape(shape), axes=(0, 1)) + raman = self._raman_spectrum(bundle.raman_rates, bundle.raman_densities) + for first in range(0, transform.n_nodes, self.node_chunk): + rows = slice(first, first + self.node_chunk) + field_t = grids.pad_scale * passes.to_time( + scratch[rows], grids.crop_index, grids.n_to, kind=self._kind + ) + sources = self._column_sources(field_t, bundle, raman) + polarisation_t = sources.polarisation + scratch[rows] = passes.to_frequency( + polarisation_t, grids.crop_index, kind=self._kind + ) + if sources.current is not None: + scratch[rows] += self._held_current(sources.current) + if responses.envelope_plasma is not None: + drive, loss = self._envelope_sources(field_t, bundle) + factors = responses.envelope_plasma.factors + scratch[rows] += factors.drude * passes.to_frequency( + drive, grids.crop_index, kind=self._kind + ) + scratch[rows] += factors.loss * passes.to_frequency( + loss, grids.crop_index, kind=self._kind + ) + view = scratch.reshape(shape) + view[...] = np.fft.fft2(view, axes=(0, 1)) + data = problem.linear.separable + assert data is not None + for first in range(0, transform.n_nodes, self.node_chunk): + rows = slice(first, first + self.node_chunk) + _, prefactor = separable_values(data, rows) + result[rows] = prefactor * self._tables.omega_window * scratch[rows] + if self._in_stage_absorber: + # The rate is additive to the normalised material term. Reusing the + # transverse scratch avoids a second retained physical spectral volume. + scratch.reshape(shape)[...] = np.fft.ifft2(lab.reshape(shape), axes=(0, 1)) + temporal = self._tables.temporal_rate + timed = temporal is not None and responses.absorber_scheme == "nonlinear" + for first in range(0, transform.n_nodes, self.node_chunk): + rows = slice(first, first + self.node_chunk) + rate = geometry.absorber_rate[rows, None, None] + if not timed: + # A rate of the node alone commutes with the temporal transforms: + # a spatial-only pass needs no temporal pair (SEP 40 section 4.7). + scratch[rows] = -0.5 * rate * scratch[rows] + continue + field_t = passes.to_time( + scratch[rows], grids.crop_index, grids.n_to, kind=self._kind + ) + scratch[rows] = passes.to_frequency( + -0.5 * (rate + temporal) * field_t, + grids.crop_index, + kind=self._kind, + ) + view = scratch.reshape(shape) + view[...] = np.fft.fft2(view, axes=(0, 1)) + result += grids.active_mask * scratch + return result * inverse_propagator + + def _nonlinear_slab( + self, + lab: np.ndarray, + bundle: StageScalars, + inverse_propagator: np.ndarray, + ) -> np.ndarray: + """Evaluate one hybrid planar stage: slab synthesis in x, an FFT in y. + + The ``(p, k_y)`` columns go to ``(p, y)`` rows by the inverse DFT in y, and + the rows to time -- a row is a slab amplitude, whose time signal is a real + field's on a field grid -- so that, as on the modal route, only ``n_p * n_y`` + temporal transforms are taken each way. In time, the slab synthesis (which + carries the pad scale) gives the field at the ``(x, y)`` nodes, the responses + are the Cartesian ones node by node, and the slab rule's dual basis projects + the polarisation back onto the rows; the rows return to frequency and to + ``(p, k_y)``, and each column takes its own prefactor from the separable leaf + (kernel schema 15). The y collar's in-stage rate depends on y alone, so it + acts on the rows directly. + + - ``lab``: Lab-frame stage spectrum. + """ + problem = self._problem + transform, grids, responses = ( + problem.transform, + problem.grids, + problem.responses, + ) + geometry = transform.geometry + assert geometry is not None + result = np.zeros_like(lab) + if len(responses.response_order) == 1 and not self._in_stage_absorber: + return result + n_x, n_y = geometry.shape + n_p = transform.synthesis.shape[1] + rows_f = slab_rows(transform, lab) + temporal = responses.temporal_absorber_fine + timed = temporal is not None and responses.absorber_scheme == "nonlinear" + rows_t = ( + passes.to_time(rows_f, grids.crop_index, grids.n_to, kind=self._kind) + if len(responses.response_order) > 1 or timed + else None + ) + if len(responses.response_order) > 1: + assert rows_t is not None + raman = self._raman_spectrum(bundle.raman_rates, bundle.raman_densities) + envelope = responses.envelope_plasma is not None + plasma = bool(responses.plasma_channels) and not self._gated_plasma + projected = np.zeros_like(rows_t) + # The envelope plasma's Drude drive and loss current, projected as the + # polarisation is; empty unless the response is present. + drives = [ + np.zeros_like(rows_t) for _ in range(2 if envelope or plasma else 0) + ] + # Whole y rows at a time, as many as the node chunk holds. + block = max(1, self.node_chunk // n_x) + for first in range(0, n_y, block): + rows = slice(first * n_p, min(first + block, n_y) * n_p) + count = (rows.stop - rows.start) // n_p + field_t = np.matmul( + transform.synthesis, rows_t[rows].reshape(count, n_p, -1) + ).reshape(count * n_x, *rows_t.shape[1:]) + sources = self._column_sources(field_t, bundle, raman) + current = sources.current + source_rows = [sources.polarisation] + if envelope: + assert responses.envelope_plasma is not None + source_rows.extend( + envelope_sources( + field_t, + responses.envelope_plasma, + bundle, + grids.dt_fine, + grids.t_window_fine, + ) + ) + if current is not None: + source_rows.extend( + ( + grids.t_window_fine * current, + grids.t_window_fine_derivative * current, + ) + ) + for target, source in zip( + (projected, *drives), source_rows, strict=True + ): + target[rows] = np.matmul( + transform.projection, source.reshape(count, n_x, -1) + ).reshape(count * n_p, *rows_t.shape[1:]) + spectrum = passes.to_frequency(projected, grids.crop_index, kind=self._kind) + if envelope: + assert responses.envelope_plasma is not None + factors = responses.envelope_plasma.factors + spectrum += factors.drude * passes.to_frequency( + drives[0], grids.crop_index, kind=self._kind + ) + spectrum += factors.loss * passes.to_frequency( + drives[1], grids.crop_index, kind=self._kind + ) + if plasma: + spectrum += self._held_streams(drives[0], drives[1]) + columns = slab_columns(transform, spectrum) + data = problem.linear.separable + assert data is not None + for first in range(0, transform.n_modes, self.node_chunk): + rows = slice(first, first + self.node_chunk) + _, prefactor = separable_values(data, rows) + result[rows] = prefactor * grids.omega_window * columns[rows] + if self._in_stage_absorber: + result += self._slab_absorber(rows_f, rows_t) + return result * inverse_propagator + + def _slab_absorber( + self, + rows_f: Complex[np.ndarray, "n_modes n_pol n_omega"], + rows_t: Inexact[np.ndarray, "n_modes n_pol n_to"] | None, + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: + """Return the planar in-stage collar's term on the ``(p, k_y)`` columns. + + The collar's rate depends on y alone, so it acts on the ``(p, y)`` rows. With + no temporal rate in-stage it commutes with the temporal transforms, and the + pass needs no temporal pair (SEP 40 section 4.7). + + - ``rows_t``: the same rows in time; required when a temporal rate applies + in-stage. + """ + problem = self._problem + transform, grids, responses = ( + problem.transform, + problem.grids, + problem.responses, + ) + geometry = transform.geometry + assert geometry is not None + n_x, n_y = geometry.shape + n_p = transform.synthesis.shape[1] + rate = np.repeat(geometry.absorber_rate.reshape(n_y, n_x)[:, 0], n_p)[ + :, None, None + ] + temporal = responses.temporal_absorber_fine + if temporal is not None and responses.absorber_scheme == "nonlinear": + assert rows_t is not None + term = passes.to_frequency( + -0.5 * (rate + temporal) * rows_t, grids.crop_index, kind=self._kind + ) + else: + term = -0.5 * rate * rows_f + return grids.active_mask * slab_columns(transform, term) + + def _absorber_term( + self, + modal_t: Inexact[np.ndarray, "n_modes n_pol n_to"], + *, + may_quiet: bool = False, + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"] | None: + """Return the in-stage absorber's contribution, or ``None`` in the other scheme. + + On the modal stage (`may_quiet`) a temporal collar alone is left out while the + boundary monitor finds it quiet (SEP 21): the term is then below + :data:`solprop.monitor.QUIET`, and its transform is the stage's largest cost + after the response's. + + - Returns: the absorber's term on the coarse grid, or ``None`` when the + ``"split_step"`` scheme is active and the rate is applied to the state after + the step instead. + """ + rate = self._tables.temporal_rate + if not self._in_stage_absorber: + return None + if may_quiet and self.collar_quiet and not self._spatial_absorber.size: + return None + grids = self._problem.grids + term = np.zeros_like(modal_t) + if rate is not None and self._problem.responses.absorber_scheme == "nonlinear": + term = -0.5 * rate * modal_t + if self._spatial_absorber.size: + term = term + ( + self._spatial_absorber @ modal_t.reshape(modal_t.shape[0], -1) + ).reshape(modal_t.shape) + return ( + passes.to_frequency(term, grids.crop_index, kind=self._kind) + * grids.active_mask + ) + + def _over_nodes( + self, + modal_t: Inexact[np.ndarray, "n_modes n_pol n_to"], + bundle: StageScalars, + ) -> tuple[ + Num[np.ndarray, "n_modes n_pol n_to"], + Num[np.ndarray, "n_modes_c n_pol_c n_to_c"] | None, + ]: + """Run the response pass over the quadrature in chunks and project it back. + + The chunk loop of ``architecture.md`` section 13: the space-domain buffers are + sized by :attr:`node_chunk` and not by the node count, so a chunk of one + and a chunk of every node differ only in round-off. The embedded coarse rule is + projected in the same loop, from the same node polarisation, because that is + what makes the quadrature alarm free: the two rules share every node the coarse + one has. + + - Returns: the modal polarisation on the fine time grid, and the same under the + embedded coarse rule, or ``None`` when the quadrature has no embedded pair + and the estimate would be identically zero. + """ + responses, grids = self._problem.responses, self._problem.grids + transform = self._problem.transform + taper = bundle.taper_scale + # Once per stage rather than once per chunk: the kernel spectrum does not depend + # on the nodes, and along a gradient it is one real transform of 2 n_to against + # n_modes n_pol transforms of n_to that the stage costs anyway. + raman = self._raman_spectrum(bundle.raman_rates, bundle.raman_densities) + n_pol = transform.n_pol + projected = np.zeros( + (transform.n_modes, self._problem.shape[1], grids.n_to), + dtype=modal_t.dtype, + ) + coarse = None if self._embedded is None else np.zeros_like(projected) + envelope = self._problem.responses.envelope_plasma + envelope_projected = ( + None + if envelope is None + else ( + np.zeros_like(projected), + np.zeros_like(projected), + None if coarse is None else np.zeros_like(coarse), + None if coarse is None else np.zeros_like(coarse), + ) + ) + plasma_projected = ( + ( + np.zeros_like(projected), + np.zeros_like(projected), + None if coarse is None else np.zeros_like(coarse), + None if coarse is None else np.zeros_like(coarse), + ) + if bool(responses.plasma_channels) and not self._gated_plasma + else None + ) + for first in range(0, transform.n_nodes, self.node_chunk): + rows = slice(first * n_pol, (first + self.node_chunk) * n_pol) + field_t = passes.synthesise( + modal_t, self._tables.synthesis[rows], taper, n_pol + ) + sources = self._column_sources(field_t, bundle, raman) + polarisation_t = sources.polarisation + projected = projected + passes.project( + polarisation_t, self._tables.projection[:, rows], taper, n_pol + ) + if coarse is not None and self._embedded is not None: + coarse = coarse + passes.project( + polarisation_t, self._embedded[:, rows], taper, n_pol + ) + if sources.current is not None and plasma_projected is not None: + gated, edge, coarse_gated, coarse_edge = plasma_projected + for target, reduced, window in ( + (gated, coarse_gated, self._tables.t_window), + (edge, coarse_edge, self._tables.t_window_derivative), + ): + current = window * sources.current + target[...] += passes.project( + current, self._tables.projection[:, rows], taper, n_pol + ) + if reduced is not None and self._embedded is not None: + reduced[...] += passes.project( + current, self._embedded[:, rows], taper, n_pol + ) + if envelope is not None and envelope_projected is not None: + drive, loss = self._envelope_sources(field_t, bundle) + full_drive, full_loss, coarse_drive, coarse_loss = envelope_projected + full_drive += passes.project( + drive, self._tables.projection[:, rows], taper, n_pol + ) + full_loss += passes.project( + loss, self._tables.projection[:, rows], taper, n_pol + ) + if ( + self._embedded is not None + and coarse_drive is not None + and coarse_loss is not None + ): + coarse_drive += passes.project( + drive, self._embedded[:, rows], taper, n_pol + ) + coarse_loss += passes.project( + loss, self._embedded[:, rows], taper, n_pol + ) + self._last_plasma = plasma_projected + self._last_envelope = envelope_projected + return projected, coarse + + def _raman_spectrum( + self, rates: tuple[float, ...], densities: tuple[float, ...] = () + ) -> Complex[np.ndarray, "... n_omega_doubled"] | None: + """Return the damped Raman kernel spectrum for a set of rates, anew. + + Memoised on the **decay rates** rather than on the density, because the rates + are what the spectrum depends on: a glass's are zero at every density, so its + kernel is transformed once for the whole run, and a molecular gas on a gradient + presents new rates at every stage and is transformed once per stage. Only the + most recent set is kept, which is the right choice here -- a growing cache would + hold thousands of spectra and hit none. + + - ``rates``: the decay rate of each term at the stage's position, s^-1, off the + bundle. + - ``densities``: component amplitude densities in m^-3, in Raman-component + order. Multiple components include every amplitude in the cache key; one keeps + density outside the convolution and retains the original arithmetic. + - Returns: the spectrum of shape ``(n_to + 1,)``, or ``None`` when no Raman + kernel was compiled. + """ + components = self._problem.responses.raman_terms + if not components: + return None + amplitudes = densities if len(components) > 1 else () + if ( + self._raman_kernel is None + or self._raman_rates != rates + or self._raman_densities != amplitudes + ): + if self._problem.transform.n_pol * self._problem.shape[1] == 2: + self._raman_kernel = passes.tensor_raman_spectrum( + components, + rates, + densities if len(components) > 1 else (1.0,), + self._problem.grids.dt_fine, + ) + elif len(components) == 1: + compiled = components[0] + self._raman_kernel = passes.raman_spectrum( + compiled.undamped, + rates, + compiled.fraction, + self._problem.grids.dt_fine, + ) + else: + self._raman_kernel = passes.mixture_raman_spectrum( + components, rates, densities, self._problem.grids.dt_fine + ) + self._raman_rates = rates + self._raman_densities = amplitudes + self._raman_transforms += 1 + return self._raman_kernel + + def exponents( + self, z: float, dz: float + ) -> Callable[[float, StageScalars], Complex[np.ndarray, "n_modes n_pol n_omega"]]: + """Return the memoised ``dPhi`` of a step, keyed by the stage fraction. + + The anchor is hoisted once per step and each exponent is evaluated once and + negated for the inverse, never evaluated forward and backward independently + (``docs/dev/stepper.md`` section 4). The propagator mode decides whether the + exponents are kept for the whole step or evaluated per stage; the exponent + itself is one linear combination of the terms over the bundle's weights, + whatever the representation (:mod:`solprop.translate.stage`). + + Parameters + ---------- + z : float + Position at the start of the step, m. + dz : float + Length of the step, m. + + Returns + ------- + callable + ``(fraction, bundle) -> dPhi``, of the state's broadcast shape. + """ + del z, dz + if self._propagator_mode == "recompute": + return lambda fraction, bundle: self.delta_phi(bundle) # noqa: ARG005 + cache: dict[float, Complex[np.ndarray, "n_modes n_pol n_omega"]] = {} + + def _exponent( + fraction: float, bundle: StageScalars + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: + """Return ``dPhi`` at a stage fraction, computing it at most once. + + - ``fraction``: the tableau node ``c_i``, dimensionless, in ``[0, 1]``. + """ + if fraction not in cache: + cache[fraction] = self.delta_phi(bundle) + return cache[fraction] + + return _exponent + + def memory_ledger(self) -> dict[str, int]: + """Return the size of every buffer the workspace works in, in bytes. + + The reference backend allocates its stage and transform buffers per pass instead + of keeping a preallocated pool, so this reports what one step has resident at + its peak -- which is what the optimised backends hold for the whole run, and + what the budget of ``docs/dev/architecture.md`` section 8 is measured against. + Every buffer is named even when it is empty. + + The space-domain entries are sized by + :attr:`node_chunk` and not by the + node count, which is the whole point of the chunk loop (``architecture.md`` + section 13): holding ``(n_to, n_pol n_nodes)`` for every node at once would be + 210 MB against 45 MB on the comb-to-continuum target. + + Returns + ------- + dict + Buffer name to bytes. + """ + problem = self._problem + distinct = int(np.unique(np.append(self._stepper.tableau.nodes, 1.0)).size) + general: dict[str, int] = dict.fromkeys(_GENERAL_LEDGER_ROWS, 0) + if self._general is not None: + # The route exists exactly when the tables do (`_general_maps`). + tables = problem.transform.modal_tables + assert tables is not None + general = general_memory(self._general, tables, problem.grids.n_to) + ledger = adams_memory(problem, self._stepper) | { + # The rows' one definition, in `solprop.backends.memory`. + **reference_base_memory( + problem, + self._stepper, + tabulating=self._propagator_mode == "tabulate", + embedded=self._embedded is not None, + noise=self._noise is not None, + statistics_weight=self._statistics_power_weight.nbytes, + spatial_absorber=self._spatial_absorber.nbytes, + node_chunk=self.node_chunk, + ), + # The coupled flow's own resident arrays: the frozen block of every + # section with its Schur factors, the residual's terms, and the one + # forward/inverse action pair held for the section and length last seen. + # All of them are on the active bins alone. + "coupled_flow_factors": 0 + if self._flow is None + else self._flow.vectors.nbytes + + self._flow.triangular.nbytes + + self._flow.frozen.nbytes, + "coupled_flow_residual_terms": 0 + if self._flow is None or self._flow.residual_terms is None + else self._flow.residual_terms.nbytes, + "coupled_flow_actions": 0 + if self._flow is None + else 2 * distinct * self._flow.frozen[0].nbytes, + # The general modal route's buffers are its own: the two execution maps, + # the per-node tensor and the record's resident E/H reference are + # whole-problem allocations no chunk shrinks, and its chunk buffers are + # three components wide and complex on a grid where the legacy ones are + # one or two and real. Every row is zero on every + # other route. + **general, + # A low-storage march's state at its last field-free plane (SEP 22, Q14), + # held from the first such plane; the admission charges it beforehand. + **( + {} + if self._tdse_binding is None + else { + f"tdse_{name}": size + for name, size in self._tdse_binding.memory_ledger().items() + } + ), + } + if self._gated_plasma: + for name in ledger: + if ( + name.startswith("held_current_") + and name != "held_current_derivative" + ): + ledger[name] = 0 + return ledger + + def close(self) -> None: + """Release the buffers. Idempotent.""" + self._state = None + self._noise = None + self._raman_kernel = None + self._last_plasma = None + self._spatial_absorber = np.empty((0, 0)) + self._raman_rates = None + self._raman_densities = None + self._flow_cache = None + self._statistics_power_weight = np.empty(0) + self._held = None + + +@dataclass(frozen=True) +class SourceTables: + """The problem's tables a source evaluation multiplies by. + + The arrays the passes read, gathered once from the problem. + + Attributes + ---------- + synthesis : numpy.ndarray + ``transform.synthesis``. + projection : numpy.ndarray + ``transform.projection``. + t_window : numpy.ndarray + ``grids.t_window_fine``. + t_window_derivative : numpy.ndarray + ``grids.t_window_fine_derivative``. + omega_window : numpy.ndarray + ``grids.omega_window``. + temporal_rate : numpy.ndarray or None + ``responses.temporal_absorber_fine``. + """ + + synthesis: Float[np.ndarray, "n_rows n_modes_s"] + projection: Float[np.ndarray, "n_modes n_columns"] + t_window: Float[np.ndarray, " n_to"] + t_window_derivative: Float[np.ndarray, " n_to"] + omega_window: Float[np.ndarray, " n_omega"] + temporal_rate: Float[np.ndarray, " n_to"] | None + + @classmethod + def of(cls, problem: PropagationProblem) -> "SourceTables": + """Return the problem's own tables. + + Parameters + ---------- + problem : solprop.translate.problem.PropagationProblem + The problem. + + Returns + ------- + SourceTables + References to its arrays, uncopied. + """ + grids = problem.grids + return cls( + problem.transform.synthesis, + problem.transform.projection, + grids.t_window_fine, + grids.t_window_fine_derivative, + grids.omega_window, + problem.responses.temporal_absorber_fine, + ) + + +_GENERAL_LEDGER_ROWS = ( + "general_synthesis", + "general_projection", + "general_stage_maps", + "general_tensor", + "general_electric", + "general_magnetic", + "general_backward_electric", + "general_backward_magnetic", + "general_reciprocal_gram", + "general_coordinate_dual", + "general_scaled_state", + "general_node_spectrum", + "general_node_field", + "general_node_pair", + "general_node_weighted", + "general_node_polarisation", + "general_node_source", + "general_node_drive", + "general_node_histories", + "general_node_drive_spectrum", + "general_node_delayed", + "general_delayed_tensor", + "general_delayed_spectrum", +) +"""The ledger rows of the general modal route, named even when they are empty. + +``memory_ledger`` names every buffer on every route, so a problem that is not a +general modal guide reports these as zero rather than omitting them +(:func:`solprop.backends.numpy_ref.general_modal.general_memory` fills them). +""" + + +def _refuse_inadmissible(problem: PropagationProblem, spec: StatsSpec) -> None: + """Refuse a statistic this problem's basis does not define, by name. + + The second door of the accessor whitelist (:mod:`solprop.output.capability`), + after the run loop's own admission: a caller may build a backend and ask it for + statistics directly, and a general guide's static synthesis matrix is a checked + **zero** placeholder, so an on-axis intensity taken from one would be zero + rather than obviously wrong. + """ + refusal = refusal_for( + declared_capability( + general_modal=problem.transform.modal_tables is not None, + spatial=problem.transform.geometry is not None, + ), + spec.names, + withheld=withheld_accessors( + general_modal=problem.transform.modal_tables is not None, + coupled_flow=problem.linear.coupled_flow is not None, + ), + ) + if refusal is not None: + raise BackendError(refusal) + refusal = axis_refusal(problem, spec.names) + if refusal is not None: + raise BackendError(refusal) + + +def _general_maps( + problem: PropagationProblem, plan: NodeChunkPlan | None = None +) -> GeneralMaps | None: + """Derive the general modal route's maps, or return ``None`` for another route. + + The maps are read out of the leaves once, here, because the route propagates + constant geometry: one interval of one Chebyshev degree along z, so there is + nothing to evaluate per stage. The chunk is the backend's own memory strategy + within the plan's budget, or the plan's exact chunk when one was forced. + + - ``plan``: the backend's node-chunk plan; ``None`` plans the automatic one. + - Returns: the derived maps, or ``None`` when the problem carries no modal tables. + """ + tables = problem.transform.modal_tables + if tables is None: + return None + assert tables.synthesis is not None and tables.projection is not None + chunk = general_planned_chunk( + problem, plan_node_chunk(problem) if plan is None else plan + ) + regional = problem.responses.regional_responses + owner, delayed_tensor, delayed_spectrum = node_delayed_maps(tables, regional) + moving = tables.synthesis.shape[0] * tables.synthesis.shape[1] > 1 + maps = GeneralMaps( + tables.synthesis[0, 0], + tables.projection[0, 0], + node_kerr_tensor(tables, regional), + tables.source_frequency_factor, + chunk, + node_kerr_form(regional), + owner, + delayed_tensor, + delayed_spectrum, + # A moving guide's coefficients, flattened over (n_intervals, n_deg) in the + # order the stage bundle's transform_weights are. + tables.synthesis.reshape(-1, *tables.synthesis.shape[2:]) if moving else None, + tables.projection.reshape(-1, *tables.projection.shape[2:]) if moving else None, + problem.responses.dispersive_kerr, + None if problem.responses.dispersive_kerr is None else tables.region_index, + ) + logger.debug( + "numpy_ref general modal route: %d channels on %d nodes, chunk %d, " + "%d fine bins, gauge %s, %s cubic, %d delayed term(s)", + maps.n_modes, + maps.n_nodes, + maps.node_chunk, + int(tables.omega_fine.size), + tables.gauge_id, + maps.form, + maps.n_terms, + ) + return maps + + +@dataclass(frozen=True) +class _CoupledFlow(CoupledFlowFactors): + """What ``numpy_ref`` holds to execute one coherent block, frozen per section. + + The shared factors (:class:`~solprop.translate.coupled.CoupledFlowFactors`, which + native reads too), with the section axis leading and only the bins the generator + is non-zero at held: the rest of the band has an identity action and the state is + masked to zero there anyway. + + A ``"constant_schur"`` leaf is the one-section case with no residual at all, and + goes through exactly the constant-section arithmetic. A ``"frozen_residual"`` leaf + adds `residual_terms`: the coefficients of ``G(z) - C(z)`` along z, flattened over + ``(n_intervals, n_deg)`` in that order, so that the stage bundle's + ``flow_weights`` combine them into ``G(z_1) - C(z_1)`` exactly as ``phi_delta`` + combines the terms of ``dPhi`` (``docs/dev/kernel-contract.md`` section 1). The + explicit residual is that combination minus the frozen block of the step's own + section. It is applied only on `residual_bins`, the active bins of the requested + band; in the spectral collar outside them the frozen flow alone carries the state + (``docs/guide/waveguides/general-modal.md``). + + Attributes + ---------- + residual_bins : numpy.ndarray + Which bins the explicit residual is applied at, bool, shape ``(n_omega,)``: + `active` and the problem's ``grids.inband_mask``, the requested band: in the + collar beyond it the wall model is outside its validity, and the residual is + left out whether or not the error norm scores there. + n_modes : int + Channels the block couples. + """ + + residual_bins: Bool[np.ndarray, " n_omega_scored"] + n_modes: int + + +_TAYLOR_ORDER = 16 +"""Degree of the Taylor series a scaled triangular exponential is summed to. + +Scaling brings the row-sum norm below :data:`_TAYLOR_SCALE`, so the truncated tail is +at most ``_TAYLOR_SCALE**(n+1)/(n+1)!``, which is 2.1e-20 at this degree -- below the +rounding of the squarings that follow it and of the two unitary products around it. +The alternative, a Pade approximant, buys a lower degree at the cost of a solve per +frequency; the oracle takes the series (``docs/dev/architecture.md`` section 3: +physics and reference code carry no performance tricks). +""" + +_TAYLOR_SCALE = 0.5 +"""Row-sum norm a block is scaled below before the series is summed.""" + +_MAX_FLOW_SQUARINGS = 30 +"""Largest number of squarings a flow action may need before it is refused. + +``2**30`` times the scale is a step whose own generator spans 21 orders of magnitude +in the exponent; a problem that needs it has not been certified by anything the +translation layer measured. +""" + + +def _flow_squarings(largest: float, *, backend: str = "numpy_ref") -> int: + """Return how many squarings an exponent of this row-sum norm needs, or refuse. + + The count brings the norm below :data:`_TAYLOR_SCALE`; past + :data:`_MAX_FLOW_SQUARINGS` the step is refused, as the compiled backends refuse it + whichever route forms their actions. + """ + squarings = 0 + if largest > _TAYLOR_SCALE: + squarings = math.ceil(math.log2(largest / _TAYLOR_SCALE)) + if squarings > _MAX_FLOW_SQUARINGS: + msg = ( + f"{backend} cannot take a coupled flow action whose exponent has row-sum " + f"norm {largest:.4g}: it would need {squarings} squarings, above the " + f"{_MAX_FLOW_SQUARINGS} this backend admits. Cap dz_max" + ) + raise BackendError(msg) + return squarings + + +def _triangular_exponential( + blocks: Complex[np.ndarray, "n_active_e n_modes_e_out n_modes_e_in"], + *, + backend: str = "numpy_ref", +) -> Complex[np.ndarray, "n_active_x n_modes_x_out n_modes_x_in"]: + """Return ``exp(A)`` for a stack of blocks, by scaling, a series and squaring. + + - Returns: ``exp(A)`` in the same layout. + """ + largest = float(np.max(np.sum(abs(blocks), axis=-1), initial=0.0)) + squarings = _flow_squarings(largest, backend=backend) + scaled = blocks / float(2**squarings) + identity = np.broadcast_to( + np.eye(blocks.shape[1], dtype=np.complex128), blocks.shape + ) + series = identity.copy() + for term in range(_TAYLOR_ORDER, 0, -1): + series = identity + scaled @ series / term + for _ in range(squarings): + series = series @ series + return series + + +def _flow_action( + flow: _CoupledFlow, section: int, length: float, *, backend: str = "numpy_ref" +) -> tuple[ + Complex[np.ndarray, "n_active_f n_modes_f_out n_modes_f_in"], + Complex[np.ndarray, "n_active_i n_modes_i_out n_modes_i_in"], +]: + """Return the forward and inverse flow actions of one section over one length. + + ``U = Z exp(l T) Z^H`` and ``U^-1 = Z exp(-l T) Z^H``: the inverse is the matrix + function of the negated exponent, never a numerical inverse of ``U``, so the + interaction picture's backward action is as accurate as its forward one and does + not inherit the conditioning of a solve (``docs/dev/stepper.md`` section 4: no + unbounded inverse propagation). + + - ``length``: distance in m, positive for the forward action. + """ + vectors = flow.vectors[section] + exponent = float(length) * flow.triangular[section] + adjoint = np.conj(np.swapaxes(vectors, -1, -2)) + forward = vectors @ _triangular_exponential(exponent, backend=backend) @ adjoint + inverse = vectors @ _triangular_exponential(-exponent, backend=backend) @ adjoint + return forward, inverse + + +def _residual_action( + flow: _CoupledFlow, section: int, weights: Float[np.ndarray, " n_flow_terms"] +) -> Complex[np.ndarray, "n_active_r n_modes_r_out n_modes_r_in"]: + """Return the explicit residual of one stage, ``R_s(z_1)``, on the active bins. + + ``R_s(z) = D(z) - D(z_s) + H(z) - H(z_s) - C(z)``, evaluated as one linear + combination of the held terms over the bundle's weights minus the frozen block of + the **step's** section. The weights are zero outside the section containing the + stage's own position, so no section's expansion is extrapolated; the frozen block + is the step's, because the exponential the interaction picture is built on is, and + freezing is a rearrangement of the same equation whichever block it names. + + - Returns: the residual in 1/m, shape ``(n_active, n_modes, n_modes)``. + """ + assert flow.residual_terms is not None + return combine(weights, flow.residual_terms) - flow.frozen[section] + + +class BlockResidual: + """``R_s(z) state`` for a held flow's positions (SEP 16 phases 5 and 6). + + A history sample's residual is formed against the section of every trial it serves, + about six; its action depends only on the section and the sample's flow weights, so + each pair's action is formed once and kept, the least recently used dropped first: + each trial's endpoint, at a new position, is used once. + + Parameters + ---------- + flow : _CoupledFlow + The held flow. + """ + + _KEPT = 64 + """Most actions kept: well above a history's samples times the sections it spans.""" + + def __init__(self, flow: _CoupledFlow) -> None: + """Hold the flow, with no action formed yet.""" + self._flow = flow + self._actions: collections.OrderedDict[tuple[int, bytes], np.ndarray] = ( + collections.OrderedDict() + ) + + def __call__( + self, + section: int, + state: Complex[np.ndarray, "n_modes n_pol n_omega"], + weights: Float[np.ndarray, " n_flow_terms"], + ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: + """Return ``R_s(z) state`` for the flow weights of a position. + + Parameters + ---------- + section : int + The step's section, whose frozen block the residual is relative to. + state : numpy.ndarray + The state the residual acts on. + weights : numpy.ndarray + The flow's term weights at the position. + + Returns + ------- + numpy.ndarray + The residual's term, zero off the scored active bins. + """ + key = (section, np.ascontiguousarray(weights).tobytes()) + action = self._actions.get(key) + if action is None: + if len(self._actions) >= self._KEPT: + self._actions.popitem(last=False) + action = _residual_action(self._flow, section, weights) + self._actions[key] = action + else: + self._actions.move_to_end(key) + flow = self._flow + return _residual_drive(state, action, flow.active, flow.residual_bins) + + +def _residual_drive( + lab: Complex[np.ndarray, "n_modes n_pol n_omega"], + action: Complex[np.ndarray, "n_active_d n_modes_d_out n_modes_d_in"], + active: Bool[np.ndarray, " n_omega"], + scored: Bool[np.ndarray, " n_omega_scored"], +) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: + """Return the explicit residual's contribution to one stage's lab-frame source. + + Unlike :func:`_apply_flow`, which *transforms* a state and therefore leaves the + bins it does not cover alone, this **adds a term** and is exactly zero off them: + the residual is zero at every bin the wall formula was never evaluated at, and a + copy of the state there would enter the source as a derivative of its own size. + + It is also zero on the active bins the error norm does not score, the spectral + collar. There the residual can reach a spectral radius the + embedded pair is unstable at, at steps the in-band error allows, and nothing + would see the growth; the frozen flow, exact at any step, carries those bins + alone. The block is diagonal in frequency, so no in-band bin reads them through + it; only the nonlinear source couples them in, at the size of the collar's + content. + + - ``action``: ``R_s(z_1)`` on the active bins, 1/m. + - Returns: ``R_s(z_1) u`` in the state's layout, zero off the scored active bins. + """ + drive = np.zeros_like(lab) + drive[:, :, scored] = np.einsum( + "wij,jpw->ipw", action[scored[active]], lab[:, :, scored] + ) + return drive + + +def _apply_flow( + state: Complex[np.ndarray, "n_modes n_pol n_omega"], + action: Complex[np.ndarray, "n_active_a n_modes_a_out n_modes_a_in"], + active: Bool[np.ndarray, " n_omega"], +) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: + """Apply a per-frequency channel action to the canonical state. + + The identity case is the caller's: a problem with no coupled flow, or the zero + stage fraction, never reaches here. + + - ``state``: the state, or any array of its layout. + - Returns: the state with its channel axis mixed on the active bins and untouched + off them, where the block is zero and the action is the identity. + """ + carried = state.copy() + carried[:, :, active] = np.einsum("wij,jpw->ipw", action, state[:, :, active]) + return carried + + +def _check_flow_conditioning( + flow: _CoupledFlow, + section: int, + pair: tuple[ + Complex[np.ndarray, "n_active_p n_modes_p_out n_modes_p_in"], + Complex[np.ndarray, "n_active_q n_modes_q_out n_modes_q_in"], + ], + dz: float, + *, + backend: str = "numpy_ref", +) -> None: + """Refuse a step whose flow action exceeds the leaf's declared conditioning. + + The certificate row the translation layer declared is + ``exp(dz_max (mu_max - mu_min))``, a bound on ``norm(U)_2 norm(U^-1)_2``; here the + two spectral norms are **measured**, from the singular values of the actual + action, and compared with it. That is the point of a certificate: the row is a + claim the executor checks rather than a number it trusts, and a step longer than + the ``dz_max`` the row was declared over is exactly what this catches. + + The inverse is what the interaction picture carries the nonlinear source back by, + so an unbounded one is an unbounded amplification of that source (the + ``norm(g(b) - V^-1 N(V b))`` inequality). Local re-anchoring is what keeps it + bounded at all: the picture is re-anchored at every accepted step, so no inverse + action is ever taken over more than one of them. + + - ``pair``: the forward and inverse actions over the whole step. + - ``dz``: length of the step, m, used in the refusal. + """ + forward, inverse = pair + if not forward.size: + return + measured = np.linalg.norm(forward, ord=2, axis=(-2, -1)) * np.linalg.norm( + inverse, ord=2, axis=(-2, -1) + ) + _refuse_flow_conditioning(flow, section, measured, dz, backend=backend) + + +def _refuse_flow_conditioning( + flow: _CoupledFlow, + section: int, + measured: Float[np.ndarray, " n_active_m"], + dz: float, + *, + backend: str = "numpy_ref", +) -> None: + """Refuse a step whose measured ``norm(U) norm(U^-1)`` exceeds the certificate. + + The decision of :func:`_check_flow_conditioning`, on a measurement made + elsewhere: a compiled backend measures the two spectral norms in its own + kernels and hands the per-bin products here, so every backend + compares them with the declared row by the same allowance and refuses in the same + words. + + - ``dz``: length of the step, m, used in the refusal. + """ + declared = flow.condition_bound[section] + # A bin whose block is normal has a bound of exactly one and a measured product + # that is one to within the rounding of two spectral norms; the allowance is that + # rounding and nothing more, because the bound is a true bound on the exact + # action and any excess above it is arithmetic. + allowance = 1.0 + 64.0 * flow.n_modes * float(np.finfo(float).eps) + excess = measured / (declared * allowance) + worst = int(np.argmax(excess)) + if excess[worst] > 1.0: + msg = ( + # Enough digits, and the ratio itself: the two quantities differ by as + # little as 1e-13 at the step that first exceeds the bound, and `.4g` + # printed both as the same number with no excess to read. + f"{backend} measured a coupled flow conditioning of " + f"{float(measured[worst]):.12g} over a step of {dz:.4g} m, above the " + f"{float(declared[worst]):.12g} the certificate declares at " + f"active bin {worst} of section {section} -- exceeding it by a factor " + f"{float(excess[worst]):.12g} of the rounding allowance: the inverse " + "action carries the nonlinear source back by the measured factor. Lower " + "dz_max, which is what the bound was declared over" + ) + raise BackendError(msg) + + +def _coupled_flow_maps(problem: PropagationProblem) -> _CoupledFlow | None: + """Decompose the coupled flow this backend will execute, once. + + - Returns: the Schur factors and the certificate, or ``None`` for a problem carrying + no coupled flow. + """ + flow = problem.linear.coupled_flow + if flow is None: + return None + assert flow.generator is not None + factors = coupled_flow_factors(flow) + active, residual = factors.active, factors.residual_terms + sections = len(flow.section_methods) + held = _CoupledFlow( + **vars(factors), + residual_bins=active & problem.grids.inband_mask, + n_modes=flow.n_modes, + ) + logger.debug( + "coupled flow: %d channel(s) on %d of %d bins over %d section(s), %s, largest " + "declared conditioning %.3e, largest declared residual %.3e 1/m, largest " + "declared representation error %.3e", + held.n_modes, + int(np.count_nonzero(active)), + len(active), + sections, + "no explicit residual" if residual is None else f"{residual.shape[0]} terms", + float(np.max(held.condition_bound, initial=1.0)), + float(np.max(flow.residual_norm_bound)), + float(np.max(flow.generator_error)), + ) + return held + + +def _harmonic_carrier( + problem: PropagationProblem, +) -> Complex[np.ndarray, " n_to"] | None: + """Return ``exp(2 i omega_0 t)`` on the fine grid when the harmonic is radiated. + + The envelope-grid third-harmonic term needs the carrier the coarse grid does not + resolve. Until contract version 3 the contract carried neither it nor a fine time + axis and a backend built it from ``omega0``, ``n_to`` and ``dt_fine`` -- one piece + of physics inside a backend, against ``docs/dev/architecture.md`` section 3, which + is why it now arrives as ``grids.carrier_2w0``. The sign is the FFT convention's + (``docs/guide/media/nonlinear.md``). ``validate`` refuses a harmonic term without + the carrier, so only a hand-built problem reaches the refusal here. + + - Returns: the carrier of shape ``(n_to,)``, or ``None`` when no harmonic term is + present. + """ + if not problem.responses.harmonic_carrier: + return None + if problem.grids.carrier_2w0 is None: + msg = ( + "a third-harmonic Kerr term is compiled and grids.carrier_2w0 is absent; " + "the envelope's harmonic sits an offset 2 omega_0 from its carrier and the " + "response pass cannot place it without the factor" + ) + raise BackendError(msg) + return problem.grids.carrier_2w0 + + +def _embedded_projection( + problem: PropagationProblem, +) -> Float[np.ndarray, "n_modes n_columns"] | None: + """Return the embedded coarse-rule projection, when the quadrature has one. + + ``transform.projection_coarse`` equals ``transform.projection`` when the rule has no + embedded pair, in which case the difference of the two projections is identically + zero and reading it as convergence would be wrong + (:class:`solprop.modes.quadrature.ModeMatrices`). The alarm reports ``nan`` there + instead, and the second projection is not computed at all. + + - Returns: the coarse projection, or ``None`` when it is the fine one. + """ + transform = problem.transform + if np.array_equal(transform.projection, transform.projection_coarse): + return None + return transform.projection_coarse + + +def _clean_launch_columns( + field: Complex[np.ndarray, "n_modes n_pol n_omega"], + noise: Complex[np.ndarray, "n_modes n_pol n_omega"], + active: np.ndarray, +) -> Float[np.ndarray, " n_modes"]: + """Return each column's energy in a masked launch, less the input noise it carries. + + That is ``mask(field + noise) - noise``: the launch on the active band, and the + noise alone off it, as a supplied realisation needn't be masked. Formed from the + parts, so that no state has to come back from where it lives to subtract the noise. + + - ``active``: the active band's mask, shape ``(n_omega,)``. + """ + inside = np.abs(field[..., active]) ** 2 + outside = np.abs(noise[..., ~active]) ** 2 + return np.sum(inside, axis=(1, 2)) + np.sum(outside, axis=(1, 2)) diff --git a/tests/backends/adams_traces.py b/tests/backends/adams_traces.py index e39296425..a0b25d871 100644 --- a/tests/backends/adams_traces.py +++ b/tests/backends/adams_traces.py @@ -32,9 +32,12 @@ import numpy as np from solprop._helpers import PLAIN +from solprop.backends.engines import AcceptRecord from solprop.backends.exponential import CarrierChord, CarrierReference from solprop.backends.host.adams import HostAdamsMarch -from solprop.backends.host.driver import HostDriver +from solprop.backends.host.driver import HostDriver, _SessionHooks +from solprop.backends.host.marches import MarchState +from solprop.backends.records import adams_policy from solprop.exceptions import BackendError, ConvergenceError, ResponseBudgetError from solprop.stepper.multistep import Formulation, Multistep from solprop.stepper.schedule import FixedSchedule @@ -165,6 +168,48 @@ def start(self, z: float) -> None: def value(self, slot: int) -> None: """Return no host sample, as a resident engine does.""" + # The engine protocol (`solprop.backends.engines.AdamsEngine`) the reference's + # march calls; the native adapter calls the per-formulation members below. + + def trial(self, z: float, dz: float, stencil: Any) -> np.ndarray: + """Return the scenario's norms for an attempt of the method's formulation.""" + return self._trial( + self.formulation, + z, + dz, + stencil.nodes, + stencil.rows, + stencil.order, + stencil.orders, + ) + + def accept(self, dz: float, free: int, stencil: Any, kept: Any) -> AcceptRecord: + """Record which rows the accepted step keeps and where the new one goes.""" + del dz, stencil + rows = np.array([entry.row for entry in kept], dtype=np.int64) + self._accept(self.formulation, rows, free) + return AcceptRecord() + + def chord_phase(self, z1: float, z2: float) -> float: + """Return the scripted carrier chord's phase over the interval.""" + assert self.carrier is not None + return self.carrier.chord_phase(z1, z2) + + def step_carrier(self, order: int) -> np.ndarray: + """Return no rotations: the script holds no field.""" + del order + return np.zeros(0) + + def begin_attempt(self, cost: int) -> None: + """Reserve nothing: no host source is bound.""" + + def end_attempt(self, outcome: Any) -> None: + """Release nothing.""" + + def reading(self) -> Any: + """Refuse: the scenarios watch no boundary.""" + raise NotImplementedError + def exponential_trial( self, z: float, @@ -319,16 +364,17 @@ def __init__(self, scenario: Scenario) -> None: self._problem = _Problem(scenario) # The run's stepper section, which the march reads off the backend. self._stepper = self._problem.stepper - self._z = scenario.z0 - self._proposal = scenario.proposal + # The march's state, which the native adapter reads and writes through the + # driver's names (the properties below); the reference's march holds it. + self._shadow = MarchState( + z=scenario.z0, proposal=scenario.proposal, norms=deque(maxlen=3) + ) self._collar_quiet = scenario.quiet.get(0, False) self._monitor = ( # pyright: ignore[reportAttributeAccessIssue] None if scenario.quiet_interval is None else _Monitor(scenario.quiet_interval) ) - self._schedule_index = 0 - self._accepted_norms = deque(maxlen=3) self._state: object = "state" self.accepted = 0 self.attempts = 0 @@ -337,13 +383,38 @@ def __init__(self, scenario: Scenario) -> None: self.engine: _Engine | None = None self.march: Any | None = None - # The driver's abstract members, which the march never calls. + def _held_state(self) -> MarchState: + march = self.march + state = getattr(march, "state", None) + return state if isinstance(state, MarchState) else self._shadow - def _trial_step(self, z: float, dz: float) -> Any: - raise NotImplementedError + @property + def _z(self) -> float: + return self._held_state().z - def _apply_mask(self, state: Any) -> Any: - raise NotImplementedError + @_z.setter + def _z(self, value: float) -> None: + self._held_state().z = value + + @property + def _proposal(self) -> float: + return self._held_state().proposal + + @_proposal.setter + def _proposal(self, value: float) -> None: + self._held_state().proposal = value + + @property + def _schedule_index(self) -> int: + return self._held_state().cursor + + @_schedule_index.setter + def _schedule_index(self, value: int) -> None: + self._held_state().cursor = value + + @property + def _accepted_norms(self) -> deque[float]: + return self._held_state().norms def stats(self, spec: Any) -> Any: raise NotImplementedError @@ -389,6 +460,37 @@ class _HostHarness(_Scripted, HostDriver): helpers = PLAIN + def __init__(self, scenario: Scenario) -> None: + super().__init__(scenario) + self._hooks = _SessionHooks(self) + + def adams_march(self, method: Multistep) -> HostAdamsMarch: + """Return the reference's march over the scripted engine, at the start.""" + engine = self.engine + assert engine is not None + carrier = engine.carrier + policy = adams_policy( + self._problem, + self._stepper, + method, + carrier=isinstance(carrier, CarrierReference) and carrier.active, + ) + march = HostAdamsMarch( + engine, + method, + self._hooks, + policy=policy, + field=lambda: np.zeros((1, 1, 1), dtype=np.complex128), + schedule=self._stepper.schedule, + interpolate=self._stepper.interpolate_planes, + shape=(1, 1, 1), + proposal=self.scenario.proposal, + lag=1, + name=self.name, + ) + march.state.z = self.scenario.z0 + return march + def _adams_engine(self, method: Multistep, compensation: str) -> _Engine: """Return a fresh scripted engine, for a march that asks its backend for one.""" del compensation @@ -435,7 +537,14 @@ def _march_state(harness: _Scripted, march: Any) -> dict[str, Any]: "last_rejected": march._last_rejected, "collar_was_quiet": march._collar_was_quiet, "quiet": harness._collar_quiet, - "history": [[entry.z, entry.identity, entry.slot] for entry in march._history], + "history": [ + [ + entry.z, + entry.identity, + entry.row if hasattr(entry, "row") else entry.slot, + ] + for entry in march._history + ], "ledger": [getattr(ledger, name) for name in LEDGER], } @@ -464,7 +573,7 @@ def run_scenario( method = Multistep(formulation=formulation, **scenario.method) harness = _HostHarness(scenario) harness.engine = _Engine(harness, method) - march = HostAdamsMarch(harness, method, engine=harness.engine) + march = harness.adams_march(method) harness.march = march if scenario.targets is not None: targets = list(scenario.targets) diff --git a/tests/backends/free_rows.py b/tests/backends/free_rows.py index 4723f0d01..5f9dd761d 100644 --- a/tests/backends/free_rows.py +++ b/tests/backends/free_rows.py @@ -594,7 +594,7 @@ def ramped_rate_bound(built: Built) -> float: grid = built.grid backend = NumpyRefBackend(problem, built.run_request, grid=grid) try: - matrix = backend._spatial_absorber.copy() + matrix = backend.workspace._spatial_absorber.copy() finally: backend.close() rate = problem.responses.temporal_absorber_fine diff --git a/tests/backends/general_rows.py b/tests/backends/general_rows.py index ab0937610..331f8018a 100644 --- a/tests/backends/general_rows.py +++ b/tests/backends/general_rows.py @@ -95,7 +95,7 @@ ) from modal_provider_cases import general_grid, split_guide from parity_ladder import Built, Row, Statistic -from solprop.backends.numpy_ref.backend import _general_maps +from solprop.backends.numpy_ref.workspace import _general_maps from solprop.boundaries import absorber from solprop.driver import Simulation from solprop.exceptions import GeneralModalBasisWarning diff --git a/tests/backends/native_mixture_launch_probe.py b/tests/backends/native_mixture_launch_probe.py index 95e213b4a..b5c9fb2c6 100644 --- a/tests/backends/native_mixture_launch_probe.py +++ b/tests/backends/native_mixture_launch_probe.py @@ -71,9 +71,12 @@ def launch_case(kerr, n_pol): reference = NumpyRefBackend(problem, run_request, grid=grid) try: reference.set_initial(problem.initial.field0, None) - reference._hoist(0.0) + reference.workspace.hoist(0.0) state = reference._require_state() - peak = max(float(np.max(abs(one))) for one in reference._plasma_nodes(state)) + peak = max( + float(np.max(abs(one))) + for one in reference.workspace._plasma_nodes(state, reference._z) + ) finally: reference.close() assert peak > 0.0 diff --git a/tests/backends/rk_traces.py b/tests/backends/rk_traces.py index 7cdd88efa..6a4151340 100644 --- a/tests/backends/rk_traces.py +++ b/tests/backends/rk_traces.py @@ -33,7 +33,12 @@ import numpy as np -from solprop.backends.host.driver import HostDriver +from solprop.backends import rk_core +from solprop.backends.engines import AcceptRecord +from solprop.backends.host.driver import HostDriver, _SessionHooks +from solprop.backends.host.marches import MarchState +from solprop.backends.host.runge_kutta import RungeKuttaMarch +from solprop.backends.records import runge_kutta_policy from solprop.exceptions import BackendError, ConvergenceError from solprop.stepper.controller import PIController from solprop.stepper.schedule import FixedSchedule, reached @@ -209,9 +214,14 @@ def __init__(self, scenario: Scenario) -> None: hard_kinks=np.array(scenario.kinks, dtype=np.float64), ), ) - self._z = scenario.z0 - self._proposal = scenario.proposal - self._accepted_norms = deque(maxlen=controller.lag + 2) + # The march's state, which the native adapter reads and writes through the + # driver's names (the properties below); the reference's march holds it. + self._shadow = MarchState( + z=scenario.z0, + proposal=scenario.proposal, + norms=deque(maxlen=controller.lag + 2), + ) + self.march: RungeKuttaMarch | None = None self._collar_quiet = scenario.quiet.get(0, False) monitor = None if scenario.quiet_interval is not None or scenario.ceiling or scenario.split: @@ -235,22 +245,59 @@ def __init__(self, scenario: Scenario) -> None: self._halt_ahead = False self._halt_check = None self._natural_due = False - self._schedule_index = 0 self._state: object = "state" self.accepted = 0 self.attempts = 0 self.pending: dict[str, Any] = {} self.events: list[dict[str, Any]] = [] - # The driver's abstract members the march does not call. + def _held_state(self) -> MarchState: + return self._shadow if self.march is None else self.march.state - def _apply_mask(self, state: Any) -> Any: - raise NotImplementedError + @property + def _z(self) -> float: + return self._held_state().z + + @_z.setter + def _z(self, value: float) -> None: + self._held_state().z = value + + @property + def _proposal(self) -> float: + return self._held_state().proposal + + @_proposal.setter + def _proposal(self, value: float) -> None: + self._held_state().proposal = value + + @property + def _schedule_index(self) -> int: + return self._held_state().cursor + + @_schedule_index.setter + def _schedule_index(self, value: int) -> None: + self._held_state().cursor = value + + @property + def _accepted_norms(self) -> deque[float]: + return self._held_state().norms def stats(self, spec: Any) -> Any: raise NotImplementedError - # The driver surface the march uses. + def _controller_policy(self) -> Any: + return runge_kutta_policy(self._problem, self._stepper) # pyright: ignore[reportArgumentType] + + def _on_accepted_step(self) -> None: + pass + + def _start_up(self, norm: float) -> None: + state = self._held_state() + state.proposal, state.norms[-1] = rk_core.start_up( + self._controller_policy(), state.proposal, norm + ) + + # The march's engine, the script. def _trial_step(self, z: float, dz: float) -> tuple[float, object]: self.close() @@ -308,8 +355,49 @@ def snapshot(self) -> dict[str, Any]: } +class _ScriptedEngine: + """The Runge-Kutta engine the reference's march asks, replaced by the script.""" + + in_flight = False + + def __init__(self, harness: _Scripted) -> None: + self.harness = harness + + def trial(self, z: float, dz: float) -> float: + norm, _ = self.harness._trial_step(z, dz) + return norm + + def accept(self, dz: float) -> AcceptRecord: + del dz + return AcceptRecord() + + def extend(self, z: float, dz: float) -> None: + raise NotImplementedError + + def reading(self) -> Any: + raise NotImplementedError + + def reset(self) -> None: + pass + + class _HostHarness(_Scripted, HostDriver): - """The stub over the reference's own driver.""" + """The stub over the reference's own driver and its Runge-Kutta march.""" + + def __init__(self, scenario: Scenario) -> None: + super().__init__(scenario) + self._hooks = _SessionHooks(self) + march = RungeKuttaMarch( + _ScriptedEngine(self), + self._controller_policy(), + self._hooks, + schedule=None, + proposal=scenario.proposal, + name=self.name, + ) + march.state.z = scenario.z0 + march.state.norms = self._shadow.norms + self.march = march def run_scenario(scenario: Scenario) -> dict[str, Any]: @@ -344,10 +432,12 @@ def run_scenario(scenario: Scenario) -> dict[str, Any]: try: for target in targets: while True: + march = harness.march + assert march is not None if schedule is None: - harness._march_to(target) + march.march_to(target) else: - harness._replay_to(schedule, target) + march.replay_to(schedule, target) harness.close() harness.events.append({"target": target, **harness.snapshot()}) # A natural stop returns short of the target; carry on to it. diff --git a/tests/backends/session_rows.py b/tests/backends/session_rows.py index d59d9b5b3..12a4a65f5 100644 --- a/tests/backends/session_rows.py +++ b/tests/backends/session_rows.py @@ -111,7 +111,7 @@ from march_bounds import FIXED_ORDER, march_bound from parity_ladder import Built, Row from solprop.backends.numpy_ref import NumpyRefBackend -from solprop.backends.numpy_ref.backend import _general_maps +from solprop.backends.numpy_ref.workspace import _general_maps from solprop.backends.session import ExecutionOptions from solprop.boundaries import Absorber, absorber from solprop.constants import C @@ -671,9 +671,9 @@ def launch_phase(problem: PropagationProblem, run_request: Any, grid: Any) -> fl backend = NumpyRefBackend(problem, run_request, grid=grid) try: state = problem.initial.field0 - backend._hoist(0.0) - source = backend._nonlinear( - state, backend._stage_scalars(0.0, 0.0), np.ones_like(state) + backend.workspace.hoist(0.0) + source = backend.workspace.nonlinear( + state, backend.workspace.stage_scalars(0.0, 0.0), np.ones_like(state) ) finally: backend.close() diff --git a/tests/backends/synthetic_leaf_cases.py b/tests/backends/synthetic_leaf_cases.py index b853cb96c..e75f303cc 100644 --- a/tests/backends/synthetic_leaf_cases.py +++ b/tests/backends/synthetic_leaf_cases.py @@ -192,11 +192,11 @@ def nonlinear_rate(problem, run_request, grid): reference = NumpyRefBackend(problem, run_request, grid=grid) try: reference.set_initial(problem.initial.field0, None) - reference._hoist(0.0) + reference.workspace.hoist(0.0) state = reference._require_state() - stage = reference._nonlinear( + stage = reference.workspace.nonlinear( state, - reference._stage_scalars(0.0, 0.0), + reference.workspace.stage_scalars(0.0, 0.0), np.ones(problem.shape, complex), ) return 3.0 * float(np.max(np.abs(stage)) / np.max(np.abs(state))) diff --git a/tests/backends/test_backend_ladder.py b/tests/backends/test_backend_ladder.py index 8b7856ac4..9db5dc405 100644 --- a/tests/backends/test_backend_ladder.py +++ b/tests/backends/test_backend_ladder.py @@ -376,7 +376,6 @@ def test_the_observation_hook_is_the_identity_on_the_reference( try: backend.set_initial(problem.initial.field0, None) state = backend._require_state() - assert backend._observed_field(state) is state assert np.array_equal(backend.observe().require_field(), state) finally: backend.close() diff --git a/tests/backends/test_carrier_frame.py b/tests/backends/test_carrier_frame.py index 5230dd943..287f90cfc 100644 --- a/tests/backends/test_carrier_frame.py +++ b/tests/backends/test_carrier_frame.py @@ -46,7 +46,6 @@ phi_functions, refuse_carrier_frame, ) -from solprop.backends.host.adams import HostAdamsMarch from solprop.backends.ledger import CallLedger from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.multistep import ( @@ -198,7 +197,7 @@ def lab_source(lab, position, *, purpose="predictor"): del lab, purpose return source.source(position) - backend._adams_lab_source = lab_source # pyright: ignore[reportAttributeAccessIssue] + backend.workspace.lab_source = lab_source # pyright: ignore[reportAttributeAccessIssue] start = problem.initial.field0 record: dict[str, object] = {} result = run(backend, problem, run_request, record=record) @@ -850,7 +849,7 @@ def gradient_run( problem, run_request, grid=simulation.grid, modes=simulation.modes ) try: - backend._adams = HostAdamsMarch(backend, method, compensation=compensation) + backend._use_adams(method, compensation=compensation) backend.set_initial(problem.initial.field0, None) backend.propagate_to(float(run_request.stepper.save_planes[-1])) return backend.observe().require_field(), backend._adams @@ -1172,7 +1171,10 @@ def test_the_chord_is_the_engine_s_exponent_at_the_reference(backend_name, opera # The stage's scalars as either backend's march forms them, and the # backend's own exponent of them. bundle = scalars(problem, z1, z2, helpers=backend.helpers) - full = backend._delta_phi(bundle) + owner = getattr(backend, "workspace", None) + full = ( + backend._delta_phi(bundle) if owner is None else owner.delta_phi(bundle) + ) expected = np.asarray(full)[0, 0, reference.bin] found = reference.chord.exponent(z1, z2) # The same representation evaluated at one element: a few roundings of the diff --git a/tests/backends/test_compiled_multistep.py b/tests/backends/test_compiled_multistep.py index 496a8f616..a70ba0fd5 100644 --- a/tests/backends/test_compiled_multistep.py +++ b/tests/backends/test_compiled_multistep.py @@ -214,7 +214,7 @@ def assert_propagates_as_the_reference(backend_class, route): } reference = NumpyRefBackend(problem, run_request, **context) try: - reference_back = np.array(reference._adams_propagator(0.0, SOURCE_AT)) + reference_back = np.array(reference.workspace.propagator(0.0, SOURCE_AT)) finally: reference.close() backend = backend_class(problem, run_request, **context) diff --git a/tests/backends/test_dispersive_kerr.py b/tests/backends/test_dispersive_kerr.py index b69add15e..ae4708d37 100644 --- a/tests/backends/test_dispersive_kerr.py +++ b/tests/backends/test_dispersive_kerr.py @@ -118,7 +118,7 @@ def test_the_response_pass_is_the_reference_evaluation(case, evaluator): assert (problem.grids.carrier_2w0 is not None) == (case == "envelope full") backend = NumpyRefBackend(problem, run_request, grid=simulation.grid) try: - bundle = backend._stage_scalars(0.0, 0.0) + bundle = backend.workspace.stage_scalars(0.0, 0.0) finally: backend.close() field_t = node_field(problem, bundle) @@ -151,7 +151,7 @@ def test_a_polynomial_mixture_is_the_sum_of_its_species(): assert leaf.n_channels == 2 backend = NumpyRefBackend(problem, run_request, grid=simulation.grid) try: - bundle = backend._stage_scalars(0.0, 0.0) + bundle = backend.workspace.stage_scalars(0.0, 0.0) finally: backend.close() field_t = node_field(problem, bundle) @@ -191,7 +191,7 @@ def test_a_symmetric_mixture_is_one_cubic_under_its_mixture_filter(): assert leaf is not None and leaf.n_channels == 2 backend = NumpyRefBackend(problem, run_request, grid=simulation.grid) try: - bundle = backend._stage_scalars(0.0, 0.0) + bundle = backend.workspace.stage_scalars(0.0, 0.0) finally: backend.close() field_t = node_field(problem, bundle) @@ -353,7 +353,7 @@ def test_the_pass_refuses_stage_inputs_that_do_not_match_the_leaf(): assert leaf is not None and leaf.carrier backend = NumpyRefBackend(problem, run_request, grid=simulation.grid) try: - bundle = backend._stage_scalars(0.0, 0.0) + bundle = backend.workspace.stage_scalars(0.0, 0.0) finally: backend.close() field_t = node_field(problem, bundle) diff --git a/tests/backends/test_dispersive_kerr_routes.py b/tests/backends/test_dispersive_kerr_routes.py index 5c4b025d0..58a4543d6 100644 --- a/tests/backends/test_dispersive_kerr_routes.py +++ b/tests/backends/test_dispersive_kerr_routes.py @@ -43,7 +43,7 @@ from solprop.backends import node_chunk from solprop.backends.node_chunk import DEFAULT_NODE_BUDGET from solprop.backends.numpy_ref import general_modal, passes -from solprop.backends.numpy_ref.backend import _general_maps +from solprop.backends.numpy_ref.workspace import _general_maps from solprop.boundaries import Absorber from solprop.driver import Simulation, SimulationSettings from solprop.exceptions import ( diff --git a/tests/backends/test_driver.py b/tests/backends/test_driver.py index 6897491ca..9549cc146 100644 --- a/tests/backends/test_driver.py +++ b/tests/backends/test_driver.py @@ -99,7 +99,7 @@ def test_a_rejected_step_is_recorded_and_not_kept(driver): # 5.0 is far above the controller's threshold of one, so the first step is refused # and the second, from the same position, is taken. made = driver(norms=[5.0, 0.1], factor=2.0) - before = present(made._state).copy() + before = present(made.workspace.state).copy() made.propagate_to(LENGTH) observed = made.observe() assert not bool(observed.step_history.accepted[0]) @@ -196,26 +196,21 @@ def test_a_replayed_schedule_takes_its_steps_as_given( def test_a_replay_that_runs_out_says_so(scripted, soliton_problem, narrow_grid): """A schedule too short for the target is an error, not a quiet stop.""" - full, full_request = soliton_problem( + problem, run_request = soliton_problem( narrow_grid, 1, - save_planes=[LENGTH], + save_planes=[LENGTH / 2, LENGTH], schedule=FixedSchedule.uniform(0.0, LENGTH, LENGTH / 8), ) - # The operator table still covers the whole run, so the guard that fires is the - # schedule's own and not the table's. - problem = full - run_request = full_request.with_stepper( - dataclasses.replace( - full_request.stepper, - schedule=FixedSchedule.uniform(0.0, LENGTH / 2, LENGTH / 8), - ) - ) made = scripted(problem, run_request, grid=narrow_grid) made.set_initial(problem.initial.field0, None) made.propagate_to(LENGTH / 2) + # The operator table still covers the whole run, so the guard that fires is the + # schedule's own and not the table's: the march replays a schedule that ends at + # the plane it stands on (the translation refuses one that misses a save plane). + short = FixedSchedule.uniform(0.0, LENGTH / 2, LENGTH / 8) with pytest.raises(BackendError, match="cannot reach"): - made.propagate_to(LENGTH) + made._march.replay_to(short, LENGTH) def test_a_schedule_of_equal_steps_lands_on_a_plane_its_running_sum_misses( @@ -290,9 +285,9 @@ def test_the_input_noise_model_adds_its_realisation_once( resumed = scripted(problem, run_request, grid=narrow_grid) resumed.set_initial(problem.initial.field0, None, z=LENGTH / 2) masked = problem.initial.field0 * problem.grids.active_mask - assert not np.array_equal(present(entrance._state), masked) - assert np.array_equal(present(resumed._state), masked) - assert entrance._noise is None + assert not np.array_equal(present(entrance.workspace.state), masked) + assert np.array_equal(present(resumed.workspace.state), masked) + assert entrance.workspace.noise is None def test_the_modified_noise_model_keeps_its_realisation_apart( @@ -308,14 +303,17 @@ def test_the_modified_noise_model_keeps_its_realisation_apart( made = scripted(problem, run_request, grid=narrow_grid) made.set_initial(problem.initial.field0, None) assert np.array_equal( - present(made._state), problem.initial.field0 * problem.grids.active_mask + present(made.workspace.state), + problem.initial.field0 * problem.grids.active_mask, + ) + drawn = present(made.workspace.noise) + advanced = present( + made.workspace.noise_at(made.workspace.stage_scalars(0.0, LENGTH / 2)) ) - drawn = present(made._noise) - advanced = present(made._noise_at(made._stage_scalars(0.0, LENGTH / 2))) # Dispersion yes, loss and gain no: the magnitude is untouched by the advance. assert np.allclose(np.abs(advanced), np.abs(drawn)) assert not np.array_equal(advanced, drawn) - assert present(made._noise_phase()).shape == problem.shape + assert present(made.workspace.noise_phase(made._z)).shape == problem.shape def test_a_given_realisation_replaces_the_contract_s( @@ -333,17 +331,19 @@ def test_a_given_realisation_replaces_the_contract_s( problem.initial.field0, modified_noise(narrow_grid, np.random.default_rng(11)), ) - assert not np.array_equal(present(made._noise), problem.initial.noise0) + assert not np.array_equal(present(made.workspace.noise), problem.initial.noise0) def test_a_run_without_noise_reports_no_phase(driver, narrow_grid): """``noise_model = "none"`` has neither a realisation nor a phase to report.""" made = driver() + workspace = made.workspace assert ( - made._noise_field(modified_noise(narrow_grid, np.random.default_rng(3))) is None + workspace._noise_field(modified_noise(narrow_grid, np.random.default_rng(3))) + is None ) - assert made._noise_phase() is None - assert made._noise_at(made._stage_scalars(0.0, 0.0)) is None + assert workspace.noise_phase(made._z) is None + assert workspace.noise_at(workspace.stage_scalars(0.0, 0.0)) is None def test_the_guards_refuse_what_cannot_be_done( @@ -382,9 +382,10 @@ def test_statistics_without_a_grid_say_which_backend_to_give_one_to( problem, run_request = soliton_problem(narrow_grid, 1, save_planes=[LENGTH]) made = scripted(problem, run_request) with pytest.raises(BackendError, match="'scripted'"): - made._require_grid() + made.workspace._require_grid() assert ( - scripted(problem, run_request, grid=narrow_grid)._require_grid() is narrow_grid + scripted(problem, run_request, grid=narrow_grid).workspace._require_grid() + is narrow_grid ) @@ -444,7 +445,7 @@ def test_started_is_announced_once_per_load_and_a_resume_announces_it_again(driv assert reporter.order.count("started") == 1 assert reporter.extent == (0.0, LENGTH, 2) - made.set_initial(present(made._state), None, z=LENGTH / 2) + made.set_initial(present(made.workspace.state), None, z=LENGTH / 2) made.propagate_to(LENGTH) assert reporter.order.count("started") == 2 assert reporter.extent == (LENGTH / 2, LENGTH, 2) @@ -803,7 +804,9 @@ def test_the_history_records_the_executed_norm_and_the_controller_the_equivalent assert taken != proposal executed = (taken / made._scale) ** 5 assert float(history.error_norm[last]) == pytest.approx(executed) - assert made._accepted_norms[-1] == pytest.approx(executed * (proposal / taken) ** 5) + assert made._march.state.norms[-1] == pytest.approx( + executed * (proposal / taken) ** 5 + ) # And no accepted step of an adaptive run scores above one, by construction. assert np.all(history.error_norm[accepted] <= 1.0) @@ -816,12 +819,12 @@ def test_the_controller_keeps_only_the_norms_it_reads(driver): """ made = driver() lag = made._stepper.controller.lag - assert made._accepted_norms.maxlen == lag + 2 + assert made._march.state.norms.maxlen == lag + 2 summary = made.propagate_to(LENGTH) assert summary.n_steps > lag + 2 - assert len(made._accepted_norms) == lag + 2 + assert len(made._march.state.norms) == lag + 2 made.set_initial(made._problem.initial.field0, None) - assert len(made._accepted_norms) == 0 + assert len(made._march.state.norms) == 0 # --- the seam a compiled backend subclasses ---------------------------------------- @@ -900,7 +903,7 @@ def test_the_controller_keeps_only_the_norms_it_reads(driver): def test_a_trials_bundles_taken_together_are_kept_until_the_next_hoist(driver): - """``_stage_bundles`` reads the tables once and ``_stage_scalars`` takes the kept. + """``stage_bundles`` reads the tables once and ``stage_scalars`` takes the kept. The bundles equal the per-position ones bit for bit; a later stage at the same anchor and position is the kept bundle itself, and the next step's hoist drops @@ -909,8 +912,9 @@ def test_a_trials_bundles_taken_together_are_kept_until_the_next_hoist(driver): made = driver() z0, dz = LENGTH / 4, LENGTH / 8 positions = [z0 + dz, z0, z0 + 0.5 * dz, z0 + dz] - made._hoist(z0) - together = made._stage_bundles(z0, positions) + workspace = made.workspace + workspace.hoist(z0) + together = workspace.stage_bundles(z0, positions) assert together[0] is together[3] for z1, bundle in zip(positions, together, strict=True): alone = scalars(made._problem, z0, z1) @@ -918,12 +922,12 @@ def test_a_trials_bundles_taken_together_are_kept_until_the_next_hoist(driver): assert np.array_equal(present(bundle.phi_delta), present(alone.phi_delta)) assert np.array_equal(present(bundle.prefactor), present(alone.prefactor)) assert bundle.density == alone.density - assert made._stage_scalars(z0, z1) is bundle + assert workspace.stage_scalars(z0, z1) is bundle # Asked again at the same anchor, nothing is read: the kept bundles come back. - again = made._stage_bundles(z0, positions[1:3]) + again = workspace.stage_bundles(z0, positions[1:3]) assert again[0] is together[1] and again[1] is together[2] - made._hoist(z0 + dz) - assert made._stage_scalars(z0, z0 + dz) is not together[0] + workspace.hoist(z0 + dz) + assert workspace.stage_scalars(z0, z0 + dz) is not together[0] made.close() @@ -943,56 +947,17 @@ def test_the_bundles_a_compiled_backend_packs_are_frozen(): HOST_SURFACE: dict[str, str] = { - "_adams_block": "(self, z: float, dz: float) -> object", - "_adams_lab_source": ( - "(self, lab: jaxtyping.Complex[ndarray, " - "'n_modes n_pol n_omega'], position: float, *, " - "purpose: Literal['startup', 'predictor', 'corrected', " - "'diagnostic'] = 'predictor') -> jaxtyping.Complex[ndarray, " - "'n_modes n_pol n_omega']" - ), - "_adams_propagator": ( - "(self, anchor: float, position: float) -> jaxtyping.Complex[ndarray, " - "'n_modes n_pol n_omega']" - ), - "_adams_source": ( - "(self, lab: jaxtyping.Complex[ndarray, " - "'n_modes n_pol n_omega'], anchor: float, position: float, *, " - "purpose: Literal['startup', 'predictor', 'corrected', " - "'diagnostic'] = 'predictor') -> tuple[jaxtyping.Complex[ndarray, " - "'n_modes n_pol n_omega'], jaxtyping.Complex[ndarray, " - "'n_modes n_pol n_omega']]" - ), - "_apply_mask": ( - "(self, state: jaxtyping.Complex[ndarray, 'n_modes n_pol n_omega']) -> _StateT" - ), - "_begin_plane": "(self) -> None", - "_dense_stages": "(self) -> list[numpy.ndarray]", - "_finish": "(self, state: _StateT, dz: float) -> _StateT", - "_march_to": "(self, target: float) -> None", - "_on_accepted_step": "(self) -> None", - "_record": "(self, z: float, dz: float, norm: float, accepted: bool) -> None", - "_release_source_calls": "(self) -> None", - "_reserve_source_calls": "(self, count: int) -> None", - "_trial_step": "(self, z: float, dz: float) -> tuple[float, _StateT]", "metadata": "(self) -> dict[str, object]", "restore_call_ledgers": ( "(self, logical: collections.abc.Mapping[str, object], " "atomic: collections.abc.Mapping[str, object] | None = None) -> None" ), - "set_initial": ( - "(self, field: jaxtyping.Complex[ndarray, " - "'n_modes n_pol n_omega'], " - "noise: solprop.noise.NoiseRealisation | None, *, z: float = 0.0, " - "resume: bool = False) -> None" - ), - "stats": "(self, spec: solprop.stats.StatsSpec) -> dict[str, numpy.ndarray]", } -"""Every ``HostDriver`` hook a NumPy reference backend overrides (SEP 47 phase 2). +"""Every ``HostDriver`` member the NumPy reference backend overrides (SEP 52). -The reference's own driver is no compiled seam, but its backends are written against -these signatures: a change here changes what ``numpy_ref`` overrides, in the same -commit.""" +Since SEP 52 the physics is the workspace's and the engines', not driver hooks: the +backend overrides only these. A change here changes what ``numpy_ref`` overrides, in +the same commit.""" HOST_ATTRIBUTES = ( "helpers", @@ -1049,20 +1014,17 @@ def test_linear_operator_fields_are_frozen_with_the_driver_seam(): ) -def test_the_adams_and_dense_hooks_default_to_refusal(driver): - # A backend that executes neither the Adams march nor dense observation inherits - # these defaults; the propagator is the shared one, exp(Phi(b) - Phi(a)). +def test_the_workspace_propagator_is_the_operator_s_flow(driver): + # The propagator is the shared one, exp(Phi(b) - Phi(a)); a Runge-Kutta engine + # that holds no accepted step's extension refuses a dense observation. made = driver() - field = made._require_state() - with pytest.raises(BackendError, match="low-call Adams integrator"): - made._adams_source(field, 0.0, LENGTH / 4) - with pytest.raises(BackendError, match="does not observe densely"): - made._dense_stages() - propagator = made._adams_propagator(0.0, LENGTH / 4) + propagator = made.workspace.propagator(0.0, LENGTH / 4) expected = np.exp(delta_phi(made._problem.linear, 0.0, LENGTH / 4)) np.testing.assert_allclose( propagator.reshape(-1), np.broadcast_to(expected, propagator.shape).reshape(-1) ) + with pytest.raises(BackendError, match="no accepted step is held"): + made._runge_kutta_engine.observe(LENGTH / 8) # --- the descriptor (SEP 47 section 6.2) ------------------------------------------- diff --git a/tests/backends/test_envelope_plasma_host.py b/tests/backends/test_envelope_plasma_host.py index 9fd007d34..e2fc1e25a 100644 --- a/tests/backends/test_envelope_plasma_host.py +++ b/tests/backends/test_envelope_plasma_host.py @@ -106,9 +106,9 @@ def test_envelope_population_values_do_not_depend_on_retaining_node_scans(host_c with closing(NumpyRefBackend(problem, run_request, grid=grid)) as backend: backend.set_initial(problem.initial.field0, None) field = problem.initial.field0 - plain = backend._species_statistics(field) + plain = backend.workspace._species_statistics(field, backend._z) scans = [] - retained = backend._species_statistics(field, scans) + retained = backend.workspace._species_statistics(field, backend._z, scans) assert len(scans) == 1 fractions, peaks = scans[0] assert ( @@ -166,7 +166,7 @@ def test_prescribed_density_off_carrier_drude_assembly(host_case): try: bundle = scalars(problem, 0.0, 0.0) lab = problem.initial.field0 - actual = backend._nonlinear(lab, bundle, np.ones_like(lab)) + actual = backend.workspace.nonlinear(lab, bundle, np.ones_like(lab)) assembly = problem.responses.envelope_plasma assert assembly is not None channel = assembly.channels[0] @@ -175,7 +175,7 @@ def test_prescribed_density_off_carrier_drude_assembly(host_case): coefficient = channel.charge_mass_ratio * bundle.plasma_densities[0] * 0.1 overlap = float((transform.projection @ transform.synthesis)[0, 0]) expected = ( - backend._prefactor(bundle) + backend.workspace.prefactor(bundle) * problem.grids.omega_window * assembly.factors.drude * coefficient diff --git a/tests/backends/test_exponential_coupled.py b/tests/backends/test_exponential_coupled.py index a1e913891..de77ab496 100644 --- a/tests/backends/test_exponential_coupled.py +++ b/tests/backends/test_exponential_coupled.py @@ -27,7 +27,6 @@ from sessions.runs import adams_ledger from sessions.runs import run as session_run from solprop.backends import available -from solprop.backends.host.adams import HostAdamsMarch from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.multistep import ( CoupledBlock, @@ -259,7 +258,7 @@ def test_the_untransported_witness_is_for_diagonal_operators_only(): ) try: with pytest.raises(BackendError, match="diagonal operators"): - HostAdamsMarch(backend, EXPONENTIAL, compensation="untransported") + backend._use_adams(EXPONENTIAL, compensation="untransported") finally: backend.close() diff --git a/tests/backends/test_exponential_march.py b/tests/backends/test_exponential_march.py index a1dd17e25..357c45a1b 100644 --- a/tests/backends/test_exponential_march.py +++ b/tests/backends/test_exponential_march.py @@ -27,7 +27,7 @@ from solprop._helpers import PLAIN 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.marches import MarchState from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.multistep import ( compensation_tables, @@ -565,28 +565,6 @@ def test_a_replayed_step_with_a_non_finite_norm_is_refused( backend.close() -DRIVERS = pytest.mark.parametrize("driver", [HostDriver], ids=["host"]) -"""The reference's driver, whose default hooks refuse what it lacks.""" - - -@DRIVERS -def test_a_backend_without_the_lab_frame_source_refuses_the_formulation(driver): - # Every shipped backend implements the hook; an external one that does not is - # told which formulation to use instead. - stub = SimpleNamespace(name="external") - lab = np.zeros((1, 1, 4), dtype=complex) - with pytest.raises(BackendError, match="external does not execute"): - driver._adams_lab_source(stub, lab, 0.0, purpose="startup") - - -@DRIVERS -def test_a_backend_without_a_coupled_flow_hands_the_march_no_block(driver): - # The default hook: every shipped backend that steps a coupled flow returns its - # block; an external one that holds none gives the march nothing to step. - stub = SimpleNamespace(name="external") - assert driver._adams_block(stub, 0.0, 1e-3) is None - - def test_the_formulation_refuses_a_section_it_does_not_step( narrow_grid, soliton_problem ): @@ -646,9 +624,11 @@ def _chooser(march_class, method, collar_rate, *, quiet=False): collar_rate=collar_rate, ) march._order = 5 - # A stand-in, not a driver: the order choice reads one flag from it. - march._backend = cast("Any", SimpleNamespace(_collar_quiet=quiet)) + # A stand-in, not a session: the order choice reads one flag from it. + march._host = cast("Any", SimpleNamespace(collar_quiet=quiet)) march._collar_was_quiet = False + march.state = MarchState(z=0.0, proposal=1.0) + march._engine = cast("Any", SimpleNamespace(reset=lambda: None)) return march @@ -692,7 +672,7 @@ def test_the_step_after_a_collar_returns_is_held_to_its_stable_step(march_class) stable = PEC_REAL_INTERVAL[4] / rate march = _chooser(march_class, EXPONENTIAL, rate, quiet=True) assert march._collar_reentry(1.0) == 1.0 - march._backend._collar_quiet = False + march._host.collar_quiet = False assert march._collar_reentry(1.0) == pytest.approx(stable) assert march._collar_reentry(1.0) == 1.0 assert _chooser(march_class, EXPONENTIAL, 0.0)._collar_reentry(1.0) == 1.0 @@ -706,7 +686,7 @@ def test_a_new_run_clears_the_collar_flag_and_a_pending_floor(march_class): march._collar_was_quiet = True march._last_rejected = True march._floor = ConvergenceError("pending") - march.begin_run() + march.load(0.0, 1.0, 0) assert march._collar_was_quiet is False assert march._last_rejected is False assert march._floor is None diff --git a/tests/backends/test_exponential_routes.py b/tests/backends/test_exponential_routes.py index 61967d959..12249d719 100644 --- a/tests/backends/test_exponential_routes.py +++ b/tests/backends/test_exponential_routes.py @@ -76,8 +76,8 @@ def test_the_lab_frame_sample_is_the_route_source(route): rng = np.random.default_rng(5) field = problem.initial.field0 * (1.0 + 0.1 * rng.standard_normal()) position = 0.3 * float(run_request.stepper.save_planes[-1]) - lab = backend._adams_lab_source(field, position) - transported, propagator = backend._adams_source(field, position, position) + lab = backend.workspace.lab_source(field, position) + transported, propagator = backend.workspace.source(field, position, position) finally: backend.close() # At equal anchor and position the transported source is multiplied by diff --git a/tests/backends/test_exponential_varying.py b/tests/backends/test_exponential_varying.py index d2e0b2636..1f915f41f 100644 --- a/tests/backends/test_exponential_varying.py +++ b/tests/backends/test_exponential_varying.py @@ -22,7 +22,6 @@ from backends.conftest import EQUIVALENCE_BACKENDS from sessions.runs import run as session_run -from solprop.backends.host.adams import HostAdamsMarch from solprop.backends.ledger import CallLedger from solprop.backends.numpy_ref import NumpyRefBackend from solprop.driver.simulation import Simulation @@ -87,7 +86,7 @@ def march(simulation, backend_class=NumpyRefBackend, *, compensation=None, plane ) if compensation is not None: method = run_request.stepper.integrator - backend._adams = HostAdamsMarch(backend, method, compensation=compensation) + backend._use_adams(method, compensation=compensation) try: backend.set_initial(problem.initial.field0, None) steps, fields = [], [] diff --git a/tests/backends/test_free_absorber.py b/tests/backends/test_free_absorber.py index 0294de244..db47bc73c 100644 --- a/tests/backends/test_free_absorber.py +++ b/tests/backends/test_free_absorber.py @@ -243,7 +243,7 @@ def test_cartesian_split_step_temporal_absorber_reconstructs_physical_field( actual = state.field_to_host().reshape(start.shape) else: backend.set_initial(problem.initial.field0, None) - actual = backend._finish(problem.initial.field0.copy(), dz) + actual, _ = backend.workspace.finish(problem.initial.field0.copy(), dz) assert np.max(np.abs(actual - expected)) < bound record_metric( request, diff --git a/tests/backends/test_free_boundaries.py b/tests/backends/test_free_boundaries.py index 5d55be636..432de3a73 100644 --- a/tests/backends/test_free_boundaries.py +++ b/tests/backends/test_free_boundaries.py @@ -35,15 +35,15 @@ def test_cartesian_reference_stage_names_missing_geometry(free_backend_problem): backend = NumpyRefBackend(problem, run_request, grid=grid) try: backend.set_initial(problem.initial.field0, None) - backend._hoist(0.0) - bundle = backend._stage_scalars(0.0, 0.0) + backend.workspace.hoist(0.0) + bundle = backend.workspace.stage_scalars(0.0, 0.0) transform = copy.copy(problem.transform) object.__setattr__(transform, "geometry", None) route = copy.copy(problem.route) object.__setattr__(route, "transform", transform) object.__setattr__(problem, "route", route) with pytest.raises(BackendError, match=r"Cartesian nonlinear.*geometry"): - backend._nonlinear( + backend.workspace.nonlinear( problem.initial.field0, bundle, np.ones(problem.shape, complex), diff --git a/tests/backends/test_free_noise.py b/tests/backends/test_free_noise.py index b86d5c1bb..5280de38a 100644 --- a/tests/backends/test_free_noise.py +++ b/tests/backends/test_free_noise.py @@ -10,6 +10,7 @@ import pytest from bounds import gamma +from builders import reference_trial from sessions.runs import load_native, native_trial from solprop.backends.numpy_ref import NumpyRefBackend from solprop.constants import C @@ -73,10 +74,10 @@ def test_cartesian_modified_noise_enters_the_rotated_nonlinear_field( backend = spatial_backend_class(problem, run_request, grid=grid) try: reference.set_initial(problem.initial.field0, None) - reference._hoist(position) - expected = reference._nonlinear( + reference.workspace.hoist(position) + expected = reference.workspace.nonlinear( rotated, - reference._stage_scalars(position, position), + reference.workspace.stage_scalars(position, position), np.ones(problem.shape, complex), ) # Zero distance isolates one nonlinear evaluation while still exercising @@ -94,7 +95,7 @@ def test_cartesian_modified_noise_enters_the_rotated_nonlinear_field( actual = _testing.stage_to_host(state, 0).reshape(expected.shape) else: captured = [] - nonlinear = backend._nonlinear + nonlinear = backend.workspace.nonlinear def capture(lab, bundle, inverse): stage = nonlinear(lab, bundle, inverse) @@ -102,9 +103,9 @@ def capture(lab, bundle, inverse): captured.append(stage.copy()) return stage - monkeypatch.setattr(backend, "_nonlinear", capture) + monkeypatch.setattr(backend.workspace, "nonlinear", capture) backend.set_initial(problem.initial.field0, noise) - backend._trial_step(position, 0.0) + reference_trial(backend, position, 0.0) actual = captured[0].reshape(expected.shape) scale = np.max(np.abs(expected)) assert scale > 0 diff --git a/tests/backends/test_general_modal.py b/tests/backends/test_general_modal.py index 9735fc836..8055283bd 100644 --- a/tests/backends/test_general_modal.py +++ b/tests/backends/test_general_modal.py @@ -46,7 +46,6 @@ from solprop.backends import select from solprop.backends.node_chunk import general_node_chunk from solprop.backends.numpy_ref import NumpyRefBackend -from solprop.backends.numpy_ref.backend import _GENERAL_LEDGER_ROWS, _general_maps from solprop.backends.numpy_ref.general_modal import ( GeneralMaps, delayed_polarisation, @@ -57,6 +56,7 @@ symmetric_kerr_coefficients, symmetric_monomials, ) +from solprop.backends.numpy_ref.workspace import _GENERAL_LEDGER_ROWS, _general_maps from solprop.boundaries import absorber from solprop.constants import EPS0 from solprop.exceptions import BackendError, TranslationError diff --git a/tests/backends/test_held_plasma_routes.py b/tests/backends/test_held_plasma_routes.py index 35ba59276..74f3de0e4 100644 --- a/tests/backends/test_held_plasma_routes.py +++ b/tests/backends/test_held_plasma_routes.py @@ -53,15 +53,15 @@ def test_source_chunking_and_zero_after_a_nonzero_evaluation(name, rule): options=ExecutionOptions(node_chunk=problem.transform.n_nodes), ) try: - bundle = backend._stage_scalars(0.0, 0.0) + bundle = backend.workspace.stage_scalars(0.0, 0.0) state = problem.initial.field0 ones = np.ones_like(state) - backend._hoist(0.0) - result = backend._nonlinear(state, bundle, ones) + backend.workspace.hoist(0.0) + result = backend.workspace.nonlinear(state, bundle, ones) allowance = relative * np.max(abs(reference)) assert allowance > 0 assert np.max(abs(result - reference)) <= allowance - zero = backend._nonlinear(np.zeros_like(state), bundle, ones) + zero = backend.workspace.nonlinear(np.zeros_like(state), bundle, ones) assert np.array_equal(zero, np.zeros_like(zero)) assert np.array_equal( result[..., ~grid.active_mask], @@ -107,7 +107,7 @@ def test_mixture_production_assembles_both_current_channels(): transform, grids = problem.transform, problem.grids backend = NumpyRefBackend(problem, run_request, grid=grid) try: - backend._hoist(0.0) + backend.workspace.hoist(0.0) nodes = passes.synthesise( passes.to_time( problem.initial.field0, grids.crop_index, grids.n_to, kind="field" @@ -116,7 +116,7 @@ def test_mixture_production_assembles_both_current_channels(): bundle.taper_scale, transform.n_pol, ) - sources = backend._column_sources(nodes, bundle, None) + sources = backend.workspace._column_sources(nodes, bundle, None) assert sources.current is not None # The compatibility polarisation entry point still integrates the physical # current; production consumes the separate streams instead. @@ -165,9 +165,9 @@ def test_mixture_production_assembles_both_current_channels(): expected[..., active] += ( spectra[1][..., active] / q - spectra[2][..., active] / q**2 ) - weight = backend._prefactor(bundle) * grids.omega_window + weight = backend.workspace.prefactor(bundle) * grids.omega_window expected *= weight - actual = backend._nonlinear( + actual = backend.workspace.nonlinear( problem.initial.field0, bundle, np.ones(problem.shape, complex) ) # Projection chunk order, three FFTs and assembly of identical currents. @@ -237,8 +237,11 @@ def test_real_column_decomposition_in_assembled_units( defect = q * v - x - y backend = NumpyRefBackend(problem, run_request, grid=grid) try: - backend._hoist(0.0) - weight = backend._prefactor(bundle)[..., active] * grids.omega_window[active] + backend.workspace.hoist(0.0) + weight = ( + backend.workspace.prefactor(bundle)[..., active] + * grids.omega_window[active] + ) finally: backend.close() allowance = ( diff --git a/tests/backends/test_kperp_collar.py b/tests/backends/test_kperp_collar.py index 5b3e14895..00d823ce8 100644 --- a/tests/backends/test_kperp_collar.py +++ b/tests/backends/test_kperp_collar.py @@ -124,7 +124,13 @@ def test_the_rate_never_reaches_the_noise_phase(backend): # The stage's scalars as either backend's march forms them, and the # backend's own unitary phase of them. bundle = scalars(problem, 0.0, 7e-4, helpers=selected.helpers) - phases.append(np.array(selected._unitary_phase(bundle))) + owner = getattr(selected, "workspace", None) + phase = ( + selected._unitary_phase(bundle) + if owner is None + else owner.unitary_phase(bundle) + ) + phases.append(np.array(phase)) finally: selected.close() # The rate is real: Im Phi is the same arithmetic, an exact structural identity. diff --git a/tests/backends/test_low_storage.py b/tests/backends/test_low_storage.py index 03d59e6e4..96dea2082 100644 --- a/tests/backends/test_low_storage.py +++ b/tests/backends/test_low_storage.py @@ -19,7 +19,7 @@ import signal import warnings from types import SimpleNamespace -from typing import cast +from typing import Any, cast import numpy as np import pytest @@ -51,9 +51,9 @@ step_budget, ) from legacy_geometry import with_collar_rate -from solprop.backends.host.driver import HostDriver from solprop.backends.low_storage import HostLowStorage, schedule_key, table_steps from solprop.backends.numpy_ref import NumpyRefBackend +from solprop.backends.numpy_ref.workspace import NumpyWorkspace from solprop.backends.registry import resolve_name from solprop.backends.session import Start from solprop.boundaries import absorber @@ -487,7 +487,7 @@ def evaluation_difference(problem, run_request, grid, gnlse): backend = NumpyRefBackend(problem, run_request, grid=grid) backend.set_initial(problem.initial.field0, None) state = backend._require_state() - march = backend._adams_lab_source(state, 0.0)[0, 0] + march = backend.workspace.lab_source(state, 0.0)[0, 0] backend.close() scaffold = gnlse_source(gnlse, grid)(state[0, 0]) assert np.linalg.norm(scaffold) > 0 @@ -890,7 +890,7 @@ class AbandonedError(RuntimeError): def abandon_after(backend, evaluations): """Make the backend's source raise after `evaluations` evaluations.""" - original = backend._adams_lab_source + original = backend.workspace.lab_source count = [0] def evaluate(lab, position, **keywords): @@ -899,8 +899,8 @@ def evaluate(lab, position, **keywords): raise AbandonedError return original(lab, position, **keywords) - backend._adams_lab_source = evaluate - return lambda: setattr(backend, "_adams_lab_source", original) + backend.workspace.lab_source = evaluate + return lambda: setattr(backend.workspace, "lab_source", original) def test_an_abandoned_step_leaves_every_reader_refusing(lifecycle, narrow_grid, scales): @@ -950,13 +950,13 @@ def test_a_diverged_state_stops_the_replay_in_flight(lifecycle, narrow_grid): problem, run_request, length = lifecycle() backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) backend.set_initial(problem.initial.field0, None) - original = backend._adams_lab_source + original = backend.workspace.lab_source def overflowing(lab, position, **keywords): # An overflowed source, as a step past a stability limit leaves one. return np.full_like(original(lab, position, **keywords), np.nan) - backend._adams_lab_source = overflowing + backend.workspace.lab_source = overflowing with pytest.raises(ConvergenceError, match=r"non-finite state.*lost"): backend.propagate_to(length) with pytest.raises(BackendError, match="abandoned in flight"): @@ -995,9 +995,8 @@ def test_an_atomic_engine_commits_its_step_whole(lifecycle, narrow_grid, atomic) backend.set_initial(problem.initial.field0, None) assert backend._low_storage is not None engine = backend._low_storage.engine - assert engine.atomic is atomic assert isinstance(engine, HostLowStorage) is not atomic - original = engine.step + original = engine.trial def interrupted(z, dz): squared = original(z, dz) @@ -1005,12 +1004,12 @@ def interrupted(z, dz): signal.raise_signal(signal.SIGINT) return squared - engine.step = interrupted + engine.trial = interrupted with handled(), pytest.raises(KeyboardInterrupt): backend.propagate_to(length) schedule = run_request.stepper.schedule assert schedule is not None - assert backend._in_flight == (0.0, float(schedule.steps[0])) + assert backend.in_flight == (0.0, float(schedule.steps[0])) with pytest.raises(BackendError, match="abandoned in flight"): backend.observe() backend.close() @@ -1076,7 +1075,7 @@ def simulation(): uninterrupted = simulation().run(progress="none") path = tmp_path / "run.h5" - original = NumpyRefBackend._adams_lab_source + original = NumpyWorkspace.lab_source count = [0] def evaluate(self, lab, position, **keywords): @@ -1086,14 +1085,14 @@ def evaluate(self, lab, position, **keywords): return original(self, lab, position, **keywords) try: - NumpyRefBackend._adams_lab_source = evaluate + NumpyWorkspace.lab_source = evaluate with ( caplog.at_level(logging.WARNING, logger=run_module.__name__), pytest.raises(AbandonedError) as caught, ): simulation().run(path, progress="none") finally: - NumpyRefBackend._adams_lab_source = original + NumpyWorkspace.lab_source = original assert any("no terminal checkpoint" in note for note in caught.value.__notes__) assert "abandoned in flight" in caplog.text with open_file(path) as stored: @@ -1138,14 +1137,18 @@ def evaluate(self, lab, position, **keywords): def held_volumes(backend, field): - """Return the bytes every state-sized array the backend and its engine hold owns. + """Return the bytes every state-sized array the workspace and the engine hold owns. - Each attribute of the backend and of the march's engine, and each array inside a - tuple attribute, is followed to the memory it views: a broadcast view of one - element owns one element, however large it reads. + Each attribute of the backend, its workspace and the march's engine, and each + array inside a tuple attribute, is followed to the memory it views: a broadcast + view of one element owns one element, however large it reads. """ found = {} - owners = {"backend": backend, "engine": backend._low_storage.engine} + owners = { + "backend": backend, + "workspace": backend.workspace, + "engine": backend._low_storage.engine, + } for owner_name, owner in owners.items(): for name, value in vars(owner).items(): items = value if isinstance(value, tuple) else (value,) @@ -1189,7 +1192,7 @@ def test_the_ledger_holds_three_registers_the_scratch_and_the_table(mode, collar row: ledger[row] for row in ("register_accumulator", "register_stage", "propagators") } - expected = {"backend._state", "engine._accumulator", "engine._stage"} + expected = {"workspace._state", "engine._accumulator", "engine._stage"} if mode == "tabulate": expected.add("engine._table") assert held_volumes(backend, field) == dict.fromkeys(expected, field) @@ -1272,7 +1275,7 @@ def test_each_pass_carries_the_draw_at_its_own_position(monkeypatch): backend = NumpyRefBackend(problem, run_request, grid=grid) backend.set_initial(problem.initial.field0, noise) inputs, carried = [], [] - source, nonlinear = backend._adams_lab_source, backend._nonlinear + source, nonlinear = backend.workspace.lab_source, backend.workspace.nonlinear def lab_source(lab, position, **keywords): inputs.append((position, lab.copy())) @@ -1282,8 +1285,8 @@ def capture(lab, bundle, inverse): carried.append(lab.copy()) return nonlinear(lab, bundle, inverse) - monkeypatch.setattr(backend, "_adams_lab_source", lab_source) - monkeypatch.setattr(backend, "_nonlinear", capture) + monkeypatch.setattr(backend.workspace, "lab_source", lab_source) + monkeypatch.setattr(backend.workspace, "nonlinear", capture) backend.propagate_to(length) backend.close() z, h = float(schedule.edges[1]), float(schedule.steps[1]) @@ -1412,13 +1415,13 @@ def test_the_table_is_keyed_on_its_run_and_rebuilt_where_the_run_changes( assert isinstance(engine, HostLowStorage) backend.set_initial(problem.initial.field0, None) built = [] - propagator = backend._adams_propagator + propagator = backend.workspace.propagator def counted(anchor, position): built.append((anchor, position)) return propagator(anchor, position) - backend._adams_propagator = counted + backend.workspace.propagator = counted backend.propagate_to(length / 2) backend.propagate_to(length) assert len(built) == 1 @@ -1437,8 +1440,8 @@ def counted(anchor, position): backend = NumpyRefBackend(varied, varied_request, grid=narrow_grid) backend.set_initial(varied.initial.field0, None) built.clear() - propagator = backend._adams_propagator - backend._adams_propagator = counted + propagator = backend.workspace.propagator + backend.workspace.propagator = counted backend.propagate_to(length) assert len(built) == varied_schedule.n_steps # A load drops the table, which the next step builds again. @@ -1466,44 +1469,38 @@ def test_a_run_s_key_is_its_mean_step_and_far_runs_keep_one_key(): assert len(set(keys.tolist())) == 2 -class LinearSource(HostDriver): - """A stand-in backend whose source is ``lambda u`` and whose flow is one. +class LinearSource: + """A stand-in workspace whose source is ``lambda u`` and whose flow is one. - Built without the driver's initialiser, which needs a translated problem: the host - engine reads only the members set here. + The host engine reads only the members set here. """ def __init__(self, rate, state): self.rate = rate self._state = state - self._low_storage = None - self._stepper = SimpleNamespace(propagator_mode="recompute") - self._problem = SimpleNamespace( + self.problem = SimpleNamespace( flags=SimpleNamespace(constant_linop=True), grids=SimpleNamespace(norm_mask=np.ones(state.shape[-1], dtype=bool)), ) - def _trial_step(self, z, dz): - raise NotImplementedError - - def _apply_mask(self, state): - raise NotImplementedError + def committed(self): + return self._state - def stats(self, spec): - raise NotImplementedError + def install(self, state): + self._state = state - def _hoist(self, z0): + def hoist(self, z0): del z0 - def _stage_bundles(self, z0, positions): + def stage_bundles(self, z0, positions): del z0, positions return () - def _adams_propagator(self, anchor, position): + def propagator(self, anchor, position): del anchor, position return np.ones_like(self._state) - def _adams_lab_source(self, lab, position, *, purpose="predictor"): + def lab_source(self, lab, position, *, purpose="predictor"): del position, purpose return self.rate * lab @@ -1520,9 +1517,9 @@ def test_a_linear_step_is_rk4_s_stability_function_and_reads_its_stiffness(rate) state = rng.standard_normal((1, 1, 64)) + 1j * rng.standard_normal((1, 1, 64)) start = state.copy() step = 0.05 - backend = LinearSource(rate, state) - engine = HostLowStorage(backend, MARCH) - squared = engine.step(0.0, step) + workspace = LinearSource(rate, state) + engine = HostLowStorage(cast("Any", workspace), MARCH, None, "recompute") + squared = engine._step(state, 0.0, step) x = step * rate expected = (1 + x + x**2 / 2 + x**3 / 6 + x**4 / 24) * start assert np.allclose(state, expected, rtol=64 * EPS, atol=0) @@ -1542,14 +1539,14 @@ def test_the_march_warns_once_when_a_step_passes_the_interval( assert backend._low_storage is not None engine = backend._low_storage.engine assert isinstance(engine, HostLowStorage) - step = engine.step + step = engine.trial def stiff(z, dz): squared = step(z, dz) engine.stiffness = 3.0 return squared - engine.step = stiff + engine.trial = stiff with caplog.at_level(logging.WARNING, logger="solprop.backends.host.low_storage"): backend.propagate_to(length / 2) history = backend.observe().step_history @@ -1630,7 +1627,7 @@ def record_outcome(self, outcome, checkpoint=None): absorber=False, noise=None, ) - original = NumpyRefBackend._adams_lab_source + original = NumpyWorkspace.lab_source count = [0] def evaluate(self, lab, position, **keywords): @@ -1640,11 +1637,11 @@ def evaluate(self, lab, position, **keywords): return original(self, lab, position, **keywords) try: - NumpyRefBackend._adams_lab_source = evaluate + NumpyWorkspace.lab_source = evaluate with pytest.raises(AbandonedError) as caught: simulation.run(Unwritable(), progress="none") finally: - NumpyRefBackend._adams_lab_source = original + NumpyWorkspace.lab_source = original notes = caught.value.__notes__ assert any("no terminal checkpoint" in note for note in notes) assert any("manufactured record failure" in note for note in notes) diff --git a/tests/backends/test_mixture_statistics.py b/tests/backends/test_mixture_statistics.py index 5cc9bf0ca..bd5f7b9df 100644 --- a/tests/backends/test_mixture_statistics.py +++ b/tests/backends/test_mixture_statistics.py @@ -100,7 +100,7 @@ def test_numpy_species_statistics_match_the_independent_node_scans(): "peak_ionisation_rate", ) values = backend.stats(StatsSpec(names=names, periodic=names[:2])) - nodes = backend._nodes_at(backend._require_state()) + nodes = backend.workspace._nodes_at(backend._require_state(), backend._z) rates, fractions = passes.plasma_channel_fractions( nodes, problem.responses.plasma_channels, diff --git a/tests/backends/test_monitor_reduction.py b/tests/backends/test_monitor_reduction.py index 13b6c892b..78ae7f13d 100644 --- a/tests/backends/test_monitor_reduction.py +++ b/tests/backends/test_monitor_reduction.py @@ -308,7 +308,7 @@ def test_a_reading_needs_a_monitor(backend: str) -> None: driver = as_driver(made) driver.set_initial(problem.initial.field0, None) with pytest.raises(BackendError, match="no boundary monitor"): - driver._boundary_energies(driver._require_state()) + driver._boundary_energies() else: # The native state's own reduction, which its session reads at a check. from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] diff --git a/tests/backends/test_multistep_march.py b/tests/backends/test_multistep_march.py index 45cdb9caf..7790c7f44 100644 --- a/tests/backends/test_multistep_march.py +++ b/tests/backends/test_multistep_march.py @@ -282,8 +282,8 @@ def test_call_budget_stops_before_overspending(narrow_grid, soliton_problem): # PEC needs one call a trial: the stop leaves none unspent. assert ledger.total == budget assert 0.0 < caught.value.z < SOLITON_PERIOD - assert backend._state is not None - np.testing.assert_array_equal(caught.value.field, backend._state) + assert backend.workspace.state is not None + np.testing.assert_array_equal(caught.value.field, backend.workspace.state) backend.close() diff --git a/tests/backends/test_native_error_norm.py b/tests/backends/test_native_error_norm.py index 4043878fc..c6799874b 100644 --- a/tests/backends/test_native_error_norm.py +++ b/tests/backends/test_native_error_norm.py @@ -32,6 +32,7 @@ import pytest from bounds import EPS, gamma, higham_gamma +from builders import reference_trial from sessions.runs import load_native, native_trial, run from solprop.backends.numpy_ref import NumpyRefBackend from solprop.stepper import PIController @@ -92,9 +93,9 @@ def _operands(backend, reference, problem, run_request, dz): for index in range(len(tableau.nodes)) ] reference.set_initial(problem.initial.field0, None) - reference._trial_step(0.0, dz) - step = reference._stage_scalars(0.0, dz) - propagator = np.exp(reference._exponents(0.0, dz)(1.0, step)) + reference_trial(reference, 0.0, dz) + step = reference.workspace.stage_scalars(0.0, dz) + propagator = np.exp(reference.workspace.exponents(0.0, dz)(1.0, step)) return stages, propagator @@ -126,7 +127,7 @@ def test_the_rk_norm_is_the_reference_norm_of_native_s_operands( before = problem.initial.field0 backend._native_state.finish(dz) after = _field(backend, problem) - wanted = reference._error_norm(carried, before, after) + wanted = reference.workspace.error_norm(carried, before, after) controller = run_request.stepper.controller mask = problem.grids.norm_mask scale = float( @@ -157,7 +158,7 @@ def test_a_whole_trial_scores_as_the_reference_s_trial_does( backend, score = _native_trial(problem, run_request, field_grid, dz) try: reference.set_initial(problem.initial.field0, None) - wanted, _ = reference._trial_step(0.0, dz) + wanted, _ = reference_trial(reference, 0.0, dz) finally: backend.close() reference.close() @@ -253,7 +254,7 @@ def test_a_weighted_controller_scores_as_the_reference_s_does( backend, score = _native_trial(problem, run_request, field_grid, dz) try: reference.set_initial(problem.initial.field0, None) - wanted, _ = reference._trial_step(0.0, dz) + wanted, _ = reference_trial(reference, 0.0, dz) finally: backend.close() reference.close() diff --git a/tests/backends/test_native_held_projection_budget.py b/tests/backends/test_native_held_projection_budget.py index 05683c155..47fb358d9 100644 --- a/tests/backends/test_native_held_projection_budget.py +++ b/tests/backends/test_native_held_projection_budget.py @@ -88,9 +88,9 @@ def test_embedded_current_projection_accumulates_partial_chunks( assert relative > 0 reference = NumpyRefBackend(problem, run_request, grid=grid, options=options) try: - reference._hoist(0.0) + reference.workspace.hoist(0.0) state = problem.initial.field0 - bundle = reference._stage_scalars(0.0, 0.0) + bundle = reference.workspace.stage_scalars(0.0, 0.0) transform, grids = problem.transform, problem.grids nodes = passes.synthesise( passes.to_time(state, grids.crop_index, grids.n_to, kind="field"), @@ -98,7 +98,7 @@ def test_embedded_current_projection_accumulates_partial_chunks( bundle.taper_scale, transform.n_pol, ) - current = reference._column_sources(nodes, bundle, None).current + current = reference.workspace._column_sources(nodes, bundle, None).current assert current is not None # SEP 27 section 4.6: the existing column allowance on J before either collar # multiplies it, then projected with absolute weights. @@ -124,12 +124,12 @@ def test_embedded_current_projection_accumulates_partial_chunks( ) for collar in collars ] - reference._nonlinear(state, bundle, np.ones_like(state)) - assert reference._last_plasma is not None - _, _, coarse_gate, coarse_edge = reference._last_plasma + reference.workspace.nonlinear(state, bundle, np.ones_like(state)) + assert reference.workspace._last_plasma is not None + _, _, coarse_gate, coarse_edge = reference.workspace._last_plasma assert coarse_gate is not None and coarse_edge is not None assert np.max(abs(coarse_gate)) > 0 and np.max(abs(coarse_edge)) > 0 - expected = reference._held_streams(coarse_gate, coarse_edge) + expected = reference.workspace._held_streams(coarse_gate, coarse_edge) finally: reference.close() # The forward transform: l1 -> linf of each row's allowance, with its own normwise diff --git a/tests/backends/test_native_mixture_fractions.py b/tests/backends/test_native_mixture_fractions.py index 949c08ec2..2d53191bb 100644 --- a/tests/backends/test_native_mixture_fractions.py +++ b/tests/backends/test_native_mixture_fractions.py @@ -52,10 +52,16 @@ def oracle(kerr, n_pol): reference = NumpyRefBackend(problem, run_request, grid=grid) try: reference.set_initial(problem.initial.field0, None) - reference._hoist(0.0) - bundle = reference._stage_scalars(0.0, 0.0) + reference.workspace.hoist(0.0) + bundle = reference.workspace.stage_scalars(0.0, 0.0) fields = np.real( - np.concatenate(list(reference._plasma_nodes(reference._require_state()))) + np.concatenate( + list( + reference.workspace._plasma_nodes( + reference._require_state(), reference._z + ) + ) + ) ) finally: reference.close() diff --git a/tests/backends/test_native_planar_statistics.py b/tests/backends/test_native_planar_statistics.py index 8ba5d110e..c8d7ffd01 100644 --- a/tests/backends/test_native_planar_statistics.py +++ b/tests/backends/test_native_planar_statistics.py @@ -167,8 +167,8 @@ def finished(problem, run_request, grid, rows, dz, options=None): reference = NumpyRefBackend(problem, run_request, grid=grid, options=options) try: reference.set_initial(problem.initial.field0, None) - reference._hoist(0.0) - expected = np.array(reference._finish(rows.copy(), dz)) + reference.workspace.hoist(0.0) + expected = np.array(reference.workspace.finish(rows.copy(), dz)[0]) finally: reference.close() backend = NativeBackend(problem, run_request, grid=grid, options=options) diff --git a/tests/backends/test_node_chunk.py b/tests/backends/test_node_chunk.py index 155e17391..ae0c44d44 100644 --- a/tests/backends/test_node_chunk.py +++ b/tests/backends/test_node_chunk.py @@ -539,7 +539,7 @@ def test_a_general_guide_takes_the_plan_s_budget(native_backend): general_problem, strand, ) - from solprop.backends.numpy_ref.backend import _general_maps # noqa: PLC0415 + from solprop.backends.numpy_ref.workspace import _general_maps # noqa: PLC0415 problem, run_request, _ = general_problem(strand(ARGON_FILL), "symmetric", "real") automatic = plan_node_chunk(problem) diff --git a/tests/backends/test_numpy_mixture_raman.py b/tests/backends/test_numpy_mixture_raman.py index 1c6d66d5e..29107576d 100644 --- a/tests/backends/test_numpy_mixture_raman.py +++ b/tests/backends/test_numpy_mixture_raman.py @@ -23,14 +23,19 @@ from solprop.translate.stage import scalars +def _owner(backend): + """Return what holds a backend's Raman kernel: the reference's workspace.""" + return getattr(backend, "workspace", backend) + + def raman_refreshes(backend): """Read the selected backend's owned Raman kernel refresh counter.""" - return backend._raman_transforms + return _owner(backend)._raman_transforms def prepare_raman(backend, rates, densities): """Exercise the actual cached Raman owner without a propagation.""" - backend._raman_spectrum(rates, densities) + _owner(backend)._raman_spectrum(rates, densities) @pytest.fixture @@ -81,23 +86,26 @@ def test_raman_cache_tracks_every_amplitude_and_decay_rate(case): grid, problem, run_request = case backend = NumpyRefBackend(problem, run_request, grid=grid) bundle = scalars(problem, 0.0, 0.0) - first = backend._raman_spectrum(bundle.raman_rates, bundle.raman_densities) - assert backend._raman_spectrum(bundle.raman_rates, bundle.raman_densities) is first + first = _owner(backend)._raman_spectrum(bundle.raman_rates, bundle.raman_densities) + assert ( + _owner(backend)._raman_spectrum(bundle.raman_rates, bundle.raman_densities) + is first + ) densities = list(bundle.raman_densities) for index in range(len(densities)): densities[index] *= 1.1 - fresh = backend._raman_spectrum(bundle.raman_rates, tuple(densities)) + fresh = _owner(backend)._raman_spectrum(bundle.raman_rates, tuple(densities)) assert fresh is not first first = fresh rates = list(bundle.raman_rates) for index in range(len(rates)): rates[index] += 1e12 - fresh = backend._raman_spectrum(tuple(rates), tuple(densities)) + fresh = _owner(backend)._raman_spectrum(tuple(rates), tuple(densities)) assert fresh is not first first = fresh - assert backend._raman_transforms == 5 + assert _owner(backend)._raman_transforms == 5 backend.close() - assert backend._raman_densities is None + assert _owner(backend)._raman_densities is None def test_raman_component_extents_are_checked(case): diff --git a/tests/backends/test_numpy_ref_backend.py b/tests/backends/test_numpy_ref_backend.py index 08b039942..2cd557d00 100644 --- a/tests/backends/test_numpy_ref_backend.py +++ b/tests/backends/test_numpy_ref_backend.py @@ -21,7 +21,7 @@ from solprop.backends import Backend from solprop.backends.events import ObservationReady from solprop.backends.numpy_ref import NumpyRefBackend -from solprop.backends.numpy_ref import backend as backend_module +from solprop.backends.numpy_ref import workspace as workspace_module from solprop.backends.protocol import BackendHistory, StepStats from solprop.backends.session import Start from solprop.backends.sessions import start_session @@ -706,7 +706,7 @@ def test_the_alarm_is_weighted_at_the_stage_it_was_scored_from( backend = NumpyRefBackend(problem, run_request, grid=field_grid) backend.set_initial(problem.initial.field0, None) backend.propagate_to(0.1) - bundle = backend._last_bundle + bundle = backend.workspace._last_bundle assert bundle is not None stage_z = bundle.z1 # The stage the alarm was scored from is the last one of the last accepted step, @@ -873,14 +873,14 @@ def test_a_harmonic_term_without_its_carrier_is_refused(thg_problem): stripped = dataclasses.replace(problem) object.__setattr__(stripped, "grids", grids) with pytest.raises(BackendError, match="carrier_2w0 is absent"): - backend_module._harmonic_carrier(stripped) + workspace_module._harmonic_carrier(stripped) def test_the_harmonic_carrier_comes_from_the_contract(thg_problem): problem, _ = thg_problem(thg=True) assert problem.grids.carrier_2w0 is not None - assert backend_module._harmonic_carrier(problem) is problem.grids.carrier_2w0 - assert backend_module._harmonic_carrier(thg_problem(thg=False).problem) is None + assert workspace_module._harmonic_carrier(problem) is problem.grids.carrier_2w0 + assert workspace_module._harmonic_carrier(thg_problem(thg=False).problem) is None def test_the_z_table_answers_the_noise_phase_too(tabulated_problem, field_grid): @@ -892,9 +892,9 @@ def test_the_z_table_answers_the_noise_phase_too(tabulated_problem, field_grid): """ backend = NumpyRefBackend(*tabulated_problem, grid=field_grid) try: - bundle = backend._stage_scalars(0.0, 0.05) + bundle = backend.workspace.stage_scalars(0.0, 0.05) assert bundle.phi_at is None - got = backend._unitary_phase(bundle) + got = backend.workspace.unitary_phase(bundle) want = unitary_phase(tabulated_problem.problem.linear, 0.05) finally: backend.close() diff --git a/tests/backends/test_numpy_ref_multimode.py b/tests/backends/test_numpy_ref_multimode.py index 893565534..8fbdfb298 100644 --- a/tests/backends/test_numpy_ref_multimode.py +++ b/tests/backends/test_numpy_ref_multimode.py @@ -132,7 +132,7 @@ def scored_alarm(backend): is what the warning of the retired step driver quoted. """ if backend.name == "numpy_ref": - return backend._alarm + return backend.workspace._alarm from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] _testing, ) @@ -470,7 +470,7 @@ def test_the_alarm_falls_with_the_radial_order_on_a_three_mode_set( rule = transverse_quadrature(modes, n_r=n_r, radial_rule="gauss_kronrod") problem, run_request = build(grid, modes, pulse(grid, 3), quadrature=rule) _, backend = propagate(DEFAULT_BACKEND, problem, run_request, grid) - alarms[n_r] = float(backend._alarm) + alarms[n_r] = float(backend.workspace._alarm) # The ladder is monotone and spans more than ten orders, and the threshold lands # where the two constants at the top of this file say it does. assert sorted(alarms, key=lambda order: alarms[order], reverse=True) == list(orders) @@ -509,11 +509,11 @@ def test_the_alarm_is_not_a_number_where_the_polarisation_vanishes(grid, capilla ) problem, run_request = build(grid, modes, pulse(grid, 2), quadrature=rule) _, backend = propagate(NumpyRefBackend, problem, run_request, grid) - assert backend._alarm > 0.0 - backend._last_projected = np.zeros_like(backend._last_projected) - backend._last_coarse = np.zeros_like(backend._last_coarse) - backend._update_alarm() - assert math.isnan(backend._alarm) + assert backend.workspace._alarm > 0.0 + backend.workspace._last_projected = np.zeros_like(backend.workspace._last_projected) + backend.workspace._last_coarse = np.zeros_like(backend.workspace._last_coarse) + backend.workspace.score_quadrature() + assert math.isnan(backend.workspace._alarm) # ------------------------------------------------------------- vector polarisation diff --git a/tests/backends/test_numpy_ref_plasma.py b/tests/backends/test_numpy_ref_plasma.py index 52830757f..1302ec754 100644 --- a/tests/backends/test_numpy_ref_plasma.py +++ b/tests/backends/test_numpy_ref_plasma.py @@ -372,7 +372,9 @@ def test_one_stage_matches_the_responses_composed_by_hand( backend.set_initial(problem.initial.field0, None) state = problem.initial.field0 ones = np.ones_like(state) - got = backend._nonlinear(state, backend._stage_scalars(0.0, 0.05), ones) + got = backend.workspace.nonlinear( + state, backend.workspace.stage_scalars(0.0, 0.05), ones + ) want = reference_nonlinear(problem, kerr, plasma, state, 0.05) # Identical formulas, held to the plasma chain's rounding and the transforms'. samples = problem.grids.n_to @@ -622,7 +624,7 @@ def test_the_plasma_statistics_are_the_same_between_planes_as_at_one( MODE_MATRIX_BUILDERS = ( - "solprop.backends.host.driver", + "solprop.backends.numpy_ref.workspace", "solprop_native._statistics", "solprop_native.backend", ) @@ -650,7 +652,7 @@ def test_the_on_axis_matrix_is_built_once_and_rescaled( ) builds = [] real = importlib.import_module("solprop.modes.quadrature").mode_matrix - # Every module that builds it: the reference's driver, native's statistics and, + # Every module that builds it: the reference's workspace, native's statistics and, # while it exists, the legacy step driver. for name in MODE_MATRIX_BUILDERS: try: @@ -716,7 +718,7 @@ def test_the_on_axis_matrix_follows_a_taper(field_grid, backend_class): try: observed = run(backend, problem, run_request).final if isinstance(backend, NumpyRefBackend): - rescaled = backend._on_axis_synthesis([mode]) + rescaled = backend.workspace._on_axis_synthesis([mode], backend._z) else: # Native keeps the entrance matrix (its statistics' own) and rescales it # by the transform's taper factor where it reads it. This is that law on diff --git a/tests/backends/test_numpy_ref_raman.py b/tests/backends/test_numpy_ref_raman.py index eee7f7ccd..490650cc6 100644 --- a/tests/backends/test_numpy_ref_raman.py +++ b/tests/backends/test_numpy_ref_raman.py @@ -61,6 +61,7 @@ kernel_taper, ) from solprop.translate.responses import ResponseStage, prefactor_at +from solprop.translate.stage import scalars # The pass is the oracle's own arithmetic -- the same padded real transform pair, the # same product, the same final multiplication -- but need not keep its order (SEP 25): @@ -68,6 +69,11 @@ # pointwise work, batched over a chunk of nodes as well as one column at a time. +def _owner(backend): + """Return what holds a backend's Raman kernel: the reference's workspace.""" + return getattr(backend, "workspace", backend) + + def convolution_bound(grid): """One padded transform round trip and its products, relative (SEP 25).""" return fft_bound(2 * grid.n_to) @@ -339,7 +345,9 @@ def test_one_stage_matches_the_responses_composed_by_hand( backend = NumpyRefBackend(problem, run_request) backend.set_initial(problem.initial.field0, None) state = problem.initial.field0 - got = backend._nonlinear(state, backend._stage_scalars(0.0, z), np.ones_like(state)) + got = backend.workspace.nonlinear( + state, backend.workspace.stage_scalars(0.0, z), np.ones_like(state) + ) want = reference_nonlinear(problem, raman_field_grid, kerr, raman, state, z) # The Raman half is one convolution's rounding -- its kernel spectrum and its # convolution each have their own test above -- and the Kerr coefficient's grouping: @@ -417,9 +425,9 @@ def test_the_kernel_is_transformed_once_per_change_of_the_decay_rates( problem, run_request, _, _ = raman_capillary(responses) backend = backend_class(problem, run_request) for z in (0.0, 0.05, 0.05, 0.15, 0.15): - rates = backend._stage_scalars(0.0, z).raman_rates - backend._raman_spectrum(rates) - transforms = backend._raman_transforms + rates = scalars(problem, 0.0, z, helpers=backend.helpers).raman_rates + _owner(backend)._raman_spectrum(rates) + transforms = _owner(backend)._raman_transforms backend.close() assert transforms == expected @@ -429,7 +437,12 @@ def test_a_problem_without_a_raman_kernel_has_no_spectrum( ): problem, run_request, _, _ = raman_capillary([KerrResponse(chi3=1.0e-51, thg=True)]) backend = backend_class(problem, run_request) - assert backend._raman_spectrum(backend._stage_scalars(0.0, 0.0).raman_rates) is None + assert ( + _owner(backend)._raman_spectrum( + scalars(problem, 0.0, 0.0, helpers=backend.helpers).raman_rates + ) + is None + ) backend.close() @@ -899,7 +912,7 @@ def test_a_raman_run_steps_and_shifts_a_capillary_pulse( backend = backend_class(problem, run_request, grid=raman_field_grid) try: plane = session_run(backend, problem, run_request, owns=False, until=0.1).final - transforms = backend._raman_transforms + transforms = _owner(backend)._raman_transforms finally: backend.close() assert plane.z == 0.1 diff --git a/tests/backends/test_on_axis_statistics.py b/tests/backends/test_on_axis_statistics.py index 68cb92091..ef6e5adbc 100644 --- a/tests/backends/test_on_axis_statistics.py +++ b/tests/backends/test_on_axis_statistics.py @@ -17,7 +17,7 @@ import math import warnings from contextlib import closing -from typing import cast +from typing import Any, cast import numpy as np import pytest @@ -27,7 +27,6 @@ from sessions.executors import IDENTITY from sessions.runs import launched, load_native, run from solprop.backends import select -from solprop.backends.host.driver import HostDriver from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.populations import axis_node from solprop.driver import Simulation @@ -115,7 +114,7 @@ def entrance_stats(grid, problem, run_request, modes, spec): backend.set_initial(problem.initial.field0, None) values = backend.stats(spec) # select() returns the seam's protocol; the counter is the shared driver's. - return values, cast("HostDriver", backend).axis_scans + return values, cast("Any", backend).workspace.axis_scans RULES: list[tuple[RadialRule, int]] = [ @@ -273,7 +272,7 @@ def test_consecutive_planes_scan_their_own_field(grid, table, name): landed = run(backend, problem, run_request) if name == "numpy_ref": # select() returns the seam's protocol; the counter is the driver's. - assert cast("HostDriver", backend).axis_scans == 2 + assert cast("Any", backend).workspace.axis_scans == 2 first, second = ( float(observation.stats["on_axis_electron_density"]) for observation in landed.observations @@ -398,7 +397,7 @@ def backend_stats(name, grid, problem, run_request, modes, spec): if name == "native": return _stats(observation), _native_axis_scans(session) # select() returns the seam's protocol; the counter is the driver's. - return _stats(observation), cast("HostDriver", backend).axis_scans + return _stats(observation), cast("Any", backend).workspace.axis_scans @pytest.mark.parametrize("name", BACKENDS) @@ -590,8 +589,8 @@ def test_a_host_backend_s_axis_scan_needs_the_field(grid, table): ) as backend: backend.set_initial(problem.initial.field0, None) with pytest.raises(BackendError, match="needs the field"): - backend._axis_row_populations( # pyright: ignore[reportPrivateUsage] - None, np.zeros((2, 1)) + backend.workspace._axis_row_populations( # pyright: ignore[reportPrivateUsage] + None, np.zeros((2, 1)), backend._z ) diff --git a/tests/backends/test_optmat_cases.py b/tests/backends/test_optmat_cases.py index 0b9fc7216..47400f8c8 100644 --- a/tests/backends/test_optmat_cases.py +++ b/tests/backends/test_optmat_cases.py @@ -62,8 +62,8 @@ def test_the_lab_frame_sample_is_the_hoisted_derivative_on_the_masked_launch(): launch = problem.initial.field0 masked = apply_hard_mask(launch, problem.grids.active_mask) assert np.any(masked != launch) - backend._hoist(1e-3) - sample = np.array(backend._adams_lab_source(masked, 0.0)) + backend.workspace.hoist(1e-3) + sample = np.array(backend.workspace.lab_source(masked, 0.0)) finally: backend.close() assert_within(sample, hoisted, 8 * EPS, what="lab-frame sample") diff --git a/tests/backends/test_polarised_runs.py b/tests/backends/test_polarised_runs.py index cbceee6a1..5985ea616 100644 --- a/tests/backends/test_polarised_runs.py +++ b/tests/backends/test_polarised_runs.py @@ -147,9 +147,9 @@ def problem_derivative(backend_class, problem, run_request, grid, modes): try: if isinstance(backend, NumpyRefBackend): backend.set_initial(problem.initial.field0, None) - backend._hoist(0.0) - bundle = backend._stage_scalars(0.0, 0.0) - derivative = backend._nonlinear( + backend.workspace.hoist(0.0) + bundle = backend.workspace.stage_scalars(0.0, 0.0) + derivative = backend.workspace.nonlinear( problem.initial.field0, bundle, np.ones(problem.shape, complex), diff --git a/tests/backends/test_radial_absorber.py b/tests/backends/test_radial_absorber.py index 40021b7f9..03deaf727 100644 --- a/tests/backends/test_radial_absorber.py +++ b/tests/backends/test_radial_absorber.py @@ -116,10 +116,10 @@ def test_spatial_absorber_derivative_matches_independent_bessel_operator( try: if isinstance(backend, NumpyRefBackend): backend.set_initial(problem.initial.field0, None) - backend._hoist(0.0) - measured = backend._nonlinear( + backend.workspace.hoist(0.0) + measured = backend.workspace.nonlinear( problem.initial.field0, - backend._stage_scalars(0.0, 0.0), + backend.workspace.stage_scalars(0.0, 0.0), np.ones(problem.shape, complex), ) else: diff --git a/tests/backends/test_records.py b/tests/backends/test_records.py index 0039ba3bf..5c4854765 100644 --- a/tests/backends/test_records.py +++ b/tests/backends/test_records.py @@ -248,7 +248,7 @@ def test_the_reference_s_runge_kutta_march_reads_the_shared_policy(): backend: Any = select("numpy_ref", problem, request) try: assert ( - backend._controller_policy() + backend._march._policy == run_records(problem, request, _entrance(problem)).policy ) assert backend._collar_can_rest() is collar_rests(problem, request.stepper) diff --git a/tests/backends/test_reference_independence.py b/tests/backends/test_reference_independence.py index ace200218..9a4aa4d4c 100644 --- a/tests/backends/test_reference_independence.py +++ b/tests/backends/test_reference_independence.py @@ -18,6 +18,7 @@ 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.records import adams_policy from solprop.backends.session import Start from solprop.backends.sessions import start_session from solprop.exceptions import BackendError @@ -66,10 +67,16 @@ def test_an_injected_adams_engine_is_gated_and_checked_as_the_bridge_s( ): # The reference's march takes an injected engine and names what it lacks. problem, run_request = soliton_problem(narrow_grid, 1, save_planes=[1e-3]) - with closing(NumpyRefBackend(problem, run_request, grid=narrow_grid)) as backend: - with pytest.raises(BackendError, match="exponential path lacks"): - HostAdamsMarch(backend, Multistep(), engine=object()) - with pytest.raises(BackendError, match="fused path lacks"): - HostAdamsMarch( - backend, Multistep(formulation="interaction"), engine=object() - ) + with ( + closing(NumpyRefBackend(problem, run_request, grid=narrow_grid)) as backend, + pytest.raises(BackendError, match="Adams engine lacks start, trial"), + ): + HostAdamsMarch( + object(), + Multistep(), + backend._hooks, + policy=adams_policy( + backend._problem, run_request.stepper, Multistep(), carrier=False + ), + field=backend.workspace.committed, + ) diff --git a/tests/backends/test_source_evaluations.py b/tests/backends/test_source_evaluations.py index 7a10459c2..4f9668cdd 100644 --- a/tests/backends/test_source_evaluations.py +++ b/tests/backends/test_source_evaluations.py @@ -61,23 +61,24 @@ def test_python_counter_tracks_dispatch_through_rejection( with closing(reference) as engine: engine.set_initial(problem.initial.field0, None) calls = [] - original_trial = engine._trial_step + stepper = engine._runge_kutta_engine + original_trial = stepper.trial def trial(z, dz): before = engine.metadata()["source_evaluations"] - _, advanced = original_trial(z, dz) + original_trial(z, dz) calls.append(engine.metadata()["source_evaluations"] - before) - return (4.0 if len(calls) == 1 else 0.01), advanced + return 4.0 if len(calls) == 1 else 0.01 - monkeypatch.setattr(engine, "_trial_step", trial) + monkeypatch.setattr(stepper, "trial", trial) dispatched = [] - original_source = engine._nonlinear + original_source = engine.workspace.nonlinear def source(*args, **kwargs): dispatched.append(None) return original_source(*args, **kwargs) - monkeypatch.setattr(engine, "_nonlinear", source) + monkeypatch.setattr(engine.workspace, "nonlinear", source) summary = engine.propagate_to(0.002) assert summary.n_rejected == 1 assert calls[0] == 7 diff --git a/tests/backends/test_tdse_native.py b/tests/backends/test_tdse_native.py index 0d978a4a3..5257ab96c 100644 --- a/tests/backends/test_tdse_native.py +++ b/tests/backends/test_tdse_native.py @@ -31,6 +31,7 @@ from solprop.backends import tdse_source from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.multistep import HostHistory +from solprop.backends.numpy_ref.workspace import NumpyWorkspace from solprop.backends.session import Start from solprop.backends.sessions import start_session from solprop.driver import Simulation @@ -305,7 +306,7 @@ def _reference_startup(case, monkeypatch): """The reference's startup: the field it evaluates, its ``F`` and row zero.""" problem, request, grid = case seen: dict[str, Any] = {} - nonlinear = NumpyRefBackend._nonlinear_tdse + nonlinear = NumpyWorkspace._nonlinear_tdse project = tdse_source.project_atomic_sources start = HostHistory.start @@ -320,13 +321,12 @@ def recording_project(*args, **kwargs): return result def recording_start(self, z): - row = start(self, z) - seen.setdefault("row", np.array(row).reshape(-1)) + start(self, z) + seen.setdefault("row", np.array(self.value(0)).reshape(-1)) seen.setdefault("history", self) - return row with monkeypatch.context() as patch: - patch.setattr(NumpyRefBackend, "_nonlinear_tdse", recording_nonlinear) + patch.setattr(NumpyWorkspace, "_nonlinear_tdse", recording_nonlinear) patch.setattr(tdse_source, "project_atomic_sources", recording_project) patch.setattr(HostHistory, "start", recording_start) binding = Unbudgeted(tdse_descriptor(problem.route), 10**6, _law) diff --git a/tests/backends/test_vector_raman.py b/tests/backends/test_vector_raman.py index b847478cb..6b971d6f5 100644 --- a/tests/backends/test_vector_raman.py +++ b/tests/backends/test_vector_raman.py @@ -31,6 +31,11 @@ from vector_raman_tensor_oracle import BUDGETS, cartesian_direct, convolution_bound +def _owner(backend): + """Return what holds a backend's Raman kernel: the reference's workspace.""" + return getattr(backend, "workspace", backend) + + def test_reference_pass_rejects_three_physical_components(): with pytest.raises(BackendError, match="one or two physical components"): passes.raman_polarisation( @@ -229,18 +234,18 @@ def test_vector_kernel_cache_refreshes_all_dynamic_inputs(backend_class): backend = backend_class(problem, run_request, grid=grid, modes=modes) bundle = scalars(problem, 0.0, 0.0) try: - backend._raman_spectrum(bundle.raman_rates, bundle.raman_densities) - backend._raman_spectrum(bundle.raman_rates, bundle.raman_densities) - assert backend._raman_transforms == 1 + _owner(backend)._raman_spectrum(bundle.raman_rates, bundle.raman_densities) + _owner(backend)._raman_spectrum(bundle.raman_rates, bundle.raman_densities) + assert _owner(backend)._raman_transforms == 1 rates = list(bundle.raman_rates) for index in range(len(rates)): rates[index] += 1e12 - backend._raman_spectrum(tuple(rates), bundle.raman_densities) - assert backend._raman_transforms == 2 + index + _owner(backend)._raman_spectrum(tuple(rates), bundle.raman_densities) + assert _owner(backend)._raman_transforms == 2 + index # Single-component amplitude is applied after convolution, so density # changes alone need no kernel rebuild (unlike mixtures). - backend._raman_spectrum(tuple(rates), (2 * bundle.raman_densities[0],)) - assert backend._raman_transforms == 1 + len(rates) + _owner(backend)._raman_spectrum(tuple(rates), (2 * bundle.raman_densities[0],)) + assert _owner(backend)._raman_transforms == 1 + len(rates) finally: backend.close() diff --git a/tests/builders.py b/tests/builders.py index 7fd9c6f05..4df278f67 100644 --- a/tests/builders.py +++ b/tests/builders.py @@ -33,6 +33,7 @@ "fixed_fibre_point", "launch_derivative", "numpy_ref_launch_derivative", + "reference_trial", "run_python", ] @@ -58,14 +59,25 @@ def launch_derivative(backend: NumpyRefBackend, problem: PropagationProblem) -> trial is. """ backend.set_initial(problem.initial.field0, None) - backend._hoist(0.0) - return backend._nonlinear( + backend.workspace.hoist(0.0) + return backend.workspace.nonlinear( backend._require_state(), - backend._stage_scalars(0.0, 0.0), + backend.workspace.stage_scalars(0.0, 0.0), np.ones(problem.shape, complex), ) +def reference_trial(backend: Any, z: float, dz: float) -> tuple[float, Any]: + """Return a ``numpy_ref`` trial's norm and raw end state, committing nothing. + + The backend's Runge-Kutta engine forms the trial from the committed state and + holds it; its end state is before the accepted step's finish. + """ + engine = backend._runge_kutta_engine + norm = engine.trial(z, dz) + return norm, engine.trial_state + + def numpy_ref_launch_derivative( problem: PropagationProblem, run_request: RunRequest, grid: TimeGrid ) -> Any: diff --git a/tests/driver/test_abandoned_step.py b/tests/driver/test_abandoned_step.py index 08aac6dad..6f73f61bc 100644 --- a/tests/driver/test_abandoned_step.py +++ b/tests/driver/test_abandoned_step.py @@ -17,7 +17,7 @@ import pytest from march_bounds import assert_matched, march_bound -from solprop.backends.numpy_ref import NumpyRefBackend +from solprop.backends.numpy_ref.workspace import NumpyWorkspace from solprop.backends.registry import available from solprop.backends.session import Start from solprop.driver import Simulation @@ -74,7 +74,7 @@ def built(backend: str = "numpy_ref", *, fields: str = "none") -> Simulation: def _abandon_a_step(monkeypatch, *, after: int) -> None: """Raise out of the reference's step `after` source evaluations from the start.""" - original = NumpyRefBackend._adams_lab_source + original = NumpyWorkspace.lab_source count = [0] def evaluate(self, lab, position, **keywords): @@ -83,7 +83,7 @@ def evaluate(self, lab, position, **keywords): raise AbandonedError return original(self, lab, position, **keywords) - monkeypatch.setattr(NumpyRefBackend, "_adams_lab_source", evaluate) + monkeypatch.setattr(NumpyWorkspace, "lab_source", evaluate) def test_a_step_abandoned_in_flight_leaves_no_checkpoint_and_says_why( diff --git a/tests/driver/test_coherent_capillary.py b/tests/driver/test_coherent_capillary.py index ca4272d8f..1e33c7d35 100644 --- a/tests/driver/test_coherent_capillary.py +++ b/tests/driver/test_coherent_capillary.py @@ -55,7 +55,7 @@ from modal_provider_cases import GENERAL_Z_END, general_grid, general_guide from solprop.backends import available from solprop.backends.numpy_ref import NumpyRefBackend -from solprop.backends.numpy_ref.backend import ( +from solprop.backends.numpy_ref.workspace import ( _MAX_FLOW_SQUARINGS, _triangular_exponential, ) diff --git a/tests/driver/test_estimate.py b/tests/driver/test_estimate.py index 2b689366e..0f612f855 100644 --- a/tests/driver/test_estimate.py +++ b/tests/driver/test_estimate.py @@ -12,6 +12,7 @@ import numpy as np import pytest +from builders import reference_trial from capability_routes import ROUTES from sessions.runs import load_native, native_trial from solprop.backends.protocol import stepping as host_stepping @@ -140,9 +141,10 @@ def test_a_low_storage_estimate_times_the_march_s_own_step(backend, monkeypatch) def spy(constructed, problem, run_request): step, evaluations = build(constructed, problem, run_request) + engine = getattr(constructed, "_runge_kutta_engine", None) monkeypatch.setattr( - constructed, - "_trial_step", + constructed if engine is None else engine, + "_trial_step" if engine is None else "trial", lambda *_: pytest.fail("a low-storage estimate took a trial step"), ) @@ -275,8 +277,8 @@ def test_a_timing_probe_commits_nothing_and_reads_back_its_trial(backend): # same arithmetic again, on one thread layout in one process, so agreement # to a few roundings of the field's largest magnitude bounds it (SEP 25). stepping = cast("Any", fresh) # the driver's own trial, as a kernel test - _, state = stepping._trial_step(float(problem.initial.z), dz) - trial = np.asarray(stepping._observed_field(stepping._finish(state, dz))) + _, state = reference_trial(stepping, float(problem.initial.z), dz) + trial = np.asarray(stepping.workspace.finish(state, dz)[0]) scale = float(np.max(np.abs(trial))) np.testing.assert_allclose(whole, trial, rtol=0.0, atol=64e-16 * scale) # A copy the probe owns: a later trial does not write to it. diff --git a/tests/driver/test_field_free_planes.py b/tests/driver/test_field_free_planes.py index e4da92f0d..0ce349e79 100644 --- a/tests/driver/test_field_free_planes.py +++ b/tests/driver/test_field_free_planes.py @@ -22,8 +22,8 @@ from bounds import AccuracyEnvelope, assert_within, fft_bound, gamma from legacy_geometry import LEGACY_GRID, bare_absorber -from solprop.backends.host.driver import HostDriver from solprop.backends.numpy_ref import NumpyRefBackend +from solprop.backends.numpy_ref.workspace import NumpyWorkspace from solprop.backends.protocol import BackendHistory, Observation, stepping from solprop.backends.registry import available, select from solprop.backends.session import Start @@ -449,13 +449,14 @@ def test_a_field_free_observation_crosses_no_field(monkeypatch): for field in (True, False): owner = select(backend, problem, run_request, grid=simulation.grid) copies = [] - original = cast("type[HostDriver]", type(owner))._observed_field + original = NumpyWorkspace.noise_phase - def counted(self, state, copies=copies, original=original): + def counted(self, z, copies=copies, original=original): copies.append(1) - return original(self, state) + return original(self, z) - monkeypatch.setattr(type(owner), "_observed_field", counted) + # The observation reads the noise phase beside the field and neither without. + monkeypatch.setattr(NumpyWorkspace, "noise_phase", counted) try: stepping(owner).set_initial(problem.initial.field0, None) stepping(owner).propagate_to(float(PLANES[0])) diff --git a/tests/driver/test_grin_system.py b/tests/driver/test_grin_system.py index 8e49a3518..fb003b997 100644 --- a/tests/driver/test_grin_system.py +++ b/tests/driver/test_grin_system.py @@ -29,8 +29,8 @@ parabolic_beta, ) from solprop import fourier -from solprop.backends.numpy_ref.backend import _general_maps from solprop.backends.numpy_ref.general_modal import general_source +from solprop.backends.numpy_ref.workspace import _general_maps from solprop.constants import EPS0 from solprop.driver import Simulation from solprop.exceptions import GeneralModalBasisWarning, TranslationError diff --git a/tests/driver/test_native_coupled_flow.py b/tests/driver/test_native_coupled_flow.py index 8069bfb93..1a6ca9841 100644 --- a/tests/driver/test_native_coupled_flow.py +++ b/tests/driver/test_native_coupled_flow.py @@ -130,7 +130,7 @@ def test_the_flow_s_native_actions_are_the_reference_s_within_the_formation_boun _host_flow, ) - from solprop.backends.numpy_ref.backend import ( # noqa: PLC0415 - private oracle + from solprop.backends.numpy_ref.workspace import ( # noqa: PLC0415 - private oracle _coupled_flow_maps, _flow_action, ) diff --git a/tests/driver/test_native_flow_marches.py b/tests/driver/test_native_flow_marches.py index 7b58a9165..4a7d4046d 100644 --- a/tests/driver/test_native_flow_marches.py +++ b/tests/driver/test_native_flow_marches.py @@ -27,7 +27,7 @@ formation_bound, section_formation_bounds, ) -from solprop.backends.numpy_ref.backend import ( +from solprop.backends.numpy_ref.workspace import ( _coupled_flow_maps, _flow_action, _triangular_exponential, diff --git a/tests/driver/test_native_flow_pathological.py b/tests/driver/test_native_flow_pathological.py index 691cf209f..dbb390cc5 100644 --- a/tests/driver/test_native_flow_pathological.py +++ b/tests/driver/test_native_flow_pathological.py @@ -30,12 +30,13 @@ import pytest import flow_parity +from builders import reference_trial from flow_parity import QUIET, STEPS, UNIT, build, reference_formation_bound from native_flow_guards import check_flow_conditioning as check_native from sessions.runs import load_native, native_trial from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref import passes as reference_passes -from solprop.backends.numpy_ref.backend import ( +from solprop.backends.numpy_ref.workspace import ( _check_flow_conditioning, _coupled_flow_maps, _flow_action, @@ -255,7 +256,7 @@ def capture(error, state, advanced, reference_mask, controller): reference = NumpyRefBackend(problem, run_request, grid=grid) try: reference.set_initial(field, None) - reference._trial_step(0.0, dz) + reference_trial(reference, 0.0, dz) expected_state = reference._require_state().copy() finally: reference.close() diff --git a/tests/driver/test_native_flow_refusals.py b/tests/driver/test_native_flow_refusals.py index 19fb85e9c..59d72ef0a 100644 --- a/tests/driver/test_native_flow_refusals.py +++ b/tests/driver/test_native_flow_refusals.py @@ -25,7 +25,7 @@ ten_step_bound, ) from solprop.backends.numpy_ref import NumpyRefBackend -from solprop.backends.numpy_ref.backend import _coupled_flow_maps +from solprop.backends.numpy_ref.workspace import _coupled_flow_maps from solprop.exceptions import BackendError, TranslationError from solprop.translate.coupled import constant_schur_flow, orthonormal_metric diff --git a/tests/driver/test_native_moving_guide.py b/tests/driver/test_native_moving_guide.py index bc16db2f0..6764221ca 100644 --- a/tests/driver/test_native_moving_guide.py +++ b/tests/driver/test_native_moving_guide.py @@ -77,14 +77,14 @@ def test_the_moving_maps_are_combined_per_stage_not_frozen(): linear = 1e3 * propagate(case, NumpyRefBackend, case.problem.initial.field0 * 1e-3) bound = moving_parity_bound(case, expected, linear) backend = NumpyRefBackend(case.problem, case.run_request, grid=case.grid) - single = backend._stage_scalars + single = backend.workspace.stage_scalars def frozen(z0, z1): first = single(z0, z0).transform_weights return dataclasses.replace(single(z0, z1), transform_weights=first) - # The reference's trial reads each stage's bundle through `_stage_scalars`. - backend._stage_scalars = frozen + # The reference's trial reads each stage's bundle through `stage_scalars`. + backend.workspace.stage_scalars = frozen try: backend.set_initial(case.problem.initial.field0, None) backend.propagate_to(case.length) diff --git a/tests/driver/test_native_moving_guide_bound.py b/tests/driver/test_native_moving_guide_bound.py index c910fa89c..eb9fd65f5 100644 --- a/tests/driver/test_native_moving_guide_bound.py +++ b/tests/driver/test_native_moving_guide_bound.py @@ -34,7 +34,7 @@ ) 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.backends.numpy_ref.workspace import _general_maps from solprop.stepper import Multistep from solprop.translate.stage import scalars @@ -69,7 +69,7 @@ def source_at(implementation, problem, run_request, grid, positions): backend = implementation(problem, run_request, grid=grid) try: backend.set_initial(state, None) - return [np.array(backend._adams_lab_source(state, z)) for z in positions] + return [np.array(backend.workspace.lab_source(state, z)) for z in positions] finally: backend.close() # Native's resident Adams engine, on the same problem under the Adams march: its diff --git a/tests/driver/test_plane_adoption.py b/tests/driver/test_plane_adoption.py index cac6d15ff..3d798d1a1 100644 --- a/tests/driver/test_plane_adoption.py +++ b/tests/driver/test_plane_adoption.py @@ -15,7 +15,7 @@ import importlib import importlib.util from collections.abc import Callable -from typing import cast +from typing import Any, cast import numpy as np import pytest @@ -336,7 +336,7 @@ def recorded(*, field: bool = True) -> Observation: # The observation's own array stays frozen; a fresh export is the caller's. assert held.flags.writeable assert not np.shares_memory(held, seen[-1].field) - state = cast("HostDriver[np.ndarray]", stepping)._state + state = cast("Any", stepping).workspace.state assert not np.shares_memory(held, state) finally: session.close() diff --git a/tests/driver/test_plasma_band_propagation.py b/tests/driver/test_plasma_band_propagation.py index 46dbe9fb1..bc26f400e 100644 --- a/tests/driver/test_plasma_band_propagation.py +++ b/tests/driver/test_plasma_band_propagation.py @@ -302,6 +302,8 @@ def test_the_reference_s_plasma_statistics_refuse_a_problem_with_no_plasma( try: state = simulation._field0 with pytest.raises(BackendError, match=message): - cast("NumpyRefBackend", backend)._backend_statistics((name,), state) + cast("NumpyRefBackend", backend).workspace._backend_statistics( + (name,), state, cast("NumpyRefBackend", backend)._z + ) finally: backend.close() diff --git a/tests/driver/test_resume.py b/tests/driver/test_resume.py index e9ece8a77..c2e640623 100644 --- a/tests/driver/test_resume.py +++ b/tests/driver/test_resume.py @@ -366,10 +366,10 @@ def test_the_input_draw_is_added_at_a_launch_and_not_to_a_resumed_state( atol=1e-12 * np.linalg.norm(draw), ) # The floor is the draw itself. - assert engine._input_floor is draw + assert engine.workspace.input_floor is draw engine.set_initial(launched, None, z=0.0, resume=True) np.testing.assert_array_equal(engine.observe().require_field(), launched) - assert engine._input_floor is draw + assert engine.workspace.input_floor is draw finally: engine.close() diff --git a/tests/driver/test_resume_history.py b/tests/driver/test_resume_history.py index 2bd71557e..84af6e7a4 100644 --- a/tests/driver/test_resume_history.py +++ b/tests/driver/test_resume_history.py @@ -35,6 +35,7 @@ from solprop.backends import available from solprop.backends.host.driver import HostDriver from solprop.backends.numpy_ref import NumpyRefBackend +from solprop.backends.numpy_ref.workspace import NumpyWorkspace from solprop.backends.registry import select from solprop.exceptions import OutputError, SolpropWarning from solprop.log import NullReporter @@ -193,7 +194,7 @@ def test_a_run_stopped_between_planes_continues_from_its_checkpoint( soliton(build_simulation, "numpy_ref", rtol=RTOL / TIGHTER), tmp_path / "tight.h5", ) - original = NumpyRefBackend._adams_lab_source + original = NumpyWorkspace.lab_source planes = [0.0, *build().settings.save_planes.tolist()] positions = [] @@ -207,7 +208,7 @@ def failing(self, field, position, *args, **keywords): return original(self, field, position, *args, **keywords) with monkeypatch.context() as patch: - patch.setattr(NumpyRefBackend, "_adams_lab_source", failing) + patch.setattr(NumpyWorkspace, "lab_source", failing) with pytest.raises(CrashError): build().run(part, progress="none") state = resume(part) diff --git a/tests/driver/test_runner.py b/tests/driver/test_runner.py index 6148abb0d..1129f91c8 100644 --- a/tests/driver/test_runner.py +++ b/tests/driver/test_runner.py @@ -153,7 +153,7 @@ def restored(backend, problem, run_request) -> tuple: ) entrance = float(backend.stats(spec)["quadrature_error"]) return ( - backend._dense_ahead is None, + backend._march._ahead is None, "nan" if np.isnan(entrance) else entrance, None if march is None else dataclasses.asdict(march.ledger), None if march is None else march._last_rejected, @@ -247,7 +247,7 @@ def test_a_load_restores_what_a_failed_run_left_as_a_fresh_backend_holds(dense): left = cast("HostDriver", runner.backend) if dense: # The failed run held the march ahead of its interpolated plane. - assert left._dense_ahead is not None + assert left._march.holding else: assert left._adams is not None assert left._adams.ledger.total > 0 diff --git a/tests/driver/test_snapshots.py b/tests/driver/test_snapshots.py index 99b7d511c..6875ac72a 100644 --- a/tests/driver/test_snapshots.py +++ b/tests/driver/test_snapshots.py @@ -123,7 +123,7 @@ def watched(*args): ( id(backend), id(backend._adams), - id(backend._tdse_binding), + id(getattr(backend, "workspace", backend)._tdse_binding), # The model and its plans live behind the provider's worker (SEP 49): # the same worker, the same view of the model and the same plans. id(binding._worker), diff --git a/tests/flow_parity.py b/tests/flow_parity.py index 0cb2663d8..e7a2750bc 100644 --- a/tests/flow_parity.py +++ b/tests/flow_parity.py @@ -109,7 +109,7 @@ ) from sessions.runs import bare, final_field from solprop.backends.numpy_ref import NumpyRefBackend -from solprop.backends.numpy_ref.backend import ( +from solprop.backends.numpy_ref.workspace import ( _TAYLOR_ORDER, _TAYLOR_SCALE, _coupled_flow_maps, @@ -579,7 +579,9 @@ def adams_formation_bound( try: anchors = np.concatenate(([0.0], np.cumsum(schedule.steps)[:-1])) exponents = [ - backend._delta_phi(backend._stage_scalars(float(z), float(z + step))) + backend.workspace.delta_phi( + backend.workspace.stage_scalars(float(z), float(z + step)) + ) for z, step in zip(anchors, schedule.steps, strict=True) ] finally: @@ -671,8 +673,8 @@ def flow_scales( backend = NumpyRefBackend(problem, run_request, grid=grid) try: state = problem.initial.field0 - bundle = backend._stage_scalars(0.0, 0.0) - source = backend._nonlinear(state, bundle, np.ones_like(state)) + bundle = backend.workspace.stage_scalars(0.0, 0.0) + source = backend.workspace.nonlinear(state, bundle, np.ones_like(state)) finally: backend.close() schedule = run_request.stepper.schedule diff --git a/tests/general_parity.py b/tests/general_parity.py index 7b08649cf..0674d9db8 100644 --- a/tests/general_parity.py +++ b/tests/general_parity.py @@ -62,7 +62,6 @@ make_provider, ) from solprop import fourier -from solprop.backends.numpy_ref.backend import _general_maps from solprop.backends.numpy_ref.general_modal import ( GeneralMaps, delayed_polarisation, @@ -70,6 +69,7 @@ symmetric_cubic, symmetric_kerr_coefficients, ) +from solprop.backends.numpy_ref.workspace import _general_maps from solprop.constants import EPS0 from solprop.grid import FieldGrid from solprop.modes.guide import ModalGuide diff --git a/tests/march_bounds.py b/tests/march_bounds.py index 017e30d07..669724df4 100644 --- a/tests/march_bounds.py +++ b/tests/march_bounds.py @@ -174,15 +174,15 @@ def measured_scales(simulation) -> tuple[float, float]: """ from general_parity import conditioning # noqa: PLC0415 from solprop.backends.numpy_ref import NumpyRefBackend # noqa: PLC0415 - from solprop.backends.numpy_ref.backend import _general_maps # noqa: PLC0415 + from solprop.backends.numpy_ref.workspace import _general_maps # noqa: PLC0415 problem = simulation.translate() run_request = simulation._run_request() backend = NumpyRefBackend(problem, run_request, grid=simulation.grid) try: state = problem.initial.field0 - bundle = backend._stage_scalars(0.0, 0.0) - source = backend._nonlinear(state, bundle, np.ones_like(state)) + bundle = backend.workspace.stage_scalars(0.0, 0.0) + source = backend.workspace.nonlinear(state, bundle, np.ones_like(state)) finally: backend.close() length = float(run_request.stepper.save_planes[-1]) diff --git a/tests/monitor_cases.py b/tests/monitor_cases.py index 79b58d80c..4ed6c160c 100644 --- a/tests/monitor_cases.py +++ b/tests/monitor_cases.py @@ -222,7 +222,8 @@ def reading(backend: Backend) -> BoundaryEnergies: For a backend other than the reference (:func:`as_driver`). """ driver = as_driver(backend) - return driver._boundary_energies(driver._require_state()) + driver._require_state() + return driver._boundary_energies() def record_after_march( diff --git a/tests/nonlinear/test_kerr_coefficient_per_true_watt.py b/tests/nonlinear/test_kerr_coefficient_per_true_watt.py index df3a71496..8373c7448 100644 --- a/tests/nonlinear/test_kerr_coefficient_per_true_watt.py +++ b/tests/nonlinear/test_kerr_coefficient_per_true_watt.py @@ -34,7 +34,7 @@ def true_watt_slope(problem, run_request, grid): carrier = int(np.argmin(abs(grid.omega - grid.omega0))) state[..., carrier] = grid.n_t / (2 if grid.kind == "field" else 1) state /= np.sqrt(power_weight_at(problem, 0.0)) - derivative = backend._nonlinear( + derivative = backend.workspace.nonlinear( state, stage.scalars(problem, 0.0, 0.0), np.ones(problem.shape, complex), diff --git a/tests/parity_ladder.py b/tests/parity_ladder.py index 450d10fa3..c38bceffb 100644 --- a/tests/parity_ladder.py +++ b/tests/parity_ladder.py @@ -279,7 +279,7 @@ def source(backend_class: type, built: Built, *, z: float = 0.0) -> np.ndarray: if backend.name == "native": return native_source(backend, launch, z) backend.set_initial(launch, None) - return np.array(backend._adams_lab_source(launch, z)) + return np.array(backend.workspace.lab_source(launch, z)) finally: backend.close() @@ -345,10 +345,10 @@ def projected(backend_class: type, built: Built) -> list[np.ndarray | None]: # The launch native loads (:func:`masked_launch`). launch = masked_launch(problem) backend.set_initial(launch, None) - backend._adams_lab_source(launch, 0.0) - coarse = backend._last_coarse + backend.workspace.lab_source(launch, 0.0) + coarse = backend.workspace._last_coarse return [ - forward(np.asarray(backend._last_projected), axis=-1), + forward(np.asarray(backend.workspace._last_projected), axis=-1), None if coarse is None else forward(np.asarray(coarse), axis=-1), ] finally: diff --git a/tests/scripted_driver.py b/tests/scripted_driver.py index 9da91378b..f434f7ac6 100644 --- a/tests/scripted_driver.py +++ b/tests/scripted_driver.py @@ -4,21 +4,21 @@ """A step driver whose numerical outcomes are scripted rather than computed. -:class:`solprop.backends.host.driver.HostDriver` is the reference's marching half, with -the kernels left abstract. :class:`HostScriptedDriver` fills them with a stage -evaluation that multiplies by a constant and an error norm taken from a list, so step -control, the -session lifecycle and the service loop can be tested without any physics being -evaluated correctly. ``tests/sessions`` tests the execution-session lifecycle with it -(SEP 47 section 7.1: "Script the same numerical outcomes to test this exact lifecycle -property on every executor"). +:class:`HostScriptedDriver` is the reference backend with its Runge-Kutta engine +replaced by a script: a trial multiplies the state by a constant and scores an error +norm taken from a list, so step control, the session lifecycle and the service loop +can be tested without any physics being evaluated correctly. ``tests/sessions`` tests +the execution-session lifecycle with it (SEP 47 section 7.1: "Script the same +numerical outcomes to test this exact lifecycle property on every executor"). """ from typing import TYPE_CHECKING, Any import numpy as np -from solprop.backends.host.driver import HostDriver +from solprop.backends.numpy_ref import NumpyRefBackend +from solprop.backends.numpy_ref.engines import NumpyRungeKutta +from solprop.backends.numpy_ref.workspace import NumpyWorkspace SCALE = 0.02 / 8 """The step length, m, whose default scripted norm is one: an eighth of a 2 cm run.""" @@ -56,8 +56,8 @@ class _Scripted: _proposal: float _problem: Any _z: float - _state: Any _closed: bool + _workspace: Any def _require_state(self) -> Any: ... @@ -98,11 +98,28 @@ def stats(self, spec) -> dict[str, np.ndarray]: def _begin_plane(self): self.planes_begun += 1 + def _runge_kutta(self, workspace: NumpyWorkspace) -> NumpyRungeKutta: + """Return the scripted engine in place of the reference's.""" + return _ScriptedEngine(workspace, self) + def close(self): """Release the state, as the seam requires.""" - self._state = None + self._workspace.close() self._closed = True -class HostScriptedDriver(_Scripted, HostDriver): - """The script on the reference's step driver.""" +class _ScriptedEngine(NumpyRungeKutta): + """A Runge-Kutta engine whose trial is the driver's script (``_trial_step``).""" + + def __init__(self, workspace: NumpyWorkspace, driver: Any) -> None: + super().__init__(workspace, workspace.stepper.tableau) + self._driver = driver + + def trial(self, z: float, dz: float) -> float: + norm, state = self._driver._trial_step(z, dz) + self._trial = (state, []) + return norm + + +class HostScriptedDriver(_Scripted, NumpyRefBackend): + """The script on the reference backend's engine.""" diff --git a/tests/sessions/executors.py b/tests/sessions/executors.py index 4a117e595..1c15659b0 100644 --- a/tests/sessions/executors.py +++ b/tests/sessions/executors.py @@ -272,12 +272,21 @@ def __init__( self._warn_at = warn_at self.trials = 0 self.accepted = 0 + self._left: tuple[float, float] | None = None + + def set_initial(self, *args: Any, **kwargs: Any) -> None: + # A load clears a step left in flight, as it does the low-storage march's. + self._left = None + super().set_initial(*args, **kwargs) # pyright: ignore[reportAttributeAccessIssue] + + def _abandoned(self) -> tuple[float, float] | None: + return self._left def _trial_step(self, z, dz): self.trials += 1 if self.trials == self._fail_at: if self._leave_in_flight: - self._in_flight = (z, dz) + self._left = (z, dz) if self._signal: raise KeyboardInterrupt msg = f"scripted failure at trial {self.trials}" @@ -376,7 +385,7 @@ def counted(*, field: bool = True): return Started( started, field_reads=lambda: reads[0], - live_state=(lambda: driver._state) if host_state else None, + live_state=(lambda: driver.workspace.state) if host_state else None, ) return start_session diff --git a/tests/sessions/test_native_load.py b/tests/sessions/test_native_load.py index 8857fcf5d..ac54df1ff 100644 --- a/tests/sessions/test_native_load.py +++ b/tests/sessions/test_native_load.py @@ -58,11 +58,11 @@ def test_an_input_draw_is_added_at_the_launch_alone(): reference.set_initial(field, None, z=float(problem.initial.z)) host = cast("Any", reference) assert loaded.floor is not None and loaded.noise is None - assert np.array_equal(loaded.floor, host._input_floor) + assert np.array_equal(loaded.floor, host.workspace.input_floor) expected = np.asarray(field) + loaded.floor assert np.array_equal(loaded.field, expected.reshape(-1)) assert loaded.clean_columns is not None - assert np.array_equal(loaded.clean_columns, host._clean_columns) + assert np.array_equal(loaded.clean_columns, host.workspace._clean_columns) resumed = native_load.load( problem, request.stepper, field, None, z=z, resume=True ) diff --git a/tests/test_transverse_reads.py b/tests/test_transverse_reads.py index 9e496a531..762627b8b 100644 --- a/tests/test_transverse_reads.py +++ b/tests/test_transverse_reads.py @@ -398,16 +398,16 @@ def test_the_scaled_miss_is_read_far_above_the_stop() -> None: def _driver_class(backend: str) -> type: - """Return the class of `backend`'s step driver, which holds its edge reading.""" + """Return the class holding `backend`'s edge reading, the reference's workspace.""" if backend == "native": from solprop_native.backend import ( # pyright: ignore[reportMissingImports] # noqa: PLC0415 NativeBackend, ) return NativeBackend - from solprop.backends.host.driver import HostDriver # noqa: PLC0415 + from solprop.backends.numpy_ref.workspace import NumpyWorkspace # noqa: PLC0415 - return HostDriver + return NumpyWorkspace @pytest.mark.parametrize( @@ -421,7 +421,7 @@ def test_a_plane_the_step_already_read_reduces_nothing_more( # Every step of this schedule is longer than the spacing, so each reads the edge, # and a plane landing on one has nothing to add. Its read used to cross the state, # synthesise it and only then find the gap zero: on a device, a whole state's copy - # for nothing. The reference reads through its driver's `_edge_reading`; the + # for nothing. The reference reads through its workspace's `edge_reading`; the # native session reads its edge resident (`Session::edge_plane` skips the plane), # with no reading through Python. _require(backend) @@ -430,13 +430,14 @@ def test_a_plane_the_step_already_read_reduces_nothing_more( planes = [length / 4, length / 2, length] calls = {"readings": 0} driver = cast("type[Any]", _driver_class(backend)) - edge_reading = driver._edge_reading + name = "_edge_reading" if backend == "native" else "edge_reading" + edge_reading = getattr(driver, name) def counting(self: Any, *args: Any, **keywords: Any) -> _EdgeReading: calls["readings"] += 1 return edge_reading(self, *args, **keywords) - monkeypatch.setattr(driver, "_edge_reading", counting) + monkeypatch.setattr(driver, name, counting) schedule = FixedSchedule.uniform(0.0, length, length / 8, save_planes=planes) with warnings.catch_warnings(): warnings.simplefilter("ignore", BoundaryWarning) diff --git a/tests/translate/test_operator_settings.py b/tests/translate/test_operator_settings.py index 335dc243e..493ffb5e6 100644 --- a/tests/translate/test_operator_settings.py +++ b/tests/translate/test_operator_settings.py @@ -16,6 +16,7 @@ import numpy as np import pytest +from builders import reference_trial from legacy_geometry import bare_absorber from solprop.backends.numpy_ref import NumpyRefBackend from solprop.boundaries import SpatialAbsorber, absorber @@ -335,11 +336,11 @@ def test_a_backend_handed_the_refused_step_forms_a_non_finite_stage(): backend.set_initial(problem.initial.field0, None) # A trial of the refused length, as only a direct caller can take one: the # inverse factor exp(lambda h) is infinite and so is the stage it scales. - backend._hoist(0.0) + backend.workspace.hoist(0.0) with np.errstate(over="ignore", invalid="ignore"): - norm, state = backend._trial_step(0.0, past) + norm, state = reference_trial(backend, 0.0, past) assert not (np.isfinite(norm) and np.all(np.isfinite(state))) - norm, state = backend._trial_step(0.0, allowed) + norm, state = reference_trial(backend, 0.0, allowed) assert np.isfinite(norm) and np.all(np.isfinite(state)) finally: backend.close() @@ -460,10 +461,10 @@ def test_a_radial_backend_handed_the_refused_step_forms_a_non_finite_stage(): backend = NumpyRefBackend(problem, run_request, grid=simulation.grid) try: backend.set_initial(problem.initial.field0, None) - backend._hoist(0.0) + backend.workspace.hoist(0.0) # The radial inverse factor exp(-dPhi) overflows as the separable one does. with np.errstate(over="ignore", invalid="ignore"): - norm, state = backend._trial_step(0.0, 1.1 * LOG_DBL_MAX / RATE) + norm, state = reference_trial(backend, 0.0, 1.1 * LOG_DBL_MAX / RATE) assert not (np.isfinite(norm) and np.all(np.isfinite(state))) finally: backend.close() diff --git a/tests/vector_raman_cases.py b/tests/vector_raman_cases.py index 5d0453b60..ad19573e8 100644 --- a/tests/vector_raman_cases.py +++ b/tests/vector_raman_cases.py @@ -136,9 +136,9 @@ def result(backend_class, problem, run_request, grid, modes, options=CHUNK): try: if backend.name == "numpy_ref": backend.set_initial(problem.initial.field0, None) - backend._hoist(0.0) - bundle = backend._stage_scalars(0.0, 0.0) - rhs = backend._nonlinear( + backend.workspace.hoist(0.0) + bundle = backend.workspace.stage_scalars(0.0, 0.0) + rhs = backend.workspace.nonlinear( problem.initial.field0, bundle, np.ones(problem.shape, complex), diff --git a/tests/wall_gas_cases.py b/tests/wall_gas_cases.py index 5d963b63e..95350184e 100644 --- a/tests/wall_gas_cases.py +++ b/tests/wall_gas_cases.py @@ -103,8 +103,8 @@ def launch_source(problem, run_request, grid) -> tuple[np.ndarray, float]: backend = NumpyRefBackend(problem, run_request, grid=grid) try: state = problem.initial.field0 - bundle = backend._stage_scalars(0.0, 0.0) - source = backend._nonlinear(state, bundle, np.ones_like(state)) + bundle = backend.workspace.stage_scalars(0.0, 0.0) + source = backend.workspace.nonlinear(state, bundle, np.ones_like(state)) return np.array(source), float(np.linalg.norm(state)) finally: backend.close() From 48436c62cebbcdabe6c380e63a0e631c1ca8838e Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 03:17:07 +0000 Subject: [PATCH 02/14] test(numpy_ref): the engines' commit contract and the marches' narrow calls Engine-contract cases of SEP 52 section 7: a Runge-Kutta trial commits nothing until accept; the low-storage trial is in flight until its accept returns, and a failure in the finish leaves no committed state; an Adams attempt reserves, then records its decision and releases, an abandoned one only releases; the accept takes the retained entries oldest first; the finish takes the split collar's sums on the masked field before the split, and the driver adds the removal and keeps the latest occupancies. The marches' tests drive them over recording engines and sessions. The design pages name the workspace, engines and marches. Co-Authored-By: Claude Opus 5.5 --- docs/dev/backends.md | 76 ++++---- docs/dev/kernel-contract.md | 94 +++++----- docs/dev/stepper.md | 30 ++- tests/backends/test_host_marches.py | 225 ++++++++++++++++++++++ tests/backends/test_numpy_engines.py | 266 +++++++++++++++++++++++++++ 5 files changed, 592 insertions(+), 99 deletions(-) create mode 100644 tests/backends/test_host_marches.py create mode 100644 tests/backends/test_numpy_engines.py diff --git a/docs/dev/backends.md b/docs/dev/backends.md index ac6ecc0ce..d4c8d086e 100644 --- a/docs/dev/backends.md +++ b/docs/dev/backends.md @@ -202,17 +202,22 @@ translation, and a native z-table run of each march with the plain forms forbidden. **3. Two owners, eight marches.** The reference steps through its own driver, -`HostDriver.propagate_to`, which hands the steps to one of its loops; every native run is +`HostDriver.propagate_to`, which hands the steps to its run's march; every native run is its native session's (`solprop_native.session`), whose compiled marches advance to an -event from one policy record and hand back the events (SEP 47): +event from one policy record and hand back the events (SEP 47). Each reference march +keeps its position, proposal, replay cursor and accepted norms in its own `MarchState` +(`backends/host/marches.py`), asks the driver only through the narrow `MarchHost`, and +hands every state-sized operation to an engine of `solprop.backends.engines` over the +reference's workspace, `NumpyWorkspace` (`backends/numpy_ref/workspace.py`), which holds +the state and does every state-sized operation (SEP 52 §5.1): | Loop | Steps | Where its state-sized work runs | |---|---|---| -| `HostDriver._march_to`, in `backends/host/driver.py` | adaptive Runge-Kutta | the backend's `_trial_step` | -| `HostDriver._replay_to` | Runge-Kutta on a fixed schedule | the backend's `_trial_step` | +| `RungeKuttaMarch.march_to`, in `backends/host/runge_kutta.py` | adaptive Runge-Kutta | a `RungeKuttaEngine`: `NumpyRungeKutta` (`backends/numpy_ref/engines.py`) | +| `RungeKuttaMarch.replay_to` | Runge-Kutta on a fixed schedule | the same engine | | `HostAdamsMarch.march_to`, in `backends/host/adams.py` | adaptive Adams | an `AdamsEngine`: `HostHistory` | | `HostAdamsMarch._replay_to` | Adams on a fixed schedule | the same engine | -| `HostLowStorageMarch.replay_to`, in `backends/host/low_storage.py` | low-storage, always on a schedule | a `LowStorageEngine`: `HostLowStorage` | +| `HostLowStorageMarch.replay_to`, in `backends/host/low_storage.py` | low-storage, always on a schedule | a `RungeKuttaEngine` with a destructive trial: `HostLowStorage` | | the native session's Adams march, `native/src/adams_march.cpp` | Adams, adaptive and replayed, compiled (ADR-060) | the resident engine (`_ResidentAdams`), from the record `_NativeAdamsMarch` | | the native session's Runge-Kutta march, `native/src/rk_march.cpp` | Runge-Kutta, adaptive and replayed, compiled (ADR-069, [SEP 45](seps/archive/sep-0045-native-rk-march.md)) | the staged trial and native norm | | the native session's low-storage replay | low-storage, always on a schedule | one in-place native step a schedule step | @@ -225,13 +230,15 @@ at a time over a scripted host backend (`tests/backends/native_trace_marches.py` hold it to the reference's decisions on the same readings. A new compiled loop needs a contract that specifies it in full and a reference to compare it with. -What the reference's loops share around a step, and the native session transcribes, is: -`propagate_to` and `observe`, the history (`_record`, or `_record_attempt` and `_skip_step` -for the attempts a compiled march books together), the committed step's work -(`_take_step_stats`: **the statistics channel between planes** and the boundary monitor), the -natural stops, the noise models and **the progress reporter**. A backend supplies -`_trial_step`, `_apply_mask` and `stats`, overrides `_finish` if it has boundary treatments, -and hooks `_begin_plane` and `_on_accepted_step` if it has something to score. +What the reference's marches share around a step, and the native session transcribes, +is the driver's: `propagate_to` and `observe`, the history (`_record`), the committed +step's work (`_take_step_stats`: **the statistics channel between planes** and the +boundary monitor), the natural stops, the noise load and **the progress reporter**. A +march reaches them through `MarchHost` (`poll_stop`, `cap`, `record`, `absorb`, +`stepped`, `natural_stop`, `natural_stop_due`), which the driver implements with +`_SessionHooks`. The backend supplies the workspace, the engines and the run's march; +the driver's `_begin_plane` and `_on_accepted_step` reset and score the workspace's +quadrature alarm, reported once per plane. `set_progress` attaches the observer the loop calls (the driver, not the backend, also tells the reporter when its loop raised). `HostDriver` calls @@ -250,9 +257,10 @@ with the periodic subset promoted to `names`, and appends one row — the positi of the accepted step in this plane's history, and one small array per statistic — to a buffer that `observe` drains into `Observation.step_stats`. Two rules make it sound: -- **The call site is the loop body, after `_finish` and after `z` advances**, not - `_on_accepted_step`. The two marches are not symmetric there: `_march_to` records an - attempt *before* it finishes the state and advances `z`, `_replay_to` after both, so a +- **The call site is the march's `MarchHost.stepped`, after the engine's accept and + after `z` advances**, not `_on_accepted_step`. The two marches are not symmetric there: + an adaptive march records an attempt *before* it accepts and advances `z`, a replay + after both, so a hook would read the previous accepted step on an adaptive run and the current one on a replayed one — and a replayed schedule is exactly what a cost measurement uses, so the wrong version measures clean and records a curve shifted by one step. @@ -280,18 +288,22 @@ predicate. **The boundary monitor's reading** is the third thing the loop calls at the same point, and the backend reduces it (SEP 21, ADR-057). At a check the driver asks -`_boundary_energies(state)` for five numbers, the state's energy and its four weighted +`_boundary_energies()` for five numbers, the state's energy and its four weighted energies (`solprop.monitor.BoundaryEnergies`), and the backend forms them where its state lives: `native` in its memory space through its statistics buffers (CPU and device builds alike). Only the five cross to the host; `numpy_ref`'s host reduction -(`BoundaryMonitor.energies`) is the reference. `_bind_monitor` hands a backend the run's -monitor when it is attached, and `None` when a state is loaded. Under the `split_step` -scheme the backend's `_finish` — and the native engine's own finish, on every march — -adds what each accepted step's split takes of the power it finds, `P (1 − e^{−αh})`, to an -accumulator the next reading drains, so the removal is exact on unchecked steps too, and -keeps the energy and the guards' and collar's energies of that power halfway through the -factor, `P e^{−αh/2}`, which the reading returns beside the five (`BoundaryEnergies.found`, -kernel schema 43) and the monitor judges the occupancies on. The split collar's crossing limit +(`NumpyWorkspace.reading`, over `BoundaryMonitor.energies`) is the reference. +`_bind_monitor` binds the run's monitor to the workspace when it is attached, and `None` +when a state is loaded, either emptying the split accumulator. Under the `split_step` +scheme each accepted step's finish (`NumpyWorkspace.finish`, and the native engine's own +finish, on every march) takes, from the masked field **before** the split, what the split +takes of the power it finds, `P (1 − e^{−αh})`, and the energy and the guards' and +collar's energies of that power halfway through the factor, `P e^{−αh/2}`, and returns +them in the step's `AcceptRecord` (SEP 52 §5.2). The driver adds the removal to an +accumulator the next reading drains (`_absorb`), so the removal is exact on unchecked +steps too, and keeps the latest step's energies, which the reading returns beside the +five (`BoundaryEnergies.found`, kernel schema 43) and the monitor judges the occupancies +on. The split collar's crossing limit reads the state's energy per walk-off bucket at each check, in the same reduction style: one histogram per thread and no atomics, which is why its bucket count has a compiled limit. The input-noise floor is read on the host, once, at the launch. @@ -404,7 +416,7 @@ through this backend. Each section's method is one of two: - **`"constant_schur"`.** The leaf's frozen generator is decomposed once per section, in the backend's constructor, by the factors both backends read (`translate/coupled.py`, `coupled_flow_factors`), and the backend applies a Schur matrix-function action over the - channel axis inside `_trial_step`, taking the inverse the interaction picture needs as + channel axis inside the Runge-Kutta trial (`NumpyRungeKutta.trial`), taking the inverse the interaction picture needs as the matrix function of the negated exponent rather than as a solve and measuring `norm(U) norm(U^-1)` of the whole step against the leaf's declared bound. The Schur factors never cross the seam. The vector wall block is the same section with a @@ -542,7 +554,7 @@ as one; its end-of-plane log is retired, and the boundary monitor's transverse e **The transverse edge is read where the state lives** ([SEP 40](seps/archive/sep-0040-transverse-absorbing-boundaries.md), [SEP 44](seps/archive/sep-0044-native-edge-read.md)). A backend whose `HostDriver.reads_transverse_edge` is set hands the monitor's -`TransverseEdge` an `_EdgeReading` from `HostDriver._edge_reading` at the edge's reads, at saved planes, and with a +`TransverseEdge` an `_EdgeReading` from `NumpyWorkspace.edge_reading` at the edge's reads, at saved planes, and with a requested collar at every committed step. The reading is numbers and never the field: region sums, each column's energy and any collar's strip and current. The default forms them with `_HostEdgeReduction` on a host copy, the reference, which `numpy_ref` uses. `native` forms them on its own state against @@ -572,7 +584,7 @@ A backend that does not set it reports `unwatched` and refuses a requested colla (`native/include/solprop_native/transverse.hpp`, a strict translation unit) owns the edge's every decision and record -- the launch's judgements, the spacing and its ceiling, each read's ledgers and verdict, a collar's current and return, the resume and the record -- and the session reads the resident state for it (`Resident::edge_reading`, the same -reduction as `_edge_reading`). The march's `read_at`/`read_spacing` bounds return it to the session, not to Python, where +reduction as `NumpyWorkspace.edge_reading`). The march's `read_at`/`read_spacing` bounds return it to the session, not to Python, where a read falls due, and with a collar at every committed step, so a collar's current costs no return to Python. The edge follows the temporal monitor at each point of SEP 47 §5.3: launched after the temporal launch, read after a committed step's check and before its statistics row, and at a plane before its row. A point's several warnings (a launch can @@ -868,11 +880,11 @@ Kokkos regions. ### 3.5 The step driver: Python first, compiled when measured **One driver for the reference, one session for native.** `backends/host/driver.py` is the -reference's Runge-Kutta march and replay, the controller bookkeeping, the history and the -noise models, which every NumPy reference backend inherits; the native backend inherits no -driver, and its session marches natively (§1, point 3, lists the marches). Per stage a backend asks the translation layer for one bundle of host -scalars and combines the terms it holds over them (§1); the driver applies the boundary -treatments of `_finish` to a step it keeps, so a rejected step does not pay the temporal +reference's scheduler -- the planes, halts, history, statistics rows and boundary checks -- +over its marches (`backends/host/runge_kutta.py`, `adams.py`, `low_storage.py`), which +own their state; the native backend inherits no driver, and its session marches natively (§1, point 3, lists the marches). Per stage a backend asks the translation layer for one bundle of host +scalars and combines the terms it holds over them (§1); an engine applies the boundary +treatments of the workspace's `finish` only to a step it accepts, so a rejected step does not pay the temporal absorber's transform pair for a state that is thrown away. Under Runge–Kutta the driver's loop is the reference, and on `native` one call executes all diff --git a/docs/dev/kernel-contract.md b/docs/dev/kernel-contract.md index 72cb2e44a..1d1d07ffc 100644 --- a/docs/dev/kernel-contract.md +++ b/docs/dev/kernel-contract.md @@ -244,64 +244,58 @@ too. The test that compares this document with the dataclass walks the tree by t in both directions; a second test checks the flags and counts named in the `flags` row of this section against the fields of `Flags`. -**The transverse edge.** `HostDriver._edge_reading(state, edge, *, faces, current, full)` -returns an `_EdgeReading` ([SEP 44](seps/archive/sep-0044-native-edge-read.md)): region sums, each column's unweighted energy, each +**The transverse edge.** `NumpyWorkspace.edge_reading(edge, *, faces, current, full)` +(native's `NativeBackend._edge_reading`) returns an `_EdgeReading` ([SEP 44](seps/archive/sep-0044-native-edge-read.md)): region sums, each column's unweighted energy, each line's `(inward, windowed)` strip and the summed rectified current, never the field. The default forms them with -`_HostEdgeReduction` on a host copy. An override takes the edge's `_EdgeTables` and `_EdgeLine`s, whose weights, strides, +`_HostEdgeReduction` on a host copy. Native's takes the edge's `_EdgeTables` and `_EdgeLine`s, whose weights, strides, windows and onsets say all there is to know about the geometry, so a backend holds no face, mask or judgement of its own. It reads the state at a committed position, so it may use scratch that a step writes before reading, and it must leave the march as it was. `HostDriver.edge_memory(space)` says what binding holds, from the grid alone, for `estimate`: the default holds nothing beyond the state, and native's is `_transverse_edge_bytes`, equal to its `transverse_edge` ledger row. -**Source reservations in the shared Adams march.** The protected hooks -`HostDriver._reserve_source_calls(count)` and `HostDriver._release_source_calls()` -bound the source evaluations of a trial. Before starting a trial, the shared march -reserves its required source evaluations through these hooks; on every exit it -releases unused capacity. The ordinary backend implementation needs no atomic -reservation. NumPy's TDSE implementation translates the reservation into the +**Source reservations in the Adams march.** The engine protocol's +`begin_attempt(cost)` and `end_attempt(outcome)` (`solprop.backends.engines.AdamsEngine`, +SEP 52 §5.2) bound the source evaluations of a trial. Before starting a trial, after the +budget check, the march begins an attempt with its required source evaluations; it ends +it with its decision once the attempt is recorded, or abandoned on any other exit, which +only releases unused capacity. The reference's engine (`HostHistory`) forwards them to +its workspace (`NumpyWorkspace.reserve_calls`, `record_trial`, `release_calls`), a no-op +without a host source. NumPy's TDSE implementation translates the reservation into the required persistent-plan chunks, while provider attempts remain charged before -invocation, including failures. Logical source-call and atomic-attempt ledgers -remain separate. The base driver owns `_adams`, initially `None`, and exports and -restores its logical ledger on every Adams backend. Loading a checkpoint resets -numerical history but preserves charged calls; startup is charged again. Atomic -ledger restoration needs a bound TDSE binding, on either backend. +invocation, including failures. Logical source-call and atomic-attempt ledgers remain +separate. The march owns its logical ledger, which the driver exports and restores on +every Adams backend. Loading a checkpoint resets numerical history but preserves charged +calls; startup is charged again. Atomic ledger restoration needs a bound TDSE binding, on +either backend. **The lab-frame source of the exponential formulation.** -`HostDriver._adams_lab_source(lab, position, *, purpose)` is the complete source -assembly at a lab-frame field and position -- the `modified` noise draw advanced to -that position's absolute phase, the in-stage absorbers and, on the reference backend, -the TDSE adapter with its labels -- returned in the lab frame, with no propagator -applied. The exponential Adams formulation -([SEP 16](seps/archive/sep-0016-unified-multistep.md)) stores these untransported samples and -integrates their polynomial against the linear flow; the base driver's hook refuses, -naming the backend, so a backend that has not implemented it refuses the formulation -rather than stepping it with another method. `Multistep.formulation` is -`"interaction"` or `"exponential"`. - -**The Adams engine.** With `HostDriver._adams_engine(method, compensation)`, -`HostAdamsMarch` keeps the controller -- orders, slots, rejection, -restarts, the call budget and the ledger -- and hands every state-sized operation of -its fused and exponential paths to an engine -(`solprop.backends.numpy_ref.multistep.AdamsEngine`): the startup sample, a trial's predictor, -source, corrector and scored defect norms, the adoption and transport of an accepted -step, holding and restoring the accepted state around a dense observation, and the -observation itself. Only scalars, the coefficient tables and the norms cross the -interface. The default returns `None`, and the march uses `HostHistory`, the host -engine, over the other Adams hooks; `native` always returns one resident in its native -state, and refuses the untransported compensation witness by name (SEP 47 phase 5 -deleted its host-engine fallback, and with it its `_adams_source`, `_adams_lab_source`, -`_adams_propagator`, `_adams_block` and `_adams_adopt` overrides). - -`HostDriver._adams_source(lab, anchor, position, *, purpose)` takes a -`TDSEPurpose` label so startup, predictor, corrected-field and diagnostic -observations retain their actual provenance. This is a host seam operation: -the shared march neither accesses NumPy's private binding nor adds atomic -physics to a compiled backend. The native backend's march reaches the same binding -through its host source hook (§6). -A corrected-field diagnostic still needs an identical cached response or a +`NumpyWorkspace.lab_source(lab, position, *, purpose)` is the complete source assembly +at a lab-frame field and position -- the `modified` noise draw advanced to that +position's absolute phase, the in-stage absorbers and the TDSE adapter with its labels -- +returned in the lab frame, with no propagator applied. The exponential Adams formulation +([SEP 16](seps/archive/sep-0016-unified-multistep.md)) stores these untransported +samples and integrates their polynomial against the linear flow, and the low-storage +step's passes evaluate it too. `Multistep.formulation` is `"interaction"` or +`"exponential"`. + +**The Adams engine.** `HostAdamsMarch` keeps the controller -- orders, the history's +entries, rejection, restarts, the call budget and the ledger -- in its own state, and +hands every state-sized operation to an engine of the protocol +`solprop.backends.engines.AdamsEngine`, native's `march::Engine` one-to-one: the startup +sample, a trial's predictor, source, corrector and scored defect norms (`trial(z, dz, +stencil)`), and the adoption and transport of an accepted step, which receives the +retained entries oldest first (`accept(dz, free, stencil, kept)`). Only scalars, the +coefficient tables and the norms cross the interface. The reference's engine is +`HostHistory` over the workspace; it still holds and restores the accepted state around +a dense observation, and the observation itself, until SEP 52 moves them to the session. +`native` keeps its engine resident in its native state and refuses the untransported +compensation witness by name. + +`NumpyWorkspace.source(lab, anchor, position, *, purpose)` takes a `TDSEPurpose` label +so startup, predictor, corrected-field and diagnostic observations retain their actual +provenance. The native backend's march reaches the same binding through its host source +hook (§6). A corrected-field diagnostic still needs an identical cached response or a separately charged solve; a predictor label never implies accepted-field data. -If the corrected-field solve fails after candidate adoption, `_adams_restore` -restores the previous accepted field and position before a checkpoint is written. **A `ZProfile` table** is how anything that varies along z crosses the seam: a scalar-valued `translate.chebyshev.PiecewiseChebyshev` over the same z range as `Phi`, @@ -1353,7 +1347,7 @@ not, on CPU and device builds. `PIController` is final (ADR-077), so its decisio the only ones either backend takes.* The adaptive loop of `RungeKutta()` (`integrator is None`, §7) is one algorithm with one -reference implementation, solprop's `HostDriver._march_to` and the controller core it +reference implementation, solprop's `RungeKuttaMarch.march_to` and the controller core it calls (`solprop.backends.rk_core`). A backend may execute the same algorithm natively, as §11's Adams march is executed. It then receives every number the algorithm reads in one record and holds no default and no constant of its own (`native/AGENTS.md`). @@ -1413,7 +1407,7 @@ reference holds it there. planes to the run's end, and the call returns the accepted step that crosses its target unfinished (`dense`), with its equivalent norm; solprop records the step's extension from the state before it and finishes it with the reference's acceptance. *Replay:* -`HostDriver._replay_to`, a call of steps at a time from the schedule's cursor: never a +`RungeKuttaMarch.replay_to`, a call of steps at a time from the schedule's cursor: never a rejection, each step recorded after its commit with its raw norm, the edges within the replay's slack; a non-finite norm returns `diverged`, the step uncommitted. *A coupled flow:* the stage rows carry the anchor's section and each stage's residual weights, and the diff --git a/docs/dev/stepper.md b/docs/dev/stepper.md index 66dccdd20..969905f6f 100644 --- a/docs/dev/stepper.md +++ b/docs/dev/stepper.md @@ -261,7 +261,7 @@ only forward flows are applied, four per element, and on a constant operator `P = Q = exp(hD/2)`. The step is four passes over three registers -- the state `A`, overwritten in place by `P A` and then by the accepted step, the accumulator `B` and the stage input `C` -- beside the pipeline's scratch, each pass one source evaluation -(`_adams_lab_source`, the complete lab-frame source with the noise draw at the pass's +(the workspace's `lab_source`, the complete lab-frame source with the noise draw at the pass's position) and one fold: | pass | evaluation | fold | @@ -272,8 +272,9 @@ position) and one fold: | 4 | `F4` at `z_n + h` | `A <- Q B + h/6 S` | `HostLowStorageMarch` replays a schedule and nothing else, mirroring `HostAdamsMarch`'s -replay: each step calls the host engine (`HostLowStorage.step`), applies `_finish` and -moves the position in one commit. The native backend holds no such march: its resident +replay: each step's trial (`HostLowStorage.trial`) overwrites the state, in flight until +the engine's accept finishes it, and the march moves its position in the same commit +(SEP 52 §5.2). The native backend holds no such march: its resident registers (`_ResidentLowStorage`) step only for a timing probe's trial, one native call per step. The native execution session ([SEP 47](seps/archive/sep-0047-run-ownership.md) section 6.3, `solprop_native.session`) owns the loop itself: the native Runge-Kutta march replays the @@ -315,25 +316,20 @@ picture, transporting the history, on request - a corrector one order higher than its predictor; - variable order up to five by default. -The march (`backends/numpy_ref/multistep.py`) is shared: a backend supplies the step driver's two -hooks `_adams_source`, one source evaluation at a lab-frame field returned in the step's -anchor frame, and `_adams_propagator`, and takes the march as its `_march_to` when the -problem carries an integrator. `numpy_ref` evaluates through its reference passes. `native` keeps -its state natively, so it also supplies `_adams_state` and `_adams_adopt`, a host copy of -the accepted state and the native finish; its source is stage zero of a trial whose -every stage row is the evaluation position's (`State.adams_source`), on every route -but a coupled flow, and its lab-frame source the same with the anchor at the -position, and after a dense -observation, which loads the interpolated field natively, `_adams_restore` reloads the -march's own state. The selected family, one-order-higher PEC, takes a **fused** +The reference's march (`backends/host/adams.py`) hands every state-sized operation to its +engine, `HostHistory` (`backends/numpy_ref/multistep.py`), over the workspace's +operations: `source`, one source evaluation at a lab-frame field returned in the step's +anchor frame, and `propagator`. `native` marches natively, its source stage zero of a +trial whose every stage row is the evaluation position's, on every route but a coupled +flow, and its lab-frame source the same with the anchor at the position. The selected family, one-order-higher PEC, takes a **fused** path: the history is a store of rows, and a step is three passes of `AdamsKernels` -- the predictor's lab-frame field, the corrected field with the defects of the step's own and the neighbouring orders, and the transport -- which the native engine runs in its kernels. Dense observation of save planes is ADR-036's; on the fused path the step's slopes are copied before the in-place transport. **The exponential formulation** (ADR-041) shares the march. Its samples are -untransported: the source comes from the hook `_adams_lab_source`, the lab-frame +untransported: the source comes from the workspace's `lab_source`, the lab-frame evaluation, and lands in the same store of rows, which an accepted step does not -re-anchor. A trial takes `x = ΔΦ` over the step from the backend's own `_delta_phi`, +re-anchor. A trial takes `x = ΔΦ` over the step from the workspace's own `delta_phi`, so that its flow `exp(x)` is the propagator the interaction formulation would apply, forms the moments `k! φ_{k+1}(x)` once (`backends/exponential.py`), and applies the predictor, the corrector and the neighbouring orders' defects in the monomial basis of @@ -342,7 +338,7 @@ so no propagator multiplies them. The defect, the norm's scale and the lifecycle the transported formulation's; so is the order choice, but for the in-stage collar's stability, which it weighs (`adams_core.order_weight`): each order's step factor is capped at `COLLAR_STABILITY` times PEC's negative-real interval over -`h max(α) / 2`, the step itself left to the chosen order's defect. **Beside a coupled flow** (ADR-044) the backend's hook `_adams_block` returns the frozen block of the step's +`h max(α) / 2`, the step itself left to the chosen order's defect. **Beside a coupled flow** (ADR-044) the workspace's `coupled_block` returns the frozen block of the step's section (`CoupledBlock`); `coupled_moments` forms the trial's flow and moments as matrix functions of `(ΔΦ/h) I + G_s` on the block's bins, `CoupledExponentialKernels` applies them -- on the native backend in its kernels, which diff --git a/tests/backends/test_host_marches.py b/tests/backends/test_host_marches.py new file mode 100644 index 000000000..70d97bfd5 --- /dev/null +++ b/tests/backends/test_host_marches.py @@ -0,0 +1,225 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""The reference's marches own their state and ask their session narrowly (SEP 52). + +Each march keeps its position, proposal, cursor and accepted norms in its own +:class:`~solprop.backends.host.marches.MarchState`, hands state-sized work to its +engine and asks the session only through +:class:`~solprop.backends.host.marches.MarchHost`. Here the engine and the session are +recorders: what a march calls, in which order, and what it hands on, without any field +arithmetic. The decisions themselves are the trace corpora's +(``test_rk_traces.py``, ``test_adams_traces.py``). +""" + +import math +from typing import Any, cast + +import pytest + +from solprop.backends.engines import AcceptRecord +from solprop.backends.host.low_storage import HostLowStorageMarch +from solprop.backends.host.marches import MarchState, in_flight_refusal +from solprop.backends.host.runge_kutta import RungeKuttaMarch +from solprop.backends.records import RungeKuttaPolicy +from solprop.exceptions import BackendError, ConvergenceError +from solprop.stepper import FixedSchedule, LowStorageRungeKutta, PIController + + +class Host: + """A session that records what a march asks of it.""" + + collar_quiet = False + + def __init__(self, *, natural_every: int = 0) -> None: + self.calls: list[tuple[Any, ...]] = [] + self.records: list[AcceptRecord] = [] + self.natural_every = natural_every + self.stepped_count = 0 + + def poll_stop(self) -> None: + self.calls.append(("poll",)) + + def cap(self, proposal: float, z: float) -> float: + self.calls.append(("cap", z)) + return proposal + + def record(self, end: float, dz: float, norm: float, accepted: bool) -> None: + self.calls.append(("record", end, accepted)) + + def absorb(self, record: AcceptRecord) -> None: + self.calls.append(("absorb",)) + self.records.append(record) + + def stepped(self) -> None: + self.calls.append(("stepped",)) + self.stepped_count += 1 + + def natural_stop(self, target: float) -> bool: + return bool(self.natural_every) and self.stepped_count % self.natural_every == 0 + + def natural_stop_due(self, target: float) -> bool: + return False + + +class Engine: + """A Runge-Kutta engine that scores trials from a list and records its calls.""" + + def __init__(self, norms: list[float], *, diverge_at: int | None = None) -> None: + self.norms = list(norms) + self.calls: list[tuple[Any, ...]] = [] + self.diverge_at = diverge_at + self.trials = 0 + self.flight = False + + @property + def in_flight(self) -> bool: + return self.flight + + def trial(self, z: float, dz: float) -> float: + self.trials += 1 + self.calls.append(("trial", z, dz)) + self.flight = True + if self.trials == self.diverge_at: + return math.inf + return self.norms.pop(0) if self.norms else 0.5 + + def accept(self, dz: float) -> AcceptRecord: + self.calls.append(("accept", dz)) + self.flight = False + return AcceptRecord(removed=float(len(self.calls)), stiffness=0.25) + + def extend(self, z: float, dz: float) -> None: + raise NotImplementedError + + def reading(self) -> Any: + raise NotImplementedError + + def reset(self) -> None: + self.calls.append(("reset",)) + self.flight = False + + +def _policy() -> RungeKuttaPolicy: + return RungeKuttaPolicy( + controller=PIController(rtol=1e-6, atol=0.0), + dz_min=0.0, + dz_max=1.0, + auto_init=False, + stretch=1.0, + z_end=1.0, + save_planes=(1.0,), + interpolate=False, + hard_kinks=(), + breakpoints=(0.0, 1.0), + landing_ulps=8, + start_growth=100.0, + quiet_interval=None, + ) + + +def test_a_march_state_starts_afresh_at_a_load(): + state = MarchState(z=0.3, proposal=0.1, cursor=4) + state.norms.extend([1.0, 2.0]) + state.load(0.5, 0.2, 7) + assert (state.z, state.proposal, state.cursor) == (0.5, 0.2, 7) + assert list(state.norms) == [] + + +def test_the_runge_kutta_march_keeps_its_state_and_asks_in_order(): + engine, host = Engine([2.0, 0.5]), Host() + march = RungeKuttaMarch(engine, _policy(), host, schedule=None, proposal=0.25) + march.load(0.0, 0.25, 0) + assert engine.calls == [("reset",)] + march.march_to(0.25) + assert march.state.z == 0.25 + assert len(march.state.norms) >= 1 + # A rejected trial is recorded and never accepted or absorbed; the accepted one + # is accepted, absorbed and accounted after the position moved. + kinds = [call[0] for call in host.calls] + assert kinds[:4] == ["poll", "cap", "record", "poll"] + assert host.calls[2] == ("record", 0.25, False) + assert kinds[4:8] == ["cap", "record", "absorb", "stepped"] + assert [call[0] for call in engine.calls[1:4]] == ["trial", "trial", "accept"] + # What the accept reported is what the session absorbs. + assert host.records[0].removed == 4.0 + + +def test_a_replayed_runge_kutta_step_that_diverges_commits_nothing(): + engine, host = Engine([], diverge_at=2), Host() + schedule = FixedSchedule.uniform(0.0, 1.0, 0.25) + march = RungeKuttaMarch(engine, _policy(), host, schedule=schedule, proposal=0.25) + march.load(0.0, 0.25, 0) + with pytest.raises(ConvergenceError, match="non-finite error norm"): + march.advance(1.0) + assert march.state.cursor == 1 + assert march.state.z == 0.25 + assert [call[0] for call in engine.calls].count("accept") == 1 + + +def test_the_low_storage_march_reports_a_step_left_in_flight(): + engine, host = Engine([], diverge_at=2), Host() + schedule = FixedSchedule.uniform(0.0, 1.0, 0.25) + march = HostLowStorageMarch( + engine, LowStorageRungeKutta(), host, schedule=schedule, proposal=0.25 + ) + march.load(0.0, 0.25, 0) + with pytest.raises(ConvergenceError, match="non-finite state"): + march.advance(1.0) + # The first step committed with its evaluations; the second is in flight. + assert march.state.z == 0.25 + assert march.source_evaluations == LowStorageRungeKutta().evaluations + assert march.in_flight == (0.25, 0.25) + assert march.refusal() == in_flight_refusal("numpy_ref", 0.25, 0.25) + with pytest.raises(BackendError, match="abandoned in flight"): + march.replay_step(0.25, 0.5, 0.0) + # A load clears it, and the count is the loaded run's. + march.load(0.0, 0.25, 0) + assert march.in_flight is None + assert march.source_evaluations == 0 + + +def test_the_low_storage_march_hands_the_stiffness_from_the_accept(caplog): + engine, host = Engine([]), Host() + schedule = FixedSchedule.uniform(0.0, 0.5, 0.25) + method = LowStorageRungeKutta() + march = HostLowStorageMarch(engine, method, host, schedule=schedule, proposal=0.25) + march.load(0.0, 0.25, 0) + march.advance(0.5) + assert march.state.z == 0.5 + assert len(host.records) == 2 + assert all(record.stiffness == 0.25 for record in host.records) + assert "stiffness indicator" not in caplog.text + + +def test_an_adams_floor_after_a_rejection_keeps_a_failed_release_as_a_note(): + from solprop.backends.host.adams import HostAdamsMarch, _Attempt # noqa: PLC0415 + + ended = [] + + class Failing: + def begin_attempt(self, cost: int) -> None: + pass + + def end_attempt(self, outcome: Any) -> None: + ended.append(outcome) + raise BackendError("release failed") + + march = cast("Any", object.__new__(HostAdamsMarch)) + march._floor = ConvergenceError("the floor") + attempt = _Attempt(Failing()) + attempt.begin(2) + with pytest.raises(ConvergenceError, match="the floor") as caught: + march._end(attempt, accepted=False) + assert caught.value.__notes__ == [ + "releasing the source reservation failed: release failed" + ] + assert not attempt.open + assert len(ended) == 1 + # Accepted, the end's failure is the error, before any floor. + march._floor = ConvergenceError("the floor") + attempt = _Attempt(Failing()) + attempt.begin(1) + with pytest.raises(BackendError, match="release failed"): + march._end(attempt, accepted=True) diff --git a/tests/backends/test_numpy_engines.py b/tests/backends/test_numpy_engines.py new file mode 100644 index 000000000..ff2067d38 --- /dev/null +++ b/tests/backends/test_numpy_engines.py @@ -0,0 +1,266 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""The reference's engines hold SEP 52 section 5.2's commit contract. + +The Runge-Kutta engine keeps its trial and commits only at ``accept``; the low-storage +engine is the same protocol with a destructive trial, in flight from ``trial`` until +``accept`` returns; the Adams engine takes the retained entries oldest first and the +host source's reservation as ``begin_attempt``/``end_attempt``. The split collar's sums +are taken by the workspace's finish on the masked field before the split and travel in +the :class:`~solprop.backends.engines.AcceptRecord`, which the driver accumulates. + +Every comparison here repeats one computation on one build, so equality is exact by +construction (structural, SEP 25): the engines move arrays, they do not recompute them. +""" + +import math +from contextlib import closing + +import numpy as np +import pytest + +from backend_corpus_cases import FIBRE, STEPS, walking_fibre +from solprop.backends.engines import AcceptRecord, AttemptOutcome +from solprop.backends.numpy_ref import NumpyRefBackend +from solprop.exceptions import BackendError +from solprop.stepper import FixedSchedule, LowStorageRungeKutta, Multistep, RungeKutta + +LENGTH = 0.02 + + +def _loaded(soliton_problem, narrow_grid, **settings): + """Return the soliton's reference backend loaded at the entrance.""" + problem, request = soliton_problem(narrow_grid, 1, save_planes=[LENGTH], **settings) + backend = NumpyRefBackend(problem, request, grid=narrow_grid) + backend.set_initial(problem.initial.field0, None) + return backend + + +def test_a_runge_kutta_trial_commits_nothing_until_it_is_accepted( + soliton_problem, narrow_grid +): + with closing(_loaded(soliton_problem, narrow_grid)) as backend: + engine, workspace = backend._runge_kutta_engine, backend.workspace + committed = workspace.state + assert committed is not None + before = committed.copy() + engine.trial(0.0, LENGTH / 8) + # A trial is held beside the committed state, which it leaves alone. + assert workspace.state is committed + assert np.array_equal(committed, before) + assert not np.array_equal(engine.trial_state, before) + # A rejected trial is replaced by the next; the committed state still stands. + engine.trial(0.0, LENGTH / 16) + assert workspace.state is committed + engine.trial(0.0, LENGTH / 8) + expected, _ = workspace.finish(engine.trial_state, LENGTH / 8) + record = engine.accept(LENGTH / 8) + assert workspace.state is not committed + assert np.array_equal(workspace.state, expected) + # Without a split collar the finish takes no sums and forms no stiffness. + assert record.removed == 0.0 + assert record.found is None + assert math.isnan(record.stiffness) + assert not engine.in_flight + + +def test_a_runge_kutta_engine_counts_every_stage_it_evaluates( + soliton_problem, narrow_grid +): + with closing(_loaded(soliton_problem, narrow_grid)) as backend: + engine = backend._runge_kutta_engine + stages = backend.request.stepper.tableau.n_stages + engine.trial(0.0, LENGTH / 8) + engine.trial(0.0, LENGTH / 16) + assert engine.evaluations == 2 * stages + assert len(engine.stages) == stages + backend.set_initial(backend._problem.initial.field0, None) + assert engine.evaluations == 0 + with pytest.raises(BackendError, match="take a trial"): + _ = engine.trial_state + + +def test_the_low_storage_trial_is_in_flight_until_its_accept_returns( + soliton_problem, narrow_grid +): + schedule = FixedSchedule.uniform(0.0, LENGTH, LENGTH / 8) + backend = _loaded( + soliton_problem, + narrow_grid, + integrator=LowStorageRungeKutta(), + schedule=schedule, + ) + with closing(backend): + assert backend._low_storage is not None + engine = backend._low_storage.engine + workspace = backend.workspace + before = np.array(workspace.state) + assert not engine.in_flight + dz = float(schedule.steps[0]) + assert engine.trial(0.0, dz) == 0.0 + # The trial overwrote the state, the register A: neither end of the step. + assert engine.in_flight + assert not np.array_equal(workspace.state, before) + record = engine.accept(dz) + assert not engine.in_flight + assert math.isfinite(record.stiffness) and record.stiffness > 0.0 + assert record.found is None + + +def test_a_low_storage_finish_that_fails_leaves_the_step_in_flight( + soliton_problem, narrow_grid, monkeypatch +): + # A failure inside the accept, after the trial overwrote the state, leaves no + # committed state at that position: the run ends failed with nothing to read. + schedule = FixedSchedule.uniform(0.0, LENGTH, LENGTH / 8) + backend = _loaded( + soliton_problem, + narrow_grid, + integrator=LowStorageRungeKutta(), + schedule=schedule, + ) + with closing(backend): + + def failing(state, dz): + raise RuntimeError("the finish failed") + + monkeypatch.setattr(backend.workspace, "finish", failing) + with pytest.raises(RuntimeError, match="the finish failed"): + backend.propagate_to(LENGTH) + assert backend.in_flight == (0.0, float(schedule.steps[0])) + assert backend.metadata()["source_evaluations"] == 0 + with pytest.raises(BackendError, match="abandoned in flight"): + backend.observe() + monkeypatch.undo() + backend.set_initial(backend._problem.initial.field0, None) + assert backend.in_flight is None + + +@pytest.mark.parametrize("formulation", ["interaction", "exponential"]) +def test_an_adams_attempt_reserves_then_records_and_releases( + soliton_problem, narrow_grid, monkeypatch, formulation +): + backend = _loaded( + soliton_problem, narrow_grid, integrator=Multistep(formulation=formulation) + ) + calls = [] + with closing(backend): + workspace = backend.workspace + monkeypatch.setattr( + workspace, "reserve_calls", lambda cost: calls.append(("reserve", cost)) + ) + monkeypatch.setattr( + workspace, + "record_trial", + lambda *, accepted: calls.append(("record", accepted)), + ) + monkeypatch.setattr( + workspace, "release_calls", lambda: calls.append(("release",)) + ) + backend.propagate_to(LENGTH / 4) + history = backend.observe().step_history + # One reservation per attempt, then its decision, then the release: the startup + # sample is charged to the first. + attempts = [calls[index : index + 3] for index in range(0, len(calls), 3)] + assert len(attempts) == history.n_steps + assert attempts[0][0] == ("reserve", 2) + for attempt, accepted in zip(attempts, history.accepted, strict=True): + assert attempt[0][0] == "reserve" + assert attempt[1:] == [("record", bool(accepted)), ("release",)] + + +def test_an_abandoned_adams_attempt_only_releases(soliton_problem, narrow_grid): + backend = _loaded(soliton_problem, narrow_grid, integrator=Multistep()) + with closing(backend): + assert backend._adams is not None + engine = backend._adams._engine + calls = [] + workspace = backend.workspace + workspace.record_trial = lambda *, accepted: calls.append(("record", accepted)) + workspace.release_calls = lambda: calls.append(("release",)) + engine.end_attempt(AttemptOutcome.ABANDONED) + engine.end_attempt(AttemptOutcome.REJECTED) + assert calls == [("release",), ("record", False), ("release",)] + + +def test_an_adams_accept_takes_the_kept_entries_oldest_first( + soliton_problem, narrow_grid, monkeypatch +): + backend = _loaded(soliton_problem, narrow_grid, integrator=Multistep()) + with closing(backend): + march = backend._adams + assert march is not None + engine = march._engine + seen = [] + accept = engine.accept + + def spy(dz, free, stencil, kept): + seen.append(([entry.z for entry in kept], [e.row for e in kept], free)) + return accept(dz, free, stencil, kept) + + monkeypatch.setattr(engine, "accept", spy) + backend.propagate_to(LENGTH / 4) + assert len(seen) > 2 + for positions, rows, free in seen: + assert positions == sorted(positions) + assert free not in rows + + +def _split_backend(): + """Return the walking fibre's reference backend, loaded and watched.""" + simulation = walking_fibre("numpy_ref", RungeKutta()) + problem = simulation.translate() + request = simulation._run_request() + backend = NumpyRefBackend(problem, request, grid=simulation.grid) + backend.set_initial(problem.initial.field0, None) + monitor = simulation._boundary_monitor() + assert monitor is not None and monitor.split + backend.attach_monitor(monitor) + return backend, monitor + + +@pytest.mark.medium +def test_the_finish_takes_the_split_sums_on_the_masked_field_before_the_split(): + backend, monitor = _split_backend() + with closing(backend): + workspace = backend.workspace + dz = FIBRE / STEPS + engine = backend._runge_kutta_engine + engine.trial(0.0, dz) + raw = engine.trial_state + finished, record = workspace.finish(raw, dz) + sums = monitor.split_sums(workspace.mask(raw), dz) + assert record.removed == float(sums[0]) + assert record.found is not None + assert np.array_equal(record.found, sums[1:]) + # The same reduction of the finished, damped field is another number: the + # measurement point is the field before the split (SEP 52 section 4). + after = monitor.split_sums(finished, dz) + assert record.removed > 0.0 + assert abs(float(after[0]) - record.removed) > 1e-3 * record.removed + + +@pytest.mark.medium +def test_the_driver_adds_the_removal_and_keeps_the_latest_occupancies(): + backend, _ = _split_backend() + with closing(backend): + first = np.array([1.0, 0.5, 0.25, 0.125]) + latest = np.array([2.0, 1.0, 0.5, 0.25]) + backend._absorb(AcceptRecord(removed=1.5, found=first)) + backend._absorb(AcceptRecord(removed=0.25, found=latest)) + # A step that took no sums (no split, or no monitor) leaves both alone. + backend._absorb(AcceptRecord()) + assert backend._split_removed == 1.75 + assert backend._split_found is latest + # The next reading drains the removal and judges the latest occupancies. + reading = backend._boundary_energies() + assert reading.removed == 1.75 + assert reading.found is latest + assert backend._split_removed == 0.0 + # Loading a state empties the accumulator. + backend._absorb(AcceptRecord(removed=3.0, found=first)) + backend.set_initial(backend._problem.initial.field0, None) + assert backend._split_removed == 0.0 + assert backend._split_found is None From f2db10845bba80539c45857deb0c4d8cf187d981 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 03:41:16 +0000 Subject: [PATCH 03/14] test: port the last tests the broad sweep found on the moved members The low-storage failure and stiffness probes wrap the engine's trial and its passes, the general route's linear short-circuit reads the workspace, the fused-predictor integration reads the march's engine, and the scripted driver, now the reference backend, refuses atomic ledgers with its TDSE message. Casts where a test reaches past the engine protocol. Co-Authored-By: Claude Opus 5.5 --- tests/backends/adams_traces.py | 11 ++++++----- tests/backends/test_carrier_frame.py | 5 +++-- tests/backends/test_exponential_varying.py | 6 +++--- tests/backends/test_general_modal.py | 8 ++++---- tests/backends/test_host_ledgers.py | 12 +++++++----- tests/backends/test_low_storage.py | 6 +++--- tests/backends/test_native_synthetic_operator.py | 14 ++++++++------ tests/backends/test_numpy_engines.py | 7 ++++--- tests/driver/test_resume.py | 6 +++--- tests/driver/test_sep12_sep14_integration.py | 5 ++++- tests/scripted_driver.py | 9 +++++++-- tests/sessions/test_native_session_low_storage.py | 6 +++--- 12 files changed, 55 insertions(+), 40 deletions(-) diff --git a/tests/backends/adams_traces.py b/tests/backends/adams_traces.py index a0b25d871..336e16503 100644 --- a/tests/backends/adams_traces.py +++ b/tests/backends/adams_traces.py @@ -27,7 +27,7 @@ import math from collections import deque from dataclasses import dataclass, field -from typing import Any +from typing import Any, cast import numpy as np @@ -469,9 +469,10 @@ def adams_march(self, method: Multistep) -> HostAdamsMarch: engine = self.engine assert engine is not None carrier = engine.carrier + stepper: Any = self._stepper policy = adams_policy( - self._problem, - self._stepper, + cast("Any", self._problem), + stepper, method, carrier=isinstance(carrier, CarrierReference) and carrier.active, ) @@ -481,8 +482,8 @@ def adams_march(self, method: Multistep) -> HostAdamsMarch: self._hooks, policy=policy, field=lambda: np.zeros((1, 1, 1), dtype=np.complex128), - schedule=self._stepper.schedule, - interpolate=self._stepper.interpolate_planes, + schedule=stepper.schedule, + interpolate=stepper.interpolate_planes, shape=(1, 1, 1), proposal=self.scenario.proposal, lag=1, diff --git a/tests/backends/test_carrier_frame.py b/tests/backends/test_carrier_frame.py index 287f90cfc..f6ebb1171 100644 --- a/tests/backends/test_carrier_frame.py +++ b/tests/backends/test_carrier_frame.py @@ -22,7 +22,7 @@ import math import warnings from types import SimpleNamespace -from typing import Literal +from typing import Any, Literal, cast import mpmath import numpy as np @@ -865,7 +865,8 @@ def test_a_varying_operator_is_compensated_under_the_frame(compensation): # samples. Both against a converged Runge-Kutta reference. reference = march(gradient(RungeKutta(), 1e-11)).fields[-1] field, run = gradient_run(SCALAR, compensation) - assert run._engine.compensated and shifted(run) + assert run is not None + assert cast("Any", run._engine).compensated and shifted(run) assert relative(field, reference) < 1e-8 * run.ledger.accepted_steps diff --git a/tests/backends/test_exponential_varying.py b/tests/backends/test_exponential_varying.py index 1f915f41f..def79532f 100644 --- a/tests/backends/test_exponential_varying.py +++ b/tests/backends/test_exponential_varying.py @@ -15,7 +15,7 @@ import dataclasses import math -from typing import Any +from typing import Any, cast import numpy as np import pytest @@ -164,7 +164,7 @@ def test_a_structurally_absent_source_takes_the_exact_flow(): problem = simulation.translate() assert len(problem.responses.response_order) == 1 field, adams, _ = march(simulation) - assert adams is not None and not adams._engine.compensated + assert adams is not None and not cast("Any", adams._engine).compensated start = problem.initial.field0 * problem.grids.active_mask exact = np.exp(delta_phi(problem.linear, 0.0, LENGTH)) * start # Round-off of the flows' products, step by step. @@ -374,7 +374,7 @@ def test_an_adiabatic_taper(): taper = Linear(100e-6, 80e-6, LENGTH) reference, _, _ = march(gradient(integrator=RungeKutta(), rtol=1e-11, radius=taper)) field, adams, _ = march(gradient(radius=taper)) - assert adams is not None and adams._engine.compensated + assert adams is not None and cast("Any", adams._engine).compensated error = np.linalg.norm(field - reference) / np.linalg.norm(reference) assert error < 1e-5, error diff --git a/tests/backends/test_general_modal.py b/tests/backends/test_general_modal.py index 8055283bd..a96f0e8e7 100644 --- a/tests/backends/test_general_modal.py +++ b/tests/backends/test_general_modal.py @@ -1303,16 +1303,16 @@ def step(backend): return field forced = NumpyRefBackend(problem, run_request, grid=case.grid) - assert not forced._general_responds - forced._general_responds = True + assert not forced.workspace._general_responds + forced.workspace._general_responds = True expected = step(forced) def refuse(*arguments, **keywords): raise AssertionError("the general source pass ran for a linear guide") - monkeypatch.setattr("solprop.backends.numpy_ref.backend.general_source", refuse) + monkeypatch.setattr("solprop.backends.numpy_ref.workspace.general_source", refuse) short = NumpyRefBackend(problem, run_request, grid=case.grid) - assert not short._general_responds + assert not short.workspace._general_responds field = step(short) assert np.any(field) np.testing.assert_array_equal(field.view(np.uint8), expected.view(np.uint8)) diff --git a/tests/backends/test_host_ledgers.py b/tests/backends/test_host_ledgers.py index 5455823a7..9537765df 100644 --- a/tests/backends/test_host_ledgers.py +++ b/tests/backends/test_host_ledgers.py @@ -2,12 +2,12 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""A reference driver with no atomic service refuses atomic call ledgers. +"""A reference backend with no atomic service refuses atomic call ledgers. :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, such as a stand-in, is refused them by name -rather than silently dropping a budget a resume must honour. +logical Adams counts every host driver keeps. Only a TDSE binding keeps atomic counts; a +run without one is refused them by name rather than silently dropping a budget a resume +must honour. """ import pytest @@ -20,7 +20,9 @@ def test_a_host_driver_without_an_atomic_service_refuses_atomic_ledgers(): driver = HostScriptedDriver(*soliton(), grid=window()) try: - with pytest.raises(BackendError, match="does not restore atomic"): + with pytest.raises( + BackendError, match="atomic call ledger requires a TDSE binding" + ): driver.restore_call_ledgers({}, {"attempted": 1}) # Nothing atomic, and a march with no logical ledger: nothing to install. driver.restore_call_ledgers({}, {}) diff --git a/tests/backends/test_low_storage.py b/tests/backends/test_low_storage.py index 96dea2082..0af2f40fc 100644 --- a/tests/backends/test_low_storage.py +++ b/tests/backends/test_low_storage.py @@ -994,7 +994,7 @@ def test_an_atomic_engine_commits_its_step_whole(lifecycle, narrow_grid, atomic) backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) backend.set_initial(problem.initial.field0, None) assert backend._low_storage is not None - engine = backend._low_storage.engine + engine = cast("Any", backend._low_storage.engine) assert isinstance(engine, HostLowStorage) is not atomic original = engine.trial @@ -1421,7 +1421,7 @@ def counted(anchor, position): built.append((anchor, position)) return propagator(anchor, position) - backend.workspace.propagator = counted + cast("Any", backend.workspace).propagator = counted backend.propagate_to(length / 2) backend.propagate_to(length) assert len(built) == 1 @@ -1441,7 +1441,7 @@ def counted(anchor, position): backend.set_initial(varied.initial.field0, None) built.clear() propagator = backend.workspace.propagator - backend.workspace.propagator = counted + cast("Any", backend.workspace).propagator = counted backend.propagate_to(length) assert len(built) == varied_schedule.n_steps # A load drops the table, which the next step builds again. diff --git a/tests/backends/test_native_synthetic_operator.py b/tests/backends/test_native_synthetic_operator.py index 1eb736495..cd7824fbf 100644 --- a/tests/backends/test_native_synthetic_operator.py +++ b/tests/backends/test_native_synthetic_operator.py @@ -46,7 +46,7 @@ from bounds import gamma from sessions.runs import load_native from sessions.runs import run as session_run -from solprop.backends.host.low_storage import HostLowStorageMarch +from solprop.backends.low_storage import HostLowStorage from solprop.backends.numpy_ref import NumpyRefBackend from solprop.exceptions import ConvergenceError @@ -139,19 +139,21 @@ def test_the_march_s_norm_reads_a_mask_with_a_hard_zero(monkeypatch): The original read it from the fold's partials. Here it is what the engine hands the accept, on each backend, against the sum over the mask of the state that step - leaves, within one sum's rounding: the reference's in its session, native's from - its resident engine, whose state is the native session's own to the bit. + leaves, within one sum's rounding: the reference's engine's (``HostLowStorage``) in + its session, native's from its resident engine, whose state is the native + session's own to the bit. """ problem, run_request, grid = free_problem(responses=[KERR]) leaf = free_leaf(problem.linear.separable) problem, mask = with_masked_bin(on_leaf(problem, leaf), leaf) seen = [] - def capture(self, z, dz, squared, accept=HostLowStorageMarch._accept): + def capture(self, state, z, dz, step=HostLowStorage._step): + squared = step(self, state, z, dz) seen.append(squared) - return accept(self, z, dz, squared) + return squared - monkeypatch.setattr(HostLowStorageMarch, "_accept", capture) + monkeypatch.setattr(HostLowStorage, "_step", capture) reference = run(NumpyRefBackend, problem, run_request, grid) assert len(seen) == 1 squared, resident = resident_step(problem, run_request, grid) diff --git a/tests/backends/test_numpy_engines.py b/tests/backends/test_numpy_engines.py index ff2067d38..861ac8f0f 100644 --- a/tests/backends/test_numpy_engines.py +++ b/tests/backends/test_numpy_engines.py @@ -17,6 +17,7 @@ import math from contextlib import closing +from typing import Any, cast import numpy as np import pytest @@ -58,7 +59,7 @@ def test_a_runge_kutta_trial_commits_nothing_until_it_is_accepted( expected, _ = workspace.finish(engine.trial_state, LENGTH / 8) record = engine.accept(LENGTH / 8) assert workspace.state is not committed - assert np.array_equal(workspace.state, expected) + assert np.array_equal(workspace.committed(), expected) # Without a split collar the finish takes no sums and forms no stiffness. assert record.removed == 0.0 assert record.found is None @@ -94,7 +95,7 @@ def test_the_low_storage_trial_is_in_flight_until_its_accept_returns( ) with closing(backend): assert backend._low_storage is not None - engine = backend._low_storage.engine + engine = cast("Any", backend._low_storage.engine) workspace = backend.workspace before = np.array(workspace.state) assert not engine.in_flight @@ -102,7 +103,7 @@ def test_the_low_storage_trial_is_in_flight_until_its_accept_returns( assert engine.trial(0.0, dz) == 0.0 # The trial overwrote the state, the register A: neither end of the step. assert engine.in_flight - assert not np.array_equal(workspace.state, before) + assert not np.array_equal(workspace.committed(), before) record = engine.accept(dz) assert not engine.in_flight assert math.isfinite(record.stiffness) and record.stiffness > 0.0 diff --git a/tests/driver/test_resume.py b/tests/driver/test_resume.py index c2e640623..0ba39dc6a 100644 --- a/tests/driver/test_resume.py +++ b/tests/driver/test_resume.py @@ -7,7 +7,7 @@ import dataclasses import importlib import importlib.util -from typing import Any +from typing import Any, cast import h5py import numpy as np @@ -366,10 +366,10 @@ def test_the_input_draw_is_added_at_a_launch_and_not_to_a_resumed_state( atol=1e-12 * np.linalg.norm(draw), ) # The floor is the draw itself. - assert engine.workspace.input_floor is draw + assert cast("Any", engine).workspace.input_floor is draw engine.set_initial(launched, None, z=0.0, resume=True) np.testing.assert_array_equal(engine.observe().require_field(), launched) - assert engine.workspace.input_floor is draw + assert cast("Any", engine).workspace.input_floor is draw finally: engine.close() diff --git a/tests/driver/test_sep12_sep14_integration.py b/tests/driver/test_sep12_sep14_integration.py index ed5212c26..feaff90f7 100644 --- a/tests/driver/test_sep12_sep14_integration.py +++ b/tests/driver/test_sep12_sep14_integration.py @@ -5,6 +5,7 @@ """Keep atomic budgets and checkpoints intact across the shared Adams march.""" import dataclasses +from typing import Any, cast import numpy as np import pytest @@ -178,7 +179,9 @@ def test_fused_predictor_failure_charges_both_ledgers_before_invocation(formulat initial = backend.observe() assert backend._adams is not None # The interaction formulation's fused path, or the exponential one's own. - assert (backend._adams._exponential is None) is (formulation == "interaction") + assert (cast("Any", backend._adams._engine)._exponential is None) is ( + formulation == "interaction" + ) with pytest.raises(BackendError, match="predictor chunk failure"): backend.propagate_to(simulation.grid.length) actual = backend.observe() diff --git a/tests/scripted_driver.py b/tests/scripted_driver.py index f434f7ac6..b37337a73 100644 --- a/tests/scripted_driver.py +++ b/tests/scripted_driver.py @@ -53,9 +53,14 @@ class _Scripted: if TYPE_CHECKING: # What the mixin reads of the driver it is mixed into. - _proposal: float _problem: Any - _z: float + + @property + def _z(self) -> float: ... + + @property + def _proposal(self) -> float: ... + _closed: bool _workspace: Any diff --git a/tests/sessions/test_native_session_low_storage.py b/tests/sessions/test_native_session_low_storage.py index 83beca03e..00234966d 100644 --- a/tests/sessions/test_native_session_low_storage.py +++ b/tests/sessions/test_native_session_low_storage.py @@ -200,13 +200,13 @@ def _reference( if failing is not None: march = cast("HostDriver[Any]", driver)._low_storage assert march is not None - engine = march.engine - engine.step = _FailingStep(engine.step, failing) + engine = cast("Any", march.engine) + engine.trial = _FailingStep(engine.trial, failing) return HostSession(driver, problem, run_request, entrance(problem)) class _FailingStep: - """An engine step that raises after the step `failing` has made its passes.""" + """An engine trial that raises after the step `failing` has made its passes.""" def __init__(self, step: Any, failing: int) -> None: """Wrap the engine's step.""" From 8afa846538515e9ca61ab1e3343c159c3f3b88bf Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 04:23:21 +0000 Subject: [PATCH 04/14] refactor(numpy_ref): the session owns the schedule; HostDriver is deleted HostSession schedules the reference's runs and drives the marches directly: planes, step planes, halts, yields, the dense hold and observation (through the backend's dense output, applying the march's carrier rotations), periodic rows, the snapshot rows, the boundary monitor and transverse edge with the split collar's sums, the quadrature report and the load. Boundary warnings go into a sink and are reported as WARNING barrier events. NumpyRefBackend builds a fresh march per run and keeps lowering, prepare, metadata, the ledger, the probe and close. HostStepping, stepping() and the statistics storage hooks are removed. The scripted executor and the decision-trace harnesses host the real marches. numpy_ref is bitwise unchanged on the pinned corpus. Other tests are ported in the following commits. Co-Authored-By: Claude Opus 5.5 --- src/solprop/_helpers.py | 2 +- src/solprop/backends/adams_core.py | 2 +- src/solprop/backends/host/__init__.py | 12 +- src/solprop/backends/host/adams.py | 201 +- src/solprop/backends/host/driver.py | 1796 ----------------- src/solprop/backends/host/low_storage.py | 8 +- src/solprop/backends/host/marches.py | 37 +- src/solprop/backends/host/runge_kutta.py | 46 +- src/solprop/backends/host/session.py | 1685 ++++++++++++++-- src/solprop/backends/memory.py | 4 +- src/solprop/backends/numpy_ref/backend.py | 498 ++++- src/solprop/backends/numpy_ref/dense.py | 319 +++ src/solprop/backends/numpy_ref/engines.py | 80 +- src/solprop/backends/numpy_ref/multistep.py | 482 ++--- src/solprop/backends/numpy_ref/populations.py | 2 +- src/solprop/backends/populations.py | 2 +- src/solprop/backends/protocol.py | 247 +-- src/solprop/backends/rk_core.py | 2 +- src/solprop/backends/session_core.py | 10 +- src/solprop/backends/sessions.py | 3 +- src/solprop/driver/run.py | 6 +- src/solprop/driver/runner.py | 7 +- src/solprop/driver/session_loop.py | 20 +- src/solprop/monitor.py | 26 +- src/solprop/output/records.py | 5 +- src/solprop/stepper/multistep.py | 2 +- src/solprop/translate/stage.py | 6 +- src/solprop/transverse_monitor.py | 52 +- tests/backends/adams_traces.py | 76 +- tests/backends/rk_traces.py | 80 +- tests/builders.py | 41 +- tests/monitor_cases.py | 51 +- tests/scripted_driver.py | 99 +- tests/sessions/executors.py | 93 +- tests/sessions/runs.py | 2 +- tests/sessions/test_conformance.py | 45 +- tests/sessions/test_host_seams.py | 18 +- 37 files changed, 2976 insertions(+), 3091 deletions(-) delete mode 100644 src/solprop/backends/host/driver.py create mode 100644 src/solprop/backends/numpy_ref/dense.py diff --git a/src/solprop/_helpers.py b/src/solprop/_helpers.py index d6fdb2d49..cc3d9f188 100644 --- a/src/solprop/_helpers.py +++ b/src/solprop/_helpers.py @@ -15,7 +15,7 @@ to be installed: the NumPy reference must not run compiled code it exists to check, and one simulation must not change another's arithmetic. -A backend names its record in ``HostDriver.helpers`` and the shared driver, march and +A backend names its record in its ``helpers`` attribute and its session, march and engines pass it down: ``numpy_ref`` takes :data:`PLAIN`, the uncompiled Python forms; the native backend takes its own record of C++ bindings, defined in its package. Both perform the same IEEE operations in the same order, strict (no contraction, no diff --git a/src/solprop/backends/adams_core.py b/src/solprop/backends/adams_core.py index 483268add..1950d81cb 100644 --- a/src/solprop/backends/adams_core.py +++ b/src/solprop/backends/adams_core.py @@ -391,7 +391,7 @@ def carrier_capped( def quiet_capped(proposal: float, *, quiet: bool, interval: float | None) -> float: """Return the proposal, held to the monitor's interval while the collar rests. - The rule of ``solprop.backends.host.driver.HostDriver._quiet_capped``, with the + The rule of :meth:`solprop.backends.host.session.HostSession.cap`, with the collar's state and the monitor's interval passed in. Parameters diff --git a/src/solprop/backends/host/__init__.py b/src/solprop/backends/host/__init__.py index 7a3d7e8bb..7da74475d 100644 --- a/src/solprop/backends/host/__init__.py +++ b/src/solprop/backends/host/__init__.py @@ -4,11 +4,13 @@ """The NumPy reference's own host execution machinery (SEP 47 phase 2). -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`) and the reference's run session -(:mod:`~solprop.backends.host.session`). The reference shares only stateless +The stateful control of the reference's runs: the reference's run session +(:mod:`~solprop.backends.host.session`), which schedules a run and drives its march, +and the marches it drives -- the Runge-Kutta march +(:mod:`~solprop.backends.host.runge_kutta`), the Adams march +(:mod:`~solprop.backends.host.adams`) and the low-storage march +(:mod:`~solprop.backends.host.low_storage`) -- with what every march holds and asks +(:mod:`~solprop.backends.host.marches`). 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 e79683c08..2fa1246a8 100644 --- a/src/solprop/backends/host/adams.py +++ b/src/solprop/backends/host/adams.py @@ -22,6 +22,7 @@ from collections import deque from collections.abc import Callable, Iterator, Mapping from contextlib import contextmanager +from dataclasses import dataclass from typing import Any, cast import numpy as np @@ -37,7 +38,38 @@ from solprop.stepper.multistep import MarchPolicy, Multistep from solprop.stepper.schedule import FixedSchedule, landing, reached, replay_tolerance -__all__ = ["HostAdamsMarch"] +__all__ = ["AcceptedStep", "HostAdamsMarch"] + + +@dataclass(frozen=True, eq=False) +class AcceptedStep: + """The last accepted step, as the session's dense observation reads it. + + The counterpart of a native march call's ``step_z``, ``step_dz``, ``step_order``, + ``step_nodes`` and ``step_carrier``. Equality is by identity (``eq=False``) + because it holds an array. + + Attributes + ---------- + z : float + Where the step started, m. + dz : float + Its length, m. + order : int + Its order. + nodes : tuple of float + The history's normalised positions it read, newest first, ``order`` of them. + carrier : numpy.ndarray + Its trial's carrier rotations + (:meth:`~solprop.backends.engines.AdamsEngine.step_carrier`); empty without a + carrier frame. + """ + + z: float + dz: float + order: int + nodes: tuple[float, ...] + carrier: np.ndarray class HostAdamsMarch: @@ -46,10 +78,7 @@ class HostAdamsMarch: Parameters ---------- engine : solprop.backends.engines.AdamsEngine - The engine that holds the history's rows. Beside the protocol, the march's - dense observation calls its ``hold``, ``restore`` and ``observe``, a load its - ``reset``, and a snapshot its ``n_slots``, ``snapshot_rows``, - ``snapshot_nbytes`` and ``load_rows``; SEP 52 moves those to the session. + The engine that holds the history's rows. method : solprop.stepper.multistep.Multistep The method. host : solprop.backends.host.marches.MarchHost @@ -57,11 +86,13 @@ class HostAdamsMarch: policy : solprop.stepper.multistep.MarchPolicy Every number the controller and the landings read (SEP 39 section 4.2). field : callable - Returns the committed state, for a snapshot and a budget's error. + Returns the committed state, for a budget's error. schedule : solprop.stepper.schedule.FixedSchedule or None, optional The schedule to replay, or ``None`` to step adaptively. interpolate : bool, optional - Whether the run interpolates its planes (ADR-036, ADR-039). + Whether the run interpolates its planes (ADR-036, ADR-039): each accepted + step's record is then kept for the session's dense observation + (:attr:`last_step`). shape : tuple of int, optional The state's shape, which a snapshot's is checked against. proposal : float, optional @@ -77,6 +108,9 @@ class HostAdamsMarch: The march's position, proposal, cursor and accepted norms. ledger : solprop.backends.ledger.CallLedger The run's call counts. + last_step : AcceptedStep or None + The last accepted step of an interpolated run; ``None`` before one, and + always without interpolation. Raises ------ @@ -115,7 +149,9 @@ def __init__( self._rejections = 0 self._last_rejected = False self._order = 1 if method.variable_order else method.order - self._ahead: tuple[float, object] | None = None + # The engine's history rows: the method's order and two more. + self._n_slots = method.order + 2 + self.last_step: AcceptedStep | None = None self.ledger = CallLedger() # Whether the stages left a quiet collar out at the last attempt: the step # after it returns is held to the collar's stable step (`_collar_reentry`). @@ -124,11 +160,6 @@ def __init__( # recorded (`_propose`, `_reject`, `_raise_floor`). self._floor: ConvergenceError | None = None - @property - def holding(self) -> bool: # numpydoc ignore=RT01 - """Whether a dense observation holds the state at a plane, the march ahead.""" - return self._ahead is not None - def load(self, z: float, proposal: float, cursor: int) -> None: """Start a run afresh at a loaded position. @@ -154,8 +185,7 @@ def load(self, z: float, proposal: float, cursor: int) -> None: self._floor = None self._history = [] self._rejections = 0 - self._engine.reset() # pyright: ignore[reportAttributeAccessIssue] - self._ahead = None + self.last_step = None def restore_ledger(self, logical: Mapping[str, object]) -> None: """Continue a resumed run's cumulative call counts. @@ -168,77 +198,75 @@ def restore_ledger(self, logical: Mapping[str, object]) -> None: """ self.ledger = CallLedger.from_record(logical) - def snapshot(self) -> MarchSnapshot | None: - """Return the march's state at its accepted position, for a resume. + def snapshot_fields(self) -> dict[str, Any] | None: + """Return the march's part of a snapshot at its accepted position. + + The session adds the state and the engine's rows + (:class:`~solprop.output.records.MarchSnapshot`'s ``state`` and ``rows``). Returns ------- - solprop.output.records.MarchSnapshot or None - The snapshot, or ``None`` where there is nothing a resume could continue: - no history yet, or the march ahead of an interpolated observation. + dict or None + The snapshot's other fields, or ``None`` with no history to continue. """ - if not self._history or self._ahead is not None: + if not self._history: return None - export = self._engine.snapshot_rows # pyright: ignore[reportAttributeAccessIssue] state = self.state - return MarchSnapshot( - z=float(state.z), - state=np.array(self._field(), dtype=np.complex128, copy=True), - proposal=float(state.proposal), - method=repr(self._method), - order=int(self._order), - rejections=int(self._rejections), - last_rejected=bool(self._last_rejected), - positions=np.array([entry.z for entry in self._history], dtype=np.float64), - identities=tuple(entry.identity for entry in self._history), - slots=np.array([entry.row for entry in self._history], dtype=np.int64), - rows=export(), - collar_was_quiet=self._collar_was_quiet, - history_key=self._method.history_key, - ) + return { + "z": float(state.z), + "proposal": float(state.proposal), + "method": repr(self._method), + "order": int(self._order), + "rejections": int(self._rejections), + "last_rejected": bool(self._last_rejected), + "positions": np.array( + [entry.z for entry in self._history], dtype=np.float64 + ), + "identities": tuple(entry.identity for entry in self._history), + "slots": np.array([entry.row for entry in self._history], dtype=np.int64), + "collar_was_quiet": self._collar_was_quiet, + "history_key": self._method.history_key, + } + + @property + def in_flight(self) -> None: # numpydoc ignore=RT01 + """No step in flight: an Adams trial never overwrites the committed state.""" + return - def snapshot_nbytes(self) -> int | None: - """Return the bytes :meth:`snapshot` would copy, copying nothing. + @property + def has_history(self) -> bool: # numpydoc ignore=RT01 + """Whether the march holds a history a snapshot could continue.""" + return bool(self._history) + + def refusal(self, snapshot: MarchSnapshot) -> str | None: + """Return why a snapshot cannot continue this march, or ``None``. + + Parameters + ---------- + snapshot : solprop.output.records.MarchSnapshot + The snapshot, possibly read back from a file. Returns ------- - int or None - The state and every engine row, or ``None`` where :meth:`snapshot` returns - ``None``. + str or None + The reason, or ``None`` when it can. """ - if not self._history or self._ahead is not None: - return None - state = math.prod(self._shape) * np.dtype(np.complex128).itemsize - return state + self._engine.snapshot_nbytes() # pyright: ignore[reportAttributeAccessIssue] + return self._refusal(snapshot) - def load_snapshot(self, snapshot: MarchSnapshot) -> str | None: + def continue_from(self, snapshot: MarchSnapshot) -> None: """Continue from a snapshot taken where the march now stands. - The state was loaded at the snapshot's position; this installs the accepted - state exactly as it was held, the history, the order, the rejection count and - the proposed step, so that the march goes on as the uninterrupted one would - have. Nothing is changed when the snapshot cannot be used. + Installs the history, the order, the rejection count, the flags and the + proposed step, so that the march goes on as the uninterrupted one would have; + the session installs the state and the engine's rows, once :meth:`refusal` + found nothing. Parameters ---------- snapshot : solprop.output.records.MarchSnapshot - What :meth:`snapshot` returned, possibly read back from a file. - - Returns - ------- - str or None - ``None`` when the history was continued, otherwise why it starts afresh. + The snapshot. """ - reason = self._refusal(snapshot) - if reason is not None: - return reason - engine = cast("Any", self._engine) - try: - engine.load_rows(snapshot.rows, self._shape) - except BackendError as error: - return str(error) self.state.z = snapshot.z - engine.restore(snapshot.z, np.array(snapshot.state, copy=True)) self._history = [ HistoryEntry(float(z), cast("Any", identity), int(slot)) for z, identity, slot in zip( @@ -249,14 +277,12 @@ def load_snapshot(self, snapshot: MarchSnapshot) -> str | None: self._rejections = snapshot.rejections self._last_rejected = snapshot.last_rejected self._collar_was_quiet = snapshot.collar_was_quiet - self._ahead = None self.state.proposal = snapshot.proposal - return None def _refusal(self, snapshot: MarchSnapshot) -> str | None: """Return why a snapshot cannot continue this march, or ``None``.""" z = self.state.z - n_slots = cast("Any", self._engine).n_slots + n_slots = self._n_slots checks = ( ( snapshot.history_key != self._method.history_key, @@ -311,15 +337,7 @@ def march_to(self, target: float) -> None: ConvergenceError If the proposal falls below the contract's ``dz_min``. """ - host, state, engine = self._host, self.state, cast("Any", self._engine) - if self._ahead is not None: - # The march is ahead of the last observation; resume it there. - z, held = self._ahead - engine.restore(z, held) - state.z = z - self._ahead = None - if host.natural_stop_due(target): - return + host, state = self._host, self.state if self._schedule is not None: self._replay_to(self._schedule, target) return @@ -345,12 +363,6 @@ def march_to(self, target: float) -> None: host.stepped() if host.natural_stop(target): return - if self._interpolate and state.z > target: - observed = engine.observe(target) - self._ahead = (state.z, engine.hold()) - engine.restore(target, observed) - state.z = target - self.ledger.dense_observations += 1 def _replay_to(self, schedule: FixedSchedule, target: float) -> None: """Replay a prescribed schedule's steps to `target` (SEP 16 section 5). @@ -592,8 +604,7 @@ def _decide( z = self.state.z keep = self._history[-policy.order :] if policy.order else [] used = {entry.row for entry in keep} - n_slots = cast("Any", engine).n_slots - free = next(slot for slot in range(n_slots) if slot not in used) + free = next(slot for slot in range(self._n_slots) if slot not in used) with committing(): record = engine.accept(dz, free, stencil, keep) self._host.absorb(record) @@ -605,6 +616,16 @@ def _decide( order, dict(zip(stencil.orders, norms.tolist(), strict=True)), dz ) self._last_rejected = False + if self._interpolate: + # The step's record for the session's dense observation, its trial's + # carrier rotations among it (`adams_march.cpp`'s `step_carrier`). + self.last_step = AcceptedStep( + z=z, + dz=dz, + order=order, + nodes=tuple(stencil.nodes[:order]), + carrier=engine.step_carrier(order), + ) self._land(z, dz, landing) self._propose( dz, @@ -742,14 +763,8 @@ def end(self, outcome: AttemptOutcome) -> None: "begin_attempt", "end_attempt", "reading", - "n_slots", - "reset", - "hold", - "restore", - "observe", ) -"""What the march asks of an engine: the protocol, and the members that move to the -session with SEP 52's step 2.""" +"""What the march asks of an engine: the protocol.""" def _check_engine(engine: object) -> None: diff --git a/src/solprop/backends/host/driver.py b/src/solprop/backends/host/driver.py deleted file mode 100644 index 60cfc54ac..000000000 --- a/src/solprop/backends/host/driver.py +++ /dev/null @@ -1,1796 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""The reference's scheduler: planes, halts, records and the seam (SEP 47, SEP 52). - -:class:`HostDriver` schedules the reference's run: the save planes and step planes, -the halts and yields of its session, the step history, the periodic statistics rows, -the boundary monitor's and the transverse edge's checks, the noise load and the seam's -``set_initial``/``propagate_to``/``observe``. It computes nothing state-sized: the -state and its operations are a workspace's -(:class:`~solprop.backends.numpy_ref.workspace.NumpyWorkspace`), and each method's -march (:class:`~solprop.backends.host.runge_kutta.RungeKuttaMarch`, -:class:`~solprop.backends.host.adams.HostAdamsMarch`, -:class:`~solprop.backends.host.low_storage.HostLowStorageMarch`) holds its own -position, proposal and history, steps through its engine and asks the driver only -through the narrow :class:`~solprop.backends.host.marches.MarchHost`. A subclass -supplies the workspace, the engines and the marches. SEP 52 moves this scheduling into -the reference's session and deletes the driver. -""" - -import dataclasses -import logging -import math -import time -from abc import ABC -from collections.abc import Callable, Mapping, Sequence -from typing import TYPE_CHECKING, Protocol, TypeVar, cast - -import numpy as np -from jaxtyping import Complex, Float - -from solprop._helpers import PLAIN, Helpers -from solprop._interrupts import poll -from solprop._ownership import hold -from solprop.backends.engines import AcceptRecord, RungeKuttaEngine -from solprop.backends.host.marches import MarchState, in_flight_refusal -from solprop.backends.node_chunk import NodeChunkPlan, plan_node_chunk -from solprop.backends.protocol import ( - Backend, - BackendHistory, - Observation, - StepStats, - StepSummary, - TimingProbe, -) -from solprop.backends.records import collar_rests -from solprop.backends.session import ( - ExecutionOptions, - PreparedExecution, - Start, -) -from solprop.exceptions import BackendError, BoundaryError -from solprop.grid import TimeGrid -from solprop.log import NOT_ESTIMATED, NullReporter, ProgressReporter, StopFlag -from solprop.modes.protocol import Mode -from solprop.monitor import BoundaryEnergies, BoundaryMonitor -from solprop.noise import NoiseRealisation -from solprop.output.records import MarchSnapshot -from solprop.profiles import ZProfile -from solprop.stats import StatsSpec -from solprop.stepper.controller import ControlRecord -from solprop.stepper.low_storage import LowStorageRungeKutta -from solprop.stepper.schedule import ( - reached, - replay_tolerance, -) -from solprop.translate.modal import QUADRATURE_ALARM, warn_quadrature -from solprop.translate.plasma_source import plasma_source_record -from solprop.translate.problem import PropagationProblem, PropagatorMode -from solprop.translate.routes import transverse_of -from solprop.translate.run_request import RunRequest - -if TYPE_CHECKING: - from solprop.backends.host.adams import HostAdamsMarch - from solprop.backends.host.low_storage import HostLowStorageMarch - from solprop.backends.numpy_ref.engines import NumpyRungeKutta - from solprop.backends.numpy_ref.workspace import NumpyWorkspace - -__all__ = [ - "INITIAL_STEP_STATS_CAPACITY", - "HostDriver", - "reached", - "replay_tolerance", -] - -_StateT = TypeVar("_StateT") - - -INITIAL_STEP_STATS_CAPACITY = 64 -"""Rows a plane's statistics buffer holds before it first has to grow.""" - - -class _StepStatsBuffer: - """The rows a periodic statistics subset produces between two save planes. - - Grown by doubling from a preallocated block and **reset without releasing it**, so - that after the first plane a run allocates nothing per step: the capacity a plane - needed is the capacity the next plane starts with, which is a better estimator of a - plane's step count than anything the driver could predict. Growing the datasets by - concatenation on every step would be quadratic. - - The shape of each statistic is learnt from the first row rather than read from - :class:`solprop.stats.StatDefinition`, whose ``shape`` is a documentation string and - whose windowed entries depend on the spec's window count. - """ - - def __init__(self) -> None: - self._capacity = 0 - self._n_rows = 0 - self._z = np.zeros(0) - self._step = np.zeros(0, dtype=np.int64) - self._values: dict[str, np.ndarray] = {} - - def clear(self) -> None: - """Drop the rows and the allocation, as a fresh load does.""" - self.__init__() - - def reset(self) -> None: - """Forget the rows of the plane just finished, keeping the allocation.""" - self._n_rows = 0 - - def append(self, z: float, step: int, values: Mapping[str, np.ndarray]) -> None: - """Add one row. - - - ``z``: position the row was taken at, m. - - ``values``: what the backend's ``stats`` returned, keyed by name. - """ - if self._capacity == 0: - self._allocate(values) - elif self._n_rows == self._capacity: - self._grow() - index = self._n_rows - self._z[index] = z - self._step[index] = step - for name, value in values.items(): - row = self._values.get(name) - if row is None or np.shape(value) != row.shape[1:]: - expected = None if row is None else row.shape[1:] - msg = ( - f"the {name!r} statistic came back with shape " - f"{np.shape(value)} and this plane's rows are {expected}" - ) - raise BackendError(msg) - row[index] = value - self._n_rows = index + 1 - - def drain(self) -> StepStats: - """Return the rows as a frozen record and forget them. - - - Returns: copies, because the buffer is about to be written over, held so that - the record takes them without another. - """ - rows = self._n_rows - drained = StepStats( - z=hold(self._z[:rows].copy()), - step=hold(self._step[:rows].copy()), - values={ - name: hold(value[:rows].copy()) for name, value in self._values.items() - }, - ) - self.reset() - return drained - - def _allocate(self, values: Mapping[str, np.ndarray]) -> None: - """Lay the block out from the first row's shapes. - - - ``values``: the first row, whose shapes every later row of this plane must - match. - """ - self._capacity = INITIAL_STEP_STATS_CAPACITY - self._z = np.zeros(self._capacity) - self._step = np.zeros(self._capacity, dtype=np.int64) - self._values = { - name: np.zeros((self._capacity, *np.shape(value)), dtype=np.float64) - for name, value in values.items() - } - - def _grow(self) -> None: - """Double the block, copying what is in it.""" - self._capacity *= 2 - self._z = np.resize(self._z, self._capacity) - self._step = np.resize(self._step, self._capacity) - self._values = { - name: np.concatenate([value, np.zeros_like(value)]) - for name, value in self._values.items() - } - - -class _TrialProbe: - """Single trials of a loaded :class:`HostDriver`, committing nothing (SEP 47 6.6). - - The :class:`solprop.backends.protocol.TimingProbe` this driver returns. A - Runge-Kutta trial (the driver's Runge-Kutta engine) leaves the loaded state, the - position and the history alone. The low-storage march has no separate trial: its - step advances the discarded registers in place and leaves no trial field. - - - ``start``: the loaded position, m, and the replayed itinerary's index there. - """ - - def __init__( - self, - driver: "HostDriver[object]", - start: tuple[float, int], - ) -> None: - """Hold the loaded driver; no trial is taken yet.""" - self._driver = driver - self._z, self._index = start - self._length: float | None = None - - def trial(self, z: float | None = None, dz: float | None = None) -> None: - """Take one trial step and keep its end state for :meth:`field`. - - - ``z``: where the trial starts, m; the loaded position by default. - - ``dz``: its length, m, positive; the problem's ``dz_init`` by default, or the - scheduled step at the loaded position for the low-storage march. - """ - driver = self._driver - start = self._z if z is None else float(z) - march = driver._low_storage - if march is not None: - schedule = driver._stepper.schedule - assert schedule is not None # the translation refuses the march without one - index = min(self._index, schedule.n_steps - 1) - length = float(schedule.steps[index]) if dz is None else float(dz) - cast("RungeKuttaEngine", march.engine).trial(start, length) - return - length = float(driver._stepper.dz_init) if dz is None else float(dz) - driver._runge_kutta_engine.trial(start, length) - self._length = length - - def field(self) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: - """Return the last trial's end state on the host, as a kept step would be. - - The trial's state after the accepted-step boundary treatments (the band mask, - and the split-step absorber where it runs). A trial is held beside the loaded - state, so finishing it leaves the loaded state alone, and no monitor is bound, - so the finish takes no split sums. - - - Returns: an owning copy, internal units and the FFT convention, shape - ``(n_modes, n_pol, n_omega)``. - """ - driver = self._driver - if driver._low_storage is not None: - msg = ( - "the low-storage march accepts its step in place and has no trial " - "field to read back" - ) - raise BackendError(msg) - if self._length is None: - raise BackendError("take a trial before reading its field") - engine = driver._runge_kutta_engine - finished, _ = driver._workspace.finish(engine.trial_state, self._length) - self._length = None - return np.array(finished) - - -class _SessionHooks: - """The driver as its marches' :class:`~solprop.backends.host.marches.MarchHost`. - - The narrow calls a march makes of the session that schedules it, forwarded to the - driver's own bookkeeping, so that no march reads or writes the driver's fields. - """ - - def __init__(self, driver: "HostDriver[object]") -> None: - self._driver = driver - - @property - def collar_quiet(self) -> bool: - """Whether the stages leave a quiet in-stage temporal collar out.""" - return self._driver._collar_quiet - - def poll_stop(self) -> None: - """Raise when the run's stop flag is set.""" - self._driver._poll_stop() - - def cap(self, proposal: float, z: float) -> float: - """Hold a proposal to the quiet collar's, the edge's and the split's limits.""" - driver = self._driver - return driver._split_capped( - driver._transverse_capped(driver._quiet_capped(proposal), z) - ) - - def record(self, end: float, dz: float, norm: float, accepted: bool) -> None: - """Record one attempt.""" - self._driver._record(end, dz, norm, accepted) - - def absorb(self, record: AcceptRecord) -> None: - """Accumulate an accepted step's split collar's sums.""" - self._driver._absorb(record) - - def stepped(self) -> None: - """Account the step just committed.""" - self._driver._take_step_stats() - - def natural_stop(self, target: float) -> bool: - """Count an accepted step; return whether to stop at its end.""" - return self._driver._natural_stop(target) - - def natural_stop_due(self, target: float) -> bool: - """Return whether the march returns where it stands.""" - return self._driver._natural_stop_due(target) - - -class _March(Protocol): - """What the driver asks of whichever march its run steps with.""" - - state: MarchState - - @property - def holding(self) -> bool: ... - - def load(self, z: float, proposal: float, cursor: int) -> None: ... - - def advance(self, target: float) -> None: ... - - -class HostDriver[_StateT](ABC): # noqa: UP049 - the protected state type is private - """The reference's scheduler, with the workspace and the marches left to a subclass. - - A subclass supplies the workspace (``_workspace``), the Runge-Kutta engine the - timing probe uses (``_runge_kutta_engine``) and the march its run steps with - (``_march``, with ``_adams`` or ``_low_storage`` set when it is that march), each - march reporting to the driver's hooks (``_hooks``). The driver gives them the whole - of :class:`solprop.backends.protocol.Backend`'s marching behaviour: the save planes - and step planes, the halts and yields, the step history, the statistics rows, the - boundary monitor and the transverse edge, and both noise models' loads. - - Parameters - ---------- - problem : solprop.translate.problem.PropagationProblem - The validated problem to step. The subclass refuses what it cannot execute - before calling this constructor. - request : solprop.translate.run_request.RunRequest - The run's policies: the method, the error control, the itinerary, the planes - and the statistics (SEP 47 section 5.2). The subclass checks it with the - problem (:func:`solprop.translate.problem.validate_run`) before calling this - constructor; a session started on this backend serves a request that differs - from it only in one run's start, retention, monitor and history - (:meth:`~solprop.translate.run_request.RunRequest.for_run`). - grid : solprop.grid.TimeGrid, optional - The grid the state lives on, which the statistics need and the contract does not - carry. - modes : collections.abc.Sequence, optional - The propagated modes, in state order, for the statistics that need them. - profiles : collections.abc.Mapping, optional - The z-profiles keyed by statistic name. - options : solprop.backends.session.ExecutionOptions, optional - The run's execution options: an explicit node budget or an exact node chunk, - from which the node chunk is planned here, before anything is allocated - (:func:`solprop.backends.node_chunk.plan_node_chunk`). ``None`` for the - automatic choice. - - Attributes - ---------- - name : str - The registry name, set by the subclass and used in every log line. - 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 - that takes both signs from a single ``exp`` and ``sincos`` overrides it. - helpers : solprop._helpers.Helpers - The implementation of the per-stage and per-step scalar evaluations -- the - stage tables' Clenshaw rows and the Adams basis -- which the driver, march and - engines pass down rather than choosing one (SEP 29 section 6.6): ``PLAIN``, the - uncompiled forms, for the NumPy reference. - """ - - name: str = "driver" - propagator_default: PropagatorMode = "tabulate" - helpers: Helpers = PLAIN - - def __init__( - self, - problem: PropagationProblem, - request: RunRequest, - *, - grid: TimeGrid | None = None, - modes: Sequence[Mode] | None = None, - profiles: Mapping[str, ZProfile] | None = None, - options: ExecutionOptions | None = None, - ) -> None: - """Adopt a validated problem and request and start the run at the entrance.""" - self._problem = problem - self._request = request - # The stepping policy as one record, read by the march at every step. - self._stepper = request.stepper - # SEP 47 section 6.5: the node chunk is an execution choice, planned from the - # problem and the options. - self._options = ExecutionOptions() if options is None else options - self._chunk_plan: NodeChunkPlan = plan_node_chunk(problem, self._options) - self._adams: HostAdamsMarch | None = None - # The low-storage march (SEP 24), set at construction by a backend that - # executes it; its engine owns the flag of a step left in flight. - self._low_storage: HostLowStorageMarch | None = None - self._grid = grid - self._modes = modes - self._profiles = profiles - self._logger = logging.getLogger(type(self).__module__) - self._closed = False - # The marches' narrow view of the driver (SEP 52 section 5.2). - self._hooks = _SessionHooks(cast("HostDriver[object]", self)) - # Whether the plane's quadrature alarm was reported (warned once per plane). - self._alarm_reported = False - # Natural-step saving (SEP 14 phase 3): accepted steps since the load, and - # whether a step that crossed a densely observed plane ends on a step to save. - self._natural_count = 0 - self._natural_due = False - self._halt_ahead = False - self._halt_requested = False - self._halt_check: Callable[[], bool] | None = None - self._halted = False - self._history: list[tuple[float, float, float, bool, float]] = [] - self._clock = time.perf_counter() - self._progress: ProgressReporter = NullReporter() - self._progress_started = False - # The statistics channel between planes. The spec a row is evaluated with is - # the periodic subset promoted to `names`, so the row goes through the very - # same `stats` the save planes use and is bitwise what a plane would record. - spec = request.observation.stats - self._row_spec: StatsSpec | None = ( - None - if not spec.periodic - else dataclasses.replace(spec, names=spec.periodic, periodic=(), period=1) - ) - self._row_period = spec.period - self._accepted_steps = 0 - self._rows = _StepStatsBuffer() - - # --- what a subclass supplies ----------------------------------------------- - - _workspace: "NumpyWorkspace" - """The state and every state-sized operation on it.""" - - _runge_kutta_engine: "NumpyRungeKutta" - """The Runge-Kutta engine: the Runge-Kutta march's and the timing probe's.""" - - _march: _March - """The march the run steps with.""" - - @property - def _z(self) -> float: - """Return the march's position, m.""" - return self._march.state.z - - @property - def _proposal(self) -> float: - """Return the march's proposal, m.""" - return self._march.state.proposal - - @property - def _schedule_index(self) -> int: - """Return the march's replay cursor.""" - return self._march.state.cursor - - def stats(self, spec: StatsSpec) -> dict[str, np.ndarray]: - """Compute the requested statistics of the state in one fused pass. - - Called by the session at a plane and by the step loop's row storage, at the - march's position. - - Parameters - ---------- - spec : solprop.stats.StatsSpec - Which statistics and which windows. - - Returns - ------- - dict - Small host arrays keyed by statistic name. - """ - self._require_state() - return self._workspace.stats(spec, self._z) - - def _on_accepted_step(self) -> None: - """Score whatever an accepted step leaves behind, before the next is proposed. - - The quadrature alarm is scored here, from buffers the last stage left behind, - and a value above :data:`~solprop.translate.modal.QUADRATURE_ALARM` is - reported once per plane. It is a statistic and a warning, never a controller - input. - """ - value, z = self._workspace.score_quadrature() - if value > QUADRATURE_ALARM and not self._alarm_reported: - self._alarm_reported = True - warn_quadrature(value, z) - - def _reset_step_stats(self, *, release: bool) -> None: - """Discard periodic rows at a load or at the start of a plane. - - - ``release``: true for a new load, which releases the old storage; false for - a new plane, which retains capacity. The accepted-step period is the - march's and is unaffected. - """ - if release: - self._rows.clear() - else: - self._rows.reset() - - def _record_step_stats(self, spec: StatsSpec, z: float, step: int) -> None: - """Evaluate and retain one selected accepted-step statistics row. - - Called after boundary treatments and after the state and position have been - committed. A device override must retain the values without copying them to - the host, using the same evaluator as :meth:`stats`. - - - ``z``: position of the committed state, m. - - ``step``: the attempt's index in the history since the previous observation, - rejected attempts included; supplied by the march, not inferred from rows. - """ - self._rows.append(z, step, self.stats(spec)) - - def _drain_step_stats(self) -> StepStats: - """Return owning host rows at observation and retain reusable capacity. - - A device override copies the packed values once here. Repeated drains return - no rows until more are recorded. - """ - return self._rows.drain() - - @property - def _propagator_mode(self) -> PropagatorMode: - """Return the propagator mode this run actually uses. - - - Returns: ``"tabulate"`` or ``"recompute"``, with the contract's ``"auto"`` - resolved to :attr:`propagator_default`. - """ - asked = self._stepper.propagator_mode - if asked == "auto" and isinstance( - self._stepper.integrator, LowStorageRungeKutta - ): - # One volume of exp(h D / 2) reused while the step holds is the cheaper - # flow on a CPU; a varying operator changes it every step (SEP 24 - # section 4.3). - return "tabulate" if self._problem.flags.constant_linop else "recompute" - if asked == "auto" and self._problem.linear.separable is not None: - return "recompute" - return self.propagator_default if asked == "auto" else asked - - def prepare( - self, problem: PropagationProblem, request: RunRequest - ) -> PreparedExecution: - """Prepare a run of this backend for one problem and request (SEP 47 5.2). - - The backend lowered the method, the error control, the itinerary, the planes - and the statistics where it was built; preparing binds the problem and the - request a run serves -- this backend's own, or one run's adaptation of it - (:meth:`~solprop.translate.run_request.RunRequest.for_run`) -- and each start - of the result opens the reference's own session - (:class:`~solprop.backends.host.session.HostSession`). - - Parameters - ---------- - problem : solprop.translate.problem.PropagationProblem - The translated problem: this backend's, or one derived from it with - another input (:func:`solprop.driver.runner.check_derived_problem`). - request : solprop.translate.run_request.RunRequest - The run's request. - - Returns - ------- - solprop.backends.session.PreparedExecution - The prepared execution. - """ - from solprop.backends.host.session import ( # noqa: PLC0415 - it builds on this module - HostPrepared, - ) - - # 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 protocol check can refuse a driver without. - return HostPrepared(cast("Backend", self), problem, request) - - @property - def request(self) -> RunRequest: # numpydoc ignore=RT01 - """Request this backend was built for. - - Its method, error control, itinerary, planes and statistics; a run adapts - it with :meth:`~solprop.translate.run_request.RunRequest.for_run`. - """ - return self._request - - @property - def node_chunk(self) -> int: # numpydoc ignore=RT01 - """The nodes a response pass of this backend holds at once. - - The planned chunk (:attr:`chunk_plan`). - """ - return self._chunk_plan.chunk - - @property - def chunk_plan(self) -> NodeChunkPlan: # numpydoc ignore=RT01 - """Node-chunk plan and what chose it.""" - return self._chunk_plan - - def available_device_memory(self) -> int | None: - """Return None for host execution; device backends report free bytes. - - Returns - ------- - int or None - None for the shared host implementation. - """ - return None - - def metadata(self) -> dict[str, object]: - """Return what this execution was, for the run's record. - - A saved run has to say what produced it: the thread configuration alone was - measured to move one step by a factor of nine, so a result whose execution is - not recorded is not reproducible. The base record is the name and the resolved - propagator mode and, for Adams runs, cumulative logical source calls; the - low-storage march's evaluations are physical, ``source_evaluations``, never - ``response_calls`` (SEP 24 section 5); a backend with pools, plans or wisdom - adds them. - - Returns - ------- - dict - JSON-serialisable scalars, keyed by name. - """ - record: dict[str, object] = { - "backend": self.name, - "propagator_mode": self._propagator_mode, - # SEP 47 section 4.3: execution metadata, outside the resume key. - **self._chunk_plan.record(), - "node_chunk": self.node_chunk, - } - if self._problem.responses.plasma_channels: - record["plasma_source"] = plasma_source_record(self._problem.grids) - if self._adams is not None: - record["response_calls"] = self._adams.ledger.to_record() - if self._low_storage is not None: - record["source_evaluations"] = self._low_storage.source_evaluations - elif self._adams is None: - record["source_evaluations"] = self._runge_kutta_engine.evaluations - if self._monitor is not None: - record["boundary_monitor"] = self._monitor.summary() - return record - - def march_snapshot(self) -> MarchSnapshot | None: - """Return the Adams march's state at the accepted position, for a resume. - - Returns - ------- - solprop.output.records.MarchSnapshot or None - The snapshot, or ``None`` for the Runge-Kutta and low-storage marches and - wherever the Adams march has nothing a resume could continue - (:meth:`solprop.backends.host.adams.HostAdamsMarch.snapshot`). - - Raises - ------ - BackendError - If a low-storage step was abandoned in flight. - """ - self._refuse_in_flight() - if self._low_storage is not None: - return self._low_storage.snapshot() - return None if self._adams is None else self._adams.snapshot() - - def march_snapshot_nbytes(self, z: float) -> int | None: - """Return the bytes :meth:`march_snapshot` would copy at `z`, copying nothing. - - Parameters - ---------- - z : float - The position the snapshot is wanted at, m. - - Returns - ------- - int or None - The state and every engine row, or ``None`` where a snapshot would be - ``None`` or stand somewhere other than `z`. - - Raises - ------ - BackendError - If a low-storage step was abandoned in flight. - """ - self._refuse_in_flight() - if self._low_storage is not None or self._adams is None or self._z != z: - return None - return self._adams.snapshot_nbytes() - - def march_export_refusal(self) -> str | None: - """Return ``None``: every march the reference admits carries its history. - - Returns - ------- - None - The Adams engines export and install their rows; the Runge-Kutta and - low-storage marches keep none. - """ - return None - - def restore_march(self, snapshot: MarchSnapshot) -> str | None: - """Continue the Adams march from a snapshot at the loaded position. - - Called after :meth:`set_initial` at the snapshot's position. The state is - replaced by the snapshot's own, exactly as the interrupted run held it. - - Parameters - ---------- - snapshot : solprop.output.records.MarchSnapshot - The snapshot a file holds. - - Returns - ------- - str or None - ``None`` when the history was continued, otherwise why the march starts - afresh, as a resume did before snapshots were kept. - """ - if self._adams is None: - march = "low-storage" if self._low_storage is not None else "Runge-Kutta" - return f"the run steps with the {march} march, which keeps no history" - return self._adams.load_snapshot(snapshot) - - def restore_call_ledgers( - self, logical: Mapping[str, object], atomic: Mapping[str, object] | None = None - ) -> None: - """Restore shared Adams call counts without restoring numerical history. - - Non-TDSE backends inherit logical budget persistence while refusing atomic - counts. The caller first loads the saved field, which resets Adams history; - the next source evaluation charges startup against these cumulative counts. A - Runge-Kutta or low-storage march keeps no logical ledger, so nothing is - installed for it. - - Parameters - ---------- - logical : mapping - Persisted logical response counts; empty on ordinary RK runs. - atomic : mapping or None, optional - Persisted atomic counts; absent on non-TDSE runs. - - Raises - ------ - BackendError - If this backend is handed counters it does not implement. - """ - if atomic: - raise BackendError( - f"{self.name} does not restore atomic response call ledgers" - ) - if logical and self._adams is not None: - self._adams.restore_ledger(logical) - - # --- the per-stage bundle ------------------------------------------------------ - - # --- the seam ---------------------------------------------------------------- - - def set_initial( - self, - field: Complex[np.ndarray, "n_modes n_pol n_omega"], - noise: NoiseRealisation | None, - *, - z: float = 0.0, - resume: bool = False, - ) -> None: - """Load a state and the noise realisation at a position. - - The state is masked to the active band once here, as the scaffold does: the - operator and the prefactor are exactly zero outside it, so out-of-band content - would neither propagate nor decay and would sit in the error norm for the whole - run. The traditional ``input`` noise model adds its realisation to the - state at the run's launch position and never again; the ``modified`` model keeps - it apart and adds it at every stage, so the propagating field never carries it. - - A **resume** loads a state from a plane the run already saved, so it already - carries whatever the ``input`` model added at the launch and must not be given a - second realisation, and a replayed schedule continues from the edge that plane - sits on. A `z` past the launch is always one. Position cannot tell for a file - holding only its launch plane, which comes back at the launch itself: its caller - says so with `resume`. The launch is the entrance unless the run starts inside - the guide (SEP 37: an interior launch with ``input`` noise takes its draw - there). The controller starts afresh from ``dz_init`` either way - (``docs/dev/stepper.md`` section 3). - - Everything else a march reads is restored too, so that a backend loaded again - after a run -- a :class:`~solprop.driver.runner.SimulationRunner`'s, or - after a failed run -- repeats a fresh backend's run (SEP 22 section 4.7): a - dense observation's look-ahead, an Adams march's call ledger and last-rejection - flag, a low-storage march's source-evaluation count and the boundary monitor, - with the collar it may have rested, here, and the quadrature alarm, whose value - the entrance plane's ``quadrature_error`` reads before any march, in the - overrides of the backends that keep one. A resume restores its - ledger afterwards (:meth:`restore_call_ledgers`). - - Loading is the one entry that clears a low-storage step abandoned in flight - (SEP 24 section 6.2): the state it holds is replaced, and the march's flow - table is rebuilt from the next step. - - Parameters - ---------- - field : numpy.ndarray - The state in the canonical layout, complex, shape - ``(n_modes, n_pol, n_omega)``, in the square root of watts and the FFT - convention. - noise : solprop.noise.NoiseRealisation or None - The realisation to carry along the run, or ``None`` to take the one the - problem was assembled with. - z : float, optional - The position the state belongs to, m. Zero, the entrance, by default. - resume : bool, optional - Whether `field` came back from a saved plane of this run, and so never takes - the ``input`` draw, whatever `z`. ``False`` by default. - - Raises - ------ - BackendError - If the backend is closed, the field does not match the contract's shape, - `z` lies outside the operator table, or a schedule is being replayed and `z` - is not one of its edges. - """ - self._check_open() - values = np.ascontiguousarray(field, dtype=np.complex128) - if values.shape != self._problem.shape: - msg = ( - f"the initial state has shape {values.shape}, expected " - f"{self._problem.shape} from the contract" - ) - raise BackendError(msg) - position = self._checked_position(float(z)) - cursor = self._schedule_index_at(position) - self._workspace.load(values, noise, z=position, resume=resume) - # The march starts afresh: its position, proposal, cursor and norms, and the - # rest of what it reads, as a fresh backend holds it (SEP 22 4.7) -- a dense - # observation's look-ahead, an Adams march's ledger and last-rejection flag, - # a low-storage march's count and a step it left in flight. - self._march.load(position, self._stepper.dz_init, cursor) - self._alarm_reported = False - self._history = [] - self._natural_count = 0 - self._natural_due = False - self._halt_ahead = False - self._halt_requested = False - self._halt_check = None - self._clock = time.perf_counter() - # A resume is a second run for a reporter's purposes: it starts from a different - # z and its own clock, so the next plane announces itself afresh. - self._progress_started = False - # The period counts from the load, so a resumed run's rows are not the - # uninterrupted run's rows unless each plane's accepted-step count is a - # multiple of the period. Said in `docs/guide/results/statistics.md`. - self._accepted_steps = 0 - self._reset_step_stats(release=True) - # A boundary monitor watches one run: the next attaches its own or none, and - # a collar the last one rested goes back into the stages (SEP 21). - self._monitor = None - self._bind_monitor(None) - self._set_collar_quiet(False) - - def set_progress(self, reporter: ProgressReporter) -> None: - """Attach the reporter every attempted step is reported to. - - The next call to :meth:`propagate_to` announces the run to it. Attaching a - reporter changes nothing the propagation computes -- the calls are observers, - made after the step is decided -- so a run with one is bitwise the run without. - - Parameters - ---------- - reporter : solprop.log.ProgressReporter - Where the step events go; :class:`solprop.log.NullReporter` turns them off. - """ - self._progress = reporter - self._progress_started = False - - _stop: StopFlag | None = None - """The flag the march polls (:meth:`set_stop`); ``None`` by default.""" - - def set_stop(self, flag: StopFlag | None) -> None: - """Attach the flag the march polls, or detach it with ``None``. - - A run polls its own flag before each trial (SEP 41, S17), where the state is - the last accepted one, so a stop abandons nothing but the trial not yet taken. - Polling changes nothing the propagation computes. - - Parameters - ---------- - flag : solprop.log.StopFlag or None - Any object with an ``is_set()`` method, such as a - :class:`threading.Event`. - """ - self._stop = flag - - def _poll_stop(self) -> None: - """Raise when the run's stop flag is set; called before every trial or call.""" - poll(self._stop) - - def propagate_to(self, z: float) -> StepSummary: - """Step the state to a position, landing on it exactly. - - Adaptive by default and a replay when the contract carries a schedule. Either - way the embedded estimate is computed and recorded every step, so a schedule too - coarse for the tolerance it is scaled by is reported rather than silent - (``docs/dev/stepper.md`` section 8). The low-storage march has no estimate: it - replays its schedule and records 0.0, "not estimated" (SEP 24 section 6.3). - - Parameters - ---------- - z : float - The save plane to reach, m, at or ahead of the current position and inside - the operator table. - - Returns - ------- - StepSummary - What the call cost and achieved. - - Raises - ------ - BackendError - If the backend is closed, no initial state was loaded, a low-storage step - was abandoned in flight, or ``z`` is behind the current position or outside - the table. - ConvergenceError - If the controller asks for a step below the contract's ``dz_min``, or a - replayed step's error norm, or the low-storage march's state, is not - finite. - """ - self._require_state() - target = float(z) - self._check_target(target) - # `started` is announced here rather than from `set_initial`, because the driver - # attaches the reporter after the state is loaded and because this is the first - # moment at which the run is actually about to cost anything. - if not self._progress_started: - self._progress_started = True - settings = self._stepper - self._progress.started(self._z, settings.z_end, len(settings.save_planes)) - started = time.perf_counter() - first = len(self._history) - # Beside `_begin_plane` and not inside it: neither backend's override calls - # `super()`, so a base-class body there would silently do nothing. - if not self._halted: - # A call resuming after a halt short of its target continues the same - # plane: its rows and per-plane latches carry on (SEP 47 section 5.1). - self._reset_step_stats(release=False) - self._begin_plane() - self._halted = False - # Each march replays a schedule or steps adaptively itself; the low-storage - # march replays only (SEP 24). - self._march.advance(target) - if self._natural_due and reached(self._z, target) and not self._march.holding: - # The step owed as a step plane ends on the target itself, whose plane - # observes it: it is not observed a second time there (`_natural_stop`). - self._natural_due = False - taken = self._history[first:] - record = ControlRecord.from_norms( - self._stepper.controller, - [entry[2] for entry in taken if entry[3]], - n_rejected=sum(1 for entry in taken if not entry[3]), - ) - if not record.met_tolerance: - self._logger.warning( - "%s: a step was too coarse for the tolerance it is scaled by on the " - "way to %.6e m; the largest scaled error norm was %.3e against the " - "requested 1.0 (rtol %.1e)", - self.name, - target, - record.max_norm, - record.requested_rtol, - ) - self._logger.debug( - "%s: reached %.6e m in %d steps (%d rejected), achieved/requested " - "tolerance ratio %s", - self.name, - self._z, - record.n_accepted + record.n_rejected, - record.n_rejected, - # 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}", - ) - if not self._halted: - # A halt short of the target is no plane (SEP 47): no plane check there. - self._monitor_plane() - return StepSummary( - z=self._z, - n_steps=len(taken), - n_rejected=record.n_rejected, - max_norm=record.max_norm, - mean_norm=record.mean_norm, - wall_time=time.perf_counter() - started, - met_tolerance=record.met_tolerance, - ) - - def observe(self, *, field: bool = True) -> Observation: - """Return the state at the current position, as host arrays. - - The field is in the lab frame and the **FFT convention** - (``spectral_convention = "fft"``): the output layer conjugates it on the way to - disk and the processing accessors on the way to a user. The step - history covers everything since the previous call. - - With ``field=False`` (SEP 22 section 5.1) neither the field nor the noise phase - crosses to the host -- a device backend copies nothing -- and the observation - carries ``None`` for both. Nothing scans the field for finiteness then: the - step loop accepts only finite error norms and a replay raises on a non-finite - one. The spatial collar diagnostic, which reads the field, is not evaluated; - the backend counts such planes in :meth:`metadata` and logs the first. - - Parameters - ---------- - field : bool, optional - Whether the field and the noise phase cross to the host. Default ``True``. - - Returns - ------- - Observation - The field, the noise phase and the step history. - - Raises - ------ - BackendError - If the backend is closed or no initial state was loaded. - """ - state = self._require_state() - history = _history_record(self._history) - whole = cast("np.ndarray", state) if field else None - if whole is not None: - # The state itself, frozen as an observed array always was so that the - # next step replaces it rather than accepting in place, and held, so the - # observation takes a view of it without a copy. A state that only views - # memory the march owns is frozen but not held, and the observation copies - # it. - hold(whole) - plane = Observation( - z=self._z, - field=whole, - noise_phase=self._workspace.noise_phase(self._z) if field else None, - step_history=history, - n_steps=history.n_steps, - n_rejected=history.n_rejected, - step_stats=self._drain_step_stats(), - ) - self._history = [] - self._clock = time.perf_counter() - return plane - - @property - def in_flight(self) -> tuple[float, float] | None: # numpydoc ignore=RT01 - """Low-storage step a failure abandoned in flight, or ``None``. - - The step's start and length, m, while the state is neither of its ends - (``solprop.backends.low_storage``). - """ - return self._abandoned() - - def _abandoned(self) -> tuple[float, float] | None: - """Return the step a failure left in flight, or ``None``: the march's.""" - return None if self._low_storage is None else self._low_storage.in_flight - - @property - def position(self) -> float: # numpydoc ignore=RT01 - """Where the march stands, m. - - 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) - - @property - def halted(self) -> bool: # numpydoc ignore=RT01 - """Whether the last march stopped at a requested halt short of its end. - - True while the halt latch of :meth:`request_halt` or the yield check of - :meth:`set_halt_check` stopped it. - """ - return self._halted - - @property - def holding_plane(self) -> bool: # numpydoc ignore=RT01 - """Whether a dense observation holds the state between endpoints. - - True while the march's dense observation holds an interpolated plane, the - march ahead of it. - """ - return self._march.holding - - def drain_attempts(self) -> Observation: - """Drain the attempts recorded since the last observation, with no field. - - For a state left in flight, which :meth:`observe` refuses: the attempts and - periodic rows recorded before the abandoned step, drained once, as an - observation drains them. - - Returns - ------- - solprop.backends.protocol.Observation - The attempts and rows at :attr:`position`, with no field. - """ - entries, self._history = self._history, [] - history = _history_record(entries) - return Observation( - z=self.position, - field=None, - noise_phase=None, - step_history=history, - n_steps=history.n_steps, - n_rejected=history.n_rejected, - step_stats=self._drain_step_stats(), - ) - - def timing_probe(self, start: Start) -> TimingProbe: - """Load a start and return single trials of this run's march from it. - - The start's field, noise, position and resume flag are loaded as by - :meth:`set_initial`; its method history, ledgers and monitor continuation are - not read. A Runge-Kutta trial leaves the loaded state alone; a low-storage - march's step advances the discarded registers in place, so a backend probed so - is closed afterwards (SEP 47 section 6.6). - - Parameters - ---------- - start : solprop.backends.session.Start - Where the trials start; its field is taken. - - Returns - ------- - solprop.backends.protocol.TimingProbe - The probe. - """ - self.set_initial( - np.asarray(start.take_field()), - start.noise, - z=float(start.z), - resume=start.resume, - ) - return _TrialProbe( - cast("HostDriver[object]", self), - (float(start.z), self._schedule_index), - ) - - # --- the step loop ------------------------------------------------------------- - - def _begin_plane(self) -> None: - """Reset whatever describes only the steps of the plane about to be taken. - - The quadrature alarm and its latch, so that each plane reports its own. - """ - self._workspace.reset_quadrature() - self._alarm_reported = False - - def _natural_stop(self, target: float) -> bool: - """Count an accepted step; return whether to stop at its end to save it. - - With ``step_planes = k`` the end of every ``k``-th accepted step since the load - is saved as a plane (SEP 14 phase 3): ``propagate_to`` returns there, short of - its target, and the driver calls it again. A step that lands on the target is - saved as the target; one that crosses a densely observed target is saved after - it, when the next call finds the stop due (:meth:`_natural_stop_due`). - - - ``target``: the position the call is stepping to, m. - """ - every = self._stepper.step_planes - self._natural_count += 1 - if every == 0 or self._natural_count % every: - return self._halted_short(target) - if reached(self._z, target): - self._natural_due = not reached(target, self._z) - return False - return True - - def request_halt(self) -> None: - """Stop the march at the next accepted endpoint short of its target. - - The execution session's snapshot latch (SEP 47 section 5.5): ``propagate_to`` - returns at the end of the next accepted step, as at a natural stop, without - counting it as one, so the session can service a snapshot there. An endpoint on - the target itself is observed as the plane, and the latch stays set for the - session to find. - """ - self._halt_requested = True - - def clear_halt(self) -> None: - """Withdraw a halt requested with :meth:`request_halt`, once it is serviced.""" - self._halt_requested = False - - def halt_ahead(self) -> None: - """Halt the next march at the endpoint a dense observation held, if short. - - The execution session's snapshot latch beside interpolated planes (SEP 47 - section 5.5): the march stands ahead of the plane it observed, at the end of - the step that crossed it. When the next march restores that endpoint and the - latch is set, it returns there at once, unless a step plane is owed there - first or the target is another plane the step crossed, so that the snapshot is - taken at that endpoint rather than wait for a step that crosses no plane. - """ - self._halt_ahead = True - - def set_halt_check(self, check: Callable[[], bool] | None) -> None: - """Ask `check` at every accepted endpoint whether to halt there. - - The execution session's bounded yield (SEP 47 section 5.1): when `check` - returns True the halt latch of :meth:`request_halt` is set, so the march - returns at that endpoint. It is asked only at safe boundaries and changes - nothing the march computes. - - Parameters - ---------- - check : callable or None - Returns whether a yield is due; ``None`` asks nothing. - """ - self._halt_check = check - - def poll_halt(self) -> None: - """Latch a halt when the yield check says one is due.""" - check = self._halt_check - if check is not None and not self._halt_requested and check(): - self._halt_requested = True - - def _halted_short(self, target: float) -> bool: - """Return whether a halt stops the march here, short of `target`. - - - ``target``: the position the call is stepping to, m. - - Returns: True when a halt is requested or the yield check asks for one, and - the endpoint is short of `target`. - """ - if reached(self._z, target): - return False - self.poll_halt() - if self._halt_requested: - self._halted = True - return self._halt_requested - - def _natural_stop_due(self, target: float) -> bool: - """Return whether a step to save ends before `target`, with the march there. - - Called at the start of a march, once a dense observation's march state is - restored: a step that crossed the last observed plane and was the ``k``-th is - saved now, unless `target` is another plane it also crossed; otherwise a halt - asked for there (:meth:`halt_ahead`) stops the march there. - - - ``target``: the position the call is stepping to, m. - """ - ahead, self._halt_ahead = self._halt_ahead, False - if self._natural_due and not reached(self._z, target): - self._natural_due = False - return True - if ahead and self._halt_requested and not reached(self._z, target): - # The restored endpoint of :meth:`halt_ahead`, every plane its step - # crossed observed. - self._halted = True - return True - return False - - _monitor: BoundaryMonitor | None = None - """The run's boundary monitor (SEP 21), fed every committed step; ``None``.""" - - _split_removed: float = 0.0 - """What the ``"split_step"`` collar took at the accepted steps since the monitor's - last reading, in its units (:attr:`solprop.monitor.BoundaryEnergies.removed`): - each accepted step's :class:`~solprop.backends.engines.AcceptRecord` adds to it - (:meth:`_absorb`) and :meth:`_boundary_energies` drains it.""" - - _split_found: Float[np.ndarray, " 4"] | None = None - """The energy and the guards' and collar's energies of the power the last accepted - step's split found (:attr:`solprop.monitor.BoundaryEnergies.found`), which the - monitor judges the occupancies on: the latest accepted step's, and ``None`` before - the first such step.""" - - reads_transverse_edge: bool = False - """Whether this backend reads a free-space run's transverse edge on the host - (SEP 40 section 5.3). A backend that does not leaves the run ``unwatched``, and - says so before the first step.""" - - _collar_quiet: bool = False - """Whether the modal stage leaves the in-stage temporal collar term out: the run - opted in, the monitor last found the collar quiet (:data:`solprop.monitor.QUIET`) - and the route can rest it (:meth:`_collar_can_rest`; SEP 21, ADR-057).""" - - def attach_monitor(self, monitor: BoundaryMonitor) -> None: - """Watch the time window's edges from here on, starting with the current state. - - The launch is recorded now; every committed step is then accounted at the - same point as the periodic statistics rows (``_take_step_stats``), on - every march, after the state is finished and the position advanced. - - Parameters - ---------- - monitor : solprop.monitor.BoundaryMonitor - A monitor with nothing recorded. - - Raises - ------ - BackendError - If the monitor's weights do not match the grid, or its columns the state. - """ - n_t = self._problem.grids.n_t - n_modes, _, _ = self._problem.shape - columns = monitor.columns - given = None if columns is None else columns.shape - if monitor.weights.shape != (4, n_t) or given not in {None, (n_modes,)}: - msg = ( - f"{self.name}: the boundary monitor's weights {monitor.weights.shape} " - f"or columns {given} do not match the grid's {n_t} samples and the " - f"state's {n_modes} modes" - ) - raise BackendError(msg) - if monitor.split: - # The split collar's crossing limit is read again at every check. - monitor.crossing = self._problem.split_crossing - self._monitor = monitor - self._bind_monitor(monitor) - workspace = self._workspace - # The noise draw is a host array already, read once. - monitor.launch( - self._boundary_energies(), - self._z, - floor=workspace.input_floor, - ) - self._set_collar_quiet(monitor.collar_quiet) - # A resumed fixed schedule is held to the state it resumes from at once. - self._refuse_scheduled_crossing(monitor) - edge = monitor.transverse - if edge is not None: - floor = workspace.input_floor - schedule = self._stepper.schedule - self._require_state() - edge.launch( - workspace.edge_reading( - edge, - # A resumed launch reads no share, but continues the current. - full=not edge.resumed, - current=edge.every_step and edge.resumed, - ), - self._z, - noise=None if floor is None else np.asarray(floor), - clean_columns=workspace.clean_columns(edge), - steps=None if schedule is None else np.asarray(schedule.steps), - reads=self.reads_transverse_edge, - declared=_declared_discard(self._problem), - ) - - def _read_transverse(self, monitor: BoundaryMonitor, *, plane: bool) -> None: - """Read the transverse edge where its spacing or a saved plane asks (SEP 40). - - - ``plane``: whether a saved plane has just been reached, which is always read. - """ - edge = monitor.transverse - if edge is None: - return - # Read before the next step would carry past the read (`TransverseEdge.due`). - due = edge.due(self._z, self._next_step()) - # A plane the step that reached it already read has nothing to add. - read = (plane or due) and edge.wants_read(self._z) - # A collar's inward current accumulates at every committed step. - accumulate = edge.every_step and not plane - if not (read or accumulate): - return - self._require_state() - reading = self._workspace.edge_reading(edge, faces=read, current=accumulate) - if accumulate: - assert reading.current is not None - edge.step(reading.current, self._z) - if read: - edge.read(reading, self._z) - - def edge_memory(self, space: object) -> int: - """Return what reading the edge holds in the state's memory space. - - What :func:`solprop.driver.estimate.estimate` adds: it attaches no monitor. - - Parameters - ---------- - space : object - The run's transverse grid. - - Returns - ------- - int - Zero by default: a read on the host holds nothing beside the state there. - """ - del space - return 0 - - def _next_step(self) -> float: - """Return the step the march takes next, m. - - A replay takes its schedule's and never updates the proposal, which stays - ``dz_init``: read from that, an edge read comes early or late by the difference. - - - Returns: the schedule's next step on a replay, zero past its end, and - otherwise the controller's proposal. - """ - schedule = self._stepper.schedule - if schedule is None: - return self._proposal - if self._schedule_index >= schedule.n_steps: - return 0.0 - return float(schedule.steps[self._schedule_index]) - - def _transverse_capped(self, proposal: float, z: float) -> float: - """Return the proposal, held to the transverse edge's read spacing (SEP 40 5.3). - - A low-source run commits long steps, and light could cross the edge unseen - within one; the read spacing is a ceiling on the step instead. The step is not - made to land on a read: the edge is read before a step would pass one. - - - ``proposal``: the controller's proposal, m. - - ``z``: where the step starts, m. - - Returns: the proposal, or the read spacing, m. - """ - monitor = self._monitor - edge = None if monitor is None else monitor.transverse - if edge is None: - return proposal - return min(proposal, edge.ceiling(z)) - - def _split_capped(self, proposal: float) -> float: - """Return the proposal, held to the split collar's crossing limit. - - The boundary monitor reads the limit from the state's occupancy at every - check (:attr:`solprop.monitor.BoundaryMonitor.step_cap`): light that spreads - into faster-walking bins shortens the steps until the next check, which reads - it again. - - - ``proposal``: the controller's proposal, m. - - Returns: the proposal, or the cap, m. - """ - monitor = self._monitor - return proposal if monitor is None else min(proposal, monitor.step_cap) - - def _bind_monitor(self, monitor: BoundaryMonitor | None) -> None: - """Read a boundary monitor's energies from now on, or stop reading them. - - Called when a monitor is attached, with nothing yet taken by a split, and - with ``None`` when a state is loaded: either empties the split collar's - accumulator (SEP 52 section 5.2), and the workspace takes the split's sums at - each accepted step's finish while a monitor of that scheme is bound. - - - ``monitor``: the run's monitor, or ``None`` to stop. - """ - self._split_removed = 0.0 - self._split_found = None - self._workspace.bind_monitor(monitor) - - def _absorb(self, record: AcceptRecord) -> None: - """Accumulate an accepted step's split collar's sums (SEP 52 section 5.2). - - The removal adds over every accepted step since the previous check, which the - next reading drains; the found occupancies are the latest accepted step's. A - step that took no split sums -- no collar of that scheme, or no monitor -- - leaves both as they were. - """ - if record.found is not None: - self._split_removed += record.removed - self._split_found = record.found - - def _boundary_energies(self) -> BoundaryEnergies: - """Return the boundary monitor's reading of the state (SEP 21, ADR-057). - - The workspace's reading of the committed state (its energy, its four weighted - energies and its occupancy), with what the split collar took at the accepted - steps since the previous reading, which this drains, and the energies of the - power the last step's split found. - """ - monitor = self._monitor - if monitor is None: - raise BackendError(f"{self.name}: no boundary monitor is attached") - removed, self._split_removed = self._split_removed, 0.0 - reading = self._workspace.reading() - return BoundaryEnergies( - total=reading.total, - regions=reading.regions, - removed=removed, - found=self._split_found, - occupancy=reading.occupancy, - ) - - def _check_boundaries( - self, monitor: BoundaryMonitor, *, plane: bool = False - ) -> None: - """Account the committed step at the current position with the monitor. - - - ``plane``: true for a saved plane's check of a step the monitor already - skipped. - """ - self._require_state() - self._check_at( - monitor, - self._boundary_energies(), - self._z, - self._schedule_index, - plane=plane, - ) - - def _check_at( - self, - monitor: BoundaryMonitor, - energies: BoundaryEnergies, - z: float, - cursor: int, - *, - plane: bool = False, - ) -> None: - """Book a reading of the step committed at `z` with the monitor (SEP 45 4.10). - - - ``z``: the step's end, m. - """ - monitor.step(energies, z, plane=plane) - self._set_collar_quiet(monitor.collar_quiet) - self._refuse_scheduled_crossing(monitor, cursor=cursor, z=z) - - def _refuse_scheduled_crossing( - self, - monitor: BoundaryMonitor, - *, - cursor: int | None = None, - z: float | None = None, - ) -> None: - """Stop a fixed schedule whose steps before the next check pass the cap. - - Translation admitted the schedule on the launch's occupancy; light that has - since spread into faster-walking bins lowers the cap, and a schedule cannot - shorten its steps (:class:`solprop.boundaries.SplitCrossing`). The cap holds - until the next check, which the monitor's cadence makes due within - :meth:`~solprop.monitor.BoundaryMonitor.steps_to_check` steps at most, so the - longest of those is held to it. Read at the launch too, so that a resumed - schedule is held to the state it resumes from. - - - ``cursor``: the replay cursor after the step read; ``None`` for the driver's - own. - - ``z``: the step's end, m; ``None`` for the driver's position. - """ - schedule = self._stepper.schedule - first = self._schedule_index if cursor is None else cursor - position = self._z if z is None else z - if schedule is None or first >= schedule.n_steps: - return - ahead = schedule.steps[first : first + monitor.steps_to_check()] - step = float(np.max(ahead)) - cap = monitor.step_cap - if step > cap: - msg = ( - f"at z = {position:.6e} m the split temporal collar's crossing limit " - f"fell to {cap:.3e} m, below the fixed schedule's step {step:.3e} m " - "before the next check: light has spread into bins that walk faster " - "than the launch's, and a step that long could carry it through the " - "collar and round the window undamped. Take shorter steps, step " - 'adaptively, or use absorber_scheme="nonlinear"' - ) - raise BoundaryError(msg) - - def _set_collar_quiet(self, quiet: bool) -> None: - """Say whether the collar is quiet. - - The term is left out only where the route can rest it - (:meth:`_collar_can_rest`), and the monitor is told what the stages do, so - that it adds no removal while the term is out. A change drops a reused - first-same-as-last stage, which was evaluated under the other setting - (:meth:`_collar_changed`); a backend whose stages run elsewhere passes the - flag on there. - """ - quiet = quiet and self._collar_can_rest() - if self._monitor is not None: - self._monitor.note_collar(quiet) - if quiet != self._collar_quiet: - self._collar_quiet = quiet - self._workspace.collar_quiet = quiet - self._collar_changed() - - def _quiet_capped(self, proposal: float) -> float: - """Return the proposal, held to the monitor's interval while the collar rests. - - A left-out collar absorbs nothing, and the monitor can only see the committed - states: one long step could carry light from a quiet collar deep into it, - unabsorbed. While the term is out no step is longer than the interval the - monitor checks a quiet window at (:attr:`BoundaryMonitor.interval`, the - guide's length over :data:`solprop.monitor.CHECKS`), so light has to walk - about twenty windows over the run to cross the collar between two checks. - - - ``proposal``: the controller's proposal, m. - - Returns: the proposal, or the monitor's interval while the collar is left out, - m. - """ - monitor = self._monitor - if not self._collar_quiet or monitor is None: - return proposal - return min(proposal, monitor.interval) - - def _collar_can_rest(self) -> bool: - """Return whether this run's stages may leave a quiet temporal collar out. - - The one rule every backend reads (:func:`solprop.backends.records.collar_rests`, - SEP 21 D15). - """ - return collar_rests(self._problem, self._stepper) - - def _collar_changed(self) -> None: # noqa: B027 - optional by design - """Drop whatever was evaluated under the other collar setting. - - The default holds nothing; a backend that reuses the last stage of a step as - the first of the next forgets it here. - """ - - def _monitor_plane(self) -> None: - """Close the boundary monitor's row for the plane just reached (SEP 21, D5). - - A plane's state is checked even when its last step was not. - """ - monitor = self._monitor - if monitor is None: - return - if monitor.stale: - self._check_boundaries(monitor, plane=True) - self._read_transverse(monitor, plane=True) - monitor.plane(self._z) - - def _take_step_stats(self) -> None: - """Record one statistics row when this accepted step is the period-th. - - Called by every march (:meth:`_SessionHooks.stepped`) **after** the engine's - accept and after the march's position is advanced, which is the only point at - which both describe the step just committed: an adaptive march records the - attempt before it accepts and a replay after, so anything reading the state or - the position from inside ``_on_accepted_step`` would be one accepted step stale - on an adaptive run and correct on a replayed one. - - The row is :meth:`stats` of the periodic subset, so there is exactly one - implementation of every statistic and a row taken at a save plane is bitwise - what that plane records; a second implementation of a statistic could drift - from the first. - """ - self._monitor_step() - self._statistics_step() - - def _monitor_step(self) -> None: - """Check or skip the step just committed, as the monitor's cadence asks. - - The boundary monitor's part of :meth:`_take_step_stats`: a quiet window is - checked every few steps, without reading the state in between - (:data:`solprop.monitor.CADENCE`), and the transverse edge read where due. - """ - monitor = self._monitor - if monitor is not None: - if monitor.due(self._z): - self._check_boundaries(monitor) - else: - monitor.skip(self._z) - self._read_transverse(monitor, plane=False) - - def _statistics_step(self) -> None: - """Take the statistics row of the step just committed when it is due. - - The statistics part of :meth:`_take_step_stats`, at the driver's position. - """ - if self._row_spec is None: - return - self._accepted_steps += 1 - if self._accepted_steps % self._row_period: - return - # The attempt this row belongs to is the one `_record` has just appended, and - # the history counts rejections, so the index is not `row * period`. - self._record_step_stats(self._row_spec, self._z, len(self._history) - 1) - - def _record(self, z: float, dz: float, norm: float, accepted: bool) -> None: - """Append one step to the history since the last observation. - - - ``z``: position at the end of the step, m. - - ``dz``: length of the step, m. - - ``norm``: the scaled error norm as executed: a landing step clipped short - records its own, not the proposal's equivalent. A diverged attempt's - (overflowed or NaN) is recorded as infinity, which the controller never - accepts. - """ - if not math.isfinite(norm): - norm = math.inf - self._history.append((z, dz, norm, accepted, time.perf_counter() - self._clock)) - self._progress.step(z, dz, accepted) - if accepted: - self._on_accepted_step() - - # --- noise --------------------------------------------------------------------- - - # --- guards -------------------------------------------------------------------- - - def _require_state(self) -> _StateT: - """Return the current state, refusing a closed or unloaded backend.""" - self._check_open() - state = self._workspace.state - if state is None: - msg = "no initial state: call set_initial before propagating or observing" - raise BackendError(msg) - self._refuse_in_flight() - return cast("_StateT", state) - - def _refuse_in_flight(self) -> None: - """Refuse every entry that reads or advances a state left between two steps. - - The low-storage march accepts each step in place (SEP 24 section 6.2): from - the step's start to its commit the state is neither the step's start nor its - end, so an exception or a signal between them leaves nothing a reader may use - and nothing a march may continue from. Only :meth:`set_initial` clears it. - """ - pending = self._abandoned() - if pending is not None: - raise BackendError(in_flight_refusal(self.name, *pending)) - - @property - def closed(self) -> bool: # numpydoc ignore=RT01 - """Whether the backend has released its buffers, as a failure may.""" - return self._closed - - def _check_open(self) -> None: - """Refuse a backend that has been closed.""" - if self._closed: - msg = "this backend is closed; its buffers were released" - raise BackendError(msg) - - def _checked_position(self, z: float) -> float: - """Return a position the state may be loaded at, refusing one off the table. - - - ``z``: the requested position, m. - """ - low, high = self._problem.linear.z_span - if not (math.isfinite(z) and low <= z <= high): - msg = ( - f"a state can only be loaded inside the operator table, which covers " - f"[{low:.6g}, {high:.6g}] m, and z = {z!r} does not" - ) - raise BackendError(msg) - return z - - def _schedule_index_at(self, z: float) -> int: - """Return how many steps of a replayed schedule a position has consumed. - - - ``z``: the position the state is loaded at, m. On a replay it must be an edge; - every save plane is one (``validate`` checks it), so the refusal fires only - for a position the run never stopped at, from which a replay could not - continue in step. - """ - schedule = self._stepper.schedule - if schedule is None: - return 0 - edges = schedule.edges - index = int(np.argmin(np.abs(edges - z))) - if abs(float(edges[index]) - z) > replay_tolerance(schedule, z): - msg = ( - f"a replayed schedule can only be resumed at one of its edges, and " - f"z = {z:.6g} m is not one; the nearest is {float(edges[index]):.6g} m" - ) - raise BackendError(msg) - return index - - def _check_target(self, target: float) -> None: - """Refuse a save plane behind the current position or outside the table. - - - ``target``: the requested position, m. - """ - if not math.isfinite(target): - msg = f"the save plane must be finite, got {target!r}" - raise BackendError(msg) - if target < self._z: - msg = ( - f"cannot propagate backwards: asked for z = {target:.6g} m from " - f"{self._z:.6g} m" - ) - raise BackendError(msg) - span = self._problem.linear.z_span - if target > span[1]: - msg = ( - f"z = {target:.6g} m lies beyond the operator table, which covers " - f"[{span[0]:.6g}, {span[1]:.6g}] m" - ) - raise BackendError(msg) - - -def _declared_discard(problem: PropagationProblem) -> bool: - """Return whether a run declared content above ``discard_above`` (SEP 40 5.3). - - - Returns: True when its transverse specification sets ``discard_above``. - """ - design = transverse_of(problem.route) - return design is not None and design.specification.discard_above is not None - - -def _history_record( - entries: Sequence[tuple[float, float, float, bool, float]], -) -> BackendHistory: - """Return the attempts since the last observation as a history record. - - - `entries`: one ``(z, dz, error_norm, accepted, wall_time)`` per attempt. - - Returns: the attempts, in arrays made here and held, so the record takes them - without a copy. - """ - columns = list(zip(*entries, strict=True)) if entries else [()] * 5 - return BackendHistory( - z=hold(np.array(columns[0], dtype=np.float64)), - dz=hold(np.array(columns[1], dtype=np.float64)), - error_norm=hold(np.array(columns[2], dtype=np.float64)), - accepted=hold(np.array(columns[3], dtype=np.bool_)), - wall_time=hold(np.array(columns[4], dtype=np.float64)), - ) diff --git a/src/solprop/backends/host/low_storage.py b/src/solprop/backends/host/low_storage.py index 8a5621c53..18d706d79 100644 --- a/src/solprop/backends/host/low_storage.py +++ b/src/solprop/backends/host/low_storage.py @@ -42,7 +42,7 @@ class HostLowStorageMarch: Parameters ---------- engine : solprop.backends.engines.RungeKuttaEngine - The engine; beside the protocol, a load calls its ``reset``. + The engine. method : solprop.stepper.low_storage.LowStorageRungeKutta The march. host : solprop.backends.host.marches.MarchHost @@ -104,11 +104,6 @@ def engine(self) -> object: # numpydoc ignore=RT01 """Engine that holds the registers.""" return self._engine - @property - def holding(self) -> bool: # numpydoc ignore=RT01 - """Whether a dense observation holds a plane; never, on this march.""" - return False - @property def in_flight(self) -> tuple[float, float] | None: # numpydoc ignore=RT01 """The step a failure left in flight, its start and length, m; or ``None``.""" @@ -127,7 +122,6 @@ def load(self, z: float, proposal: float, cursor: int) -> None: The replay cursor at `z`. """ self.state.load(z, proposal, cursor) - self._engine.reset() # pyright: ignore[reportAttributeAccessIssue] self._pending = None # Its count is the loaded run's, as the Adams ledger is (SEP 22 4.7). self.source_evaluations = 0 diff --git a/src/solprop/backends/host/marches.py b/src/solprop/backends/host/marches.py index 7da300049..234203afb 100644 --- a/src/solprop/backends/host/marches.py +++ b/src/solprop/backends/host/marches.py @@ -9,9 +9,11 @@ :class:`~solprop.backends.host.low_storage.HostLowStorageMarch` -- keeps its position, proposal, replay cursor and accepted norms in a :class:`MarchState` of its own, hands every state-sized operation to its engine -(:mod:`solprop.backends.engines`) and asks the session only through the narrow +(:mod:`solprop.backends.engines`) and asks the session that schedules it +(:class:`~solprop.backends.host.session.HostSession`) only through the narrow :class:`MarchHost`: whether to stop, how far a step may go, and what to record when an -attempt ends. It touches no other object's fields; the session reads its state. +attempt ends. It touches no other object's fields; the session reads its state, and +holds the dense observation of a plane a step crossed (SEP 52 section 5.2). """ from collections import deque @@ -30,8 +32,7 @@ class MarchState: Attributes ---------- z : float - The committed state's position, m; while a dense observation holds a plane, - the plane's. + The committed state's position, m. proposal : float The controller's proposal, m: its own state, never the executed step. cursor : int @@ -67,8 +68,9 @@ def load(self, z: float, proposal: float, cursor: int) -> None: class MarchHost(Protocol): """What a march asks of the session that schedules it. - The reference's step driver implements it today; SEP 52 moves it into the - reference's session. + The reference's session implements it + (:class:`~solprop.backends.host.session.HostSession`); a decision-trace harness + scripts it. """ @property @@ -125,7 +127,7 @@ def absorb(self, record: AcceptRecord) -> None: ... def stepped(self) -> None: - """Account the step just committed: the monitor and the statistics row.""" + """Account the step just committed: the monitor, the edge and the row.""" ... def natural_stop(self, target: float) -> bool: @@ -139,22 +141,7 @@ def natural_stop(self, target: float) -> bool: Returns ------- bool - Whether a step plane or a halt stops the march here. - """ - ... - - def natural_stop_due(self, target: float) -> bool: - """Return whether a step to save, or a halt, ends the march where it stands. - - Parameters - ---------- - target : float - The position the call is stepping to, m. - - Returns - ------- - bool - Whether the march returns at once. + Whether a step plane, a halt or a warning barrier stops the march here. """ ... @@ -183,6 +170,6 @@ def in_flight_refusal(name: str, z: float, dz: float) -> str: return ( f"{name}: the low-storage step of {dz:.6g} m from z = {z:.6g} m was " "abandoned in flight, and the state it was accepting in place holds " - "neither end of the step; load a state with set_initial (resume from the " - "last saved plane) before observing or propagating again" + "neither end of the step; start a new session from the last saved plane " + "before observing or propagating again" ) diff --git a/src/solprop/backends/host/runge_kutta.py b/src/solprop/backends/host/runge_kutta.py index 1e0e2b0e9..0f65cd9a1 100644 --- a/src/solprop/backends/host/runge_kutta.py +++ b/src/solprop/backends/host/runge_kutta.py @@ -46,8 +46,7 @@ class RungeKuttaMarch: Parameters ---------- engine : solprop.backends.engines.RungeKuttaEngine - The engine; beside the protocol, the march's dense observation calls its - ``hold``, ``restore`` and ``observe``, and a load its ``reset``. + The engine. policy : solprop.backends.records.RungeKuttaPolicy The controller and the landings. host : solprop.backends.host.marches.MarchHost @@ -84,13 +83,19 @@ def __init__( self.state = MarchState( z=0.0, proposal=proposal, norms=deque(maxlen=policy.controller.lag + 2) ) - # The march's own position and state while an interpolated plane is observed. - self._ahead: tuple[float, object] | None = None + # The step of the trial last begun, which an engine stepping in place may + # leave in flight (the commit contract, SEP 52 section 5.2). + self._trying = (0.0, 0.0) @property - def holding(self) -> bool: # numpydoc ignore=RT01 - """Whether a dense observation holds the state at a plane, the march ahead.""" - return self._ahead is not None + def engine(self) -> object: # numpydoc ignore=RT01 + """Engine the march steps through.""" + return self._engine + + @property + def in_flight(self) -> tuple[float, float] | None: # numpydoc ignore=RT01 + """The step its engine left in flight, its start and length, m; or ``None``.""" + return self._trying if self._engine.in_flight else None def load(self, z: float, proposal: float, cursor: int) -> None: """Start afresh at a loaded position. @@ -105,8 +110,6 @@ def load(self, z: float, proposal: float, cursor: int) -> None: The replay cursor at `z`. """ self.state.load(z, proposal, cursor) - self._ahead = None - self._engine.reset() # pyright: ignore[reportAttributeAccessIssue] def advance(self, target: float) -> None: """Replay the schedule, or step adaptively, towards `target`. @@ -136,14 +139,6 @@ def march_to(self, target: float) -> None: """ policy, host, state, engine = self._policy, self._host, self.state, self._engine dense = policy.interpolate - if dense and self._ahead is not None: - # The march is ahead of the last interpolated plane; resume it there. - z, held = self._ahead - engine.restore(z, held) # pyright: ignore[reportAttributeAccessIssue] - state.z = z - self._ahead = None - if host.natural_stop_due(target): - return # The policy's landings (SEP 45 section 4.2): only the operator table's two # ends bound a step without the interval cap (SEP 14 section 4.1), and dense # output steps across the save planes, still landing on the end of the run and @@ -163,6 +158,7 @@ def march_to(self, target: float) -> None: # from a sliver and it regrows at the growth cap, which over two hundred # planes costs more steps than the run needs between them (stepper.md 3). stop = landing(state.z, host.cap(state.proposal, state.z), targets) + self._trying = (state.z, stop.dz) norm = engine.trial(state.z, stop.dz) # What the controller learns from, and what a rejection is scaled by, is the # norm the *proposal* would have scored; what decides acceptance, and what @@ -177,7 +173,7 @@ def march_to(self, target: float) -> None: if accepted: if dense and not reached(target, end): # The step crosses the plane: hold its extension for the - # observation, and for any later plane it also crosses. + # session's observation, and for any later plane it crosses. engine.extend(state.z, stop.dz) with committing(): record = engine.accept(stop.dz) @@ -197,19 +193,6 @@ def march_to(self, target: float) -> None: return else: state.proposal = rk_core.reject(policy, state.proposal, equivalent) - if dense and not reached(target, state.z): - self._observe_inside(target) - - def _observe_inside(self, position: float) -> None: - """Make the state the interpolated field at `position` and hold the march's. - - - ``position``: the plane, m, inside the last accepted step. - """ - engine, state = self._engine, self.state - observed = engine.observe(position) # pyright: ignore[reportAttributeAccessIssue] - self._ahead = (state.z, engine.hold()) # pyright: ignore[reportAttributeAccessIssue] - engine.restore(position, observed) # pyright: ignore[reportAttributeAccessIssue] - state.z = position def _start_up(self, norm: float) -> None: """Take the step after the first from the first step's own estimate. @@ -256,6 +239,7 @@ def replay_to(self, schedule: FixedSchedule, target: float) -> None: while state.cursor < schedule.n_steps and state.z < target - slack: host.poll_stop() dz = float(schedule.steps[state.cursor]) + self._trying = (state.z, dz) norm = engine.trial(state.z, dz) if not math.isfinite(norm): msg = ( diff --git a/src/solprop/backends/host/session.py b/src/solprop/backends/host/session.py index 77f03ca64..a0e4a398f 100644 --- a/src/solprop/backends/host/session.py +++ b/src/solprop/backends/host/session.py @@ -2,34 +2,51 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The NumPy reference's run session (SEP 47 sections 5 and 6.6). +"""The NumPy reference's run session: the schedule of a run (SEP 47, SEP 52). :class:`HostSession` is the :class:`~solprop.backends.session.RunSession` that serves -every ``numpy_ref`` run: the launch-before-monitor order, the plane -schedule, the snapshot latch, bounded yields, chunked attempts, exports and the terminal -outcome with its checkpoint eligibility, over the reference's own driver -(:class:`solprop.backends.host.driver.HostDriver`), through its halt and yield hooks -(``request_halt``, ``clear_halt``, ``halt_ahead``, ``set_halt_check``) and its read-only -march state (``halted``, ``holding_plane``, ``position``, ``drain_attempts``). -:class:`HostPrepared` is the prepared execution (SEP 47 section 5.2) a reference backend -returns from ``prepare``; each of its starts opens one. +every ``numpy_ref`` run, and the Python counterpart of native's ``session.cpp``, whose +scheduling decisions are this module's transcribed. It owns the run's schedule: the +save planes and step planes, the natural stops, the bounded yields, the landing +targets, the halts and the snapshot latch, the dense observation of a plane a step +crossed (through the backend's :class:`Dense`), the periodic statistics rows, the +boundary monitor's and the transverse edge's checks with the split collar's sums, the +quadrature alarm's report, the load of the start with its noise, the events and the +exports. It drives the run's march directly (:class:`HostMethod`), as the march's +:class:`~solprop.backends.host.marches.MarchHost`; the state and every state-sized +operation are the backend's workspace's +(:class:`~solprop.backends.numpy_ref.workspace.NumpyWorkspace`). + +**Boundary warnings are barriers.** The monitor's and the edge's warnings go into a +sink (:attr:`solprop.monitor.BoundaryMonitor.sink`) rather than being issued where they +arise, and each is reported, in order, as a ``WARNING`` barrier event at the committed +endpoint it arose at, whose consumer emits it (:func:`~solprop.backends.events. +emit_warning`): its filters may raise it, which fails the run there. Once allowed, the +next advance does the rest of that point's work, once, as native's session does. -The session composes the parts every Python session shares -(:mod:`solprop.backends.session_core`: the attempt counter, the yield check, the -snapshot latch, the shared observation and its exports, and the preparation's -refusals) with the lifecycle ledger (:class:`~solprop.backends.session.SessionLedger`). -It imports nothing of the native backend's. +:class:`HostPrepared` is the prepared execution (SEP 47 section 5.2) a reference backend +returns from ``prepare``; each of its starts opens one session. The session composes the +parts every Python session shares (:mod:`solprop.backends.session_core`) with the +lifecycle ledger (:class:`~solprop.backends.session.SessionLedger`). It imports nothing +of the native backend's. """ from __future__ import annotations +import dataclasses +import logging +import math import time -from collections.abc import Callable, Mapping +from collections.abc import Callable, Generator, Mapping, Sequence +from dataclasses import dataclass from types import TracebackType -from typing import TYPE_CHECKING, Any +from typing import TYPE_CHECKING, Protocol, cast, runtime_checkable import numpy as np +from solprop._interrupts import poll +from solprop._ownership import hold +from solprop.backends.engines import AcceptRecord from solprop.backends.events import ( Eligibility, Event, @@ -46,14 +63,17 @@ join_attempts, ) from solprop.backends.export import ExportRecipe -from solprop.backends.host.driver import HostDriver +from solprop.backends.host.adams import HostAdamsMarch +from solprop.backends.host.low_storage import HostLowStorageMarch +from solprop.backends.host.marches import MarchState, in_flight_refusal +from solprop.backends.host.runge_kutta import RungeKuttaMarch from solprop.backends.protocol import ( BackendHistory, Observation, StepStats, StepSummary, ) -from solprop.backends.records import plane_plan +from solprop.backends.records import collar_rests, plane_plan from solprop.backends.session import ( DEFAULT_DEADLINE, DEFAULT_WORK_LIMIT, @@ -76,22 +96,415 @@ check_preparation, merge_summaries, ) -from solprop.exceptions import BackendError, StopRequested -from solprop.log import StopFlag -from solprop.monitor import BoundaryMonitor +from solprop.exceptions import BackendError, BoundaryError, StopRequested +from solprop.log import NOT_ESTIMATED, StopFlag +from solprop.monitor import BoundaryEnergies, BoundaryMonitor from solprop.output.records import MarchSnapshot -from solprop.translate.problem import PropagationProblem +from solprop.stats import StatsSpec +from solprop.stepper.controller import ControlRecord +from solprop.stepper.low_storage import LowStorageRungeKutta +from solprop.stepper.schedule import reached, replay_tolerance +from solprop.translate.modal import QUADRATURE_ALARM, warn_quadrature +from solprop.translate.problem import PropagationProblem, StepperSettings +from solprop.translate.routes import transverse_of 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 - # hold the scripted drivers to the full protocol or check a refused export - # destination's shape before the session refuses it. + # check a refused export destination's shape before the session refuses it. from jaxtyping import Complex - from solprop.backends.protocol import Backend, HostStepping + from solprop.backends.numpy_ref.workspace import NumpyWorkspace + from solprop.backends.protocol import Backend + +__all__ = [ + "INITIAL_STEP_STATS_CAPACITY", + "Dense", + "HistoryRows", + "HostBackend", + "HostMethod", + "HostPrepared", + "HostSession", + "natural_stop", + "start_position", + "step_cap", +] + +logger = logging.getLogger(__name__) + +INITIAL_STEP_STATS_CAPACITY = 64 +"""Rows a plane's statistics buffer holds before it first has to grow.""" + + +@runtime_checkable +class Dense(Protocol): + """A march's dense output: what a session interpolates a crossed plane from. + + Native's ``session::Dense``; the reference's are + :mod:`solprop.backends.numpy_ref.dense`'s. + """ + + def crosses(self, position: float, target: float) -> bool: + """Return whether a march that returned at `position` stepped across `target`. + + Parameters + ---------- + position : float + The committed position, m. + target : float + The plane, m. + + Returns + ------- + bool + Whether the plane is observed inside the last step. + """ + ... + + def observe(self, position: float) -> None: + """Hold the committed state aside; make the state the field at `position`. + + Parameters + ---------- + position : float + The plane, m, inside the last accepted step. + """ + ... + + def restore(self) -> None: + """Make the held committed state current again.""" + ... + + +@runtime_checkable +class HistoryRows(Protocol): + """An Adams history's rows where the state lives, which a snapshot carries.""" + + def nbytes(self) -> int: + """Return the bytes :meth:`export` would copy. + + Returns + ------- + int + The size of every row. + """ + ... + + def export(self) -> dict[str, np.ndarray]: + """Return copies of the rows, by name. + + Returns + ------- + dict + The rows. + """ + ... + + def install(self, rows: Mapping[str, np.ndarray], shape: tuple[int, ...]) -> None: + """Install rows :meth:`export` returned, for a state of `shape`. + + Parameters + ---------- + rows : collections.abc.Mapping + The rows, by name. + shape : tuple of int + The state's shape. + """ + ... + + +@dataclass(eq=False) +class HostMethod: + """The march one session runs, built for it by the backend (native's ``Method``). + + Attributes + ---------- + march : object + The march: a :class:`~solprop.backends.host.runge_kutta.RungeKuttaMarch`, + :class:`~solprop.backends.host.adams.HostAdamsMarch` or + :class:`~solprop.backends.host.low_storage.HostLowStorageMarch`, its session + the march's host. + dense : Dense or None + Its dense output when the run interpolates its planes; ``None`` otherwise. + rows : HistoryRows or None + The Adams history's rows a snapshot carries; ``None`` for the other marches. + """ + + march: RungeKuttaMarch | HostAdamsMarch | HostLowStorageMarch + dense: Dense | None = None + rows: HistoryRows | None = None + + +@runtime_checkable +class HostBackend(Protocol): + """What the reference's session reads of its backend. + + Attributes + ---------- + name : str + The registry name. + reads_transverse_edge : bool + Whether a free-space run's transverse edge is read (SEP 40 section 5.3). + """ + + name: str + reads_transverse_edge: bool + + @property + def request(self) -> RunRequest: # numpydoc ignore=RT01 + """Request the backend was built for.""" + ... + + @property + def workspace(self) -> NumpyWorkspace: # numpydoc ignore=RT01 + """Workspace that holds the state.""" + ... + + @property + def closed(self) -> bool: # numpydoc ignore=RT01 + """Whether the backend has released its buffers.""" + ... + + def method(self, host: object) -> HostMethod: + """Return a fresh march, and its dense output and rows, reporting to `host`. + + Parameters + ---------- + host : object + The session, as the march's + :class:`~solprop.backends.host.marches.MarchHost`. + + Returns + ------- + HostMethod + The method. + """ + ... + + def metadata(self) -> dict[str, object]: + """Return the execution's facts. + + Returns + ------- + dict + The record. + """ + ... + + def memory_ledger(self) -> dict[str, int]: + """Return every retained buffer by name, bytes. + + Returns + ------- + dict + The ledger. + """ + ... + + def close(self) -> None: + """Release the buffers.""" + ... + + +def start_position( + problem: PropagationProblem, stepper: StepperSettings, z: float +) -> tuple[float, int]: + """Return where a state may be loaded, and a replay's cursor there. + + Parameters + ---------- + problem : solprop.translate.problem.PropagationProblem + The problem, whose operator table bounds the position. + stepper : solprop.translate.problem.StepperSettings + The run's stepper settings, whose schedule a replay follows. + z : float + The requested position, m. + + Returns + ------- + tuple + The position, m, and how many steps of a replayed schedule it has consumed + (zero for an adaptive run). + + Raises + ------ + BackendError + If `z` lies outside the operator table, or a schedule is replayed and `z` is + not one of its edges: every save plane is one (``validate`` checks it), so this + fires only for a position the run never stopped at. + """ + low, high = problem.linear.z_span + if not (math.isfinite(z) and low <= z <= high): + msg = ( + f"a state can only be loaded inside the operator table, which covers " + f"[{low:.6g}, {high:.6g}] m, and z = {z!r} does not" + ) + raise BackendError(msg) + schedule = stepper.schedule + if schedule is None: + return z, 0 + edges = schedule.edges + index = int(np.argmin(np.abs(edges - z))) + if abs(float(edges[index]) - z) > replay_tolerance(schedule, z): + msg = ( + f"a replayed schedule can only be resumed at one of its edges, and " + f"z = {z:.6g} m is not one; the nearest is {float(edges[index]):.6g} m" + ) + raise BackendError(msg) + return z, index + + +def step_cap(monitor: object, quiet: bool, proposal: float, z: float) -> float: + """Return a proposal held to the boundary monitor's limits on a step. + + The session's rule (:meth:`HostSession.cap`), which a decision-trace harness drives + the real march with. + + Parameters + ---------- + monitor : solprop.monitor.BoundaryMonitor or None + The attached monitor, or ``None`` before one watches (no cap); a harness's + stand-in needs only its ``interval``, ``step_cap`` and ``transverse``. + quiet : bool + Whether the stages leave a quiet in-stage temporal collar out. + proposal : float + The controller's proposal, m. + z : float + Where the step starts, m. + + Returns + ------- + float + The proposal, or the quiet collar's interval, the transverse edge's read + spacing or the split collar's crossing limit when shorter, m. + """ + if monitor is None: + return proposal + monitor = cast("BoundaryMonitor", monitor) + # A left-out collar absorbs nothing, and the monitor sees only committed states: + # while the term is out no step is longer than the interval it checks a quiet + # window at (`BoundaryMonitor.interval`), so light has to walk about twenty + # windows over the run to cross the collar between two checks. + if quiet: + proposal = min(proposal, monitor.interval) + # A low-source run commits long steps, and light could cross the transverse edge + # unseen within one: its read spacing is a ceiling, the step not made to land on + # a read (SEP 40 section 5.3). + edge = monitor.transverse + if edge is not None: + proposal = min(proposal, edge.ceiling(z)) + # The split collar's crossing limit, read from the occupancy at every check: light + # spreading into faster-walking bins shortens the steps until the next check. + return min(proposal, monitor.step_cap) + + +def natural_stop(every: int, count: int, z: float, target: float) -> bool | None: + """Return whether the `count`-th accepted step since the load is a step plane. + + With ``step_planes = k`` the end of every ``k``-th accepted step is a plane (SEP 14 + phase 3): the march returns there, short of its target. A step that lands on the + target is saved as the target; one that crosses a densely observed target is saved + after it. The session's rule (:meth:`HostSession.natural_stop`), which a + decision-trace harness drives the real march with. + + Parameters + ---------- + every : int + The step planes' period ``k``; zero for none. + count : int + Accepted steps since the load, this one included. + z : float + Its end, m. + target : float + The position the march is stepping to, m. + + Returns + ------- + bool or None + ``None`` when the step is no ``k``-th; otherwise whether the march stops at its + end -- ``False`` at the target, whose plane observes it. + """ + if every == 0 or count % every: + return None + return not reached(z, target) + + +class _StepStatsBuffer: + """The rows a periodic statistics subset produces between two events. + + Grown by doubling from a preallocated block and reset without releasing it, so + that after the first plane a run allocates nothing per step: the capacity a plane + needed is the capacity the next starts with. Growing by concatenation on every step + would be quadratic. The shape of each statistic is learnt from the first row. + """ + + def __init__(self) -> None: + self._capacity = 0 + self._n_rows = 0 + self._z = np.zeros(0) + self._step = np.zeros(0, dtype=np.int64) + self._values: dict[str, np.ndarray] = {} + + def reset(self) -> None: + """Forget the rows held, keeping the allocation.""" + self._n_rows = 0 + + def append(self, z: float, step: int, values: Mapping[str, np.ndarray]) -> None: + """Add one row taken at `z`, after the chunk's attempt `step`.""" + if self._capacity == 0: + self._allocate(values) + elif self._n_rows == self._capacity: + self._grow() + index = self._n_rows + self._z[index] = z + self._step[index] = step + for name, value in values.items(): + row = self._values.get(name) + if row is None or np.shape(value) != row.shape[1:]: + expected = None if row is None else row.shape[1:] + msg = ( + f"the {name!r} statistic came back with shape " + f"{np.shape(value)} and this plane's rows are {expected}" + ) + raise BackendError(msg) + row[index] = value + self._n_rows = index + 1 + + def drain(self) -> StepStats: + """Return the rows as a frozen record of held copies and forget them.""" + rows = self._n_rows + drained = StepStats( + z=hold(self._z[:rows].copy()), + step=hold(self._step[:rows].copy()), + values={ + name: hold(value[:rows].copy()) for name, value in self._values.items() + }, + ) + self.reset() + return drained + + def _allocate(self, values: Mapping[str, np.ndarray]) -> None: + self._capacity = INITIAL_STEP_STATS_CAPACITY + self._z = np.zeros(self._capacity) + self._step = np.zeros(self._capacity, dtype=np.int64) + self._values = { + name: np.zeros((self._capacity, *np.shape(value)), dtype=np.float64) + for name, value in values.items() + } + + def _grow(self) -> None: + self._capacity *= 2 + self._z = np.resize(self._z, self._capacity) + self._step = np.resize(self._step, self._capacity) + self._values = { + name: np.concatenate([value, np.zeros_like(value)]) + for name, value in self._values.items() + } -__all__ = ["HostPrepared", "HostSession"] + +_Work = Generator[Warning, None, object] +"""A point's work: it yields each boundary warning as it arises, in order, and returns +what follows it.""" class HostSession: @@ -99,18 +512,18 @@ class HostSession: Parameters ---------- - driver : solprop.backends.protocol.Backend - The reference backend (a :class:`~solprop.backends.host.driver.HostDriver`), - constructed for `problem`. A driver reused from an earlier run is loaded again - from `start`, which restores everything its march reads. The session closes it - with itself when `owns` is set. + backend : solprop.backends.protocol.Backend + The reference backend (a :class:`HostBackend`), constructed for `problem`. A + backend reused from an earlier run is loaded again from `start`; the session + builds its own march (:meth:`HostBackend.method`), and closes the backend with + itself when `owns` is set. problem : solprop.translate.problem.PropagationProblem The translated problem. request : solprop.translate.run_request.RunRequest The run's policies. start : solprop.backends.session.Start - Where the run starts. The session loads it into the driver -- the field, the - noise, the call ledgers and any method history -- and takes its field. + Where the run starts. The session loads it -- the field, the noise, the call + ledgers and any method history -- and takes its field. listener : callable or None, optional Called with each attempt as it is made, for a progress reporter. It observes only; it cannot change the run. @@ -119,18 +532,25 @@ class HostSession: stop : solprop.log.StopFlag or None, optional The run's stop token, polled before every trial. owns : bool, optional - Whether closing the session closes the driver. A caller that reuses its driver - for later runs (a runner, a scan) keeps it open. + Whether closing the session closes the backend. A caller that reuses its + backend for later runs (a runner, a scan) keeps it open. + + Attributes + ---------- + reads_transverse_edge : bool + The backend's (SEP 40 section 5.3), which the service loop reads. Raises ------ solprop.exceptions.BackendError - If `driver` is not a reference driver. + If `backend` is not a reference backend, is closed, or `start` does not fit + the problem: its field's shape, or its position off the operator table or off + a replayed schedule's edges. """ - def __init__( + def __init__( # noqa: PLR0915 - the session's whole state, set once self, - driver: Backend, + backend: Backend, problem: PropagationProblem, request: RunRequest, start: Start, @@ -140,18 +560,22 @@ def __init__( stop: StopFlag | None = None, owns: bool = True, ) -> None: - """Refuse a driver that is not the reference's, and load the starting state.""" - if not isinstance(driver, HostDriver): + """Refuse a backend that is not the reference's, and load the starting state.""" + if not isinstance(backend, HostBackend): msg = ( - f"the reference session serves a host driver, not " - f"{type(driver).__name__}" + f"the reference session serves a reference backend, not " + f"{type(backend).__name__}" ) raise BackendError(msg) - self._driver = driver - # The same object, as the march whose hooks and state the session reads. - self._host: HostDriver[Any] = driver + if backend.closed: + raise BackendError("this backend is closed; its buffers were released") + self._backend = backend + self._workspace = backend.workspace self._problem = problem self._request = request + self._stepper = request.stepper + self._name = backend.name + self.reads_transverse_edge = bool(backend.reads_transverse_edge) self._ledger = SessionLedger() # The run's plane plan (SEP 52 section 5.1): its planes, the first beyond the # start, whether the start's own plane is owed, and the step planes. @@ -161,12 +585,30 @@ def __init__( self._owns = owns self._index = plan.next_plane self._launch_pending = plan.launch_pending - # The session takes over the request's fresh monitor and feeds it. + # The statistics channel between planes: the periodic subset promoted to + # `names`, so a row goes through the very same evaluation a save plane uses. + spec = request.observation.stats + self._row_spec: StatsSpec | None = ( + None + if not spec.periodic + else dataclasses.replace(spec, names=spec.periodic, periodic=(), period=1) + ) + self._row_period = spec.period + self._rows = _StepStatsBuffer() + # The session takes over the request's fresh monitor and feeds it; its and its + # edge's warnings come here, each reported as a barrier. self._monitor: BoundaryMonitor | None = request.boundary.monitor + self._sink: list[Warning] = [] self._monitor_resume = start.monitor self._attached = False + self._collar_quiet = False + self._split_removed = 0.0 + self._split_found: np.ndarray | None = None + # A point's work suspended at a warning barrier, and what follows it. + self._continuation: tuple[_Work, Callable[[object], EventBatch | None]] | None + self._continuation = None + self._barrier: Warning | None = None self._generation = 0 - self._z = float(start.z) self._attempts = 0 self._rejected = 0 self._stepped = False @@ -174,30 +616,43 @@ def __init__( self._latch = SnapshotLatch() self._fields = ObservedField(problem, self._drain) self._counter = AttemptCounter(listener, started) - driver.set_progress(self._counter) - driver.set_stop(stop) - driver.set_initial( - np.asarray(start.take_field()), - start.noise, - z=float(start.z), - resume=start.resume, - ) + self._stop = stop + # The schedule's cursors (`session.cpp`): accepted steps since the load, the + # natural count, a step plane owed past an interpolated target, the halt latch + # and the yield check. + self._accepted_steps = 0 + self._natural_count = 0 + self._natural_due = False + self._halt_requested = False + self._halt_check: YieldDue | None = None + self._halted = False + self._midplane = False + self._stop_here = False + self._stopped_short = False + self._target = math.nan + self._progress_started = False + self._alarm_reported = False + self._history: list[tuple[float, float, float, bool, float]] = [] + self._clock = time.perf_counter() + # The dense observation (SEP 47 section 5.3): whether the state holds an + # interpolated plane, and where. + self._observed = False + self._observed_z = math.nan + self._method = backend.method(self) + self._march = self._method.march + self._load(start) if start.ledgers is not None: - logical = start.ledgers.get("logical", {}) - atomic = start.ledgers.get("atomic", {}) - driver.restore_call_ledgers(logical, atomic) # pyright: ignore[reportArgumentType] - # After the field, which resets the method's history, as a resume always did. + self._restore_ledgers( + start.ledgers.get("logical", {}), # pyright: ignore[reportArgumentType] + start.ledgers.get("atomic", {}), # pyright: ignore[reportArgumentType] + ) + # After the field, which starts the method afresh, as a resume always did. self._march_refusal = ( - None if start.march is None else driver.restore_march(start.march) + None if start.march is None else self._restore_march(start.march) ) # -- protocol ------------------------------------------------------------------- - @property - def driver(self) -> HostStepping: # numpydoc ignore=RT01 - """Reference backend, whose facts the service loop records.""" - return self._driver - @property def finished(self) -> bool: # numpydoc ignore=RT01 """Whether the session yielded its terminal event.""" @@ -208,6 +663,14 @@ def closed(self) -> bool: # numpydoc ignore=RT01 """Whether the session was closed.""" return self._ledger.state is SessionState.CLOSED + @property + def in_flight(self) -> tuple[float, float] | None: # numpydoc ignore=RT01 + """Low-storage step a failure abandoned in flight, or ``None``. + + Its start and length, m, while the state is neither of its ends. + """ + return self._march.in_flight + def status(self) -> SessionStatus: """Return a read-only summary of the session. @@ -217,7 +680,7 @@ def status(self) -> SessionStatus: Position, plane, attempts and lifecycle state. """ return SessionStatus( - z=self._z, + z=self._here(), plane_index=self._index, attempts=self._attempts, rejected=self._rejected, @@ -225,7 +688,7 @@ def status(self) -> SessionStatus: outcome=self._ledger.outcome, ) - def advance( # noqa: PLR0911 - one return per barrier kind + def advance( self, *, work_limit: int = DEFAULT_WORK_LIMIT, @@ -233,11 +696,11 @@ def advance( # noqa: PLR0911 - one return per barrier kind ) -> EventBatch: """Run to the next barrier and report it. - A batch ends at the next observation, snapshot or terminal outcome, or at a - bounded yield: once `work_limit` attempts are made or `deadline` has passed, - the march returns at its next accepted endpoint, exactly as at a natural stop, - and the batch reports only progress. Nothing numerical depends on where a - yield falls. + A batch ends at the next observation, snapshot, warning or terminal outcome, + or at a bounded yield: once `work_limit` attempts are made or `deadline` has + passed, the march returns at its next accepted endpoint, exactly as at a + natural stop, and the batch reports only progress. Nothing numerical depends + on where a yield falls. Parameters ---------- @@ -252,62 +715,23 @@ def advance( # noqa: PLR0911 - one return per barrier kind The events, ending at a barrier. """ self._ledger.check_advance() + # `session.cpp`'s order: the owed launch plane, a warning's continuation, the + # monitor's attachment, a latched snapshot at an endpoint, completion, then + # the march to the next plane. if self._launch_pending: self._launch_pending = False return self._observation(ObservationKind.LAUNCH, -1, EMPTY_SUMMARY) - if not self._attached: - self._attach_monitor() - host = self._host - if self._latch.pending is not None and self._at_endpoint(): - return self._snapshot() - if self._index >= self._planes.size: - return self._complete() - target = float(self._planes[self._index]) - if self._latch.pending is not None and host.holding_plane: - # The march restores the endpoint ahead of the plane it holds, and halts - # there if the target lies beyond: planes closer than the steps would - # otherwise put off the snapshot with every step (SEP 47 section 5.5). - host.halt_ahead() started = time.perf_counter() limit = self._counter.count + max(int(work_limit), 1) - host.set_halt_check(YieldDue(self._counter, limit, started, deadline)) + self._halt_check = YieldDue(self._counter, limit, started, deadline) try: - step = self._driver.propagate_to(target) + return self._advance() except StopRequested as error: return self._terminal(Outcome.STOPPED, error) except Exception as error: return self._terminal(Outcome.FAILED, error) finally: - host.set_halt_check(None) - self._account(step) - summary = merge_summaries(self._summary, step) - self._summary = summary - if self._latch.pending is None and not host.halted: - # A yield latched that the target came first. - host.clear_halt() - if bool(np.isclose(step.z, target, rtol=1e-12, atol=0.0)): - plane = self._index - self._index += 1 - self._summary = None - return self._observation(ObservationKind.PLANE, plane, summary) - if host.halted: - # A halt short of the target is never a step plane: the driver counts a - # step plane first and stops there unhalted, so a coincident plane is - # observed below and the latch, still set, is serviced at the next advance - # (SEP 47 section 5.3: a coincident plane's transaction precedes the - # snapshot). - if self._latch.pending is not None: - return self._snapshot() - # A bounded yield: no barrier, only progress; the plane goes on later. - host.clear_halt() - history, rows = self._chunk() - return self._issue([Progress(self._z, history, rows)]) - self._summary = None - return self._observation( - ObservationKind.STEP if self._step_planes else ObservationKind.NATURAL, - self._index, - summary, - ) + self._halt_check = None def acknowledge(self, receipt: Receipt) -> None: """Release the pending batch and allow advancing across its barrier. @@ -365,7 +789,7 @@ def noise_phase(self, ticket: ExportTicket) -> np.ndarray | None: def pending_ticket(self) -> ExportTicket | None: """Return a ticket for the committed state after a failure outside the session. - A service failure, or a signal raised while the driver held no uncommitted + A service failure, or a signal raised while the session held no uncommitted state, leaves the field where the last commit put it. When a batch is pending, the ticket is bound to it; otherwise a failed terminal batch is issued, so the state can be exported for a terminal checkpoint and nothing advances again. @@ -375,15 +799,14 @@ def pending_ticket(self) -> ExportTicket | None: solprop.backends.events.ExportTicket or None The ticket, or ``None`` when the session is closed or its state poisoned. """ - if self.closed or self._host.in_flight is not None: + if self.closed or self.in_flight is not None: return None if self._ledger.state is not SessionState.PENDING: self._generation += 1 - self._z = self._host.position self._ledger.issue(outcome=Outcome.FAILED) receipt = self._ledger.pending assert receipt is not None - return ExportTicket(receipt, self._generation, self._z) + return ExportTicket(receipt, self._generation, self._here()) def request_snapshot(self) -> SnapshotReceipt: """Latch a snapshot for the next eligible accepted endpoint. @@ -396,7 +819,8 @@ def request_snapshot(self) -> SnapshotReceipt: self._ledger.check_open() receipt = self._latch.request() if not receipt.coalesced: - self._host.request_halt() + # The halt latch the march's endpoints read (`_halted_short`). + self._halt_requested = True return receipt def continue_monitor(self, continuation: Mapping[str, object]) -> None: @@ -449,6 +873,11 @@ def undelivered(self, ticket: ExportTicket) -> tuple[BackendHistory, StepStats]: def march_snapshot(self, ticket: ExportTicket) -> MarchSnapshot | None: """Return the method history at a pending observation, when the march has one. + The march's part of the snapshot, the committed state and the history's rows, + at an accepted endpoint: ``None`` while a dense observation holds the state + between endpoints, for a march that keeps no history, and before the first + sample. + Parameters ---------- ticket : solprop.backends.events.ExportTicket @@ -458,32 +887,62 @@ def march_snapshot(self, ticket: ExportTicket) -> MarchSnapshot | None: ------- solprop.output.records.MarchSnapshot or None The history at the ticket's position, or ``None``. + + Raises + ------ + solprop.exceptions.BackendError + If a low-storage step was abandoned in flight. """ self._ledger.check_ticket(ticket) - snapshot = self._driver.march_snapshot() - if snapshot is None or snapshot.z != ticket.z: + self._refuse_in_flight() + march, rows = self._march, self._method.rows + if self._observed or not isinstance(march, HostAdamsMarch) or rows is None: + return None + fields = march.snapshot_fields() + if fields is None: return None - return snapshot + snapshot = MarchSnapshot( + state=np.array(self._workspace.committed(), dtype=np.complex128, copy=True), + rows=rows.export(), + **fields, + ) + return None if snapshot.z != ticket.z else snapshot def march_snapshot_nbytes(self) -> int | None: - """Return the size a method-history snapshot would have. + """Return the size a method-history snapshot would have, copying nothing. Returns ------- int or None - Bytes, or ``None`` when the march keeps no history. + The state and every row, bytes, or ``None`` where a snapshot would be + ``None``. + + Raises + ------ + solprop.exceptions.BackendError + If a low-storage step was abandoned in flight. """ - return self._driver.march_snapshot_nbytes(self._z) + self._refuse_in_flight() + march, rows = self._march, self._method.rows + if ( + self._observed + or not isinstance(march, HostAdamsMarch) + or rows is None + or not march.has_history + ): + return None + state = math.prod(self._problem.shape) * np.dtype(np.complex128).itemsize + return state + rows.nbytes() def march_export_refusal(self) -> str | None: - """Return why the march cannot export its history, or ``None``. + """Return ``None``: every march the reference admits carries its history. Returns ------- - str or None - The reason, or ``None`` when it can. + None + The Adams history exports its rows; the other marches keep none. """ - return self._driver.march_export_refusal() + return None @property def march_refusal(self) -> str | None: # numpydoc ignore=RT01 @@ -499,9 +958,13 @@ def execution_record(self) -> Mapping[str, object]: Returns ------- collections.abc.Mapping - The driver's metadata. + The backend's metadata, with this run's call or evaluation counts, and the + boundary monitor's record once it watches. """ - return self._driver.metadata() + record = self._backend.metadata() + if self._attached and self._monitor is not None: + record["boundary_monitor"] = self._monitor.summary() + return record def monitor_record(self) -> Mapping[str, object] | None: """Return the boundary monitor's record. @@ -514,13 +977,13 @@ def monitor_record(self) -> Mapping[str, object] | None: return None if self._monitor is None else self._monitor.summary() def close(self) -> None: - """Release the driver; idempotent.""" + """Release the backend when the session owns it; idempotent.""" if self._ledger.close(): - self._driver.set_stop(None) + self._stop = None if self._owns: - self._driver.close() + self._backend.close() - def __enter__(self) -> "HostSession": + def __enter__(self) -> HostSession: """Return the session. Returns @@ -550,34 +1013,786 @@ def __exit__( del kind, error, trace self.close() - # -- internals ------------------------------------------------------------------ + # -- the march's host (`MarchHost`) ----------------------------------------------- - def _attach_monitor(self) -> None: - """Restore and attach the boundary monitor after the launch plane's commit.""" - self._attached = True - if self._monitor is None: + @property + def collar_quiet(self) -> bool: # numpydoc ignore=RT01 + """Whether the stages leave a quiet in-stage temporal collar out (SEP 21).""" + return self._collar_quiet + + def poll_stop(self) -> None: + """Raise when the run's stop flag is set; called before every trial.""" + poll(self._stop) + + def cap(self, proposal: float, z: float) -> float: + """Return a proposal held to the quiet collar's, the edge's and split's limits. + + Parameters + ---------- + proposal : float + The controller's proposal, m. + z : float + Where the step starts, m. + + Returns + ------- + float + The capped proposal, m. + """ + monitor = self._monitor if self._attached else None + return step_cap(monitor, self._collar_quiet, proposal, z) + + def record(self, end: float, dz: float, norm: float, accepted: bool) -> None: + """Append one attempt to the history since the last event. + + A diverged attempt's norm (overflowed or NaN) is recorded as infinity, which + the controller never accepts. An accepted attempt's quadrature score is read + then, and one above :data:`~solprop.translate.modal.QUADRATURE_ALARM` reported + once a plane: a statistic and a log line, never a controller input. + + Parameters + ---------- + end : float + The attempt's end, m. + dz : float + Its length, m. + norm : float + The scaled error norm as executed. + accepted : bool + Whether it was accepted. + """ + if not math.isfinite(norm): + norm = math.inf + self._history.append( + (end, dz, norm, accepted, time.perf_counter() - self._clock) + ) + self._counter.step(end, dz, accepted) + if accepted: + value, z = self._workspace.score_quadrature() + if value > QUADRATURE_ALARM and not self._alarm_reported: + self._alarm_reported = True + warn_quadrature(value, z) + + def absorb(self, record: AcceptRecord) -> None: + """Accumulate an accepted step's split collar's sums (SEP 52 section 5.2). + + The removal adds over every accepted step since the previous check, which the + next reading drains; the found occupancies are the latest accepted step's. A + step that took no split sums leaves both as they were. + + Parameters + ---------- + record : solprop.backends.engines.AcceptRecord + What the step's finish reported. + """ + if record.found is not None: + self._split_removed += record.removed + self._split_found = record.found + + def stepped(self) -> None: + """Account the step just committed: the monitor, the edge, the row and stop. + + A warning on the way suspends the rest of the point's work, which the next + advance does once the warning's barrier is acknowledged. + """ + work = self._endpoint(self._target) + try: + warning = next(work) + except StopIteration as done: + self._stop_here = bool(done.value) return + self._barrier = warning + self._continuation = (work, self._endpoint_done) + self._stop_here = True + + def natural_stop(self, target: float) -> bool: + """Return whether the march stops at the endpoint just accounted. + + Parameters + ---------- + target : float + The position the march is stepping to, m. + + Returns + ------- + bool + Whether a step plane, a halt or a warning barrier stops it there. + """ + del target # the session's own, read in `stepped` + stop, self._stop_here = self._stop_here, False + self._stopped_short = self._stopped_short or stop + return stop + + # -- the schedule --------------------------------------------------------------- + + def _advance(self) -> EventBatch: # noqa: PLR0911 - one return per barrier kind + """Run to the next barrier; failures propagate to :meth:`advance`.""" + continued = self._continuation is not None + if continued: + batch = self._continue() + if batch is not None: + return batch + if not continued or not self._midplane: + if not self._attached: + batch = self._serve(self._attach(), _nothing) + if batch is not None: + return batch + if self._latch.pending is not None and self._at_endpoint(): + return self._snapshot() + if self._index >= self._planes.size: + return self._complete() + target = float(self._planes[self._index]) + # Checked from the observed position, before a held plane is restored. + self._require_state() + self._check_target(target) + restored = self._observed + if restored: + # The march is ahead of the last interpolated plane: resume it there. + dense = self._method.dense + assert dense is not None + dense.restore() + self._observed = False + z = self._march.state.z + if self._natural_due and not reached(z, target): + # The step that crossed the last plane ends before this one, and is + # observed first (`_natural_stop_due`). + self._natural_due = False + self._account_plane() + return self._at_plane(ObservationKind.STEP, self._index) + if ( + restored + and self._latch.pending is not None + and self._at_endpoint() + and not reached(z, target) + ): + # A snapshot latched while a plane was held is taken at the endpoint ahead + # of it, every plane its step crossed observed (`halt_ahead`). + return self._snapshot() + return self._march_to(target) + + def _march_to(self, target: float) -> EventBatch: + """March towards `target` and report what stopped it.""" + step = self._propagate(target) + self._account(step) + summary = merge_summaries(self._summary, step) + self._summary = summary + if self._barrier is not None: + # A warning at an endpoint the march returned at: the rest of that point's + # work, then the march, follows the barrier. + return self._warning() + return self._returned(target) + + def _returned(self, target: float) -> EventBatch: + """Report a march that returned without a barrier, its plane checked.""" + if self._latch.pending is None and not self._halted: + # A yield latched that the target came first. + self._halt_requested = False + if self._halted: + # A halt short of the target is no plane (SEP 47): no plane check there. + return self._classify(target) + return self._serve(self._plane_checks(), lambda _: self._classify(target)) # pyright: ignore[reportReturnType] + + def _endpoint_done(self, stop: object) -> EventBatch | None: + """Follow an endpoint's work a barrier suspended: stop there, or march on.""" + if not stop: + return None + target = self._target + self._stopped_short = True + # A step plane begins the next plane afresh; a halt goes on with this one. + self._midplane = self._halted + self._after_march(target) + return self._returned(target) + + def _propagate(self, target: float) -> StepSummary: + """Step the march towards `target`, landing on it exactly. + + As the step driver's ``propagate_to``: the plane's per-step latches start + afresh unless a halt or a barrier returned the last march short of it, and a + plane the march stepped across is observed inside its last step. + """ + if not self._progress_started: + # Announced at the first march, the first moment the run costs anything. + self._progress_started = True + self._counter.started( + self._here(), self._stepper.z_end, len(self._stepper.save_planes) + ) + started = time.perf_counter() + first = len(self._history) + if not self._midplane: + self._rows.reset() + # Each plane reports its own quadrature alarm. + self._workspace.reset_quadrature() + self._alarm_reported = False + self._midplane = False + self._halted = False + self._stopped_short = False + self._target = target + self._march.advance(target) + if self._halted or self._barrier is not None: + self._midplane = True + if self._barrier is None: + self._after_march(target) + taken = self._history[first:] + record = ControlRecord.from_norms( + self._stepper.controller, + [entry[2] for entry in taken if entry[3]], + n_rejected=sum(1 for entry in taken if not entry[3]), + ) + if not record.met_tolerance: + logger.warning( + "%s: a step was too coarse for the tolerance it is scaled by on the " + "way to %.6e m; the largest scaled error norm was %.3e against the " + "requested 1.0 (rtol %.1e)", + self._name, + target, + record.max_norm, + record.requested_rtol, + ) + logger.debug( + "%s: reached %.6e m in %d steps (%d rejected), achieved/requested " + "tolerance ratio %s", + self._name, + self._march.state.z, + record.n_accepted + record.n_rejected, + record.n_rejected, + # 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}", + ) + return StepSummary( + z=self._here(), + n_steps=len(taken), + n_rejected=record.n_rejected, + max_norm=record.max_norm, + mean_norm=record.mean_norm, + wall_time=time.perf_counter() - started, + met_tolerance=record.met_tolerance, + ) + + def _after_march(self, target: float) -> None: + """Observe a plane a march stepped across; settle a step plane owed there.""" + z = self._march.state.z + dense = self._method.dense + if not self._stopped_short and dense is not None and dense.crosses(z, target): + # `_observe_inside` and the Adams march's observation: the state becomes + # the crossing step's interpolated field at the plane, the committed state + # held aside, and the plane is observed there (SEP 47 section 5.3). + dense.observe(target) + self._observed = True + self._observed_z = target + if isinstance(self._march, HostAdamsMarch): + self._march.ledger.dense_observations += 1 + if self._natural_due and reached(self._here(), target) and not self._observed: + # The step owed as a step plane ends on the target itself, whose plane + # observes it: it is not observed a second time there. + self._natural_due = False + + def _classify(self, target: float) -> EventBatch: + """Report what the march stopped at: a plane, a halt or a step plane.""" + summary = self._summary + assert summary is not None + if bool(np.isclose(self._here(), target, rtol=1e-12, atol=0.0)): + plane = self._index + self._index += 1 + self._summary = None + return self._observation(ObservationKind.PLANE, plane, summary) + if self._halted: + # A halt short of the target is never a step plane: a step plane is counted + # first and stops the march unhalted, so a coincident plane is observed + # and the latch, still set, is serviced at the next advance (SEP 47 section + # 5.3: a coincident plane's transaction precedes the snapshot). + if self._latch.pending is not None: + return self._snapshot() + # A bounded yield: no barrier, only progress; the plane goes on later. + self._halt_requested = False + history, rows = self._chunk() + return self._issue([Progress(self._here(), history, rows)]) + self._summary = None + return self._observation( + ObservationKind.STEP if self._step_planes else ObservationKind.NATURAL, + self._index, + summary, + ) + + def _at_plane(self, kind: ObservationKind, plane: int) -> EventBatch: + """Check the boundaries at a plane short of the next, then observe it.""" + summary = merge_summaries( + self._summary, dataclasses.replace(EMPTY_SUMMARY, z=self._here()) + ) + + def _observe(_: object) -> EventBatch: + self._summary = None + return self._observation(kind, plane, summary) + + batch = self._serve(self._plane_checks(), _observe) + assert batch is not None + return batch + + def _account_plane(self) -> None: + """Begin the observation of a step plane owed at an endpoint already reached.""" + self._rows.reset() + self._workspace.reset_quadrature() + self._alarm_reported = False + self._generation += 1 + + def _natural_stop(self, target: float) -> bool: + """Count an accepted step; return whether to stop at its end to save it. + + With ``step_planes = k`` the end of every ``k``-th accepted step since the load + is a plane (SEP 14 phase 3): the march returns there, short of its target. A + step that lands on the target is saved as the target; one that crosses a + densely observed target is saved after it, at the next advance. + """ + self._natural_count += 1 + z = self._march.state.z + stop = natural_stop(self._stepper.step_planes, self._natural_count, z, target) + if stop is None: + return self._halted_short(z, target) + if not stop: + # A step that crossed a densely observed target is saved after it. + self._natural_due = not reached(target, z) + return stop + + def _halted_short(self, z: float, target: float) -> bool: + """Return whether a halt -- a snapshot or a yield -- stops the march at `z`.""" + if reached(z, target): + return False + check = self._halt_check + if check is not None and not self._halt_requested and check(): + self._halt_requested = True + if self._halt_requested: + self._halted = True + return self._halt_requested + + def _at_endpoint(self) -> bool: + """Return whether the state stands at an accepted endpoint of this session.""" + # The starting position is no accepted endpoint of this session: an Adams + # march holds no history there to snapshot. + return self._stepped and not self._observed + + def _here(self) -> float: + """Return the observed position: a held dense plane's, else the march's.""" + return self._observed_z if self._observed else self._march.state.z + + # -- the boundary monitor and the transverse edge -------------------------------- + + def _serve( + self, work: _Work, then: Callable[[object], EventBatch | None] + ) -> EventBatch | None: + """Run a point's work to its next warning, or to its end and what follows.""" + try: + warning = next(work) + except StopIteration as done: + return then(done.value) + self._barrier = warning + self._continuation = (work, then) + return self._warning() + + def _continue(self) -> EventBatch | None: + """Resume the point's work a warning barrier suspended.""" + assert self._continuation is not None + work, then = self._continuation + self._continuation = None + return self._serve(work, then) + + def _drained(self) -> Generator[Warning]: + """Yield the warnings the monitor and the edge put in the sink, in order.""" + sink = self._sink + while sink: + yield sink.pop(0) + + def _attach(self) -> _Work: + """Restore and attach the boundary monitor after the launch plane's commit. + + The launch is recorded and judged now; every committed step is then accounted + after the state is finished and the position advanced (:meth:`_endpoint`). + """ + self._attached = True + monitor = self._monitor + if monitor is None: + return None resume = self._monitor_resume if resume is not None: - self._monitor.resume( + monitor.resume( resume.get("record"), # pyright: ignore[reportArgumentType] plane=bool(resume.get("plane", False)), unwatched=resume.get("unwatched", ()), # pyright: ignore[reportArgumentType] ) - self._driver.attach_monitor(self._monitor) + n_t = self._problem.grids.n_t + n_modes, _, _ = self._problem.shape + columns = monitor.columns + given = None if columns is None else columns.shape + if monitor.weights.shape != (4, n_t) or given not in {None, (n_modes,)}: + msg = ( + f"{self._name}: the boundary monitor's weights {monitor.weights.shape} " + f"or columns {given} do not match the grid's {n_t} samples and the " + f"state's {n_modes} modes" + ) + raise BackendError(msg) + if monitor.split: + # The split collar's crossing limit is read again at every check. + monitor.crossing = self._problem.split_crossing + monitor.sink = self._sink + if monitor.transverse is not None: + monitor.transverse.sink = self._sink + self._bind_monitor(monitor) + workspace = self._workspace + monitor.launch(self._energies(), self._here(), floor=workspace.input_floor) + self._set_collar_quiet(monitor.collar_quiet) + yield from self._drained() + # A resumed fixed schedule is held to the state it resumes from at once. + self._refuse_scheduled_crossing(monitor) + edge = monitor.transverse + if edge is not None: + floor = workspace.input_floor + schedule = self._stepper.schedule + self._require_state() + edge.launch( + workspace.edge_reading( + edge, + # A resumed launch reads no share, but continues the current. + full=not edge.resumed, + current=edge.every_step and edge.resumed, + ), + self._here(), + noise=None if floor is None else np.asarray(floor), + clean_columns=workspace.clean_columns(edge), + steps=None if schedule is None else np.asarray(schedule.steps), + reads=self.reads_transverse_edge, + declared=_declared_discard(self._problem), + ) + yield from self._drained() + return None + + def _endpoint(self, target: float) -> _Work: + """Account the step just committed (:meth:`_account_step`), then its stop.""" + yield from self._account_step() + return self._natural_stop(target) + + def _account_step(self) -> _Work: + """Account the step just committed, after the engine's accept and the move. + + The boundary monitor's check or skip, as its cadence asks, with the transverse + edge's read where due, then the periodic statistics row when the step is the + period-th. It is the only point at which the state and the position both + describe the step just committed. + """ + monitor = self._monitor if self._attached else None + if monitor is not None: + if monitor.due(self._march.state.z): + yield from self._check(monitor) + else: + monitor.skip(self._march.state.z) + yield from self._read_transverse(monitor, plane=False) + if self._row_spec is not None: + self._accepted_steps += 1 + if self._accepted_steps % self._row_period == 0: + # The attempt this row belongs to is the one just recorded, counted in + # the chunk; -1 when a warning barrier delivered it, as native's. + z = self._march.state.z + self._rows.append( + z, + len(self._history) - 1, + self._workspace.stats(self._row_spec, z), + ) + return None + + def _plane_checks(self) -> _Work: + """Close the boundary monitor's row for the plane just reached (SEP 21, D5). + + A plane's state is checked even when its last step was not. + """ + monitor = self._monitor if self._attached else None + if monitor is None: + return None + if monitor.stale: + yield from self._check(monitor, plane=True) + yield from self._read_transverse(monitor, plane=True) + monitor.plane(self._here()) + return None + + def _finish(self) -> _Work: + """Run the monitor's final check (`BoundaryMonitor.finish`).""" + monitor = self._monitor + if monitor is not None and self._attached: + monitor.finish() + yield from self._drained() + return None + + def _check(self, monitor: BoundaryMonitor, *, plane: bool = False) -> _Work: + """Book a reading of the committed state with the monitor (SEP 45 4.10). + + - ``plane``: true for a saved plane's check of a step the monitor skipped. + """ + self._require_state() + z = self._here() + monitor.step(self._energies(), z, plane=plane) + self._set_collar_quiet(monitor.collar_quiet) + yield from self._drained() + self._refuse_scheduled_crossing(monitor, z=z) + + def _read_transverse(self, monitor: BoundaryMonitor, *, plane: bool) -> _Work: + """Read the transverse edge where its spacing or a saved plane asks (SEP 40). + + - ``plane``: whether a saved plane has just been reached, which is always read. + """ + edge = monitor.transverse + if edge is None: + return None + z = self._here() + # Read before the next step would carry past the read (`TransverseEdge.due`). + due = edge.due(z, self._next_step()) + # A plane the step that reached it already read has nothing to add. + read = (plane or due) and edge.wants_read(z) + # A collar's inward current accumulates at every committed step. + accumulate = edge.every_step and not plane + if not (read or accumulate): + return None + self._require_state() + reading = self._workspace.edge_reading(edge, faces=read, current=accumulate) + if accumulate: + assert reading.current is not None + edge.step(reading.current, z) + yield from self._drained() + if read: + edge.read(reading, z) + yield from self._drained() + return None + + def _next_step(self) -> float: + """Return the step the march takes next, m. + + A replay takes its schedule's and never updates the proposal, which stays + ``dz_init``: read from that, an edge read comes early or late by the + difference. Zero past the schedule's end. + """ + schedule = self._stepper.schedule + state: MarchState = self._march.state + if schedule is None: + return state.proposal + if state.cursor >= schedule.n_steps: + return 0.0 + return float(schedule.steps[state.cursor]) + + def _bind_monitor(self, monitor: BoundaryMonitor | None) -> None: + """Read a monitor's energies from now on, or stop; either empties the sums. + + The workspace takes the split's sums at each accepted step's finish while a + monitor of that scheme is bound (SEP 52 section 5.2). + """ + self._split_removed = 0.0 + self._split_found = None + self._workspace.bind_monitor(monitor) + + def _energies(self) -> BoundaryEnergies: + """Return the monitor's reading of the state, draining the split's removal. + + The workspace's reading of the committed state (its energy, its four weighted + energies and its occupancy), with what the split collar took at the accepted + steps since the previous reading and the energies of the power the last step's + split found (SEP 21, ADR-057). + """ + removed, self._split_removed = self._split_removed, 0.0 + reading = self._workspace.reading() + return BoundaryEnergies( + total=reading.total, + regions=reading.regions, + removed=removed, + found=self._split_found, + occupancy=reading.occupancy, + ) + + def _refuse_scheduled_crossing( + self, monitor: BoundaryMonitor, *, z: float | None = None + ) -> None: + """Stop a fixed schedule whose steps before the next check pass the cap. + + Translation admitted the schedule on the launch's occupancy; light that has + since spread into faster-walking bins lowers the cap, and a schedule cannot + shorten its steps (:class:`solprop.boundaries.SplitCrossing`). The cap holds + until the next check, due within + :meth:`~solprop.monitor.BoundaryMonitor.steps_to_check` steps at most, so the + longest of those is held to it. Read at the launch too, so that a resumed + schedule is held to the state it resumes from. + + - ``z``: the step's end, m; the session's position by default. + """ + schedule = self._stepper.schedule + first = self._march.state.cursor + position = self._here() if z is None else z + if schedule is None or first >= schedule.n_steps: + return + ahead = schedule.steps[first : first + monitor.steps_to_check()] + step = float(np.max(ahead)) + cap = monitor.step_cap + if step > cap: + msg = ( + f"at z = {position:.6e} m the split temporal collar's crossing limit " + f"fell to {cap:.3e} m, below the fixed schedule's step {step:.3e} m " + "before the next check: light has spread into bins that walk faster " + "than the launch's, and a step that long could carry it through the " + "collar and round the window undamped. Take shorter steps, step " + 'adaptively, or use absorber_scheme="nonlinear"' + ) + raise BoundaryError(msg) + + def _set_collar_quiet(self, quiet: bool) -> None: + """Say whether the collar is quiet, as the monitor last found it. + + The term is left out only where the route can rest it + (:func:`solprop.backends.records.collar_rests`, SEP 21 D15), and the monitor is + told what the stages do, so that it adds no removal while the term is out. + """ + quiet = quiet and collar_rests(self._problem, self._stepper) + if self._monitor is not None and self._attached: + self._monitor.note_collar(quiet) + if quiet != self._collar_quiet: + self._collar_quiet = quiet + self._workspace.collar_quiet = quiet + + # -- loading ---------------------------------------------------------------------- + + def _load(self, start: Start) -> None: + """Load the start's state and noise, and start the march afresh at it. + + The state is masked to the active band once (the operator and the prefactor + are exactly zero outside it). The ``input`` noise model adds its realisation at + the run's launch and never again; a resume, which loads a plane the run saved, + never takes it (:meth:`~solprop.backends.numpy_ref.workspace.NumpyWorkspace. + load`). The controller starts afresh from ``dz_init`` + (``docs/dev/stepper.md`` section 3), and a replay from the edge the state sits + on. Everything a march reads starts as a fresh backend's does (SEP 22 4.7): + the session's march is its own, the monitor unbound, the collar back in the + stages and the quadrature alarm forgotten. + """ + values = np.ascontiguousarray(start.take_field(), dtype=np.complex128) + if values.shape != self._problem.shape: + msg = ( + f"the initial state has shape {values.shape}, expected " + f"{self._problem.shape} from the contract" + ) + raise BackendError(msg) + position, cursor = start_position(self._problem, self._stepper, float(start.z)) + workspace = self._workspace + workspace.load(values, start.noise, z=position, resume=start.resume) + self._march.load(position, self._stepper.dz_init, cursor) + self._bind_monitor(None) + workspace.collar_quiet = False + + def _restore_ledgers( + self, logical: Mapping[str, object], atomic: Mapping[str, object] + ) -> None: + """Continue a resumed run's cumulative call counts, its history afresh. + + A Runge-Kutta or low-storage march keeps no logical ledger, so nothing is + installed for it; atomic counts go to the workspace's bound source, which + refuses them without one. + """ + if logical and isinstance(self._march, HostAdamsMarch): + self._march.restore_ledger(logical) + if atomic: + self._workspace.restore_atomic_ledger(atomic) + + def _restore_march(self, snapshot: MarchSnapshot) -> str | None: + """Continue the Adams march from a snapshot at the loaded position. + + The state is replaced by the snapshot's own, exactly as the interrupted run held + it, and the rows installed. Nothing is changed when the snapshot cannot be used. + + - Returns: ``None`` when the history was continued, otherwise why the march + starts afresh, as a resume did before snapshots were kept. + """ + march, rows = self._march, self._method.rows + if not isinstance(march, HostAdamsMarch) or rows is None: + kind = ( + "low-storage" + if isinstance(march, HostLowStorageMarch) + else "Runge-Kutta" + ) + return f"the run steps with the {kind} march, which keeps no history" + reason = march.refusal(snapshot) + if reason is not None: + return reason + try: + rows.install(snapshot.rows, self._problem.shape) + except BackendError as error: + return str(error) + self._workspace.install(np.array(snapshot.state, copy=True)) + march.continue_from(snapshot) + return None + + # -- guards ----------------------------------------------------------------------- + + def _require_state(self) -> None: + """Refuse a closed or unloaded backend, or a state left in flight.""" + if self._backend.closed: + raise BackendError("this backend is closed; its buffers were released") + self._workspace.committed() + self._refuse_in_flight() + + def _refuse_in_flight(self) -> None: + """Refuse every read or advance of a state left between two steps (SEP 24).""" + pending = self.in_flight + if pending is not None: + raise BackendError(in_flight_refusal(self._name, *pending)) + + def _check_target(self, target: float) -> None: + """Refuse a save plane behind the observed position or outside the table.""" + z = self._here() + if not math.isfinite(target): + msg = f"the save plane must be finite, got {target!r}" + raise BackendError(msg) + if target < z: + msg = ( + f"cannot propagate backwards: asked for z = {target:.6g} m from " + f"{z:.6g} m" + ) + raise BackendError(msg) + span = self._problem.linear.z_span + if target > span[1]: + msg = ( + f"z = {target:.6g} m lies beyond the operator table, which covers " + f"[{span[0]:.6g}, {span[1]:.6g}] m" + ) + raise BackendError(msg) + + # -- events ----------------------------------------------------------------------- def _account(self, summary: StepSummary) -> None: - """Advance the committed position and the state generation.""" + """Advance the committed position's generation after a march.""" self._stepped = self._stepped or summary.n_steps > summary.n_rejected - self._z = float(summary.z) self._generation += 1 - def _drain(self, *, field: bool) -> Observation: - """Observe the driver, draining its attempts and rows since the last drain. + def _observe(self, *, field: bool) -> Observation: + """Return the state at the observed position and the attempts since the last. - Every attempt is drained exactly once, so the status counts them here. + The field is the workspace's state itself, frozen and held so that an + observation takes a view of it without a copy: the next step replaces it. + With ``field=False`` nothing crosses (SEP 22 section 5.1). """ - return self._counted(self._driver.observe(field=field)) + self._require_state() + history = _history_record(self._history) + whole = self._workspace.state if field else None + if whole is not None: + hold(whole) + z = self._here() + plane = Observation( + z=z, + field=whole, + noise_phase=self._workspace.noise_phase(z) if field else None, + step_history=history, + n_steps=history.n_steps, + n_rejected=history.n_rejected, + step_stats=self._rows.drain(), + ) + self._history = [] + self._clock = time.perf_counter() + return plane + + def _drain(self, *, field: bool) -> Observation: + """Observe the state, draining the attempts and rows; count them once.""" + return self._counted(self._observe(field=field)) def _counted(self, observed: Observation) -> Observation: """Count a drained observation's attempts into the status.""" @@ -585,34 +1800,36 @@ def _counted(self, observed: Observation) -> Observation: self._rejected += observed.n_rejected return observed + def _drain_attempts(self) -> Observation: + """Drain the attempts and rows of a state left in flight, with no field.""" + entries, self._history = self._history, [] + self._clock = time.perf_counter() + history = _history_record(entries) + return Observation( + z=self._march.state.z, + field=None, + noise_phase=None, + step_history=history, + n_steps=history.n_steps, + n_rejected=history.n_rejected, + step_stats=self._rows.drain(), + ) + def _chunk(self) -> tuple[BackendHistory, StepStats]: """Drain the attempts and rows since the previous event, for the next one. - A state left in flight cannot be observed; the attempts recorded before the - abandoned step are drained from the driver's record instead - (:meth:`~solprop.backends.host.driver.HostDriver.drain_attempts`). - - Returns: the attempts and the rows (without a batch axis), delivered by exactly one event (:mod:`solprop.backends.events`). """ drained = ( - self._counted(self._host.drain_attempts()) - if self._host.in_flight is not None + self._counted(self._drain_attempts()) + if self.in_flight is not None else self._drain(field=False) ) chunks = self._fields.undelivered() chunks.append((drained.step_history, drained.step_stats)) return join_attempts(chunks) - def _at_endpoint(self) -> bool: - """Return whether the driver stands at an accepted endpoint. - - - Returns: False while a dense observation holds the state between endpoints. - """ - # The starting position is no accepted endpoint of this session: an Adams - # march holds no history there to snapshot. - return self._stepped and not self._host.holding_plane - def _issue( self, events: list[Event], *, outcome: Outcome | None = None ) -> EventBatch: @@ -624,24 +1841,25 @@ def _issue( return EventBatch(receipt, tuple(bind(event, receipt) for event in events)) def _ticket(self) -> ExportTicket: - """Return an unbound ticket for the current committed state. - - - Returns: the ticket, its receipt filled in when the batch is issued. - """ - return ExportTicket(Receipt(self._ledger.session, 0), self._generation, self._z) + """Return an unbound ticket for the current committed state.""" + return ExportTicket( + Receipt(self._ledger.session, 0), self._generation, self._here() + ) def _observation( self, kind: ObservationKind, plane: int, summary: StepSummary ) -> EventBatch: - """Observe the driver field-free and report it.""" + """Observe the state field-free, evaluate the plane's statistics, report it.""" history, rows = self._chunk() self._fields.release() try: - stats = dict(self._driver.stats(self._request.observation.stats)) + stats = dict( + self._workspace.stats(self._request.observation.stats, self._here()) + ) except Exception as error: return self._terminal(Outcome.FAILED, error, (history, rows)) event = ObservationReady( - z=self._z, + z=self._here(), kind=kind, plane_index=plane, history=history, @@ -652,6 +1870,31 @@ def _observation( ) return self._issue([event]) + def _warning(self) -> EventBatch: + """Report a boundary warning as a barrier at the committed endpoint. + + Its field can be exported for a checkpoint while the caller emits the warning, + which its filters may raise; it delivers the attempts and rows since the + previous event (SEP 47 section 5.5). + """ + warning, self._barrier = self._barrier, None + assert warning is not None + history, rows = self._chunk() + return self._issue( + [ + ServiceRequired( + kind=ServiceKind.WARNING, + z=self._here(), + message=str(warning), + category=type(warning), + ticket=self._ticket(), + history=history, + step_stats=rows, + warning=warning, + ) + ] + ) + def _snapshot(self) -> EventBatch: """Report a snapshot service request at the current accepted endpoint. @@ -660,13 +1903,13 @@ def _snapshot(self) -> EventBatch: checkpoint, and keeps them for the next plane (SEP 47 section 5.5). """ history, rows = self._chunk() - self._host.clear_halt() + self._halt_requested = False self._latch.clear() return self._issue( [ ServiceRequired( kind=ServiceKind.SNAPSHOT, - z=self._z, + z=self._here(), message="snapshot at an accepted endpoint", ticket=self._ticket(), history=history, @@ -677,25 +1920,25 @@ def _snapshot(self) -> EventBatch: def _complete(self) -> EventBatch: """Run the final checks and report completion.""" - chunk = self._chunk() - try: - if self._monitor is not None and self._attached: - self._monitor.finish() - except Exception as error: - return self._terminal(Outcome.FAILED, error, chunk) - return self._issue( - [ - Terminal( - Outcome.COMPLETED, - self._z, - Eligibility.ELIGIBLE, - None, - None, - *chunk, - ) - ], - outcome=Outcome.COMPLETED, - ) + + def _completed(_: object) -> EventBatch: + return self._issue( + [ + Terminal( + Outcome.COMPLETED, + self._here(), + Eligibility.ELIGIBLE, + None, + None, + *self._chunk(), + ) + ], + outcome=Outcome.COMPLETED, + ) + + batch = self._serve(self._finish(), _completed) + assert batch is not None + return batch def _terminal( self, @@ -709,13 +1952,14 @@ def _terminal( drained for an event the failure replaced; drained here otherwise. - Returns: the terminal event, with a ticket when the state is valid. """ - poisoned = self._host.in_flight is not None + self._continuation = None + self._barrier = None + poisoned = self.in_flight is not None history, rows = self._chunk() if chunk is None else chunk self._generation += 1 - self._z = self._host.position event = Terminal( outcome, - self._z, + self._here(), Eligibility.POISONED if poisoned else Eligibility.ELIGIBLE, error, None if poisoned else self._ticket(), @@ -725,6 +1969,10 @@ def _terminal( return self._issue([event], outcome=outcome) +def _nothing(_: object) -> None: + """Follow a point's work with nothing: the advance goes on.""" + + class HostPrepared: """A prepared run of a reference backend (SEP 47 section 5.2). @@ -737,7 +1985,7 @@ class HostPrepared: Parameters ---------- - driver : solprop.backends.protocol.Backend + backend : solprop.backends.protocol.Backend The constructed reference backend; it stays its caller's unless a session owns it. problem : solprop.translate.problem.PropagationProblem @@ -756,11 +2004,11 @@ class HostPrepared: """ def __init__( - self, driver: Backend, problem: PropagationProblem, request: RunRequest + self, backend: Backend, problem: PropagationProblem, request: RunRequest ) -> None: """Bind the problem and the request to the backend.""" - check_preparation(driver.name, driver.request, problem, request) - self._driver = driver + check_preparation(backend.name, backend.request, problem, request) + self._backend = backend self._problem = problem self._request = request self._closed = False @@ -768,7 +2016,7 @@ def __init__( @property def backend(self) -> str: # numpydoc ignore=RT01 """Registered name of the backend that prepared it.""" - return self._driver.name + return self._backend.name def start( self, @@ -809,7 +2057,7 @@ def start( msg = "the prepared execution is closed" raise SessionError(msg) return HostSession( - self._driver, + self._backend, self._problem, self._request, start, @@ -827,7 +2075,7 @@ def metadata(self) -> Mapping[str, object]: collections.abc.Mapping The backend's own (:meth:`solprop.backends.protocol.Backend.metadata`). """ - return self._driver.metadata() + return self._backend.metadata() def memory_ledger(self) -> Mapping[str, int]: """Return every retained buffer by name, bytes. @@ -837,7 +2085,7 @@ def memory_ledger(self) -> Mapping[str, int]: collections.abc.Mapping The backend's ledger. """ - return self._driver.memory_ledger() + return self._backend.memory_ledger() def close(self) -> None: """Refuse further starts and close the backend it was prepared on; idempotent. @@ -848,4 +2096,27 @@ def close(self) -> None: if self._closed: return self._closed = True - self._driver.close() + self._backend.close() + + +def _declared_discard(problem: PropagationProblem) -> bool: + """Return whether a run declared content above ``discard_above`` (SEP 40 5.3).""" + design = transverse_of(problem.route) + return design is not None and design.specification.discard_above is not None + + +def _history_record( + entries: Sequence[tuple[float, float, float, bool, float]], +) -> BackendHistory: + """Return the attempts since the last observation as a held history record. + + - ``entries``: one ``(z, dz, error_norm, accepted, wall_time)`` per attempt. + """ + columns = list(zip(*entries, strict=True)) if entries else [()] * 5 + return BackendHistory( + z=hold(np.array(columns[0], dtype=np.float64)), + dz=hold(np.array(columns[1], dtype=np.float64)), + error_norm=hold(np.array(columns[2], dtype=np.float64)), + accepted=hold(np.array(columns[3], dtype=np.bool_)), + wall_time=hold(np.array(columns[4], dtype=np.float64)), + ) diff --git a/src/solprop/backends/memory.py b/src/solprop/backends/memory.py index 21be409d8..ed5ca8b29 100644 --- a/src/solprop/backends/memory.py +++ b/src/solprop/backends/memory.py @@ -243,8 +243,8 @@ def low_storage_flows( """Return how many flow volumes a compiled backend's low-storage march holds. The one predicate the engines share (SEP 24 section 4.3): with - ``propagator_mode="auto"`` resolved for this march as - ``HostDriver._propagator_mode`` resolves it on a CPU, a tabulated constant operator + ``propagator_mode="auto"`` resolved for this march as the reference resolves it + on a CPU (``NumpyRefBackend._propagator_mode``), a tabulated constant operator -- every separable one included, whose ``phi_representation`` is ``"separable"`` -- holds one volume, ``exp(h_t D / 2)``; a tabulated varying operator holds the step's ``P`` and ``Q``; recomputing holds none. A native device build resolves diff --git a/src/solprop/backends/numpy_ref/backend.py b/src/solprop/backends/numpy_ref/backend.py index 94e23a878..aebd9f313 100644 --- a/src/solprop/backends/numpy_ref/backend.py +++ b/src/solprop/backends/numpy_ref/backend.py @@ -6,12 +6,14 @@ One :class:`NumpyRefBackend` steps one problem in plain NumPy. It builds the workspace that holds the state and does every state-sized operation -(:class:`~solprop.backends.numpy_ref.workspace.NumpyWorkspace`), the engines a march -asks of it (:class:`~solprop.backends.numpy_ref.engines.NumpyRungeKutta`, -:class:`~solprop.backends.numpy_ref.multistep.HostHistory`, -:class:`~solprop.backends.low_storage.HostLowStorage`) and the run's march, and keeps -``prepare``, the metadata, the memory ledger, the timing probe and ``close``. The step -control follows ``docs/dev/stepper.md`` section 3 exactly: the controller's +(:class:`~solprop.backends.numpy_ref.workspace.NumpyWorkspace`) and, for each run, the +engines a march asks of it (:class:`~solprop.backends.numpy_ref.engines. +NumpyRungeKutta`, :class:`~solprop.backends.numpy_ref.multistep.HostHistory`, +:class:`~solprop.backends.low_storage.HostLowStorage`), the run's march and its dense +output (:meth:`NumpyRefBackend.method`); it keeps ``prepare``, the metadata, the +memory ledger, the timing probe and ``close``. Every run is the reference's own +session's (:class:`~solprop.backends.host.session.HostSession`), which schedules it. +The step control follows ``docs/dev/stepper.md`` section 3 exactly: the controller's *proposal* is its state, the executed step's own norm decides acceptance and is what the history records, and the equivalent norm of the proposal is what the controller and a rejection see. @@ -19,7 +21,7 @@ import logging from collections.abc import Mapping, Sequence -from typing import Literal +from typing import TYPE_CHECKING, Literal, cast import numpy as np from jaxtyping import Complex @@ -29,27 +31,32 @@ refuse_carrier_frame, refuse_formulation, ) -from solprop.backends.host.driver import HostDriver from solprop.backends.host.low_storage import HostLowStorageMarch from solprop.backends.host.runge_kutta import RungeKuttaMarch +from solprop.backends.host.session import HostMethod, HostPrepared, start_position +from solprop.backends.ledger import CallLedger from solprop.backends.low_storage import HostLowStorage +from solprop.backends.node_chunk import NodeChunkPlan, plan_node_chunk from solprop.backends.numpy_ref.engines import NumpyRungeKutta from solprop.backends.numpy_ref.workspace import ( BlockResidual, NumpyWorkspace, SourceTables, ) +from solprop.backends.protocol import TimingProbe from solprop.backends.records import adams_policy, runge_kutta_policy -from solprop.backends.session import ExecutionOptions +from solprop.backends.session import ExecutionOptions, PreparedExecution, Start from solprop.exceptions import BackendError from solprop.grid import TimeGrid from solprop.modes.protocol import Mode from solprop.profiles import ZProfile from solprop.stepper.low_storage import LowStorageRungeKutta from solprop.stepper.multistep import Multistep +from solprop.translate.plasma_source import plasma_source_record from solprop.translate.problem import ( MAX_N_POL, PropagationProblem, + PropagatorMode, StepperSettings, validate_run, ) @@ -63,12 +70,15 @@ from solprop.translate.run_request import RunRequest from solprop.translate.tdse import TDSEBinding +if TYPE_CHECKING: + from solprop.backends.protocol import Backend + __all__ = ["BlockResidual", "NumpyRefBackend", "SourceTables"] logger = logging.getLogger(__name__) -class NumpyRefBackend(HostDriver[Complex[np.ndarray, "n_modes n_pol n_omega"]]): +class NumpyRefBackend: """Propagate one Kerr and plasma problem with interaction-picture DOPRI5. The oracle of ``docs/dev/backends.md`` section 2. It implements @@ -89,7 +99,7 @@ class NumpyRefBackend(HostDriver[Complex[np.ndarray, "n_modes n_pol n_omega"]]): output layer converts on the way to disk and the processing accessors on the way to a user. - **The grid.** :meth:`stats` delegates to :func:`solprop.stats.collect`, which needs + **The grid.** The statistics delegate to :func:`solprop.stats.collect`, which needs a :class:`solprop.grid.TimeGrid`; the kernel contract carries the array group :class:`solprop.translate.masks.Grids` and no grid object, so the grid is supplied here instead. This is a known gap in the contract. @@ -104,7 +114,7 @@ class NumpyRefBackend(HostDriver[Complex[np.ndarray, "n_modes n_pol n_omega"]]): before anything is allocated: validation is the backend's defence, not the caller's courtesy. grid : solprop.grid.TimeGrid, optional - The grid the state lives on, needed only by :meth:`stats`. + The grid the state lives on, needed only by the statistics. modes : collections.abc.Sequence, optional The propagated modes, in state order, needed only by the ``zdw`` statistic. profiles : collections.abc.Mapping, optional @@ -116,6 +126,16 @@ class NumpyRefBackend(HostDriver[Complex[np.ndarray, "n_modes n_pol n_omega"]]): The run's execution options, from which the node chunk is planned; ``None`` for the automatic choice. + Attributes + ---------- + name : str + The registry name, ``"numpy_ref"``. + reads_transverse_edge : bool + True: the reference reads a free-space run's transverse edge on the host. + helpers : solprop._helpers.Helpers + The uncompiled stage-table and Adams-basis evaluations, ``PLAIN``, which the + engines and marches are passed rather than choosing one (SEP 29 section 6.6). + Raises ------ BackendError @@ -137,14 +157,17 @@ class NumpyRefBackend(HostDriver[Complex[np.ndarray, "n_modes n_pol n_omega"]]): ... controller=PIController(rtol=1e-8, atol=1e-16), ... save_planes=[0.01], dz_max=0.01, dz_init=1e-3, ... density=1.0, shock=False, prefactor_index=1.0) + >>> from solprop.backends.session import Start >>> backend = NumpyRefBackend(problem, request, grid=grid) - >>> backend.set_initial(problem.initial.field0, None) - >>> summary = backend.propagate_to(0.01) - >>> summary.z, summary.n_rejected, summary.met_tolerance - (0.01, 0, True) - >>> backend.observe().field.shape - (1, 1, 768) - >>> backend.close() + >>> session = backend.prepare(problem, request).start(Start.entrance(problem)) + >>> kinds = [] + >>> while not session.finished: + ... batch = session.advance() + ... kinds += [type(event).__name__ for event in batch.events] + ... session.acknowledge(batch.receipt) + >>> kinds + ['ObservationReady', 'ObservationReady', 'Terminal'] + >>> session.close() """ reads_transverse_edge = True @@ -176,9 +199,15 @@ def __init__( raise BackendError( "TDSE problems require an explicit host response binding" ) - super().__init__( - problem, request, grid=grid, modes=modes, profiles=profiles, options=options - ) + self._problem = problem + self._request = request + # The stepping policy as one record, read by the marches. + self._stepper = request.stepper + # SEP 47 section 6.5: the node chunk is an execution choice, planned from the + # problem and the options before anything is allocated. + self._options = ExecutionOptions() if options is None else options + self._chunk_plan: NodeChunkPlan = plan_node_chunk(problem, self._options) + self._closed = False self._workspace = NumpyWorkspace( problem, request, @@ -191,36 +220,16 @@ def __init__( name=self.name, ) stepper = self._stepper - self._runge_kutta_engine = self._runge_kutta(self._workspace) integrator = stepper.integrator - if isinstance(integrator, Multistep): - self._use_adams(integrator) - elif isinstance(integrator, LowStorageRungeKutta): - # The host engine is the oracle (SEP 24 section 6.5). - schedule = stepper.schedule - assert schedule is not None # the translation refused it without one - engine = HostLowStorage( - self._workspace, integrator, schedule, self._propagator_mode - ) - self._low_storage = HostLowStorageMarch( - engine, - integrator, - self._hooks, - schedule=schedule, - proposal=stepper.dz_init, - lag=stepper.controller.lag, - name=self.name, - ) - self._march = self._low_storage - else: - self._march = RungeKuttaMarch( - self._runge_kutta_engine, - runge_kutta_policy(problem, stepper), - self._hooks, - schedule=stepper.schedule, - proposal=stepper.dz_init, - name=self.name, - ) + # The Adams method and its compensation's treatment (SEP 16 Q8), which a test + # witness may switch (`_use_adams`). + self._adams_method: Multistep | None = ( + integrator if isinstance(integrator, Multistep) else None + ) + self._compensation: Literal["transported", "untransported"] = "transported" + # The latest run's method, whose counts the metadata reports: a session's or the + # timing probe's, each built afresh (SEP 22 section 4.7). + self._run = self.method(None) if logger.isEnabledFor(logging.DEBUG): logger.debug( "numpy_ref: %s grid, shape %s, %d Phi intervals, %s propagators, " @@ -232,6 +241,76 @@ def __init__( "replayed" if stepper.schedule is not None else "adaptive", ) + # --- the lowering of one run --------------------------------------------------- + + def method(self, host: object) -> HostMethod: + """Return a fresh march for one run, its dense output and its history's rows. + + Each run steps with engines and a march of its own, over the backend's + workspace, so that a backend loaded again repeats a fresh backend's run + (SEP 22 section 4.7): its call ledger, its counts, its held trial and its + dense output start afresh. The run's session is the march's host. + + Parameters + ---------- + host : object + The run's session, the march's + :class:`~solprop.backends.host.marches.MarchHost`; ``None`` for a march + that never steps. + + Returns + ------- + solprop.backends.host.session.HostMethod + The march, with its dense output when the run interpolates its planes and + the Adams history's rows. + """ + stepper = self._stepper + integrator = stepper.integrator + if self._adams_method is not None: + method = self._adams(self._adams_method, host) + elif isinstance(integrator, LowStorageRungeKutta): + # The host engine is the oracle (SEP 24 section 6.5). + schedule = stepper.schedule + assert schedule is not None # the translation refused it without one + engine = HostLowStorage( + self._workspace, integrator, schedule, self._propagator_mode + ) + method = HostMethod( + HostLowStorageMarch( + engine, + integrator, + host, + schedule=schedule, + proposal=stepper.dz_init, + lag=stepper.controller.lag, + name=self.name, + ) + ) + else: + method = self._runge_kutta_method(host) + self._run = method + return method + + def _runge_kutta_method(self, host: object) -> HostMethod: + """Return the Runge-Kutta march over a fresh engine, and its dense output.""" + from solprop.backends.numpy_ref.dense import ( # noqa: PLC0415 - it builds on the engines + RungeKuttaDense, + ) + + stepper = self._stepper + engine = self._runge_kutta(self._workspace) + policy = runge_kutta_policy(self._problem, stepper) + march = RungeKuttaMarch( + engine, + policy, + host, + schedule=stepper.schedule, + proposal=stepper.dz_init, + name=self.name, + ) + dense = RungeKuttaDense(self._workspace, engine) if policy.interpolate else None + return HostMethod(march, dense) + def _runge_kutta(self, workspace: NumpyWorkspace) -> NumpyRungeKutta: """Return the Runge-Kutta engine over the workspace; a test may script one.""" return NumpyRungeKutta(workspace, self._stepper.tableau) @@ -241,21 +320,29 @@ def _use_adams( method: Multistep, compensation: Literal["transported", "untransported"] = "transported", ) -> None: - """Build the Adams engine and march, and step the run with them. + """Step the next runs with this Adams method and compensation treatment. - ``compensation``: how a varying operator's linear compensation is integrated (SEP 16 Q8): ``"transported"``, the delivered treatment, or ``"untransported"``, kept as a test witness only. """ + self._adams_method = method + self._compensation = compensation + self._run = self.method(None) + + def _adams(self, method: Multistep, host: object) -> HostMethod: + """Return the Adams march over a fresh engine, its dense output and rows.""" # The engine reads this package's passes, so it is imported when a run asks # for it rather than with the package. from solprop.backends.host.adams import HostAdamsMarch # noqa: PLC0415 + from solprop.backends.numpy_ref.dense import AdamsDense # noqa: PLC0415 from solprop.backends.numpy_ref.multistep import ( # noqa: PLC0415 AdamsKernels, ExponentialKernels, HostHistory, ) + compensation = self._compensation stepper = self._stepper interpolate = bool(stepper.interpolate_planes) engine = HostHistory( @@ -281,10 +368,10 @@ def _use_adams( method, carrier=isinstance(carrier, CarrierReference) and carrier.active, ) - self._adams = HostAdamsMarch( + march = HostAdamsMarch( engine, method, - self._hooks, + host, policy=policy, field=self._workspace.committed, schedule=stepper.schedule, @@ -294,46 +381,210 @@ def _use_adams( lag=stepper.controller.lag, name=self.name, ) - self._march = self._adams + dense = AdamsDense(self._workspace, engine, march) if interpolate else None + return HostMethod(march, dense, engine.rows) + + # --- the backend protocol -------------------------------------------------------- + + @property + def request(self) -> RunRequest: # numpydoc ignore=RT01 + """Request this backend was built for. + + Its method, error control, itinerary, planes and statistics; a run adapts + it with :meth:`~solprop.translate.run_request.RunRequest.for_run`. + """ + return self._request @property def workspace(self) -> NumpyWorkspace: # numpydoc ignore=RT01 """The workspace: the state and every state-sized operation on it.""" return self._workspace + @property + def march(self) -> object: # numpydoc ignore=RT01 + """The latest run's march: a session's, the timing probe's, or a fresh one.""" + return self._run.march + + @property + def node_chunk(self) -> int: # numpydoc ignore=RT01 + """The nodes a response pass of this backend holds at once.""" + return self._chunk_plan.chunk + + @property + def chunk_plan(self) -> NodeChunkPlan: # numpydoc ignore=RT01 + """Node-chunk plan and what chose it.""" + return self._chunk_plan + + @property + def _propagator_mode(self) -> PropagatorMode: + """Return the propagator mode this run uses, the contract's ``"auto"`` resolved. + + One volume of ``exp(h D / 2)`` reused while the step holds is the cheaper + low-storage flow on a CPU, and a varying operator changes it every step (SEP 24 + section 4.3); a separable operator recomputes. + """ + asked = self._stepper.propagator_mode + if asked == "auto" and isinstance( + self._stepper.integrator, LowStorageRungeKutta + ): + return "tabulate" if self._problem.flags.constant_linop else "recompute" + if asked == "auto" and self._problem.linear.separable is not None: + return "recompute" + return self.propagator_default if asked == "auto" else asked + + def prepare( + self, problem: PropagationProblem, request: RunRequest + ) -> PreparedExecution: + """Prepare a run of this backend for one problem and request (SEP 47 5.2). + + The backend lowered the method, the error control, the itinerary, the planes + and the statistics where it was built; preparing binds the problem and the + request a run serves -- this backend's own, or one run's adaptation of it + (:meth:`~solprop.translate.run_request.RunRequest.for_run`) -- and each start + of the result opens the reference's own session + (:class:`~solprop.backends.host.session.HostSession`). + + Parameters + ---------- + problem : solprop.translate.problem.PropagationProblem + The translated problem: this backend's, or one derived from it with + another input (:func:`solprop.driver.runner.check_derived_problem`). + request : solprop.translate.run_request.RunRequest + The run's request. + + Returns + ------- + solprop.backends.session.PreparedExecution + The prepared execution. + """ + return HostPrepared(cast("Backend", self), problem, request) + + def timing_probe(self, start: Start) -> TimingProbe: + """Load a start and return single trials of this run's march from it. + + The start's field, noise, position and resume flag are loaded as a session + loads them; its method history, ledgers and monitor continuation are not read. + A Runge-Kutta trial leaves the loaded state alone; a low-storage march's step + advances the discarded registers in place, so a backend probed so is closed + afterwards (SEP 47 section 6.6). + + Parameters + ---------- + start : solprop.backends.session.Start + Where the trials start; its field is taken. + + Returns + ------- + solprop.backends.protocol.TimingProbe + The probe. + + Raises + ------ + BackendError + If the backend is closed or the start does not fit the problem. + """ + self._check_open() + values = np.ascontiguousarray(start.take_field(), dtype=np.complex128) + if values.shape != self._problem.shape: + msg = ( + f"the initial state has shape {values.shape}, expected " + f"{self._problem.shape} from the contract" + ) + raise BackendError(msg) + position, cursor = start_position(self._problem, self._stepper, float(start.z)) + self._workspace.load(values, start.noise, z=position, resume=start.resume) + self._workspace.bind_monitor(None) + self._workspace.collar_quiet = False + method = self.method(None) + march = method.march + if isinstance(march, HostLowStorageMarch): + return _TrialProbe(self, march.engine, position, cursor, low_storage=True) + engine = ( + march.engine + if isinstance(march, RungeKuttaMarch) + else self._runge_kutta(self._workspace) + ) + return _TrialProbe(self, engine, position, cursor, low_storage=False) + + def available_device_memory(self) -> int | None: + """Return None for host execution. + + Returns + ------- + int or None + None: the reference runs on the host. + """ + return None + def metadata(self) -> dict[str, object]: - """Return execution facts and cumulative logical and atomic call ledgers. + """Return what this execution was, for the run's record. + + A saved run has to say what produced it: the thread configuration alone was + measured to move one step by a factor of nine, so a result whose execution is + not recorded is not reproducible. The record is the name, the resolved + propagator mode and the node chunk; for an Adams run the latest run's + cumulative logical source calls, and otherwise its physical + ``source_evaluations`` (SEP 24 section 5); and the workspace's facts: the + benchmark-gated plasma source and a host source's ledger, execution and last + evaluation. A PEC predictor is explicitly labelled and is never reported as an + accepted-field diagnostic. Returns ------- dict - Provider-free, serializable facts. A PEC predictor is explicitly - labelled and is never reported as an accepted-field diagnostic. + JSON-serialisable scalars, keyed by name. """ - record = super().metadata() + record: dict[str, object] = { + "backend": self.name, + "propagator_mode": self._propagator_mode, + # SEP 47 section 4.3: execution metadata, outside the resume key. + **self._chunk_plan.record(), + "node_chunk": self.node_chunk, + } + if self._problem.responses.plasma_channels: + record["plasma_source"] = plasma_source_record(self._problem.grids) + march = self._run.march + if isinstance(march, RungeKuttaMarch): + engine = march.engine + record["source_evaluations"] = ( + engine.evaluations if isinstance(engine, NumpyRungeKutta) else 0 + ) + elif isinstance(march, HostLowStorageMarch): + record["source_evaluations"] = march.source_evaluations + else: + ledger: CallLedger = march.ledger + record["response_calls"] = ledger.to_record() record.update(self._workspace.metadata()) return record - def restore_call_ledgers( - self, logical: Mapping[str, object], atomic: Mapping[str, object] | None = None - ) -> None: - """Restore cumulative counters while leaving the Adams history empty. + def march_export_refusal(self) -> str | None: + """Return ``None``: every march the reference admits carries its history. + + Returns + ------- + None + The Adams engines export and install their rows; the Runge-Kutta and + low-storage marches keep none. + """ + return None + + def edge_memory(self, space: object) -> int: + """Return what reading the edge holds in the state's memory space. + + What :func:`solprop.driver.estimate.estimate` adds: it attaches no monitor. Parameters ---------- - logical : mapping - Persisted logical call counters and accepted-order record. - atomic : mapping or None, optional - Persisted atomic attempts; unused reservations are released. + space : object + The run's transverse grid. - Raises - ------ - BackendError - If a ledger is incompatible with this run. + Returns + ------- + int + Zero: a read on the host holds nothing beside the state there. """ - super().restore_call_ledgers(logical) - if atomic: - self._workspace.restore_atomic_ledger(atomic) + del space + return 0 def memory_ledger(self) -> dict[str, int]: """Return the size of every buffer the backend works in, in bytes. @@ -351,12 +602,107 @@ def memory_ledger(self) -> dict[str, int]: def close(self) -> None: """Release the buffers. Idempotent.""" self._workspace.close() - if self._low_storage is not None: - engine = self._low_storage.engine + march = self._run.march + if isinstance(march, HostLowStorageMarch): + engine = march.engine assert isinstance(engine, HostLowStorage) engine.close() self._closed = True + @property + def closed(self) -> bool: # numpydoc ignore=RT01 + """Whether the backend has released its buffers, as a failure may.""" + return self._closed + + def _check_open(self) -> None: + """Refuse a backend that has been closed.""" + if self._closed: + msg = "this backend is closed; its buffers were released" + raise BackendError(msg) + + +class _TrialProbe: + """Single trials of a loaded backend, committing nothing (SEP 47 6.6). + + The :class:`solprop.backends.protocol.TimingProbe` the backend returns. A + Runge-Kutta trial leaves the loaded state, the position and any history alone. The + low-storage march has no separate trial: its step advances the discarded registers + in place and leaves no trial field. + """ + + def __init__( + self, + backend: NumpyRefBackend, + engine: object, + z: float, + index: int, + *, + low_storage: bool, + ) -> None: + """Hold the loaded backend and its engine; no trial is taken yet.""" + self._backend = backend + self._engine = engine + self._z = z + self._index = index + self._low_storage = low_storage + self._length: float | None = None + + def trial(self, z: float | None = None, dz: float | None = None) -> None: + """Take one trial step and keep its end state for :meth:`field`. + + Parameters + ---------- + z : float or None, optional + Where the trial starts, m; the loaded position by default. + dz : float or None, optional + Its length, m, positive; the problem's ``dz_init`` by default, or the + scheduled step at the loaded position for the low-storage march. + """ + stepper = self._backend.request.stepper + start = self._z if z is None else float(z) + if self._low_storage: + schedule = stepper.schedule + assert schedule is not None # the translation refuses the march without one + index = min(self._index, schedule.n_steps - 1) + length = float(schedule.steps[index]) if dz is None else float(dz) + cast("HostLowStorage", self._engine).trial(start, length) + return + length = float(stepper.dz_init) if dz is None else float(dz) + cast("NumpyRungeKutta", self._engine).trial(start, length) + self._length = length + + def field(self) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: + """Return the last trial's end state on the host, as a kept step would be. + + The trial's state after the accepted-step boundary treatments (the band mask, + and the split-step absorber where it runs). A trial is held beside the loaded + state, so finishing it leaves the loaded state alone, and no monitor is bound, + so the finish takes no split sums. + + Returns + ------- + numpy.ndarray + An owning copy, internal units and the FFT convention, shape + ``(n_modes, n_pol, n_omega)``. + + Raises + ------ + BackendError + For the low-storage march, or with no trial since the last read-back. + """ + if self._low_storage: + msg = ( + "the low-storage march accepts its step in place and has no trial " + "field to read back" + ) + raise BackendError(msg) + if self._length is None: + raise BackendError("take a trial before reading its field") + engine = cast("NumpyRungeKutta", self._engine) + finished, _ = self._backend.workspace.finish(engine.trial_state, self._length) + self._length = None + return np.array(finished) + def _refuse_adams(problem: PropagationProblem, stepper: StepperSettings) -> None: """Refuse what the Adams march does not execute (SEP 13 sections 2 and 6.2). diff --git a/src/solprop/backends/numpy_ref/dense.py b/src/solprop/backends/numpy_ref/dense.py new file mode 100644 index 000000000..a11dcfa20 --- /dev/null +++ b/src/solprop/backends/numpy_ref/dense.py @@ -0,0 +1,319 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""The reference's dense output: a plane interpolated inside the step that crossed it. + +The counterparts of native's ``engines::RungeKuttaDense`` and ``engines::AdamsDense`` +(``native/src/dense.cpp``), which implement the session's ``Dense``: the session +(:class:`~solprop.backends.host.session.HostSession`) decides when a plane is observed +inside the last accepted step, and asks one of these to hold the committed state aside, +make the state the interpolated field there, and restore the committed state before +the march goes on (SEP 14 phase 3, ADR-036, SEP 52 section 5.2). An observation +neither rewinds the controller nor advances the history, and evaluates no source. + +- :class:`RungeKuttaDense` evaluates DOPRI5's continuous extension of Hairer, Norsett + and Wanner II.6, which the engine held when the step was accepted + (:meth:`~solprop.backends.numpy_ref.engines.NumpyRungeKutta.extend`), and carries + it to the plane by the exact linear flow. +- :class:`AdamsDense` evaluates the Adams march's interpolant over its last accepted + step: the weights at the plane's fraction from the march's record of the step + (:class:`~solprop.backends.host.adams.AcceptedStep`), its carrier rotations applied + to the samples the engine kept (SEP 35 section 4.1). +""" + +import numpy as np +from jaxtyping import Complex + +from solprop.backends.host.adams import AcceptedStep, HostAdamsMarch +from solprop.backends.numpy_ref.engines import NumpyRungeKutta +from solprop.backends.numpy_ref.multistep import ( + ExponentialKernels, + HostHistory, + _combine, + _DenseStep, + _ExponentialStep, +) +from solprop.backends.numpy_ref.workspace import NumpyWorkspace +from solprop.exceptions import BackendError +from solprop.stepper.multistep import integrated_weights, lagrange_coefficients +from solprop.stepper.schedule import reached +from solprop.stepper.tableau import extension_value + +__all__ = ["AdamsDense", "RungeKuttaDense"] + +_State = Complex[np.ndarray, "n_modes n_pol n_omega"] + + +class _Held: + """The committed state a dense observation set aside, restored afterwards.""" + + def __init__(self, workspace: NumpyWorkspace) -> None: + self._workspace = workspace + self._held: _State | None = None + + def hold(self, observed: _State) -> None: + """Set the committed state aside and make `observed` the state.""" + workspace = self._workspace + self._held = workspace.committed() + workspace.install(observed) + + def restore(self) -> None: + """Make the committed state current again.""" + held, self._held = self._held, None + if held is None: + raise BackendError("no dense observation holds the state") + self._workspace.install(held) + + +class RungeKuttaDense: + """DOPRI5's continuous extension of the last step that crossed a plane. + + Parameters + ---------- + workspace : solprop.backends.numpy_ref.workspace.NumpyWorkspace + The workspace whose state is observed. + engine : solprop.backends.numpy_ref.engines.NumpyRungeKutta + The engine that held the extension. + """ + + def __init__(self, workspace: NumpyWorkspace, engine: NumpyRungeKutta) -> None: + """Hold the workspace and the engine; nothing is observed yet.""" + self._workspace = workspace + self._engine = engine + self._held = _Held(workspace) + + @staticmethod + def crosses(position: float, target: float) -> bool: + """Return whether a march that returned at `position` stepped across `target`. + + Parameters + ---------- + position : float + The committed position, m. + target : float + The plane, m. + + Returns + ------- + bool + True past the plane's landing tolerance (``not reached(target, z)``). + """ + return not reached(target, position) + + def observe(self, position: float) -> None: + """Hold the committed state aside; make the state the field at `position`. + + Interpolated by the continuous extension and carried to `position` by the + exact linear flow; no source is evaluated. + + Parameters + ---------- + position : float + The plane, m, inside the extended step. + + Raises + ------ + BackendError + If no extension is held. + """ + extension = self._engine.extension + if extension is None: + raise BackendError("no accepted step is held for a dense observation") + workspace = self._workspace + z, dz, coefficients = extension + start = coefficients[0] + value = extension_value(coefficients, (position - z) / dz) + # A bin the linear flow attenuates or amplifies by more than an e-fold over the + # step -- the spectral collar's, outside the controlled band -- has an + # interaction-picture derivative growing exponentially across it, which no + # polynomial in theta follows: interpolated there it returns orders of + # magnitude more than the field. Its source is negligible beside its own loss, + # so the anchor's linear flow is its honest value. + stiff = ( + np.abs(np.real(workspace.delta_phi(workspace.stage_scalars(z, z + dz)))) + > 1.0 + ) + value = np.where(stiff, start, value) + self._held.hold(workspace.mask(workspace.propagator(z, position) * value)) + + def restore(self) -> None: + """Make the committed state current again.""" + self._held.restore() + + +class AdamsDense: + """The Adams march's interpolant over its last accepted step. + + Parameters + ---------- + workspace : solprop.backends.numpy_ref.workspace.NumpyWorkspace + The workspace whose state is observed. + engine : solprop.backends.numpy_ref.multistep.HostHistory + The engine that kept the step's samples. + march : solprop.backends.host.adams.HostAdamsMarch + The march whose record of the step (:attr:`~HostAdamsMarch.last_step`) gives + the weights' nodes and the carrier rotations. + """ + + def __init__( + self, workspace: NumpyWorkspace, engine: HostHistory, march: HostAdamsMarch + ) -> None: + """Hold the workspace, the engine and the march; nothing is observed yet.""" + self._workspace = workspace + self._engine = engine + self._march = march + self._exponential = engine.exponential + self._held = _Held(workspace) + + @staticmethod + def crosses(position: float, target: float) -> bool: + """Return whether a march that returned at `position` stepped past `target`. + + Parameters + ---------- + position : float + The committed position, m. + target : float + The plane, m. + + Returns + ------- + bool + True when `position` is past it. + """ + return position > target + + def observe(self, position: float) -> None: + """Hold the committed state aside; make the state the field at `position`. + + Parameters + ---------- + position : float + The plane, m, inside the last accepted step. + + Raises + ------ + BackendError + If no accepted step is held. + """ + step = self._march.last_step + if step is None: + raise BackendError("no accepted Adams step is held for a dense observation") + if self._exponential: + held = self._engine.exponential_dense + assert held is not None + observed = self._observe_exponential(held, step, position) + else: + held = self._engine.dense + assert isinstance(held, _DenseStep) + observed = self._observe_fused(held, step, position) + self._held.hold(observed) + + def restore(self) -> None: + """Make the committed state current again.""" + self._held.restore() + + def _observe_fused( + self, held: _DenseStep, step: AcceptedStep, position: float + ) -> _State: + """Return the interaction formulation's field at `position`.""" + workspace = self._workspace + theta = (position - held.z) / held.dz + weights = integrated_weights( + np.array([1.0, *step.nodes]), + theta, + check=False, + helpers=workspace.helpers, + ) + value = held.start + _combine(weights, held.slopes, held.dz) + # A bin the linear flow changes by more than an e-fold over the step (the + # spectral collar's) takes the anchor's linear flow: no polynomial follows its + # exponentially growing derivative (as for the Runge-Kutta extension). + exponent = workspace.delta_phi( + workspace.stage_scalars(held.z, held.z + held.dz) + ) + value = np.where(np.abs(np.real(exponent)) > 1.0, held.start, value) + return workspace.mask(workspace.propagator(held.z, position, hold=True) * value) + + def _observe_exponential( + self, held: _ExponentialStep, step: AcceptedStep, position: float + ) -> _State: + """Return the exponential formulation's field at `position`. + + The accepted corrector's interpolant integrated exactly against the flow to the + fraction ``xi`` of the step (SEP 16 section 4.3): + ``exp(xi x) u_n + h sum_k k! xi**(k+1) phi_{k+1}(xi x) sum_j c_jk F_j``; under + a carrier frame the samples rotated by the step's rotations, ``G_j``, the + moments at ``xi (x - sigma)`` and the factor ``exp(-sigma (1 - xi))``, with the + accepted step's ``sigma`` (SEP 35 section 4.1). Every factor is a forward flow, + so a strongly damped bin needs no guard; no source is evaluated and nothing + enters the history. + """ + # One evaluation per plane: the reference passes serve every backend. + helpers = self._workspace.helpers + kernels = ExponentialKernels(helpers=helpers) + xi = (position - held.z) / held.dz + # The accepted step's corrector, over (source, newest, ...), as its trial + # formed it. + coefficients = lagrange_coefficients( + [1.0, *step.nodes], check=False, helpers=helpers + ) + count = coefficients.shape[1] + shift, values = _rotated(step.carrier, held.values) + # Under a carrier frame (SEP 35 section 4.1) the accepted step's rotated + # samples, integrated against the moments at xi (x - sigma) and carried back + # by exp(-sigma (1 - xi)); every factor is bounded for an imaginary sigma. + moments = kernels.moments( + xi * (held.exponent if shift is None else held.exponent - shift), count + ) + scaled = moments * np.array([xi ** (k + 1) for k in range(count)]).reshape( + (count, *([1] * held.start.ndim)) + ) + increment = kernels.apply(scaled, coefficients, values, held.dz) + if shift is not None: + increment = np.exp(-shift * (1.0 - xi)) * increment + value = np.exp(xi * held.exponent) * held.start + increment + if held.compensation is not None: + nodes, terms = held.compensation + weights = integrated_weights( + np.asarray(nodes), xi, check=False, helpers=helpers + ) + # e^{(xi - theta_j) x} is a forward flow for every history sample; for + # the endpoint sample it is an inverse one, which a bin the step damps by + # more than an e-fold would amplify: such a bin takes the anchor's flow, + # as the interaction formulation's interpolant does (ADR-039). + for weight, node, term in zip(weights, nodes, terms, strict=True): + value = ( + value + + held.dz * weight * np.exp((xi - node) * held.exponent) * term + ) + damped = np.real(held.exponent) < -1.0 + value = np.where(damped, np.exp(xi * held.exponent) * held.start, value) + return self._workspace.mask(value) + + +def _rotated( + carrier: np.ndarray, values: list[_State] +) -> tuple[np.ndarray | None, list[_State]]: + """Return a step's carrier shift and its samples, rotated by its rotations. + + - ``carrier``: :meth:`~solprop.backends.engines.AdamsEngine.step_carrier`'s + packing -- the shift's imaginary part, then each history row's rotation as its + real and imaginary parts -- or empty without a carrier frame. + - ``values``: the new sample, then the history rows the step read, newest first. + - Returns: the shift, purely imaginary and shape ``(1, 1, 1)`` as the trial formed + it, or ``None``; the new sample unrotated and each history row times its factor. + """ + if carrier.size == 0: + return None, values + # As `CarrierReference.shift` forms it, so that it is the trial's own bits. + shift = 1j * np.array(carrier[0]).reshape((1, 1, 1)) + factors = [ + np.array(complex(carrier[1 + 2 * row], carrier[2 + 2 * row])).reshape((1, 1, 1)) + for row in range(len(values) - 1) + ] + return shift, [ + values[0], + *(factor * value for factor, value in zip(factors, values[1:], strict=True)), + ] diff --git a/src/solprop/backends/numpy_ref/engines.py b/src/solprop/backends/numpy_ref/engines.py index e9e9b3776..c2a9238ba 100644 --- a/src/solprop/backends/numpy_ref/engines.py +++ b/src/solprop/backends/numpy_ref/engines.py @@ -21,15 +21,13 @@ from solprop.backends.numpy_ref import passes from solprop.backends.numpy_ref.workspace import NumpyWorkspace from solprop.exceptions import BackendError -from solprop.stepper.tableau import ( - Tableau, - extension_coefficients, - extension_value, -) +from solprop.stepper.tableau import Tableau, extension_coefficients __all__ = ["NumpyRungeKutta"] _State = Complex[np.ndarray, "n_modes n_pol n_omega"] +_Extension = tuple[float, float, list[np.ndarray]] +"""A continuous extension: its step's start and length, m, and its coefficients.""" class NumpyRungeKutta: @@ -51,8 +49,9 @@ class NumpyRungeKutta: Attributes ---------- evaluations : int - Physical source evaluations of the trials since :meth:`reset`, rejected trials - included (SEP 30 records work rather than estimating it from steps). + Physical source evaluations of the trials since the engine was built, for one + run, rejected trials included (SEP 30 records work rather than estimating it + from steps). """ def __init__(self, workspace: NumpyWorkspace, tableau: Tableau) -> None: @@ -63,12 +62,6 @@ def __init__(self, workspace: NumpyWorkspace, tableau: Tableau) -> None: self._extension: tuple[float, float, list[np.ndarray]] | None = None self.evaluations = 0 - def reset(self) -> None: - """Forget the held trial and extension and the count: a state was loaded.""" - self._trial = None - self._extension = None - self.evaluations = 0 - @property def in_flight(self) -> bool: # numpydoc ignore=RT01 """Whether a trial overwrote the committed state; never, on this engine.""" @@ -211,63 +204,10 @@ def extend(self, z: float, dz: float) -> None: coefficients = extension_coefficients(self._tableau, start, self.stages, dz) self._extension = (z, dz, coefficients) - def observe(self, position: float) -> _State: - """Return the masked field at `position` inside the held extension's step. - - Interpolated by the continuous extension and carried to `position` by the - exact linear flow; no source is evaluated. - - Parameters - ---------- - position : float - The plane, m, inside the extended step. - - Returns - ------- - numpy.ndarray - The field in the state's layout. - """ - if self._extension is None: - raise BackendError("no accepted step is held for a dense observation") - workspace = self._workspace - z, dz, coefficients = self._extension - start = coefficients[0] - value = extension_value(coefficients, (position - z) / dz) - # A bin the linear flow attenuates or amplifies by more than an e-fold over the - # step -- the spectral collar's, outside the controlled band -- has an - # interaction-picture derivative growing exponentially across it, which no - # polynomial in theta follows: interpolated there it returns orders of - # magnitude more than the field. Its source is negligible beside its own loss, - # so the anchor's linear flow is its honest value. - stiff = ( - np.abs(np.real(workspace.delta_phi(workspace.stage_scalars(z, z + dz)))) - > 1.0 - ) - value = np.where(stiff, start, value) - return workspace.mask(workspace.propagator(z, position) * value) - - def hold(self) -> object: - """Return the committed state, to restore after a dense observation. - - Returns - ------- - object - The workspace's state array. - """ - return self._workspace.committed() - - def restore(self, z: float, held: object) -> None: - """Make a held or observed state the workspace's committed state. - - Parameters - ---------- - z : float - Its position, m. - held : object - The array. - """ - del z - self._workspace.install(held) # pyright: ignore[reportArgumentType] + @property + def extension(self) -> "_Extension | None": # numpydoc ignore=RT01 + """The held extension: its step's start and length, m, and its coefficients.""" + return self._extension def reading(self) -> BoundaryReading: """Return the committed state's boundary reading. diff --git a/src/solprop/backends/numpy_ref/multistep.py b/src/solprop/backends/numpy_ref/multistep.py index 47e8664de..70ca24040 100644 --- a/src/solprop/backends/numpy_ref/multistep.py +++ b/src/solprop/backends/numpy_ref/multistep.py @@ -81,6 +81,7 @@ __all__ = [ "AdamsKernels", + "AdamsRows", "CoupledBlock", "CoupledExponentialKernels", "ExponentialKernels", @@ -105,12 +106,15 @@ @dataclass class _DenseStep: - """The last accepted step, in its anchor's frame, for dense observation.""" + """The last accepted step, in its anchor's frame, for dense observation. + + Its slopes, the new source first; the observation's weights are the session's, from + the march's record of the step (:class:`solprop.backends.host.adams.AcceptedStep`). + """ z: float dz: float start: _State - nodes: np.ndarray slopes: list[_State] @@ -1112,17 +1116,19 @@ def correct( # noqa: PLR0917 - buffers are a kernel's parameters @dataclass class _ExponentialStep: - """The last accepted exponential step, for dense observation.""" + """The last accepted exponential step, for dense observation. + + Its samples as stored, the new one first; the observation's coefficients and, under + a carrier frame, its rotations are the session's, from the march's record of the + step (:class:`solprop.backends.host.adams.AcceptedStep`). + """ z: float dz: float start: _State exponent: _State - coefficients: np.ndarray values: list[_State] compensation: tuple[list[float], list[_State]] | None = None - shift: np.ndarray | None = None - """The accepted trial's carrier shift (SEP 35), ``None`` without one.""" @dataclass @@ -1271,6 +1277,150 @@ def observation( return [1.0, *self.nodes[:order]], [self.endpoint.copy(), *history] +class AdamsRows: + """The Adams history's rows, where the state lives (SEP 52 section 5.2). + + The samples a march's entries name, and for a compensated history each sample's + state, rate and frozen-residual weights: what the engine + (:class:`HostHistory`) writes at a startup and an accepted step, and what the + session exports into a snapshot and installs from one, as native's session reads + its resident rows. + + Parameters + ---------- + n_slots : int + The rows: the method's order and two more. + compensated : bool + Whether each sample's state, rate and weights are kept too. + name : str, optional + The backend's name, for messages. + + Attributes + ---------- + n_slots : int + As given. + compensated : bool + As given. + name : str + As given. + store : numpy.ndarray or None + The samples, shape ``(n_slots, n_modes, n_pol, n_omega)``; ``None`` before the + first startup. + states, rates : numpy.ndarray or None + A compensated history's per-sample states and rates, shaped as `store`. + weights : list + A frozen-residual flow's weights per sample, ``None`` where a sample has none. + """ + + def __init__( + self, n_slots: int, compensated: bool, *, name: str = "numpy_ref" + ) -> None: + """Hold no rows yet.""" + self.n_slots = n_slots + self.compensated = compensated + self.name = name + self.store: np.ndarray | None = None + self.states: np.ndarray | None = None + self.rates: np.ndarray | None = None + self.weights: list[np.ndarray | None] = [] + + def nbytes(self) -> int: + """Return the bytes :meth:`export` would copy, copying nothing. + + Returns + ------- + int + The size of every row. + """ + assert self.store is not None + rows = [self.store, *self.weights] + if self.compensated: + assert self.states is not None and self.rates is not None + rows += [self.states, self.rates] + return sum(int(row.nbytes) for row in rows if row is not None) + + def export(self) -> dict[str, np.ndarray]: + """Return copies of the rows a resume needs to continue the history. + + Returns + ------- + dict + ``"store"``, the samples; for a compensated march also ``"states"`` and + ``"rates"``, and ``"weights_"`` for each row a frozen-residual flow + weights. + """ + assert self.store is not None + rows = {"store": self.store.copy()} + if self.compensated: + assert self.states is not None and self.rates is not None + rows["states"] = self.states.copy() + rows["rates"] = self.rates.copy() + for slot, weights in enumerate(self.weights): + if weights is not None: + rows[f"weights_{slot}"] = np.array(weights, copy=True) + return rows + + def install(self, rows: Mapping[str, np.ndarray], shape: tuple[int, ...]) -> None: + """Install rows :meth:`export` returned, for a state of `shape`. + + Parameters + ---------- + rows : collections.abc.Mapping + The rows, by name. + shape : tuple of int + The state's shape. + + Raises + ------ + BackendError + If a row is missing, does not have the store's shape, or is one this + history does not keep -- the native engine's applied frozen-residual + generators (``"applied"``) among them. + """ + expected = (self.n_slots, *shape) + names = ("store", "states", "rates") if self.compensated else ("store",) + # A compensated history keeps a frozen-residual flow's weights per sample. + kept = set(names) | ( + {f"weights_{slot}" for slot in range(self.n_slots)} + if self.compensated + else set() + ) + foreign = sorted(set(rows) - kept) + if foreign: + name = self.name + if "applied" in foreign: + msg = ( + f"the {name} backend cannot continue this Adams history: the " + "snapshot holds the native engine's applied frozen-residual " + "generators ('applied'), and this engine keeps each sample's " + "weights instead" + ) + else: + msg = ( + f"the {name} backend cannot continue this Adams history: its " + f"engine keeps no {foreign} rows" + ) + raise BackendError(msg) + for name in names: + row = rows.get(name) + if row is None or row.shape != expected: + msg = ( + f"the snapshot's {name!r} rows do not fit a store of shape " + f"{expected}" + ) + raise BackendError(msg) + self.store = np.array(rows["store"], dtype=np.complex128, copy=True) + if self.compensated: + self.states = np.array(rows["states"], dtype=np.complex128, copy=True) + self.rates = np.array(rows["rates"], dtype=np.complex128, copy=True) + self.weights = [ + None + if f"weights_{slot}" not in rows + else np.array(rows[f"weights_{slot}"], copy=True) + for slot in range(self.n_slots) + ] + + class HostHistory: """The Adams history and its field arithmetic, on host arrays (SEP 16 phase 3b). @@ -1280,11 +1430,11 @@ class HostHistory: orders, the entries, rejection, restarts, the budget and the ledger -- and hands every state-sized operation to this engine over the workspace: the startup sample, a trial's predictor, source, corrector and defect norms, and the adoption and - transport of an accepted step. The engine holds the history's rows in a NumPy - store; between a trial and its acceptance it holds the trial. Beside the protocol - it still holds the last accepted step for dense observation (:meth:`hold`, - :meth:`restore`, :meth:`observe`) and the rows a snapshot carries, which SEP 52 - moves to the session. + transport of an accepted step. The engine writes the history's rows into + :class:`AdamsRows`, which the session exports and installs; between a trial and its + acceptance it holds the trial, and an interpolated run's accepted step keeps what + its dense observation reads (:attr:`dense`, :attr:`exponential_dense`; + :mod:`solprop.backends.numpy_ref.dense`). Parameters ---------- @@ -1300,6 +1450,22 @@ class HostHistory: A varying operator's compensation treatment (SEP 16 Q8). interpolate : bool, optional Whether an accepted step keeps its interpolant for dense observation. + rows : AdamsRows or None, optional + The rows to write; new ones by default. + + Attributes + ---------- + rows : AdamsRows + The history's rows. + dense : object + The interaction formulation's last accepted step, for dense observation; + ``None`` before one. + exponential_dense : object + The exponential formulation's, likewise. + compensated : bool + Whether a varying operator's linear compensation is integrated. + carrier : solprop.backends.exponential.CarrierReference or None + The exponential formulation's carrier frame; ``None`` for the interaction one. """ def __init__( @@ -1311,6 +1477,7 @@ def __init__( compensation: Literal["transported", "untransported"], *, interpolate: bool = False, + rows: AdamsRows | None = None, ) -> None: """Hold the workspace, the kernels and an empty store.""" self._workspace = workspace @@ -1338,13 +1505,14 @@ def __init__( if self.compensated and flow is not None and compensation != "transported": msg = "the untransported compensation is a witness for diagonal operators" raise BackendError(msg) - self._weights: list[np.ndarray | None] = [] + self.rows = ( + AdamsRows(method.order + 2, self.compensated, name=workspace.name) + if rows is None + else rows + ) self._trial_weights: np.ndarray | None = None - self._store: np.ndarray | None = None - self._states: np.ndarray | None = None - self._rates: np.ndarray | None = None self.dense: Any = None - self._exponential_dense: _ExponentialStep | None = None + self.exponential_dense: _ExponentialStep | None = None self._fused_trial: _FusedTrial | None = None self._exponential_trial: _ExponentialTrial | None = None # SEP 35: the carrier phase each exponential trial removes from the samples @@ -1362,42 +1530,49 @@ def __init__( # The last exponential trial's carrier shift and row rotations (SEP 35). self._carrier_rows: tuple[np.ndarray, np.ndarray] | None = None - def reset(self) -> None: - """Forget the last accepted step and any trial in flight.""" - self.dense = None - self._exponential_dense = None - self._fused_trial = None - self._exponential_trial = None - @property def n_slots(self) -> int: # numpydoc ignore=RT01 """The history store's rows: the method's order and two more.""" - return self._method.order + 2 + return self.rows.n_slots - # --- the accepted state, held across a dense observation -------------------------- + @property + def exponential(self) -> bool: # numpydoc ignore=RT01 + """Whether the exponential formulation's arithmetic steps the history.""" + return self._exponential is not None - def hold(self) -> object: - """Return the accepted state, to restore after a dense observation. + # The rows' arrays under the names the arithmetic below reads them by. - Returns - ------- - object - The backend's host copy of the accepted state. - """ - return self._workspace.committed() + @property + def _store(self) -> np.ndarray | None: + return self.rows.store - def restore(self, z: float, held: object) -> None: - """Make a held accepted state current again at `z`. + @_store.setter + def _store(self, value: np.ndarray | None) -> None: + self.rows.store = value - Parameters - ---------- - z : float - Its position, m. - held : object - What :meth:`hold` returned. - """ - del z - self._workspace.install(cast("_State", held)) + @property + def _states(self) -> np.ndarray | None: + return self.rows.states + + @_states.setter + def _states(self, value: np.ndarray | None) -> None: + self.rows.states = value + + @property + def _rates(self) -> np.ndarray | None: + return self.rows.rates + + @_rates.setter + def _rates(self, value: np.ndarray | None) -> None: + self.rows.rates = value + + @property + def _weights(self) -> list[np.ndarray | None]: + return self.rows.weights + + @_weights.setter + def _weights(self, value: list[np.ndarray | None]) -> None: + self.rows.weights = value # --- startup ---------------------------------------------------------------------- @@ -1684,7 +1859,6 @@ def fused_accept( z=trial.z, dz=trial.dz, start=trial.state.copy(), - nodes=np.array([1.0, *trial.nodes[:order]]), slopes=slopes, ) self._kernels.transport(store, keep, trial.propagator, free, trial.source) @@ -1696,121 +1870,6 @@ def _adopt(self, advanced: _State, dz: float) -> AcceptRecord: self._workspace.install(finished) return record - def value(self, slot: int) -> _State: - """Return a store row, for the history entry that names it. - - Parameters - ---------- - slot : int - The row. - - Returns - ------- - numpy.ndarray - The row itself, not a copy. - """ - assert self._store is not None - return self._store[slot] - - # --- persistence across a resume -------------------------------------------------- - - def snapshot_nbytes(self) -> int: - """Return the bytes :meth:`snapshot_rows` would copy, copying nothing. - - Returns - ------- - int - The size of every row. - """ - assert self._store is not None - rows = [self._store, *self._weights] - if self.compensated: - assert self._states is not None and self._rates is not None - rows += [self._states, self._rates] - return sum(int(row.nbytes) for row in rows if row is not None) - - def snapshot_rows(self) -> dict[str, np.ndarray]: - """Return copies of the rows a resume needs to continue the history. - - Returns - ------- - dict - ``"store"``, the samples; for a compensated march also ``"states"`` and - ``"rates"``, and ``"weights_"`` for each row a frozen-residual flow - weights. - """ - assert self._store is not None - rows = {"store": self._store.copy()} - if self.compensated: - assert self._states is not None and self._rates is not None - rows["states"] = self._states.copy() - rows["rates"] = self._rates.copy() - for slot, weights in enumerate(self._weights): - if weights is not None: - rows[f"weights_{slot}"] = np.array(weights, copy=True) - return rows - - def load_rows(self, rows: Mapping[str, np.ndarray], shape: tuple[int, ...]) -> None: - """Install rows :meth:`snapshot_rows` returned, for a state of `shape`. - - Parameters - ---------- - rows : collections.abc.Mapping - The rows, by name. - shape : tuple of int - The state's shape. - - Raises - ------ - BackendError - If a row is missing, does not have the store's shape, or is one this - history does not keep -- the native engine's applied frozen-residual - generators (``"applied"``) among them. - """ - expected = (self.n_slots, *shape) - names = ("store", "states", "rates") if self.compensated else ("store",) - # A compensated history keeps a frozen-residual flow's weights per sample. - kept = set(names) | ( - {f"weights_{slot}" for slot in range(self.n_slots)} - if self.compensated - else set() - ) - foreign = sorted(set(rows) - kept) - if foreign: - name = self._workspace.name - if "applied" in foreign: - msg = ( - f"the {name} backend cannot continue this Adams history: the " - "snapshot holds the native engine's applied frozen-residual " - "generators ('applied'), and this engine keeps each sample's " - "weights instead" - ) - else: - msg = ( - f"the {name} backend cannot continue this Adams history: its " - f"engine keeps no {foreign} rows" - ) - raise BackendError(msg) - for name in names: - row = rows.get(name) - if row is None or row.shape != expected: - msg = ( - f"the snapshot's {name!r} rows do not fit a store of shape " - f"{expected}" - ) - raise BackendError(msg) - self.reset() - self._store = np.array(rows["store"], dtype=np.complex128, copy=True) - if self.compensated: - self._states = np.array(rows["states"], dtype=np.complex128, copy=True) - self._rates = np.array(rows["rates"], dtype=np.complex128, copy=True) - self._weights = [ - None - if f"weights_{slot}" not in rows - else np.array(rows[f"weights_{slot}"], copy=True) - for slot in range(self.n_slots) - ] - # --- the exponential formulation -------------------------------------------------- def exponential_trial( # noqa: PLR0917 - called positionally @@ -1983,24 +2042,17 @@ def exponential_accept( compensation = trial.compensation if interpolate: # Copied: the store's rows are overwritten by later steps. - self._exponential_dense = _ExponentialStep( + self.exponential_dense = _ExponentialStep( z=z, dz=dz, start=trial.state.copy(), exponent=trial.exponent, - coefficients=trial.corrector[: order + 1, : order + 1].copy(), - # Under a carrier frame, the rotated samples and the accepted - # trial's own shift, held until the next accepted step. + # The samples as stored: under a carrier frame the observation + # rotates them by the step's rotations (`AcceptedStep.carrier`). values=[ trial.source.copy(), - *( - store[slot].copy() - if trial.factors is None - else trial.factors[index] * store[slot] - for index, slot in enumerate(slots[:order]) - ), + *(store[slot].copy() for slot in slots[:order]), ], - shift=trial.shift, compensation=None if compensation is None else compensation.observation( @@ -2075,94 +2127,6 @@ def _compensation_terms( # noqa: PLR0917 - called positionally helpers=self._workspace.helpers, ) - # --- dense observation ------------------------------------------------------------ - - def observe(self, position: float) -> object: - """Return the field at `position` inside the last accepted step. - - Parameters - ---------- - position : float - The observation, m, inside the last accepted step. - - Returns - ------- - object - The masked lab-frame field at `position`, as the backend holds a state: - a host array, or Kokkos's native state loaded with it. - """ - if self._exponential is not None: - return self._observe_exponential(position) - step = cast("_DenseStep | None", self.dense) - assert step is not None - workspace = self._workspace - theta = (position - step.z) / step.dz - weights = integrated_weights( - step.nodes, theta, check=False, helpers=workspace.helpers - ) - value = step.start + _combine(weights, step.slopes, step.dz) - # A bin the linear flow changes by more than an e-fold over the step (the - # spectral collar's) takes the anchor's linear flow: no polynomial follows its - # exponentially growing derivative (as for the Runge-Kutta extension). - exponent = workspace.delta_phi( - workspace.stage_scalars(step.z, step.z + step.dz) - ) - value = np.where(np.abs(np.real(exponent)) > 1.0, step.start, value) - return workspace.mask(workspace.propagator(step.z, position, hold=True) * value) - - def _observe_exponential(self, position: float) -> object: - """Return the field at `position` inside the last accepted exponential step. - - The accepted corrector's interpolant integrated exactly against the flow to the - fraction ``xi`` of the step (SEP 16 section 4.3): - ``exp(xi x) u_n + h sum_k k! xi**(k+1) phi_{k+1}(xi x) sum_j c_jk F_j``; under - a carrier frame the rotated samples ``G_j``, the moments at ``xi (x - sigma)`` - and the factor ``exp(-sigma (1 - xi))``, with the accepted step's ``sigma`` - (SEP 35 section 4.1). Every - factor is a forward flow, so a strongly damped bin needs no guard; no source - is evaluated and nothing enters the history. - - - ``position``: the observation, m, inside the last accepted step. - """ - step = self._exponential_dense - assert step is not None - # One evaluation per plane: the reference passes serve every backend. - helpers = self._workspace.helpers - kernels = ExponentialKernels(helpers=helpers) - xi = (position - step.z) / step.dz - count = step.coefficients.shape[1] - shift = step.shift - # Under a carrier frame (SEP 35 section 4.1) the accepted step's rotated - # samples, integrated against the moments at xi (x - sigma) and carried back - # by exp(-sigma (1 - xi)); every factor is bounded for an imaginary sigma. - moments = kernels.moments( - xi * (step.exponent if shift is None else step.exponent - shift), count - ) - scaled = moments * np.array([xi ** (k + 1) for k in range(count)]).reshape( - (count, *([1] * step.start.ndim)) - ) - increment = kernels.apply(scaled, step.coefficients, step.values, step.dz) - if shift is not None: - increment = np.exp(-shift * (1.0 - xi)) * increment - value = np.exp(xi * step.exponent) * step.start + increment - if step.compensation is not None: - nodes, terms = step.compensation - weights = integrated_weights( - np.asarray(nodes), xi, check=False, helpers=helpers - ) - # e^{(xi - theta_j) x} is a forward flow for every history sample; for - # the endpoint sample it is an inverse one, which a bin the step damps by - # more than an e-fold would amplify: such a bin takes the anchor's flow, - # as the interaction formulation's interpolant does (ADR-039). - for weight, node, term in zip(weights, nodes, terms, strict=True): - value = ( - value - + step.dz * weight * np.exp((xi - node) * step.exponent) * term - ) - damped = np.real(step.exponent) < -1.0 - value = np.where(damped, np.exp(xi * step.exponent) * step.start, value) - return self._workspace.mask(value) - def _trial_propagators( # noqa: PLR0917 - called positionally kernels: Any, diff --git a/src/solprop/backends/numpy_ref/populations.py b/src/solprop/backends/numpy_ref/populations.py index 5264fda8b..8af96ac07 100644 --- a/src/solprop/backends/numpy_ref/populations.py +++ b/src/solprop/backends/numpy_ref/populations.py @@ -41,7 +41,7 @@ def axis_populations( Plane position in m. axis : numpy.ndarray The mode set's synthesis on the axis at `z`, taper included, rows x and y - (``HostDriver._on_axis_synthesis``). + (``NumpyWorkspace._on_axis_synthesis``). Returns ------- diff --git a/src/solprop/backends/populations.py b/src/solprop/backends/populations.py index 2e40fdbdd..0af1d413d 100644 --- a/src/solprop/backends/populations.py +++ b/src/solprop/backends/populations.py @@ -212,7 +212,7 @@ def axis_row_matrix( The translated problem. axis : numpy.ndarray The mode set's synthesis on the axis at this position, taper included, rows x - and y (``HostDriver._on_axis_synthesis``). + and y (``NumpyWorkspace._on_axis_synthesis``). Returns ------- diff --git a/src/solprop/backends/protocol.py b/src/solprop/backends/protocol.py index b578ae50d..82356f9dd 100644 --- a/src/solprop/backends/protocol.py +++ b/src/solprop/backends/protocol.py @@ -15,8 +15,8 @@ A backend is constructed from a validated :class:`solprop.translate.problem.PropagationProblem`, takes host arrays and returns host arrays; its buffers, layout and plans are private, and the state is never a -parameter of :meth:`HostStepping.propagate_to` or :meth:`HostStepping.observe`. -Selection by name and the availability rules are in :mod:`solprop.backends.registry`. +parameter of anything a run's session is asked. Selection by name and the availability +rules are in :mod:`solprop.backends.registry`. **Sign convention.** Every complex array crossing this seam, in either direction, is in the **FFT convention** of ``docs/dev/conventions.md`` section 2, with the phase origin @@ -37,11 +37,6 @@ from solprop._ownership import frozen_copy, hold from solprop._process import parallel_rows from solprop.exceptions import BackendError -from solprop.log import ProgressReporter, StopFlag -from solprop.monitor import BoundaryMonitor -from solprop.noise import NoiseRealisation -from solprop.output.records import MarchSnapshot -from solprop.stats import StatsSpec if TYPE_CHECKING: # The session module builds on this one's records, so its start is a forward name. @@ -52,12 +47,10 @@ __all__ = [ "Backend", "BackendHistory", - "HostStepping", "Observation", "StepStats", "StepSummary", "TimingProbe", - "stepping", ] logger = logging.getLogger(__name__) @@ -487,7 +480,7 @@ def _check_counts(self) -> None: @dataclass(frozen=True, eq=False) class StepSummary: - """What one call to :meth:`HostStepping.propagate_to` cost and achieved. + """What one march of a session towards a plane cost and achieved. A handful of host scalars, so that a driver can report progress and warn about a tolerance that was not met without pulling the whole step history across the seam @@ -763,237 +756,3 @@ def close(self) -> None: def closed(self) -> bool: # numpydoc ignore=RT01 """Whether the backend has released its buffers, as a failure may.""" ... - - -@runtime_checkable -class HostStepping(Backend, Protocol): - """The host stepping seam a host-owned session drives (SEP 47 section 6.6). - - 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`) 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`. - - Examples - -------- - >>> from solprop.backends.protocol import Backend, HostStepping - >>> added = set(dir(HostStepping)) - set(dir(Backend)) - >>> sorted(name for name in added if not name.startswith("_"))[:4] - ['attach_monitor', 'in_flight', 'march_snapshot', 'march_snapshot_nbytes'] - """ - - def set_initial( - self, - field: Complex[np.ndarray, "n_modes n_pol n_omega"], - noise: NoiseRealisation | None, - *, - z: float = 0.0, - resume: bool = False, - ) -> None: - """Load a state and the noise realisation at a position, host to device, once. - - Parameters - ---------- - field : numpy.ndarray - The state, shape ``(n_modes, n_pol, n_omega)``, FFT convention. - noise : solprop.noise.NoiseRealisation or None - The realisation to carry along the run, or ``None``. - z : float, optional - The position the state belongs to, m, inside the operator table. Zero is - the entrance; a positive value is a **resume** from a plane the run reached - before, so the backend takes - its position -- and its place in a replayed schedule -- from here. A state - past the entrance already carries an ``input``-model noise realisation, and - a backend must not add one to it a second time. The step controller starts - afresh either way, so an adaptive run resumed agrees with an uninterrupted - one to the controller's tolerance and not bitwise, while a replayed - schedule agrees bitwise on a backend that recycles no stage and to - round-off on one that does (``docs/dev/stepper.md`` section 3). - resume : bool, optional - Whether `field` came back from a saved plane of this run, and so already - carries the ``input`` realisation even at the launch position, where a file - holding only that plane resumes. ``False`` by default. - """ - ... - - def set_progress(self, reporter: ProgressReporter) -> None: - """Attach the reporter the step loop calls as it goes. - - The driver attaches one before the first plane and never changes it mid-run. A - backend that steps on the host calls - :meth:`~solprop.log.ProgressReporter.step` once per attempted step, including - the rejected ones; a backend whose loop is on a device may call it once per - plane instead (``docs/dev/backends.md`` section 1). Nothing a reporter does may - change the propagation: a run with one is bitwise the run without. - - Parameters - ---------- - reporter : solprop.log.ProgressReporter - Where the step events go. :class:`solprop.log.NullReporter` is the way to - turn them off. - """ - ... - - def set_stop(self, flag: StopFlag | None) -> None: - """Attach the flag the march polls, or detach it with ``None``. - - Parameters - ---------- - flag : solprop.log.StopFlag or None - Any object with an ``is_set()`` method, such as a - :class:`threading.Event`. - """ - ... - - def attach_monitor(self, monitor: BoundaryMonitor) -> None: - """Watch the time window's edges from here on, starting with the current state. - - Parameters - ---------- - monitor : solprop.monitor.BoundaryMonitor - The monitor, fed every committed step. - """ - ... - - def propagate_to(self, z: float) -> StepSummary: - """Step the state to a position through the shared driver's marches. - - Parameters - ---------- - z : float - The save plane to reach, m. Steps land on it exactly. - - Returns - ------- - StepSummary - What the call cost and achieved. - """ - ... - - def observe(self, *, field: bool = True) -> Observation: - """Return the state at the current position, as host arrays. - - Nothing writes to the returned arrays again, the backend included: a run hands - them to its output without a copy (:func:`solprop.driver.run.run_problem`), and - a handler may keep them. A backend either returns arrays it no longer owns or - leaves the ones it returns behind, as a step that replaces its state does. - - Parameters - ---------- - field : bool, optional - Whether the field and the noise phase cross to the host; ``False`` - observes the step history alone (SEP 22 section 5.1). - - Returns - ------- - Observation - The field, the noise phase and the step history since the last call. - """ - ... - - @property - def in_flight(self) -> tuple[float, float] | None: # numpydoc ignore=RT01 - """Low-storage step a failure abandoned in flight, or ``None``. - - The step's start and length, m, while the state is neither of its ends. - """ - ... - - def stats(self, spec: StatsSpec) -> dict[str, np.ndarray]: - """Compute the requested statistics in one fused pass. - - Parameters - ---------- - spec : solprop.stats.StatsSpec - Which statistics and which windows. - - Returns - ------- - dict - Small host arrays keyed by statistic name. - """ - ... - - def restore_call_ledgers( - self, logical: Mapping[str, object], atomic: Mapping[str, object] | None = None - ) -> None: - """Restore cumulative budgets after loading a saved state. - - Parameters - ---------- - logical : mapping - Persisted logical response counters, or empty for ordinary RK runs. - atomic : mapping or None, optional - Persisted provider attempts. Numerical history always restarts fresh. - """ - ... - - def march_snapshot(self) -> MarchSnapshot | None: - """Return the Adams march's state at the accepted position, for a resume. - - Returns - ------- - solprop.output.records.MarchSnapshot or None - The snapshot, or ``None`` wherever the march has nothing to continue. - """ - ... - - def march_snapshot_nbytes(self, z: float) -> int | None: - """Return the bytes :meth:`march_snapshot` would copy at `z`, copying nothing. - - Parameters - ---------- - z : float - The position the snapshot is wanted at, m. - - Returns - ------- - int or None - The size, or ``None`` where a snapshot would be ``None`` or stand elsewhere. - """ - ... - - def restore_march(self, snapshot: MarchSnapshot) -> str | None: - """Continue the Adams march from a snapshot at the loaded position. - - Parameters - ---------- - snapshot : solprop.output.records.MarchSnapshot - The snapshot a file holds. - - Returns - ------- - str or None - ``None`` when the history was continued, otherwise why it starts afresh. - """ - ... - - -def stepping(backend: Backend) -> HostStepping: - """Return a backend as the host stepping seam it implements. - - Parameters - ---------- - backend : Backend - A backend that steps on the host: the reference, or a test's scripted one. - - Returns - ------- - HostStepping - The same object. - - Raises - ------ - solprop.exceptions.BackendError - If it does not implement the seam: the native backend runs only in its - session (SEP 47 section 6.8). - """ - if not isinstance(backend, HostStepping): - msg = ( - f"{backend.name} runs in its own session, not through the host stepping " - "seam: start a run with backend.prepare(problem, request).start(start)" - ) - raise BackendError(msg) - return backend diff --git a/src/solprop/backends/rk_core.py b/src/solprop/backends/rk_core.py index fe45141f2..0b337ada7 100644 --- a/src/solprop/backends/rk_core.py +++ b/src/solprop/backends/rk_core.py @@ -4,7 +4,7 @@ """The Runge-Kutta march's controller as functions of its policy and state (SEP 45). -The decisions of ``HostDriver._march_to`` -- the equivalent norm and acceptance of an +The decisions of the Runge-Kutta march -- the equivalent norm and acceptance of an attempt, the start-up rule, the next proposal after an accepted step and the shrink after a rejected one -- each as a function of the run's :class:`~solprop.backends.records.RungeKuttaPolicy` and the values it decides on, with diff --git a/src/solprop/backends/session_core.py b/src/solprop/backends/session_core.py index e66a51b26..430684b50 100644 --- a/src/solprop/backends/session_core.py +++ b/src/solprop/backends/session_core.py @@ -307,10 +307,10 @@ def export_weight( class ObservedField: """One committed field per ticket, shared by every export of it (SEP 47 5.4). - A session observes its driver's field once per state generation, when a consumer + A session observes its committed field once per state generation, when a consumer first asks for it; every export of that ticket reads the same observation. An - observation's arrays are read-only and nothing writes to them again - (:meth:`solprop.backends.protocol.HostStepping.observe`), so an export with nothing + observation's arrays are read-only and nothing writes to them again (the next step + replaces the state rather than writing into it), so an export with nothing to convert is that array on a spatial grid, and every other export a new array (or the caller's destination). Attempts a field fetch drains are kept for the next event's chunk. @@ -320,13 +320,13 @@ class ObservedField: problem : solprop.translate.problem.PropagationProblem The run's problem, for the true-power conversion. drain : callable - ``drain(field=True)`` observes the driver, draining its attempts. + ``drain(field=True)`` observes the committed state, draining the attempts. """ def __init__( self, problem: PropagationProblem, drain: Callable[..., Observation] ) -> None: - """Hold the problem and the driver's drain; nothing is observed yet.""" + """Hold the problem and the session's drain; nothing is observed yet.""" self._problem = problem self._drain = drain self._observed: Observation | None = None diff --git a/src/solprop/backends/sessions.py b/src/solprop/backends/sessions.py index 37ad91adc..d20f0e2b6 100644 --- a/src/solprop/backends/sessions.py +++ b/src/solprop/backends/sessions.py @@ -8,8 +8,7 @@ 47 section 5.2), ``backend.prepare(problem, request).start(start, ...)``, so a backend chooses its session and nothing here names one. The NumPy reference's prepared execution opens its own session -(:class:`solprop.backends.host.session.HostSession`, over -:class:`solprop.backends.host.driver.HostDriver`); a native backend's +(:class:`solprop.backends.host.session.HostSession`); a native backend's (``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. diff --git a/src/solprop/driver/run.py b/src/solprop/driver/run.py index e5c8655e7..522e64f09 100644 --- a/src/solprop/driver/run.py +++ b/src/solprop/driver/run.py @@ -158,11 +158,9 @@ def plane_from_observation( Parameters ---------- observation : solprop.backends.protocol.Observation - The state at a save plane, from - :meth:`solprop.backends.protocol.HostStepping.observe`. + The state at a save plane, as a session observes it. stats : collections.abc.Mapping, optional - What :meth:`solprop.backends.protocol.HostStepping.stats` returned there, keyed - by statistic name. Empty when omitted. + The plane's statistics, keyed by statistic name. Empty when omitted. field : bool, optional Whether the plane keeps the field and its noise phase; ``False``, or an observation that carries no field, builds a field-free plane (SEP 22), which diff --git a/src/solprop/driver/runner.py b/src/solprop/driver/runner.py index a17a0c095..efacb6039 100644 --- a/src/solprop/driver/runner.py +++ b/src/solprop/driver/runner.py @@ -113,10 +113,9 @@ class SimulationRunner(Displayed): every input. A run on the reused backend repeats a fresh backend's run, to the rounding that - separates any two runs: loading an input restores everything the march reads - (the reference's :meth:`solprop.backends.host.driver.HostDriver.set_initial`, the - native backend's own load). Each run's record is - its own input's, so each has its own configuration hash. + separates any two runs: each run's session builds its march afresh and loads its + input, on either backend. Each run's record is its own input's, so each has its own + configuration hash. Use it as a context manager, or call :meth:`close`: the backend holds about fifteen copies of the state until then. A closed runner refuses :meth:`run`. A diff --git a/src/solprop/driver/session_loop.py b/src/solprop/driver/session_loop.py index 46ff44fc6..7b16f015c 100644 --- a/src/solprop/driver/session_loop.py +++ b/src/solprop/driver/session_loop.py @@ -47,8 +47,7 @@ join_attempts, ) from solprop.backends.export import ExportRecipe -from solprop.backends.host.session import HostSession -from solprop.backends.protocol import Backend, BackendHistory, HostStepping +from solprop.backends.protocol import Backend, BackendHistory from solprop.backends.protocol import StepStats as BackendRows from solprop.backends.session import RunSession from solprop.driver.plane_view import PlaneWatch @@ -429,10 +428,9 @@ def serve( # noqa: PLR0912, PLR0915 - the commit sequence of SEP 47 section 5.3 ) -> None: """Advance a session to its end, servicing every event it reports. - Any :class:`~solprop.backends.session.RunSession` is served: the reference's - :class:`~solprop.backends.host.session.HostSession`, whose driver gives the - execution facts and method history, or a backend's own session, through its - protocol alone (:class:`~solprop.driver.run.SessionFacts`). + Any :class:`~solprop.backends.session.RunSession` is served -- the reference's + :class:`~solprop.backends.host.session.HostSession` or the native backend's -- + through its protocol alone (:class:`~solprop.driver.run.SessionFacts`). Parameters ---------- @@ -932,14 +930,12 @@ def _fallback_ticket(session: RunSession) -> ExportTicket | None: return session.pending_ticket() -def _facts(session: RunSession) -> HostStepping | SessionFacts: +def _facts(session: RunSession) -> SessionFacts: """Return what the service loop's records read as the session's backend. - The reference session's driver, or a session's own facts - (:class:`~solprop.driver.run.SessionFacts`). + The session's own facts (:class:`~solprop.driver.run.SessionFacts`), through its + protocol: every session reports them through ``execution_record``. """ - if isinstance(session, HostSession): - return session.driver return SessionFacts(session) @@ -1160,7 +1156,7 @@ class _MarchKeeper: def __init__( self, output: Output, - backend: HostStepping | SessionFacts, + backend: SessionFacts, policy: bool | None, *, method: Literal["adams", "rk", "low_storage"] = "adams", diff --git a/src/solprop/monitor.py b/src/solprop/monitor.py index 63f91ddb8..b10c9a0ca 100644 --- a/src/solprop/monitor.py +++ b/src/solprop/monitor.py @@ -37,7 +37,7 @@ **Where the reduction runs.** A check needs five numbers of the state, its energy and its four weighted energies (:class:`BoundaryEnergies`), and the backend forms them -where its state lives (``HostDriver._boundary_energies``): only the five cross to the +where its state lives (``HostSession._energies``): only the five cross to the host. :meth:`BoundaryMonitor.energies` and :meth:`BoundaryMonitor.split_sums` are the host reductions, the reference every backend is held to. @@ -388,6 +388,10 @@ class BoundaryMonitor: monitor integrating the rate by the trapezoid (D5), and whose guards are judged on the power the split found (:attr:`BoundaryEnergies.found`), which every reading after a step must then carry. + sink : list of Warning or None + Where the monitor's warnings go instead of being issued, in order, for a + session that reports each as a ``WARNING`` barrier event (SEP 52 section 5.1); + ``None``, the default, issues them through :func:`warnings.warn`. """ check: BoundaryCheck @@ -398,6 +402,7 @@ class BoundaryMonitor: interval: float = math.inf transverse: TransverseEdge | None = None crossing: SplitCrossing | None = None + sink: list[Warning] | None = field(default=None, init=False, repr=False) _cap: float = field(default=math.inf, init=False) _launch: float = field(default=math.nan, init=False) _floor: float = field(default=0.0, init=False) @@ -952,9 +957,8 @@ def _judge(self, shares: Float[np.ndarray, " 4"], z: float | None) -> None: raise BoundaryError(_guard_message(check, worst, z, stop=True)) if worst > check.budget and not self._warned: self._warned = True - warnings.warn( - _boundary_warning(_guard_message(check, worst, z, stop=False)), - stacklevel=3, + self._warn( + _boundary_warning(_guard_message(check, worst, z, stop=False)), 3 ) def _settle( @@ -1303,6 +1307,14 @@ def finish(self) -> None: removed = max(self.removed, 0.0) _log_finish(removed, self._guard_max[0], self._guard_max[1]) if removed > 0.0 and math.sqrt(removed) > self.check.budget: - warnings.warn( - _boundary_warning(_removal_message(self.check, removed)), stacklevel=2 - ) + self._warn(_boundary_warning(_removal_message(self.check, removed)), 2) + + def _warn(self, warning: Warning, stacklevel: int) -> None: + """Issue a warning, or put it in the :attr:`sink` a session reports from. + + - ``stacklevel``: as the caller would pass to :func:`warnings.warn`. + """ + if self.sink is not None: + self.sink.append(warning) + return + warnings.warn(warning, stacklevel=stacklevel + 1) diff --git a/src/solprop/output/records.py b/src/solprop/output/records.py index b3e4850c4..35e42c414 100644 --- a/src/solprop/output/records.py +++ b/src/solprop/output/records.py @@ -909,9 +909,8 @@ def _adopted(values: np.ndarray) -> np.ndarray: """Mark an array a :class:`SavedPlane` takes as it is, instead of copying it. The driver's route (:func:`solprop.driver.run.run_problem`) for what an observation - holds. Only for an array that nothing writes to again, as - :meth:`solprop.backends.protocol.HostStepping.observe` promises, and never for a - view into a larger array, which it would pin. + holds. Only for an array that nothing writes to again, as a session's observation + promises, and never for a view into a larger array, which it would pin. - Returns: the same array, read-only. """ diff --git a/src/solprop/stepper/multistep.py b/src/solprop/stepper/multistep.py index 57897d8bc..46382bb7b 100644 --- a/src/solprop/stepper/multistep.py +++ b/src/solprop/stepper/multistep.py @@ -358,7 +358,7 @@ class MarchPolicy: quiet_interval : float or None The boundary monitor's interval, m, which caps a step while the collar rests; ``None`` without a monitor. The Python march reads the same number from the - monitor through the driver (``HostDriver._quiet_capped``). + monitor through its session (``HostSession.cap``). Raises ------ diff --git a/src/solprop/translate/stage.py b/src/solprop/translate/stage.py index be77037ab..bc9684bed 100644 --- a/src/solprop/translate/stage.py +++ b/src/solprop/translate/stage.py @@ -156,7 +156,7 @@ def anchor( The step's anchor, m, inside the tabulated range. helpers : solprop._helpers.Helpers, optional The implementation of the tables' Clenshaw pass: the backend's that runs the - step (``HostDriver.helpers``, SEP 29 section 6.6), or the plain Python forms by + step (``Backend.helpers``, SEP 29 section 6.6), or the plain Python forms by default. Returns @@ -447,7 +447,7 @@ def scalars( stage that the step did not need. Must be the anchor of `z0`. helpers : solprop._helpers.Helpers, optional The implementation of the tables' Clenshaw pass: the backend's that runs the - stage (``HostDriver.helpers``, SEP 29 section 6.6), or the plain Python forms by + stage (``Backend.helpers``, SEP 29 section 6.6), or the plain Python forms by default. Returns @@ -553,7 +553,7 @@ def scalars_at( The anchor's weights from :func:`anchor`; must be the anchor of `z0`. helpers : solprop._helpers.Helpers, optional The implementation of the tables' Clenshaw pass: the backend's that runs the - stages (``HostDriver.helpers``, SEP 29 section 6.6), or the plain Python forms + stages (``Backend.helpers``, SEP 29 section 6.6), or the plain Python forms by default, for callers outside a backend. Returns diff --git a/src/solprop/transverse_monitor.py b/src/solprop/transverse_monitor.py index 95dcfe5bc..bb5d9f03c 100644 --- a/src/solprop/transverse_monitor.py +++ b/src/solprop/transverse_monitor.py @@ -612,7 +612,7 @@ class _HostEdgeReduction: """The reference reductions of the edge, on a host copy of a state (SEP 44). A backend whose state lives elsewhere forms the same numbers there instead - (``HostDriver._edge_reading``), and is held to these. + (native's ``Resident::edge_reading``), and is held to these. Attributes ---------- @@ -624,6 +624,10 @@ class _HostEdgeReduction: A requested collar's lines; none without one. k_min : float The smallest wavenumber over the requested band, rad/m. + sink : list of Warning or None + Where the edge's warnings go instead of being issued, in order, for a session + that reports each as a ``WARNING`` barrier event (SEP 52 section 5.1); + ``None``, the default, issues them through :func:`warnings.warn`. """ space: RadialGrid | FreeGrid | PlanarGrid @@ -827,6 +831,7 @@ class TransverseEdge: length: float band: Int[np.ndarray, " n_band"] k_min: float + sink: list[Warning] | None = field(default=None, init=False, repr=False) _faces: tuple[_Face, ...] = field(init=False) _weights: np.ndarray = field(init=False) _columns: np.ndarray = field(init=False) @@ -893,6 +898,17 @@ def __post_init__(self) -> None: space, self.tables, _edge_lines(space, self.design), self.k_min ) + def _warn(self, message: str, stacklevel: int) -> None: + """Issue a boundary warning, or put it in the :attr:`sink` a session reports. + + - ``stacklevel``: as the caller would pass to :func:`warnings.warn`. + """ + warning = BoundaryWarning(message) + if self.sink is not None: + self.sink.append(warning) + return + warnings.warn(warning, stacklevel=stacklevel + 1) + def _edge_tables(self) -> _EdgeTables: """Return the weights a state's node energies are summed with.""" weights = self._weights @@ -1024,15 +1040,13 @@ def launch( # noqa: PLR0912, PLR0915 - the launch and judgements, in order if not reads: self._status = "unwatched" self._reason = _UNWATCHED_REASON - warnings.warn(_UNWATCHED_MESSAGE, BoundaryWarning, stacklevel=4) + self._warn(_UNWATCHED_MESSAGE, 4) return for index, face in enumerate(self._faces): self._baseline[index] = float(reading.faces[index]) / self._launch clipped = float(reading.clip[index]) / self._launch if clipped > warn: - warnings.warn( - _clip_message(clipped, face.name), BoundaryWarning, stacklevel=4 - ) + self._warn(_clip_message(clipped, face.name), 4) if noise is not None: noise_nodes = self._weights * self.reduction.node_power(noise) eta = float(np.sum(noise_nodes)) / self._launch @@ -1052,11 +1066,7 @@ def launch( # noqa: PLR0912, PLR0915 - the launch and judgements, in order if self._allowance > warn: self._status = "insensitive" self._reason = _insensitive_reason(self._allowance) - warnings.warn( - _insensitive_message(self._allowance), - BoundaryWarning, - stacklevel=4, - ) + self._warn(_insensitive_message(self._allowance), 4) self._last_columns = self._column_power(columns) self._respace(self._last_columns, launch=True) spacing = self._spacing_now @@ -1064,11 +1074,7 @@ def launch( # noqa: PLR0912, PLR0915 - the launch and judgements, in order if steps is not None and steps.size and float(np.max(steps)) > spacing: self._status = "coarse" if self._status == "clear" else self._status self._largest_gap = float(np.max(steps)) - warnings.warn( - _coarse_message(float(np.max(steps)), spacing), - BoundaryWarning, - stacklevel=4, - ) + self._warn(_coarse_message(float(np.max(steps)), spacing), 4) self._last_rate = (z, self._collar_rate(reading)) if self.every_step: self._launch_return(reading, noise) @@ -1098,9 +1104,7 @@ def _judge_ramp_band( if share > stop: raise BoundaryError(_ramp_band_message(share, stop=True)) if share > warn: - warnings.warn( - _ramp_band_message(share, stop=False), BoundaryWarning, stacklevel=5 - ) + self._warn(_ramp_band_message(share, stop=False), 5) def _collar_rate(self, reading: _EdgeReading) -> float: """Return a requested collar's removal rate, as a share of the launch per m.""" @@ -1283,9 +1287,7 @@ def read(self, reading: _EdgeReading, z: float) -> None: self._warned_at = z if self._status in ("clear", "coarse"): self._status = "warned" - warnings.warn( - _face_message(face_name, z, judged), BoundaryWarning, stacklevel=4 - ) + self._warn(_face_message(face_name, z, judged), 4) self._judge_ramp_removal() # ------------------------------------------------------------------ a collar @@ -1383,9 +1385,7 @@ def _judge_return(self, reading: _EdgeReading, z: float) -> None: self._warned = True self._warned_at = z self._status = "warned" - warnings.warn( - _return_message(returned, z, None), BoundaryWarning, stacklevel=5 - ) + self._warn(_return_message(returned, z, None), 5) def _judge_ramp_removal(self) -> None: """Warn, or stop, on what the safety ramp has removed (section 5.3, Q8). @@ -1404,9 +1404,7 @@ def _judge_ramp_removal(self) -> None: # Only a run below the warning throughout is clear (section 5.3). if self._status in ("clear", "coarse"): self._status = "warned" - warnings.warn( - _ramp_removal_message(removed, None), BoundaryWarning, stacklevel=5 - ) + self._warn(_ramp_removal_message(removed, None), 5) def _stop_message(self, face: str, judged: float, z: float) -> str: """Return the stop's message, naming a size and a sample count to try. diff --git a/tests/backends/adams_traces.py b/tests/backends/adams_traces.py index 336e16503..a7e061abc 100644 --- a/tests/backends/adams_traces.py +++ b/tests/backends/adams_traces.py @@ -4,10 +4,12 @@ """Decision traces of the Adams march on scripted norms (SEP 39 section 7.1). -The march's controller is driven through a stub backend and a stub engine. The engine -returns, for each attempt, the norms a scenario prescribes, so every decision the -march makes -- acceptance, the next order and proposal, the landing, a restart, the -call ledger -- is a function of the scenario's data alone, with no field arithmetic. +The real march is driven over a stub engine and a stub session that hosts it with the +session's own cap (:func:`~solprop.backends.host.session.step_cap`) and dense +observation's rule. The engine returns, for each attempt, the norms a scenario +prescribes, so every decision the march makes -- acceptance, the next order and +proposal, the landing, a restart, the call ledger -- is a function of the scenario's +data alone, with no field arithmetic. The corpus ``tests/data/adams_traces.json.gz`` was generated by ``tests/data/generate_adams_traces.py`` from the march as it stood before SEP 39's @@ -35,8 +37,8 @@ from solprop.backends.engines import AcceptRecord from solprop.backends.exponential import CarrierChord, CarrierReference from solprop.backends.host.adams import HostAdamsMarch -from solprop.backends.host.driver import HostDriver, _SessionHooks from solprop.backends.host.marches import MarchState +from solprop.backends.host.session import step_cap from solprop.backends.records import adams_policy from solprop.exceptions import BackendError, ConvergenceError, ResponseBudgetError from solprop.stepper.multistep import Formulation, Multistep @@ -348,12 +350,14 @@ def __init__(self, interval: float) -> None: class _Scripted: - """A stub backend: the driver surface an Adams march calls, recording it. - - Built without the driver's initialiser, which needs a translated problem; the march - reads only the members set here and the methods overridden below. Mixed into the - reference's driver (:class:`_HostHarness`), whose march the native march's - decision traces are held to (``test_native_march_traces.py``). + """A stub session: what the Adams marches ask of it, recording it. + + The reference's march asks through + :class:`~solprop.backends.host.marches.MarchHost` (:class:`_HostHarness`); the + native march's call-by-call adapter (``native_trace_marches.TraceAdamsMarch``) + reads the members set here, in the names the reference's step driver had, so that + the native march's decision traces are held to the reference's + (``test_native_march_traces.py``). """ name = "scripted" @@ -382,6 +386,8 @@ def __init__(self, scenario: Scenario) -> None: self.events: list[dict[str, Any]] = [] self.engine: _Engine | None = None self.march: Any | None = None + # The plane a dense observation holds, as the session observes it. + self.observed: float | None = None def _held_state(self) -> MarchState: march = self.march @@ -430,6 +436,9 @@ def _reserve_source_calls(self, count: int) -> None: def _release_source_calls(self) -> None: pass + def _poll_stop(self) -> None: + pass + def _natural_stop_due(self, target: float) -> bool: return False @@ -455,14 +464,34 @@ def _record(self, z: float, dz: float, norm: float, accepted: bool) -> None: self.pending = {} -class _HostHarness(_Scripted, HostDriver): - """The stub over the reference's driver; the engine is given to its march.""" +class _HostHarness(_Scripted): + """The stub hosting the reference's Adams march; the engine is given to it.""" helpers = PLAIN - def __init__(self, scenario: Scenario) -> None: - super().__init__(scenario) - self._hooks = _SessionHooks(self) + # The march's host (`MarchHost`), with the session's rules. + + @property + def collar_quiet(self) -> bool: + return self._collar_quiet + + def poll_stop(self) -> None: + self._poll_stop() + + def cap(self, proposal: float, z: float) -> float: + return step_cap(self._monitor, self._collar_quiet, proposal, z) + + def record(self, end: float, dz: float, norm: float, accepted: bool) -> None: + self._record(end, dz, norm, accepted) + + def absorb(self, record: AcceptRecord) -> None: + del record + + def stepped(self) -> None: + self._take_step_stats() + + def natural_stop(self, target: float) -> bool: + return self._natural_stop(target) def adams_march(self, method: Multistep) -> HostAdamsMarch: """Return the reference's march over the scripted engine, at the start.""" @@ -479,7 +508,7 @@ def adams_march(self, method: Multistep) -> HostAdamsMarch: march = HostAdamsMarch( engine, method, - self._hooks, + self, policy=policy, field=lambda: np.zeros((1, 1, 1), dtype=np.complex128), schedule=stepper.schedule, @@ -531,7 +560,7 @@ def _march_state(harness: _Scripted, march: Any) -> dict[str, Any]: """ ledger = march.ledger return { - "position": harness._z, + "position": harness._z if harness.observed is None else harness.observed, "proposal": harness._proposal, "stored_order": march._order, "rejections": march._rejections, @@ -586,8 +615,17 @@ def run_scenario( end: dict[str, Any] = {"stop": "done"} try: for target in targets: + # The session restores a held plane's committed state before it marches. + harness.observed = None march.march_to(target) - harness.events.append({"target": target, "position": harness._z}) + if scenario.interpolate and march.state.z > target: + # The session observes the plane inside the step that crossed it + # (`AdamsDense.crosses`), holding the committed state aside. + harness.observed = target + march.ledger.dense_observations += 1 + harness.events.append( + {"target": target, "position": _march_state(harness, march)["position"]} + ) except (BackendError, ConvergenceError, ResponseBudgetError) as error: end = {"stop": type(error).__name__, "message": str(error)} end["in_flight"] = dict(harness.pending) diff --git a/tests/backends/rk_traces.py b/tests/backends/rk_traces.py index 6a4151340..1c0bd6e85 100644 --- a/tests/backends/rk_traces.py +++ b/tests/backends/rk_traces.py @@ -4,10 +4,12 @@ """Decision traces of the Runge-Kutta march on scripted norms (SEP 45 section 7.2). -The march's controller is driven through a stub backend whose trial returns, for each -attempt, the norm a scenario prescribes, so every decision the march makes -- -acceptance, the next proposal, the landing, the start-up rule, the caps, the floor, a -natural stop -- is a function of the scenario's data alone, with no field arithmetic. +The real march is driven over a scripted engine whose trial returns, for each attempt, +the norm a scenario prescribes, and a stub session that hosts it with the session's +own rules (:func:`~solprop.backends.host.session.step_cap`, +:func:`~solprop.backends.host.session.natural_stop`), so every decision the march +makes -- acceptance, the next proposal, the landing, the start-up rule, the caps, the +floor, a natural stop -- is a function of the scenario's data alone, with no field arithmetic. The corpus ``tests/data/rk_traces.json.gz`` was generated by ``tests/data/generate_rk_traces.py`` from the march as it stood before SEP 45's @@ -35,9 +37,9 @@ from solprop.backends import rk_core from solprop.backends.engines import AcceptRecord -from solprop.backends.host.driver import HostDriver, _SessionHooks from solprop.backends.host.marches import MarchState from solprop.backends.host.runge_kutta import RungeKuttaMarch +from solprop.backends.host.session import natural_stop, step_cap from solprop.backends.records import runge_kutta_policy from solprop.exceptions import BackendError, ConvergenceError from solprop.stepper.controller import PIController @@ -180,12 +182,13 @@ def __init__(self, interval: float, ceiling: float | None) -> None: class _Scripted: - """A stub backend: the driver surface the Runge-Kutta march calls, recording it. + """A stub session: what the Runge-Kutta marches ask of it, recording it. - Built without the driver's initialiser, which needs a translated problem; the march - reads only the members set here and the methods overridden below. Mixed into each - driver family: the native bridge's (:class:`_Harness`) and the reference's own - (:class:`_HostHarness`, SEP 47 phase 2), whose marches must decide alike. + The reference's march asks through + :class:`~solprop.backends.host.marches.MarchHost` (:class:`_HostHarness`); the + native march's call-by-call adapter (``native_trace_marches.TraceRungeKuttaMarch``) + reads the members set here, in the names the reference's step driver had, so that + both marches decide on the same scripted readings. """ name = "scripted" @@ -239,12 +242,6 @@ def __init__(self, scenario: Scenario) -> None: self._stop = None self._dense_ahead = None self._natural_count = 0 - # The reference's halt latch (``HostDriver``), which its host arm reads; the - # native backend's inherited driver has none since SEP 47 phase 5. - self._halt_requested = False - self._halt_ahead = False - self._halt_check = None - self._natural_due = False self._state: object = "state" self.accepted = 0 self.attempts = 0 @@ -291,6 +288,23 @@ def _controller_policy(self) -> Any: def _on_accepted_step(self) -> None: pass + def _poll_stop(self) -> None: + pass + + def _natural_stop(self, target: float) -> bool: + """Count an accepted step; return whether a step plane stops the march there. + + The session's rule; no halt is asked of these scenarios. + """ + self._natural_count += 1 + every = self.scenario.step_planes + return bool(natural_stop(every, self._natural_count, self._z, target)) + + def _natural_stop_due(self, target: float) -> bool: + """Return no stop owed: the scenarios observe no plane inside a step.""" + del target + return False + def _start_up(self, norm: float) -> None: state = self._held_state() state.proposal, state.norms[-1] = rk_core.start_up( @@ -377,20 +391,16 @@ def extend(self, z: float, dz: float) -> None: def reading(self) -> Any: raise NotImplementedError - def reset(self) -> None: - pass - -class _HostHarness(_Scripted, HostDriver): - """The stub over the reference's own driver and its Runge-Kutta march.""" +class _HostHarness(_Scripted): + """The stub hosting the reference's Runge-Kutta march over the scripted engine.""" def __init__(self, scenario: Scenario) -> None: super().__init__(scenario) - self._hooks = _SessionHooks(self) march = RungeKuttaMarch( _ScriptedEngine(self), self._controller_policy(), - self._hooks, + self, schedule=None, proposal=scenario.proposal, name=self.name, @@ -399,6 +409,30 @@ def __init__(self, scenario: Scenario) -> None: march.state.norms = self._shadow.norms self.march = march + # The march's host (`MarchHost`), with the session's rules. + + @property + def collar_quiet(self) -> bool: + return self._collar_quiet + + def poll_stop(self) -> None: + self._poll_stop() + + def cap(self, proposal: float, z: float) -> float: + return step_cap(self._monitor, self._collar_quiet, proposal, z) + + def record(self, end: float, dz: float, norm: float, accepted: bool) -> None: + self._record(end, dz, norm, accepted) + + def absorb(self, record: AcceptRecord) -> None: + del record + + def stepped(self) -> None: + self._take_step_stats() + + def natural_stop(self, target: float) -> bool: + return self._natural_stop(target) + def run_scenario(scenario: Scenario) -> dict[str, Any]: """Run a scenario through a Python Runge-Kutta march and return its trace. diff --git a/tests/builders.py b/tests/builders.py index 4df278f67..2d7e54a9d 100644 --- a/tests/builders.py +++ b/tests/builders.py @@ -32,6 +32,7 @@ "HASH_PROBE", "fixed_fibre_point", "launch_derivative", + "load_reference", "numpy_ref_launch_derivative", "reference_trial", "run_python", @@ -51,6 +52,36 @@ def run(self, *args, **kwargs): """A prefix for an exported script: its run prints the configuration hash and exits.""" +def load_reference( + backend: Any, + field: Any = None, + *, + noise: Any = None, + z: float | None = None, + resume: bool = False, +) -> Any: + """Load a ``numpy_ref`` backend's workspace as a session loads its start. + + The state masked to the active band, with the ``input`` noise's draw at the + launch (:meth:`solprop.backends.numpy_ref.workspace.NumpyWorkspace.load`), for the + workspace- and engine-level checks; no monitor is bound and nothing is stepped. + + - ``field``: the state; the problem's launch by default. + - ``z``: its position, m; the problem's entrance by default. + - Returns: the committed state. + """ + workspace = backend.workspace + problem = workspace.problem + values = problem.initial.field0 if field is None else field + workspace.load( + np.ascontiguousarray(values, dtype=np.complex128), + noise, + z=float(problem.initial.z) if z is None else float(z), + resume=resume, + ) + return workspace.committed() + + def launch_derivative(backend: NumpyRefBackend, problem: PropagationProblem) -> Any: """Return an open ``numpy_ref`` backend's stage derivative ``N(E, z=0)`` at launch. @@ -58,10 +89,10 @@ def launch_derivative(backend: NumpyRefBackend, problem: PropagationProblem) -> for its nonlinear stage there with unit stage weights, as the first stage of a trial is. """ - backend.set_initial(problem.initial.field0, None) + state = load_reference(backend, problem.initial.field0) backend.workspace.hoist(0.0) return backend.workspace.nonlinear( - backend._require_state(), + state, backend.workspace.stage_scalars(0.0, 0.0), np.ones(problem.shape, complex), ) @@ -70,10 +101,10 @@ def launch_derivative(backend: NumpyRefBackend, problem: PropagationProblem) -> def reference_trial(backend: Any, z: float, dz: float) -> tuple[float, Any]: """Return a ``numpy_ref`` trial's norm and raw end state, committing nothing. - The backend's Runge-Kutta engine forms the trial from the committed state and - holds it; its end state is before the accepted step's finish. + A Runge-Kutta engine over the backend's workspace forms the trial from the + committed state and holds it; its end state is before the accepted step's finish. """ - engine = backend._runge_kutta_engine + engine = backend._runge_kutta(backend.workspace) norm = engine.trial(z, dz) return norm, engine.trial_state diff --git a/tests/monitor_cases.py b/tests/monitor_cases.py index 4ed6c160c..45ad150b9 100644 --- a/tests/monitor_cases.py +++ b/tests/monitor_cases.py @@ -22,9 +22,10 @@ import numpy as np +from builders import load_reference from capability_routes import LENGTH, ROUTES from solprop.backends.events import Terminal -from solprop.backends.host.driver import HostDriver +from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.protocol import Backend from solprop.backends.registry import select from solprop.backends.session import ExecutionOptions, Start @@ -153,24 +154,23 @@ def with_copy(field: np.ndarray, n_t: int) -> np.ndarray: return field * (1.0 + COPY_SHARE * phase) -def as_driver(backend: Backend) -> HostDriver[Any]: - """Return the reference backend as its step driver. +def as_reference(backend: Backend) -> NumpyRefBackend: + """Return the reference backend, whose workspace a test loads and reads directly. Raises ------ TypeError - For any other backend: since SEP 47 phase 5 the native backend has no direct - driver API, and its monitor is read through its session + For any other backend: the native backend's state is read through its session (:func:`record_after_march`, or a session's ``monitor_record``). """ - if not isinstance(backend, HostDriver): + if not isinstance(backend, NumpyRefBackend): msg = ( - f"{type(backend).__name__} has no step driver to load and read directly; " + f"{type(backend).__name__} has no workspace to load and read directly; " "read its boundary monitor through its session " "(monitor_cases.record_after_march or RunSession.monitor_record)" ) raise TypeError(msg) - return cast("HostDriver[Any]", backend) + return backend def watched( @@ -182,13 +182,15 @@ def watched( ) -> Backend: """Return the reference backend loaded with the edge-reaching launch and watched. - `options` default to the simulation's own execution options; `problem` and - `run_request` to its own translation. + Its workspace holds the launch and reads the simulation's boundary monitor, as a + session's attached monitor has it read; nothing is judged. `options` default to + the simulation's own execution options; `problem` and `run_request` to its own + translation. Raises ------ TypeError - For a backend other than the reference (:func:`as_driver`). + For a backend other than the reference (:func:`as_reference`). """ problem = simulation.translate() if problem is None else problem run_request = simulation._run_request() if run_request is None else run_request @@ -202,28 +204,39 @@ def watched( options=simulation.settings.execution_options() if options is None else options, ) try: - driver = as_driver(backend) + reference = as_reference(backend) except TypeError: backend.close() raise - driver.set_initial(with_copy(problem.initial.field0, simulation.grid.n_t), None) + load_reference(reference, with_copy(problem.initial.field0, simulation.grid.n_t)) monitor = simulation._boundary_monitor() assert monitor is not None - driver.attach_monitor(monitor) + if monitor.split: + # The split collar's crossing limit, which a reading's occupancy needs. + monitor.crossing = problem.split_crossing + reference.workspace.bind_monitor(monitor) return backend def reading(backend: Backend) -> BoundaryEnergies: """Return the reference backend's reading of its current state. + The workspace's reading of the committed state, with nothing taken by a split since + the load, as a session's first reading after attaching its monitor. + Raises ------ TypeError - For a backend other than the reference (:func:`as_driver`). + For a backend other than the reference (:func:`as_reference`). """ - driver = as_driver(backend) - driver._require_state() - return driver._boundary_energies() + reading = as_reference(backend).workspace.reading() + return BoundaryEnergies( + total=reading.total, + regions=reading.regions, + removed=0.0, + found=None, + occupancy=reading.occupancy, + ) def record_after_march( @@ -278,7 +291,7 @@ def record_after_march( raise terminal.error record = session.monitor_record() assert record is not None - if isinstance(backend, HostDriver): + if isinstance(backend, NumpyRefBackend): cap = float(monitor.step_cap) else: cap = float(cast("Any", session).monitor_cap()) diff --git a/tests/scripted_driver.py b/tests/scripted_driver.py index b37337a73..db6756339 100644 --- a/tests/scripted_driver.py +++ b/tests/scripted_driver.py @@ -2,17 +2,20 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""A step driver whose numerical outcomes are scripted rather than computed. +"""A reference backend whose numerical outcomes are scripted rather than computed. :class:`HostScriptedDriver` is the reference backend with its Runge-Kutta engine -replaced by a script: a trial multiplies the state by a constant and scores an error -norm taken from a list, so step control, the session lifecycle and the service loop -can be tested without any physics being evaluated correctly. ``tests/sessions`` tests -the execution-session lifecycle with it (SEP 47 section 7.1: "Script the same -numerical outcomes to test this exact lifecycle property on every executor"). +replaced by a scripted engine under the real march and the real session: a trial +multiplies the state by a constant and scores an error norm taken from a list, so step +control, the session lifecycle and the service loop can be tested without any physics +being evaluated correctly. ``tests/sessions`` tests the execution-session lifecycle +with it (SEP 47 section 7.1: "Script the same numerical outcomes to test this exact +lifecycle property on every executor"). Its statistics are scripted too: every name +reads the position it was taken at. """ -from typing import TYPE_CHECKING, Any +from types import MethodType +from typing import Any import numpy as np @@ -24,8 +27,14 @@ """The step length, m, whose default scripted norm is one: an eighth of a 2 cm run.""" -class _Scripted: - """A driver whose stage evaluation multiplies by a constant and scores from a list. +def _scripted_stats(workspace: NumpyWorkspace, spec: Any, z: float) -> dict: + """Return one scriptable number per name: the position the row was taken at.""" + state = workspace.committed() + return {name: np.full((state.shape[0],), z) for name in spec.names} + + +class HostScriptedDriver(NumpyRefBackend): + """The reference backend over a scripted Runge-Kutta engine. The state advances by a factor per step so that a rejected step can be seen not to have been kept, and the error norms come from a script so that acceptance, @@ -46,85 +55,55 @@ class _Scripted: scale : float, optional The step length, m, whose default norm is one. **kwargs - Passed to the step driver. + Passed to the reference backend. """ name = "scripted" - if TYPE_CHECKING: - # What the mixin reads of the driver it is mixed into. - _problem: Any - - @property - def _z(self) -> float: ... - - @property - def _proposal(self) -> float: ... - - _closed: bool - _workspace: Any - - def _require_state(self) -> Any: ... - def __init__( self, problem, run_request, *, norms=(), factor=1.0, scale=SCALE, **kwargs ): - super().__init__(problem, run_request, **kwargs) # pyright: ignore[reportCallIssue] self._norms = list(norms) self._factor = factor self._scale = scale self.calls: list[tuple[float, float]] = [] - self.proposals: list[float] = [] - self.accepted_hooks = 0 - self.planes_begun = 0 + super().__init__(problem, run_request, **kwargs) + self._workspace.stats = MethodType(_scripted_stats, self._workspace) # pyright: ignore[reportAttributeAccessIssue] - def _trial_step(self, z, dz): + def _trial_step(self, z: float, dz: float) -> tuple[float, np.ndarray]: + """Return a trial's scripted norm and end state, the state times a factor.""" self.calls.append((z, dz)) - self.proposals.append(self._proposal) # A fifth-order embedded estimate: the norm has to fall like dz^5 or the # controller's equivalent_norm reads every short landing step as a failure and # the proposal collapses. A constant would test the loop against a stand-in the # loop was never written for. norm = self._norms.pop(0) if self._norms else (dz / self._scale) ** 5 - state = self._require_state() * self._factor - return norm, self._apply_mask(state) - - def _apply_mask(self, state): - return state * self._problem.grids.active_mask - - def _on_accepted_step(self): - self.accepted_hooks += 1 - - def stats(self, spec) -> dict[str, np.ndarray]: - """Return one scriptable number per name: the position the row was taken at.""" - state = self._require_state() - return {name: np.full((state.shape[0],), self._z) for name in spec.names} - - def _begin_plane(self): - self.planes_begun += 1 + state = self._workspace.committed() * self._factor + return norm, state * self._problem.grids.active_mask def _runge_kutta(self, workspace: NumpyWorkspace) -> NumpyRungeKutta: """Return the scripted engine in place of the reference's.""" return _ScriptedEngine(workspace, self) - def close(self): - """Release the state, as the seam requires.""" - self._workspace.close() - self._closed = True - class _ScriptedEngine(NumpyRungeKutta): - """A Runge-Kutta engine whose trial is the driver's script (``_trial_step``).""" + """A Runge-Kutta engine whose trial is the backend's script (``_trial_step``). + + It is in flight from a trial the script left partway until the next engine is + built, as an in-place step abandoned there is (the commit contract). + """ - def __init__(self, workspace: NumpyWorkspace, driver: Any) -> None: + def __init__(self, workspace: NumpyWorkspace, backend: Any) -> None: super().__init__(workspace, workspace.stepper.tableau) - self._driver = driver + self._backend = backend + self.left = False + + @property + def in_flight(self) -> bool: # numpydoc ignore=RT01 + """Whether the script left a trial in flight.""" + return self.left def trial(self, z: float, dz: float) -> float: - norm, state = self._driver._trial_step(z, dz) + norm, state = self._backend._trial_step(z, dz) self._trial = (state, []) return norm - - -class HostScriptedDriver(_Scripted, NumpyRefBackend): - """The script on the reference backend's engine.""" diff --git a/tests/sessions/executors.py b/tests/sessions/executors.py index 1c15659b0..20b522c48 100644 --- a/tests/sessions/executors.py +++ b/tests/sessions/executors.py @@ -23,8 +23,9 @@ - ``native-session-low-storage`` is the native execution session replaying the same problem's planes on a uniform schedule of :data:`LOW_STORAGE_STEPS` steps with the low-storage march (SEP 47 section 6.3), whose loop the native session owns. -- ``scripted-host`` is :class:`HostSessionScript`, the reference's own driver in the - reference's session, whose norms, rejections, failures, in-flight failures and +- ``scripted-host`` is :class:`HostSessionScript`, the reference backend over a + scripted engine under the real march, in the reference's session + (:class:`ScriptedSession`), whose norms, rejections, failures, in-flight failures and warnings are chosen by the test. The problem is the fundamental GNLSE soliton of ``tests/backends/conftest.py`` on its @@ -223,10 +224,10 @@ class ScriptedWarning(UserWarning): """What a scripted committed endpoint warns with.""" -class _Outcomes: - """A scripted driver with the outcomes the lifecycle tests choose. +class HostSessionScript(HostScriptedDriver): + """The reference backend with the outcomes the lifecycle tests choose. - Trials and accepted steps are counted from 1 since the load. + Trials and accepted steps are counted from 1 since the session started. Parameters ---------- @@ -243,11 +244,12 @@ class _Outcomes: abandoned partway does: the state is then neither end of the step. signal : bool, optional Whether that trial raises ``KeyboardInterrupt`` instead, as a signal handler - does that runs between the driver's steps: a failure outside the session, - with nothing in flight. + does that runs between the steps: a failure outside the session, with nothing + in flight. warn_at : int or None, optional The accepted step whose committed endpoint warns with - :class:`ScriptedWarning`, after the step's statistics row. + :class:`ScriptedWarning`, after the step's statistics row + (:class:`ScriptedSession`). **kwargs Passed to :class:`scripted_driver.HostScriptedDriver`. """ @@ -264,49 +266,50 @@ def __init__( warn_at: int | None = None, **kwargs: Any, ) -> None: - super().__init__(problem, run_request, factor=FACTOR, scale=SCALE, **kwargs) # pyright: ignore[reportCallIssue] self._reject_at = frozenset(reject_at) self._fail_at = fail_at self._leave_in_flight = in_flight self._signal = signal - self._warn_at = warn_at + self.warn_at = warn_at self.trials = 0 - self.accepted = 0 - self._left: tuple[float, float] | None = None + super().__init__(problem, run_request, factor=FACTOR, scale=SCALE, **kwargs) - def set_initial(self, *args: Any, **kwargs: Any) -> None: - # A load clears a step left in flight, as it does the low-storage march's. - self._left = None - super().set_initial(*args, **kwargs) # pyright: ignore[reportAttributeAccessIssue] - - def _abandoned(self) -> tuple[float, float] | None: - return self._left + def method(self, host: object) -> Any: + """Count trials afresh with each session's march.""" + self.trials = 0 + return super().method(host) def _trial_step(self, z, dz): self.trials += 1 if self.trials == self._fail_at: if self._leave_in_flight: - self._left = (z, dz) + self._run.march.engine.left = True # pyright: ignore[reportAttributeAccessIssue] if self._signal: raise KeyboardInterrupt msg = f"scripted failure at trial {self.trials}" raise ScriptedError(msg) - norm, state = super()._trial_step(z, dz) # pyright: ignore[reportAttributeAccessIssue] + norm, state = super()._trial_step(z, dz) return (REJECTED if self.trials in self._reject_at else norm), state - def _take_step_stats(self): - super()._take_step_stats() # pyright: ignore[reportAttributeAccessIssue] - self.accepted += 1 - if self.accepted == self._warn_at: - warnings.warn( - f"scripted warning at accepted step {self.accepted}", - ScriptedWarning, - stacklevel=2, - ) +class ScriptedSession(HostSession): + """The reference's session, warning at the committed endpoint a script chooses. -class HostSessionScript(_Outcomes, HostScriptedDriver): - """The scripted outcomes on the reference's own driver (SEP 47 phase 2).""" + A :class:`HostSessionScript` backend's ``warn_at`` accepted step warns with + :class:`ScriptedWarning` after its statistics row, a barrier as a boundary + warning is; any other backend runs as in :class:`HostSession`. + """ + + def __init__(self, backend: Any, *args: Any, **kwargs: Any) -> None: + self._warn_at = getattr(backend, "warn_at", None) + self._accepted = 0 + super().__init__(backend, *args, **kwargs) + + def _account_step(self): + yield from super()._account_step() + self._accepted += 1 + if self._accepted == self._warn_at: + yield ScriptedWarning(f"scripted warning at accepted step {self._accepted}") @dataclass(frozen=True, eq=False) @@ -350,18 +353,18 @@ def __call__( def _over_driver( - make: Callable[..., Any], *, host_state: bool, session: type = HostSession + make: Callable[..., Any], *, host_state: bool, session: type = ScriptedSession ) -> Factory: - """Return a factory of sessions over a step driver. + """Return a factory of the reference's sessions over a backend. Parameters ---------- make : callable - ``(problem, request, **script) -> driver``. + ``(problem, request, **script) -> backend``. host_state : bool - Whether the driver's state is a host array the aliasing checks can read. + Whether the backend's state is a host array the aliasing checks can read. session : type, optional - The session class: the reference's by default. + The session class: the reference's, warning where a script asks. Returns ------- @@ -372,20 +375,22 @@ def _over_driver( def start_session( problem, request, start, *, stop=None, listener=None, context=None, **script ): - driver = make(problem, request, context=context, **script) + backend = make(problem, request, context=context, **script) reads = [0] - observe = driver.observe + started = session( + backend, problem, request, start, listener=listener, stop=stop + ) + observe = started._observe - def counted(*, field: bool = True): + def counted(*, field: bool): reads[0] += bool(field) return observe(field=field) - driver.observe = counted - started = session(driver, problem, request, start, listener=listener, stop=stop) + started._observe = counted return Started( started, field_reads=lambda: reads[0], - live_state=(lambda: driver.workspace.state) if host_state else None, + live_state=(lambda: backend.workspace.state) if host_state else None, ) return start_session @@ -455,7 +460,7 @@ def _host_scripted( Returns ------- HostSessionScript - The driver. + The backend. """ assert context is None, "a script runs the soliton alone" return HostSessionScript(problem, request, grid=window(), **script) diff --git a/tests/sessions/runs.py b/tests/sessions/runs.py index 70d59b535..cea58d518 100644 --- a/tests/sessions/runs.py +++ b/tests/sessions/runs.py @@ -654,7 +654,7 @@ def adams_ledger(backend: Any, record: Mapping[str, object]) -> CallLedger: The ledger. """ if backend.name == "numpy_ref": - return backend._adams.ledger + return backend.march.ledger return CallLedger.from_record( cast("Mapping[str, object]", record["response_calls"]) ) diff --git a/tests/sessions/test_conformance.py b/tests/sessions/test_conformance.py index 8db3775b9..f35e14a75 100644 --- a/tests/sessions/test_conformance.py +++ b/tests/sessions/test_conformance.py @@ -818,27 +818,38 @@ def test_an_in_flight_failure_poisons_the_state(start_scripted): def test_a_warning_raised_as_an_error_fails_at_its_committed_endpoint(start_scripted): """SEP 47 section 5.5: a warning the filters promote is a barrier, then a failure. - The warning arises after an accepted step's commit; the failure reports that - endpoint, eligible, with its field. + The warning arises after an accepted step's commit and is reported as a barrier at + that endpoint, whose ticket exports its field for the failure's checkpoint; the + caller's filters raise it when it is emitted. """ warn_at = 6 - held: dict[str, np.ndarray] = {} + session = start_scripted(soliton(), warn_at=warn_at).session + batches = [] + launched = None + while True: + batch = session.advance() + batches.append(batch) + event = batch.events[-1] + if isinstance(event, ServiceRequired) and event.kind is ServiceKind.WARNING: + break + assert batch.terminal is None + if launched is None: + assert isinstance(event, ObservationReady) + launched = session.export(event.ticket, IDENTITY) + session.acknowledge(batch.receipt) + histories = [one.history for batch in batches for one in batch.events] + flags = np.concatenate([history.accepted for history in histories]) + ends = np.concatenate([history.z for history in histories])[flags] + assert ends.size == warn_at and event.z == ends[-1] == session.status().z + assert event.ticket is not None + held = session.export(event.ticket, IDENTITY) with warnings.catch_warnings(): warnings.simplefilter("error", ScriptedWarning) - run = drive( - start_scripted(soliton(), warn_at=warn_at), - export=IDENTITY, - between=_terminal_field(held), - raises=False, - ) - terminal = run.terminal - assert terminal.outcome is Outcome.FAILED - assert isinstance(terminal.error, ScriptedWarning) - assert terminal.eligibility is Eligibility.ELIGIBLE - ends = run.accepted_ends() - assert ends.size == warn_at and terminal.z == ends[-1] - np.testing.assert_array_equal(held["field"], run.fields[0] * FACTOR**warn_at) - assert run.attempts == run.status.attempts + with pytest.raises(ScriptedWarning, match="accepted step 6"): + emit_warning(event) + # The launch's field after `warn_at` doublings, exactly (FACTOR is a power of two). + np.testing.assert_array_equal(held, launched * FACTOR**warn_at) + session.close() def test_an_allowed_warning_changes_nothing(start_scripted): diff --git a/tests/sessions/test_host_seams.py b/tests/sessions/test_host_seams.py index a999cf7fa..f6b9c8521 100644 --- a/tests/sessions/test_host_seams.py +++ b/tests/sessions/test_host_seams.py @@ -2,10 +2,9 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The host-only seams refuse the native backend by name (SEP 47 section 6.8). +"""The reference's session refuses the native backend by name (SEP 47 section 6.8). -Native runs only in its own session: neither the reference's session nor the host -stepping seam takes it. +Native runs only in its own session. """ import pytest @@ -16,7 +15,6 @@ soliton, ) from solprop.backends.host.session import HostSession -from solprop.backends.protocol import stepping from solprop.backends.registry import available, select from solprop.exceptions import BackendError @@ -29,17 +27,7 @@ def test_the_reference_session_refuses_a_native_backend(): problem, request = soliton() backend = select("native", problem, request, **_soliton_context()) try: - with pytest.raises(BackendError, match="serves a host driver"): + with pytest.raises(BackendError, match="serves a reference backend"): HostSession(backend, problem, request, entrance(problem)) finally: backend.close() - - -def test_the_stepping_seam_refuses_a_native_backend(): - problem, request = soliton() - backend = select("native", problem, request, **_soliton_context()) - try: - with pytest.raises(BackendError, match="runs in its own session"): - stepping(backend) - finally: - backend.close() From 2ba9603903404744a2096abeb0f90f5e6e0dec12 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 05:07:19 +0000 Subject: [PATCH 05/14] test: port the reference's tests to its session, workspace and engines The tests that loaded and stepped the reference's step driver now run its session, read its workspace or build its engines; the scripted executor and the trace harnesses host the real marches. Tests of the deleted structure go (HostDriver inheritance, the HostStepping seam, the statistics storage hooks, target refusals a session cannot reach). Native tests that use the reference as their oracle load its workspace. The benchmark worker times the reference's workspace load. The structure figures name the session's parts. Co-Authored-By: Claude Opus 5.5 --- benchmarks/worker.py | 31 +- docs/dev/figures/backends.svg | 36 +- docs/dev/figures/build.py | 46 +- docs/dev/figures/layers.svg | 17 +- docs/dev/figures/one_run.svg | 7 +- native/tests/plasma_bounds.py | 13 +- native/tests/test_backend.py | 9 +- native/tests/test_band_column_budget.py | 20 +- native/tests/test_band_pathological.py | 17 +- native/tests/test_band_plasma.py | 24 +- native/tests/test_band_statistics_per_node.py | 19 +- native/tests/test_band_stress.py | 31 +- native/tests/test_dispersive.py | 7 +- native/tests/test_envelope_plasma.py | 7 +- native/tests/test_envelope_subnormal.py | 20 +- native/tests/test_radial.py | 9 +- src/solprop/backends/numpy_ref/backend.py | 15 +- src/solprop/backends/numpy_ref/workspace.py | 2 +- tests/backends/carrier_frame_cases.py | 3 +- tests/backends/native_mixture_launch_probe.py | 6 +- tests/backends/rk_traces.py | 3 +- tests/backends/synthetic_leaf_cases.py | 4 +- tests/backends/test_absorber_schemes.py | 6 +- tests/backends/test_adams_natural_kink.py | 4 +- tests/backends/test_backend_ladder.py | 25 +- tests/backends/test_backend_protocol.py | 50 +- tests/backends/test_carrier_frame.py | 79 +- tests/backends/test_driver.py | 709 +++++++++--------- tests/backends/test_envelope_plasma.py | 5 +- tests/backends/test_envelope_plasma_host.py | 9 +- tests/backends/test_exponential_coupled.py | 2 +- tests/backends/test_exponential_march.py | 70 +- tests/backends/test_exponential_routes.py | 9 +- tests/backends/test_exponential_varying.py | 20 +- tests/backends/test_free_absorber.py | 3 +- tests/backends/test_free_boundaries.py | 3 +- tests/backends/test_free_noise.py | 6 +- tests/backends/test_general_modal.py | 29 +- tests/backends/test_host_edge_resume.py | 24 +- tests/backends/test_host_ledgers.py | 30 +- tests/backends/test_low_storage.py | 268 ++++--- tests/backends/test_mixture_statistics.py | 9 +- tests/backends/test_monitor_reduction.py | 104 ++- tests/backends/test_multistep_march.py | 115 +-- tests/backends/test_native_error_norm.py | 8 +- .../backends/test_native_mixture_fractions.py | 9 +- .../backends/test_native_planar_statistics.py | 11 +- tests/backends/test_numpy_engines.py | 128 ++-- tests/backends/test_numpy_ref_backend.py | 60 +- tests/backends/test_numpy_ref_plasma.py | 5 +- tests/backends/test_numpy_ref_raman.py | 3 +- tests/backends/test_on_axis_statistics.py | 13 +- tests/backends/test_planar_hybrid.py | 36 +- tests/backends/test_polarised_runs.py | 3 +- tests/backends/test_radial_absorber.py | 3 +- tests/backends/test_radial_statistics.py | 12 +- tests/backends/test_records.py | 5 +- tests/backends/test_reference_independence.py | 16 +- tests/backends/test_source_evaluations.py | 34 +- tests/backends/test_step_limits.py | 29 +- tests/backends/test_tdse_march.py | 176 +++-- tests/driver/test_coherent_capillary.py | 10 +- tests/driver/test_estimate.py | 25 +- tests/driver/test_field_free_planes.py | 77 +- tests/driver/test_flow_collar.py | 27 +- tests/driver/test_general_modal.py | 14 +- tests/driver/test_initial_z_and_checkpoint.py | 54 +- tests/driver/test_moving_guide.py | 36 +- tests/driver/test_native_flow_pathological.py | 5 +- tests/driver/test_native_moving_guide.py | 8 +- .../driver/test_native_moving_guide_bound.py | 3 +- tests/driver/test_plane_adoption.py | 35 +- tests/driver/test_plane_observer.py | 8 +- tests/driver/test_profile_dispersion.py | 11 +- tests/driver/test_prop_capillary.py | 10 +- tests/driver/test_restart_record.py | 21 +- tests/driver/test_resume.py | 56 +- tests/driver/test_resume_history.py | 102 ++- tests/driver/test_run.py | 67 +- tests/driver/test_runner.py | 89 ++- tests/driver/test_scan_worker_validation.py | 6 +- tests/driver/test_sep12_sep14_integration.py | 47 +- tests/driver/test_snapshots.py | 3 +- tests/driver/test_solid_multimode.py | 6 +- tests/driver/test_stated_input.py | 8 +- .../driver/test_tdse_gated_derivative_run.py | 22 +- tests/driver/test_tdse_input_noise.py | 9 +- tests/driver/test_wall_production.py | 11 +- tests/modes/test_field_scale.py | 5 +- tests/parity_ladder.py | 6 +- tests/sessions/test_native_load.py | 6 +- .../test_native_session_axis_plasma.py | 9 +- tests/sessions/test_native_session_history.py | 3 +- .../test_native_session_low_storage.py | 17 +- .../test_native_session_statistics.py | 21 +- tests/sessions/test_split_collar_rules.py | 10 +- tests/test_helpers.py | 3 +- tests/test_split_crossing.py | 85 ++- tests/test_structure_figures.py | 8 +- tests/test_tools.py | 12 +- tests/translate/test_operator_settings.py | 6 +- tests/vector_raman_cases.py | 3 +- 102 files changed, 1960 insertions(+), 1480 deletions(-) diff --git a/benchmarks/worker.py b/benchmarks/worker.py index c241c2760..4f55ea173 100644 --- a/benchmarks/worker.py +++ b/benchmarks/worker.py @@ -59,7 +59,7 @@ if TYPE_CHECKING: import numpy as np - from solprop.backends.protocol import Backend, HostStepping + from solprop.backends.protocol import Backend from solprop.driver import Simulation from solprop.monitor import BoundaryMonitor from solprop.output.store import FieldRetention, Output @@ -202,8 +202,8 @@ class _Loaded: loaded, before the output opens and the launch plane is saved. Within the block the backend's load is wrapped to read the clock and the counter as it returns; it is restored on exit. The load is the native backend's own ``_load`` where it has - one (SEP 47 phase 5), else ``set_initial``, the reference's and an earlier - native build's. + one (SEP 47 phase 5), else the reference's workspace's ``load``, which its session + calls (SEP 52), else ``set_initial``, an earlier build's. Attributes ---------- @@ -215,28 +215,31 @@ class _Loaded: def __init__(self, engine: Backend) -> None: self._engine = engine - self._name = ( - "_load" - if callable(getattr(type(engine), "_load", None)) - else ("set_initial") - ) + workspace = getattr(engine, "workspace", None) + self._owner: object = engine + if callable(getattr(type(engine), "_load", None)): + self._name = "_load" + elif callable(getattr(type(workspace), "load", None)): + self._owner, self._name = workspace, "load" + else: + self._name = "set_initial" self.ended = 0 self.calls: int | None = None def _load(self, *args: object, **keywords: object) -> object: - loaded = getattr(type(self._engine), self._name)( - self._engine, *args, **keywords + loaded = getattr(type(self._owner), self._name)( + self._owner, *args, **keywords ) self.calls = source_calls(self._engine) self.ended = time.perf_counter_ns() return loaded def __enter__(self) -> _Loaded: - setattr(self._engine, self._name, self._load) + setattr(self._owner, self._name, self._load) return self def __exit__(self, kind: type[BaseException] | None, *rest: object) -> None: - delattr(self._engine, self._name) + delattr(self._owner, self._name) if kind is None and not self.ended: msg = "the run never loaded its backend, so nothing was timed" raise SuiteError(msg) @@ -298,7 +301,7 @@ def timed_run( if Start is None: # A build from before SEP 47's sessions: run_problem takes a loaded backend, # so the load comes first and the window starts after it, as it did then. - cast("HostStepping", engine).set_initial( + cast("Any", engine).set_initial( problem.initial.field0, None, z=problem.initial.z ) before = source_calls(engine) @@ -542,7 +545,7 @@ def warm_up(engine: Backend, problem: PropagationProblem, until: float) -> None: if Start is None: # Before SEP 47: load, march and observe the backend directly, through the # stepping seam every backend had then. - stepped = cast("HostStepping", engine) + stepped = cast("Any", engine) stepped.set_initial(problem.initial.field0, None, z=problem.initial.z) if until > problem.initial.z: stepped.propagate_to(until) diff --git a/docs/dev/figures/backends.svg b/docs/dev/figures/backends.svg index fc85044a4..b51640898 100644 --- a/docs/dev/figures/backends.svg +++ b/docs/dev/figures/backends.svg @@ -70,7 +70,7 @@ text { font-family: Inter, "Helvetica Neue", Helvetica, Arial, sans-serif; fill: .ink-x { fill: var(--x-edge); } -One seam, a shared driver, and the backends behind them +One seam, a session, 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. @@ -95,23 +95,23 @@ text { font-family: Inter, "Helvetica Neue", Helvetica, Arial, sans-serif; fill: backends.registry.select(name, problem, grid=, modes=, profiles=) -HostDriver (the reference's scheduler) +HostSession (the reference's schedule) the planes and the halts -propagate_to · _natural_stop · request_halt -the replay's cursor -_schedule_index_at +advance · natural_stop · request_snapshot +the load and the cursor +_load · _restore_march the history -_record · observe -the progress reporter -set_progress +record · _observe +the dense observation +_after_march · _here the statistics channel -_take_step_stats · stats +_account_step · _observation the boundary monitor -attach_monitor · _absorb · _boundary_energies +_attach · absorb · _energies · _warning the caps a march asks for -_quiet_capped · _transverse_capped -the march's state, read -_z · _proposal · _schedule_index +cap · collar_quiet +the march, driven +_propagate · stepped the stepper it drives stepper.tableau @@ -122,7 +122,7 @@ text { font-family: Inter, "Helvetica Neue", Helvetica, Arial, sans-serif; fill: stepper.schedule landing, discover, calibrate, replay the quadrature alarm -_begin_plane · _on_accepted_step +record · _propagate @@ -131,7 +131,7 @@ text { font-family: Inter, "Helvetica Neue", Helvetica, Arial, sans-serif; fill: one named function per pass the general representation, the z table included propagator_mode auto → tabulate -NumpyWorkspace · engines · marches +NumpyWorkspace · engines · marches · dense output @@ -140,7 +140,7 @@ text { font-family: Inter, "Helvetica Neue", Helvetica, Arial, sans-serif; fill: C++20 Kokkos + persistent Kokkos-FFT plans one native call per seven-stage trial OpenMP on CPUs; CUDA and HIP on GPUs -NumpyWorkspace · engines · marches -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. +NumpyWorkspace · engines · marches · dense output +Three things every backend owes beyond the methods: deterministic reductions, the device form of the stage, and the session'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 a4dc4c9b2..4d64af178 100644 --- a/docs/dev/figures/build.py +++ b/docs/dev/figures/build.py @@ -744,12 +744,11 @@ class Layer(NamedTuple): Module( "backends/host/", ( - "driver", + "session", "marches", "runge_kutta", "adams", "low_storage", - "session", ), ), Module( @@ -758,6 +757,7 @@ class Layer(NamedTuple): "backend", "workspace", "engines", + "dense", "passes", "multistep", "populations", @@ -974,13 +974,13 @@ class Stage(NamedTuple): "the march, the replay, the landing, the controller,", "the history, the noise, the per-stage bundle", ), - "HostDriver for numpy_ref; native's session", + "HostSession for numpy_ref; native's session", ), Stage( "D", "run loop over save planes", ( - "obs = backend.observe() stats = backend.stats(spec)", + "event = session.advance() field = session.export(ticket, recipe)", "output.save(SavedPlane(z, field, stats, step_history, step_stats))", ), "small host arrays, one fused pass", @@ -1250,24 +1250,24 @@ class Pass(NamedTuple): ("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 -`HostStepping`'s, which its session drives.""" +"""The methods of `backends.protocol.Backend`: a run is its session's, on every +backend.""" DRIVER_PARTS = ( - ("the planes and the halts", ("propagate_to", "_natural_stop", "request_halt")), - ("the replay's cursor", ("_schedule_index_at",)), - ("the history", ("_record", "observe")), - ("the progress reporter", ("set_progress",)), - ("the statistics channel", ("_take_step_stats", "stats")), - ("the boundary monitor", ("attach_monitor", "_absorb", "_boundary_energies")), - ("the caps a march asks for", ("_quiet_capped", "_transverse_capped")), - ("the march's state, read", ("_z", "_proposal", "_schedule_index")), - ("the quadrature alarm", ("_begin_plane", "_on_accepted_step")), + ("the planes and the halts", ("advance", "natural_stop", "request_snapshot")), + ("the load and the cursor", ("_load", "_restore_march")), + ("the history", ("record", "_observe")), + ("the dense observation", ("_after_march", "_here")), + ("the statistics channel", ("_account_step", "_observation")), + ("the boundary monitor", ("_attach", "absorb", "_energies", "_warning")), + ("the caps a march asks for", ("cap", "collar_quiet")), + ("the march, driven", ("_propagate", "stepped")), + ("the quadrature alarm", ("record", "_propagate")), ) -"""What `backends/host/driver.py` owns, and the `HostDriver` members of each part.""" +"""What `backends/host/session.py` owns, and the `HostSession` members of each part.""" CONTROLLER_PARTS = ("propose", "accepts", "rejection_factor", "equivalent_norm") -"""The methods of `stepper.controller.PIController` the driver calls.""" +"""The methods of `stepper.controller.PIController` the marches call.""" SCHEDULE_PARTS = ("landing", "discover", "calibrate", "replay") """The functions of `stepper.schedule` behind the landing and the fixed schedules.""" @@ -2554,8 +2554,8 @@ def _step_panel( _text(drawing, line, x + PAD + 8, cursor, size=SMALL_SIZE, klass="dim") -BACKEND_OVERRIDES = ("NumpyWorkspace", "engines", "marches") -"""What the reference backend supplies to `HostDriver`, and nothing else of the loop.""" +BACKEND_OVERRIDES = ("NumpyWorkspace", "engines", "marches", "dense output") +"""What the reference backend supplies to `HostSession`, and nothing else of the loop.""" DEVICE_SLOT = ( "solprop-native distribution, native/", @@ -2567,7 +2567,7 @@ def _step_panel( def backends() -> drawsvg.Drawing: - """Draw figure 5: the seam, the shared driver, and the backends behind it. + """Draw figure 5: the seam, the reference's session, and the backends behind it. Returns ------- @@ -2615,7 +2615,7 @@ def backends() -> drawsvg.Drawing: ) footer = ( "Three things every backend owes beyond the methods: deterministic " - "reductions, the device form of the stage, and the driver's bookkeeping. The " + "reductions, the device form of the stage, and the session's bookkeeping. The " "error norm is control flow, so a sum whose association depends on the thread " "count forks the trajectory." ) @@ -2635,7 +2635,7 @@ def backends() -> drawsvg.Drawing: drawing = _canvas(height) _header( - drawing, "One seam, a shared driver, and the backends behind them", subtitle + drawing, "One seam, a session, and the backends behind them", subtitle ) y = top @@ -2659,7 +2659,7 @@ def backends() -> drawsvg.Drawing: _table( drawing, Slot(MARGIN, y, left_width), - "HostDriver (the reference's scheduler)", + "HostSession (the reference's schedule)", driver_rows, 168, Paint("fill-d", "ink-d"), diff --git a/docs/dev/figures/layers.svg b/docs/dev/figures/layers.svg index 213904bc5..d77e2752a 100644 --- a/docs/dev/figures/layers.svg +++ b/docs/dev/figures/layers.svg @@ -189,15 +189,16 @@ text { font-family: Inter, "Helvetica Neue", Helvetica, Arial, sans-serif; fill: exponential · low_storage · session events · export · session_core sessions - + backends/host/ -driver · marches · runge_kutta -adams · low_storage · session - -backends/numpy_ref/ -backend · workspace · engines -passes · multistep · populations -envelope_plasma · general_modal +session · marches · runge_kutta +adams · low_storage + +backends/numpy_ref/ +backend · workspace · engines +dense · passes · multistep +populations · envelope_plasma +general_modal D diff --git a/docs/dev/figures/one_run.svg b/docs/dev/figures/one_run.svg index a4757b063..735d25e15 100644 --- a/docs/dev/figures/one_run.svg +++ b/docs/dev/figures/one_run.svg @@ -108,13 +108,14 @@ text { font-family: Inter, "Helvetica Neue", Helvetica, Arial, sans-serif; fill: z, n_steps, n_rejected, max_norm, mean_norm, wall_time -HostDriver for numpy_ref; -native's session +HostSession for +numpy_ref; native's +session run loop over save planes -obs = backend.observe() stats = backend.stats(spec) +event = session.advance() field = session.export(ticket, recipe) output.save(SavedPlane(z, field, stats, step_history, step_stats)) Observation → SavedPlane diff --git a/native/tests/plasma_bounds.py b/native/tests/plasma_bounds.py index 6ca7f773a..92e39fd58 100644 --- a/native/tests/plasma_bounds.py +++ b/native/tests/plasma_bounds.py @@ -241,7 +241,7 @@ def node_field_error( # within fft_bound of the field's 2-norm over every node and sample. size = grids.n_to * transform.n_nodes return np.full(fields.shape, fft_bound(size) * float(np.linalg.norm(fields))) - state = reference._require_state() # pyright: ignore[reportPrivateUsage] + state = reference.workspace.committed() # pyright: ignore[reportPrivateUsage] kind = reference.workspace._kind # pyright: ignore[reportPrivateUsage] bundle = reference.workspace.stage_scalars(0.0, 0.0) # pyright: ignore[reportPrivateUsage] taper = float(bundle.taper_scale) @@ -409,16 +409,21 @@ def plasma_stage_bound( """ reference = NumpyRefBackend(problem, run_request, grid=grid) try: - reference.set_initial(problem.initial.field0, None) + reference.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe - state = reference._require_state() # pyright: ignore[reportPrivateUsage] + state = reference.workspace.committed() # pyright: ignore[reportPrivateUsage] bundle = reference.workspace.stage_scalars(0.0, 0.0) # pyright: ignore[reportPrivateUsage] stage = reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] state, bundle, np.ones(problem.shape, complex) ) fields = np.real( np.concatenate( - list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, 0.0)) # pyright: ignore[reportPrivateUsage] ) ) field_error = node_field_error(reference, problem, fields) diff --git a/native/tests/test_backend.py b/native/tests/test_backend.py index 93fc19ee9..3392eb0bf 100644 --- a/native/tests/test_backend.py +++ b/native/tests/test_backend.py @@ -885,11 +885,16 @@ def test_packed_real_blas_radial_envelope_matches_the_reference_when_eligible() ) reference = NumpyRefBackend(problem, run_request, grid=grid) try: - reference.set_initial(problem.initial.field0, None) + reference.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] expected = np.asarray( reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] - reference._require_state(), # pyright: ignore[reportPrivateUsage] + reference.workspace.committed(), # pyright: ignore[reportPrivateUsage] reference.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] np.ones(problem.shape, complex), ) diff --git a/native/tests/test_band_column_budget.py b/native/tests/test_band_column_budget.py index 015075328..f6a4389b9 100644 --- a/native/tests/test_band_column_budget.py +++ b/native/tests/test_band_column_budget.py @@ -226,10 +226,15 @@ def stages( """Return native's and the reference's first stage on the launch.""" reference = NumpyRefBackend(problem, run_request, grid=GRID) try: - reference.set_initial(problem.initial.field0, None) + reference.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe expected = reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] - reference._require_state(), # pyright: ignore[reportPrivateUsage] + reference.workspace.committed(), # pyright: ignore[reportPrivateUsage] reference.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] np.ones(problem.shape, complex), ) @@ -274,13 +279,18 @@ def launch_fraction_bound( dt = GRID.dt_fine reference = NumpyRefBackend(problem, run_request, grid=GRID) try: - reference.set_initial(problem.initial.field0, None) + reference.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe - state = reference._require_state() # pyright: ignore[reportPrivateUsage] + state = reference.workspace.committed() # pyright: ignore[reportPrivateUsage] bundle = reference.workspace.stage_scalars(0.0, 0.0) # pyright: ignore[reportPrivateUsage] fields = np.real( np.concatenate( - list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, 0.0)) # pyright: ignore[reportPrivateUsage] ) ) field_error = node_field_error(reference, problem, fields) diff --git a/native/tests/test_band_pathological.py b/native/tests/test_band_pathological.py index ae6086c6c..9159f7060 100644 --- a/native/tests/test_band_pathological.py +++ b/native/tests/test_band_pathological.py @@ -168,11 +168,13 @@ def synthesised( """Return the reference's node fields of `field`, ``(nodes, n_pol, n_to)``.""" reference = NumpyRefBackend(problem, run_request, grid=grid) try: - reference.set_initial(field, None) - state = reference._require_state() # pyright: ignore[reportPrivateUsage] + reference.workspace.load( + np.ascontiguousarray(field, dtype=complex), None, z=0.0, resume=False + ) + state = reference.workspace.committed() # pyright: ignore[reportPrivateUsage] return np.real( np.concatenate( - list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, 0.0)) # pyright: ignore[reportPrivateUsage] ) ) finally: @@ -185,10 +187,15 @@ def source_of_reference( """Return the reference's first stage on the launch, ``N(E, z = 0)``.""" reference = NumpyRefBackend(problem, run_request, grid=grid) try: - reference.set_initial(problem.initial.field0, None) + reference.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe return reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] - reference._require_state(), # pyright: ignore[reportPrivateUsage] + reference.workspace.committed(), # pyright: ignore[reportPrivateUsage] reference.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] np.ones(problem.shape, complex), ) diff --git a/native/tests/test_band_plasma.py b/native/tests/test_band_plasma.py index 570792e2a..a0e20dbcf 100644 --- a/native/tests/test_band_plasma.py +++ b/native/tests/test_band_plasma.py @@ -432,10 +432,15 @@ def test_one_evaluation_matches_the_reference() -> None: grid, problem, run_request = spatial("radial") reference = NumpyRefBackend(problem, run_request, grid=grid) try: - reference.set_initial(problem.initial.field0, None) + reference.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe expected = reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] - reference._require_state(), # pyright: ignore[reportPrivateUsage] + reference.workspace.committed(), # pyright: ignore[reportPrivateUsage] reference.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] np.ones(problem.shape, complex), ) @@ -482,12 +487,15 @@ def test_every_stage_of_a_trial_matches_the_reference( dz = float(run_request.stepper.save_planes[-1]) / STEPS reference = NumpyRefBackend(problem, run_request, grid=grid) try: - reference.set_initial(problem.initial.field0, None) - reference._runge_kutta_engine.trial(0.0, dz) # pyright: ignore[reportPrivateUsage] - oracle - expected = [ - np.asarray(stage) - for stage in reference._runge_kutta_engine.stages # pyright: ignore[reportPrivateUsage] - ] + reference.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) + engine = reference._runge_kutta(reference.workspace) # pyright: ignore[reportPrivateUsage] - oracle + engine.trial(0.0, dz) + expected = [np.asarray(stage) for stage in engine.stages] finally: reference.close() backend = NativeBackend(problem, run_request, grid=grid) diff --git a/native/tests/test_band_statistics_per_node.py b/native/tests/test_band_statistics_per_node.py index 1007615bd..b81e31548 100644 --- a/native/tests/test_band_statistics_per_node.py +++ b/native/tests/test_band_statistics_per_node.py @@ -142,11 +142,13 @@ def fields_of( """Return the reference's node fields for the state `field`.""" reference = NumpyRefBackend(problem, run_request, grid=GRID) try: - reference.set_initial(field, None) - state = reference._require_state() # pyright: ignore[reportPrivateUsage] + reference.workspace.load( + np.ascontiguousarray(field, dtype=complex), None, z=0.0, resume=False + ) + state = reference.workspace.committed() # pyright: ignore[reportPrivateUsage] return np.real( np.concatenate( - list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, 0.0)) # pyright: ignore[reportPrivateUsage] ) ) finally: @@ -169,12 +171,17 @@ def node_fields_and_error( """Return the reference's launch node fields and their error between syntheses.""" reference = NumpyRefBackend(problem, run_request, grid=grid) try: - reference.set_initial(problem.initial.field0, None) - state = reference._require_state() # pyright: ignore[reportPrivateUsage] + reference.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) + state = reference.workspace.committed() # pyright: ignore[reportPrivateUsage] reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe fields = np.real( np.concatenate( - list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, 0.0)) # pyright: ignore[reportPrivateUsage] ) ) return fields, node_field_error(reference, problem, fields) diff --git a/native/tests/test_band_stress.py b/native/tests/test_band_stress.py index f00fe9523..ed196b3d2 100644 --- a/native/tests/test_band_stress.py +++ b/native/tests/test_band_stress.py @@ -198,10 +198,15 @@ def node_fields( """Return the reference's node fields at the launch plane, (nodes, n_pol, n_to).""" reference = NumpyRefBackend(problem, run_request, grid=grid) try: - reference.set_initial(problem.initial.field0, None) - state = reference._require_state() # pyright: ignore[reportPrivateUsage] + reference.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) + state = reference.workspace.committed() # pyright: ignore[reportPrivateUsage] return np.concatenate( - list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, 0.0)) # pyright: ignore[reportPrivateUsage] ) finally: reference.close() @@ -272,10 +277,15 @@ def test_one_evaluation_matches_the_reference(kind: str) -> None: assert_is_stressing(kind, problem, run_request, grid) reference = NumpyRefBackend(problem, run_request, grid=grid) try: - reference.set_initial(problem.initial.field0, None) + reference.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe expected = reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] - reference._require_state(), # pyright: ignore[reportPrivateUsage] + reference.workspace.committed(), # pyright: ignore[reportPrivateUsage] reference.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] np.ones(problem.shape, complex), ) @@ -327,13 +337,18 @@ def test_the_launch_exposure_is_within_its_scan_bound(kind: str) -> None: dt = grid.dt_fine reference = NumpyRefBackend(problem, run_request, grid=grid) try: - reference.set_initial(problem.initial.field0, None) + reference.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] - oracle probe - state = reference._require_state() # pyright: ignore[reportPrivateUsage] + state = reference.workspace.committed() # pyright: ignore[reportPrivateUsage] bundle = reference.workspace.stage_scalars(0.0, 0.0) # pyright: ignore[reportPrivateUsage] fields = np.real( np.concatenate( - list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, 0.0)) # pyright: ignore[reportPrivateUsage] ) ) field_error = node_field_error(reference, problem, fields) diff --git a/native/tests/test_dispersive.py b/native/tests/test_dispersive.py index 04a25c61e..d9110e49c 100644 --- a/native/tests/test_dispersive.py +++ b/native/tests/test_dispersive.py @@ -325,7 +325,12 @@ def test_one_evaluation_matches_the_reference(evaluator: str, thg: bool) -> None native_trial(backend, 0.0, 0.0) spectra.append(_testing.projected_to_host(state, False)) else: - backend.set_initial(problem.initial.field0, None) + backend.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) backend.workspace.lab_source(problem.initial.field0, 0.0) projected = np.asarray(backend.workspace._last_projected) # pyright: ignore[reportPrivateUsage] spectra.append(np.asarray(np.fft.rfft(projected, axis=-1))) diff --git a/native/tests/test_envelope_plasma.py b/native/tests/test_envelope_plasma.py index 881fa46c7..8f6bb2af0 100644 --- a/native/tests/test_envelope_plasma.py +++ b/native/tests/test_envelope_plasma.py @@ -179,7 +179,12 @@ def test_envelope_current_streams_use_large_radial_projection() -> None: NativeBackend(problem, run_request, grid=grid), ) try: - reference.set_initial(problem.initial.field0, None) + reference.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) expected = reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] problem.initial.field0, reference.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] diff --git a/native/tests/test_envelope_subnormal.py b/native/tests/test_envelope_subnormal.py index 3c0589c8b..37bdac8fc 100644 --- a/native/tests/test_envelope_subnormal.py +++ b/native/tests/test_envelope_subnormal.py @@ -126,10 +126,15 @@ def evaluate( native_trial(backend, 0.0, 0.0) stage = np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) else: - backend.set_initial(problem.initial.field0, None) + backend.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) backend.workspace.hoist(0.0) stage = backend.workspace.nonlinear( # pyright: ignore[reportAttributeAccessIssue, reportPrivateUsage, reportUnknownMemberType, reportUnknownVariableType] - backend._require_state(), # pyright: ignore[reportArgumentType, reportPrivateUsage] + backend.workspace.committed(), backend.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportAttributeAccessIssue] np.ones(problem.shape, complex), ) @@ -144,10 +149,15 @@ def node_magnitude( """Return the largest node field the reference synthesises, V/m.""" reference = NumpyRefBackend(problem, run_request, grid=grid) try: - reference.set_initial(problem.initial.field0, None) - state = reference._require_state() # pyright: ignore[reportPrivateUsage] + reference.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) + state = reference.workspace.committed() # pyright: ignore[reportPrivateUsage] nodes = np.concatenate( - list(reference.workspace._plasma_nodes(state, reference._z)) # pyright: ignore[reportPrivateUsage] + list(reference.workspace._plasma_nodes(state, 0.0)) # pyright: ignore[reportPrivateUsage] ) return float(np.max(np.abs(nodes))) finally: diff --git a/native/tests/test_radial.py b/native/tests/test_radial.py index 76a85e414..5ea6577a0 100644 --- a/native/tests/test_radial.py +++ b/native/tests/test_radial.py @@ -107,11 +107,16 @@ def test_radial_partial_chunks_preserve_the_reference_source( assert bound > 0 reference = NumpyRefBackend(problem, run_request, grid=grid, options=options) try: - reference.set_initial(problem.initial.field0, None) + reference.workspace.load( + np.ascontiguousarray(problem.initial.field0, dtype=complex), + None, + z=0.0, + resume=False, + ) reference.workspace.hoist(0.0) # pyright: ignore[reportPrivateUsage] expected = np.asarray( reference.workspace.nonlinear( # pyright: ignore[reportPrivateUsage] - reference._require_state(), # pyright: ignore[reportPrivateUsage] + reference.workspace.committed(), # pyright: ignore[reportPrivateUsage] reference.workspace.stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] np.ones(problem.shape, complex), ) diff --git a/src/solprop/backends/numpy_ref/backend.py b/src/solprop/backends/numpy_ref/backend.py index aebd9f313..9426960e4 100644 --- a/src/solprop/backends/numpy_ref/backend.py +++ b/src/solprop/backends/numpy_ref/backend.py @@ -26,11 +26,13 @@ import numpy as np from jaxtyping import Complex +from solprop._helpers import Helpers from solprop.backends.exponential import ( CarrierReference, refuse_carrier_frame, refuse_formulation, ) +from solprop.backends.host.adams import HostAdamsMarch from solprop.backends.host.low_storage import HostLowStorageMarch from solprop.backends.host.runge_kutta import RungeKuttaMarch from solprop.backends.host.session import HostMethod, HostPrepared, start_position @@ -170,16 +172,16 @@ class NumpyRefBackend: >>> session.close() """ - reads_transverse_edge = True + reads_transverse_edge: bool = True - name = "numpy_ref" + name: str = "numpy_ref" # 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 = NumpyWorkspace.helpers + helpers: Helpers = NumpyWorkspace.helpers # The reference forms `exp(+dPhi)` and `exp(-dPhi)` afresh at every stage, so # keeping the six distinct exponents of a step is worth its memory here where it is # not on a backend that takes both signs from one transcendental. - propagator_default = "tabulate" + propagator_default: PropagatorMode = "tabulate" def __init__( self, @@ -334,7 +336,6 @@ def _adams(self, method: Multistep, host: object) -> HostMethod: """Return the Adams march over a fresh engine, its dense output and rows.""" # The engine reads this package's passes, so it is imported when a run asks # for it rather than with the package. - from solprop.backends.host.adams import HostAdamsMarch # noqa: PLC0415 from solprop.backends.numpy_ref.dense import AdamsDense # noqa: PLC0415 from solprop.backends.numpy_ref.multistep import ( # noqa: PLC0415 AdamsKernels, @@ -401,7 +402,9 @@ def workspace(self) -> NumpyWorkspace: # numpydoc ignore=RT01 return self._workspace @property - def march(self) -> object: # numpydoc ignore=RT01 + def march( + self, + ) -> RungeKuttaMarch | HostAdamsMarch | HostLowStorageMarch: # numpydoc ignore=RT01 """The latest run's march: a session's, the timing probe's, or a fresh one.""" return self._run.march diff --git a/src/solprop/backends/numpy_ref/workspace.py b/src/solprop/backends/numpy_ref/workspace.py index 3ca1f31a3..d4e927334 100644 --- a/src/solprop/backends/numpy_ref/workspace.py +++ b/src/solprop/backends/numpy_ref/workspace.py @@ -524,7 +524,7 @@ def committed(self) -> _State: If no state is loaded. """ if self._state is None: - msg = "no initial state: call set_initial before propagating or observing" + msg = "no initial state: start a session before propagating or observing" raise BackendError(msg) return self._state diff --git a/tests/backends/carrier_frame_cases.py b/tests/backends/carrier_frame_cases.py index 7a0c970a5..efa61fbb5 100644 --- a/tests/backends/carrier_frame_cases.py +++ b/tests/backends/carrier_frame_cases.py @@ -12,6 +12,7 @@ import dataclasses import functools import warnings +from typing import Any, cast import numpy as np @@ -153,7 +154,7 @@ def matched_window(simulation: Simulation, *, compensated: bool = False) -> Buil try: result = run(backend, problem, run_request, record={}) attempts = result.joined[0] - march = backend._adams + march = cast("Any", backend.march) assert march is not None assert not compensated or march._engine.compensated finally: diff --git a/tests/backends/native_mixture_launch_probe.py b/tests/backends/native_mixture_launch_probe.py index b5c9fb2c6..6f0c15849 100644 --- a/tests/backends/native_mixture_launch_probe.py +++ b/tests/backends/native_mixture_launch_probe.py @@ -26,6 +26,7 @@ if importlib.util.find_spec("solprop_native") is not None: importlib.import_module("solprop_native") +from builders import load_reference from mixture_cases import mixture_translation from sessions.runs import launch_statistics as state_statistics from solprop.backends.numpy_ref import NumpyRefBackend @@ -70,12 +71,11 @@ def launch_case(kerr, n_pol): ) reference = NumpyRefBackend(problem, run_request, grid=grid) try: - reference.set_initial(problem.initial.field0, None) + state = load_reference(reference) reference.workspace.hoist(0.0) - state = reference._require_state() peak = max( float(np.max(abs(one))) - for one in reference.workspace._plasma_nodes(state, reference._z) + for one in reference.workspace._plasma_nodes(state, problem.initial.z) ) finally: reference.close() diff --git a/tests/backends/rk_traces.py b/tests/backends/rk_traces.py index 1c0bd6e85..ed445cad7 100644 --- a/tests/backends/rk_traces.py +++ b/tests/backends/rk_traces.py @@ -9,7 +9,8 @@ own rules (:func:`~solprop.backends.host.session.step_cap`, :func:`~solprop.backends.host.session.natural_stop`), so every decision the march makes -- acceptance, the next proposal, the landing, the start-up rule, the caps, the -floor, a natural stop -- is a function of the scenario's data alone, with no field arithmetic. +floor, a natural stop -- is a function of the scenario's data alone, with no field +arithmetic. The corpus ``tests/data/rk_traces.json.gz`` was generated by ``tests/data/generate_rk_traces.py`` from the march as it stood before SEP 45's diff --git a/tests/backends/synthetic_leaf_cases.py b/tests/backends/synthetic_leaf_cases.py index e75f303cc..805613546 100644 --- a/tests/backends/synthetic_leaf_cases.py +++ b/tests/backends/synthetic_leaf_cases.py @@ -20,6 +20,7 @@ from backends.low_storage_cases import MARCH, parity_bound from bounds import propagation_growth, step_evaluations +from builders import load_reference from solprop.backends.numpy_ref import NumpyRefBackend from solprop.boundaries import absorber from solprop.grid import EnvelopeGrid, FreeGrid @@ -191,9 +192,8 @@ def nonlinear_rate(problem, run_request, grid): """Return ``3 |N| / |a|`` on the launch, the Kerr term's Lipschitz bound, 1/m.""" reference = NumpyRefBackend(problem, run_request, grid=grid) try: - reference.set_initial(problem.initial.field0, None) + state = load_reference(reference) reference.workspace.hoist(0.0) - state = reference._require_state() stage = reference.workspace.nonlinear( state, reference.workspace.stage_scalars(0.0, 0.0), diff --git a/tests/backends/test_absorber_schemes.py b/tests/backends/test_absorber_schemes.py index dbc4f679b..0c7e69c59 100644 --- a/tests/backends/test_absorber_schemes.py +++ b/tests/backends/test_absorber_schemes.py @@ -48,7 +48,7 @@ import numpy as np import pytest -from sessions.runs import final_field +from sessions.runs import bare, final_field from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.passes import apply_temporal_rate from solprop.boundaries import STABILITY_RADIUS, absorber, stable_step @@ -116,9 +116,7 @@ def exit_field(grid, scheme, n_steps): problem, run_request = biting_case(grid, scheme, n_steps) backend = NumpyRefBackend(problem, run_request, grid=grid) try: - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(LENGTH) - return backend.observe().require_field()[0, 0].copy() + return final_field(backend, problem, bare(run_request), z=LENGTH)[0, 0].copy() finally: backend.close() diff --git a/tests/backends/test_adams_natural_kink.py b/tests/backends/test_adams_natural_kink.py index 4d8d67ac7..e3d9d1b50 100644 --- a/tests/backends/test_adams_natural_kink.py +++ b/tests/backends/test_adams_natural_kink.py @@ -100,12 +100,12 @@ def _march(session: Any) -> tuple[dict[str, int], int, list[int]]: """Return a session's Adams march: four of its counters, its history's length and the order of every accepted step. - The reference's march is its driver's (:class:`~solprop.backends.host.session. + The reference's march is its session's own (:class:`~solprop.backends.host.session. HostSession`); the native session's is the native march's state. """ names = ("accepted_steps", "rejected_steps", "restarts", "startup") if isinstance(session, HostSession): - march = cast("Any", session.driver)._adams + march = cast("Any", session)._march counters = {name: int(getattr(march.ledger, name)) for name in names} return counters, len(march._history), list(march.ledger.orders) state = session.native.march_state(0) diff --git a/tests/backends/test_backend_ladder.py b/tests/backends/test_backend_ladder.py index 9db5dc405..07cccf402 100644 --- a/tests/backends/test_backend_ladder.py +++ b/tests/backends/test_backend_ladder.py @@ -43,6 +43,8 @@ from convergence_records import record from convergence_studies import BACKEND_EQUIVALENCE from sessions.runs import run as session_run +from solprop.backends.events import ObservationReady +from solprop.backends.export import ExportRecipe from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.session import Start from solprop.stepper import FixedSchedule, PIController @@ -367,15 +369,24 @@ def test_a_resume_continues_where_the_run_stopped( assert disagreement(resumed, whole[1]) < 32 * EPS -def test_the_observation_hook_is_the_identity_on_the_reference( - soliton_problem, narrow_grid -): - """The device-state hook cannot copy or perturb the reference's state.""" +def test_the_observation_is_the_reference_s_state(soliton_problem, narrow_grid): + """A session's observation neither copies a perturbed state nor perturbs it.""" problem, run_request = soliton_problem(narrow_grid, 1, save_planes=[0.01]) backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) try: - backend.set_initial(problem.initial.field0, None) - state = backend._require_state() - assert np.array_equal(backend.observe().require_field(), state) + session = backend.prepare(problem, run_request).start( + Start.entrance(problem), owns=False + ) + try: + launch = session.advance() + state = backend.workspace.committed() + event = launch.events[0] + assert isinstance(event, ObservationReady) + ticket = event.ticket + observed = session.export(ticket, ExportRecipe(power=False, optics=False)) + assert np.array_equal(observed, state) + assert backend.workspace.committed() is state + finally: + session.close() finally: backend.close() diff --git a/tests/backends/test_backend_protocol.py b/tests/backends/test_backend_protocol.py index 5bc32d094..20bdaf2a7 100644 --- a/tests/backends/test_backend_protocol.py +++ b/tests/backends/test_backend_protocol.py @@ -20,8 +20,6 @@ ) from solprop.backends.host.session import HostPrepared from solprop.exceptions import BackendError -from solprop.log import NullReporter -from solprop.stats import StatsSpec from solprop.translate.run_request import RunRequest @@ -386,11 +384,10 @@ def test_a_negative_or_infinite_measure_is_refused(name): class Stub: - """The smallest object that satisfies the seam.""" + """The smallest object that satisfies the seam: SEP 52 section 5.1's members.""" name = "stub" reads_transverse_edge = False - in_flight = None closed = False @property @@ -398,56 +395,23 @@ def request(self) -> RunRequest: """The run's request: the stub runs nothing, so it holds none.""" raise NotImplementedError - def set_initial(self, field, noise, *, z=0.0, resume=False): - self.field = field - def prepare(self, problem, request): return HostPrepared(self, problem, request) - def restore_call_ledgers(self, logical, atomic=None): - return None - - def set_progress(self, reporter): - self.reporter = reporter - - def set_stop(self, flag): - return None - def edge_memory(self, space): return 0 - def attach_monitor(self, monitor): - return None - - def march_snapshot(self): - return None - - def march_snapshot_nbytes(self, z): - return None - def march_export_refusal(self): return None - def restore_march(self, snapshot): - return None - def timing_probe(self, start): raise NotImplementedError - def propagate_to(self, z): - return StepSummary(z, 1, 0, 0.5, 0.5, 0.0, True) - - def observe(self, *, field=True): - return Observation(0.0, self.field if field else None, None, history(1), 1, 0) - - def stats(self, spec): - return {name: np.zeros(1) for name in spec.names} - def metadata(self) -> dict[str, object]: return {"backend": self.name, "propagator_mode": "tabulate"} def memory_ledger(self): - return {"state": self.field.nbytes} + return {"state": 64} def available_device_memory(self): return None @@ -459,12 +423,8 @@ def close(self): def test_a_minimal_backend_satisfies_the_protocol(): backend = Stub() assert isinstance(backend, Backend) - backend.set_initial(np.zeros((1, 1, 4), complex), None) - assert backend.restore_call_ledgers({}) is None - backend.set_progress(NullReporter()) - assert backend.propagate_to(0.5).z == 0.5 - assert backend.observe().require_field().shape == (1, 1, 4) - assert backend.stats(StatsSpec(names=("energy",))) == {"energy": pytest.approx(0.0)} + assert backend.edge_memory(None) == 0 + assert backend.march_export_refusal() is None assert backend.memory_ledger() == {"state": 64} assert backend.available_device_memory() is None assert backend.metadata()["backend"] == "stub" @@ -475,7 +435,7 @@ def test_an_object_missing_a_method_is_not_a_backend(): class Partial: name = "partial" - def set_initial(self, field, noise): + def prepare(self, problem, request): return None assert not isinstance(Partial(), Backend) diff --git a/tests/backends/test_carrier_frame.py b/tests/backends/test_carrier_frame.py index f6ebb1171..2e6de7ffb 100644 --- a/tests/backends/test_carrier_frame.py +++ b/tests/backends/test_carrier_frame.py @@ -34,8 +34,9 @@ from backends.carrier_frame_cases import WINDOW, capillary, gradient from backends.conftest import EQUIVALENCE_BACKENDS from bounds import EPS, assert_within, carrier_increment_budget -from sessions.runs import adams_ledger, run -from solprop.backends.events import ObservationKind +from sessions.executors import IDENTITY, Started, drive +from sessions.runs import adams_ledger, bare, final_field, run +from solprop.backends.events import ObservationKind, ObservationReady from solprop.backends.exponential import ( CarrierReference, _carrier_refusal, # pyright: ignore[reportPrivateUsage] @@ -46,6 +47,7 @@ phi_functions, refuse_carrier_frame, ) +from solprop.backends.host.adams import HostAdamsMarch from solprop.backends.ledger import CallLedger from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.multistep import ( @@ -54,6 +56,8 @@ HostHistory, coupled_moments, ) +from solprop.backends.session import Start +from solprop.backends.sessions import start_session from solprop.driver import Simulation, SimulationSettings from solprop.exceptions import BackendError, SolpropWarning, StepperError from solprop.grid import EnvelopeGrid, FreeGrid @@ -217,7 +221,7 @@ def lab_source(lab, position, *, purpose="predictor"): / float(np.max(np.abs(exact * active))) ) attempts = result.joined[0] - march = getattr(backend, "_adams", None) if _on_host(backend) else None + march = _adams_march(backend) return SimpleNamespace( fields=fields, errors=errors, @@ -231,10 +235,18 @@ def lab_source(lab, position, *, purpose="predictor"): def _on_host(backend) -> bool: - """Return whether a backend is the reference, whose march is its own driver's.""" + """Return whether a backend is the reference, whose march a test can read.""" return backend.name == "numpy_ref" +def _adams_march(backend): + """Return the reference's last run's Adams march, or ``None`` for any other.""" + if not _on_host(backend): + return None + march = backend.march + return march if isinstance(march, HostAdamsMarch) else None + + def _ledger(backend, record) -> CallLedger | None: """Return an Adams run's call ledger, or ``None`` for a Runge-Kutta run.""" if not isinstance(backend.request.stepper.integrator, Multistep): @@ -850,9 +862,8 @@ def gradient_run( ) try: backend._use_adams(method, compensation=compensation) - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(float(run_request.stepper.save_planes[-1])) - return backend.observe().require_field(), backend._adams + field = final_field(backend, problem, bare(run_request), ended=True) + return field, cast("Any", backend.march) finally: backend.close() @@ -949,7 +960,7 @@ def coupled_run(name, integrator, rtol, backend_class=NumpyRefBackend): try: record: dict[str, object] = {} field = run(backend, problem, run_request, record=record).fields[-1] - march = getattr(backend, "_adams", None) if _on_host(backend) else None + march = _adams_march(backend) return field, SimpleNamespace(march=march, ledger=_ledger(backend, record)) finally: backend.close() @@ -981,14 +992,19 @@ def test_a_snapshot_continues_only_under_its_own_policy(): first = NumpyRefBackend( problem, run_request, grid=simulation.grid, modes=simulation.modes ) + held = {} + + def keep(session, batch): + # The method history at the second plane, as a snapshot service takes it. + for event in batch.events: + if isinstance(event, ObservationReady) and event.z == planes[1]: + held["stored"] = session.march_snapshot(event.ticket) + try: - first.set_initial(problem.initial.field0, None) - first.propagate_to(planes[1]) - stored = first.march_snapshot() - first.propagate_to(planes[-1]) - continued = first.observe().require_field() + continued = run(first, problem, bare(run_request), between=keep).fields[-1] finally: first.close() + stored = held.get("stored") assert stored is not None # Under the same policy the saved history continues; with the same steps, orders # and history it agrees with the in-memory continuation within a rounding budget @@ -997,12 +1013,15 @@ def test_a_snapshot_continues_only_under_its_own_policy(): problem, run_request, grid=simulation.grid, modes=simulation.modes ) try: - second.set_initial(problem.initial.field0, None, z=stored.z) - assert second.restore_march(stored) is None - second.propagate_to(planes[-1]) - resumed = second.observe().require_field() - assert second._adams is not None - steps = second._adams.ledger.accepted_steps + session = start_session( + second, problem, bare(run_request), _resumed(stored, planes), owns=False + ) + try: + assert cast("Any", session).march_refusal is None + resumed = drive(Started(session), export=IDENTITY).fields[-1] + finally: + session.close() + steps = cast("Any", second.march).ledger.accepted_steps finally: second.close() assert_within(resumed, continued, max(steps, 1) * 512 * EPS, what="resumed history") @@ -1015,13 +1034,31 @@ def test_a_snapshot_continues_only_under_its_own_policy(): problem, other, grid=simulation.grid, modes=simulation.modes ) try: - backend.set_initial(problem.initial.field0, None, z=stored.z) - reason = backend.restore_march(stored) + session = start_session( + backend, problem, other, _resumed(stored, planes), owns=False + ) + reason = cast("Any", session).march_refusal + session.close() finally: backend.close() assert reason is not None and "scalar-frame" in reason +def _resumed(stored, planes): + """Return the start of a resume from a snapshot at a saved plane. + + Its own plane is observed again, so that a resume at the last plane still reports + the state it holds. + """ + return Start( + field=np.array(stored.state), + z=stored.z, + plane_index=planes.index(stored.z) + 1, + march=stored, + resume=True, + ) + + # --- the parity rounding budget ------------------------------------------------------- diff --git a/tests/backends/test_driver.py b/tests/backends/test_driver.py index 9549cc146..b16e8f1cd 100644 --- a/tests/backends/test_driver.py +++ b/tests/backends/test_driver.py @@ -2,32 +2,37 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The reference's step loop, driven through a stage evaluation that is not a backend. +"""The reference's step control, driven through a stage evaluation that is scripted. -:class:`solprop.backends.host.driver.HostDriver` is the marching half of the NumPy -reference with the kernels left abstract, so it can be tested with a stage evaluation -whose answers are scripted. That is the point: every claim here is about the *step +The reference's session (:class:`solprop.backends.host.session.HostSession`) schedules +a run and drives its march; here the march's engine is a script +(:class:`scripted_driver.HostScriptedDriver`), so every claim is about the *step control* -- landing, acceptance, the controller's state, the history, the noise models, -the guards -- and none of them depends on any physics being evaluated correctly, which -is what makes the same assertions true of every reference backend that inherits it. -The descriptor and stage bundles a compiled backend is built against are frozen here -too (``docs/dev/kernel-contract.md``). +the guards, the statistics rows -- and none of them depends on any physics being +evaluated correctly. The descriptor, the stage bundles and the backend surface a +compiled backend is built against are frozen here too (``docs/dev/kernel-contract.md``). """ import dataclasses -import inspect import io import logging +import sys import typing +from typing import Any, cast import numpy as np import pytest from bounds import assert_within from scripted_driver import HostScriptedDriver -from solprop.backends.host.driver import INITIAL_STEP_STATS_CAPACITY, HostDriver +from sessions.executors import IDENTITY, Started, drive +from sessions.runs import run +from solprop.backends.events import ObservationReady +from solprop.backends.host.session import INITIAL_STEP_STATS_CAPACITY from solprop.backends.numpy_ref import NumpyRefBackend -from solprop.backends.protocol import StepStats +from solprop.backends.numpy_ref.dense import RungeKuttaDense +from solprop.backends.protocol import Backend +from solprop.backends.session import Start from solprop.exceptions import BackendError from solprop.log import BarReporter, LogReporter, NullReporter from solprop.noise import input_noise, modified_noise @@ -48,29 +53,69 @@ def present(value): """Return an optional array, having asserted that it is there. - The state and the noise are ``None`` before ``set_initial`` and after ``close``, so - the seam types them optional; a test that has just loaded one says so here rather - than asserting around it at every use. + The state and the noise are ``None`` before a start is loaded and after ``close``, + so the seam types them optional; a test that has just loaded one says so here + rather than asserting around it at every use. """ assert value is not None return value +def resumed(run_request, problem, z, *, field=None, noise=None): + """Return a start resuming at `z`, whose plane the run already saved.""" + planes = np.asarray(run_request.stepper.save_planes) + return Start( + field=problem.initial.field0 if field is None else field, + z=float(z), + noise=noise, + plane_index=int(np.searchsorted(planes, z, side="right")), + plane_pending=False, + ) + + +def session_of(made, problem, run_request, start=None, **options): + """Return a session started on `made`, which it leaves open.""" + return made.prepare(problem, run_request).start( + Start.entrance(problem) if start is None else start, owns=False, **options + ) + + +def planes_of(result): + """Return each observation past the launch, with its assembled history and rows.""" + return [ + (event, history, rows) + for event, history, rows in result.assembled() + if isinstance(event, ObservationReady) and event.plane_index >= 0 + ] + + +@dataclasses.dataclass +class Scripted: + """A scripted backend with its problem and request.""" + + made: Any + problem: PropagationProblem + request: RunRequest + + def run(self, start=None, **options): + """Drive a session from `start` to its end, exporting every field.""" + return run(self.made, self.problem, self.request, start, **options) + + @pytest.fixture def scripted(): - """The scripted driver on the reference's step loop.""" + """The scripted reference backend.""" return HostScriptedDriver @pytest.fixture def driver(soliton_problem, narrow_grid, scripted): - """Return ``(**kwargs) -> HostScriptedDriver`` loaded at the entrance.""" + """Return ``(**kwargs) -> Scripted`` on the soliton's planes.""" - def build(*, planes=(LENGTH,), field=None, noise=None, **kwargs): + def build(*, planes=(LENGTH,), **kwargs): problem, run_request = soliton_problem(narrow_grid, 1, save_planes=list(planes)) made = scripted(problem, run_request, grid=narrow_grid, **kwargs) - made.set_initial(problem.initial.field0 if field is None else field, noise) - return made + return Scripted(made, problem, run_request) return build @@ -78,13 +123,13 @@ def build(*, planes=(LENGTH,), field=None, noise=None, **kwargs): def test_a_march_lands_exactly_on_its_save_plane(driver): """The position is the plane itself, not an accumulation of steps that nears it.""" made = driver() - summary = made.propagate_to(LENGTH) - assert made._z == LENGTH - assert summary.z == LENGTH - assert summary.n_steps > 1 - assert summary.n_rejected == 0 - assert made.planes_begun == 1 - assert made.accepted_hooks == summary.n_steps + result = made.run() + final = result.observations[-1] + assert final.z == LENGTH + assert made.made.march.state.z == LENGTH + assert final.summary.z == LENGTH + assert final.summary.n_steps > 1 + assert final.summary.n_rejected == 0 def test_the_landing_guard_admits_the_target_and_nothing_short_of_it(): @@ -98,21 +143,20 @@ def test_a_rejected_step_is_recorded_and_not_kept(driver): """The state after a rejection is the state before it, and the history says so.""" # 5.0 is far above the controller's threshold of one, so the first step is refused # and the second, from the same position, is taken. - made = driver(norms=[5.0, 0.1], factor=2.0) - before = present(made.workspace.state).copy() - made.propagate_to(LENGTH) - observed = made.observe() - assert not bool(observed.step_history.accepted[0]) - assert bool(observed.step_history.accepted[1]) + scripted = driver(norms=[5.0, 0.1], factor=2.0) + made = scripted.made + result = scripted.run() + before = result.fields[0] + ((_, history, _),) = planes_of(result) + assert not bool(history.accepted[0]) + assert bool(history.accepted[1]) assert made.calls[0][0] == made.calls[1][0] == 0.0 # The refused step's shorter successor is what the controller asked for next. assert made.calls[1][1] < made.calls[0][1] # The scripted step doubles the state, so the division by powers of two is exact. assert np.array_equal( - before, - np.asarray(observed.field) / 2.0 ** (int(observed.step_history.accepted.sum())), + before, result.fields[-1] / 2.0 ** (int(history.accepted.sum())) ) - assert made.accepted_hooks == int(observed.step_history.accepted.sum()) def test_a_rejected_step_is_retried_at_the_rejection_factor_alone( @@ -133,9 +177,8 @@ def test_a_rejected_step_is_retried_at_the_rejection_factor_alone( made = scripted( problem, run_request, grid=narrow_grid, norms=[0.01, 0.01, 0.01, 1.0001] ) - made.set_initial(problem.initial.field0, None) - made.propagate_to(LENGTH) - accepted = made.observe().step_history.accepted + history, _ = run(made, problem, run_request, export=None).joined + accepted = history.accepted assert [bool(flag) for flag in accepted[:4]] == [True, True, True, False] assert controller.propose([0.01, 0.01, 0.01]) > 1.1 rejected, retried = made.calls[3][1], made.calls[4][1] @@ -150,25 +193,22 @@ def test_a_diverged_trial_is_rejected_shrunk_and_recorded_as_infinity(driver, di infinity, so the observation at the next plane reads it back rather than refusing the record and ending the run. """ - made = driver(norms=[diverged, 0.1], factor=2.0) - made.propagate_to(LENGTH) - history = made.observe().step_history + scripted = driver(norms=[diverged, 0.1], factor=2.0) + made = scripted.made + history, _ = scripted.run(export=None).joined assert not bool(history.accepted[0]) assert history.error_norm[0] == np.inf assert np.all(np.isfinite(history.error_norm[1:])) assert bool(history.accepted[1]) - controller = made._stepper.controller + controller = made.request.stepper.controller assert made.calls[1][0] == 0.0 assert made.calls[1][1] == pytest.approx(made.calls[0][1] * controller.min_factor) def test_the_history_covers_only_the_steps_since_the_last_observation(driver): - """``observe`` empties the history, as the protocol promises.""" - made = driver(planes=(LENGTH / 2, LENGTH)) - made.propagate_to(LENGTH / 2) - first = made.observe().step_history - made.propagate_to(LENGTH) - second = made.observe().step_history + """An observation's chunks are the attempts since the previous one.""" + result = driver(planes=(LENGTH / 2, LENGTH)).run(export=None) + (_, first, _), (_, second, _) = planes_of(result) assert first.n_steps > 0 assert second.n_steps > 0 assert float(first.z[-1]) == LENGTH / 2 @@ -176,7 +216,7 @@ def test_the_history_covers_only_the_steps_since_the_last_observation(driver): def test_a_replayed_schedule_takes_its_steps_as_given( - scripted, driver, soliton_problem, narrow_grid + scripted, soliton_problem, narrow_grid ): """A replay never rejects and reads its position off the schedule's edges.""" schedule = FixedSchedule.uniform(0.0, LENGTH, LENGTH / 8) @@ -184,11 +224,11 @@ def test_a_replayed_schedule_takes_its_steps_as_given( narrow_grid, 1, save_planes=[LENGTH], schedule=schedule ) made = scripted(problem, run_request, grid=narrow_grid, norms=[5.0] * 8) - made.set_initial(problem.initial.field0, None) - summary = made.propagate_to(LENGTH) + final = run(made, problem, run_request, export=None).observations[-1] + summary = final.summary assert summary.n_steps == 8 assert summary.n_rejected == 0 - assert made._z == LENGTH + assert final.z == LENGTH # Every step is the schedule's, not the controller's. assert [dz for _, dz in made.calls] == pytest.approx([LENGTH / 8] * 8) assert not summary.met_tolerance @@ -203,14 +243,13 @@ def test_a_replay_that_runs_out_says_so(scripted, soliton_problem, narrow_grid): schedule=FixedSchedule.uniform(0.0, LENGTH, LENGTH / 8), ) made = scripted(problem, run_request, grid=narrow_grid) - made.set_initial(problem.initial.field0, None) - made.propagate_to(LENGTH / 2) + run(made, problem, run_request, export=None, observations=2) # The operator table still covers the whole run, so the guard that fires is the # schedule's own and not the table's: the march replays a schedule that ends at # the plane it stands on (the translation refuses one that misses a save plane). short = FixedSchedule.uniform(0.0, LENGTH / 2, LENGTH / 8) with pytest.raises(BackendError, match="cannot reach"): - made._march.replay_to(short, LENGTH) + made.march.replay_to(short, LENGTH) def test_a_schedule_of_equal_steps_lands_on_a_plane_its_running_sum_misses( @@ -231,29 +270,35 @@ def test_a_schedule_of_equal_steps_lands_on_a_plane_its_running_sum_misses( narrow_grid, 1, save_planes=[LENGTH / 2, LENGTH], schedule=schedule ) made = scripted(problem, run_request, grid=narrow_grid) - made.set_initial(problem.initial.field0, None) - made.propagate_to(LENGTH / 2) - assert made._schedule_index == 200 - assert made._z == middle - made.propagate_to(LENGTH) - assert made._schedule_index == 400 - resumed = scripted(problem, run_request, grid=narrow_grid) - resumed.set_initial(problem.initial.field0, None, z=LENGTH / 2) - assert resumed._schedule_index == 200 + held = [] + + def march_state(session, batch): + del session + if any(isinstance(event, ObservationReady) for event in batch.events): + held.append((made.march.state.cursor, made.march.state.z)) + + run(made, problem, run_request, export=None, between=march_state) + assert held[1] == (200, middle) + assert held[2][0] == 400 + with session_of( + made, problem, run_request, resumed(run_request, problem, LENGTH / 2) + ): + assert made.march.state.cursor == 200 def test_a_resume_continues_a_replay_from_the_edge_it_stopped_at( scripted, soliton_problem, narrow_grid ): - """``set_initial(z=)`` finds the schedule index the position belongs to.""" + """A start at a plane finds the schedule index the position belongs to.""" schedule = FixedSchedule.uniform(0.0, LENGTH, LENGTH / 8) problem, run_request = soliton_problem( narrow_grid, 1, save_planes=[LENGTH / 2, LENGTH], schedule=schedule ) made = scripted(problem, run_request, grid=narrow_grid) - made.set_initial(problem.initial.field0, None, z=LENGTH / 2) - assert made._schedule_index == 4 - made.propagate_to(LENGTH) + start = resumed(run_request, problem, LENGTH / 2) + with session_of(made, problem, run_request, start): + assert made.march.state.cursor == 4 + run(made, problem, run_request, resumed(run_request, problem, LENGTH / 2)) assert len(made.calls) == 4 @@ -267,11 +312,13 @@ def test_a_resume_off_the_schedule_s_edges_is_refused( ) made = scripted(problem, run_request, grid=narrow_grid) with pytest.raises(BackendError, match="one of its edges"): - made.set_initial(problem.initial.field0, None, z=LENGTH / 3) + session_of( + made, problem, run_request, resumed(run_request, problem, LENGTH / 3) + ) def test_the_input_noise_model_adds_its_realisation_once( - scripted, driver, soliton_problem, narrow_grid + scripted, soliton_problem, narrow_grid ): """Added at the entrance and never again, so a resume is not given a second draw.""" problem, run_request = soliton_problem( @@ -280,14 +327,16 @@ def test_the_input_noise_model_adds_its_realisation_once( save_planes=[LENGTH], noise=input_noise(narrow_grid, np.random.default_rng(7)), ) - entrance = scripted(problem, run_request, grid=narrow_grid) - entrance.set_initial(problem.initial.field0, None) - resumed = scripted(problem, run_request, grid=narrow_grid) - resumed.set_initial(problem.initial.field0, None, z=LENGTH / 2) masked = problem.initial.field0 * problem.grids.active_mask - assert not np.array_equal(present(entrance.workspace.state), masked) - assert np.array_equal(present(resumed.workspace.state), masked) - assert entrance.workspace.noise is None + entrance = scripted(problem, run_request, grid=narrow_grid) + with session_of(entrance, problem, run_request): + assert not np.array_equal(present(entrance.workspace.state), masked) + assert entrance.workspace.noise is None + later = scripted(problem, run_request, grid=narrow_grid) + with session_of( + later, problem, run_request, resumed(run_request, problem, LENGTH / 2) + ): + assert np.array_equal(present(later.workspace.state), masked) def test_the_modified_noise_model_keeps_its_realisation_apart( @@ -301,25 +350,25 @@ def test_the_modified_noise_model_keeps_its_realisation_apart( noise=modified_noise(narrow_grid, np.random.default_rng(7)), ) made = scripted(problem, run_request, grid=narrow_grid) - made.set_initial(problem.initial.field0, None) - assert np.array_equal( - present(made.workspace.state), - problem.initial.field0 * problem.grids.active_mask, - ) - drawn = present(made.workspace.noise) - advanced = present( - made.workspace.noise_at(made.workspace.stage_scalars(0.0, LENGTH / 2)) - ) - # Dispersion yes, loss and gain no: the magnitude is untouched by the advance. - assert np.allclose(np.abs(advanced), np.abs(drawn)) - assert not np.array_equal(advanced, drawn) - assert present(made.workspace.noise_phase(made._z)).shape == problem.shape + with session_of(made, problem, run_request): + assert np.array_equal( + present(made.workspace.state), + problem.initial.field0 * problem.grids.active_mask, + ) + drawn = present(made.workspace.noise) + advanced = present( + made.workspace.noise_at(made.workspace.stage_scalars(0.0, LENGTH / 2)) + ) + # Dispersion yes, loss and gain no: the magnitude is untouched by the advance. + assert np.allclose(np.abs(advanced), np.abs(drawn)) + assert not np.array_equal(advanced, drawn) + assert present(made.workspace.noise_phase(0.0)).shape == problem.shape def test_a_given_realisation_replaces_the_contract_s( scripted, soliton_problem, narrow_grid ): - """The realisation given to ``set_initial`` wins over the assembled one.""" + """The realisation a start carries wins over the assembled one.""" problem, run_request = soliton_problem( narrow_grid, 1, @@ -327,52 +376,51 @@ def test_a_given_realisation_replaces_the_contract_s( noise=modified_noise(narrow_grid, np.random.default_rng(7)), ) made = scripted(problem, run_request, grid=narrow_grid) - made.set_initial( - problem.initial.field0, - modified_noise(narrow_grid, np.random.default_rng(11)), + start = Start.entrance( + problem, noise=modified_noise(narrow_grid, np.random.default_rng(11)) ) - assert not np.array_equal(present(made.workspace.noise), problem.initial.noise0) + with session_of(made, problem, run_request, start): + assert not np.array_equal(present(made.workspace.noise), problem.initial.noise0) def test_a_run_without_noise_reports_no_phase(driver, narrow_grid): """``noise_model = "none"`` has neither a realisation nor a phase to report.""" - made = driver() - workspace = made.workspace - assert ( - workspace._noise_field(modified_noise(narrow_grid, np.random.default_rng(3))) - is None - ) - assert workspace.noise_phase(made._z) is None - assert workspace.noise_at(workspace.stage_scalars(0.0, 0.0)) is None + scripted = driver() + workspace = scripted.made.workspace + with session_of(scripted.made, scripted.problem, scripted.request): + assert ( + workspace._noise_field( + modified_noise(narrow_grid, np.random.default_rng(3)) + ) + is None + ) + assert workspace.noise_phase(0.0) is None + assert workspace.noise_at(workspace.stage_scalars(0.0, 0.0)) is None -def test_the_guards_refuse_what_cannot_be_done( - scripted, driver, soliton_problem, narrow_grid -): - """Closed, unloaded, backwards, off the table, and the wrong shape.""" +def test_the_guards_refuse_what_cannot_be_done(scripted, soliton_problem, narrow_grid): + """Closed, unloaded, off the table, and the wrong shape.""" problem, run_request = soliton_problem(narrow_grid, 1, save_planes=[LENGTH]) empty = scripted(problem, run_request, grid=narrow_grid) with pytest.raises(BackendError, match="no initial state"): - empty.propagate_to(LENGTH) + empty.workspace.committed() with pytest.raises(BackendError, match="expected"): - empty.set_initial(np.zeros((1, 1, 3), dtype=complex), None) + session_of( + empty, + problem, + run_request, + Start(field=np.zeros((1, 1, 3), dtype=complex), z=0.0), + ) with pytest.raises(BackendError, match="inside the operator table"): - empty.set_initial(problem.initial.field0, None, z=2 * LENGTH) - - made = driver() - made.propagate_to(LENGTH) - with pytest.raises(BackendError, match="backwards"): - made.propagate_to(0.0) - with pytest.raises(BackendError, match="must be finite"): - made.propagate_to(float("nan")) - with pytest.raises(BackendError, match="beyond the operator table"): - made.propagate_to(1e3) + session_of( + empty, problem, run_request, Start(problem.initial.field0, 2 * LENGTH) + ) - made.close() + empty.close() with pytest.raises(BackendError, match="closed"): - made.observe() + session_of(empty, problem, run_request) with pytest.raises(BackendError, match="closed"): - made.set_initial(problem.initial.field0, None) + empty.timing_probe(Start.entrance(problem)) def test_statistics_without_a_grid_say_which_backend_to_give_one_to( @@ -417,47 +465,60 @@ def finished(self, total): self.order.append("finished") +def reported(made, problem, run_request, reporter, start=None, **options): + """Drive a session whose attempts and start go to `reporter`; return the run.""" + session = session_of( + made, + problem, + run_request, + start, + listener=reporter.step, + started=reporter.started, + ) + try: + return drive(Started(session), **options) + finally: + session.close() + + def test_a_reporter_sees_every_attempted_step_including_the_rejected_ones(driver): - """`_record` is the one funnel every attempt goes through, so nothing is missed.""" + """Every attempt reaches the session's listener, so nothing is missed.""" reporter = Events() - made = driver(norms=[5.0, 0.1], factor=2.0) - made.set_progress(reporter) - summary = made.propagate_to(LENGTH) - made._progress.plane(LENGTH, summary) - + scripted = driver(norms=[5.0, 0.1], factor=2.0) + result = reported(scripted.made, scripted.problem, scripted.request, reporter) + summary = result.observations[-1].summary assert reporter.order[0] == "started" assert reporter.extent == (0.0, LENGTH, 1) assert reporter.order.count("step") == summary.n_steps assert sum(1 for _, _, accepted in reporter.steps if not accepted) == 1 assert summary.n_rejected == 1 # The rejected attempt is reported at the position it would have reached, which the - # retry then reaches more slowly: the reporter, not the driver, is what has to know. + # retry then reaches more slowly: the reporter, not the session, has to know. rejected_at = next(z for z, _, accepted in reporter.steps if not accepted) assert rejected_at > reporter.steps[1][0] -def test_started_is_announced_once_per_load_and_a_resume_announces_it_again(driver): +def test_started_is_announced_once_per_session_and_a_resume_announces_it_again( + driver, +): reporter = Events() - made = driver(planes=(LENGTH / 2, LENGTH)) - made.set_progress(reporter) - made.propagate_to(LENGTH / 2) - made.propagate_to(LENGTH) + scripted = driver(planes=(LENGTH / 2, LENGTH)) + made, problem, request = scripted.made, scripted.problem, scripted.request + result = reported(made, problem, request, reporter, export=IDENTITY) assert reporter.order.count("started") == 1 assert reporter.extent == (0.0, LENGTH, 2) - - made.set_initial(present(made.workspace.state), None, z=LENGTH / 2) - made.propagate_to(LENGTH) + middle = result.fields[1] + reported( + made, + problem, + request, + reporter, + resumed(request, problem, LENGTH / 2, field=middle), + ) assert reporter.order.count("started") == 2 assert reporter.extent == (LENGTH / 2, LENGTH, 2) -def test_the_reporter_is_the_backend_s_and_the_default_is_silent(driver): - """Nothing is reported until one is attached, so a bare backend costs nothing.""" - made = driver() - assert isinstance(made._progress, NullReporter) - made.propagate_to(LENGTH) - - @pytest.mark.parametrize("period", [0.0, 1e9]) def test_a_run_with_a_reporter_is_the_run_without(soliton_problem, narrow_grid, period): """Layer D throughout: the calls are observers, made after the step is decided. @@ -474,23 +535,19 @@ def test_a_run_with_a_reporter_is_the_run_without(soliton_problem, narrow_grid, bound = 8 * 16 * np.finfo(float).eps schedule = FixedSchedule.uniform(0.0, LENGTH, LENGTH / 8) - def run(reporter): + def marched(reporter): problem, run_request = soliton_problem( narrow_grid, 1, save_planes=[LENGTH / 2, LENGTH], schedule=schedule ) made = NumpyRefBackend(problem, run_request, grid=narrow_grid) - made.set_progress(reporter) - made.set_initial(problem.initial.field0, None) - fields, histories = [], [] - for plane in (LENGTH / 2, LENGTH): - made.propagate_to(plane) - observed = made.observe() - fields.append(observed.field) - histories.append(observed.step_history) - made.close() - return fields, histories - - quiet_fields, quiet_history = run(NullReporter()) + try: + result = reported(made, problem, run_request, reporter, export=IDENTITY) + finally: + made.close() + observed = planes_of(result) + return result.fields[1:], [history for _, history, _ in observed] + + quiet_fields, quiet_history = marched(NullReporter()) rtol = soliton_problem( narrow_grid, 1, save_planes=[LENGTH] ).request.stepper.controller.rtol @@ -502,7 +559,7 @@ def run(reporter): BarReporter(period=1e-9, file=io.StringIO(), ncols=60, ascii=True), ] for reporter in reporters: - loud_fields, loud_history = run(reporter) + loud_fields, loud_history = marched(reporter) for quiet, loud in zip(quiet_fields, loud_fields, strict=True): assert_within(loud, quiet, bound, what="field") for quiet, loud in zip(quiet_history, loud_history, strict=True): @@ -515,28 +572,32 @@ def run(reporter): def test_the_reference_reports_its_calls_in_order(soliton_problem, narrow_grid): - # The native backend reports through its session's listener (the lifecycle + # The native backend reports through its session's listener too (the lifecycle # suite's progress cases, ``tests/sessions``). reporter = Events() planes = [LENGTH / 2, LENGTH] problem, run_request = soliton_problem(narrow_grid, 1, save_planes=planes) made = NumpyRefBackend(problem, run_request, grid=narrow_grid) - made.set_progress(reporter) - made.set_initial(problem.initial.field0, None) - summaries = [] - for plane in planes: - summary = made.propagate_to(plane) - summaries.append(summary) - reporter.plane(plane, summary) - reporter.finished(1.0) - made.close() + def plane(session, batch): + del session + for event in batch.events: + if isinstance(event, ObservationReady) and event.plane_index >= 0: + reporter.plane(event.z, event.summary) + + try: + reported(made, problem, run_request, reporter, between=plane) + finally: + made.close() + reporter.finished(1.0) assert reporter.order[0] == "started" assert reporter.order[-1] == "finished" assert reporter.order.count("started") == 1 assert reporter.order.count("finished") == 1 assert reporter.order.count("plane") == len(planes) - assert reporter.order.count("step") == sum(one.n_steps for one in summaries) + assert reporter.order.count("step") == sum( + summary.n_steps for _, summary in reporter.planes + ) # One `started`, then steps and planes interleaved with a plane last before the end. assert reporter.order[-2] == "plane" @@ -551,23 +612,29 @@ def periodic(translation, names=("energy",), *, period=1): return Translation(problem, run_request.for_run(stats=spec)) -def rows_of(made): - """Propagate to the one plane and return the channel it flushed.""" - made.propagate_to(LENGTH) - return made.observe().step_stats +def observed_planes(made, problem, run_request): + """Run to the end; return each plane's assembled history and rows.""" + result = run(made, problem, run_request, export=None) + return [(history, rows) for _, history, rows in planes_of(result)] + + +def rows_of(made, problem, run_request): + """Run to the one plane and return the rows it assembled.""" + ((_, rows),) = observed_planes(made, problem, run_request) + return rows def test_a_row_is_taken_at_the_position_the_accepted_step_reached( scripted, soliton_problem, narrow_grid ): - """The trap this test exists for, and the reason the call is not in a hook. - - ``_march_to`` records an attempt *before* it finishes the state and advances ``z``; - ``_replay_to`` records it *after* both. So a channel evaluated from inside - ``_on_accepted_step`` reads the previous step's position and state on an adaptive - run and the current step's on a replayed one -- and a cost gate is naturally - specified on a replayed schedule, where the wrong version passes. Both paths are - asserted here, against the same expectation. + """The trap this test exists for: a row describes the step just committed. + + An adaptive march records an attempt *before* it finishes the state and advances + ``z``, a replay *after* both. So a channel evaluated from the attempt's record + reads the previous step's position and state on an adaptive run and the current + step's on a replayed one -- and a cost gate is naturally specified on a replayed + schedule, where the wrong version passes. Both paths are asserted here, against the + same expectation. """ schedule = FixedSchedule.uniform(0.0, LENGTH, LENGTH / 8) for extra in ({}, {"schedule": schedule}): @@ -575,10 +642,8 @@ def test_a_row_is_taken_at_the_position_the_accepted_step_reached( soliton_problem(narrow_grid, 1, save_planes=[LENGTH], **extra) ) made = scripted(problem, run_request, grid=narrow_grid) - made.set_initial(problem.initial.field0, None) - rows = rows_of(made) - # `HostScriptedDriver.stats` returns `self._z`, so the recorded value is the - # position the driver held when the row was taken. + rows = rows_of(made, problem, run_request) + # The scripted statistics read the position they were taken at. assert rows.n_rows > 0 np.testing.assert_array_equal(rows.values["energy"][:, 0], rows.z) # And that position is the end of an accepted step, never the start. @@ -588,8 +653,8 @@ def test_a_row_is_taken_at_the_position_the_accepted_step_reached( def test_the_channel_is_empty_unless_the_run_asks_for_one(driver): """The default spec has no periodic subset, so nothing is buffered or flushed.""" - made = driver() - rows = rows_of(made) + scripted = driver() + rows = rows_of(scripted.made, scripted.problem, scripted.request) assert rows.n_rows == 0 assert rows.names == () @@ -602,10 +667,7 @@ def test_a_row_indexes_the_attempt_it_was_taken_after( soliton_problem(narrow_grid, 1, save_planes=[LENGTH]) ) made = scripted(problem, run_request, grid=narrow_grid, norms=[5.0, 0.1, 0.1]) - made.set_initial(problem.initial.field0, None) - made.propagate_to(LENGTH) - observed = made.observe() - rows, history = observed.step_stats, observed.step_history + ((history, rows),) = observed_planes(made, problem, run_request) assert history.n_rejected == 1 # The first attempt was rejected, so the first row indexes attempt 1, not 0. assert rows.step[0] == 1 @@ -624,29 +686,24 @@ def test_the_period_counts_accepted_steps_and_a_rejection_is_not_one( made = scripted( problem, run_request, grid=narrow_grid, norms=[5.0, 0.1, 0.1, 0.1, 0.1] ) - made.set_initial(problem.initial.field0, None) - made.propagate_to(LENGTH) - observed = made.observe() - accepted = np.flatnonzero(observed.step_history.accepted) + ((history, rows),) = observed_planes(made, problem, run_request) + accepted = np.flatnonzero(history.accepted) # Every second *accepted* attempt, so the rejection shifts nothing. - np.testing.assert_array_equal(observed.step_stats.step, accepted[1::2]) + np.testing.assert_array_equal(rows.step, accepted[1::2]) def test_the_rows_of_one_plane_are_flushed_with_it( scripted, soliton_problem, narrow_grid ): - """`observe` drains the buffer, so a plane's rows are its own.""" + """An observation drains the buffer, so a plane's rows are its own.""" planes = [LENGTH / 2, LENGTH] problem, run_request = periodic(soliton_problem(narrow_grid, 1, save_planes=planes)) made = scripted(problem, run_request, grid=narrow_grid) - made.set_initial(problem.initial.field0, None) seen = [] - for plane in planes: - made.propagate_to(plane) - observed = made.observe() - seen.append(observed.step_stats) + for history, rows in observed_planes(made, problem, run_request): + seen.append(rows) # Each plane's rows index that plane's own history, from zero. - assert observed.step_stats.step[0] < observed.step_history.n_steps + assert rows.step[0] < history.n_steps assert all(one.n_rows for one in seen) assert seen[0].z[-1] == pytest.approx(LENGTH / 2) assert seen[1].z[0] > LENGTH / 2 @@ -662,95 +719,27 @@ def test_the_buffer_grows_across_a_plane_with_more_steps_than_its_capacity( soliton_problem(narrow_grid, 1, save_planes=[LENGTH], schedule=schedule) ) made = scripted(problem, run_request, grid=narrow_grid) - made.set_initial(problem.initial.field0, None) - rows = rows_of(made) + rows = rows_of(made, problem, run_request) assert rows.n_rows == n_steps assert np.all(np.diff(rows.z) > 0.0) np.testing.assert_array_equal(rows.step, np.arange(n_steps)) def test_a_load_starts_the_period_again(scripted, soliton_problem, narrow_grid): - """`set_initial` resets the phase, so a resume is not the uninterrupted run.""" + """Each session counts the period from its load, so a resume is not the + uninterrupted run.""" problem, run_request = periodic( soliton_problem(narrow_grid, 1, save_planes=[LENGTH]), period=3 ) made = scripted(problem, run_request, grid=narrow_grid) - made.set_initial(problem.initial.field0, None) - assert made._accepted_steps == 0 - made.propagate_to(LENGTH) - assert made._accepted_steps > 0 - made.set_initial(problem.initial.field0, None) - assert made._accepted_steps == 0 - assert made.observe().step_stats.n_rows == 0 - - -@pytest.mark.parametrize("replay", [False, True]) -def test_alternate_statistics_storage_hooks_keep_shared_acceptance_and_period( - scripted, soliton_problem, narrow_grid, replay -): - class DeferredRows(scripted): - def __init__(self, *args, **kwargs): - super().__init__(*args, **kwargs) - self.pending = [] - self.resets = [] - self.drains = 0 - - def stats(self, spec): - raise AssertionError("a periodic device row must not call host stats") - - def _reset_step_stats(self, *, release): - self.pending.clear() - self.resets.append(release) - - def _record_step_stats(self, spec, z, step): - assert spec.names == ("energy",) - assert spec.periodic == () - assert z == self._z - self.pending.append((z, step)) - - def _drain_step_stats(self): - self.drains += 1 - if not self.pending: - return StepStats.empty() - positions = np.array([z for z, _ in self.pending]) - indices = np.array([step for _, step in self.pending]) - self.pending.clear() - return StepStats(positions, indices, {"energy": positions[:, None]}) - - extra = {"schedule": FixedSchedule.uniform(0, LENGTH, LENGTH / 8)} if replay else {} - problem, run_request = periodic( - soliton_problem(narrow_grid, 1, save_planes=[LENGTH / 2, LENGTH], **extra), - period=3, - ) - norms = () if replay else (5.0, 0.1) - deferred = DeferredRows(problem, run_request, grid=narrow_grid, norms=norms) - default = scripted(problem, run_request, grid=narrow_grid, norms=norms) - for owner in (deferred, default): - owner.set_initial(problem.initial.field0, None) - for plane in (LENGTH / 2, LENGTH): - for owner in (deferred, default): - owner.propagate_to(plane) - actual, expected = deferred.observe(), default.observe() - for name in ("z", "step"): - np.testing.assert_array_equal( - getattr(actual.step_stats, name), getattr(expected.step_stats, name) - ) - for name in expected.step_stats.names: - np.testing.assert_array_equal( - actual.step_stats.values[name], expected.step_stats.values[name] - ) - np.testing.assert_array_equal(actual.field, expected.field) - np.testing.assert_array_equal( - actual.step_history.accepted, expected.step_history.accepted - ) - assert deferred.resets == [True, False, False] - assert deferred.drains == 2 - assert deferred.observe().step_stats.n_rows == 0 - deferred.set_initial(problem.initial.field0, None, z=LENGTH / 2) - assert deferred.resets[-1] is True - assert not deferred.pending - deferred.close() - default.close() + session = cast("Any", session_of(made, problem, run_request)) + assert session._accepted_steps == 0 + drive(Started(session)) + assert session._accepted_steps > 0 + session.close() + with cast("Any", session_of(made, problem, run_request)) as again: + assert again._accepted_steps == 0 + assert again._rows.drain().n_rows == 0 def test_a_statistic_that_changes_shape_within_a_plane_is_refused( @@ -759,30 +748,31 @@ def test_a_statistic_that_changes_shape_within_a_plane_is_refused( """The buffer is laid out from the first row and indexes by that shape. Nothing the package builds can do this -- the spec is fixed when the backend is - built -- but a backend whose `stats` disagreed with itself would otherwise be - caught by a broadcast error deep in numpy rather than by a message naming the + built -- but a workspace whose statistics disagreed with themselves would otherwise + be caught by a broadcast error deep in numpy rather than by a message naming the statistic. """ - - class Widening(scripted): - def stats(self, spec) -> dict[str, np.ndarray]: - width = 1 + len(self._history) // 2 - return {name: np.zeros((1, width)) for name in spec.names} - problem, run_request = periodic( soliton_problem(narrow_grid, 1, save_planes=[LENGTH]) ) - made = Widening(problem, run_request, grid=narrow_grid) - made.set_initial(problem.initial.field0, None) + made = scripted(problem, run_request, grid=narrow_grid) + taken = [0] + + def widening(spec, z): + del z + taken[0] += 1 + return {name: np.zeros((1, taken[0])) for name in spec.names} + + made.workspace.stats = widening with pytest.raises(BackendError, match="came back with shape"): - made.propagate_to(LENGTH) + run(made, problem, run_request, export=None) # ----------------------------------------------------------- the executed norm def test_the_history_records_the_executed_norm_and_the_controller_the_equivalent( - driver, + driver, monkeypatch ): """A landing step clipped short is written up at the norm it scored. @@ -793,18 +783,26 @@ def test_the_history_records_the_executed_norm_and_the_controller_the_equivalent plane does not restart it from a sliver; the history and everything read off it carry the norm each step actually committed. """ - made = driver() - made.propagate_to(LENGTH) - history = made.observe().step_history + scripted = driver() + made = scripted.made + proposals = [] + trial = made._trial_step + + def recorded(z, dz): + proposals.append(made.march.state.proposal) + return trial(z, dz) + + monkeypatch.setattr(made, "_trial_step", recorded) + history, _ = scripted.run(export=None).joined accepted = np.flatnonzero(history.accepted) last = accepted[-1] taken = float(history.dz[last]) - proposal = made.proposals[last] + proposal = proposals[last] # The last accepted step is the landing on the plane, and it is not the proposal. assert taken != proposal executed = (taken / made._scale) ** 5 assert float(history.error_norm[last]) == pytest.approx(executed) - assert made._march.state.norms[-1] == pytest.approx( + assert made.march.state.norms[-1] == pytest.approx( executed * (proposal / taken) ** 5 ) # And no accepted step of an adaptive run scores above one, by construction. @@ -814,21 +812,20 @@ def test_the_history_records_the_executed_norm_and_the_controller_the_equivalent def test_the_controller_keeps_only_the_norms_it_reads(driver): """The controller reads two norms, a lag back; a march keeps those, not every step. - The first entry is still the start-up rule's cue: the history is emptied when a - field is loaded, and its length is one only after the first accepted step. + The first entry is still the start-up rule's cue: a session's march starts with no + norms, and its length is one only after the first accepted step. """ - made = driver() - lag = made._stepper.controller.lag - assert made._march.state.norms.maxlen == lag + 2 - summary = made.propagate_to(LENGTH) + scripted = driver() + made = scripted.made + lag = made.request.stepper.controller.lag + assert made.march.state.norms.maxlen == lag + 2 + summary = scripted.run(export=None).observations[-1].summary assert summary.n_steps > lag + 2 - assert len(made._march.state.norms) == lag + 2 - made.set_initial(made._problem.initial.field0, None) - assert len(made._march.state.norms) == 0 + assert len(made.march.state.norms) == lag + 2 + with session_of(made, scripted.problem, scripted.request): + assert len(made.march.state.norms) == 0 -# --- the seam a compiled backend subclasses ---------------------------------------- - SEPARABLE_OPERATOR_FIELDS = ( "k_squared", "kperp_sq", @@ -909,7 +906,7 @@ def test_a_trials_bundles_taken_together_are_kept_until_the_next_hoist(driver): anchor and position is the kept bundle itself, and the next step's hoist drops them, so nothing a later step reads was taken for an earlier one. """ - made = driver() + made = driver().made z0, dz = LENGTH / 4, LENGTH / 8 positions = [z0 + dz, z0, z0 + 0.5 * dz, z0 + dz] workspace = made.workspace @@ -917,7 +914,7 @@ def test_a_trials_bundles_taken_together_are_kept_until_the_next_hoist(driver): together = workspace.stage_bundles(z0, positions) assert together[0] is together[3] for z1, bundle in zip(positions, together, strict=True): - alone = scalars(made._problem, z0, z1) + alone = scalars(made.workspace.problem, z0, z1) assert bundle.z0 == z0 and bundle.z1 == z1 assert np.array_equal(present(bundle.phi_delta), present(alone.phi_delta)) assert np.array_equal(present(bundle.prefactor), present(alone.prefactor)) @@ -946,43 +943,64 @@ def test_the_bundles_a_compiled_backend_packs_are_frozen(): assert tuple(f.name for f in dataclasses.fields(MarchPolicy)) == MARCH_POLICY_FIELDS -HOST_SURFACE: dict[str, str] = { - "metadata": "(self) -> dict[str, object]", - "restore_call_ledgers": ( - "(self, logical: collections.abc.Mapping[str, object], " - "atomic: collections.abc.Mapping[str, object] | None = None) -> None" - ), -} -"""Every ``HostDriver`` member the NumPy reference backend overrides (SEP 52). - -Since SEP 52 the physics is the workspace's and the engines', not driver hooks: the -backend overrides only these. A change here changes what ``numpy_ref`` overrides, in -the same commit.""" +BACKEND_MEMBERS = ( + "available_device_memory", + "close", + "closed", + "edge_memory", + "march_export_refusal", + "memory_ledger", + "metadata", + "prepare", + "request", + "timing_probe", +) +"""The :class:`~solprop.backends.protocol.Backend` protocol's methods and properties, +complete (SEP 52 section 5.1): its attributes are ``name`` and +``reads_transverse_edge``. A change here changes the seam, in the same commit.""" + +RETIRED_MEMBERS = ( + "attach_monitor", + "drain_attempts", + "halt_ahead", + "march_snapshot", + "march_snapshot_nbytes", + "observe", + "propagate_to", + "request_halt", + "restore_call_ledgers", + "restore_march", + "set_halt_check", + "set_initial", + "set_progress", + "set_stop", + "stats", +) +"""The host stepping seam SEP 52 deleted: every run is a session's, which schedules it +and reads the state through the workspace.""" -HOST_ATTRIBUTES = ( +REFERENCE_ATTRIBUTES = ( "helpers", "name", "propagator_default", "reads_transverse_edge", ) -"""The ``HostDriver`` class attributes a NumPy reference backend sets.""" +"""The class attributes the NumPy reference backend sets.""" -def test_the_host_hooks_the_reference_overrides_are_frozen(): - overridden = { +def test_the_backend_surface_the_reference_implements_is_frozen(): + members = { name - 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("__") - } - {"_abc_impl"} - assert overridden == set(HOST_SURFACE) | set(HOST_ATTRIBUTES) - for name, signature in HOST_SURFACE.items(): - hook = getattr(HostDriver, name) - if isinstance(hook, property): - assert hook.fget is not None - hook = hook.fget - assert str(inspect.signature(hook)) == signature, name + for name in dir(Backend) + if not name.startswith("_") and name not in {"name", "reads_transverse_edge"} + } + assert members == set(BACKEND_MEMBERS) + assert isinstance(NumpyRefBackend.__dict__["request"], property) + for name in (*BACKEND_MEMBERS, *REFERENCE_ATTRIBUTES): + assert hasattr(NumpyRefBackend, name), name + retired = [name for name in RETIRED_MEMBERS if hasattr(NumpyRefBackend, name)] + assert retired == [] + assert not hasattr(sys.modules["solprop.backends.protocol"], "HostStepping") def test_separable_operator_fields_are_frozen_with_the_driver_seam(): @@ -1015,16 +1033,17 @@ def test_linear_operator_fields_are_frozen_with_the_driver_seam(): def test_the_workspace_propagator_is_the_operator_s_flow(driver): - # The propagator is the shared one, exp(Phi(b) - Phi(a)); a Runge-Kutta engine - # that holds no accepted step's extension refuses a dense observation. - made = driver() + # The propagator is the shared one, exp(Phi(b) - Phi(a)); a dense output whose + # engine holds no accepted step's extension refuses an observation. + made = driver().made propagator = made.workspace.propagator(0.0, LENGTH / 4) - expected = np.exp(delta_phi(made._problem.linear, 0.0, LENGTH / 4)) + expected = np.exp(delta_phi(made.workspace.problem.linear, 0.0, LENGTH / 4)) np.testing.assert_allclose( propagator.reshape(-1), np.broadcast_to(expected, propagator.shape).reshape(-1) ) + dense = RungeKuttaDense(made.workspace, made._runge_kutta(made.workspace)) with pytest.raises(BackendError, match="no accepted step is held"): - made._runge_kutta_engine.observe(LENGTH / 8) + dense.observe(LENGTH / 8) # --- the descriptor (SEP 47 section 6.2) ------------------------------------------- diff --git a/tests/backends/test_envelope_plasma.py b/tests/backends/test_envelope_plasma.py index 7219c069b..30a35e84f 100644 --- a/tests/backends/test_envelope_plasma.py +++ b/tests/backends/test_envelope_plasma.py @@ -22,6 +22,7 @@ ) from envelope_oracle_angular import BUDGETS, order_record from rate_oracles import adk_oracle +from sessions.runs import bare, final_field from solprop.backends.numpy_ref import NumpyRefBackend from solprop.constants import CHARGE_MASS_RATIO, EPS0, C from solprop.grid import EnvelopeGrid @@ -175,9 +176,7 @@ def test_prescribed_density_drude_conserves_energy_with_fifth_order_steps(): ) owner = NumpyRefBackend(problem, run_request, grid=grid) try: - owner.set_initial(problem.initial.field0, None) - owner.propagate_to(grid.length) - actual = owner.observe().require_field() + actual = final_field(owner, problem, bare(run_request), ended=True) finally: owner.close() error = np.linalg.norm(actual - exact) / norm diff --git a/tests/backends/test_envelope_plasma_host.py b/tests/backends/test_envelope_plasma_host.py index e2fc1e25a..b8354c69f 100644 --- a/tests/backends/test_envelope_plasma_host.py +++ b/tests/backends/test_envelope_plasma_host.py @@ -18,6 +18,7 @@ from backends.envelope_host_cases import argon_host_case from backends.mixture_rows import host from bounds import scan_bound +from builders import load_reference from sessions.runs import run as session_run from solprop.backends.node_chunk import plan_node_chunk from solprop.backends.numpy_ref import NumpyRefBackend @@ -104,11 +105,13 @@ def test_envelope_population_values_do_not_depend_on_retaining_node_scans(host_c """The optional on-axis reuse record must not alter the node statistics.""" problem, run_request, grid = host_case with closing(NumpyRefBackend(problem, run_request, grid=grid)) as backend: - backend.set_initial(problem.initial.field0, None) + load_reference(backend) field = problem.initial.field0 - plain = backend.workspace._species_statistics(field, backend._z) + plain = backend.workspace._species_statistics(field, problem.initial.z) scans = [] - retained = backend.workspace._species_statistics(field, backend._z, scans) + retained = backend.workspace._species_statistics( + field, problem.initial.z, scans + ) assert len(scans) == 1 fractions, peaks = scans[0] assert ( diff --git a/tests/backends/test_exponential_coupled.py b/tests/backends/test_exponential_coupled.py index de77ab496..97099bb37 100644 --- a/tests/backends/test_exponential_coupled.py +++ b/tests/backends/test_exponential_coupled.py @@ -197,7 +197,7 @@ def run(name, integrator, rtol, backend_class=NumpyRefBackend, **overrides): field = session_run(backend, problem, record=record).fields[-1] adams = isinstance(integrator, Multistep) return field, SimpleNamespace( - march=backend._adams if backend.name == "numpy_ref" else None, + march=backend.march if backend.name == "numpy_ref" else None, ledger=adams_ledger(backend, record) if adams else None, ) finally: diff --git a/tests/backends/test_exponential_march.py b/tests/backends/test_exponential_march.py index 357c45a1b..95a8ced4e 100644 --- a/tests/backends/test_exponential_march.py +++ b/tests/backends/test_exponential_march.py @@ -24,6 +24,8 @@ from bounds import assert_within, gamma, step_evaluations from legacy_geometry import LEGACY_GRID +from sessions.runs import bare +from sessions.runs import run as session_run from solprop._helpers import PLAIN from solprop.backends.exponential import refuse_formulation from solprop.backends.host.adams import HostAdamsMarch @@ -92,16 +94,12 @@ def replay_bound(run_request, steps: int) -> float: def run(problem, run_request, grid): """Propagate to the last plane; return the final field, the march and its steps.""" backend = NumpyRefBackend(problem, run_request, grid=grid) - backend.set_initial(problem.initial.field0, None) - steps, field = [], None - for plane in run_request.stepper.save_planes: - backend.propagate_to(float(plane)) - observed = backend.observe() - steps += list(observed.step_history.dz) - field = observed.require_field()[0, 0] - march = backend._adams + result = session_run(backend, problem, bare(run_request)) + # Every attempt's step, rejected ones included, and the last plane's field. + steps = list(result.joined[0].dz) + field = result.fields[-1][0, 0] + march = backend.march backend.close() - assert field is not None return field, march, np.array(steps) @@ -337,12 +335,10 @@ def solve(interpolate): interpolate_planes=interpolate, ) backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) - fields = [] - for plane in planes: - backend.propagate_to(float(plane)) - fields.append(backend.observe().require_field()[0, 0]) - ledger = ledger_of(backend._adams) + result = session_run(backend, problem, bare(run_request)) + assert [event.z for event in result.observations[1:]] == planes + fields = [field[0, 0] for field in result.fields[1:]] + ledger = ledger_of(backend.march) backend.close() return np.array(fields), ledger @@ -367,9 +363,9 @@ def test_exponential_dense_observation_is_the_linear_flow_without_a_source( dz_max=0.3, ) backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(planes[0]) - observed = backend.observe().require_field()[0, 0] + result = session_run(backend, problem, bare(run_request), observations=2) + assert result.observations[-1].z == planes[0] + observed = result.fields[-1][0, 0] backend.close() start = problem.initial.field0[0, 0] * problem.grids.active_mask exact = np.exp(delta_phi(problem.linear, 0.0, planes[0]))[0, 0] * start @@ -520,27 +516,22 @@ def start(**overrides): soliton_problem, narrow_grid, fixed(method), schedule, length, **overrides ) backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) - return backend + return backend, session_run(backend, problem, bare(run_request)) - def field_of(runner): - return runner.observe().field[0, 0, 0] - - # Every third step's end is saved: each call stops there, and the steps, so the + # Every third step's end is saved: the march stops there, and the steps, so the # field, are those of the uninterrupted replay. - whole = start() - whole.propagate_to(length) - stopping = start(step_planes=3) - calls = 0 - while stopping._z < length * (1 - 1e-12): - stopping.propagate_to(length) - calls += 1 - assert calls == 3 + whole, uninterrupted = start() + stopping, stopped = start(step_planes=3) + assert len(stopped.observations) - 1 == 3 matched = scheduled(soliton_problem, narrow_grid, fixed(method), schedule, length) - assert_within(field_of(stopping), field_of(whole), replay_bound(matched.request, 9)) + assert_within( + stopped.fields[-1][0, 0, 0], + uninterrupted.fields[-1][0, 0, 0], + replay_bound(matched.request, 9), + ) # Past its last edge the schedule cannot take the march. with pytest.raises(BackendError, match="cannot reach"): - whole.propagate_to(1.01 * length) + cast("Any", whole.march).advance(1.01 * length) whole.close() stopping.close() @@ -555,13 +546,14 @@ def test_a_replayed_step_with_a_non_finite_norm_is_refused( soliton_problem, narrow_grid, method, schedule, length ) backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) # A diverged field: a replay cannot reject the step, so it stops and says why. monkeypatch.setattr( - backend._adams, "_attempt", lambda dz, *, fixed, landing: (None, math.nan) + HostAdamsMarch, + "_attempt", + lambda self, dz, *, fixed, landing: (None, math.nan), ) with pytest.raises(ConvergenceError, match="non-finite error norm"): - backend.propagate_to(length) + session_run(backend, problem, bare(run_request)) backend.close() @@ -726,8 +718,8 @@ def test_only_the_exponential_formulation_reads_the_collar(integrator): problem, run_request, grid=simulation.grid, modes=simulation.modes ) try: - march = backend._adams - assert march is not None + march = cast("Any", backend.march) + assert isinstance(march, HostAdamsMarch) collar = problem.responses.temporal_absorber assert collar is not None expected = 0.5 * float(np.max(collar)) diff --git a/tests/backends/test_exponential_routes.py b/tests/backends/test_exponential_routes.py index 12249d719..88af372a8 100644 --- a/tests/backends/test_exponential_routes.py +++ b/tests/backends/test_exponential_routes.py @@ -5,7 +5,7 @@ """SEP 16 phase 2: the exponential formulation on every constant-operator route. The only route-specific part of the exponential formulation is its source sample, -``HostDriver._adams_lab_source``: one evaluation of the route's own source pipeline, +``NumpyWorkspace.lab_source``: one evaluation of the route's own source pipeline, untransported. On each route it must be the source the transported formulation evaluates when the anchor is the sample's own position, where the propagator is one; and a short run must reproduce the Runge-Kutta march's field. The routes are the @@ -27,7 +27,7 @@ fft_bound, ) from capability_routes import ROUTES -from sessions.runs import adams_ledger +from sessions.runs import adams_ledger, bare, final_field from sessions.runs import run as session_run from solprop.backends import available from solprop.backends.numpy_ref import NumpyRefBackend @@ -104,10 +104,7 @@ def final(integrator, rtol): problem, run_request, grid=simulation.grid, modes=simulation.modes ) try: - backend.set_initial(problem.initial.field0, None) - for plane in run_request.stepper.save_planes: - backend.propagate_to(float(plane)) - return backend.observe().require_field() + return final_field(backend, problem, bare(run_request), ended=True) finally: backend.close() diff --git a/tests/backends/test_exponential_varying.py b/tests/backends/test_exponential_varying.py index def79532f..ce8e9a741 100644 --- a/tests/backends/test_exponential_varying.py +++ b/tests/backends/test_exponential_varying.py @@ -21,6 +21,7 @@ import pytest from backends.conftest import EQUIVALENCE_BACKENDS +from sessions.runs import bare, final_field from sessions.runs import run as session_run from solprop.backends.ledger import CallLedger from solprop.backends.numpy_ref import NumpyRefBackend @@ -88,14 +89,12 @@ def march(simulation, backend_class=NumpyRefBackend, *, compensation=None, plane method = run_request.stepper.integrator backend._use_adams(method, compensation=compensation) try: - backend.set_initial(problem.initial.field0, None) - steps, fields = [], [] - for position in run_request.stepper.save_planes: - backend.propagate_to(float(position)) - observed = backend.observe() - steps += list(observed.step_history.dz) - fields.append(observed.field) - return fields[plane], backend._adams, np.array(steps) + result = session_run(backend, problem, bare(run_request)) + # Every attempt's step, rejected ones included, and each save plane's field. + steps = list(result.joined[0].dz) + fields = result.fields[1:] + assert len(fields) == len(run_request.stepper.save_planes) + return fields[plane], cast("Any", backend.march), np.array(steps) finally: backend.close() @@ -290,10 +289,7 @@ def _table_field(candidate, simulation, backend_class): candidate, run_request, grid=simulation.grid, modes=simulation.modes ) try: - backend.set_initial(candidate.initial.field0, None) - for position in run_request.stepper.save_planes: - backend.propagate_to(float(position)) - return backend.observe().require_field() + return final_field(backend, candidate, bare(run_request), ended=True) finally: backend.close() diff --git a/tests/backends/test_free_absorber.py b/tests/backends/test_free_absorber.py index db47bc73c..bbd4d4485 100644 --- a/tests/backends/test_free_absorber.py +++ b/tests/backends/test_free_absorber.py @@ -19,6 +19,7 @@ from backends.test_radial_absorber import rk_bound from backends.test_radial_nonlinear import derivative from bounds import gamma +from builders import load_reference from sessions.runs import load_native, native_trial from sessions.runs import run as session_run from solprop.backends.session import ExecutionOptions @@ -242,7 +243,7 @@ def test_cartesian_split_step_temporal_absorber_reconstructs_physical_field( state.finish(dz) actual = state.field_to_host().reshape(start.shape) else: - backend.set_initial(problem.initial.field0, None) + load_reference(backend) actual, _ = backend.workspace.finish(problem.initial.field0.copy(), dz) assert np.max(np.abs(actual - expected)) < bound record_metric( diff --git a/tests/backends/test_free_boundaries.py b/tests/backends/test_free_boundaries.py index 432de3a73..0795f58e8 100644 --- a/tests/backends/test_free_boundaries.py +++ b/tests/backends/test_free_boundaries.py @@ -10,6 +10,7 @@ import pytest from backends.spatial_cases import make_problem +from builders import load_reference from solprop.backends.numpy_ref import NumpyRefBackend from solprop.exceptions import BackendError, GridError from solprop.grid import EnvelopeGrid, FreeGrid @@ -34,7 +35,7 @@ def test_cartesian_reference_stage_names_missing_geometry(free_backend_problem): grid, problem, run_request = free_backend_problem backend = NumpyRefBackend(problem, run_request, grid=grid) try: - backend.set_initial(problem.initial.field0, None) + load_reference(backend) backend.workspace.hoist(0.0) bundle = backend.workspace.stage_scalars(0.0, 0.0) transform = copy.copy(problem.transform) diff --git a/tests/backends/test_free_noise.py b/tests/backends/test_free_noise.py index 5280de38a..53bd1933d 100644 --- a/tests/backends/test_free_noise.py +++ b/tests/backends/test_free_noise.py @@ -10,7 +10,7 @@ import pytest from bounds import gamma -from builders import reference_trial +from builders import load_reference, reference_trial from sessions.runs import load_native, native_trial from solprop.backends.numpy_ref import NumpyRefBackend from solprop.constants import C @@ -73,7 +73,7 @@ def test_cartesian_modified_noise_enters_the_rotated_nonlinear_field( reference = NumpyRefBackend(problem, run_request, grid=grid) backend = spatial_backend_class(problem, run_request, grid=grid) try: - reference.set_initial(problem.initial.field0, None) + load_reference(reference) reference.workspace.hoist(position) expected = reference.workspace.nonlinear( rotated, @@ -104,7 +104,7 @@ def capture(lab, bundle, inverse): return stage monkeypatch.setattr(backend.workspace, "nonlinear", capture) - backend.set_initial(problem.initial.field0, noise) + load_reference(backend, noise=noise) reference_trial(backend, position, 0.0) actual = captured[0].reshape(expected.shape) scale = np.max(np.abs(expected)) diff --git a/tests/backends/test_general_modal.py b/tests/backends/test_general_modal.py index a96f0e8e7..da2c4f79c 100644 --- a/tests/backends/test_general_modal.py +++ b/tests/backends/test_general_modal.py @@ -31,6 +31,7 @@ from numpy.testing import assert_allclose from bounds import assert_within, fft_bound, higham_gamma +from builders import load_reference from legacy_geometry import LEGACY_GRID from modal_provider_cases import ( GENERAL_CHI3 as CHI3, @@ -39,7 +40,7 @@ GENERAL_Z_END as Z_END, ) from modal_provider_cases import general_case as strand_case -from sessions.runs import launch_statistics +from sessions.runs import bare, final_field, launch_statistics, summary from sessions.runs import run as session_run from solprop import fourier from solprop import stats as stats_module @@ -575,11 +576,11 @@ def test_a_millimetre_of_one_channel_accumulates_the_self_phase( index, state = continuous_wave(case, [9.5e3]) problem, run_request = general_problem(case, state) backend = NumpyRefBackend(problem, run_request, grid=case.grid) - backend.set_initial(problem.initial.field0, None) - summary = backend.propagate_to(length) - final = backend.observe().require_field()[0, 0, index] + result = session_run(backend, problem, bare(run_request)) + assert result.observations[-1].z == length + final = result.fields[-1][0, 0, index] backend.close() - assert summary.met_tolerance + assert summary(result).met_tolerance omega = float(case.grid.omega[index]) sample = case.table.evaluate(omega, 0.0) @@ -665,8 +666,10 @@ def test_the_reference_executes_a_dense_metric_of_a_declared_basis(circular_stra assert problem.linear.modal_metric is not None assert problem.linear.modal_metric.kind == "dense" backend = NumpyRefBackend(problem, run_request, grid=circular_strand.grid) - backend.set_initial(problem.initial.field0, None) - values = backend.stats(StatsSpec(names=("physical_energy", "analytic_flux"))) + load_reference(backend) + values = backend.workspace.stats( + StatsSpec(names=("physical_energy", "analytic_flux")), problem.initial.z + ) assert set(values) == {"physical_energy", "analytic_flux"} # The metric is handed over, so the numbers are the weighted ones. What sets # the difference is the **stored block's** departure from the identity at the @@ -687,7 +690,9 @@ def test_the_reference_executes_a_dense_metric_of_a_declared_basis(circular_stra assert_allclose(float(value), plain[name], rtol=2 * departure, atol=0.0) # The unlaunched partner carries only the whitening's rounding, so it has no # centroid to report: the guard is relative to the plane, not to zero. - centroid = backend.stats(StatsSpec(names=("omega0",)))["omega0"] + centroid = backend.workspace.stats(StatsSpec(names=("omega0",)), problem.initial.z)[ + "omega0" + ] assert np.isfinite(centroid[0, 0]) assert np.isnan(centroid[1, 0]) backend.close() @@ -1296,9 +1301,7 @@ def test_a_linear_guide_does_not_run_the_source_pass(strand, monkeypatch): ) def step(backend): - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(plane) - field = backend.observe().require_field().copy() + field = final_field(backend, problem, bare(run_request), z=plane).copy() backend.close() return field @@ -1360,9 +1363,7 @@ def test_the_route_carries_the_in_stage_absorber(strand): scheme is not None ) backend = NumpyRefBackend(problem, run_request, grid=case.grid) - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(plane) - field = backend.observe().require_field()[0, 0] + field = final_field(backend, problem, bare(run_request), z=plane)[0, 0] backend.close() traces[scheme] = np.abs(fourier.inverse(field[None], kind="field")[0]) middle = len(traces[None]) // 2 diff --git a/tests/backends/test_host_edge_resume.py b/tests/backends/test_host_edge_resume.py index 0c26a7c11..f25219603 100644 --- a/tests/backends/test_host_edge_resume.py +++ b/tests/backends/test_host_edge_resume.py @@ -17,6 +17,8 @@ import pytest from solprop.backends.registry import select +from solprop.backends.session import Start +from solprop.backends.sessions import start_session from solprop.boundaries import SpatialAbsorber from solprop.driver import Simulation, SimulationSettings from solprop.exceptions import BoundaryWarning @@ -54,7 +56,7 @@ def _line() -> Simulation: def _judged(simulation: Simulation, state: np.ndarray, draw, *, resume: bool) -> None: - """Load `state` with `draw` and attach a fresh monitor, which judges the launch.""" + """Start a session at `state` with `draw`, whose fresh monitor judges the launch.""" problem = simulation.translate() run_request = simulation._run_request() backend = cast( @@ -69,12 +71,24 @@ def _judged(simulation: Simulation, state: np.ndarray, draw, *, resume: bool) -> ), ) try: - backend.set_initial(state, draw, resume=resume) monitor = simulation._boundary_monitor() assert monitor is not None - with warnings.catch_warnings(): - warnings.simplefilter("ignore", BoundaryWarning) - backend.attach_monitor(monitor) + start = Start( + field=state, z=float(problem.initial.z), noise=draw, resume=resume + ) + session = start_session( + backend, problem, run_request.for_run(monitor=monitor), start, owns=False + ) + try: + with warnings.catch_warnings(): + warnings.simplefilter("ignore", BoundaryWarning) + # The launch plane, then the advance that attaches the monitor, which + # judges the launch. + for _ in range(2): + batch = session.advance() + session.acknowledge(batch.receipt) + finally: + session.close() finally: backend.close() diff --git a/tests/backends/test_host_ledgers.py b/tests/backends/test_host_ledgers.py index 9537765df..c2a6b52ec 100644 --- a/tests/backends/test_host_ledgers.py +++ b/tests/backends/test_host_ledgers.py @@ -4,28 +4,40 @@ """A reference backend with no atomic service refuses atomic call ledgers. -:meth:`solprop.backends.host.driver.HostDriver.restore_call_ledgers` restores the -logical Adams counts every host driver keeps. Only a TDSE binding keeps atomic counts; a -run without one is refused them by name rather than silently dropping a budget a resume -must honour. +A resumed start's ledgers are restored by the reference's session +(:class:`solprop.backends.host.session.HostSession`): the logical Adams counts every +Adams march keeps, and atomic counts only into a TDSE binding. A run without one is +refused them by name rather than silently dropping a budget a resume must honour. """ import pytest from scripted_driver import HostScriptedDriver from sessions.executors import soliton, window +from solprop.backends.session import Start from solprop.exceptions import BackendError +def _start(problem, ledgers): + return Start( + field=problem.initial.field0, z=float(problem.initial.z), ledgers=ledgers + ) + + def test_a_host_driver_without_an_atomic_service_refuses_atomic_ledgers(): - driver = HostScriptedDriver(*soliton(), grid=window()) + problem, request = soliton() + backend = HostScriptedDriver(problem, request, grid=window()) + prepared = backend.prepare(problem, request) try: with pytest.raises( BackendError, match="atomic call ledger requires a TDSE binding" ): - driver.restore_call_ledgers({}, {"attempted": 1}) + prepared.start( + _start(problem, {"logical": {}, "atomic": {"attempted": 1}}), + owns=False, + ) # Nothing atomic, and a march with no logical ledger: nothing to install. - driver.restore_call_ledgers({}, {}) - driver.restore_call_ledgers({}, None) + for ledgers in ({"logical": {}, "atomic": {}}, {"logical": {}}): + prepared.start(_start(problem, ledgers), owns=False).close() finally: - driver.close() + backend.close() diff --git a/tests/backends/test_low_storage.py b/tests/backends/test_low_storage.py index 0af2f40fc..6f520ac5f 100644 --- a/tests/backends/test_low_storage.py +++ b/tests/backends/test_low_storage.py @@ -50,7 +50,12 @@ propagation_growth, step_budget, ) +from builders import load_reference from legacy_geometry import with_collar_rate +from sessions.executors import IDENTITY +from sessions.runs import bare +from sessions.runs import run as session_run +from solprop.backends.events import Eligibility, ObservationKind, ObservationReady from solprop.backends.low_storage import HostLowStorage, schedule_key, table_steps from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.workspace import NumpyWorkspace @@ -72,7 +77,6 @@ from solprop.output.records import MarchSnapshot from solprop.pulses import GaussianPulse, SpatialPulse from solprop.spatial import SpatialFlux, SpatialMedium, beam_radius -from solprop.stats import StatsSpec from solprop.stepper import ( DOPRI5, FixedSchedule, @@ -95,17 +99,40 @@ pytestmark = pytest.mark.filterwarnings("ignore::solprop.exceptions.BoundaryWarning") -def run(problem, run_request, grid, *, planes=None, backend=None, options=None): - """Replay a problem through its save planes; return the final state and backend.""" - made = ( - NumpyRefBackend(problem, run_request, grid=grid, options=options) - if backend is None - else backend +def run(problem, run_request, grid, *, start=None, options=None): + """Replay a problem through its save planes in its session; return the final state + and the backend, still open.""" + made = NumpyRefBackend(problem, run_request, grid=grid, options=options) + result = session_run(made, problem, bare(run_request), start) + return result.fields[-1].copy(), made + + +def resumed_at(field, z, planes, *, noise=None): + """Return a start from a state at `z`, its plane already saved.""" + return Start( + field=field, + z=float(z), + noise=noise, + plane_index=int(np.searchsorted(np.asarray(planes), z, side="right")), + plane_pending=False, ) - made.set_initial(problem.initial.field0, None) - for plane in run_request.stepper.save_planes if planes is None else planes: - made.propagate_to(float(plane)) - return made.observe().require_field().copy(), made + + +def drive_to(session, z): + """Advance a started session to its observation at `z`; return that field. + + Every batch before it, the observation's included, is acknowledged. + """ + while True: + batch = session.advance() + assert batch.terminal is None, batch.terminal + (event,) = batch.events + field = None + if isinstance(event, ObservationReady): + field = np.array(session.export(event.ticket, IDENTITY)) + session.acknowledge(batch.receipt) + if field is not None and event.z == z: + return field def linear_bound(problem, schedule): @@ -347,12 +374,9 @@ def evaluate(schedule, integrator, mode="auto"): integrator=MARCH, ) backend = NumpyRefBackend(probe, probe_request, grid=soliton_grid) - backend.set_initial(probe.initial.field0, None) - spectra = [probe.initial.field0] - for plane in planes: - backend.propagate_to(plane) - spectra.append(backend.observe().require_field()) + result = session_run(backend, probe, bare(probe_request)) backend.close() + spectra = [probe.initial.field0, *result.fields[1:]] assert driven_phase(probe, base.max_step, populated(spectra)) < 1.0 march, _ = assert_order_four(evaluate, base, round_off_floor(evaluate, base)) # Measured: the march reads 3.96 (errors 7.64e-3, 4.93e-4, 3.36e-5) and IP-DOPRI5 @@ -485,8 +509,7 @@ def evaluation_difference(problem, run_request, grid, gnlse): Returns the departure and the masked input it was taken at. """ backend = NumpyRefBackend(problem, run_request, grid=grid) - backend.set_initial(problem.initial.field0, None) - state = backend._require_state() + state = load_reference(backend) march = backend.workspace.lab_source(state, 0.0)[0, 0] backend.close() scaffold = gnlse_source(gnlse, grid)(state[0, 0]) @@ -614,16 +637,16 @@ def test_planes_at_natural_steps_match_the_uninterrupted_run( backend.close() natural, natural_request, _ = lifecycle(step_planes=7) backend = NumpyRefBackend(natural, natural_request, grid=narrow_grid) - backend.set_initial(natural.initial.field0, None) - stops = [] - while backend._z < length: - summary = backend.propagate_to(length) - stops.append(summary.z) - final = backend.observe().require_field() + result = session_run(backend, natural, bare(natural_request)) backend.close() + final = result.fields[-1] + stops = [ + event.z for event in result.observations if event.kind is ObservationKind.STEP + ] edges = run_request.stepper.schedule.edges - # On the same edges, exactly: the 7th, 14th, ... edge, and the end. - assert stops == [float(edges[k]) for k in (7, 14, 21, 28, 35)] + [length] + # On the same edges, exactly: the 7th, 14th, ... edge; the run ends at the end. + assert stops == [float(edges[k]) for k in (7, 14, 21, 28, 35)] + assert result.observations[-1].z == length bound = rounding_bound(problem, run_request.stepper.schedule, scales) assert np.linalg.norm(final - uninterrupted) <= bound * np.linalg.norm( uninterrupted @@ -645,38 +668,48 @@ def test_a_resume_at_an_edge_agrees_to_rounding(lifecycle, narrow_grid, scales, step_planes=7 if edge == "mid-segment" else 0 ) backend = NumpyRefBackend(resumable, resumable_request, grid=narrow_grid) - backend.set_initial(resumable.initial.field0, None) - summary = backend.propagate_to(length / 2) - stopped = backend.observe() + first = session_run(backend, resumable, bare(resumable_request), observations=2) backend.close() + stopped_z, stopped_field = first.observations[-1].z, first.fields[-1] edges = run_request.stepper.schedule.edges expected_stop = float(edges[7]) if edge == "mid-segment" else length / 2 - assert summary.z == stopped.z == expected_stop + assert stopped_z == expected_stop resumed = NumpyRefBackend(problem, run_request, grid=narrow_grid) - resumed.set_initial(stopped.require_field(), None, z=stopped.z) - for plane in run_request.stepper.save_planes: - if plane > stopped.z: - resumed.propagate_to(float(plane)) - final = resumed.observe().require_field() - assert resumed.march_snapshot() is None + snapshots = [] + + def keep_snapshots(session, batch): + snapshots.extend( + session.march_snapshot(event.ticket) + for event in batch.events + if isinstance(event, ObservationReady) + ) + + start = resumed_at(stopped_field, stopped_z, run_request.stepper.save_planes) + final = session_run( + resumed, problem, bare(run_request), start, between=keep_snapshots + ).fields[-1] + assert snapshots and all(one is None for one in snapshots) # A snapshot from an Adams run is not continued: this march keeps no history. snapshot = MarchSnapshot( - z=stopped.z, - state=stopped.require_field(), + z=stopped_z, + state=stopped_field, proposal=1e-3, method=repr(MARCH), order=1, rejections=0, last_rejected=False, - positions=np.array([stopped.z]), + positions=np.array([stopped_z]), identities=("accepted",), slots=np.array([0]), rows={}, history_key="adams", ) - assert "low-storage march, which keeps no history" in str( - resumed.restore_march(snapshot) - ) + start = resumed_at(stopped_field, stopped_z, run_request.stepper.save_planes) + start = dataclasses.replace(start, march=snapshot) + with cast( + "Any", resumed.prepare(problem, run_request).start(start, owns=False) + ) as session: + assert "low-storage march, which keeps no history" in str(session.march_refusal) resumed.close() bound = rounding_bound(problem, run_request.stepper.schedule, scales) assert np.linalg.norm(final - uninterrupted) <= bound * np.linalg.norm( @@ -906,38 +939,41 @@ def evaluate(lab, position, **keywords): def test_an_abandoned_step_leaves_every_reader_refusing(lifecycle, narrow_grid, scales): """Between passes the state is neither end of the step: nothing may read it. - ``observe``, ``propagate_to``, ``stats`` and ``march_snapshot`` refuse it, naming - the step; ``set_initial`` alone clears it, and a resume from the last plane agrees - with the uninterrupted run to rounding. + The session ends failed, poisoned; its observation and its method history refuse + the state, naming the step; a new session alone clears it, and a resume from the + last plane agrees with the uninterrupted run to rounding. """ problem, run_request, length = lifecycle() uninterrupted, backend = run(problem, run_request, narrow_grid) backend.close() backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(length / 2) - plane = backend.observe() + request = bare(run_request) + session: Any = backend.prepare(problem, request).start( + Start.entrance(problem), owns=False + ) + plane = drive_to(session, length / 2) # Two steps and one pass more: the third step is abandoned after its first pass, # which has already overwritten the state with its interaction-picture image. restore = abandon_after(backend, 4 * 2 + 1) - with pytest.raises(AbandonedError): - backend.propagate_to(length) + terminal = session.advance().terminal restore() + assert terminal is not None and isinstance(terminal.error, AbandonedError) + assert terminal.eligibility is Eligibility.POISONED and terminal.ticket is None step = run_request.stepper.schedule.steps[LIFECYCLE_STEPS // 2 + 2] message = rf"step of {step:.6g} m from z = .* abandoned in flight" for reader in ( - backend.observe, - lambda: backend.propagate_to(length), - lambda: backend.stats(StatsSpec(names=("energy",))), - backend.march_snapshot, + lambda: session._observe(field=True), + lambda: session._observe(field=False), + session.march_snapshot_nbytes, ): with pytest.raises(BackendError, match=message): reader() + assert session.pending_ticket() is None # The two committed steps are counted; the abandoned one is not. assert backend.metadata()["source_evaluations"] == 4 * (LIFECYCLE_STEPS // 2 + 2) - backend.set_initial(plane.require_field(), None, z=plane.z) - backend.propagate_to(length) - final = backend.observe().require_field() + session.close() + start = resumed_at(plane, length / 2, run_request.stepper.save_planes) + final = session_run(backend, problem, request, start).fields[-1] backend.close() bound = rounding_bound(problem, run_request.stepper.schedule, scales) assert np.linalg.norm(final - uninterrupted) <= bound * np.linalg.norm( @@ -947,9 +983,8 @@ def test_an_abandoned_step_leaves_every_reader_refusing(lifecycle, narrow_grid, 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() + problem, run_request, _ = lifecycle() backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) original = backend.workspace.lab_source def overflowing(lab, position, **keywords): @@ -958,9 +993,9 @@ def overflowing(lab, position, **keywords): backend.workspace.lab_source = overflowing with pytest.raises(ConvergenceError, match=r"non-finite state.*lost"): - backend.propagate_to(length) - with pytest.raises(BackendError, match="abandoned in flight"): - backend.observe() + session_run(backend, problem, bare(run_request), export=None) + # The session ended poisoned: the workspace's state is the step's register. + assert cast("Any", backend.march).in_flight is not None # The diverged step was not committed, so its evaluations are not counted. assert backend.metadata()["source_evaluations"] == 0 backend.close() @@ -984,7 +1019,7 @@ def test_an_atomic_engine_commits_its_step_whole(lifecycle, narrow_grid, atomic) """ from solprop._interrupts import handled # noqa: PLC0415 - problem, run_request, length = lifecycle() + problem, run_request, _ = lifecycle() if atomic: native = pytest.importorskip("solprop_native") _native_signal_lands_after_the_step( @@ -992,9 +1027,10 @@ def test_an_atomic_engine_commits_its_step_whole(lifecycle, narrow_grid, atomic) ) return backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) - assert backend._low_storage is not None - engine = cast("Any", backend._low_storage.engine) + session: Any = backend.prepare(problem, bare(run_request)).start( + Start.entrance(problem), owns=False + ) + engine = cast("Any", session._march.engine) assert isinstance(engine, HostLowStorage) is not atomic original = engine.trial @@ -1005,13 +1041,16 @@ def interrupted(z, dz): return squared engine.trial = interrupted + # The launch plane, then the first step. + session.acknowledge(session.advance().receipt) with handled(), pytest.raises(KeyboardInterrupt): - backend.propagate_to(length) + session.advance() schedule = run_request.stepper.schedule assert schedule is not None - assert backend.in_flight == (0.0, float(schedule.steps[0])) + assert session.in_flight == (0.0, float(schedule.steps[0])) with pytest.raises(BackendError, match="abandoned in flight"): - backend.observe() + session._observe(field=True) + session.close() backend.close() @@ -1147,7 +1186,7 @@ def held_volumes(backend, field): owners = { "backend": backend, "workspace": backend.workspace, - "engine": backend._low_storage.engine, + "engine": cast("Any", backend.march).engine, } for owner_name, owner in owners.items(): for name, value in vars(owner).items(): @@ -1181,12 +1220,11 @@ def test_the_ledger_holds_three_registers_the_scratch_and_the_table(mode, collar assert problem.responses.temporal_absorber_fine is not None field = 16 * math.prod(problem.shape) backend = NumpyRefBackend(problem, run_request, grid=grid, options=CARTESIAN_CHUNK) - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(float(run_request.stepper.save_planes[-1])) - assert np.all(np.isfinite(backend.observe().require_field())) + final = session_run(backend, problem, bare(run_request)).fields[-1] + assert np.all(np.isfinite(final)) ledger = backend.memory_ledger() - assert backend._low_storage is not None - engine = backend._low_storage.engine + # The run's own engine, which the backend keeps after it. + engine = cast("Any", backend.march).engine assert isinstance(engine, HostLowStorage) assert engine.held() == { row: ledger[row] @@ -1255,9 +1293,8 @@ def test_the_noise_draw_never_enters_the_propagating_field(): length = 1e-3 grid, _, noise, schedule, problem, run_request = noisy_free_case(length, 3, 8, []) backend = NumpyRefBackend(problem, run_request, grid=grid) - backend.set_initial(problem.initial.field0, noise) - backend.propagate_to(length) - final = backend.observe().require_field() + start = Start(field=problem.initial.field0, z=0.0, noise=noise) + final = session_run(backend, problem, bare(run_request), start).fields[-1] backend.close() assert_linear_limit(problem, final, schedule) @@ -1273,7 +1310,6 @@ def test_each_pass_carries_the_draw_at_its_own_position(monkeypatch): length, 94, 2, [KerrResponse(1e-22, thg=False)] ) backend = NumpyRefBackend(problem, run_request, grid=grid) - backend.set_initial(problem.initial.field0, noise) inputs, carried = [], [] source, nonlinear = backend.workspace.lab_source, backend.workspace.nonlinear @@ -1287,7 +1323,8 @@ def capture(lab, bundle, inverse): monkeypatch.setattr(backend.workspace, "lab_source", lab_source) monkeypatch.setattr(backend.workspace, "nonlinear", capture) - backend.propagate_to(length) + start = Start(field=problem.initial.field0, z=0.0, noise=noise) + session_run(backend, problem, bare(run_request), start, export=None) backend.close() z, h = float(schedule.edges[1]), float(schedule.steps[1]) positions = [position for position, _ in inputs[4:]] @@ -1410,10 +1447,6 @@ def test_the_table_is_keyed_on_its_run_and_rebuilt_where_the_run_changes( assert len(set(schedule.steps.tolist())) > 1 assert abs(float(keys[0]) - length / LIFECYCLE_STEPS) <= 4 * EPS * length backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - assert backend._low_storage is not None - engine = backend._low_storage.engine - assert isinstance(engine, HostLowStorage) - backend.set_initial(problem.initial.field0, None) built = [] propagator = backend.workspace.propagator @@ -1422,8 +1455,9 @@ def counted(anchor, position): return propagator(anchor, position) cast("Any", backend.workspace).propagator = counted - backend.propagate_to(length / 2) - backend.propagate_to(length) + session_run(backend, problem, bare(run_request), export=None) + engine = cast("Any", backend.march).engine + assert isinstance(engine, HostLowStorage) assert len(built) == 1 assert engine._table_step == float(keys[0]) backend.close() @@ -1438,17 +1472,18 @@ def counted(anchor, position): dataclasses.replace(varied_request.stepper, save_planes=[length]) ) backend = NumpyRefBackend(varied, varied_request, grid=narrow_grid) - backend.set_initial(varied.initial.field0, None) built.clear() propagator = backend.workspace.propagator cast("Any", backend.workspace).propagator = counted - backend.propagate_to(length) + session_run(backend, varied, bare(varied_request), export=None) assert len(built) == varied_schedule.n_steps - # A load drops the table, which the next step builds again. - backend.set_initial(varied.initial.field0, None) - assert backend._low_storage is not None - engine = backend._low_storage.engine - assert isinstance(engine, HostLowStorage) and engine._table is None + assert cast("Any", backend.march).engine._table is not None + # The next run's engine starts with no table, which its first step builds again. + with backend.prepare(varied, varied_request).start( + Start.entrance(varied), owns=False + ) as session: + engine = cast("Any", session)._march.engine + assert isinstance(engine, HostLowStorage) and engine._table is None backend.close() @@ -1530,26 +1565,26 @@ def test_a_linear_step_is_rk4_s_stability_function_and_reads_its_stiffness(rate) def test_the_march_warns_once_when_a_step_passes_the_interval( - lifecycle, narrow_grid, caplog + lifecycle, narrow_grid, caplog, monkeypatch ): """A stiffness past 2.785 is logged once per replay, never in the norm column.""" problem, run_request, length = lifecycle() backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) - assert backend._low_storage is not None - engine = backend._low_storage.engine - assert isinstance(engine, HostLowStorage) - step = engine.trial + step = HostLowStorage.trial - def stiff(z, dz): - squared = step(z, dz) + def stiff(engine, z, dz): + squared = step(engine, z, dz) engine.stiffness = 3.0 return squared - engine.trial = stiff + # The session's own engine, built for its run. + monkeypatch.setattr(HostLowStorage, "trial", stiff) with caplog.at_level(logging.WARNING, logger="solprop.backends.host.low_storage"): - backend.propagate_to(length / 2) - history = backend.observe().step_history + result = session_run( + backend, problem, bare(run_request), export=None, observations=2 + ) + history, _ = result.joined + assert result.observations[-1].z == length / 2 backend.close() warnings_logged = [ record.getMessage() @@ -1563,27 +1598,16 @@ def stiff(z, dz): @pytest.mark.parametrize("name", ["numpy_ref", "native"]) def test_a_replay_that_runs_out_says_so(lifecycle, narrow_grid, name): - # The reference's march, and the bridge's around the native resident engine. - problem, run_request, length = lifecycle() - if name == "native": - native = pytest.importorskip("solprop_native") - _native_replay_runs_out(native, problem, run_request, narrow_grid, length) - return - backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) - with pytest.raises(BackendError, match="cannot reach"): - backend.propagate_to(length * 1.02) - # Every step was taken and committed: nothing is left in flight. - assert backend.observe().z == length - backend.close() - - -def _native_replay_runs_out(native, problem, run_request, grid, length): - """A native run whose last plane lies past its schedule is refused by name. + """A run whose last plane lies past its schedule is refused by name. A session's planes are its itinerary, so the target past the schedule is a save plane the schedule does not reach, which the run is refused before any step. """ + problem, run_request, length = lifecycle() + if name == "native": + backend_class = pytest.importorskip("solprop_native").NativeBackend + else: + backend_class = NumpyRefBackend stepper = run_request.stepper beyond = run_request.with_stepper( dataclasses.replace( @@ -1591,7 +1615,7 @@ def _native_replay_runs_out(native, problem, run_request, grid, length): ) ) with pytest.raises(TranslationError, match="does not land on the save plane"): - native.NativeBackend(problem, beyond, grid=grid).close() + backend_class(problem, beyond, grid=narrow_grid).close() def test_a_failure_record_that_cannot_be_written_keeps_the_original_error(caplog): diff --git a/tests/backends/test_mixture_statistics.py b/tests/backends/test_mixture_statistics.py index bd5f7b9df..edea224f6 100644 --- a/tests/backends/test_mixture_statistics.py +++ b/tests/backends/test_mixture_statistics.py @@ -13,6 +13,7 @@ from numpy.testing import assert_allclose, assert_array_equal from bounds import assert_within, gamma +from builders import load_reference from mixture_cases import mixture_translation from sessions.runs import run as session_run from solprop.backends.numpy_ref import NumpyRefBackend, passes @@ -89,7 +90,7 @@ def test_population_statistics_refuse_invalid_domains(quantity): def test_numpy_species_statistics_match_the_independent_node_scans(): mixture, grid, _, _, (problem, run_request) = mixture_translation() backend = NumpyRefBackend(problem, run_request, grid=grid) - backend.set_initial(problem.initial.field0, None) + state = load_reference(backend) names = ( "species_ionisation", "species_electron_density", @@ -99,8 +100,10 @@ def test_numpy_species_statistics_match_the_independent_node_scans(): "electron_density", "peak_ionisation_rate", ) - values = backend.stats(StatsSpec(names=names, periodic=names[:2])) - nodes = backend.workspace._nodes_at(backend._require_state(), backend._z) + values = backend.workspace.stats( + StatsSpec(names=names, periodic=names[:2]), problem.initial.z + ) + nodes = backend.workspace._nodes_at(state, problem.initial.z) rates, fractions = passes.plasma_channel_fractions( nodes, problem.responses.plasma_channels, diff --git a/tests/backends/test_monitor_reduction.py b/tests/backends/test_monitor_reduction.py index 78ae7f13d..046c1a51f 100644 --- a/tests/backends/test_monitor_reduction.py +++ b/tests/backends/test_monitor_reduction.py @@ -28,6 +28,7 @@ import pytest from bounds import device_backend, ladder_bound +from builders import load_reference from capability_routes import LENGTH from legacy_geometry import bare_absorber from monitor_cases import ( @@ -38,16 +39,17 @@ ROUTE_NAMES, SCHEMES, STEPS, - as_driver, + as_reference, probe, reading, record_after_march, watched, with_copy, ) -from sessions.runs import bind_native_monitor, load_native, native_reading +from sessions.runs import bind_native_monitor, load_native, native_reading, to_planes from sessions.runs import run as session_run -from solprop.backends.protocol import stepping +from solprop.backends.events import ObservationKind, ObservationReady +from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.registry import available, select from solprop.backends.session import ExecutionOptions, Start from solprop.driver import Simulation @@ -305,10 +307,10 @@ def test_a_reading_needs_a_monitor(backend: str) -> None: made = select(backend, problem, run_request, grid=simulation.grid) try: if backend == "numpy_ref": - driver = as_driver(made) - driver.set_initial(problem.initial.field0, None) + reference = as_reference(made) + load_reference(reference) with pytest.raises(BackendError, match="no boundary monitor"): - driver._boundary_energies() + reference.workspace.reading() else: # The native state's own reduction, which its session reads at a check. from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] @@ -334,16 +336,10 @@ def test_a_monitor_for_another_grid_is_refused(backend: str) -> None: assert other is not None made = select(backend, problem, run_request, grid=simulation.grid) try: - if backend == "numpy_ref": - driver = as_driver(made) - driver.set_initial(problem.initial.field0, None) - with pytest.raises(BackendError, match="do not match the grid"): - driver.attach_monitor(other) - else: - # The native session refuses the weights by name before it binds them - # where its state lives. - with pytest.raises(BackendError, match="do not match the grid"): - session_run(made, problem, run_request.for_run(monitor=other)) + # Each session refuses the weights by name when it attaches the monitor, + # before it binds them where its state lives. + with pytest.raises(BackendError, match="do not match the grid"): + session_run(made, problem, run_request.for_run(monitor=other)) finally: made.close() @@ -404,14 +400,25 @@ def _host_second_run( """The reference's launch reading, a march, and its reading of a second load.""" made = watched(simulation, "numpy_ref") try: - driver = as_driver(made) first = reading(made) - stepping(made).propagate_to(LENGTH) problem = simulation.translate() - driver.set_initial(with_copy(problem.initial.field0, simulation.grid.n_t), None) + launch = with_copy(problem.initial.field0, simulation.grid.n_t) monitor = simulation._boundary_monitor() assert monitor is not None - driver.attach_monitor(monitor) + # A watched session marches the state to the end. + session_run( + made, + problem, + simulation._run_request().for_run(monitor=monitor), + Start(field=launch, z=float(problem.initial.z)), + ) + # The next load, watched by a fresh monitor, as the next run's session has it. + load_reference(made, launch) + fresh = simulation._boundary_monitor() + assert fresh is not None + if fresh.split: + fresh.crossing = problem.split_crossing + as_reference(made).workspace.bind_monitor(fresh) return first, reading(made), made.memory_ledger() finally: made.close() @@ -576,20 +583,61 @@ def test_successive_occupancies_are_the_reference_s(backend: str, route: str) -> _require(backend) simulation = probe(route, "split_step", MARCHES["runge_kutta"]) problem = simulation.translate() - theirs = watched(simulation, "numpy_ref") + run_request = simulation._run_request() + # The schedule's edges a replay to each third of the length stops at. + schedule = run_request.stepper.schedule + assert schedule is not None + edges = np.asarray(schedule.edges) + planes = sorted( + { + float(edges[np.searchsorted(edges, LENGTH * third / 3 * (1 - 1e-12))]) + for third in (1, 2, 3) + } + ) + request = to_planes(run_request, planes) + theirs = NumpyRefBackend( + problem, + request, + grid=simulation.grid, + modes=simulation.modes, + profiles=simulation.profiles, + options=simulation.settings.execution_options(), + ) ours = _built(simulation, backend, problem) # The matched march's rounding, amplified over its steps, relative to the energy. bound = ladder_bound( backend, 1e3 * _rounding(simulation), simulation.grid.n_t, 8 * STEPS ) + readings: list[tuple[np.ndarray, np.ndarray]] = [] + + def keep(session: Any, batch: Any) -> None: + # The reference's reading of the state at each plane, and the state itself. + for event in batch.events: + if isinstance(event, ObservationReady) and event.kind is ( + ObservationKind.PLANE + ): + occupancy = theirs.workspace.reading().occupancy + assert occupancy is not None + readings.append((occupancy, theirs.workspace.committed().copy())) + try: - monitor = _fresh_bound(ours, simulation, problem) - for third in (1, 2, 3): - stepping(theirs).propagate_to(LENGTH * third / 3) - expected = reading(theirs).occupancy - state = as_driver(theirs)._require_state() - got = native_reading(ours, monitor, np.array(state)).occupancy - assert expected is not None and got is not None + monitor = simulation._boundary_monitor() + assert monitor is not None + session_run( + theirs, + problem, + request.for_run(monitor=monitor), + Start( + field=with_copy(problem.initial.field0, simulation.grid.n_t), + z=float(problem.initial.z), + ), + between=keep, + ) + assert len(readings) == len(planes) + bound_monitor = _fresh_bound(ours, simulation, problem) + for expected, state in readings: + got = native_reading(ours, bound_monitor, state).occupancy + assert got is not None np.testing.assert_allclose( got, expected, rtol=0.0, atol=bound * float(expected.sum()) ) diff --git a/tests/backends/test_multistep_march.py b/tests/backends/test_multistep_march.py index 7790c7f44..b628f5506 100644 --- a/tests/backends/test_multistep_march.py +++ b/tests/backends/test_multistep_march.py @@ -15,8 +15,12 @@ import pytest from legacy_geometry import LEGACY_GRID +from sessions.runs import bare +from sessions.runs import run as session_run +from solprop.backends.host.adams import HostAdamsMarch from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.registry import resolve_name +from solprop.backends.session import Start from solprop.driver.settings import SimulationSettings from solprop.driver.simulation import Simulation from solprop.exceptions import ( @@ -49,15 +53,34 @@ def narrow_grid(): return EnvelopeGrid.from_limits(1.0, 835e-9, (500e-9, 2e-6), 1e-12, **LEGACY_GRID) +def _ledger(backend): + """Return the last run's Adams call ledger, or ``None`` for another march.""" + march = backend.march + return march.ledger if isinstance(march, HostAdamsMarch) else None + + +def observed(problem, run_request, grid, start=None): + """Run a problem through its session; return every plane's field and the ledger. + + The fields are those of the planes beyond the start, launch excluded. + """ + backend = NumpyRefBackend(problem, run_request, grid=grid) + try: + result = session_run(backend, problem, bare(run_request), start) + planes = [ + field[0, 0] + for event, field in zip(result.observations, result.fields, strict=True) + if event.plane_index >= 0 + ] + return planes, _ledger(backend) + finally: + backend.close() + + def run(problem, run_request, grid): """Propagate a problem to its last plane; return the field and the call ledger.""" - backend = NumpyRefBackend(problem, run_request, grid=grid) - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(float(run_request.stepper.save_planes[-1])) - field = backend.observe().require_field()[0, 0] - ledger = None if backend._adams is None else backend._adams.ledger - backend.close() - return field, ledger + planes, ledger = observed(problem, run_request, grid) + return planes[-1], ledger @pytest.mark.medium @@ -184,22 +207,18 @@ def test_dense_observation_is_the_exact_linear_flow_without_a_source( problem, run_request = linear_problem( narrow_grid, save_planes=planes, integrator=method, interpolate_planes=True ) - backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) + fields, ledger = observed(problem, run_request, narrow_grid) start = problem.initial.field0[0, 0] * problem.grids.active_mask - for plane in planes: - backend.propagate_to(plane) - field = backend.observe().require_field()[0, 0] + for plane, field in zip(planes, fields, strict=True): exact = np.exp(delta_phi(problem.linear, 0.0, plane))[0, 0] * start # With no source the interaction variable is constant across the step, so # the interpolant reproduces it: round-off in the propagators only. np.testing.assert_allclose( field, exact, rtol=0, atol=1e-12 * np.abs(start).max() ) - assert backend._adams is not None + assert ledger is not None # One step crosses every plane short of the end, which is landed on. - assert backend._adams.ledger.dense_observations == len(planes) - 1 - backend.close() + assert ledger.dense_observations == len(planes) - 1 @pytest.mark.medium @@ -215,15 +234,8 @@ def fields(method, *, interpolate=False): integrator=method, interpolate_planes=interpolate, ) - backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) - observed = [] - for plane in planes: - backend.propagate_to(plane) - observed.append(backend.observe().require_field()[0, 0]) - ledger = backend._adams.ledger if backend._adams is not None else None - backend.close() - return np.array(observed), ledger + found, ledger = observed(problem, run_request, narrow_grid) + return np.array(found), ledger landed, _ = fields(PEC45) interpolated, ledger = fields(PEC45, interpolate=True) @@ -273,11 +285,10 @@ def test_call_budget_stops_before_overspending(narrow_grid, soliton_problem): integrator=method, ) backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) with pytest.raises(ResponseBudgetError, match="budget of 25") as caught: - backend.propagate_to(SOLITON_PERIOD) - assert backend._adams is not None - ledger = backend._adams.ledger + session_run(backend, problem, bare(run_request), export=None) + ledger = _ledger(backend) + assert ledger is not None assert ledger.total == caught.value.calls <= budget # PEC needs one call a trial: the stop leaves none unspent. assert ledger.total == budget @@ -298,23 +309,18 @@ def test_resume_restarts_the_history_and_charges_its_startup( controller=PIController(rtol=1e-7, atol=1e-18), integrator=method, ) - whole = NumpyRefBackend(problem, run_request, grid=narrow_grid) - whole.set_initial(problem.initial.field0, None) - whole.propagate_to(SOLITON_PERIOD / 2) - halfway = whole.observe().require_field() - whole.propagate_to(SOLITON_PERIOD) - uninterrupted = whole.observe().require_field() - whole.close() - - resumed = NumpyRefBackend(problem, run_request, grid=narrow_grid) - resumed.set_initial(halfway, None, z=SOLITON_PERIOD / 2) - resumed.propagate_to(SOLITON_PERIOD) - restarted = resumed.observe().require_field() - assert resumed._adams is not None + (halfway, uninterrupted), _ = observed(problem, run_request, narrow_grid) + start = Start( + field=np.asarray(halfway)[None, None, :], + z=SOLITON_PERIOD / 2, + plane_index=1, + plane_pending=False, + ) + (restarted,), ledger = observed(problem, run_request, narrow_grid, start) + assert ledger is not None # A fresh start: one startup call and the order ramp again from one. - assert resumed._adams.ledger.startup == 1 - assert resumed._adams.ledger.orders[0] == 1 - resumed.close() + assert ledger.startup == 1 + assert ledger.orders[0] == 1 # Two trajectories each converged to rtol 1e-7: 1.2e-8 apart measured, bounded at # ten times that. error = np.linalg.norm(restarted - uninterrupted) / np.linalg.norm(uninterrupted) @@ -395,12 +401,14 @@ def test_an_interior_kink_restarts_the_history(): backend = NumpyRefBackend( problem, run_request, grid=simulation.grid, modes=simulation.modes ) - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(0.2) - history = backend.observe().step_history - assert backend._adams is not None - ledger = backend._adams.ledger - backend.close() + try: + history, _ = session_run( + backend, problem, bare(run_request), export=None + ).joined + ledger = _ledger(backend) + finally: + backend.close() + assert ledger is not None # The kink is an accepted step's end (the history records each attempt's end), and # the history restarts there at order one. ends = history.z[history.accepted] @@ -450,10 +458,9 @@ def test_repeated_rejections_restart_the_history(narrow_grid, soliton_problem): integrator=Multistep(formulation="interaction"), ) backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(SOLITON_PERIOD / 4) - march = backend._adams - assert march is not None + session_run(backend, problem, bare(run_request), export=None) + march = backend.march + assert isinstance(march, HostAdamsMarch) assert len(march._history) > 1 for _ in range(3): march._reject(1e-3, 2.0, 2) diff --git a/tests/backends/test_native_error_norm.py b/tests/backends/test_native_error_norm.py index c6799874b..262a5b852 100644 --- a/tests/backends/test_native_error_norm.py +++ b/tests/backends/test_native_error_norm.py @@ -32,7 +32,7 @@ import pytest from bounds import EPS, gamma, higham_gamma -from builders import reference_trial +from builders import load_reference, reference_trial from sessions.runs import load_native, native_trial, run from solprop.backends.numpy_ref import NumpyRefBackend from solprop.stepper import PIController @@ -92,7 +92,7 @@ def _operands(backend, reference, problem, run_request, dz): np.asarray(_testing.stage_to_host(state, index)).reshape(shape) for index in range(len(tableau.nodes)) ] - reference.set_initial(problem.initial.field0, None) + load_reference(reference) reference_trial(reference, 0.0, dz) step = reference.workspace.stage_scalars(0.0, dz) propagator = np.exp(reference.workspace.exponents(0.0, dz)(1.0, step)) @@ -157,7 +157,7 @@ def test_a_whole_trial_scores_as_the_reference_s_trial_does( reference = NumpyRefBackend(problem, run_request, grid=field_grid) backend, score = _native_trial(problem, run_request, field_grid, dz) try: - reference.set_initial(problem.initial.field0, None) + load_reference(reference) wanted, _ = reference_trial(reference, 0.0, dz) finally: backend.close() @@ -253,7 +253,7 @@ def test_a_weighted_controller_scores_as_the_reference_s_does( reference = NumpyRefBackend(problem, run_request, grid=field_grid) backend, score = _native_trial(problem, run_request, field_grid, dz) try: - reference.set_initial(problem.initial.field0, None) + load_reference(reference) wanted, _ = reference_trial(reference, 0.0, dz) finally: backend.close() diff --git a/tests/backends/test_native_mixture_fractions.py b/tests/backends/test_native_mixture_fractions.py index 2d53191bb..0deeb3738 100644 --- a/tests/backends/test_native_mixture_fractions.py +++ b/tests/backends/test_native_mixture_fractions.py @@ -35,6 +35,7 @@ from backends.matched import native_thread_fields from backends.native_mixture_launch_probe import NAMES, launch_case from bounds import EPS +from builders import load_reference from solprop.backends.numpy_ref import NumpyRefBackend, passes native = pytest.importorskip("solprop_native") @@ -51,16 +52,12 @@ def oracle(kerr, n_pol): grid, problem, run_request = launch_case(kerr, n_pol) reference = NumpyRefBackend(problem, run_request, grid=grid) try: - reference.set_initial(problem.initial.field0, None) + state = load_reference(reference) reference.workspace.hoist(0.0) bundle = reference.workspace.stage_scalars(0.0, 0.0) fields = np.real( np.concatenate( - list( - reference.workspace._plasma_nodes( - reference._require_state(), reference._z - ) - ) + list(reference.workspace._plasma_nodes(state, problem.initial.z)) ) ) finally: diff --git a/tests/backends/test_native_planar_statistics.py b/tests/backends/test_native_planar_statistics.py index c8d7ffd01..2a50e0b49 100644 --- a/tests/backends/test_native_planar_statistics.py +++ b/tests/backends/test_native_planar_statistics.py @@ -28,7 +28,8 @@ from backends.planar_plate_cases import chunked from backends.planar_plate_cases import planar_case as collar_family_case from bounds import assert_within, fft_bound, gamma -from sessions.runs import launch_statistics, load_native +from builders import load_reference +from sessions.runs import bare, final_field, launch_statistics, load_native from solprop.backends.numpy_ref import NumpyRefBackend from solprop.stats import StatsSpec @@ -83,9 +84,9 @@ def run(backend_class, problem, run_request, grid, length): """Propagate the problem's launch and return the state.""" backend = backend_class(problem, run_request, grid=grid) try: - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(length) - return backend.observe().require_field().copy() + result = final_field(backend, problem, bare(run_request)) + assert math.isclose(float(run_request.stepper.z_end), length, rel_tol=1e-12) + return result.copy() finally: backend.close() @@ -166,7 +167,7 @@ def finished(problem, run_request, grid, rows, dz, options=None): """Return each backend's finish of the rows it is handed, the reference's first.""" reference = NumpyRefBackend(problem, run_request, grid=grid, options=options) try: - reference.set_initial(problem.initial.field0, None) + load_reference(reference) reference.workspace.hoist(0.0) expected = np.array(reference.workspace.finish(rows.copy(), dz)[0]) finally: diff --git a/tests/backends/test_numpy_engines.py b/tests/backends/test_numpy_engines.py index 861ac8f0f..988f14906 100644 --- a/tests/backends/test_numpy_engines.py +++ b/tests/backends/test_numpy_engines.py @@ -9,7 +9,7 @@ ``accept`` returns; the Adams engine takes the retained entries oldest first and the host source's reservation as ``begin_attempt``/``end_attempt``. The split collar's sums are taken by the workspace's finish on the masked field before the split and travel in -the :class:`~solprop.backends.engines.AcceptRecord`, which the driver accumulates. +the :class:`~solprop.backends.engines.AcceptRecord`, which the session accumulates. Every comparison here repeats one computation on one build, so equality is exact by construction (structural, SEP 25): the engines move arrays, they do not recompute them. @@ -23,8 +23,13 @@ import pytest from backend_corpus_cases import FIBRE, STEPS, walking_fibre +from builders import load_reference +from sessions.runs import bare, run from solprop.backends.engines import AcceptRecord, AttemptOutcome +from solprop.backends.events import Eligibility, Outcome from solprop.backends.numpy_ref import NumpyRefBackend +from solprop.backends.numpy_ref.multistep import HostHistory +from solprop.backends.session import Start from solprop.exceptions import BackendError from solprop.stepper import FixedSchedule, LowStorageRungeKutta, Multistep, RungeKutta @@ -35,7 +40,7 @@ def _loaded(soliton_problem, narrow_grid, **settings): """Return the soliton's reference backend loaded at the entrance.""" problem, request = soliton_problem(narrow_grid, 1, save_planes=[LENGTH], **settings) backend = NumpyRefBackend(problem, request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) + load_reference(backend) return backend @@ -43,7 +48,8 @@ def test_a_runge_kutta_trial_commits_nothing_until_it_is_accepted( soliton_problem, narrow_grid ): with closing(_loaded(soliton_problem, narrow_grid)) as backend: - engine, workspace = backend._runge_kutta_engine, backend.workspace + workspace = backend.workspace + engine = backend._runge_kutta(workspace) committed = workspace.state assert committed is not None before = committed.copy() @@ -71,16 +77,19 @@ def test_a_runge_kutta_engine_counts_every_stage_it_evaluates( soliton_problem, narrow_grid ): with closing(_loaded(soliton_problem, narrow_grid)) as backend: - engine = backend._runge_kutta_engine + engine = cast("Any", backend.march).engine stages = backend.request.stepper.tableau.n_stages engine.trial(0.0, LENGTH / 8) engine.trial(0.0, LENGTH / 16) assert engine.evaluations == 2 * stages assert len(engine.stages) == stages - backend.set_initial(backend._problem.initial.field0, None) - assert engine.evaluations == 0 + assert backend.metadata()["source_evaluations"] == 2 * stages + # The next run's engine is its own, and counts afresh. + fresh = cast("Any", backend.method(None).march).engine + assert fresh.evaluations == 0 + assert backend.metadata()["source_evaluations"] == 0 with pytest.raises(BackendError, match="take a trial"): - _ = engine.trial_state + _ = fresh.trial_state def test_the_low_storage_trial_is_in_flight_until_its_accept_returns( @@ -94,8 +103,7 @@ def test_the_low_storage_trial_is_in_flight_until_its_accept_returns( schedule=schedule, ) with closing(backend): - assert backend._low_storage is not None - engine = cast("Any", backend._low_storage.engine) + engine = cast("Any", backend.march).engine workspace = backend.workspace before = np.array(workspace.state) assert not engine.in_flight @@ -128,24 +136,36 @@ def failing(state, dz): raise RuntimeError("the finish failed") monkeypatch.setattr(backend.workspace, "finish", failing) - with pytest.raises(RuntimeError, match="the finish failed"): - backend.propagate_to(LENGTH) - assert backend.in_flight == (0.0, float(schedule.steps[0])) + problem, request = backend.workspace.problem, backend.request + prepared = backend.prepare(problem, request) + session: Any = prepared.start(Start.entrance(problem), owns=False) + session.acknowledge(session.advance().receipt) + terminal = session.advance().terminal + assert terminal is not None and terminal.outcome is Outcome.FAILED + assert isinstance(terminal.error, RuntimeError) + assert terminal.eligibility is Eligibility.POISONED + assert session.in_flight == (0.0, float(schedule.steps[0])) assert backend.metadata()["source_evaluations"] == 0 with pytest.raises(BackendError, match="abandoned in flight"): - backend.observe() + session.march_snapshot_nbytes() + session.close() monkeypatch.undo() - backend.set_initial(backend._problem.initial.field0, None) - assert backend.in_flight is None + # A new session loads afresh, with nothing in flight. + with cast("Any", prepared.start(Start.entrance(problem), owns=False)) as again: + assert again.in_flight is None @pytest.mark.parametrize("formulation", ["interaction", "exponential"]) def test_an_adams_attempt_reserves_then_records_and_releases( soliton_problem, narrow_grid, monkeypatch, formulation ): - backend = _loaded( - soliton_problem, narrow_grid, integrator=Multistep(formulation=formulation) + problem, request = soliton_problem( + narrow_grid, + 1, + save_planes=[LENGTH / 4], + integrator=Multistep(formulation=formulation), ) + backend = NumpyRefBackend(problem, request, grid=narrow_grid) calls = [] with closing(backend): workspace = backend.workspace @@ -160,8 +180,7 @@ def test_an_adams_attempt_reserves_then_records_and_releases( monkeypatch.setattr( workspace, "release_calls", lambda: calls.append(("release",)) ) - backend.propagate_to(LENGTH / 4) - history = backend.observe().step_history + history, _ = run(backend, problem, bare(request), export=None).joined # One reservation per attempt, then its decision, then the release: the startup # sample is charged to the first. attempts = [calls[index : index + 3] for index in range(0, len(calls), 3)] @@ -175,8 +194,7 @@ def test_an_adams_attempt_reserves_then_records_and_releases( def test_an_abandoned_adams_attempt_only_releases(soliton_problem, narrow_grid): backend = _loaded(soliton_problem, narrow_grid, integrator=Multistep()) with closing(backend): - assert backend._adams is not None - engine = backend._adams._engine + engine = cast("Any", backend.march)._engine calls = [] workspace = backend.workspace workspace.record_trial = lambda *, accepted: calls.append(("record", accepted)) @@ -189,20 +207,21 @@ def test_an_abandoned_adams_attempt_only_releases(soliton_problem, narrow_grid): def test_an_adams_accept_takes_the_kept_entries_oldest_first( soliton_problem, narrow_grid, monkeypatch ): - backend = _loaded(soliton_problem, narrow_grid, integrator=Multistep()) + problem, request = soliton_problem( + narrow_grid, 1, save_planes=[LENGTH / 4], integrator=Multistep() + ) + backend = NumpyRefBackend(problem, request, grid=narrow_grid) with closing(backend): - march = backend._adams - assert march is not None - engine = march._engine seen = [] - accept = engine.accept + accept = HostHistory.accept - def spy(dz, free, stencil, kept): + def spy(engine, dz, free, stencil, kept): seen.append(([entry.z for entry in kept], [e.row for e in kept], free)) - return accept(dz, free, stencil, kept) + return accept(engine, dz, free, stencil, kept) - monkeypatch.setattr(engine, "accept", spy) - backend.propagate_to(LENGTH / 4) + # The session's own engine, built for its run. + monkeypatch.setattr(HostHistory, "accept", spy) + run(backend, problem, bare(request), export=None) assert len(seen) > 2 for positions, rows, free in seen: assert positions == sorted(positions) @@ -210,15 +229,18 @@ def spy(dz, free, stencil, kept): def _split_backend(): - """Return the walking fibre's reference backend, loaded and watched.""" + """Return the walking fibre's reference backend, its workspace loaded and watched, + and its monitor.""" simulation = walking_fibre("numpy_ref", RungeKutta()) problem = simulation.translate() request = simulation._run_request() backend = NumpyRefBackend(problem, request, grid=simulation.grid) - backend.set_initial(problem.initial.field0, None) + load_reference(backend) monitor = simulation._boundary_monitor() assert monitor is not None and monitor.split - backend.attach_monitor(monitor) + # As a session's attached monitor: the crossing limit read, the workspace bound. + monitor.crossing = problem.split_crossing + backend.workspace.bind_monitor(monitor) return backend, monitor @@ -228,7 +250,7 @@ def test_the_finish_takes_the_split_sums_on_the_masked_field_before_the_split(): with closing(backend): workspace = backend.workspace dz = FIBRE / STEPS - engine = backend._runge_kutta_engine + engine = backend._runge_kutta(workspace) engine.trial(0.0, dz) raw = engine.trial_state finished, record = workspace.finish(raw, dz) @@ -244,24 +266,34 @@ def test_the_finish_takes_the_split_sums_on_the_masked_field_before_the_split(): @pytest.mark.medium -def test_the_driver_adds_the_removal_and_keeps_the_latest_occupancies(): - backend, _ = _split_backend() +def test_the_session_adds_the_removal_and_keeps_the_latest_occupancies(): + backend, monitor = _split_backend() with closing(backend): + problem, request = backend.workspace.problem, backend.request + prepared = backend.prepare(problem, request) + session = cast("Any", prepared.start(Start.entrance(problem), owns=False)) + # The monitor bound as the session's attachment binds it. + session._bind_monitor(monitor) first = np.array([1.0, 0.5, 0.25, 0.125]) latest = np.array([2.0, 1.0, 0.5, 0.25]) - backend._absorb(AcceptRecord(removed=1.5, found=first)) - backend._absorb(AcceptRecord(removed=0.25, found=latest)) + session.absorb(AcceptRecord(removed=1.5, found=first)) + session.absorb(AcceptRecord(removed=0.25, found=latest)) # A step that took no sums (no split, or no monitor) leaves both alone. - backend._absorb(AcceptRecord()) - assert backend._split_removed == 1.75 - assert backend._split_found is latest + session.absorb(AcceptRecord()) + assert session._split_removed == 1.75 + assert session._split_found is latest # The next reading drains the removal and judges the latest occupancies. - reading = backend._boundary_energies() + reading = session._energies() assert reading.removed == 1.75 assert reading.found is latest - assert backend._split_removed == 0.0 - # Loading a state empties the accumulator. - backend._absorb(AcceptRecord(removed=3.0, found=first)) - backend.set_initial(backend._problem.initial.field0, None) - assert backend._split_removed == 0.0 - assert backend._split_found is None + assert session._split_removed == 0.0 + # Attaching a monitor starts the accumulator from zero. + session.absorb(AcceptRecord(removed=3.0, found=first)) + session._bind_monitor(monitor) + assert session._split_removed == 0.0 + assert session._split_found is None + session.close() + # Loading a state, as every session does, starts it empty. + with cast("Any", prepared.start(Start.entrance(problem), owns=False)) as again: + assert again._split_removed == 0.0 + assert again._split_found is None diff --git a/tests/backends/test_numpy_ref_backend.py b/tests/backends/test_numpy_ref_backend.py index 2cd557d00..40a0b02aa 100644 --- a/tests/backends/test_numpy_ref_backend.py +++ b/tests/backends/test_numpy_ref_backend.py @@ -17,7 +17,9 @@ import pytest from bounds import EPS, assert_within, departure, gamma +from builders import load_reference from sessions.executors import IDENTITY, Started, drive, entrance +from sessions.runs import bare, run, to_planes from solprop.backends import Backend from solprop.backends.events import ObservationReady from solprop.backends.numpy_ref import NumpyRefBackend @@ -180,17 +182,6 @@ def test_the_observation_is_the_state_in_the_fft_convention( assert plane.noise_phase is None -def test_a_plane_already_reached_costs_no_steps(soliton_problem, narrow_grid): - """The reference driver's own call; a session's launch plane costs no attempt - (:func:`test_the_observation_is_the_state_in_the_fft_convention`).""" - problem, run_request = soliton_problem(narrow_grid, 1, save_planes=[LENGTH]) - backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) - summary = backend.propagate_to(0.0) - assert (summary.n_steps, summary.max_norm, summary.met_tolerance) == (0, 0.0, True) - backend.close() - - def test_the_history_covers_only_what_happened_since_the_last_observation( backend_class, soliton_problem, narrow_grid ): @@ -304,41 +295,30 @@ def test_the_initial_state_must_match_the_contract( backend.close() -def test_propagating_without_a_state_is_refused(soliton_problem, narrow_grid): - """The reference driver's own call: a session always loads its start.""" - problem, run_request = soliton_problem(narrow_grid, 1, save_planes=[LENGTH]) - backend = NumpyRefBackend(problem, run_request) - with pytest.raises(BackendError, match="call set_initial"): - backend.propagate_to(LENGTH) - backend.close() - - -@pytest.mark.parametrize("target", [-1.0, 10.0, float("nan")]) -def test_an_unreachable_plane_is_refused(soliton_problem, narrow_grid, target): - """The reference driver's own call: a session's targets are its request's planes.""" +def test_an_unloaded_workspace_is_refused(soliton_problem, narrow_grid): + """The reference's workspace holds no state until a session loads its start.""" problem, run_request = soliton_problem(narrow_grid, 1, save_planes=[LENGTH]) backend = NumpyRefBackend(problem, run_request) - backend.set_initial(problem.initial.field0, None) - with pytest.raises(BackendError): - backend.propagate_to(target) + with pytest.raises(BackendError, match="no initial state"): + backend.workspace.committed() backend.close() def test_close_is_idempotent_and_use_after_close_is_refused( soliton_problem, narrow_grid ): - """The reference driver's own calls (:func:`test_a_closed_backend_starts_nothing` - is every backend's).""" + """The reference's own entries after a close (:func:`test_a_closed_backend_starts_ + nothing` is every backend's).""" problem, run_request = soliton_problem(narrow_grid, 1, save_planes=[LENGTH]) backend = NumpyRefBackend(problem, run_request, grid=narrow_grid) - backend.set_initial(problem.initial.field0, None) + load_reference(backend) backend.close() backend.close() for call in ( - lambda: backend.propagate_to(LENGTH), - backend.observe, - lambda: backend.stats(StatsSpec(names=("energy",))), - lambda: backend.set_initial(problem.initial.field0, None), + lambda: backend.timing_probe(entrance(problem)), + lambda: start_session( + backend, problem, run_request, entrance(problem), owns=False + ), ): with pytest.raises(BackendError, match="closed"): call() @@ -595,13 +575,13 @@ def test_statistics_reproduce_the_reference( def test_statistics_without_a_grid_say_what_is_missing(soliton_problem, narrow_grid): """The contract carries no grid, so the backend has to be told which one it is. - The reference driver's own call: a session's statistics are its request's. + The reference's workspace, which a session's statistics are evaluated by. """ problem, run_request = soliton_problem(narrow_grid, 1, save_planes=[LENGTH]) backend = NumpyRefBackend(problem, run_request) - backend.set_initial(problem.initial.field0, None) + load_reference(backend) with pytest.raises(BackendError, match="grid=grid"): - backend.stats(StatsSpec(names=("energy",))) + backend.workspace.stats(StatsSpec(names=("energy",)), 0.0) backend.close() @@ -703,9 +683,9 @@ def test_the_alarm_is_weighted_at_the_stage_it_was_scored_from( stage. """ problem, run_request = capillary_problem() - backend = NumpyRefBackend(problem, run_request, grid=field_grid) - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(0.1) + request = to_planes(run_request, [0.1]) + backend = NumpyRefBackend(problem, request, grid=field_grid) + run(backend, problem, bare(request), export=None) bundle = backend.workspace._last_bundle assert bundle is not None stage_z = bundle.z1 @@ -786,7 +766,7 @@ def test_a_step_too_large_for_the_tolerance_is_rejected_and_retried( assert np.all(plane.step_history.error_norm[accepted] <= 1.0) -def test_the_realisation_passed_to_set_initial_is_the_one_carried( +def test_the_realisation_a_start_passes_is_the_one_carried( backend_class, soliton_problem, narrow_grid ): """The protocol loads the noise; the problem's own realisation is the fallback.""" diff --git a/tests/backends/test_numpy_ref_plasma.py b/tests/backends/test_numpy_ref_plasma.py index 1302ec754..e6d8f4537 100644 --- a/tests/backends/test_numpy_ref_plasma.py +++ b/tests/backends/test_numpy_ref_plasma.py @@ -23,6 +23,7 @@ import pytest from bounds import fft_bound, scan_bound +from builders import load_reference from plasma_cases import ( CARRIER, CHARGE_MASS_RATIO, @@ -369,7 +370,7 @@ def test_one_stage_matches_the_responses_composed_by_hand( """The whole chain against the two oracles, with nothing of the backend in it.""" problem, run_request, kerr, plasma = ionising_capillary(preionisation) backend = NumpyRefBackend(problem, run_request) - backend.set_initial(problem.initial.field0, None) + load_reference(backend) state = problem.initial.field0 ones = np.ones_like(state) got = backend.workspace.nonlinear( @@ -718,7 +719,7 @@ def test_the_on_axis_matrix_follows_a_taper(field_grid, backend_class): try: observed = run(backend, problem, run_request).final if isinstance(backend, NumpyRefBackend): - rescaled = backend.workspace._on_axis_synthesis([mode], backend._z) + rescaled = backend.workspace._on_axis_synthesis([mode], observed.z) else: # Native keeps the entrance matrix (its statistics' own) and rescales it # by the transform's taper factor where it reads it. This is that law on diff --git a/tests/backends/test_numpy_ref_raman.py b/tests/backends/test_numpy_ref_raman.py index 490650cc6..88a7aa2b3 100644 --- a/tests/backends/test_numpy_ref_raman.py +++ b/tests/backends/test_numpy_ref_raman.py @@ -30,6 +30,7 @@ import pytest from bounds import assert_within, fft_bound +from builders import load_reference from former_raman import FORMER_H2, FORMER_N2, former_response from legacy_geometry import LEGACY_GRID from sessions.runs import run as session_run @@ -343,7 +344,7 @@ def test_one_stage_matches_the_responses_composed_by_hand( """The whole chain against the two oracles, at three densities of the gradient.""" problem, run_request, kerr, raman = raman_capillary() backend = NumpyRefBackend(problem, run_request) - backend.set_initial(problem.initial.field0, None) + load_reference(backend) state = problem.initial.field0 got = backend.workspace.nonlinear( state, backend.workspace.stage_scalars(0.0, z), np.ones_like(state) diff --git a/tests/backends/test_on_axis_statistics.py b/tests/backends/test_on_axis_statistics.py index ef6e5adbc..a106ff278 100644 --- a/tests/backends/test_on_axis_statistics.py +++ b/tests/backends/test_on_axis_statistics.py @@ -23,6 +23,7 @@ import pytest from bounds import assert_within, device_backend, fft_bound, gamma, rate_log_sensitivity +from builders import load_reference from rate_oracles import adk_oracle from sessions.executors import IDENTITY from sessions.runs import launched, load_native, run @@ -111,8 +112,8 @@ def entrance_stats(grid, problem, run_request, modes, spec): with closing( NumpyRefBackend(problem, run_request, grid=grid, modes=modes) ) as backend: - backend.set_initial(problem.initial.field0, None) - values = backend.stats(spec) + load_reference(backend) + values = backend.workspace.stats(spec, problem.initial.z) # select() returns the seam's protocol; the counter is the shared driver's. return values, cast("Any", backend).workspace.axis_scans @@ -376,8 +377,8 @@ def test_a_problem_without_plasma_refuses_them(grid): ) as backend, pytest.raises(BackendError, match="need a compiled plasma response"), ): - backend.set_initial(problem.initial.field0, None) - backend.stats(AXIS) + load_reference(backend) + backend.workspace.stats(AXIS, problem.initial.z) BACKENDS = ["native"] @@ -587,10 +588,10 @@ def test_a_host_backend_s_axis_scan_needs_the_field(grid, table): with closing( NumpyRefBackend(problem, run_request, grid=grid, modes=[mode]) ) as backend: - backend.set_initial(problem.initial.field0, None) + load_reference(backend) with pytest.raises(BackendError, match="needs the field"): backend.workspace._axis_row_populations( # pyright: ignore[reportPrivateUsage] - None, np.zeros((2, 1)), backend._z + None, np.zeros((2, 1)), problem.initial.z ) diff --git a/tests/backends/test_planar_hybrid.py b/tests/backends/test_planar_hybrid.py index e6eda2ffb..2c7f68477 100644 --- a/tests/backends/test_planar_hybrid.py +++ b/tests/backends/test_planar_hybrid.py @@ -27,7 +27,10 @@ from backends.planar_hybrid_cases import ENVELOPE, FAMILIES, HALF_GAP, LENGTH, ORDERS from backends.rate_bounds import rate_error_bound from bounds import fft_bound, gamma, step_evaluations +from builders import load_reference from legacy_geometry import bare_absorber +from sessions.runs import bare, final_field +from sessions.runs import run as session_run from solprop.backends.numpy_ref import NumpyRefBackend, passes from solprop.backends.spatial import ( slab_columns, @@ -123,10 +126,13 @@ def modal_and_planar(family): def run(problem, run_request, grid, names=()): backend = NumpyRefBackend(problem, run_request, grid=grid) try: - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(LENGTH) - field = backend.observe().require_field().copy() - values = backend.stats(StatsSpec(names=names)) if names else {} + result = session_run( + backend, problem, run_request.for_run(stats=StatsSpec(names=names)) + ) + last = result.observations[-1] + assert math.isclose(last.z, LENGTH, rel_tol=1e-12) + field = result.fields[-1].copy() + values = dict(last.stats) if names else {} finally: backend.close() return field, values @@ -340,9 +346,7 @@ def test_a_linear_beam_diffracts_in_y_and_decays_as_each_slab_mode(): problem, run_request = hybrid.translate(), hybrid._run_request() backend = NumpyRefBackend(problem, run_request, grid=grid) try: - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(length) - final = backend.observe().require_field()[:, 0, 0] + final = final_field(backend, problem, bare(run_request), ended=True)[:, 0, 0] finally: backend.close() start = problem.initial.field0[:, 0, 0] @@ -429,9 +433,9 @@ def test_the_kerr_phase_at_the_beam_centre_is_the_closed_form_b_integral(): problem, run_request = hybrid.translate(), hybrid._run_request() backend = NumpyRefBackend(problem, run_request, grid=grid) try: - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(LENGTH) - final = backend.observe().require_field()[:, 0, :] + final = final_field(backend, problem, bare(run_request), ended=True)[ + :, 0, : + ] finally: backend.close() centre = np.fft.ifft(final.reshape(space.n_y, -1), axis=0)[space.n_y // 2] @@ -488,8 +492,8 @@ def test_the_planar_launch_carries_the_coupled_share_of_the_incident_energy(): run_request = simulation._run_request() backend = NumpyRefBackend(problem, run_request, grid=grid) try: - backend.set_initial(problem.initial.field0, None) - values = backend.stats(spec) + load_reference(backend) + values = backend.workspace.stats(spec, problem.initial.z) finally: backend.close() shares = gaussian_coupling(modes, 0.735 * HALF_GAP) @@ -559,9 +563,11 @@ def test_a_modulation_in_y_grows_at_the_modulational_instability_rate(): problem, run_request = hybrid.translate(), hybrid._run_request() backend = NumpyRefBackend(problem, run_request, grid=grid) try: - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(length) - finals.append(backend.observe().require_field()[:, 0, :].copy()) + finals.append( + final_field(backend, problem, bare(run_request), ended=True)[ + :, 0, : + ].copy() + ) finally: backend.close() kerr_run, linear_run = finals diff --git a/tests/backends/test_polarised_runs.py b/tests/backends/test_polarised_runs.py index 5985ea616..1a2a62eec 100644 --- a/tests/backends/test_polarised_runs.py +++ b/tests/backends/test_polarised_runs.py @@ -11,6 +11,7 @@ import pytest from bounds import gamma, ladder_bound, record_backend +from builders import load_reference from convergence_records import record from convergence_studies import BACKEND_EQUIVALENCE from legacy_geometry import LEGACY_GRID @@ -146,7 +147,7 @@ def problem_derivative(backend_class, problem, run_request, grid, modes): backend = backend_class(problem, run_request, grid=grid, modes=modes) try: if isinstance(backend, NumpyRefBackend): - backend.set_initial(problem.initial.field0, None) + load_reference(backend) backend.workspace.hoist(0.0) bundle = backend.workspace.stage_scalars(0.0, 0.0) derivative = backend.workspace.nonlinear( diff --git a/tests/backends/test_radial_absorber.py b/tests/backends/test_radial_absorber.py index 03deaf727..2739d0590 100644 --- a/tests/backends/test_radial_absorber.py +++ b/tests/backends/test_radial_absorber.py @@ -25,6 +25,7 @@ problem_for, radial_absorber_case, ) +from builders import load_reference from sessions.runs import native_trial, run from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.spatial import collar_field_fraction @@ -115,7 +116,7 @@ def test_spatial_absorber_derivative_matches_independent_bessel_operator( backend = spatial_backend_class(problem, run_request, grid=grid) try: if isinstance(backend, NumpyRefBackend): - backend.set_initial(problem.initial.field0, None) + load_reference(backend) backend.workspace.hoist(0.0) measured = backend.workspace.nonlinear( problem.initial.field0, diff --git a/tests/backends/test_radial_statistics.py b/tests/backends/test_radial_statistics.py index 894cc802f..daedb1502 100644 --- a/tests/backends/test_radial_statistics.py +++ b/tests/backends/test_radial_statistics.py @@ -11,8 +11,9 @@ import pytest from numpy.testing import assert_allclose +from builders import load_reference from hankel_oracles import gamma -from sessions.runs import launch_statistics +from sessions.runs import bare, final_field, launch_statistics from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.spatial import collect_spatial from solprop.exceptions import BackendError @@ -123,10 +124,11 @@ def test_radial_statistics_match_the_host_without_field_observation( oracle = NumpyRefBackend(problem, run_request, grid=grid) backend = spatial_backend_class(problem, run_request, grid=grid) try: - oracle.set_initial(problem.initial.field0, None) - if steps: - oracle.propagate_to(grid.length) - state = oracle.observe().require_field() + state = ( + final_field(oracle, problem, bare(run_request), ended=True) + if steps + else load_reference(oracle) + ) reference = collect(spec, grid, SavedPlane(z=0.0, field=state), flux=flux) bounds = statistic_bounds(grid, space, state, reference, flux) # The backend's own session observes the state as its launch plane; the diff --git a/tests/backends/test_records.py b/tests/backends/test_records.py index 5c4854765..a9d322229 100644 --- a/tests/backends/test_records.py +++ b/tests/backends/test_records.py @@ -202,7 +202,7 @@ def test_the_reference_s_adams_march_reads_the_shared_policy(): records = run_records(problem, request, _entrance(problem)) backend: Any = select("numpy_ref", problem, request) try: - assert backend._adams._policy == records.policy + assert backend.march._policy == records.policy finally: backend.close() @@ -248,10 +248,9 @@ def test_the_reference_s_runge_kutta_march_reads_the_shared_policy(): backend: Any = select("numpy_ref", problem, request) try: assert ( - backend._march._policy + backend.march._policy == run_records(problem, request, _entrance(problem)).policy ) - assert backend._collar_can_rest() is collar_rests(problem, request.stepper) finally: backend.close() diff --git a/tests/backends/test_reference_independence.py b/tests/backends/test_reference_independence.py index 9a4aa4d4c..c96a6e37b 100644 --- a/tests/backends/test_reference_independence.py +++ b/tests/backends/test_reference_independence.py @@ -14,7 +14,6 @@ import pytest from solprop.backends.host.adams import HostAdamsMarch -from solprop.backends.host.driver import HostDriver from solprop.backends.host.low_storage import HostLowStorageMarch from solprop.backends.host.session import HostSession from solprop.backends.numpy_ref import NumpyRefBackend @@ -25,18 +24,14 @@ from solprop.stepper import FixedSchedule, LowStorageRungeKutta, Multistep -def test_the_reference_backend_inherits_the_host_driver(): - assert issubclass(NumpyRefBackend, HostDriver) - - 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 = { - "_adams": (Multistep(), HostAdamsMarch), - "_low_storage": (LowStorageRungeKutta(), HostLowStorageMarch), + "adams": (Multistep(), HostAdamsMarch), + "low_storage": (LowStorageRungeKutta(), HostLowStorageMarch), } - for attribute, (integrator, march) in marches.items(): + for integrator, march in marches.values(): problem, run_request = soliton_problem( narrow_grid, 1, @@ -49,7 +44,8 @@ def test_the_reference_marches_with_the_host_copies(soliton_problem, narrow_grid with closing( NumpyRefBackend(problem, run_request, grid=narrow_grid) ) as backend: - assert type(getattr(backend, attribute)) is march + assert type(backend.march) is march + assert type(backend.method(None).march) is march def test_the_run_layer_serves_the_reference_with_the_host_session( @@ -74,7 +70,7 @@ def test_an_injected_adams_engine_is_gated_and_checked_as_the_bridge_s( HostAdamsMarch( object(), Multistep(), - backend._hooks, + None, policy=adams_policy( backend._problem, run_request.stepper, Multistep(), carrier=False ), diff --git a/tests/backends/test_source_evaluations.py b/tests/backends/test_source_evaluations.py index 4f9668cdd..0d84ae469 100644 --- a/tests/backends/test_source_evaluations.py +++ b/tests/backends/test_source_evaluations.py @@ -59,18 +59,24 @@ def test_python_counter_tracks_dispatch_through_rejection( ) reference: Any = NumpyRefBackend(problem, run_request, grid=narrow_grid) with closing(reference) as engine: - engine.set_initial(problem.initial.field0, None) calls = [] - stepper = engine._runge_kutta_engine - original_trial = stepper.trial + build = engine._runge_kutta - def trial(z, dz): - before = engine.metadata()["source_evaluations"] - original_trial(z, dz) - calls.append(engine.metadata()["source_evaluations"] - before) - return 4.0 if len(calls) == 1 else 0.01 + def scripted(workspace): + # The session's own Runge-Kutta engine, its trial's norms scripted. + stepper = build(workspace) + original_trial = stepper.trial - monkeypatch.setattr(stepper, "trial", trial) + def trial(z, dz): + before = engine.metadata()["source_evaluations"] + original_trial(z, dz) + calls.append(engine.metadata()["source_evaluations"] - before) + return 4.0 if len(calls) == 1 else 0.01 + + monkeypatch.setattr(stepper, "trial", trial) + return stepper + + monkeypatch.setattr(engine, "_runge_kutta", scripted) dispatched = [] original_source = engine.workspace.nonlinear @@ -79,11 +85,13 @@ def source(*args, **kwargs): return original_source(*args, **kwargs) monkeypatch.setattr(engine.workspace, "nonlinear", source) - summary = engine.propagate_to(0.002) - assert summary.n_rejected == 1 + record: dict[str, Any] = {} + result = session_run(engine, problem, run_request, record=record) + history, _ = result.joined + assert int(np.sum(~np.asarray(history.accepted))) == 1 assert calls[0] == 7 - count = engine.metadata()["source_evaluations"] + count = record["source_evaluations"] assert count == sum(calls) assert count > sum(calls[1:]) assert count == len(dispatched) - assert np.isfinite(engine.observe().field).all() + assert np.isfinite(result.fields[-1]).all() diff --git a/tests/backends/test_step_limits.py b/tests/backends/test_step_limits.py index 1333f5d35..41dc0c74a 100644 --- a/tests/backends/test_step_limits.py +++ b/tests/backends/test_step_limits.py @@ -16,7 +16,9 @@ import numpy as np import pytest +from sessions.runs import bare, run from solprop.backends.numpy_ref import NumpyRefBackend +from solprop.backends.session import Start from solprop.driver import simulation as simulation_module from solprop.driver.simulation import Simulation from solprop.gasflow import steady_fill @@ -34,18 +36,21 @@ def history(problem, run_request, grid, *, z_start=0.0): """Run a problem to its last plane; return the accepted starts and lengths.""" backend = NumpyRefBackend(problem, run_request, grid=grid) - backend.set_initial(problem.initial.field0, None, z=z_start) - starts, lengths = [], [] - for plane in run_request.stepper.save_planes: - if plane <= z_start: - continue - backend.propagate_to(float(plane)) - steps = backend.observe().step_history - # The history records where each attempt ended. - starts += list((steps.z - steps.dz)[steps.accepted]) - lengths += list(steps.dz[steps.accepted]) - backend.close() - return np.array(starts), np.array(lengths) + planes = np.asarray(run_request.stepper.save_planes) + start = Start( + field=problem.initial.field0, + z=z_start, + plane_index=int(np.searchsorted(planes, z_start, side="right")), + plane_pending=z_start == problem.initial.z, + ) + try: + steps, _ = run(backend, problem, bare(run_request), start, export=None).joined + finally: + backend.close() + accepted = np.asarray(steps.accepted, dtype=bool) + # The history records where each attempt ended. + starts = (np.asarray(steps.z) - np.asarray(steps.dz))[accepted] + return starts, np.asarray(steps.dz)[accepted] def with_limits(run_request, **limits): diff --git a/tests/backends/test_tdse_march.py b/tests/backends/test_tdse_march.py index 450060fe4..40821264e 100644 --- a/tests/backends/test_tdse_march.py +++ b/tests/backends/test_tdse_march.py @@ -7,15 +7,17 @@ import dataclasses import itertools import json -from typing import cast +from typing import Any, cast import numpy as np import pytest from numpy.testing import assert_array_equal +from builders import load_reference from sessions.executors import IDENTITY, Started, drive from sessions.runs import run as session_run from solprop.backends import registry +from solprop.backends.events import ObservationReady from solprop.backends.ledger import CallLedger from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.session import Start @@ -150,29 +152,56 @@ def march_problem(request): return simulation.translate(), simulation._run_request(), simulation.grid -def opened_backend(case, limit, *, fail_at=None): +def opened_backend(case, limit, *, fail_at=None, binding_type=None): problem, run_request, grid = case assert tdse_descriptor(problem.route) is not None - binding = ManufacturedBinding( + binding = (ManufacturedBinding if binding_type is None else binding_type)( tdse_descriptor(problem.route), limit, fail_at=fail_at ) backend = NumpyRefBackend(problem, run_request, grid=grid, tdse_binding=binding) - backend.set_initial(problem.initial.field0, None, z=problem.initial.z) return backend, binding +def failed_run(backend, case, z=None): + """Run a session from the launch (or `z`) to its failure. + + Returns the terminal event, the field its ticket exports (``None`` without one) + and the run, whose first field is the loaded launch's. + """ + problem, run_request, _ = case + held = {} + + def keep(session, batch): + terminal = batch.terminal + if terminal is not None and terminal.ticket is not None: + held["field"] = session.export(terminal.ticket, IDENTITY) + + start = None + if z is not None: + planes = run_request.stepper.save_planes + start = Start( + field=problem.initial.field0, + z=z, + plane_index=int(np.searchsorted(planes, z, side="right")), + ) + result = session_run( + backend, problem, run_request, start, raises=False, between=keep + ) + terminal = result.terminal + assert terminal.error is not None + return terminal, held.get("field"), result + + def test_whole_startup_trial_is_reserved_before_any_atomic_chunk(march_problem): backend, binding = opened_backend(march_problem, 3) - initial = backend.observe().require_field() try: - with pytest.raises(ResponseBudgetError): - backend.propagate_to(1e-5) + terminal, field, result = failed_run(backend, march_problem) + assert isinstance(terminal.error, ResponseBudgetError) assert binding.ledger.attempted == 0 assert binding.ledger.reserved == 0 - assert backend._adams is not None - assert backend._adams.ledger.total == 0 - assert backend.observe().z == 0.0 - assert_array_equal(backend.observe().require_field(), initial) + assert cast("Any", backend.march).ledger.total == 0 + assert terminal.z == 0.0 + assert_array_equal(field, result.fields[0]) finally: backend.close() @@ -182,21 +211,20 @@ def test_atomic_stop_keeps_accepted_state_and_labels_predictor( march_problem, initial_z ): backend, binding = opened_backend(march_problem, 5) - backend.set_initial(march_problem[0].initial.field0, None, z=initial_z) try: - with pytest.raises(ResponseBudgetError, match="atomic-call budget") as caught: - backend.propagate_to(1e-5) - observation = backend.observe() - assert observation.z > initial_z - assert caught.value.z == observation.z - assert f"z = {observation.z:g} m" in str(caught.value) - assert caught.value.calls == binding.ledger.attempted - assert caught.value.__suppress_context__ - assert_array_equal(caught.value.field, observation.field) + terminal, field, _ = failed_run(backend, march_problem, z=initial_z) + error = terminal.error + assert isinstance(error, ResponseBudgetError) + assert "atomic-call budget" in str(error) + assert terminal.z > initial_z + assert error.z == terminal.z + assert f"z = {terminal.z:g} m" in str(error) + assert error.calls == binding.ledger.attempted + assert error.__suppress_context__ + assert_array_equal(error.field, field) assert binding.ledger.attempted == 4 assert binding.ledger.reserved == 0 - assert backend._adams is not None - assert backend._adams.ledger.total == 2 + assert cast("Any", backend.march).ledger.total == 2 assert binding.purposes == ["startup", "predictor"] metadata = backend.metadata() last = metadata["tdse_last_evaluation"] @@ -207,7 +235,7 @@ def test_atomic_stop_keeps_accepted_state_and_labels_predictor( assert projection["kind"] == "embedded_same_rows" # Optical observation and permitted statistics do not request another # expensive atomic evaluation of the corrected accepted field. - backend.stats(StatsSpec(names=("energy",))) + backend.workspace.stats(StatsSpec(names=("energy",)), terminal.z) assert binding.ledger.attempted == 4 finally: backend.close() @@ -217,17 +245,16 @@ def test_failed_chunk_is_charged_and_unused_trial_reservation_is_released( march_problem, ): backend, binding = opened_backend(march_problem, 8, fail_at=2) - initial = backend.observe().require_field() try: - with pytest.raises(BackendError, match="second-chunk failure"): - backend.propagate_to(1e-5) + terminal, field, result = failed_run(backend, march_problem) + assert isinstance(terminal.error, BackendError) + assert "second-chunk failure" in str(terminal.error) assert binding.ledger.attempted == 2 assert binding.ledger.failed_calls == 1 assert binding.ledger.reserved == 0 - assert backend._adams is not None - assert backend._adams.ledger.total == 1 - assert backend.observe().z == 0.0 - assert_array_equal(backend.observe().require_field(), initial) + assert cast("Any", backend.march).ledger.total == 1 + assert terminal.z == 0.0 + assert_array_equal(field, result.fields[0]) finally: backend.close() @@ -255,17 +282,16 @@ def test_an_archive_failure_after_an_accepted_commit_keeps_the_new_state( march_problem, ): """The commit is the failure boundary (SEP 49, section 6.3).""" - problem, run_request, grid = march_problem - binding = _ArchiveFailsOnAcceptance(tdse_descriptor(problem.route), 20) - backend = NumpyRefBackend(problem, run_request, grid=grid, tdse_binding=binding) - backend.set_initial(problem.initial.field0, None, z=problem.initial.z) + backend, binding = opened_backend( + march_problem, 20, binding_type=_ArchiveFailsOnAcceptance + ) try: - with pytest.raises(TDSEArchiveError, match="synthetic archive failure"): - backend.propagate_to(1e-5) + terminal, _, _ = failed_run(backend, march_problem) + assert isinstance(terminal.error, TDSEArchiveError) + assert "synthetic archive failure" in str(terminal.error) # The accepted step stands and is booked; nothing stays reserved. - assert backend.observe().z > 0.0 - assert backend._adams is not None - assert backend._adams.ledger.accepted_steps == 1 + assert terminal.z > 0.0 + assert cast("Any", backend.march).ledger.accepted_steps == 1 assert binding.ledger.reserved == 0 # The startup and the predictor, two chunks each, stay charged. assert binding.ledger.attempted == 4 @@ -274,18 +300,19 @@ def test_an_archive_failure_after_an_accepted_commit_keeps_the_new_state( def test_a_failed_release_is_a_note_on_the_trial_s_own_error(march_problem): - problem, run_request, grid = march_problem - binding = _ReleaseFails(tdse_descriptor(problem.route), 8, fail_at=2) - backend = NumpyRefBackend(problem, run_request, grid=grid, tdse_binding=binding) - backend.set_initial(problem.initial.field0, None, z=problem.initial.z) + backend, binding = opened_backend( + march_problem, 8, fail_at=2, binding_type=_ReleaseFails + ) try: - with pytest.raises(BackendError, match="second-chunk failure") as caught: - backend.propagate_to(1e-5) - assert "synthetic release failure" in "\n".join(caught.value.__notes__) + terminal, _, _ = failed_run(backend, march_problem) + error = terminal.error + assert isinstance(error, BackendError) + assert "second-chunk failure" in str(error) + assert "synthetic release failure" in "\n".join(error.__notes__) assert binding.ledger.reserved == 0 - assert backend.observe().z == 0.0 + assert terminal.z == 0.0 finally: - binding.failing = False + cast("_ReleaseFails", binding).failing = False backend.close() @@ -334,8 +361,9 @@ def test_tdse_runtime_statistics_refuse_legacy_rate_observables(march_problem, n """A dynamic request for rate-model statistics cannot trigger another solve.""" backend, binding = opened_backend(march_problem, 4) try: + load_reference(backend) with pytest.raises(BackendError, match="does not define legacy statistics"): - backend.stats(StatsSpec(names=(name,))) + backend.workspace.stats(StatsSpec(names=(name,)), 0.0) assert binding.ledger.attempted == 0 finally: backend.close() @@ -401,13 +429,21 @@ def test_reference_rk_restoration_requires_the_matching_response_path( if kind == "atomic" else None ) + start = Start( + field=problem.initial.field0, + z=float(problem.initial.z), + ledgers={"logical": logical, "atomic": atomic or {}}, + ) if kind == "logical": # Not installed in a Runge-Kutta march (SEP 42 section 5.6). - backend.restore_call_ledgers(logical, atomic) - assert backend._adams is None + session = start_session(backend, problem, run_request, start, owns=False) + try: + assert "response_calls" not in session.execution_record() + finally: + session.close() else: with pytest.raises(BackendError, match="requires a TDSE binding"): - backend.restore_call_ledgers(logical, atomic) + start_session(backend, problem, run_request, start, owns=False) finally: backend.close() @@ -419,17 +455,31 @@ def test_backend_restores_atomic_charges_without_numerical_history(march_problem startup=1, predictor=1, accepted_steps=1, orders=[1] ).to_record() atomic = dataclasses.asdict(AtomicCallLedger(8, 4, 2, 2, 0, 0)) - initial = backend.observe().require_field().copy() + problem, run_request, _ = march_problem + start = Start( + field=problem.initial.field0, + z=float(problem.initial.z), + ledgers={"logical": logical, "atomic": atomic}, + ) try: - backend.restore_call_ledgers(logical, atomic) - assert backend.metadata()["response_calls"] == logical - assert binding.ledger == AtomicCallLedger(8, 4, 0, 2, 0, 0) - assert backend._adams is not None - assert backend._adams._history == [] - assert backend._adams._order == 1 - assert_array_equal(backend.observe().require_field(), initial) - cast("list[list[int]]", logical["orders"]).append([3, 1]) - assert backend._adams.ledger.orders == [1] + session = start_session(backend, problem, run_request, start, owns=False) + try: + initial = backend.workspace.committed().copy() + assert session.execution_record()["response_calls"] == logical + assert binding.ledger == AtomicCallLedger(8, 4, 0, 2, 0, 0) + march = cast("Any", backend.march) + assert march._history == [] + assert march._order == 1 + launch = session.advance() + event = launch.events[0] + assert isinstance(event, ObservationReady) + observed = session.export(event.ticket, IDENTITY) + assert_array_equal(observed, initial) + session.acknowledge(launch.receipt) + cast("list[list[int]]", logical["orders"]).append([3, 1]) + assert march.ledger.orders == [1] + finally: + session.close() finally: backend.close() diff --git a/tests/driver/test_coherent_capillary.py b/tests/driver/test_coherent_capillary.py index 1e33c7d35..67903ad7a 100644 --- a/tests/driver/test_coherent_capillary.py +++ b/tests/driver/test_coherent_capillary.py @@ -53,6 +53,7 @@ ) from march_bounds import FIXED_ORDER from modal_provider_cases import GENERAL_Z_END, general_grid, general_guide +from sessions.runs import bare, final_field from solprop.backends import available from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.workspace import ( @@ -192,10 +193,11 @@ def energy_loss(handler): def propagated(problem, run_request, grid, backend=NumpyRefBackend): """Run one problem to its end plane on the fixed schedule and return the state.""" driver = backend(problem, run_request, grid=grid) - driver.set_initial(problem.initial.field0, None) - driver.propagate_to(LENGTH) - final = driver.observe().require_field().copy() - driver.close() + try: + final = final_field(driver, problem, bare(run_request)) + finally: + driver.close() + assert final.shape == problem.shape return final diff --git a/tests/driver/test_estimate.py b/tests/driver/test_estimate.py index 0f612f855..bb13f0bb5 100644 --- a/tests/driver/test_estimate.py +++ b/tests/driver/test_estimate.py @@ -12,10 +12,10 @@ import numpy as np import pytest -from builders import reference_trial +from builders import load_reference, reference_trial from capability_routes import ROUTES from sessions.runs import load_native, native_trial -from solprop.backends.protocol import stepping as host_stepping +from solprop.backends.numpy_ref.engines import NumpyRungeKutta from solprop.backends.registry import available, select from solprop.backends.session import SessionError, Start from solprop.driver import Simulation @@ -141,10 +141,11 @@ def test_a_low_storage_estimate_times_the_march_s_own_step(backend, monkeypatch) def spy(constructed, problem, run_request): step, evaluations = build(constructed, problem, run_request) - engine = getattr(constructed, "_runge_kutta_engine", None) + # The reference's Runge-Kutta engine, built afresh for each run, or native's. + reference = constructed.name == "numpy_ref" monkeypatch.setattr( - constructed if engine is None else engine, - "_trial_step" if engine is None else "trial", + NumpyRungeKutta if reference else constructed, + "trial" if reference else "_trial_step", lambda *_: pytest.fail("a low-storage estimate took a trial step"), ) @@ -263,16 +264,12 @@ def test_a_timing_probe_commits_nothing_and_reads_back_its_trial(backend): if backend == "native": trial = _native_committed_nothing(problem, probed, fresh, dz) else: - # Nothing was committed: no attempt, the launch position, the loaded state. - host_stepping(fresh).set_initial( - problem.initial.field0, None, z=problem.initial.z + # Nothing was committed: the probed workspace holds the loaded state. + expected = load_reference( + fresh, problem.initial.field0, z=problem.initial.z ) - expected = host_stepping(fresh).observe() - observed = host_stepping(probed).observe() - assert observed.n_steps == 0 - assert observed.z == problem.initial.z - assert observed.field is not None and expected.field is not None - assert np.array_equal(observed.field, expected.field) + observed = cast("Any", probed).workspace.committed() + assert np.array_equal(observed, expected) # The readback is the trial's own state as a kept step finishes it: the # same arithmetic again, on one thread layout in one process, so agreement # to a few roundings of the field's largest magnitude bounds it (SEP 25). diff --git a/tests/driver/test_field_free_planes.py b/tests/driver/test_field_free_planes.py index 0ce349e79..75e7ddbff 100644 --- a/tests/driver/test_field_free_planes.py +++ b/tests/driver/test_field_free_planes.py @@ -22,9 +22,13 @@ from bounds import AccuracyEnvelope, assert_within, fft_bound, gamma from legacy_geometry import LEGACY_GRID, bare_absorber +from sessions.runs import bare +from solprop.backends.events import ObservationReady, Terminal +from solprop.backends.export import ExportRecipe +from solprop.backends.host.session import HostSession from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.workspace import NumpyWorkspace -from solprop.backends.protocol import BackendHistory, Observation, stepping +from solprop.backends.protocol import BackendHistory, Observation from solprop.backends.registry import available, select from solprop.backends.session import Start from solprop.driver import Simulation, SimulationSettings @@ -433,12 +437,24 @@ class _NoRetention(MemoryOutput): backend.close() -# --- the seam: observe(field=False) (SEP 22 phase 2) -------------------------------- +# --- field-free observation (SEP 22 phase 2) ----------------------------------------- + + +IDENTITY = ExportRecipe(power=False, optics=False) + + +def _first_plane(owner, problem, run_request, start): + """Start the reference's session, acknowledge its launch, return the first plane.""" + session = owner.prepare(problem, run_request).start(start, owns=False) + launch = session.advance() + session.acknowledge(launch.receipt) + batch = session.advance() + return session, batch def test_a_field_free_observation_crosses_no_field(monkeypatch): - # The reference's driver seam. The native backend has no such seam: its session - # exports a field only on request (SEP 47 section 5.4), which + # The reference session's observation of its state (`HostSession._observe`). The + # native session exports a field only on request (SEP 47 section 5.4), which # tests/sessions/test_conformance.py::test_a_plane_nobody_exports_transfers_no_field # counts on every executor. backend = "numpy_ref" @@ -446,6 +462,7 @@ def test_a_field_free_observation_crosses_no_field(monkeypatch): problem = simulation.translate() run_request = simulation._run_request() observations = [] + histories = [] for field in (True, False): owner = select(backend, problem, run_request, grid=simulation.grid) copies = [] @@ -458,20 +475,27 @@ def counted(self, z, copies=copies, original=original): # The observation reads the noise phase beside the field and neither without. monkeypatch.setattr(NumpyWorkspace, "noise_phase", counted) try: - stepping(owner).set_initial(problem.initial.field0, None) - stepping(owner).propagate_to(float(PLANES[0])) - observations.append(stepping(owner).observe(field=field)) + session, batch = _first_plane( + owner, problem, run_request, Start.entrance(problem) + ) + (event,) = batch.events + assert isinstance(event, ObservationReady) + assert event.z == float(PLANES[0]) + histories.append(event.history) + assert isinstance(session, HostSession) + observations.append(session._observe(field=field)) + session.close() finally: owner.close() monkeypatch.undo() - # The field-free observation makes no copy at all. + # The field-free observation makes no copy at all, the event's included. assert len(copies) == (1 if field else 0) kept, free = observations assert kept.field is not None and kept.noise_phase is not None assert free.field is None and free.noise_phase is None # The same replayed march: its history is one structure, observed either way. - assert np.array_equal(free.step_history.z, kept.step_history.z) - assert np.array_equal(free.step_history.dz, kept.step_history.dz) + assert np.array_equal(histories[1].z, histories[0].z) + assert np.array_equal(histories[1].dz, histories[0].dz) with pytest.raises(BackendError, match=r"observe\(field=False\)"): free.require_field() @@ -479,13 +503,13 @@ def counted(self, z, copies=copies, original=original): def test_the_run_asks_the_backend_for_exactly_the_kept_fields(monkeypatch): simulation = keeping(cartesian("numpy_ref"), "planes", (0, -1)) asked = [] - original = NumpyRefBackend.observe + original = HostSession._observe - def observe(self, *, field=True): + def observe(self, *, field): asked.append(field) return original(self, field=field) - monkeypatch.setattr(NumpyRefBackend, "observe", observe) + monkeypatch.setattr(HostSession, "_observe", observe) stored(simulation.run(progress="none")) # Every event drains its attempts field-free (a yield's and the terminal event's # too, SEP 47 section 5.3); the field crosses only for the two planes that keep it @@ -514,17 +538,24 @@ def test_a_field_free_observation_relies_on_the_step_loop_for_finiteness(): poisoned[0, 0, np.flatnonzero(problem.grids.active_mask)[0]] = np.nan backend = NumpyRefBackend(problem, run_request, grid=simulation.grid) try: - backend.set_initial(poisoned, None) - # Nothing scans a field that is not observed... - assert backend.observe(field=False).field is None - # ...while an observed one is scanned, and the replay refuses to step on. + # No statistics: they would read the poisoned field at the launch plane. + session = backend.prepare(problem, bare(run_request)).start( + Start(field=poisoned, z=float(problem.initial.z)), owns=False + ) + # Nothing scans a field that is not observed: the launch plane is reported... + launch = session.advance() + (event,) = launch.events + assert isinstance(event, ObservationReady) + # ...while an exported one is scanned, and the replay refuses to step on. with pytest.raises(BackendError, match="not finite"): - backend.observe() - with ( - np.errstate(invalid="ignore"), - pytest.raises((ConvergenceError, BackendError)), - ): - backend.propagate_to(float(PLANES[0])) + session.export(event.ticket, IDENTITY) + session.acknowledge(launch.receipt) + with np.errstate(invalid="ignore"): + batch = session.advance() + terminal = batch.terminal + assert isinstance(terminal, Terminal) + assert isinstance(terminal.error, (ConvergenceError, BackendError)) + session.close() finally: backend.close() diff --git a/tests/driver/test_flow_collar.py b/tests/driver/test_flow_collar.py index c444d74c6..1f4574485 100644 --- a/tests/driver/test_flow_collar.py +++ b/tests/driver/test_flow_collar.py @@ -62,6 +62,7 @@ from march_bounds import FIXED_ORDER from modal_provider_cases import GENERAL_Z_END from sessions.runs import bare, final_field, to_planes +from sessions.runs import run as session_run from solprop.backends import available, records from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.session import Start @@ -308,12 +309,17 @@ def test_a_coupled_flow_keeps_its_collar_in_every_stage(transient, name, monkeyp problem, run_request, grid = transient assert problem.linear.coupled_flow is not None if name == "numpy_ref": - # The reference's driver, whose collar rule the native session's mirrors. + # The reference's session, whose collar rule the native session's mirrors. + assert not records.collar_rests(problem, run_request.stepper) driver: Any = backend(problem, run_request, grid=grid) try: - assert not driver._collar_can_rest() - driver._set_collar_quiet(True) - assert not driver._collar_quiet + session: Any = driver.prepare(problem, run_request).start( + Start.entrance(problem), owns=False + ) + session._set_collar_quiet(True) + assert not session.collar_quiet + assert not driver.workspace.collar_quiet + session.close() finally: driver.close() return @@ -443,15 +449,16 @@ def test_the_in_band_answer_moves_by_less_than_the_derived_bound(case): run_request = simulation._run_request() grid = simulation.grid band = problem.grids.inband_mask - planes = [] - driver = NumpyRefBackend(problem, run_request, grid=grid) + # Every step's end observed, through the backend's session (SEP 47). + request = to_planes( + bare(run_request), [(step + 1) * LENGTH / STEPS for step in range(STEPS)] + ) + driver = NumpyRefBackend(problem, request, grid=grid) try: - driver.set_initial(problem.initial.field0, None) - for step in range(STEPS): - driver.propagate_to((step + 1) * LENGTH / STEPS) - planes.append(driver.observe().require_field().copy()) + planes = [field.copy() for field in session_run(driver, problem).fields[1:]] finally: driver.close() + assert len(planes) == STEPS old = run(NumpyRefBackend, scored_everywhere(problem), run_request, grid) departure = float( np.linalg.norm((planes[-1] - old)[..., band]) / np.linalg.norm(old[..., band]) diff --git a/tests/driver/test_general_modal.py b/tests/driver/test_general_modal.py index e7d15d0dd..4dd83c7eb 100644 --- a/tests/driver/test_general_modal.py +++ b/tests/driver/test_general_modal.py @@ -33,6 +33,7 @@ from numpy.testing import assert_allclose from bounds import departure +from builders import load_reference from legacy_geometry import LEGACY_GRID from march_bounds import ( FIXED_ORDER, @@ -47,7 +48,6 @@ ) from solprop import fourier from solprop.backends import select -from solprop.backends.protocol import stepping from solprop.backends.session import Start from solprop.constants import ROOM_TEMPERATURE, C from solprop.coupling import CouplingModel, CouplingReport @@ -1132,14 +1132,14 @@ def test_the_backend_refuses_an_inadmissible_name_on_its_own(guide, grid): run_request = simulation._run_request() backend = select("numpy_ref", problem, run_request, grid=grid) try: - stepping(backend).set_initial(problem.initial.field0, None) + load_reference(backend) + workspace = cast("Any", backend).workspace + z = float(problem.initial.z) with pytest.raises(BackendError, match="peak_intensity is unavailable"): - stepping(backend).stats(StatsSpec(names=("peak_intensity",))) + workspace.stats(StatsSpec(names=("peak_intensity",)), z) with pytest.raises(BackendError, match="energy is unavailable"): - stepping(backend).stats(StatsSpec(names=("energy",))) - assert stepping(backend).stats( - StatsSpec(names=("physical_energy", "analytic_flux")) - ) + workspace.stats(StatsSpec(names=("energy",)), z) + assert workspace.stats(StatsSpec(names=("physical_energy", "analytic_flux")), z) finally: backend.close() diff --git a/tests/driver/test_initial_z_and_checkpoint.py b/tests/driver/test_initial_z_and_checkpoint.py index e971e65fa..f9bcea0f0 100644 --- a/tests/driver/test_initial_z_and_checkpoint.py +++ b/tests/driver/test_initial_z_and_checkpoint.py @@ -5,6 +5,7 @@ """Exercise interior launches and restartable stops on tiny optical problems.""" import dataclasses +from typing import Any, cast import numpy as np import pytest @@ -13,9 +14,10 @@ from tests.driver.test_resume import run_until from tests.driver.test_run import NullBackend +from builders import load_reference +from solprop.backends.host.session import HostSession from solprop.backends.ledger import CallLedger -from solprop.backends.numpy_ref import NumpyRefBackend -from solprop.backends.protocol import stepping +from solprop.backends.numpy_ref.workspace import NumpyWorkspace from solprop.backends.registry import select from solprop.backends.session import Start from solprop.backends.sessions import start_session @@ -507,6 +509,11 @@ def _loaded(backend, problem, run_request, start) -> int: return start.plane_index +def _position(backend) -> float: + """Return where the reference's last session left its march, m.""" + return float(backend.march.state.z) + + def test_resume_uses_checkpoint_position_and_rejects_inconsistent_index(tmp_path): simulation = tiny_simulation() problem = simulation.translate() @@ -534,7 +541,7 @@ def test_resume_uses_checkpoint_position_and_rejects_inconsistent_index(tmp_path ) == 0 ) - assert stepping(backend).observe().z == 5e-6 + assert _position(backend) == 5e-6 assert state.checkpoint is not None invalid = dataclasses.replace( state, checkpoint=dataclasses.replace(state.checkpoint, next_save_index=1) @@ -575,13 +582,13 @@ def test_ordinary_resume_without_outcome_restores_plane_and_starts_fresh_ledgers ) == 1 ) - observed = stepping(backend).observe() - assert observed.z == 5e-6 + observed = cast("Any", backend).workspace.committed() + assert _position(backend) == 5e-6 assert_array_equal( - observed.require_field()[..., problem.grids.active_mask], + observed[..., problem.grids.active_mask], problem.initial.field0[..., problem.grids.active_mask], ) - assert np.all(observed.require_field()[..., ~problem.grids.active_mask] == 0) + assert np.all(observed[..., ~problem.grids.active_mask] == 0) assert backend.metadata()["response_calls"] == CallLedger().to_record() finally: backend.close() @@ -598,15 +605,16 @@ def test_statistics_failure_keeps_drained_history_without_retrying_statistics( "numpy_ref", problem, run_request, grid=simulation.grid, modes=simulation.modes ) calls = [] - original = NumpyRefBackend.stats + # The session evaluates every observation's statistics on its workspace. + original = NumpyWorkspace.stats - def fail_second(self, spec): + def fail_second(self, spec, z): calls.append(1) if len(calls) == 2: raise DriverError("manufactured statistics failure") - return original(self, spec) + return original(self, spec, z) - monkeypatch.setattr(NumpyRefBackend, "stats", fail_second) + monkeypatch.setattr(NumpyWorkspace, "stats", fail_second) memory = MemoryOutput() try: with pytest.raises(DriverError, match="manufactured statistics failure"): @@ -803,21 +811,22 @@ def test_resume_saves_checkpoint_on_missing_final_plane_before_completion( ): simulation = tiny_simulation() path = tmp_path / "missing-final.h5" - original = NumpyRefBackend.stats + # The session evaluates every observation's statistics on its workspace. + original = NumpyWorkspace.stats attempts = [] - def fail_final(self, spec): + def fail_final(self, spec, z): attempts.append(1) if len(attempts) == 2: raise DriverError("manufactured final statistics failure") - return original(self, spec) + return original(self, spec, z) - monkeypatch.setattr(NumpyRefBackend, "stats", fail_final) + monkeypatch.setattr(NumpyWorkspace, "stats", fail_final) with pytest.raises(DriverError, match="final statistics"): simulation.run(path, progress="none") first = resume(path) assert first.n_saved == 1 and first.plane.z == 1e-5 - monkeypatch.setattr(NumpyRefBackend, "stats", original) + monkeypatch.setattr(NumpyWorkspace, "stats", original) simulation.run(path, resume=True, progress="none") finished = resume(path) assert finished.n_saved == 2 @@ -1165,7 +1174,8 @@ def test_a_resume_without_an_outcome_loads_the_field_without_restoring_ledgers( def forbidden(*args, **kwargs): raise AssertionError("a file without an outcome carries no call ledgers") - monkeypatch.setattr(NumpyRefBackend, "restore_call_ledgers", forbidden) + # The reference's session restores a start's ledgers. + monkeypatch.setattr(HostSession, "_restore_ledgers", forbidden) backend = select( "numpy_ref", problem, run_request, grid=simulation.grid, modes=simulation.modes ) @@ -1179,7 +1189,7 @@ def forbidden(*args, **kwargs): ) == 0 ) - assert stepping(backend).observe().z == state.plane.z + assert _position(backend) == state.plane.z finally: backend.close() @@ -1239,8 +1249,7 @@ def test_spatial_resume_retains_physical_field_without_modal_normalisation(monke "numpy_ref", problem, run_request, grid=grid, modes=simulation.modes ) try: - stepping(backend).set_initial(problem.initial.field0, None) - field = stepping(backend).observe().require_field().copy() + field = load_reference(backend).copy() state = ResumeState( simulation.metadata(), SavedPlane(z=5e-6, field=field), @@ -1262,9 +1271,8 @@ def forbidden(*args, **kwargs): ) == 0 ) - restored = stepping(backend).observe() - assert restored.z == state.plane.z - assert_array_equal(restored.require_field(), field) + assert _position(backend) == state.plane.z + assert_array_equal(cast("Any", backend).workspace.committed(), field) finally: backend.close() diff --git a/tests/driver/test_moving_guide.py b/tests/driver/test_moving_guide.py index 3f92fb519..2754ddccf 100644 --- a/tests/driver/test_moving_guide.py +++ b/tests/driver/test_moving_guide.py @@ -49,6 +49,7 @@ moving_simulation, step_grid, ) +from sessions.runs import bare, final_field from solprop.backends import select from solprop.backends.numpy_ref.backend import NumpyRefBackend from solprop.constants import C @@ -291,10 +292,12 @@ def _single_bin(guide, grid, length, steps, index, **overrides): problem, initial=dataclasses.replace(problem.initial, field0=state) ) backend = NumpyRefBackend(problem, run_request, grid=grid) - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(length) - final = backend.observe().require_field()[:, 0, index].copy() - backend.close() + try: + final = final_field(backend, problem, bare(run_request), ended=True) + finally: + backend.close() + assert final_z(run_request) == length + final = final[:, 0, index].copy() return final / 1e-9, problem, run_request @@ -530,13 +533,20 @@ def _step_run(guide, steps, index, launch=None): problem, initial=dataclasses.replace(problem.initial, field0=state) ) backend = NumpyRefBackend(problem, run_request, grid=grid) - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(LENGTH) - final = backend.observe().require_field()[:, 0, index].copy() - backend.close() + try: + final = final_field(backend, problem, bare(run_request), ended=True) + finally: + backend.close() + assert final_z(run_request) == LENGTH + final = final[:, 0, index].copy() return final / 1e-9, problem, run_request +def final_z(run_request): + """Return the end of a run's itinerary, m: its last save plane.""" + return float(run_request.stepper.save_planes[-1]) + + def _dense_reference(provider, omega, *, basis=None, samples=33): """Return ``b(L)`` of the coupled-mode equations, solved independently by DOP853. @@ -750,10 +760,12 @@ def test_the_connection_is_stored_unconjugated_as_a_complex_basis_decides( wrong_problem = dataclasses.replace(problem) object.__setattr__(wrong_problem, "linear", linear) backend = NumpyRefBackend(wrong_problem, run_request, grid=grid) - backend.set_initial(wrong_problem.initial.field0, None) - backend.propagate_to(LENGTH) - wrong = backend.observe().require_field()[:, 0, index] / 1e-9 - backend.close() + try: + wrong = final_field(backend, wrong_problem, bare(run_request), ended=True) + finally: + backend.close() + assert final_z(run_request) == LENGTH + wrong = wrong[:, 0, index] / 1e-9 wrong_departure = float(np.max(abs(wrong[1:] / wrong[0] - expected))) record_property("tc801_conjugated_departure", wrong_departure) # Conjugating flips the sign of the imaginary couplings, so the channels they fill diff --git a/tests/driver/test_native_flow_pathological.py b/tests/driver/test_native_flow_pathological.py index dbb390cc5..503c1c4c4 100644 --- a/tests/driver/test_native_flow_pathological.py +++ b/tests/driver/test_native_flow_pathological.py @@ -30,7 +30,7 @@ import pytest import flow_parity -from builders import reference_trial +from builders import load_reference, reference_trial from flow_parity import QUIET, STEPS, UNIT, build, reference_formation_bound from native_flow_guards import check_flow_conditioning as check_native from sessions.runs import load_native, native_trial @@ -255,9 +255,8 @@ def capture(error, state, advanced, reference_mask, controller): patch.setattr(reference_passes, "error_norm", capture) reference = NumpyRefBackend(problem, run_request, grid=grid) try: - reference.set_initial(field, None) + expected_state = load_reference(reference, field).copy() reference_trial(reference, 0.0, dz) - expected_state = reference._require_state().copy() finally: reference.close() diff --git a/tests/driver/test_native_moving_guide.py b/tests/driver/test_native_moving_guide.py index 6764221ca..e93fadc9e 100644 --- a/tests/driver/test_native_moving_guide.py +++ b/tests/driver/test_native_moving_guide.py @@ -46,6 +46,7 @@ kinked_radius, moving_parity_bound, ) +from sessions.runs import bare, final_field from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.registry import available from solprop.driver import Simulation @@ -86,9 +87,10 @@ def frozen(z0, z1): # The reference's trial reads each stage's bundle through `stage_scalars`. backend.workspace.stage_scalars = frozen try: - backend.set_initial(case.problem.initial.field0, None) - backend.propagate_to(case.length) - actual = backend.observe().require_field().copy() + actual = final_field( + backend, case.problem, bare(case.run_request), ended=True + ).copy() + assert float(case.run_request.stepper.save_planes[-1]) == case.length finally: backend.close() assert float(np.max(np.abs(actual - expected))) > 100 * bound diff --git a/tests/driver/test_native_moving_guide_bound.py b/tests/driver/test_native_moving_guide_bound.py index eb9fd65f5..cf6208c9d 100644 --- a/tests/driver/test_native_moving_guide_bound.py +++ b/tests/driver/test_native_moving_guide_bound.py @@ -26,6 +26,7 @@ import pytest import flow_parity +from builders import load_reference from general_parity import conditioning, moving_count, source_bound from moving_guide_cases import ( BOUND_STEP_LENGTH, @@ -68,7 +69,7 @@ def source_at(implementation, problem, run_request, grid, positions): if implementation is NumpyRefBackend: backend = implementation(problem, run_request, grid=grid) try: - backend.set_initial(state, None) + load_reference(backend, state) return [np.array(backend.workspace.lab_source(state, z)) for z in positions] finally: backend.close() diff --git a/tests/driver/test_plane_adoption.py b/tests/driver/test_plane_adoption.py index 3d798d1a1..473e4c79e 100644 --- a/tests/driver/test_plane_adoption.py +++ b/tests/driver/test_plane_adoption.py @@ -25,10 +25,8 @@ from solprop import fourier from solprop.backends.events import ObservationReady from solprop.backends.export import ExportRecipe -from solprop.backends.host.driver import HostDriver from solprop.backends.host.session import HostSession from solprop.backends.protocol import BackendHistory, Observation -from solprop.backends.protocol import stepping as host_stepping from solprop.backends.registry import available, select from solprop.backends.session import Start from solprop.backends.sessions import start_session @@ -224,16 +222,16 @@ def _observation(field: np.ndarray) -> Observation: def _copied_observations(monkeypatch: pytest.MonkeyPatch) -> list[np.ndarray]: """Copy each observed field as its backend returned it, before any conversion.""" copies: list[np.ndarray] = [] - # The reference's driver observes for its session. - observe: Callable[..., Observation] = HostDriver.observe + # The reference's session observes its own state. + observe: Callable[..., Observation] = HostSession._observe - def copying(self: HostDriver, *, field: bool = True) -> Observation: + def copying(self: HostSession, *, field: bool) -> Observation: observation = observe(self, field=field) if observation.field is not None: copies.append(np.array(observation.field)) return observation - monkeypatch.setattr(HostDriver, "observe", copying) + monkeypatch.setattr(HostSession, "_observe", copying) # The native session observes its resident state: the identity export is that # state, copied, at each observation it reports. if importlib.util.find_spec("solprop_native") is not None: @@ -286,10 +284,10 @@ def test_a_stored_field_has_the_bits_of_the_conversion_in_two_steps( @pytest.mark.parametrize("case", ["modal", "single-mode"]) def test_a_borrowed_observed_field_is_detached(case): - """The session's export of its driver's own state is a new array, detached from it. + """The session's export of its own state is a new array, detached from it. - The reference session's own conversion of its driver's observation, the driver's - own state. The native session exports from its resident state instead + The reference session's own conversion of its observation, the workspace's state. + The native session exports from its resident state instead (``tests/sessions/test_destination_export.py``). """ backend = "numpy_ref" @@ -306,22 +304,23 @@ def test_a_borrowed_observed_field_is_detached(case): ) raws: list[np.ndarray] = [] seen: list[Observation] = [] - observe = host_stepping(stepping).observe + session = start_session( + stepping, + problem, + run_request, + Start(field=problem.initial.field0, z=float(problem.initial.z)), + ) + assert isinstance(session, HostSession) + observe = session._observe - def recorded(*, field: bool = True) -> Observation: + def recorded(*, field: bool) -> Observation: observation = observe(field=field) if observation.field is not None: raws.append(observation.field.copy()) seen.append(observation) return observation - stepping.observe = recorded # pyright: ignore[reportAttributeAccessIssue] - session = start_session( - stepping, - problem, - run_request, - Start(field=problem.initial.field0, z=float(problem.initial.z)), - ) + session._observe = recorded # pyright: ignore[reportAttributeAccessIssue] try: session.acknowledge(session.advance().receipt) # the launch plane while True: # past any bounded yield's progress batch diff --git a/tests/driver/test_plane_observer.py b/tests/driver/test_plane_observer.py index 81a865b98..130b2bcda 100644 --- a/tests/driver/test_plane_observer.py +++ b/tests/driver/test_plane_observer.py @@ -11,7 +11,7 @@ import pytest from legacy_geometry import LEGACY_GRID, bare_absorber -from solprop.backends.host.driver import HostDriver +from solprop.backends.host.session import HostSession from solprop.backends.registry import available from solprop.exceptions import DriverError, SolpropWarning from solprop.grid import EnvelopeGrid @@ -159,14 +159,14 @@ def test_a_stop_after_a_fetched_plane_checkpoints_the_field_fetched_once( """The observer and the failure checkpoint share one fetch (SEP 47 section 5.4).""" fetched = [] - # The reference's driver observes; the native backend's session exports. - def counted(self, *, field=True, observe=HostDriver.observe): + # The reference's session observes its state; the native session exports. + def counted(self, *, field, observe=HostSession._observe): observation = observe(self, field=field) if field: fetched.append(observation.z) return observation - monkeypatch.setattr(HostDriver, "observe", counted) + monkeypatch.setattr(HostSession, "_observe", counted) if backend == "native": # The native session fetches from its resident state: a fetch is a native # export, which the session counts. diff --git a/tests/driver/test_profile_dispersion.py b/tests/driver/test_profile_dispersion.py index e2b29b7ab..659633c19 100644 --- a/tests/driver/test_profile_dispersion.py +++ b/tests/driver/test_profile_dispersion.py @@ -38,6 +38,8 @@ import pytest from modal_provider_cases import GENERAL_CHI3, general_guide +from sessions.runs import bare +from sessions.runs import run as session_run from solprop.backends.numpy_ref import NumpyRefBackend from solprop.constants import C from solprop.driver import prop_gnlse @@ -161,12 +163,9 @@ def general_runs(strand): for name, one in problems.items(): owner = NumpyRefBackend(one, run_request, grid=grid) try: - owner.set_initial(one.initial.field0, None) - summary = owner.propagate_to(LENGTH) - runs[name] = ( - np.array(owner.observe().require_field()[0, 0]), - summary.n_steps, - ) + result = session_run(owner, one, bare(run_request)) + assert result.observations[-1].z == LENGTH + runs[name] = (np.array(result.fields[-1][0, 0]), result.status.attempts) finally: owner.close() return runs, launch, support, tables.synthesis, centre diff --git a/tests/driver/test_prop_capillary.py b/tests/driver/test_prop_capillary.py index 2a34a3db9..7c4d87d5d 100644 --- a/tests/driver/test_prop_capillary.py +++ b/tests/driver/test_prop_capillary.py @@ -41,6 +41,7 @@ from scipy.special import jn_zeros, jv from bounds import assert_within, record_backend +from builders import load_reference from convergence_records import Column, Study, record from convergence_studies import BACKEND_EQUIVALENCE from former_raman import FORMER_H2 @@ -801,8 +802,13 @@ def _peak_intensity(simulation): modes=simulation.modes, profiles=simulation.profiles, ) - backend.set_initial(problem.initial.field0, None) - return float(backend.stats(StatsSpec(names=("peak_intensity",)))["peak_intensity"]) + try: + load_reference(backend) + spec = StatsSpec(names=("peak_intensity",)) + stats = backend.workspace.stats(spec, float(problem.initial.z)) + finally: + backend.close() + return float(stats["peak_intensity"]) def test_the_field_range_is_not_derived_without_a_plasma(): diff --git a/tests/driver/test_restart_record.py b/tests/driver/test_restart_record.py index e7b7bf838..764cc65a0 100644 --- a/tests/driver/test_restart_record.py +++ b/tests/driver/test_restart_record.py @@ -25,8 +25,8 @@ from driver.test_abandoned_step import built as low_storage from driver.test_resume import run_until from driver.test_resume_history import AFRESH, soliton -from solprop.backends.host.driver import HostDriver from solprop.backends.host.session import HostSession +from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.session import SessionError from solprop.exceptions import SolpropWarning from solprop.output import ( @@ -170,7 +170,7 @@ def test_a_history_this_backend_cannot_install_is_recorded_as_incompatible( path = tmp_path / "run.h5" interrupted(build, path) monkeypatch.setattr( - HostDriver, "restore_march", lambda self, snapshot: "refused by the test" + HostSession, "_restore_march", lambda self, snapshot: "refused by the test" ) warned_once_and_reset( build, path, "refused by the test", "incompatible_representation" @@ -187,9 +187,11 @@ def test_a_resuming_march_that_cannot_carry_a_history_warns_once_and_resets( path = tmp_path / "run.h5" interrupted(build, path) assert restart(path)["retention"]["state"] == "retained" - monkeypatch.setattr( - HostDriver, "march_export_refusal", lambda self: "refused by the test" - ) + # The backend's answer and its session's, which the service loop reads. + for owner in (NumpyRefBackend, HostSession): + monkeypatch.setattr( + owner, "march_export_refusal", lambda self: "refused by the test" + ) caught = resumed(build, path) assert [str(one.message) for one in caught] == [f"{AFRESH}: refused by the test"] restoration = restart(path)["restoration"] @@ -385,10 +387,11 @@ def test_a_history_the_writing_engine_could_not_export_warns_once_on_resume( build = soliton(build_simulation, "numpy_ref") path = tmp_path / "run.h5" with monkeypatch.context() as patched: - patched.setattr(HostDriver, "march_snapshot_nbytes", lambda self, z: None) - patched.setattr( - HostDriver, "march_export_refusal", lambda self: "refused by the test" - ) + patched.setattr(HostSession, "march_snapshot_nbytes", lambda self: None) + for owner in (NumpyRefBackend, HostSession): + patched.setattr( + owner, "march_export_refusal", lambda self: "refused by the test" + ) interrupted(build, path) retention = restart(path)["retention"] assert (retention["state"], retention["reason"]) == ( diff --git a/tests/driver/test_resume.py b/tests/driver/test_resume.py index 0ba39dc6a..caad3c916 100644 --- a/tests/driver/test_resume.py +++ b/tests/driver/test_resume.py @@ -13,13 +13,14 @@ import numpy as np import pytest +from builders import load_reference from legacy_geometry import LEGACY_GRID, bare_absorber from march_bounds import FIXED_ORDER, assert_in_envelope, assert_matched, march_bound from sessions.executors import IDENTITY from sessions.runs import bare from solprop.backends.events import ObservationReady -from solprop.backends.host.driver import HostDriver -from solprop.backends.protocol import stepping +from solprop.backends.host.session import HostSession +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_session @@ -353,10 +354,9 @@ def test_the_input_draw_is_added_at_a_launch_and_not_to_a_resumed_state( modes=simulation.modes, profiles=simulation.profiles, ) - assert isinstance(engine, HostDriver) + assert isinstance(engine, NumpyRefBackend) try: - engine.set_initial(problem.initial.field0, None) - launched = engine.observe().require_field().copy() + launched = load_reference(engine).copy() # In band: the load masks the launch, whose pulse has tails outside it. active = problem.grids.active_mask np.testing.assert_allclose( @@ -367,8 +367,8 @@ def test_the_input_draw_is_added_at_a_launch_and_not_to_a_resumed_state( ) # The floor is the draw itself. assert cast("Any", engine).workspace.input_floor is draw - engine.set_initial(launched, None, z=0.0, resume=True) - np.testing.assert_array_equal(engine.observe().require_field(), launched) + load_reference(engine, launched, z=0.0, resume=True) + np.testing.assert_array_equal(engine.workspace.committed(), launched) assert cast("Any", engine).workspace.input_floor is draw finally: engine.close() @@ -539,7 +539,7 @@ def fail_first_march(self, **bounds): return advance(self, **bounds) with monkeypatch.context() as patch: - patch.setattr(HostDriver, "propagate_to", fail_before_first_step) + patch.setattr(HostSession, "_propagate", fail_before_first_step) if native is not None: advance = native.NativeSession.advance patch.setattr(native.NativeSession, "advance", fail_first_march) @@ -596,26 +596,37 @@ def test_resuming_with_no_file_starts_from_the_beginning(build_simulation, tmp_p assert read_file(path, "z").tolist() == [0.0, LENGTH / 2, LENGTH] -def test_set_initial_refuses_a_position_outside_the_table(build_simulation): +def _start_at(backend, problem, run_request, z): + """Start the reference's session from the launch field placed at `z`.""" + planes = run_request.observation.save_planes + start = Start( + field=problem.initial.field0, + z=z, + plane_index=int(np.searchsorted(planes, z, side="right")), + ) + return backend.prepare(problem, run_request).start(start, owns=False) + + +def test_a_session_refuses_a_start_outside_the_table(build_simulation): simulation = build_simulation(length=LENGTH, n_save=2) problem = simulation.translate() run_request = simulation._run_request() backend = select("numpy_ref", problem, run_request, grid=simulation.grid) with pytest.raises(BackendError, match="operator table"): - stepping(backend).set_initial(problem.initial.field0, None, z=2 * LENGTH) + _start_at(backend, problem, run_request, 2 * LENGTH) with pytest.raises(BackendError, match="operator table"): - stepping(backend).set_initial(problem.initial.field0, None, z=-LENGTH) + _start_at(backend, problem, run_request, -LENGTH) backend.close() -def test_set_initial_refuses_a_position_off_a_replayed_schedule(build_simulation): +def test_a_session_refuses_a_start_off_a_replayed_schedule(build_simulation): simulation = scheduled(build_simulation) problem = simulation.translate() run_request = simulation._run_request() backend = select("numpy_ref", problem, run_request, grid=simulation.grid) # Half a step past an edge: a replay could not continue in step from there. with pytest.raises(BackendError, match="one of its edges"): - stepping(backend).set_initial(problem.initial.field0, None, z=LENGTH / 80) + _start_at(backend, problem, run_request, LENGTH / 80) backend.close() @@ -625,11 +636,22 @@ def test_a_state_loaded_at_a_plane_starts_the_run_there(build_simulation): problem = simulation.translate() run_request = simulation._run_request() backend = select("numpy_ref", problem, run_request, grid=simulation.grid) - stepping(backend).set_initial(problem.initial.field0, None, z=LENGTH / 2) - assert stepping(backend).observe().z == LENGTH / 2 - summary = stepping(backend).propagate_to(LENGTH) + session = _start_at(backend, problem, run_request, LENGTH / 2) + assert session.status().z == LENGTH / 2 + ends = [] + while not session.finished: + batch = session.advance() + ends += [event.z for event in batch.events] + steps = sum( + 0 if event.history is None else event.history.n_steps + for event in batch.events + ) + ends.append(steps) + session.acknowledge(batch.receipt) + session.close() # Half the fibre at forty steps over the whole of it: twenty steps left. - assert summary.n_steps == 20 + assert ends[0] == LENGTH / 2 + assert sum(ends[1::2]) == 20 backend.close() diff --git a/tests/driver/test_resume_history.py b/tests/driver/test_resume_history.py index 84af6e7a4..8b8dc35ef 100644 --- a/tests/driver/test_resume_history.py +++ b/tests/driver/test_resume_history.py @@ -33,10 +33,12 @@ from flow_parity import build as flow_case from march_bounds import TIGHTER, assert_in_envelope from solprop.backends import available -from solprop.backends.host.driver import HostDriver +from solprop.backends.events import ObservationReady +from solprop.backends.host.session import HostSession from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.workspace import NumpyWorkspace from solprop.backends.registry import select +from solprop.backends.session import Start from solprop.exceptions import OutputError, SolpropWarning from solprop.log import NullReporter from solprop.output import HDF5Output @@ -271,8 +273,8 @@ def test_a_snapshot_over_the_default_size_is_never_copied( def refuse(*_): pytest.fail("a snapshot over the limit was taken") - # The reference's session takes its driver's; the native session its own. - monkeypatch.setattr(HostDriver, "march_snapshot", refuse) + # Each session takes its own. + monkeypatch.setattr(HostSession, "march_snapshot", refuse) if backend == "native": monkeypatch.setattr( "solprop_native.session.NativeSession.march_snapshot", refuse @@ -306,17 +308,54 @@ def test_a_snapshot_s_size_is_known_without_it(build_simulation, integrator): ), ) try: - engine.set_initial(problem.initial.field0, None, z=problem.initial.z) - assert engine.march_snapshot_nbytes(0.0) is None - engine.propagate_to(0.5 * LENGTH) - snapshot = engine.march_snapshot() + session = _started(engine, problem, run_request) + # No history at the launch. + assert session.march_snapshot_nbytes() is None + snapshot, nbytes = _first_plane_snapshot(session) assert snapshot is not None - assert engine.march_snapshot_nbytes(snapshot.z) == snapshot.nbytes - assert engine.march_snapshot_nbytes(0.5 * snapshot.z) is None + assert nbytes == snapshot.nbytes + session.close() finally: engine.close() +def _started(backend, problem, run_request, z=None, march=None): + """Start the reference's session at `z` (the launch by default), with `march`.""" + position = float(problem.initial.z) if z is None else float(z) + planes = run_request.observation.save_planes + start = Start( + field=problem.initial.field0, + z=position, + plane_index=int(np.searchsorted(planes, position, side="right")), + march=march, + ) + return backend.prepare(problem, run_request).start(start, owns=False) + + +def _first_plane_snapshot(session): + """Advance past the launch to the first plane; return its snapshot and size.""" + while True: + batch = session.advance() + event = batch.events[-1] + if isinstance(event, ObservationReady) and event.plane_index >= 0: + break + session.acknowledge(batch.receipt) + snapshot = session.march_snapshot(event.ticket) + nbytes = session.march_snapshot_nbytes() + session.acknowledge(batch.receipt) + return snapshot, nbytes + + +def _launch_snapshot(session): + """Return the method history at a session's launch plane, before any step.""" + batch = session.advance() + (event,) = batch.events + assert isinstance(event, ObservationReady) + snapshot = session.march_snapshot(event.ticket) + session.acknowledge(batch.receipt) + return snapshot + + @pytest.mark.medium def test_the_snapshot_is_rewritten_in_place(build_simulation, tmp_path): # HDF5 does not reclaim a deleted dataset's space: a snapshot recreated at every @@ -342,19 +381,22 @@ def test_a_snapshot_from_another_run_is_not_continued(build_simulation): run_request = simulation._run_request() backend = NumpyRefBackend(problem, run_request, grid=simulation.grid) try: - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(float(run_request.stepper.save_planes[0])) - snapshot = backend.march_snapshot() + session = _started(backend, problem, run_request) + snapshot, _ = _first_plane_snapshot(session) + session.close() assert snapshot is not None - backend.set_initial(problem.initial.field0, None) - assert "resumes at z = 0.0 m" in str(backend.restore_march(snapshot)) - backend.set_initial(problem.initial.field0, None, z=snapshot.z) - assert backend.restore_march(snapshot) is None + session = _started(backend, problem, run_request, march=snapshot) + assert "resumes at z = 0.0 m" in str(cast("Any", session).march_refusal) + session.close() + session = _started(backend, problem, run_request, snapshot.z, snapshot) + assert cast("Any", session).march_refusal is None + session.close() moved = snapshot.__class__( **{**vars(snapshot), "history_key": INTERACTION.history_key}, ) - backend.set_initial(problem.initial.field0, None, z=snapshot.z) - assert "history was kept by" in str(backend.restore_march(moved)) + session = _started(backend, problem, run_request, snapshot.z, moved) + assert "history was kept by" in str(cast("Any", session).march_refusal) + session.close() finally: backend.close() runge_kutta = build_simulation( @@ -363,8 +405,12 @@ def test_a_snapshot_from_another_run_is_not_continued(build_simulation): problem, run_request = runge_kutta.translate(), runge_kutta._run_request() backend = NumpyRefBackend(problem, run_request, grid=runge_kutta.grid) try: - assert backend.march_snapshot() is None - assert "Runge-Kutta" in str(backend.restore_march(snapshot)) + session = _started(backend, problem, run_request) + assert _launch_snapshot(session) is None + session.close() + session = _started(backend, problem, run_request, snapshot.z, snapshot) + assert "Runge-Kutta" in str(cast("Any", session).march_refusal) + session.close() finally: backend.close() @@ -571,17 +617,19 @@ def test_rows_another_history_keeps_are_refused_by_name(build_simulation): run_request = simulation._run_request() backend = NumpyRefBackend(problem, run_request, grid=simulation.grid) try: - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(float(run_request.stepper.save_planes[0])) - snapshot = backend.march_snapshot() + session = _started(backend, problem, run_request) + snapshot, _ = _first_plane_snapshot(session) + session.close() assert snapshot is not None rows = {**snapshot.rows, "states": snapshot.rows["store"]} - backend.set_initial(problem.initial.field0, None, z=snapshot.z) - reason = backend.restore_march(dataclasses.replace(snapshot, rows=rows)) - assert reason == ( + damaged = dataclasses.replace(snapshot, rows=rows) + session = _started(backend, problem, run_request, snapshot.z, damaged) + assert cast("Any", session).march_refusal == ( "the numpy_ref backend cannot continue this Adams history: its engine " "keeps no ['states'] rows" ) - assert backend.march_snapshot() is None + # Nothing of it was installed: the march starts afresh, with no history. + assert _launch_snapshot(session) is None + session.close() finally: backend.close() diff --git a/tests/driver/test_run.py b/tests/driver/test_run.py index af0319d2e..42c940e9a 100644 --- a/tests/driver/test_run.py +++ b/tests/driver/test_run.py @@ -5,7 +5,7 @@ """The outer loop: what it saves, what it reports and what it refuses.""" import logging -from typing import Any +from typing import Any, cast import h5py import numpy as np @@ -26,8 +26,6 @@ Backend, BackendHistory, Observation, - StepSummary, - stepping, ) from solprop.backends.registry import select from solprop.backends.session import Start @@ -164,57 +162,18 @@ 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 set_initial(self, field, noise, *, z=0.0, resume=False): - pass - - def set_progress(self, reporter): - self.reporter = reporter - - def set_stop(self, flag): - pass - def edge_memory(self, space): return 0 - def attach_monitor(self, monitor): - pass - - def march_snapshot(self): - return None - - def march_snapshot_nbytes(self, z): - return None - def march_export_refusal(self): return None - def restore_march(self, snapshot): - return None - def timing_probe(self, start): raise NotImplementedError - def propagate_to(self, z): - if self.failure is not None: - raise self.failure - return StepSummary(z, 1, 0, 0.5, 0.5, 0.0, True) - - def observe(self, *, field=True): - history = BackendHistory( - np.zeros(0), np.zeros(0), np.zeros(0), np.zeros(0, bool), np.zeros(0) - ) - state = np.zeros(self.shape, complex) if field else None - return Observation(0.0, state, None, history, 0, 0) - - def stats(self, spec): - return {} - def metadata(self) -> dict[str, object]: return {"backend": self.name, "propagator_mode": "tabulate"} - def restore_call_ledgers(self, logical, atomic=None): - pass - def memory_ledger(self): return {} @@ -239,12 +198,20 @@ def failing_backend(simulation, error): modes=simulation.modes, ) - def propagate_to(z): - raise error + built = cast("Any", backend).method + + def method(host): + # Each session's march, whose every advance raises. + made = built(host) + + def advance(target): + raise error + + made.march.advance = advance # pyright: ignore[reportAttributeAccessIssue] + return made - # A patched instance attribute: the reference's stepping seam fails each march. - stepped = stepping(backend) - stepped.propagate_to = propagate_to # pyright: ignore[reportAttributeAccessIssue] + # A patched instance attribute: every run the backend serves fails its march. + backend.method = method # pyright: ignore[reportAttributeAccessIssue] return backend @@ -693,9 +660,9 @@ def interrupted(self, z, error): metadata=simulation.metadata(), progress=events, ) - # The failing march never calls `started` (a real march does), so the - # interruption is the only event, and it names the last plane reached: none. - assert events.calls == [("interrupted", 0.0, "RuntimeError")] + # The session announces the run before its first march, which fails: the + # interruption follows, naming the last plane reached: none. + assert events.calls == ["started", ("interrupted", 0.0, "RuntimeError")] def testhistory_of_stores_start_positions_and_per_attempt_times(): diff --git a/tests/driver/test_runner.py b/tests/driver/test_runner.py index 1129f91c8..055e8d6e4 100644 --- a/tests/driver/test_runner.py +++ b/tests/driver/test_runner.py @@ -16,7 +16,7 @@ import threading import types import weakref -from typing import cast +from typing import Any, cast import numpy as np import pytest @@ -26,9 +26,9 @@ from runtime_types import unchecked from sessions.executors import one_thread from solprop.backends import sessions -from solprop.backends.host.driver import HostDriver -from solprop.backends.protocol import stepping +from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.registry import available, select +from solprop.backends.session import Start from solprop.boundaries import absorber from solprop.driver import Simulation, SimulationRunner from solprop.driver.runner import check_derived_problem @@ -142,22 +142,32 @@ def plane(self, z, summary) -> None: def restored(backend, problem, run_request) -> tuple: - """Return the four pieces of state a load restores (SEP 22 section 4.7). + """Return the four pieces of state a session's load restores (SEP 22 section 4.7). - The quadrature alarm as the entrance plane reads it, ``quadrature_error`` before - any march: in-tree backends keep it on the host, Kokkos in its native state. + A session started on the reference: whether a dense observation holds its state, + the quadrature alarm as the entrance plane reads it (``quadrature_error`` before + any march), and its Adams march's ledger and last rejection. """ - march = backend._adams - spec = dataclasses.replace( - run_request.observation.stats, names=("quadrature_error",) - ) - entrance = float(backend.stats(spec)["quadrature_error"]) - return ( - backend._march._ahead is None, - "nan" if np.isnan(entrance) else entrance, - None if march is None else dataclasses.asdict(march.ledger), - None if march is None else march._last_rejected, + session = backend.prepare(problem, run_request).start( + Start.entrance(problem), owns=False ) + try: + march = backend.march + ledger = getattr(march, "ledger", None) + spec = dataclasses.replace( + run_request.observation.stats, names=("quadrature_error",) + ) + entrance = float( + backend.workspace.stats(spec, float(problem.initial.z))["quadrature_error"] + ) + return ( + not session._observed, + "nan" if np.isnan(entrance) else entrance, + None if ledger is None else dataclasses.asdict(ledger), + None if ledger is None else march._last_rejected, + ) + finally: + session.close() @pytest.mark.medium @@ -235,8 +245,9 @@ def _failed_runner_case(backend: str, dense: bool) -> Simulation: @pytest.mark.medium @DENSE def test_a_load_restores_what_a_failed_run_left_as_a_fresh_backend_holds(dense): - # The reference's driver keeps a run's march state on the backend itself; the - # native session keeps it in the session, which the next test checks by its runs. + # The reference's session builds its march afresh over the backend's workspace, + # which the failed run left behind; the native session keeps its state in the + # session, which the next test checks by its runs. backend = "numpy_ref" simulation = _failed_runner_case(backend, dense) problem = simulation.translate() @@ -244,16 +255,13 @@ def test_a_load_restores_what_a_failed_run_left_as_a_fresh_backend_holds(dense): with simulation.runner() as runner: with pytest.raises(RuntimeError, match="on purpose"): runner.run(inputs(simulation)[0], progress=_Stop()) - left = cast("HostDriver", runner.backend) - if dense: - # The failed run held the march ahead of its interpolated plane. - assert left._march.holding - else: - assert left._adams is not None - assert left._adams.ledger.total > 0 + left = cast("NumpyRefBackend", runner.backend) + if not dense: + # The failed run's march, which the next session does not inherit. + failed = cast("Any", left.march) + assert failed.ledger.total > 0 # A failed run can stop just after a rejection; the load clears it. - left._adams._last_rejected = True - left.set_initial(problem.initial.field0, None, z=problem.initial.z) + failed._last_rejected = True fresh = select( backend, problem, @@ -263,9 +271,6 @@ def test_a_load_restores_what_a_failed_run_left_as_a_fresh_backend_holds(dense): profiles=simulation.profiles, ) try: - stepping(fresh).set_initial( - problem.initial.field0, None, z=problem.initial.z - ) # Restored state is exact: the same flags, alarm and integer ledger. assert restored(left, problem, run_request) == restored( fresh, problem, run_request @@ -548,27 +553,29 @@ def no_collector(): gc.enable() -def _load_name(backend) -> str: - """Return the backend's load: the native session's ``_load``, the host's - ``set_initial``; both take the field, the noise, ``z`` and ``resume``.""" - return "_load" if hasattr(backend, "_load") else "set_initial" +def _load_owner(backend) -> tuple[object, str]: + """Return the backend's load: the native backend's ``_load``, the reference's + workspace's ``load``; both take the field, the noise, ``z`` and ``resume``.""" + if hasattr(backend, "_load"): + return backend, "_load" + return backend.workspace, "load" def _spied_load(backend, monkeypatch) -> list[weakref.ref[np.ndarray]]: """Return a list that keeps a weak reference to each array the backend loads. - The reference loads through its driver's ``set_initial``, the native backend + The reference's session loads through its workspace's ``load``, the native backend through its own ``_load`` (SEP 47 phase 5). """ loads: list[weakref.ref[np.ndarray]] = [] - name = _load_name(backend) - load = getattr(backend, name) + owner, name = _load_owner(backend) + load = getattr(owner, name) def spy(field, noise, *, z=0.0, resume=False) -> object: loads.append(weakref.ref(field)) return load(field, noise, z=z, resume=resume) - monkeypatch.setattr(backend, name, spy) + monkeypatch.setattr(owner, name, spy) return loads @@ -614,15 +621,15 @@ def test_a_runner_reads_a_digested_input_without_a_copy(backend, monkeypatch): field = 0.9 * simulation._field0 before = field.copy() with simulation.runner() as runner: - name = _load_name(runner.backend) - load = getattr(runner.backend, name) + owner, name = _load_owner(runner.backend) + load = getattr(owner, name) shared: list[bool] = [] def spy(given, noise, *, z=0.0, resume=False) -> object: shared.append(np.shares_memory(given, field)) return load(given, noise, z=z, resume=resume) - monkeypatch.setattr(runner.backend, name, spy) + monkeypatch.setattr(owner, name, spy) output = stored(runner.run(field, progress="none")) fresh = stored(simulation.with_input(field).run(progress="none")) assert shared == [True] diff --git a/tests/driver/test_scan_worker_validation.py b/tests/driver/test_scan_worker_validation.py index 053a049c3..aadf6ae00 100644 --- a/tests/driver/test_scan_worker_validation.py +++ b/tests/driver/test_scan_worker_validation.py @@ -14,7 +14,7 @@ import pytest from builders import fixed_fibre_point as build -from solprop.backends.numpy_ref.backend import NumpyRefBackend +from solprop.backends.numpy_ref.workspace import NumpyWorkspace from solprop.backends.registry import select from solprop.driver import Simulation, _scan_run from solprop.driver._scan_run import ( @@ -263,10 +263,10 @@ def test_a_probe_whose_launch_fails_raises_the_launch_s_own_error(point, monkeyp simulation = build(point) problem = simulation.translate() - def broken(self, spec): + def broken(self, spec, z): raise OutputError("manufactured launch statistics failure") - monkeypatch.setattr(NumpyRefBackend, "stats", broken) + monkeypatch.setattr(NumpyWorkspace, "stats", broken) backend = select( "numpy_ref", problem, diff --git a/tests/driver/test_sep12_sep14_integration.py b/tests/driver/test_sep12_sep14_integration.py index feaff90f7..176639e74 100644 --- a/tests/driver/test_sep12_sep14_integration.py +++ b/tests/driver/test_sep12_sep14_integration.py @@ -11,8 +11,13 @@ import pytest from numpy.testing import assert_allclose, assert_array_equal +from sessions.runs import IDENTITY, bare +from solprop.backends.events import ObservationReady, Terminal +from solprop.backends.host.adams import HostAdamsMarch from solprop.backends.ledger import CallLedger from solprop.backends.numpy_ref import NumpyRefBackend +from solprop.backends.numpy_ref.workspace import NumpyWorkspace +from solprop.backends.session import Start from solprop.driver import Simulation from solprop.driver import tdse as runtime_module from solprop.exceptions import ( @@ -175,26 +180,37 @@ def test_fused_predictor_failure_charges_both_ledgers_before_invocation(formulat problem, run_request, grid=simulation.grid, tdse_binding=binding ) try: - backend.set_initial(problem.initial.field0, None, z=problem.initial.z) - initial = backend.observe() - assert backend._adams is not None + session = backend.prepare(problem, bare(run_request)).start( + Start.entrance(problem), owns=False + ) + launch = session.advance() + (opened,) = launch.events + assert isinstance(opened, ObservationReady) + initial = session.export(opened.ticket, IDENTITY) + session.acknowledge(launch.receipt) + march = cast("Any", backend.march) + assert isinstance(march, HostAdamsMarch) # The interaction formulation's fused path, or the exponential one's own. - assert (cast("Any", backend._adams._engine)._exponential is None) is ( + assert (cast("Any", march._engine)._exponential is None) is ( formulation == "interaction" ) - with pytest.raises(BackendError, match="predictor chunk failure"): - backend.propagate_to(simulation.grid.length) - actual = backend.observe() + terminal = session.advance().terminal + assert isinstance(terminal, Terminal) + assert isinstance(terminal.error, BackendError) + assert "predictor chunk failure" in str(terminal.error) + assert terminal.ticket is not None + actual = session.export(terminal.ticket, IDENTITY) + session.close() assert binding.purposes == ["startup", "predictor"] assert binding.ledger.logical_evaluations == 2 assert binding.ledger.attempted == 3 assert binding.ledger.failed_calls == 1 assert binding.ledger.reserved == 0 - calls = backend._adams.ledger + calls = march.ledger assert (calls.startup, calls.predictor, calls.corrected) == (1, 1, 0) assert calls.accepted_steps == calls.rejected_steps == 0 - assert actual.z == initial.z == simulation.initial_z - assert_array_equal(actual.field, initial.field) + assert terminal.z == opened.z == simulation.initial_z + assert_array_equal(actual, initial) finally: backend.close() binding.close() @@ -311,16 +327,17 @@ def test_dense_observation_failure_records_actual_checkpoint_landing( monkeypatch, step_planes ): simulation = _dense_simulation(step_planes=step_planes) - original = NumpyRefBackend.stats + original = NumpyWorkspace.stats observed = [] - def fail_second(self, spec): - observed.append(self._z) + # The session evaluates each observation's statistics on its workspace. + def fail_second(self, spec, z): + observed.append(z) if len(observed) == 2: raise DriverError("manufactured observation statistics failure") - return original(self, spec) + return original(self, spec, z) - monkeypatch.setattr(NumpyRefBackend, "stats", fail_second) + monkeypatch.setattr(NumpyWorkspace, "stats", fail_second) output = MemoryOutput() with pytest.raises(DriverError, match="observation statistics failure"): simulation.run(output, progress="none") diff --git a/tests/driver/test_snapshots.py b/tests/driver/test_snapshots.py index 6875ac72a..ebf3cf648 100644 --- a/tests/driver/test_snapshots.py +++ b/tests/driver/test_snapshots.py @@ -122,7 +122,8 @@ def watched(*args): identities.append( ( id(backend), - id(backend._adams), + # The reference's session's march (its latest), native's own record. + id(backend.march if backend.name == "numpy_ref" else backend._adams), id(getattr(backend, "workspace", backend)._tdse_binding), # The model and its plans live behind the provider's worker (SEP 49): # the same worker, the same view of the model and the same plans. diff --git a/tests/driver/test_solid_multimode.py b/tests/driver/test_solid_multimode.py index 9ee25a986..620994133 100644 --- a/tests/driver/test_solid_multimode.py +++ b/tests/driver/test_solid_multimode.py @@ -43,7 +43,7 @@ GRIN_RADIUS, make_provider, ) -from sessions.runs import final_field +from sessions.runs import bare, final_field from solprop.backends import select from solprop.backends.numpy_ref import NumpyRefBackend from solprop.constants import EPS0 @@ -621,9 +621,7 @@ def grin_exit_energies(elements, trange, steps): ) owner = NumpyRefBackend(problem, run_request, grid=grid) try: - owner.set_initial(problem.initial.field0, None) - owner.propagate_to(GRIN_LENGTH) - final = owner.observe().require_field() + final = final_field(owner, problem, bare(run_request), ended=True) finally: owner.close() return energy(grid, final)[:, 0] diff --git a/tests/driver/test_stated_input.py b/tests/driver/test_stated_input.py index 26d164fe3..46be01e4d 100644 --- a/tests/driver/test_stated_input.py +++ b/tests/driver/test_stated_input.py @@ -10,13 +10,13 @@ """ import dataclasses +from typing import Any, cast import numpy as np import pytest from driver.test_field_free_planes import cartesian from driver.test_runner import capillary, inputs, stored -from solprop.backends.protocol import stepping from solprop.driver import Simulation from solprop.driver.executors import Local from solprop.driver.scan import Scan, run_scan @@ -136,14 +136,16 @@ def test_a_runner_reads_a_small_stated_input_without_a_copy(monkeypatch): simulation = cartesian("numpy_ref") field = 0.9 * simulation._field0 with simulation.runner() as runner: - load = stepping(runner.backend).set_initial + # The reference's session loads its workspace. + workspace = cast("Any", runner.backend).workspace + load = workspace.load shared: list[bool] = [] def spy(given, noise, *, z=0.0, resume=False) -> None: shared.append(np.shares_memory(given, field)) load(given, noise, z=z, resume=resume) - monkeypatch.setattr(runner.backend, "set_initial", spy) + monkeypatch.setattr(workspace, "load", spy) runner.run(field, input_identity="a", progress="none") assert shared == [True] diff --git a/tests/driver/test_tdse_gated_derivative_run.py b/tests/driver/test_tdse_gated_derivative_run.py index 5c1c911e3..865880c29 100644 --- a/tests/driver/test_tdse_gated_derivative_run.py +++ b/tests/driver/test_tdse_gated_derivative_run.py @@ -23,6 +23,9 @@ from tests.edge_source_cases import ManufacturedBinding, case_from_problem, evaluate from tests.hacc_cases import alpha_law, hacc_response, install, plain, preset_basis +from sessions.runs import bare, to_planes +from sessions.runs import run as session_run +from solprop.backends.events import ObservationReady from solprop.backends.numpy_ref import NumpyRefBackend from solprop.driver import Simulation from solprop.driver import tdse as runtime_module @@ -227,21 +230,26 @@ def test_the_fake_drift_keeps_its_rise_and_reports_its_edge_ratio(bindings): def test_the_edge_entry_is_the_last_evaluation_and_keeps_no_history(bindings): simulation = _sae(TDSEAtomicWindow(40e-15, 5e-15)) problem = simulation.translate() - run_request = simulation._run_request() + # Two planes, each a session's observation, read between the session's batches. + run_request = to_planes(bare(simulation._run_request()), [2 * _STEP, 4 * _STEP]) assert tdse_descriptor(problem.route) is not None binding = ManufacturedBinding(tdse_descriptor(problem.route), 1000, _drift) backend = NumpyRefBackend( problem, run_request, grid=simulation.grid, tdse_binding=binding ) + records = [] + + def between(_, batch): + for event in batch.events: + if isinstance(event, ObservationReady) and event.plane_index >= 0: + records.append(plain(backend.metadata()["tdse_last_evaluation"])) + binding.law = lambda times: 3 * _drift(times) + try: - backend.set_initial(problem.initial.field0, None, z=problem.initial.z) - backend.propagate_to(2 * _STEP) - first = plain(backend.metadata()["tdse_last_evaluation"]) - binding.law = lambda times: 3 * _drift(times) - backend.propagate_to(4 * _STEP) - second = plain(backend.metadata()["tdse_last_evaluation"]) + session_run(backend, problem, between=between) finally: backend.close() + first, second = records before = first["projection"]["edge"]["bands"]["active"] after = second["projection"]["edge"]["bands"]["active"] # A linear map of a remainder three times larger: three times the norms, to the diff --git a/tests/driver/test_tdse_input_noise.py b/tests/driver/test_tdse_input_noise.py index 89c8f62ec..b96c6a81b 100644 --- a/tests/driver/test_tdse_input_noise.py +++ b/tests/driver/test_tdse_input_noise.py @@ -20,7 +20,10 @@ import pytest from tests.driver.test_sep12_sep14_integration import _Binding +from sessions.runs import bare, to_planes +from sessions.runs import run as session_run from solprop.backends.numpy_ref import NumpyRefBackend +from solprop.backends.session import Start from solprop.constants import EPS0, C from solprop.driver import Simulation from solprop.exceptions import DriverError, TranslationError @@ -108,7 +111,8 @@ def _atomic(noise: str | None) -> Simulation: def _first_drive(simulation: Simulation, *, pulse: bool = True) -> np.ndarray: """Return the real field the atom is driven by at its first evaluation.""" problem = simulation.translate() - run_request = simulation._run_request() + # One plane at the first step's end: the first evaluation is the session's startup. + run_request = to_planes(bare(simulation._run_request()), [_STEP]) assert tdse_descriptor(problem.route) is not None binding = _Binding(tdse_descriptor(problem.route), 20) backend = NumpyRefBackend( @@ -116,8 +120,7 @@ def _first_drive(simulation: Simulation, *, pulse: bool = True) -> np.ndarray: ) try: launch = problem.initial.field0 if pulse else np.zeros(problem.shape, complex) - backend.set_initial(launch, None, z=0.0) - backend.propagate_to(_STEP) + session_run(backend, problem, start=Start(field=launch, z=0.0)) finally: backend.close() binding.close() diff --git a/tests/driver/test_wall_production.py b/tests/driver/test_wall_production.py index db80736e0..95ac8e205 100644 --- a/tests/driver/test_wall_production.py +++ b/tests/driver/test_wall_production.py @@ -20,6 +20,7 @@ import pytest from legacy_geometry import LEGACY_GRID +from sessions.runs import bare, final_field from solprop.backends.numpy_ref import NumpyRefBackend from solprop.boundaries import absorber from solprop.constants import C @@ -92,10 +93,12 @@ def pinned_final(): problem, initial=replace(problem.initial, field0=state, noise0=None) ) driver = NumpyRefBackend(problem, run_request, grid=grid) - driver.set_initial(problem.initial.field0, None) - driver.propagate_to(length) - final = np.conj(driver.observe().require_field()[:, 0, index]) / AMPLITUDE - driver.close() + try: + reached = final_field(driver, problem, bare(run_request), ended=True) + finally: + driver.close() + assert float(run_request.stepper.save_planes[-1]) == length + final = np.conj(reached[:, 0, index]) / AMPLITUDE flow = problem.linear.coupled_flow assert flow is not None assert flow.generator is not None diff --git a/tests/modes/test_field_scale.py b/tests/modes/test_field_scale.py index 243bf64f4..fb513624d 100644 --- a/tests/modes/test_field_scale.py +++ b/tests/modes/test_field_scale.py @@ -25,6 +25,7 @@ from scipy.special import j0, j1, jn_zeros from rate_oracles import adk_oracle +from sessions.runs import bare, final_field from solprop.backends.numpy_ref import NumpyRefBackend from solprop.exceptions import MaterialRangeWarning, ModeError from solprop.grid import FieldGrid @@ -302,9 +303,7 @@ def run(grid, modes, responses, energy, **options): **options, ) with closing(NumpyRefBackend(problem, run_request, grid=grid)) as backend: - backend.set_initial(problem.initial.field0, None) - backend.propagate_to(LENGTH) - return backend.observe().require_field(), problem + return final_field(backend, problem, bare(run_request), z=LENGTH), problem def peak_gap(got, want): diff --git a/tests/parity_ladder.py b/tests/parity_ladder.py index c38bceffb..e7bf90538 100644 --- a/tests/parity_ladder.py +++ b/tests/parity_ladder.py @@ -26,7 +26,7 @@ import numpy as np from bounds import departure -from builders import launch_derivative +from builders import launch_derivative, load_reference from sessions.runs import launch_statistics, native_source, saved, to_planes from sessions.runs import run as session_run from sessions.runs import summary as run_summary @@ -278,7 +278,7 @@ def source(backend_class: type, built: Built, *, z: float = 0.0) -> np.ndarray: try: if backend.name == "native": return native_source(backend, launch, z) - backend.set_initial(launch, None) + load_reference(backend, launch) return np.array(backend.workspace.lab_source(launch, z)) finally: backend.close() @@ -344,7 +344,7 @@ def projected(backend_class: type, built: Built) -> list[np.ndarray | None]: forward = np.fft.rfft if problem.grid_kind == "field" else np.fft.fft # The launch native loads (:func:`masked_launch`). launch = masked_launch(problem) - backend.set_initial(launch, None) + load_reference(backend, launch) backend.workspace.lab_source(launch, 0.0) coarse = backend.workspace._last_coarse return [ diff --git a/tests/sessions/test_native_load.py b/tests/sessions/test_native_load.py index ac54df1ff..851eb9a02 100644 --- a/tests/sessions/test_native_load.py +++ b/tests/sessions/test_native_load.py @@ -7,8 +7,8 @@ The native backend loads a start (``solprop_native._load``), restores a resumed Adams history into its own record (``_NativeAdamsMarch``, no longer an ``AdamsMarch``) and times single trials (``solprop_native._probe``) without solprop's legacy step driver. -These are held to what the reference does with the same inputs: its load -(``HostDriver.set_initial``), its refusals and its probe's trial. +These are held to what the reference does with the same inputs: its workspace's load +(``NumpyWorkspace.load``, which its session calls), its refusals and its probe's trial. """ from typing import Any, cast @@ -55,8 +55,8 @@ def test_an_input_draw_is_added_at_the_launch_alone(): kept = native._load(field, None, z=z, resume=False) assert kept.field.size == 0 assert np.array_equal(kept.floor, loaded.floor) - reference.set_initial(field, None, z=float(problem.initial.z)) host = cast("Any", reference) + host.workspace.load(field, None, z=float(problem.initial.z), resume=False) assert loaded.floor is not None and loaded.noise is None assert np.array_equal(loaded.floor, host.workspace.input_floor) expected = np.asarray(field) + loaded.floor diff --git a/tests/sessions/test_native_session_axis_plasma.py b/tests/sessions/test_native_session_axis_plasma.py index bc0b93c5c..be887b714 100644 --- a/tests/sessions/test_native_session_axis_plasma.py +++ b/tests/sessions/test_native_session_axis_plasma.py @@ -23,11 +23,13 @@ import math import warnings from contextlib import closing +from typing import Any, cast import numpy as np import pytest from axis_plasma_cases import entrance_problem +from builders import load_reference from rate_oracles import adk_oracle from sessions.executors import ( EXECUTORS, @@ -37,7 +39,6 @@ from sessions.runs import load_native from solprop.backends.events import ObservationReady, Terminal from solprop.backends.export import ExportRecipe -from solprop.backends.protocol import stepping from solprop.backends.registry import select from solprop.exceptions import BackendError, MaterialRangeWarning from solprop.grid import FieldGrid @@ -173,10 +174,10 @@ def _reference(grid, modes, problem, request, names, seen): out = [] with closing(select("numpy_ref", problem, run, grid=grid, modes=modes)) as backend: for record in seen: - stepping(backend).set_initial( - record.field, None, z=record.z, resume=record.z > start + load_reference(backend, record.field, z=record.z, resume=record.z > start) + values = cast("Any", backend).workspace.stats( + run.observation.stats, record.z ) - values = stepping(backend).stats(run.observation.stats) out.append({name: np.asarray(value) for name, value in values.items()}) return out diff --git a/tests/sessions/test_native_session_history.py b/tests/sessions/test_native_session_history.py index b0e2420de..8f71cd202 100644 --- a/tests/sessions/test_native_session_history.py +++ b/tests/sessions/test_native_session_history.py @@ -401,8 +401,7 @@ def test_the_ledger_record_is_the_reference_s(): request = run_request started = _reference_session(problem, request) drive(started) - driver = started.session.driver # pyright: ignore[reportAttributeAccessIssue] - expected = driver.metadata()["response_calls"] + expected = started.session.execution_record()["response_calls"] started.session.close() session = _native(problem, request, _entrance(problem)) drive(Started(session)) diff --git a/tests/sessions/test_native_session_low_storage.py b/tests/sessions/test_native_session_low_storage.py index 00234966d..583418483 100644 --- a/tests/sessions/test_native_session_low_storage.py +++ b/tests/sessions/test_native_session_low_storage.py @@ -37,7 +37,7 @@ window, ) from solprop.backends.events import Eligibility, Outcome -from solprop.backends.host.driver import HostDriver +from solprop.backends.host.low_storage import HostLowStorageMarch from solprop.backends.host.session import HostSession from solprop.backends.registry import select from solprop.exceptions import ConvergenceError @@ -198,10 +198,17 @@ def _reference( "numpy_ref", problem, run_request, grid=window(), modes=[fibre().mode] ) if failing is not None: - march = cast("HostDriver[Any]", driver)._low_storage - assert march is not None - engine = cast("Any", march.engine) - engine.trial = _FailingStep(engine.trial, failing) + built = cast("Any", driver).method + + def method(host): + # The session's own low-storage march, its engine's trial failing. + made = built(host) + assert isinstance(made.march, HostLowStorageMarch) + engine = cast("Any", made.march.engine) + engine.trial = _FailingStep(engine.trial, failing) + return made + + cast("Any", driver).method = method return HostSession(driver, problem, run_request, entrance(problem)) diff --git a/tests/sessions/test_native_session_statistics.py b/tests/sessions/test_native_session_statistics.py index da815e221..29ad95c1e 100644 --- a/tests/sessions/test_native_session_statistics.py +++ b/tests/sessions/test_native_session_statistics.py @@ -24,11 +24,13 @@ import functools import math import re +from typing import Any, cast import numpy as np import pytest from bounds import INTEGRATION_AGREEMENT, gamma +from builders import load_reference from sessions.executors import ( PLANES, device_build, @@ -40,7 +42,6 @@ from sessions.runs import load_native from solprop.backends.events import ObservationReady, Terminal from solprop.backends.export import ExportRecipe -from solprop.backends.protocol import stepping from solprop.backends.registry import select from solprop.exceptions import BackendError, SolpropError, TranslationError from solprop.stats import ( @@ -186,10 +187,8 @@ def _reference(problem, run_request, spec, seen, *, grid, modes=None, profiles=N out = [] try: for record in seen: - stepping(backend).set_initial( - record.field, None, z=record.z, resume=record.z > start - ) - values = stepping(backend).stats(spec) + load_reference(backend, record.field, z=record.z, resume=record.z > start) + values = cast("Any", backend).workspace.stats(spec, record.z) out.append({name: np.asarray(value) for name, value in values.items()}) finally: backend.close() @@ -951,8 +950,10 @@ def test_a_negative_lobe_s_widths_are_refused_by_the_session_as_by_the_reference with pytest.raises(BackendError, match="nonnegative fluence profile") as want: reference = select("numpy_ref", problem, run_request, grid=grid) try: - stepping(reference).set_initial(field, None) - stepping(reference).stats(StatsSpec(names=("beam_radius",))) + load_reference(reference, field) + cast("Any", reference).workspace.stats( + StatsSpec(names=("beam_radius",)), float(problem.initial.z) + ) finally: reference.close() session = native_session.NativeSession( @@ -1036,10 +1037,8 @@ def test_a_varying_metric_s_statistics_are_refused_by_native_before_allocation() inside = float(run_request.stepper.save_planes[-1]) / 8 reference = select("numpy_ref", problem, request, grid=grid) try: - stepping(reference).set_initial( - problem.initial.field0, None, z=inside, resume=True - ) - values = stepping(reference).stats(spec) + load_reference(reference, z=inside, resume=True) + values = cast("Any", reference).workspace.stats(spec, inside) finally: reference.close() assert set(values) == set(GENERAL) diff --git a/tests/sessions/test_split_collar_rules.py b/tests/sessions/test_split_collar_rules.py index 7c90a10a3..fd7d8a4e9 100644 --- a/tests/sessions/test_split_collar_rules.py +++ b/tests/sessions/test_split_collar_rules.py @@ -7,11 +7,11 @@ Under ``absorber_scheme="split_step"`` each accepted step's finish reduces the field after its first band mask and before the split: what the split takes, and the power it finds halfway through its factor, which the guards are judged on (SEP 52 section 4, -``BoundaryMonitor.split_sums``). Today the reference keeps those sums on its driver -(``_finish`` into ``_split_removed`` and ``_split_found``, drained by -``_boundary_energies``, reset by ``_bind_monitor``) and native in its state and session. -SEP 52 phase 3 moves their ownership into the session; these tests hold the rules it -must keep, through sessions on both backends, before anything moves: +``BoundaryMonitor.split_sums``). The workspace's finish takes them into each step's +``AcceptRecord``, and the reference's session accumulates them (``HostSession.absorb`` +into ``_split_removed`` and ``_split_found``, drained by ``_energies``, reset by +``_bind_monitor``), as native's state and session do. These tests hold the rules, +through sessions on both backends: - the removal adds over every accepted step since the previous reading, and the next boundary reading drains it; diff --git a/tests/test_helpers.py b/tests/test_helpers.py index 7cd8227c3..5d9632738 100644 --- a/tests/test_helpers.py +++ b/tests/test_helpers.py @@ -19,7 +19,6 @@ from bounds import EPS, assert_within, gamma from solprop._helpers import PLAIN, Helpers -from solprop.backends.host.driver import HostDriver from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.multistep import trial_tables from solprop.stepper.multistep import integrated_weights, lagrange_coefficients @@ -149,7 +148,7 @@ def refuse(*_): for record in records(): for name in ("points", "basis"): monkeypatch.setitem(record.__dict__, name, refuse) - assert HostDriver.helpers is PLAIN + assert NumpyRefBackend.helpers is PLAIN assert integrated_weights([1.0, 0.0]).tolist() == [0.5, 0.5] assert lagrange_coefficients([1.0, 0.0]).shape == (2, 2) table = build(np.sin, 0.0, 1.0, tol=1e-8) diff --git a/tests/test_split_crossing.py b/tests/test_split_crossing.py index 64f0c604f..f7c8bb976 100644 --- a/tests/test_split_crossing.py +++ b/tests/test_split_crossing.py @@ -18,14 +18,20 @@ import dataclasses import logging import math +from typing import Any, cast import numpy as np import pytest import solprop.translate.assembly as assembly_module -from monitor_cases import as_driver -from solprop.backends.protocol import stepping +from builders import load_reference +from monitor_cases import as_reference, reading +from sessions.runs import run as session_run +from sessions.runs import to_planes +from solprop.backends.events import ObservationReady from solprop.backends.registry import available, select +from solprop.backends.session import Start +from solprop.backends.sessions import start_session from solprop.boundaries import ( SPLIT_CROSSING, SPLIT_RATE_BUCKETS, @@ -299,19 +305,30 @@ def test_the_cap_tightens_as_the_beam_self_focuses() -> None: run_request = simulation._run_request() crossing = problem.split_crossing assert crossing is not None - backend = select("numpy_ref", problem, run_request, grid=simulation.grid) + planes = [float(z) for z in np.linspace(0.005, 0.05, 10)] + request = to_planes(run_request, planes) + backend = select("numpy_ref", problem, request, grid=simulation.grid) try: - driver = as_driver(backend) - driver.set_initial(problem.initial.field0, None) + # The launch's reading gives the launch's limit, as an attached monitor reads. + load_reference(backend) + launched = simulation._boundary_monitor() + assert launched is not None + launched.crossing = crossing + as_reference(backend).workspace.bind_monitor(launched) + launched.launch(reading(backend), float(problem.initial.z)) + assert launched.step_cap == crossing.launch_limit monitor = simulation._boundary_monitor() assert monitor is not None - driver.attach_monitor(monitor) - assert monitor.step_cap == crossing.launch_limit - tightest = monitor.step_cap - for z in np.linspace(0.005, 0.05, 10): - stepping(backend).propagate_to(float(z)) - tightest = min(tightest, monitor.step_cap) - assert tightest < 0.7 * crossing.launch_limit + caps: list[float] = [] + + def keep(session: object, batch: object) -> None: + for event in batch.events: # pyright: ignore[reportAttributeAccessIssue] + if isinstance(event, ObservationReady) and event.z > 0.0: + caps.append(monitor.step_cap) + + session_run(backend, problem, request.for_run(monitor=monitor), between=keep) + assert len(caps) == len(planes) + assert min(caps) < 0.7 * crossing.launch_limit finally: backend.close() @@ -427,19 +444,31 @@ def test_a_longer_step_before_the_next_check_is_refused() -> None: run_request = simulation._run_request() backend = select("numpy_ref", problem, run_request, grid=simulation.grid) try: - driver = as_driver(backend) - driver.set_initial(problem.initial.field0, None) monitor = simulation._boundary_monitor() assert monitor is not None - driver.attach_monitor(monitor) - monitor._cap = 0.03 - monitor._busy = True - assert monitor.steps_to_check() == 1 - driver._refuse_scheduled_crossing(monitor) - monitor._busy = False - assert monitor.steps_to_check() >= 3 - with pytest.raises(BoundaryError, match=r"schedule's step 5\.000e-02 m"): - driver._refuse_scheduled_crossing(monitor) + session = start_session( + backend, + problem, + run_request.for_run(monitor=monitor), + Start.entrance(problem), + owns=False, + ) + try: + # The monitor launched on the loaded state, as the session attaches it. + monitor.crossing = problem.split_crossing + as_reference(backend).workspace.bind_monitor(monitor) + monitor.launch(reading(backend), float(problem.initial.z)) + refuse = cast("Any", session)._refuse_scheduled_crossing + monitor._cap = 0.03 + monitor._busy = True + assert monitor.steps_to_check() == 1 + refuse(monitor) + monitor._busy = False + assert monitor.steps_to_check() >= 3 + with pytest.raises(BoundaryError, match=r"schedule's step 5\.000e-02 m"): + refuse(monitor) + finally: + session.close() finally: backend.close() @@ -457,8 +486,6 @@ def test_a_state_that_walks_past_the_schedule_is_refused_when_watched() -> None: state[..., edge - 2 : edge] = math.sqrt(5e-4 * total) backend = select("numpy_ref", problem, run_request, grid=grid) try: - driver = as_driver(backend) - driver.set_initial(state, None) # Relaxed: the spread light fills the window, guards included. simulation.settings = dataclasses.replace( simulation.settings, @@ -466,8 +493,14 @@ def test_a_state_that_walks_past_the_schedule_is_refused_when_watched() -> None: ) monitor = simulation._boundary_monitor() assert monitor is not None + # The session attaches its monitor after the launch plane, and refuses there. with pytest.raises(BoundaryError, match="crossing limit fell to"): - driver.attach_monitor(monitor) + session_run( + backend, + problem, + run_request.for_run(monitor=monitor), + Start(field=state, z=float(problem.initial.z)), + ) finally: backend.close() diff --git a/tests/test_structure_figures.py b/tests/test_structure_figures.py index aa8a24d3b..bafd4e8ab 100644 --- a/tests/test_structure_figures.py +++ b/tests/test_structure_figures.py @@ -27,7 +27,7 @@ import pytest -from solprop.backends.host.driver import HostDriver +from solprop.backends.host.session import HostSession from solprop.backends.numpy_ref import passes from solprop.backends.protocol import Backend from solprop.output.metadata import RunMetadata @@ -184,9 +184,9 @@ def test_the_stage_figure_draws_every_reference_pass(): @pytest.mark.parametrize( "name", [name for _, members in build.DRIVER_PARTS for name in members] ) -def test_every_driver_part_is_a_member_of_the_step_driver(name): - """Figure 5 breaks `HostDriver` into parts, and each part names real members.""" - assert hasattr(HostDriver, name) +def test_every_driver_part_is_a_member_of_the_reference_session(name): + """Figure 5 breaks `HostSession` into parts, and each part names real members.""" + assert hasattr(HostSession, name) @pytest.mark.parametrize("name", build.CONTROLLER_PARTS) diff --git a/tests/test_tools.py b/tests/test_tools.py index a4a1548ab..2d8203989 100644 --- a/tests/test_tools.py +++ b/tests/test_tools.py @@ -19,6 +19,7 @@ from scipy.optimize import brentq from scipy.special import jn_zeros, jv +from builders import load_reference from solprop import tools from solprop._validation import choice from solprop.backends.numpy_ref import NumpyRefBackend @@ -924,10 +925,13 @@ def test_the_predicted_peak_intensity_is_the_statistic_a_run_reports_at_its_entr modes=simulation.modes, profiles=simulation.profiles, ) - backend.set_initial(problem.initial.field0, None) - reported = float( - backend.stats(StatsSpec(names=("peak_intensity",)))["peak_intensity"] - ) + try: + load_reference(backend) + spec = StatsSpec(names=("peak_intensity",)) + stats = backend.workspace.stats(spec, float(problem.initial.z)) + finally: + backend.close() + reported = float(stats["peak_intensity"]) predicted = tools.capillary_params( 125e-6, "He", 1.0, energy=energy, fwhm=fwhm, wavelength=PUMP, cladding=GLASS ).peak_intensity diff --git a/tests/translate/test_operator_settings.py b/tests/translate/test_operator_settings.py index 493ffb5e6..2d06bfe84 100644 --- a/tests/translate/test_operator_settings.py +++ b/tests/translate/test_operator_settings.py @@ -16,7 +16,7 @@ import numpy as np import pytest -from builders import reference_trial +from builders import load_reference, reference_trial from legacy_geometry import bare_absorber from solprop.backends.numpy_ref import NumpyRefBackend from solprop.boundaries import SpatialAbsorber, absorber @@ -333,7 +333,7 @@ def test_a_backend_handed_the_refused_step_forms_a_non_finite_stage(): run_request = simulation._run_request() backend = NumpyRefBackend(problem, run_request, grid=simulation.grid) try: - backend.set_initial(problem.initial.field0, None) + load_reference(backend) # A trial of the refused length, as only a direct caller can take one: the # inverse factor exp(lambda h) is infinite and so is the stage it scales. backend.workspace.hoist(0.0) @@ -460,7 +460,7 @@ def test_a_radial_backend_handed_the_refused_step_forms_a_non_finite_stage(): run_request = simulation._run_request() backend = NumpyRefBackend(problem, run_request, grid=simulation.grid) try: - backend.set_initial(problem.initial.field0, None) + load_reference(backend) backend.workspace.hoist(0.0) # The radial inverse factor exp(-dPhi) overflows as the separable one does. with np.errstate(over="ignore", invalid="ignore"): diff --git a/tests/vector_raman_cases.py b/tests/vector_raman_cases.py index ad19573e8..b735c91cc 100644 --- a/tests/vector_raman_cases.py +++ b/tests/vector_raman_cases.py @@ -16,6 +16,7 @@ import numpy as np +from builders import load_reference from former_raman import ( FORMER_CH4, FORMER_D2, @@ -135,7 +136,7 @@ def result(backend_class, problem, run_request, grid, modes, options=CHUNK): ) try: if backend.name == "numpy_ref": - backend.set_initial(problem.initial.field0, None) + load_reference(backend) backend.workspace.hoist(0.0) bundle = backend.workspace.stage_scalars(0.0, 0.0) rhs = backend.workspace.nonlinear( From 090c6ae72a2173f484086ea42428167793488f25 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 05:15:16 +0000 Subject: [PATCH 06/14] docs: the reference's session owns the schedule backends.md (the seam, the five parts, the marches, boundary warnings as barrier events), architecture.md section 9, kernel-contract.md (the statistics rows and the march's bounds name the session), stepper.md, structure.md, algorithms.md and testing.md (scripted engines) describe the code without the step driver. The timing probe's private docstrings take the private style. Co-Authored-By: Claude Opus 5.5 --- docs/dev/algorithms.md | 2 +- docs/dev/architecture.md | 12 +- docs/dev/backends.md | 175 +++++++++++----------- docs/dev/kernel-contract.md | 41 +++-- docs/dev/stepper.md | 14 +- docs/dev/structure.md | 10 +- docs/dev/testing.md | 19 +++ docs/guide/results/statistics.md | 2 +- src/solprop/backends/numpy_ref/backend.py | 25 +--- 9 files changed, 153 insertions(+), 147 deletions(-) diff --git a/docs/dev/algorithms.md b/docs/dev/algorithms.md index 66f29e35a..687114688 100644 --- a/docs/dev/algorithms.md +++ b/docs/dev/algorithms.md @@ -156,7 +156,7 @@ $f_{\max} = 1.1$, and a lag of one step by default. {py:func}`solprop.stepper.controller.limit_step`; {py:func}`solprop.stepper.schedule.landing` with {py:class}`solprop.stepper.schedule.StepTargets`. The loop is the reference's -`backends/host/driver.py`; the native session's compiled march performs the same steps. +`backends/host/runge_kutta.py`; the native session's compiled march performs the same steps. **Why a global magnitude.** Per-element scaling is catastrophic here: the in-band dynamic range of a hollow-fibre spectrum reaches $10^{17}$ and about a third of in-band bins carry diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md index 43f17a9d8..68bb9e64a 100644 --- a/docs/dev/architecture.md +++ b/docs/dev/architecture.md @@ -591,9 +591,10 @@ class Backend(Protocol): def memory_ledger(self) -> dict[str, int]: ... def close(self) -> None: ... - # The reference's host stepping seam (set_initial, propagate_to, observe, stats, the - # monitor and the march's snapshot) is a protocol of its own, HostStepping, which - # its session drives (backends.md section 1). + # Nothing else: a run is its session's on both backends (SEP 52). Behind the + # protocol each backend has a lowering, a workspace, engines, marches and a + # session; the reference's session (HostSession) is the Python counterpart of + # native's session.cpp (backends.md section 1). ``` - `numpy_ref`: the readable oracle. Plain NumPy + `scipy.fft`, no fusion, no in-place @@ -736,7 +737,7 @@ otherwise, with a warning, `numpy_ref` (ADR-029, ADR-064); the installed native [SEP 22](seps/archive/sep-0022-memory-lean-spatial-execution.md)): a plane without its field is not copied, converted or stored, the stores allocate field storage for the kept planes only, and the admission charges those alone (its `output` group). The backend is asked for the field only on - the kept planes: `HostDriver.observe(field=False)` transfers nothing from a device, + the kept planes: a field-free observation transfers nothing from a device, scans nothing for finiteness, skips the collar diagnostic (counted in the execution record) and forms no noise-phase volume, so a field-free plane costs its statistics alone. Under the low-storage march a step abandoned in flight after such a plane leaves @@ -745,7 +746,8 @@ otherwise, with a warning, `numpy_ref` (ADR-029, ADR-064); the installed native frequency, at most a node chunk's worth of samples at a time, never the whole volume. - A `SimulationRunner` keeps one backend's buffers and plans across many inputs, and is admitted once; each session's load restores everything a march reads (the native - backend's `_load`, the reference's `HostDriver.set_initial`), so a reused backend + backend's `_load`; the reference's session builds its march afresh and loads its + workspace), so a reused backend repeats a fresh one's run. An input array of more than 2²⁰ elements is recorded by its SHA-256 digest, not inline, so the run record stays small; the runner reads such an array in place and marches on a problem without it, so no input outlives diff --git a/docs/dev/backends.md b/docs/dev/backends.md index d4c8d086e..3c292b14f 100644 --- a/docs/dev/backends.md +++ b/docs/dev/backends.md @@ -49,37 +49,19 @@ class Backend(Protocol): def close(self) -> None: ... # idempotent @property def closed(self) -> bool: ... # a failure can close a backend - - -class HostStepping(Backend, Protocol): # the reference's seam; `stepping(backend)` - def set_initial( - self, - field: Field, - noise: NoiseRealisation | None, - *, - z: float = 0.0, - resume: bool = False, - ) -> None: ... - def set_progress(self, reporter: ProgressReporter) -> None: ... # observer only - def set_stop(self, flag: StopFlag | None) -> None: ... # polled between trials - def attach_monitor(self, monitor: BoundaryMonitor) -> None: ... - def propagate_to(self, z: float) -> StepSummary: ... - def observe( - self, *, field: bool = True - ) -> Observation: ... # host arrays: field at z, step history - @property - def in_flight(self) -> tuple[float, float] | None: ... # a step abandoned there - def stats(self, spec: StatsSpec) -> dict[str, NDArray]: ... - def restore_call_ledgers(self, logical, atomic=None) -> None: ... - def march_snapshot(self) -> MarchSnapshot | None: ... # the Adams history - def march_snapshot_nbytes(self, z: float) -> int | None: ... # copying nothing - def restore_march(self, snapshot: MarchSnapshot) -> str | None: ... ``` -A run goes through the backend's session (`prepare(...).start(...)`, SEP 47 §5.2). The -NumPy reference's session drives the host stepping seam, `HostStepping`, which the -reference's `HostDriver` implements; the native backend implements `Backend` alone, and -its session marches natively (SEP 47 §6.8). +Each backend also sets the class attribute `helpers` (SEP 29). That is the whole +protocol (SEP 52 §5.1): a run goes through the backend's session +(`prepare(...).start(...)`, SEP 47 §5.2), which loads the start, schedules the run, +reports its events and exports its fields, on both backends. Each backend has the same +five parts behind it: a lowering, a workspace that holds the state and does every +state-sized operation, the engines a march asks of it, the marches, and the session +(§1, point 3). The NumPy reference's are `NumpyRefBackend`'s constructor tables, +`NumpyWorkspace`, the engines of `solprop.backends.engines`, the marches of +`backends/host/` and `HostSession`; the native backend's are its lowering into +`_core.Problem`, its resident state, `rk::Engine` and `march::Engine`, its compiled +marches and `session.cpp`, of which `HostSession` is the Python counterpart. The listing is abbreviated; `solprop/backends/protocol.py` holds the exact signatures and docstrings, in the order of [architecture.md §9](architecture.md#9-backends-in-one-page). @@ -88,8 +70,8 @@ Rules: a backend is constructed from a validated `PropagationProblem` ([kernel-contract.md](kernel-contract.md)), the `RunRequest` that carries the run's policy ([SEP 47](seps/archive/sep-0047-run-ownership.md) §5.2; it checks the two with `validate_run` before it allocates) and host arrays, and returns host arrays; its -buffers, layout and plans are private; the state is never a parameter of `propagate_to` or -`observe`; the numbers are the contract — a backend is correct when it reproduces the +buffers, layout and plans are private; the state is never a parameter of anything a +session is asked; the numbers are the contract — a backend is correct when it reproduces the reference to the stated bound. Selection is by name (`backends.select(name, problem, request)`); availability is detected with `importlib.util.find_spec` (importing an accelerator package can initialise a device runtime), never cached; a name that is neither backend, a retired @@ -111,12 +93,20 @@ reference is refused a required device by name); and `statistics_refusal` reads 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 -that a device backend can keep its rows resident and copy them once per plane; the shared -march still decides which accepted steps produce rows and passes their history indices. -The CPU backends inherit the host defaults. The hooks are part of the frozen surface -([kernel-contract.md §8](kernel-contract.md)). +**Periodic statistics are the session's.** Each session decides which accepted steps +produce rows and keeps them between events: the reference's in a host buffer it drains at +each event, the native session in its bounded resident chunk buffers. The storage hooks +the step driver once carried for a device backend are gone with it (SEP 52 §5.1). + +**Boundary warnings are barriers on both backends.** The boundary monitor's and the +transverse edge's warnings arrive as `ServiceRequired` events of kind `WARNING` at the +committed endpoint they arose at, one barrier each, in order (SEP 52 §5.1): the caller +emits each with `emit_warning`, so its filters may raise it and fail the run there with +that endpoint's field checkpointed, and once allowed the next advance does the rest of +that point's work, once. The reference's monitor and edge put their warnings into a sink +the session drains (`BoundaryMonitor.sink`); used on its own, a monitor issues them +through `warnings.warn` as before. Both sessions report their execution facts through +`execution_record`, which the service loop reads (`driver.run.SessionFacts`). **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`, @@ -178,7 +168,7 @@ and `rate_weights`) and the Lagrange basis of an Adams formula on its actual nod takes the implementation from the backend that runs the stage, never from a process-wide switch or from what is installed (SEP 29 section 6.6, R16): each backend sets the class attribute `helpers` (kernel schema 34), a -`solprop._helpers.Helpers` record of the two operations, and the reference's driver, its +`solprop._helpers.Helpers` record of the two operations, and the reference's session, its Adams march, its engines and the native backend's own load and resident engine pass it down. `numpy_ref` takes `PLAIN`, the uncompiled Python forms, so the oracle never runs the compiled code it @@ -201,15 +191,17 @@ both backends in one process, with every other implementation made to raise afte translation, and a native z-table run of each march with the plain forms forbidden. -**3. Two owners, eight marches.** The reference steps through its own driver, -`HostDriver.propagate_to`, which hands the steps to its run's march; every native run is -its native session's (`solprop_native.session`), whose compiled marches advance to an -event from one policy record and hand back the events (SEP 47). Each reference march -keeps its position, proposal, replay cursor and accepted norms in its own `MarchState` -(`backends/host/marches.py`), asks the driver only through the narrow `MarchHost`, and -hands every state-sized operation to an engine of `solprop.backends.engines` over the -reference's workspace, `NumpyWorkspace` (`backends/numpy_ref/workspace.py`), which holds -the state and does every state-sized operation (SEP 52 §5.1): +**3. One shape, two implementations: the marches.** Every reference run is its session's, +`HostSession` (`backends/host/session.py`), which drives the run's march directly; every +native run is its native session's (`solprop_native.session`, over `session.cpp`), whose +compiled marches advance to an event from one policy record and hand back the events +(SEP 47). Each reference march keeps its position, proposal, replay cursor and accepted +norms in its own `MarchState` (`backends/host/marches.py`), asks the session only through +the narrow `MarchHost`, and hands every state-sized operation to an engine of +`solprop.backends.engines` over the reference's workspace, `NumpyWorkspace` +(`backends/numpy_ref/workspace.py`), which holds the state and does every state-sized +operation (SEP 52 §5.1). The backend builds a fresh march and engines for each run +(`NumpyRefBackend.method`), so a reused backend repeats a fresh backend's run: | Loop | Steps | Where its state-sized work runs | |---|---|---| @@ -225,25 +217,32 @@ the state and does every state-sized operation (SEP 52 §5.1): The reference's Runge-Kutta march is the reference for the compiled Runge-Kutta march, which holds to it through kernel contract §12 (ADR-069), and for the march's bookkeeping. `HostAdamsMarch` is the reference for the compiled Adams march, which holds to it through -kernel contract §11 (ADR-060). The decision-trace tests drive each compiled march a call -at a time over a scripted host backend (`tests/backends/native_trace_marches.py`) and -hold it to the reference's decisions on the same readings. A new compiled loop needs a +kernel contract §11 (ADR-060). The decision-trace tests drive each reference march over a +scripted engine and a stub session that applies the session's rules +(`host.session.step_cap`, `host.session.natural_stop`), and each compiled march a call at +a time over the same stub (`tests/backends/native_trace_marches.py`), and hold the two to +the same decisions on the same readings. A new compiled loop needs a contract that specifies it in full and a reference to compare it with. -What the reference's marches share around a step, and the native session transcribes, -is the driver's: `propagate_to` and `observe`, the history (`_record`), the committed -step's work (`_take_step_stats`: **the statistics channel between planes** and the -boundary monitor), the natural stops, the noise load and **the progress reporter**. A -march reaches them through `MarchHost` (`poll_stop`, `cap`, `record`, `absorb`, -`stepped`, `natural_stop`, `natural_stop_due`), which the driver implements with -`_SessionHooks`. The backend supplies the workspace, the engines and the run's march; -the driver's `_begin_plane` and `_on_accepted_step` reset and score the workspace's -quadrature alarm, reported once per plane. - -`set_progress` attaches the observer the loop calls (the driver, not the backend, also -tells the reporter when its loop raised). `HostDriver` calls -`ProgressReporter.step` from `_record`, which every attempted step of every backend already -passes through, so a host backend gets the per-step channel for nothing; a backend whose +What the reference's marches share around a step is the session's, transcribing +`session.cpp`'s order: the planes, step planes and natural stops, the bounded yields and +the snapshot latch's halts, the history (`record`), the committed step's work +(`_account_step`: the boundary monitor's check, the transverse edge's read and **the +statistics channel between planes**), the dense hold and observation of a plane a step +crossed, the snapshot rows, the load with its noise, the events and **the progress +listener**. A march reaches them through `MarchHost` (`collar_quiet`, `poll_stop`, `cap`, +`record`, `absorb`, `stepped`, `natural_stop`), which `HostSession` implements. The dense +observation is the backend's dense output (`numpy_ref/dense.py`: DOPRI5's continuous +extension, or the Adams interpolant at the weights of the march's record of its last +step, `AcceptedStep`, with its trial's carrier rotations applied to the samples, as +native's `dense.cpp` does); the session holds the committed state aside while a plane is +observed and restores it before the march goes on. The snapshot's rows are the Adams +history's `AdamsRows`, which the session exports and installs. The session's `record` +scores the workspace's quadrature alarm at each accepted step and reports it once per +plane, as native reads `quadrature_peak`. + +The session's attempt listener is the observer the loop calls. `HostSession` calls it from +`record`, which every attempted step passes through, so a host backend gets the per-step channel for nothing; a backend whose loop runs on a **device** -- where a per-step host callback would mean a synchronisation per step -- is allowed to call `step` once per plane instead, with the plane's own totals. That is the only place a backend may differ in what it reports. What it may never do is let the @@ -252,13 +251,13 @@ with a reporter is the run without one, to the rounding bound of any repeat of t (`tests/backends/test_driver.py`); the reporter's calls are exact no-ops on the state. **The statistics channel between planes** is the second thing the loop owns and a backend -does not. After every `period`-th accepted step the march calls the backend's own `stats` -with the periodic subset promoted to `names`, and appends one row — the position, the index +does not. After every `period`-th accepted step the session evaluates the workspace's own +`stats` with the periodic subset promoted to `names`, and appends one row — the position, the index of the accepted step in this plane's history, and one small array per statistic — to a -buffer that `observe` drains into `Observation.step_stats`. Two rules make it sound: +buffer that each event drains into its chunk's `step_stats`. Two rules make it sound: - **The call site is the march's `MarchHost.stepped`, after the engine's accept and - after `z` advances**, not `_on_accepted_step`. The two marches are not symmetric there: + after `z` advances**, not at the attempt's record. The two marches are not symmetric there: an adaptive march records an attempt *before* it accepts and advances `z`, a replay after both, so a hook would read the previous accepted step on an adaptive run and the current one on a @@ -275,9 +274,7 @@ repeat its last bit). Luna carries a plane starts with — a measured estimate of a plane's step count rather than a predicted one, and after the first plane a run allocates nothing per step. **On a device** the rows are the same host buffer: the reductions run on the device, to the bound of rule 1 above, and -each row returns one packed scalar transfer. The hooks (`_reset_step_stats`, -`_record_step_stats`, `_drain_step_stats`) would let a backend keep rows on the device and copy -them once per plane, but none does. A backend that +each row returns one packed scalar transfer. A backend that cannot evaluate one of the subset's statistics between planes refuses the spec by name, as it refuses a plane statistic it cannot form. @@ -287,8 +284,8 @@ the run adopted. `native` does this for the plasma pair: §3.1a has the measurem predicate. **The boundary monitor's reading** is the third thing the loop calls at the same point, and -the backend reduces it (SEP 21, ADR-057). At a check the driver asks -`_boundary_energies()` for five numbers, the state's energy and its four weighted +the backend reduces it (SEP 21, ADR-057). At a check the session asks the workspace +(`HostSession._energies`) for five numbers, the state's energy and its four weighted energies (`solprop.monitor.BoundaryEnergies`), and the backend forms them where its state lives: `native` in its memory space through its statistics buffers (CPU and device builds alike). Only the five cross to the host; `numpy_ref`'s host reduction @@ -299,8 +296,8 @@ scheme each accepted step's finish (`NumpyWorkspace.finish`, and the native engi finish, on every march) takes, from the masked field **before** the split, what the split takes of the power it finds, `P (1 − e^{−αh})`, and the energy and the guards' and collar's energies of that power halfway through the factor, `P e^{−αh/2}`, and returns -them in the step's `AcceptRecord` (SEP 52 §5.2). The driver adds the removal to an -accumulator the next reading drains (`_absorb`), so the removal is exact on unchecked +them in the step's `AcceptRecord` (SEP 52 §5.2). The session adds the removal to an +accumulator the next reading drains (`HostSession.absorb`), so the removal is exact on unchecked steps too, and keeps the latest step's energies, which the reading returns beside the five (`BoundaryEnergies.found`, kernel schema 43) and the monitor judges the occupancies on. The split collar's crossing limit @@ -507,7 +504,7 @@ starts through the backend's own preparation shape (SEP 47 §5.2): without the run layer naming it. The reference's (`backends.host.session.HostPrepared`) opens `HostSession`, which composes the parts the Python sessions share (`backends.session_core`: the attempt counter, yield check, snapshot latch, shared -observation and preparation refusals) and imports nothing of the inherited driver; the +observation and preparation refusals) and imports nothing of the native backend's; the native backend's (`solprop_native.session.NativePrepared`) opens `NativeSession`, the only 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 @@ -553,7 +550,7 @@ as one; its end-of-plane log is retired, and the boundary monitor's transverse e (SEP 40) judges the boundary instead. A backend whose own statistics do not apply this measure refuses the problem. **The transverse edge is read where the state lives** ([SEP 40](seps/archive/sep-0040-transverse-absorbing-boundaries.md), [SEP 44](seps/archive/sep-0044-native-edge-read.md)). -A backend whose `HostDriver.reads_transverse_edge` is set hands the monitor's +A backend whose `reads_transverse_edge` is set hands the monitor's `TransverseEdge` an `_EdgeReading` from `NumpyWorkspace.edge_reading` at the edge's reads, at saved planes, and with a requested collar at every committed step. The reading is numbers and never the field: region sums, each column's energy and any collar's strip and current. The default forms them with `_HostEdgeReduction` on a host copy, @@ -562,8 +559,8 @@ the edge's `_EdgeTables`, four regions' weights on the nodes, so it holds no fac field-free run crosses no state (`tests/backends/test_native_edge_reading.py`). A requested collar's lines are described once, as `_edge_lines`, for both reductions (`tests/backends/test_native_edge_collar.py`): native takes each strip's padded transform in batches of planes under `_STRIP_BATCH_BYTES`, on buffers listed in the `transverse_edge` ledger row, and the -current from the onset's three nodes, rectified per row, all on one load of the transverse scratch. Under the driver -the current is still accumulated in Python (under the native session, below, nothing is). Everything else, the weights, the spacing, the ledgers and the judgement, is one +current from the onset's three nodes, rectified per row, all on one load of the transverse scratch. Under the reference's +session the current is accumulated in Python (under the native session, below, nothing is). Everything else, the weights, the spacing, the ledgers and the judgement, is one code on every backend. The read spacing is a ceiling on the step, and a step is not made to land on a read: the edge is read at the last committed position from which the next step, a replay's scheduled one or else the controller's proposal, would @@ -571,7 +568,7 @@ carry past the next read (`TransverseEdge.due`), so reads stay at most a spacing apart without shortening the steps between them (landing on each read cost 10-35 % more steps on the suite's line and planar cases). Every solprop backend sets it; `numpy_ref` keeps its state on the host and steps from there, under the -driver's ceiling. The native Adams march +session's ceiling. The native Adams march takes the next read and the spacing as the call's `read_at` and `read_spacing` bounds: an adaptive step is capped at the spacing, and the call returns at the committed position from which the next step would pass the read, so the host reads the state @@ -589,7 +586,8 @@ a read falls due, and with a collar at every committed step, so a collar's curre follows the temporal monitor at each point of SEP 47 §5.3: launched after the temporal launch, read after a committed step's check and before its statistics row, and at a plane before its row. A point's several warnings (a launch can raise five) are each a `ServiceRequired` barrier, the edge holding its place between them (`Edge::proceed`), so a -warning the caller raises leaves the rest of that point undone, as solprop's inline warning does. The scalar decisions +warning the caller raises leaves the rest of that point undone, as the reference's session does (a suspended point's +work resumes after its barrier). The scalar decisions are solprop's exactly on the same readings, the worst face's ties broken on its name as `max` breaks a tuple's and the reach's tail summed in order over the columns as solprop sorted them; the launch's share in the ramp's band and the ramp's removal per interval are the native reading, summed in order with the C library's `expm1` where NumPy sums @@ -877,17 +875,18 @@ The pools, the widths and the wait policy are stored in the output metadata `SOLPROP_FFTW_PLAN` and `SOLPROP_FFTW_WISDOM` remain. Pass timings are the native engine's Kokkos regions. -### 3.5 The step driver: Python first, compiled when measured +### 3.5 The session's march: Python first, compiled when measured -**One driver for the reference, one session for native.** `backends/host/driver.py` is the -reference's scheduler -- the planes, halts, history, statistics rows and boundary checks -- -over its marches (`backends/host/runge_kutta.py`, `adams.py`, `low_storage.py`), which -own their state; the native backend inherits no driver, and its session marches natively (§1, point 3, lists the marches). Per stage a backend asks the translation layer for one bundle of host +**One session per backend, the same shape.** `backends/host/session.py` is the +reference's schedule -- the planes, halts, history, statistics rows, dense observation and +boundary checks -- over its marches (`backends/host/runge_kutta.py`, `adams.py`, +`low_storage.py`), which own their state; the native backend's session marches natively +(§1, point 3, lists the marches). Per stage a backend asks the translation layer for one bundle of host scalars and combines the terms it holds over them (§1); an engine applies the boundary treatments of the workspace's `finish` only to a step it accepts, so a rejected step does not pay the temporal absorber's transform pair for a state that is thrown away. -Under Runge–Kutta the driver's loop is the reference, and on `native` one call executes all +Under Runge–Kutta the reference's march is the reference, and on `native` one call executes all seven stages of a trial (§4), its rows formed natively from the uploaded stage tables and its norm reduced natively ([SEP 45](seps/archive/sep-0045-native-rk-march.md) phase 2). An earlier measurement on the retired `numba_cpu` backend found the loop's Python cheap (about 50 calls a @@ -919,7 +918,7 @@ builds, the system libm, with each element's own calls, on Arm and on devices the stage that formed them — the forward in pass 1 and the inverse in pass 7 — so recomputing evaluates `ΔΦ` exactly as often as tabulating does and the table buys residency and nothing else (a step within 2 %, measured on the retired `numba_cpu` backend). The flag's -default is therefore `"auto"` and the choice is the backend's (`HostDriver.propagator_default`): +default is therefore `"auto"` and the choice is the backend's (`NumpyRefBackend.propagator_default`): `numpy_ref` resolves it to `tabulate`, because it forms two complex exponentials per stage and the table saves five of them, and implements both paths; `native` resolves it to `recompute`, because both signs come from one `exp` and a `sincos` in the stage that consumes them diff --git a/docs/dev/kernel-contract.md b/docs/dev/kernel-contract.md index 1d1d07ffc..22f8f1174 100644 --- a/docs/dev/kernel-contract.md +++ b/docs/dev/kernel-contract.md @@ -52,7 +52,7 @@ hard-mask zeros, and explicitly exact zeros and no-ops. | `responses` | frozen dataclass | section 5 (`translate.responses.CompiledResponses`) | | `initial` | frozen dataclass | section 6 (`translate.problem.Initial`) | | `route` | `ModalRoute \| GeneralRoute \| SpatialRoute` | the closed union of route descriptions (`translate.routes`), each variant carrying exactly the fields its executor needs: the transform (§4) and the route's own leaves. Below, under *The route union* | -| `split_crossing` | `SplitCrossing` or `None` | the split temporal collar's crossing limit (`boundaries.SplitCrossing`): `buckets`, each `(mode, frequency)` bin's walk-off bucket as `(n_modes,n_omega) uint8` (the fastest of its polarisations and positions, a coupled flow's channels with the generator's diagonal added to the shared carrier; `boundaries.split_rate_buckets`), the fastest rate a bin reaches `fastest` (the open first bucket's rate), the collar's `width` and the launch's limit `launch_limit`, which holds an adaptive `dz_max` and a fixed schedule at translation. A backend that reads the boundary monitor under the `"split_step"` scheme returns the state's energy per bucket with every reading (`BoundaryEnergies.occupancy`; native: `bind_occupancy`, then `monitor_reading`'s ten numbers followed by the 128 buckets); the monitor turns it into a cap on the steps until the next check (`HostDriver._split_capped`, the native Adams march's required `step_cap` bound), and a fixed schedule whose steps before the next check exceed it, at a check or when a resumed state is watched, stops with a `BoundaryError`. `None` under the in-stage scheme or without a temporal collar. Added in version 43 | +| `split_crossing` | `SplitCrossing` or `None` | the split temporal collar's crossing limit (`boundaries.SplitCrossing`): `buckets`, each `(mode, frequency)` bin's walk-off bucket as `(n_modes,n_omega) uint8` (the fastest of its polarisations and positions, a coupled flow's channels with the generator's diagonal added to the shared carrier; `boundaries.split_rate_buckets`), the fastest rate a bin reaches `fastest` (the open first bucket's rate), the collar's `width` and the launch's limit `launch_limit`, which holds an adaptive `dz_max` and a fixed schedule at translation. A backend that reads the boundary monitor under the `"split_step"` scheme returns the state's energy per bucket with every reading (`BoundaryEnergies.occupancy`; native: `bind_occupancy`, then `monitor_reading`'s ten numbers followed by the 128 buckets); the monitor turns it into a cap on the steps until the next check (`host.session.step_cap`, the native Adams march's required `step_cap` bound), and a fixed schedule whose steps before the next check exceed it, at a check or when a resumed state is watched, stops with a `BoundaryError`. `None` under the in-stage scheme or without a temporal collar. Added in version 43 | `PropagationProblem` also carries two **properties**, which are not fields and so not rows above: `transform`, the route's transform, and `device_ready`, true when Φ (§3) and the prefactor (§5) are each a weighted sum of a fixed set of arrays, and false when either took the z table. @@ -250,7 +250,7 @@ line's `(inward, windowed)` strip and the summed rectified current, never the fi `_HostEdgeReduction` on a host copy. Native's takes the edge's `_EdgeTables` and `_EdgeLine`s, whose weights, strides, windows and onsets say all there is to know about the geometry, so a backend holds no face, mask or judgement of its own. It reads the state at a committed position, so it may use scratch that a step writes before reading, and it must leave the march -as it was. `HostDriver.edge_memory(space)` says what binding holds, from the grid alone, for `estimate`: the default holds +as it was. `Backend.edge_memory(space)` says what binding holds, from the grid alone, for `estimate`: the default holds nothing beyond the state, and native's is `_transverse_edge_bytes`, equal to its `transverse_edge` ledger row. **Source reservations in the Adams march.** The engine protocol's @@ -263,7 +263,7 @@ its workspace (`NumpyWorkspace.reserve_calls`, `record_trial`, `release_calls`), without a host source. NumPy's TDSE implementation translates the reservation into the required persistent-plan chunks, while provider attempts remain charged before invocation, including failures. Logical source-call and atomic-attempt ledgers remain -separate. The march owns its logical ledger, which the driver exports and restores on +separate. The march owns its logical ledger, which the session exports and restores on every Adams backend. Loading a checkpoint resets numerical history but preserves charged calls; startup is charged again. Atomic ledger restoration needs a bound TDSE binding, on either backend. @@ -1088,7 +1088,7 @@ The initial-state fields below are independent of that optional binding. | `noise_model` | `"none" \| "input" \| "modified"` | | | `z` | `float` | absolute initial position in m, non-negative and before the first requested save; true-power input is normalised at this position | -No kernel indexes `field0`: `HostDriver.set_initial` accepts a state of any strides and +No kernel indexes `field0`: a session's load accepts a state of any strides and copies it contiguous into the backend's own state, so since version 42 `field0` may be a zero-stride broadcast view. Every array of `Initial` is the problem's own, so that nothing a caller does afterwards to an array it passed changes the problem, and the @@ -1125,7 +1125,7 @@ launch's remaining planes). | `interval_cap` | bool | whether a step is capped at the width of the operator-table interval it starts in. `assemble` turns it off on the diagonal-flow routes and on for a coupled flow or a reject-free controller, unless set ([SEP 14](seps/archive/sep-0014-stepper-efficiency.md) §4.1) | | `auto_init` | bool | whether the start-up rule takes the step after the first from the first step's own scaled norm (`PIController.start_factor`, at most 100 times `dz_init`). Set by the convenience interfaces when no `dz_init` is given; off for a coupled flow or a reject-free controller ([SEP 14](seps/archive/sep-0014-stepper-efficiency.md) §4.2) | | `interpolate_planes` | bool | steps across the save planes and observes each inside its accepted step, through DOPRI5's continuous extension or, with an `integrator`, the Adams march's own polynomial (ADR-039); the end of the run and the hard kinks are still landed on. Refused with a schedule, a Runge-Kutta tableau without an extension, the per-step collar, a coupled flow and the `modified` noise | -| `step_planes` | int | a positive `k` also saves the end of every `k`-th accepted step since the load: the shared march returns from `propagate_to` there, short of its target, and the driver saves the plane and asks for the target again (ADR-039). `0` never stops short | +| `step_planes` | int | a positive `k` also saves the end of every `k`-th accepted step since the load: the march returns to its session there, short of its target, and the session observes the plane and marches on to the target (ADR-039). `0` never stops short | **The finish's input is on the band.** Under the split-step absorber scheme the reference masks before and after the temporal absorber, and native masks only after it. With content @@ -1143,24 +1143,19 @@ the problem. | `stats` | frozen dataclass | `solprop.stats.StatsSpec`: which statistics, energy windows (`(n_windows, 2)` in ω), periodic subset and period, validated against the catalogue at construction; and the far-field tables of [SEP 23](seps/archive/sep-0023-far-field-aperture-spectra.md), `apertures` (an `ApertureSet`: centres, diameters, distances, edges, profile, weighting, labels, and from schema 45 the optional shapes, profiles and extents, which a record leaves out while they are unset) and `spectral_regions` (`(n_regions, 4)` boxes of physical transverse wavevector in rad/m, the one leaf whose entries may be infinite), read only when a name that uses them is requested, so a backend that does not know a name refuses it rather than misreading a table. Fields of the leaf, not rows of the contract | The `periodic` subset and its `period` are read **when the backend is built**, not when a -run is started: the shared step loop arms the between-planes channel from the statistics +run is started: the session arms the between-planes channel from the statistics of the request the backend was built with, so a spec handed to `run_problem` that disagrees with that request's own about either is refused. Every name in the subset must carry the catalogue's `between_planes` trait, which `StatsSpec` enforces at construction and by name; a backend that cannot form one of them at all refuses the run the same way its plane statistics do. -The driver exposes three storage hooks; the shared march decides which accepted -steps produce rows and passes their exact history indices: - -| hook | contract | -|---|---| -| `_reset_step_stats(*, release: bool)` | Discard rows on a fresh load (`True`, release storage) or at a new plane (`False`, retain capacity). Period counting remains in the shared march. | -| `_record_step_stats(spec: StatsSpec, z: float, step: int)` | Evaluate a row after boundary treatments, state commitment and position advancement. `step` includes rejected attempts. Device implementations retain device values and share their evaluator with `stats()`. | -| `_drain_step_stats() -> StepStats` | Return owning host rows at observation, then reset the row count while retaining capacity. A device implementation copies packed values once here. An empty drain transfers nothing. | - -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, +Each session decides which accepted steps produce rows and keeps them between events +(the step-driver storage hooks were removed by SEP 52): a row is evaluated after the +step's boundary treatments, its commit and the position's advance, with the index of its +attempt in the event's chunk, rejected attempts counted (`-1` when a warning barrier +delivered that attempt in the chunk before). The reference keeps a host buffer and +evaluates the workspace's `stats`; the native session keeps bounded resident chunk +buffers. Device arrays remain behind the seam. A backend must implement the contract, 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. @@ -1279,10 +1274,10 @@ records no rejected attempt and raises it at once. **What a native call takes**: the policy, once per run and again when the monitor's interval changes (`MarchPolicy`, every field of the record), with a replay's -schedule (its steps and edges); the state above, with a replay's cursor (the driver's -schedule index); and its bounds: the target; for a replay, the edges' slack +schedule (its steps and edges); the state above, with a replay's cursor (the march +state's `cursor`); and its bounds: the target; for a replay, the edges' slack (`replay_tolerance`); whether the collar rests; the accepted steps after which the -driver has work (the next statistics row, natural stop or monitor check, whichever comes +session has work (the next statistics row, natural stop or monitor check, whichever comes first; none for zero); the monitor's last check and interval; and the call's own bound, 256 attempts or 0.1 s of wall time, read after each attempt, which bounds the wait of a signal or a stop flag. Where a call returns is not a decision of the march's: a return @@ -1296,7 +1291,7 @@ one attempt, of seven and of none to one set of bits. - each accepted step's order, and the last accepted step's anchor, step, order and nodes, for a dense observation; - the reason it returned (`march::Reason`): the target reached, or crossed with planes - interpolated; an accepted step on which the driver has work; the monitor's distance; + interpolated; an accepted step on which the session has work; the monitor's distance; the call's bound; the budget, with the refused attempt's cost; the floor, with the proposal below it; a replayed step whose norm is not finite, with its step, end and norm; or a native error, with its stage (startup, trial, accept), category @@ -1395,7 +1390,7 @@ start-up rule, before the history's last value is rewritten; and after an accept commit and append, before its boundary check and statistics. **What a native call takes and returns** is §11's, with this march's policy and state: -the call's bounds (the target, the accepted steps after which the driver has work, the +the call's bounds (the target, the accepted steps after which the session has work, the call's own bound of 256 attempts or 0.1 s), and per attempt one row of end, step, norm (non-finite as infinity), accepted and wall time, the reason it returned and the state. The call takes the boundary monitor's checks inside the march as §11's does, with the diff --git a/docs/dev/stepper.md b/docs/dev/stepper.md index 969905f6f..11c4cbf2c 100644 --- a/docs/dev/stepper.md +++ b/docs/dev/stepper.md @@ -175,9 +175,10 @@ order conditions are checked for both weight vectors and the propagated solution fifth-order one, and the FSAL stage is not recycled before anything that depends on the 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` -and `HostLowStorageMarch`. Every native run is its native session's, whose compiled Runge-Kutta, Adams and low-storage +**Who marches** ([SEP 47](seps/archive/sep-0047-run-ownership.md), [SEP 52](seps/sep-0052-backend-shape.md)). +The NumPy reference's session schedules its runs and drives its marches in +`backends/host/`: `HostSession` over `RungeKuttaMarch`, `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 @@ -283,8 +284,9 @@ of `table_steps` and the flows' increments, the native state forms from its stag tables (`native/src/low_storage.cpp`), with no return to Python; a failure partway through a step leaves no consistent state, so the session's terminal event is poisoned and claims no checkpoint. There is no estimate: the history's norm is 0.0, "not estimated". The step -is **in flight** from its start to its commit (`HostDriver._in_flight`), and every entry -that reads or advances the state refuses it until `set_initial`; divergence is detected +is **in flight** from its start to its commit (the engine's `in_flight`, which the march +reports with the step's start and length), and every entry that reads or advances the +state refuses it until a new session loads a start; divergence is detected on the accepted state's squared norm, which pass 4 reduces over the norm mask. The stiffness indicator `h rho = 2 ||F3 - F2|| / ||F2 - g1||` (exactly `|h lambda|` for `u' = lambda u`) is kept by the host engine and logged when it passes RK4's negative-real @@ -400,7 +402,7 @@ corrector, carry and defect norms are native passes over its resident eigenbasis frozen-residual flow's generator applied once per sample. **The native Runge–Kutta march** (ADR-069, [SEP 45](seps/archive/sep-0045-native-rk-march.md)): -`HostDriver._march_to`'s decisions are pure functions of a `RungeKuttaPolicy` +`RungeKuttaMarch.march_to`'s decisions are pure functions of a `RungeKuttaPolicy` (`backends/rk_core.py`), held to a decision corpus recorded before the refactor (`tests/data/rk_traces.json.gz`), and `native` executes them (`native/src/rk_march.cpp`) on its staged trial and native norm, a call of attempts at a time, returning only at a host diff --git a/docs/dev/structure.md b/docs/dev/structure.md index afe2f45a0..e20686a93 100644 --- a/docs/dev/structure.md +++ b/docs/dev/structure.md @@ -49,9 +49,9 @@ The spine on the left is the call sequence, from the convenience function down t plots; the column on the right is what each stage hands to the next, in the colour of the layer that owns it. The annotations between them are [architecture.md §5](architecture.md)'s own. The thing to notice is where the boundary -falls: the outer driver visits save planes, while the step driver's `propagate_to` runs -the Python step loop (the reference's `HostDriver`, or the native bridge's -`StepDriver`, [SEP 47](seps/archive/sep-0047-run-ownership.md) phase 2). Reference passes, compiled kernels and library transforms, +falls: the service loop serves a session's events, while the session runs the step loop +(the reference's `HostSession` over its Python marches, or native's session over its +compiled ones, [SEP 47](seps/archive/sep-0047-run-ownership.md), [SEP 52](seps/sep-0052-backend-shape.md)). Reference passes, compiled kernels and library transforms, or one native trial do the numerical work behind that loop. ![One run of solprop, from prop_capillary through the kernel problem and the step driver to a saved plane](figures/one_run.svg) @@ -91,8 +91,8 @@ Text: [architecture.md §8](architecture.md) for the passes, The seam at the top is the whole of what a backend is. Under it is the step loop no backend reimplements — the march, the replay, the landing, the controller, the history, -the noise and the per-stage bundle all live in the reference's step driver, -`backends/host/driver.py`, while the native backend's session marches natively +the noise and the per-stage bundle all live in the reference's session and marches, +`backends/host/`, while the native backend's session marches natively ([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 diff --git a/docs/dev/testing.md b/docs/dev/testing.md index 67ae1d561..c048deba0 100644 --- a/docs/dev/testing.md +++ b/docs/dev/testing.md @@ -192,6 +192,25 @@ signal and stop flag, and clean-up. These tests have hard deadlines, so a broken cancellation fails instead of hanging; the production code has none. An installed Pyroraptor is not tested in CI; it is checked by hand (SEP 49, section 7.4). +### Scripted engines + +Step control, the session lifecycle and the service loop are tested with their numerical +outcomes scripted, never by substituting the code under test. A scripted engine replaces +the engine under the real march and the real session ([SEP 52](seps/sep-0052-backend-shape.md) +§6.3), as native's scripted engines test its compiled marches: + +- `tests/scripted_driver.py`'s `HostScriptedDriver` is the reference backend whose + Runge-Kutta engine multiplies the state by a constant and scores norms from a list, + with statistics that read the position; `tests/sessions/executors.py`'s + `HostSessionScript` adds the lifecycle suite's rejections, failures and in-flight + failures, and `ScriptedSession` a warning barrier at a chosen endpoint. +- The decision traces (`tests/backends/rk_traces.py`, `adams_traces.py`) run each + reference march over a scripted engine and a stub session that applies the session's + own rules (`host.session.step_cap`, `natural_stop`), and the native marches over the same + stub (`tests/backends/native_trace_marches.py`); the stored corpora + (`tests/data/*_traces.json.gz`) hold both to the same decisions and are regenerated only + under SEP 52 §4's rule. + ### Budgets and timing assertions The fast and medium budgets are judged on CI's macOS arm64 test lane, from each test's diff --git a/docs/guide/results/statistics.md b/docs/guide/results/statistics.md index 252d0ad87..487ea01f8 100644 --- a/docs/guide/results/statistics.md +++ b/docs/guide/results/statistics.md @@ -122,7 +122,7 @@ recorded no subset reads back as an **empty channel** rather than an error, so a there is one. **A row is the plane's own number.** The channel evaluates through the same -{py:meth}`~solprop.backends.protocol.HostStepping.stats` a save plane uses, on the state the +statistics a save plane uses, on the state the accepted step committed, so a row that lands on a plane is what that plane records, to the statistic's rounding. There is one definition of each statistic and no second implementation to drift from the first. diff --git a/src/solprop/backends/numpy_ref/backend.py b/src/solprop/backends/numpy_ref/backend.py index 9426960e4..b108def01 100644 --- a/src/solprop/backends/numpy_ref/backend.py +++ b/src/solprop/backends/numpy_ref/backend.py @@ -653,13 +653,9 @@ def __init__( def trial(self, z: float | None = None, dz: float | None = None) -> None: """Take one trial step and keep its end state for :meth:`field`. - Parameters - ---------- - z : float or None, optional - Where the trial starts, m; the loaded position by default. - dz : float or None, optional - Its length, m, positive; the problem's ``dz_init`` by default, or the - scheduled step at the loaded position for the low-storage march. + - ``z``: where the trial starts, m; the loaded position by default. + - ``dz``: its length, m, positive; the problem's ``dz_init`` by default, or the + scheduled step at the loaded position for the low-storage march. """ stepper = self._backend.request.stepper start = self._z if z is None else float(z) @@ -680,18 +676,11 @@ def field(self) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: The trial's state after the accepted-step boundary treatments (the band mask, and the split-step absorber where it runs). A trial is held beside the loaded state, so finishing it leaves the loaded state alone, and no monitor is bound, - so the finish takes no split sums. - - Returns - ------- - numpy.ndarray - An owning copy, internal units and the FFT convention, shape - ``(n_modes, n_pol, n_omega)``. + so the finish takes no split sums. Refused for the low-storage march, and with + no trial since the last read-back. - Raises - ------ - BackendError - For the low-storage march, or with no trial since the last read-back. + - Returns: an owning copy, internal units and the FFT convention, shape + ``(n_modes, n_pol, n_omega)``. """ if self._low_storage: msg = ( From 19e1059642c4e5dfb0fa33d76584b03dd2ffc66c Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 05:18:57 +0000 Subject: [PATCH 07/14] docs(backends): mend cross-references the restructure split or left stale Co-Authored-By: Claude Opus 5.5 --- src/solprop/backends/engines.py | 8 ++++---- src/solprop/backends/host/runge_kutta.py | 12 ++++++------ src/solprop/backends/host/session.py | 7 ++++--- src/solprop/backends/numpy_ref/backend.py | 11 +++++++---- src/solprop/backends/numpy_ref/dense.py | 5 +++-- src/solprop/backends/numpy_ref/multistep.py | 2 +- 6 files changed, 25 insertions(+), 20 deletions(-) diff --git a/src/solprop/backends/engines.py b/src/solprop/backends/engines.py index 8de004f78..98d8715b4 100644 --- a/src/solprop/backends/engines.py +++ b/src/solprop/backends/engines.py @@ -10,10 +10,10 @@ included: :class:`RungeKuttaEngine` is ``rk::Engine`` (``native/include/solprop_native/rk_march.hpp``), which the low-storage step implements too, and :class:`AdamsEngine` is ``march::Engine`` -(``native/include/solprop_native/adams_march.hpp``). They are the target the -reference's engines take in SEP 52's phase 3; until then its Adams march reads -:class:`solprop.backends.numpy_ref.multistep.AdamsEngine` and its low-storage march -:class:`solprop.backends.low_storage.LowStorageEngine`. +(``native/include/solprop_native/adams_march.hpp``). The reference's engines are +:class:`~solprop.backends.numpy_ref.engines.NumpyRungeKutta`, the low-storage step +:class:`~solprop.backends.low_storage.HostLowStorage` and the Adams history +:class:`~solprop.backends.numpy_ref.multistep.HostHistory`. **The commit contract.** diff --git a/src/solprop/backends/host/runge_kutta.py b/src/solprop/backends/host/runge_kutta.py index 0f65cd9a1..de60980bd 100644 --- a/src/solprop/backends/host/runge_kutta.py +++ b/src/solprop/backends/host/runge_kutta.py @@ -4,12 +4,12 @@ """The reference's Runge-Kutta march, adaptive and replayed (SEP 45, SEP 52). -:class:`RungeKuttaMarch` holds the march's state (:class:`~solprop.backends.host. -marches.MarchState`) and makes its decisions with :mod:`solprop.backends.rk_core`'s -functions of one policy record; every state-sized operation is its engine's -(:class:`~solprop.backends.engines.RungeKuttaEngine`). It is the counterpart of -native's ``rk_march.cpp``, whose decisions on identical inputs are its own (the -decision traces of ``tests/backends``). +:class:`RungeKuttaMarch` holds the march's state +(:class:`~solprop.backends.host.marches.MarchState`) and makes its decisions with +:mod:`solprop.backends.rk_core`'s functions of one policy record; every state-sized +operation is its engine's (:class:`~solprop.backends.engines.RungeKuttaEngine`). It is +the counterpart of native's ``rk_march.cpp``, whose decisions on identical inputs are +its own (the decision traces of ``tests/backends``). **The controller's state is its own proposal**, never the clipped or stretched step that was executed, and what the history and a rejection see is the norm the proposal diff --git a/src/solprop/backends/host/session.py b/src/solprop/backends/host/session.py index a0e4a398f..c78d19c3d 100644 --- a/src/solprop/backends/host/session.py +++ b/src/solprop/backends/host/session.py @@ -20,9 +20,10 @@ **Boundary warnings are barriers.** The monitor's and the edge's warnings go into a sink (:attr:`solprop.monitor.BoundaryMonitor.sink`) rather than being issued where they arise, and each is reported, in order, as a ``WARNING`` barrier event at the committed -endpoint it arose at, whose consumer emits it (:func:`~solprop.backends.events. -emit_warning`): its filters may raise it, which fails the run there. Once allowed, the -next advance does the rest of that point's work, once, as native's session does. +endpoint it arose at, whose consumer emits it +(:func:`~solprop.backends.events.emit_warning`): its filters may raise it, which +fails the run there. Once allowed, the next advance does the rest of that point's work, +once, as native's session does. :class:`HostPrepared` is the prepared execution (SEP 47 section 5.2) a reference backend returns from ``prepare``; each of its starts opens one session. The session composes the diff --git a/src/solprop/backends/numpy_ref/backend.py b/src/solprop/backends/numpy_ref/backend.py index b108def01..d4ef1d685 100644 --- a/src/solprop/backends/numpy_ref/backend.py +++ b/src/solprop/backends/numpy_ref/backend.py @@ -7,8 +7,9 @@ One :class:`NumpyRefBackend` steps one problem in plain NumPy. It builds the workspace that holds the state and does every state-sized operation (:class:`~solprop.backends.numpy_ref.workspace.NumpyWorkspace`) and, for each run, the -engines a march asks of it (:class:`~solprop.backends.numpy_ref.engines. -NumpyRungeKutta`, :class:`~solprop.backends.numpy_ref.multistep.HostHistory`, +engines a march asks of it +(:class:`~solprop.backends.numpy_ref.engines.NumpyRungeKutta`, +:class:`~solprop.backends.numpy_ref.multistep.HostHistory`, :class:`~solprop.backends.low_storage.HostLowStorage`), the run's march and its dense output (:meth:`NumpyRefBackend.method`); it keeps ``prepare``, the metadata, the memory ledger, the timing probe and ``close``. Every run is the reference's own @@ -592,8 +593,10 @@ def edge_memory(self, space: object) -> int: def memory_ledger(self) -> dict[str, int]: """Return the size of every buffer the backend works in, in bytes. - The workspace's (:meth:`NumpyWorkspace.memory_ledger`): what one step has - resident at its peak, every buffer named even when it is empty. + The workspace's + (:meth:`~solprop.backends.numpy_ref.workspace.NumpyWorkspace.memory_ledger`): + what one step has resident at its peak, every buffer named even when it is + empty. Returns ------- diff --git a/src/solprop/backends/numpy_ref/dense.py b/src/solprop/backends/numpy_ref/dense.py index a11dcfa20..5b593f3d3 100644 --- a/src/solprop/backends/numpy_ref/dense.py +++ b/src/solprop/backends/numpy_ref/dense.py @@ -152,8 +152,9 @@ class AdamsDense: engine : solprop.backends.numpy_ref.multistep.HostHistory The engine that kept the step's samples. march : solprop.backends.host.adams.HostAdamsMarch - The march whose record of the step (:attr:`~HostAdamsMarch.last_step`) gives - the weights' nodes and the carrier rotations. + The march whose record of the step + (:attr:`~solprop.backends.host.adams.HostAdamsMarch.last_step`) gives the + weights' nodes and the carrier rotations. """ def __init__( diff --git a/src/solprop/backends/numpy_ref/multistep.py b/src/solprop/backends/numpy_ref/multistep.py index 70ca24040..1f7f0e65b 100644 --- a/src/solprop/backends/numpy_ref/multistep.py +++ b/src/solprop/backends/numpy_ref/multistep.py @@ -1512,7 +1512,7 @@ def __init__( ) self._trial_weights: np.ndarray | None = None self.dense: Any = None - self.exponential_dense: _ExponentialStep | None = None + self.exponential_dense: Any = None self._fused_trial: _FusedTrial | None = None self._exponential_trial: _ExponentialTrial | None = None # SEP 35: the carrier phase each exponential trial removes from the samples From 8564397301c55cc248f5b35456f2b2f699629423 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 05:29:41 +0000 Subject: [PATCH 08/14] test: port the tests the broad sweep found on the session's structure Native-against-reference warning tests now compare both sessions' warning barriers; the march loads no engine; the TDSE startup reads the history's rows; the stiffness warning's test holds the plane's replay to one march call. Co-Authored-By: Claude Opus 5.5 --- tests/backends/test_host_marches.py | 15 +++----- tests/backends/test_low_storage.py | 5 ++- tests/backends/test_tdse_native.py | 2 +- tests/driver/test_plasma_band_propagation.py | 2 +- tests/sessions/test_native_session_monitor.py | 36 +++++++++---------- .../test_native_session_transverse.py | 17 +++++---- 6 files changed, 35 insertions(+), 42 deletions(-) diff --git a/tests/backends/test_host_marches.py b/tests/backends/test_host_marches.py index 70d97bfd5..a20c4bf51 100644 --- a/tests/backends/test_host_marches.py +++ b/tests/backends/test_host_marches.py @@ -59,9 +59,6 @@ def stepped(self) -> None: def natural_stop(self, target: float) -> bool: return bool(self.natural_every) and self.stepped_count % self.natural_every == 0 - def natural_stop_due(self, target: float) -> bool: - return False - class Engine: """A Runge-Kutta engine that scores trials from a list and records its calls.""" @@ -96,10 +93,6 @@ def extend(self, z: float, dz: float) -> None: def reading(self) -> Any: raise NotImplementedError - def reset(self) -> None: - self.calls.append(("reset",)) - self.flight = False - def _policy() -> RungeKuttaPolicy: return RungeKuttaPolicy( @@ -131,7 +124,9 @@ def test_the_runge_kutta_march_keeps_its_state_and_asks_in_order(): engine, host = Engine([2.0, 0.5]), Host() march = RungeKuttaMarch(engine, _policy(), host, schedule=None, proposal=0.25) march.load(0.0, 0.25, 0) - assert engine.calls == [("reset",)] + # A load starts the march's own state afresh and asks nothing of the engine: each + # run builds its engine afresh (SEP 52). + assert engine.calls == [] march.march_to(0.25) assert march.state.z == 0.25 assert len(march.state.norms) >= 1 @@ -141,9 +136,9 @@ def test_the_runge_kutta_march_keeps_its_state_and_asks_in_order(): assert kinds[:4] == ["poll", "cap", "record", "poll"] assert host.calls[2] == ("record", 0.25, False) assert kinds[4:8] == ["cap", "record", "absorb", "stepped"] - assert [call[0] for call in engine.calls[1:4]] == ["trial", "trial", "accept"] + assert [call[0] for call in engine.calls[:3]] == ["trial", "trial", "accept"] # What the accept reported is what the session absorbs. - assert host.records[0].removed == 4.0 + assert host.records[0].removed == 3.0 def test_a_replayed_runge_kutta_step_that_diverges_commits_nothing(): diff --git a/tests/backends/test_low_storage.py b/tests/backends/test_low_storage.py index 6f520ac5f..aec077eea 100644 --- a/tests/backends/test_low_storage.py +++ b/tests/backends/test_low_storage.py @@ -61,6 +61,7 @@ from solprop.backends.numpy_ref.workspace import NumpyWorkspace from solprop.backends.registry import resolve_name from solprop.backends.session import Start +from solprop.backends.session_core import YieldDue from solprop.boundaries import absorber from solprop.constants import C from solprop.driver.scaffold import gnlse_source @@ -1577,8 +1578,10 @@ def stiff(engine, z, dz): engine.stiffness = 3.0 return squared - # The session's own engine, built for its run. + # The session's own engine, built for its run; no bounded yield splits the plane's + # replay into two march calls, each of which warns once. monkeypatch.setattr(HostLowStorage, "trial", stiff) + monkeypatch.setattr(YieldDue, "__call__", lambda self: False) with caplog.at_level(logging.WARNING, logger="solprop.backends.host.low_storage"): result = session_run( backend, problem, bare(run_request), export=None, observations=2 diff --git a/tests/backends/test_tdse_native.py b/tests/backends/test_tdse_native.py index 5257ab96c..869e51dd3 100644 --- a/tests/backends/test_tdse_native.py +++ b/tests/backends/test_tdse_native.py @@ -322,7 +322,7 @@ def recording_project(*args, **kwargs): def recording_start(self, z): start(self, z) - seen.setdefault("row", np.array(self.value(0)).reshape(-1)) + seen.setdefault("row", np.array(self._store[0]).reshape(-1)) seen.setdefault("history", self) with monkeypatch.context() as patch: diff --git a/tests/driver/test_plasma_band_propagation.py b/tests/driver/test_plasma_band_propagation.py index bc26f400e..20d2550a3 100644 --- a/tests/driver/test_plasma_band_propagation.py +++ b/tests/driver/test_plasma_band_propagation.py @@ -303,7 +303,7 @@ def test_the_reference_s_plasma_statistics_refuse_a_problem_with_no_plasma( state = simulation._field0 with pytest.raises(BackendError, match=message): cast("NumpyRefBackend", backend).workspace._backend_statistics( - (name,), state, cast("NumpyRefBackend", backend)._z + (name,), state, float(problem.initial.z) ) finally: backend.close() diff --git a/tests/sessions/test_native_session_monitor.py b/tests/sessions/test_native_session_monitor.py index c768e3ce0..f825b443a 100644 --- a/tests/sessions/test_native_session_monitor.py +++ b/tests/sessions/test_native_session_monitor.py @@ -47,7 +47,6 @@ trace, ) from solprop.backends.events import ( - Eligibility, EventBatch, ObservationReady, Outcome, @@ -323,18 +322,17 @@ def test_a_walking_pulse_warns_and_stops_where_the_reference_does(march, scheme) @pytest.mark.parametrize("march", sorted(MARCHES)) def test_a_raised_warning_ends_the_run_at_its_endpoint(march): + # Both sessions report the warning as a barrier at its committed endpoint, whose + # filters raise it there (SEP 52 section 5.1). reference, native = _both( lambda: walker(0.47e-12, integrator=MARCHES[march]()), error=True ) - terminal = reference.run.terminal - assert terminal.outcome is Outcome.FAILED - assert isinstance(terminal.error, BoundaryWarning) - assert native.raised is not None - z, warning = native.raised - assert terminal.error is not None - assert type(warning) is type(terminal.error) - assert masked(str(warning)) == masked(str(terminal.error)) - assert z == pytest.approx(terminal.z, rel=TERMINAL_RTOL) + assert reference.raised is not None and native.raised is not None + (expected_z, expected), (z, warning) = reference.raised, native.raised + assert isinstance(expected, BoundaryWarning) + assert type(warning) is type(expected) + assert masked(str(warning)) == masked(str(expected)) + assert z == pytest.approx(expected_z, rel=TERMINAL_RTOL) # The observations before it are the reference's. assert [(one.kind, one.plane_index) for one in native.run.observations] == [ (one.kind, one.plane_index) for one in reference.run.observations @@ -390,16 +388,14 @@ def test_the_final_removal_warns_before_completion(): def test_a_raised_final_warning_is_a_failure_with_its_field(): check = BoundaryCheck(budget=1e-3, stop_factor=1e3) 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) - assert masked(str(native.raised[1])) == masked(str(terminal.error)) - assert native.raised[0] == pytest.approx(terminal.z, rel=TERMINAL_RTOL) + # The final check runs at the run's end, after its last plane: both sessions report + # it as a barrier there, whose ticket exports the committed state for a checkpoint + # (`_serve` exports it before the warning is raised). + assert reference.raised is not None and native.raised is not None + expected = reference.raised[1] + assert type(native.raised[1]) is type(expected) + assert masked(str(native.raised[1])) == masked(str(expected)) + assert native.raised[0] == pytest.approx(reference.raised[0], rel=TERMINAL_RTOL) def test_a_replay_the_light_outgrows_is_refused_where_the_reference_refuses(): diff --git a/tests/sessions/test_native_session_transverse.py b/tests/sessions/test_native_session_transverse.py index 1bb044acc..f92e1e381 100644 --- a/tests/sessions/test_native_session_transverse.py +++ b/tests/sessions/test_native_session_transverse.py @@ -303,16 +303,15 @@ def test_a_raised_warning_ends_the_run_at_its_endpoint(march): def simulation() -> Simulation: return packet_run(REREVIEW, integrator=MARCHES[march](), backend="native") + # Both sessions report the edge's warning as a barrier at its committed endpoint, + # whose filters raise it there (SEP 52 section 5.1). reference, native = _both(simulation, error=True) - terminal = reference.run.terminal - assert terminal.outcome is Outcome.FAILED - assert isinstance(terminal.error, BoundaryWarning) - assert native.raised is not None - z, warning = native.raised - assert terminal.error is not None - assert type(warning) is type(terminal.error) - assert masked(str(warning)) == masked(str(terminal.error)) - assert z == pytest.approx(terminal.z, rel=PLANE_RTOL) + assert reference.raised is not None and native.raised is not None + (expected_z, expected), (z, warning) = reference.raised, native.raised + assert isinstance(expected, BoundaryWarning) + assert type(warning) is type(expected) + assert masked(str(warning)) == masked(str(expected)) + assert z == pytest.approx(expected_z, rel=PLANE_RTOL) assert [(one.kind, one.plane_index) for one in native.run.observations] == [ (one.kind, one.plane_index) for one in reference.run.observations ] From 8c3f93e7d9408f3160030db9729bdc4804708c0d Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 05:44:20 +0000 Subject: [PATCH 09/14] docs(sep-0052): report milestone 3 (the reference restructured) [skip ci] Co-Authored-By: Claude Opus 5.5 --- docs/dev/seps/sep-0052-backend-shape.md | 89 +++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/docs/dev/seps/sep-0052-backend-shape.md b/docs/dev/seps/sep-0052-backend-shape.md index 78aa04b23..98be15639 100644 --- a/docs/dev/seps/sep-0052-backend-shape.md +++ b/docs/dev/seps/sep-0052-backend-shape.md @@ -1221,6 +1221,94 @@ monitor resumes through its own `BoundaryMonitor` path: all three go with the dr private-import count is at its cap (87), because `records.py` reads two private monitor names. +### Milestone 3 (the rest of phase 3) — 2026-11-16 + +Branch `feature/sep-0052-backend-shape-p3`, stacked on milestone 2, by Opus 5.5 (AI) for +John Travers. Two steps were developed by AI agents one after the other and merged: +the workspace, engines and marches (`56101a60`, `48436c62`, `f2db1084`), then the session +and the deletion of `HostDriver` (`8afa8465`, `2ba96039`, `090c6ae7`, `19e10596`, +`85643973`). + +**Delivered.** + +- *`NumpyWorkspace`* (`numpy_ref/workspace.py`) holds the state and every state-sized + operation, with no march state: load and install, mask, finish (which takes the split + collar's sums on the masked field before the temporal split, where `_finish` took them, + and returns them in an `AcceptRecord`), the stage bundles and scalars, the source, the + propagator, the coupled block, the residual, the flow actions, the error norm, the + statistics, the boundary and edge readings, the quadrature reading, the noise, the TDSE + ledger operations, the metadata and the memory ledger. The `_adams_*` hooks became + march-neutral operations (the naming item of #344). `numpy_ref/backend.py` went from + about 2,920 lines to about 550. +- *Engines* implementing §5.2: `NumpyRungeKutta` (`numpy_ref/engines.py`) keeps its + stages and trial and commits only at `accept`; `HostLowStorage` is the same + `RungeKuttaEngine`, with the destructive trial, the in-flight interval and the stiffness + in its `AcceptRecord`; `HostHistory` implements the new `AdamsEngine`, with the retained + history passed to `accept`, `step_carrier` and the TDSE reservation as + `begin_attempt`/`end_attempt`. The old `AdamsEngine` and `LowStorageEngine` protocols + are deleted. +- *Marches that own their state* (`host/marches.py`, `host/runge_kutta.py`, `host/adams.py`, + `host/low_storage.py`): the new `RungeKuttaMarch` (adaptive and replayed) and the + rewritten Adams and low-storage marches hold position, proposal, schedule index, + accepted norms and ledgers in their own state, and write no other object's fields. The + Adams attempt follows native's: an accepted attempt ends before its floor is raised. +- *`HostSession` owns the schedule* (`host/session.py`), in `session.cpp`'s order: planes, + step planes, natural stops, yields, the snapshot latch, halts, the dense hold and + observation (`numpy_ref/dense.py`, `RungeKuttaDense` and `AdamsDense`, the exponential + observation applying the step's carrier rotations), periodic rows, the Adams rows + (`AdamsRows`), the load and noise, the monitor and edge checks with the split sums + accumulated from `AcceptRecord`s under the pinned rules, the quadrature report, events + and exports. The engines lost `reset`, `hold`, `restore`, `observe`, `value` and their + snapshot members; the backend builds a fresh march and engines per run. +- *Deleted:* `host/driver.py`, `HostStepping`, `stepping()` and the three periodic + statistics storage hooks. +- *Boundary warnings are `WARNING` barrier events* on the reference too: the monitor and + the transverse edge take a sink, and warn directly only when used on their own. The + service loop's `HostSession` special case is gone; both sessions report through + `execution_record`. Warnings-as-errors, the warning text and the saved field are + unchanged, so there is no changelog fragment. +- *Tests:* about 135 test files changed, ported to sessions, the workspace and engines + (`builders.load_reference`, `builders.reference_trial`), or scripted engines, which now + host the real marches in `HostScriptedDriver`, `HostSessionScript`, `ScriptedSession` + and both trace harnesses; `native_trace_marches.py` is unchanged. New: + `tests/backends/test_numpy_engines.py` (the engine-contract cases, the split sums before + the split, the accumulation rules) and `tests/backends/test_host_marches.py`. Deleted, + each because its subject no longer exists: the inheritance and stepping-seam tests, the + storage-hook and reporter tests, the default-hook refusals, three unreachable-target + guards (a session's targets are its validated planes), a duplicate launch-plane test, + and the `_collar_can_rest` assertion. `HOST_SURFACE` in `test_driver.py` became + `metadata` and `restore_call_ledgers`. +- *Docs:* `backends.md` (§1, the marches as one shape with two implementations, the + warnings), `architecture.md` §9, `kernel-contract.md` §8 and §§11–12, `stepper.md`, + `structure.md`, `algorithms.md`, `testing.md` (scripted engines), and the regenerated + structure figures. + +**Numbers.** No change. After each step, the `numpy_ref` corpus arrays and records were +recorded from the base and the new tree on one build and one thread: all 13 cases are +bitwise identical, `capillary_adams_carrier` included. The engine keeping its own trial, +the expected first change of §4, changed no bits, so nothing was measured or accepted +under §4 and native has nothing to follow. The decision traces, the split collar's rules +and the deep-collar residue test pass unchanged; no corpus was regenerated. + +**Verification.** On an Apple M5 Max: the affected modules at four workers, the +conformance and trace suites, doctests, ruff, basedpyright, the docstring check and the +size check. On a 32-core AMD EPYC 7763 node of a Slurm cluster, the whole of +`tests/backends`, `tests/driver`, `tests/sessions`, `tests/output`, `tests/stepper` and +`native/tests`, on the base and on each step: every failure on the final tree was also a +failure on the base, and those four were fixed on milestone 2. After merging, the corpus, +rules, traces, frozen surfaces, records, protocols, monitor, identity, snapshot and native +session modules were rerun together (565 passed). + +**Cost** (`poe size --all`). `backends` 24,208 → 24,862 lines, of which public docstrings +rise by about 840, because the workspace's operations are now public and documented, and +private docstrings fall by about 590; `host/driver.py` (2,530 lines) is gone, +`host/session.py` is 2,123 lines and `numpy_ref/dense.py` 320. Total 267,882 → 268,538. +Tests: about 3,300 lines added and 2,000 removed. + +**Handoff.** Milestone 4 adds the engine-level parity tests over both backends' engines, +now that the reference has them. The two new refusals in the session (`_Held.restore`, +the rows install) are covered only if CI's coverage lane says so. + ## Part III — History - 2026-11-15: Drafted, from a review of the native binding's use in production and of the @@ -1238,6 +1326,7 @@ names. `feature/sep-0052-backend-shape-p1`. - 2026-11-16: Milestone 1 (phases 0–1) reported in Part II. - 2026-11-16: Milestone 2 (phase 2 and the axis removal) reported in Part II. +- 2026-11-16: Milestone 3 (the reference restructured, `HostDriver` deleted) reported in Part II. ### AI review — 2026-11-15 From 2b8cd6d1746d40c4eccac089788ee9cede0dac70 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 05:44:59 +0000 Subject: [PATCH 10/14] docs(sep-0052): link milestone 3's pull request Co-Authored-By: Claude Opus 5.5 --- docs/dev/seps/sep-0052-backend-shape.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/dev/seps/sep-0052-backend-shape.md b/docs/dev/seps/sep-0052-backend-shape.md index 98be15639..8879d08a9 100644 --- a/docs/dev/seps/sep-0052-backend-shape.md +++ b/docs/dev/seps/sep-0052-backend-shape.md @@ -15,7 +15,7 @@ | **Requires** | SEPs 25, 39, 45 and 47 | | **Supersedes** | — | | **Superseded-by** | — | -| **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` ([#854](https://github.com/LupoLab/solprop/pull/854)); (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 | +| **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` ([#854](https://github.com/LupoLab/solprop/pull/854)); (3) the rest of phase 3, `feature/sep-0052-backend-shape-p3` ([#858](https://github.com/LupoLab/solprop/pull/858)); (4) phases 4–5, `feature/sep-0052-backend-shape-p4`; started 2026-11-15 | | **Manual pages** | — | ## Part I — Proposal @@ -1223,8 +1223,9 @@ names. ### Milestone 3 (the rest of phase 3) — 2026-11-16 -Branch `feature/sep-0052-backend-shape-p3`, stacked on milestone 2, by Opus 5.5 (AI) for -John Travers. Two steps were developed by AI agents one after the other and merged: +Branch `feature/sep-0052-backend-shape-p3` +([#858](https://github.com/LupoLab/solprop/pull/858)), stacked on milestone 2, by Opus 5.5 +(AI) for John Travers. Two steps were developed by AI agents one after the other and merged: the workspace, engines and marches (`56101a60`, `48436c62`, `f2db1084`), then the session and the deletion of `HostDriver` (`8afa8465`, `2ba96039`, `090c6ae7`, `19e10596`, `85643973`). From 95bcb16bb9c5e924e71d3a6710818650b3f90c39 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 07:03:49 +0000 Subject: [PATCH 11/14] fix(sep-0052): the last step-driver imports, and yield-proof session tests test_transverse_monitor reads the clean launch columns from the workspace. The backend's doctest lists the barriers and the field-free test's plane advance is unbounded: a bounded yield on a slow host adds a Progress batch before a plane, on the reference before and after this restructure and on native alike. Stale step-driver names in docstrings, and two long lines. Co-Authored-By: Claude Opus 5.5 --- benchmarks/worker.py | 4 +--- docs/dev/figures/build.py | 6 ++---- src/solprop/backends/host/session.py | 6 +++--- src/solprop/backends/numpy_ref/backend.py | 9 +++++++-- src/solprop/translate/problem.py | 4 ++-- tests/backends/native_trace_marches.py | 6 +++--- tests/driver/test_field_free_planes.py | 9 +++++++-- tests/sessions/runs.py | 4 ++-- tests/test_transverse_monitor.py | 2 +- 9 files changed, 28 insertions(+), 22 deletions(-) diff --git a/benchmarks/worker.py b/benchmarks/worker.py index 4f55ea173..597548da3 100644 --- a/benchmarks/worker.py +++ b/benchmarks/worker.py @@ -227,9 +227,7 @@ def __init__(self, engine: Backend) -> None: self.calls: int | None = None def _load(self, *args: object, **keywords: object) -> object: - loaded = getattr(type(self._owner), self._name)( - self._owner, *args, **keywords - ) + loaded = getattr(type(self._owner), self._name)(self._owner, *args, **keywords) self.calls = source_calls(self._engine) self.ended = time.perf_counter_ns() return loaded diff --git a/docs/dev/figures/build.py b/docs/dev/figures/build.py index 4d64af178..5d1880beb 100644 --- a/docs/dev/figures/build.py +++ b/docs/dev/figures/build.py @@ -2555,7 +2555,7 @@ def _step_panel( BACKEND_OVERRIDES = ("NumpyWorkspace", "engines", "marches", "dense output") -"""What the reference backend supplies to `HostSession`, and nothing else of the loop.""" +"""What the reference backend supplies to `HostSession`; nothing else of the loop.""" DEVICE_SLOT = ( "solprop-native distribution, native/", @@ -2634,9 +2634,7 @@ def backends() -> drawsvg.Drawing: ) drawing = _canvas(height) - _header( - drawing, "One seam, a session, and the backends behind them", subtitle - ) + _header(drawing, "One seam, a session, and the backends behind them", subtitle) y = top _table( diff --git a/src/solprop/backends/host/session.py b/src/solprop/backends/host/session.py index c78d19c3d..e0b423307 100644 --- a/src/solprop/backends/host/session.py +++ b/src/solprop/backends/host/session.py @@ -1207,9 +1207,9 @@ def _endpoint_done(self, stop: object) -> EventBatch | None: def _propagate(self, target: float) -> StepSummary: """Step the march towards `target`, landing on it exactly. - As the step driver's ``propagate_to``: the plane's per-step latches start - afresh unless a halt or a barrier returned the last march short of it, and a - plane the march stepped across is observed inside its last step. + The plane's per-step latches start afresh unless a halt or a barrier returned + the last march short of it, and a plane the march stepped across is observed + inside its last step. """ if not self._progress_started: # Announced at the first march, the first moment the run costs anything. diff --git a/src/solprop/backends/numpy_ref/backend.py b/src/solprop/backends/numpy_ref/backend.py index d4ef1d685..af6f3ce59 100644 --- a/src/solprop/backends/numpy_ref/backend.py +++ b/src/solprop/backends/numpy_ref/backend.py @@ -160,13 +160,18 @@ class NumpyRefBackend: ... controller=PIController(rtol=1e-8, atol=1e-16), ... save_planes=[0.01], dz_max=0.01, dz_init=1e-3, ... density=1.0, shock=False, prefactor_index=1.0) + >>> from solprop.backends.events import Progress >>> from solprop.backends.session import Start >>> backend = NumpyRefBackend(problem, request, grid=grid) >>> session = backend.prepare(problem, request).start(Start.entrance(problem)) - >>> kinds = [] + >>> kinds = [] # the barriers; a bounded yield on a slow host adds a Progress >>> while not session.finished: ... batch = session.advance() - ... kinds += [type(event).__name__ for event in batch.events] + ... kinds += [ + ... type(event).__name__ + ... for event in batch.events + ... if not isinstance(event, Progress) + ... ] ... session.acknowledge(batch.receipt) >>> kinds ['ObservationReady', 'ObservationReady', 'Terminal'] diff --git a/src/solprop/translate/problem.py b/src/solprop/translate/problem.py index 6390caf08..7bc35856a 100644 --- a/src/solprop/translate/problem.py +++ b/src/solprop/translate/problem.py @@ -562,8 +562,8 @@ class StepperSettings: landed on either way. step_planes : int A positive ``k`` also saves the end of every ``k``-th accepted step: the - march's ``propagate_to`` returns there, short of its target, and is called - again (SEP 14 phase 3). ``0`` saves the requested planes only. + march returns to its session there, short of its target, and marches on + (SEP 14 phase 3). ``0`` saves the requested planes only. Raises ------ diff --git a/tests/backends/native_trace_marches.py b/tests/backends/native_trace_marches.py index 63b1a69ff..aedddc64a 100644 --- a/tests/backends/native_trace_marches.py +++ b/tests/backends/native_trace_marches.py @@ -506,8 +506,8 @@ def march_to(self, target: float) -> None: def replay_to(self, schedule: FixedSchedule, target: float) -> None: """Replay the contract's schedule to `target` on the native march. - ``HostDriver._replay_to``, a call of steps at a time: the steps as given, never - rejected, the edges hit exactly. + ``RungeKuttaMarch.replay_to``, a call of steps at a time: the steps as given, + never rejected, the edges hit exactly. Parameters ---------- @@ -671,7 +671,7 @@ def _finish_crossing( ) -> bool: """Finish the accepted step across an interpolated plane, as the reference. - `HostDriver._march_to`'s acceptance, line for line: the accepted-step hook + `RungeKuttaMarch.march_to`'s acceptance, line for line: the accepted-step hook `_record` makes, the step's extension from the state before it, the finish and the commit, the norm, the start-up rule, the proposal, the statistics and the natural stop. The native march returned the step accepted and unfinished. diff --git a/tests/driver/test_field_free_planes.py b/tests/driver/test_field_free_planes.py index 75e7ddbff..ca8e10075 100644 --- a/tests/driver/test_field_free_planes.py +++ b/tests/driver/test_field_free_planes.py @@ -14,6 +14,7 @@ import dataclasses import logging +import math from typing import cast import h5py @@ -444,11 +445,15 @@ class _NoRetention(MemoryOutput): def _first_plane(owner, problem, run_request, start): - """Start the reference's session, acknowledge its launch, return the first plane.""" + """Start the reference's session, acknowledge its launch, return the first plane. + + The plane's advance is unbounded, so that no yield on a slow host splits its march + into a progress batch before the plane's. + """ session = owner.prepare(problem, run_request).start(start, owns=False) launch = session.advance() session.acknowledge(launch.receipt) - batch = session.advance() + batch = session.advance(work_limit=1 << 30, deadline=math.inf) return session, batch diff --git a/tests/sessions/runs.py b/tests/sessions/runs.py index cea58d518..7181b7b72 100644 --- a/tests/sessions/runs.py +++ b/tests/sessions/runs.py @@ -4,8 +4,8 @@ """Run a constructed backend through its own session, for the tests outside the suite. -SEP 47 phase 5 retired the native backend's step-driver calls (``set_initial``, -``propagate_to``, ``observe``, ``stats``): every run starts through +SEP 47 phase 5 retired the native backend's step-driver calls, and SEP 52 the +reference's: every run starts through :func:`solprop.backends.sessions.start_session`, which opens the native session for a native backend and the reference's own :class:`~solprop.backends.host.session.HostSession` for ``numpy_ref``, so one call diff --git a/tests/test_transverse_monitor.py b/tests/test_transverse_monitor.py index 89cce5a40..064be7199 100644 --- a/tests/test_transverse_monitor.py +++ b/tests/test_transverse_monitor.py @@ -20,7 +20,7 @@ import numpy as np import pytest -from solprop.backends.host import driver as host +from solprop.backends.numpy_ref import workspace as host from solprop.backends.registry import available from solprop.boundaries import SpatialAbsorber, SpatialAbsorberDesign from solprop.driver import Simulation From 9dab470596adc4a2953627a7575a65284e1535ff Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 07:27:07 +0000 Subject: [PATCH 12/14] test: narrow the launch field before its use, for the type check [skip ci] Co-Authored-By: Claude Opus 5.5 --- tests/sessions/test_conformance.py | 1 + 1 file changed, 1 insertion(+) diff --git a/tests/sessions/test_conformance.py b/tests/sessions/test_conformance.py index f35e14a75..8fcc70b5b 100644 --- a/tests/sessions/test_conformance.py +++ b/tests/sessions/test_conformance.py @@ -848,6 +848,7 @@ def test_a_warning_raised_as_an_error_fails_at_its_committed_endpoint(start_scri with pytest.raises(ScriptedWarning, match="accepted step 6"): emit_warning(event) # The launch's field after `warn_at` doublings, exactly (FACTOR is a power of two). + assert launched is not None np.testing.assert_array_equal(held, launched * FACTOR**warn_at) session.close() From 21bab7ac6077d260391f370e54427584b2a03afc Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 07:55:04 +0000 Subject: [PATCH 13/14] test(sep-0052): cover the reference's refusals; delete what the session made dead Tests reach a backend closed under its session, a start whose plane lies behind it, a probe start of the wrong shape, the dense outputs' refusals before a step, the engine's stages before a trial, each engine's protocol reading and the low-storage extend refusal, and a low-storage replay that runs out. A field-free drain no longer needs a loaded, open backend, so the closed backend's failure reaches its terminal event. Removed as dead: adams_core.quiet_capped (the session's step_cap), the low-storage march's snapshot, the workspace's quadrature property, and the target guard's finiteness and table-end checks, which the validated request already makes. Co-Authored-By: Claude Opus 5.5 --- src/solprop/backends/adams_core.py | 26 ---- src/solprop/backends/host/low_storage.py | 8 -- src/solprop/backends/host/session.py | 27 ++-- src/solprop/backends/numpy_ref/workspace.py | 5 - tests/backends/test_host_marches.py | 13 ++ tests/backends/test_reference_refusals.py | 133 ++++++++++++++++++++ 6 files changed, 159 insertions(+), 53 deletions(-) create mode 100644 tests/backends/test_reference_refusals.py diff --git a/src/solprop/backends/adams_core.py b/src/solprop/backends/adams_core.py index 1950d81cb..1bd2ce86c 100644 --- a/src/solprop/backends/adams_core.py +++ b/src/solprop/backends/adams_core.py @@ -39,7 +39,6 @@ "factor", "next_landing", "order_weight", - "quiet_capped", "rejection", "replay_kink", "stable_factor", @@ -388,31 +387,6 @@ def carrier_capped( return (end - z) * (policy.carrier_cap / phase) -def quiet_capped(proposal: float, *, quiet: bool, interval: float | None) -> float: - """Return the proposal, held to the monitor's interval while the collar rests. - - The rule of :meth:`solprop.backends.host.session.HostSession.cap`, with the - collar's state and the monitor's interval passed in. - - Parameters - ---------- - proposal : float - The controller's proposal, m. - quiet : bool - Whether the stages leave a quiet collar out. - interval : float or None - The monitor's interval, m, or ``None`` without a monitor. - - Returns - ------- - float - The proposal, or the interval while the collar is left out, m. - """ - if not quiet or interval is None: - return proposal - return min(proposal, interval) - - def collar_reentry( policy: MarchPolicy, proposal: float, diff --git a/src/solprop/backends/host/low_storage.py b/src/solprop/backends/host/low_storage.py index 18d706d79..039a20568 100644 --- a/src/solprop/backends/host/low_storage.py +++ b/src/solprop/backends/host/low_storage.py @@ -126,14 +126,6 @@ def load(self, z: float, proposal: float, cursor: int) -> None: # Its count is the loaded run's, as the Adams ledger is (SEP 22 4.7). self.source_evaluations = 0 - def snapshot(self) -> None: - """Return nothing for a resume to continue: the march keeps no history. - - A resume at a schedule edge needs no history and no recycled stage - (SEP 24 section 5), as under ``RungeKutta()``. - """ - return - def refusal(self) -> str | None: """Return why the state cannot be read or advanced, or ``None``. diff --git a/src/solprop/backends/host/session.py b/src/solprop/backends/host/session.py index e0b423307..e7bfe5b45 100644 --- a/src/solprop/backends/host/session.py +++ b/src/solprop/backends/host/session.py @@ -1739,22 +1739,16 @@ def _refuse_in_flight(self) -> None: raise BackendError(in_flight_refusal(self._name, *pending)) def _check_target(self, target: float) -> None: - """Refuse a save plane behind the observed position or outside the table.""" + """Refuse a plane behind the observed position: a start's wrong plane index. + + The planes themselves are the validated request's: finite, increasing and + inside the operator table (`validate_run`). + """ z = self._here() - if not math.isfinite(target): - msg = f"the save plane must be finite, got {target!r}" - raise BackendError(msg) if target < z: msg = ( f"cannot propagate backwards: asked for z = {target:.6g} m from " - f"{z:.6g} m" - ) - raise BackendError(msg) - span = self._problem.linear.z_span - if target > span[1]: - msg = ( - f"z = {target:.6g} m lies beyond the operator table, which covers " - f"[{span[0]:.6g}, {span[1]:.6g}] m" + f"{z:.6g} m; the start's plane index names a plane behind it" ) raise BackendError(msg) @@ -1770,9 +1764,14 @@ def _observe(self, *, field: bool) -> Observation: The field is the workspace's state itself, frozen and held so that an observation takes a view of it without a copy: the next step replaces it. - With ``field=False`` nothing crosses (SEP 22 section 5.1). + With ``field=False`` nothing crosses (SEP 22 section 5.1) and nothing of the + state is read, so a failure's terminal event drains its attempts even when the + failure was the backend's closing; a state left in flight is refused either way. """ - self._require_state() + if field: + self._require_state() + else: + self._refuse_in_flight() history = _history_record(self._history) whole = self._workspace.state if field else None if whole is not None: diff --git a/src/solprop/backends/numpy_ref/workspace.py b/src/solprop/backends/numpy_ref/workspace.py index d4e927334..d01e0d994 100644 --- a/src/solprop/backends/numpy_ref/workspace.py +++ b/src/solprop/backends/numpy_ref/workspace.py @@ -325,11 +325,6 @@ def input_floor(self) -> _State | None: # numpydoc ignore=RT01 """The ``input`` noise draw the state carries (the monitor's floor), or None.""" return self._input_floor - @property - def quadrature(self) -> float: # numpydoc ignore=RT01 - """The quadrature alarm of the plane's last accepted step; NaN without one.""" - return self._alarm - def load( self, field: _State, diff --git a/tests/backends/test_host_marches.py b/tests/backends/test_host_marches.py index a20c4bf51..9d0b47bff 100644 --- a/tests/backends/test_host_marches.py +++ b/tests/backends/test_host_marches.py @@ -188,6 +188,19 @@ def test_the_low_storage_march_hands_the_stiffness_from_the_accept(caplog): assert "stiffness indicator" not in caplog.text +def test_a_low_storage_replay_that_runs_out_says_so(): + engine, host = Engine([]), Host() + schedule = FixedSchedule.uniform(0.0, 0.5, 0.25) + march = HostLowStorageMarch( + engine, LowStorageRungeKutta(), host, schedule=schedule, proposal=0.25 + ) + march.load(0.0, 0.25, 0) + with pytest.raises(BackendError, match="cannot reach z = 1"): + march.advance(1.0) + # Every step of the schedule committed before the refusal. + assert march.state.z == 0.5 + + def test_an_adams_floor_after_a_rejection_keeps_a_failed_release_as_a_note(): from solprop.backends.host.adams import HostAdamsMarch, _Attempt # noqa: PLC0415 diff --git a/tests/backends/test_reference_refusals.py b/tests/backends/test_reference_refusals.py new file mode 100644 index 000000000..9f3ea4085 --- /dev/null +++ b/tests/backends/test_reference_refusals.py @@ -0,0 +1,133 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""The reference's refusals around its session, dense output, probe and engines. + +What a caller can misuse once the session owns the schedule (SEP 52): a backend closed +under an open session, a start whose plane index lies behind it, a probe's start of +the wrong shape, a dense output asked for before it holds a step, an engine's stages +before a trial; and the engines' own members of the protocol (``reading``, the +low-storage ``extend``), which the session does not call. +""" + +import numpy as np +import pytest + +from builders import load_reference +from sessions.executors import entrance, low_storage, soliton, window +from solprop.backends.events import Outcome, Terminal +from solprop.backends.host.adams import HostAdamsMarch +from solprop.backends.host.low_storage import HostLowStorageMarch +from solprop.backends.numpy_ref import NumpyRefBackend +from solprop.backends.numpy_ref.dense import AdamsDense, RungeKuttaDense +from solprop.backends.numpy_ref.engines import NumpyRungeKutta +from solprop.backends.session import Start +from solprop.exceptions import BackendError +from solprop.monitor import BoundaryCheck, BoundaryMonitor +from solprop.stepper.multistep import Multistep + + +def _backend(translation): + problem, request = translation + return problem, request, NumpyRefBackend(problem, request, grid=window()) + + +def test_a_backend_closed_under_its_session_ends_the_run_failed(): + problem, request, backend = _backend(soliton()) + session = backend.prepare(problem, request).start(entrance(problem), owns=False) + launch = session.advance() + session.acknowledge(launch.receipt) + backend.close() + batch = session.advance() + (terminal,) = batch.events + assert isinstance(terminal, Terminal) + assert terminal.outcome is Outcome.FAILED + assert isinstance(terminal.error, BackendError) + assert "closed" in str(terminal.error) + session.close() + + +def test_a_start_whose_plane_lies_behind_it_is_refused(): + problem, request, backend = _backend(soliton()) + try: + # The state at the second plane, with the first plane named as the next. + z = float(request.stepper.save_planes[1]) + start = Start(problem.initial.field0, z, plane_index=0, plane_pending=False) + session = backend.prepare(problem, request).start(start, owns=False) + (terminal,) = session.advance().events + assert isinstance(terminal, Terminal) + assert isinstance(terminal.error, BackendError) + assert "cannot propagate backwards" in str(terminal.error) + session.close() + finally: + backend.close() + + +def test_a_probe_refuses_a_start_of_another_shape(): + problem, _request, backend = _backend(soliton()) + try: + field = np.zeros((1, 1, problem.shape[-1] + 2), dtype=complex) + with pytest.raises(BackendError, match="initial state has shape"): + backend.timing_probe(Start(field, 0.0)) + finally: + backend.close() + + +@pytest.mark.parametrize("integrator", [None, Multistep()], ids=["rk", "adams"]) +def test_a_dense_output_refuses_what_it_does_not_hold(integrator): + _problem, _request, backend = _backend( + soliton(integrator=integrator, interpolate=True) + ) + try: + load_reference(backend) + dense = backend.method(None).dense + assert isinstance(dense, AdamsDense if integrator else RungeKuttaDense) + # No accepted step yet: nothing to interpolate, and nothing held to restore. + with pytest.raises(BackendError, match=r"accepted .*step is held"): + dense.observe(0.001) + with pytest.raises(BackendError, match="no dense observation holds"): + dense.restore() + finally: + backend.close() + + +def test_an_engine_has_no_stages_before_a_trial(): + _problem, request, backend = _backend(soliton()) + try: + engine = NumpyRungeKutta(backend.workspace, request.stepper.tableau) + with pytest.raises( + BackendError, match="take a trial before reading its stages" + ): + engine.stages # noqa: B018 - the property's refusal is the subject + finally: + backend.close() + + +@pytest.mark.parametrize("kind", ["runge_kutta", "adams", "low_storage"]) +def test_each_engine_reads_the_committed_state_as_its_workspace_does(kind): + """The engine protocol's ``reading`` is the workspace's (SEP 52 section 5.2).""" + translation = soliton(integrator=Multistep() if kind == "adams" else None) + if kind == "low_storage": + translation = low_storage(*translation) + _problem, _request, backend = _backend(translation) + try: + load_reference(backend) + monitor = BoundaryMonitor.build(window(), None, BoundaryCheck()) + backend.workspace.bind_monitor(monitor) + march = backend.method(None).march + engine = march.engine if not isinstance(march, HostAdamsMarch) else None + if isinstance(march, HostAdamsMarch): + engine = march._engine # pyright: ignore[reportPrivateUsage] + assert engine is not None + expected = backend.workspace.reading() + found = engine.reading() # pyright: ignore[reportAttributeAccessIssue] + assert found.total == expected.total + np.testing.assert_array_equal(found.regions, expected.regions) + if isinstance(march, HostLowStorageMarch): + # The low-storage step holds no dense extension: interpolation is refused + # at translation, and the engine says so if asked. + with pytest.raises(BackendError, match="holds no dense extension"): + engine.extend(0.0, 1e-3) # pyright: ignore[reportAttributeAccessIssue] + finally: + backend.close() From 6eb0de344ebe3823de3f98e1a6b694d7a6bd410b Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 09:00:44 +0000 Subject: [PATCH 14/14] docs: the quadrature score names no deleted attribute Co-Authored-By: Claude Opus 5.5 --- src/solprop/backends/numpy_ref/workspace.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/solprop/backends/numpy_ref/workspace.py b/src/solprop/backends/numpy_ref/workspace.py index d01e0d994..f99ef39cb 100644 --- a/src/solprop/backends/numpy_ref/workspace.py +++ b/src/solprop/backends/numpy_ref/workspace.py @@ -1211,7 +1211,7 @@ def score_quadrature(self) -> tuple[float, float]: ``nan`` where the polarisation itself vanishes, at a true vacuum end, because a relative measure of nothing says nothing. The session reports a value above :data:`~solprop.translate.modal.QUADRATURE_ALARM` once per plane, and the - ``quadrature_error`` statistic reads it (:attr:`quadrature`). + ``quadrature_error`` statistic reads it. Returns -------