From 14cd4f382d259ad4814f84215b7f7665a939dd3d Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 02:21:06 +0000 Subject: [PATCH 01/29] feat(native): field-table records, workspace, probe and schemas (SEP 52 phase 4) The new native seam beside the old one. Each record that crosses declares its fields once, next to its definition (fields.hpp), and one converter (src/records.hpp) reads a dataclass, mapping or tuple into it by its table and writes it back, refusing a malformed field by its path before copying anything; _core.schemas() exports every table. Problem's groups are bound from their tables, and Problem absorbs the set-once data (stage, z and flux tables, flow guard, controllers, low-storage settings, monitor and edge). native::Workspace (workspace.hpp) holds the lease, the coupled-flow guard, the marches' construction and entry points, the session (Run) and the timing probe, moved out of the binding unit; the old State binds over it. _core gains Workspace(problem).start(run)/probe(start)/diagnostics(), Probe, configure_runtime and the Session's ticketed export, snapshot, noise_phase and records; _testing gains engines, inject_fault, evaluate and round_trip. Co-Authored-By: Claude Opus 5.5 --- native/CMakeLists.txt | 6 +- native/include/solprop_native/adams_march.hpp | 61 + native/include/solprop_native/core.hpp | 244 +++ native/include/solprop_native/fields.hpp | 200 ++ native/include/solprop_native/low_storage.hpp | 13 + native/include/solprop_native/rk_march.hpp | 9 + .../include/solprop_native/stage_tables.hpp | 58 + native/include/solprop_native/transverse.hpp | 37 + native/include/solprop_native/watch.hpp | 40 + native/include/solprop_native/workspace.hpp | 767 +++++++ native/src/bindings.cpp | 1822 ++++++++--------- native/src/records.cpp | 249 +++ native/src/records.hpp | 763 +++++++ native/src/solprop_native/_core.pyi | 62 + native/src/solprop_native/_core_testing.pyi | 43 +- native/src/workspace.cpp | 1006 +++++++++ native/tests/native/test_workspace.cpp | 269 +++ native/tests/test_workspace.py | 658 ++++++ 18 files changed, 5385 insertions(+), 922 deletions(-) create mode 100644 native/include/solprop_native/fields.hpp create mode 100644 native/include/solprop_native/workspace.hpp create mode 100644 native/src/records.cpp create mode 100644 native/src/records.hpp create mode 100644 native/src/workspace.cpp create mode 100644 native/tests/native/test_workspace.cpp create mode 100644 native/tests/test_workspace.py diff --git a/native/CMakeLists.txt b/native/CMakeLists.txt index e78ee5504..b8bbc0cc6 100644 --- a/native/CMakeLists.txt +++ b/native/CMakeLists.txt @@ -815,7 +815,7 @@ add_library(solprop_native_core STATIC src/core.cpp src/crossing.cpp src/general/statistics.cpp src/general/state.cpp src/general_modal.cpp src/coupled_flow.cpp src/dispersive.cpp src/far_field.cpp src/adams_march.cpp src/watch.cpp src/rk_march.cpp src/engines.cpp src/session.cpp src/session_statistics.cpp src/session_widths.cpp src/low_storage.cpp src/transverse.cpp - src/session_edge.cpp src/dense.cpp) + src/session_edge.cpp src/dense.cpp src/workspace.cpp) # solprop SEP 39, SEP 45 and SEP 47: the Adams march's decisions, the boundary watch's # predictions, the Runge-Kutta march's positions and norm, the low-storage replay's # positions and table keys, the native session's scheduling, export, statistics @@ -901,7 +901,8 @@ add_custom_command( ) nanobind_add_module(_core STABLE_ABI NOMINSIZE NB_SUPPRESS_WARNINGS src/bindings.cpp - src/bindings_transverse.cpp src/helpers.cpp "${SOLPROP_NATIVE_SOURCE_DIGEST_CPP}") + src/bindings_transverse.cpp src/helpers.cpp src/records.cpp + "${SOLPROP_NATIVE_SOURCE_DIGEST_CPP}") target_link_libraries(_core PRIVATE solprop_native_core ${CMAKE_DL_LIBS}) solprop_native_mark_dependency_headers_system(_core) solprop_native_configure_project_target(_core) @@ -982,6 +983,7 @@ if(BUILD_TESTING) tests/native/test_dispersive.cpp tests/native/test_aperture.cpp tests/native/test_vmath.cpp + tests/native/test_workspace.cpp ) target_link_libraries(solprop_native_tests PRIVATE solprop_native_core diff --git a/native/include/solprop_native/adams_march.hpp b/native/include/solprop_native/adams_march.hpp index c00d7ac0b..ef485aced 100644 --- a/native/include/solprop_native/adams_march.hpp +++ b/native/include/solprop_native/adams_march.hpp @@ -14,6 +14,7 @@ #include #include #include +#include #include /* @@ -117,6 +118,66 @@ struct State { watch::State watch; }; +// The field tables (solprop SEP 52 section 5.3): the policy as +// `solprop.stepper.multistep.MarchPolicy`, the state as a run's start holds it. +[[nodiscard]] constexpr auto describe(const Policy* /*unused*/) { + using P = Policy; + return fields::table

( + "MarchPolicy", fields::value("order", &P::order), + fields::value("variable_order", &P::variable_order), + fields::value("safety", &P::safety), fields::value("max_growth", &P::max_growth), + fields::value("min_factor", &P::min_factor), + fields::value("rejection_growth", &P::rejection_growth), + fields::value("hysteresis", &P::hysteresis), + fields::value("restart_after", &P::restart_after), + fields::value("collar_stability", &P::collar_stability), + fields::value("real_intervals", &P::real_intervals), + fields::value("collar_rate", &P::collar_rate), + fields::value("carrier", &P::carrier), + fields::value("carrier_cap", &P::carrier_cap), + fields::flagged("max_calls", &P::has_budget, &P::max_calls), + fields::value("equal_approach", &P::equal_approach), + fields::value("interval_cap", &P::interval_cap), + fields::value("dz_min", &P::dz_min), fields::value("dz_max", &P::dz_max), + fields::value("stretch", &P::stretch), fields::value("z_end", &P::z_end), + fields::value("save_planes", &P::save_planes), + fields::value("hard_kinks", &P::hard_kinks), + fields::value("breakpoints", &P::breakpoints), + fields::value("landing_ulps", &P::landing_ulps), + fields::value("interpolate", &P::interpolate), + fields::flagged("quiet_interval", &P::has_quiet_interval, &P::quiet_interval)); +} +[[nodiscard]] constexpr auto names(const Identity* /*unused*/) { + return std::array{std::pair{"accepted", Identity::accepted}, + std::pair{"predicted", Identity::predicted}}; +} +[[nodiscard]] constexpr auto describe(const Entry* /*unused*/) { + return fields::table("march.Entry", fields::value("z", &Entry::z), + fields::value("identity", &Entry::identity), + fields::value("row", &Entry::row)); +} +[[nodiscard]] constexpr auto describe(const Ledger* /*unused*/) { + using L = Ledger; + return fields::table("march.Ledger", fields::value("startup", &L::startup), + fields::value("predictor", &L::predictor), + fields::value("rejected", &L::rejected), + fields::value("accepted_steps", &L::accepted_steps), + fields::value("rejected_steps", &L::rejected_steps), + fields::value("restarts", &L::restarts), + fields::value("failure_restarts", &L::failure_restarts), + fields::value("dense_observations", &L::dense_observations)); +} +[[nodiscard]] constexpr auto describe(const State* /*unused*/) { + using S = State; + return fields::table( + "march.State", fields::value("z", &S::z), fields::value("proposal", &S::proposal), + fields::value("order", &S::order), fields::value("rejections", &S::rejections), + fields::value("last_rejected", &S::last_rejected), + fields::value("collar_was_quiet", &S::collar_was_quiet), + fields::value("cursor", &S::cursor), fields::value("history", &S::history), + fields::value("ledger", &S::ledger), fields::value("watch", &S::watch)); +} + /** A replayed schedule's steps and their edges, one more than the steps (SEP 39 4.3). */ struct Schedule { diff --git a/native/include/solprop_native/core.hpp b/native/include/solprop_native/core.hpp index 54a38ac62..10e9ef8d8 100644 --- a/native/include/solprop_native/core.hpp +++ b/native/include/solprop_native/core.hpp @@ -4,6 +4,7 @@ #pragma once +#include "solprop_native/fields.hpp" #include "solprop_native/host_source.hpp" #include "solprop_native/launch.hpp" @@ -72,6 +73,15 @@ template } using Complex = Kokkos::complex; +} // namespace solprop_native + +// NumPy's complex128 is two doubles, real part first, as `Complex` is. +template <> struct solprop_native::fields::ElementDtype { + static constexpr Dtype value = Dtype::complex128; +}; + +namespace solprop_native { + /** The boundary monitor's five sums of a state (solprop SEP 21), one reduction value: the energy, then the low guard's, the high guard's, the collar's and the rate's. */ struct MonitorSums { @@ -448,6 +458,13 @@ reference_stream_copies(std::size_t elements, std::size_t warm, std::size_t repe enum class FieldFamily { field_real, field_analytic, envelope }; +/** The field families by name, for the field tables (`fields.hpp`). */ +[[nodiscard]] constexpr auto names(const FieldFamily* /*unused*/) { + return std::array{std::pair{"field_real", FieldFamily::field_real}, + std::pair{"field_analytic", FieldFamily::field_analytic}, + std::pair{"envelope", FieldFamily::envelope}}; +} + enum StatisticsFlag : std::uint64_t { statistics_omega0 = 1ULL << 0U, statistics_energy = 1ULL << 1U, @@ -473,6 +490,8 @@ inline constexpr std::size_t plasma_max_taps = 9; /** The six parts of SEP 18's run diagnostics, in solprop's order. */ inline constexpr std::size_t plasma_diagnostic_parts = 6; +struct Setup; + /** Fixed, Python-free problem data uploaded once by a native state, grouped as solprop's kernel contract groups it. The adapter fills it field by field (`lower` in solprop_native's backend); `validate` checks presence and extents before a state @@ -756,6 +775,11 @@ struct Problem { CpuExecution cpu_execution{}; // How the workspace plans its host transforms (solprop SEP 46 phase 3). FftPlanning fft_planning{}; + /** The set-once data a workspace applies once it has built its state (solprop SEP + 52 section 5.3): the stage, z and flux tables, the flow guard, the controllers, + the low-storage settings, the monitor's weights and the edge's geometry + (`workspace.hpp`). Shared, so that a copy of the problem copies none of it. */ + std::shared_ptr setup; /** Refuse, naming the field, data whose presence or extents disagree with the problem's own flags and extents: the checks that need no execution space. */ @@ -786,6 +810,226 @@ struct Problem { }; /** The most samples an Adams formula of solprop's shipped orders combines. */ +// The problem's groups as the seam fills them, one field table a group (solprop SEP 52 +// section 5.3). The relations a table states within its group are its schema's; the +// extents that a count in another group gives are `Problem::validate`'s. +[[nodiscard]] constexpr auto describe(const Problem::Dims* /*unused*/) { + using G = Problem::Dims; + return fields::table( + "Problem.Dims", fields::value("n_omega", &G::n_omega), + fields::value("n_t", &G::n_t), fields::value("n_to", &G::n_to), + fields::value("n_modes", &G::n_modes), + fields::value("n_pol_state", &G::n_pol_state), + fields::value("n_pol_transform", &G::n_pol_transform), + fields::value("n_nodes", &G::n_nodes), + fields::value("node_chunk", &G::node_chunk), fields::value("family", &G::family)); +} + +[[nodiscard]] constexpr auto describe(const Problem::Grid* /*unused*/) { + using G = Problem::Grid; + return fields::table( + "Problem.Grid", fields::array("crop_index", &G::crop_index), + fields::array("active_mask", &G::active_mask), + fields::array("norm_mask", &G::norm_mask), + fields::array("omega_window", &G::omega_window), + fields::array("omega", &G::omega), + fields::array("power_weight", &G::power_weight), + fields::array("time_window", &G::time_window), + fields::array("time_window_derivative", &G::time_window_derivative), + fields::array("carrier", &G::carrier), fields::value("dt_fine", &G::dt_fine), + fields::value("dt", &G::dt)); +} + +[[nodiscard]] constexpr auto describe(const Problem::Spatial* /*unused*/) { + using G = Problem::Spatial; + return fields::table( + "Problem.Spatial", fields::value("n_x", &G::n_x), fields::value("n_y", &G::n_y), + fields::array("k_squared", &G::k_squared), + fields::array("k_squared_low", &G::k_squared_low), + fields::array("numerator", &G::numerator), fields::array("clamped", &G::clamped), + fields::array("kperp_sq", &G::kperp_sq), + fields::array("kperp_sq_low", &G::kperp_sq_low), + fields::array("frame", &G::frame), + fields::array("spectral_rate", &G::spectral_rate), + fields::array("user_rate", &G::user_rate), + fields::array("absorber_rate", &G::absorber_rate), + fields::array("kperp_rate", &G::kperp_rate), + fields::value("evanescent_rate", &G::evanescent_rate), + fields::array("k_x", &G::k_x), fields::array("k_y", &G::k_y), + fields::value("far_field_slots", &G::far_field_slots), + fields::value("n_p", &G::n_p), fields::array("kappa_sq", &G::kappa_sq), + fields::array("absorber_matrix", &G::absorber_matrix), + fields::array("spectral_weights", &G::spectral_weights), + fields::array("on_axis", &G::on_axis)); +} + +[[nodiscard]] constexpr auto describe(const Problem::Flux* /*unused*/) { + using G = Problem::Flux; + return fields::table("Problem.Flux", fields::array("k_squared", &G::k_squared), + fields::array("k_squared_low", &G::k_squared_low), + fields::array("kperp_sq", &G::kperp_sq), + fields::array("kperp_sq_low", &G::kperp_sq_low), + fields::value("table", &G::table), + fields::value("closure", &G::closure)); +} + +[[nodiscard]] constexpr auto describe(const Problem::Stepper* /*unused*/) { + using G = Problem::Stepper; + return fields::table( + "Problem.Stepper", fields::value("n_stages", &G::n_stages), + fields::array("tableau_matrix", &G::tableau_matrix), + fields::array("tableau_nodes", &G::tableau_nodes), + fields::array("solution_weights", &G::solution_weights), + fields::array("error_weights", &G::error_weights), + fields::value("first_same_as_last", &G::first_same_as_last), + fields::value("weighted_controller", &G::weighted_controller), + fields::value("modified_noise", &G::modified_noise), + fields::value("low_storage", &G::low_storage), + fields::value("low_storage_stage_register", &G::low_storage_stage_register), + fields::value("low_storage_flows", &G::low_storage_flows), + fields::value("low_storage_tiled_input", &G::low_storage_tiled_input)); +} + +[[nodiscard]] constexpr auto describe(const Problem::Linear* /*unused*/) { + using G = Problem::Linear; + return fields::table("Problem.Linear", + fields::value("n_phi_terms", &G::n_phi_terms), + fields::value("n_prefactor_terms", &G::n_prefactor_terms), + fields::value("phi_table", &G::phi_table), + fields::value("prefactor_table", &G::prefactor_table), + fields::array("phi_terms", &G::phi_terms), + fields::array("prefactor_terms", &G::prefactor_terms)); +} + +[[nodiscard]] constexpr auto describe(const Problem::Absorber* /*unused*/) { + using G = Problem::Absorber; + return fields::table("Problem.Absorber", fields::value("in_stage", &G::in_stage), + fields::value("split_step", &G::split_step), + fields::array("fine", &G::fine), + fields::array("coarse", &G::coarse)); +} + +[[nodiscard]] constexpr auto describe(const Problem::Transform* /*unused*/) { + using G = Problem::Transform; + return fields::table( + "Problem.Transform", fields::array("synthesis_matrix", &G::synthesis_matrix), + fields::array("projection_matrix", &G::projection_matrix), + fields::array("projection_coarse_matrix", &G::projection_coarse_matrix), + fields::value("synthesis", &G::synthesis), + fields::value("projection", &G::projection)); +} + +[[nodiscard]] constexpr auto describe(const Problem::Kerr* /*unused*/) { + using G = Problem::Kerr; + return fields::table("Problem.Kerr", fields::value("nonlinear", &G::nonlinear), + fields::value("coefficient", &G::coefficient), + fields::value("self_factor", &G::self_factor), + fields::value("conjugate_factor", &G::conjugate_factor), + fields::value("harmonic_factor", &G::harmonic_factor), + fields::value("take_real", &G::take_real)); +} + +[[nodiscard]] constexpr auto describe(const Problem::Plasma* /*unused*/) { + using G = Problem::Plasma; + using E = fields::Extent; + return fields::table( + "Problem.Plasma", fields::value("enabled", &G::enabled), + fields::value("envelope", &G::envelope), fields::value("gated", &G::gated), + fields::value("stash", &G::stash), + fields::array("envelope_rule_nodes", &G::envelope_rule_nodes, E::of("n_channels"), + E::fixed(4), E::fixed(512)), + fields::array("envelope_rule_weights", &G::envelope_rule_weights, + E::of("n_channels"), E::fixed(4), E::fixed(512)), + fields::array("envelope_drude_factor", &G::envelope_drude_factor, E::any()), + fields::array("envelope_loss_factor", &G::envelope_loss_factor, E::any()), + fields::value("charge_mass_ratio", &G::charge_mass_ratio), + fields::value("ionisation_potential", &G::ionisation_potential), + fields::value("log_field_min", &G::log_field_min), + fields::value("d_log_field", &G::d_log_field), + fields::value("field_min", &G::field_min), + fields::value("field_max", &G::field_max), + fields::value("rate_max", &G::rate_max), + fields::value("rate_intervals", &G::rate_intervals), + fields::array("rate_coefficients", &G::rate_coefficients, E::fixed(4), + E::of("rate_intervals")), + fields::value("n_channels", &G::n_channels), fields::value("band", &G::band), + fields::array("taps", &G::taps, E::any()), + fields::array("channel_parameters", &G::channel_parameters), + fields::array("channel_coefficients", &G::channel_coefficients)); +} + +[[nodiscard]] constexpr auto describe(const Problem::Raman* /*unused*/) { + using G = Problem::Raman; + using E = fields::Extent; + return fields::table( + "Problem.Raman", fields::value("enabled", &G::enabled), + fields::value("thg", &G::thg), + fields::value("tensor_capable", &G::tensor_capable), + fields::value("n_terms", &G::n_terms), fields::value("fraction", &G::fraction), + fields::value("epsilon0", &G::epsilon0), + fields::array("undamped", &G::undamped, E::of("n_terms"), E::any()), + fields::array("tensor_weights", &G::tensor_weights, E::of("n_terms"), + E::fixed(2)), + fields::value("n_components", &G::n_components), + fields::array("row_component", &G::row_component), + fields::array("component_fraction", &G::component_fraction)); +} + +[[nodiscard]] constexpr auto describe(const Problem::General* /*unused*/) { + using G = Problem::General; + return fields::table( + "Problem.General", fields::value("enabled", &G::enabled), + fields::value("real_form", &G::real_form), + fields::value("map_intervals", &G::map_intervals), + fields::value("map_n_deg", &G::map_n_deg), + fields::value("components", &G::components), fields::value("nodes", &G::nodes), + fields::value("node_chunk", &G::node_chunk), + fields::value("responses", &G::responses), fields::value("terms", &G::terms), + fields::value("pad_scale", &G::pad_scale), + fields::value("epsilon0", &G::epsilon0), + fields::array("synthesis", &G::synthesis), + fields::array("projection", &G::projection), + fields::array("frequency_factor", &G::frequency_factor), + fields::array("delayed_spectrum", &G::delayed_spectrum), + fields::array("tensor", &G::tensor), + fields::array("delayed_tensor", &G::delayed_tensor), + fields::array("node_response", &G::node_response)); +} + +[[nodiscard]] constexpr auto describe(const Problem::Flow* /*unused*/) { + using G = Problem::Flow; + return fields::table( + "Problem.Flow", fields::value("enabled", &G::enabled), + fields::value("active", &G::active), fields::value("sections", &G::sections), + fields::value("terms", &G::terms), fields::array("slot", &G::slot), + fields::array("frozen", &G::frozen), + fields::array("residual_terms", &G::residual_terms), + fields::array("left", &G::left), fields::array("right", &G::right), + fields::array("eigenvalues", &G::eigenvalues), fields::array("route", &G::route), + fields::array("fallback_vectors", &G::fallback_vectors), + fields::array("fallback_triangular", &G::fallback_triangular)); +} + +[[nodiscard]] constexpr auto describe(const Problem::Dispersive* /*unused*/) { + using G = Problem::Dispersive; + return fields::table("Problem.Dispersive", fields::value("enabled", &G::enabled), + fields::value("symmetric", &G::symmetric), + fields::value("form", &G::form), + fields::array("inputs", &G::inputs), + fields::array("term_multipliers", &G::term_multipliers), + fields::array("coefficients", &G::coefficients), + fields::array("pair_constants", &G::pair_constants), + fields::array("quartics", &G::quartics), + fields::array("input_scale", &G::input_scale), + fields::array("output_scale", &G::output_scale), + fields::array("term_rows", &G::term_rows), + fields::array("term_channels", &G::term_channels), + fields::array("group_offsets", &G::group_offsets), + fields::array("group_members", &G::group_members), + fields::array("group_keys", &G::group_keys), + fields::array("node_region", &G::node_region)); +} + inline constexpr std::size_t adams_max_samples = 8; /** The most defect norms an Adams trial scores: its order's and its two neighbours'. */ diff --git a/native/include/solprop_native/fields.hpp b/native/include/solprop_native/fields.hpp new file mode 100644 index 000000000..c8192b26e --- /dev/null +++ b/native/include/solprop_native/fields.hpp @@ -0,0 +1,200 @@ +// SPDX-FileCopyrightText: 2026 John C. Travers and contributors +// +// SPDX-License-Identifier: GPL-3.0-or-later + +#pragma once + +#include +#include +#include +#include +#include +#include +#include +#include + +/* + * The field tables of the records that cross the seam (solprop SEP 52 section 5.3). + * + * Each record declares its fields once, next to its definition, as a function found by + * argument-dependent lookup: + * + * constexpr auto describe(const Policy*) { + * return fields::table("march.Policy", + * fields::value("order", &Policy::order), + * fields::array("steps", &Policy::steps, ...)); + * } + * + * A field gives its name and its member. A value's conversion follows the member's + * C++ type (a number, a bool, a string, a sequence, an optional, a nested record, a + * list of records, a mapping of numbers, a variant of records). An array gives its + * dtype, its rank and its extents, each written as a literal, as the record's own + * count, or as a symbol another array's extent binds (the Raman table's + * `(n_terms, 2, n_to)`). A count field takes its value from a symbol the arrays bound, + * so that a count an array's extents give is read from the array and never sent beside + * it. The binding layer's converter (`src/records.hpp`) reads a Python dataclass or + * mapping into the record and back, and exports the tables (`_core.schemas()`). + * + * Python-free and Kokkos-free: descriptors only. + */ +namespace solprop_native::fields { + +/** The NumPy dtype an array field takes. */ +enum class Dtype : std::uint8_t { float64, complex128, uint64, uint8, boolean }; + +/** The dtype's NumPy name. */ +[[nodiscard]] constexpr const char* dtype_name(const Dtype dtype) noexcept { + switch (dtype) { + case Dtype::float64: + return "float64"; + case Dtype::complex128: + return "complex128"; + case Dtype::uint64: + return "uint64"; + case Dtype::uint8: + return "uint8"; + case Dtype::boolean: + return "bool"; + } + return "?"; +} + +/** The dtype an element type takes by default, beyond the numbers and the bools: + `core.hpp` adds the complex one. */ +template struct ElementDtype; + +template [[nodiscard]] constexpr Dtype element_dtype() noexcept { + if constexpr (std::is_same_v) + return Dtype::float64; + else if constexpr (std::is_same_v) + return Dtype::boolean; + else if constexpr (std::is_integral_v && std::is_unsigned_v && + sizeof(T) == sizeof(std::uint64_t)) + return Dtype::uint64; + else + return ElementDtype::value; +} + +/** The element an array field stores: a vector's, or an optional vector's (an array + that may be `None`). */ +template struct ArrayElement; +template struct ArrayElement> { + using type = T; + static constexpr bool optional = false; +}; +template struct ArrayElement>> { + using type = T; + static constexpr bool optional = true; +}; + +/** One axis of an array field: free (`any`), a literal (`fixed`), or a symbol with an + offset (`of`), which the first array to name it binds and every other one meets. */ +struct Extent { + const char* symbol = nullptr; + std::size_t literal = 0; + std::ptrdiff_t offset = 0; + bool fixed_size = false; + + [[nodiscard]] static constexpr Extent any() noexcept { return {}; } + [[nodiscard]] static constexpr Extent fixed(const std::size_t size) noexcept { + return {.symbol = nullptr, .literal = size, .offset = 0, .fixed_size = true}; + } + [[nodiscard]] static constexpr Extent of(const char* symbol, + const std::ptrdiff_t offset = 0) noexcept { + return {.symbol = symbol, .literal = 0, .offset = offset, .fixed_size = false}; + } +}; + +/** A field whose conversion follows its member's type. */ +template struct Value { + const char* name; + Member Record::* member; +}; + +/** An optional value held as a flag beside it: `None` clears the flag. */ +template struct Flagged { + const char* name; + bool Record::* flag; + Member Record::* member; +}; + +/** An array of `Element` stored flat in a vector, C order. `Rank` zero takes any rank, + and the record keeps the shape in its `shapes` map when it has one. */ +template struct Array { + const char* name; + Element Record::* member; // a std::vector of the stored element + Dtype dtype; + std::array extents; +}; + +/** A count the arrays' extents give: set from `symbol`, never read from Python. */ +template struct Count { + const char* symbol; + Member Record::* member; +}; + +/** A record's table: its name and its fields, in order. */ +template struct Table { + using record_type = Record; + const char* name; + std::tuple fields; +}; + +template +[[nodiscard]] constexpr Table table(const char* name, + Fields... entries) { + return {name, std::tuple{entries...}}; +} + +template +[[nodiscard]] constexpr Value value(const char* name, + Member Record::* member) { + return {name, member}; +} + +template +[[nodiscard]] constexpr Flagged +flagged(const char* name, bool Record::* flag, Member Record::* member) { + return {name, flag, member}; +} + +/** An array field of `rank` axes with the given extents (or any rank, none given). */ +template +[[nodiscard]] constexpr Array +array(const char* name, Vector Record::* member, const Dtype dtype, + Extents... extents) { + return {name, member, dtype, {Extent(extents)...}}; +} + +/** An array field with its element's default dtype. */ +template +[[nodiscard]] constexpr Array +array(const char* name, Vector Record::* member, Extents... extents) { + return {name, + member, + element_dtype::type>(), + {Extent(extents)...}}; +} + +template +[[nodiscard]] constexpr Count count(const char* symbol, + Member Record::* member) { + return {symbol, member}; +} + +/** Whether `Record` has a table (`describe`, found by argument-dependent lookup). */ +template +concept Described = requires { describe(static_cast(nullptr)); }; + +/** `Record`'s table. */ +template [[nodiscard]] constexpr auto table_of() { + return describe(static_cast(nullptr)); +} + +/** Call `visit` on each of `table`'s fields, in order. */ +template +constexpr void each(const Table& table, Visit&& visit) { + std::apply([&](const auto&... entry) { (visit(entry), ...); }, table.fields); +} + +} // namespace solprop_native::fields diff --git a/native/include/solprop_native/low_storage.hpp b/native/include/solprop_native/low_storage.hpp index 7787dff57..56006f3eb 100644 --- a/native/include/solprop_native/low_storage.hpp +++ b/native/include/solprop_native/low_storage.hpp @@ -48,6 +48,19 @@ struct Config { double origin = 0.0; }; +/** The source evaluations of one step: the four register passes of the scheme the + native step implements (solprop's `LowStorageRungeKutta().evaluations`). */ +inline constexpr std::size_t evaluations = 4; + +/** The settings' field table:`solprop.backends.records.LowStorageSettings` (solprop + SEP 52 section 5.3), with the flows the adapter resolved for this build. */ +[[nodiscard]] constexpr auto describe(const Config* /*unused*/) { + return fields::table("LowStorageSettings", + fields::value("flows", &Config::flows), + fields::value("separable", &Config::separable), + fields::value("origin", &Config::origin)); +} + /** * `solprop.backends.low_storage.table_steps`: the key each of a schedule's steps builds * its table on, the mean step of its run -- the longest stretch of steps within diff --git a/native/include/solprop_native/rk_march.hpp b/native/include/solprop_native/rk_march.hpp index 6d8646915..d4aa6be0e 100644 --- a/native/include/solprop_native/rk_march.hpp +++ b/native/include/solprop_native/rk_march.hpp @@ -88,6 +88,15 @@ struct State { std::uint64_t cursor = 0; }; +/** The state's field table (solprop SEP 52 section 5.3). */ +[[nodiscard]] constexpr auto describe(const State* /*unused*/) { + return fields::table("rk.State", fields::value("z", &State::z), + fields::value("proposal", &State::proposal), + fields::value("norms", &State::norms), + fields::value("watch", &State::watch), + fields::value("cursor", &State::cursor)); +} + /** The field arithmetic a Runge-Kutta march hands its trials to. */ class Engine { public: diff --git a/native/include/solprop_native/stage_tables.hpp b/native/include/solprop_native/stage_tables.hpp index 209cb6008..a761b5c32 100644 --- a/native/include/solprop_native/stage_tables.hpp +++ b/native/include/solprop_native/stage_tables.hpp @@ -214,6 +214,64 @@ struct Tables { Sections transform; }; +// The field tables (solprop SEP 52 section 5.3). A table's term and value counts are +// its coefficients' extents, read from the array; the z table's slots are the +// workspace's, not a field. +[[nodiscard]] constexpr auto describe(const Table* /*unused*/) { + using E = fields::Extent; + return fields::table( + "stage.Table", fields::array("edges", &Table::edges, E::of("n_edges")), + fields::value("lower", &Table::lower), fields::value("upper", &Table::upper), + fields::array("coefficients", &Table::coefficients, E::of("n_edges", -1), + E::of("n_terms"), E::of("n_values")), + fields::count("n_terms", &Table::n_terms), + fields::count("n_values", &Table::n_values)); +} +[[nodiscard]] constexpr auto describe(const Sections* /*unused*/) { + return fields::table("stage.Sections", + fields::value("edges", &Sections::edges), + fields::value("degrees", &Sections::degrees), + fields::value("slack", &Sections::slack)); +} +[[nodiscard]] constexpr auto names(const Terms* /*unused*/) { + return std::array{std::pair{"constant", Terms::constant}, + std::pair{"expansion", Terms::expansion}, + std::pair{"table", Terms::table}}; +} +[[nodiscard]] constexpr auto names(const KerrDensity* /*unused*/) { + return std::array{std::pair{"none", KerrDensity::none}, + std::pair{"density", KerrDensity::density}, + std::pair{"table", KerrDensity::table}}; +} +[[nodiscard]] constexpr auto names(const Chord* /*unused*/) { + return std::array{ + std::pair{"none", Chord::none}, std::pair{"constant", Chord::constant}, + std::pair{"expansion", Chord::expansion}, std::pair{"table", Chord::table}}; +} +[[nodiscard]] constexpr auto describe(const Tables* /*unused*/) { + using T = Tables; + return fields::table( + "stage.Tables", fields::value("n_stages", &T::n_stages), + fields::value("phi", &T::phi), fields::value("phi_weights", &T::phi_weights), + fields::value("phi_rate", &T::phi_rate), + fields::value("prefactor", &T::prefactor), + fields::value("prefactor_weights", &T::prefactor_weights), + fields::value("prefactor_low", &T::prefactor_low), + fields::value("prefactor_high", &T::prefactor_high), + fields::value("density", &T::density), fields::value("taper", &T::taper), + fields::value("raman_rates", &T::raman_rates), fields::value("kerr", &T::kerr), + fields::value("kerr_density", &T::kerr_density), + fields::value("plasma_densities", &T::plasma_densities), + fields::value("plasma_preionisation", &T::plasma_preionisation), + fields::value("raman_densities", &T::raman_densities), + fields::value("dispersive_densities", &T::dispersive_densities), + fields::value("chord", &T::chord), fields::value("chord_rate", &T::chord_rate), + fields::value("chord_terms", &T::chord_terms), + fields::value("chord_table", &T::chord_table), fields::value("flow", &T::flow), + fields::value("flow_residual", &T::flow_residual), + fields::value("transform", &T::transform)); +} + /** * A z table's position slots (solprop's `_ZTables`, SEP 29 G1), least recently used * first: the positions a trial reads are evaluated into the native state's term slots diff --git a/native/include/solprop_native/transverse.hpp b/native/include/solprop_native/transverse.hpp index db95eb064..67fb3e262 100644 --- a/native/include/solprop_native/transverse.hpp +++ b/native/include/solprop_native/transverse.hpp @@ -4,6 +4,8 @@ #pragma once +#include "solprop_native/fields.hpp" + #include #include #include @@ -108,6 +110,33 @@ struct Config { double noise_modes = 1.0; }; +/** The configuration's field table: `solprop.backends.records.EdgeConfig` (solprop SEP + 52 section 5.3). */ +[[nodiscard]] constexpr auto describe(const Config* /*unused*/) { + using C = Config; + using E = fields::Extent; + return fields::table( + "EdgeConfig", fields::value("faces", &C::faces), fields::value("warn", &C::warn), + fields::value("stop", &C::stop), fields::value("length", &C::length), + fields::value("guard", &C::guard), fields::value("k_min", &C::k_min), + fields::value("k_floor", &C::k_floor), fields::value("reads", &C::reads), + fields::value("backstop_reads", &C::backstop_reads), + fields::value("reach_growth", &C::reach_growth), + fields::value("noise_factor", &C::noise_factor), + fields::array("columns", &C::columns, E::of("n_columns")), + fields::array("kappa", &C::kappa, E::of("n_kappa")), + fields::array("kappa_order", &C::kappa_order, E::of("n_kappa")), + fields::value("design", &C::design), + fields::array("ramp_rate", &C::ramp_rate, E::of("n_ramp")), + fields::value("collar", &C::collar), + fields::value("collar_rate", &C::collar_rate), + fields::value("declared", &C::declared), + fields::value("reads_edge", &C::reads_edge), + fields::value("longest_step", &C::longest_step), + fields::value("noise_share", &C::noise_share), + fields::value("noise_modes", &C::noise_modes)); +} + /** What a backend reads of its state for the edge (`_EdgeReading`): numbers, never the field. Each part is present only when it was asked for. */ struct Reading { @@ -140,6 +169,14 @@ struct Noise { std::optional> clean; }; +/** The noise readings' field table (solprop SEP 52 section 5.3). */ +[[nodiscard]] constexpr auto describe(const Noise* /*unused*/) { + return fields::table( + "transverse.Noise", fields::value("columns", &Noise::columns), + fields::value("energy", &Noise::energy), fields::value("ramp", &Noise::ramp), + fields::value("strip", &Noise::strip), fields::value("clean", &Noise::clean)); +} + /** The launch's ramp-band reading: the judged columns' total and their energy in the band (`_judge_ramp_band`). */ struct LaunchSums { diff --git a/native/include/solprop_native/watch.hpp b/native/include/solprop_native/watch.hpp index 85ebfddec..31d68a55c 100644 --- a/native/include/solprop_native/watch.hpp +++ b/native/include/solprop_native/watch.hpp @@ -4,6 +4,8 @@ #pragma once +#include "solprop_native/fields.hpp" + #include #include #include @@ -158,6 +160,44 @@ struct Config { bool can_rest = false; }; +// The field tables (solprop SEP 52 section 5.3): the policy as solprop's +// `BoundaryMonitor.watch_policy` names it, the state as `.watch_state` does, and the +// configuration as `solprop.backends.records.MonitorConfig`. +[[nodiscard]] constexpr auto describe(const Policy* /*unused*/) { + using P = Policy; + return fields::table

( + "watch.Policy", fields::value("split", &P::split), + fields::value("crossing", &P::crossing), + fields::value("floor_regions", &P::floor_regions), + fields::value("launch_floor", &P::launch_floor), + fields::value("activity", &P::activity), fields::value("warn", &P::warn), + fields::value("stop", &P::stop), fields::value("quiet_share", &P::quiet_share), + fields::value("quiet_checks", &P::quiet_checks), + fields::value("quiet_collar", &P::quiet_collar), + fields::value("cadence", &P::cadence), fields::value("interval", &P::interval), + fields::value("share", &P::share), + fields::value("bucket_limits", &P::bucket_limits)); +} +[[nodiscard]] constexpr auto describe(const State* /*unused*/) { + using S = State; + return fields::table( + "watch.State", fields::value("has_last", &S::has_last), + fields::value("last_z", &S::last_z), fields::value("since", &S::since), + fields::value("busy", &S::busy), fields::value("quiet_run", &S::quiet_run), + fields::value("quiet", &S::quiet), fields::value("warned", &S::warned), + fields::value("cap", &S::cap)); +} +[[nodiscard]] constexpr auto describe(const Config* /*unused*/) { + using C = Config; + using E = fields::Extent; + return fields::table("MonitorConfig", fields::value("policy", &C::policy), + fields::value("floor_share", &C::floor_share), + fields::value("floor_margin", &C::floor_margin), + fields::value("budget", &C::budget), + fields::array("rate", &C::rate, E::of("n_t")), + fields::value("can_rest", &C::can_rest)); +} + /** An earlier execution's record as a resume reads it (`BoundaryMonitor.resume`): each number present in it, and the lists. solprop reads the record's types; the reconstruction -- which fields are restored, their defaults, the fallbacks of a diff --git a/native/include/solprop_native/workspace.hpp b/native/include/solprop_native/workspace.hpp new file mode 100644 index 000000000..894105820 --- /dev/null +++ b/native/include/solprop_native/workspace.hpp @@ -0,0 +1,767 @@ +// SPDX-FileCopyrightText: 2026 John C. Travers and contributors +// +// SPDX-License-Identifier: GPL-3.0-or-later + +#pragma once + +#include "solprop_native/adams_march.hpp" +#include "solprop_native/core.hpp" +#include "solprop_native/engines.hpp" +#include "solprop_native/fields.hpp" +#include "solprop_native/low_storage.hpp" +#include "solprop_native/rk_march.hpp" +#include "solprop_native/session.hpp" +#include "solprop_native/stage_tables.hpp" +#include "solprop_native/transverse.hpp" +#include "solprop_native/watch.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +/* + * The native workspace (solprop SEP 52 section 5.3): one problem's state, built once + * and reused across the runs of a scan, with every set-once table, guard and geometry + * applied from the problem's `Setup`; the lease between it and the one session or + * probe that uses it; the coupled flow's guard; the marches' construction from a run's + * records; and the timing probe of section 5.5. + * + * The binding converts Python's records into the structs here (each with its field + * table, `fields.hpp`), releases the interpreter lock and forwards; the logic is here, + * where the native tests reach it. + */ +namespace solprop_native { + +// ------------------------------------------------------------------ the set-once data + +/** The z tables by name (`TableKind`). */ +[[nodiscard]] constexpr auto names(const TableKind* /*unused*/) { + return std::array{ + std::pair{"phi", TableKind::phi}, std::pair{"prefactor", TableKind::prefactor}, + std::pair{"rate", TableKind::rate}, std::pair{"flux", TableKind::flux}}; +} + +/** One general z table made resident at construction (solprop SEP 29 G1): its + breakpoints, admitted span and coefficients `(n_edges - 1, n_terms, n_values)`. */ +struct ZTable { + TableKind kind = TableKind::phi; + std::vector edges; + double lower = 0.0; + double upper = 0.0; + std::vector coefficients; + std::size_t n_terms = 0; + std::size_t n_values = 0; +}; + +[[nodiscard]] constexpr auto describe(const ZTable* /*unused*/) { + using E = fields::Extent; + return fields::table( + "ZTable", fields::value("kind", &ZTable::kind), + fields::array("edges", &ZTable::edges, E::of("n_edges")), + fields::value("lower", &ZTable::lower), fields::value("upper", &ZTable::upper), + fields::array("coefficients", &ZTable::coefficients, E::of("n_edges", -1), + E::of("n_terms"), E::of("n_values")), + fields::count("n_terms", &ZTable::n_terms), + fields::count("n_values", &ZTable::n_values)); +} + +/** The z tables' position slots (`stage::ZSlots::configure`). */ +struct ZSlotsConfig { + bool phi = false; + bool prefactor = false; + std::size_t slots = 0; + bool rate = false; +}; + +[[nodiscard]] constexpr auto describe(const ZSlotsConfig* /*unused*/) { + using Z = ZSlotsConfig; + return fields::table("ZSlots", fields::value("phi", &Z::phi), + fields::value("prefactor", &Z::prefactor), + fields::value("slots", &Z::slots), + fields::value("rate", &Z::rate)); +} + +/** A coupled flow's certificate and the guard's constants (solprop SEP 45 phase 4): + each section's row-sum norm, each section's conditioning bound per active bin + `(n_sections, n_bins)`, the Taylor scale, the most squarings and the rounding + allowance, as solprop's `_flow_squarings` and `_check_flow_conditioning` read + them. */ +struct FlowGuard { + std::vector row_sum; + std::vector condition_bound; + double taylor_scale = 0.0; + int max_squarings = 0; + double allowance = 0.0; +}; + +[[nodiscard]] constexpr auto describe(const FlowGuard* /*unused*/) { + using F = FlowGuard; + using E = fields::Extent; + return fields::table("FlowGuard", + fields::array("row_sum", &F::row_sum, E::of("n_sections")), + fields::array("condition_bound", &F::condition_bound, + E::of("n_sections"), E::of("n_bins")), + fields::value("taylor_scale", &F::taylor_scale), + fields::value("max_squarings", &F::max_squarings), + fields::value("allowance", &F::allowance)); +} + +/** The Runge-Kutta trial's tableau nodes and error control (solprop SEP 45): the + nodes, the tolerances, a weighted controller's weights (empty for none) and the + tableau's dense-output weights (empty without dense output). */ +struct RungeKuttaConfig { + std::vector nodes; + double rtol = 0.0; + double atol = 0.0; + std::vector weights; + std::vector dense_weights; +}; + +[[nodiscard]] constexpr auto describe(const RungeKuttaConfig* /*unused*/) { + using R = RungeKuttaConfig; + using E = fields::Extent; + return fields::table( + "RungeKuttaConfig", fields::array("nodes", &R::nodes, E::of("n_stages")), + fields::value("rtol", &R::rtol), fields::value("atol", &R::atol), + fields::array("weights", &R::weights, E::any()), + fields::array("dense_weights", &R::dense_weights, E::any())); +} + +/** The resident Adams history (solprop SEP 16, SEP 39): its rows, whether trials carry + the transported compensation, whether the steps are kept for interpolation, the + fused (interaction) formulation, and the controller's scale. */ +struct AdamsConfig { + std::size_t slots = 0; + bool compensated = false; + bool interpolate = false; + bool fused = false; + double rtol = 0.0; + double atol = 0.0; + std::vector weights; +}; + +[[nodiscard]] constexpr auto describe(const AdamsConfig* /*unused*/) { + using A = AdamsConfig; + using E = fields::Extent; + return fields::table( + "AdamsConfig", fields::value("slots", &A::slots), + fields::value("compensated", &A::compensated), + fields::value("interpolate", &A::interpolate), fields::value("fused", &A::fused), + fields::value("rtol", &A::rtol), fields::value("atol", &A::atol), + fields::array("weights", &A::weights, E::any())); +} + +/** The boundary monitor's weights where the state lives (solprop SEP 21), and the split + collar's walk-off bucket of each bin (solprop #440; empty for none). */ +struct MonitorBinding { + std::vector weights; + std::vector column_weights; + std::vector buckets; + std::size_t bucket_count = 0; +}; + +[[nodiscard]] constexpr auto describe(const MonitorBinding* /*unused*/) { + using M = MonitorBinding; + using E = fields::Extent; + return fields::table( + "MonitorBinding", fields::array("weights", &M::weights, E::any()), + fields::array("column_weights", &M::column_weights, E::any()), + fields::array("buckets", &M::buckets, fields::Dtype::uint8, E::any()), + fields::value("bucket_count", &M::bucket_count)); +} + +[[nodiscard]] constexpr auto describe(const EdgeLines* /*unused*/) { + using L = EdgeLines; + using E = fields::Extent; + return fields::table( + "EdgeLines", fields::array("axes", &L::axes, E::of("n_lines")), + fields::array("counts", &L::counts, E::of("n_lines")), + fields::array("positions", &L::positions, E::any()), + fields::array("windows", &L::windows, E::any()), + fields::array("inward", &L::inward, E::any()), + fields::array("factors", &L::factors, E::of("n_lines")), + fields::array("measures", &L::measures, E::of("n_lines")), + fields::array("onsets", &L::onsets, E::any()), + fields::array("steps", &L::steps, E::of("n_lines")), + fields::value("k_min", &L::k_min), fields::array("scale", &L::scale, E::any()), + fields::value("batch_bytes", &L::batch_bytes)); +} + +/** The transverse edge's tables where the state lives (solprop SEP 44): the faces', + the clip's and the totals' weights, a reduction's synthesis (empty for none), the + first row, and a requested collar's lines. */ +struct EdgeBinding { + std::vector faces; + std::vector clip; + std::vector totals; + std::vector synthesis; + std::size_t first_row = 0; + std::optional lines; +}; + +[[nodiscard]] constexpr auto describe(const EdgeBinding* /*unused*/) { + using B = EdgeBinding; + using E = fields::Extent; + return fields::table("EdgeBinding", fields::array("faces", &B::faces, E::any()), + fields::array("clip", &B::clip, E::any()), + fields::array("totals", &B::totals, E::any()), + fields::array("synthesis", &B::synthesis, E::any()), + fields::value("first_row", &B::first_row), + fields::value("lines", &B::lines)); +} + +/** Everything fixed for a workspace beside the problem's groups (SEP 52 section 5.3). + Each part is absent where the problem has none. */ +struct Setup { + std::optional stage_tables; + std::optional z_slots; + std::vector z_tables; + std::optional flow_guard; + std::optional runge_kutta; + std::optional adams; + std::optional low_storage; + std::optional monitor; + std::optional edge; +}; + +[[nodiscard]] constexpr auto describe(const Setup* /*unused*/) { + using S = Setup; + return fields::table( + "Setup", fields::value("stage_tables", &S::stage_tables), + fields::value("z_slots", &S::z_slots), fields::value("z_tables", &S::z_tables), + fields::value("flow_guard", &S::flow_guard), + fields::value("runge_kutta", &S::runge_kutta), fields::value("adams", &S::adams), + fields::value("low_storage", &S::low_storage), + fields::value("monitor", &S::monitor), fields::value("edge", &S::edge)); +} + +// -------------------------------------------------------------------- the run records +// The structs below mirror `solprop.backends.records`, field for field, so that one +// table holds each to its Python dataclass; `to_native` forms what the marches and the +// session read from them. + +/** `solprop.stepper.controller.PIController`. */ +struct ControllerRecord { + double rtol = 0.0; + double atol = 0.0; + double safety = 0.0; + double max_factor = 0.0; + double min_factor = 0.0; + double beta1 = 0.0; + double beta2 = 0.0; + std::int64_t lag = 0; + bool reject_free = false; + std::optional> weights; + std::int64_t estimator_order = 0; + std::string region; +}; + +[[nodiscard]] constexpr auto describe(const ControllerRecord* /*unused*/) { + using C = ControllerRecord; + using E = fields::Extent; + return fields::table( + "PIController", fields::value("rtol", &C::rtol), fields::value("atol", &C::atol), + fields::value("safety", &C::safety), fields::value("max_factor", &C::max_factor), + fields::value("min_factor", &C::min_factor), fields::value("beta1", &C::beta1), + fields::value("beta2", &C::beta2), fields::value("lag", &C::lag), + fields::value("reject_free", &C::reject_free), + fields::array("weights", &C::weights, E::of("n_omega")), + fields::value("estimator_order", &C::estimator_order), + fields::value("region", &C::region)); +} + +/** `solprop.backends.records.RungeKuttaPolicy`. */ +struct RungeKuttaPolicyRecord { + ControllerRecord controller; + double dz_min = 0.0; + double dz_max = 0.0; + bool auto_init = false; + double stretch = 0.0; + double z_end = 0.0; + std::vector save_planes; + bool interpolate = false; + std::vector hard_kinks; + std::vector breakpoints; + int landing_ulps = 0; + double start_growth = 0.0; + std::optional quiet_interval; +}; + +[[nodiscard]] constexpr auto describe(const RungeKuttaPolicyRecord* /*unused*/) { + using R = RungeKuttaPolicyRecord; + return fields::table( + "RungeKuttaPolicy", fields::value("controller", &R::controller), + fields::value("dz_min", &R::dz_min), fields::value("dz_max", &R::dz_max), + fields::value("auto_init", &R::auto_init), fields::value("stretch", &R::stretch), + fields::value("z_end", &R::z_end), fields::value("save_planes", &R::save_planes), + fields::value("interpolate", &R::interpolate), + fields::value("hard_kinks", &R::hard_kinks), + fields::value("breakpoints", &R::breakpoints), + fields::value("landing_ulps", &R::landing_ulps), + fields::value("start_growth", &R::start_growth), + fields::value("quiet_interval", &R::quiet_interval)); +} + +/** `solprop.stepper.schedule.FixedSchedule`: its steps and start; the edges are + accumulated in step order (`FixedSchedule.edges`). */ +struct ScheduleRecord { + std::vector steps; + double z_start = 0.0; +}; + +[[nodiscard]] constexpr auto describe(const ScheduleRecord* /*unused*/) { + using E = fields::Extent; + return fields::table( + "FixedSchedule", fields::array("steps", &ScheduleRecord::steps, E::of("n_steps")), + fields::value("z_start", &ScheduleRecord::z_start)); +} + +/** `solprop.backends.records.PlanePlan`. */ +struct PlanePlanRecord { + double z = 0.0; + std::vector planes; + std::size_t next_plane = 0; + bool launch_pending = true; + std::uint64_t step_planes = 0; + bool dense = false; + std::uint64_t period = 0; + std::size_t replay_steps = 0; + double replay_length = 0.0; + std::size_t attempt_capacity = 0; + std::size_t row_capacity = 0; + std::size_t call_attempts = 0; + double call_seconds = 0.0; +}; + +[[nodiscard]] constexpr auto describe(const PlanePlanRecord* /*unused*/) { + using P = PlanePlanRecord; + using E = fields::Extent; + return fields::table

("PlanePlan", fields::value("z", &P::z), + fields::array("planes", &P::planes, E::of("n_z")), + fields::value("next_plane", &P::next_plane), + fields::value("launch_pending", &P::launch_pending), + fields::value("step_planes", &P::step_planes), + fields::value("dense", &P::dense), + fields::value("period", &P::period), + fields::value("replay_steps", &P::replay_steps), + fields::value("replay_length", &P::replay_length), + fields::value("attempt_capacity", &P::attempt_capacity), + fields::value("row_capacity", &P::row_capacity), + fields::value("call_attempts", &P::call_attempts), + fields::value("call_seconds", &P::call_seconds)); +} + +/** `solprop.backends.records.Resumption`: the numbers a resume reads by name. */ +struct ResumptionRecord { + bool record = false; + bool collar_quiet = false; + std::map numbers; + std::optional>> unwatched; + std::optional> resumed_at; + std::optional>> planes; +}; + +[[nodiscard]] constexpr auto describe(const ResumptionRecord* /*unused*/) { + using R = ResumptionRecord; + return fields::table( + "Resumption", fields::value("record", &R::record), + fields::value("collar_quiet", &R::collar_quiet), + fields::value("numbers", &R::numbers), fields::value("unwatched", &R::unwatched), + fields::value("resumed_at", &R::resumed_at), fields::value("planes", &R::planes)); +} + +/** `solprop.backends.records.EdgeResumption`. */ +struct EdgeResumptionRecord { + bool record = false; + std::map numbers; + std::optional> edge_baseline; + std::optional> edge_max; + std::optional> edge_max_raw; + std::optional reads; + std::optional transverse_status; +}; + +[[nodiscard]] constexpr auto describe(const EdgeResumptionRecord* /*unused*/) { + using R = EdgeResumptionRecord; + return fields::table("EdgeResumption", fields::value("record", &R::record), + fields::value("numbers", &R::numbers), + fields::value("edge_baseline", &R::edge_baseline), + fields::value("edge_max", &R::edge_max), + fields::value("edge_max_raw", &R::edge_max_raw), + fields::value("reads", &R::reads), + fields::value("transverse_status", &R::transverse_status)); +} + +/** `solprop.backends.records.MonitorContinuation`. */ +struct ContinuationRecord { + ResumptionRecord record; + EdgeResumptionRecord edge; + bool plane = false; + std::vector> unwatched; +}; + +[[nodiscard]] constexpr auto describe(const ContinuationRecord* /*unused*/) { + using C = ContinuationRecord; + return fields::table("MonitorContinuation", fields::value("record", &C::record), + fields::value("edge", &C::edge), + fields::value("plane", &C::plane), + fields::value("unwatched", &C::unwatched)); +} + +/** `solprop.backends.records.MonitorRecords`. */ +struct MonitorRecordsRecord { + watch::Config config; + std::optional edge; + std::optional continuation; +}; + +[[nodiscard]] constexpr auto describe(const MonitorRecordsRecord* /*unused*/) { + using M = MonitorRecordsRecord; + return fields::table("MonitorRecords", fields::value("config", &M::config), + fields::value("edge", &M::edge), + fields::value("continuation", &M::continuation)); +} + +/** `solprop.backends.records.RunRecords`: the method's policy is the Adams march's or + the Runge-Kutta march's, told apart by their fields. */ +struct RunRecordsRecord { + std::variant policy; + std::optional low_storage; + std::optional schedule; + PlanePlanRecord planes; + std::optional monitor; +}; + +[[nodiscard]] constexpr auto describe(const RunRecordsRecord* /*unused*/) { + using R = RunRecordsRecord; + return fields::table("RunRecords", fields::value("policy", &R::policy), + fields::value("low_storage", &R::low_storage), + fields::value("schedule", &R::schedule), + fields::value("planes", &R::planes), + fields::value("monitor", &R::monitor)); +} + +/** One persistent row of a resumed Adams history, `(n_slots, rows, n_omega)`. */ +struct HistoryRow { + std::string name; + std::vector values; + std::size_t n_slots = 0; + std::size_t n_rows = 0; + std::size_t n_omega = 0; +}; + +[[nodiscard]] constexpr auto describe(const HistoryRow* /*unused*/) { + using H = HistoryRow; + using E = fields::Extent; + return fields::table("HistoryRow", fields::value("name", &H::name), + fields::array("values", &H::values, E::of("n_slots"), + E::of("n_rows"), E::of("n_omega")), + fields::count("n_slots", &H::n_slots), + fields::count("n_rows", &H::n_rows), + fields::count("n_omega", &H::n_omega)); +} + +/** What one run starts from (`Workspace::start`): its records, the initial field and + noise as the state takes them (`set_initial`), the march's state at the start (the + Adams march's or the Runge-Kutta march's, none for a fresh state of its own), a + resumed history's rows, the statistics plans, and the monitor's launch readings of + the input noise: its floor (energy, then four regions' shares) and the edge's. */ +struct RunStart { + RunRecordsRecord records; + std::vector field; + std::vector noise; + std::optional adams; + std::optional runge_kutta; + std::vector rows; + std::shared_ptr plane_statistics; + std::shared_ptr row_statistics; + std::optional> floor; + std::optional edge_noise; +}; + +[[nodiscard]] constexpr auto describe(const RunStart* /*unused*/) { + using R = RunStart; + using E = fields::Extent; + return fields::table( + "RunStart", fields::value("records", &R::records), + fields::array("field", &R::field, E::any()), + fields::array("noise", &R::noise, E::any()), fields::value("adams", &R::adams), + fields::value("runge_kutta", &R::runge_kutta), fields::value("rows", &R::rows), + fields::value("plane_statistics", &R::plane_statistics), + fields::value("row_statistics", &R::row_statistics), + fields::value("floor", &R::floor), fields::value("edge_noise", &R::edge_noise)); +} + +/** The Runge-Kutta march's policy from its record (kernel contract section 12): the + controller's gains, factors, lag and acceptance rule flattened in, and the + equivalent norm's power `estimator_order + 1` and its reciprocal. */ +[[nodiscard]] rk::Policy to_native(const RungeKuttaPolicyRecord& record); +/** A fixed schedule's steps and edges, accumulated in step order. */ +[[nodiscard]] march::Schedule to_native(const ScheduleRecord& record); +/** A monitor record's resumption, each number by name; refuses an unknown name. */ +[[nodiscard]] watch::Resumption to_native(const ResumptionRecord& record); +/** An edge record's resumption, likewise. */ +[[nodiscard]] transverse::Resumption to_native(const EdgeResumptionRecord& record); + +/** A test's injected failure by name: the stage (`startup`, `trial`, `trial_source` + or `accept`) and the category (`convergence`, `value`, `backend`, `sigint` or + `sigterm`). */ +[[nodiscard]] engines::MarchFault +fault_from(const std::string& stage, std::size_t after, const std::string& category); + +/** The stage tables' consistency (the checks `adams_stage_tables` makes). */ +void validate(const stage::Tables& tables); + +// ------------------------------------------------------------------------ the +// workspace + +/** Which march a workspace runs, from its setup: the Adams march with its history, + the low-storage replay with its settings, or else the Runge-Kutta march. */ +enum class MethodKind : int { adams = 0, runge_kutta = 1, low_storage = 2 }; + +class Workspace; + +/** A session over a leased workspace (SEP 47): it keeps the lease until it closes, and + reads what only the workspace knows (the history rows, the z table) for the + session's snapshot and noise phase under the session's lock. */ +class Run { +public: + Run(Workspace& owner, std::unique_ptr session); + ~Run(); + Run(const Run&) = delete; + Run& operator=(const Run&) = delete; + Run(Run&&) = delete; + Run& operator=(Run&&) = delete; + + [[nodiscard]] session::Session& session() { return *session_; } + + /** A method-history snapshot at the pending ticket: the march's state, the accepted + field and each persistent history row with its extents; none for a Runge-Kutta + march or before any history (`HostAdamsMarch.snapshot`). */ + struct Snapshot { + march::State state; + std::vector> field; + std::vector names; + std::vector> extents; + std::vector>> rows; + }; + [[nodiscard]] std::optional snapshot(std::uint64_t sequence, + std::uint64_t generation); + /** The Adams march's state and the orders of its accepted steps from `since`, read + between advances; none for a Runge-Kutta march. */ + [[nodiscard]] std::optional>> + march_state(std::size_t since); + /** A z table's `Phi` at `z`: the noise phase at the ticket's plane. */ + [[nodiscard]] std::vector noise_phase(std::uint64_t sequence, + std::uint64_t generation, double z); + /** Close the session and release the lease; false (nothing released) when the + session's lock could not be taken. */ + bool close() noexcept; + [[nodiscard]] bool closed() const noexcept { return owner_ == nullptr; } + +private: + Workspace* owner_; + std::unique_ptr session_; +}; + +/** The timing probe (SEP 52 section 5.5): trials of the workspace's march from a loaded + start, committing nothing. A Runge-Kutta trial keeps the loaded state, and its end + state reads back as an owning copy; the low-storage march's trial advances the + discarded registers in place, its field is refused, and the workspace closes with + the probe. */ +class Probe { +public: + Probe(Workspace& owner, std::vector field, std::vector noise, + double z); + ~Probe(); + Probe(const Probe&) = delete; + Probe& operator=(const Probe&) = delete; + Probe(Probe&&) = delete; + Probe& operator=(Probe&&) = delete; + + /** One trial from `z` over `dz`: the Runge-Kutta march's scaled error norm, or the + low-storage step's (0, or non-finite on a divergence). */ + double trial(double z, double dz); + /** The last Runge-Kutta trial's end state, as a kept step would be, the loaded + state loaded again after it; refused for the low-storage march. */ + [[nodiscard]] std::vector field(); + /** Trials taken. */ + [[nodiscard]] std::size_t trials() const noexcept { return trials_; } + /** The source evaluations the trials made: the low-storage step's four passes each; + the state's own count of a Runge-Kutta trial's stages. */ + [[nodiscard]] std::size_t evaluations() const; + [[nodiscard]] bool low_storage() const noexcept { return low_storage_; } + [[nodiscard]] double z() const noexcept { return z_; } + void close() noexcept; + [[nodiscard]] bool closed() const noexcept { return owner_ == nullptr; } + +private: + Workspace* owner_; + std::vector field_; + std::vector noise_; + double z_; + bool low_storage_; + std::optional length_; + std::size_t trials_ = 0; + std::size_t evaluations_at_load_ = 0; + std::unique_ptr engine_; +}; + +/** One problem's state and every set-once table, guard and geometry (SEP 52 section + 5.3). It holds no march state: each run's comes in its `RunStart`. */ +class Workspace { +public: + explicit Workspace(Problem problem); + ~Workspace(); + Workspace(const Workspace&) = delete; + Workspace& operator=(const Workspace&) = delete; + Workspace(Workspace&&) = delete; + Workspace& operator=(Workspace&&) = delete; + + // -- the setup, applied at construction or, for the old seam, one part at a time + void set_stage_tables(stage::Tables tables); + void configure_z_slots(const ZSlotsConfig& slots); + void upload_z_table(const ZTable& table); + void configure_flow_guard(FlowGuard guard); + void configure_runge_kutta(RungeKuttaConfig config); + void configure_adams(const AdamsConfig& config); + void configure_low_storage(rk::low_storage::Config config); + void set_monitor(std::optional monitor); + void set_edge(std::optional edge); + /** The old seam's per-run march configuration. */ + void configure_adams_march(march::Policy policy, bool fused, bool compensated, + bool interpolate, march::Schedule schedule); + void configure_rk_march(rk::Policy policy, std::vector nodes, double rtol, + double atol, march::Schedule schedule); + void set_rk_weights(std::vector weights); + /** The old seam's dense-output weights, from a session's plan. */ + void set_dense_weights(std::vector weights); + /** Fail the resident engine's `stage` after `after` more passes (a test hook). */ + void inject_fault(engines::MarchFault fault); + /** Bind a host source (solprop SEP 49), or unbind with null; CPU builds only. */ + void bind_host_source(std::shared_ptr source); + + // -- the lease (SEP 47 section 5.2): one session or probe at a time + void lease(const void* holder); + void release(const void* holder) noexcept; + void require_unleased() const; + [[nodiscard]] bool leased() const noexcept { return holder_ != nullptr; } + + /** The state, open and not leased: every mutation and every live read. */ + GeneralState& state(); + /** The state's fixed facts, which a lease leaves readable. */ + [[nodiscard]] GeneralState& built() const; + /** The state `holder` leases, for its own reads under its lock. */ + [[nodiscard]] GeneralState& leased_state(const void* holder) const; + [[nodiscard]] bool closed() const noexcept; + /** Close the session or probe that leases the workspace first, then release the + state; a session that cannot close keeps it. */ + void close() noexcept; + + // -- the trial and the coupled flow's guard + /** A Runge-Kutta trial whose stage rows the state forms from the stage tables at + `z + c_i dz` and the step's end (solprop SEP 45 phase 2): the partials. */ + std::vector staged_trial(double z, double dz, bool prepare_only, + const std::vector* nodes = nullptr); + /** `_flow_trial`'s guards, transcribed (solprop SEP 45 phase 4): a set of actions is + held for one (section, step); a length whose exponent needs too many squarings + is refused before forming, and a measured conditioning above the certificate's + after, each as a `BackendRefusal`. */ + void guard_flow(std::size_t section, double dz, const std::vector& nodes); + /** Forget the held actions' key (a test forming its own). */ + void forget_flow_key() noexcept { flow_key_.reset(); } + /** A weighted controller's norm from a trial's partials `(3, slots)`. */ + double weighted_score(const double* partials, std::size_t slots, double rtol, + double atol); + + // -- the marches + [[nodiscard]] MethodKind kind() const noexcept; + /** The march a session runs: from the configured policy, schedule and stage tables, + its engine over the state, its dense output when `dense`, and its state at the + start. */ + session::Method method(MethodKind kind, std::variant start, + bool dense); + /** One call of the configured Adams march (the decision traces' entry point). */ + march::Result run_adams(march::State& state, const march::Bounds& bounds); + /** One call of the configured Runge-Kutta march. */ + rk::Result run_rk(rk::State& state, const march::Bounds& bounds); + + // -- runs and probes + /** Load a start as a fresh workspace's (SEP 22 section 4.7): the field and noise, + the collar back in the stages, no recycled stage and no monitor bound. */ + void load(std::span field, std::span noise); + /** Start one run from `start` (SEP 52 section 5.3), leasing the workspace to it. */ + std::unique_ptr start(RunStart start); + /** Start a session from a method and a plan the old seam formed (`start_session`). */ + std::unique_ptr start(session::Method method, session::Plan plan, double z); + /** Load `field` and `noise` at `z` and return a probe of the configured march. */ + std::unique_ptr probe(std::vector field, std::vector noise, + double z); + /** A probe from a run's start (SEP 52 section 5.5): its field, noise and position, + and, for the low-storage replay, the policy's landings and the schedule its table + keys come from. Its march state, history and monitor are not read. */ + std::unique_ptr probe(RunStart start); + + // -- what the old seam's accessors read + [[nodiscard]] const std::optional& stage_tables() const noexcept { + return stage_tables_; + } + [[nodiscard]] stage::ZSlots& z_slots() noexcept { return z_slots_; } + [[nodiscard]] std::size_t elements() const noexcept { return elements_; } + [[nodiscard]] std::size_t columns() const noexcept { return columns_; } + [[nodiscard]] std::size_t stages() const noexcept { return stages_; } + /** A trial's stage rows from the tables (`stage::row`, `trial`, `sample`). */ + stage::Trial stage_trial(double z0, double z1); + [[nodiscard]] std::vector stage_rate(double z) const; + /** The z table's `Phi` at `z`, through the one slot cache, for `holder`. */ + std::vector table_phi(const void* holder, double z); + /** The configured march's engines over the state, for an engine-level test: the + Runge-Kutta (or low-storage) engine and the Adams engine. */ + std::unique_ptr trial_engine(); + std::unique_ptr adams_engine(); + +private: + friend class Run; + friend class Probe; + void apply(const Setup& setup); + void require_built() const; + void require_open() const; + void bind_run_monitor(); + + std::size_t columns_ = 0; + std::size_t elements_ = 0; + std::size_t stages_ = 0; + std::shared_ptr state_; + std::optional stage_tables_; + stage::Anchor stage_anchor_; + stage::ZSlots z_slots_; + std::optional flow_guard_; + std::optional> flow_key_; + std::optional runge_kutta_; + std::optional adams_; + std::optional low_storage_; + std::optional monitor_; + bool occupancy_bound_ = false; + std::optional edge_; + std::optional march_policy_; + march::Schedule march_schedule_; + bool march_fused_ = false; + bool march_compensated_ = false; + bool march_interpolate_ = false; + std::optional rk_policy_; + march::Schedule rk_schedule_; + std::optional fault_; + const void* holder_ = nullptr; + Run* run_ = nullptr; + Probe* probe_ = nullptr; +}; + +} // namespace solprop_native diff --git a/native/src/bindings.cpp b/native/src/bindings.cpp index 9f55010aa..af5782b89 100644 --- a/native/src/bindings.cpp +++ b/native/src/bindings.cpp @@ -4,6 +4,7 @@ #include "bindings_transverse.hpp" #include "helpers.hpp" +#include "records.hpp" #include "solprop_native/adams_march.hpp" #include "solprop_native/core.hpp" #include "solprop_native/crossing.hpp" @@ -19,6 +20,7 @@ #include "solprop_native/stage_tables.hpp" #include "solprop_native/vmath.hpp" #include "solprop_native/watch.hpp" +#include "solprop_native/workspace.hpp" #include @@ -39,6 +41,7 @@ #include #include #include +#include #include #include #include @@ -93,8 +96,18 @@ using HostField = using ComplexStorage = std::vector>; using RealStorage = std::vector; -class BoundState; -class BoundSession; +// A native object the runtime closes before Kokkos is finalised: a state or a +// workspace, each of which closes the session that leases it first. +class Owned { +public: + Owned() = default; + Owned(const Owned&) = delete; + Owned& operator=(const Owned&) = delete; + Owned(Owned&&) = delete; + Owned& operator=(Owned&&) = delete; + virtual ~Owned() = default; + virtual void close() noexcept = 0; +}; // solprop SEP 49 section 6.2: a host source whose three entry points are a Python // object's `begin(cost)`, `evaluate(field, z, purpose, out)` and `end(outcome)`. Each @@ -153,11 +166,23 @@ struct RuntimeState { int requested_threads = 0; // The BLAS thread policy the package applied at start-up, if any. std::string blas_policy; - std::vector states; + std::vector states; }; RuntimeState runtime_state; +void register_owned(Owned* owned) { + const std::scoped_lock lock(runtime_state.mutex); + runtime_state.states.push_back(owned); +} + +void forget_owned(Owned* owned) { + const std::scoped_lock lock(runtime_state.mutex); + const auto found = std::ranges::find(runtime_state.states, owned); + if (found != runtime_state.states.end()) + runtime_state.states.erase(found); +} + template std::size_t element_count(const nb::ndarray& values) { std::size_t count = 1; @@ -471,56 +496,83 @@ typename ExactArray::Output array_of(const std::vector& values return {storage.release(), 1, shape.data(), owner}; } -template struct IsVector : std::false_type {}; -template struct IsVector> : std::true_type {}; +/** The problem's set-once data, copied on write (`Problem::setup`). */ +native::Setup& setup_of(native::Problem& problem) { + auto copy = problem.setup ? std::make_shared(*problem.setup) + : std::make_shared(); + auto& held = *copy; + problem.setup = std::move(copy); + return held; +} -/** One group of the problem's fields, bound as a nested class: scalars read and - written as they are, vectors as exact arrays (`exact_vector`). */ -template class Fields { -public: - Fields(nb::handle scope, const char* name, std::string path) - : class_(scope, name), path_(std::move(path)) { - class_.def(nb::init<>()); - } - /** Bind `member` as `name`; a vector field of a nonzero `rank` takes arrays of that - rank alone, as the extents a count beside it gives are laid out. */ - template - Fields& field(const char* name, Value Group::* member, const std::size_t rank = 0) { - if constexpr (IsVector::value) { +/** Bind one part of the problem's setup as a property that reads a record (a + dataclass or a mapping) through its table, and writes it back as a dict. */ +template +void bind_setup(nb::class_& problem, const char* name, + Value native::Setup::* member, const char* python_type) { + const std::string getter = native::concat("def ", name, "(self) -> ", python_type); + const std::string setter = + native::concat("def ", name, "(self, arg: ", python_type, ", /) -> None"); + problem.def_prop_rw( + name, + [member](const native::Problem& self) -> nb::object { + if (!self.setup) + return native::records::write_value(Value{}); + return native::records::write_value((*self.setup).*member); + }, + [member, name](native::Problem& self, const nb::handle value) { + auto held = + native::records::read(value, native::concat("problem.", name)); + setup_of(self).*member = std::move(held); + }, + nb::for_getter(nb::sig(getter.c_str())), nb::for_setter(nb::sig(setter.c_str())), + nb::for_setter(nb::arg("value").none())); +} + +/** One group of the problem's fields, bound as a nested class from its field table + (solprop SEP 52 section 5.3): scalars read and written as they are, arrays as exact + arrays (`exact_vector`) of the table's rank, or of any rank where it gives none. A + group whose layouts its counts give keeps each array's shape for + `Problem::validate`, which holds the relations across groups. */ +template +void bind_group(const nb::handle scope, const char* name, const std::string& path) { + nb::class_ bound(scope, name); + bound.def(nb::init<>()); + native::fields::each(native::fields::table_of(), [&](const auto& field) { + using Field = std::remove_cvref_t; + constexpr int kind = native::records::FieldKind::kind; + if constexpr (kind == 2) { + using Vector = + std::remove_cvref_t().*field.member)>; // NOLINTNEXTLINE(readability-redundant-typename): nvcc's front end needs it - using Element = typename Value::value_type; + using Element = typename Vector::value_type; + constexpr std::size_t rank = std::tuple_size_v; + const auto member = field.member; + const char* label = field.name; // The setter's stub names the one dtype it takes. const std::string setter = - native::concat("def ", name, "(self, arg: numpy.typing.NDArray[", + native::concat("def ", label, "(self, arg: numpy.typing.NDArray[", ExactArray::scalar, "], /) -> None"); - class_.def_prop_rw( - name, [member](const Group& self) { return array_of(self.*member); }, - [member, rank, name, path = path_ + "." + name](Group& self, - const nb::handle value) { - // A group whose layouts its counts give keeps each array's shape for - // `Problem::validate`. + bound.def_prop_rw( + label, [member](const Group& self) { return array_of(self.*member); }, + [member, label, where = path + "." + label](Group& self, + const nb::handle value) { if constexpr (requires { self.shapes; }) { std::vector shape; - self.*member = exact_vector(value, path, rank, &shape); - self.shapes[name] = std::move(shape); + self.*member = exact_vector(value, where, rank, &shape); + self.shapes[label] = std::move(shape); } else { - static_cast(name); - self.*member = exact_vector(value, path, rank); + static_cast(label); + self.*member = exact_vector(value, where, rank); } }, nb::for_getter(nb::rv_policy::automatic), nb::for_setter(nb::sig(setter.c_str()))); - } else { - static_cast(rank); - class_.def_rw(name, member); + } else if constexpr (kind == 0) { + bound.def_rw(field.name, field.member); } - return *this; - } - -private: - nb::class_ class_; - std::string path_; -}; + }); +} void bind_problem(nb::module_& module_) { using P = native::Problem; @@ -529,181 +581,39 @@ void bind_problem(nb::module_& module_) { .value("field_analytic", native::FieldFamily::field_analytic) .value("envelope", native::FieldFamily::envelope); nb::class_

problem(module_, "Problem"); - Fields(problem, "Dims", "dims") - .field("n_omega", &P::Dims::n_omega) - .field("n_t", &P::Dims::n_t) - .field("n_to", &P::Dims::n_to) - .field("n_modes", &P::Dims::n_modes) - .field("n_pol_state", &P::Dims::n_pol_state) - .field("n_pol_transform", &P::Dims::n_pol_transform) - .field("n_nodes", &P::Dims::n_nodes) - .field("node_chunk", &P::Dims::node_chunk) - .field("family", &P::Dims::family); - Fields(problem, "Grid", "grid") - .field("crop_index", &P::Grid::crop_index) - .field("active_mask", &P::Grid::active_mask) - .field("norm_mask", &P::Grid::norm_mask) - .field("omega_window", &P::Grid::omega_window) - .field("omega", &P::Grid::omega) - .field("power_weight", &P::Grid::power_weight) - .field("time_window", &P::Grid::time_window) - .field("time_window_derivative", &P::Grid::time_window_derivative) - .field("carrier", &P::Grid::carrier) - .field("dt_fine", &P::Grid::dt_fine) - .field("dt", &P::Grid::dt); - Fields(problem, "Spatial", "spatial") - .field("n_x", &P::Spatial::n_x) - .field("n_y", &P::Spatial::n_y) - .field("k_squared", &P::Spatial::k_squared) - .field("k_squared_low", &P::Spatial::k_squared_low) - .field("numerator", &P::Spatial::numerator) - .field("clamped", &P::Spatial::clamped) - .field("kperp_sq", &P::Spatial::kperp_sq) - .field("kperp_sq_low", &P::Spatial::kperp_sq_low) - .field("frame", &P::Spatial::frame) - .field("spectral_rate", &P::Spatial::spectral_rate) - .field("user_rate", &P::Spatial::user_rate) - .field("absorber_rate", &P::Spatial::absorber_rate) - .field("kperp_rate", &P::Spatial::kperp_rate) - .field("evanescent_rate", &P::Spatial::evanescent_rate) - .field("k_x", &P::Spatial::k_x) - .field("k_y", &P::Spatial::k_y) - .field("far_field_slots", &P::Spatial::far_field_slots) - .field("n_p", &P::Spatial::n_p) - .field("kappa_sq", &P::Spatial::kappa_sq) - .field("absorber_matrix", &P::Spatial::absorber_matrix) - .field("spectral_weights", &P::Spatial::spectral_weights) - .field("on_axis", &P::Spatial::on_axis); - Fields(problem, "Flux", "flux") - .field("k_squared", &P::Flux::k_squared) - .field("k_squared_low", &P::Flux::k_squared_low) - .field("kperp_sq", &P::Flux::kperp_sq) - .field("kperp_sq_low", &P::Flux::kperp_sq_low) - .field("table", &P::Flux::table) - .field("closure", &P::Flux::closure); - Fields(problem, "Stepper", "stepper") - .field("n_stages", &P::Stepper::n_stages) - .field("tableau_matrix", &P::Stepper::tableau_matrix) - .field("tableau_nodes", &P::Stepper::tableau_nodes) - .field("solution_weights", &P::Stepper::solution_weights) - .field("error_weights", &P::Stepper::error_weights) - .field("first_same_as_last", &P::Stepper::first_same_as_last) - .field("weighted_controller", &P::Stepper::weighted_controller) - .field("modified_noise", &P::Stepper::modified_noise) - .field("low_storage", &P::Stepper::low_storage) - .field("low_storage_stage_register", &P::Stepper::low_storage_stage_register) - .field("low_storage_flows", &P::Stepper::low_storage_flows) - .field("low_storage_tiled_input", &P::Stepper::low_storage_tiled_input); - Fields(problem, "Linear", "linear") - .field("n_phi_terms", &P::Linear::n_phi_terms) - .field("n_prefactor_terms", &P::Linear::n_prefactor_terms) - .field("phi_table", &P::Linear::phi_table) - .field("prefactor_table", &P::Linear::prefactor_table) - .field("phi_terms", &P::Linear::phi_terms) - .field("prefactor_terms", &P::Linear::prefactor_terms); - Fields(problem, "Absorber", "absorber") - .field("in_stage", &P::Absorber::in_stage) - .field("split_step", &P::Absorber::split_step) - .field("fine", &P::Absorber::fine) - .field("coarse", &P::Absorber::coarse); - Fields(problem, "Transform", "transform") - .field("synthesis_matrix", &P::Transform::synthesis_matrix) - .field("projection_matrix", &P::Transform::projection_matrix) - .field("projection_coarse_matrix", &P::Transform::projection_coarse_matrix) - .field("synthesis", &P::Transform::synthesis) - .field("projection", &P::Transform::projection); - Fields(problem, "Kerr", "kerr") - .field("nonlinear", &P::Kerr::nonlinear) - .field("coefficient", &P::Kerr::coefficient) - .field("self_factor", &P::Kerr::self_factor) - .field("conjugate_factor", &P::Kerr::conjugate_factor) - .field("harmonic_factor", &P::Kerr::harmonic_factor) - .field("take_real", &P::Kerr::take_real); - Fields(problem, "Plasma", "plasma") - .field("enabled", &P::Plasma::enabled) - .field("envelope", &P::Plasma::envelope) - .field("gated", &P::Plasma::gated) - .field("stash", &P::Plasma::stash) - .field("envelope_rule_nodes", &P::Plasma::envelope_rule_nodes, 3) - .field("envelope_rule_weights", &P::Plasma::envelope_rule_weights, 3) - .field("envelope_drude_factor", &P::Plasma::envelope_drude_factor, 1) - .field("envelope_loss_factor", &P::Plasma::envelope_loss_factor, 1) - .field("charge_mass_ratio", &P::Plasma::charge_mass_ratio) - .field("ionisation_potential", &P::Plasma::ionisation_potential) - .field("log_field_min", &P::Plasma::log_field_min) - .field("d_log_field", &P::Plasma::d_log_field) - .field("field_min", &P::Plasma::field_min) - .field("field_max", &P::Plasma::field_max) - .field("rate_max", &P::Plasma::rate_max) - .field("rate_intervals", &P::Plasma::rate_intervals) - .field("rate_coefficients", &P::Plasma::rate_coefficients, 2) - .field("n_channels", &P::Plasma::n_channels) - .field("band", &P::Plasma::band) - .field("taps", &P::Plasma::taps, 1) - .field("channel_parameters", &P::Plasma::channel_parameters) - .field("channel_coefficients", &P::Plasma::channel_coefficients); - Fields(problem, "Raman", "raman") - .field("enabled", &P::Raman::enabled) - .field("thg", &P::Raman::thg) - .field("tensor_capable", &P::Raman::tensor_capable) - .field("n_terms", &P::Raman::n_terms) - .field("fraction", &P::Raman::fraction) - .field("epsilon0", &P::Raman::epsilon0) - .field("undamped", &P::Raman::undamped, 2) - .field("tensor_weights", &P::Raman::tensor_weights, 2) - .field("n_components", &P::Raman::n_components) - .field("row_component", &P::Raman::row_component) - .field("component_fraction", &P::Raman::component_fraction); - Fields(problem, "General", "general") - .field("enabled", &P::General::enabled) - .field("real_form", &P::General::real_form) - .field("map_intervals", &P::General::map_intervals) - .field("map_n_deg", &P::General::map_n_deg) - .field("components", &P::General::components) - .field("nodes", &P::General::nodes) - .field("node_chunk", &P::General::node_chunk) - .field("responses", &P::General::responses) - .field("terms", &P::General::terms) - .field("pad_scale", &P::General::pad_scale) - .field("epsilon0", &P::General::epsilon0) - .field("synthesis", &P::General::synthesis) - .field("projection", &P::General::projection) - .field("frequency_factor", &P::General::frequency_factor) - .field("delayed_spectrum", &P::General::delayed_spectrum) - .field("tensor", &P::General::tensor) - .field("delayed_tensor", &P::General::delayed_tensor) - .field("node_response", &P::General::node_response); - Fields(problem, "Flow", "flow") - .field("enabled", &P::Flow::enabled) - .field("active", &P::Flow::active) - .field("sections", &P::Flow::sections) - .field("terms", &P::Flow::terms) - .field("slot", &P::Flow::slot) - .field("frozen", &P::Flow::frozen) - .field("residual_terms", &P::Flow::residual_terms) - .field("left", &P::Flow::left) - .field("right", &P::Flow::right) - .field("eigenvalues", &P::Flow::eigenvalues) - .field("route", &P::Flow::route) - .field("fallback_vectors", &P::Flow::fallback_vectors) - .field("fallback_triangular", &P::Flow::fallback_triangular); - Fields(problem, "Dispersive", "dispersive") - .field("enabled", &P::Dispersive::enabled) - .field("symmetric", &P::Dispersive::symmetric) - .field("form", &P::Dispersive::form) - .field("inputs", &P::Dispersive::inputs) - .field("term_multipliers", &P::Dispersive::term_multipliers) - .field("coefficients", &P::Dispersive::coefficients) - .field("pair_constants", &P::Dispersive::pair_constants) - .field("quartics", &P::Dispersive::quartics) - .field("input_scale", &P::Dispersive::input_scale) - .field("output_scale", &P::Dispersive::output_scale) - .field("term_rows", &P::Dispersive::term_rows) - .field("term_channels", &P::Dispersive::term_channels) - .field("group_offsets", &P::Dispersive::group_offsets) - .field("group_members", &P::Dispersive::group_members) - .field("group_keys", &P::Dispersive::group_keys) - .field("node_region", &P::Dispersive::node_region); + bind_group(problem, "Dims", "dims"); + bind_group(problem, "Grid", "grid"); + bind_group(problem, "Spatial", "spatial"); + bind_group(problem, "Flux", "flux"); + bind_group(problem, "Stepper", "stepper"); + bind_group(problem, "Linear", "linear"); + bind_group(problem, "Absorber", "absorber"); + bind_group(problem, "Transform", "transform"); + bind_group(problem, "Kerr", "kerr"); + bind_group(problem, "Plasma", "plasma"); + bind_group(problem, "Raman", "raman"); + bind_group(problem, "General", "general"); + bind_group(problem, "Flow", "flow"); + bind_group(problem, "Dispersive", "dispersive"); + // solprop SEP 52 section 5.3: the set-once data a workspace applies, each part a + // record read through its table. + bind_setup(problem, "stage_tables", &native::Setup::stage_tables, + "collections.abc.Mapping[str, object] | None"); + bind_setup(problem, "z_slots", &native::Setup::z_slots, + "collections.abc.Mapping[str, object] | None"); + bind_setup(problem, "z_tables", &native::Setup::z_tables, + "collections.abc.Sequence[collections.abc.Mapping[str, object]]"); + bind_setup(problem, "flow_guard", &native::Setup::flow_guard, + "collections.abc.Mapping[str, object] | None"); + bind_setup(problem, "runge_kutta", &native::Setup::runge_kutta, + "collections.abc.Mapping[str, object] | None"); + bind_setup(problem, "adams", &native::Setup::adams, + "collections.abc.Mapping[str, object] | None"); + bind_setup(problem, "low_storage", &native::Setup::low_storage, "object | None"); + bind_setup(problem, "monitor", &native::Setup::monitor, + "collections.abc.Mapping[str, object] | None"); + bind_setup(problem, "edge", &native::Setup::edge, + "collections.abc.Mapping[str, object] | None"); problem.def(nb::init<>()) .def_rw("dims", &P::dims) .def_rw("grid", &P::grid) @@ -1332,13 +1242,6 @@ native::session::MonitorPlan monitor_plan_from(const nb::dict values) { return plan; } -/** Python's `format(value, f".{precision}g")`, which follows C's `%g`. */ -std::string py_g(const double value, const int precision) { - std::array buffer{}; - std::snprintf(buffer.data(), buffer.size(), "%.*g", precision, value); - return buffer.data(); -} - // solprop SEP 45 phase 3: the Runge-Kutta march's policy and state, from and to // solprop's `rk_march_policy` and `_NativeRungeKuttaMarch._state`. native::rk::Policy rk_policy_from(const nb::dict values) { @@ -1657,235 +1560,111 @@ class ScriptedRkMarch { std::vector log_; }; -class BoundState { +// The old seam's state (solprop SEP 47): a `native::Workspace` configured one call at a +// time, as solprop_native's adapter configures it. The lease, the flow guard, the +// marches' construction and the march entry points are the workspace's (workspace.hpp); +// this class converts and forwards. +class BoundState final : public Owned { public: explicit BoundState(native::Problem problem) - : columns_(problem.n_columns()), - elements_(problem.n_columns() * problem.dims.n_omega), - stages_(problem.stepper.n_stages), raman_terms_(problem.raman.n_terms), - raman_(problem.raman.enabled) { - problem.validate(); - general_state_ = std::make_shared(std::move(problem)); - const std::scoped_lock lock(runtime_state.mutex); - runtime_state.states.push_back(this); - } - ~BoundState() { + : raman_terms_(problem.raman.n_terms), raman_(problem.raman.enabled), + workspace_(std::make_unique(std::move(problem))) { + register_owned(this); + } + ~BoundState() override { close(); - const std::scoped_lock lock(runtime_state.mutex); - const auto found = std::ranges::find(runtime_state.states, this); - if (found != runtime_state.states.end()) - runtime_state.states.erase(found); + forget_owned(this); } BoundState(const BoundState&) = delete; BoundState& operator=(const BoundState&) = delete; - // The runtime's list of live states holds this address. BoundState(BoundState&&) = delete; BoundState& operator=(BoundState&&) = delete; + [[nodiscard]] native::Workspace& workspace() const { return *workspace_; } + void set_initial(const std::span field, const std::span noise) { - require_unleased(); - require_open(); - general_state_->set_initial(field, noise); + workspace_->state().set_initial(field, noise); } // solprop SEP 45 phase 2: a Runge-Kutta trial whose stage rows the state forms from // the uploaded tables, at the positions `z + c_i dz` and the step's end. std::vector rk_trial(const double z, const double dz, const std::vector& nodes, const bool prepare_only) { - require_open(); - return staged_trial(z, dz, nodes, prepare_only); - } - // The trial itself, which a session's engine calls on the state it leases. - std::vector staged_trial(const double z, const double dz, - const std::vector& nodes, - const bool prepare_only) { - if (!stage_tables_) - throw std::logic_error("a staged Runge-Kutta trial needs the stage tables"); - if (nodes.size() != stages_) - throw std::invalid_argument("the trial's nodes are the tableau's stages"); - const auto scalars = native::stage::rows(*stage_tables_, stage_anchor_, z, - native::rk::positions(z, dz, nodes)); - if (stage_tables_->flow.present()) - guarded_flow_actions(scalars.flow_section, dz, nodes); - auto& general = built_state(); - if (prepare_only) { - general.prepare_trial(dz, scalars); - return {}; - } - return general.trial_step(dz, scalars); + workspace_->require_unleased(); + workspace_->state(); + return workspace_->staged_trial(z, dz, prepare_only, &nodes); } - // solprop SEP 45 phase 4: `_flow_trial`'s guards, transcribed. A set of actions is - // held for one (section, step); a length whose exponent needs too many squarings is - // refused before forming, and a measured conditioning above the section's - // certificate after, each as solprop's `_flow_squarings` and - // `_check_flow_conditioning` refuse them, with their constants handed over. void flow_guard_configure(std::vector row_sum, std::vector condition_bound, const double taylor_scale, const int max_squarings, const double allowance) { - open_state(); - const std::size_t sections = row_sum.size(); - if (sections == 0 || condition_bound.size() % sections != 0) - throw std::invalid_argument("the flow guard's certificate is one row a section"); - flow_guard_ = FlowGuard{.row_sum = std::move(row_sum), - .condition_bound = std::move(condition_bound), - .taylor_scale = taylor_scale, - .max_squarings = max_squarings, - .allowance = allowance}; - flow_key_.reset(); - } - void guarded_flow_actions(const std::size_t section, const double dz, - const std::vector& nodes) { - if (!flow_guard_) - throw std::logic_error("a staged trial beside a coupled flow needs its guard"); - if (flow_key_ && flow_key_->first == section && flow_key_->second == dz) - return; - // Forgotten first: a refusal below leaves no set of actions behind a key. - flow_key_.reset(); - const auto& guard = *flow_guard_; - if (section >= guard.row_sum.size()) - throw std::out_of_range("the trial's flow section is past the guard's"); - std::vector fractions(nodes); - fractions.push_back(1.0); - for (const double fraction : fractions) { - if (fraction == 0.0) - continue; - const double largest = fraction * dz * guard.row_sum[section]; - int squarings = 0; - if (largest > guard.taylor_scale) - squarings = - static_cast(std::ceil(std::log2(largest / guard.taylor_scale))); - if (squarings > guard.max_squarings) - native::refuse( - "native cannot take a coupled flow action whose exponent has row-sum " - "norm ", - py_g(largest, 4), ": it would need ", squarings, " squarings, above the ", - guard.max_squarings, " this backend admits. Cap dz_max"); - } - const auto measured = general_state_->form_flow_actions(section, dz, fractions); - const std::size_t width = guard.condition_bound.size() / guard.row_sum.size(); - if (!measured.empty()) { - if (measured.size() != width) - throw std::logic_error("the measured conditioning is one value an active bin"); - const double* declared = guard.condition_bound.data() + section * width; - // NumPy's argmax: the first largest, or the first NaN. - std::size_t worst = 0; - double largest = measured[0] / (declared[0] * guard.allowance); - for (std::size_t bin = 1; bin < width && !std::isnan(largest); ++bin) { - const double excess = measured[bin] / (declared[bin] * guard.allowance); - if (std::isnan(excess) || excess > largest) { - largest = excess; - worst = bin; - } - } - if (largest > 1.0) - native::refuse( - "native measured a coupled flow conditioning of ", - py_g(measured[worst], 12), " over a step of ", py_g(dz, 4), - " m, above the ", py_g(declared[worst], 12), - " the certificate declares at active bin ", worst, " of section ", section, - " -- exceeding it by a factor ", py_g(largest, 12), - " 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"); - } - flow_key_ = std::make_pair(section, dz); + workspace_->configure_flow_guard({.row_sum = std::move(row_sum), + .condition_bound = std::move(condition_bound), + .taylor_scale = taylor_scale, + .max_squarings = max_squarings, + .allowance = allowance}); } - // solprop SEP 45 phase 3: the native Runge-Kutta march over the staged trial. void rk_march_configure(native::rk::Policy policy, std::vector nodes, const double rtol, const double atol, std::vector steps, std::vector edges) { - open_state(); - if (!stage_tables_) - throw std::logic_error("the native Runge-Kutta march needs the stage tables"); - if (nodes.size() != stages_) - throw std::invalid_argument("the march's nodes are the tableau's stages"); - rk_policy_ = std::move(policy); - rk_nodes_ = std::move(nodes); - rk_rtol_ = rtol; - rk_atol_ = atol; - rk_schedule_ = {.steps = std::move(steps), .edges = std::move(edges)}; + workspace_->configure_rk_march( + std::move(policy), std::move(nodes), rtol, atol, + {.steps = std::move(steps), .edges = std::move(edges)}); } nb::dict rk_march_run(const nb::dict state_values, const nb::dict bounds_values) { - require_unleased(); - if (!rk_policy_) - throw std::logic_error("the native Runge-Kutta march is not configured"); + workspace_->require_unleased(); auto state = rk_state_from(state_values); const auto bounds = march_bounds_from(bounds_values); - auto& general = open_state(); - native::engines::ResidentRungeKutta engine( - general, - [this](const double z, const double dz) { - return rk_trial(z, dz, rk_nodes_, false); - }, - rk_rtol_, rk_atol_, rk_weights_); native::rk::Result result; { const nb::gil_scoped_release release; - result = native::rk::run(rk_policy_.value(), state, engine, bounds, rk_schedule_); + result = workspace_->run_rk(state, bounds); } return rk_result_to(result, state); } std::vector trial_step(const double dz, const native::TrialScalars& scalars, const bool prepare_only = false) { - require_open(); + auto& state = workspace_->state(); if (prepare_only) { - general_state_->prepare_trial(dz, scalars); + state.prepare_trial(dz, scalars); return {}; } - return general_state_->trial_step(dz, scalars); + return state.trial_step(dz, scalars); } std::vector flow_actions_to_host(const bool inverse) { - require_open(); - return general_state_->flow_actions_to_host(inverse); + return workspace_->state().flow_actions_to_host(inverse); } std::vector adams_block_to_host() { - require_open(); - return general_state_->adams_block_to_host(); + return workspace_->state().adams_block_to_host(); } std::vector adams_exponent_to_host() { - require_open(); - return general_state_->adams_exponent_to_host(); + return workspace_->state().adams_exponent_to_host(); } std::vector form_flow_actions(const std::size_t section, const double dz, const std::vector& fractions) { - require_open(); - flow_key_.reset(); - return general_state_->form_flow_actions(section, dz, fractions); + auto& state = workspace_->state(); + workspace_->forget_flow_key(); + return state.form_flow_actions(section, dz, fractions); } std::vector weighted_error(const std::vector& scale) { - require_open(); - return general_state_->weighted_error(scale); + return workspace_->state().weighted_error(scale); } - // solprop SEP 47 section 6.3: the low-storage replay's flows and operator origin, - // which a session's low-storage engine reads beside the Runge-Kutta policy. void low_storage_configure(const std::size_t flows, const bool separable, const double origin) { - open_state(); - if (flows > 2) - throw std::invalid_argument("the low-storage march holds at most two flows"); - low_storage_ = native::rk::low_storage::Config{ - .flows = flows, .separable = separable, .origin = origin}; - } - // solprop SEP 45 phase 4: a weighted controller's weights, and its norm from a - // trial's partials, for both Runge-Kutta loops. + workspace_->configure_low_storage( + {.flows = flows, .separable = separable, .origin = origin}); + } void rk_weights_configure(std::vector weights) { - open_state(); - rk_weights_ = std::move(weights); + workspace_->set_rk_weights(std::move(weights)); } double rk_weighted_score(const double* partials, const std::size_t slots, const double rtol, const double atol) { - if (rk_weights_.empty()) - throw std::logic_error("no weighted controller's weights were configured"); - const std::vector values(partials, partials + 3 * slots); - return native::engines::ResidentRungeKutta::weighted_norm(open_state(), values, - rtol, atol, rk_weights_); + return workspace_->weighted_score(partials, slots, rtol, atol); } void prepare_raman(const std::vector& rates, const std::vector& densities) { - require_open(); - general_state_->prepare_raman(rates, densities); + workspace_->state().prepare_raman(rates, densities); } std::vector statistics(const std::uint64_t flags, const std::vector& windows, @@ -1895,16 +1674,14 @@ class BoundState { const double intensity_factor, const std::vector& channel_preionisation, const std::vector& power_weight) { - require_open(); - return general_state_->statistics(flags, windows, on_axis, density, taper, - preionisation, intensity_factor, - channel_preionisation, power_weight); + return workspace_->state().statistics(flags, windows, on_axis, density, taper, + preionisation, intensity_factor, + channel_preionisation, power_weight); } std::vector spatial_statistics(const std::uint64_t flags, const double intensity_factor, const double z) { - require_open(); - return general_state_->spatial_statistics(flags, intensity_factor, z); + return workspace_->state().spatial_statistics(flags, intensity_factor, z); } std::vector plane_fluence_trace(const double center_x, const double center_y, const double dx, const double dy, @@ -1912,496 +1689,197 @@ class BoundState { const std::size_t n_radii, const std::vector& cosines, const std::vector& sines) { - require_open(); - return general_state_->plane_fluence_trace(center_x, center_y, dx, dy, extent, - spacing, n_radii, cosines, sines); + return workspace_->state().plane_fluence_trace(center_x, center_y, dx, dy, extent, + spacing, n_radii, cosines, sines); } std::vector axis_spectrum(const std::vector& matrix) { - require_open(); - return general_state_->axis_spectrum(matrix); + return workspace_->state().axis_spectrum(matrix); } std::vector aperture_statistics(const std::uint64_t flags, const std::vector& apertures, const int exponent, const std::vector& regions, const double intensity_factor) { - require_open(); - return general_state_->aperture_statistics(flags, apertures, exponent, regions, - intensity_factor); + return workspace_->state().aperture_statistics(flags, apertures, exponent, regions, + intensity_factor); } std::vector planned_statistics(const std::shared_ptr& plan, const double z) { - require_open(); - return native::statistics::evaluate(*general_state_, *plan, z); + return native::statistics::evaluate(workspace_->state(), *plan, z); } void bind_edge(const std::vector& faces, const std::vector& clip, const std::vector& totals, const std::vector& synthesis, const std::size_t first_row) { - open_state().bind_edge(faces, clip, totals, synthesis, first_row); + workspace_->state().bind_edge(faces, clip, totals, synthesis, first_row); } - native::CrossedBytes crossed_bytes() { return built_state().crossed_bytes(); } + native::CrossedBytes crossed_bytes() { return workspace_->built().crossed_bytes(); } void bind_edge_lines(const native::EdgeLines& lines) { - open_state().bind_edge_lines(lines); + workspace_->state().bind_edge_lines(lines); } native::EdgeNumbers edge_reading(const bool faces, const bool whole, const bool totals, const bool strip, const bool current) { - return open_state().edge_reading(faces, whole, totals, strip, current); + return workspace_->state().edge_reading(faces, whole, totals, strip, current); } - // Not `require_open`: this stays a no-op on a closed state, whose pointer is null. + // A no-op on a closed state. void set_crossing_workers(const std::size_t workers) noexcept { - if (general_state_) - general_state_->set_crossing_workers(workers); + if (!workspace_->closed()) + workspace_->built().set_crossing_workers(workers); } void field_to_host(const std::span destination) { - require_open(); - general_state_->field_to_host(destination); + workspace_->state().field_to_host(destination); } /** The state's element count, `columns * n_omega`. */ - [[nodiscard]] std::size_t elements() const noexcept { return elements_; } + [[nodiscard]] std::size_t elements() const noexcept { return workspace_->elements(); } std::vector adams_source(const std::vector& input, const native::TrialScalars& scalars) { - require_open(); - return general_state_->adams_source(input, scalars); + return workspace_->state().adams_source(input, scalars); } void adopt(const std::vector& field, const double dz) { - require_unleased(); - require_open(); - general_state_->adopt(field, dz); - } - native::GeneralState& open_state() { - require_open(); - return *general_state_; + workspace_->state().adopt(field, dz); } - // The stage tables an exponential Adams trial reads natively (solprop SEP 39). + native::GeneralState& open_state() { return workspace_->state(); } void set_stage_tables(native::stage::Tables tables) { - open_state(); - if (tables.n_stages != stages_) - throw std::invalid_argument("the stage tables name another tableau's stages"); - // A z table's rows are its slots: the tables read the state's one cache. - const bool phi_table = tables.phi == native::stage::Terms::table; - const bool prefactor_table = tables.prefactor == native::stage::Terms::table; - if (phi_table != z_slots_.phi || prefactor_table != z_slots_.prefactor) - throw std::invalid_argument("the stage tables and the z table's slots disagree"); - if (phi_table || prefactor_table) { - tables.z_slots = &z_slots_; - tables.z_state = &open_state(); - } - stage_tables_ = std::move(tables); - stage_anchor_ = {}; + workspace_->set_stage_tables(std::move(tables)); } - // solprop SEP 39 phase 4: the z table's slots, one cache for every consumer. void table_slots(const bool phi, const bool prefactor, const std::size_t slots, const bool rate) { - open_state(); - z_slots_.configure(phi, prefactor, slots, rate); + workspace_->configure_z_slots( + {.phi = phi, .prefactor = prefactor, .slots = slots, .rate = rate}); } std::vector table_load(const std::vector& positions) { - if (!z_slots_.present()) + auto& slots = workspace_->z_slots(); + if (!slots.present()) throw std::logic_error("no z table's slots were configured"); - return z_slots_.load(open_state(), positions); + return slots.load(workspace_->state(), positions); } void table_rate_at(const double z, const bool before) { - if (!z_slots_.has_rate) + auto& slots = workspace_->z_slots(); + if (!slots.has_rate) throw std::logic_error("the z table reads no rate"); - z_slots_.rate(open_state(), z, before); + slots.rate(workspace_->state(), z, before); + } + [[nodiscard]] std::uint64_t table_evaluations() const { + return workspace_->z_slots().evaluations; + } + [[nodiscard]] bool has_stage_tables() const { + return workspace_->stage_tables().has_value(); } - [[nodiscard]] std::uint64_t table_evaluations() const { return z_slots_.evaluations; } - [[nodiscard]] bool has_stage_tables() const { return stage_tables_.has_value(); } native::stage::Trial stage_trial(const double z0, const double z1) { - require_open(); - if (!stage_tables_) - throw std::logic_error("no stage tables were uploaded"); - const auto row = native::stage::row(*stage_tables_, stage_anchor_, z0, z1); - auto step = native::stage::trial(*stage_tables_, row); - auto sample = native::stage::sample(*stage_tables_, stage_anchor_, step, z1); - return {.step = std::move(step), .sample = std::move(sample)}; + return workspace_->stage_trial(z0, z1); } [[nodiscard]] std::vector stage_rate(const double z) const { - require_open(); - if (!stage_tables_) - throw std::logic_error("no stage tables were uploaded"); - return native::stage::rate(*stage_tables_, z); + return workspace_->stage_rate(z); } - // solprop SEP 39 phase 2: the native march over the resident engine. void march_configure(march::Policy policy, const bool fused, const bool compensated, const bool interpolate, march::Schedule schedule) { - open_state(); - if (!stage_tables_) - throw std::logic_error("the native Adams march needs the stage tables"); - if (!schedule.steps.empty() && schedule.edges.size() != schedule.steps.size() + 1) - throw std::invalid_argument("a replayed schedule has one more edge than steps"); - march_policy_ = std::move(policy); - march_schedule_ = std::move(schedule); - march_fused_ = fused; - march_compensated_ = compensated; - march_interpolate_ = interpolate; + workspace_->configure_adams_march(std::move(policy), fused, compensated, + interpolate, std::move(schedule)); } nb::dict march_run(const nb::dict state_values, const nb::dict bounds_values) { - require_unleased(); - if (!march_policy_) - throw std::logic_error("the native Adams march is not configured"); + workspace_->require_unleased(); auto state = march_state_from(state_values); const auto bounds = march_bounds_from(bounds_values); - auto& general = open_state(); - native::engines::ResidentEngine engine( - general, stage_tables_.value(), stage_anchor_, march_fused_, march_compensated_, - march_interpolate_, march_fault_); march::Result result; { const nb::gil_scoped_release release; - result = - march::run(march_policy_.value(), state, engine, bounds, march_schedule_); + result = workspace_->run_adams(state, bounds); } return march_result_to(result, state); } void march_fault(const std::string& stage, const std::size_t after, const std::string& category) { - require_open(); - native::engines::MarchFault fault; - // `trial_source` fails inside the trial's source evaluation, its prediction in - // the state. - fault.in_source = stage == "trial_source"; - if (stage == "startup") - fault.stage = march::Stage::startup; - else if (stage == "trial" || fault.in_source) - fault.stage = march::Stage::trial; - else if (stage == "accept") - fault.stage = march::Stage::accept; - else - throw std::invalid_argument( - "a march fault's stage is startup, trial, trial_source or accept"); - if (category == "convergence") - fault.category = march::Category::convergence; - else if (category == "value") - fault.category = march::Category::value; - else if (category == "backend") - fault.category = march::Category::backend; - else if (category == "sigint") - fault.signal = SIGINT; - else if (category == "sigterm") - fault.signal = SIGTERM; - else - throw std::invalid_argument("a march fault's category is convergence, value, " - "backend, sigint or sigterm"); - fault.after = after; - march_fault_ = fault; + workspace_->inject_fault(native::fault_from(stage, after, category)); } void stage_to_host(const std::size_t stage, const std::span destination) { - require_open(); - general_state_->stage_to_host(stage, destination); + workspace_->state().stage_to_host(stage, destination); } std::vector projected_to_host(const bool coarse) { - require_open(); - return general_state_->projected_to_host(coarse); + return workspace_->state().projected_to_host(coarse); } - // Not `require_open`: a closed state, whose pointer is null, reads as having none. + // A closed state reads as having none. [[nodiscard]] std::map dispersive_path() const { - return general_state_ ? general_state_->dispersive_path() - : std::map{}; - } - void finish(const double dz) { - require_unleased(); - require_open(); - general_state_->finish(dz); + return workspace_->closed() ? std::map{} + : workspace_->built().dispersive_path(); } - void promote_fsal() { - require_open(); - general_state_->promote_fsal(); - } - void clear_fsal() { - require_open(); - general_state_->clear_fsal(); - } - // The engine leaves a quiet collar out where the reference does (solprop SEP 21). + void finish(const double dz) { workspace_->state().finish(dz); } + void promote_fsal() { workspace_->state().promote_fsal(); } + void clear_fsal() { workspace_->state().clear_fsal(); } void set_absorber_quiet(const bool quiet) { - require_open(); - general_state_->set_absorber_quiet(quiet); + workspace_->state().set_absorber_quiet(quiet); } void bind_monitor(const std::vector& weights, const std::vector& column_weights) { - require_open(); - general_state_->bind_monitor(weights, column_weights); - } - void unbind_monitor() { - require_open(); - general_state_->unbind_monitor(); + workspace_->state().bind_monitor(weights, column_weights); } + void unbind_monitor() { workspace_->state().unbind_monitor(); } void bind_occupancy(const std::vector& buckets, const std::size_t count) { - require_open(); - general_state_->bind_occupancy(buckets, count); + workspace_->state().bind_occupancy(buckets, count); } std::vector monitor_reading() { - require_open(); - return general_state_->monitor_reading(); - } - std::map memory_ledger() { - require_built(); - return general_state_->memory_ledger(); - } - [[nodiscard]] native::CpuSizing execution_sizing() const { - require_built(); - return general_state_->execution_sizing(); - } - [[nodiscard]] nb::dict cpu_execution() const { - require_built(); - return cpu_execution_dict(general_state_->cpu_execution()); - } - [[nodiscard]] nb::dict fft_planning() const { - require_built(); - return fft_planning_dict(general_state_->fft_planning()); - } - [[nodiscard]] double planning_seconds() const { - require_built(); - return general_state_->planning_seconds(); - } - [[nodiscard]] double raman_planning_seconds() const { - require_built(); - return general_state_->raman_planning_seconds(); - } - [[nodiscard]] std::string raman_fft_provider() const { - require_built(); - return general_state_->raman_fft_provider(); - } - [[nodiscard]] std::map raman_fft_tasks() const { - require_built(); - return general_state_->raman_fft_tasks(); - } - [[nodiscard]] std::size_t raman_kernel_transforms() const { - require_built(); - return general_state_->raman_kernel_transforms(); - } - [[nodiscard]] bool fsal_ready() const { - require_built(); - return general_state_->fsal_ready(); - } - [[nodiscard]] std::size_t rk_source_evaluations() const { - require_built(); - return general_state_->rk_source_evaluations(); - } - [[nodiscard]] std::size_t axis_scans() const { - require_built(); - return general_state_->axis_scans(); + return workspace_->state().monitor_reading(); } + [[nodiscard]] native::GeneralState& built() const { return workspace_->built(); } [[nodiscard]] double quadrature_error() const { - require_open(); - return general_state_->quadrature_error(); - } - double quadrature_peak() { - require_open(); - return general_state_->quadrature_peak(); - } - [[nodiscard]] std::string synthesis_provider() const { - require_built(); - return general_state_->synthesis_provider(); - } - [[nodiscard]] std::string projection_provider() const { - require_built(); - return general_state_->projection_provider(); - } - [[nodiscard]] std::string gemm_shape_policy() const { - require_built(); - return general_state_->gemm_shape_policy(); - } - [[nodiscard]] std::size_t response_team_size() const { - require_built(); - return general_state_->response_team_size(); + workspace_->require_unleased(); + return workspace_->built().quadrature_error(); } - [[nodiscard]] std::size_t columns() const noexcept { return columns_; } - [[nodiscard]] std::size_t stages() const noexcept { return stages_; } + double quadrature_peak() { return workspace_->state().quadrature_peak(); } + [[nodiscard]] std::size_t columns() const noexcept { return workspace_->columns(); } + [[nodiscard]] std::size_t stages() const noexcept { return workspace_->stages(); } [[nodiscard]] std::size_t raman_terms() const noexcept { return raman_terms_; } [[nodiscard]] bool raman() const noexcept { return raman_; } - [[nodiscard]] bool closed() const noexcept { - return !general_state_ || general_state_->closed(); - } - // Closes a session that leases this state first (below, after its class). - void close() noexcept; + [[nodiscard]] bool closed() const noexcept { return workspace_->closed(); } + // Closes a session that leases this state first; one that cannot close keeps it. + void close() noexcept override { workspace_->close(); } // solprop SEP 49: bind `owner` as the state's host source, or unbind with None (on // a closed state too, which no longer borrows it). The state keeps the object; the // engine borrows it. void bind_host_source(nb::object owner) { - require_unleased(); if (owner.is_none()) { - if (general_state_) - general_state_->bind_host_source(nullptr); + workspace_->bind_host_source(nullptr); host_owner_ = nb::object(); return; } - open_state().bind_host_source(std::make_shared(owner)); + workspace_->bind_host_source(std::make_shared(owner)); host_owner_ = std::move(owner); } - - // solprop SEP 47: the march a native execution session runs, from the policy, the - // schedule and the stage tables this state was configured with, its engine over the - // state and its tables; `state` is the march's state at the session's start. - // `dense`, a session's dense output (solprop SEP 47 section 5.3), is none or - // `{"weights": float64 array}`: a Runge-Kutta tableau's dense-output weights, empty - // for the Adams march. + // solprop SEP 47: the march a native execution session runs, from the march this + // state was configured with; `state` is the march's state at the session's start. + // `dense`, a session's dense output, is none or `{"weights": float64 array}`: a + // Runge-Kutta tableau's dense-output weights, empty for the Adams march. native::session::Method session_method(const std::string& kind, const nb::dict state_values, const nb::handle dense) { - require_unleased(); - auto& general = open_state(); + workspace_->require_unleased(); const bool interpolated = !dense.is_none(); - if (kind == "adams") { - if (!march_policy_ || !stage_tables_) - throw std::logic_error("the native Adams march is not configured"); - native::session::AdamsMethod method; - method.policy = *march_policy_; - method.state = march_state_from(state_values); - method.schedule = march_schedule_; - method.engine = std::make_unique( - general, *stage_tables_, stage_anchor_, march_fused_, march_compensated_, - march_interpolate_, march_fault_); - if (interpolated) { - if (!march_interpolate_) - throw std::invalid_argument( - "a session's dense output needs an Adams engine that keeps its steps"); - method.dense = std::make_unique( - general, *stage_tables_, stage_anchor_, march_fused_, march_compensated_); - } - return method; - } - if (kind == "runge_kutta") { - if (!rk_policy_) - throw std::logic_error("the native Runge-Kutta march is not configured"); - native::session::RungeKuttaMethod method; - method.policy = *rk_policy_; - method.state = rk_state_from(state_values); - method.schedule = rk_schedule_; - auto engine = std::make_unique( - general, - [this](const double z, const double dz) { - return staged_trial(z, dz, rk_nodes_, false); - }, - rk_rtol_, rk_atol_, rk_weights_); - if (interpolated) { - if (!stage_tables_) - throw std::logic_error("a session's dense output needs the stage tables"); - auto holder = std::make_unique( - general, *stage_tables_, stage_anchor_, - real_vector(exact_array(nb::cast(dense)["weights"]))); - // The engine holds each crossing step's extension through it; both live in - // the method, the engine released first. - auto* held = holder.get(); - engine->set_extension( - [held](const double z, const double dz) { held->hold(z, dz); }); - method.dense = std::move(holder); - } - method.engine = std::move(engine); - return method; - } - if (kind == "low_storage") { - // solprop SEP 47 section 6.3: the replay is the Runge-Kutta march's, each step - // one in-place low-storage step whose scalars the state forms itself. - if (!rk_policy_ || !stage_tables_ || !low_storage_) - throw std::logic_error("the native low-storage replay is not configured"); - native::session::RungeKuttaMethod method; - method.policy = *rk_policy_; - method.state = rk_state_from(state_values); - method.schedule = rk_schedule_; - method.engine = std::make_unique( - general, *stage_tables_, stage_anchor_, *low_storage_, rk_schedule_, - rk_policy_->landings.landing_ulps, march_fault_); - return method; - } - throw std::invalid_argument( - R"(a session's march is "adams", "runge_kutta" or "low_storage")"); - } - // The state's field and statistics, as a session reads them. - std::unique_ptr session_resident() { - return std::make_unique(open_state(), elements_, - elements_ / columns_); - } - // The state `session` leases, for that session's own reads under its lock. - native::GeneralState& leased_state(const BoundSession* session) const { - if (session_ != session) - throw std::logic_error("native state is not leased by this session"); - return built_state(); - } - // A z table's `Phi` at `z` (`_ZTables.values`), for the session that leases the - // state, under its lock: the noise phase at a plane, through the one slot cache. - std::vector leased_table_phi(const BoundSession* session, - const double z) { - auto& state = leased_state(session); - if (!z_slots_.phi) - throw std::logic_error("native state holds no z table of Phi"); - const std::size_t slot = z_slots_.load(state, {z}).front(); - return state.table_terms_to_host(native::TableKind::phi, slot); - } - // A session leases the state exclusively: the host's own march and loads refuse. - void lease(BoundSession* session) { - require_unleased(); - session_ = session; - } - void release(const BoundSession* session) noexcept { - if (session_ == session) - session_ = nullptr; + if (kind == "adams") + return workspace_->method(native::MethodKind::adams, + march_state_from(state_values), interpolated); + native::MethodKind method_kind = native::MethodKind::runge_kutta; + if (kind == "low_storage") + method_kind = native::MethodKind::low_storage; + else if (kind != "runge_kutta") + throw std::invalid_argument( + R"(a session's march is "adams", "runge_kutta" or "low_storage")"); + const bool dense_rk = + interpolated && method_kind == native::MethodKind::runge_kutta; + if (dense_rk) + workspace_->set_dense_weights( + real_vector(exact_array(nb::cast(dense)["weights"]))); + return workspace_->method(method_kind, rk_state_from(state_values), dense_rk); } private: - // Every method that mutates the state or reads its live field or workspace: open, - // and not leased by an execution session (SEP 47 section 5.2), whose engines alone - // use the state while it holds it. - void require_open() const { - require_built(); - require_unleased(); - } - // A reader of the state's fixed facts (its plans, execution record, ledger and - // providers), which a lease leaves readable. - void require_built() const { - if (closed()) - throw std::logic_error("native state is closed"); - } - [[nodiscard]] native::GeneralState& built_state() const { - require_built(); - return *general_state_; - } - void require_unleased() const { - if (session_ != nullptr) - throw std::logic_error("native state is leased by an execution session"); - } - BoundSession* session_ = nullptr; - std::size_t columns_{}; - std::size_t elements_{}; - std::size_t stages_{}; std::size_t raman_terms_{}; bool raman_{}; - std::shared_ptr general_state_; - std::optional stage_tables_; - native::stage::Anchor stage_anchor_; - native::stage::ZSlots z_slots_; - std::optional march_policy_; - struct FlowGuard { - std::vector row_sum; - std::vector condition_bound; - double taylor_scale; - int max_squarings; - double allowance; - }; - std::optional flow_guard_; - std::optional> flow_key_; - std::optional rk_policy_; - std::vector rk_nodes_; - double rk_rtol_ = 0.0; - double rk_atol_ = 0.0; - march::Schedule rk_schedule_; - std::vector rk_weights_; - std::optional low_storage_; - march::Schedule march_schedule_; - bool march_fused_ = false; - bool march_compensated_ = false; - bool march_interpolate_ = false; - std::optional march_fault_; + std::unique_ptr workspace_; nb::object host_owner_; }; -// solprop SEP 47: a native execution session over a leased state. It keeps that state -// alive (the binding's keep-alive) and releases the lease when it closes; the state -// closes the session first when it closes itself. // solprop SEP 47: a batch's chunk as owning NumPy arrays, each made once from the // vector the session moved into the batch (no copy), its capsule owning the storage. template @@ -2446,35 +1924,57 @@ struct BatchRecord { nb::object plane_stats; }; +/** A session's snapshot as Python reads it: the march's state, the field and each + history row, every array owning its copy; None without one. */ +nb::object snapshot_to(std::optional snapshot) { + if (!snapshot) + return nb::none(); + nb::dict held; + for (std::size_t index = 0; index < snapshot->names.size(); ++index) { + const auto& extent = snapshot->extents[index]; + held[snapshot->names[index].c_str()] = owned_complex( + std::make_unique(std::move(snapshot->rows[index])), + {extent[0], extent[1], extent[2]}); + } + const std::size_t n = snapshot->field.size(); + return nb::make_tuple( + march_state_to(snapshot->state), + owned_complex(std::make_unique(std::move(snapshot->field)), {n}), + held); +} + +// solprop SEP 47: a native execution session over a leased workspace (`native::Run`). +// The binding keeps the workspace's Python object alive while the session lives; the +// workspace closes the session first when it closes itself. class BoundSession { public: - BoundSession(BoundState& owner, std::unique_ptr session) - : owner_(&owner), session_(std::move(session)) { - owner.lease(this); - } + BoundSession(std::unique_ptr run, const std::size_t columns) + : run_(std::move(run)), columns_(columns) {} ~BoundSession() { close(); } BoundSession(const BoundSession&) = delete; BoundSession& operator=(const BoundSession&) = delete; BoundSession(BoundSession&&) = delete; BoundSession& operator=(BoundSession&&) = delete; + native::session::Session& session() const { return run_->session(); } + // The advance runs without the interpreter lock; its batch becomes a record with it. BatchRecord advance(const std::size_t work_limit, const double deadline) { native::session::Batch batch; { const nb::gil_scoped_release release; - batch = session_->advance(work_limit, deadline); + batch = session().advance(work_limit, deadline); } return BatchRecord(std::move(batch)); } // Takes the session's lock: bound with the interpreter lock released. - void acknowledge(const std::uint64_t sequence) { session_->acknowledge(sequence); } + void acknowledge(const std::uint64_t sequence) { session().acknowledge(sequence); } void export_field(const std::uint64_t sequence, const std::uint64_t generation, const bool power, const bool optics, const std::optional& weight, nb::ndarray, nb::c_contig, nb::device::cpu> out) { - const std::size_t n = session_->elements(); + const std::size_t n = session().elements(); if (out.size() != n) native::refuse("an export destination has ", out.size(), " elements, expected ", n); @@ -2484,17 +1984,17 @@ class BoundSession { const double* values = weight ? weight->data() : nullptr; auto* destination = reinterpret_cast(out.data()); const nb::gil_scoped_release release; - session_->export_field(sequence, generation, power, optics, values, destination); + session().export_field(sequence, generation, power, optics, values, destination); } - void request_stop() noexcept { session_->request_stop(); } + void request_stop() noexcept { session().request_stop(); } nb::tuple request_snapshot() { - const auto receipt = session_->request_snapshot(); + const auto receipt = session().request_snapshot(); return nb::make_tuple(receipt.request, receipt.coalesced); } [[nodiscard]] native::session::Status status() const noexcept { - return session_->status(); + return session().status(); } - [[nodiscard]] std::size_t elements() const { return session_->elements(); } + [[nodiscard]] std::size_t elements() const { return session().elements(); } // Continue a resumed run's monitor record; takes the session's lock. void continue_monitor(const nb::dict record, const bool plane, const nb::handle unwatched, const nb::dict edge_record) { @@ -2502,7 +2002,16 @@ class BoundSession { auto stretches = watch_stretches_from(unwatched); auto edge = native::bindings::transverse_resumption_from(edge_record); const nb::gil_scoped_release release; - session_->continue_monitor(resumption, plane, stretches, edge); + session().continue_monitor(resumption, plane, stretches, edge); + } + // SEP 52: the continuation as `solprop.backends.records.MonitorContinuation`. + void continue_with(const nb::handle continuation) { + const auto held = + native::records::read(continuation, "continuation"); + const auto record = native::to_native(held.record); + const auto edge = native::to_native(held.edge); + const nb::gil_scoped_release release; + session().continue_monitor(record, held.plane, held.unwatched, edge); } // The transverse edge's record and finish, or None; takes the session's lock. nb::object edge_record() { @@ -2510,7 +2019,7 @@ class BoundSession { record; { const nb::gil_scoped_release release; - record = session_->edge_record(); + record = session().edge_record(); } if (!record) return nb::none(); @@ -2521,124 +2030,78 @@ class BoundSession { std::optional record; { const nb::gil_scoped_release release; - record = session_->monitor_record(); + record = session().monitor_record(); } if (!record) return nb::none(); return watch_record_to(*record); } - // The resident state's quadrature peak since the last read; takes the lock. double quadrature_peak() { const nb::gil_scoped_release release; - return session_->quadrature_peak(); + return session().quadrature_peak(); } - // The split collar's crossing cap the monitor holds, m, or None; takes the lock. nb::object monitor_cap() { std::optional cap; { const nb::gil_scoped_release release; - cap = session_->monitor_cap(); + cap = session().monitor_cap(); } if (!cap) return nb::none(); return nb::float_(*cap); } + // SEP 52: every record the session keeps, in one: the monitor's, the edge's, the + // split collar's cap and the quadrature peak since the last read. + nb::dict records() { + nb::dict out; + out["monitor"] = monitor_record(); + out["edge"] = edge_record(); + out["cap"] = monitor_cap(); + out["quadrature_peak"] = quadrature_peak(); + return out; + } // solprop SEP 47 section 5.5: the Adams march's state with the orders of its - // accepted steps from `since` (the call ledger), or None for a Runge-Kutta march; - // read under the session's lock, between advances. + // accepted steps from `since` (the call ledger), or None for a Runge-Kutta march. nb::object march_state(const std::size_t since) { - std::optional state; - std::vector orders; + std::optional>> state; { const nb::gil_scoped_release release; - session_->read( - 0, 0, - [&](const native::session::Method& method, - native::session::Resident& /*resident*/) { - const auto* adams = std::get_if(&method); - if (adams == nullptr) - return; - state = adams->state; - const std::size_t first = std::min(since, adams->orders.size()); - orders.assign(adams->orders.begin() + static_cast(first), - adams->orders.end()); - }); + state = run_->march_state(since); } if (!state) return nb::none(); - nb::dict out = march_state_to(*state); - out["orders"] = orders; + nb::dict out = march_state_to(state->first); + out["orders"] = state->second; return out; } - // The Adams march's history at the pending batch's committed state, its ticket - // `(sequence, generation)` (SEP 47 section 5.4): the march's state, the accepted - // field as the state holds it and each persistent history row, each copied once, - // losslessly (`HostAdamsMarch.snapshot`); None for a Runge-Kutta march or before any + // The Adams march's history at the pending ticket `(sequence, generation)` (SEP 47 + // section 5.4), each part copied once; None for a Runge-Kutta march or before any // history. nb::object march_snapshot(const std::uint64_t sequence, const std::uint64_t generation) { - std::optional state; - std::unique_ptr field; - std::vector names; - std::vector> extents; - std::vector> rows; + std::optional snapshot; { const nb::gil_scoped_release release; - session_->read( - sequence, generation, - [&](const native::session::Method& method, - native::session::Resident& resident) { - const auto* adams = std::get_if(&method); - if (adams == nullptr || adams->state.history.empty()) - return; - state = adams->state; - field = std::make_unique(resident.elements()); - resident.field_to_host(reinterpret_cast(field->data())); - const auto& general = owner_->leased_state(this); - names = general.adams_row_names(); - for (const auto& name : names) { - const auto extent = general.adams_row_extents(name); - auto storage = - std::make_unique(extent[0] * extent[1] * extent[2]); - general.adams_rows_to_host(name, storage->data(), storage->size()); - extents.push_back(extent); - rows.push_back(std::move(storage)); - } - }); + snapshot = run_->snapshot(sequence, generation); } - if (!state) - return nb::none(); - const std::size_t n = field->size(); - nb::dict held; - for (std::size_t index = 0; index < names.size(); ++index) - held[names[index].c_str()] = - owned_complex(std::move(rows[index]), - {extents[index][0], extents[index][1], extents[index][2]}); - return nb::make_tuple(march_state_to(*state), owned_complex(std::move(field), {n}), - held); - } - // A z table's `Phi` at `z`, the noise phase at the pending ticket - // `(sequence, generation)`'s plane (`_ZTables.values`); takes the session's lock. + return snapshot_to(std::move(snapshot)); + } + // A z table's `Phi` at `z`, the noise phase at the pending ticket's plane. ComplexOutput table_phi(const std::uint64_t sequence, const std::uint64_t generation, const double z) { std::vector values; { const nb::gil_scoped_release release; - session_->read(sequence, generation, - [&](const native::session::Method& /*method*/, - native::session::Resident& /*resident*/) { - values = owner_->leased_table_phi(this, z); - }); + values = run_->noise_phase(sequence, generation, z); } - const std::size_t columns = owner_->columns(); - return complex_output(values, {columns, values.size() / columns}); + return complex_output(values, {columns_, values.size() / columns_}); } // Issue a failed terminal batch for a failure outside the session; takes its lock. std::optional fail_outside() { std::optional batch; { const nb::gil_scoped_release release; - batch = session_->fail_outside(); + batch = session().fail_outside(); } if (!batch) return std::nullopt; @@ -2646,40 +2109,13 @@ class BoundSession { } // Takes the session's lock (waiting for an advance in hand): bound with the // interpreter lock released. The lease is released only once the session closed. - void close() noexcept { - BoundState* owner = owner_; - if (close_native() && owner != nullptr) - owner->release(this); - } - // The owner's own close: the owner forgets the session only once it closed, so a - // session that could not take its lock keeps the state it uses alive. - bool close_native() noexcept { - if (!session_->close()) - return false; - owner_ = nullptr; - return true; - } + void close() noexcept { static_cast(run_->close()); } private: - BoundState* owner_; - std::unique_ptr session_; + std::unique_ptr run_; + std::size_t columns_; }; -void BoundState::close() noexcept { - if (session_ != nullptr) { - // A session that did not close still uses the state: keep it, leased. - if (!session_->close_native()) - return; - session_ = nullptr; - } - if (general_state_) { - general_state_->close(); - general_state_.reset(); - } - // A host source's owner (SEP 49) is not released here, without the interpreter - // lock: the engine that borrowed it is gone, and `bind_host_source(None)` drops it. -} - // solprop SEP 47 section 6.4: a statistics evaluation lowered once from the problem, // the one native implementation of each statistic (statistics_plan.hpp). template @@ -2858,9 +2294,263 @@ std::unique_ptr start_session(BoundState& state, const std::string const nb::object dense = plan.contains("dense") ? nb::object(plan["dense"]) : nb::object(nb::none()); auto method = state.session_method(kind, march_state, dense); - auto session = std::make_unique( - state.session_resident(), std::move(method), session_plan_from(plan), z); - return std::make_unique(state, std::move(session)); + auto run = state.workspace().start(std::move(method), session_plan_from(plan), z); + return std::make_unique(std::move(run), state.columns()); +} + +} // namespace + +// The statistics plans a run's start names cross as the bound `StatisticsPlan`. +template <> +struct solprop_native::records::Extern< + std::shared_ptr> { + static constexpr const char* kind = "StatisticsPlan"; + static void read(const nb::handle value, + std::shared_ptr* out, + const std::string& path) { + if (value.is_none()) { + if (out != nullptr) + out->reset(); + return; + } + const BoundStatisticsPlan* plan = nullptr; + if (!nb::try_cast(value, plan) || plan == nullptr) + solprop_native::records::type_refusal(path, "must be a StatisticsPlan or None"); + if (out != nullptr) + *out = plan->plan(); + } + static nb::object + write(const std::shared_ptr& plan) { + return plan ? nb::cast(plan->packed_size()) : nb::none(); + } +}; + +namespace { + +namespace records = native::records; + +// The runtime's one record (solprop SEP 52 section 5.3): the thread pools, the BLAS +// fitting and the spin, applied once at import. +struct RuntimeRecord { + int threads = 0; + int kernels = 0; + int fft = 0; + int raman_fft = 0; + int raman_tail_fft = 0; + int band_tiles = -1; + int spin_milliseconds = 0; + std::optional blas_threads; + bool host_blas = true; +}; + +[[nodiscard]] constexpr auto describe(const RuntimeRecord* /*unused*/) { + using R = RuntimeRecord; + return native::fields::table( + "RuntimeRecord", native::fields::value("threads", &R::threads), + native::fields::value("kernels", &R::kernels), + native::fields::value("fft", &R::fft), + native::fields::value("raman_fft", &R::raman_fft), + native::fields::value("raman_tail_fft", &R::raman_tail_fft), + native::fields::value("band_tiles", &R::band_tiles), + native::fields::value("spin_milliseconds", &R::spin_milliseconds), + native::fields::value("blas_threads", &R::blas_threads), + native::fields::value("host_blas", &R::host_blas)); +} + +// Defined with the library lookups below. +std::string fit_blas_threads(int threads); +void register_host_blas(); + +nb::dict configure_runtime(const nb::handle value) { + const auto record = records::read(value, "runtime"); + initialize_kokkos(record.threads, record.kernels, record.fft, record.raman_fft, + record.raman_tail_fft, record.band_tiles); + native::configure_native_spin(record.spin_milliseconds); + nb::dict out; + out["blas_policy"] = + record.blas_threads ? fit_blas_threads(*record.blas_threads) : std::string(); + if (record.host_blas) + register_host_blas(); + return out; +} + +// The timing probe (SEP 52 section 5.5), over the workspace that leases it. +class BoundProbe { +public: + BoundProbe(std::unique_ptr probe, const std::size_t columns) + : probe_(std::move(probe)), columns_(columns) {} + double trial(const double z, const double dz) { + const nb::gil_scoped_release release; + return probe_->trial(z, dz); + } + ComplexOutput field() { + std::vector values; + { + const nb::gil_scoped_release release; + values = probe_->field(); + } + return complex_output(values, {columns_, values.size() / columns_}); + } + [[nodiscard]] std::size_t trials() const noexcept { return probe_->trials(); } + [[nodiscard]] std::size_t evaluations() const { return probe_->evaluations(); } + [[nodiscard]] bool low_storage() const noexcept { return probe_->low_storage(); } + [[nodiscard]] double z() const noexcept { return probe_->z(); } + [[nodiscard]] bool closed() const noexcept { return probe_->closed(); } + void close() noexcept { probe_->close(); } + +private: + std::unique_ptr probe_; + std::size_t columns_; +}; + +// solprop SEP 52 section 5.3: one problem's workspace, its set-once data applied when +// it is built, reused across the runs of a scan. +class BoundWorkspace final : public Owned { +public: + explicit BoundWorkspace(native::Problem problem) + : workspace_(std::make_unique(std::move(problem))) { + register_owned(this); + } + ~BoundWorkspace() override { + close(); + forget_owned(this); + } + BoundWorkspace(const BoundWorkspace&) = delete; + BoundWorkspace& operator=(const BoundWorkspace&) = delete; + BoundWorkspace(BoundWorkspace&&) = delete; + BoundWorkspace& operator=(BoundWorkspace&&) = delete; + + [[nodiscard]] native::Workspace& workspace() const { return *workspace_; } + + std::unique_ptr start(const nb::handle run, const nb::object& host) { + auto held = records::read(run, "run"); + workspace_->require_unleased(); + if (host.is_none()) { + workspace_->bind_host_source(nullptr); + host_owner_ = nb::object(); + } else { + workspace_->bind_host_source(std::make_shared(host)); + host_owner_ = host; + } + std::unique_ptr started; + { + const nb::gil_scoped_release release; + started = workspace_->start(std::move(held)); + } + return std::make_unique(std::move(started), workspace_->columns()); + } + std::unique_ptr probe(const nb::handle run) { + auto held = records::read(run, "start"); + std::unique_ptr probe; + { + const nb::gil_scoped_release release; + probe = workspace_->probe(std::move(held)); + } + return std::make_unique(std::move(probe), workspace_->columns()); + } + // Everything `NativeBackend.metadata` assembles from the state's facts. + [[nodiscard]] nb::dict diagnostics() const { + const auto& state = workspace_->built(); + nb::dict out; + out["memory_ledger"] = state.memory_ledger(); + out["execution_sizing"] = state.execution_sizing(); + out["cpu_execution"] = cpu_execution_dict(state.cpu_execution()); + out["fft_planning"] = fft_planning_dict(state.fft_planning()); + out["planning_seconds"] = state.planning_seconds(); + out["raman_planning_seconds"] = state.raman_planning_seconds(); + out["raman_fft_provider"] = state.raman_fft_provider(); + out["raman_fft_tasks"] = state.raman_fft_tasks(); + out["raman_kernel_transforms"] = state.raman_kernel_transforms(); + out["fsal_ready"] = state.fsal_ready(); + out["rk_source_evaluations"] = state.rk_source_evaluations(); + out["axis_scans"] = state.axis_scans(); + out["synthesis_provider"] = state.synthesis_provider(); + out["projection_provider"] = state.projection_provider(); + out["gemm_shape_policy"] = state.gemm_shape_policy(); + out["response_team_size"] = state.response_team_size(); + out["dispersive_path"] = state.dispersive_path(); + const auto crossed = state.crossed_bytes(); + out["crossed_bytes"] = nb::make_tuple(crossed.to_host, crossed.from_host); + out["table_evaluations"] = workspace_->z_slots().evaluations; + static constexpr std::array kinds{"adams", "runge_kutta", + "low_storage"}; + out["method"] = kinds[static_cast(workspace_->kind())]; + return out; + } + [[nodiscard]] bool closed() const noexcept { return workspace_->closed(); } + void close() noexcept override { workspace_->close(); } + void unbind_host_source() { + workspace_->bind_host_source(nullptr); + host_owner_ = nb::object(); + } + +private: + std::unique_ptr workspace_; + nb::object host_owner_; +}; + +/** Every table `schemas()` exports, by name. */ +nb::dict schemas() { + nb::dict tables; + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + records::collect(tables); + return tables; +} + +/** Read `value` as the record named `name` and write it back (the round-trip tests). */ +nb::dict round_trip(const std::string& name, const nb::handle value) { + const auto trip = [&]() -> nb::dict { + return records::write_record(records::read(value, name)); + }; +#define SOLPROP_NATIVE_TRIP(Type) \ + if (name == native::fields::table_of().name) \ + return trip.template operator()(); + SOLPROP_NATIVE_TRIP(native::RunRecordsRecord) + SOLPROP_NATIVE_TRIP(native::RunStart) + SOLPROP_NATIVE_TRIP(native::march::Policy) + SOLPROP_NATIVE_TRIP(native::RungeKuttaPolicyRecord) + SOLPROP_NATIVE_TRIP(native::ControllerRecord) + SOLPROP_NATIVE_TRIP(native::rk::low_storage::Config) + SOLPROP_NATIVE_TRIP(native::ScheduleRecord) + SOLPROP_NATIVE_TRIP(native::PlanePlanRecord) + SOLPROP_NATIVE_TRIP(native::watch::Config) + SOLPROP_NATIVE_TRIP(native::watch::Policy) + SOLPROP_NATIVE_TRIP(native::transverse::Config) + SOLPROP_NATIVE_TRIP(native::ResumptionRecord) + SOLPROP_NATIVE_TRIP(native::EdgeResumptionRecord) + SOLPROP_NATIVE_TRIP(native::ContinuationRecord) + SOLPROP_NATIVE_TRIP(native::MonitorRecordsRecord) + SOLPROP_NATIVE_TRIP(native::march::State) + SOLPROP_NATIVE_TRIP(native::rk::State) + SOLPROP_NATIVE_TRIP(native::stage::Table) + SOLPROP_NATIVE_TRIP(native::stage::Tables) + SOLPROP_NATIVE_TRIP(native::ZTable) + SOLPROP_NATIVE_TRIP(native::FlowGuard) + SOLPROP_NATIVE_TRIP(native::MonitorBinding) + SOLPROP_NATIVE_TRIP(native::EdgeBinding) + SOLPROP_NATIVE_TRIP(native::Problem::Raman) + SOLPROP_NATIVE_TRIP(native::Problem::Plasma) + SOLPROP_NATIVE_TRIP(native::Setup) +#undef SOLPROP_NATIVE_TRIP + native::refuse("no record is named '", name, "'"); } void shutdown_kokkos() { @@ -3191,6 +2881,237 @@ nb::dict build_record() { return result; } +// solprop SEP 52 section 6.5: native's engines through solprop's Python protocols +// (`solprop.backends.engines`), for the engine-level parity tests, with a read-back of +// the field and of a stage register. The object leases the workspace while it lives, +// as a session does. +class TestEngines { +public: + explicit TestEngines(BoundWorkspace& owner) : owner_(&owner.workspace()) { + auto& workspace = *owner_; + workspace.require_unleased(); + // Each engine the workspace's configuration makes; one it cannot make is absent. + try { + runge_kutta_ = workspace.trial_engine(); + } catch (const std::logic_error&) { + runge_kutta_.reset(); + } + try { + adams_ = workspace.adams_engine(); + } catch (const std::logic_error&) { + adams_.reset(); + } + workspace.lease(this); + } + ~TestEngines() { close(); } + TestEngines(const TestEngines&) = delete; + TestEngines& operator=(const TestEngines&) = delete; + TestEngines(TestEngines&&) = delete; + TestEngines& operator=(TestEngines&&) = delete; + + void close() noexcept { + if (owner_ == nullptr) + return; + runge_kutta_.reset(); + adams_.reset(); + owner_->release(this); + owner_ = nullptr; + } + native::GeneralState& state() const { + if (owner_ == nullptr) + throw std::logic_error("the engines are closed"); + return owner_->leased_state(this); + } + native::rk::Engine& runge_kutta() const { + state(); + if (!runge_kutta_) + throw std::logic_error("this workspace has no Runge-Kutta engine"); + return *runge_kutta_; + } + native::march::Engine& adams() const { + state(); + if (!adams_) + throw std::logic_error("this workspace has no Adams engine"); + return *adams_; + } + ComplexOutput field() const { + const std::size_t count = owner_ == nullptr ? 0 : owner_->elements(); + auto storage = native::crossing::host_buffer(2 * count); + state().field_to_host({reinterpret_cast(storage.get()), count}); + return complex_buffer_output(std::move(storage), + {owner_->columns(), count / owner_->columns()}); + } + ComplexOutput stage(const std::size_t index) const { + const std::size_t count = owner_ == nullptr ? 0 : owner_->elements(); + auto storage = native::crossing::host_buffer(2 * count); + state().stage_to_host(index, + {reinterpret_cast(storage.get()), count}); + return complex_buffer_output(std::move(storage), + {owner_->columns(), count / owner_->columns()}); + } + void load(const ComplexInput field, const ComplexInput noise) const { + auto& general = state(); + const nb::gil_scoped_release release; + general.set_initial(complex_span(field), complex_span(noise)); + } + +private: + native::Workspace* owner_; + std::unique_ptr runge_kutta_; + std::unique_ptr adams_; +}; + +/** solprop's protocol records, built where a test reads them. */ +nb::object engines_module() { return nb::module_::import_("solprop.backends.engines"); } + +nb::object boundary_reading(const std::vector& values) { + if (values.size() < native::watch::reading_head) + throw std::logic_error("a boundary reading is too short"); + const std::vector regions(values.begin() + 1, values.begin() + 5); + nb::object occupancy = nb::none(); + if (values.size() > native::watch::reading_head) + occupancy = nb::cast(real_output( + std::vector(values.begin() + native::watch::reading_head, values.end()), + 1)); + return engines_module().attr("BoundaryReading")( + values[0], nb::cast(real_output(regions, 1)).attr("reshape")(-1), occupancy); +} + +/** A Python `adams_core.Stencil` as the march's. */ +native::march::Stencil stencil_from(const nb::handle value) { + native::march::Stencil stencil; + const auto nodes = nb::cast>(value.attr("nodes")); + const auto rows = + nb::cast>(value.attr("rows").attr("tolist")()); + const auto orders = nb::cast>(value.attr("orders")); + if (nodes.size() != rows.size() || nodes.size() > native::march::max_history || + orders.size() > native::march::max_orders) + throw std::invalid_argument("a stencil's nodes and rows are one per held entry"); + std::copy(nodes.begin(), nodes.end(), stencil.nodes.begin()); + std::copy(rows.begin(), rows.end(), stencil.rows.begin()); + stencil.held = nodes.size(); + stencil.order = nb::cast(value.attr("order")); + std::copy(orders.begin(), orders.end(), stencil.orders.begin()); + stencil.n_orders = orders.size(); + return stencil; +} + +void bind_engines(nb::module_& testing) { + nb::class_(testing, "Engines") + .def("field", &TestEngines::field) + .def("stage", &TestEngines::stage, "index"_a) + .def("load", &TestEngines::load, "field"_a.noconvert(), "noise"_a.noconvert()) + .def("close", &TestEngines::close) + // The Runge-Kutta protocol (`RungeKuttaEngine`), each prefixed `rk_` here and + // dispatched by the Python wrapper in the tests. + .def("rk_trial", + [](TestEngines& self, const double z, const double dz) { + auto& engine = self.runge_kutta(); + const nb::gil_scoped_release release; + return engine.trial(z, dz); + }) + .def("rk_accept", + [](TestEngines& self, const double dz) { + auto& engine = self.runge_kutta(); + { + const nb::gil_scoped_release release; + engine.accept(dz); + } + return engines_module().attr("AcceptRecord")(); + }) + .def("rk_extend", [](TestEngines& self, const double z, + const double dz) { self.runge_kutta().extend(z, dz); }) + .def("rk_reading", + [](TestEngines& self) { + return boundary_reading(self.runge_kutta().reading()); + }) + .def_prop_ro("rk_in_flight", + [](TestEngines& self) { return self.runge_kutta().in_flight(); }) + // The Adams protocol (`AdamsEngine`). + .def("adams_start", + [](TestEngines& self, const double z) { + auto& engine = self.adams(); + const nb::gil_scoped_release release; + engine.start(z); + }) + .def("adams_trial", + [](TestEngines& self, const double z, const double dz, + const nb::handle held) { + auto& engine = self.adams(); + const auto stencil = stencil_from(held); + std::vector norms(stencil.n_orders); + { + const nb::gil_scoped_release release; + engine.trial(z, dz, stencil, norms.data()); + } + return real_output(std::move(norms), 1); + }) + .def("adams_accept", + [](TestEngines& self, const double dz, const std::size_t free, + const nb::handle held, const nb::handle kept) { + auto& engine = self.adams(); + const auto stencil = stencil_from(held); + std::vector entries; + for (const auto entry : nb::cast(kept)) + entries.push_back( + native::records::read(entry, "kept")); + { + const nb::gil_scoped_release release; + engine.accept(dz, free, stencil, entries); + } + return engines_module().attr("AcceptRecord")(); + }) + .def("adams_chord_phase", + [](TestEngines& self, const double z1, const double z2) { + return self.adams().chord_phase(z1, z2); + }) + .def("adams_step_carrier", + [](TestEngines& self, const std::size_t order) { + auto values = self.adams().step_carrier(order); + return values.empty() ? nb::cast(std::vector{}) + : nb::cast(real_output(std::move(values), 1)); + }) + .def("adams_begin_attempt", + [](TestEngines& self, const std::uint64_t cost) { + self.adams().begin_attempt(cost); + }) + .def("adams_end_attempt", + [](TestEngines& self, const int outcome) { + if (outcome < 0 || outcome > 2) + throw std::invalid_argument("an attempt's outcome is 0, 1 or 2"); + self.adams().end_attempt(static_cast(outcome)); + }) + .def("adams_reading", + [](TestEngines& self) { return boundary_reading(self.adams().reading()); }); + testing.def( + "engines", + [](BoundWorkspace& workspace) { + return std::make_unique(workspace); + }, + "workspace"_a, nb::keep_alive<0, 1>()); + testing.def( + "inject_fault", + [](BoundWorkspace& workspace, const std::string& stage, const std::size_t after, + const std::string& category) { + workspace.workspace().inject_fault(native::fault_from(stage, after, category)); + }, + "workspace"_a, "stage"_a, "after"_a, "category"_a); + testing.def( + "evaluate", + [](BoundWorkspace& workspace, const BoundStatisticsPlan& plan, const double z) { + auto& state = workspace.workspace().state(); + const auto& held = plan.plan(); + std::vector values; + { + const nb::gil_scoped_release release; + values = native::statistics::evaluate(state, *held, z); + } + return real_output(std::move(values), 1); + }, + "workspace"_a, "plan"_a, "z"_a); + testing.def("round_trip", &round_trip, "name"_a, "value"_a); +} + // The private `_testing` module (solprop SEP 52 section 6.5): every entry point that // only solprop's own tests reach, built into the same extension and shipped in the // wheel. It promises nothing. A `State` method that moved here takes the state as its @@ -4288,37 +4209,49 @@ NB_MODULE(_core, module_) { .def("memory_ledger", [](BoundState& self) { nb::dict result; - for (const auto& [name, bytes] : self.memory_ledger()) { + for (const auto& [name, bytes] : self.built().memory_ledger()) { result[name.c_str()] = bytes; } return result; }) .def_prop_ro("planning_seconds", - [](BoundState& self) { return self.planning_seconds(); }) + [](BoundState& self) { return self.built().planning_seconds(); }) .def_prop_ro("raman_fft_provider", - [](BoundState& self) { return self.raman_fft_provider(); }) - .def_prop_ro("execution_sizing", &BoundState::execution_sizing) - .def_prop_ro("cpu_execution", &BoundState::cpu_execution) - .def_prop_ro("fft_planning", &BoundState::fft_planning) + [](BoundState& self) { return self.built().raman_fft_provider(); }) + .def_prop_ro("execution_sizing", + [](BoundState& self) { return self.built().execution_sizing(); }) + .def_prop_ro("cpu_execution", + [](BoundState& self) { + return cpu_execution_dict(self.built().cpu_execution()); + }) + .def_prop_ro("fft_planning", + [](BoundState& self) { + return fft_planning_dict(self.built().fft_planning()); + }) .def_prop_ro("raman_fft_tasks", - [](BoundState& self) { return self.raman_fft_tasks(); }) - .def_prop_ro("raman_planning_seconds", - [](BoundState& self) { return self.raman_planning_seconds(); }) - .def_prop_ro("raman_kernel_transforms", - [](BoundState& self) { return self.raman_kernel_transforms(); }) - .def_prop_ro("fsal_ready", [](BoundState& self) { return self.fsal_ready(); }) - .def_prop_ro("rk_source_evaluations", - [](BoundState& self) { return self.rk_source_evaluations(); }) - .def_prop_ro("axis_scans", [](BoundState& self) { return self.axis_scans(); }) + [](BoundState& self) { return self.built().raman_fft_tasks(); }) + .def_prop_ro( + "raman_planning_seconds", + [](BoundState& self) { return self.built().raman_planning_seconds(); }) + .def_prop_ro( + "raman_kernel_transforms", + [](BoundState& self) { return self.built().raman_kernel_transforms(); }) + .def_prop_ro("fsal_ready", + [](BoundState& self) { return self.built().fsal_ready(); }) + .def_prop_ro( + "rk_source_evaluations", + [](BoundState& self) { return self.built().rk_source_evaluations(); }) + .def_prop_ro("axis_scans", + [](BoundState& self) { return self.built().axis_scans(); }) .def("quadrature_peak", [](BoundState& self) { return self.quadrature_peak(); }) .def_prop_ro("synthesis_provider", - [](BoundState& self) { return self.synthesis_provider(); }) + [](BoundState& self) { return self.built().synthesis_provider(); }) .def_prop_ro("projection_provider", - [](BoundState& self) { return self.projection_provider(); }) + [](BoundState& self) { return self.built().projection_provider(); }) .def_prop_ro("gemm_shape_policy", - [](BoundState& self) { return self.gemm_shape_policy(); }) + [](BoundState& self) { return self.built().gemm_shape_policy(); }) .def_prop_ro("response_team_size", - [](BoundState& self) { return self.response_team_size(); }) + [](BoundState& self) { return self.built().response_team_size(); }) .def_prop_ro("closed", &BoundState::closed) .def("close", &BoundState::close, nb::call_guard()); // solprop SEP 47: the native execution session and its compact event records. @@ -4447,12 +4380,63 @@ NB_MODULE(_core, module_) { "generation"_a) .def("table_phi", &BoundSession::table_phi, "sequence"_a, "generation"_a, "z"_a) .def("fail_outside", &BoundSession::fail_outside) + // solprop SEP 52 section 5.3: a ticket is `(sequence, generation)`; a recipe is + // `{"power", "optics", "weight"}`. + .def( + "export", + [](BoundSession& self, const std::pair ticket, + const nb::dict recipe, + nb::ndarray, nb::c_contig, nb::device::cpu> out) { + std::optional weight; + if (recipe.contains("weight") && !recipe["weight"].is_none()) + weight = exact_array(recipe["weight"]); + self.export_field(ticket.first, ticket.second, + nb::cast(recipe["power"]), + nb::cast(recipe["optics"]), weight, out); + }, + "ticket"_a, "recipe"_a, "out"_a) + .def( + "snapshot", + [](BoundSession& self, const std::pair ticket) { + return self.march_snapshot(ticket.first, ticket.second); + }, + "ticket"_a) + .def( + "noise_phase", + [](BoundSession& self, const std::pair ticket, + const double z) { return self.table_phi(ticket.first, ticket.second, z); }, + "ticket"_a, "z"_a) + .def("records", &BoundSession::records) + .def("continue_with", &BoundSession::continue_with, "continuation"_a) .def("close", &BoundSession::close, nb::call_guard()); + // solprop SEP 52 section 5.3: the new seam -- one workspace a problem, one run record + // a start, the probe, and the tables every record is read by. + nb::class_(module_, "Probe") + .def("trial", &BoundProbe::trial, "z"_a, "dz"_a) + .def("field", &BoundProbe::field) + .def_prop_ro("trials", &BoundProbe::trials) + .def_prop_ro("evaluations", &BoundProbe::evaluations) + .def_prop_ro("low_storage", &BoundProbe::low_storage) + .def_prop_ro("z", &BoundProbe::z) + .def_prop_ro("closed", &BoundProbe::closed) + .def("close", &BoundProbe::close, nb::call_guard()); + nb::class_(module_, "Workspace") + .def(nb::init(), "problem"_a) + .def("start", &BoundWorkspace::start, "run"_a, + "host_source"_a.none() = nb::none(), nb::keep_alive<0, 1>()) + .def("probe", &BoundWorkspace::probe, "start"_a, nb::keep_alive<0, 1>()) + .def("diagnostics", &BoundWorkspace::diagnostics) + .def("unbind_host_source", &BoundWorkspace::unbind_host_source) + .def_prop_ro("closed", &BoundWorkspace::closed) + .def("close", &BoundWorkspace::close, nb::call_guard()); + module_.def("configure_runtime", &configure_runtime, "record"_a); + module_.def("schemas", &schemas); auto testing = module_.def_submodule("_testing", "Private entry points for solprop's own tests"); native::bindings::bind_helpers(module_, testing); native::bindings::bind_transverse(testing); bind_testing(testing); + bind_engines(testing); if (Py_AtExit(&shutdown_after_interpreter) != 0) throw std::runtime_error( "cannot register the Kokkos runtime's shutdown at interpreter exit"); diff --git a/native/src/records.cpp b/native/src/records.cpp new file mode 100644 index 000000000..fa06094f3 --- /dev/null +++ b/native/src/records.cpp @@ -0,0 +1,249 @@ +// SPDX-FileCopyrightText: 2026 John C. Travers and contributors +// +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "records.hpp" + +#include + +#include +#include + +namespace solprop_native::records { + +void type_refusal(const std::string& path, const std::string& message) { + throw nb::type_error((path + " " + message).c_str()); +} + +void value_refusal(const std::string& path, const std::string& message) { + throw std::invalid_argument(path + " " + message); +} + +std::string child(const std::string& path, const std::string& name) { + return path.empty() ? name : path + "." + name; +} + +std::string child(const std::string& path, const std::size_t index) { + return path + "[" + std::to_string(index) + "]"; +} + +bool is_bool(const nb::handle value) { + if (PyBool_Check(value.ptr())) + return true; + // NumPy's bool scalar. + const auto type = + nb::borrow(reinterpret_cast(Py_TYPE(value.ptr()))); + return nb::hasattr(type, "__module__") && + nb::cast(nb::str(type.attr("__module__"))) == "numpy" && + nb::cast(nb::str(type.attr("__name__"))) == "bool"; +} + +bool is_integer(const nb::handle value) { return PyIndex_Check(value.ptr()) != 0; } + +bool is_number(const nb::handle value) { + // A float (NumPy's float64 among them) or an integer; never a complex or a str. + return PyFloat_Check(value.ptr()) || PyIndex_Check(value.ptr()) != 0; +} + +bool is_sequence(const nb::handle value) { + return PySequence_Check(value.ptr()) != 0 && !nb::isinstance(value) && + !nb::isinstance(value) && !nb::isinstance(value); +} + +bool is_mapping(const nb::handle value) { + return nb::isinstance(value) || + (PyMapping_Check(value.ptr()) != 0 && nb::hasattr(value, "keys") && + !is_sequence(value)); +} + +Source::Source(const nb::handle value, const std::string& path) : value_(value) { + const auto type = nb::handle(reinterpret_cast(Py_TYPE(value.ptr()))); + if (nb::hasattr(type, "__dataclass_fields__") && + !nb::isinstance(value)) { + for (const auto key : + nb::borrow(type.attr("__dataclass_fields__")).keys()) + names_.push_back(nb::cast(key)); + return; + } + if (is_mapping(value)) { + mapping_ = true; + PyObject* keys = PyMapping_Keys(value.ptr()); + if (keys == nullptr) + throw nb::python_error(); + for (const auto key : nb::steal(keys)) { + if (!nb::isinstance(key)) + type_refusal(path, "must have str keys"); + names_.push_back(nb::cast(key)); + } + return; + } + if (nb::isinstance(value) || nb::isinstance(value)) { + positional_ = true; + size_ = nb::len(value); + return; + } + type_refusal(path, "must be a dataclass, a mapping or a tuple of fields"); +} + +bool Source::has(const char* name, const std::size_t index) const { + if (positional_) + return index < size_; + for (const auto& entry : names_) + if (entry == name) + return true; + return false; +} + +nb::object Source::get(const char* name, const std::size_t index) const { + if (positional_) + return nb::borrow(value_)[index]; + if (mapping_) + return value_[name]; + return value_.attr(name); +} + +namespace { + +nb::dlpack::dtype numpy_dtype(const fields::Dtype dtype) { + switch (dtype) { + case fields::Dtype::float64: + return nb::dtype(); + case fields::Dtype::complex128: + return nb::dtype>(); + case fields::Dtype::uint64: + return nb::dtype(); + case fields::Dtype::uint8: + return nb::dtype(); + case fields::Dtype::boolean: + return nb::dtype(); + } + return {}; +} + +std::size_t element_size(const fields::Dtype dtype) { + switch (dtype) { + case fields::Dtype::float64: + case fields::Dtype::uint64: + return 8; + case fields::Dtype::complex128: + return 16; + case fields::Dtype::uint8: + case fields::Dtype::boolean: + return 1; + } + return 0; +} + +std::string shape_text(const std::vector& shape) { + std::string text = "("; + for (std::size_t axis = 0; axis < shape.size(); ++axis) + text += (axis == 0 ? "" : ", ") + std::to_string(shape[axis]); + return text + (shape.size() == 1 ? ",)" : ")"); +} + +} // namespace + +Borrowed borrow(const nb::handle value, const fields::Dtype dtype, + const std::size_t rank, const std::string& path) { + using Any = nb::ndarray; + const std::string wanted = fields::dtype_name(dtype); + const std::string axes = rank == 0 ? "" : " of rank " + std::to_string(rank); + Any array; + if (!nb::try_cast(value, array, false)) + type_refusal(path, "must be a C-contiguous " + wanted + " array" + axes); + if (array.dtype() != numpy_dtype(dtype)) + type_refusal(path, "must be a C-contiguous " + wanted + " array" + axes + + ", not another dtype"); + Borrowed out; + out.shape.resize(array.ndim()); + for (std::size_t axis = 0; axis < array.ndim(); ++axis) + out.shape[axis] = array.shape(axis); + if (rank != 0 && array.ndim() != rank) + value_refusal(path, "must be a C-contiguous " + wanted + " array" + axes + + ", given shape " + shape_text(out.shape)); + // C order, element strides: an axis of one may take any stride; a stride of zero + // elsewhere is an overlapping (broadcast) view. + // An empty array holds nothing to overlap, whatever its strides. + bool empty = false; + for (const auto size : out.shape) + empty = empty || size == 0; + std::size_t count = 1; + for (std::size_t axis = array.ndim(); axis-- > 0;) { + const std::size_t size = out.shape[axis]; + if (!empty && size != 1 && array.stride(axis) != static_cast(count)) + value_refusal(path, "must be a C-contiguous " + wanted + " array" + axes + + ", not a strided or overlapping view"); + if (size != 0 && count > std::numeric_limits::max() / size) + value_refusal(path, "has a size whose product overflows"); + count *= size; + } + if (count > std::numeric_limits::max() / element_size(dtype)) + value_refusal(path, "has a size whose product overflows"); + out.count = count; + out.data = array.data(); + return out; +} + +std::string extent_text(const fields::Extent& extent) { + if (extent.fixed_size) + return std::to_string(extent.literal); + if (extent.symbol == nullptr) + return "*"; + std::string text = extent.symbol; + if (extent.offset > 0) + text += "+" + std::to_string(extent.offset); + else if (extent.offset < 0) + text += std::to_string(extent.offset); + return text; +} + +void relate(const std::vector& shape, const fields::Extent* extents, + const std::size_t rank, Symbols& symbols, const std::string& path) { + std::string relation = "("; + for (std::size_t axis = 0; axis < rank; ++axis) + relation += (axis == 0 ? "" : ", ") + extent_text(extents[axis]); + relation += rank == 1 ? ",)" : ")"; + for (std::size_t axis = 0; axis < rank; ++axis) { + const auto& extent = extents[axis]; + const std::size_t size = shape[axis]; + const auto refuse_axis = [&](const std::string& why) { + value_refusal(path, "has shape " + shape_text(shape) + ", and its layout is " + + relation + ": axis " + std::to_string(axis) + " " + why); + }; + if (extent.fixed_size) { + if (size != extent.literal) + refuse_axis("must be " + std::to_string(extent.literal)); + continue; + } + if (extent.symbol == nullptr) + continue; + const auto signed_size = static_cast(size); + if (signed_size < extent.offset) + refuse_axis("is shorter than its offset"); + const auto value = static_cast(signed_size - extent.offset); + const auto found = symbols.find(extent.symbol); + if (found == symbols.end()) + symbols[extent.symbol] = value; + else if (found->second != value) + refuse_axis("gives " + std::string(extent.symbol) + " = " + + std::to_string(value) + ", where the record has " + + std::to_string(found->second)); + } +} + +nb::object owned_array(const void* data, const std::size_t bytes, + const fields::Dtype dtype, + const std::vector& shape) { + auto storage = std::make_unique(bytes == 0 ? 1 : bytes); + if (bytes != 0) + std::memcpy(storage.get(), data, bytes); + nb::capsule owner(storage.get(), [](void* held) noexcept { + const std::unique_ptr owned(static_cast(held)); + }); + void* pointer = storage.release(); + const nb::ndarray array(pointer, shape.size(), shape.data(), owner, + nullptr, numpy_dtype(dtype)); + return nb::cast(array); +} + +} // namespace solprop_native::records diff --git a/native/src/records.hpp b/native/src/records.hpp new file mode 100644 index 000000000..4af3973c1 --- /dev/null +++ b/native/src/records.hpp @@ -0,0 +1,763 @@ +// SPDX-FileCopyrightText: 2026 John C. Travers and contributors +// +// SPDX-License-Identifier: GPL-3.0-or-later + +#pragma once + +#include "solprop_native/fields.hpp" + +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +/* + * The field-table converter (solprop SEP 52 section 5.3): one template that reads a + * Python dataclass, a mapping or a tuple into a C++ record by its table + * (`solprop_native/fields.hpp`) and writes the record back as a dictionary, and the + * schema export of every table. + * + * Reading takes two passes over the input, both under the interpreter lock: the first + * checks every field -- a missing or unknown field, a wrong type or dtype, an array + * that is not C-contiguous or overlaps itself, a wrong rank, extents that disagree with + * their relations, a size whose product overflows -- and allocates nothing; the second + * copies each value into the record's own storage. Inputs are borrowed for the call: + * read-only arrays are admitted, since nothing writes them. A refusal names the + * field's path (`run.records.planes.planes`). Arrays written back own their storage + * through a capsule. + */ +namespace solprop_native::records { + +namespace nb = nanobind; + +/** The symbols an array's extents bind within one record, by name. */ +using Symbols = std::map; + +/** How a binding reads a type the tables name but cannot describe (a bound object such + as a statistics plan); specialised before use. */ +template struct Extern; + +// ------------------------------------------------------------- non-template helpers + +/** Refuse with Python's `TypeError`, naming `path`. */ +[[noreturn]] void type_refusal(const std::string& path, const std::string& message); +/** Refuse with Python's `ValueError`, naming `path`. */ +[[noreturn]] void value_refusal(const std::string& path, const std::string& message); +/** A child's path. */ +[[nodiscard]] std::string child(const std::string& path, const std::string& name); +[[nodiscard]] std::string child(const std::string& path, std::size_t index); + +/** The fields a Python record offers: a dataclass's, a mapping's keys or a tuple's + positions. */ +class Source { +public: + Source(nb::handle value, const std::string& path); + /** Whether a field of this name (at this position) is given. */ + [[nodiscard]] bool has(const char* name, std::size_t index) const; + [[nodiscard]] nb::object get(const char* name, std::size_t index) const; + /** The given names (empty for a tuple). */ + [[nodiscard]] const std::vector& names() const { return names_; } + [[nodiscard]] bool positional() const { return positional_; } + [[nodiscard]] std::size_t size() const { return size_; } + +private: + nb::handle value_; + bool positional_ = false; + bool mapping_ = false; + std::size_t size_ = 0; + std::vector names_; +}; + +/** A checked array: its data, shape and dtype, borrowed for the conversion. */ +struct Borrowed { + const void* data = nullptr; + std::vector shape; + std::size_t count = 0; +}; + +/** Check `value` as a C-contiguous CPU array of `dtype` (`rank` axes, or any rank for + zero) whose element count does not overflow; refuse naming `path`. */ +[[nodiscard]] Borrowed borrow(nb::handle value, fields::Dtype dtype, std::size_t rank, + const std::string& path); +/** Hold `shape` to `extents`, binding the symbols they name the first time. */ +void relate(const std::vector& shape, const fields::Extent* extents, + std::size_t rank, Symbols& symbols, const std::string& path); +/** One extent as text: `n_terms`, `n_edges-1`, `2` or `*`. */ +[[nodiscard]] std::string extent_text(const fields::Extent& extent); +/** A NumPy array owning a copy of `bytes` bytes of `dtype`, of `shape`. */ +[[nodiscard]] nb::object owned_array(const void* data, std::size_t bytes, + fields::Dtype dtype, + const std::vector& shape); + +[[nodiscard]] bool is_bool(nb::handle value); +[[nodiscard]] bool is_integer(nb::handle value); +[[nodiscard]] bool is_number(nb::handle value); +[[nodiscard]] bool is_sequence(nb::handle value); +[[nodiscard]] bool is_mapping(nb::handle value); + +// ------------------------------------------------------------------ type traits + +template struct IsVector : std::false_type {}; +template struct IsVector> : std::true_type {}; +template struct IsVector> : std::true_type {}; +template struct IsOptional : std::false_type {}; +template struct IsOptional> : std::true_type {}; +template struct IsStdArray : std::false_type {}; +template +struct IsStdArray> : std::true_type {}; +template struct IsVariant : std::false_type {}; +template struct IsVariant> : std::true_type {}; +template struct IsNumberMap : std::false_type {}; +template <> struct IsNumberMap> : std::true_type {}; + +template +concept Named = + std::is_enum_v && requires { names(static_cast(nullptr)); }; +template +concept HasExtern = requires { Extern::kind; }; +template +concept Presence = requires(const T& value) { + { value.present() } -> std::convertible_to; +}; +template +concept HasShapes = requires(R& record) { record.shapes; }; + +template struct FieldKind; +template struct FieldKind> { + static constexpr int kind = 0; +}; +template struct FieldKind> { + static constexpr int kind = 1; +}; +template struct FieldKind> { + static constexpr int kind = 2; +}; +template struct FieldKind> { + static constexpr int kind = 3; +}; + +// --------------------------------------------------------------------- reading + +template void read_record(nb::handle value, R* out, const std::string& path); + +/** The names a record's table reads from Python (its counts are not read). */ +template std::vector table_names() { + std::vector out; + fields::each(fields::table_of(), [&](const auto& field) { + using Field = std::remove_cvref_t; + if constexpr (FieldKind::kind != 3) + out.push_back(field.name); + }); + return out; +} + +/** Whether `source` names exactly `R`'s fields (every one, nothing else). */ +template bool matches(const Source& source) { + const auto wanted = table_names(); + if (source.positional()) + return source.size() == wanted.size(); + if (source.names().size() != wanted.size()) + return false; + for (const char* name : wanted) + if (!source.has(name, 0)) + return false; + return true; +} + +template void read_value(nb::handle value, T* out, const std::string& path); + +template +void read_variant(nb::handle value, Variant* out, const std::string& path) { + const Source source(value, path); + bool found = false; + const auto attempt = [&]() { + if (found || !matches(source)) + return; + found = true; + if (out == nullptr) { + read_record(value, static_cast(nullptr), path); + } else { + A held; + read_record(value, &held, path); + *out = std::move(held); + } + }; + (attempt.template operator()(), ...); + if (!found) { + std::string names; + ((names += + std::string(names.empty() ? "" : " or ") + fields::table_of().name), + ...); + type_refusal(path, "matches none of " + names + " by its fields"); + } +} + +template struct VariantReader; +template struct VariantReader> { + static void read(nb::handle value, Variant* out, const std::string& path) { + read_variant(value, out, path); + } +}; + +template void read_value(nb::handle value, T* out, const std::string& path) { + if constexpr (std::is_same_v) { + if (!is_bool(value)) + type_refusal(path, "must be a bool"); + if (out != nullptr) + *out = nb::cast(value, true); + } else if constexpr (Named) { + constexpr auto table = names(static_cast(nullptr)); + std::optional held; + nb::handle name = value; + nb::object attribute; + if (!nb::isinstance(value) && nb::hasattr(value, "name")) { + attribute = value.attr("name"); + name = attribute; + } + if (nb::isinstance(name)) { + const auto text = nb::cast(name); + for (const auto& [label, entry] : table) + if (text == label) + held = entry; + } else if (is_integer(value)) { + const auto number = nb::cast(value, true); + for (const auto& [label, entry] : table) + if (static_cast(entry) == number) + held = entry; + } + if (!held) { + std::string labels; + for (const auto& [label, entry] : table) + labels += std::string(labels.empty() ? "" : ", ") + label; + value_refusal(path, "must name one of " + labels); + } + if (out != nullptr) + *out = *held; + } else if constexpr (std::is_integral_v) { + if (!is_integer(value) || is_bool(value)) + type_refusal(path, "must be an integer"); + T held{}; + if (!nb::try_cast(value, held, true)) + value_refusal(path, "is out of range"); + if (out != nullptr) + *out = held; + } else if constexpr (std::is_floating_point_v) { + if (!is_number(value) || is_bool(value)) + type_refusal(path, "must be a number"); + if (out != nullptr) + *out = nb::cast(value, true); + } else if constexpr (std::is_same_v) { + if (!nb::isinstance(value)) + type_refusal(path, "must be a str"); + if (out != nullptr) + *out = nb::cast(value); + } else if constexpr (IsOptional::value) { + using Inner = typename T::value_type; + if (value.is_none()) { + if (out != nullptr) + out->reset(); + return; + } + if (out == nullptr) { + read_value(value, nullptr, path); + } else { + Inner held{}; + read_value(value, &held, path); + *out = std::move(held); + } + } else if constexpr (HasExtern) { + Extern::read(value, out, path); + } else if constexpr (IsVariant::value) { + VariantReader::read(value, out, path); + } else if constexpr (IsNumberMap::value) { + if (!is_mapping(value)) + type_refusal(path, "must be a mapping of names to numbers"); + PyObject* listed = PyMapping_Items(value.ptr()); + if (listed == nullptr) + throw nb::python_error(); + const auto items = nb::steal(listed); + if (out != nullptr) + out->clear(); + for (const auto item : items) { + const auto pair = nb::borrow(item); + if (!nb::isinstance(pair[0])) + type_refusal(path, "must have str keys"); + const auto key = nb::cast(pair[0]); + double number = 0.0; + read_value(pair[1], &number, child(path, key)); + if (out != nullptr) + (*out)[key] = number; + } + } else if constexpr (IsStdArray::value || std::is_array_v) { + using Element = std::remove_cvref_t()[0])>; + constexpr std::size_t size = sizeof(T) / sizeof(Element); + if (!is_sequence(value)) + type_refusal(path, "must be a sequence of " + std::to_string(size)); + const auto items = nb::borrow(value); + if (nb::len(items) != size) + value_refusal(path, "must hold " + std::to_string(size) + " values"); + for (std::size_t index = 0; index < size; ++index) + read_value(items[index], out == nullptr ? nullptr : &(*out)[index], + child(path, index)); + } else if constexpr (IsVector::value) { + using Element = typename T::value_type; + if (!is_sequence(value)) + type_refusal(path, "must be a sequence"); + const auto items = nb::borrow(value); + const std::size_t size = nb::len(items); + if (out != nullptr) + out->clear(); + for (std::size_t index = 0; index < size; ++index) { + if (out == nullptr) { + read_value(items[index], nullptr, child(path, index)); + } else { + Element held{}; + read_value(items[index], &held, child(path, index)); + out->push_back(std::move(held)); + } + } + } else if constexpr (fields::Described) { + // A table with a notion of absence (a stage table) reads `None` as absent. + if constexpr (Presence) { + if (value.is_none()) { + if (out != nullptr) + *out = T{}; + return; + } + } + read_record(value, out, path); + } else { + static_assert(sizeof(T) == 0, "a field type the converter cannot read"); + } +} + +template +void read_array(const fields::Array& field, nb::handle value, R* out, + Symbols& symbols, const std::string& path) { + using Traits = fields::ArrayElement; + using Element = typename Traits::type; + if constexpr (Traits::optional) { + if (value.is_none()) { + if (out != nullptr) + (out->*field.member).reset(); + return; + } + } + const auto borrowed = borrow(value, field.dtype, N, path); + if constexpr (N > 0) + relate(borrowed.shape, field.extents.data(), N, symbols, path); + if (out == nullptr) + return; + std::vector held(borrowed.count); + static_assert(std::is_trivially_copyable_v); + if (borrowed.count != 0) + std::memcpy(static_cast(held.data()), borrowed.data, + borrowed.count * sizeof(Element)); + out->*field.member = std::move(held); + if constexpr (N == 0 && HasShapes) + out->shapes[field.name] = borrowed.shape; +} + +/** Bind an integral field's value as the symbol of its name, for the arrays. */ +template +void bind_count(const char* name, const T& value, Symbols& symbols, + const std::string& path) { + if constexpr (std::is_integral_v && !std::is_same_v) { + if (value < 0) + return; + const auto count = static_cast(value); + const auto found = symbols.find(name); + if (found != symbols.end() && found->second != count) + value_refusal(path, "is " + std::to_string(count) + ", and the arrays give " + + std::to_string(found->second)); + symbols[name] = count; + } +} + +template void read_record(nb::handle value, R* out, const std::string& path) { + const Source source(value, path); + constexpr auto table = fields::table_of(); + const auto wanted = table_names(); + if (source.positional()) { + if (source.size() != wanted.size()) + value_refusal(path, std::string("is a ") + table.name + " of " + + std::to_string(wanted.size()) + " fields, given " + + std::to_string(source.size())); + } else { + for (const auto& name : source.names()) { + bool known = false; + for (const char* entry : wanted) + known = known || name == entry; + if (!known) + value_refusal(path, std::string("has an unknown field '") + name + "' for a " + + table.name); + } + } + Symbols symbols; + std::size_t index = 0; + fields::each(table, [&](const auto& field) { + using Field = std::remove_cvref_t; + constexpr int kind = FieldKind::kind; + if constexpr (kind == 3) { + return; + } else { + const std::size_t position = index++; + const auto where = child(path, field.name); + if (!source.has(field.name, position)) { + // An optional field may be left out of a mapping. + if constexpr (kind == 1) { + if (out != nullptr) + out->*field.flag = false; + return; + } else if constexpr (kind == 0) { + using M = std::remove_cvref_t().*field.member)>; + if constexpr (IsOptional::value) { + if (out != nullptr) + (out->*field.member).reset(); + return; + } + } else if constexpr (kind == 2) { + using M = std::remove_cvref_t().*field.member)>; + if constexpr (fields::ArrayElement::optional) { + if (out != nullptr) + (out->*field.member).reset(); + return; + } + } + value_refusal(where, std::string("is missing from a ") + table.name); + } + const auto item = source.get(field.name, position); + if constexpr (kind == 0) { + using M = std::remove_cvref_t().*field.member)>; + if (out == nullptr) { + if constexpr (std::is_integral_v && !std::is_same_v) { + M held{}; + read_value(item, &held, where); + bind_count(field.name, held, symbols, where); + } else { + read_value(item, static_cast(nullptr), where); + } + } else { + read_value(item, &(out->*field.member), where); + bind_count(field.name, out->*field.member, symbols, where); + } + } else if constexpr (kind == 1) { + using M = std::remove_cvref_t().*field.member)>; + if (item.is_none()) { + if (out != nullptr) { + out->*field.flag = false; + out->*field.member = M{}; + } + } else { + read_value(item, out == nullptr ? nullptr : &(out->*field.member), where); + if (out != nullptr) + out->*field.flag = true; + } + } else { + read_array(field, item, out, symbols, where); + } + } + }); + if (out == nullptr) + return; + fields::each(table, [&](const auto& field) { + using Field = std::remove_cvref_t; + if constexpr (FieldKind::kind == 3) { + const auto found = symbols.find(field.symbol); + using M = std::remove_cvref_t*field.member)>; + out->*field.member = found == symbols.end() ? M{} : static_cast(found->second); + } + }); +} + +/** Read `value` into a new `R`: check everything, then copy. */ +template R read(nb::handle value, const std::string& path) { + read_value(value, static_cast(nullptr), path); + R out{}; + read_value(value, &out, path); + return out; +} + +// --------------------------------------------------------------------- writing + +template nb::dict write_record(const R& record); + +template nb::object write_value(const T& value) { + if constexpr (std::is_same_v) { + return nb::bool_(value); + } else if constexpr (Named) { + constexpr auto table = names(static_cast(nullptr)); + for (const auto& [label, entry] : table) + if (entry == value) + return nb::str(label); + return nb::int_(static_cast(value)); + } else if constexpr (std::is_integral_v || std::is_floating_point_v || + std::is_same_v) { + return nb::cast(value); + } else if constexpr (IsOptional::value) { + return value ? write_value(*value) : nb::none(); + } else if constexpr (HasExtern) { + return Extern::write(value); + } else if constexpr (IsVariant::value) { + return std::visit([](const auto& held) -> nb::object { return write_value(held); }, + value); + } else if constexpr (IsNumberMap::value) { + nb::dict out; + for (const auto& [key, number] : value) + out[key.c_str()] = number; + return out; + } else if constexpr (IsStdArray::value || std::is_array_v || + IsVector::value) { + nb::list out; + for (const auto& item : value) + out.append(write_value(item)); + return out; + } else if constexpr (fields::Described) { + if constexpr (Presence) { + if (!value.present()) + return nb::none(); + } + return write_record(value); + } else { + static_assert(sizeof(T) == 0, "a field type the converter cannot write"); + } +} + +/** The symbols a record's counts, integral fields and arrays give back. */ +template Symbols written_symbols(const R& record) { + Symbols symbols; + constexpr auto table = fields::table_of(); + fields::each(table, [&](const auto& field) { + using Field = std::remove_cvref_t; + constexpr int kind = FieldKind::kind; + if constexpr (kind == 3) { + symbols[field.symbol] = static_cast(record.*field.member); + } else if constexpr (kind == 0) { + using M = std::remove_cvref_t; + if constexpr (std::is_integral_v && !std::is_same_v) + symbols[field.name] = static_cast(record.*field.member); + } + }); + // An array with one axis left to resolve gives it, twice round for chains. + for (int round = 0; round < 2; ++round) + fields::each(table, [&](const auto& field) { + using Field = std::remove_cvref_t; + if constexpr (FieldKind::kind == 2) { + constexpr std::size_t rank = std::tuple_size_v; + if constexpr (rank > 0) { + const auto* values = &(record.*field.member); + std::size_t size = 0; + if constexpr (fields::ArrayElement< + std::remove_cvref_t>::optional) { + if (!*values) + return; + size = (*values)->size(); + } else { + size = values->size(); + } + std::size_t known = 1; + const fields::Extent* open = nullptr; + for (const auto& extent : field.extents) { + if (extent.fixed_size) { + known *= extent.literal; + } else if (extent.symbol != nullptr && symbols.contains(extent.symbol)) { + known *= static_cast( + static_cast(symbols[extent.symbol]) + extent.offset); + } else if (open == nullptr && extent.symbol != nullptr) { + open = &extent; + } else { + return; + } + } + if (open != nullptr && known != 0 && size % known == 0) + symbols[open->symbol] = static_cast( + static_cast(size / known) - open->offset); + } + } + }); + return symbols; +} + +template +nb::object write_array(const fields::Array& field, const R& record, + const Symbols& symbols) { + using Traits = fields::ArrayElement; + const std::vector* values = nullptr; + if constexpr (Traits::optional) { + if (!(record.*field.member)) + return nb::none(); + values = &*(record.*field.member); + } else { + values = &(record.*field.member); + } + std::vector shape{values->size()}; + if constexpr (N == 0 && HasShapes) { + const auto found = record.shapes.find(field.name); + if (found != record.shapes.end()) + shape = found->second; + } else if constexpr (N > 0) { + std::vector resolved; + std::size_t product = 1; + bool known = true; + for (const auto& extent : field.extents) { + std::size_t size = 0; + if (extent.fixed_size) { + size = extent.literal; + } else if (extent.symbol != nullptr && symbols.contains(extent.symbol)) { + size = static_cast( + static_cast(symbols.at(extent.symbol)) + extent.offset); + } else { + known = false; + break; + } + resolved.push_back(size); + product *= size; + } + if (known && product == values->size()) + shape = std::move(resolved); + } + std::size_t product = 1; + for (const auto size : shape) + product *= size; + if (product != values->size()) + shape = {values->size()}; + return owned_array(values->data(), values->size() * sizeof(typename Traits::type), + field.dtype, shape); +} + +template nb::dict write_record(const R& record) { + nb::dict out; + const auto symbols = written_symbols(record); + fields::each(fields::table_of(), [&](const auto& field) { + using Field = std::remove_cvref_t; + constexpr int kind = FieldKind::kind; + if constexpr (kind == 0) { + out[field.name] = write_value(record.*field.member); + } else if constexpr (kind == 1) { + out[field.name] = + record.*field.flag ? write_value(record.*field.member) : nb::none(); + } else if constexpr (kind == 2) { + out[field.name] = write_array(field, record, symbols); + } + }); + return out; +} + +// --------------------------------------------------------------------- schemas + +template void collect(nb::dict& tables); + +template nb::dict describe_value(nb::dict& tables) { + nb::dict out; + if constexpr (std::is_same_v) { + out["kind"] = "bool"; + } else if constexpr (Named) { + out["kind"] = "enum"; + nb::list labels; + for (const auto& [label, entry] : names(static_cast(nullptr))) + labels.append(label); + out["values"] = labels; + } else if constexpr (std::is_integral_v) { + out["kind"] = "int"; + } else if constexpr (std::is_floating_point_v) { + out["kind"] = "float"; + } else if constexpr (std::is_same_v) { + out["kind"] = "str"; + } else if constexpr (IsOptional::value) { + out["kind"] = "optional"; + out["of"] = describe_value(tables); + } else if constexpr (HasExtern) { + out["kind"] = "object"; + out["type"] = Extern::kind; + } else if constexpr (IsVariant::value) { + out["kind"] = "variant"; + nb::list names; + [&](std::variant* /*unused*/) { + (collect(tables), ...); + (names.append(fields::table_of().name), ...); + }(static_cast(nullptr)); + out["records"] = names; + } else if constexpr (IsNumberMap::value) { + out["kind"] = "mapping"; + out["of"] = describe_value(tables); + } else if constexpr (IsStdArray::value || std::is_array_v) { + using Element = std::remove_cvref_t()[0])>; + out["kind"] = "sequence"; + out["size"] = sizeof(T) / sizeof(Element); + out["of"] = describe_value(tables); + } else if constexpr (IsVector::value) { + out["kind"] = "sequence"; + out["of"] = describe_value(tables); + } else if constexpr (fields::Described) { + collect(tables); + out["kind"] = "record"; + out["record"] = fields::table_of().name; + out["nullable"] = Presence; + } + return out; +} + +/** `R`'s table as data: each field's name and kind, an array's dtype, rank and extent + relations, and the counts its arrays give. */ +template nb::dict schema(nb::dict& tables) { + constexpr auto table = fields::table_of(); + nb::list entries; + nb::dict counts; + fields::each(table, [&](const auto& field) { + using Field = std::remove_cvref_t; + constexpr int kind = FieldKind::kind; + if constexpr (kind == 3) { + counts[field.symbol] = field.symbol; + } else { + nb::dict entry; + if constexpr (kind == 0) { + using M = std::remove_cvref_t().*field.member)>; + entry = describe_value(tables); + } else if constexpr (kind == 1) { + using M = std::remove_cvref_t().*field.member)>; + entry["kind"] = "optional"; + entry["of"] = describe_value(tables); + } else { + using M = std::remove_cvref_t().*field.member)>; + constexpr std::size_t rank = std::tuple_size_v; + entry["kind"] = "array"; + entry["dtype"] = fields::dtype_name(field.dtype); + entry["rank"] = rank == 0 ? nb::none() : nb::cast(rank); + nb::list extents; + for (const auto& extent : field.extents) + extents.append(extent_text(extent)); + entry["extents"] = extents; + entry["optional"] = fields::ArrayElement::optional; + } + entry["name"] = field.name; + entries.append(entry); + } + }); + nb::dict out; + out["fields"] = entries; + out["counts"] = counts; + return out; +} + +template void collect(nb::dict& tables) { + constexpr auto name = fields::table_of().name; + if (tables.contains(name)) + return; + tables[name] = nb::none(); // held while its fields are described + tables[name] = schema(tables); +} + +} // namespace solprop_native::records diff --git a/native/src/solprop_native/_core.pyi b/native/src/solprop_native/_core.pyi index cd9fb9d4b..d449202c0 100644 --- a/native/src/solprop_native/_core.pyi +++ b/native/src/solprop_native/_core.pyi @@ -5,6 +5,7 @@ from __future__ import annotations import enum +from collections.abc import Mapping, Sequence from typing import Any, overload import numpy as np @@ -231,6 +232,15 @@ class Problem: group_keys: npt.NDArray[np.uint64] node_region: npt.NDArray[np.uint64] + stage_tables: Mapping[str, object] | None + z_slots: Mapping[str, object] | None + z_tables: Sequence[Mapping[str, object]] + flow_guard: Mapping[str, object] | None + runge_kutta: Mapping[str, object] | None + adams: Mapping[str, object] | None + low_storage: object | None + monitor: Mapping[str, object] | None + edge: Mapping[str, object] | None dims: Problem.Dims grid: Problem.Grid spatial: Problem.Spatial @@ -593,6 +603,7 @@ class StatisticsPlan: class Session: def advance(self, work_limit: int, deadline: float) -> SessionBatch: ... def acknowledge(self, sequence: int) -> None: ... + @overload def export( self, sequence: int, @@ -602,6 +613,28 @@ class Session: weight: npt.NDArray[np.float64] | None, out: npt.NDArray[np.complex128], ) -> None: ... + @overload + def export( + self, + ticket: tuple[int, int], + recipe: Mapping[str, object], + out: npt.NDArray[np.complex128], + ) -> None: ... + def snapshot( + self, ticket: tuple[int, int] + ) -> ( + tuple[ + dict[str, Any], + npt.NDArray[np.complex128], + dict[str, npt.NDArray[np.complex128]], + ] + | None + ): ... + def noise_phase( + self, ticket: tuple[int, int], z: float + ) -> npt.NDArray[np.complex128]: ... + def records(self) -> dict[str, Any]: ... + def continue_with(self, continuation: object) -> None: ... def request_stop(self) -> None: ... def request_snapshot(self) -> tuple[int, bool]: ... def status(self) -> SessionStatus: ... @@ -634,3 +667,32 @@ class Session: ) -> npt.NDArray[np.complex128]: ... def fail_outside(self) -> SessionBatch | None: ... def close(self) -> None: ... + +# solprop SEP 52 section 5.3: one workspace a problem, one run record a start. +class Probe: + def trial(self, z: float, dz: float) -> float: ... + def field(self) -> npt.NDArray[np.complex128]: ... + @property + def trials(self) -> int: ... + @property + def evaluations(self) -> int: ... + @property + def low_storage(self) -> bool: ... + @property + def z(self) -> float: ... + @property + def closed(self) -> bool: ... + def close(self) -> None: ... + +class Workspace: + def __init__(self, problem: Problem) -> None: ... + def start(self, run: object, host_source: object | None = None) -> Session: ... + def probe(self, start: object) -> Probe: ... + def diagnostics(self) -> dict[str, Any]: ... + def unbind_host_source(self) -> None: ... + @property + def closed(self) -> bool: ... + def close(self) -> None: ... + +def configure_runtime(record: object) -> dict[str, str]: ... +def schemas() -> dict[str, dict[str, Any]]: ... diff --git a/native/src/solprop_native/_core_testing.pyi b/native/src/solprop_native/_core_testing.pyi index 1223c0371..6affbc299 100644 --- a/native/src/solprop_native/_core_testing.pyi +++ b/native/src/solprop_native/_core_testing.pyi @@ -9,12 +9,13 @@ from __future__ import annotations +from collections.abc import Sequence from typing import Any import numpy as np import numpy.typing as npt -from solprop_native._core import State, StatisticsPlan +from solprop_native._core import State, StatisticsPlan, Workspace def trial_step( state: State, @@ -308,3 +309,43 @@ class ScriptedRkMarch: ) -> dict[str, Any]: ... def log(self) -> list[dict[str, Any]]: ... def used(self) -> int: ... + +# solprop SEP 52 section 6.5: native's engines through solprop's protocols +# (`solprop.backends.engines`), each method prefixed by its engine, with read-backs. +class Engines: + def __init__(self) -> None: ... # made by `engines(workspace)` alone + def field(self) -> npt.NDArray[np.complex128]: ... + def stage(self, index: int) -> npt.NDArray[np.complex128]: ... + def load( + self, field: npt.NDArray[np.complex128], noise: npt.NDArray[np.complex128] + ) -> None: ... + def close(self) -> None: ... + def rk_trial(self, z: float, dz: float) -> float: ... + def rk_accept(self, dz: float) -> Any: ... + def rk_extend(self, z: float, dz: float) -> None: ... + def rk_reading(self) -> Any: ... + @property + def rk_in_flight(self) -> bool: ... + def adams_start(self, z: float) -> None: ... + def adams_trial( + self, z: float, dz: float, stencil: Any + ) -> npt.NDArray[np.float64]: ... + def adams_accept( + self, dz: float, free: int, stencil: Any, kept: Sequence[Any] + ) -> Any: ... + def adams_chord_phase(self, z1: float, z2: float) -> float: ... + def adams_step_carrier( + self, order: int + ) -> npt.NDArray[np.float64] | list[float]: ... + def adams_begin_attempt(self, cost: int) -> None: ... + def adams_end_attempt(self, outcome: int) -> None: ... + def adams_reading(self) -> Any: ... + +def engines(workspace: Workspace) -> Engines: ... +def inject_fault( + workspace: Workspace, stage: str, after: int, category: str +) -> None: ... +def evaluate( + workspace: Workspace, plan: StatisticsPlan, z: float +) -> npt.NDArray[np.float64]: ... +def round_trip(name: str, value: object) -> dict[str, Any]: ... diff --git a/native/src/workspace.cpp b/native/src/workspace.cpp new file mode 100644 index 000000000..aceaba495 --- /dev/null +++ b/native/src/workspace.cpp @@ -0,0 +1,1006 @@ +// SPDX-FileCopyrightText: 2026 John C. Travers and contributors +// +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "solprop_native/workspace.hpp" + +#include "solprop_native/dense_output.hpp" +#include "solprop_native/refuse.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace solprop_native { + +namespace { + +/** Python's `format(value, f".{precision}g")`, which follows C's `%g`. */ +std::string py_g(const double value, const int precision) { + std::array buffer{}; + std::snprintf(buffer.data(), buffer.size(), "%.*g", precision, value); + return buffer.data(); +} + +/** Set the optional `name` names in `numbers`; refuse a name `known` lacks. */ +template +void numbers_into(const std::map& numbers, const Slots& known, + const char* record) { + for (const auto& [name, value] : numbers) { + const auto found = std::ranges::find_if( + known, [&name](const auto& slot) { return name == slot.first; }); + if (found == known.end()) + refuse(record, " holds an unknown number '", name, "'"); + *found->second = value; + } +} + +} // namespace + +// ----------------------------------------------------------------- the run records + +rk::Policy to_native(const RungeKuttaPolicyRecord& record) { + rk::Policy policy; + auto& landings = policy.landings; + landings.dz_min = record.dz_min; + landings.dz_max = record.dz_max; + landings.stretch = record.stretch; + landings.z_end = record.z_end; + landings.save_planes = record.save_planes; + landings.hard_kinks = record.hard_kinks; + landings.breakpoints = record.breakpoints; + landings.landing_ulps = record.landing_ulps; + landings.interpolate = record.interpolate; + landings.has_quiet_interval = record.quiet_interval.has_value(); + landings.quiet_interval = record.quiet_interval.value_or(0.0); + const auto& controller = record.controller; + if (controller.estimator_order < 0 || controller.lag < 0) + refuse("a Runge-Kutta controller's lag and estimator order are not negative"); + policy.safety = controller.safety; + policy.beta1 = controller.beta1; + policy.beta2 = controller.beta2; + policy.min_factor = controller.min_factor; + policy.max_factor = controller.max_factor; + policy.lag = static_cast(controller.lag); + policy.reject_free = controller.reject_free; + // `_records.rk_policy`: the equivalent norm's power and its reciprocal, as solprop + // forms them from the estimator's order. + const auto power = static_cast(controller.estimator_order + 1); + policy.power = power; + policy.exponent = 1.0 / power; + policy.start_growth = record.start_growth; + policy.auto_init = record.auto_init; + policy.dz_min = record.dz_min; + policy.dz_max = record.dz_max; + if (policy.landings.breakpoints.size() < 2 || !(policy.dz_max >= policy.dz_min)) + refuse("the Runge-Kutta march's landings are invalid"); + return policy; +} + +march::Schedule to_native(const ScheduleRecord& record) { + // `FixedSchedule.edges`: z_start + concatenate(([0.0], cumsum(steps))), the sum + // accumulated in step order. + march::Schedule schedule; + schedule.steps = record.steps; + schedule.edges.reserve(record.steps.size() + 1); + double sum = 0.0; + schedule.edges.push_back(record.z_start + sum); + for (const double step : record.steps) { + sum += step; + schedule.edges.push_back(record.z_start + sum); + } + return schedule; +} + +watch::Resumption to_native(const ResumptionRecord& record) { + watch::Resumption out; + out.record = record.record; + out.collar_quiet = record.collar_quiet; + const std::array*>, 18> known{{ + {"launch_energy", &out.launch_energy}, + {"launch_guard_low", &out.launch_guard_low}, + {"launch_guard_high", &out.launch_guard_high}, + {"launch_collar", &out.launch_collar}, + {"guard_low_max", &out.guard_low_max}, + {"guard_high_max", &out.guard_high_max}, + {"guard_low_at", &out.guard_low_at}, + {"guard_high_at", &out.guard_high_at}, + {"collar_max", &out.collar_max}, + {"raw_removed_fraction", &out.raw_removed_fraction}, + {"removed_signed", &out.removed_signed}, + {"removed_fraction", &out.removed_fraction}, + {"floor_removed_fraction", &out.floor_removed_fraction}, + {"quiet_checks", &out.quiet_checks}, + {"raw_guard_max", &out.raw_guard_max}, + {"steps", &out.steps}, + {"skipped", &out.skipped}, + {"collar_left_out_checks", &out.collar_left_out_checks}, + }}; + numbers_into(record.numbers, known, "a resumed boundary record"); + if (record.unwatched) { + std::vector> stretches; + for (const auto& pair : *record.unwatched) { + if (pair.size() != 2) + refuse("an unwatched stretch is a start and an end"); + stretches.push_back({pair[0], pair[1]}); + } + out.unwatched = std::move(stretches); + } + out.resumed_at = record.resumed_at; + if (record.planes) { + if (record.planes->size() != watch::plane_columns) + refuse("a monitor record's plane rows have five columns"); + out.has_planes = true; + for (std::size_t column = 0; column < watch::plane_columns; ++column) + out.planes[column] = (*record.planes)[column]; + } + return out; +} + +transverse::Resumption to_native(const EdgeResumptionRecord& record) { + transverse::Resumption out; + out.record = record.record; + // `_records.edge_resumption`: a record that is none carries nothing else. + if (!record.record) + return out; + const std::array*>, 15> known{{ + {"launch_energy", &out.launch_energy}, + {"noise_allowance", &out.noise_allowance}, + {"raw_ramp_removed", &out.raw_ramp_removed}, + {"noise_ramp_removed", &out.noise_ramp_removed}, + {"noise_share_in_ramp", &out.noise_share_in_ramp}, + {"declared_share_in_ramp", &out.declared_share_in_ramp}, + {"spatial_removed", &out.spatial_removed}, + {"current", &out.current}, + {"current_baseline", &out.current_baseline}, + {"strip_baseline", &out.strip_baseline}, + {"strip_floor", &out.strip_floor}, + {"strip_max", &out.strip_max}, + {"returned_max", &out.returned_max}, + {"largest_gap", &out.largest_gap}, + {"warned_at", &out.warned_at}, + }}; + numbers_into(record.numbers, known, "a resumed transverse record"); + out.edge_baseline = record.edge_baseline; + out.edge_max = record.edge_max; + out.edge_max_raw = record.edge_max_raw; + out.reads = record.reads.value_or(0); + out.status = record.transverse_status; + return out; +} + +engines::MarchFault fault_from(const std::string& stage, const std::size_t after, + const std::string& category) { + engines::MarchFault fault; + // `trial_source` fails inside the trial's source evaluation, its prediction in the + // state. + fault.in_source = stage == "trial_source"; + if (stage == "startup") + fault.stage = march::Stage::startup; + else if (stage == "trial" || fault.in_source) + fault.stage = march::Stage::trial; + else if (stage == "accept") + fault.stage = march::Stage::accept; + else + throw std::invalid_argument( + "a march fault's stage is startup, trial, trial_source or accept"); + if (category == "convergence") + fault.category = march::Category::convergence; + else if (category == "value") + fault.category = march::Category::value; + else if (category == "backend") + fault.category = march::Category::backend; + else if (category == "sigint") + fault.signal = SIGINT; + else if (category == "sigterm") + fault.signal = SIGTERM; + else + throw std::invalid_argument("a march fault's category is convergence, value, " + "backend, sigint or sigterm"); + fault.after = after; + return fault; +} + +void validate(const stage::Tables& tables) { + using stage::Terms; + const bool expansion = tables.phi == Terms::expansion; + const auto known_terms = [](const Terms terms) { + return terms == Terms::constant || terms == Terms::expansion || + terms == Terms::table; + }; + const bool known = known_terms(tables.phi) && known_terms(tables.prefactor); + if (static_cast(tables.chord) < static_cast(stage::Chord::none) || + static_cast(tables.chord) > static_cast(stage::Chord::table)) + refuse("the stage tables are inconsistent: chord kind ", + static_cast(tables.chord), " is unknown"); + if (!known || tables.n_stages == 0 || !tables.density.present() || + (expansion && (!tables.phi_weights.present() || !tables.phi_rate.present() || + tables.phi_rate.n_values != tables.phi_weights.n_values)) || + (tables.prefactor == Terms::expansion && !tables.prefactor_weights.present()) || + (tables.kerr == stage::KerrDensity::table && !tables.kerr_density.present()) || + tables.plasma_densities.size() != tables.plasma_preionisation.size() || + (tables.chord == stage::Chord::expansion && + (!expansion || tables.chord_terms.size() != tables.phi_weights.n_values)) || + (tables.chord == stage::Chord::table && + (!tables.chord_table.present() || tables.chord_table.n_values != 1)) || + (tables.flow.present() && tables.flow.edges.size() < 2) || + (tables.transform.present() && tables.transform.edges.size() < 2)) + refuse("the stage tables are inconsistent"); + stage::require_scalar_tables(tables); +} + +// ------------------------------------------------------------------------ the run + +Run::Run(Workspace& owner, std::unique_ptr session) + : owner_(&owner), session_(std::move(session)) { + owner.lease(this); + owner.run_ = this; +} + +Run::~Run() { static_cast(close()); } + +bool Run::close() noexcept { + if (owner_ == nullptr) + return true; + if (!session_->close()) + return false; + owner_->release(this); + owner_->run_ = nullptr; + owner_ = nullptr; + return true; +} + +std::optional Run::snapshot(const std::uint64_t sequence, + const std::uint64_t generation) { + std::optional out; + session_->read( + sequence, generation, + [&](const session::Method& method, session::Resident& resident) { + const auto* adams = std::get_if(&method); + if (adams == nullptr || adams->state.history.empty()) + return; + Snapshot snapshot; + snapshot.state = adams->state; + snapshot.field.resize(resident.elements()); + resident.field_to_host(reinterpret_cast(snapshot.field.data())); + if (owner_ == nullptr) + throw session::LifecycleError("the run is closed"); + const auto& general = owner_->leased_state(this); + snapshot.names = general.adams_row_names(); + for (const auto& name : snapshot.names) { + const auto extent = general.adams_row_extents(name); + std::vector> row(extent[0] * extent[1] * extent[2]); + general.adams_rows_to_host(name, row.data(), row.size()); + snapshot.extents.push_back(extent); + snapshot.rows.push_back(std::move(row)); + } + out = std::move(snapshot); + }); + return out; +} + +std::optional>> +Run::march_state(const std::size_t since) { + std::optional>> out; + session_->read(0, 0, + [&](const session::Method& method, session::Resident& /*resident*/) { + const auto* adams = std::get_if(&method); + if (adams == nullptr) + return; + const std::size_t first = std::min(since, adams->orders.size()); + std::vector orders( + adams->orders.begin() + static_cast(first), + adams->orders.end()); + out.emplace(adams->state, std::move(orders)); + }); + return out; +} + +std::vector Run::noise_phase(const std::uint64_t sequence, + const std::uint64_t generation, const double z) { + std::vector values; + session_->read( + sequence, generation, + [&](const session::Method& /*method*/, session::Resident& /*resident*/) { + if (owner_ == nullptr) + throw session::LifecycleError("the run is closed"); + values = owner_->table_phi(this, z); + }); + return values; +} + +// ---------------------------------------------------------------------- the probe + +Probe::Probe(Workspace& owner, std::vector field, std::vector noise, + const double z) + : owner_(&owner), field_(std::move(field)), noise_(std::move(noise)), z_(z), + low_storage_(owner.low_storage_.has_value()) { + owner.load(field_, noise_); + engine_ = owner.trial_engine(); + evaluations_at_load_ = owner.built().rk_source_evaluations(); + owner.lease(this); + owner.probe_ = this; +} + +Probe::~Probe() { close(); } + +std::size_t Probe::evaluations() const { + if (low_storage_) + return trials_ * rk::low_storage::evaluations; + if (owner_ == nullptr) + return 0; + return owner_->built().rk_source_evaluations() - evaluations_at_load_; +} + +double Probe::trial(const double z, const double dz) { + if (owner_ == nullptr) + throw std::logic_error("the probe is closed"); + if (!(dz > 0.0) || !std::isfinite(z)) + refuse("a probe's trial takes a finite position and a positive step"); + const double norm = engine_->trial(z, dz); + ++trials_; + if (!low_storage_) + length_ = dz; + return norm; +} + +std::vector Probe::field() { + if (owner_ == nullptr) + throw std::logic_error("the probe is closed"); + if (low_storage_) + refuse("the low-storage march accepts its step in place and has " + "no trial field to read back"); + if (!length_) + refuse("take a trial before reading its field"); + // The trial lives in the state, which only finishing the step there reads back: the + // loaded state is kept first and loaded again after, so that nothing is committed. + auto& state = owner_->built(); + std::vector kept(owner_->elements()); + state.field_to_host(kept); + state.finish(*length_); + std::vector out(owner_->elements()); + state.field_to_host(out); + state.unbind_monitor(); + state.set_initial(kept, noise_); + state.set_absorber_quiet(false); + state.clear_fsal(); + length_.reset(); + return out; +} + +void Probe::close() noexcept { + if (owner_ == nullptr) + return; + engine_.reset(); + Workspace* owner = owner_; + owner->release(this); + owner->probe_ = nullptr; + owner_ = nullptr; + // The low-storage trial overwrote the registers: nothing is left to run from. + if (low_storage_) + owner->close(); +} + +// ------------------------------------------------------------------ the workspace + +Workspace::Workspace(Problem problem) + : columns_(problem.n_columns()), + elements_(problem.n_columns() * problem.dims.n_omega), + stages_(problem.stepper.n_stages) { + problem.validate(); + const auto setup = std::move(problem.setup); + state_ = std::make_shared(std::move(problem)); + if (setup) + apply(*setup); +} + +Workspace::~Workspace() { close(); } + +void Workspace::apply(const Setup& setup) { + if (setup.z_slots) + configure_z_slots(*setup.z_slots); + for (const auto& table : setup.z_tables) + upload_z_table(table); + if (setup.stage_tables) + set_stage_tables(*setup.stage_tables); + if (setup.flow_guard) + configure_flow_guard(*setup.flow_guard); + if (setup.runge_kutta) + configure_runge_kutta(*setup.runge_kutta); + if (setup.adams) + configure_adams(*setup.adams); + if (setup.low_storage) + configure_low_storage(*setup.low_storage); + set_monitor(setup.monitor); + set_edge(setup.edge); +} + +void Workspace::require_built() const { + if (closed()) + throw std::logic_error("native state is closed"); +} + +void Workspace::require_unleased() const { + if (holder_ != nullptr) + throw std::logic_error("native state is leased by an execution session"); +} + +void Workspace::require_open() const { + require_built(); + require_unleased(); +} + +GeneralState& Workspace::state() { + require_open(); + return *state_; +} + +GeneralState& Workspace::built() const { + require_built(); + return *state_; +} + +GeneralState& Workspace::leased_state(const void* holder) const { + if (holder_ != holder || holder == nullptr) + throw std::logic_error("native state is not leased by this session"); + return built(); +} + +bool Workspace::closed() const noexcept { return !state_ || state_->closed(); } + +void Workspace::lease(const void* holder) { + require_open(); + holder_ = holder; +} + +void Workspace::release(const void* holder) noexcept { + if (holder_ == holder) + holder_ = nullptr; +} + +void Workspace::close() noexcept { + if (run_ != nullptr && !run_->close()) + return; // a session that did not close still uses the state: keep it, leased + if (probe_ != nullptr) + probe_->close(); + if (state_) { + state_->close(); + state_.reset(); + } +} + +void Workspace::set_stage_tables(stage::Tables tables) { + require_open(); + validate(tables); + if (tables.n_stages != stages_) + throw std::invalid_argument("the stage tables name another tableau's stages"); + // A z table's rows are its slots: the tables read the state's one cache. + const bool phi_table = tables.phi == stage::Terms::table; + const bool prefactor_table = tables.prefactor == stage::Terms::table; + if (phi_table != z_slots_.phi || prefactor_table != z_slots_.prefactor) + throw std::invalid_argument("the stage tables and the z table's slots disagree"); + tables.z_slots = nullptr; + tables.z_state = nullptr; + if (phi_table || prefactor_table) { + tables.z_slots = &z_slots_; + tables.z_state = state_.get(); + } + stage_tables_ = std::move(tables); + stage_anchor_ = {}; +} + +void Workspace::configure_z_slots(const ZSlotsConfig& slots) { + require_open(); + z_slots_.configure(slots.phi, slots.prefactor, slots.slots, slots.rate); +} + +void Workspace::upload_z_table(const ZTable& table) { + auto& state = this->state(); + if (table.edges.size() < 2) + refuse("a z table needs at least two breakpoints"); + state.table_upload( + table.kind, table.edges, table.lower, table.upper, + reinterpret_cast*>(table.coefficients.data()), + table.edges.size() - 1, table.n_terms, table.n_values); +} + +void Workspace::configure_flow_guard(FlowGuard guard) { + require_open(); + const std::size_t sections = guard.row_sum.size(); + if (sections == 0 || guard.condition_bound.size() % sections != 0) + throw std::invalid_argument("the flow guard's certificate is one row a section"); + flow_guard_ = std::move(guard); + flow_key_.reset(); +} + +void Workspace::configure_runge_kutta(RungeKuttaConfig config) { + require_open(); + if (config.nodes.size() != stages_) + throw std::invalid_argument("the march's nodes are the tableau's stages"); + runge_kutta_ = std::move(config); +} + +void Workspace::configure_adams(const AdamsConfig& config) { + auto& state = this->state(); + state.adams_allocate(config.slots, config.compensated, config.interpolate); + state.adams_scale(config.rtol, config.atol, config.weights); + adams_ = config; + march_fused_ = config.fused; + march_compensated_ = config.compensated; + march_interpolate_ = config.interpolate; +} + +void Workspace::configure_low_storage(const rk::low_storage::Config config) { + require_open(); + if (config.flows > 2) + throw std::invalid_argument("the low-storage march holds at most two flows"); + low_storage_ = config; +} + +void Workspace::set_monitor(std::optional monitor) { + require_open(); + if (monitor && !monitor->buckets.empty() && monitor->bucket_count == 0) + refuse("a monitor's occupancy buckets need their count"); + monitor_ = std::move(monitor); + occupancy_bound_ = false; +} + +void Workspace::set_edge(std::optional edge) { + require_open(); + edge_ = std::move(edge); +} + +void Workspace::configure_adams_march(march::Policy policy, const bool fused, + const bool compensated, const bool interpolate, + march::Schedule schedule) { + require_open(); + if (!stage_tables_) + throw std::logic_error("the native Adams march needs the stage tables"); + if (!schedule.steps.empty() && schedule.edges.size() != schedule.steps.size() + 1) + throw std::invalid_argument("a replayed schedule has one more edge than steps"); + march_policy_ = std::move(policy); + march_schedule_ = std::move(schedule); + march_fused_ = fused; + march_compensated_ = compensated; + march_interpolate_ = interpolate; +} + +void Workspace::configure_rk_march(rk::Policy policy, std::vector nodes, + const double rtol, const double atol, + march::Schedule schedule) { + require_open(); + if (!stage_tables_) + throw std::logic_error("the native Runge-Kutta march needs the stage tables"); + if (nodes.size() != stages_) + throw std::invalid_argument("the march's nodes are the tableau's stages"); + auto config = runge_kutta_.value_or(RungeKuttaConfig{}); + config.nodes = std::move(nodes); + config.rtol = rtol; + config.atol = atol; + runge_kutta_ = std::move(config); + rk_policy_ = std::move(policy); + rk_schedule_ = std::move(schedule); +} + +void Workspace::set_rk_weights(std::vector weights) { + require_open(); + auto config = runge_kutta_.value_or(RungeKuttaConfig{}); + config.weights = std::move(weights); + runge_kutta_ = std::move(config); +} + +void Workspace::set_dense_weights(std::vector weights) { + require_open(); + auto config = runge_kutta_.value_or(RungeKuttaConfig{}); + config.dense_weights = std::move(weights); + runge_kutta_ = std::move(config); +} + +void Workspace::inject_fault(const engines::MarchFault fault) { + require_open(); + fault_ = fault; +} + +void Workspace::bind_host_source(std::shared_ptr source) { + require_unleased(); + if (!source) { + if (state_) + state_->bind_host_source(nullptr); + return; + } + state().bind_host_source(std::move(source)); +} + +std::vector Workspace::staged_trial(const double z, const double dz, + const bool prepare_only, + const std::vector* given) { + if (!stage_tables_) + throw std::logic_error("a staged Runge-Kutta trial needs the stage tables"); + if (given == nullptr && !runge_kutta_) + throw std::logic_error("a staged Runge-Kutta trial needs the tableau's nodes"); + const auto& nodes = given != nullptr ? *given : runge_kutta_->nodes; + if (nodes.size() != stages_) + throw std::invalid_argument("the trial's nodes are the tableau's stages"); + const auto scalars = + stage::rows(*stage_tables_, stage_anchor_, z, rk::positions(z, dz, nodes)); + if (stage_tables_->flow.present()) + guard_flow(scalars.flow_section, dz, nodes); + auto& general = built(); + if (prepare_only) { + general.prepare_trial(dz, scalars); + return {}; + } + return general.trial_step(dz, scalars); +} + +void Workspace::guard_flow(const std::size_t section, const double dz, + const std::vector& nodes) { + if (!flow_guard_) + throw std::logic_error("a staged trial beside a coupled flow needs its guard"); + if (flow_key_ && flow_key_->first == section && flow_key_->second == dz) + return; + // Forgotten first: a refusal below leaves no set of actions behind a key. + flow_key_.reset(); + const auto& guard = *flow_guard_; + if (section >= guard.row_sum.size()) + throw std::out_of_range("the trial's flow section is past the guard's"); + std::vector fractions(nodes); + fractions.push_back(1.0); + for (const double fraction : fractions) { + if (fraction == 0.0) + continue; + const double largest = fraction * dz * guard.row_sum[section]; + int squarings = 0; + if (largest > guard.taylor_scale) + squarings = static_cast(std::ceil(std::log2(largest / guard.taylor_scale))); + if (squarings > guard.max_squarings) + refuse( + "native cannot take a coupled flow action whose exponent has row-sum norm ", + py_g(largest, 4), ": it would need ", squarings, " squarings, above the ", + guard.max_squarings, " this backend admits. Cap dz_max"); + } + const auto measured = built().form_flow_actions(section, dz, fractions); + const std::size_t width = guard.condition_bound.size() / guard.row_sum.size(); + if (!measured.empty()) { + if (measured.size() != width) + throw std::logic_error("the measured conditioning is one value an active bin"); + const double* declared = guard.condition_bound.data() + section * width; + // NumPy's argmax: the first largest, or the first NaN. + std::size_t worst = 0; + double largest = measured[0] / (declared[0] * guard.allowance); + for (std::size_t bin = 1; bin < width && !std::isnan(largest); ++bin) { + const double excess = measured[bin] / (declared[bin] * guard.allowance); + if (std::isnan(excess) || excess > largest) { + largest = excess; + worst = bin; + } + } + if (largest > 1.0) + refuse( + "native measured a coupled flow conditioning of ", py_g(measured[worst], 12), + " over a step of ", py_g(dz, 4), " m, above the ", py_g(declared[worst], 12), + " the certificate declares at active bin ", worst, " of section ", section, + " -- exceeding it by a factor ", py_g(largest, 12), + " 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"); + } + flow_key_ = std::make_pair(section, dz); +} + +double Workspace::weighted_score(const double* partials, const std::size_t slots, + const double rtol, const double atol) { + if (!runge_kutta_ || runge_kutta_->weights.empty()) + throw std::logic_error("no weighted controller's weights were configured"); + const std::vector values(partials, partials + 3 * slots); + return engines::ResidentRungeKutta::weighted_norm(state(), values, rtol, atol, + runge_kutta_->weights); +} + +MethodKind Workspace::kind() const noexcept { + if (adams_) + return MethodKind::adams; + if (low_storage_) + return MethodKind::low_storage; + return MethodKind::runge_kutta; +} + +std::unique_ptr Workspace::trial_engine() { + auto& general = built(); + if (low_storage_) { + if (!stage_tables_ || !rk_policy_) + throw std::logic_error("the native low-storage replay is not configured"); + return std::make_unique( + general, *stage_tables_, stage_anchor_, *low_storage_, rk_schedule_, + rk_policy_->landings.landing_ulps, fault_); + } + if (!runge_kutta_) + throw std::logic_error("the native Runge-Kutta trial is not configured"); + return std::make_unique( + general, + [this](const double z, const double dz) { return staged_trial(z, dz, false); }, + runge_kutta_->rtol, runge_kutta_->atol, runge_kutta_->weights); +} + +std::unique_ptr Workspace::adams_engine() { + auto& general = built(); + if (!stage_tables_) + throw std::logic_error("the native Adams engine needs the stage tables"); + return std::make_unique( + general, *stage_tables_, stage_anchor_, march_fused_, march_compensated_, + march_interpolate_, fault_); +} + +session::Method Workspace::method(const MethodKind kind, + std::variant start, + const bool dense) { + require_unleased(); + auto& general = state(); + if (kind == MethodKind::adams) { + if (!march_policy_ || !stage_tables_) + throw std::logic_error("the native Adams march is not configured"); + session::AdamsMethod method; + method.policy = *march_policy_; + method.state = std::get(std::move(start)); + method.schedule = march_schedule_; + method.engine = std::make_unique( + general, *stage_tables_, stage_anchor_, march_fused_, march_compensated_, + march_interpolate_, fault_); + if (dense) { + if (!march_interpolate_) + throw std::invalid_argument( + "a session's dense output needs an Adams engine that keeps its steps"); + method.dense = std::make_unique( + general, *stage_tables_, stage_anchor_, march_fused_, march_compensated_); + } + return method; + } + if (!rk_policy_) + throw std::logic_error("the native Runge-Kutta march is not configured"); + session::RungeKuttaMethod method; + method.policy = *rk_policy_; + method.state = std::get(std::move(start)); + method.schedule = rk_schedule_; + if (kind == MethodKind::low_storage) { + // solprop SEP 47 section 6.3: the replay is the Runge-Kutta march's, each step one + // in-place low-storage step whose scalars the state forms itself. + if (!stage_tables_ || !low_storage_) + throw std::logic_error("the native low-storage replay is not configured"); + method.engine = std::make_unique( + general, *stage_tables_, stage_anchor_, *low_storage_, rk_schedule_, + rk_policy_->landings.landing_ulps, fault_); + return method; + } + if (!runge_kutta_) + throw std::logic_error("the native Runge-Kutta march is not configured"); + auto engine = std::make_unique( + general, + [this](const double z, const double dz) { return staged_trial(z, dz, false); }, + runge_kutta_->rtol, runge_kutta_->atol, runge_kutta_->weights); + if (dense) { + if (!stage_tables_) + throw std::logic_error("a session's dense output needs the stage tables"); + auto holder = std::make_unique( + general, *stage_tables_, stage_anchor_, runge_kutta_->dense_weights); + // The engine holds each crossing step's extension through it; both live in the + // method, the engine released first. + auto* held = holder.get(); + engine->set_extension( + [held](const double z, const double dz) { held->hold(z, dz); }); + method.dense = std::move(holder); + } + method.engine = std::move(engine); + return method; +} + +march::Result Workspace::run_adams(march::State& state, const march::Bounds& bounds) { + require_unleased(); + if (!march_policy_ || !stage_tables_) + throw std::logic_error("the native Adams march is not configured"); + engines::ResidentEngine engine(this->state(), *stage_tables_, stage_anchor_, + march_fused_, march_compensated_, march_interpolate_, + fault_); + return march::run(*march_policy_, state, engine, bounds, march_schedule_); +} + +rk::Result Workspace::run_rk(rk::State& state, const march::Bounds& bounds) { + require_unleased(); + if (!rk_policy_) + throw std::logic_error("the native Runge-Kutta march is not configured"); + if (!runge_kutta_) + throw std::logic_error("the native Runge-Kutta trial is not configured"); + engines::ResidentRungeKutta engine( + this->state(), + [this](const double z, const double dz) { return staged_trial(z, dz, false); }, + runge_kutta_->rtol, runge_kutta_->atol, runge_kutta_->weights); + return rk::run(*rk_policy_, state, engine, bounds, rk_schedule_); +} + +void Workspace::load(const std::span field, + const std::span noise) { + auto& state = this->state(); + if (field.size() != elements_) + refuse("a start's field has ", field.size(), " elements, expected ", elements_); + state.unbind_monitor(); + state.set_initial(field, noise); + // A collar an earlier run rested goes back into the stages (SEP 21). + state.set_absorber_quiet(false); + state.clear_fsal(); +} + +void Workspace::bind_run_monitor() { + auto& state = this->state(); + if (!monitor_) + refuse("a run with a boundary monitor needs the problem's monitor weights"); + state.bind_monitor(monitor_->weights, monitor_->column_weights); + // A runner's points share the table: it crosses once. + if (!monitor_->buckets.empty() && !occupancy_bound_) { + state.bind_occupancy(monitor_->buckets, monitor_->bucket_count); + occupancy_bound_ = true; + } + if (edge_) { + state.bind_edge(edge_->faces, edge_->clip, edge_->totals, edge_->synthesis, + edge_->first_row); + if (edge_->lines) + state.bind_edge_lines(*edge_->lines); + } +} + +std::unique_ptr Workspace::start(RunStart start) { + require_open(); + const auto method_kind = kind(); + auto& records = start.records; + const auto schedule = + records.schedule ? to_native(*records.schedule) : march::Schedule{}; + std::variant initial; + if (method_kind == MethodKind::adams) { + auto* policy = std::get_if(&records.policy); + if (policy == nullptr) + refuse("an Adams workspace's run needs the Adams march's policy"); + if (!start.adams) + refuse("an Adams run's start needs the march's state"); + march::validate(*policy); + if (!stage_tables_) + throw std::logic_error("the native Adams march needs the stage tables"); + march_policy_ = *policy; + march_schedule_ = schedule; + initial = std::move(*start.adams); + } else { + auto* policy = std::get_if(&records.policy); + if (policy == nullptr) + refuse("a Runge-Kutta workspace's run needs the Runge-Kutta march's policy"); + if (!start.runge_kutta) + refuse("a Runge-Kutta run's start needs the march's state"); + if (!stage_tables_) + throw std::logic_error("the native Runge-Kutta march needs the stage tables"); + rk_policy_ = to_native(*policy); + rk_schedule_ = schedule; + initial = std::move(*start.runge_kutta); + } + if (!schedule.steps.empty() && schedule.edges.size() != schedule.steps.size() + 1) + throw std::invalid_argument("a replayed schedule has one more edge than steps"); + // A resumed history's rows, every one checked before any is copied, so that a + // refused history leaves the rows as they were. + if (!start.rows.empty()) { + if (method_kind != MethodKind::adams) + refuse("only the Adams march resumes a history's rows"); + const auto names = state().adams_row_names(); + if (names.size() != start.rows.size()) + refuse("a resumed history holds ", start.rows.size(), " rows, and the engine ", + names.size()); + for (const auto& row : start.rows) { + if (std::ranges::find(names, row.name) == names.end()) + refuse("the engine keeps no Adams history row '", row.name, "'"); + const auto extents = state().adams_row_extents(row.name); + if (row.n_slots != extents[0] || row.n_rows != extents[1] || + row.n_omega != extents[2]) + refuse("the Adams history row '", row.name, "' must have shape (", extents[0], + ", ", extents[1], ", ", extents[2], ")"); + } + } + load(start.field, start.noise); + for (const auto& row : start.rows) + state().adams_rows_from_host(row.name, row.values); + session::Plan plan; + const auto& planes = records.planes; + plan.planes = planes.planes; + plan.next_plane = planes.next_plane; + plan.launch_pending = planes.launch_pending; + plan.step_planes = planes.step_planes; + plan.plane_statistics.plan = std::move(start.plane_statistics); + plan.row_statistics.plan = std::move(start.row_statistics); + plan.period = planes.period; + plan.attempt_capacity = planes.attempt_capacity; + plan.row_capacity = planes.row_capacity; + plan.replay = planes.replay_steps > 0; + plan.replay_steps = planes.replay_steps; + plan.replay_length = planes.replay_length; + plan.call_attempts = planes.call_attempts; + plan.call_seconds = planes.call_seconds; + if (records.monitor) { + const auto& monitor = *records.monitor; + watch::validate(monitor.config.policy); + session::MonitorPlan held; + held.config = monitor.config; + held.resume = monitor.continuation.has_value(); + if (monitor.continuation) { + held.record = to_native(monitor.continuation->record); + held.plane = monitor.continuation->plane; + held.unwatched = monitor.continuation->unwatched; + held.edge_record = to_native(monitor.continuation->edge); + } + if (start.floor) { + held.floor = true; + held.floor_energy = (*start.floor)[0]; + std::copy(start.floor->begin() + 1, start.floor->end(), + held.floor_regions.begin()); + } + if (monitor.edge) { + held.edge = *monitor.edge; + held.edge_noise = start.edge_noise; + } + plan.monitor = std::move(held); + bind_run_monitor(); + } + auto method = this->method(method_kind, std::move(initial), planes.dense); + return this->start(std::move(method), std::move(plan), planes.z); +} + +std::unique_ptr Workspace::start(session::Method method, session::Plan plan, + const double z) { + auto& general = state(); + auto session = + std::make_unique(std::make_unique( + general, elements_, elements_ / columns_), + std::move(method), std::move(plan), z); + return std::make_unique(*this, std::move(session)); +} + +std::unique_ptr Workspace::probe(std::vector field, + std::vector noise, const double z) { + require_open(); + return std::make_unique(*this, std::move(field), std::move(noise), z); +} + +std::unique_ptr Workspace::probe(RunStart start) { + require_open(); + if (const auto* policy = std::get_if(&start.records.policy)) { + rk_policy_ = to_native(*policy); + rk_schedule_ = + start.records.schedule ? to_native(*start.records.schedule) : march::Schedule{}; + } + return probe(std::move(start.field), std::move(start.noise), start.records.planes.z); +} + +stage::Trial Workspace::stage_trial(const double z0, const double z1) { + require_open(); + if (!stage_tables_) + throw std::logic_error("no stage tables were uploaded"); + const auto row = stage::row(*stage_tables_, stage_anchor_, z0, z1); + auto step = stage::trial(*stage_tables_, row); + auto sample = stage::sample(*stage_tables_, stage_anchor_, step, z1); + return {.step = std::move(step), .sample = std::move(sample)}; +} + +std::vector Workspace::stage_rate(const double z) const { + require_open(); + if (!stage_tables_) + throw std::logic_error("no stage tables were uploaded"); + return stage::rate(*stage_tables_, z); +} + +std::vector Workspace::table_phi(const void* holder, const double z) { + auto& state = leased_state(holder); + if (!z_slots_.phi) + throw std::logic_error("native state holds no z table of Phi"); + const std::size_t slot = z_slots_.load(state, {z}).front(); + return state.table_terms_to_host(TableKind::phi, slot); +} + +} // namespace solprop_native diff --git a/native/tests/native/test_workspace.cpp b/native/tests/native/test_workspace.cpp new file mode 100644 index 000000000..218192b20 --- /dev/null +++ b/native/tests/native/test_workspace.cpp @@ -0,0 +1,269 @@ +// SPDX-FileCopyrightText: 2026 John C. Travers and contributors +// +// SPDX-License-Identifier: GPL-3.0-or-later + +// The workspace (solprop SEP 52 section 5.3): the lease between it and the session or +// probe that uses it, the coupled flow's guard, the run records' native forms, and the +// timing probe, each moved out of the binding unit and tested here. + +#include "execution.hpp" +#include "solprop_native/workspace.hpp" + +#include + +#include +#include +#include +#include +#include +#include + +namespace { + +namespace native = solprop_native; +using native::Complex; + +// A one-stage envelope of four bins with a constant operator and Kerr response. +native::Problem envelope_problem() { + native::Problem problem; + problem.cpu_execution = native::test::table(); + problem.dims.n_t = 4; + problem.dims.n_to = 4; + problem.dims.n_omega = 4; + problem.dims.family = native::FieldFamily::envelope; + problem.stepper.n_stages = 1; + problem.linear.n_phi_terms = 1; + problem.linear.n_prefactor_terms = 1; + problem.grid.crop_index = {0, 1, 2, 3}; + problem.grid.active_mask.assign(4, 1U); + problem.grid.norm_mask.assign(4, 1U); + problem.grid.omega_window.assign(4, 1.0); + problem.grid.omega = {1.0, 2.0, 3.0, 4.0}; + problem.grid.dt = 0.25; + problem.grid.time_window.assign(4, 1.0); + problem.grid.time_window_derivative.assign(4, 0.0); + problem.grid.carrier.assign(4, Complex(1.0, 0.0)); + problem.linear.phi_terms.assign(4, Complex(0.0, -1.0)); + problem.linear.prefactor_terms.assign(4, Complex(1.0, 0.0)); + problem.stepper.tableau_matrix = {0.0}; + problem.stepper.tableau_nodes = {0.0}; + problem.stepper.solution_weights = {1.0}; + problem.stepper.error_weights = {0.25}; + problem.transform.synthesis = 2.0; + problem.transform.projection = 0.5; + problem.kerr.nonlinear = true; + problem.kerr.coefficient = 0.125; + problem.kerr.self_factor = 0.5; + problem.kerr.conjugate_factor = 0.25; + return problem; +} + +native::stage::Table constant_table(const std::vector& values) { + native::stage::Table table; + table.edges = {-1.0, 2.0}; + table.lower = -1.0; + table.upper = 2.0; + table.coefficients = values; + table.n_terms = 1; + table.n_values = values.size(); + return table; +} + +native::Setup runge_kutta_setup() { + native::Setup setup; + native::stage::Tables tables; + tables.n_stages = 1; + tables.phi = native::stage::Terms::constant; + tables.prefactor = native::stage::Terms::constant; + tables.prefactor_low = -1.0; + tables.prefactor_high = 2.0; + tables.density = constant_table({1.0}); + setup.stage_tables = tables; + setup.runge_kutta = + native::RungeKuttaConfig{.nodes = {0.0}, .rtol = 1e-6, .atol = 1e-12}; + return setup; +} + +native::Problem with_setup(native::Problem problem, native::Setup setup) { + problem.setup = std::make_shared(std::move(setup)); + return problem; +} + +std::vector launch() { + return {Complex(1.0, 0.5), Complex(0.25, -0.5), Complex(-0.75, 0.0), + Complex(0.0, 0.125)}; +} + +} // namespace + +TEST(Workspace, TheLeaseIsExclusiveAndReleasedOnlyByItsHolder) { + native::Workspace workspace(envelope_problem()); + int first = 0; + int second = 0; + workspace.lease(&first); + EXPECT_TRUE(workspace.leased()); + EXPECT_THROW(workspace.lease(&second), std::logic_error); + EXPECT_THROW(static_cast(workspace.state()), std::logic_error); + // The fixed facts stay readable under a lease. + EXPECT_NO_THROW(static_cast(workspace.built())); + EXPECT_NO_THROW(static_cast(workspace.leased_state(&first))); + EXPECT_THROW(static_cast(workspace.leased_state(&second)), std::logic_error); + workspace.release(&second); + EXPECT_TRUE(workspace.leased()); + workspace.release(&first); + EXPECT_FALSE(workspace.leased()); + EXPECT_NO_THROW(static_cast(workspace.state())); +} + +TEST(Workspace, AClosedWorkspaceRefusesEverything) { + native::Workspace workspace(envelope_problem()); + workspace.close(); + EXPECT_TRUE(workspace.closed()); + EXPECT_THROW(static_cast(workspace.built()), std::logic_error); + EXPECT_THROW(workspace.load(launch(), {}), std::logic_error); + workspace.close(); // idempotent +} + +TEST(Workspace, TheSetupIsAppliedWhenTheWorkspaceIsBuilt) { + native::Workspace workspace(with_setup(envelope_problem(), runge_kutta_setup())); + EXPECT_TRUE(workspace.stage_tables().has_value()); + EXPECT_EQ(workspace.kind(), native::MethodKind::runge_kutta); + auto setup = runge_kutta_setup(); + setup.low_storage = native::rk::low_storage::Config{}; + native::Workspace replay(with_setup(envelope_problem(), setup)); + EXPECT_EQ(replay.kind(), native::MethodKind::low_storage); +} + +TEST(Workspace, StageTablesOfAnotherTableauAreRefused) { + auto setup = runge_kutta_setup(); + setup.stage_tables->n_stages = 2; + EXPECT_THROW(native::Workspace(with_setup(envelope_problem(), setup)), + std::invalid_argument); +} + +TEST(Workspace, TheFlowGuardRefusesTooManySquaringsBeforeForming) { + native::Workspace workspace(envelope_problem()); + workspace.configure_flow_guard({.row_sum = {1e6}, + .condition_bound = {1.0}, + .taylor_scale = 0.5, + .max_squarings = 4, + .allowance = 2.0}); + // A node of zero forms nothing; the step's end needs ceil(log2(1e6 / 0.5)) = 21. + try { + workspace.guard_flow(0, 1.0, {0.0}); + FAIL() << "the guard admitted too many squarings"; + } catch (const native::BackendRefusal& error) { + EXPECT_NE(std::string(error.what()).find("21 squarings, above the 4"), + std::string::npos); + } + EXPECT_THROW(workspace.guard_flow(1, 1.0, {0.0}), std::out_of_range); +} + +TEST(Workspace, AFlowGuardsCertificateIsOneRowASection) { + native::Workspace workspace(envelope_problem()); + EXPECT_THROW(workspace.configure_flow_guard({.row_sum = {1.0, 2.0}, + .condition_bound = {1.0, 2.0, 3.0}, + .taylor_scale = 0.5, + .max_squarings = 4, + .allowance = 2.0}), + std::invalid_argument); + EXPECT_THROW(workspace.guard_flow(0, 1.0, {0.0}), std::logic_error); +} + +TEST(Workspace, AScheduleRecordsEdgesAccumulateInStepOrder) { + // 0.1 + 0.2 rounds above 0.3: the edges are the running sum, as NumPy's cumsum. + const auto schedule = native::to_native( + native::ScheduleRecord{.steps = {0.1, 0.2, 0.3}, .z_start = 1.0}); + ASSERT_EQ(schedule.edges.size(), 4U); + double sum = 0.0; + EXPECT_EQ(schedule.edges[0], 1.0); + for (std::size_t index = 0; index < 3; ++index) { + sum += schedule.steps[index]; + EXPECT_EQ(schedule.edges[index + 1], 1.0 + sum); + } +} + +TEST(Workspace, ARungeKuttaPolicyFlattensItsController) { + native::RungeKuttaPolicyRecord record; + record.controller.safety = 0.8; + record.controller.beta1 = 0.12; + record.controller.beta2 = -0.04; + record.controller.lag = 1; + record.controller.estimator_order = 4; + record.dz_min = 1e-6; + record.dz_max = 1e-2; + record.breakpoints = {0.0, 1.0}; + record.quiet_interval = 0.5; + const auto policy = native::to_native(record); + EXPECT_EQ(policy.power, 5.0); + EXPECT_EQ(policy.exponent, 1.0 / 5.0); + EXPECT_EQ(policy.safety, 0.8); + EXPECT_EQ(policy.lag, 1U); + EXPECT_TRUE(policy.landings.has_quiet_interval); + EXPECT_EQ(policy.landings.quiet_interval, 0.5); + record.breakpoints = {0.0}; + EXPECT_THROW(static_cast(native::to_native(record)), std::invalid_argument); +} + +TEST(Workspace, AResumptionReadsItsNumbersByName) { + native::ResumptionRecord record; + record.record = true; + record.numbers = {{"launch_energy", 2.0}, {"steps", 7.0}}; + record.planes = std::vector>(5, std::vector{0.5}); + const auto resumption = native::to_native(record); + EXPECT_EQ(resumption.launch_energy, 2.0); + EXPECT_EQ(resumption.steps, 7.0); + EXPECT_FALSE(resumption.collar_max.has_value()); + EXPECT_TRUE(resumption.has_planes); + record.numbers["nonsense"] = 1.0; + EXPECT_THROW(static_cast(native::to_native(record)), std::invalid_argument); + native::EdgeResumptionRecord edge; + edge.numbers = {{"nonsense", 1.0}}; + // A record that is none carries nothing else, as solprop's resumption writes it. + EXPECT_FALSE(native::to_native(edge).record); +} + +TEST(Workspace, AFaultIsNamedByItsStageAndCategory) { + const auto source = native::fault_from("trial_source", 2, "value"); + EXPECT_TRUE(source.in_source); + EXPECT_EQ(source.stage, native::march::Stage::trial); + EXPECT_EQ(source.category, native::march::Category::value); + EXPECT_EQ(source.after, 2U); + EXPECT_EQ(native::fault_from("accept", 0, "sigterm").signal, SIGTERM); + EXPECT_THROW(static_cast(native::fault_from("finish", 0, "value")), + std::invalid_argument); + EXPECT_THROW(static_cast(native::fault_from("trial", 0, "other")), + std::invalid_argument); +} + +TEST(Workspace, AProbesTrialsRepeatAndItsFieldOwnsAKeptStep) { + native::Workspace workspace(with_setup(envelope_problem(), runge_kutta_setup())); + auto probe = workspace.probe(launch(), {}, 0.0); + // The probe holds the workspace: no load, session or other probe meanwhile. + EXPECT_TRUE(workspace.leased()); + EXPECT_THROW(workspace.load(launch(), {}), std::logic_error); + EXPECT_THROW(static_cast(workspace.probe(launch(), {}, 0.0)), std::logic_error); + EXPECT_THROW(static_cast(probe->field()), native::BackendRefusal); + const double first = probe->trial(0.0, 0.1); + ASSERT_TRUE(std::isfinite(first)); + // The same trial from the same loaded state: the same operations on the same build, + // held to a few roundings of a four-bin norm rather than to its bits (SEP 25). + const double bound = 16.0 * std::numeric_limits::epsilon() * std::abs(first); + EXPECT_NEAR(probe->trial(0.0, 0.1), first, bound); + const auto field = probe->field(); + EXPECT_EQ(field.size(), 4U); + // The loaded state was loaded again after the read-back. + EXPECT_NEAR(probe->trial(0.0, 0.1), first, bound); + EXPECT_EQ(probe->trials(), 3U); + probe->close(); + EXPECT_FALSE(workspace.leased()); + EXPECT_FALSE(workspace.closed()); +} + +TEST(Workspace, ALowStorageProbeNeedsItsReplaysSchedule) { + auto setup = runge_kutta_setup(); + setup.low_storage = native::rk::low_storage::Config{}; + native::Workspace workspace(with_setup(envelope_problem(), setup)); + EXPECT_THROW(static_cast(workspace.probe(launch(), {}, 0.0)), std::logic_error); + EXPECT_FALSE(workspace.leased()); +} diff --git a/native/tests/test_workspace.py b/native/tests/test_workspace.py new file mode 100644 index 000000000..52efcc325 --- /dev/null +++ b/native/tests/test_workspace.py @@ -0,0 +1,658 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""The new native seam (solprop SEP 52 section 5.3): records, workspace, probe. + +The field tables hold each Python record that crosses to its C++ table +(``_core.schemas()``); each record round-trips through the converter, and the +converter refuses a malformed record by its field's path. A ``_core.Workspace`` built +from one ``Problem`` with its set-once data, started from one run record, runs a session +to the same fields as the old seam's session over the same problem; the probe repeats +its trials, reads back an owning copy, refuses the low-storage march's field, and is +refused while a session holds the workspace. The adapter is not yet on this seam: the +records' native forms are assembled here from the old adapter's own parts. +""" + +from __future__ import annotations + +import dataclasses +import math +import types +import typing +from collections.abc import Mapping +from typing import Any, cast + +import numpy as np +import pytest +from conftest import PhaseACase +from session_runs import run +from solprop.backends import engines as protocol +from solprop.backends import records as shared +from solprop.backends.session import Start +from solprop.stepper.controller import PIController +from solprop.stepper.low_storage import LowStorageRungeKutta +from solprop.stepper.multistep import MarchPolicy, Multistep +from solprop.stepper.schedule import FixedSchedule +from solprop.stepper.tableau import continuous_extension + +from solprop_native import _core +from solprop_native._load import load +from solprop_native.backend import ( + NativeBackend, + _chord_tables, # pyright: ignore[reportPrivateUsage] + _lower, # pyright: ignore[reportPrivateUsage] + _LowerPlan, # pyright: ignore[reportPrivateUsage] + _resident_flows, # pyright: ignore[reportPrivateUsage] +) + +_testing: Any = cast(Any, _core)._testing +EPS = float(np.finfo(np.float64).eps) + +# -- the schema test ------------------------------------------------------------------ + +_RECORDS: list[tuple[type, str]] = [ + (shared.RungeKuttaPolicy, "RungeKuttaPolicy"), + (PIController, "PIController"), + (MarchPolicy, "MarchPolicy"), + (shared.LowStorageSettings, "LowStorageSettings"), + (FixedSchedule, "FixedSchedule"), + (shared.PlanePlan, "PlanePlan"), + (shared.MonitorConfig, "MonitorConfig"), + (shared.EdgeConfig, "EdgeConfig"), + (shared.Resumption, "Resumption"), + (shared.EdgeResumption, "EdgeResumption"), + (shared.MonitorContinuation, "MonitorContinuation"), + (shared.MonitorRecords, "MonitorRecords"), + (shared.RunRecords, "RunRecords"), + (protocol.HistoryEntry, "march.Entry"), +] +"""Each Python record that crosses to native, and the C++ table that reads it.""" + +_DTYPES = {"float64": "float64", "complex128": "complex128", "uint64": "uint64"} + + +def _optional(hint: object) -> tuple[bool, object]: + """Return whether `hint` admits None, and what it is without None.""" + if isinstance(hint, types.UnionType) or typing.get_origin(hint) is typing.Union: + arguments = [one for one in typing.get_args(hint) if one is not type(None)] + none = len(arguments) < len(typing.get_args(hint)) + return none, arguments[0] if len(arguments) == 1 else hint + return False, hint + + +def _array_facts(hint: object) -> tuple[set[str], list[str]] | None: + """Return a jaxtyping annotation's dtypes and axis names, or None for another.""" + dtypes = getattr(hint, "dtypes", None) + dims = getattr(hint, "dim_str", None) + if dtypes is None or dims is None: + return None + return set(cast("tuple[str, ...]", dtypes)), str(dims).split() + + +@pytest.mark.parametrize(("record", "name"), _RECORDS, ids=[one[1] for one in _RECORDS]) +def test_each_python_record_is_held_to_its_native_table( + record: type, name: str +) -> None: + """A renamed field, a lost optional, a changed dtype or axis name fails here.""" + table = _core.schemas()[name] + entries = {entry["name"]: entry for entry in table["fields"]} + fields = [one.name for one in dataclasses.fields(record)] + assert [entry["name"] for entry in table["fields"]] == fields + hints = typing.get_type_hints(record) + for field in fields: + entry = entries[field] + none, bare = _optional(hints[field]) + facts = _array_facts(bare) + if entry["kind"] == "array": + assert facts is not None, f"{name}.{field} is an array natively only" + dtypes, axes = facts + assert entry["dtype"] in dtypes, (name, field, entry["dtype"], dtypes) + assert entry["optional"] == none, (name, field) + # Each named axis is the native table's relation, symbol for symbol. + assert len(axes) == len(entry["extents"]), (name, field) + for axis, extent in zip(axes, entry["extents"], strict=True): + if not axis[0].isdigit(): + assert axis == extent, (name, field, axis, extent) + else: + assert facts is None, f"{name}.{field} is an array in Python only" + assert (entry["kind"] == "optional") == none, (name, field, entry) + + +def test_the_schemas_state_the_relations_a_transposed_table_breaks() -> None: + raman = { + entry["name"]: entry for entry in _core.schemas()["Problem.Raman"]["fields"] + } + assert raman["tensor_weights"]["extents"] == ["n_terms", "2"] + table = {entry["name"]: entry for entry in _core.schemas()["stage.Table"]["fields"]} + assert table["coefficients"]["extents"] == ["n_edges-1", "n_terms", "n_values"] + assert _core.schemas()["stage.Table"]["counts"] == { + "n_terms": "n_terms", + "n_values": "n_values", + } + + +# -- the converter ------------------------------------------------------------------- + + +def _same(left: object, right: object) -> None: + """Assert that a written-back record holds what was read, by value.""" + if dataclasses.is_dataclass(left) and not isinstance(left, type): + left = {one.name: getattr(left, one.name) for one in dataclasses.fields(left)} + if isinstance(left, Mapping): + assert isinstance(right, Mapping) + left_map = cast("Mapping[str, object]", left) + right_map = cast("Mapping[str, object]", right) + assert set(left_map) == set(right_map) + for key, value in left_map.items(): + _same(value, right_map[key]) + elif isinstance(left, np.ndarray): + assert isinstance(right, np.ndarray) + assert right.dtype == left.dtype + np.testing.assert_array_equal(right.reshape(left.shape), left) + elif isinstance(left, (list, tuple)): + assert isinstance(right, list) + assert len(right) == len(left) # pyright: ignore[reportUnknownArgumentType] + for one, other in zip(left, right, strict=True): # pyright: ignore[reportUnknownArgumentType] + _same(one, other) + elif isinstance(left, float) and math.isnan(left): + assert isinstance(right, float) + assert math.isnan(right) + else: + assert right == left, (left, right) + + +def test_a_run_s_records_round_trip(phase_a_case: PhaseACase) -> None: + problem, request, _ = phase_a_case + records = shared.run_records(problem, request, Start.entrance(problem)) + back = _testing.round_trip("RunRecords", records) + _same(records, back) + + +@pytest.mark.parametrize( + ("name", "value"), + [ + ("LowStorageSettings", shared.LowStorageSettings(2, True, 0.25)), + ("FixedSchedule", FixedSchedule(np.array([0.1, 0.2, 0.3]), 0.5)), + ( + "Resumption", + shared.Resumption( + record=True, + collar_quiet=True, + numbers={"launch_energy": 2.0, "steps": 3.0}, + unwatched=((0.0, 0.1),), + resumed_at=(0.1,), + planes=((0.1,), (0.2,), (0.3,), (0.4,), (0.5,)), + ), + ), + ( + "EdgeResumption", + shared.EdgeResumption( + record=True, + numbers={"current": 1.5}, + edge_baseline=(1.0, 2.0), + reads=4, + transverse_status="clear", + ), + ), + ( + "stage.Table", + { + "edges": np.array([0.0, 0.5, 1.0]), + "lower": 0.0, + "upper": 1.0, + "coefficients": np.arange(12.0).reshape(2, 3, 2), + }, + ), + ( + "ZTable", + { + "kind": "phi", + "edges": np.array([0.0, 1.0]), + "lower": 0.0, + "upper": 1.0, + "coefficients": np.ones((1, 2, 3), dtype=np.complex128), + }, + ), + ], + ids=lambda value: value if isinstance(value, str) else "", +) +def test_records_round_trip(name: str, value: object) -> None: + _same(value, _testing.round_trip(name, value)) + + +def _table(n_edges: int = 3) -> dict[str, object]: + return { + "edges": np.linspace(0.0, 1.0, n_edges), + "lower": 0.0, + "upper": 1.0, + "coefficients": np.zeros((n_edges - 1, 2, 1)), + } + + +@pytest.mark.parametrize( + ("spoil", "error", "message"), + [ + (lambda t: t.pop("lower"), ValueError, r"stage\.Table\.lower is missing"), + (lambda t: t.update(extra=1), ValueError, "unknown field 'extra'"), + ( + lambda t: t.update(coefficients=np.zeros((2, 2, 1), dtype=np.float32)), + TypeError, + r"coefficients must be a C-contiguous float64 array of rank 3", + ), + ( + lambda t: t.update(coefficients=np.zeros((2, 2))), + ValueError, + "of rank 3", + ), + # The right element count with its axes swapped breaks the relation. + ( + lambda t: t.update(coefficients=np.zeros((1, 2, 2))), + ValueError, + r"axis 0 gives n_edges = 2, where the record has 3", + ), + ( + lambda t: t.update(coefficients=np.zeros((2, 4, 1))[:, ::2]), + ValueError, + "not a strided or overlapping view", + ), + ( + lambda t: t.update(coefficients=np.broadcast_to(np.zeros(1), (2, 2, 1))), + ValueError, + "not a strided or overlapping view", + ), + (lambda t: t.update(lower="0"), TypeError, r"stage\.Table\.lower must be a"), + ], +) +def test_the_converter_refuses_a_malformed_record_by_its_path( + spoil: Any, error: type[Exception], message: str +) -> None: + table = _table() + spoil(table) + with pytest.raises(error, match=message): + _testing.round_trip("stage.Table", table) + + +def test_the_converter_admits_read_only_arrays_and_copies_them() -> None: + table = _table() + coefficients = cast(np.ndarray, table["coefficients"]) + coefficients.setflags(write=False) + back = _testing.round_trip("stage.Table", table) + assert back["coefficients"].flags.owndata or back["coefficients"].base is not None + assert not np.shares_memory(back["coefficients"], coefficients) + + +def test_a_variant_is_told_apart_by_its_fields(phase_a_case: PhaseACase) -> None: + problem, request, _ = phase_a_case + records = shared.run_records(problem, request, Start.entrance(problem)) + stranger = { + "policy": {"order": 1}, + **{ + k: getattr(records, k) + for k in ("low_storage", "schedule", "planes", "monitor") + }, + } + with pytest.raises( + TypeError, match="matches none of MarchPolicy or RungeKuttaPolicy" + ): + _testing.round_trip("RunRecords", stranger) + + +# -- the workspace: the old adapter's parts in the new seam's records ------------------ + +_TERMS = {1: "constant", 2: "expansion", 3: "table"} +_KERR = {0: "none", 1: "density", 2: "table"} +_CHORD = {0: "none", 1: "constant", 2: "expansion", 3: "table"} +_PLANNING = {"mode": "legacy"} +_WATCH = { + "has_last": False, + "last_z": 0.0, + "since": 0, + "busy": False, + "quiet_run": 0, + "quiet": False, + "warned": False, + "cap": math.inf, +} +_OBSERVATION, _TERMINAL = 0, 3 + + +def _stage_table(packed: object) -> dict[str, object] | None: + if packed is None: + return None + edges, lower, upper, coefficients = cast("tuple[Any, Any, Any, Any]", packed) + return { + "edges": np.ascontiguousarray(edges, dtype=np.float64), + "lower": float(lower), + "upper": float(upper), + "coefficients": np.ascontiguousarray(coefficients, dtype=np.float64), + } + + +def _stage_tables(old: Mapping[str, Any]) -> dict[str, object]: + """Return the old adapter's stage tables in the new seam's record.""" + return { + "n_stages": old["n_stages"], + "phi": _TERMS[old["phi"]], + "phi_weights": _stage_table(old["phi_weights"]), + "phi_rate": _stage_table(old["phi_rate"]), + "prefactor": _TERMS[old["prefactor"]], + "prefactor_weights": _stage_table(old["prefactor_weights"]), + "prefactor_low": old["prefactor_low"], + "prefactor_high": old["prefactor_high"], + "density": _stage_table(old["density"]), + "taper": _stage_table(old["taper"]), + "raman_rates": [_stage_table(one) for one in old["raman_rates"]], + "kerr": _KERR[old["kerr"]], + "kerr_density": _stage_table(old["kerr_density"]), + "plasma_densities": [_stage_table(one) for one in old["plasma_densities"]], + "plasma_preionisation": [ + _stage_table(one) for one in old["plasma_preionisation"] + ], + "raman_densities": [_stage_table(one) for one in old["raman_densities"]], + "dispersive_densities": [ + _stage_table(one) for one in old["dispersive_densities"] + ], + "chord": _CHORD[old["chord"]], + "chord_rate": old["chord_rate"], + "chord_terms": list(old["chord_terms"]), + "chord_table": _stage_table(old.get("chord_table")), + "flow": { + "edges": list(old["flow_edges"]), + "degrees": old["flow_degrees"], + "slack": old["flow_slack"], + }, + "flow_residual": old["flow_residual"], + "transform": { + "edges": list(old["transform_edges"]), + "degrees": old["transform_degrees"], + "slack": old["transform_slack"], + }, + } + + +def _workspace(backend: Any, problem: Any, request: Any) -> _core.Workspace: + """Build the new seam's workspace from the parts the old adapter formed.""" + assert backend._flow is None + assert backend._z_tables is None + native = _lower( + problem, + request, + _LowerPlan( + terms=backend._terms, + node_chunk=backend._node_chunk, + general_chunk=backend._general_chunk, + cpu_execution=backend._applied_execution, + fft_planning=_PLANNING, + ), + ) + stepper = request.stepper + integrator = stepper.integrator + controller = stepper.controller + adams = isinstance(integrator, Multistep) + carrier = backend._resident.carrier if adams else None + held: Any = native + held.stage_tables = _stage_tables(backend._stage_tables() | _chord_tables(carrier)) + dense = ( + continuous_extension(stepper.tableau) + if stepper.interpolate_planes and not adams + else None + ) + weights = ( + np.empty(0) if controller.weights is None else np.asarray(controller.weights) + ) + held.runge_kutta = { + "nodes": np.asarray(stepper.tableau.nodes, dtype=np.float64), + "rtol": float(controller.rtol), + "atol": float(controller.atol), + "weights": weights, + "dense_weights": np.empty(0) if dense is None else np.asarray(dense, float), + } + if adams: + resident = backend._resident + held.adams = { + "slots": resident.n_slots, + "compensated": resident.compensated, + "interpolate": resident.interpolate, + "fused": backend._adams._fused, + "rtol": float(controller.rtol), + "atol": float(controller.atol), + "weights": weights, + } + if isinstance(integrator, LowStorageRungeKutta): + settings = shared.low_storage_settings(problem, stepper) + assert settings is not None + held.low_storage = dataclasses.replace( + settings, + flows=_resident_flows(settings.flows, stepper, device=False), + ) + return _core.Workspace(native) + + +def _run_start(backend: Any, problem: Any, request: Any) -> dict[str, object]: + """Return one run's start in the new seam's record, at the entrance.""" + start = Start.entrance(problem) + records = shared.run_records(problem, request, start) + loaded = load( + problem, + request.stepper, + np.asarray(start.take_field()), + start.noise, + z=float(start.z), + resume=start.resume, + ) + proposal = float(request.stepper.dz_init) + adams = runge_kutta = None + if isinstance(request.stepper.integrator, Multistep): + state = backend._adams.start_state(loaded.z, proposal, loaded.cursor) + adams = {**state, "watch": _WATCH} + else: + runge_kutta = { + "z": float(loaded.z), + "proposal": proposal, + "norms": [], + "watch": _WATCH, + "cursor": int(loaded.cursor), + } + return { + "records": records, + "field": np.ascontiguousarray(loaded.field.reshape(-1)), + "noise": np.ascontiguousarray(loaded.native_noise()), + "adams": adams, + "runge_kutta": runge_kutta, + "rows": [], + "plane_statistics": None, + "row_statistics": None, + "floor": None, + "edge_noise": None, + } + + +def _drive(session: Any, elements: int) -> tuple[list[tuple[float, np.ndarray]], Any]: + """Advance a native session to its end, exporting each observed state.""" + fields: list[tuple[float, np.ndarray]] = [] + recipe = {"power": False, "optics": False, "weight": None} + while True: + batch = session.advance(4096, 3600.0) + event = batch.event + if event.kind == _OBSERVATION and event.ticket: + out = np.empty(elements, dtype=np.complex128) + session.export((batch.sequence, event.generation), recipe, out) + fields.append((float(event.z), out)) + session.acknowledge(batch.sequence) + if event.kind == _TERMINAL: + return fields, event + + +def _case(phase_a_case: PhaseACase, march: str) -> tuple[Any, Any, Any]: + problem, request, grid = phase_a_case + stepper = request.stepper + if march == "adams": + stepper = dataclasses.replace(stepper, integrator=Multistep()) + elif march == "low_storage": + target = float(stepper.save_planes[-1]) + stepper = dataclasses.replace( + stepper, + integrator=LowStorageRungeKutta(), + schedule=FixedSchedule.uniform(0.0, target, target / 4), + ) + return problem, request.with_stepper(stepper), grid + + +@pytest.mark.parametrize("march", ["runge_kutta", "adams", "low_storage"]) +def test_a_workspace_runs_a_session_as_the_old_seam_does( + phase_a_case: PhaseACase, march: str +) -> None: + problem, request, grid = _case(phase_a_case, march) + backend = NativeBackend(problem, request, grid=grid, fft_planning=_PLANNING) + try: + old = run(backend, problem, request) + workspace = _workspace(backend, problem, request) + start = _run_start(backend, problem, request) + finally: + backend.close() + try: + session = workspace.start(start) + fields, terminal = _drive(session, int(np.prod(problem.shape))) + session.close() + assert terminal.outcome == 1 # completed + old_planes = old.all_planes() + assert [z for z, _ in fields] == [plane.z for plane in old_planes] + # The same operations on the same build, over the same tables: the matched + # computation, compared bitwise here as a single-build diagnostic (SEP 25). + for (_, field), plane in zip(fields, old_planes, strict=True): + np.testing.assert_array_equal(field, plane.field.reshape(-1)) + finally: + workspace.close() + + +def test_a_workspace_is_reused_across_starts_and_its_arrays_outlive_it( + phase_a_case: PhaseACase, +) -> None: + problem, request, grid = phase_a_case + backend = NativeBackend(problem, request, grid=grid, fft_planning=_PLANNING) + try: + workspace = _workspace(backend, problem, request) + first_start = _run_start(backend, problem, request) + second_start = _run_start(backend, problem, request) + finally: + backend.close() + n = int(np.prod(problem.shape)) + session = workspace.start(first_start) + # The launch's batch, taken by hand: its arrays are kept past everything below. + batch = session.advance(1, 3600.0) + attempts = batch.attempts + kept = np.array(attempts, copy=True) + out = np.empty(n, dtype=np.complex128) + recipe = {"power": False, "optics": False, "weight": None} + session.export((batch.sequence, batch.event.generation), recipe, out) + session.acknowledge(batch.sequence) + # A second start is refused while the session holds the workspace. + with pytest.raises(RuntimeError, match="leased"): + workspace.start(second_start) + with pytest.raises(RuntimeError, match="leased"): + workspace.probe(second_start) + first, _ = _drive(session, n) + first.insert(0, (float(batch.event.z), out)) + session.close() + again = workspace.start(second_start) + second, _ = _drive(again, n) + again.close() + assert len(first) == len(second) + for (_, one), (_, other) in zip(first, second, strict=True): + np.testing.assert_array_equal(one, other) + workspace.close() + assert workspace.closed + # A batch's arrays own their storage: valid after acknowledgment, reuse and close. + np.testing.assert_array_equal(attempts, kept) + with pytest.raises(RuntimeError): + workspace.start(second_start) + with pytest.raises(_core.SessionLifecycleError): + again.advance(1, 1.0) + + +def test_diagnostics_hold_what_the_metadata_reads(phase_a_case: PhaseACase) -> None: + problem, request, grid = phase_a_case + backend = NativeBackend(problem, request, grid=grid, fft_planning=_PLANNING) + try: + workspace = _workspace(backend, problem, request) + ledger = backend.memory_ledger() + finally: + backend.close() + try: + diagnostics = workspace.diagnostics() + assert diagnostics["method"] == "runge_kutta" + assert set(diagnostics["memory_ledger"]) >= {"state"} + assert diagnostics["memory_ledger"]["state"] == ledger["state"] + assert set(diagnostics["crossed_bytes"]) is not None + for key in ("cpu_execution", "fft_planning", "execution_sizing"): + assert diagnostics[key] + finally: + workspace.close() + + +# -- the probe ------------------------------------------------------------------------ + + +def test_the_probe_repeats_its_trials_and_reads_back_an_owning_copy( + phase_a_case: PhaseACase, +) -> None: + problem, request, grid = phase_a_case + dz = float(request.stepper.dz_init) + backend = NativeBackend(problem, request, grid=grid, fft_planning=_PLANNING) + try: + old = backend.timing_probe(Start.entrance(problem)) + old.trial(0.0, dz) + old_field = old.field() + workspace = _workspace(backend, problem, request) + start = _run_start(backend, problem, request) + finally: + backend.close() + try: + probe = workspace.probe(start) + first = probe.trial(0.0, dz) + # The same trial from the same loaded state, held to a few roundings of the + # norm (SEP 25), which on one build is its bits. + assert probe.trial(0.0, dz) == pytest.approx(first, rel=64 * EPS) + field = probe.field() + assert field.flags.owndata or field.base is not None + # The same trial and finish as the old probe's, on the same build. + np.testing.assert_array_equal(field.reshape(problem.shape), old_field) + field[...] = 0.0 # an owning copy: nothing native reads it + assert probe.trial(0.0, dz) == pytest.approx(first, rel=64 * EPS) + assert probe.trials == 3 + # Refused while the probe holds the workspace. + with pytest.raises(RuntimeError, match="leased"): + workspace.start(start) + probe.close() + assert probe.closed + assert not workspace.closed + session = workspace.start(start) + with pytest.raises(RuntimeError, match="leased"): + workspace.probe(start) + session.close() + finally: + workspace.close() + + +def test_the_low_storage_probe_steps_in_place_and_closes_its_workspace( + phase_a_case: PhaseACase, +) -> None: + problem, request, grid = _case(phase_a_case, "low_storage") + backend = NativeBackend(problem, request, grid=grid, fft_planning=_PLANNING) + try: + workspace = _workspace(backend, problem, request) + start = _run_start(backend, problem, request) + finally: + backend.close() + schedule = request.stepper.schedule + assert schedule is not None + probe = workspace.probe(start) + assert probe.low_storage + assert probe.trial(0.0, float(schedule.steps[0])) == 0.0 + # Four evaluations a step: the timing a probe of this march measures. + assert probe.evaluations == LowStorageRungeKutta().evaluations + with pytest.raises(_core.BackendRefusal, match="no trial field to read back"): + probe.field() + probe.close() + assert workspace.closed From 35dfa32e1627eaa27d3b24e801c96a9149030e32 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 02:27:27 +0000 Subject: [PATCH 02/29] refactor(native): read the march and watch records by their tables march_policy_from, watch_policy_from, watch_state_from, watch_config_from and stage_table_from now read through the field-table converter, so the old seam and the new one refuse a malformed record alike; the workspace's native test builds a complete envelope problem. Co-Authored-By: Claude Opus 5.5 --- native/src/bindings.cpp | 125 ++----------------------- native/tests/native/test_workspace.cpp | 2 + 2 files changed, 9 insertions(+), 118 deletions(-) diff --git a/native/src/bindings.cpp b/native/src/bindings.cpp index af5782b89..b30c3d92a 100644 --- a/native/src/bindings.cpp +++ b/native/src/bindings.cpp @@ -722,32 +722,8 @@ native::TrialScalars adams_scalars(const RealInput phi_delta, const RealInput ph // packs it: (edges, lower, upper, coefficients) with the coefficients // (n_intervals, n_terms, n_values); `None` for an absent table (solprop SEP 39). native::stage::Table stage_table_from(const nb::handle value) { - native::stage::Table table; - if (value.is_none()) - return table; - using Coefficients = - nb::ndarray, nb::c_contig, nb::device::cpu>; - try { - const auto parts = nb::cast(value); - if (parts.size() != 4) - throw std::invalid_argument( - "a stage table is (edges, lower, upper, coefficients)"); - table.edges = real_vector(exact_array(parts[0])); - table.lower = nb::cast(parts[1]); - table.upper = nb::cast(parts[2]); - const auto coefficients = exact_array(parts[3]); - if (table.edges.size() < 2 || coefficients.shape(0) + 1 != table.edges.size() || - coefficients.shape(1) < 1 || coefficients.shape(2) < 1) - throw std::invalid_argument( - "a stage table's coefficients do not match its breakpoints"); - table.n_terms = coefficients.shape(1); - table.n_values = coefficients.shape(2); - table.coefficients.assign(coefficients.data(), - coefficients.data() + coefficients.size()); - } catch (const nb::cast_error&) { - throw std::invalid_argument("a stage table has the wrong types"); - } - return table; + // A tuple `(edges, lower, upper, coefficients)` read by the table's field order. + return native::records::read(value, "stage table"); } std::vector stage_table_list(const nb::handle values) { @@ -977,43 +953,7 @@ void initialize_kokkos(const int threads, const int kernels, const int fft, namespace march = native::march; march::Policy march_policy_from(const nb::dict values) { - march::Policy policy; - try { - policy.order = nb::cast(values["order"]); - policy.variable_order = nb::cast(values["variable_order"]); - policy.safety = nb::cast(values["safety"]); - policy.max_growth = nb::cast(values["max_growth"]); - policy.min_factor = nb::cast(values["min_factor"]); - policy.rejection_growth = nb::cast(values["rejection_growth"]); - policy.hysteresis = nb::cast(values["hysteresis"]); - policy.restart_after = nb::cast(values["restart_after"]); - policy.collar_stability = nb::cast(values["collar_stability"]); - policy.real_intervals = nb::cast>(values["real_intervals"]); - policy.collar_rate = nb::cast(values["collar_rate"]); - policy.carrier = nb::cast(values["carrier"]); - policy.carrier_cap = nb::cast(values["carrier_cap"]); - policy.has_budget = !values["max_calls"].is_none(); - policy.max_calls = - policy.has_budget ? nb::cast(values["max_calls"]) : 0; - policy.equal_approach = nb::cast(values["equal_approach"]); - policy.interval_cap = nb::cast(values["interval_cap"]); - policy.dz_min = nb::cast(values["dz_min"]); - policy.dz_max = nb::cast(values["dz_max"]); - policy.stretch = nb::cast(values["stretch"]); - policy.z_end = nb::cast(values["z_end"]); - policy.save_planes = nb::cast>(values["save_planes"]); - policy.hard_kinks = nb::cast>(values["hard_kinks"]); - policy.breakpoints = nb::cast>(values["breakpoints"]); - policy.landing_ulps = nb::cast(values["landing_ulps"]); - policy.interpolate = nb::cast(values["interpolate"]); - policy.has_quiet_interval = !values["quiet_interval"].is_none(); - policy.quiet_interval = - policy.has_quiet_interval ? nb::cast(values["quiet_interval"]) : 0.0; - } catch (const nb::cast_error&) { - throw std::invalid_argument("the Adams march's policy has the wrong types"); - } catch (const nb::python_error&) { - throw std::invalid_argument("the Adams march's policy lacks a field"); - } + auto policy = native::records::read(values, "policy"); march::validate(policy); return policy; } @@ -1021,52 +961,13 @@ march::Policy march_policy_from(const nb::dict values) { // solprop SEP 45 phase 1: the boundary watch's policy and state, from and to solprop's // `BoundaryMonitor.watch_policy` and `.watch_state`. native::watch::Policy watch_policy_from(const nb::dict values) { - native::watch::Policy policy; - try { - policy.split = nb::cast(values["split"]); - policy.crossing = nb::cast(values["crossing"]); - const auto regions = nb::cast>(values["floor_regions"]); - if (regions.size() != 4) - throw std::invalid_argument("the boundary watch's floor regions are four"); - for (std::size_t index = 0; index < 4; ++index) - policy.floor_regions[index] = regions[index]; - policy.launch_floor = nb::cast(values["launch_floor"]); - policy.activity = nb::cast(values["activity"]); - policy.warn = nb::cast(values["warn"]); - policy.stop = nb::cast(values["stop"]); - policy.quiet_share = nb::cast(values["quiet_share"]); - policy.quiet_checks = nb::cast(values["quiet_checks"]); - policy.quiet_collar = nb::cast(values["quiet_collar"]); - policy.cadence = nb::cast(values["cadence"]); - policy.interval = nb::cast(values["interval"]); - policy.share = nb::cast(values["share"]); - policy.bucket_limits = nb::cast>(values["bucket_limits"]); - } catch (const nb::cast_error&) { - throw std::invalid_argument("the boundary watch's policy has the wrong types"); - } catch (const nb::python_error&) { - throw std::invalid_argument("the boundary watch's policy lacks a field"); - } + auto policy = native::records::read(values, "policy"); native::watch::validate(policy); return policy; } native::watch::State watch_state_from(const nb::dict values) { - native::watch::State state; - try { - state.has_last = nb::cast(values["has_last"]); - state.last_z = nb::cast(values["last_z"]); - state.since = nb::cast(values["since"]); - state.busy = nb::cast(values["busy"]); - state.quiet_run = nb::cast(values["quiet_run"]); - state.quiet = nb::cast(values["quiet"]); - state.warned = nb::cast(values["warned"]); - state.cap = nb::cast(values["cap"]); - } catch (const nb::cast_error&) { - throw std::invalid_argument("the boundary watch's state has the wrong types"); - } catch (const nb::python_error&) { - throw std::invalid_argument("the boundary watch's state lacks a field"); - } - return state; + return native::records::read(values, "watch"); } nb::dict watch_state_to(const native::watch::State& state) { @@ -1085,20 +986,8 @@ nb::dict watch_state_to(const native::watch::State& state) { // solprop SEP 47 section 6.4: the owning boundary monitor's configuration, the record // a resume continues and the record it keeps, from and to solprop's dictionaries. native::watch::Config watch_config_from(const nb::dict values) { - native::watch::Config config; - config.policy = watch_policy_from(nb::cast(values["policy"])); - try { - config.floor_share = nb::cast(values["floor_share"]); - config.floor_margin = nb::cast(values["floor_margin"]); - config.budget = nb::cast(values["budget"]); - config.rate = real_vector(exact_array(values["rate"])); - config.can_rest = nb::cast(values["can_rest"]); - } catch (const nb::cast_error&) { - throw std::invalid_argument("the boundary monitor's configuration has the wrong " - "types"); - } catch (const nb::python_error&) { - throw std::invalid_argument("the boundary monitor's configuration lacks a field"); - } + auto config = native::records::read(values, "config"); + native::watch::validate(config.policy); return config; } diff --git a/native/tests/native/test_workspace.cpp b/native/tests/native/test_workspace.cpp index 218192b20..79808ad4d 100644 --- a/native/tests/native/test_workspace.cpp +++ b/native/tests/native/test_workspace.cpp @@ -51,6 +51,8 @@ native::Problem envelope_problem() { problem.stepper.error_weights = {0.25}; problem.transform.synthesis = 2.0; problem.transform.projection = 0.5; + problem.transform.synthesis_matrix = {2.0}; + problem.transform.projection_matrix = {0.5}; problem.kerr.nonlinear = true; problem.kerr.coefficient = 0.125; problem.kerr.self_factor = 0.5; From 218aabb4f71de752071257209e7ea74d081783af Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 02:28:25 +0000 Subject: [PATCH 03/29] test(native): the engines and the fault hook over a workspace (SEP 52) Co-Authored-By: Claude Opus 5.5 --- native/tests/test_workspace.py | 64 ++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/native/tests/test_workspace.py b/native/tests/test_workspace.py index 52efcc325..a8ee58833 100644 --- a/native/tests/test_workspace.py +++ b/native/tests/test_workspace.py @@ -656,3 +656,67 @@ def test_the_low_storage_probe_steps_in_place_and_closes_its_workspace( probe.field() probe.close() assert workspace.closed + + +# -- the engines and the test hooks --------------------------------------------------- + + +def test_the_engines_take_the_probe_s_trial_through_solprop_s_protocol( + phase_a_case: PhaseACase, +) -> None: + problem, request, grid = phase_a_case + dz = float(request.stepper.dz_init) + backend = NativeBackend(problem, request, grid=grid, fft_planning=_PLANNING) + try: + workspace = _workspace(backend, problem, request) + start = _run_start(backend, problem, request) + finally: + backend.close() + try: + probe = workspace.probe(start) + expected = probe.trial(0.0, dz) + probe.close() + engines = _testing.engines(workspace) + # The engines hold the workspace as a session does. + with pytest.raises(RuntimeError, match="leased"): + workspace.start(start) + loaded = engines.field() + assert loaded.shape == (1, problem.shape[-1]) + assert engines.rk_trial(0.0, dz) == pytest.approx(expected, rel=64 * EPS) + assert not engines.rk_in_flight + stage = engines.stage(0) + assert stage.shape == loaded.shape + record = engines.rk_accept(dz) + assert isinstance(record, protocol.AcceptRecord) + assert math.isnan(record.stiffness) + # The committed state moved; its reading is the protocol's record. + assert not np.array_equal(engines.field(), loaded) + with pytest.raises(RuntimeError, match="no boundary readings|monitor"): + engines.rk_reading() + engines.close() + session = workspace.start(start) + session.close() + finally: + workspace.close() + + +def test_an_injected_fault_fails_the_run_at_its_stage(phase_a_case: PhaseACase) -> None: + problem, request, grid = _case(phase_a_case, "low_storage") + backend = NativeBackend(problem, request, grid=grid, fft_planning=_PLANNING) + try: + workspace = _workspace(backend, problem, request) + start = _run_start(backend, problem, request) + finally: + backend.close() + try: + with pytest.raises(ValueError, match="a march fault's stage"): + _testing.inject_fault(workspace, "finish", 0, "value") + # The second step's trial fails, after the first committed. + _testing.inject_fault(workspace, "trial", 1, "value") + session = workspace.start(start) + _, terminal = _drive(session, int(np.prod(problem.shape))) + session.close() + assert terminal.outcome == 3 # failed + assert "injected" in terminal.message + finally: + workspace.close() From e81c220ad531505d6a1637e38b43b79d6922c93c Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 02:28:37 +0000 Subject: [PATCH 04/29] test(native): a raw pattern for the reading's refusal Co-Authored-By: Claude Opus 5.5 --- native/tests/test_workspace.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/native/tests/test_workspace.py b/native/tests/test_workspace.py index a8ee58833..605dc678a 100644 --- a/native/tests/test_workspace.py +++ b/native/tests/test_workspace.py @@ -691,7 +691,7 @@ def test_the_engines_take_the_probe_s_trial_through_solprop_s_protocol( assert math.isnan(record.stiffness) # The committed state moved; its reading is the protocol's record. assert not np.array_equal(engines.field(), loaded) - with pytest.raises(RuntimeError, match="no boundary readings|monitor"): + with pytest.raises(RuntimeError, match=r"no boundary readings|monitor"): engines.rk_reading() engines.close() session = workspace.start(start) From 6b4716d6a915fa565912bc08a45df2bad9c04932 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 03:19:16 +0000 Subject: [PATCH 05/29] refactor(native): the adapter on Workspace, start(run) and probe(start); the State seam deleted (SEP 52) NativeBackend builds one Problem with its set-once data and one Workspace for its life; a session starts it from one run record (RunStart: the run records, field, noise, march state, history rows, statistics plans, monitor weights and edge tables), and the timing probe is Workspace.probe. The State class, its configure, upload, bind and metadata names, start_session, the per-step probe paths (_trial_step, _ResidentLowStorage, _ZTables' evaluation), _ResidentAdams, _records and the old dict converters go; the _testing entry points take a workspace. Tests not yet ported. Co-Authored-By: Claude Opus 5.5 --- native/include/solprop_native/workspace.hpp | 103 +- native/src/bindings.cpp | 1715 +++++------------ native/src/general/trial.cpp | 5 +- native/src/solprop_native/__init__.py | 46 +- native/src/solprop_native/_probe.py | 87 +- native/src/solprop_native/_records.py | 199 -- native/src/solprop_native/backend.py | 1636 ++++++---------- native/src/solprop_native/session.py | 310 ++- native/src/workspace.cpp | 170 +- native/tests/session_runs.py | 42 +- native/tests/test_api_contract.py | 2 +- native/tests/test_backend.py | 6 +- native/tests/test_band_column_budget.py | 2 +- native/tests/test_band_pathological.py | 2 +- native/tests/test_band_plasma.py | 4 +- native/tests/test_band_stress.py | 2 +- native/tests/test_dispersive.py | 4 +- native/tests/test_envelope_plasma.py | 2 +- native/tests/test_envelope_subnormal.py | 2 +- native/tests/test_mixtures.py | 2 +- native/tests/test_radial.py | 4 +- tests/backends/test_native_error_norm.py | 2 +- tests/backends/test_native_far_field.py | 2 +- tests/backends/test_native_gpu.py | 2 +- tests/backends/test_native_low_storage.py | 2 +- .../backends/test_native_planar_statistics.py | 2 +- .../test_native_synthetic_operator.py | 2 +- tests/backends/test_native_widths.py | 8 +- tests/backends/test_on_axis_statistics.py | 2 +- tests/driver/test_estimate.py | 2 +- tests/driver/test_native_flow_pathological.py | 2 +- tests/driver/test_native_flow_session.py | 2 +- .../driver/test_native_moving_guide_bound.py | 2 +- tests/driver/test_native_rk_march.py | 2 +- tests/sessions/runs.py | 187 +- tests/sessions/test_native_load.py | 21 +- tests/sessions/test_native_session.py | 77 +- .../test_native_session_axis_plasma.py | 2 +- .../test_native_session_statistics.py | 4 +- tests/vector_raman_cases.py | 2 +- 40 files changed, 1603 insertions(+), 3067 deletions(-) delete mode 100644 native/src/solprop_native/_records.py diff --git a/native/include/solprop_native/workspace.hpp b/native/include/solprop_native/workspace.hpp index 894105820..eb6467a51 100644 --- a/native/include/solprop_native/workspace.hpp +++ b/native/include/solprop_native/workspace.hpp @@ -159,23 +159,37 @@ struct AdamsConfig { fields::array("weights", &A::weights, E::any())); } -/** The boundary monitor's weights where the state lives (solprop SEP 21), and the split - collar's walk-off bucket of each bin (solprop #440; empty for none). */ +/** The boundary monitor's weights where the state lives (solprop SEP 21), a run's: each + run's monitor is its own (`RunRequest.for_run`). `split` says the monitor reads the + split collar's crossing, whose walk-off buckets are the problem's (`Occupancy`). */ struct MonitorBinding { std::vector weights; std::vector column_weights; - std::vector buckets; - std::size_t bucket_count = 0; + bool split = false; }; [[nodiscard]] constexpr auto describe(const MonitorBinding* /*unused*/) { using M = MonitorBinding; using E = fields::Extent; - return fields::table( - "MonitorBinding", fields::array("weights", &M::weights, E::any()), - fields::array("column_weights", &M::column_weights, E::any()), - fields::array("buckets", &M::buckets, fields::Dtype::uint8, E::any()), - fields::value("bucket_count", &M::bucket_count)); + return fields::table("MonitorBinding", + fields::array("weights", &M::weights, E::any()), + fields::array("column_weights", &M::column_weights, E::any()), + fields::value("split", &M::split)); +} + +/** The split collar's walk-off bucket of each bin (solprop #440), the problem's: set + once, and bound to the state by the first run whose monitor reads it. */ +struct Occupancy { + std::vector buckets; + std::size_t count = 0; +}; + +[[nodiscard]] constexpr auto describe(const Occupancy* /*unused*/) { + using O = Occupancy; + using E = fields::Extent; + return fields::table( + "Occupancy", fields::array("buckets", &O::buckets, fields::Dtype::uint8, E::any()), + fields::value("count", &O::count)); } [[nodiscard]] constexpr auto describe(const EdgeLines* /*unused*/) { @@ -195,9 +209,9 @@ struct MonitorBinding { fields::value("batch_bytes", &L::batch_bytes)); } -/** The transverse edge's tables where the state lives (solprop SEP 44): the faces', - the clip's and the totals' weights, a reduction's synthesis (empty for none), the - first row, and a requested collar's lines. */ +/** The transverse edge's tables where the state lives (solprop SEP 44), a run's: the + faces', the clip's and the totals' weights, a reduction's synthesis (empty for none), + the first row, and a requested collar's lines. */ struct EdgeBinding { std::vector faces; std::vector clip; @@ -219,7 +233,8 @@ struct EdgeBinding { } /** Everything fixed for a workspace beside the problem's groups (SEP 52 section 5.3). - Each part is absent where the problem has none. */ + Each part is absent where the problem has none; `crossing_workers` is the threads a + crossing's copy may use (zero keeps the state's default). */ struct Setup { std::optional stage_tables; std::optional z_slots; @@ -228,8 +243,8 @@ struct Setup { std::optional runge_kutta; std::optional adams; std::optional low_storage; - std::optional monitor; - std::optional edge; + std::optional occupancy; + std::size_t crossing_workers = 0; }; [[nodiscard]] constexpr auto describe(const Setup* /*unused*/) { @@ -240,7 +255,8 @@ struct Setup { fields::value("flow_guard", &S::flow_guard), fields::value("runge_kutta", &S::runge_kutta), fields::value("adams", &S::adams), fields::value("low_storage", &S::low_storage), - fields::value("monitor", &S::monitor), fields::value("edge", &S::edge)); + fields::value("occupancy", &S::occupancy), + fields::value("crossing_workers", &S::crossing_workers)); } // -------------------------------------------------------------------- the run records @@ -472,8 +488,9 @@ struct HistoryRow { /** What one run starts from (`Workspace::start`): its records, the initial field and noise as the state takes them (`set_initial`), the march's state at the start (the Adams march's or the Runge-Kutta march's, none for a fresh state of its own), a - resumed history's rows, the statistics plans, and the monitor's launch readings of - the input noise: its floor (energy, then four regions' shares) and the edge's. */ + resumed history's rows, the statistics plans, the monitor's launch readings of the + input noise (its floor: energy, then four regions' shares; and the edge's), and the + run's monitor weights and edge tables where the state lives. */ struct RunStart { RunRecordsRecord records; std::vector field; @@ -485,6 +502,8 @@ struct RunStart { std::shared_ptr row_statistics; std::optional> floor; std::optional edge_noise; + std::optional monitor; + std::optional edge; }; [[nodiscard]] constexpr auto describe(const RunStart* /*unused*/) { @@ -497,7 +516,8 @@ struct RunStart { fields::value("runge_kutta", &R::runge_kutta), fields::value("rows", &R::rows), fields::value("plane_statistics", &R::plane_statistics), fields::value("row_statistics", &R::row_statistics), - fields::value("floor", &R::floor), fields::value("edge_noise", &R::edge_noise)); + fields::value("floor", &R::floor), fields::value("edge_noise", &R::edge_noise), + fields::value("monitor", &R::monitor), fields::value("edge", &R::edge)); } /** The Runge-Kutta march's policy from its record (kernel contract section 12): the @@ -626,7 +646,7 @@ class Workspace { Workspace(Workspace&&) = delete; Workspace& operator=(Workspace&&) = delete; - // -- the setup, applied at construction or, for the old seam, one part at a time + // -- the setup, applied at construction (each part is public for the native tests) void set_stage_tables(stage::Tables tables); void configure_z_slots(const ZSlotsConfig& slots); void upload_z_table(const ZTable& table); @@ -634,16 +654,7 @@ class Workspace { void configure_runge_kutta(RungeKuttaConfig config); void configure_adams(const AdamsConfig& config); void configure_low_storage(rk::low_storage::Config config); - void set_monitor(std::optional monitor); - void set_edge(std::optional edge); - /** The old seam's per-run march configuration. */ - void configure_adams_march(march::Policy policy, bool fused, bool compensated, - bool interpolate, march::Schedule schedule); - void configure_rk_march(rk::Policy policy, std::vector nodes, double rtol, - double atol, march::Schedule schedule); - void set_rk_weights(std::vector weights); - /** The old seam's dense-output weights, from a session's plan. */ - void set_dense_weights(std::vector weights); + void set_occupancy(std::optional occupancy); /** Fail the resident engine's `stage` after `after` more passes (a test hook). */ void inject_fault(engines::MarchFault fault); /** Bind a host source (solprop SEP 49), or unbind with null; CPU builds only. */ @@ -669,8 +680,7 @@ class Workspace { // -- the trial and the coupled flow's guard /** A Runge-Kutta trial whose stage rows the state forms from the stage tables at `z + c_i dz` and the step's end (solprop SEP 45 phase 2): the partials. */ - std::vector staged_trial(double z, double dz, bool prepare_only, - const std::vector* nodes = nullptr); + std::vector staged_trial(double z, double dz, bool prepare_only); /** `_flow_trial`'s guards, transcribed (solprop SEP 45 phase 4): a set of actions is held for one (section, step); a length whose exponent needs too many squarings is refused before forming, and a measured conditioning above the certificate's @@ -678,21 +688,17 @@ class Workspace { void guard_flow(std::size_t section, double dz, const std::vector& nodes); /** Forget the held actions' key (a test forming its own). */ void forget_flow_key() noexcept { flow_key_.reset(); } - /** A weighted controller's norm from a trial's partials `(3, slots)`. */ - double weighted_score(const double* partials, std::size_t slots, double rtol, - double atol); // -- the marches [[nodiscard]] MethodKind kind() const noexcept; - /** The march a session runs: from the configured policy, schedule and stage tables, - its engine over the state, its dense output when `dense`, and its state at the - start. */ - session::Method method(MethodKind kind, std::variant start, - bool dense); - /** One call of the configured Adams march (the decision traces' entry point). */ + /** One call of the Adams march with the policy and schedule a run's records gave + (the decision traces' entry point). */ march::Result run_adams(march::State& state, const march::Bounds& bounds); - /** One call of the configured Runge-Kutta march. */ + /** One call of the Runge-Kutta march, likewise. */ rk::Result run_rk(rk::State& state, const march::Bounds& bounds); + /** Take a run's march policy and schedule from its records without starting it (the + decision traces' configuration). */ + void configure_march(const RunRecordsRecord& records); // -- runs and probes /** Load a start as a fresh workspace's (SEP 22 section 4.7): the field and noise, @@ -700,8 +706,6 @@ class Workspace { void load(std::span field, std::span noise); /** Start one run from `start` (SEP 52 section 5.3), leasing the workspace to it. */ std::unique_ptr start(RunStart start); - /** Start a session from a method and a plan the old seam formed (`start_session`). */ - std::unique_ptr start(session::Method method, session::Plan plan, double z); /** Load `field` and `noise` at `z` and return a probe of the configured march. */ std::unique_ptr probe(std::vector field, std::vector noise, double z); @@ -734,7 +738,13 @@ class Workspace { void apply(const Setup& setup); void require_built() const; void require_open() const; - void bind_run_monitor(); + void bind_run_monitor(const MonitorBinding& monitor, const std::optional& edge); + /** The march a session runs: from the run's policy and schedule and the stage tables, + its engine over the state, its dense output when `dense`, and its state at the + start. */ + session::Method method(MethodKind kind, std::variant start, + bool dense); + std::unique_ptr launch(session::Method method, session::Plan plan, double z); std::size_t columns_ = 0; std::size_t elements_ = 0; @@ -748,9 +758,8 @@ class Workspace { std::optional runge_kutta_; std::optional adams_; std::optional low_storage_; - std::optional monitor_; + std::optional occupancy_; bool occupancy_bound_ = false; - std::optional edge_; std::optional march_policy_; march::Schedule march_schedule_; bool march_fused_ = false; diff --git a/native/src/bindings.cpp b/native/src/bindings.cpp index b30c3d92a..c31089bd5 100644 --- a/native/src/bindings.cpp +++ b/native/src/bindings.cpp @@ -235,19 +235,6 @@ std::vector index_vector(const IndexInput values) { return result; } -native::TableKind table_kind(const std::string& name) { - if (name == "phi") - return native::TableKind::phi; - if (name == "prefactor") - return native::TableKind::prefactor; - if (name == "rate") - return native::TableKind::rate; - if (name == "flux") - return native::TableKind::flux; - throw std::invalid_argument("unknown z table '" + name + - "'; expected 'phi', 'prefactor', 'rate' or 'flux'"); -} - // solprop SEP 46: a workspace's CPU execution record, as solprop_native's // `_execution.ExecutionRecord.native()` writes it: each operation's threshold and full // size, then the response bounds, widths and rules, every key required. @@ -610,10 +597,9 @@ void bind_problem(nb::module_& module_) { bind_setup(problem, "adams", &native::Setup::adams, "collections.abc.Mapping[str, object] | None"); bind_setup(problem, "low_storage", &native::Setup::low_storage, "object | None"); - bind_setup(problem, "monitor", &native::Setup::monitor, - "collections.abc.Mapping[str, object] | None"); - bind_setup(problem, "edge", &native::Setup::edge, + bind_setup(problem, "occupancy", &native::Setup::occupancy, "collections.abc.Mapping[str, object] | None"); + bind_setup(problem, "crossing_workers", &native::Setup::crossing_workers, "int"); problem.def(nb::init<>()) .def_rw("dims", &P::dims) .def_rw("grid", &P::grid) @@ -718,91 +704,6 @@ native::TrialScalars adams_scalars(const RealInput phi_delta, const RealInput ph return scalars; } -// One of solprop's piecewise Chebyshev tables of real values, as solprop's adapter -// packs it: (edges, lower, upper, coefficients) with the coefficients -// (n_intervals, n_terms, n_values); `None` for an absent table (solprop SEP 39). -native::stage::Table stage_table_from(const nb::handle value) { - // A tuple `(edges, lower, upper, coefficients)` read by the table's field order. - return native::records::read(value, "stage table"); -} - -std::vector stage_table_list(const nb::handle values) { - std::vector tables; - for (const auto value : nb::cast(values)) - tables.push_back(stage_table_from(value)); - return tables; -} - -// Every table an exponential Adams trial's stage scalars read (solprop SEP 39 phase 1): -// solprop's adapter packs them once per run from the problem's own leaves. -native::stage::Tables stage_tables_from(const nb::dict values) { - native::stage::Tables tables; - try { - tables.n_stages = nb::cast(values["n_stages"]); - tables.phi = static_cast(nb::cast(values["phi"])); - tables.phi_weights = stage_table_from(values["phi_weights"]); - tables.phi_rate = stage_table_from(values["phi_rate"]); - tables.prefactor = - static_cast(nb::cast(values["prefactor"])); - tables.prefactor_weights = stage_table_from(values["prefactor_weights"]); - tables.prefactor_low = nb::cast(values["prefactor_low"]); - tables.prefactor_high = nb::cast(values["prefactor_high"]); - tables.density = stage_table_from(values["density"]); - tables.taper = stage_table_from(values["taper"]); - tables.raman_rates = stage_table_list(values["raman_rates"]); - tables.kerr = - static_cast(nb::cast(values["kerr"])); - tables.kerr_density = stage_table_from(values["kerr_density"]); - tables.plasma_densities = stage_table_list(values["plasma_densities"]); - tables.plasma_preionisation = stage_table_list(values["plasma_preionisation"]); - tables.raman_densities = stage_table_list(values["raman_densities"]); - tables.dispersive_densities = stage_table_list(values["dispersive_densities"]); - const int chord = nb::cast(values["chord"]); - if (chord < static_cast(native::stage::Chord::none) || - chord > static_cast(native::stage::Chord::table)) - native::refuse("the stage tables are inconsistent: chord kind ", chord, - " is unknown"); - tables.chord = static_cast(chord); - tables.chord_rate = nb::cast(values["chord_rate"]); - tables.chord_terms = nb::cast>(values["chord_terms"]); - if (values.contains("chord_table")) - tables.chord_table = stage_table_from(values["chord_table"]); - tables.flow.edges = nb::cast>(values["flow_edges"]); - tables.flow.degrees = nb::cast(values["flow_degrees"]); - tables.flow.slack = nb::cast(values["flow_slack"]); - tables.flow_residual = nb::cast(values["flow_residual"]); - tables.transform.edges = nb::cast>(values["transform_edges"]); - tables.transform.degrees = nb::cast(values["transform_degrees"]); - tables.transform.slack = nb::cast(values["transform_slack"]); - } catch (const nb::cast_error&) { - throw std::invalid_argument("the stage tables have the wrong types"); - } - const bool expansion = tables.phi == native::stage::Terms::expansion; - const auto known_terms = [](const native::stage::Terms terms) { - return terms == native::stage::Terms::constant || - terms == native::stage::Terms::expansion || - terms == native::stage::Terms::table; - }; - const bool known = known_terms(tables.phi) && known_terms(tables.prefactor); - if (!known || tables.n_stages == 0 || !tables.density.present() || - (expansion && (!tables.phi_weights.present() || !tables.phi_rate.present() || - tables.phi_rate.n_values != tables.phi_weights.n_values)) || - (tables.prefactor == native::stage::Terms::expansion && - !tables.prefactor_weights.present()) || - (tables.kerr == native::stage::KerrDensity::table && - !tables.kerr_density.present()) || - tables.plasma_densities.size() != tables.plasma_preionisation.size() || - (tables.chord == native::stage::Chord::expansion && - (!expansion || tables.chord_terms.size() != tables.phi_weights.n_values)) || - (tables.chord == native::stage::Chord::table && - (!tables.chord_table.present() || tables.chord_table.n_values != 1)) || - (tables.flow.present() && tables.flow.edges.size() < 2) || - (tables.transform.present() && tables.transform.edges.size() < 2)) - throw std::invalid_argument("the stage tables are inconsistent"); - native::stage::require_scalar_tables(tables); - return tables; -} - // One exponential trial's tables formed natively from its nodes (solprop SEP 39 // phase 1): `stage::weights` of the arrays solprop passes. native::ExponentialWeights @@ -985,70 +886,12 @@ nb::dict watch_state_to(const native::watch::State& state) { // solprop SEP 47 section 6.4: the owning boundary monitor's configuration, the record // a resume continues and the record it keeps, from and to solprop's dictionaries. -native::watch::Config watch_config_from(const nb::dict values) { +native::watch::Config watch_config_from(const nb::handle values) { auto config = native::records::read(values, "config"); native::watch::validate(config.policy); return config; } -std::vector> watch_stretches_from(const nb::handle values) { - std::vector> stretches; - for (const auto& pair : nb::cast>>(values)) { - if (pair.size() != 2) - throw std::invalid_argument("an unwatched stretch is a start and an end"); - stretches.push_back({pair[0], pair[1]}); - } - return stretches; -} - -native::watch::Resumption watch_resumption_from(const nb::dict values) { - native::watch::Resumption record; - const auto number = [&values](const char* name) -> std::optional { - if (!values.contains(name)) - return std::nullopt; - return nb::cast(values[name]); - }; - try { - record.record = nb::cast(values["record"]); - record.launch_energy = number("launch_energy"); - record.launch_guard_low = number("launch_guard_low"); - record.launch_guard_high = number("launch_guard_high"); - record.launch_collar = number("launch_collar"); - record.guard_low_max = number("guard_low_max"); - record.guard_high_max = number("guard_high_max"); - record.guard_low_at = number("guard_low_at"); - record.guard_high_at = number("guard_high_at"); - record.collar_max = number("collar_max"); - record.raw_removed_fraction = number("raw_removed_fraction"); - record.removed_signed = number("removed_signed"); - record.removed_fraction = number("removed_fraction"); - record.floor_removed_fraction = number("floor_removed_fraction"); - record.quiet_checks = number("quiet_checks"); - record.collar_quiet = nb::cast(values["collar_quiet"]); - record.raw_guard_max = number("raw_guard_max"); - record.steps = number("steps"); - record.skipped = number("skipped"); - record.collar_left_out_checks = number("collar_left_out_checks"); - if (values.contains("unwatched")) - record.unwatched = watch_stretches_from(values["unwatched"]); - if (values.contains("resumed_at")) - record.resumed_at = nb::cast>(values["resumed_at"]); - if (values.contains("planes")) { - const auto rows = nb::cast>>(values["planes"]); - if (rows.size() != native::watch::plane_columns) - throw std::invalid_argument("a monitor record's plane rows have five columns"); - record.has_planes = true; - for (std::size_t column = 0; column < native::watch::plane_columns; ++column) - record.planes[column] = rows[column]; - } - } catch (const nb::cast_error&) { - throw std::invalid_argument("a resumed boundary record has the wrong types"); - } catch (const nb::python_error&) { - throw std::invalid_argument("a resumed boundary record lacks a field"); - } - return record; -} - nb::dict watch_record_to(const native::watch::Record& record) { nb::dict out; out["launch_energy"] = record.launch_energy; @@ -1094,84 +937,6 @@ nb::dict watch_judgement_to(const native::watch::Judgement& judgement) { return out; } -native::session::MonitorPlan monitor_plan_from(const nb::dict values) { - native::session::MonitorPlan plan; - plan.config = watch_config_from(nb::cast(values["config"])); - try { - plan.resume = nb::cast(values["resume"]); - if (plan.resume) { - plan.record = watch_resumption_from(nb::cast(values["record"])); - plan.plane = nb::cast(values["plane"]); - plan.unwatched = watch_stretches_from(values["unwatched"]); - if (values.contains("edge_record")) - plan.edge_record = native::bindings::transverse_resumption_from( - nb::cast(values["edge_record"])); - } - // The input noise's floor: its energy, then its four regions' shares. - if (values.contains("floor") && !values["floor"].is_none()) { - const auto floor = nb::cast>(values["floor"]); - if (floor.size() != 5) - throw std::invalid_argument("a monitor's floor is its energy and four regions"); - plan.floor = true; - plan.floor_energy = floor[0]; - std::copy(floor.begin() + 1, floor.end(), plan.floor_regions.begin()); - } - // A free-space run's transverse edge (SEP 40 section 5.3), owned alike. - if (values.contains("edge") && !values["edge"].is_none()) - plan.edge = - native::bindings::transverse_config_from(nb::cast(values["edge"])); - if (values.contains("edge_noise") && !values["edge_noise"].is_none()) - plan.edge_noise = native::bindings::transverse_noise_from( - nb::cast(values["edge_noise"])); - } catch (const nb::cast_error&) { - throw std::invalid_argument("a session's boundary monitor has the wrong types"); - } catch (const nb::python_error&) { - throw std::invalid_argument("a session's boundary monitor lacks a field"); - } - return plan; -} - -// solprop SEP 45 phase 3: the Runge-Kutta march's policy and state, from and to -// solprop's `rk_march_policy` and `_NativeRungeKuttaMarch._state`. -native::rk::Policy rk_policy_from(const nb::dict values) { - native::rk::Policy policy; - try { - auto& landings = policy.landings; - landings.dz_min = nb::cast(values["dz_min"]); - landings.dz_max = nb::cast(values["dz_max"]); - landings.stretch = nb::cast(values["stretch"]); - landings.z_end = nb::cast(values["z_end"]); - landings.save_planes = nb::cast>(values["save_planes"]); - landings.hard_kinks = nb::cast>(values["hard_kinks"]); - landings.breakpoints = nb::cast>(values["breakpoints"]); - landings.landing_ulps = nb::cast(values["landing_ulps"]); - landings.interpolate = nb::cast(values["interpolate"]); - landings.has_quiet_interval = !values["quiet_interval"].is_none(); - landings.quiet_interval = - landings.has_quiet_interval ? nb::cast(values["quiet_interval"]) : 0.0; - policy.safety = nb::cast(values["safety"]); - policy.beta1 = nb::cast(values["beta1"]); - policy.beta2 = nb::cast(values["beta2"]); - policy.min_factor = nb::cast(values["min_factor"]); - policy.max_factor = nb::cast(values["max_factor"]); - policy.lag = nb::cast(values["lag"]); - policy.reject_free = nb::cast(values["reject_free"]); - policy.power = nb::cast(values["power"]); - policy.exponent = nb::cast(values["exponent"]); - policy.start_growth = nb::cast(values["start_growth"]); - policy.auto_init = nb::cast(values["auto_init"]); - policy.dz_min = landings.dz_min; - policy.dz_max = landings.dz_max; - } catch (const nb::cast_error&) { - throw std::invalid_argument("the Runge-Kutta march's policy has the wrong types"); - } catch (const nb::python_error&) { - throw std::invalid_argument("the Runge-Kutta march's policy lacks a field"); - } - if (policy.landings.breakpoints.size() < 2 || !(policy.dz_max >= policy.dz_min)) - throw std::invalid_argument("the Runge-Kutta march's landings are invalid"); - return policy; -} - native::rk::State rk_state_from(const nb::dict values) { native::rk::State state; try { @@ -1416,9 +1181,11 @@ class ScriptedMarch { class ScriptedRkMarch { public: - ScriptedRkMarch(const nb::dict policy, const RealInput norms, const double h0, + ScriptedRkMarch(const nb::object& policy, const RealInput norms, const double h0, const RealInput steps, const RealInput edges) - : policy_(rk_policy_from(policy)), norms_(real_vector(norms)), h0_(h0), + : policy_(native::to_native(native::records::read( + policy, "policy"))), + norms_(real_vector(norms)), h0_(h0), schedule_{.steps = real_vector(steps), .edges = real_vector(edges)} {} nb::dict run(const nb::dict state_values, const nb::dict bounds_values) { auto state = rk_state_from(state_values); @@ -1449,326 +1216,6 @@ class ScriptedRkMarch { std::vector log_; }; -// The old seam's state (solprop SEP 47): a `native::Workspace` configured one call at a -// time, as solprop_native's adapter configures it. The lease, the flow guard, the -// marches' construction and the march entry points are the workspace's (workspace.hpp); -// this class converts and forwards. -class BoundState final : public Owned { -public: - explicit BoundState(native::Problem problem) - : raman_terms_(problem.raman.n_terms), raman_(problem.raman.enabled), - workspace_(std::make_unique(std::move(problem))) { - register_owned(this); - } - ~BoundState() override { - close(); - forget_owned(this); - } - BoundState(const BoundState&) = delete; - BoundState& operator=(const BoundState&) = delete; - BoundState(BoundState&&) = delete; - BoundState& operator=(BoundState&&) = delete; - - [[nodiscard]] native::Workspace& workspace() const { return *workspace_; } - - void set_initial(const std::span field, - const std::span noise) { - workspace_->state().set_initial(field, noise); - } - // solprop SEP 45 phase 2: a Runge-Kutta trial whose stage rows the state forms from - // the uploaded tables, at the positions `z + c_i dz` and the step's end. - std::vector rk_trial(const double z, const double dz, - const std::vector& nodes, - const bool prepare_only) { - workspace_->require_unleased(); - workspace_->state(); - return workspace_->staged_trial(z, dz, prepare_only, &nodes); - } - void flow_guard_configure(std::vector row_sum, - std::vector condition_bound, - const double taylor_scale, const int max_squarings, - const double allowance) { - workspace_->configure_flow_guard({.row_sum = std::move(row_sum), - .condition_bound = std::move(condition_bound), - .taylor_scale = taylor_scale, - .max_squarings = max_squarings, - .allowance = allowance}); - } - void rk_march_configure(native::rk::Policy policy, std::vector nodes, - const double rtol, const double atol, - std::vector steps, std::vector edges) { - workspace_->configure_rk_march( - std::move(policy), std::move(nodes), rtol, atol, - {.steps = std::move(steps), .edges = std::move(edges)}); - } - nb::dict rk_march_run(const nb::dict state_values, const nb::dict bounds_values) { - workspace_->require_unleased(); - auto state = rk_state_from(state_values); - const auto bounds = march_bounds_from(bounds_values); - native::rk::Result result; - { - const nb::gil_scoped_release release; - result = workspace_->run_rk(state, bounds); - } - return rk_result_to(result, state); - } - std::vector trial_step(const double dz, const native::TrialScalars& scalars, - const bool prepare_only = false) { - auto& state = workspace_->state(); - if (prepare_only) { - state.prepare_trial(dz, scalars); - return {}; - } - return state.trial_step(dz, scalars); - } - std::vector flow_actions_to_host(const bool inverse) { - return workspace_->state().flow_actions_to_host(inverse); - } - std::vector adams_block_to_host() { - return workspace_->state().adams_block_to_host(); - } - std::vector adams_exponent_to_host() { - return workspace_->state().adams_exponent_to_host(); - } - std::vector form_flow_actions(const std::size_t section, const double dz, - const std::vector& fractions) { - auto& state = workspace_->state(); - workspace_->forget_flow_key(); - return state.form_flow_actions(section, dz, fractions); - } - std::vector weighted_error(const std::vector& scale) { - return workspace_->state().weighted_error(scale); - } - void low_storage_configure(const std::size_t flows, const bool separable, - const double origin) { - workspace_->configure_low_storage( - {.flows = flows, .separable = separable, .origin = origin}); - } - void rk_weights_configure(std::vector weights) { - workspace_->set_rk_weights(std::move(weights)); - } - double rk_weighted_score(const double* partials, const std::size_t slots, - const double rtol, const double atol) { - return workspace_->weighted_score(partials, slots, rtol, atol); - } - void prepare_raman(const std::vector& rates, - const std::vector& densities) { - workspace_->state().prepare_raman(rates, densities); - } - std::vector statistics(const std::uint64_t flags, - const std::vector& windows, - const std::vector& on_axis, - const double density, const double taper, - const double preionisation, - const double intensity_factor, - const std::vector& channel_preionisation, - const std::vector& power_weight) { - return workspace_->state().statistics(flags, windows, on_axis, density, taper, - preionisation, intensity_factor, - channel_preionisation, power_weight); - } - std::vector spatial_statistics(const std::uint64_t flags, - const double intensity_factor, - const double z) { - return workspace_->state().spatial_statistics(flags, intensity_factor, z); - } - std::vector plane_fluence_trace(const double center_x, const double center_y, - const double dx, const double dy, - const double extent, const double spacing, - const std::size_t n_radii, - const std::vector& cosines, - const std::vector& sines) { - return workspace_->state().plane_fluence_trace(center_x, center_y, dx, dy, extent, - spacing, n_radii, cosines, sines); - } - std::vector axis_spectrum(const std::vector& matrix) { - return workspace_->state().axis_spectrum(matrix); - } - std::vector aperture_statistics(const std::uint64_t flags, - const std::vector& apertures, - const int exponent, - const std::vector& regions, - const double intensity_factor) { - return workspace_->state().aperture_statistics(flags, apertures, exponent, regions, - intensity_factor); - } - std::vector - planned_statistics(const std::shared_ptr& plan, - const double z) { - return native::statistics::evaluate(workspace_->state(), *plan, z); - } - void bind_edge(const std::vector& faces, const std::vector& clip, - const std::vector& totals, - const std::vector& synthesis, const std::size_t first_row) { - workspace_->state().bind_edge(faces, clip, totals, synthesis, first_row); - } - native::CrossedBytes crossed_bytes() { return workspace_->built().crossed_bytes(); } - void bind_edge_lines(const native::EdgeLines& lines) { - workspace_->state().bind_edge_lines(lines); - } - native::EdgeNumbers edge_reading(const bool faces, const bool whole, - const bool totals, const bool strip, - const bool current) { - return workspace_->state().edge_reading(faces, whole, totals, strip, current); - } - // A no-op on a closed state. - void set_crossing_workers(const std::size_t workers) noexcept { - if (!workspace_->closed()) - workspace_->built().set_crossing_workers(workers); - } - void field_to_host(const std::span destination) { - workspace_->state().field_to_host(destination); - } - /** The state's element count, `columns * n_omega`. */ - [[nodiscard]] std::size_t elements() const noexcept { return workspace_->elements(); } - std::vector adams_source(const std::vector& input, - const native::TrialScalars& scalars) { - return workspace_->state().adams_source(input, scalars); - } - void adopt(const std::vector& field, const double dz) { - workspace_->state().adopt(field, dz); - } - native::GeneralState& open_state() { return workspace_->state(); } - void set_stage_tables(native::stage::Tables tables) { - workspace_->set_stage_tables(std::move(tables)); - } - void table_slots(const bool phi, const bool prefactor, const std::size_t slots, - const bool rate) { - workspace_->configure_z_slots( - {.phi = phi, .prefactor = prefactor, .slots = slots, .rate = rate}); - } - std::vector table_load(const std::vector& positions) { - auto& slots = workspace_->z_slots(); - if (!slots.present()) - throw std::logic_error("no z table's slots were configured"); - return slots.load(workspace_->state(), positions); - } - void table_rate_at(const double z, const bool before) { - auto& slots = workspace_->z_slots(); - if (!slots.has_rate) - throw std::logic_error("the z table reads no rate"); - slots.rate(workspace_->state(), z, before); - } - [[nodiscard]] std::uint64_t table_evaluations() const { - return workspace_->z_slots().evaluations; - } - [[nodiscard]] bool has_stage_tables() const { - return workspace_->stage_tables().has_value(); - } - native::stage::Trial stage_trial(const double z0, const double z1) { - return workspace_->stage_trial(z0, z1); - } - [[nodiscard]] std::vector stage_rate(const double z) const { - return workspace_->stage_rate(z); - } - void march_configure(march::Policy policy, const bool fused, const bool compensated, - const bool interpolate, march::Schedule schedule) { - workspace_->configure_adams_march(std::move(policy), fused, compensated, - interpolate, std::move(schedule)); - } - nb::dict march_run(const nb::dict state_values, const nb::dict bounds_values) { - workspace_->require_unleased(); - auto state = march_state_from(state_values); - const auto bounds = march_bounds_from(bounds_values); - march::Result result; - { - const nb::gil_scoped_release release; - result = workspace_->run_adams(state, bounds); - } - return march_result_to(result, state); - } - void march_fault(const std::string& stage, const std::size_t after, - const std::string& category) { - workspace_->inject_fault(native::fault_from(stage, after, category)); - } - void stage_to_host(const std::size_t stage, - const std::span destination) { - workspace_->state().stage_to_host(stage, destination); - } - std::vector projected_to_host(const bool coarse) { - return workspace_->state().projected_to_host(coarse); - } - // A closed state reads as having none. - [[nodiscard]] std::map dispersive_path() const { - return workspace_->closed() ? std::map{} - : workspace_->built().dispersive_path(); - } - void finish(const double dz) { workspace_->state().finish(dz); } - void promote_fsal() { workspace_->state().promote_fsal(); } - void clear_fsal() { workspace_->state().clear_fsal(); } - void set_absorber_quiet(const bool quiet) { - workspace_->state().set_absorber_quiet(quiet); - } - void bind_monitor(const std::vector& weights, - const std::vector& column_weights) { - workspace_->state().bind_monitor(weights, column_weights); - } - void unbind_monitor() { workspace_->state().unbind_monitor(); } - void bind_occupancy(const std::vector& buckets, - const std::size_t count) { - workspace_->state().bind_occupancy(buckets, count); - } - std::vector monitor_reading() { - return workspace_->state().monitor_reading(); - } - [[nodiscard]] native::GeneralState& built() const { return workspace_->built(); } - [[nodiscard]] double quadrature_error() const { - workspace_->require_unleased(); - return workspace_->built().quadrature_error(); - } - double quadrature_peak() { return workspace_->state().quadrature_peak(); } - [[nodiscard]] std::size_t columns() const noexcept { return workspace_->columns(); } - [[nodiscard]] std::size_t stages() const noexcept { return workspace_->stages(); } - [[nodiscard]] std::size_t raman_terms() const noexcept { return raman_terms_; } - [[nodiscard]] bool raman() const noexcept { return raman_; } - [[nodiscard]] bool closed() const noexcept { return workspace_->closed(); } - // Closes a session that leases this state first; one that cannot close keeps it. - void close() noexcept override { workspace_->close(); } - // solprop SEP 49: bind `owner` as the state's host source, or unbind with None (on - // a closed state too, which no longer borrows it). The state keeps the object; the - // engine borrows it. - void bind_host_source(nb::object owner) { - if (owner.is_none()) { - workspace_->bind_host_source(nullptr); - host_owner_ = nb::object(); - return; - } - workspace_->bind_host_source(std::make_shared(owner)); - host_owner_ = std::move(owner); - } - // solprop SEP 47: the march a native execution session runs, from the march this - // state was configured with; `state` is the march's state at the session's start. - // `dense`, a session's dense output, is none or `{"weights": float64 array}`: a - // Runge-Kutta tableau's dense-output weights, empty for the Adams march. - native::session::Method session_method(const std::string& kind, - const nb::dict state_values, - const nb::handle dense) { - workspace_->require_unleased(); - const bool interpolated = !dense.is_none(); - if (kind == "adams") - return workspace_->method(native::MethodKind::adams, - march_state_from(state_values), interpolated); - native::MethodKind method_kind = native::MethodKind::runge_kutta; - if (kind == "low_storage") - method_kind = native::MethodKind::low_storage; - else if (kind != "runge_kutta") - throw std::invalid_argument( - R"(a session's march is "adams", "runge_kutta" or "low_storage")"); - const bool dense_rk = - interpolated && method_kind == native::MethodKind::runge_kutta; - if (dense_rk) - workspace_->set_dense_weights( - real_vector(exact_array(nb::cast(dense)["weights"]))); - return workspace_->method(method_kind, rk_state_from(state_values), dense_rk); - } - -private: - std::size_t raman_terms_{}; - bool raman_{}; - std::unique_ptr workspace_; - nb::object host_owner_; -}; - // solprop SEP 47: a batch's chunk as owning NumPy arrays, each made once from the // vector the session moved into the batch (no copy), its capsule owning the storage. template @@ -1832,6 +1279,34 @@ nb::object snapshot_to(std::optional snapshot) { held); } +// A pending batch's ticket, `(sequence, generation)` (SEP 52 section 5.3). +using Ticket = std::pair; + +} // namespace + +namespace solprop_native { + +// An export's conversion (`solprop.backends.export.ExportRecipe`) with the route's power +// weight at the ticket's position, none unless `power`. +struct ExportRecipe { + bool power = false; + bool optics = false; + std::optional> weight; +}; + +[[nodiscard]] constexpr auto describe(const ExportRecipe* /*unused*/) { + using R = ExportRecipe; + return fields::table("ExportRecipe", fields::value("power", &R::power), + fields::value("optics", &R::optics), + fields::array("weight", &R::weight, fields::Extent::any())); +} + +} // namespace solprop_native + +namespace { + +using native::ExportRecipe; + // solprop SEP 47: a native execution session over a leased workspace (`native::Run`). // The binding keeps the workspace's Python object alive while the session lives; the // workspace closes the session first when it closes itself. @@ -1858,22 +1333,22 @@ class BoundSession { } // Takes the session's lock: bound with the interpreter lock released. void acknowledge(const std::uint64_t sequence) { session().acknowledge(sequence); } - void - export_field(const std::uint64_t sequence, const std::uint64_t generation, - const bool power, const bool optics, - const std::optional& weight, - nb::ndarray, nb::c_contig, nb::device::cpu> out) { + // Fill `out` with the pending ticket's field, converted by `recipe` natively. + void export_field(const Ticket ticket, const nb::handle recipe, + nb::ndarray, nb::c_contig, nb::device::cpu> out) { + const auto held = native::records::read(recipe, "recipe"); const std::size_t n = session().elements(); if (out.size() != n) native::refuse("an export destination has ", out.size(), " elements, expected ", n); - if (weight && weight->size() != n) - native::refuse("an export's power weight has ", weight->size(), + if (held.weight && held.weight->size() != n) + native::refuse("an export's power weight has ", held.weight->size(), " elements, expected ", n); - const double* values = weight ? weight->data() : nullptr; + const double* values = held.weight ? held.weight->data() : nullptr; auto* destination = reinterpret_cast(out.data()); const nb::gil_scoped_release release; - session().export_field(sequence, generation, power, optics, values, destination); + session().export_field(ticket.first, ticket.second, held.power, held.optics, values, + destination); } void request_stop() noexcept { session().request_stop(); } nb::tuple request_snapshot() { @@ -1883,18 +1358,9 @@ class BoundSession { [[nodiscard]] native::session::Status status() const noexcept { return session().status(); } - [[nodiscard]] std::size_t elements() const { return session().elements(); } - // Continue a resumed run's monitor record; takes the session's lock. - void continue_monitor(const nb::dict record, const bool plane, - const nb::handle unwatched, const nb::dict edge_record) { - auto resumption = watch_resumption_from(record); - auto stretches = watch_stretches_from(unwatched); - auto edge = native::bindings::transverse_resumption_from(edge_record); - const nb::gil_scoped_release release; - session().continue_monitor(resumption, plane, stretches, edge); - } - // SEP 52: the continuation as `solprop.backends.records.MonitorContinuation`. - void continue_with(const nb::handle continuation) { + // Continue a resumed run's monitor record, given as + // `solprop.backends.records.MonitorContinuation`; takes the session's lock. + void continue_monitor(const nb::handle continuation) { const auto held = native::records::read(continuation, "continuation"); const auto record = native::to_native(held.record); @@ -1902,51 +1368,28 @@ class BoundSession { const nb::gil_scoped_release release; session().continue_monitor(record, held.plane, held.unwatched, edge); } - // The transverse edge's record and finish, or None; takes the session's lock. - nb::object edge_record() { - std::optional> - record; - { - const nb::gil_scoped_release release; - record = session().edge_record(); - } - if (!record) - return nb::none(); - return native::bindings::transverse_record_to(record->first, record->second); - } - // The boundary monitor's record, or None; takes the session's lock. - nb::object monitor_record() { - std::optional record; - { - const nb::gil_scoped_release release; - record = session().monitor_record(); - } - if (!record) - return nb::none(); - return watch_record_to(*record); - } - double quadrature_peak() { - const nb::gil_scoped_release release; - return session().quadrature_peak(); - } - nb::object monitor_cap() { + // SEP 52: every record the session keeps, in one, each read under the session's + // lock: the monitor's and the edge's (None without them), the split collar's cap + // (None without one) and the quadrature peak, drained since the last read. + nb::dict records() { + std::optional monitor; + std::optional> edge; std::optional cap; + double peak = 0.0; { const nb::gil_scoped_release release; + monitor = session().monitor_record(); + edge = session().edge_record(); cap = session().monitor_cap(); + peak = session().quadrature_peak(); } - if (!cap) - return nb::none(); - return nb::float_(*cap); - } - // SEP 52: every record the session keeps, in one: the monitor's, the edge's, the - // split collar's cap and the quadrature peak since the last read. - nb::dict records() { nb::dict out; - out["monitor"] = monitor_record(); - out["edge"] = edge_record(); - out["cap"] = monitor_cap(); - out["quadrature_peak"] = quadrature_peak(); + out["monitor"] = monitor ? nb::object(watch_record_to(*monitor)) : nb::none(); + out["edge"] = edge ? nb::object(native::bindings::transverse_record_to(edge->first, + edge->second)) + : nb::none(); + out["cap"] = cap ? nb::object(nb::float_(*cap)) : nb::none(); + out["quadrature_peak"] = peak; return out; } // solprop SEP 47 section 5.5: the Adams march's state with the orders of its @@ -1963,25 +1406,22 @@ class BoundSession { out["orders"] = state->second; return out; } - // The Adams march's history at the pending ticket `(sequence, generation)` (SEP 47 - // section 5.4), each part copied once; None for a Runge-Kutta march or before any - // history. - nb::object march_snapshot(const std::uint64_t sequence, - const std::uint64_t generation) { - std::optional snapshot; + // The Adams march's history at the pending ticket (SEP 47 section 5.4), each part + // copied once; None for a Runge-Kutta march or before any history. + nb::object snapshot(const Ticket ticket) { + std::optional held; { const nb::gil_scoped_release release; - snapshot = run_->snapshot(sequence, generation); + held = run_->snapshot(ticket.first, ticket.second); } - return snapshot_to(std::move(snapshot)); + return snapshot_to(std::move(held)); } // A z table's `Phi` at `z`, the noise phase at the pending ticket's plane. - ComplexOutput table_phi(const std::uint64_t sequence, const std::uint64_t generation, - const double z) { + ComplexOutput noise_phase(const Ticket ticket, const double z) { std::vector values; { const nb::gil_scoped_release release; - values = run_->noise_phase(sequence, generation, z); + values = run_->noise_phase(ticket.first, ticket.second, z); } return complex_output(values, {columns_, values.size() / columns_}); } @@ -2138,55 +1578,6 @@ class BoundStatisticsPlan { std::shared_ptr plan_; }; -native::session::StatisticsRecipe statistics_recipe_from(const nb::handle value) { - native::session::StatisticsRecipe recipe; - if (value.is_none()) - return recipe; - try { - recipe.plan = nb::cast(value).plan(); - } catch (const nb::cast_error&) { - throw std::invalid_argument("a session's statistics recipe is a StatisticsPlan"); - } - return recipe; -} - -native::session::Plan session_plan_from(const nb::dict values) { - native::session::Plan plan; - try { - plan.planes = real_vector(exact_array(values["planes"])); - plan.next_plane = nb::cast(values["next_plane"]); - plan.launch_pending = nb::cast(values["launch_pending"]); - plan.step_planes = nb::cast(values["step_planes"]); - plan.plane_statistics = statistics_recipe_from(values["plane_statistics"]); - plan.row_statistics = statistics_recipe_from(values["row_statistics"]); - plan.period = nb::cast(values["period"]); - plan.attempt_capacity = nb::cast(values["attempt_capacity"]); - plan.row_capacity = nb::cast(values["row_capacity"]); - plan.replay = nb::cast(values["replay"]); - plan.replay_steps = nb::cast(values["replay_steps"]); - plan.replay_length = nb::cast(values["replay_length"]); - plan.call_attempts = nb::cast(values["call_attempts"]); - plan.call_seconds = nb::cast(values["call_seconds"]); - if (values.contains("monitor") && !values["monitor"].is_none()) - plan.monitor = monitor_plan_from(nb::cast(values["monitor"])); - } catch (const nb::cast_error&) { - throw std::invalid_argument("a session's plan has the wrong types"); - } catch (const nb::python_error&) { - throw std::invalid_argument("a session's plan lacks a field"); - } - return plan; -} - -std::unique_ptr start_session(BoundState& state, const std::string& kind, - const nb::dict march_state, - const nb::dict plan, const double z) { - const nb::object dense = - plan.contains("dense") ? nb::object(plan["dense"]) : nb::object(nb::none()); - auto method = state.session_method(kind, march_state, dense); - auto run = state.workspace().start(std::move(method), session_plan_from(plan), z); - return std::make_unique(std::move(run), state.columns()); -} - } // namespace // The statistics plans a run's start names cross as the bound `StatisticsPlan`. @@ -2297,7 +1688,8 @@ class BoundProbe { class BoundWorkspace final : public Owned { public: explicit BoundWorkspace(native::Problem problem) - : workspace_(std::make_unique(std::move(problem))) { + : raman_terms_(problem.raman.n_terms), raman_(problem.raman.enabled), + workspace_(std::make_unique(std::move(problem))) { register_owned(this); } ~BoundWorkspace() override { @@ -2313,14 +1705,7 @@ class BoundWorkspace final : public Owned { std::unique_ptr start(const nb::handle run, const nb::object& host) { auto held = records::read(run, "run"); - workspace_->require_unleased(); - if (host.is_none()) { - workspace_->bind_host_source(nullptr); - host_owner_ = nb::object(); - } else { - workspace_->bind_host_source(std::make_shared(host)); - host_owner_ = host; - } + bind_host(host); std::unique_ptr started; { const nb::gil_scoped_release release; @@ -2328,8 +1713,9 @@ class BoundWorkspace final : public Owned { } return std::make_unique(std::move(started), workspace_->columns()); } - std::unique_ptr probe(const nb::handle run) { + std::unique_ptr probe(const nb::handle run, const nb::object& host) { auto held = records::read(run, "start"); + bind_host(host); std::unique_ptr probe; { const nb::gil_scoped_release release; @@ -2363,17 +1749,46 @@ class BoundWorkspace final : public Owned { out["table_evaluations"] = workspace_->z_slots().evaluations; static constexpr std::array kinds{"adams", "runge_kutta", "low_storage"}; - out["method"] = kinds[static_cast(workspace_->kind())]; + const auto kind = workspace_->kind(); + out["method"] = kinds[static_cast(kind)]; + out["history_rows"] = kind == native::MethodKind::adams + ? state.adams_row_names() + : std::vector{}; return out; } [[nodiscard]] bool closed() const noexcept { return workspace_->closed(); } + // Closes a session or probe that leases the workspace first. Python-free: the runtime + // calls it at shutdown, after the interpreter. void close() noexcept override { workspace_->close(); } - void unbind_host_source() { - workspace_->bind_host_source(nullptr); - host_owner_ = nb::object(); + // `close` from Python: without the interpreter lock (a session's close waits for an + // advance in hand), then the host source dropped with it once the state is gone, + // since the state's reference to it is invisible to the garbage collector. + void close_from_python() noexcept { + { + const nb::gil_scoped_release release; + close(); + } + if (workspace_->closed()) + host_owner_ = nb::object(); } + [[nodiscard]] std::size_t raman_terms() const noexcept { return raman_terms_; } + [[nodiscard]] bool raman() const noexcept { return raman_; } private: + // Bind `host` as the next run's host source (solprop SEP 49), or unbind with None. + void bind_host(const nb::object& host) { + workspace_->require_unleased(); + if (host.is_none()) { + workspace_->bind_host_source(nullptr); + host_owner_ = nb::object(); + return; + } + workspace_->bind_host_source(std::make_shared(host)); + host_owner_ = host; + } + + std::size_t raman_terms_{}; + bool raman_{}; std::unique_ptr workspace_; nb::object host_owner_; }; @@ -2774,6 +2189,144 @@ nb::dict build_record() { // (`solprop.backends.engines`), for the engine-level parity tests, with a read-back of // the field and of a stage register. The object leases the workspace while it lives, // as a session does. +// A test's view of a workspace's state, for the `_testing` entry points that read or +// step it directly (solprop SEP 52 section 6.5): it owns nothing and holds no lease, so +// each call refuses while a session or probe holds the workspace. +class TestState { +public: + explicit TestState(BoundWorkspace& owner) + : owner_(&owner), workspace_(&owner.workspace()) {} + + [[nodiscard]] native::GeneralState& open_state() const { return workspace_->state(); } + [[nodiscard]] std::size_t elements() const noexcept { return workspace_->elements(); } + [[nodiscard]] std::size_t columns() const noexcept { return workspace_->columns(); } + [[nodiscard]] std::size_t stages() const noexcept { return workspace_->stages(); } + [[nodiscard]] std::size_t raman_terms() const noexcept { + return owner_->raman_terms(); + } + [[nodiscard]] bool raman() const noexcept { return owner_->raman(); } + std::vector trial_step(const double dz, const native::TrialScalars& scalars, + const bool prepare_only) const { + auto& state = open_state(); + if (prepare_only) { + state.prepare_trial(dz, scalars); + return {}; + } + return state.trial_step(dz, scalars); + } + void adopt(const std::vector& field, const double dz) const { + open_state().adopt(field, dz); + } + void stage_to_host(const std::size_t stage, + const std::span destination) const { + open_state().stage_to_host(stage, destination); + } + [[nodiscard]] std::vector projected_to_host(const bool coarse) const { + return open_state().projected_to_host(coarse); + } + [[nodiscard]] std::vector weighted_error(const std::vector& scale) const { + return open_state().weighted_error(scale); + } + std::vector form_flow_actions(const std::size_t section, const double dz, + const std::vector& fractions) const { + auto& state = open_state(); + workspace_->forget_flow_key(); + return state.form_flow_actions(section, dz, fractions); + } + [[nodiscard]] std::vector flow_actions_to_host(const bool inverse) const { + return open_state().flow_actions_to_host(inverse); + } + [[nodiscard]] std::vector adams_block_to_host() const { + return open_state().adams_block_to_host(); + } + [[nodiscard]] std::vector adams_exponent_to_host() const { + return open_state().adams_exponent_to_host(); + } + [[nodiscard]] native::stage::Trial stage_trial(const double z0, const double z1) const { + return workspace_->stage_trial(z0, z1); + } + [[nodiscard]] std::vector stage_rate(const double z) const { + return workspace_->stage_rate(z); + } + [[nodiscard]] bool has_stage_tables() const { + return workspace_->stage_tables().has_value(); + } + void table_rate_at(const double z, const bool before) const { + auto& slots = workspace_->z_slots(); + if (!slots.has_rate) + throw std::logic_error("the z table reads no rate"); + slots.rate(open_state(), z, before); + } + void promote_fsal() const { open_state().promote_fsal(); } + [[nodiscard]] nb::dict march_run(const nb::dict state_values, + const nb::dict bounds_values) const { + workspace_->require_unleased(); + auto state = march_state_from(state_values); + const auto bounds = march_bounds_from(bounds_values); + march::Result result; + { + const nb::gil_scoped_release release; + result = workspace_->run_adams(state, bounds); + } + return march_result_to(result, state); + } + [[nodiscard]] nb::dict rk_march_run(const nb::dict state_values, + const nb::dict bounds_values) const { + workspace_->require_unleased(); + auto state = rk_state_from(state_values); + const auto bounds = march_bounds_from(bounds_values); + native::rk::Result result; + { + const nb::gil_scoped_release release; + result = workspace_->run_rk(state, bounds); + } + return rk_result_to(result, state); + } + [[nodiscard]] std::vector + statistics(const std::uint64_t flags, const std::vector& windows, + const std::vector& on_axis, const double density, const double taper, + const double preionisation, const double intensity_factor, + const std::vector& channel_preionisation, + const std::vector& power_weight) const { + return open_state().statistics(flags, windows, on_axis, density, taper, + preionisation, intensity_factor, + channel_preionisation, power_weight); + } + [[nodiscard]] std::vector spatial_statistics(const std::uint64_t flags, + const double intensity_factor, + const double z) const { + return open_state().spatial_statistics(flags, intensity_factor, z); + } + [[nodiscard]] std::vector + planned_statistics(const std::shared_ptr& plan, + const double z) const { + return native::statistics::evaluate(open_state(), *plan, z); + } + [[nodiscard]] std::vector + plane_fluence_trace(const double center_x, const double center_y, const double dx, + const double dy, const double extent, const double spacing, + const std::size_t n_radii, const std::vector& cosines, + const std::vector& sines) const { + return open_state().plane_fluence_trace(center_x, center_y, dx, dy, extent, spacing, + n_radii, cosines, sines); + } + [[nodiscard]] std::vector + axis_spectrum(const std::vector& matrix) const { + return open_state().axis_spectrum(matrix); + } + [[nodiscard]] std::vector monitor_reading() const { + return open_state().monitor_reading(); + } + [[nodiscard]] double quadrature_error() const { + workspace_->require_unleased(); + return workspace_->built().quadrature_error(); + } + +private: + BoundWorkspace* owner_; + native::Workspace* workspace_; +}; + class TestEngines { public: explicit TestEngines(BoundWorkspace& owner) : owner_(&owner.workspace()) { @@ -3156,7 +2709,7 @@ void bind_testing(nb::module_& testing) { .def("run", &ScriptedMarch::run, "state"_a, "bounds"_a) .def("log", &ScriptedMarch::log); nb::class_(testing, "ScriptedRkMarch") - .def(nb::init(), "policy"_a, + .def(nb::init(), "policy"_a, "norms"_a.noconvert(), "h0"_a, "steps"_a.noconvert(), "edges"_a.noconvert()) .def("run", &ScriptedRkMarch::run, "state"_a, "bounds"_a) .def("log", &ScriptedRkMarch::log) @@ -3166,16 +2719,20 @@ void bind_testing(nb::module_& testing) { nb::class_(testing, "Monitor") .def( "__init__", - [](native::watch::Monitor* self, const nb::dict config) { + [](native::watch::Monitor* self, const nb::handle config) { new (self) native::watch::Monitor(watch_config_from(config)); }, "config"_a) .def( "resume", - [](native::watch::Monitor& self, const nb::dict record, const bool plane, + [](native::watch::Monitor& self, const nb::handle record, const bool plane, const nb::handle unwatched) { - self.resume(watch_resumption_from(record), plane, - watch_stretches_from(unwatched)); + const auto held = + native::records::read(record, "record"); + const auto stretches = + native::records::read>>(unwatched, + "unwatched"); + self.resume(native::to_native(held), plane, stretches); }, "record"_a, "plane"_a, "unwatched"_a) .def( @@ -3232,11 +2789,11 @@ void bind_testing(nb::module_& testing) { .def("steps_to_check", &native::watch::Monitor::steps_to_check); testing.def( "trial_step", - [](BoundState& self, const double dz, const RealInput phi_delta, + [](BoundWorkspace& owner, const double dz, const RealInput phi_delta, const RealInput phi_at, const RealInput prefactor, const RealInput density, const RealInput taper, const RealInput preionisation, const RealInput raman_rates, const nb::object material, - const bool prepare_only) { + const bool prepare_only) { TestState self(owner); if (self.raman() && (raman_rates.ndim() != 2 || raman_rates.shape(0) != self.stages() || raman_rates.shape(1) != self.raman_terms())) @@ -3273,21 +2830,21 @@ void bind_testing(nb::module_& testing) { } return real_output(std::move(partials), 3); }, - "state"_a, "dz"_a, "phi_delta"_a.noconvert(), "phi_at"_a.noconvert(), + "workspace"_a, "dz"_a, "phi_delta"_a.noconvert(), "phi_at"_a.noconvert(), "prefactor"_a.noconvert(), "density"_a.noconvert(), "taper"_a.noconvert(), "preionisation"_a.noconvert(), "raman_rates"_a.noconvert(), "material"_a = nb::none(), "prepare_only"_a = false); testing.def( "adopt", - [](BoundState& self, const ComplexInput field, const double dz) { + [](BoundWorkspace& owner, const ComplexInput field, const double dz) { TestState self(owner); const auto held = complex_vector(field); const nb::gil_scoped_release release; self.adopt(held, dz); }, - "state"_a, "field"_a.noconvert(), "dz"_a); + "workspace"_a, "field"_a.noconvert(), "dz"_a); testing.def( "stage_to_host", - [](BoundState& self, const std::size_t stage) { + [](BoundWorkspace& owner, const std::size_t stage) { TestState self(owner); const auto count = self.elements(); auto storage = native::crossing::host_buffer(2 * count); { @@ -3298,10 +2855,10 @@ void bind_testing(nb::module_& testing) { return complex_buffer_output(std::move(storage), {self.columns(), count / self.columns()}); }, - "state"_a, "stage"_a); + "workspace"_a, "stage"_a); testing.def( "projected_to_host", - [](BoundState& self, const bool coarse) { + [](BoundWorkspace& owner, const bool coarse) { TestState self(owner); std::vector values; { const nb::gil_scoped_release release; @@ -3309,10 +2866,10 @@ void bind_testing(nb::module_& testing) { } return complex_output(values, {self.columns(), values.size() / self.columns()}); }, - "state"_a, "coarse"_a = false); + "workspace"_a, "coarse"_a = false); testing.def( "weighted_error", - [](BoundState& self, const RealInput scale) { + [](BoundWorkspace& owner, const RealInput scale) { TestState self(owner); std::vector partials; const auto held_scale = real_vector(scale); { @@ -3321,11 +2878,11 @@ void bind_testing(nb::module_& testing) { } return real_output(std::move(partials), 1); }, - "state"_a, "scale"_a.noconvert()); + "workspace"_a, "scale"_a.noconvert()); testing.def( "form_flow_actions", - [](BoundState& self, const std::size_t section, const double dz, - const RealInput fractions) { + [](BoundWorkspace& owner, const std::size_t section, const double dz, + const RealInput fractions) { TestState self(owner); const auto held_fractions = real_vector(fractions); std::vector measured; { @@ -3334,10 +2891,10 @@ void bind_testing(nb::module_& testing) { } return real_output(std::move(measured), 1); }, - "state"_a, "section"_a, "dz"_a, "fractions"_a.noconvert()); + "workspace"_a, "section"_a, "dz"_a, "fractions"_a.noconvert()); testing.def( "flow_actions_to_host", - [](BoundState& self, const bool inverse) { + [](BoundWorkspace& owner, const bool inverse) { TestState self(owner); std::vector values; { const nb::gil_scoped_release release; @@ -3345,12 +2902,12 @@ void bind_testing(nb::module_& testing) { } return complex_output(values, {values.size()}); }, - "state"_a, "inverse"_a); + "workspace"_a, "inverse"_a); // solprop SEP 47 phase 4: the last exponential Adams trial's coupled block and // exponent, observations for tests. testing.def( "adams_block_to_host", - [](BoundState& self) { + [](BoundWorkspace& owner) { TestState self(owner); std::vector values; { const nb::gil_scoped_release release; @@ -3358,10 +2915,10 @@ void bind_testing(nb::module_& testing) { } return complex_output(values, {values.size()}); }, - "state"_a); + "workspace"_a); testing.def( "adams_exponent_to_host", - [](BoundState& self) { + [](BoundWorkspace& owner) { TestState self(owner); std::vector values; { const nb::gil_scoped_release release; @@ -3369,10 +2926,10 @@ void bind_testing(nb::module_& testing) { } return complex_output(values, {values.size()}); }, - "state"_a); + "workspace"_a); testing.def( "adams_exponential_trial", - [](BoundState& self, const double dz, const IndexInput slots, + [](BoundWorkspace& owner, const double dz, const IndexInput slots, const RealInput predictor, const RealInput corrector, const RealInput rows, const RealInput divisor, const RealInput phi_delta, const RealInput phi_at, const RealInput prefactor, const RealInput density, const RealInput taper, @@ -3383,7 +2940,7 @@ void bind_testing(nb::module_& testing) { const RealInput sample_preionisation, const RealInput sample_raman_rates, const nb::dict sample_material, const RealInput spans, const RealInput comp_predictor, const RealInput comp_corrector, - const RealInput comp_rows, const RealInput rate, const RealInput carrier) { + const RealInput comp_rows, const RealInput rate, const RealInput carrier) { TestState self(owner); auto weights = exponential_weights(slots, predictor, corrector, rows); carrier_frame(weights, carrier, weights.width - 1); const auto rate_weights = real_vector(rate); @@ -3425,7 +2982,7 @@ void bind_testing(nb::module_& testing) { } return real_output(std::move(norms), 1); }, - "state"_a, "dz"_a, "slots"_a.noconvert(), "predictor"_a.noconvert(), + "workspace"_a, "dz"_a, "slots"_a.noconvert(), "predictor"_a.noconvert(), "corrector"_a.noconvert(), "rows"_a.noconvert(), "divisor"_a.noconvert(), "phi_delta"_a.noconvert(), "phi_at"_a.noconvert(), "prefactor"_a.noconvert(), "density"_a.noconvert(), "taper"_a.noconvert(), "preionisation"_a.noconvert(), @@ -3438,10 +2995,10 @@ void bind_testing(nb::module_& testing) { "carrier"_a.noconvert()); testing.def( "adams_exponential_trial_at", - [](BoundState& self, const double z, const double dz, const RealInput nodes, + [](BoundWorkspace& owner, const double z, const double dz, const RealInput nodes, const IndexInput slots, const std::size_t order, const std::vector& orders, const bool compensated, - const RealInput carrier) { + const RealInput carrier) { TestState self(owner); auto weights = exponential_weights_at(nodes, slots, order, orders, compensated); carrier_frame(weights, carrier, weights.width - 1); const double end = z + dz; @@ -3455,49 +3012,49 @@ void bind_testing(nb::module_& testing) { } return real_output(std::move(norms), 1); }, - "state"_a, "z"_a, "dz"_a, "nodes"_a.noconvert(), "slots"_a.noconvert(), "order"_a, + "workspace"_a, "z"_a, "dz"_a, "nodes"_a.noconvert(), "slots"_a.noconvert(), "order"_a, "orders"_a, "compensated"_a, "carrier"_a.noconvert()); testing.def( "adams_exponential_accept", - [](BoundState& self, const double dz, const std::size_t free, - const IndexInput dense, const bool interpolate) { + [](BoundWorkspace& owner, const double dz, const std::size_t free, + const IndexInput dense, const bool interpolate) { TestState self(owner); auto slopes = adams_rows(dense); slopes.width = interpolate ? slopes.width + 1 : 0; const nb::gil_scoped_release release; self.open_state().adams_exponential_accept(dz, free, slopes); }, - "state"_a, "dz"_a, "free"_a, "dense"_a.noconvert(), "interpolate"_a); + "workspace"_a, "dz"_a, "free"_a, "dense"_a.noconvert(), "interpolate"_a); testing.def( "adams_start", - [](BoundState& self, const std::size_t slot, const RealInput phi_delta, + [](BoundWorkspace& owner, const std::size_t slot, const RealInput phi_delta, const RealInput phi_at, const RealInput prefactor, const RealInput density, const RealInput taper, const RealInput preionisation, - const RealInput raman_rates, const nb::dict material) { + const RealInput raman_rates, const nb::dict material) { TestState self(owner); const auto scalars = adams_scalars(phi_delta, phi_at, prefactor, density, taper, preionisation, raman_rates, material); const nb::gil_scoped_release release; self.open_state().adams_start(slot, scalars); }, - "state"_a, "slot"_a, "phi_delta"_a.noconvert(), "phi_at"_a.noconvert(), + "workspace"_a, "slot"_a, "phi_delta"_a.noconvert(), "phi_at"_a.noconvert(), "prefactor"_a.noconvert(), "density"_a.noconvert(), "taper"_a.noconvert(), "preionisation"_a.noconvert(), "raman_rates"_a.noconvert(), "material"_a); testing.def( "adams_compensation_start", - [](BoundState& self, const std::size_t slot, const RealInput rate) { + [](BoundWorkspace& owner, const std::size_t slot, const RealInput rate) { TestState self(owner); const auto weights = real_vector(rate); const nb::gil_scoped_release release; self.open_state().adams_compensation_start(slot, weights); }, - "state"_a, "slot"_a, "rate"_a.noconvert()); + "workspace"_a, "slot"_a, "rate"_a.noconvert()); testing.def( - "adams_hold", [](BoundState& self) { self.open_state().adams_hold(); }, - "state"_a); + "adams_hold", [](BoundWorkspace& owner) { TestState self(owner); self.open_state().adams_hold(); }, + "workspace"_a); testing.def( - "adams_restore", [](BoundState& self) { self.open_state().adams_restore(); }, - "state"_a); + "adams_restore", [](BoundWorkspace& owner) { TestState self(owner); self.open_state().adams_restore(); }, + "workspace"_a); testing.def( "adams_rows_to_host", - [](BoundState& self, const std::string& name) { + [](BoundWorkspace& owner, const std::string& name) { TestState self(owner); auto& state = self.open_state(); const auto extents = state.adams_row_extents(name); // The array's own storage is written once, as the host engine's copy is. @@ -3508,18 +3065,18 @@ void bind_testing(nb::module_& testing) { state.adams_rows_to_host(name, storage->data(), storage->size()); } auto* pointer = storage.get(); - nb::capsule owner(pointer, [](void* value) noexcept { + nb::capsule keeper(pointer, [](void* value) noexcept { const std::unique_ptr held( static_cast(value)); }); static_cast(storage.release()); // the capsule owns it now const std::array shape{extents[0], extents[1], extents[2]}; - return ComplexOutput(pointer->data(), shape.size(), shape.data(), owner); + return ComplexOutput(pointer->data(), shape.size(), shape.data(), keeper); }, - "state"_a, "name"_a); + "workspace"_a, "name"_a); testing.def( "adams_stage_scalars", - [](BoundState& self, const double z0, const double z1) { + [](BoundWorkspace& owner, const double z0, const double z1) { TestState self(owner); const auto trial = self.stage_trial(z0, z1); const auto& step = trial.step; // The first stage row's values; the test of the native evaluation reads @@ -3542,24 +3099,24 @@ void bind_testing(nb::module_& testing) { out["transform_weights"] = step.transform_weights; return out; }, - "state"_a, "z0"_a, "z1"_a); + "workspace"_a, "z0"_a, "z1"_a); testing.def( "adams_stage_rate", - [](BoundState& self, const double z) { return self.stage_rate(z); }, "state"_a, + [](BoundWorkspace& owner, const double z) { TestState self(owner); return self.stage_rate(z); }, "workspace"_a, "z"_a); testing.def( "has_stage_tables", - [](const BoundState& self) { return self.has_stage_tables(); }, "state"_a); + [](BoundWorkspace& owner) { TestState self(owner); return self.has_stage_tables(); }, "workspace"_a); testing.def( "table_rate_at", - [](BoundState& self, const double z, const bool before) { + [](BoundWorkspace& owner, const double z, const bool before) { TestState self(owner); const nb::gil_scoped_release release; self.table_rate_at(z, before); }, - "state"_a, "z"_a, "before"_a); + "workspace"_a, "z"_a, "before"_a); testing.def( "phase_sum_to_host", - [](BoundState& self, const RealInput weights) { + [](BoundWorkspace& owner, const RealInput weights) { TestState self(owner); const auto held = real_vector(weights); auto& state = self.open_state(); std::vector values; @@ -3569,33 +3126,197 @@ void bind_testing(nb::module_& testing) { } return complex_output(values, {self.columns(), values.size() / self.columns()}); }, - "state"_a, "weights"_a.noconvert()); - testing.def("promote_fsal", [](BoundState& self) { self.promote_fsal(); }, "state"_a); + "workspace"_a, "weights"_a.noconvert()); + testing.def("promote_fsal", [](BoundWorkspace& owner) { TestState self(owner); self.promote_fsal(); }, "workspace"_a); testing.def( "adams_march_run", - [](BoundState& self, const nb::dict march, const nb::dict bounds) { + [](BoundWorkspace& owner, const nb::dict march, const nb::dict bounds) { TestState self(owner); return self.march_run(march, bounds); }, - "state"_a, "march"_a, "bounds"_a); + "workspace"_a, "march"_a, "bounds"_a); testing.def( "rk_march_run", - [](BoundState& self, const nb::dict march, const nb::dict bounds) { + [](BoundWorkspace& owner, const nb::dict march, const nb::dict bounds) { TestState self(owner); return self.rk_march_run(march, bounds); }, - "state"_a, "march"_a, "bounds"_a); - // A test hook: fail the resident engine's `stage` after `after` more calls; - // `trial_source` fails inside the trial's source evaluation. + "workspace"_a, "march"_a, "bounds"_a); + // A Runge-Kutta trial's scaled error norm from its partials (solprop SEP 45 phase 2). testing.def( - "adams_march_fault", - [](BoundState& self, const std::string& stage, const std::size_t after, - const std::string& category) { self.march_fault(stage, after, category); }, - "state"_a, "stage"_a, "after"_a, "category"_a); + "rk_score", + [](const RealInput partials, const double rtol, const double atol) { + if (partials.ndim() != 2 || partials.shape(0) != 3) + throw std::invalid_argument("a trial's partials have shape (3, slots)"); + return native::rk::score(partials.data(), partials.shape(1), rtol, atol); + }, + "partials"_a, "rtol"_a, "atol"_a); + // The decision traces' configuration: a run's march policy and schedule, taken from + // its records without starting it. + testing.def( + "configure_march", + [](BoundWorkspace& owner, const nb::handle records) { + owner.workspace().configure_march( + native::records::read(records, "records")); + }, + "workspace"_a, "records"_a); + // Load a start into the state as a run would, for the tests that step it directly. + testing.def( + "load", + [](BoundWorkspace& owner, const ComplexInput field, const ComplexInput noise) { + auto& workspace = owner.workspace(); + const nb::gil_scoped_release release; + workspace.load(complex_span(field), complex_span(noise)); + }, + "workspace"_a, "field"_a.noconvert(), "noise"_a.noconvert()); + testing.def( + "field", + [](BoundWorkspace& owner) { + TestState self(owner); + auto& state = self.open_state(); + const auto count = self.elements(); + auto storage = native::crossing::host_buffer(2 * count); + { + const nb::gil_scoped_release release; + state.field_to_host({reinterpret_cast(storage.get()), count}); + } + return complex_buffer_output(std::move(storage), + {self.columns(), count / self.columns()}); + }, + "workspace"_a); + testing.def( + "finish", + [](BoundWorkspace& owner, const double dz) { + auto& state = owner.workspace().state(); + const nb::gil_scoped_release release; + state.finish(dz); + }, + "workspace"_a, "dz"_a); + testing.def( + "clear_fsal", + [](BoundWorkspace& owner) { owner.workspace().state().clear_fsal(); }, + "workspace"_a); + testing.def( + "set_absorber_quiet", + [](BoundWorkspace& owner, const bool quiet) { + owner.workspace().state().set_absorber_quiet(quiet); + }, + "workspace"_a, "quiet"_a); + // A Runge-Kutta trial on the stage tables at the setup's nodes, as the march takes + // it (solprop SEP 45 phase 2): its partials `(3, slots)`, its stages kept in the state. + testing.def( + "rk_trial", + [](BoundWorkspace& owner, const double z, const double dz) { + auto& workspace = owner.workspace(); + workspace.require_unleased(); + std::vector partials; + { + const nb::gil_scoped_release release; + partials = workspace.staged_trial(z, dz, false); + } + return real_output(std::move(partials), 3); + }, + "workspace"_a, "z"_a, "dz"_a); + // A weighted controller's norm of a trial's partials, as the march scores it. + testing.def( + "weighted_score", + [](BoundWorkspace& owner, const RealInput partials, const double rtol, + const double atol, const RealInput weights) { + if (partials.ndim() != 2 || partials.shape(0) != 3) + throw std::invalid_argument("a trial's partials have shape (3, slots)"); + const auto values = real_vector(partials); + const auto scale = real_vector(weights); + return native::engines::ResidentRungeKutta::weighted_norm( + owner.workspace().state(), values, rtol, atol, scale); + }, + "workspace"_a, "partials"_a.noconvert(), "rtol"_a, "atol"_a, + "weights"_a.noconvert()); + // A z table's value at `z` through the one slot cache (solprop SEP 29 G1). + testing.def( + "table_values", + [](BoundWorkspace& owner, const std::string& kind, const double z) { + auto& workspace = owner.workspace(); + auto& state = workspace.state(); + auto& slots = workspace.z_slots(); + if (!slots.present()) + throw std::logic_error("no z table's slots were configured"); + const auto known = native::names(static_cast(nullptr)); + const auto found = std::ranges::find_if( + known, [&kind](const auto& entry) { return kind == entry.first; }); + if (found == known.end()) + throw std::invalid_argument("a z table is phi, prefactor, rate or flux"); + std::vector values; + { + const nb::gil_scoped_release release; + const std::size_t slot = slots.load(state, {z}).front(); + values = state.table_terms_to_host(found->second, slot); + } + return complex_output(values, + {workspace.columns(), values.size() / workspace.columns()}); + }, + "workspace"_a, "kind"_a, "z"_a); + testing.def( + "table_evaluations", + [](BoundWorkspace& owner) { return owner.workspace().z_slots().evaluations; }, + "workspace"_a); + testing.def( + "prepare_raman", + [](BoundWorkspace& owner, const RealInput rates, const RealInput densities) { + if (rates.ndim() != 1 || rates.shape(0) != owner.raman_terms()) + throw std::invalid_argument("Raman decay rates must have shape (n_terms,)"); + const auto held_rates = real_vector(rates); + const auto held_densities = real_vector(densities); + auto& state = owner.workspace().state(); + const nb::gil_scoped_release release; + state.prepare_raman(held_rates, held_densities); + }, + "workspace"_a, "rates"_a.noconvert(), "densities"_a.noconvert()); + // Bind a run's monitor weights, the problem's occupancy and the edge's tables as a + // run's start binds them, for the tests that read the state directly. + testing.def( + "bind_monitor", + [](BoundWorkspace& owner, const nb::handle monitor, const nb::handle edge, + const nb::handle occupancy) { + const auto weights = + native::records::read(monitor, "monitor"); + const auto tables = + native::records::read>(edge, "edge"); + const auto buckets = + native::records::read>(occupancy, + "occupancy"); + auto& state = owner.workspace().state(); + // Holding the interpreter lock: a strip's plan goes through FFTW's planner. + state.bind_monitor(weights.weights, weights.column_weights); + if (weights.split && buckets) + state.bind_occupancy(buckets->buckets, buckets->count); + if (tables) { + state.bind_edge(tables->faces, tables->clip, tables->totals, + tables->synthesis, tables->first_row); + if (tables->lines) + state.bind_edge_lines(*tables->lines); + } + }, + "workspace"_a, "monitor"_a, "edge"_a.none(), "occupancy"_a.none()); + testing.def( + "edge_reading", + [](BoundWorkspace& owner, const bool faces, const bool whole, const bool totals, + const bool strip, const bool current) { + auto& state = owner.workspace().state(); + native::EdgeNumbers numbers; + { + const nb::gil_scoped_release release; + numbers = state.edge_reading(faces, whole, totals, strip, current); + } + return nb::make_tuple(real_output(std::move(numbers.sums), 1), + real_output(std::move(numbers.columns), 1), + real_output(std::move(numbers.strip), 1), + numbers.current); + }, + "workspace"_a, "faces"_a, "whole"_a, "totals"_a, "strip"_a, "current"_a); testing.def( "statistics", - [](BoundState& self, const std::uint64_t flags, const RealInput windows, + [](BoundWorkspace& owner, const std::uint64_t flags, const RealInput windows, const RealInput on_axis, const double density, const double taper, const double preionisation, const double intensity_factor, - const nb::object channel_preionisation, const nb::object power_weight) { + const nb::object channel_preionisation, const nb::object power_weight) { TestState self(owner); const auto held_weight = power_weight.is_none() ? std::vector{} : real_vector(exact_array(power_weight)); @@ -3614,13 +3335,13 @@ void bind_testing(nb::module_& testing) { } return real_output(std::move(values), 1); }, - "state"_a, "flags"_a, "windows"_a.noconvert(), "on_axis"_a.noconvert(), + "workspace"_a, "flags"_a, "windows"_a.noconvert(), "on_axis"_a.noconvert(), "density"_a, "taper"_a, "preionisation"_a, "intensity_factor"_a, "channel_preionisation"_a = nb::none(), "power_weight"_a = nb::none()); testing.def( "spatial_statistics", - [](BoundState& self, const std::uint64_t flags, const double intensity_factor, - const double z) { + [](BoundWorkspace& owner, const std::uint64_t flags, const double intensity_factor, + const double z) { TestState self(owner); std::vector values; { const nb::gil_scoped_release release; @@ -3628,10 +3349,10 @@ void bind_testing(nb::module_& testing) { } return real_output(std::move(values), 1); }, - "state"_a, "flags"_a, "intensity_factor"_a, "z"_a); + "workspace"_a, "flags"_a, "intensity_factor"_a, "z"_a); testing.def( "planned_statistics", - [](BoundState& self, const BoundStatisticsPlan& plan, const double z) { + [](BoundWorkspace& owner, const BoundStatisticsPlan& plan, const double z) { TestState self(owner); const auto& held = plan.plan(); std::vector values; { @@ -3640,12 +3361,12 @@ void bind_testing(nb::module_& testing) { } return real_output(std::move(values), 1); }, - "state"_a, "plan"_a, "z"_a); + "workspace"_a, "plan"_a, "z"_a); testing.def( "plane_fluence_trace", - [](BoundState& self, const double center_x, const double center_y, + [](BoundWorkspace& owner, const double center_x, const double center_y, const double dx, const double dy, const double extent, const double spacing, - const std::size_t n_radii, const RealInput cosines, const RealInput sines) { + const std::size_t n_radii, const RealInput cosines, const RealInput sines) { TestState self(owner); if (cosines.ndim() != 1 || sines.ndim() != 1) throw std::invalid_argument("fluence rings must be one-dimensional"); const auto held_cosines = real_vector(cosines); @@ -3658,11 +3379,11 @@ void bind_testing(nb::module_& testing) { } return real_output(std::move(values), 1); }, - "state"_a, "center_x"_a, "center_y"_a, "dx"_a, "dy"_a, "extent"_a, "spacing"_a, + "workspace"_a, "center_x"_a, "center_y"_a, "dx"_a, "dy"_a, "extent"_a, "spacing"_a, "n_radii"_a, "cosines"_a.noconvert(), "sines"_a.noconvert()); testing.def( "axis_spectrum", - [](BoundState& self, const RealInput matrix) { + [](BoundWorkspace& owner, const RealInput matrix) { TestState self(owner); if (matrix.ndim() != 2) throw std::invalid_argument("an on-axis matrix must be two-dimensional"); const auto held = real_vector(matrix); @@ -3673,10 +3394,10 @@ void bind_testing(nb::module_& testing) { } return complex_output(values, {values.size()}); }, - "state"_a, "matrix"_a.noconvert()); + "workspace"_a, "matrix"_a.noconvert()); testing.def( "monitor_reading", - [](BoundState& self) { + [](BoundWorkspace& owner) { TestState self(owner); std::vector values; { const nb::gil_scoped_release release; @@ -3684,10 +3405,10 @@ void bind_testing(nb::module_& testing) { } return real_output(std::move(values), 1); }, - "state"_a); + "workspace"_a); testing.def( - "quadrature_error", [](BoundState& self) { return self.quadrature_error(); }, - "state"_a); + "quadrature_error", [](BoundWorkspace& owner) { TestState self(owner); return self.quadrature_error(); }, + "workspace"_a); } } // namespace @@ -3700,19 +3421,6 @@ NB_MODULE(_core, module_) { const nb::exception backend_refusal(module_, "BackendRefusal"); module_.doc() = "Private nanobind seam for solprop-native"; - module_.def("initialize_runtime", &initialize_kokkos, "threads"_a, "kernels"_a = 0, - "fft"_a = 0, "raman_fft"_a = 0, "raman_tail_fft"_a = 0, - "band_tiles"_a = -1); - module_.def("fit_blas_threads", &fit_blas_threads, "threads"_a); - module_.def("register_host_blas", ®ister_host_blas); - module_.def( - "rk_score", - [](const RealInput partials, const double rtol, const double atol) { - if (partials.ndim() != 2 || partials.shape(0) != 3) - throw std::invalid_argument("a trial's partials have shape (3, slots)"); - return native::rk::score(partials.data(), partials.shape(1), rtol, atol); - }, - "partials"_a, "rtol"_a, "atol"_a); module_.def("available_device_memory", []() -> nb::object { #ifdef KOKKOS_ENABLE_CUDA std::size_t free_bytes = 0; @@ -3750,8 +3458,6 @@ NB_MODULE(_core, module_) { nb::arg("key"), nb::arg("wisdom"), nb::arg("effort")); module_.def("reference_stream_copies", &native::reference_stream_copies, "elements"_a, "warm"_a, "repeats"_a); - module_.def("configure_native_spin", &native::configure_native_spin, - "milliseconds"_a); module_.def("build_record", &build_record); // FFTW's wisdom as text, for the plan store the adapter owns // (solprop_native._wisdom). None where there is none to keep: a device build, @@ -3765,384 +3471,6 @@ NB_MODULE(_core, module_) { #endif }); bind_problem(module_); - nb::class_(module_, "State") - .def(nb::init(), "problem"_a) - .def( - "set_initial", - [](BoundState& self, const ComplexInput field, const ComplexInput noise) { - // Read in place: the arguments keep the arrays alive for the call. - const nb::gil_scoped_release release; - self.set_initial(complex_span(field), complex_span(noise)); - }, - "field"_a.noconvert(), "noise"_a.noconvert()) - .def( - "rk_trial", - [](BoundState& self, const double z, const double dz, - const std::vector& nodes, const bool prepare_only) { - std::vector partials; - { - const nb::gil_scoped_release release; - partials = self.rk_trial(z, dz, nodes, prepare_only); - } - return prepare_only ? nb::object(nb::none()) - : nb::cast(real_output(std::move(partials), 3)); - }, - "z"_a, "dz"_a, "nodes"_a, "prepare_only"_a = false) - // solprop SEP 24 phase 3: the low-storage march's resident step. - .def( - "low_storage_step", - [](BoundState& self, const double dz, const RealInput phi_delta, - const RealInput phi_at, const RealInput prefactor, const RealInput density, - const RealInput taper, const RealInput preionisation, - const RealInput raman_rates, const nb::dict material, - const bool rebuild_table) { - if (self.raman() && - (raman_rates.ndim() != 2 || raman_rates.shape(0) != self.stages() || - raman_rates.shape(1) != self.raman_terms())) - throw std::invalid_argument( - "raman_rates must have shape (n_stages, n_terms)"); - const auto scalars = - adams_scalars(phi_delta, phi_at, prefactor, density, taper, - preionisation, raman_rates, material); - auto& state = self.open_state(); - const nb::gil_scoped_release release; - return state.low_storage_step(dz, scalars, rebuild_table); - }, - "dz"_a, "phi_delta"_a.noconvert(), "phi_at"_a.noconvert(), - "prefactor"_a.noconvert(), "density"_a.noconvert(), "taper"_a.noconvert(), - "preionisation"_a.noconvert(), "raman_rates"_a.noconvert(), "material"_a, - "rebuild_table"_a) - // solprop SEP 16 phase 3b: the Adams history resident in the engine. - .def( - "adams_allocate", - [](BoundState& self, const std::size_t slots, const bool compensated, - const bool interpolate) { - self.open_state().adams_allocate(slots, compensated, interpolate); - }, - "slots"_a, "compensated"_a = false, "interpolate"_a = true) - .def( - "adams_scale", - [](BoundState& self, const double rtol, const double atol, - const RealInput weights) { - const auto values = real_vector(weights); - const nb::gil_scoped_release release; - self.open_state().adams_scale(rtol, atol, values); - }, - "rtol"_a, "atol"_a, "weights"_a.noconvert()) - // solprop SEP 29 G2: the resident history's persistent rows across a resume. - .def("adams_row_names", - [](BoundState& self) { return self.open_state().adams_row_names(); }) - .def( - "adams_rows_from_host", - [](BoundState& self, const std::string& name, const ComplexInput rows) { - auto& state = self.open_state(); - // The extents are checked against the row's view before any copy. - const auto extents = state.adams_row_extents(name); - if (rows.ndim() != 3 || rows.shape(0) != extents[0] || - rows.shape(1) != extents[1] || rows.shape(2) != extents[2]) - native::refuse("the Adams history row '", name, "' must have shape (", - extents[0], ", ", extents[1], ", ", extents[2], ")"); - const auto values = complex_vector(rows); - const nb::gil_scoped_release release; - state.adams_rows_from_host(name, values); - }, - "name"_a, "rows"_a.noconvert()) - // solprop SEP 29 G1: the general z tables, resident and evaluated natively. - .def( - "table_upload", - [](BoundState& self, const std::string& kind, const RealInput edges, - const double lower, const double upper, - const nb::ndarray, nb::ndim<3>, nb::c_contig, - nb::device::cpu> - coefficients) { - if (edges.ndim() != 1) - throw std::invalid_argument( - "z table breakpoints must be one-dimensional"); - auto& state = self.open_state(); - const nb::gil_scoped_release release; - state.table_upload(table_kind(kind), real_vector(edges), lower, upper, - coefficients.data(), coefficients.shape(0), - coefficients.shape(1), coefficients.shape(2)); - }, - "kind"_a, "edges"_a.noconvert(), "lower"_a, "upper"_a, - "coefficients"_a.noconvert()) - .def( - "table_terms_to_host", - [](BoundState& self, const std::string& kind, const std::size_t slot) { - auto& state = self.open_state(); - std::vector values; - { - const nb::gil_scoped_release release; - values = state.table_terms_to_host(table_kind(kind), slot); - } - return complex_output(values, - {self.columns(), values.size() / self.columns()}); - }, - "kind"_a, "slot"_a) - // solprop SEP 39 phase 1: the trial's tables, stage scalars and rate formed - // natively from the nodes and the tables uploaded once per run. - .def( - "adams_stage_tables", - [](BoundState& self, const nb::dict tables) { - self.set_stage_tables(stage_tables_from(tables)); - }, - "tables"_a) - .def("table_slots", &BoundState::table_slots, "phi"_a, "prefactor"_a, "slots"_a, - "rate"_a) - .def( - "table_load", - [](BoundState& self, const std::vector& positions) { - const nb::gil_scoped_release release; - return self.table_load(positions); - }, - "positions"_a) - .def("table_evaluations", &BoundState::table_evaluations) - // solprop SEP 39 phase 2: the native Adams march. - .def( - "adams_march_configure", - [](BoundState& self, const nb::dict policy, const bool fused, - const bool compensated, const bool interpolate, const RealInput steps, - const RealInput edges) { - self.march_configure( - march_policy_from(policy), fused, compensated, interpolate, - {.steps = real_vector(steps), .edges = real_vector(edges)}); - }, - "policy"_a, "fused"_a, "compensated"_a, "interpolate"_a, - "steps"_a.noconvert(), "edges"_a.noconvert()) - .def("bind_host_source", &BoundState::bind_host_source, "owner"_a.none()) - .def( - "rk_march_configure", - [](BoundState& self, const nb::dict policy, const std::vector& nodes, - const double rtol, const double atol, const RealInput steps, - const RealInput edges) { - self.rk_march_configure(rk_policy_from(policy), nodes, rtol, atol, - real_vector(steps), real_vector(edges)); - }, - "policy"_a, "nodes"_a, "rtol"_a, "atol"_a, "steps"_a.noconvert(), - "edges"_a.noconvert()) - .def("low_storage_configure", &BoundState::low_storage_configure, "flows"_a, - "separable"_a, "origin"_a) - .def("start_session", &start_session, "kind"_a, "state"_a, "plan"_a, "z"_a, - nb::keep_alive<0, 1>()) - .def("rk_weights_configure", &BoundState::rk_weights_configure, "weights"_a) - .def( - "rk_weighted_score", - [](BoundState& self, const RealInput partials, const double rtol, - const double atol) { - if (partials.ndim() != 2 || partials.shape(0) != 3) - throw std::invalid_argument("a trial's partials have shape (3, slots)"); - return self.rk_weighted_score(partials.data(), partials.shape(1), rtol, - atol); - }, - "partials"_a.noconvert(), "rtol"_a, "atol"_a) - .def("flow_guard_configure", &BoundState::flow_guard_configure, "row_sum"_a, - "condition_bound"_a, "taylor_scale"_a, "max_squarings"_a, "allowance"_a) - .def( - "prepare_raman", - [](BoundState& self, const RealInput rates, const nb::object densities) { - if (rates.ndim() != 1 || rates.shape(0) != self.raman_terms()) - throw std::invalid_argument( - "Raman decay rates must have shape (n_terms,)"); - const auto held_rates = real_vector(rates); - const auto held_densities = - densities.is_none() ? std::vector{} - : real_vector(exact_array(densities)); - const nb::gil_scoped_release release; - self.prepare_raman(held_rates, held_densities); - }, - "rates"_a.noconvert(), "densities"_a = nb::none()) - .def( - "aperture_statistics", - [](BoundState& self, const std::uint64_t flags, const RealInput apertures, - const int exponent, const RealInput regions, - const double intensity_factor) { - if (apertures.ndim() != 2 || regions.ndim() != 2 || regions.shape(1) != 4) - throw std::invalid_argument( - "aperture tables must be (n_apertures, 11 + n_omega) and regions " - "(n_regions, 4)"); - const auto held_apertures = real_vector(apertures); - const auto held_regions = real_vector(regions); - std::vector values; - { - const nb::gil_scoped_release release; - values = self.aperture_statistics(flags, held_apertures, exponent, - held_regions, intensity_factor); - } - return real_output(std::move(values), 1); - }, - "flags"_a, "apertures"_a.noconvert(), "exponent"_a, "regions"_a.noconvert(), - "intensity_factor"_a) - .def( - "finish", - [](BoundState& self, const double dz) { - const nb::gil_scoped_release release; - self.finish(dz); - }, - "dz"_a) - .def("clear_fsal", [](BoundState& self) { self.clear_fsal(); }) - .def( - "set_absorber_quiet", - [](BoundState& self, const bool quiet) { self.set_absorber_quiet(quiet); }, - "quiet"_a) - // solprop SEP 21: the boundary monitor's weights, and its five numbers and the - // split's removal read where the state lives. - .def( - "bind_monitor", - [](BoundState& self, const RealInput weights, - const RealInput column_weights) { - const auto held_weights = real_vector(weights); - const auto held_columns = real_vector(column_weights); - const nb::gil_scoped_release release; - self.bind_monitor(held_weights, held_columns); - }, - "weights"_a.noconvert(), "column_weights"_a.noconvert()) - .def("unbind_monitor", [](BoundState& self) { self.unbind_monitor(); }) - // solprop #440: the split collar's walk-off bucket of each bin, whose energy - // per bucket a reading then returns beside the five. - .def( - "bind_occupancy", - [](BoundState& self, const ByteInput buckets, const std::size_t count) { - const auto count_in = element_count(buckets); - const std::vector held(buckets.data(), - buckets.data() + count_in); - const nb::gil_scoped_release release; - self.bind_occupancy(held, count); - }, - "buckets"_a.noconvert(), "count"_a) - // solprop SEP 44: the bytes through the state's crossings, each way. - .def("crossed_bytes", - [](BoundState& self) { - const auto crossed = self.crossed_bytes(); - return nb::make_tuple(crossed.to_host, crossed.from_host); - }) - // solprop SEP 44: the transverse edge's reading, where the state lives. - .def( - "bind_edge", - [](BoundState& self, const RealInput faces, const RealInput clip, - const RealInput totals, const RealInput synthesis, - const std::size_t first_row) { - const auto held_faces = real_vector(faces); - const auto held_clip = real_vector(clip); - const auto held_totals = real_vector(totals); - const auto held_synthesis = real_vector(synthesis); - const nb::gil_scoped_release release; - self.bind_edge(held_faces, held_clip, held_totals, held_synthesis, - first_row); - }, - "faces"_a.noconvert(), "clip"_a.noconvert(), "totals"_a.noconvert(), - "synthesis"_a.noconvert(), "first_row"_a) - .def( - "edge_reading", - [](BoundState& self, const bool faces, const bool whole, const bool totals, - const bool strip, const bool current) { - native::EdgeNumbers numbers; - { - const nb::gil_scoped_release release; - numbers = self.edge_reading(faces, whole, totals, strip, current); - } - return nb::make_tuple(real_output(std::move(numbers.sums), 1), - real_output(std::move(numbers.columns), 1), - real_output(std::move(numbers.strip), 1), - numbers.current); - }, - "faces"_a, "whole"_a, "totals"_a, "strip"_a, "current"_a) - .def( - "bind_edge_lines", - [](BoundState& self, const IndexInput axes, const IndexInput counts, - const IndexInput positions, const RealInput windows, - const IndexInput inward, const RealInput factors, const RealInput measures, - const IndexInput onsets, const RealInput steps, const double k_min, - const RealInput scale, const std::size_t batch_bytes) { - native::EdgeLines lines; - lines.axes = index_vector(axes); - lines.counts = index_vector(counts); - lines.positions = index_vector(positions); - lines.windows = real_vector(windows); - lines.inward = index_vector(inward); - lines.factors = real_vector(factors); - lines.measures = real_vector(measures); - lines.onsets = index_vector(onsets); - lines.steps = real_vector(steps); - lines.k_min = k_min; - lines.scale = real_vector(scale); - lines.batch_bytes = batch_bytes; - // Holding the GIL: a strip's plan goes through FFTW's planner, which the - // GIL serialises against another thread's backend being built. - self.bind_edge_lines(lines); - }, - "axes"_a.noconvert(), "counts"_a.noconvert(), "positions"_a.noconvert(), - "windows"_a.noconvert(), "inward"_a.noconvert(), "factors"_a.noconvert(), - "measures"_a.noconvert(), "onsets"_a.noconvert(), "steps"_a.noconvert(), - "k_min"_a, "scale"_a.noconvert(), "batch_bytes"_a) - .def( - "set_crossing_workers", - [](BoundState& self, const std::size_t workers) { - self.set_crossing_workers(workers); - }, - "workers"_a) - .def("field_to_host", - [](BoundState& self) { - // The state crosses once, straight into the returned array's memory. - const auto count = self.elements(); - auto storage = native::crossing::host_buffer(2 * count); - { - const nb::gil_scoped_release release; - self.field_to_host( - {reinterpret_cast(storage.get()), count}); - } - return complex_buffer_output(std::move(storage), - {self.columns(), count / self.columns()}); - }) - .def_prop_ro("dispersive_path", - [](BoundState& self) { return self.dispersive_path(); }) - .def("memory_ledger", - [](BoundState& self) { - nb::dict result; - for (const auto& [name, bytes] : self.built().memory_ledger()) { - result[name.c_str()] = bytes; - } - return result; - }) - .def_prop_ro("planning_seconds", - [](BoundState& self) { return self.built().planning_seconds(); }) - .def_prop_ro("raman_fft_provider", - [](BoundState& self) { return self.built().raman_fft_provider(); }) - .def_prop_ro("execution_sizing", - [](BoundState& self) { return self.built().execution_sizing(); }) - .def_prop_ro("cpu_execution", - [](BoundState& self) { - return cpu_execution_dict(self.built().cpu_execution()); - }) - .def_prop_ro("fft_planning", - [](BoundState& self) { - return fft_planning_dict(self.built().fft_planning()); - }) - .def_prop_ro("raman_fft_tasks", - [](BoundState& self) { return self.built().raman_fft_tasks(); }) - .def_prop_ro( - "raman_planning_seconds", - [](BoundState& self) { return self.built().raman_planning_seconds(); }) - .def_prop_ro( - "raman_kernel_transforms", - [](BoundState& self) { return self.built().raman_kernel_transforms(); }) - .def_prop_ro("fsal_ready", - [](BoundState& self) { return self.built().fsal_ready(); }) - .def_prop_ro( - "rk_source_evaluations", - [](BoundState& self) { return self.built().rk_source_evaluations(); }) - .def_prop_ro("axis_scans", - [](BoundState& self) { return self.built().axis_scans(); }) - .def("quadrature_peak", [](BoundState& self) { return self.quadrature_peak(); }) - .def_prop_ro("synthesis_provider", - [](BoundState& self) { return self.built().synthesis_provider(); }) - .def_prop_ro("projection_provider", - [](BoundState& self) { return self.built().projection_provider(); }) - .def_prop_ro("gemm_shape_policy", - [](BoundState& self) { return self.built().gemm_shape_policy(); }) - .def_prop_ro("response_team_size", - [](BoundState& self) { return self.built().response_team_size(); }) - .def_prop_ro("closed", &BoundState::closed) - .def("close", &BoundState::close, nb::call_guard()); // solprop SEP 47: the native execution session and its compact event records. const nb::exception lifecycle_error( module_, "SessionLifecycleError", PyExc_RuntimeError); @@ -4251,52 +3579,19 @@ NB_MODULE(_core, module_) { .def("advance", &BoundSession::advance, "work_limit"_a, "deadline"_a) .def("acknowledge", &BoundSession::acknowledge, "sequence"_a, nb::call_guard()) - .def("export", &BoundSession::export_field, "sequence"_a, "generation"_a, - "power"_a, "optics"_a, "weight"_a.none(), "out"_a) .def("request_stop", &BoundSession::request_stop, nb::call_guard()) .def("request_snapshot", &BoundSession::request_snapshot) .def("status", &BoundSession::status) - .def_prop_ro("elements", &BoundSession::elements) - .def("monitor_record", &BoundSession::monitor_record) - .def("monitor_cap", &BoundSession::monitor_cap) - .def("quadrature_peak", &BoundSession::quadrature_peak) - .def("continue_monitor", &BoundSession::continue_monitor, "record"_a, "plane"_a, - "unwatched"_a, "edge_record"_a) - .def("edge_record", &BoundSession::edge_record) .def("march_state", &BoundSession::march_state, "since"_a) - .def("march_snapshot", &BoundSession::march_snapshot, "sequence"_a, - "generation"_a) - .def("table_phi", &BoundSession::table_phi, "sequence"_a, "generation"_a, "z"_a) .def("fail_outside", &BoundSession::fail_outside) // solprop SEP 52 section 5.3: a ticket is `(sequence, generation)`; a recipe is // `{"power", "optics", "weight"}`. - .def( - "export", - [](BoundSession& self, const std::pair ticket, - const nb::dict recipe, - nb::ndarray, nb::c_contig, nb::device::cpu> out) { - std::optional weight; - if (recipe.contains("weight") && !recipe["weight"].is_none()) - weight = exact_array(recipe["weight"]); - self.export_field(ticket.first, ticket.second, - nb::cast(recipe["power"]), - nb::cast(recipe["optics"]), weight, out); - }, - "ticket"_a, "recipe"_a, "out"_a) - .def( - "snapshot", - [](BoundSession& self, const std::pair ticket) { - return self.march_snapshot(ticket.first, ticket.second); - }, - "ticket"_a) - .def( - "noise_phase", - [](BoundSession& self, const std::pair ticket, - const double z) { return self.table_phi(ticket.first, ticket.second, z); }, - "ticket"_a, "z"_a) + .def("export", &BoundSession::export_field, "ticket"_a, "recipe"_a, "out"_a) + .def("snapshot", &BoundSession::snapshot, "ticket"_a) + .def("noise_phase", &BoundSession::noise_phase, "ticket"_a, "z"_a) .def("records", &BoundSession::records) - .def("continue_with", &BoundSession::continue_with, "continuation"_a) + .def("continue_monitor", &BoundSession::continue_monitor, "continuation"_a) .def("close", &BoundSession::close, nb::call_guard()); // solprop SEP 52 section 5.3: the new seam -- one workspace a problem, one run record // a start, the probe, and the tables every record is read by. @@ -4313,11 +3608,11 @@ NB_MODULE(_core, module_) { .def(nb::init(), "problem"_a) .def("start", &BoundWorkspace::start, "run"_a, "host_source"_a.none() = nb::none(), nb::keep_alive<0, 1>()) - .def("probe", &BoundWorkspace::probe, "start"_a, nb::keep_alive<0, 1>()) + .def("probe", &BoundWorkspace::probe, "start"_a, + "host_source"_a.none() = nb::none(), nb::keep_alive<0, 1>()) .def("diagnostics", &BoundWorkspace::diagnostics) - .def("unbind_host_source", &BoundWorkspace::unbind_host_source) .def_prop_ro("closed", &BoundWorkspace::closed) - .def("close", &BoundWorkspace::close, nb::call_guard()); + .def("close", &BoundWorkspace::close_from_python); module_.def("configure_runtime", &configure_runtime, "record"_a); module_.def("schemas", &schemas); auto testing = diff --git a/native/src/general/trial.cpp b/native/src/general/trial.cpp index d5f215b4c..95309f6b5 100644 --- a/native/src/general/trial.cpp +++ b/native/src/general/trial.cpp @@ -2032,7 +2032,10 @@ ComplexView3 GeneralWorkspace::adams_row_view(const std::string& name) const { } std::vector GeneralWorkspace::adams_row_names() const { - require_adams(); + // A fact of the allocation, read before any field is loaded (the workspace's + // diagnostics). + if (adams_store_.extent(0) == 0) + throw std::logic_error("the resident Adams history is not allocated"); std::vector names{"store"}; if (adams_states_.extent(0) != 0) names.insert(names.end(), {"states", "rates"}); diff --git a/native/src/solprop_native/__init__.py b/native/src/solprop_native/__init__.py index bae2dd209..34e811202 100644 --- a/native/src/solprop_native/__init__.py +++ b/native/src/solprop_native/__init__.py @@ -173,15 +173,31 @@ def _band_request() -> int: return count -_core.initialize_runtime( - _REQUESTED_THREADS, - _pool_request("SOLPROP_NATIVE_KERNEL_THREADS"), - _pool_request("SOLPROP_NATIVE_FFT_THREADS"), - _pool_request("SOLPROP_NATIVE_RAMAN_FFT_THREADS"), - _pool_request("SOLPROP_NATIVE_RAMAN_TAIL_FFT_THREADS"), - _band_request(), +# The runtime as one record (solprop SEP 52 section 5.3): the Kokkos pools, the spin, +# and a host OpenBLAS fitted to the Kokkos pool unless its thread count is set +# explicitly. A pthreads OpenBLAS runs its own pool beside Kokkos's and oversubscribes +# the cores (2 to 75 times slower on the modal and wall cases), so it is held to one +# thread; an OpenMP OpenBLAS shares the runtime and is capped at the Kokkos thread +# count, and at the budget where SOLPROP_OVERSUBSCRIBE took Kokkos past it. A compact +# problem's products then run on one OpenBLAS thread (``CpuTeamScope``). +_core.configure_runtime( + { + "threads": _REQUESTED_THREADS, + "kernels": _pool_request("SOLPROP_NATIVE_KERNEL_THREADS"), + "fft": _pool_request("SOLPROP_NATIVE_FFT_THREADS"), + "raman_fft": _pool_request("SOLPROP_NATIVE_RAMAN_FFT_THREADS"), + "raman_tail_fft": _pool_request("SOLPROP_NATIVE_RAMAN_TAIL_FFT_THREADS"), + "band_tiles": _band_request(), + "spin_milliseconds": _WAIT.spin_milliseconds, + "blas_threads": None + if any( + os.environ.get(name, "").strip() + for name in ("OPENBLAS_NUM_THREADS", "GOTO_NUM_THREADS", "OMP_NUM_THREADS") + ) + else min(_REQUESTED_THREADS, THREAD_BUDGET.threads), + "host_blas": True, + } ) -_core.configure_native_spin(_WAIT.spin_milliseconds) # The built-in table's CPU execution record for this process (solprop SEP 46 section # 6.11): its operating system's values, divided on Apple silicon's spinning top tier, @@ -240,20 +256,6 @@ def refresh_profile() -> str: return source -# Fit a host OpenBLAS to the Kokkos pool unless its thread count is set explicitly. A -# pthreads OpenBLAS runs its own pool beside Kokkos's and oversubscribes the cores (2 to -# 75 times slower on the modal and wall cases), so it is held to one thread; an OpenMP -# OpenBLAS shares the runtime and is capped at the Kokkos thread count, and at the -# budget where SOLPROP_OVERSUBSCRIBE took Kokkos past it. -if not any( - os.environ.get(name, "").strip() - for name in ("OPENBLAS_NUM_THREADS", "GOTO_NUM_THREADS", "OMP_NUM_THREADS") -): - _core.fit_blas_threads(min(_REQUESTED_THREADS, THREAD_BUDGET.threads)) -# A compact problem's products then run on one OpenBLAS thread (``CpuTeamScope``). -_core.register_host_blas() - - @dataclass(frozen=True) class BuildInfo: """Immutable build and execution provenance for this extension. diff --git a/native/src/solprop_native/_probe.py b/native/src/solprop_native/_probe.py index 64ba56cdb..62b71ba1a 100644 --- a/native/src/solprop_native/_probe.py +++ b/native/src/solprop_native/_probe.py @@ -2,14 +2,15 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""Single trials of a loaded native run, committing nothing (solprop SEP 47 6.6). +"""Single trials of a loaded native run, committing nothing (solprop SEP 52 5.5). ``Simulation.estimate`` and the SEP 46 calibration time one step's arithmetic from a -run's start (:meth:`solprop.backends.protocol.Backend.timing_probe`). The probe here is -the native backend's: a Runge-Kutta trial on the staged rows (``rk_trial``, solprop -SEP 45), which leaves the loaded state, position and history alone, and a readback of -its end state for the stage-2 refinement's plan comparison; or, for the low-storage -march (SEP 24), one step of the resident registers, which accepts in place. +run's start (:meth:`solprop.backends.protocol.Backend.timing_probe`). The probe here +wraps the workspace's own (``_core.Workspace.probe``): a Runge-Kutta trial on the +stage tables, which leaves the loaded state, position and history alone, and a +readback of its end state for the stage-2 refinement's plan comparison; or, for the +low-storage march (SEP 24), one step of the resident registers, which accepts in place, +whose field is refused and whose workspace closes with the probe. """ from __future__ import annotations @@ -18,10 +19,9 @@ import numpy as np import numpy.typing as npt -from solprop.exceptions import BackendError -from solprop.noise import NoiseRealisation -from solprop.stepper.low_storage import LowStorageRungeKutta +from solprop.exceptions import BackendError, ConvergenceError +from . import _core from ._load import Loaded if TYPE_CHECKING: @@ -34,16 +34,13 @@ class NativeProbe: """The native backend's :class:`~solprop.backends.protocol.TimingProbe`.""" def __init__( - self, - backend: NativeBackend, - loaded: Loaded, - noise: NoiseRealisation | None, + self, backend: NativeBackend, probe: _core.Probe, loaded: Loaded ) -> None: - """Hold the loaded backend; no trial is taken yet.""" + """Hold the workspace's probe over the loaded start; no trial is taken yet.""" self._backend = backend - self._loaded = loaded - self._noise = noise - self._length: float | None = None + self._probe = probe + self._z = float(loaded.z) + self._cursor = int(loaded.cursor) def trial(self, z: float | None = None, dz: float | None = None) -> None: """Take one trial step and keep its end state for :meth:`field`. @@ -53,48 +50,36 @@ def trial(self, z: float | None = None, dz: float | None = None) -> None: scheduled step at the loaded position for the low-storage march. """ backend = self._backend - start = self._loaded.z if z is None else float(z) stepper = backend._stepper # pyright: ignore[reportPrivateUsage] - the owner's policy - engine = backend._resident_low_storage # pyright: ignore[reportPrivateUsage] - if engine is not None: + start = self._z if z is None else float(z) + if self._probe.low_storage and dz is None: schedule = stepper.schedule assert schedule is not None # the translation refuses the march without one - index = min(self._loaded.cursor, schedule.n_steps - 1) - length = float(schedule.steps[index]) if dz is None else float(dz) - engine.step(start, length) - method = stepper.integrator - assert isinstance(method, LowStorageRungeKutta) - backend._low_storage_evaluations += method.evaluations # pyright: ignore[reportPrivateUsage] - return - length = float(stepper.dz_init) if dz is None else float(dz) - backend._trial_step(start, length) # pyright: ignore[reportPrivateUsage] - self._length = length + length = float(schedule.steps[min(self._cursor, schedule.n_steps - 1)]) + else: + length = float(stepper.dz_init) if dz is None else float(dz) + try: + self._probe.trial(start, length) + except _core.EnvelopeConvergenceError as error: + raise ConvergenceError(str(error)) from error + except _core.BackendRefusal as error: + raise BackendError(str(error)) from error + if self._probe.low_storage: + backend._low_storage_evaluations = int(self._probe.evaluations) # pyright: ignore[reportPrivateUsage] def field(self) -> npt.NDArray[np.complex128]: """Return the last trial's end state on the host, as a kept step would be. - The trial lives in the native state, which only finishing the step there (the - band mask, and the split-step absorber where it runs) can read back: the loaded - state is kept first and loaded again after, exactly, so that the probe still - commits nothing. + The trial lives in the workspace, which only finishing the step there (the + band mask, and the split-step absorber where it runs) can read back: the + loaded state is kept first and loaded again after, exactly, so that the probe + still commits nothing. - Returns: an owning copy, internal units and the FFT convention, shape ``(n_modes, n_pol, n_omega)``. """ - backend = self._backend - if backend._resident_low_storage is not None: # pyright: ignore[reportPrivateUsage] - 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") - native = backend._native_state # pyright: ignore[reportPrivateUsage] - kept = np.array(backend._observed_field(native)) # pyright: ignore[reportPrivateUsage] - finished = backend._finish(native, self._length) # pyright: ignore[reportPrivateUsage] - field = np.array(backend._observed_field(finished)) # pyright: ignore[reportPrivateUsage] - # The kept state already carries any `input` draw: a resume adds none. - backend._load(kept, self._noise, z=self._loaded.z, resume=True) # pyright: ignore[reportPrivateUsage] - self._length = None - return field + try: + field = self._probe.field() + except _core.BackendRefusal as error: + raise BackendError(str(error)) from error + return field.reshape(self._backend._problem.shape) # pyright: ignore[reportPrivateUsage] diff --git a/native/src/solprop_native/_records.py b/native/src/solprop_native/_records.py deleted file mode 100644 index 9849e794e..000000000 --- a/native/src/solprop_native/_records.py +++ /dev/null @@ -1,199 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""solprop's run records as ``_core`` reads them (solprop SEP 52 section 5.1). - -solprop forms each run's records once (:func:`solprop.backends.records.run_records`): -the method's policy, the low-storage settings, the schedule, the plane plan and the -boundary monitor's configuration and continuation. This module only converts them into -the dictionaries and arrays the extension's configuration calls take; it derives -nothing. -""" - -from __future__ import annotations - -import dataclasses -from typing import TYPE_CHECKING - -import numpy as np - -if TYPE_CHECKING: - from solprop.backends.records import ( - EdgeConfig, - EdgeResumption, - MonitorConfig, - MonitorContinuation, - PlanePlan, - Resumption, - RungeKuttaPolicy, - ) - from solprop.stepper.multistep import MarchPolicy - from solprop.stepper.schedule import FixedSchedule - -__all__ = [ - "NO_SCHEDULE", - "adams_policy", - "continuation", - "edge_config", - "edge_resumption", - "monitor_config", - "resumption", - "rk_policy", - "schedule_arrays", - "session_plan", -] - -NO_SCHEDULE = np.empty(0, dtype=np.float64) -"""The empty schedule of an adaptive march's configuration.""" - - -def adams_policy(policy: MarchPolicy) -> dict[str, object]: - """Return the Adams march's policy as ``adams_march_configure`` reads it.""" - return dataclasses.asdict(policy) - - -def rk_policy(policy: RungeKuttaPolicy) -> dict[str, object]: - """Return the Runge-Kutta march's policy as ``rk_march_configure`` reads it. - - The controller's fields flattened in: its gains, factors, lag, acceptance rule and - the equivalent norm's power and exponent (the kernel contract's section 12). - """ - controller = policy.controller - return { - "dz_min": policy.dz_min, - "dz_max": policy.dz_max, - "stretch": policy.stretch, - "z_end": policy.z_end, - "save_planes": list(policy.save_planes), - "interpolate": policy.interpolate, - "hard_kinks": list(policy.hard_kinks), - "breakpoints": list(policy.breakpoints), - "landing_ulps": policy.landing_ulps, - "quiet_interval": policy.quiet_interval, - "safety": float(controller.safety), - "beta1": float(controller.beta1), - "beta2": float(controller.beta2), - "min_factor": float(controller.min_factor), - "max_factor": float(controller.max_factor), - "lag": int(controller.lag), - "reject_free": bool(controller.reject_free), - "power": float(controller.estimator_order + 1), - "exponent": 1.0 / (controller.estimator_order + 1), - "start_growth": policy.start_growth, - "auto_init": policy.auto_init, - } - - -def schedule_arrays(schedule: FixedSchedule | None) -> tuple[np.ndarray, np.ndarray]: - """Return a replay's steps and edges, m, or an adaptive run's empty schedule.""" - if schedule is None: - return NO_SCHEDULE, NO_SCHEDULE - return ( - np.ascontiguousarray(schedule.steps, dtype=np.float64), - np.ascontiguousarray(schedule.edges, dtype=np.float64), - ) - - -def session_plan( - planes: PlanePlan, - *, - plane_statistics: object, - row_statistics: object, - monitor: dict[str, object] | None, - dense: dict[str, object] | None, -) -> dict[str, object]: - """Return the observation request and itinerary ``start_session`` reads. - - - ``plane_statistics``, ``row_statistics``: the lowered statistics plans - (``_core.StatisticsPlan``), each ``None`` for none. - - ``monitor``: the monitor's plan, or ``None`` without a monitor. - - ``dense``: the dense output's weights, or ``None`` without dense output. - """ - return { - "planes": planes.planes, - "next_plane": planes.next_plane, - "launch_pending": planes.launch_pending, - "step_planes": planes.step_planes, - "plane_statistics": plane_statistics, - "row_statistics": row_statistics, - "period": planes.period, - "attempt_capacity": planes.attempt_capacity, - "row_capacity": planes.row_capacity, - "replay": planes.replay_steps > 0, - "replay_steps": planes.replay_steps, - "replay_length": planes.replay_length, - "call_attempts": planes.call_attempts, - "call_seconds": planes.call_seconds, - "monitor": monitor, - "dense": dense, - } - - -def monitor_config(config: MonitorConfig) -> dict[str, object]: - """Return the monitor's configuration as ``watch::Config`` reads it.""" - return { - "policy": dict(config.policy), - "floor_share": config.floor_share, - "floor_margin": config.floor_margin, - "budget": config.budget, - "rate": config.rate, - "can_rest": config.can_rest, - } - - -def edge_config(config: EdgeConfig) -> dict[str, object]: - """Return the edge's configuration as ``transverse::Config`` reads it. - - Its fields by name, the arrays as they are (``dataclasses.asdict`` would copy them). - """ - values = {one.name: getattr(config, one.name) for one in dataclasses.fields(config)} - values["faces"] = list(config.faces) - return values - - -def resumption(held: Resumption) -> dict[str, object]: - """Return a monitor record's resumption: numbers flattened in, no absent list.""" - out: dict[str, object] = { - "record": held.record, - "collar_quiet": held.collar_quiet, - **held.numbers, - } - if held.unwatched is not None: - out["unwatched"] = [list(stretch) for stretch in held.unwatched] - if held.resumed_at is not None: - out["resumed_at"] = list(held.resumed_at) - if held.planes is not None: - out["planes"] = [list(column) for column in held.planes] - return out - - -def edge_resumption(held: EdgeResumption) -> dict[str, object]: - """Return an edge record's resumption: the numbers flattened in, no absent field.""" - out: dict[str, object] = {"record": held.record} - if not held.record: - return out - out.update(held.numbers) - for name in ("edge_baseline", "edge_max", "edge_max_raw"): - values = getattr(held, name) - if values is not None: - out[name] = list(values) - if held.reads is not None: - out["reads"] = held.reads - if held.transverse_status is not None: - out["transverse_status"] = held.transverse_status - return out - - -def continuation(held: MonitorContinuation) -> dict[str, object]: - """Return a monitored resume's continuation as the native session reads it. - - - Returns: the earlier record's resumption and its transverse edge's, whether the - run resumes at a saved plane, and the stretches run since without a monitor. - """ - return { - "edge_record": edge_resumption(held.edge), - "record": resumption(held.record), - "plane": held.plane, - "unwatched": [[start, end] for start, end in held.unwatched], - } diff --git a/native/src/solprop_native/backend.py b/native/src/solprop_native/backend.py index b0482fcb5..c99866531 100644 --- a/native/src/solprop_native/backend.py +++ b/native/src/solprop_native/backend.py @@ -6,7 +6,6 @@ from __future__ import annotations -import contextlib import dataclasses import functools import logging @@ -31,7 +30,6 @@ refuse_formulation, ) from solprop.backends.ledger import CallLedger, Derivative, source_absent -from solprop.backends.low_storage import schedule_key, table_steps from solprop.backends.memory import ( LOCAL_FLUX_STATISTICS, low_storage_flows, @@ -44,7 +42,12 @@ plan_node_chunk, ) from solprop.backends.protocol import TimingProbe -from solprop.backends.records import adams_policy +from solprop.backends.records import ( + RunRecords, + adams_policy, + low_storage_settings, + run_records, +) from solprop.backends.session import ( ExecutionOptions, PreparedExecution, @@ -56,7 +59,7 @@ radial_absorber_matrix, ) from solprop.boundaries import SPLIT_RATE_BUCKETS -from solprop.constants import EPS0, C +from solprop.constants import EPS0 from solprop.exceptions import ( BackendError, ConvergenceError, @@ -68,17 +71,15 @@ from solprop.output.records import MarchSnapshot from solprop.profiles import ZProfile from solprop.spatial import ( - ABSORBED_CHANNELS, FAR_FIELD_STATISTICS, ApertureTables, ) from solprop.stats import ( StatsSpec, ) -from solprop.stepper.controller import PIController from solprop.stepper.low_storage import LowStorageRungeKutta from solprop.stepper.multistep import MarchPolicy, Multistep -from solprop.stepper.schedule import FixedSchedule +from solprop.stepper.tableau import continuous_extension from solprop.translate.chebyshev import ( _EDGE_SLACK_FRACTION, # pyright: ignore[reportPrivateUsage] - the tables' own admitted span PiecewiseChebyshev, @@ -96,7 +97,6 @@ node_kerr_tensor, ) from solprop.translate.linop import ( - delta_phi, power_weight_at, unitary_phase, ) @@ -130,7 +130,6 @@ from solprop.translate.tdse_source import TDSE_UNAVAILABLE_STATISTICS from solprop.transverse_monitor import ( TransverseEdge, - _EdgeReading, # pyright: ignore[reportPrivateUsage] - released together _transverse_edge_bytes, # pyright: ignore[reportPrivateUsage] - released together ) @@ -145,7 +144,6 @@ _core, _counters, _host_blas, - _records, _wisdom, build_info, check_build, @@ -370,10 +368,6 @@ def __init__( ) self._z_tables = None if problem.device_ready else _ZTables(problem, stepper) self._flow = _host_flow(problem) - # solprop SEP 45 phase 2: the staged Runge-Kutta rows, decided on first use. - self._rk_staged = False - self._rk_nodes: list[float] = [] - self._rk_weighted = False tables = problem.transform.modal_tables self._moving_maps = ( tables is not None @@ -398,13 +392,19 @@ def __init__( stored, self._wisdom_loaded = ( _wisdom.plans(wisdom) if fft_planning is None else ({}, False) ) - self._bound_buckets: np.ndarray | None = None # solprop SEP 46: the workspace's CPU execution record, the process's (the # calibration's where it holds, else the built-in table) unless one is given, - # as a stage-2 refinement gives one; read back from the state it built. + # as a stage-2 refinement gives one; read back from the workspace it built. self._execution_source = ( _package.EXECUTION_SOURCE if cpu_execution is None else "given" ) + integrator = stepper.integrator + # The run's carrier frame (solprop SEP 35), whose chord the stage tables read. + self._carrier = ( + carrier_reference(problem, integrator) + if isinstance(integrator, Multistep) + else None + ) plan = _LowerPlan( terms=self._terms, flow=self._flow, @@ -414,19 +414,23 @@ def __init__( cpu_execution=cpu_execution, fft_planning=_planning(fft_planning, stored), device=_on_device(), + setup=self._setup(), ) - self._native_state = _core.State(_lower(problem, request, plan)) + # One workspace for the backend's life (solprop SEP 52 section 5.3): the + # problem and every set-once table, guard and geometry cross once, here. + self._workspace = _core.Workspace(_lower(problem, request, plan)) + diagnostics = self._workspace.diagnostics() self._applied_execution = ExecutionRecord.from_native( - self._native_state.cpu_execution + diagnostics["cpu_execution"] ) if cpu_execution is None: # A stage-2 refinement of this very execution (solprop SEP 46 section # 6.6): the workspace is built again with its record. - refined = _refined_record(problem, stepper, self._native_state) + refined = _refined_record(problem, stepper, diagnostics) if refined is not None: - stored |= _keep_plans(self._native_state, wisdom) - self._native_state.close() - self._native_state = _core.State( + stored |= _keep_plans(diagnostics, wisdom) + self._workspace.close() + self._workspace = _core.Workspace( _lower( problem, request, @@ -437,24 +441,23 @@ def __init__( ), ) ) + diagnostics = self._workspace.diagnostics() self._execution_source = refined[1] self._applied_execution = ExecutionRecord.from_native( - self._native_state.cpu_execution + diagnostics["cpu_execution"] ) - self._native_state.set_crossing_workers(thread_budget().threads) - # solprop SEP 49: the TDSE response is the march's host source, bound here for - # the backend's life; the driver owns the binding and closes it. + # solprop SEP 49: the TDSE response is the march's host source, handed to each + # run and probe; the driver owns the binding and closes it. self._tdse_binding = tdse_binding self._host_source: TDSEHostSource | None = None if tdse_binding is not None: self._host_source = TDSEHostSource(tdse_binding, problem, self._terms) - self._native_state.bind_host_source(self._host_source) if fft_planning is None: - _keep_plans(self._native_state, wisdom) + _keep_plans(diagnostics, wisdom) self._wisdom_digest = ( _wisdom.digest( _applied_plans( - self._native_state, + diagnostics, stored, fft_planning if fft_planning is not None else _package.PLANNING, ) @@ -462,27 +465,20 @@ def __init__( if not _on_device() else None ) - if self._z_tables is not None: - self._z_tables.upload(self._native_state) - _upload_flux_table(self._native_state, problem) # The native Adams march's record (SEP 39): its policy, ledger and history, - # over the resident history the native state keeps (`_adams_engine`). - integrator = stepper.integrator - self._resident: _ResidentAdams | None = None + # over the resident history the workspace keeps. self._adams: _NativeAdamsMarch | None = ( - _NativeAdamsMarch(self, integrator) + _NativeAdamsMarch(self, integrator, diagnostics["history_rows"]) if isinstance(integrator, Multistep) else None ) # The low-storage march (SEP 24) is the native session's; its resident # registers' step is a timing probe's trial (`timing_probe`), and the - # evaluations the probe makes are counted for the metadata. - self._resident_low_storage = ( - _ResidentLowStorage(self, integrator) - if isinstance(integrator, LowStorageRungeKutta) - else None - ) + # evaluations the probes make are counted for the metadata. + self._low_storage = isinstance(integrator, LowStorageRungeKutta) self._low_storage_evaluations = 0 + # The open timing probe, which leases the workspace until the next run or probe. + self._probe: _core.Probe | None = None # NumPy's own BLAS pool would spin beside the native one while this backend # lives; it is held to one thread until the last native backend closes. self._host_blas = _host_blas.hold( @@ -518,12 +514,13 @@ def _load( z: float, resume: bool, ) -> Loaded: - """Load a start into the native state, as a fresh backend's (SEP 22 4.7). + """Form a start's load as a fresh backend's (SEP 22 4.7). - The field and the noise realisation (:func:`solprop_native._load.load`), the - stages' collar back in and the recycled stage dropped, no monitor bound, and - the Adams record's history and accounting started afresh; a session or a - timing probe goes on from here. + The field and the noise realisation (:func:`solprop_native._load.load`) and the + Adams record's history and accounting started afresh; the workspace takes the + load with the run's start (`_run_start`), which puts the stages' collar back + in, drops the recycled stage and binds no monitor before a session or a timing + probe goes on from it. - ``field``: the state, ``complex128`` of shape ``(n_modes, n_pol, n_omega)``, of any strides. @@ -535,43 +532,21 @@ def _load( raise BackendError("this backend is closed; its buffers were released") _require_initial_array(field, self._problem.shape) loaded = load(self._problem, self._stepper, field, noise, z=z, resume=resume) - self._native_state.unbind_monitor() - self._native_state.set_initial(loaded.field, loaded.native_noise()) if (counters := _counters.active) is not None: counters.load("start", loaded.field.nbytes) - # A collar an earlier run rested goes back into the stages (SEP 21). - self._native_state.set_absorber_quiet(False) - self._native_state.clear_fsal() if self._adams is not None: self._adams.reset() self._adams.begin_run() - if self._resident_low_storage is not None: - self._resident_low_storage.reset() self._low_storage_evaluations = 0 - # The state holds the field now: the record keeps no host copy past the load. - kept = dataclasses.replace(loaded, field=_EMPTY) - self._loaded = kept - return kept - - def _install(self, field: ComplexArray) -> None: - """Load a resumed history's own state, with the loaded noise realisation. + return loaded - - ``field``: the state as the interrupted run held it, contiguous. - """ - loaded = self._loaded - self._native_state.set_initial( - np.ascontiguousarray(field.reshape(-1)), - _EMPTY if loaded is None else loaded.native_noise(), - ) - if (counters := _counters.active) is not None: - counters.load("restore", field.nbytes) - - def _restore(self, start: Start, loaded: Loaded) -> tuple[str | None, float]: + def _restore(self, start: Start, loaded: Loaded) -> _Restored: """Restore a resumed start's ledgers and method history after its load. - Returns: why the snapshot's history was not installed (``None`` when it was or - none was given), and the next step's proposal, m: the snapshot's when its - history continues, else ``dz_init``. + none was given), the next step's proposal, m (the snapshot's when its + history continues, else ``dz_init``), and the history's own state and rows + the run then starts from. """ adams = self._adams proposal = float(self._stepper.dz_init) @@ -592,37 +567,110 @@ def _restore(self, start: Start, loaded: Loaded) -> tuple[str | None, float]: ) snapshot = start.march if snapshot is None: - return None, proposal + return _Restored(None, proposal) if adams is None: - march = ( - "low-storage" - if self._resident_low_storage is not None - else "Runge-Kutta" - ) - return f"the run steps with the {march} march, which keeps no history", ( - proposal + march = "low-storage" if self._low_storage else "Runge-Kutta" + return _Restored( + f"the run steps with the {march} march, which keeps no history", + proposal, ) - reason = adams.resume(snapshot, loaded.z) + reason, rows = adams.resume(snapshot, loaded.z) if reason is not None: - return reason, proposal - self._install(np.array(snapshot.state, copy=True)) - return None, float(snapshot.proposal) + return _Restored(reason, proposal) + if (counters := _counters.active) is not None: + counters.load("restore", snapshot.state.nbytes) + return _Restored( + None, + float(snapshot.proposal), + np.ascontiguousarray(snapshot.state, dtype=np.complex128).reshape(-1), + rows, + ) - def _adams_engine( + def _setup(self) -> dict[str, object]: + """Return the workspace's set-once data (solprop SEP 52 section 5.3). + + The stage tables, the z tables and their slots, a coupled flow's guard, the + Runge-Kutta trial's nodes and error control, the resident Adams history, the + low-storage settings, the split collar's occupancy buckets and the crossings' + threads, each absent where the problem has none. + """ + problem, stepper = self._problem, self._stepper + integrator = stepper.integrator + controller = stepper.controller + weights = ( + np.empty(0) + if controller.weights is None + else np.ascontiguousarray(controller.weights, dtype=np.float64) + ) + adams = isinstance(integrator, Multistep) + dense = ( + continuous_extension(stepper.tableau) + if stepper.interpolate_planes and not adams + else None + ) + tables = self._z_tables + setup: dict[str, object] = { + "stage_tables": self._stage_tables(), + "z_slots": None if tables is None else tables.slots_record(), + "z_tables": ([] if tables is None else tables.records()) + + _flux_tables(problem), + "flow_guard": _flow_guard(self._flow), + "runge_kutta": { + "nodes": np.ascontiguousarray(stepper.tableau.nodes, dtype=np.float64), + "rtol": float(controller.rtol), + "atol": float(controller.atol), + "weights": weights, + "dense_weights": np.empty(0) + if dense is None + else np.ascontiguousarray(dense, dtype=np.float64), + }, + "adams": None, + "low_storage": None, + "occupancy": None, + "crossing_workers": thread_budget().threads, + } + if isinstance(integrator, Multistep): + setup["adams"] = { + "slots": integrator.order + 2, + "compensated": self._compensated(integrator, "transported"), + "interpolate": bool(stepper.interpolate_planes), + "fused": integrator.formulation != "exponential", + "rtol": float(controller.rtol), + "atol": float(controller.atol), + "weights": weights, + } + settings = low_storage_settings(problem, stepper) + if settings is not None: + setup["low_storage"] = dataclasses.replace( + settings, + flows=_resident_flows(settings.flows, stepper, device=_on_device()), + ) + crossing = problem.split_crossing + if crossing is not None: + # The split collar's walk-off bucket of each bin (solprop #440), bound by + # the first run whose monitor reads its crossing limit. + setup["occupancy"] = { + "buckets": np.ascontiguousarray( + crossing.buckets, dtype=np.uint8 + ).reshape(-1), + "count": SPLIT_RATE_BUCKETS, + } + return setup + + def _compensated( self, method: Multistep, compensation: Literal["transported", "untransported"], - ) -> object: - """Return the resident Adams history (solprop SEP 16). + ) -> bool: + """Return whether the resident Adams history carries a compensation (SEP 16). Either formulation keeps its history, its step arithmetic and its norms in the - native state (solprop ADR-043), beside a coupled flow too (SEP 16 phase 6), - whose interaction formulation the admission refuses (`_refuse_adams`). + workspace (solprop ADR-043), beside a coupled flow too (SEP 16 phase 6), whose + interaction formulation the admission refuses (`_refuse_adams`). A varying + operator's exponential formulation carries the transported compensation + natively, as does a frozen-residual flow's residual, whatever the diagonal's + representation; the untransported test witness is the reference's alone. """ - # A varying operator's exponential formulation carries the transported - # compensation natively, as does a frozen-residual flow's residual, whatever - # the diagonal's representation; the untransported test witness is the - # reference's alone. flow = self._flow linear = self._problem.linear residual = flow is not None and flow.residual_terms is not None @@ -639,27 +687,10 @@ def _adams_engine( "untransported one is a test witness of backend='numpy_ref'" ) raise BackendError(msg) - self._resident = _ResidentAdams( - native=self._native_state, - method=method, - controller=self._stepper.controller, - shape=self._problem.shape, - compensated=compensated, - interpolate=self._stepper.interpolate_planes, - carrier=carrier_reference(self._problem, method), - ) - # solprop SEP 39 phases 1 and 3: the native state reads the scalar tables - # itself, uploaded once; the admission refused a problem whose rows they do not - # read (`host_rows_refusal`). - tables = self._stage_tables() - assert tables is not None - self._native_state.adams_stage_tables( - tables | _chord_tables(self._resident.carrier) - ) - return self._resident + return compensated def _stage_tables(self) -> dict[str, object] | None: - """Return the tables a resident Adams trial reads natively, or ``None``. + """Return the tables the native marches read each stage's scalars from. solprop SEP 39 phases 1 and 4: every scalar table ``translate.stage.scalars`` reads at a stage -- the weights of a constant or expanded ``Phi`` and @@ -667,12 +698,13 @@ def _stage_tables(self) -> dict[str, object] | None: the Kerr density, the plasma channels' densities and fractions, SEP 6's channel densities -- and an expansion's rate table, each packed as its batch pass reads it (``PiecewiseChebyshev.packed``). A separable operator's rows are - a constant's, the distance and the position with a unit prefactor - (`_trial_arrays`), and read no span. A z table's rows are its slots, which the - native state loads through the cache `_ZTables` shares. A coupled flow's - section and residual weights and a moving guide's map weights are sectioned - Chebyshev rows (`flow_weights`, `transform_weights`), formed natively from - their edges. + a constant's, the distance and the position with a unit prefactor, and read no + span. A z table's rows are its slots, which the workspace loads through the + cache the z tables share. A coupled flow's section and residual weights and a + moving guide's map weights are sectioned Chebyshev rows, formed natively from + their edges; the carrier frame's chord is read beside them + (:func:`_chord_tables`). ``None`` where the rows are not tables, which the + admission refuses (:func:`host_rows_refusal`). """ problem = self._problem if not stage_tables_available(problem): @@ -682,69 +714,79 @@ def _stage_tables(self) -> dict[str, object] | None: separable = self._terms.separable is not None tables = self._z_tables if tables is not None and tables.phi: - phi = _STAGE_TABLE + phi = "table" elif separable or linear.phi_constant is not None: - phi = _STAGE_CONSTANT + phi = "constant" elif linear.phi_expansion is not None: - phi = _STAGE_EXPANSION + phi = "expansion" phi_weights = linear.phi_expansion.weights.packed() phi_rate = linear.rate.packed() else: return None low = high = 0.0 if tables is not None and tables.prefactor: - prefactor = _STAGE_TABLE + prefactor = "table" elif separable: - prefactor = _STAGE_CONSTANT + prefactor = "constant" low, high = -math.inf, math.inf elif responses.prefactor_constant is not None: - prefactor = _STAGE_CONSTANT + prefactor = "constant" low, high = responses.prefactor_span elif responses.prefactor_expansion is not None: - prefactor = _STAGE_EXPANSION + prefactor = "expansion" prefactor_weights = responses.prefactor_expansion.weights.packed() else: return None kerr = responses.kerr_coefficients taper = problem.transform.taper_scale - return { - "n_stages": self._stepper.tableau.n_stages, - "phi": phi, - "phi_weights": phi_weights, - "phi_rate": phi_rate, - "prefactor": prefactor, - "prefactor_weights": prefactor_weights, - "prefactor_low": float(low), - "prefactor_high": float(high), - "density": responses.density.packed(), - "taper": None if taper is None else taper.packed(), - "raman_rates": [ - table.packed() - for term in responses.raman_terms - for table in term.decay_rates - ], - "kerr": 0 if kerr is None else 1 if kerr.density is None else 2, - "kerr_density": None - if kerr is None or kerr.density is None - else kerr.density.packed(), - "plasma_densities": [ - channel.density.packed() for channel in responses.population_channels - ], - "plasma_preionisation": [ - channel.preionisation.packed() - for channel in responses.population_channels - ], - "raman_densities": [ - None if term.density is None else term.density.packed() - for term in responses.raman_terms - ], - "dispersive_densities": [] - if responses.dispersive_kerr is None - else [table.packed() for table in responses.dispersive_kerr.densities], - } | _section_tables( - problem, - moving=self._moving_maps, - residual=self._flow is not None and self._flow.residual_terms is not None, + return ( + { + "n_stages": self._stepper.tableau.n_stages, + "phi": phi, + "phi_weights": phi_weights, + "phi_rate": phi_rate, + "prefactor": prefactor, + "prefactor_weights": prefactor_weights, + "prefactor_low": float(low), + "prefactor_high": float(high), + "density": responses.density.packed(), + "taper": None if taper is None else taper.packed(), + "raman_rates": [ + table.packed() + for term in responses.raman_terms + for table in term.decay_rates + ], + "kerr": "none" + if kerr is None + else "density" + if kerr.density is None + else "table", + "kerr_density": None + if kerr is None or kerr.density is None + else kerr.density.packed(), + "plasma_densities": [ + channel.density.packed() + for channel in responses.population_channels + ], + "plasma_preionisation": [ + channel.preionisation.packed() + for channel in responses.population_channels + ], + "raman_densities": [ + None if term.density is None else term.density.packed() + for term in responses.raman_terms + ], + "dispersive_densities": [] + if responses.dispersive_kerr is None + else [table.packed() for table in responses.dispersive_kerr.densities], + } + | _section_tables( + problem, + moving=self._moving_maps, + residual=self._flow is not None + and self._flow.residual_terms is not None, + ) + | _chord_tables(self._carrier) ) @property @@ -758,325 +800,60 @@ def _propagator_mode(self) -> PropagatorMode: """ return propagator_mode(self._problem, self._stepper, device=_on_device()) - def _trial_step(self, z: float, dz: float) -> tuple[float, _core.State]: - partials = self._prepare_trial(z, dz) - return self._score_trial(partials), self._native_state - - def _staged_rows(self) -> None: - """Upload the stage tables a Runge-Kutta trial's rows are formed from, once. - - solprop SEP 45 phase 2: every row a trial reads is one of the uploaded stage - tables', and the state evaluates each stage's scalars at ``z + c_i dz`` - natively. Phase 4 adds the z table, whose positions the state loads into the - one slot cache stage by stage. Beside a coupled flow the state also forms the - step's flow actions behind its guards, transcribed with their constants. The - admission refuses a problem whose rows the tables do not read - (:func:`host_rows_refusal`), so the tables are always formed. - """ - if self._rk_staged: - return - tables = self._stage_tables() - assert tables is not None # `host_rows_refusal` admitted the problem - self._native_state.adams_stage_tables(tables | _chord_tables(None)) - self._rk_nodes = [float(node) for node in self._stepper.tableau.nodes] - flow = self._flow - if flow is not None: - modes = int(flow.vectors.shape[-1]) - self._native_state.flow_guard_configure( - [float(value) for value in flow.row_sum], - [float(value) for value in np.ravel(flow.condition_bound)], - _TAYLOR_SCALE, - _MAX_FLOW_SQUARINGS, - _flow_allowance(modes), - ) - self._rk_staged = True - - def _prepare_trial(self, z: float, dz: float) -> RealArray: - """Prepare a Runge-Kutta trial's stages on the staged rows and score it.""" - self._staged_rows() - with _envelope_errors(): - return self._native_state.rk_trial( - z, dz, self._rk_nodes, prepare_only=False - ) - - def _trial_arrays( - self, bundles: Sequence[StageScalars], whole: StageScalars - ) -> tuple[ - tuple[ - RealArray, RealArray, RealArray, RealArray, RealArray, RealArray, RealArray - ], - dict[str, npt.NDArray[np.float64] | int], - ]: - """Pack the stages' host scalars into the engine's trial arrays.""" - if self._terms.separable is not None: - phi_delta = np.array([[one.z1 - one.z0] for one in [*bundles, whole]]) - phi_at = np.array([[one.z1] for one in bundles]) - prefactor = np.ones((len(bundles), 1)) - else: - phi_delta, phi_at, prefactor = self._weight_rows(bundles, whole) - density = np.ascontiguousarray( - np.array([bundle.density for bundle in bundles], dtype=np.float64) - ) - taper = np.ascontiguousarray( - np.array([bundle.taper_scale for bundle in bundles], dtype=np.float64) - ) - preionisation = np.ascontiguousarray( - np.array([bundle.preionisation for bundle in bundles], dtype=np.float64) - ) - raman_rates = np.ascontiguousarray( - np.array([bundle.raman_rates for bundle in bundles], dtype=np.float64) - ) - material: dict[str, npt.NDArray[np.float64] | int] = { - "kerr_density": np.asarray([one.kerr_density for one in bundles]), - "plasma_densities": np.asarray([one.plasma_densities for one in bundles]), - "plasma_preionisation": np.asarray( - [one.plasma_preionisation for one in bundles] - ), - "raman_densities": np.asarray([one.raman_densities for one in bundles]), - } - if self._problem.responses.dispersive_kerr is not None: - # solprop SEP 6's channel densities, each stage's row; the native response - # weighs its channels and rebuilds a mixture's filter from them. - material["dispersive_densities"] = np.ascontiguousarray( - [one.dispersive_kerr_densities for one in bundles], dtype=np.float64 - ) - if self._moving_maps: - # Schema 14's row: each stage's weights of a moving guide's maps, which the - # engine combines natively per stage. - material["transform_weights"] = np.ascontiguousarray( - np.stack( - [ - _required(one.transform_weights, "transform_weights") - for one in bundles - ] - ), - dtype=np.float64, - ) - arrays = ( - phi_delta, - phi_at, - prefactor, - density, - taper, - preionisation, - raman_rates, - ) - return arrays, material - - def _weight_rows( - self, bundles: Sequence[StageScalars], whole: StageScalars - ) -> tuple[RealArray, RealArray, RealArray]: - """Return the stages' weights of ``Phi`` and of the prefactor over the terms. - - Each stage's increment, the whole step's and each stage's value of ``Phi``, and - each stage's prefactor: the bundles' own weights of a constant or an expansion, - or, for a z table, the +-1 weights of its slots (solprop SEP 29 G1), whose - positions are evaluated natively first where no slot holds them. - """ - tables = self._z_tables - slot_of: dict[float, int] = {} - if tables is not None: - stages = [*bundles, whole] - slot_of = tables.load( - [one.z0 for one in stages if tables.phi] + [one.z1 for one in stages] - ) - if tables is not None and tables.phi: - phi_delta = np.stack( - [tables.phi_row(slot_of, one.z0, one.z1) for one in [*bundles, whole]] - ) - phi_at = np.stack( - [tables.at_row(slot_of, one.z1, tables.n_phi) for one in bundles] - ) - else: - phi_delta = np.stack( - [ - *(_required(bundle.phi_delta, "phi_delta") for bundle in bundles), - _required(whole.phi_delta, "whole phi_delta"), - ] - ) - phi_at = np.stack( - [_required(bundle.phi_at, "phi_at") for bundle in bundles] - ) - if tables is not None and tables.prefactor: - prefactor = np.stack( - [tables.at_row(slot_of, one.z1, tables.slots) for one in bundles] - ) - else: - prefactor = np.stack( - [_required(bundle.prefactor, "prefactor") for bundle in bundles] - ) - return ( - np.ascontiguousarray(phi_delta), - np.ascontiguousarray(phi_at), - np.ascontiguousarray(prefactor), - ) - - def _phi_increment(self, z0: float, z1: float) -> RealArray: - """Return the weights of ``Phi(z1) - Phi(z0)`` over the native terms. - - The bundle's own for a constant or an expansion; a z table's two slots, - evaluated where no slot holds them, for a z table (solprop SEP 29 G1). - """ - tables = self._z_tables - if tables is not None and tables.phi: - return tables.phi_row(tables.load([z0, z1]), z0, z1) - return _required(self._stage_scalars(z0, z1).phi_delta, "phi_delta") - - def _delta_phi(self, bundle: StageScalars) -> ComplexArray: - """Return the stage's exponent on the host, a z table's from its native slots. - - A host engine's propagator and the dense observation's stiffness test read it; - a z table's two values are copied from the native slots and subtracted once, as - the stage kernels subtract them (solprop SEP 29 G1). - """ - tables = self._z_tables - if tables is not None and tables.phi: - here = tables.values("phi", bundle.z1) - anchored = tables.values("phi", bundle.z0) - return (here - anchored).reshape(self._problem.shape) - 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 _unitary_phase(self, bundle: StageScalars) -> RealArray: - """Return ``Im Phi`` at the stage's position, a z table's from its slot. + """Return ``Im Phi`` at the stage's position, formed on the host. 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 terms. + so its value at a position is the bundle's ``phi_at`` against the same terms. A + z table's value is the workspace's (``Session.noise_phase``). """ - tables = self._z_tables - if tables is not None and tables.phi: - return np.imag(tables.values("phi", bundle.z1)).reshape(self._problem.shape) 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 _hoist(self, z0: float) -> None: - """Hoist a step's anchor in the stage cache (`_load.StageCache.hoist`).""" - self._stages.hoist(z0) - - def _stage_bundles( - self, z0: float, positions: Sequence[float] - ) -> tuple[StageScalars, ...]: - """Return several stages' scalars taken together (`StageCache.bundles`).""" - return self._stages.bundles(z0, positions) - def _stage_scalars(self, z0: float, z1: float) -> StageScalars: """Return one stage's scalars (`StageCache.scalars`).""" return self._stages.scalars(z0, z1) - def _score_trial(self, partials: RealArray) -> float: - """Reduce one member's partials to the trial's scaled error norm. + def _diagnostics(self) -> dict[str, Any]: + """Return the workspace's facts and counters (``Workspace.diagnostics``).""" + return cast("dict[str, Any]", self._workspace.diagnostics()) - solprop's own weak scale is formed natively, the partials summed in order - (solprop SEP 45 phase 2, Q1), and a weighted one likewise (phase 4). A - controller with a scale of its own never reaches here: the backend refuses it - where it is built. - """ - controller = self._stepper.controller - if controller.weights is None: - return float(_core.rk_score(partials, controller.rtol, controller.atol)) - # The weighted scale and its reduction, in order (SEP 45 phase 4). - self._rk_weights_ready() - return float( - self._native_state.rk_weighted_score( - np.ascontiguousarray(partials, dtype=np.float64), - controller.rtol, - controller.atol, - ) - ) + def _monitor_binding(self, monitor: BoundaryMonitor) -> dict[str, object]: + """Return a run's boundary monitor weights where the state lives (SEP 21). - def _rk_weights_ready(self) -> None: - """Hand the native state a weighted controller's weights, once (SEP 45).""" - if not self._rk_weighted: - weights = self._stepper.controller.weights - assert weights is not None - self._native_state.rk_weights_configure( - [float(value) for value in np.asarray(weights, dtype=np.float64)] - ) - self._rk_weighted = True + From the run's start on, the engine's finish adds a split-step collar's removal + at every accepted step, on every march; a split monitor reads the problem's + walk-off buckets beside its five numbers (solprop #440). + """ + return { + "weights": np.ascontiguousarray(monitor.weights, dtype=np.float64).reshape( + -1 + ), + "column_weights": np.empty(0, dtype=np.float64) + if monitor.columns is None + else np.ascontiguousarray(monitor.columns, dtype=np.float64), + "split": bool(monitor.split) and self._problem.split_crossing is not None, + } - def _bind_monitor(self, monitor: BoundaryMonitor | None) -> None: - """Hold the boundary monitor's weights in the native state (solprop SEP 21). + def _edge_binding(self, edge: TransverseEdge) -> dict[str, object]: + """Return a transverse edge's tables where the state lives (solprop SEP 44). - From here on the engine's finish adds a split-step collar's removal at every - accepted step, on every march, and :meth:`_boundary_energies` reads it. + Weights and no faces: what it reads comes back to the edge's judging. A + requested collar's lines go as arrays. """ - if monitor is None: - self._native_state.unbind_monitor() - return - columns = ( - np.empty(0, dtype=np.float64) - if monitor.columns is None - else np.ascontiguousarray(monitor.columns, dtype=np.float64) - ) - self._native_state.bind_monitor( - np.ascontiguousarray(monitor.weights, dtype=np.float64).reshape(-1), columns - ) - crossing = monitor.crossing - # A runner's points share the table: uploading it again would move a sixteenth - # of a state per point. - if crossing is not None and crossing.buckets is not self._bound_buckets: - # The split collar's crossing limit, read from the state's occupancy of - # its walk-off buckets at every check (solprop #440). - self._native_state.bind_occupancy( - np.ascontiguousarray(crossing.buckets, dtype=np.uint8).reshape(-1), - SPLIT_RATE_BUCKETS, - ) - self._bound_buckets = crossing.buckets - edge = getattr(monitor, "transverse", None) - if edge is not None: - # Weights and no faces: what it reads comes back to the edge's judging. - tables = edge.tables - synthesis = edge.reduction.synthesis() - self._native_state.bind_edge( - np.ascontiguousarray(tables.faces, dtype=np.float64).reshape(-1), - np.ascontiguousarray(tables.clip, dtype=np.float64).reshape(-1), - np.ascontiguousarray(tables.totals, dtype=np.float64).reshape(-1), - np.empty(0, dtype=np.float64) - if synthesis is None - else np.ascontiguousarray(synthesis, dtype=np.float64).reshape(-1), - int(np.argmax(tables.rows)), - ) - self._bind_edge_lines(edge) - - def _bind_edge_lines(self, edge: TransverseEdge) -> None: - """Hand native a requested collar's lines, as arrays (solprop SEP 44).""" - lines = edge.reduction.lines - axes = {"r": 0, "x": 1, "y": 2} - none = 2**64 - 1 - strip = [np.asarray(line.strip, dtype=np.uint64) for line in lines] - window = [np.asarray(line.window, dtype=np.float64) for line in lines] - onsets = [ - line.onset if line.onset is not None else (none, 0, 0) for line in lines - ] - space = edge.space - self._native_state.bind_edge_lines( - np.array([axes[line.axis] for line in lines], dtype=np.uint64), - np.array([array.size for array in strip], dtype=np.uint64), - np.concatenate(strip) if strip else np.empty(0, dtype=np.uint64), - np.concatenate(window) if window else np.empty(0, dtype=np.float64), - np.array([line.inward for line in lines], dtype=np.uint64).reshape(-1), - np.array( - [ - line.spacing / (2 * array.size) * line.measure - if array.size - else 0.0 - for line, array in zip(lines, strip, strict=True) - ], - dtype=np.float64, - ), - np.array([line.measure for line in lines], dtype=np.float64), - np.array(onsets, dtype=np.uint64).reshape(-1), - np.array([line.onset_step for line in lines], dtype=np.float64), - float(edge.k_min), - np.sqrt(np.asarray(space.r, dtype=np.float64)) - if lines and isinstance(space, RadialGrid) - else np.empty(0, dtype=np.float64), - transverse_monitor._STRIP_BATCH_BYTES, # pyright: ignore[reportPrivateUsage] - ) + tables = edge.tables + synthesis = edge.reduction.synthesis() + return { + "faces": np.ascontiguousarray(tables.faces, dtype=np.float64).reshape(-1), + "clip": np.ascontiguousarray(tables.clip, dtype=np.float64).reshape(-1), + "totals": np.ascontiguousarray(tables.totals, dtype=np.float64).reshape(-1), + "synthesis": np.empty(0, dtype=np.float64) + if synthesis is None + else np.ascontiguousarray(synthesis, dtype=np.float64).reshape(-1), + "first_row": int(np.argmax(tables.rows)), + "lines": _edge_lines(edge), + } def edge_memory(self, space: object) -> int: """Return what reading the edge holds in the state's memory space (SEP 44). @@ -1096,79 +873,50 @@ def edge_memory(self, space: object) -> int: cast("Any", space), transverse_of(self._problem.route), n_pol, n_omega ) - def _edge_reading( - self, - state: _core.State, - edge: TransverseEdge, - *, - faces: bool = True, - current: bool = False, - full: bool = False, - ) -> _EdgeReading: - """Read the state for the transverse edge where it lives (solprop SEP 44). - - - Returns: the reading, of which only numbers crossed. A requested collar still - reduces a host copy of the state. - """ - if state is not self._native_state: - raise BackendError("the read state does not belong to this backend") - if (counters := _counters.active) is not None: - counters.transverse_reads += 1 - collar = edge.every_step - sums, columns, strip, rate = state.edge_reading( - faces, full, collar, faces and collar, current - ) - rate_value = float(rate) if current else None - if not faces: - return _EdgeReading(current=rate_value) - values = np.asarray(sums).reshape(-1) - if full: - clip, totals = values[4:8], values[8:12] - else: - clip, totals = None, values[4:8] if collar else None - return _EdgeReading( - faces=values[:4], - clip=clip, - totals=totals, - columns=np.asarray(columns).reshape(-1), - strip=np.asarray(strip).reshape(-1, 2) if collar else None, - current=rate_value, - ) - - def _finish(self, state: _core.State, dz: float) -> _core.State: - if state is not self._native_state: - raise BackendError("the advanced state does not belong to this backend") - state.finish(dz) - return state - - def _launch_clean_columns(self, edge: TransverseEdge) -> RealArray | None: + def _launch_clean_columns( + self, edge: TransverseEdge, loaded: Loaded + ) -> RealArray | None: """Return each column's launched energy without the input draw, or ``None``. What the transverse edge's safety ramp is judged on (SEP 40), so a run with no - ramp needs none. Formed where the load held both parts (`_load`), which needs - no state on the host; only a launch that resumed without its edge's record has - none, and then the loaded state crosses once. + ramp needs none. Formed where the load held both parts (`_load`); a launch that + resumed without its edge's record has none, and is formed from the loaded state. - Returns: the unweighted energies, or ``None`` with no draw, no ramp or on a resumed launch. """ - loaded = self._loaded - floor = None if loaded is None else loaded.floor - if loaded is None or floor is None or edge.resumed or edge.design is None: + floor = loaded.floor + if floor is None or edge.resumed or edge.design is None: return None if loaded.clean_columns is not None: return loaded.clean_columns - state = np.asarray(self._observed_field(self._native_state)) + state = np.asarray(loaded.field).reshape(self._problem.shape) return edge.reduction.column_power(state - np.asarray(floor)) + def _take_workspace(self) -> _core.Workspace: + """Return the workspace for a run or a probe, closing an open probe first.""" + if self._closed: + raise BackendError("this backend is closed; its buffers were released") + if self._probe is not None: + self._probe.close() + self._probe = None + if self._workspace.closed: + raise BackendError( + "this backend's workspace closed with its low-storage timing " + "probe, whose trials advanced the registers in place (solprop SEP " + "52 section 5.5); build another backend" + ) + return self._workspace + 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 (`_load`); its method history, ledgers and monitor continuation are - not read. A Runge-Kutta trial (``rk_trial``) leaves the loaded state alone; the - low-storage march's step advances the discarded registers in place, so a - backend probed so is closed afterwards (solprop SEP 47 section 6.6). + not read. A Runge-Kutta trial leaves the loaded state alone; the low-storage + march's step advances the discarded registers in place, so a backend probed so + is closed afterwards (solprop SEP 52 section 5.5). The probe holds the + workspace until the backend's next run or probe. Parameters ---------- @@ -1186,94 +934,14 @@ def timing_probe(self, start: Start) -> TimingProbe: z=float(start.z), resume=start.resume, ) - return NativeProbe(self, loaded, start.noise) - - def _observed_field(self, state: _core.State) -> ComplexArray: - if state is not self._native_state: - raise BackendError("the observed state does not belong to this backend") - field = state.field_to_host().reshape(self._problem.shape) - if (counters := _counters.active) is not None: - counters.crossing("plane", field.nbytes) - return field - - def _raman_spectrum( - self, rates: tuple[float, ...], densities: tuple[float, ...] = () - ) -> None: - """Prepare the native Raman kernel for private memoization diagnostics.""" - if not self._problem.responses.raman_terms: - return None - self._native_state.prepare_raman( - np.ascontiguousarray(np.asarray(rates, dtype=np.float64)), - np.ascontiguousarray(np.asarray(densities, dtype=np.float64)), - ) - - @property - def _raman_transforms(self) -> int: - """Return the number of native Raman-kernel transforms.""" - return int(self._native_state.raman_kernel_transforms) - - def _far_field_statistics( - self, names: set[str], spec: StatsSpec | None - ) -> dict[str, np.ndarray]: - """Form the far-field statistics in the native banded pass (SEP 23 section 6). - - The tables are those solprop's :class:`~solprop.backends.spatial.FarFieldTables` - forms for the call's spec, packed as :func:`_aperture_payload` says, and - ``(n_regions, 4)`` boxes; the pass returns each statistic finished, in - :data:`_FAR_FIELD_ORDER`. - """ - far = names & set(FAR_FIELD_STATISTICS) - tables = ( - None - if not far - else self._far_field.for_spec( - self._request.observation.stats if spec is None else spec - ) - ) - if far and tables is None: - raise BackendError( - f"the far-field statistics {sorted(far)} need the tables the backend " - "forms at construction" - ) - n_omega = self._problem.shape[-1] - apertures, regions, exponent = _aperture_payload(tables, n_omega) - flags = 0 - for name in names: - flags |= _FAR_FIELD_FLAGS[name] - packed = np.asarray( - self._native_state.aperture_statistics( - flags, apertures, exponent, regions, 0.5 * EPS0 * C - ) - ).ravel() - n_apertures = apertures.shape[0] - rows = { - "beam_spectrum": None, - "absorbed_power": 0, - "region_spectrum": regions.shape[0], - "aperture_spectrum": n_apertures, - "aperture_on_axis_spectrum": n_apertures, - "on_axis_spectrum": None, - } - values: dict[str, np.ndarray] = {} - offset = 0 - for name in _FAR_FIELD_ORDER: - if name not in names: - continue - count = rows[name] - if name == "absorbed_power": - size, shape = len(ABSORBED_CHANNELS), (1, len(ABSORBED_CHANNELS)) - elif count is None: - size, shape = n_omega, (1, n_omega) - else: - size, shape = count * n_omega, (1, count, n_omega) - values[name] = packed[offset : offset + size].reshape(shape) - offset += size - if offset != packed.size: - raise BackendError( - f"native far-field statistics returned {packed.size} values; " - f"consumed {offset}" + records = run_records(self._problem, self._request, start) + workspace = self._take_workspace() + with _envelope_errors(): + probe = workspace.probe( + _probe_start(records, loaded), host_source=self._host_source ) - return values + self._probe = probe + return NativeProbe(self, probe, loaded) def march_export_refusal(self) -> str | None: """Return ``None``: every march the backend admits carries its history. @@ -1294,6 +962,7 @@ def metadata(self) -> dict[str, object]: (:func:`_build_facts`); the native state's counters are read at every call. """ facts = _build_facts() + native = self._diagnostics() work: dict[str, object] = { "backend": self.name, "propagator_mode": self._propagator_mode, @@ -1311,15 +980,15 @@ def metadata(self) -> dict[str, object]: # Runge-Kutta trials' dispatches (SEP 30); a session states its own run's. if self._adams is not None: work["response_calls"] = self._adams.ledger.to_record() - elif self._resident_low_storage is not None: + elif self._low_storage: work["source_evaluations"] = self._low_storage_evaluations else: - work["source_evaluations"] = self._native_state.rk_source_evaluations + work["source_evaluations"] = native["rk_source_evaluations"] # Which march steps the run (solprop SEP 39 and 45 section 5): the native one, # the only one since SEP 47 phase 5. if self._adams is not None: work["adams_march"] = "native" - elif self._resident_low_storage is None: + elif not self._low_storage: work["rk_march"] = "native" if self._statistics_tables: # The profile statistics' tables and their measured errors (SEP 47 6.4). @@ -1349,15 +1018,15 @@ def metadata(self) -> dict[str, object]: _package.BUILTIN_EXECUTION, self._execution_source, ) - | _planning_record(self._native_state), + | _planning_record(native), "host_blas": self._host_blas, - "planning_seconds": self._native_state.planning_seconds, + "planning_seconds": native["planning_seconds"], "wisdom_loaded": self._wisdom_loaded, "wisdom_digest": self._wisdom_digest, - "raman_fft_provider": self._native_state.raman_fft_provider, - "raman_fft_tasks": self._native_state.raman_fft_tasks, - "execution_sizing": self._native_state.execution_sizing, - "raman_planning_seconds": self._native_state.raman_planning_seconds, + "raman_fft_provider": native["raman_fft_provider"], + "raman_fft_tasks": native["raman_fft_tasks"], + "execution_sizing": native["execution_sizing"], + "raman_planning_seconds": native["raman_planning_seconds"], "raman_enabled": self._problem.flags.has_raman, "raman_terms": sum( term.n_terms for term in self._problem.responses.raman_terms @@ -1375,13 +1044,13 @@ def metadata(self) -> dict[str, object]: and self._problem.grid_kind == "field" else "cycle_averaged" ), - "raman_kernel_transforms": self._native_state.raman_kernel_transforms, - "fsal_ready": self._native_state.fsal_ready, - "dispersive_path": dict(self._native_state.dispersive_path) or None, - "synthesis_provider": self._native_state.synthesis_provider, - "projection_provider": self._native_state.projection_provider, - "gemm_shape_policy": self._native_state.gemm_shape_policy, - "device_team_size": self._native_state.response_team_size, + "raman_kernel_transforms": native["raman_kernel_transforms"], + "fsal_ready": native["fsal_ready"], + "dispersive_path": dict(native["dispersive_path"]) or None, + "synthesis_provider": native["synthesis_provider"], + "projection_provider": native["projection_provider"], + "gemm_shape_policy": native["gemm_shape_policy"], + "device_team_size": native["response_team_size"], "device_team_size_limit": facts.device_team_size, "device_team_size_policy": ( "256 below n_to=8192; configured limit otherwise" @@ -1414,7 +1083,7 @@ def memory_ledger(self) -> dict[str, int]: """ ledger = { str(name): int(value) - for name, value in self._native_state.memory_ledger().items() + for name, value in self._diagnostics()["memory_ledger"].items() } stepper = self._stepper if ( @@ -1464,16 +1133,12 @@ def prepare( def close(self) -> None: """Release native plans and views; repeated calls have no effect.""" if not self._closed: - # Closing the state drops a host source with the engine that borrowed it, - # also while a session still leases the state (SEP 49). The state's own - # reference to the source is invisible to the garbage collector, which - # could then never free a cycle through it (a kept exception's traceback - # reaching the session), so it is dropped once the state is closed. A - # session that could not close still uses the state, and keeps it. - self._native_state.close() - if self._host_source is not None: - with contextlib.suppress(RuntimeError): - self._native_state.bind_host_source(None) + # Closing the workspace closes a session or probe that leases it first and + # drops a host source with the engine that borrowed it (SEP 49), whose + # reference the garbage collector cannot see. A session that could not + # close still uses the workspace, and keeps it. + self._probe = None + self._workspace.close() _host_blas.release() self._closed = True @@ -1528,118 +1193,128 @@ def _require_initial_array(field: object, shape: tuple[int, ...]) -> None: # 42), and the driver's load copies the field into a contiguous state first. -@dataclasses.dataclass -class _ResidentAdams: - """solprop's Adams history kept in the native state (solprop SEP 16 phase 3b). +@dataclasses.dataclass(frozen=True) +class _Restored: + """What a resumed start restores beside its load (`NativeBackend._restore`). - The native Adams march (solprop SEP 39) takes its trials, accepts, start-up and - dense observations in C++ (``adams_march.cpp``, ``dense.cpp``); this record holds - what Python still does with the history: it allocates the rows and sets the - controller's scale when it is built, and copies a resumed snapshot's rows in - (:meth:`load_rows`). A session snapshot copies them out natively - (``Session.march_snapshot``). + `reason` says why the snapshot's history was not installed (``None`` when it was or + none was given); `proposal` is the next step's, m; `field`, when the history + continues, is its own state, flat, which the run starts from in the loaded one's + place, and `rows` its persistent rows as the workspace takes them (``HistoryRow``). """ - native: _core.State - method: Multistep - controller: PIController - shape: tuple[int, ...] - """The state layout, ``(n_modes, n_pol, n_omega)``.""" - interpolate: bool - compensated: bool = False - """Whether trials carry a varying operator's transported compensation.""" - carrier: CarrierReference | None = None - """The run's carrier frame (solprop SEP 35), whose chord tables the native state - reads (:func:`_chord_tables`).""" - - def __post_init__(self) -> None: - """Allocate the history's rows in the native state.""" - self.native.adams_allocate(self.n_slots, self.compensated, self.interpolate) - # The controller's scale is formed on the device each trial, so that the - # state's magnitude never crosses: it is solprop's own, since PIController - # is final (ADR-077). - controller = self.controller - weights = controller.weights - self.native.adams_scale( - float(controller.rtol), - float(controller.atol), - np.empty(0, dtype=np.float64) - if weights is None - else np.ascontiguousarray(weights, dtype=np.float64), - ) + reason: str | None + proposal: float + field: ComplexArray | None = None + rows: tuple[dict[str, object], ...] = () - @property - def n_slots(self) -> int: - """The history's rows: the method's order and two more.""" - return self.method.order + 2 - def reset(self) -> None: - """Forget the last step: the native march holds no trial between calls.""" +def _probe_start(records: RunRecords, loaded: Loaded) -> dict[str, object]: + """Return a timing probe's start (solprop SEP 52 section 5.5). - def value(self, slot: int) -> None: - """The rows are resident: there is no host row to name.""" - del slot + The run's records (the low-storage replay's landings and schedule), the loaded + field and noise and its position; no march state, history or monitor. + """ + return { + "records": records, + "field": np.ascontiguousarray(loaded.field).reshape(-1), + "noise": np.ascontiguousarray(loaded.native_noise()), + "adams": None, + "runge_kutta": None, + "rows": [], + "plane_statistics": None, + "row_statistics": None, + "floor": None, + "edge_noise": None, + "monitor": None, + "edge": None, + } - # --- persistence across a resume (solprop SEP 29 G2) ------------------------------ - def snapshot_nbytes(self) -> int: - """Return the bytes a snapshot of the rows copies, copying nothing.""" - rows = len(self.native.adams_row_names()) - return rows * self.n_slots * math.prod(self.shape) * 2 * 8 +def _edge_lines(edge: TransverseEdge) -> dict[str, object]: + """Return a requested collar's lines as the workspace takes them (SEP 44).""" + lines = edge.reduction.lines + axes = {"r": 0, "x": 1, "y": 2} + none = 2**64 - 1 + strip = [np.asarray(line.strip, dtype=np.uint64) for line in lines] + window = [np.asarray(line.window, dtype=np.float64) for line in lines] + onsets = [line.onset if line.onset is not None else (none, 0, 0) for line in lines] + space = edge.space + return { + "axes": np.array([axes[line.axis] for line in lines], dtype=np.uint64), + "counts": np.array([array.size for array in strip], dtype=np.uint64), + "positions": np.concatenate(strip) if strip else np.empty(0, dtype=np.uint64), + "windows": np.concatenate(window) if window else np.empty(0, dtype=np.float64), + "inward": np.array([line.inward for line in lines], dtype=np.uint64).reshape( + -1 + ), + "factors": np.array( + [ + line.spacing / (2 * array.size) * line.measure if array.size else 0.0 + for line, array in zip(lines, strip, strict=True) + ], + dtype=np.float64, + ), + "measures": np.array([line.measure for line in lines], dtype=np.float64), + "onsets": np.array(onsets, dtype=np.uint64).reshape(-1), + "steps": np.array([line.onset_step for line in lines], dtype=np.float64), + "k_min": float(edge.k_min), + "scale": np.sqrt(np.asarray(space.r, dtype=np.float64)) + if lines and isinstance(space, RadialGrid) + else np.empty(0, dtype=np.float64), + "batch_bytes": transverse_monitor._STRIP_BATCH_BYTES, # pyright: ignore[reportPrivateUsage] + } - def load_rows(self, rows: Mapping[str, np.ndarray], shape: tuple[int, ...]) -> None: - """Install a snapshot's rows, for a state of `shape`. - The rows keep ``HostHistory``'s names and layout, ``(n_slots, n_modes, - n_pol, n_omega)``: ``"store"`` and, compensated, ``"states"`` and - ``"rates"``. A frozen-residual flow's history holds each sample's generator - applied to its state, ``"applied"``, where the host engine holds the sample's - weights (``"weights_"``); the two are not interchangeable, and each engine - refuses the other's. Everything is checked before any row is copied, so a - refused snapshot leaves the history as it was. - """ - names = self.native.adams_row_names() - weights = sorted(name for name in rows if name.startswith("weights_")) - if weights: - listed = ", ".join(weights) - raise BackendError( - "the native backend cannot continue this Adams history: the snapshot " - f"holds the host engine's frozen-residual weights ({listed}), and the " - "native engine keeps each sample's applied generator ('applied') " - "instead" - ) - foreign = sorted(set(rows) - set(names)) - missing = [name for name in names if name not in rows] - if foreign or missing: - raise BackendError( - "the native backend cannot continue this Adams history: its engine " - f"keeps the rows {names}, and the snapshot " - + (f"lacks {missing}" if missing else f"also holds {foreign}") - ) - expected = (self.n_slots, *shape) - for name in names: - row = rows[name] - if row.shape != expected or not np.iscomplexobj(row): - raise BackendError( - f"the snapshot's {name!r} rows ({row.dtype}, shape {row.shape}) do " - f"not fit the native backend's complex store of shape {expected}" - ) - for name in names: - flat = np.ascontiguousarray(rows[name], dtype=np.complex128) - self.native.adams_rows_from_host( - name, flat.reshape(self.n_slots, -1, shape[-1]) - ) +def _z_table(kind: str, table: PiecewiseChebyshev) -> dict[str, object]: + """Return one z table as the workspace makes it resident: its breakpoints, the + admitted span (``_EDGE_SLACK_FRACTION`` past each end) and its coefficients.""" + low, high = table.z_span + slack = _EDGE_SLACK_FRACTION * (high - low) + n_intervals, n_terms = table.coefficients.shape[:2] + return { + "kind": kind, + "edges": np.ascontiguousarray(table.breakpoints, dtype=np.float64), + "lower": low - slack, + "upper": high + slack, + "coefficients": np.ascontiguousarray( + table.coefficients, dtype=np.complex128 + ).reshape(n_intervals, n_terms, -1), + } + + +def _flux_tables(problem: PropagationProblem) -> list[dict[str, object]]: + """Return a radial plane measure's material z table, or none (SEP 34).""" + flux = flux_of(problem.route) + if flux is None or flux.material is None: + return [] + return [_z_table("flux", flux.material)] + + +def _flow_guard(flow: _HostFlow | None) -> dict[str, object] | None: + """Return a coupled flow's certificate and the guard's constants, or ``None``. + + Each section's row-sum norm and conditioning bound per active bin, with the scale + solprop's reference reduces an exponent below, the most squarings and the + rounding allowance on two spectral norms (solprop SEP 45 phase 4). + """ + if flow is None: + return None + row_sum = np.ascontiguousarray(flow.row_sum, dtype=np.float64) + return { + "row_sum": row_sum, + "condition_bound": np.ascontiguousarray( + flow.condition_bound, dtype=np.float64 + ).reshape(row_sum.size, -1), + "taylor_scale": _TAYLOR_SCALE, + "max_squarings": _MAX_FLOW_SQUARINGS, + "allowance": _flow_allowance(int(flow.vectors.shape[-1])), + } _EMPTY = np.empty(0, dtype=np.complex128) """No modified-noise realisation: the native state adds none.""" -_STAGE_CONSTANT = 1 -_STAGE_EXPANSION = 2 -_STAGE_TABLE = 3 -"""How the stage tables name a constant, an expanded or a z table's ``Phi`` and -prefactor (``stage::Terms``).""" - def _section_tables( problem: PropagationProblem, *, moving: bool, residual: bool @@ -1649,28 +1324,27 @@ def _section_tables( `transform_section`), and whether the flow carries a frozen residual.""" flow = problem.linear.coupled_flow maps = problem.transform.modal_tables if moving else None + none: dict[str, object] = {"edges": [], "degrees": 0, "slack": 0.0} out: dict[str, object] = { - "flow_edges": [], - "flow_degrees": 0, - "flow_slack": 0.0, + "flow": none, "flow_residual": False, - "transform_edges": [], - "transform_degrees": 0, - "transform_slack": 0.0, + "transform": none, } if flow is not None: out |= { - "flow_edges": np.asarray(flow.z_edges, dtype=np.float64).tolist(), - "flow_degrees": int(flow.n_deg), - "flow_slack": float(flow_edge_slack(flow)), + "flow": { + "edges": np.asarray(flow.z_edges, dtype=np.float64).tolist(), + "degrees": int(flow.n_deg), + "slack": float(flow_edge_slack(flow)), + }, "flow_residual": residual, } if maps is not None and maps.synthesis is not None: edges = np.asarray(maps.z_edges, dtype=np.float64) - out |= { - "transform_edges": edges.tolist(), - "transform_degrees": int(maps.synthesis.shape[1]), - "transform_slack": _EDGE_SLACK_FRACTION * float(edges[-1] - edges[0]), + out["transform"] = { + "edges": edges.tolist(), + "degrees": int(maps.synthesis.shape[1]), + "slack": _EDGE_SLACK_FRACTION * float(edges[-1] - edges[0]), } return out @@ -1687,7 +1361,7 @@ def _chord_tables(carrier: CarrierReference | None) -> dict[str, object]: chord = None if carrier is None or not carrier.active else carrier.chord if chord is not None and chord.constant is not None: return { - "chord": 1, + "chord": "constant", "chord_rate": float(np.imag(chord.constant)), "chord_terms": [], "chord_table": None, @@ -1695,7 +1369,7 @@ def _chord_tables(carrier: CarrierReference | None) -> dict[str, object]: if chord is not None and chord.expansion is not None: terms = np.imag(np.asarray(chord.expansion.terms)) return { - "chord": 2, + "chord": "expansion", "chord_rate": 0.0, "chord_terms": terms.tolist(), "chord_table": None, @@ -1706,12 +1380,12 @@ def _chord_tables(carrier: CarrierReference | None) -> dict[str, object]: # same operations (`stage::chord`). column = np.ascontiguousarray(np.imag(coefficients)) return { - "chord": 3, + "chord": "table", "chord_rate": 0.0, "chord_terms": [], "chord_table": (edges, lower, upper, column), } - return {"chord": 0, "chord_rate": 0.0, "chord_terms": [], "chord_table": None} + return {"chord": "none", "chord_rate": 0.0, "chord_terms": [], "chord_table": None} def _on_device() -> bool: @@ -1831,6 +1505,21 @@ def _resident_flows(flows: int, stepper: StepperSettings, *, device: bool) -> in return 0 if device and stepper.propagator_mode == "auto" else flows +FRESH_WATCH: Mapping[str, object] = types.MappingProxyType( + { + "has_last": False, + "last_z": 0.0, + "since": 0, + "busy": False, + "quiet_run": 0, + "quiet": False, + "warned": False, + "cap": math.inf, + } +) +"""The boundary watch's state at a run's start (``watch::State``): no check yet; a +session's monitor holds its own from there (solprop SEP 45 section 4.8).""" + _MARCH_COUNTERS = ( "startup", "predictor", @@ -1953,70 +1642,71 @@ def host_rows_refusal(problem: PropagationProblem) -> str | None: class _NativeAdamsMarch: """The native Adams march's record: its policy, ledger and history (SEP 39, 47). - The native state steps solprop's exponential Adams march (solprop SEP 39 phase 2): - the controller, the history, the landings and the call ledger's counts advance + The native workspace steps solprop's exponential Adams march (solprop SEP 39 phase + 2): the controller, the history, the landings and the call ledger's counts advance natively, from one policy record (:func:`~solprop.backends.records.adams_policy`). This record is what the run starts from: the policy, the history's entries (position, identity and engine row), the order, the rejection flags and the - :class:`~solprop.backends.numpy_ref.multistep.CallLedger`, each fresh at a load - (:meth:`reset`, :meth:`begin_run`) or restored from a resume's snapshot and ledger - (:meth:`resume`, :meth:`restore_ledger`). A native session hands it to the native - state once (:meth:`start_state`, :meth:`_configure`) and holds the march's state - there from then on (solprop SEP 47 section 5.2). + :class:`~solprop.backends.ledger.CallLedger`, each fresh at a load (:meth:`reset`, + :meth:`begin_run`) or restored from a resume's snapshot and ledger (:meth:`resume`, + :meth:`restore_ledger`). A native session hands it to the workspace once, with the + run's start (:meth:`start_state`), and holds the march's state there from then on + (solprop SEP 47 section 5.2). + + `rows` are the names of the resident history's persistent rows + (``Workspace.diagnostics``); `engine` is a scripted harness's own history. """ def __init__( - self, backend: Any, method: Multistep, *, engine: object | None = None + self, + backend: Any, + method: Multistep, + rows: Sequence[str] = (), + *, + engine: object | None = None, ) -> None: """Build the record over the backend's resident history, with no history.""" self._backend = backend - self._configured = False self._method = method + self._rows = tuple(str(name) for name in rows) + self._engine: Any = engine stepper = backend._stepper problem = backend._problem - # Whether the run interpolates its planes (ADR-036, ADR-039). - self._interpolate = bool(stepper.interpolate_planes) - exponential_form = method.formulation == "exponential" - # The interaction formulation takes the fused path. - self._fused = not exponential_form - resident = engine is None - self._engine: Any = ( - backend._adams_engine(method, "transported") if engine is None else engine - ) self._history: list[Derivative] = [] self._rejections = 0 self._last_rejected = False self._order = 1 if method.variable_order else method.order self.ledger = CallLedger() - carrier = getattr(self._engine, "carrier", None) + carrier = carrier_reference(problem, method) # Every number the native controller and landings read (SEP 39 section 4.2), # formed as the reference forms it. self._policy: MarchPolicy = adams_policy( - problem, - stepper, - method, - carrier=isinstance(carrier, CarrierReference) and carrier.active, + problem, stepper, method, carrier=carrier is not None and carrier.active ) # Whether the stages left a quiet collar out at the last attempt. self._collar_was_quiet = False # The admission refuses a carrier frame on an operator with no chord - # (``refuse_carrier_frame``); a scripted harness keeps its own engine. - assert not resident or ( - isinstance(self._engine, _ResidentAdams) - and not ( - self._policy.carrier - and self._engine.carrier is not None - and self._engine.carrier.chord is None - ) + # (``refuse_carrier_frame``). + assert not ( + self._policy.carrier and carrier is not None and carrier.chord is None ) + @property + def n_slots(self) -> int: + """The history's rows: the method's order and two more.""" + return self._method.order + 2 + + def snapshot_nbytes(self) -> int: + """Return the bytes a snapshot of the history's rows copies, copying nothing.""" + shape = self._backend._problem.shape + return len(self._rows) * self.n_slots * math.prod(shape) * 2 * 8 + # -- the record ------------------------------------------------------------------ def reset(self) -> None: """Forget the history: the state was loaded outside the march.""" self._history = [] self._rejections = 0 - self._engine.reset() def begin_run(self) -> None: """Start a run's accounting afresh: the ledger and the last attempt's flags. @@ -2042,26 +1732,29 @@ def restore_ledger( if logical: self.ledger = CallLedger.from_record(logical) - def resume(self, snapshot: MarchSnapshot, z: float) -> str | None: - """Install a snapshot's history taken where the run resumes, at `z`. + def resume( + self, snapshot: MarchSnapshot, z: float + ) -> tuple[str | None, tuple[dict[str, object], ...]]: + """Take a snapshot's history where the run resumes, at `z`. - The history's rows go to the resident engine and its entries, order and flags - to this record; the snapshot's state and proposal are the caller's to load. A - snapshot that cannot continue the march changes nothing. + Its entries, order and flags go to this record, and its rows are returned as + the workspace installs them with the run's start; the snapshot's state and + proposal are the caller's. A snapshot that cannot continue the march changes + nothing. - ``z``: the loaded position, m. - - Returns: ``None`` when the history was installed, otherwise why the march - starts afresh, as a resume did before snapshots were kept. + - Returns: ``None`` and the rows when the history continues, otherwise why the + march starts afresh, as a resume did before snapshots were kept, and no rows. """ reason = self._refusal(snapshot, z) if reason is not None: - return reason + return reason, () try: - self._engine.load_rows(snapshot.rows, self._backend._problem.shape) + rows = self._rows_record(snapshot.rows, self._backend._problem.shape) except BackendError as error: - return str(error) + return str(error), () self._history = [ - Derivative(float(z), self._engine.value(int(slot)), identity, int(slot)) + Derivative(float(z), None, identity, int(slot)) for z, identity, slot in zip( snapshot.positions, snapshot.identities, snapshot.slots, strict=True ) @@ -2070,7 +1763,55 @@ def resume(self, snapshot: MarchSnapshot, z: float) -> str | None: self._rejections = snapshot.rejections self._last_rejected = snapshot.last_rejected self._collar_was_quiet = snapshot.collar_was_quiet - return None + return None, rows + + def _rows_record( + self, rows: Mapping[str, np.ndarray], shape: tuple[int, ...] + ) -> tuple[dict[str, object], ...]: + """Return a snapshot's rows as the workspace takes them, for a state of `shape`. + + The rows keep ``HostHistory``'s names and layout, ``(n_slots, n_modes, + n_pol, n_omega)``: ``"store"`` and, compensated, ``"states"`` and + ``"rates"``. A frozen-residual flow's history holds each sample's generator + applied to its state, ``"applied"``, where the host engine holds the sample's + weights (``"weights_"``); the two are not interchangeable, and each engine + refuses the other's. Everything is checked before any row is copied. + """ + names = list(self._rows) + weights = sorted(name for name in rows if name.startswith("weights_")) + if weights: + listed = ", ".join(weights) + raise BackendError( + "the native backend cannot continue this Adams history: the snapshot " + f"holds the host engine's frozen-residual weights ({listed}), and the " + "native engine keeps each sample's applied generator ('applied') " + "instead" + ) + foreign = sorted(set(rows) - set(names)) + missing = [name for name in names if name not in rows] + if foreign or missing: + raise BackendError( + "the native backend cannot continue this Adams history: its engine " + f"keeps the rows {names}, and the snapshot " + + (f"lacks {missing}" if missing else f"also holds {foreign}") + ) + expected = (self.n_slots, *shape) + for name in names: + row = rows[name] + if row.shape != expected or not np.iscomplexobj(row): + raise BackendError( + f"the snapshot's {name!r} rows ({row.dtype}, shape {row.shape}) do " + f"not fit the native backend's complex store of shape {expected}" + ) + return tuple( + { + "name": name, + "values": np.ascontiguousarray(rows[name], dtype=np.complex128).reshape( + self.n_slots, -1, shape[-1] + ), + } + for name in names + ) def _refusal(self, snapshot: MarchSnapshot, z: float) -> str | None: """Return why a snapshot cannot continue this march at `z`, or ``None``.""" @@ -2098,11 +1839,7 @@ def _refusal(self, snapshot: MarchSnapshot, z: float) -> 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 >= self.n_slots))), "the snapshot's history names no row of this engine", ), ) @@ -2131,30 +1868,9 @@ def start_state(self, z: float, proposal: float, cursor: int) -> dict[str, objec for entry in self._history ], "ledger": {name: getattr(ledger, name) for name in _MARCH_COUNTERS}, + "watch": FRESH_WATCH, } - def _configure(self, policy: MarchPolicy, schedule: FixedSchedule | None) -> None: - """Hand the native state a run's policy and a replay's schedule, once. - - - ``policy``: the run's record - (:attr:`~solprop.backends.records.RunRecords.policy`), with no quiet - interval: a session's native monitor holds its own (SEP 47 section 6.4). - """ - if self._configured: - return - backend = self._backend - engine = cast("_ResidentAdams", self._engine) - steps, edges = _records.schedule_arrays(schedule) - backend._native_state.adams_march_configure( - _records.adams_policy(policy), - self._fused, - engine.compensated, - engine.interpolate, - steps, - edges, - ) - self._configured = True - def _raise(self, reason: int, result: dict[str, Any]) -> None: """Raise the error a native call returned with, if any. @@ -2200,153 +1916,32 @@ def _raise_native(result: Mapping[str, Any]) -> None: raise RuntimeError(message) -class _ResidentLowStorage: - """solprop's low-storage RK4IP engine on the native state (SEP 24 section 6.7). - - A ``solprop.backends.low_storage.LowStorageEngine``: the native state is the - register ``A`` and holds ``B``, ``C`` (unless elided, solprop's Q4) and the flows; - a step is one native call making the four register passes in the route's own - scratch (the transverse scratch, or the modal fine spectrum) through the stage core - the Runge-Kutta march shares, accepted in place. Only the step's host scalars - cross: one bundle per position (the start, the midpoint, the end) and the flows' - intervals. - - **The flows.** A constant operator tabulating holds one volume, ``exp(h_t D / 2)`` - for the key ``h_t`` of solprop's ``table_steps`` (the step's run's mean, SEP 24 - Q10), built from the operator's origin as solprop's engines build it and rebuilt - only when the key changes; a varying operator tabulating holds the step's ``P`` - and ``Q``; recomputing holds none and forms each flow per element in the finish - that applies it -- on a modal route from the phase terms, so a varying operator's - flows are never transients outside the ledger. - - **The stiffness indicator** (SEP 24 Q11) is not formed: - ``stiffness`` is NaN. Recovering ``g1`` and ``F2`` needs ``C``, which is elided on - the Cartesian and line routes the march is for or split across the exchange's two - evaluations, and two more reductions a step. - - Attributes - ---------- - stiffness : float - Always NaN: not formed on this backend. - atomic : bool - Always ``True``: the step is one native call, during which no signal handler - runs, so solprop's march commits the step, the finish and the move together. - """ - - def __init__(self, backend: NativeBackend, method: LowStorageRungeKutta) -> None: - """Hold the backend and the schedule's table keys.""" - self._backend = backend - self._method = method - self.stiffness = math.nan - self.atomic = True - problem = backend._problem # pyright: ignore[reportPrivateUsage] - the owner's problem - stepper = backend._stepper # pyright: ignore[reportPrivateUsage] - the owner's policy - flows = _low_storage_flows(problem, stepper, device=_on_device()) - assert flows is not None # the march is the low-storage one - self._flows = flows - schedule = stepper.schedule - assert schedule is not None # the translation refused the march without one - self._keys, self._edges = table_steps(schedule), schedule.edges - self._table_step = math.nan - self._separable = backend._terms.separable is not None # pyright: ignore[reportPrivateUsage] - the owner's fixed terms - - def reset(self) -> None: - """Drop the table's key: a resume builds it again from its own step.""" - self._table_step = math.nan - - def close(self) -> None: - """Forget the table; the native state releases the views when it closes.""" - self.reset() - - def step(self, z: float, dz: float) -> float: - """Take one step in four native register passes, accepted in place. - - - ``z``: where the step starts, m. - - ``dz``: the step, m, positive. - """ - backend = self._backend - if (counters := _counters.active) is not None: - counters.low_storage_steps += 1 - midpoint, end = z + 0.5 * dz, z + dz - # The engine reads its owner's tables, as solprop's engines read theirs. - hoist = backend._hoist # pyright: ignore[reportPrivateUsage] - bundles_at = backend._stage_bundles # pyright: ignore[reportPrivateUsage] - # A z table's increments are its slots' (solprop SEP 29 G1). - increment = backend._phi_increment # pyright: ignore[reportPrivateUsage] - problem = backend._problem # pyright: ignore[reportPrivateUsage] - hoist(z) - # Each evaluation reads its position as its own anchor (solprop's engines); - # a modal flow formed for the step reads its interval. - modal = not self._separable and self._flows != 1 - bundles = [ - bundles_at(z, [z, midpoint] if modal else [z])[0], - bundles_at(midpoint, [midpoint, end] if modal else [midpoint])[0], - bundles_at(end, [end])[0], - ] - stages = backend._stepper.tableau.n_stages # pyright: ignore[reportPrivateUsage] - padded = bundles + [bundles[-1]] * (stages - len(bundles)) - arrays, material = backend._trial_arrays(padded, bundles[-1]) # pyright: ignore[reportPrivateUsage] - phi_delta = np.zeros_like(arrays[0]) - rebuild = False - key = math.nan - if self._flows == 1: - key = schedule_key(self._keys, self._edges, z, dz) - rebuild = key != self._table_step - if self._separable: - # A constant operator's increment is the distance itself. - phi_delta[0:2, 0] = 0.5 * dz - if rebuild: - phi_delta[2, 0] = 0.5 * key - else: - if modal: - phi_delta[0] = increment(z, midpoint) - phi_delta[1] = increment(midpoint, end) - if rebuild: - # From the operator's origin, not fl(z + h/2) - z (solprop's engines). - origin = float(problem.linear.z_span[0]) - half = origin + 0.5 * key - bundles_at(origin, [half]) - phi_delta[2] = increment(origin, half) - with _envelope_errors(): - squared = backend._native_state.low_storage_step( # pyright: ignore[reportPrivateUsage] - dz, - np.ascontiguousarray(phi_delta), - *arrays[1:], - material, - rebuild, - ) - if rebuild: - self._table_step = key - return float(squared) - - _TABLE_POINTS = 16 """The most positions one native table evaluation takes (``z_table::max_points``).""" class _ZTables: - """The general z tables of one native state (solprop SEP 29 section 6.6, G1). + """The general z tables of one workspace (solprop SEP 29 section 6.6, G1). solprop falls back to a Chebyshev table of the state's size for ``Phi`` (``linear.phi_coefficients``) or the response prefactor (``responses.prefactor``) - when neither is a weighted sum of fixed arrays. The coefficients cross once, at - construction (``table_upload``), and stay resident; a trial's positions are then - evaluated natively into the native state's term slots, ``slots`` of them, and the + when neither is a weighted sum of fixed arrays. The coefficients cross once, with + the workspace's setup (:meth:`records`), and stay resident; a trial's positions are + then evaluated natively into the state's term slots, ``slots`` of them, and the stage weights select them: ``Phi(z1) - Phi(z0)`` is the row ``e_1 - e_0`` and ``Phi(z1)`` the row ``e_1``, so every native consumer of the terms (the Runge-Kutta stages, the low-storage flows, the Adams phase and the noise) reads the table unchanged, as one rounded subtraction of two values, as solprop's reference forms it. The prefactor's slots are its values at the same positions, one-hot weighted. - The slots are kept as a least-recently-used set of positions, in the native state - (``stage::ZSlots``, solprop SEP 39 phase 4), where the native Adams march reads - them too: each call's positions are evaluated only where no slot holds them yet, - so an accepted step's end, which is the next step's anchor, is never evaluated - twice. A call's positions - number at most ``slots`` (the tableau's distinct stage fractions, five for the - low-storage march), so none of one call's positions is evicted by another of its - own. A compensated Adams march reads ``D = dPhi/dz`` from the derivative table - (``linear.rate``) into one more ``Phi`` slot, ``rate_slot``. + The slots are kept as a least-recently-used set of positions in the workspace + (``stage::ZSlots``, solprop SEP 39 phase 4): each call's positions are evaluated + only where no slot holds them yet, so an accepted step's end, which is the next + step's anchor, is never evaluated twice. A call's positions number at most + ``slots`` (the tableau's distinct stage fractions, five for the low-storage march), + so none of one call's positions is evicted by another of its own. A compensated + Adams march reads ``D = dPhi/dz`` from the derivative table (``linear.rate``) into + one more ``Phi`` slot, ``rate_slot``. Attributes ---------- @@ -2377,12 +1972,6 @@ def __init__(self, problem: PropagationProblem, stepper: StepperSettings) -> Non and not source_absent(problem) ) self.rate_slot = self.slots if compensated else None - self._native: _core.State | None = None - - @property - def evaluations(self) -> int: - """Positions evaluated so far, a count for the tests and the benchmarks.""" - return 0 if self._native is None else self._native.table_evaluations() @property def n_phi(self) -> int: @@ -2391,7 +1980,7 @@ def n_phi(self) -> int: @property def nbytes(self) -> int: - """The bytes of the coefficients that cross to the native state.""" + """The bytes of the coefficients that cross to the workspace.""" coefficients = 0 if self.phi: phi = self._problem.linear.phi_coefficients @@ -2405,69 +1994,27 @@ def nbytes(self) -> int: coefficients += table.coefficients.nbytes return int(coefficients) - def upload(self, native: _core.State) -> None: - """Make the tables resident in `native`, once, before its first trial.""" - self._native = native - native.table_slots( - self.phi, self.prefactor, self.slots, self.rate_slot is not None - ) + def slots_record(self) -> dict[str, object]: + """Return the slots as the workspace configures them (``ZSlots``).""" + return { + "phi": self.phi, + "prefactor": self.prefactor, + "slots": self.slots, + "rate": self.rate_slot is not None, + } + + def records(self) -> list[dict[str, object]]: + """Return the tables the workspace makes resident (``ZTable``).""" + out: list[dict[str, object]] = [] if self.phi: - self._upload("phi", self._problem.linear.polynomial) + out.append(_z_table("phi", self._problem.linear.polynomial)) if self.rate_slot is not None: - self._upload("rate", self._problem.linear.rate) + out.append(_z_table("rate", self._problem.linear.rate)) if self.prefactor: table = self._problem.responses.prefactor assert table is not None - self._upload("prefactor", table) - - def _upload(self, kind: str, table: PiecewiseChebyshev) -> None: - """Send one table's breakpoints and coefficients, and its admitted span.""" - assert self._native is not None - low, high = table.z_span - slack = _EDGE_SLACK_FRACTION * (high - low) - n_intervals, n_terms = table.coefficients.shape[:2] - self._native.table_upload( - kind, - np.ascontiguousarray(table.breakpoints, dtype=np.float64), - low - slack, - high + slack, - np.ascontiguousarray(table.coefficients, dtype=np.complex128).reshape( - n_intervals, n_terms, -1 - ), - ) - - def load(self, positions: Sequence[float]) -> dict[float, int]: - """Return each position's slot, evaluating those no slot holds, in one call. - - - ``positions``: the positions one native call reads, m, at most ``slots`` - distinct. - """ - assert self._native is not None - wanted = [float(z) for z in positions] - try: - slots = self._native.table_load(wanted) - except ValueError as error: - raise BackendError(str(error)) from error - return dict(zip(wanted, slots, strict=True)) - - def phi_row(self, slot_of: Mapping[float, int], z0: float, z1: float) -> RealArray: - """Return the weights of ``Phi(z1) - Phi(z0)`` over the native terms.""" - row = np.zeros(self.n_phi) - row[slot_of[z1]] += 1.0 - row[slot_of[z0]] -= 1.0 - return row - - def at_row(self, slot_of: Mapping[float, int], z: float, count: int) -> RealArray: - """Return the one-hot weights of a table's value at `z` over `count` terms.""" - row = np.zeros(count) - row[slot_of[z]] = 1.0 - return row - - def values(self, kind: Literal["phi", "prefactor"], z: float) -> ComplexArray: - """Return a table's value at `z` on the host, from its native slot.""" - assert self._native is not None - slot = self.load([z])[float(z)] - return self._native.table_terms_to_host(kind, slot) + out.append(_z_table("prefactor", table)) + return out def _refuse_tdse( @@ -2735,7 +2282,9 @@ def _aperture_payload( def _refined_record( - problem: PropagationProblem, stepper: StepperSettings, state: _core.State + problem: PropagationProblem, + stepper: StepperSettings, + diagnostics: Mapping[str, Any], ) -> tuple[ExecutionRecord, str] | None: """Return a stored stage-2 refinement of this execution, or ``None``. @@ -2754,7 +2303,7 @@ def _refined_record( shape=(1, *problem.shape), grid_kind=problem.grid_kind, integrator=type(stepper.integrator).__name__, - sizing=state.execution_sizing, + sizing=diagnostics["execution_sizing"], process=_package.PROCESS, fingerprint=_package.PROFILE.fingerprint.digest, ) @@ -2790,14 +2339,14 @@ def _planning( return dict(chosen) | {"stored": dict(stored), "keep": True} -def _keep_plans(state: _core.State, path: Path | None) -> dict[str, str]: +def _keep_plans(diagnostics: Mapping[str, Any], path: Path | None) -> dict[str, str]: """Keep the plans a workspace measured, in this process and in `path`; return them. A key the profile holds is never kept: its winner takes precedence. """ if _on_device(): return {} - measured = cast(dict[str, str], state.fft_planning["measured"]) + measured = cast(dict[str, str], diagnostics["fft_planning"]["measured"]) profiled = cast(Mapping[str, str], (_package.PLANNING or {}).get("wisdom", {})) kept = {key: plan for key, plan in measured.items() if key not in profiled} if kept: @@ -2807,7 +2356,7 @@ def _keep_plans(state: _core.State, path: Path | None) -> dict[str, str]: def _applied_plans( - state: _core.State, + diagnostics: Mapping[str, Any], stored: Mapping[str, str], planning: Mapping[str, object] | None, ) -> dict[str, str]: @@ -2815,7 +2364,7 @@ def _applied_plans( `planning` is the one it was given, or the profile's; `stored` the plans offered. """ - found = state.fft_planning + found = diagnostics["fft_planning"] profiled = cast(Mapping[str, str], (planning or {}).get("wisdom", {})) missing = set(cast(list[str], found["missing"])) applied = { @@ -2827,7 +2376,7 @@ def _applied_plans( return applied | cast(dict[str, str], found["measured"]) -def _planning_record(state: _core.State) -> dict[str, object]: +def _planning_record(diagnostics: Mapping[str, Any]) -> dict[str, object]: """Return what a workspace's FFT planning applied, for its run's metadata. The plans keyed in its profile that no longer build from their wisdom are listed: @@ -2835,7 +2384,7 @@ def _planning_record(state: _core.State) -> dict[str, object]: """ if _on_device(): return {} - found = state.fft_planning + found = diagnostics["fft_planning"] groups = cast(dict[str, str], found["groups"]) if not groups: return {"fft_planning": "policy"} @@ -2855,7 +2404,8 @@ class _LowerPlan: `tables` the z tables; the chunks are the backend's lowered execution choices (solprop SEP 47 section 6.5), the automatic plan's when absent. `cpu_execution` is the workspace's CPU record (the process's when absent) and `fft_planning` its - FFT planning record (none on a device); `device` says the state is a device's. + FFT planning record (none on a device); `device` says the state is a device's, and + `setup` holds the workspace's set-once data by part (`NativeBackend._setup`). """ terms: StageTerms @@ -2866,6 +2416,7 @@ class _LowerPlan: cpu_execution: ExecutionRecord | None = None fft_planning: Mapping[str, object] | None = None device: bool = False + setup: Mapping[str, object] | None = None def _lower( @@ -2988,6 +2539,11 @@ def _lower( _lower_flow(native, plan.flow) _lower_dispersive(native, problem) _lower_flux(native, problem, request.observation.stats) + if plan.setup is not None: + # The set-once data, each part read through its record's table (SEP 52). + held: Any = native + for name, value in plan.setup.items(): + setattr(held, name, value) return native @@ -3333,7 +2889,7 @@ def _lower_flux( which the native state already holds: nothing more is packed, and a plan that is not that operator is refused. A radial run packs the entrance's material and transverse squares and whether a material z table follows - (:func:`_upload_flux_table`); the admission record is not read. ``closure`` + (:func:`_flux_tables`); the admission record is not read. ``closure`` sizes the magnetic closure's buffers for the run's own local statistics, `stats`. """ @@ -3358,26 +2914,6 @@ def _lower_flux( native.flux.table = flux.material is not None -def _upload_flux_table(native: _core.State, problem: PropagationProblem) -> None: - """Make a radial plane measure's material z table resident, once (SEP 34).""" - flux = flux_of(problem.route) - if flux is None or flux.material is None: - return - table = flux.material - low, high = table.z_span - slack = _EDGE_SLACK_FRACTION * (high - low) - n_intervals, n_terms = table.coefficients.shape[:2] - native.table_upload( - "flux", - np.ascontiguousarray(table.breakpoints, dtype=np.float64), - low - slack, - high + slack, - np.ascontiguousarray(table.coefficients, dtype=np.complex128).reshape( - n_intervals, n_terms, -1 - ), - ) - - def _lower_general( native: _core.Problem, problem: PropagationProblem, chunk: int | None ) -> None: diff --git a/native/src/solprop_native/session.py b/native/src/solprop_native/session.py index 81fd18b23..29fc2c072 100644 --- a/native/src/solprop_native/session.py +++ b/native/src/solprop_native/session.py @@ -102,10 +102,8 @@ from solprop.backends.protocol import BackendHistory, StepStats, StepSummary from solprop.backends.records import ( NoticeKind, - RungeKuttaPolicy, monitor_continuation, run_records, - runge_kutta_policy, ) from solprop.backends.session import ( DEFAULT_DEADLINE, @@ -139,11 +137,10 @@ from solprop.stepper.controller import ControlRecord from solprop.stepper.low_storage import LowStorageRungeKutta from solprop.stepper.multistep import Multistep -from solprop.stepper.tableau import continuous_extension from solprop.translate.linop import power_weight_at from solprop.translate.modal import QUADRATURE_ALARM, warn_quadrature -from . import _core, _counters, _records, _transverse, _watch +from . import _core, _counters, _transverse, _watch from ._load import Loaded from ._statistics import ( ADMITTED_GENERAL_STATISTICS, @@ -159,11 +156,11 @@ _DIVERGED, # pyright: ignore[reportPrivateUsage] _ERROR, # pyright: ignore[reportPrivateUsage] _FLOOR, # pyright: ignore[reportPrivateUsage] + FRESH_WATCH, NativeBackend, _aperture_payload, # pyright: ignore[reportPrivateUsage] - _on_device, # pyright: ignore[reportPrivateUsage] + _envelope_errors, # pyright: ignore[reportPrivateUsage] _raise_native, # pyright: ignore[reportPrivateUsage] - _resident_flows, # pyright: ignore[reportPrivateUsage] ) _LOG = logging.getLogger(__name__) @@ -184,7 +181,6 @@ from solprop.profiles import ZProfile from solprop.stats import StatsSpec from solprop.stepper.multistep import MarchPolicy - from solprop.stepper.schedule import FixedSchedule from solprop.translate.problem import PropagationProblem, StepperSettings from solprop.translate.run_request import RunRequest @@ -214,7 +210,8 @@ _OBSERVATION, _PROGRESS, _SNAPSHOT, _TERMINAL, _WARNING = range(5) _EVENT_NAMES = ("observation", "progress", "snapshot", "terminal", "warning") """The native event kinds by name, as the benchmark counters report a batch.""" -_EMPTY = np.empty(0, dtype=np.float64) +_NO_FIELD = np.empty(0, dtype=np.complex128) +"""A load whose state crossed to the workspace keeps no host copy.""" _NO_ORDERS = 1 << 62 """An order index past any run's, to read the march's state without its orders.""" _LEDGER_COUNTERS = ( @@ -519,14 +516,24 @@ def __init__( # the largest accepted step's score the session has drained for it. self._alarm_reported = False self._quadrature_peak = math.nan + # The largest score drained since the last alarm check (`_native_records`). + self._pending_peak = math.nan + integrator = self._stepper.integrator + kind = "runge_kutta" + if isinstance(integrator, Multistep): + kind = "adams" + elif isinstance(integrator, LowStorageRungeKutta): + kind = "low_storage" try: - kind, state = self._prepare(backend, start) - # The on-axis row scans this session's statistics make: the state's + run = self._prepare(backend, start) + driver = self._driver(backend) + # The on-axis row scans this session's statistics make: the workspace's # count, less what earlier runs on the backend made (SEP 19). - self._axis_scans = int(backend._native_state.axis_scans) # pyright: ignore[reportPrivateUsage] - self._native = backend._native_state.start_session( # pyright: ignore[reportPrivateUsage] - kind, state, self._plan(), float(start.z) - ) + self._axis_scans = int(driver._diagnostics()["axis_scans"]) + with _envelope_errors(): + self._native = driver._take_workspace().start( + run, host_source=driver._host_source + ) except BaseException: if owned: backend.close() @@ -573,87 +580,79 @@ def _lower( msg = f"the native session does not run {error}" raise BackendError(msg) from error - def _prepare( - self, backend: NativeBackend, start: Start - ) -> tuple[str, dict[str, object]]: - """Load the start and configure the backend's native march; return its state. + def _prepare(self, backend: NativeBackend, start: Start) -> dict[str, object]: + """Load the start and return the run's start as the workspace takes it. - - Returns: the march's kind and its state at the start, as the native call takes - it. + - Returns: the run's records, its field and noise, the march's state at the + start, a resumed history's rows, the statistics plans, the monitor's launch + readings and the monitor's weights and edge tables (``RunStart``). """ driver = self._driver(backend) integrator = self._stepper.integrator - # The native load: the field, the noise, the collar back in the stages and a - # fresh Adams record (`NativeBackend._load`); then a resume's ledgers and its - # method history, whose state replaces the loaded one. + # The load: the field, the noise and a fresh Adams record (`NativeBackend. + # _load`); then a resume's ledgers and its method history, whose state replaces + # the loaded one. The workspace puts the collar back in the stages. loaded = driver._load( np.asarray(start.take_field()), start.noise, z=float(start.z), resume=start.resume, ) + restored = driver._restore(start, loaded) + if restored.field is not None: + loaded = dataclasses.replace( + loaded, field=restored.field.reshape(self._problem.shape) + ) self._loaded = loaded - self._march_refusal, proposal = driver._restore(start, loaded) + self._march_refusal = restored.reason + proposal = restored.proposal records = self._records - if isinstance(integrator, Multistep): - march = driver._adams - march._configure( # pyright: ignore[reportPrivateUsage] - cast("MarchPolicy", records.policy), records.schedule - ) - else: - # The Runge-Kutta march, and the low-storage replay, which is the native - # Runge-Kutta march's over the stage tables the state reads each step's - # scalars from (SEP 47 section 6.3). - driver._staged_rows() - _NativeRungeKuttaMarch(backend)._configure( # pyright: ignore[reportPrivateUsage] - cast("RungeKuttaPolicy", records.policy), records.schedule - ) - kind = "runge_kutta" - if isinstance(integrator, Multistep): - kind = "adams" - elif isinstance(integrator, LowStorageRungeKutta): - kind = "low_storage" - # The flows `_ResidentLowStorage` holds, and the operator's origin, from - # which a constant operator's table is built. - settings = records.low_storage - assert settings is not None # the march is the low-storage one - backend._native_state.low_storage_configure( # pyright: ignore[reportPrivateUsage] - _resident_flows(settings.flows, self._stepper, device=_on_device()), - settings.separable, - settings.origin, - ) - monitor = self._monitor - if monitor is not None: - # The monitor's weights where the state lives, read at every check, and the - # split collar's walk-off buckets; the monitor stays solprop's and fresh: - # the session owns its state natively. - driver._bind_monitor( - dataclasses.replace( - monitor, - crossing=self._problem.split_crossing if monitor.split else None, - ) - ) + adams_state: dict[str, object] | None = None + runge_kutta_state: dict[str, object] | None = None if isinstance(integrator, Multistep): adams = driver._adams ledger = adams.ledger self._calls = dataclasses.replace(ledger, orders=list(ledger.orders)) self._method = adams._method self._max_calls = cast("MarchPolicy", records.policy).max_calls - # The history's persistent rows, sized while the state is not leased. - self._rows_nbytes = int(adams._engine.snapshot_nbytes()) - state: dict[str, object] = adams.start_state( - loaded.z, proposal, loaded.cursor - ) + # The history's persistent rows. + self._rows_nbytes = int(adams.snapshot_nbytes()) + adams_state = adams.start_state(loaded.z, proposal, loaded.cursor) else: - norms: list[float] = [] - state = { + runge_kutta_state = { "z": float(loaded.z), "proposal": float(proposal), - "norms": norms, + "norms": [], + "watch": FRESH_WATCH, "cursor": int(loaded.cursor), } self._edge_noise = self._noise_readings(driver) - return kind, state + monitor = self._monitor + floor = None + if monitor is not None and loaded.floor is not None: + # The input noise's vacuum floor, read from its draw on the host once, as + # `BoundaryMonitor.launch` reads it. + energy = float(monitor.power(loaded.floor).sum()) + floor = [energy, *(energy * monitor.weights.mean(axis=1)).tolist()] + field = np.ascontiguousarray(loaded.field, dtype=np.complex128).reshape(-1) + # The state crossed: the record keeps no host copy past the load. + self._loaded = dataclasses.replace(loaded, field=_NO_FIELD) + return { + "records": records, + "field": field, + "noise": np.ascontiguousarray(loaded.native_noise()), + "adams": adams_state, + "runge_kutta": runge_kutta_state, + "rows": list(restored.rows), + "plane_statistics": self._plane_lowering.plan, + "row_statistics": self._row_lowering.plan, + "floor": floor, + "edge_noise": self._edge_noise, + "monitor": None if monitor is None else driver._monitor_binding(monitor), + "edge": None + if monitor is None or monitor.transverse is None + else driver._edge_binding(monitor.transverse), + } def _noise_readings(self, driver: Any) -> dict[str, object] | None: """Return the input noise's readings the transverse edge's launch carries. @@ -679,7 +678,7 @@ def _noise_readings(self, driver: Any) -> dict[str, object] | None: resumed = ( continuation is not None and continuation.edge.edge_baseline is not None ) - clean = None if resumed else driver._launch_clean_columns(edge) + clean = None if resumed else driver._launch_clean_columns(edge, self._loaded) return _transverse.noise_readings(edge, np.asarray(drawn), clean) @staticmethod @@ -694,58 +693,6 @@ def _driver(backend: NativeBackend | None) -> Any: assert backend is not None return backend - def _plan(self) -> dict[str, object]: - """Return the observation request and itinerary for the native session.""" - planes = self._records.planes - return _records.session_plan( - planes, - plane_statistics=self._plane_lowering.plan, - row_statistics=self._row_lowering.plan, - monitor=self._monitor_plan(), - dense=self._dense_plan() if planes.dense else None, - ) - - def _dense_plan(self) -> dict[str, object]: - """Return the dense output the native session interpolates planes with. - - - Returns: the tableau's dense-output weights, one per stage, empty for Adams: - those of :func:`~solprop.stepper.tableau.continuous_extension`, which the - translation requires of a Runge-Kutta run with interpolated planes. - """ - stepper = self._stepper - if isinstance(stepper.integrator, Multistep): - return {"weights": _EMPTY} - weights = continuous_extension(stepper.tableau) - assert weights is not None # the translation refuses dense output without one - return {"weights": np.ascontiguousarray(weights, dtype=np.float64)} - - def _monitor_plan(self) -> dict[str, object] | None: - """Return the native monitor's configuration and any record it continues. - - - Returns: the monitor's plan, or ``None`` without a monitor. - """ - monitor = self._monitor - held = self._records.monitor - if monitor is None or held is None: - return None - plan: dict[str, object] = { - "config": _records.monitor_config(held.config), - "resume": held.continuation is not None, - } - assert self._loaded is not None # `_prepare` loaded the start - drawn = self._loaded.floor - if drawn is not None: - # The input noise's vacuum floor, read from its draw on the host once, as - # `BoundaryMonitor.launch` reads it. - floor = float(monitor.power(drawn).sum()) - plan["floor"] = [floor, *(floor * monitor.weights.mean(axis=1)).tolist()] - if held.edge is not None: - plan["edge"] = _records.edge_config(held.edge) - plan["edge_noise"] = self._edge_noise - if held.continuation is not None: - plan.update(_records.continuation(held.continuation)) - return plan - # -- protocol ------------------------------------------------------------------- @property @@ -885,16 +832,30 @@ def _check_quadrature(self, event: Event) -> None: """ if self.closed: return - peak = float(self._native.quadrature_peak()) - if not math.isnan(peak) and not peak <= self._quadrature_peak: - # The largest drained so far, for the record (`execution_record`). - self._quadrature_peak = peak + self._native_records() + peak, self._pending_peak = self._pending_peak, math.nan if peak > QUADRATURE_ALARM and not self._alarm_reported: self._alarm_reported = True warn_quadrature(peak, float(self._native.status().z)) if isinstance(event, ObservationReady): self._alarm_reported = False + def _native_records(self) -> dict[str, Any]: + """Return the native session's records (``Session.records``). + + Each read drains the quadrature peak the state kept since the last, which is + held here until the next alarm check (`_check_quadrature`) and for the record. + """ + records = cast("dict[str, Any]", self._native.records()) + peak = float(records["quadrature_peak"]) + if not math.isnan(peak): + if not peak <= self._quadrature_peak: + # The largest drained so far, for the record (`execution_record`). + self._quadrature_peak = peak + if not peak <= self._pending_peak: + self._pending_peak = peak + return records + def _translate( self, batch: _core.SessionBatch, receipt: Receipt ) -> tuple[BackendHistory, Event]: @@ -906,7 +867,7 @@ def _translate( chunk = self._history(batch.attempts) rows = self._chunk_rows(batch) if not self._declared_logged: - edge = self._native.edge_record() + edge = self._native_records()["edge"] self._declared_logged = edge is None or _transverse.log_declared(edge) return chunk, self._event(batch, receipt, chunk, rows) @@ -1013,11 +974,8 @@ def export( destination = np.empty(self._shape, dtype=np.complex128) if out is None else out try: self._native.export( - ticket.receipt.sequence, - ticket.generation, - recipe.power, - recipe.optics, - weight, + (ticket.receipt.sequence, ticket.generation), + {"power": recipe.power, "optics": recipe.optics, "weight": weight}, destination, ) except _core.SessionLifecycleError as error: @@ -1069,8 +1027,8 @@ def noise_phase(self, ticket: ExportTicket) -> np.ndarray | None: tables = driver._z_tables if tables is not None and tables.phi: try: - values = self._native.table_phi( - ticket.receipt.sequence, ticket.generation, z + values = self._native.noise_phase( + (ticket.receipt.sequence, ticket.generation), z ) except _core.SessionLifecycleError as error: raise SessionError(str(error)) from None @@ -1133,9 +1091,7 @@ def march_snapshot(self, ticket: ExportTicket) -> MarchSnapshot | None: msg = f"the ticket for z = {ticket.z!r} m has expired" raise SessionError(msg) try: - taken = self._native.march_snapshot( - ticket.receipt.sequence, ticket.generation - ) + taken = self._native.snapshot((ticket.receipt.sequence, ticket.generation)) except _core.SessionLifecycleError as error: raise SessionError(str(error)) from None if taken is None: @@ -1266,7 +1222,7 @@ def _axis_scan_count(self) -> int: if backend is None or backend.closed: return self._axis_scans_closed try: - scans = int(backend._native_state.axis_scans) # pyright: ignore[reportPrivateUsage] + scans = int(backend._diagnostics()["axis_scans"]) # pyright: ignore[reportPrivateUsage] except RuntimeError: # The state was closed under the session. return self._axis_scans_closed @@ -1306,11 +1262,12 @@ def monitor_record(self) -> Mapping[str, object] | None: monitor = self._monitor if monitor is None: return None - native = self._native.monitor_record() + records = self._native_records() + native = records["monitor"] if native is None: return None record = _watch.record_of(monitor.check, native) - edge = self._native.edge_record() + edge = records["edge"] if monitor.transverse is not None and edge is not None: record["transverse"] = _transverse.record_of(monitor.transverse, edge) return record @@ -1329,7 +1286,7 @@ def monitor_cap(self) -> float: float The cap, m. """ - cap = self._native.monitor_cap() + cap = self._native_records()["cap"] return math.inf if cap is None else float(cap) def continue_monitor(self, continuation: Mapping[str, object]) -> None: @@ -1347,13 +1304,9 @@ def continue_monitor(self, continuation: Mapping[str, object]) -> None: """ if self._monitor is None: return - held = _records.continuation(monitor_continuation(self._monitor, continuation)) try: self._native.continue_monitor( - cast("dict[str, object]", held["record"]), - bool(held["plane"]), - cast("list[list[float]]", held["unwatched"]), - cast("dict[str, object]", held["edge_record"]), + monitor_continuation(self._monitor, continuation) ) except _core.SessionLifecycleError as error: raise SessionError(str(error)) from None @@ -1717,7 +1670,11 @@ def _budget_error(self, event: _core.SessionEvent) -> BaseException: calls = self._sync_calls() assert calls is not None field = np.empty(self._shape, dtype=np.complex128) - self._native.export(self._sequence, event.generation, False, False, None, field) + self._native.export( + (self._sequence, event.generation), + {"power": False, "optics": False, "weight": None}, + field, + ) return budget_error( self._max_calls, calls.total, @@ -1744,7 +1701,11 @@ def _host_error( if not isinstance(kept, ResponseBudgetError): return kept field = np.empty(self._shape, dtype=np.complex128) - self._native.export(self._sequence, event.generation, False, False, None, field) + self._native.export( + (self._sequence, event.generation), + {"power": False, "optics": False, "weight": None}, + field, + ) z = float(event.z) error = ResponseBudgetError( "the TDSE atomic-call budget cannot reserve the next trial " @@ -1794,10 +1755,11 @@ def _log_finish(self) -> None: if self._finish_logged or self._monitor is None: return self._finish_logged = True - edge = self._native.edge_record() + records = self._native_records() + edge = records["edge"] if edge is not None: _transverse.log_finish(edge) - record = self._native.monitor_record() + record = records["monitor"] if record is not None: _log_finish( float(record["removed_fraction"]), @@ -1892,50 +1854,6 @@ def _reported_error( return RuntimeError(event.message or "the native session failed") -class _NativeRungeKuttaMarch: - """The Runge-Kutta march's policy for the native state (solprop SEP 45 phase 3). - - The adaptive loop -- the landing candidate, the trial on the staged rows, the - equivalent norm and acceptance, the start-up rule, the next proposal or the - rejection's, and the boundary checks -- runs natively in the session from one - policy record (the kernel contract's section 12, - :class:`~solprop.backends.records.RungeKuttaPolicy`), which this hands the native - state once. - """ - - def __init__(self, backend: Any) -> None: - """Hold the backend; nothing is configured yet.""" - self._driver: Any = backend - - def _policy(self, interval: float | None = None) -> dict[str, object]: - """Return the backend's controller and landing record (kernel contract 12). - - - ``interval``: a resting collar's quiet interval, m; ``None`` for a session, - whose native monitor holds its own. - """ - backend = self._driver - policy = runge_kutta_policy(backend._problem, backend._stepper) - return _records.rk_policy(dataclasses.replace(policy, quiet_interval=interval)) - - def _configure( - self, policy: RungeKuttaPolicy, schedule: FixedSchedule | None - ) -> None: - """Hand the native state the run's policy and a replay's schedule.""" - backend = self._driver - controller = policy.controller - if controller.weights is not None: - backend._rk_weights_ready() - steps, edges = _records.schedule_arrays(schedule) - backend._native_state.rk_march_configure( - _records.rk_policy(policy), - list(backend._rk_nodes), - float(controller.rtol), - float(controller.atol), - steps, - edges, - ) - - def _raise_rk( reason: int, result: Mapping[str, Any], diff --git a/native/src/workspace.cpp b/native/src/workspace.cpp index aceaba495..c5df58bf9 100644 --- a/native/src/workspace.cpp +++ b/native/src/workspace.cpp @@ -417,8 +417,9 @@ void Workspace::apply(const Setup& setup) { configure_adams(*setup.adams); if (setup.low_storage) configure_low_storage(*setup.low_storage); - set_monitor(setup.monitor); - set_edge(setup.edge); + set_occupancy(setup.occupancy); + if (setup.crossing_workers != 0) + state().set_crossing_workers(setup.crossing_workers); } void Workspace::require_built() const { @@ -543,65 +544,14 @@ void Workspace::configure_low_storage(const rk::low_storage::Config config) { low_storage_ = config; } -void Workspace::set_monitor(std::optional monitor) { +void Workspace::set_occupancy(std::optional occupancy) { require_open(); - if (monitor && !monitor->buckets.empty() && monitor->bucket_count == 0) - refuse("a monitor's occupancy buckets need their count"); - monitor_ = std::move(monitor); + if (occupancy && (occupancy->buckets.empty() || occupancy->count == 0)) + refuse("a split collar's occupancy needs its buckets and their count"); + occupancy_ = std::move(occupancy); occupancy_bound_ = false; } -void Workspace::set_edge(std::optional edge) { - require_open(); - edge_ = std::move(edge); -} - -void Workspace::configure_adams_march(march::Policy policy, const bool fused, - const bool compensated, const bool interpolate, - march::Schedule schedule) { - require_open(); - if (!stage_tables_) - throw std::logic_error("the native Adams march needs the stage tables"); - if (!schedule.steps.empty() && schedule.edges.size() != schedule.steps.size() + 1) - throw std::invalid_argument("a replayed schedule has one more edge than steps"); - march_policy_ = std::move(policy); - march_schedule_ = std::move(schedule); - march_fused_ = fused; - march_compensated_ = compensated; - march_interpolate_ = interpolate; -} - -void Workspace::configure_rk_march(rk::Policy policy, std::vector nodes, - const double rtol, const double atol, - march::Schedule schedule) { - require_open(); - if (!stage_tables_) - throw std::logic_error("the native Runge-Kutta march needs the stage tables"); - if (nodes.size() != stages_) - throw std::invalid_argument("the march's nodes are the tableau's stages"); - auto config = runge_kutta_.value_or(RungeKuttaConfig{}); - config.nodes = std::move(nodes); - config.rtol = rtol; - config.atol = atol; - runge_kutta_ = std::move(config); - rk_policy_ = std::move(policy); - rk_schedule_ = std::move(schedule); -} - -void Workspace::set_rk_weights(std::vector weights) { - require_open(); - auto config = runge_kutta_.value_or(RungeKuttaConfig{}); - config.weights = std::move(weights); - runge_kutta_ = std::move(config); -} - -void Workspace::set_dense_weights(std::vector weights) { - require_open(); - auto config = runge_kutta_.value_or(RungeKuttaConfig{}); - config.dense_weights = std::move(weights); - runge_kutta_ = std::move(config); -} - void Workspace::inject_fault(const engines::MarchFault fault) { require_open(); fault_ = fault; @@ -618,13 +568,12 @@ void Workspace::bind_host_source(std::shared_ptr source) { } std::vector Workspace::staged_trial(const double z, const double dz, - const bool prepare_only, - const std::vector* given) { + const bool prepare_only) { if (!stage_tables_) throw std::logic_error("a staged Runge-Kutta trial needs the stage tables"); - if (given == nullptr && !runge_kutta_) + if (!runge_kutta_) throw std::logic_error("a staged Runge-Kutta trial needs the tableau's nodes"); - const auto& nodes = given != nullptr ? *given : runge_kutta_->nodes; + const auto& nodes = runge_kutta_->nodes; if (nodes.size() != stages_) throw std::invalid_argument("the trial's nodes are the tableau's stages"); const auto scalars = @@ -694,15 +643,6 @@ void Workspace::guard_flow(const std::size_t section, const double dz, flow_key_ = std::make_pair(section, dz); } -double Workspace::weighted_score(const double* partials, const std::size_t slots, - const double rtol, const double atol) { - if (!runge_kutta_ || runge_kutta_->weights.empty()) - throw std::logic_error("no weighted controller's weights were configured"); - const std::vector values(partials, partials + 3 * slots); - return engines::ResidentRungeKutta::weighted_norm(state(), values, rtol, atol, - runge_kutta_->weights); -} - MethodKind Workspace::kind() const noexcept { if (adams_) return MethodKind::adams; @@ -834,21 +774,41 @@ void Workspace::load(const std::span field, state.clear_fsal(); } -void Workspace::bind_run_monitor() { +void Workspace::bind_run_monitor(const MonitorBinding& monitor, + const std::optional& edge) { auto& state = this->state(); - if (!monitor_) - refuse("a run with a boundary monitor needs the problem's monitor weights"); - state.bind_monitor(monitor_->weights, monitor_->column_weights); - // A runner's points share the table: it crosses once. - if (!monitor_->buckets.empty() && !occupancy_bound_) { - state.bind_occupancy(monitor_->buckets, monitor_->bucket_count); + state.bind_monitor(monitor.weights, monitor.column_weights); + // The problem's table, shared by a runner's points: it crosses once. + if (monitor.split && occupancy_ && !occupancy_bound_) { + state.bind_occupancy(occupancy_->buckets, occupancy_->count); occupancy_bound_ = true; } - if (edge_) { - state.bind_edge(edge_->faces, edge_->clip, edge_->totals, edge_->synthesis, - edge_->first_row); - if (edge_->lines) - state.bind_edge_lines(*edge_->lines); + if (edge) { + state.bind_edge(edge->faces, edge->clip, edge->totals, edge->synthesis, + edge->first_row); + if (edge->lines) + state.bind_edge_lines(*edge->lines); + } +} + +void Workspace::configure_march(const RunRecordsRecord& records) { + require_open(); + if (!stage_tables_) + throw std::logic_error("the native marches need the stage tables"); + auto schedule = records.schedule ? to_native(*records.schedule) : march::Schedule{}; + if (kind() == MethodKind::adams) { + const auto* policy = std::get_if(&records.policy); + if (policy == nullptr) + refuse("an Adams workspace's run needs the Adams march's policy"); + march::validate(*policy); + march_policy_ = *policy; + march_schedule_ = std::move(schedule); + } else { + const auto* policy = std::get_if(&records.policy); + if (policy == nullptr) + refuse("a Runge-Kutta workspace's run needs the Runge-Kutta march's policy"); + rk_policy_ = to_native(*policy); + rk_schedule_ = std::move(schedule); } } @@ -856,37 +816,23 @@ std::unique_ptr Workspace::start(RunStart start) { require_open(); const auto method_kind = kind(); auto& records = start.records; - const auto schedule = - records.schedule ? to_native(*records.schedule) : march::Schedule{}; std::variant initial; if (method_kind == MethodKind::adams) { - auto* policy = std::get_if(&records.policy); - if (policy == nullptr) - refuse("an Adams workspace's run needs the Adams march's policy"); if (!start.adams) refuse("an Adams run's start needs the march's state"); - march::validate(*policy); - if (!stage_tables_) - throw std::logic_error("the native Adams march needs the stage tables"); - march_policy_ = *policy; - march_schedule_ = schedule; initial = std::move(*start.adams); } else { - auto* policy = std::get_if(&records.policy); - if (policy == nullptr) - refuse("a Runge-Kutta workspace's run needs the Runge-Kutta march's policy"); if (!start.runge_kutta) refuse("a Runge-Kutta run's start needs the march's state"); - if (!stage_tables_) - throw std::logic_error("the native Runge-Kutta march needs the stage tables"); - rk_policy_ = to_native(*policy); - rk_schedule_ = schedule; initial = std::move(*start.runge_kutta); } - if (!schedule.steps.empty() && schedule.edges.size() != schedule.steps.size() + 1) - throw std::invalid_argument("a replayed schedule has one more edge than steps"); - // A resumed history's rows, every one checked before any is copied, so that a - // refused history leaves the rows as they were. + if (records.monitor && !start.monitor) + refuse("a run with a boundary monitor needs its weights"); + configure_march(records); + // The load first: a history's rows are read from a loaded state. They are every one + // checked before any is copied, so that a refused history leaves the rows as they + // were and starts no run. + load(start.field, start.noise); if (!start.rows.empty()) { if (method_kind != MethodKind::adams) refuse("only the Adams march resumes a history's rows"); @@ -904,7 +850,6 @@ std::unique_ptr Workspace::start(RunStart start) { ", ", extents[1], ", ", extents[2], ")"); } } - load(start.field, start.noise); for (const auto& row : start.rows) state().adams_rows_from_host(row.name, row.values); session::Plan plan; @@ -946,14 +891,14 @@ std::unique_ptr Workspace::start(RunStart start) { held.edge_noise = start.edge_noise; } plan.monitor = std::move(held); - bind_run_monitor(); + bind_run_monitor(*start.monitor, start.edge); } auto method = this->method(method_kind, std::move(initial), planes.dense); - return this->start(std::move(method), std::move(plan), planes.z); + return launch(std::move(method), std::move(plan), planes.z); } -std::unique_ptr Workspace::start(session::Method method, session::Plan plan, - const double z) { +std::unique_ptr Workspace::launch(session::Method method, session::Plan plan, + const double z) { auto& general = state(); auto session = std::make_unique(std::make_unique( @@ -970,11 +915,10 @@ std::unique_ptr Workspace::probe(std::vector field, std::unique_ptr Workspace::probe(RunStart start) { require_open(); - if (const auto* policy = std::get_if(&start.records.policy)) { - rk_policy_ = to_native(*policy); - rk_schedule_ = - start.records.schedule ? to_native(*start.records.schedule) : march::Schedule{}; - } + // The low-storage replay's landings and table keys come from the run's records; an + // Adams workspace's probe takes Runge-Kutta trials, which read none of them. + if (kind() != MethodKind::adams) + configure_march(start.records); return probe(std::move(start.field), std::move(start.noise), start.records.planes.z); } diff --git a/native/tests/session_runs.py b/native/tests/session_runs.py index 1af6652e3..b5d383bcd 100644 --- a/native/tests/session_runs.py +++ b/native/tests/session_runs.py @@ -39,6 +39,10 @@ from solprop.backends.session import RunSession, SessionStatus, Start from solprop.backends.sessions import start_session +from solprop_native import _core + +_testing: Any = cast(Any, _core)._testing + IDENTITY = ExportRecipe(power=False, optics=False) """The state as the session holds it, in the internal FFT convention.""" @@ -477,48 +481,40 @@ def launch_statistics( return {name: np.array(value) for name, value in observation.stats.items()} -def load_native( - backend: Any, - field: Any, - noise: Any = None, - *, - clear_fsal: bool = True, -) -> Any: - """Load a host state into a native backend's state, its recycled stage dropped. +def load_native(backend: Any, field: Any, noise: Any = None) -> Any: + """Load a host state into a native backend's workspace, as a run's start does. + + The collar back in the stages, the recycled stage dropped and no monitor bound + (``Workspace::load``). Parameters ---------- backend : solprop_native.NativeBackend - The backend; its native state is returned. + The backend; its workspace is returned. field : numpy.ndarray The state, shape ``(n_modes, n_pol, n_omega)``. noise : numpy.ndarray or None, optional The ``modified`` noise model's spectrum the stages add, in the state's layout, or ``None``. - clear_fsal : bool, optional - Drop the recycled first-same-as-last stage, as a session's load does; the - checks that loaded the bare state keep it with ``False``. Returns ------- - solprop_native._core.State - The loaded native state. + solprop_native._core.Workspace + The loaded workspace. """ - state = backend._native_state # pyright: ignore[reportPrivateUsage] + workspace = backend._workspace # pyright: ignore[reportPrivateUsage] flat = np.ascontiguousarray(field, dtype=np.complex128).reshape(-1) added = ( np.empty(0, dtype=np.complex128) if noise is None else np.ascontiguousarray(noise, dtype=np.complex128).reshape(-1) ) - state.set_initial(flat, added) - if clear_fsal: - state.clear_fsal() - return state + _testing.load(workspace, flat, added) + return workspace def native_trial(backend: Any, z: float, dz: float, *, field: Any = None) -> np.ndarray: - """Make one native Runge-Kutta trial from `z` on the backend's staged rows. + """Make one native Runge-Kutta trial from `z` on the backend's stage tables. At the nodes of the backend's own request's tableau; its stages stay in the state. A `field` is loaded first (:func:`load_native`). @@ -530,10 +526,8 @@ def native_trial(backend: Any, z: float, dz: float, *, field: Any = None) -> np. """ if field is not None: load_native(backend, field) - backend._staged_rows() # pyright: ignore[reportPrivateUsage] - nodes = [float(node) for node in backend.request.stepper.tableau.nodes] - state = backend._native_state # pyright: ignore[reportPrivateUsage] - return np.array(state.rk_trial(z, dz, nodes, prepare_only=False), dtype=np.float64) + workspace = backend._workspace # pyright: ignore[reportPrivateUsage] + return np.array(_testing.rk_trial(workspace, z, dz), dtype=np.float64) def drain(session: Any) -> Terminal: diff --git a/native/tests/test_api_contract.py b/native/tests/test_api_contract.py index 2dc8ab1f5..eaa95f7cc 100644 --- a/native/tests/test_api_contract.py +++ b/native/tests/test_api_contract.py @@ -740,7 +740,7 @@ def test_substantial_native_trial_releases_the_gil( """ problem, run_request, grid = phase_a_case backend = native.NativeBackend(problem, run_request, grid=grid) - load_native(backend, problem.initial.field0, clear_fsal=False) + load_native(backend, problem.initial.field0) active = threading.Event() finished = threading.Event() stamps: list[float] = [] diff --git a/native/tests/test_backend.py b/native/tests/test_backend.py index bc2c258d2..ae7f1991d 100644 --- a/native/tests/test_backend.py +++ b/native/tests/test_backend.py @@ -177,7 +177,7 @@ def test_stage_observation_owns_its_host_copy_and_checks_lifetime( """ problem, run_request, grid = phase_a_case backend = NativeBackend(problem, run_request, grid=grid) - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) with pytest.raises(RuntimeError, match="stage"): _testing.stage_to_host(state, 0) native_trial(backend, 0.0, 1e-4) @@ -330,7 +330,7 @@ def test_a_low_storage_table_never_built_is_refused(phase_a_case: PhaseACase) -> try: # The resident engine on the loaded state, with the key of the first step's # table, which no step built. - load_native(backend, marched.initial.field0, clear_fsal=False) + load_native(backend, marched.initial.field0) method = marched_request.stepper.integrator assert isinstance(method, LowStorageRungeKutta) engine = _ResidentLowStorage(backend, method) @@ -898,7 +898,7 @@ def test_packed_real_blas_radial_envelope_matches_the_reference_when_eligible() reference.close() backend = NativeBackend(problem, run_request, grid=grid) try: - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) info = build_info() # The native rule: a host execution space, at this shape; the dev build # without TPL BLAS packs too. diff --git a/native/tests/test_band_column_budget.py b/native/tests/test_band_column_budget.py index 57c693b5a..c8c8b0460 100644 --- a/native/tests/test_band_column_budget.py +++ b/native/tests/test_band_column_budget.py @@ -237,7 +237,7 @@ def stages( reference.close() backend = NativeBackend(problem, run_request, grid=GRID) try: - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) # A zero-length trial exposes the first stage, N(E, z = 0). native_trial(backend, 0.0, 0.0) actual = np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) diff --git a/native/tests/test_band_pathological.py b/native/tests/test_band_pathological.py index 29d4fc6a0..8ec62f41c 100644 --- a/native/tests/test_band_pathological.py +++ b/native/tests/test_band_pathological.py @@ -202,7 +202,7 @@ def source_of_native( """Return native's first stage on the launch, from a zero-length trial.""" backend = NativeBackend(problem, run_request, grid=grid) try: - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) native_trial(backend, 0.0, 0.0) return np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) finally: diff --git a/native/tests/test_band_plasma.py b/native/tests/test_band_plasma.py index 76eaa583b..bd9b7b950 100644 --- a/native/tests/test_band_plasma.py +++ b/native/tests/test_band_plasma.py @@ -443,7 +443,7 @@ def test_one_evaluation_matches_the_reference() -> None: reference.close() backend = NativeBackend(problem, run_request, grid=grid) try: - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) # A zero-length trial exposes the first stage, N(E, z = 0). native_trial(backend, 0.0, 0.0) actual = np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) @@ -492,7 +492,7 @@ def test_every_stage_of_a_trial_matches_the_reference( reference.close() backend = NativeBackend(problem, run_request, grid=grid) try: - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) if averaged and not DEVICE_BUILD: assert backend.metadata()["synthesis_provider"] == "folded" assert backend.metadata()["projection_provider"] == "folded" diff --git a/native/tests/test_band_stress.py b/native/tests/test_band_stress.py index 69af69c62..ed2005a96 100644 --- a/native/tests/test_band_stress.py +++ b/native/tests/test_band_stress.py @@ -283,7 +283,7 @@ def test_one_evaluation_matches_the_reference(kind: str) -> None: reference.close() backend = NativeBackend(problem, run_request, grid=grid) try: - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) # A zero-length trial exposes the first stage, N(E, z = 0). native_trial(backend, 0.0, 0.0) actual = np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) diff --git a/native/tests/test_dispersive.py b/native/tests/test_dispersive.py index d14803a95..dbd9d2192 100644 --- a/native/tests/test_dispersive.py +++ b/native/tests/test_dispersive.py @@ -282,7 +282,7 @@ def test_a_trial_without_the_densities_is_refused() -> None: problem, run_request, grid = averaged("symmetric", thg=True) backend = NativeBackend(problem, run_request, grid=grid) try: - load_native(backend, problem.initial.field0, clear_fsal=False) + load_native(backend, problem.initial.field0) stages = run_request.stepper.tableau.n_stages terms = backend._terms.phi # pyright: ignore[reportPrivateUsage] assert terms is not None @@ -321,7 +321,7 @@ def test_one_evaluation_matches_the_reference(evaluator: str, thg: bool) -> None backend = backend_class(problem, run_request, grid=grid) try: if isinstance(backend, NativeBackend): - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) native_trial(backend, 0.0, 0.0) spectra.append(_testing.projected_to_host(state, False)) else: diff --git a/native/tests/test_envelope_plasma.py b/native/tests/test_envelope_plasma.py index 28af8e818..1ee5a34b4 100644 --- a/native/tests/test_envelope_plasma.py +++ b/native/tests/test_envelope_plasma.py @@ -185,7 +185,7 @@ def test_envelope_current_streams_use_large_radial_projection() -> None: reference._stage_scalars(0.0, 0.0), # pyright: ignore[reportPrivateUsage] np.ones(problem.shape, complex), ) - state = load_native(actual, problem.initial.field0, clear_fsal=False) + state = load_native(actual, problem.initial.field0) native_trial(actual, 0.0, 0.0) observed = np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) info = build_info() diff --git a/native/tests/test_envelope_subnormal.py b/native/tests/test_envelope_subnormal.py index 627f201d1..d2f8582fa 100644 --- a/native/tests/test_envelope_subnormal.py +++ b/native/tests/test_envelope_subnormal.py @@ -122,7 +122,7 @@ def evaluate( try: if isinstance(backend, NativeBackend): # A zero-length trial exposes the first stage, N(E, z = 0). - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) native_trial(backend, 0.0, 0.0) stage = np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) else: diff --git a/native/tests/test_mixtures.py b/native/tests/test_mixtures.py index 31f58f4e9..ca5fc1916 100644 --- a/native/tests/test_mixtures.py +++ b/native/tests/test_mixtures.py @@ -131,7 +131,7 @@ def test_native_statistics_refuse_channel_preionisation_shape( problem, run_request, grid = mixture_case backend = NativeBackend(problem, run_request, grid=grid) try: - load_native(backend, problem.initial.field0, clear_fsal=False) + load_native(backend, problem.initial.field0) with pytest.raises(ValueError, match="channel preionisation"): _testing.statistics( backend._native_state, # pyright: ignore[reportPrivateUsage] - native refusal diff --git a/native/tests/test_radial.py b/native/tests/test_radial.py index 2bfcebda4..f0abe78fe 100644 --- a/native/tests/test_radial.py +++ b/native/tests/test_radial.py @@ -133,7 +133,7 @@ def test_radial_partial_chunks_preserve_the_reference_source( == retained ) assert (ledger["retained_synthesis"] > 0) == retained - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) native_trial(backend, 0.0, 0.0) actual = np.asarray(_testing.stage_to_host(state, 0)).reshape(problem.shape) assert np.isfinite(actual).all() @@ -141,7 +141,7 @@ def test_radial_partial_chunks_preserve_the_reference_source( assert scale > 0 np.testing.assert_allclose(actual, expected, rtol=0, atol=bound * scale) assert np.count_nonzero(actual[..., ~grid.active_mask]) == 0 - load_native(backend, np.zeros_like(problem.initial.field0), clear_fsal=False) + load_native(backend, np.zeros_like(problem.initial.field0)) native_trial(backend, 0.0, 0.0) assert np.count_nonzero(_testing.stage_to_host(state, 0)) == 0 assert backend.memory_ledger() == ledger diff --git a/tests/backends/test_native_error_norm.py b/tests/backends/test_native_error_norm.py index 4043878fc..d6f3eded4 100644 --- a/tests/backends/test_native_error_norm.py +++ b/tests/backends/test_native_error_norm.py @@ -315,7 +315,7 @@ def test_the_recycled_stage_is_the_one_it_replaces( delta = 1e-11 field = _field(backend, problem).copy() field *= 1.0 + delta * np.exp(2j * np.pi * rng.random(field.shape)) - load_native(backend, field, clear_fsal=False) + load_native(backend, field) native_trial(backend, z, dz) moved = np.asarray(_testing.stage_to_host(state, 0)) sensitivity = float(np.linalg.norm(moved - fresh) / np.linalg.norm(fresh)) diff --git a/tests/backends/test_native_far_field.py b/tests/backends/test_native_far_field.py index ea7335a78..96f39692d 100644 --- a/tests/backends/test_native_far_field.py +++ b/tests/backends/test_native_far_field.py @@ -829,7 +829,7 @@ def test_the_native_refusals_name_what_is_missing(): problem, run_request = problem_of(grid, space, field, spec_of(holes("tanh"))) owner = NativeBackend(problem, run_request, grid=grid) try: - native = load_native(owner, field, clear_fsal=False) + native = load_native(owner, field) apertures = np.zeros((1, NATIVE_CONSTANTS + grid.n_omega)) unknown = apertures.copy() unknown[0, 8] = 7.0 # a profile code past supergauss diff --git a/tests/backends/test_native_gpu.py b/tests/backends/test_native_gpu.py index 3fbe3e58d..9e9f33978 100644 --- a/tests/backends/test_native_gpu.py +++ b/tests/backends/test_native_gpu.py @@ -126,7 +126,7 @@ def test_a_large_state_crosses_both_ways_through_the_ring_bit_for_bit( assert field.nbytes >= 2**28 assert engine.memory_ledger()["host_crossing_ring"] == 0 # The state's own crossings, each way. - load_native(engine, field, clear_fsal=False) + load_native(engine, field) assert engine.memory_ledger()["host_crossing_ring"] > 0 back = engine._native_state.field_to_host().reshape(shape) assert back.tobytes() == field.tobytes() diff --git a/tests/backends/test_native_low_storage.py b/tests/backends/test_native_low_storage.py index 3a5685185..897d127fb 100644 --- a/tests/backends/test_native_low_storage.py +++ b/tests/backends/test_native_low_storage.py @@ -260,7 +260,7 @@ def test_a_trial_step_on_a_low_storage_state_is_refused_by_name(): problem, run_request, grid, _ = cartesian_march("tabulate") backend = NativeBackend(problem, run_request, grid=grid, options=CARTESIAN_CHUNK) try: - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) backend._staged_rows() nodes = [float(node) for node in run_request.stepper.tableau.nodes] with pytest.raises(RuntimeError, match=r"low-storage state .* no Runge-Kutta"): diff --git a/tests/backends/test_native_planar_statistics.py b/tests/backends/test_native_planar_statistics.py index 8ba5d110e..96da6a26f 100644 --- a/tests/backends/test_native_planar_statistics.py +++ b/tests/backends/test_native_planar_statistics.py @@ -173,7 +173,7 @@ def finished(problem, run_request, grid, rows, dz, options=None): reference.close() backend = NativeBackend(problem, run_request, grid=grid, options=options) try: - native = load_native(backend, problem.initial.field0, clear_fsal=False) + native = load_native(backend, problem.initial.field0) _testing.adopt(native, np.ascontiguousarray(rows.reshape(-1)), dz) actual = native.field_to_host().reshape(problem.shape) finally: diff --git a/tests/backends/test_native_synthetic_operator.py b/tests/backends/test_native_synthetic_operator.py index 1eb736495..31dfd6a33 100644 --- a/tests/backends/test_native_synthetic_operator.py +++ b/tests/backends/test_native_synthetic_operator.py @@ -94,7 +94,7 @@ def resident_step(problem, run_request, grid): dz = float(edges[1] - edges[0]) backend = NativeBackend(problem, run_request, grid=grid) try: - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) engine = backend_module._ResidentLowStorage(backend, MARCH) squared = engine.step(float(edges[0]), dz) state.finish(dz) diff --git a/tests/backends/test_native_widths.py b/tests/backends/test_native_widths.py index 45b974edb..47b582b5f 100644 --- a/tests/backends/test_native_widths.py +++ b/tests/backends/test_native_widths.py @@ -292,7 +292,7 @@ def capture(geometry, fluence, budget, axis): monkeypatch.undo() backend = select("native", problem, run_request, grid=grid) try: - state = load_native(backend, field, clear_fsal=False) + state = load_native(backend, field) packed = np.ravel(_testing.spatial_statistics(state, 16, 0.5 * EPS0 * C, 0.0)) finally: backend.close() @@ -350,7 +350,7 @@ def test_a_plane_s_moments_bound_the_refusal_as_its_fluence_does(route, kind): field = _field_for(route, grid, problem) backend = select("native", problem, run_request, grid=grid) try: - state = load_native(backend, field, clear_fsal=False) + state = load_native(backend, field) fluence = np.ravel(_testing.spatial_statistics(state, 16, 0.5 * EPS0 * C, 0.0)) moments = np.ravel(_testing.spatial_statistics(state, 32, 0.5 * EPS0 * C, 0.0)) finally: @@ -524,7 +524,7 @@ def test_the_native_trace_needs_a_held_plane_and_real_rings(): no_rings = np.empty(0) factor = 0.5 * EPS0 * C try: - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) with pytest.raises(RuntimeError, match="follows the call that holds it"): _testing.plane_fluence_trace( state, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0, 0, no_rings, no_rings @@ -554,7 +554,7 @@ def test_a_line_has_no_plane_moments(): grid, problem, run_request = _route("line") backend = select("native", problem, run_request, grid=grid) try: - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) with pytest.raises(ValueError, match="need a Cartesian plane"): _testing.spatial_statistics(state, 32, 0.5 * EPS0 * C, 0.0) finally: diff --git a/tests/backends/test_on_axis_statistics.py b/tests/backends/test_on_axis_statistics.py index 68cb92091..846ce50df 100644 --- a/tests/backends/test_on_axis_statistics.py +++ b/tests/backends/test_on_axis_statistics.py @@ -574,7 +574,7 @@ def test_the_native_row_refuses_a_matrix_that_is_not_one_or_two_rows(grid, table state = backend._native_state # pyright: ignore[reportAttributeAccessIssue] with pytest.raises(RuntimeError, match="no initial field"): _testing.axis_spectrum(state, np.ones((1, 1))) - load_native(backend, problem.initial.field0, clear_fsal=False) + load_native(backend, problem.initial.field0) with pytest.raises(ValueError, match="at most two rows"): _testing.axis_spectrum(state, np.ones((3, 1))) with pytest.raises(ValueError, match="two-dimensional"): diff --git a/tests/driver/test_estimate.py b/tests/driver/test_estimate.py index 2b689366e..4f119a18b 100644 --- a/tests/driver/test_estimate.py +++ b/tests/driver/test_estimate.py @@ -223,7 +223,7 @@ def _native_committed_nothing(problem, probed, fresh, dz): """ assert problem.initial.noise0 is None fresh._staged_rows() - state = load_native(fresh, problem.initial.field0, clear_fsal=False) + state = load_native(fresh, problem.initial.field0) loaded = state.field_to_host() held = probed._native_state.field_to_host() assert held.tobytes() == loaded.tobytes() diff --git a/tests/driver/test_native_flow_pathological.py b/tests/driver/test_native_flow_pathological.py index 691cf209f..baadae932 100644 --- a/tests/driver/test_native_flow_pathological.py +++ b/tests/driver/test_native_flow_pathological.py @@ -210,7 +210,7 @@ def _native_partials(problem, run_request, grid, field, dz): backend = NativeBackend(problem, run_request, grid=grid) try: backend._staged_rows() - load_native(backend, field, clear_fsal=False) + load_native(backend, field) return native_trial(backend, 0.0, dz) finally: backend.close() diff --git a/tests/driver/test_native_flow_session.py b/tests/driver/test_native_flow_session.py index 7dd880454..8b19860a0 100644 --- a/tests/driver/test_native_flow_session.py +++ b/tests/driver/test_native_flow_session.py @@ -356,7 +356,7 @@ def _resident(simulation: Simulation, problem: Any, request: Any) -> Any: engine = backend._resident assert type(engine).__name__ == "_ResidentAdams" field = np.ascontiguousarray(problem.initial.field0, dtype=np.complex128) - load_native(backend, field, clear_fsal=False) + load_native(backend, field) native_adams_start(backend, 0.0) rows = { name: np.broadcast_to(row[:1], row.shape).copy() diff --git a/tests/driver/test_native_moving_guide_bound.py b/tests/driver/test_native_moving_guide_bound.py index c910fa89c..8bda0b220 100644 --- a/tests/driver/test_native_moving_guide_bound.py +++ b/tests/driver/test_native_moving_guide_bound.py @@ -84,7 +84,7 @@ def source_at(implementation, problem, run_request, grid, positions): assert type(engine).__name__ == "_ResidentAdams" sources = [] for z in positions: - load_native(backend, state, clear_fsal=False) + load_native(backend, state) native_adams_start(backend, float(z)) sources.append(np.array(native_adams_rows(backend)["store"][0])) return sources diff --git a/tests/driver/test_native_rk_march.py b/tests/driver/test_native_rk_march.py index 11f5f5c25..50d3c1bde 100644 --- a/tests/driver/test_native_rk_march.py +++ b/tests/driver/test_native_rk_march.py @@ -170,7 +170,7 @@ def test_a_z_table_s_staged_trial_is_the_host_packed_trial(): try: backend._staged_rows() assert backend._rk_staged - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) nodes = [float(node) for node in run_request.stepper.tableau.nodes] end = float(run_request.stepper.z_end) for z in (0.0, 0.37 * end, 0.8 * end): diff --git a/tests/sessions/runs.py b/tests/sessions/runs.py index 70d59b535..2ca32160d 100644 --- a/tests/sessions/runs.py +++ b/tests/sessions/runs.py @@ -729,13 +729,13 @@ def load_native( backend: Any, field: np.ndarray, noise: np.ndarray | None = None, - *, - clear_fsal: bool = True, ) -> Any: - """Load a host state into a native backend's state, its recycled stage dropped. + """Load a host state into a native backend's workspace, as a run's start does. - The kernel-level tests call the native state (``solprop_native._core.State``) - directly, as the session's march does, in place of the retired driver load. + The kernel-level tests call the workspace's state (``solprop_native._core. + _testing``) directly, as the session's march does: the field and noise go in, the + collar back into the stages, the recycled stage dropped and no monitor bound + (``Workspace::load``). Parameters ---------- @@ -747,41 +747,40 @@ def load_native( noise : numpy.ndarray or None, optional The ``modified`` noise model's spectrum the stages add, in the state's layout (:func:`solprop.translate.masks.noise_spectrum`), or ``None``. - clear_fsal : bool, optional - Drop the recycled first-same-as-last stage, as a session's load does; the - checks that loaded the bare state keep it with ``False``. Returns ------- - solprop_native._core.State - The backend's native state, loaded. + solprop_native._core.Workspace + The backend's workspace, loaded. """ - state = backend._native_state + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + + workspace = backend._workspace values = np.ascontiguousarray(field, dtype=np.complex128).reshape(-1) added = ( np.empty(0, dtype=np.complex128) if noise is None else np.ascontiguousarray(noise, dtype=np.complex128).reshape(-1) ) - state.set_initial(values, added) - if clear_fsal: - state.clear_fsal() - return state + _testing.load(workspace, values, added) + return workspace def native_trial( backend: Any, z: float, dz: float, *, field: np.ndarray | None = None ) -> np.ndarray: - """Take one Runge-Kutta trial on a native backend's staged rows; its partials. + """Take one Runge-Kutta trial on a native backend's stage tables; its partials. - The trial is the native state's own (``rk_trial`` on the uploaded stage tables), - as the native march takes it, at the nodes of the backend's own request's - tableau; its stages stay in the state for ``stage_to_host``. + The trial is the workspace's own (``_testing.rk_trial``), as the native march + takes it, at the nodes of the backend's own request's tableau; its stages stay in + the state for ``stage_to_host``. Parameters ---------- backend : solprop_native.NativeBackend - The constructed backend, its state loaded (:func:`load_native`). + The constructed backend, its workspace loaded (:func:`load_native`). z : float Where the trial starts, m. dz : float @@ -794,11 +793,17 @@ def native_trial( numpy.ndarray The trial's scored partials, float64. """ + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + from solprop_native.backend import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] + _envelope_errors, + ) + if field is not None: load_native(backend, field) - backend._staged_rows() - nodes = [float(node) for node in backend.request.stepper.tableau.nodes] - partials = backend._native_state.rk_trial(z, dz, nodes, prepare_only=False) + with _envelope_errors(): + partials = _testing.rk_trial(backend._workspace, z, dz) return np.array(partials, dtype=np.float64) @@ -829,19 +834,19 @@ def native_source(backend: Any, field: np.ndarray, z: float = 0.0) -> np.ndarray _testing, ) - state = load_native(backend, field) + workspace = load_native(backend, field) native_trial(backend, z, 0.0) - return np.array(_testing.stage_to_host(state, 0)).reshape(np.shape(field)) + return np.array(_testing.stage_to_host(workspace, 0)).reshape(np.shape(field)) def bind_native_monitor( backend: Any, problem: PropagationProblem, monitor: BoundaryMonitor ) -> BoundaryMonitor: - """Hold a boundary monitor's weights and walk-off buckets in a native state. + """Hold a boundary monitor's weights and walk-off buckets in a native workspace. - What the native session binds for its monitor (the backend's ``_bind_monitor``, - the split collar's crossing the problem's), through the state's own bindings, for - the kernel-level readings of :func:`native_reading`. + What a native run's start binds for its monitor (the backend's + ``_monitor_binding``, the split collar's crossing the problem's), through + ``_testing.bind_monitor``, for the kernel-level readings of :func:`native_reading`. Parameters ---------- @@ -857,23 +862,26 @@ def bind_native_monitor( solprop.monitor.BoundaryMonitor The monitor as bound, for :func:`native_reading`. """ + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + monitor = dataclasses.replace( monitor, crossing=problem.split_crossing if monitor.split else None ) - state = backend._native_state - columns = ( - np.empty(0, dtype=np.float64) - if monitor.columns is None - else np.ascontiguousarray(monitor.columns, dtype=np.float64) + occupancy = ( + None + if monitor.crossing is None + else { + "buckets": np.ascontiguousarray( + monitor.crossing.buckets, dtype=np.uint8 + ).reshape(-1), + "count": SPLIT_RATE_BUCKETS, + } ) - state.bind_monitor( - np.ascontiguousarray(monitor.weights, dtype=np.float64).reshape(-1), columns + _testing.bind_monitor( + backend._workspace, backend._monitor_binding(monitor), None, occupancy ) - if monitor.crossing is not None: - state.bind_occupancy( - np.ascontiguousarray(monitor.crossing.buckets, dtype=np.uint8).reshape(-1), - SPLIT_RATE_BUCKETS, - ) return monitor @@ -893,8 +901,8 @@ def native_reading( monitor : solprop.monitor.BoundaryMonitor The monitor as bound (:func:`bind_native_monitor`). field : numpy.ndarray or None, optional - A state to load first (:func:`load_native`); the state as it stands by - default. + A state to load first (:func:`load_native`, which unbinds the monitor: + bind it again after); the state as it stands by default. Returns ------- @@ -907,9 +915,7 @@ def native_reading( if field is not None: load_native(backend, field) - reading = np.asarray( - _testing.monitor_reading(backend._native_state), dtype=np.float64 - ) + reading = np.asarray(_testing.monitor_reading(backend._workspace), dtype=np.float64) reading = reading.reshape(-1) found = reading[6:10].copy() if monitor.split else None occupancy = None @@ -930,10 +936,11 @@ def native_stage_rows( """Return the host-packed rows of a trial whose every stage reads `position`. The arrays a resident Adams trial took before the native march formed its rows - from the uploaded stage tables (SEP 39): the bundle at `position`, anchored at - `anchor`, repeated over the tableau's stages, through the backend's own packing - (``NativeBackend._trial_arrays``), with a coupled flow's section and a - frozen-residual flow's weights. The tests hold the native evaluation to them. + from the stage tables (SEP 39): the bundle at `position`, anchored at `anchor`, + repeated over the tableau's stages, packed as the backend packed them, with a + coupled flow's section and a frozen-residual flow's weights. The tests hold the + native evaluation to them. A z table's rows are its native slots, which no host + bundle holds: such a problem is refused here. Parameters ---------- @@ -950,9 +957,49 @@ def native_stage_rows( The seven row arrays (``phi_delta`` to ``raman_rates``) and the material record. """ + tables = backend._z_tables + if tables is not None and (tables.phi or tables.prefactor): + msg = "a z table's stage rows are its native slots, not a host bundle's" + raise NotImplementedError(msg) bundle = backend._stage_scalars(anchor, position) stages = backend.request.stepper.tableau.n_stages - arrays, material = backend._trial_arrays([bundle] * stages, bundle) + bundles = [bundle] * stages + if backend._terms.separable is not None: + phi_delta = np.array([[one.z1 - one.z0] for one in [*bundles, bundle]]) + phi_at = np.array([[one.z1] for one in bundles]) + prefactor = np.ones((stages, 1)) + else: + phi_delta = np.stack([one.phi_delta for one in [*bundles, bundle]]) + phi_at = np.stack([one.phi_at for one in bundles]) + prefactor = np.stack([one.prefactor for one in bundles]) + arrays = tuple( + np.ascontiguousarray(values, dtype=np.float64) + for values in ( + phi_delta, + phi_at, + prefactor, + [one.density for one in bundles], + [one.taper_scale for one in bundles], + [one.preionisation for one in bundles], + [one.raman_rates for one in bundles], + ) + ) + material: dict[str, Any] = { + "kerr_density": np.asarray([one.kerr_density for one in bundles]), + "plasma_densities": np.asarray([one.plasma_densities for one in bundles]), + "plasma_preionisation": np.asarray( + [one.plasma_preionisation for one in bundles] + ), + "raman_densities": np.asarray([one.raman_densities for one in bundles]), + } + if backend._problem.responses.dispersive_kerr is not None: + material["dispersive_densities"] = np.ascontiguousarray( + [one.dispersive_kerr_densities for one in bundles], dtype=np.float64 + ) + if backend._moving_maps: + material["transform_weights"] = np.ascontiguousarray( + np.stack([one.transform_weights for one in bundles]), dtype=np.float64 + ) flow = backend._flow if flow is not None: material |= { @@ -993,7 +1040,7 @@ def native_rate_weights(backend: Any, z: float, *, before: bool = False) -> np.n tables = backend._z_tables if tables is not None and tables.phi: - _testing.table_rate_at(backend._native_state, float(z), before) + _testing.table_rate_at(backend._workspace, float(z), before) rate = np.zeros(tables.n_phi) rate[tables.rate_slot] = 1.0 return rate @@ -1002,6 +1049,12 @@ def native_rate_weights(backend: Any, z: float, *, before: bool = False) -> np.n return np.ascontiguousarray(weights, dtype=np.float64) +def _native_compensated(backend: Any) -> bool: + """Whether a native backend's resident Adams history carries a compensation.""" + method = backend.request.stepper.integrator + return bool(backend._compensated(method, "transported")) + + def native_adams_start(backend: Any, z: float) -> None: """Evaluate a native backend's first Adams sample at its loaded state, into row 0. @@ -1013,7 +1066,7 @@ def native_adams_start(backend: Any, z: float) -> None: Parameters ---------- backend : solprop_native.NativeBackend - The constructed backend, under an Adams method, its state loaded + The constructed backend, under an Adams method, its workspace loaded (:func:`load_native`). z : float The state's position, m. @@ -1025,13 +1078,13 @@ def native_adams_start(backend: Any, z: float) -> None: _envelope_errors, ) - state = backend._native_state - backend._hoist(z) + workspace = backend._workspace + backend._stages.hoist(z) arrays, material = native_stage_rows(backend, z, z) with _envelope_errors(): - _testing.adams_start(state, 0, *arrays, material=material) - if backend._resident.compensated: - _testing.adams_compensation_start(state, 0, native_rate_weights(backend, z)) + _testing.adams_start(workspace, 0, *arrays, material=material) + if _native_compensated(backend): + _testing.adams_compensation_start(workspace, 0, native_rate_weights(backend, z)) def native_adams_rows(backend: Any) -> dict[str, np.ndarray]: @@ -1045,19 +1098,18 @@ def native_adams_rows(backend: Any) -> dict[str, np.ndarray]: Returns ------- dict of str to numpy.ndarray - Each row the engine keeps, ``(n_slots, 1, n_modes, n_pol, n_omega)``, as a + Each row the engine keeps, ``(n_slots, n_modes, n_pol, n_omega)``, as a snapshot holds it. """ from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] _testing, ) - state = backend._native_state - engine = backend._resident - expected = (engine.n_slots, *engine.shape) + workspace = backend._workspace + expected = (backend._adams.n_slots, *backend._problem.shape) return { - name: _testing.adams_rows_to_host(state, name).reshape(expected) - for name in state.adams_row_names() + name: _testing.adams_rows_to_host(workspace, name).reshape(expected) + for name in backend._diagnostics()["history_rows"] } @@ -1105,10 +1157,9 @@ def native_exponential_trial( _envelope_errors, ) - engine = backend._resident rows = max(orders) carrier = np.empty(0, dtype=np.float64) - reference = engine.carrier + reference = backend._carrier if reference is not None and reference.active: # (Im sigma, Re f_0, Im f_0, ...), f_t = exp(sigma (1 - theta_t)), over the # rows read; sigma is the reference element's chord over the step (SEP 35). @@ -1120,14 +1171,14 @@ def native_exponential_trial( carrier[2::2] = np.sin(shift * spans) with _envelope_errors(): norms = _testing.adams_exponential_trial_at( - backend._native_state, + backend._workspace, z, dz, np.asarray(nodes, dtype=np.float64), np.ascontiguousarray(slots[: max(rows, order)], dtype=np.uint64), order, list(orders), - engine.compensated, + _native_compensated(backend), carrier, ) return np.asarray(norms, dtype=np.float64).reshape(-1), carrier diff --git a/tests/sessions/test_native_load.py b/tests/sessions/test_native_load.py index 8857fcf5d..b596548b8 100644 --- a/tests/sessions/test_native_load.py +++ b/tests/sessions/test_native_load.py @@ -47,13 +47,13 @@ def test_an_input_draw_is_added_at_the_launch_alone(): try: field = np.asarray(problem.initial.field0) z = float(problem.initial.z) - # The load rule itself, whose record holds the field the state is given; the - # backend's kept record drops it once the state holds it. + # The load rule itself, whose record holds the field the workspace is given + # with the run's start; the backend's load is the rule's. loaded = native_load.load( problem, request.stepper, field, None, z=z, resume=False ) kept = native._load(field, None, z=z, resume=False) - assert kept.field.size == 0 + assert np.array_equal(kept.field, loaded.field) assert np.array_equal(kept.floor, loaded.floor) reference.set_initial(field, None, z=float(problem.initial.z)) host = cast("Any", reference) @@ -129,12 +129,14 @@ def test_the_probe_commits_nothing_and_its_trial_meets_the_reference(integrator) native, reference = _pair(problem, request, _soliton_context()) try: probe = native.timing_probe(Start.entrance(problem)) - loaded = native._native_state.field_to_host().copy() dz = float(request.stepper.dz_init) probe.trial() whole = probe.field() - # The readback loaded the start again, exactly: nothing was committed. - assert np.array_equal(native._native_state.field_to_host(), loaded) + # The readback loaded the start again, exactly: nothing was committed, so the + # same trial from it reads back the same field (one build's matched + # computation, compared bitwise as a diagnostic; SEP 25). + probe.trial() + assert np.array_equal(probe.field(), whole) probe.trial(float(problem.initial.z), 0.5 * dz) half = probe.field() assert not np.array_equal(half, whole) @@ -164,8 +166,9 @@ def test_a_low_storage_probe_counts_its_evaluations_and_has_no_field(): assert native.metadata()["source_evaluations"] == 12 with pytest.raises(BackendError, match="no trial field"): probe.field() - # The next load counts from zero, as a fresh backend's. - native.timing_probe(Start.entrance(problem)) - assert native.metadata()["source_evaluations"] == 0 + # The trials advanced the registers in place: the workspace closes with the + # probe, and the backend refuses another (SEP 52 section 5.5). + with pytest.raises(BackendError, match="low-storage timing probe"): + native.timing_probe(Start.entrance(problem)) finally: native.close() diff --git a/tests/sessions/test_native_session.py b/tests/sessions/test_native_session.py index 855abe305..ff6e915fc 100644 --- a/tests/sessions/test_native_session.py +++ b/tests/sessions/test_native_session.py @@ -459,9 +459,9 @@ def test_a_session_leases_its_state_exclusively(): session = _make_native(problem, run_request) backend = session._backend # pyright: ignore[reportPrivateUsage] assert backend is not None - state = backend._native_state # pyright: ignore[reportPrivateUsage] + workspace = backend._workspace # pyright: ignore[reportPrivateUsage] with pytest.raises(RuntimeError, match="leased"): - _testing.rk_march_run(state, {}, {}) + _testing.rk_march_run(workspace, {}, {}) session.close() @@ -533,70 +533,65 @@ def test_the_native_export_is_apply_recipe_to_the_bit(): LEASED_CALLS = { - "set_initial": lambda state, n: state.set_initial( - np.zeros(n, np.complex128), np.empty(0, np.complex128) + "load": lambda workspace, n: _testing.load( + workspace, np.zeros(n, np.complex128), np.empty(0, np.complex128) ), - "rk_march_run": lambda state, n: _testing.rk_march_run(state, {}, {}), - "adams_march_run": lambda state, n: _testing.adams_march_run(state, {}, {}), - "table_slots": lambda state, n: state.table_slots(False, False, 1, False), - "rk_weights_configure": lambda state, n: state.rk_weights_configure([1.0]), - "low_storage_configure": lambda state, n: state.low_storage_configure( - 1, False, 0.0 + "rk_march_run": lambda workspace, n: _testing.rk_march_run(workspace, {}, {}), + "adams_march_run": lambda workspace, n: _testing.adams_march_run( + workspace, {}, {} ), - "flow_guard_configure": lambda state, n: state.flow_guard_configure( - [1.0], [1.0], 1.0, 1, 1.0 + "inject_fault": lambda workspace, n: _testing.inject_fault( + workspace, "trial", 0, "backend" ), - "adams_march_fault": lambda state, n: _testing.adams_march_fault( - state, "trial", 0, "backend" + "field": lambda workspace, n: _testing.field(workspace), + "statistics": lambda workspace, n: _testing.statistics( + workspace, 2, np.empty(0), np.empty(0), 0.0, 1.0, 0.0, 1.0, np.empty(0) ), - "field_to_host": lambda state, n: state.field_to_host(), - "statistics": lambda state, n: _testing.statistics( - state, 2, np.empty(0), np.empty(0), 0.0, 1.0, 0.0, 1.0, np.empty(0) - ), - "finish": lambda state, n: state.finish(1e-6), - "promote_fsal": lambda state, n: _testing.promote_fsal(state), - "clear_fsal": lambda state, n: state.clear_fsal(), - "monitor_reading": lambda state, n: _testing.monitor_reading(state), - "quadrature_peak": lambda state, n: state.quadrature_peak(), + "finish": lambda workspace, n: _testing.finish(workspace, 1e-6), + "promote_fsal": lambda workspace, n: _testing.promote_fsal(workspace), + "monitor_reading": lambda workspace, n: _testing.monitor_reading(workspace), + "engines": lambda workspace, n: _testing.engines(workspace), } -"""Methods of a leased state that mutate it or read its live field or workspace.""" +"""Uses of a leased workspace that mutate its state or read its live field.""" @pytest.mark.parametrize("name", sorted(LEASED_CALLS)) def test_a_leased_state_refuses_every_live_use(name): - """SEP 47 section 5.2: one mutable owner. While a session leases the state, every - method that mutates it or reads its live field or workspace is refused by name; - its fixed facts stay readable, so the execution record can be written. + """SEP 47 section 5.2: one mutable owner. While a session leases the workspace, + every use that mutates its state or reads its live field is refused by name; its + fixed facts stay readable (``diagnostics``), so the execution record can be + written. """ problem, run_request = _case() session = _make_native(problem, run_request) backend = session._backend # pyright: ignore[reportPrivateUsage] assert backend is not None - state = backend._native_state # pyright: ignore[reportPrivateUsage] + workspace = backend._workspace # pyright: ignore[reportPrivateUsage] try: with pytest.raises(RuntimeError, match="leased by an execution session"): - LEASED_CALLS[name](state, int(np.prod(problem.shape))) - assert state.memory_ledger() - assert state.cpu_execution + LEASED_CALLS[name](workspace, int(np.prod(problem.shape))) + diagnostics = workspace.diagnostics() + assert diagnostics["memory_ledger"] + assert diagnostics["cpu_execution"] assert "native_session" in session.execution_record() finally: session.close() # Closed, the session released its lease. with pytest.raises(Exception) as caught: - _testing.rk_march_run(state, {}, {}) + _testing.rk_march_run(workspace, {}, {}) assert "leased" not in str(caught.value) def test_closing_the_state_closes_its_session_first(): - """SEP 47 section 5.2: the state's own close closes the session that leases it, - which then refuses to advance; nothing uses the closed state. + """SEP 47 section 5.2: the workspace's own close closes the session that leases + it, which then refuses to advance; nothing uses the closed workspace. """ problem, run_request = _case() session = _make_native(problem, run_request) batch = session.advance() backend = session._backend # pyright: ignore[reportPrivateUsage] assert backend is not None - backend._native_state.close() # pyright: ignore[reportPrivateUsage] + backend._workspace.close() # pyright: ignore[reportPrivateUsage] assert session.closed with pytest.raises(SessionError): session.acknowledge(batch.receipt) @@ -773,10 +768,10 @@ def test_a_dense_plane_crosses_to_the_host_only_as_its_export(case): session = _make_native(problem, run_request) backend = session._backend # pyright: ignore[reportPrivateUsage] assert backend is not None - state = backend._native_state # pyright: ignore[reportPrivateUsage] - before = state.crossed_bytes() + workspace = backend._workspace # pyright: ignore[reportPrivateUsage] + before = workspace.diagnostics()["crossed_bytes"] run = drive(Started(session), export=CONSUMER) - after = state.crossed_bytes() + after = workspace.diagnostics()["crossed_bytes"] status = session.native.status() session.close() assert status.exports == len(run.observations) @@ -807,11 +802,11 @@ def test_the_ledger_counts_runge_kutta_dense_output_before_and_during_a_session( live = session._backend # pyright: ignore[reportPrivateUsage] assert live is not None assert live.memory_ledger()["rk_dense"] == ledger["rk_dense"] - state = live._native_state # pyright: ignore[reportPrivateUsage] - assert state.memory_ledger()["rk_dense"] == ledger["rk_dense"] + workspace = live._workspace # pyright: ignore[reportPrivateUsage] + assert workspace.diagnostics()["memory_ledger"]["rk_dense"] == ledger["rk_dense"] # Closing the native session releases it, before its backend closes. session.native.close() - assert state.memory_ledger()["rk_dense"] == 0 + assert workspace.diagnostics()["memory_ledger"]["rk_dense"] == 0 session.close() landed, landed_request = _case(step_planes=0) backend = select( diff --git a/tests/sessions/test_native_session_axis_plasma.py b/tests/sessions/test_native_session_axis_plasma.py index bc0b93c5c..480ee1ea6 100644 --- a/tests/sessions/test_native_session_axis_plasma.py +++ b/tests/sessions/test_native_session_axis_plasma.py @@ -206,7 +206,7 @@ def _plan(grid, modes, problem, request, names, seen): out = [] with closing(select("native", problem, run, grid=grid, modes=modes)) as backend: for record in seen: - state = load_native(backend, record.field, clear_fsal=False) + state = load_native(backend, record.field) values = lowering.unpack( _testing.planned_statistics(state, lowering.plan, record.z) ) diff --git a/tests/sessions/test_native_session_statistics.py b/tests/sessions/test_native_session_statistics.py index da815e221..506a5d509 100644 --- a/tests/sessions/test_native_session_statistics.py +++ b/tests/sessions/test_native_session_statistics.py @@ -586,7 +586,7 @@ def test_a_native_plan_refusal_is_the_reference_s_exception(): assert lowering.plan is not None backend = select("native", problem, run_request, grid=grid, modes=modes) try: - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) with pytest.raises(SolpropError) as caught: try: _testing.planned_statistics(state, lowering.plan, far) @@ -860,7 +860,7 @@ def _host_widths(problem, run_request, grid, record, monkeypatch): backend = select("native", problem, run_request, grid=grid) try: # The record's exported state, loaded into the native state itself. - state = load_native(backend, record.field, clear_fsal=False) + state = load_native(backend, record.field) packed = np.ravel( _testing.spatial_statistics( state, 32 if plane else 16, 0.5 * EPS0 * C, record.z diff --git a/tests/vector_raman_cases.py b/tests/vector_raman_cases.py index 5d0453b60..cfbf9a471 100644 --- a/tests/vector_raman_cases.py +++ b/tests/vector_raman_cases.py @@ -147,7 +147,7 @@ def result(backend_class, problem, run_request, grid, modes, options=CHUNK): assert backend.name == "native" assert problem.initial.noise0 is None backend._staged_rows() - state = load_native(backend, problem.initial.field0, clear_fsal=False) + state = load_native(backend, problem.initial.field0) native_trial(backend, 0.0, LENGTH / 8) from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] _testing, From da4b5e6982e97c6bf3acb58e3bf2991b171c2914 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 04:08:07 +0000 Subject: [PATCH 06/29] test: port the native tests to the workspace seam; the split sums in AcceptRecord (SEP 52) Tests that reached the native State now reach the backend's Workspace through _testing (load, field, finish, rk_trial, bind_monitor, edge_reading, table_values, table_load, prepare_raman, adams_rows_from_host, aperture_statistics, low_storage_norms, quadrature_peak, configure_march) and diagnostics(). _testing.engines' accept returns the split collar's sums its finish measured (GeneralState::split_sums, read without draining); the low-storage engine keeps its last squared norm for the forced-thread folds. The adapter projects a TDSE host source's rows in the memory ledger before a run binds them. Co-Authored-By: Claude Opus 5.5 --- benchmarks/device_split.py | 7 +- benchmarks/native_session.py | 2 +- native/include/solprop_native/core.hpp | 8 ++ native/include/solprop_native/low_storage.hpp | 4 + native/include/solprop_native/workspace.hpp | 3 + native/src/bindings.cpp | 97 ++++++++++++- native/src/general/state.cpp | 3 + native/src/general/statistics.cpp | 12 ++ native/src/general/workspace.hpp | 1 + native/src/low_storage.cpp | 1 + native/src/solprop_native/backend.py | 12 +- native/src/solprop_native/session.py | 2 +- native/src/workspace.cpp | 18 ++- native/tests/test_backend.py | 78 +++++----- native/tests/test_band_plasma.py | 16 ++- native/tests/test_coupled_flow.py | 2 +- native/tests/test_dispersive.py | 2 +- native/tests/test_envelope_plasma.py | 7 +- .../tests/test_envelope_statistics_refusal.py | 5 +- native/tests/test_execution.py | 20 +-- native/tests/test_free.py | 93 +++++++----- native/tests/test_mixtures.py | 8 +- native/tests/test_planning.py | 2 +- native/tests/test_raman_tail.py | 2 +- native/tests/test_wisdom.py | 2 +- native/tests/test_workspace.py | 134 ++---------------- src/solprop/calibration/child.py | 2 +- tests/backends/flow_rows.py | 2 +- tests/backends/forced_thread_cases.py | 59 +++++--- tests/backends/native_edge.py | 124 ++++++++++++++++ tests/backends/native_trace_marches.py | 39 +++-- tests/backends/test_compiled_multistep.py | 3 +- tests/backends/test_free_absorber.py | 6 +- tests/backends/test_free_split_rows.py | 7 +- tests/backends/test_monitor_owner.py | 10 +- tests/backends/test_monitor_reduction.py | 91 ++++++------ tests/backends/test_native_dispersive_kerr.py | 6 +- tests/backends/test_native_edge_collar.py | 45 +++--- tests/backends/test_native_edge_reading.py | 52 +++---- tests/backends/test_native_error_norm.py | 38 ++--- tests/backends/test_native_far_field.py | 31 ++-- tests/backends/test_native_gpu.py | 3 +- tests/backends/test_native_held_plasma.py | 2 +- .../test_native_held_projection_budget.py | 2 +- tests/backends/test_native_low_storage.py | 7 +- tests/backends/test_native_march_admission.py | 4 +- tests/backends/test_native_march_rows.py | 2 +- tests/backends/test_native_phi_moments.py | 21 ++- .../backends/test_native_planar_statistics.py | 2 +- tests/backends/test_native_rk_rows.py | 84 ++++++----- tests/backends/test_native_rk_traces.py | 3 +- tests/backends/test_native_stage_tables.py | 8 +- .../backends/test_native_stash_and_saving.py | 14 +- .../test_native_synthetic_operator.py | 24 ++-- tests/backends/test_native_widths.py | 8 +- tests/backends/test_native_z_table.py | 72 ++++++---- tests/backends/test_numpy_mixture_raman.py | 27 +++- tests/backends/test_numpy_ref_multimode.py | 4 +- tests/backends/test_numpy_ref_raman.py | 39 ++++- tests/backends/test_on_axis_statistics.py | 24 +--- tests/backends/test_polarised_runs.py | 2 +- tests/backends/test_radial_absorber.py | 2 +- tests/backends/test_radial_nonlinear.py | 2 +- tests/backends/test_records.py | 86 ----------- tests/backends/test_resident_adams.py | 24 ++-- tests/backends/test_tdse_native.py | 2 +- tests/backends/test_transverse_owner.py | 38 +++-- tests/backends/test_vector_raman.py | 43 +++++- tests/driver/test_abandoned_step.py | 4 +- tests/driver/test_estimate.py | 51 ++++--- tests/driver/test_native_coupled_flow.py | 2 +- tests/driver/test_native_flow_marches.py | 4 +- tests/driver/test_native_flow_pathological.py | 7 +- tests/driver/test_native_flow_session.py | 35 ++--- tests/driver/test_native_march_lifecycle.py | 19 ++- .../driver/test_native_moving_guide_bound.py | 3 +- tests/driver/test_native_resume_history.py | 7 +- tests/driver/test_native_rk_march.py | 68 +++++++-- tests/driver/test_runner.py | 4 +- tests/parity_ladder.py | 2 +- tests/sessions/runs.py | 38 ++--- tests/sessions/test_native_session.py | 4 +- .../test_native_session_carrier_table.py | 16 ++- tests/sessions/test_native_session_device.py | 2 +- tests/sessions/test_native_session_history.py | 17 +-- .../test_native_session_low_storage.py | 4 +- .../test_native_session_transverse.py | 10 +- tests/test_transverse_reads.py | 34 ++--- tests/vector_raman_cases.py | 1 - 89 files changed, 1124 insertions(+), 813 deletions(-) create mode 100644 tests/backends/native_edge.py diff --git a/benchmarks/device_split.py b/benchmarks/device_split.py index 64f39a31e..ef9b7b716 100644 --- a/benchmarks/device_split.py +++ b/benchmarks/device_split.py @@ -261,7 +261,7 @@ def _calls(nx: int, steps: int, planes: int) -> dict[str, Any]: problem, request, backend = _native(_simulation(nx, steps, planes, None)) geometry = problem.transform.geometry x, y = geometry.axes - state = backend._native_state + state = backend._workspace try: with backend.prepare(problem, request).start( Start.entrance(problem), owns=False @@ -297,7 +297,10 @@ def _calls(nx: int, steps: int, planes: int) -> dict[str, Any]: ), } session.acknowledge(batch.receipt) - crossings = {"field_to_host": _timed(state.field_to_host, 3), **exports} + crossings = { + "field_to_host": _timed(lambda: _testing.field(state), 3), + **exports, + } # A width's parts: the fluence and its moments, one native call; and what the # host's azimuthal average of a Gaussian's fluence takes on this machine. widths = { diff --git a/benchmarks/native_session.py b/benchmarks/native_session.py index 2a6b17c08..fd304e31f 100644 --- a/benchmarks/native_session.py +++ b/benchmarks/native_session.py @@ -212,7 +212,7 @@ def _once( _counters.disable() # The field bytes through the state's crossings, each way (SEP 44): a device's # plane exports and loads, or a host build's copies. - to_host, from_host = session._backend._native_state.crossed_bytes() + to_host, from_host = session._backend._diagnostics()["crossed_bytes"] record: dict[str, Any] = { "crossed_to_host": int(to_host), "crossed_from_host": int(from_host), diff --git a/native/include/solprop_native/core.hpp b/native/include/solprop_native/core.hpp index 10e9ef8d8..42821422d 100644 --- a/native/include/solprop_native/core.hpp +++ b/native/include/solprop_native/core.hpp @@ -19,6 +19,7 @@ #include #include #include +#include #include #include #include @@ -1345,6 +1346,13 @@ class GeneralState { * last step's split found (zeros before the first such step). */ [[nodiscard]] std::vector monitor_reading(); + /** + * The last accepted step's split collar sums, read without draining anything (SEP + * 52 section 5.2's `AcceptRecord`): what its split took, then `sum_t P` and the two + * guards' and the collar's sums of the power it found, from the masked field before + * the split; none without a bound monitor and a split collar. + */ + [[nodiscard]] std::optional> split_sums(); /** * Bind the split collar's walk-off bucket of each frequency bin, by mode * `(n_modes, n_omega)`, `count` buckets (solprop #440): from here on diff --git a/native/include/solprop_native/low_storage.hpp b/native/include/solprop_native/low_storage.hpp index 56006f3eb..fceb521d5 100644 --- a/native/include/solprop_native/low_storage.hpp +++ b/native/include/solprop_native/low_storage.hpp @@ -115,6 +115,9 @@ class ResidentLowStorage final : public rk::Engine { void accept(double dz) override; std::vector reading() override; [[nodiscard]] bool in_flight() const noexcept override { return in_flight_; } + /** The last trial's squared norm over the norm mask, from the passes' own threaded + reduction, before the history's 0.0 replaces a finite one (a test's reading). */ + [[nodiscard]] double squared() const noexcept { return squared_; } private: void inject(march::Stage stage); @@ -128,6 +131,7 @@ class ResidentLowStorage final : public rk::Engine { std::optional& fault_; /** The key the held table was built for; NaN before the first step. */ double table_step_; + double squared_ = 0.0; bool in_flight_ = false; }; diff --git a/native/include/solprop_native/workspace.hpp b/native/include/solprop_native/workspace.hpp index eb6467a51..afa4a63ec 100644 --- a/native/include/solprop_native/workspace.hpp +++ b/native/include/solprop_native/workspace.hpp @@ -730,6 +730,9 @@ class Workspace { /** The configured march's engines over the state, for an engine-level test: the Runge-Kutta (or low-storage) engine and the Adams engine. */ std::unique_ptr trial_engine(); + /** The low-storage replay's engine over the state, its type kept for a test that + reads its squared norms. */ + std::unique_ptr low_storage_engine(); std::unique_ptr adams_engine(); private: diff --git a/native/src/bindings.cpp b/native/src/bindings.cpp index c31089bd5..0a9832650 100644 --- a/native/src/bindings.cpp +++ b/native/src/bindings.cpp @@ -2406,6 +2406,18 @@ class TestEngines { /** solprop's protocol records, built where a test reads them. */ nb::object engines_module() { return nb::module_::import_("solprop.backends.engines"); } +/** An accepted step's `AcceptRecord` (SEP 52 section 5.2): the split collar's sums its + finish measured, from the masked field before the split, where a monitor reads a + split collar; the stiffness is not formed natively (NaN). */ +nb::object accept_record(native::GeneralState& state) { + auto sums = state.split_sums(); + if (!sums) + return engines_module().attr("AcceptRecord")(); + const std::vector found(sums->begin() + 1, sums->end()); + return engines_module().attr("AcceptRecord")( + "removed"_a = (*sums)[0], "found"_a = nb::cast(real_output(found, 1)).attr("reshape")(-1)); +} + nb::object boundary_reading(const std::vector& values) { if (values.size() < native::watch::reading_head) throw std::logic_error("a boundary reading is too short"); @@ -2459,7 +2471,7 @@ void bind_engines(nb::module_& testing) { const nb::gil_scoped_release release; engine.accept(dz); } - return engines_module().attr("AcceptRecord")(); + return accept_record(self.state()); }) .def("rk_extend", [](TestEngines& self, const double z, const double dz) { self.runge_kutta().extend(z, dz); }) @@ -2501,7 +2513,7 @@ void bind_engines(nb::module_& testing) { const nb::gil_scoped_release release; engine.accept(dz, free, stencil, entries); } - return engines_module().attr("AcceptRecord")(); + return accept_record(self.state()); }) .def("adams_chord_phase", [](TestEngines& self, const double z1, const double z2) { @@ -3253,6 +3265,87 @@ void bind_testing(nb::module_& testing) { {workspace.columns(), values.size() / workspace.columns()}); }, "workspace"_a, "kind"_a, "z"_a); + // The slot each position's z-table value is held in, evaluating only those no slot + // holds (solprop SEP 29 G1; at most the slots a call). + testing.def( + "table_load", + [](BoundWorkspace& owner, const std::vector& positions) { + auto& workspace = owner.workspace(); + auto& state = workspace.state(); + auto& slots = workspace.z_slots(); + if (!slots.present()) + throw std::logic_error("no z table's slots were configured"); + const nb::gil_scoped_release release; + return slots.load(state, positions); + }, + "workspace"_a, "positions"_a); + // Write a history row `(n_slots, rows, n_omega)` straight into the resident Adams + // history, as a resumed run's start does. + testing.def( + "adams_rows_from_host", + [](BoundWorkspace& owner, const std::string& name, const ComplexInput rows) { + auto& state = owner.workspace().state(); + const auto extents = state.adams_row_extents(name); + if (rows.ndim() != 3 || rows.shape(0) != extents[0] || + rows.shape(1) != extents[1] || rows.shape(2) != extents[2]) + native::refuse("the Adams history row '", name, "' must have shape (", + extents[0], ", ", extents[1], ", ", extents[2], ")"); + const auto values = complex_vector(rows); + const nb::gil_scoped_release release; + state.adams_rows_from_host(name, values); + }, + "workspace"_a, "name"_a, "rows"_a.noconvert()); + // The far-field statistics' banded pass on the state (solprop SEP 23 section 6). + testing.def( + "aperture_statistics", + [](BoundWorkspace& owner, const std::uint64_t flags, const RealInput apertures, + const int exponent, const RealInput regions, const double intensity_factor) { + if (apertures.ndim() != 2 || regions.ndim() != 2 || regions.shape(1) != 4) + throw std::invalid_argument( + "aperture tables must be (n_apertures, 11 + n_omega) and regions " + "(n_regions, 4)"); + const auto held_apertures = real_vector(apertures); + const auto held_regions = real_vector(regions); + auto& state = owner.workspace().state(); + std::vector values; + { + const nb::gil_scoped_release release; + values = state.aperture_statistics(flags, held_apertures, exponent, + held_regions, intensity_factor); + } + return real_output(std::move(values), 1); + }, + "workspace"_a, "flags"_a, "apertures"_a.noconvert(), "exponent"_a, + "regions"_a.noconvert(), "intensity_factor"_a); + // March the low-storage replay's engine over consecutive positions, each step + // finished as the state's finish alone, and return each step's squared norm over the + // norm mask from the passes' own reduction (the forced-thread folds' reading). The + // run's records must be configured (`configure_march`). + testing.def( + "low_storage_norms", + [](BoundWorkspace& owner, const std::vector& positions) { + auto& workspace = owner.workspace(); + workspace.require_unleased(); + auto engine = workspace.low_storage_engine(); + auto& state = workspace.state(); + std::vector norms; + { + const nb::gil_scoped_release release; + for (std::size_t index = 0; index + 1 < positions.size(); ++index) { + const double dz = positions[index + 1] - positions[index]; + static_cast(engine->trial(positions[index], dz)); + norms.push_back(engine->squared()); + state.finish(dz); + } + } + return real_output(norms.empty() ? std::vector{} : std::move(norms), 1); + }, + "workspace"_a, "positions"_a); + // The largest accepted step's quadrature score since the last read, drained. + testing.def( + "quadrature_peak", + [](BoundWorkspace& owner) { return owner.workspace().state().quadrature_peak(); }, + "workspace"_a); testing.def( "table_evaluations", [](BoundWorkspace& owner) { return owner.workspace().z_slots().evaluations; }, diff --git a/native/src/general/state.cpp b/native/src/general/state.cpp index 424aa8e02..4bb6510a1 100644 --- a/native/src/general/state.cpp +++ b/native/src/general/state.cpp @@ -334,6 +334,9 @@ void GeneralState::unbind_monitor() noexcept { std::vector GeneralState::monitor_reading() { return with_team(&GeneralWorkspace::monitor_reading); } +std::optional> GeneralState::split_sums() { + return with_team(&GeneralWorkspace::split_sums); +} void GeneralState::bind_edge(const std::vector& faces, const std::vector& clip, const std::vector& totals, diff --git a/native/src/general/statistics.cpp b/native/src/general/statistics.cpp index 9b33cfd7e..ed4b33402 100644 --- a/native/src/general/statistics.cpp +++ b/native/src/general/statistics.cpp @@ -2343,6 +2343,18 @@ EdgeNumbers GeneralWorkspace::edge_reading(const bool faces, const bool whole, return reading; } +std::optional> GeneralWorkspace::split_sums() { + if (!monitoring_split()) + return std::nullopt; + // The last step's split adds its chunks' sums here, the removal first (`split_step`): + // read where they are kept, nothing drained. + execution_space_.fence("solprop_native split sums"); + const auto found = + Kokkos::create_mirror_view_and_copy(Kokkos::HostSpace{}, monitor_found_)(); + return std::array{found.values[0], found.values[1], found.values[2], + found.values[3], found.values[4]}; +} + std::vector GeneralWorkspace::monitor_reading() { if (!initialized_) throw std::logic_error("no initial field has been loaded"); diff --git a/native/src/general/workspace.hpp b/native/src/general/workspace.hpp index 5c9b38985..b6d74594e 100644 --- a/native/src/general/workspace.hpp +++ b/native/src/general/workspace.hpp @@ -140,6 +140,7 @@ class GeneralWorkspace { void unbind_monitor() noexcept { monitor_bound_ = false; } void bind_occupancy(const std::vector& buckets, std::size_t count); std::vector monitor_reading(); + std::optional> split_sums(); void bind_edge(const std::vector& faces, const std::vector& clip, const std::vector& totals, const std::vector& synthesis, std::size_t first_row); diff --git a/native/src/low_storage.cpp b/native/src/low_storage.cpp index fad1ea646..86532d7d1 100644 --- a/native/src/low_storage.cpp +++ b/native/src/low_storage.cpp @@ -196,6 +196,7 @@ double ResidentLowStorage::trial(const double z, const double dz) { const auto scalars = rk::low_storage::scalars(tables_, anchor_, config_, z, dz, rebuild, key); const double squared = state_.low_storage_step(dz, scalars, rebuild); + squared_ = squared; if (rebuild) table_step_ = key; // An injected failure after the passes, the state already overwritten. diff --git a/native/src/solprop_native/backend.py b/native/src/solprop_native/backend.py index c99866531..e72f8b142 100644 --- a/native/src/solprop_native/backend.py +++ b/native/src/solprop_native/backend.py @@ -1098,6 +1098,9 @@ def memory_ledger(self) -> dict[str, int]: field = int(ledger.get("state", 0)) ledger["rk_dense"] = 6 * field + field // 16 if self._tdse_binding is not None: + # The host source's field and source rows (SEP 49), before a run binds + # them, so that an estimate made before the run counts them. + ledger.setdefault("host_source", 2 * 16 * int(self._problem.shape[-1])) ledger |= { f"tdse_{name}": int(size) for name, size in self._tdse_binding.memory_ledger().items() @@ -1677,7 +1680,12 @@ def __init__( self._last_rejected = False self._order = 1 if method.variable_order else method.order self.ledger = CallLedger() - carrier = carrier_reference(problem, method) + # A scripted harness's history holds its own frame. + carrier = ( + carrier_reference(problem, method) + if engine is None + else getattr(engine, "carrier", None) + ) # Every number the native controller and landings read (SEP 39 section 4.2), # formed as the reference forms it. self._policy: MarchPolicy = adams_policy( @@ -1868,7 +1876,7 @@ def start_state(self, z: float, proposal: float, cursor: int) -> dict[str, objec for entry in self._history ], "ledger": {name: getattr(ledger, name) for name in _MARCH_COUNTERS}, - "watch": FRESH_WATCH, + "watch": dict(FRESH_WATCH), } def _raise(self, reason: int, result: dict[str, Any]) -> None: diff --git a/native/src/solprop_native/session.py b/native/src/solprop_native/session.py index 29fc2c072..c6064f762 100644 --- a/native/src/solprop_native/session.py +++ b/native/src/solprop_native/session.py @@ -623,7 +623,7 @@ def _prepare(self, backend: NativeBackend, start: Start) -> dict[str, object]: "z": float(loaded.z), "proposal": float(proposal), "norms": [], - "watch": FRESH_WATCH, + "watch": dict(FRESH_WATCH), "cursor": int(loaded.cursor), } self._edge_noise = self._noise_readings(driver) diff --git a/native/src/workspace.cpp b/native/src/workspace.cpp index c5df58bf9..0750897ac 100644 --- a/native/src/workspace.cpp +++ b/native/src/workspace.cpp @@ -653,13 +653,8 @@ MethodKind Workspace::kind() const noexcept { std::unique_ptr Workspace::trial_engine() { auto& general = built(); - if (low_storage_) { - if (!stage_tables_ || !rk_policy_) - throw std::logic_error("the native low-storage replay is not configured"); - return std::make_unique( - general, *stage_tables_, stage_anchor_, *low_storage_, rk_schedule_, - rk_policy_->landings.landing_ulps, fault_); - } + if (low_storage_) + return low_storage_engine(); if (!runge_kutta_) throw std::logic_error("the native Runge-Kutta trial is not configured"); return std::make_unique( @@ -668,6 +663,15 @@ std::unique_ptr Workspace::trial_engine() { runge_kutta_->rtol, runge_kutta_->atol, runge_kutta_->weights); } +std::unique_ptr Workspace::low_storage_engine() { + auto& general = built(); + if (!low_storage_ || !stage_tables_ || !rk_policy_) + throw std::logic_error("the native low-storage replay is not configured"); + return std::make_unique( + general, *stage_tables_, stage_anchor_, *low_storage_, rk_schedule_, + rk_policy_->landings.landing_ulps, fault_); +} + std::unique_ptr Workspace::adams_engine() { auto& general = built(); if (!stage_tables_) diff --git a/native/tests/test_backend.py b/native/tests/test_backend.py index ae7f1991d..2f5450d11 100644 --- a/native/tests/test_backend.py +++ b/native/tests/test_backend.py @@ -22,9 +22,9 @@ from legacy_geometry import LEGACY_GRID from session_runs import committed_steps, load_native, native_trial, run from solprop.backends.events import ObservationReady -from solprop.backends.low_storage import schedule_key from solprop.backends.node_chunk import plan_node_chunk from solprop.backends.numpy_ref import NumpyRefBackend +from solprop.backends.records import run_records from solprop.backends.session import Start from solprop.driver import Simulation from solprop.exceptions import BackendError, TranslationError @@ -49,7 +49,6 @@ from solprop_native.backend import ( _lower, # pyright: ignore[reportPrivateUsage] _LowerPlan, # pyright: ignore[reportPrivateUsage] - _ResidentLowStorage, # pyright: ignore[reportPrivateUsage] ) from solprop_native.session import NativeSession @@ -328,20 +327,22 @@ def test_a_low_storage_table_never_built_is_refused(phase_a_case: PhaseACase) -> marched, marched_request = problem, run_request.with_stepper(stepper) backend = NativeBackend(marched, marched_request, grid=grid) try: - # The resident engine on the loaded state, with the key of the first step's - # table, which no step built. - load_native(backend, marched.initial.field0) - method = marched_request.stepper.integrator - assert isinstance(method, LowStorageRungeKutta) - engine = _ResidentLowStorage(backend, method) - engine._table_step = schedule_key( # pyright: ignore[reportPrivateUsage] - engine._keys, # pyright: ignore[reportPrivateUsage] - engine._edges, # pyright: ignore[reportPrivateUsage] - 0.0, - target / 4, + # The resident engine builds the first step's table; a load then forgets + # it, and the same engine, still holding that step's key, steps again. + workspace = load_native(backend, marched.initial.field0) + _testing.configure_march( + workspace, + run_records(marched, marched_request, Start.entrance(marched)), ) - with pytest.raises(RuntimeError, match="table has not been built"): - engine.step(0.0, target / 4) + engines = _testing.engines(workspace) + try: + engines.rk_trial(0.0, target / 4) + field = np.ascontiguousarray(marched.initial.field0).reshape(-1) + engines.load(field, np.empty(0, dtype=np.complex128)) + with pytest.raises(RuntimeError, match="table has not been built"): + engines.rk_trial(0.0, target / 4) + finally: + engines.close() finally: backend.close() @@ -429,7 +430,7 @@ def forbidden(*_arguments: object, **_keywords: object) -> NoReturn: raise AssertionError("unsupported TDSE reached native setup") monkeypatch.setattr(solprop_native.backend, "require_device_ready", forbidden) - monkeypatch.setattr(_core, "State", forbidden) + monkeypatch.setattr(_core, "Workspace", forbidden) with pytest.raises(BackendError, match="explicit host response binding"): NativeBackend(requested, requested_request, grid=grid) @@ -599,11 +600,6 @@ def test_statistics_do_not_observe_the_full_field( names = ("omega0", "energy", "peak_power", "fwhm_t") run_request = run_request.for_run(stats=StatsSpec(names=names)) backend = NativeBackend(problem, run_request, grid=grid) - - def fail_if_observed(state: object) -> NoReturn: - pytest.fail(f"statistics observed native state {state!r}") - - monkeypatch.setattr(backend, "_observed_field", fail_if_observed) session = backend.prepare(problem, run_request).start(Start.entrance(problem)) observed: list[dict[str, np.ndarray]] = [] try: @@ -634,13 +630,20 @@ def test_raman_metadata_memoization_and_conditional_ledger( coefficients = problem.responses.raman_coefficients assert coefficients is not None rates = tuple(float(table(0.0)) for table in coefficients.decay_rates) - backend._raman_spectrum(rates) # pyright: ignore[reportPrivateUsage] - assert backend._raman_transforms == 1 # pyright: ignore[reportPrivateUsage] - backend._raman_spectrum(rates) # pyright: ignore[reportPrivateUsage] - assert backend._raman_transforms == 1 # pyright: ignore[reportPrivateUsage] - backend._raman_spectrum(tuple(reversed(rates))) # pyright: ignore[reportPrivateUsage] + workspace = backend._workspace # pyright: ignore[reportPrivateUsage] + none = np.empty(0, dtype=np.float64) + + def transforms() -> int: + diagnostics = backend._diagnostics() # pyright: ignore[reportPrivateUsage] + return int(diagnostics["raman_kernel_transforms"]) + + _testing.prepare_raman(workspace, np.asarray(rates), none) + assert transforms() == 1 + _testing.prepare_raman(workspace, np.asarray(rates), none) + assert transforms() == 1 + _testing.prepare_raman(workspace, np.asarray(rates[::-1]), none) expected = 1 if len(set(rates)) == 1 else 2 - assert backend._raman_transforms == expected # pyright: ignore[reportPrivateUsage] + assert transforms() == expected metadata = backend.metadata() ledger = backend.memory_ledger() assert metadata["raman_enabled"] is True @@ -688,7 +691,7 @@ def _spoil() -> None: raman.undamped = np.zeros( (rows.shape[0], 2 * rows.shape[1]), dtype=np.float64 )[:, ::2] - _core.State(payload) + _core.Workspace(payload) with pytest.raises((TypeError, ValueError)): _spoil() @@ -706,7 +709,7 @@ def test_native_raman_tables_refuse_a_transposed_layout( else: raman.tensor_weights = raman.tensor_weights.reshape(2, raman.n_terms) with pytest.raises(ValueError, match=f"raman_{spoiling} must have shape"): - _core.State(payload) + _core.Workspace(payload) @pytest.mark.parametrize("spoiling", ["flat", "rank_four", "count"]) @@ -738,7 +741,7 @@ def test_native_fixed_terms_refuse_a_wrong_layout( payload.linear.phi_terms = phi.reshape(phi.shape[::-1]) message = "phi_terms must hold n_phi_terms rows" with pytest.raises(ValueError, match=message): - _core.State(payload) + _core.Workspace(payload) def test_native_raman_rows_accept_read_only_input(raman_case: RamanCase) -> None: @@ -747,24 +750,23 @@ def test_native_raman_rows_accept_read_only_input(raman_case: RamanCase) -> None rows = payload.raman.undamped.reshape(payload.raman.n_terms, -1) rows.setflags(write=False) payload.raman.undamped = rows - state = _core.State(payload) - state.close() + workspace = _core.Workspace(payload) + workspace.close() def test_native_raman_rates_refuse_wrong_dtype_and_shape( raman_case: RamanCase, ) -> None: """The diagnostic preparation seam has the same exact-array contract as trials.""" - state = _core.State(_raman_native_payload(raman_case)) + workspace = _core.Workspace(_raman_native_payload(raman_case)) + none = np.empty(0, dtype=np.float64) try: with pytest.raises(TypeError): - state.prepare_raman( - np.zeros(1, dtype=np.float32) # pyright: ignore[reportArgumentType] - ) + _testing.prepare_raman(workspace, np.zeros(1, dtype=np.float32), none) with pytest.raises(ValueError, match="shape"): - state.prepare_raman(np.zeros((1, 1), dtype=np.float64)) + _testing.prepare_raman(workspace, np.zeros((1, 1), dtype=np.float64), none) finally: - state.close() + workspace.close() def test_metadata_and_memory_ledger_are_self_consistent( diff --git a/native/tests/test_band_plasma.py b/native/tests/test_band_plasma.py index bd9b7b950..d59504a0d 100644 --- a/native/tests/test_band_plasma.py +++ b/native/tests/test_band_plasma.py @@ -580,7 +580,7 @@ def test_quadrature_keeps_accepted_scores_through_rejection_and_reset( owns=True, ) backend = NativeBackend(problem, run_request, grid=grid, options=options) - state = backend._native_state # pyright: ignore[reportPrivateUsage] - score lifetime + state = backend._workspace # pyright: ignore[reportPrivateUsage] - score lifetime try: record: dict[str, object] = {} finished = run(backend, problem, run_request, record=record) @@ -615,7 +615,7 @@ def test_quadrature_keeps_accepted_scores_through_rejection_and_reset( native_record = record["native_session"] assert isinstance(native_record, dict) assert native_record["quadrature_peak"] == max(steps) - assert math.isnan(state.quadrature_peak()) + assert math.isnan(_testing.quadrature_peak(state)) # Leave an unaccepted trial in scratch: the stored score and the accepted # field stay. (Its positions are the first step's, inside the problem's @@ -623,8 +623,10 @@ def test_quadrature_keeps_accepted_scores_through_rejection_and_reset( native_trial(backend, dz, 0.5 * dz) # The stored accepted value, no arithmetic. assert _testing.quadrature_error(state) == score - assert math.isnan(state.quadrature_peak()) - np.testing.assert_array_equal(state.field_to_host().reshape(got.shape), got) + assert math.isnan(_testing.quadrature_peak(state)) + np.testing.assert_array_equal( + np.asarray(_testing.field(state)).reshape(got.shape), got + ) # A second run's load resets the score (read once the session, closed before # its first step, returns the state); its first step repeats the first's. @@ -632,7 +634,7 @@ def test_quadrature_keeps_accepted_scores_through_rejection_and_reset( Start.entrance(problem), owns=False ).close() assert math.isnan(_testing.quadrature_error(state)) - assert math.isnan(state.quadrature_peak()) + assert math.isnan(_testing.quadrature_peak(state)) again = run(backend, problem, run_request).fields np.testing.assert_allclose( again[1], @@ -780,7 +782,7 @@ def test_native_taps_are_validated(damage: str) -> None: # The trapezoid is the one identity tap and nothing else. plasma.band = False with pytest.raises(ValueError, match=r"taps|trapezoid|band"): - _core.State(payload) + _core.Workspace(payload) def test_native_rate_table_refuses_a_transposed_layout() -> None: @@ -801,7 +803,7 @@ def test_native_rate_table_refuses_a_transposed_layout() -> None: plasma.rate_intervals, 4 ) with pytest.raises(ValueError, match=r"rate_coefficients must have shape"): - _core.State(payload) + _core.Workspace(payload) def test_the_diagnostics_need_a_field_plasma_column(phase_a_case: PhaseACase) -> None: diff --git a/native/tests/test_coupled_flow.py b/native/tests/test_coupled_flow.py index 8f2068498..7839d0cfb 100644 --- a/native/tests/test_coupled_flow.py +++ b/native/tests/test_coupled_flow.py @@ -344,7 +344,7 @@ def test_the_engine_forms_the_reference_s_actions_within_the_formation_bound() - ) backend = NativeBackend(problem, run_request, grid=case.grid) try: - native = backend._native_state # pyright: ignore[reportPrivateUsage] + native = backend._workspace # pyright: ignore[reportPrivateUsage] shape = (fractions.size, -1, reference.n_modes, reference.n_modes) for section in range(reference.frozen.shape[0]): measured = _testing.form_flow_actions(native, section, dz, fractions)[0] diff --git a/native/tests/test_dispersive.py b/native/tests/test_dispersive.py index dbd9d2192..20fcf63e4 100644 --- a/native/tests/test_dispersive.py +++ b/native/tests/test_dispersive.py @@ -289,7 +289,7 @@ def test_a_trial_without_the_densities_is_refused() -> None: n_phi = terms.shape[0] with pytest.raises(ValueError, match="dispersive densities"): _testing.trial_step( - backend._native_state, # pyright: ignore[reportPrivateUsage] + backend._workspace, # pyright: ignore[reportPrivateUsage] 1e-4, np.zeros((stages + 1) * n_phi), np.zeros(stages * n_phi), diff --git a/native/tests/test_envelope_plasma.py b/native/tests/test_envelope_plasma.py index 1ee5a34b4..4874eff31 100644 --- a/native/tests/test_envelope_plasma.py +++ b/native/tests/test_envelope_plasma.py @@ -406,7 +406,7 @@ def _spoil() -> None: index = int(np.flatnonzero(mask if corruption == "sign" else ~mask)[0]) array[index] = 1.0 plasma.envelope_drude_factor = array - _core.State(payload) + _core.Workspace(payload) # A reordered rule keeps its elements: only its layout can refuse it. match = "envelope rules require" if corruption == "layout" else "envelope" @@ -444,7 +444,10 @@ def test_envelope_angular_failure_is_a_solprop_convergence_error( payload.plasma.envelope_rule_nodes = nodes def corrupt_payload(*args: object, **keywords: object) -> _core.Problem: - return payload + # The backend's own lowering, its set-once data included, with the bad rule. + built = _lower(*args, **keywords) # pyright: ignore[reportArgumentType] + built.plasma.envelope_rule_nodes = nodes + return built monkeypatch.setattr(adapter, "_lower", corrupt_payload) owner = NativeBackend( diff --git a/native/tests/test_envelope_statistics_refusal.py b/native/tests/test_envelope_statistics_refusal.py index 9116b28a5..9be0e921e 100644 --- a/native/tests/test_envelope_statistics_refusal.py +++ b/native/tests/test_envelope_statistics_refusal.py @@ -51,7 +51,10 @@ def test_the_statistics_refuse_and_a_quiet_field_recovers( payload.plasma.envelope_rule_nodes = nodes def corrupt_payload(*args: object, **keywords: object) -> _core.Problem: - return payload + # The backend's own lowering, its set-once data included, with the bad rule. + built = _lower(*args, **keywords) # pyright: ignore[reportArgumentType] + built.plasma.envelope_rule_nodes = nodes + return built monkeypatch.setattr(adapter, "_lower", corrupt_payload) # The launch plane's statistics meet the bad rule before any step. diff --git a/native/tests/test_execution.py b/native/tests/test_execution.py index 705ea3243..9e510de94 100644 --- a/native/tests/test_execution.py +++ b/native/tests/test_execution.py @@ -227,16 +227,16 @@ def test_a_state_reads_back_the_record_it_was_built_with( **{f"{name}_threshold": 1 << 40 for name in ("stage", "copy", "adams")}, **{f"{name}_full": 1 << 40 for name in ("stage", "copy", "adams")}, ) - first = _core.State(payload) - second = _core.State(_with_record(payload, serial.native())) + first = _core.Workspace(payload) + second = _core.Workspace(_with_record(payload, serial.native())) try: # Two live workspaces hold their own records (solprop SEP 46 section 7 item 7). - assert first.cpu_execution == native.BUILTIN_EXECUTION.native() - assert second.cpu_execution == serial.native() + assert first.diagnostics()["cpu_execution"] == native.BUILTIN_EXECUTION.native() + assert second.diagnostics()["cpu_execution"] == serial.native() if native.build_info().cpu_size_policy_enabled: assert all( choice["threads"] == 1 - for name, choice in second.execution_sizing.items() + for name, choice in second.diagnostics()["execution_sizing"].items() if name.startswith(("kernels.stage.", "kernels.copy.")) ) finally: @@ -259,10 +259,10 @@ def test_a_state_refuses_a_missing_or_malformed_record( def _spoil() -> None: if change == "missing": - _core.State(_with_record(payload)) + _core.Workspace(_with_record(payload)) else: assert isinstance(change, dict) - _core.State(_with_record(payload, change["cpu_execution"])) + _core.Workspace(_with_record(payload, change["cpu_execution"])) with pytest.raises(ValueError, match=message): _spoil() @@ -274,12 +274,12 @@ def test_a_state_refuses_a_record_the_native_core_refuses( payload = _payload(phase_a_case) record = native.BUILTIN_EXECUTION.native() with pytest.raises(ValueError, match="positive threshold"): - _core.State(_with_record(payload, record | {"dense_full": 1})) + _core.Workspace(_with_record(payload, record | {"dense_full": 1})) with pytest.raises(ValueError, match="positive response bounds"): - _core.State(_with_record(payload, record | {"medium_threads": 0})) + _core.Workspace(_with_record(payload, record | {"medium_threads": 0})) renamed = {k: v for k, v in record.items() if k != "adams_full"} with pytest.raises(ValueError, match="misses a field: adams_full"): - _core.State(_with_record(payload, renamed | {"adams_fulll": 1})) + _core.Workspace(_with_record(payload, renamed | {"adams_fulll": 1})) def test_a_backend_given_a_record_builds_with_it_and_records_it( diff --git a/native/tests/test_free.py b/native/tests/test_free.py index ea815c826..bc2025382 100644 --- a/native/tests/test_free.py +++ b/native/tests/test_free.py @@ -126,7 +126,7 @@ def test_free_native_vectors_reject_invalid_data( def _spoil() -> None: _set(free_payload, name, values) - _core.State(free_payload) + _core.Workspace(free_payload) with pytest.raises((TypeError, ValueError)): _spoil() @@ -148,7 +148,7 @@ def test_free_native_axes_and_clamp_are_checked( ) -> None: def _spoil() -> None: _set(free_payload, name, value) - _core.State(free_payload) + _core.Workspace(free_payload) with pytest.raises((TypeError, ValueError)): _spoil() @@ -163,15 +163,15 @@ def test_the_far_field_payload_belongs_to_free_space( assert free_payload.spatial.k_y.shape == (6,) planar_payload.spatial.far_field_slots = 3 with pytest.raises(ValueError, match="belong to free space"): - _core.State(planar_payload) + _core.Workspace(planar_payload) def test_free_native_ledger_retains_one_transverse_volume_and_chunked_time( free_payload: _core.Problem, ) -> None: - state = _core.State(free_payload) + state = _core.Workspace(free_payload) try: - ledger = state.memory_ledger() + ledger = state.diagnostics()["memory_ledger"] omega, time = ( free_payload.dims.n_omega, free_payload.dims.n_to, @@ -203,31 +203,47 @@ def test_free_native_ledger_retains_one_transverse_volume_and_chunked_time( state.close() +def _with_adams(payload: _core.Problem, slots: int, *, dense: bool) -> _core.Problem: + """Return `payload`, this test's own, with a resident Adams history in its setup.""" + held: Any = payload + held.adams = { + "slots": slots, + "compensated": False, + "interpolate": dense, + "fused": False, + "rtol": 1e-6, + "atol": 1e-12, + "weights": np.empty(0), + } + return held + + @pytest.mark.parametrize("slots", [3, 7, 8]) -def test_adams_dense_storage_is_optional_and_reallocation_is_idempotent( - free_payload: _core.Problem, slots: int +@pytest.mark.parametrize("dense", [False, True]) +def test_adams_dense_storage_is_optional( + free_payload: _core.Problem, slots: int, dense: bool ) -> None: - state = _core.State(free_payload) + state = _core.Workspace(_with_adams(free_payload, slots, dense=dense)) try: - field_bytes = state.memory_ledger()["state"] + ledger = state.diagnostics()["memory_ledger"] + field_bytes = ledger["state"] omega = free_payload.dims.n_omega initial = np.zeros(field_bytes // 16, dtype=np.complex128) - state.set_initial(initial, np.empty(0, dtype=np.complex128)) - for dense in (False, True, True, False): - state.adams_allocate(slots, False, dense) - expected = (2 * slots + 4 + (slots + 4 if dense else 0)) * field_bytes - assert state.memory_ledger()["adams_history"] == expected + 8 * omega - if dense: + _testing.load(state, initial, np.empty(0, dtype=np.complex128)) + expected = (2 * slots + 4 + (slots + 4 if dense else 0)) * field_bytes + # The divisor row, and the controller's magnitude sum the setup's scale forms. + assert ledger["adams_history"] == expected + 8 * omega + 8 + if dense: + _testing.adams_hold(state) + _testing.adams_restore(state) + np.testing.assert_array_equal( + np.asarray(_testing.field(state)).reshape(-1), initial + ) + else: + with pytest.raises(RuntimeError, match="dense observation storage"): _testing.adams_hold(state) + with pytest.raises(RuntimeError, match="dense observation storage"): _testing.adams_restore(state) - np.testing.assert_array_equal( - state.field_to_host().reshape(-1), initial - ) - else: - with pytest.raises(RuntimeError, match="dense observation storage"): - _testing.adams_hold(state) - with pytest.raises(RuntimeError, match="dense observation storage"): - _testing.adams_restore(state) finally: state.close() state.close() @@ -239,34 +255,33 @@ def test_adams_rows_cross_to_the_host_and_back_exactly( # solprop SEP 29 G2: the resident history's rows are exported for a resume and # installed again; a copy, so exact, and refused by name, extent, dtype and order # before anything is copied. - state = _core.State(free_payload) + state = _core.Workspace(_with_adams(free_payload, 3, dense=False)) try: - columns = state.memory_ledger()["state"] // 16 + diagnostics = state.diagnostics() + columns = diagnostics["memory_ledger"]["state"] // 16 omega = free_payload.dims.n_omega - state.set_initial( - np.zeros(columns, dtype=np.complex128), np.empty(0, dtype=np.complex128) + _testing.load( + state, + np.zeros(columns, dtype=np.complex128), + np.empty(0, dtype=np.complex128), ) - state.adams_allocate(3, False, False) - assert state.adams_row_names() == ["store"] + assert diagnostics["history_rows"] == ["store"] shape = (3, columns // omega, omega) rng = np.random.default_rng(29) rows = rng.standard_normal(shape) + 1j * rng.standard_normal(shape) - state.adams_rows_from_host("store", rows) + _testing.adams_rows_from_host(state, "store", rows) back = _testing.adams_rows_to_host(state, "store") assert back.shape == shape assert back.dtype == np.complex128 np.testing.assert_array_equal(back, rows) with pytest.raises(ValueError, match="must have shape"): - state.adams_rows_from_host("store", rows[:2]) + _testing.adams_rows_from_host(state, "store", rows[:2]) with pytest.raises(ValueError, match="must have shape"): - state.adams_rows_from_host("store", rows.reshape(3, -1)) + _testing.adams_rows_from_host(state, "store", rows.reshape(3, -1)) with pytest.raises(TypeError): - state.adams_rows_from_host( - "store", - rows.real.copy(), # pyright: ignore[reportArgumentType] - ) + _testing.adams_rows_from_host(state, "store", rows.real.copy()) with pytest.raises(TypeError): - state.adams_rows_from_host("store", np.asfortranarray(rows)) + _testing.adams_rows_from_host(state, "store", np.asfortranarray(rows)) with pytest.raises(ValueError, match="unknown Adams history row"): _testing.adams_rows_to_host(state, "slopes") with pytest.raises(RuntimeError, match="not allocated"): @@ -477,7 +492,7 @@ def _spoil() -> None: _set(planar_payload, name, kappa) else: _set(planar_payload, name, value) - _core.State(planar_payload) + _core.Workspace(planar_payload) with pytest.raises((TypeError, ValueError)): _spoil() @@ -492,4 +507,4 @@ def test_a_free_payload_with_slab_channels_is_refused( free_payload.dims.n_omega, dtype=np.complex128 ) with pytest.raises(ValueError, match="hybrid planar"): - _core.State(free_payload) + _core.Workspace(free_payload) diff --git a/native/tests/test_mixtures.py b/native/tests/test_mixtures.py index ca5fc1916..814799ec1 100644 --- a/native/tests/test_mixtures.py +++ b/native/tests/test_mixtures.py @@ -78,7 +78,7 @@ def test_species_statistics_preserve_an_inert_component_and_close( assert backend.metadata()["plasma_channels"] == 2 finally: backend.close() - assert backend._native_state.closed # pyright: ignore[reportPrivateUsage] - lifecycle + assert backend._workspace.closed # pyright: ignore[reportPrivateUsage] - lifecycle backend.close() @@ -120,7 +120,7 @@ def test_native_channel_payload_refusals( plasma.channel_coefficients = np.empty(0) plasma.channel_parameters = parameters with pytest.raises(ValueError, match=r"channel|Channel|plasma"): - _core.State(payload) + _core.Workspace(payload) finally: backend.close() @@ -134,7 +134,7 @@ def test_native_statistics_refuse_channel_preionisation_shape( load_native(backend, problem.initial.field0) with pytest.raises(ValueError, match="channel preionisation"): _testing.statistics( - backend._native_state, # pyright: ignore[reportPrivateUsage] - native refusal + backend._workspace, # pyright: ignore[reportPrivateUsage] - native refusal 1 << 11, np.empty(0), np.empty(0), @@ -146,7 +146,7 @@ def test_native_statistics_refuse_channel_preionisation_shape( ) with pytest.raises(ValueError, match="channel preionisation"): _testing.statistics( - backend._native_state, # pyright: ignore[reportPrivateUsage] - native refusal + backend._workspace, # pyright: ignore[reportPrivateUsage] - native refusal 1 << 11, np.empty(0), np.empty(0), diff --git a/native/tests/test_planning.py b/native/tests/test_planning.py index 0748a4e0d..90c451b3a 100644 --- a/native/tests/test_planning.py +++ b/native/tests/test_planning.py @@ -28,7 +28,7 @@ def _plan(case: PhaseACase, planning: dict[str, object] | None) -> dict[str, obj problem, run_request, grid = case backend = NativeBackend(problem, run_request, grid=grid, fft_planning=planning) try: - found = dict(backend._native_state.fft_planning) # pyright: ignore[reportPrivateUsage] + found = dict(backend._diagnostics()["fft_planning"]) # pyright: ignore[reportPrivateUsage] found["metadata"] = cast(dict[str, object], backend.metadata()["calibration"])[ "fft_planning" ] diff --git a/native/tests/test_raman_tail.py b/native/tests/test_raman_tail.py index 8074888ae..3987815ab 100644 --- a/native/tests/test_raman_tail.py +++ b/native/tests/test_raman_tail.py @@ -195,7 +195,7 @@ def test_raman_partial_chunk_matches_reference_and_repeats( finally: backend.close() if isinstance(backend, NativeBackend): - assert backend._native_state.closed # pyright: ignore[reportPrivateUsage] - native lifetime + assert backend._workspace.closed # pyright: ignore[reportPrivateUsage] - native lifetime scale = np.max(np.abs(fields[0])) np.testing.assert_allclose( fields[1], fields[0], rtol=0.0, atol=_bound(grid.n_to) * scale diff --git a/native/tests/test_wisdom.py b/native/tests/test_wisdom.py index 9fed9c670..731caab73 100644 --- a/native/tests/test_wisdom.py +++ b/native/tests/test_wisdom.py @@ -267,7 +267,7 @@ class _Planned: def _planning(backend: NativeBackend) -> _Planned: - found = backend._native_state.fft_planning # pyright: ignore[reportPrivateUsage] + found = backend._diagnostics()["fft_planning"] # pyright: ignore[reportPrivateUsage] return _Planned( measured=cast(dict[str, str], found["measured"]), reused=cast(list[str], found["reused"]), diff --git a/native/tests/test_workspace.py b/native/tests/test_workspace.py index 605dc678a..dfa4382e8 100644 --- a/native/tests/test_workspace.py +++ b/native/tests/test_workspace.py @@ -8,10 +8,11 @@ (``_core.schemas()``); each record round-trips through the converter, and the converter refuses a malformed record by its field's path. A ``_core.Workspace`` built from one ``Problem`` with its set-once data, started from one run record, runs a session -to the same fields as the old seam's session over the same problem; the probe repeats +to the same fields as the backend's own session over the same problem; the probe repeats its trials, reads back an owning copy, refuses the low-storage march's field, and is -refused while a session holds the workspace. The adapter is not yet on this seam: the -records' native forms are assembled here from the old adapter's own parts. +refused while a session holds the workspace. The +records are the ones the backend built its own workspace from, sent through the +bindings directly. """ from __future__ import annotations @@ -34,16 +35,14 @@ from solprop.stepper.low_storage import LowStorageRungeKutta from solprop.stepper.multistep import MarchPolicy, Multistep from solprop.stepper.schedule import FixedSchedule -from solprop.stepper.tableau import continuous_extension from solprop_native import _core from solprop_native._load import load from solprop_native.backend import ( + FRESH_WATCH, NativeBackend, - _chord_tables, # pyright: ignore[reportPrivateUsage] _lower, # pyright: ignore[reportPrivateUsage] _LowerPlan, # pyright: ignore[reportPrivateUsage] - _resident_flows, # pyright: ignore[reportPrivateUsage] ) _testing: Any = cast(Any, _core)._testing @@ -298,134 +297,28 @@ def test_a_variant_is_told_apart_by_its_fields(phase_a_case: PhaseACase) -> None _testing.round_trip("RunRecords", stranger) -# -- the workspace: the old adapter's parts in the new seam's records ------------------ +# -- the workspace: a backend's own records, through the bindings directly ------------ -_TERMS = {1: "constant", 2: "expansion", 3: "table"} -_KERR = {0: "none", 1: "density", 2: "table"} -_CHORD = {0: "none", 1: "constant", 2: "expansion", 3: "table"} _PLANNING = {"mode": "legacy"} -_WATCH = { - "has_last": False, - "last_z": 0.0, - "since": 0, - "busy": False, - "quiet_run": 0, - "quiet": False, - "warned": False, - "cap": math.inf, -} _OBSERVATION, _TERMINAL = 0, 3 -def _stage_table(packed: object) -> dict[str, object] | None: - if packed is None: - return None - edges, lower, upper, coefficients = cast("tuple[Any, Any, Any, Any]", packed) - return { - "edges": np.ascontiguousarray(edges, dtype=np.float64), - "lower": float(lower), - "upper": float(upper), - "coefficients": np.ascontiguousarray(coefficients, dtype=np.float64), - } - - -def _stage_tables(old: Mapping[str, Any]) -> dict[str, object]: - """Return the old adapter's stage tables in the new seam's record.""" - return { - "n_stages": old["n_stages"], - "phi": _TERMS[old["phi"]], - "phi_weights": _stage_table(old["phi_weights"]), - "phi_rate": _stage_table(old["phi_rate"]), - "prefactor": _TERMS[old["prefactor"]], - "prefactor_weights": _stage_table(old["prefactor_weights"]), - "prefactor_low": old["prefactor_low"], - "prefactor_high": old["prefactor_high"], - "density": _stage_table(old["density"]), - "taper": _stage_table(old["taper"]), - "raman_rates": [_stage_table(one) for one in old["raman_rates"]], - "kerr": _KERR[old["kerr"]], - "kerr_density": _stage_table(old["kerr_density"]), - "plasma_densities": [_stage_table(one) for one in old["plasma_densities"]], - "plasma_preionisation": [ - _stage_table(one) for one in old["plasma_preionisation"] - ], - "raman_densities": [_stage_table(one) for one in old["raman_densities"]], - "dispersive_densities": [ - _stage_table(one) for one in old["dispersive_densities"] - ], - "chord": _CHORD[old["chord"]], - "chord_rate": old["chord_rate"], - "chord_terms": list(old["chord_terms"]), - "chord_table": _stage_table(old.get("chord_table")), - "flow": { - "edges": list(old["flow_edges"]), - "degrees": old["flow_degrees"], - "slack": old["flow_slack"], - }, - "flow_residual": old["flow_residual"], - "transform": { - "edges": list(old["transform_edges"]), - "degrees": old["transform_degrees"], - "slack": old["transform_slack"], - }, - } - - def _workspace(backend: Any, problem: Any, request: Any) -> _core.Workspace: - """Build the new seam's workspace from the parts the old adapter formed.""" - assert backend._flow is None - assert backend._z_tables is None + """Build a second workspace from the records the backend built its own from.""" native = _lower( problem, request, _LowerPlan( terms=backend._terms, + flow=backend._flow, + tables=backend._z_tables, node_chunk=backend._node_chunk, general_chunk=backend._general_chunk, cpu_execution=backend._applied_execution, fft_planning=_PLANNING, + setup=backend._setup(), ), ) - stepper = request.stepper - integrator = stepper.integrator - controller = stepper.controller - adams = isinstance(integrator, Multistep) - carrier = backend._resident.carrier if adams else None - held: Any = native - held.stage_tables = _stage_tables(backend._stage_tables() | _chord_tables(carrier)) - dense = ( - continuous_extension(stepper.tableau) - if stepper.interpolate_planes and not adams - else None - ) - weights = ( - np.empty(0) if controller.weights is None else np.asarray(controller.weights) - ) - held.runge_kutta = { - "nodes": np.asarray(stepper.tableau.nodes, dtype=np.float64), - "rtol": float(controller.rtol), - "atol": float(controller.atol), - "weights": weights, - "dense_weights": np.empty(0) if dense is None else np.asarray(dense, float), - } - if adams: - resident = backend._resident - held.adams = { - "slots": resident.n_slots, - "compensated": resident.compensated, - "interpolate": resident.interpolate, - "fused": backend._adams._fused, - "rtol": float(controller.rtol), - "atol": float(controller.atol), - "weights": weights, - } - if isinstance(integrator, LowStorageRungeKutta): - settings = shared.low_storage_settings(problem, stepper) - assert settings is not None - held.low_storage = dataclasses.replace( - settings, - flows=_resident_flows(settings.flows, stepper, device=False), - ) return _core.Workspace(native) @@ -444,14 +337,13 @@ def _run_start(backend: Any, problem: Any, request: Any) -> dict[str, object]: proposal = float(request.stepper.dz_init) adams = runge_kutta = None if isinstance(request.stepper.integrator, Multistep): - state = backend._adams.start_state(loaded.z, proposal, loaded.cursor) - adams = {**state, "watch": _WATCH} + adams = backend._adams.start_state(loaded.z, proposal, loaded.cursor) else: runge_kutta = { "z": float(loaded.z), "proposal": proposal, "norms": [], - "watch": _WATCH, + "watch": dict(FRESH_WATCH), "cursor": int(loaded.cursor), } return { @@ -465,6 +357,8 @@ def _run_start(backend: Any, problem: Any, request: Any) -> dict[str, object]: "row_statistics": None, "floor": None, "edge_noise": None, + "monitor": None, + "edge": None, } diff --git a/src/solprop/calibration/child.py b/src/solprop/calibration/child.py index 2fc253c88..5503b97fd 100644 --- a/src/solprop/calibration/child.py +++ b/src/solprop/calibration/child.py @@ -271,7 +271,7 @@ def capture( options=simulation.settings.execution_options(), ) try: - found = backend._native_state.fft_planning # pyright: ignore[reportPrivateUsage] + found = backend._diagnostics()["fft_planning"] # pyright: ignore[reportPrivateUsage] finally: backend.close() wisdom |= cast(dict[str, str], found["captured"]) diff --git a/tests/backends/flow_rows.py b/tests/backends/flow_rows.py index b9884d569..116d5fab2 100644 --- a/tests/backends/flow_rows.py +++ b/tests/backends/flow_rows.py @@ -395,7 +395,7 @@ def check(built: Built) -> bool: off = not np.any(held.route) if route == "off" else not np.all(held.route) native = NativeBackend(built.problem, built.run_request, grid=built.grid) try: - resident = type(native._resident).__name__ == "_ResidentAdams" + resident = native._diagnostics()["method"] == "adams" finally: native.close() return ( diff --git a/tests/backends/forced_thread_cases.py b/tests/backends/forced_thread_cases.py index 548b80b0a..f6b268355 100644 --- a/tests/backends/forced_thread_cases.py +++ b/tests/backends/forced_thread_cases.py @@ -11,7 +11,6 @@ """ import dataclasses -import itertools import warnings from typing import Any, cast @@ -56,6 +55,16 @@ def _native(): return NativeBackend +def _testing() -> Any: + """Return the optional wheel's private test module, in the probe's process.""" + # Optional wheel: absent from the base environment. + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + + return _testing + + def _sizing(backend) -> dict[str, dict[str, int]]: return dict(backend.metadata()["execution_sizing"]) @@ -408,14 +417,15 @@ def accept(): simulation, problem, run_request = accept_problem() backend = _native()(problem, run_request, grid=simulation.grid) try: + testing = _testing() state = load_native(backend, problem.initial.field0) - launch = state.field_to_host().copy() + launch = np.array(testing.field(state)) partials = native_trial(backend, 0.0, ACCEPT_STEP) - state.finish(ACCEPT_STEP) + testing.finish(state, ACCEPT_STEP) return { "launch": launch, "partials": partials, - "advanced": state.field_to_host().copy(), + "advanced": np.array(testing.field(state)), "mask": np.asarray(problem.grids.norm_mask), }, _sizing(backend) finally: @@ -443,32 +453,34 @@ def linear_cartesian(mode: str): def folds(mode: str): """March the linear beam on the resident engine, saving every step's squared norm. - Each step is the resident low-storage engine's on the backend's native state, as - ``test_native_synthetic_operator.py``'s ``resident_step`` takes one, followed by the - state's finish, as the march accepts a step. The squared norm over the norm mask is - the one the engine's threaded reduction hands the accept, so a width's norms test - that reduction's order, and its state the folds. + Each step is the resident low-storage engine's on the backend's workspace, followed + by the state's finish, as the march accepts a step (``_testing.low_storage_norms``). + The squared norm over the norm mask is the one the engine's threaded reduction + hands the accept, so a width's norms test that reduction's order, and its state + the folds. """ # Optional wheel: absent from the base environment. - from solprop_native.backend import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] - _ResidentLowStorage, # pyright: ignore[reportPrivateUsage] + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing as testing, ) - from backends.low_storage_cases import CARTESIAN_CHUNK, MARCH # noqa: PLC0415 + from backends.low_storage_cases import CARTESIAN_CHUNK # noqa: PLC0415 + from solprop.backends.records import run_records # noqa: PLC0415 + from solprop.backends.session import Start # noqa: PLC0415 problem, run_request, grid = linear_cartesian(mode) edges = np.asarray(run_request.stepper.schedule.edges) # pyright: ignore[reportOptionalMemberAccess] backend = _native()(problem, run_request, grid=grid, options=CARTESIAN_CHUNK) try: - state = load_native(backend, problem.initial.field0) - engine = _ResidentLowStorage(backend, MARCH) - norms = [] - for z, end in itertools.pairwise(edges): - dz = float(end - z) - norms.append(engine.step(float(z), dz)) - state.finish(dz) - field = np.asarray(state.field_to_host()).reshape(problem.shape).copy() - return {"field": field, "norms": np.array(norms)}, _sizing(backend) + workspace = load_native(backend, problem.initial.field0) + testing.configure_march( + workspace, run_records(problem, run_request, Start.entrance(problem)) + ) + norms = np.asarray( + testing.low_storage_norms(workspace, [float(z) for z in edges]) + ).reshape(-1) + field = np.asarray(testing.field(workspace)).reshape(problem.shape).copy() + return {"field": field, "norms": norms}, _sizing(backend) finally: backend.close() @@ -507,12 +519,13 @@ def flow(name: str): problem, run_request, grid, dz = linear_flow_problem(name) backend = _native()(problem, run_request, grid=grid) try: + testing = _testing() state = load_native(backend, problem.initial.field0) partials = native_trial(backend, 0.0, dz) - state.finish(dz) + testing.finish(state, dz) return { "partials": partials, - "field": state.field_to_host().copy(), + "field": np.array(testing.field(state)), }, _sizing(backend) finally: backend.close() diff --git a/tests/backends/native_edge.py b/tests/backends/native_edge.py new file mode 100644 index 000000000..3dd4a7012 --- /dev/null +++ b/tests/backends/native_edge.py @@ -0,0 +1,124 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""Bind a transverse edge in a native workspace and read it, as a native run does. + +The edge tests (``test_native_edge_reading.py``, ``test_native_edge_collar.py``) hold +native's own reading of a loaded state to the host's. A run's start binds the monitor +and its edge (``Workspace::start``); these helpers bind them alone, through the private +test module (``solprop_native._core._testing``), and lay the reading out as the edge's +judging reads it (:class:`solprop.transverse_monitor._EdgeReading`): + +- :func:`bind_edge_monitor` binds a boundary monitor's weights, the problem's walk-off + buckets and the monitor's edge (``_testing.bind_monitor``); +- :func:`edge_reading` reads the state for the edge (``_testing.edge_reading``). +""" + +from typing import Any + +import numpy as np + +from solprop.boundaries import SPLIT_RATE_BUCKETS +from solprop.monitor import BoundaryMonitor +from solprop.transverse_monitor import TransverseEdge, _EdgeReading + +__all__ = ["bind_edge_monitor", "edge_reading"] + + +def _testing() -> Any: + """Return the native extension's private test module.""" + from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] + _testing, + ) + + return _testing + + +def bind_edge_monitor(backend: Any, monitor: BoundaryMonitor) -> None: + """Hold a monitor's weights, buckets and edge tables in a native workspace. + + What a native run's start binds for its monitor: the backend's + ``_monitor_binding``, the walk-off occupancy of a monitor with a crossing and the + tables of its transverse edge (``_edge_binding``), if it has one. + + Parameters + ---------- + backend : solprop_native.NativeBackend + The constructed backend, its workspace loaded (``sessions.runs.load_native``, + which unbinds the monitor: bind it after). + monitor : solprop.monitor.BoundaryMonitor + The monitor. + """ + crossing = monitor.crossing + occupancy = ( + None + if crossing is None + else { + "buckets": np.ascontiguousarray(crossing.buckets, dtype=np.uint8).reshape( + -1 + ), + "count": SPLIT_RATE_BUCKETS, + } + ) + edge = monitor.transverse + _testing().bind_monitor( + backend._workspace, + backend._monitor_binding(monitor), + None if edge is None else backend._edge_binding(edge), + occupancy, + ) + + +def edge_reading( + backend: Any, + edge: TransverseEdge, + *, + faces: bool = True, + current: bool = False, + full: bool = False, +) -> Any: # an `_EdgeReading` whose fields the flags fill, which its type can't say + """Read a native workspace's state for the transverse edge, where it lives. + + Only numbers cross. A launch's reading (`full`) adds the clip and the totals; a + requested collar's read adds the totals and its return strip. + + Parameters + ---------- + backend : solprop_native.NativeBackend + The constructed backend, its edge bound (:func:`bind_edge_monitor`). + edge : solprop.transverse_monitor.TransverseEdge + The bound edge. + faces : bool, optional + Read the faces, columns and (with a collar) the strip; ``False`` reads only the + current. + current : bool, optional + Read the collar's rectified inward current. + full : bool, optional + Read as a launch does. + + Returns + ------- + solprop.transverse_monitor._EdgeReading + The reading. + """ + collar = edge.every_step + sums, columns, strip, rate = _testing().edge_reading( + backend._workspace, faces, full, collar, faces and collar, current + ) + rate_value = float(rate) if current else None + if not faces: + return _EdgeReading(current=rate_value) + values = np.asarray(sums).reshape(-1) + if full: + clip, totals = values[4:8], values[8:12] + else: + clip, totals = None, values[4:8] if collar else None + return _EdgeReading( + faces=values[:4], + clip=clip, + totals=totals, + columns=np.asarray(columns).reshape(-1), + strip=np.asarray(strip).reshape(-1, 2) if collar else None, + current=rate_value, + ) diff --git a/tests/backends/native_trace_marches.py b/tests/backends/native_trace_marches.py index 63b1a69ff..e314131d4 100644 --- a/tests/backends/native_trace_marches.py +++ b/tests/backends/native_trace_marches.py @@ -17,16 +17,18 @@ from __future__ import annotations +import dataclasses import logging import math import time from typing import Any, ClassVar, cast +from unittest import mock import numpy as np import pytest from solprop._interrupts import committing -from solprop.backends import rk_core +from solprop.backends import records, rk_core from solprop.backends.ledger import Derivative, budget_error from solprop.exceptions import BackendError, ResponseBudgetError from solprop.monitor import BoundaryEnergies, BoundaryMonitor @@ -158,12 +160,18 @@ class TraceAdamsMarch(backend_module._NativeAdamsMarch): """ def __init__(self, backend: Any, method: Multistep, *, runner: Any) -> None: - super().__init__( - backend, method, engine=backend._adams_engine(method, "transported") - ) + engine = backend._adams_engine(method, "transported") + # The record reads its carrier frame from the backend's problem; the scripted + # harness's engine holds its own. + with mock.patch.object( + backend_module, "carrier_reference", lambda *_: engine.carrier + ): + super().__init__(backend, method, engine=engine) self._driver: Any = backend self._runner = runner self._ahead: tuple[float, object] | None = None + # Whether the run interpolates its planes (ADR-036, ADR-039). + self._interpolate = bool(backend._stepper.interpolate_planes) def _configure(self, *_: object) -> None: """Configure nothing: the scripted runner takes the policy itself.""" @@ -317,6 +325,8 @@ def _state(self, watching: bool = False) -> dict[str, object]: """Return the bridge march's state as the native call takes it.""" backend = self._driver state = self.start_state(backend._z, backend._proposal, backend._schedule_index) + # The call takes a plain dict where the record keeps a read-only mapping. + state["watch"] = dict(cast("dict[str, object]", state["watch"])) if watching: state["watch"] = backend._monitor.watch_state() return state @@ -408,9 +418,9 @@ def _native_run( """Run the native march from `state` to an event within `bounds`.""" if self._runner is not None: return self._runner.run(state, bounds) - native = self._driver._native_state + workspace = self._driver._workspace with _envelope_errors(): - return _testing.adams_march_run(native, state, bounds) + return _testing.adams_march_run(workspace, state, bounds) def _synchronise(self, result: dict[str, Any]) -> None: """Adopt the state a native call handed back.""" @@ -435,7 +445,7 @@ def _synchronise(self, result: dict[str, Any]) -> None: ledger.orders.extend(int(order) for order in result["orders"]) -class TraceRungeKuttaMarch(session_module._NativeRungeKuttaMarch): +class TraceRungeKuttaMarch: """The native Runge-Kutta policy, its march driven a call at a time. Parameters @@ -447,7 +457,7 @@ class TraceRungeKuttaMarch(session_module._NativeRungeKuttaMarch): """ def __init__(self, backend: Any, runner: Any = None) -> None: - super().__init__(backend) + self._driver: Any = backend self._runner = runner self._replaying: FixedSchedule | None = None @@ -456,9 +466,14 @@ def _interval(self) -> float | None: monitor = self._driver._monitor return None if monitor is None else float(monitor.interval) - def _policy(self, interval: float | None = None) -> dict[str, object]: - """Return the record with the harness's quiet interval.""" - return super()._policy(self._interval() if interval is None else interval) + def _policy(self, interval: float | None = None) -> records.RungeKuttaPolicy: + """Return the harness's policy record (kernel contract 12), with its monitor's + quiet interval unless `interval` is given.""" + backend = self._driver + policy = records.runge_kutta_policy(backend._problem, backend._stepper) + return dataclasses.replace( + policy, quiet_interval=self._interval() if interval is None else interval + ) def _configure(self, *_: object) -> None: """Configure nothing: the scripted runner takes the policy itself.""" @@ -700,7 +715,7 @@ def _native_run( if self._runner is not None: return self._runner.run(state, bounds) with _envelope_errors(): - return _testing.rk_march_run(self._driver._native_state, state, bounds) + return _testing.rk_march_run(self._driver._workspace, state, bounds) def _raise(self, reason: int, result: dict[str, Any]) -> None: """Raise the error a call returned with, if any.""" diff --git a/tests/backends/test_compiled_multistep.py b/tests/backends/test_compiled_multistep.py index 496a8f616..be4575065 100644 --- a/tests/backends/test_compiled_multistep.py +++ b/tests/backends/test_compiled_multistep.py @@ -219,8 +219,7 @@ def assert_propagates_as_the_reference(backend_class, route): reference.close() backend = backend_class(problem, run_request, **context) try: - backend._staged_rows() - state = backend._native_state + state = backend._workspace stages = run_request.stepper.tableau.n_stages from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] _testing, diff --git a/tests/backends/test_free_absorber.py b/tests/backends/test_free_absorber.py index 0294de244..5ebfc2da7 100644 --- a/tests/backends/test_free_absorber.py +++ b/tests/backends/test_free_absorber.py @@ -237,10 +237,12 @@ def test_cartesian_split_step_temporal_absorber_reconstructs_physical_field( if backend.name == "native": # A zero-length trial loads the unmodified field into advanced; # finish then exercises precisely the once-per-step absorber. + _testing = pytest.importorskip("solprop_native._core")._testing + state = load_native(backend, problem.initial.field0) native_trial(backend, 0.0, 0.0) - state.finish(dz) - actual = state.field_to_host().reshape(start.shape) + _testing.finish(state, dz) + actual = np.asarray(_testing.field(state)).reshape(start.shape) else: backend.set_initial(problem.initial.field0, None) actual = backend._finish(problem.initial.field0.copy(), dz) diff --git a/tests/backends/test_free_split_rows.py b/tests/backends/test_free_split_rows.py index 25f94ade6..fcc2a9440 100644 --- a/tests/backends/test_free_split_rows.py +++ b/tests/backends/test_free_split_rows.py @@ -35,7 +35,6 @@ from solprop.translate.problem import PropagationProblem native_backend = pytest.importorskip("solprop_native.backend") -native_session = pytest.importorskip("solprop_native.session") BLOCKS = [1, 5, None] """Node chunks: one row at a time, one that leaves a shorter last block (192 columns @@ -186,9 +185,9 @@ def test_a_devices_choices_on_any_build( ) -> None: # Flows recomputed under "auto" and input through tiles of team scratch, with a # short last block's plan, at the reference's numbers. - # The session reads the build's kind where it lowers the low-storage flows. - for module in (native_backend, native_session): - monkeypatch.setattr(module, "_on_device", lambda: True) + # The backend reads the build's kind where it lowers the problem, the low-storage + # flows with it. + monkeypatch.setattr(native_backend, "_on_device", lambda: True) _check_block(reference, 5) diff --git a/tests/backends/test_monitor_owner.py b/tests/backends/test_monitor_owner.py index 4c2514b6c..fd5085ca8 100644 --- a/tests/backends/test_monitor_owner.py +++ b/tests/backends/test_monitor_owner.py @@ -59,10 +59,6 @@ def _modules() -> tuple[Any, Any]: ) -def _native_records() -> Any: - return importlib.import_module("solprop_native._records") - - def _grid() -> EnvelopeGrid: return EnvelopeGrid.from_limits(1.0, 1e-6, (0.8e-6, 1.25e-6), 1e-12) @@ -91,9 +87,7 @@ def __init__(self, monitor: BoundaryMonitor, *, can_rest: bool) -> None: self.python = monitor self.watch = watch self.native = core.Monitor( - _native_records().monitor_config( - records.monitor_config(monitor, monitor.crossing, can_rest=can_rest) - ) + records.monitor_config(monitor, monitor.crossing, can_rest=can_rest) ) self.can_rest = can_rest self.steps = 0 @@ -167,7 +161,7 @@ def collar(self) -> None: def resume(self, record: dict | None, *, plane: bool, unwatched=()) -> None: self.python.resume(record, plane=plane, unwatched=unwatched) self.native.resume( - _native_records().resumption(records.resumption(record)), + records.resumption(record), plane, [[float(start), float(end)] for start, end in unwatched], ) diff --git a/tests/backends/test_monitor_reduction.py b/tests/backends/test_monitor_reduction.py index 13b6c892b..4a013c23b 100644 --- a/tests/backends/test_monitor_reduction.py +++ b/tests/backends/test_monitor_reduction.py @@ -139,6 +139,20 @@ def _built( ) +def _loaded_reading( + made: Any, + problem: PropagationProblem, + monitor: BoundaryMonitor, + field: np.ndarray, +) -> BoundaryEnergies: + """Load `field` in a native backend's workspace, bind `monitor` there, and read it. + + A load unbinds the monitor, as a run's start does, so the monitor is bound after. + """ + load_native(made, field) + return native_reading(made, bind_native_monitor(made, problem, monitor)) + + def _launch_reading( simulation: Simulation, backend: str, @@ -151,9 +165,8 @@ def _launch_reading( try: monitor = simulation._boundary_monitor() assert monitor is not None - bound = bind_native_monitor(made, problem, monitor) launch = with_copy(problem.initial.field0, simulation.grid.n_t) - return native_reading(made, bound, launch) + return _loaded_reading(made, problem, monitor, launch) finally: made.close() @@ -429,9 +442,7 @@ def _native_second_run( launch = with_copy(problem.initial.field0, simulation.grid.n_t) made = _built(simulation, backend, problem) try: - first = native_reading( - made, _fresh_bound(made, simulation, problem), launch.copy() - ) + first = _loaded_reading(made, problem, _fresh(simulation), launch.copy()) boundary = simulation._boundary_monitor() assert boundary is not None session_run( @@ -440,14 +451,19 @@ def _native_second_run( made.request.for_run(monitor=boundary), Start(field=launch.copy(), z=0.0), ) - again = native_reading( - made, _fresh_bound(made, simulation, problem), launch.copy() - ) + again = _loaded_reading(made, problem, _fresh(simulation), launch.copy()) return first, again, made.memory_ledger() finally: made.close() +def _fresh(simulation: Simulation) -> BoundaryMonitor: + """Return a case's fresh monitor.""" + monitor = simulation._boundary_monitor() + assert monitor is not None + return monitor + + def _fresh_bound( made: Any, simulation: Simulation, problem: PropagationProblem ) -> BoundaryMonitor: @@ -483,30 +499,11 @@ def test_a_monitor_s_own_transform_is_in_the_ledger( assert all(ledger[row] > 0 for row in rows), {row: ledger[row] for row in rows} -class _CountingState: - """A native state that counts its `bind_occupancy` calls.""" - - def __init__(self, state: object) -> None: - """Wrap `state`.""" - self.__dict__["_state"] = state - self.__dict__["binds"] = 0 - - def bind_occupancy(self, *args: object) -> None: - """Count, then bind.""" - self.__dict__["binds"] += 1 - self.__dict__["_state"].bind_occupancy(*args) - - def __getattr__(self, name: str) -> object: - """Hand everything else to the state.""" - return getattr(self.__dict__["_state"], name) - - -def test_a_second_point_keeps_its_bucket_table_and_reads_as_the_first( - monkeypatch: pytest.MonkeyPatch, -) -> None: - # The table is a sixteenth of a state, and a runner's points share it: a second - # upload would move it per point. Nothing else may carry over. Each point is a - # watched session on the one backend, which binds its fresh monitor there. +def test_a_second_point_keeps_its_bucket_table_and_reads_as_the_first() -> None: + # The table is a sixteenth of a state, and a runner's points share it: it is one + # of the workspace's set-once tables, uploaded when the backend is built, never + # per point. Nothing else may carry over. Each point is a watched session on the + # one backend, which binds its fresh monitor there. _require("native") simulation = probe("radial", "split_step", MARCHES["runge_kutta"]) problem = simulation.translate() @@ -514,23 +511,9 @@ def test_a_second_point_keeps_its_bucket_table_and_reads_as_the_first( launch = with_copy(problem.initial.field0, simulation.grid.n_t) records = [] try: - for point in range(2): + for _ in range(2): boundary = simulation._boundary_monitor() assert boundary is not None - if point == 1: - assert made._bound_buckets is not None - counting = _CountingState(made._native_state) - bind = made._bind_monitor - - def counted(monitor, *, bind=bind, counting=counting): - # The counting state stands in while the session binds alone. - state, made._native_state = made._native_state, counting - try: - bind(monitor) - finally: - made._native_state = state - - monkeypatch.setattr(made, "_bind_monitor", counted) record: dict[str, object] = {} session_run( made, @@ -540,7 +523,6 @@ def counted(monitor, *, bind=bind, counting=counting): monitor=record, ) records.append(record) - assert counting.binds == 0 # pyright: ignore[reportPossiblyUnboundVariable] finally: made.close() # The same launch and march on the same build: the second record is a @@ -558,9 +540,16 @@ def test_an_occupancy_outside_its_reduction_is_refused(count: int) -> None: problem = simulation.translate() made = cast("Any", _built(simulation, "native", problem)) try: + _testing = pytest.importorskip("solprop_native._core")._testing + + monitor = simulation._boundary_monitor() + assert monitor is not None and monitor.split table = np.zeros(math.prod(problem.shape[0:1]) * simulation.grid.n_omega) + occupancy = {"buckets": table.astype(np.uint8), "count": count} with pytest.raises(ValueError, match="between 1 and 128 buckets"): - made._native_state.bind_occupancy(table.astype(np.uint8), count) + _testing.bind_monitor( + made._workspace, made._monitor_binding(monitor), None, occupancy + ) finally: made.close() @@ -583,12 +572,12 @@ def test_successive_occupancies_are_the_reference_s(backend: str, route: str) -> backend, 1e3 * _rounding(simulation), simulation.grid.n_t, 8 * STEPS ) try: - monitor = _fresh_bound(ours, simulation, problem) + monitor = _fresh(simulation) 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 + got = _loaded_reading(ours, problem, monitor, np.array(state)).occupancy assert expected is not None and got is not None np.testing.assert_allclose( got, expected, rtol=0.0, atol=bound * float(expected.sum()) diff --git a/tests/backends/test_native_dispersive_kerr.py b/tests/backends/test_native_dispersive_kerr.py index 985a7d0dc..55c571700 100644 --- a/tests/backends/test_native_dispersive_kerr.py +++ b/tests/backends/test_native_dispersive_kerr.py @@ -103,7 +103,7 @@ def test_a_state_with_zero_frequency_content_matches_the_reference(thg, evaluato start[..., 0] = 1e-3 * np.abs(start).max() backend = NativeBackend(problem, case.run_request, grid=case.grid) try: - held = load_native(backend, start).field_to_host().reshape(problem.shape) + held = _testing.field(load_native(backend, start)).reshape(problem.shape) finally: backend.close() np.testing.assert_array_equal(held[..., 0], 0.0) @@ -131,7 +131,7 @@ def test_the_embedded_rule_is_finished_once_and_only_where_it_exists(evaluator): backend = NativeBackend(case.problem, case.run_request, grid=case.grid) try: native_source(backend, case.problem.initial.field0) - native = backend._native_state + native = backend._workspace fine = np.array(_testing.projected_to_host(native, False)) landed = np.array(_testing.projected_to_host(native, True)) assert np.any(landed) @@ -144,7 +144,7 @@ def test_the_embedded_rule_is_finished_once_and_only_where_it_exists(evaluator): backend = NativeBackend(radial_problem, radial_request, grid=grid) try: native_source(backend, radial_problem.initial.field0) - native = backend._native_state + native = backend._workspace before = np.array(_testing.projected_to_host(native, False)) assert np.any(before) np.testing.assert_array_equal(_testing.projected_to_host(native, False), before) diff --git a/tests/backends/test_native_edge_collar.py b/tests/backends/test_native_edge_collar.py index 930f0cd60..5359712b5 100644 --- a/tests/backends/test_native_edge_collar.py +++ b/tests/backends/test_native_edge_collar.py @@ -27,6 +27,7 @@ STEPS, collar_case, ) +from backends.native_edge import bind_edge_monitor, edge_reading from bounds import fft_bound from sessions.runs import load_native, watched_run from sessions.runs import run as session_run @@ -70,7 +71,7 @@ def _attached(simulation: Simulation, state: np.ndarray) -> tuple[Any, Any]: """Return a native backend loaded with `state`, its edge bound. The state is loaded into the backend's native state and the monitor bound there, - as the native session binds its own (the backend's ``_bind_monitor``). + as the native session binds its own (``backends.native_edge.bind_edge_monitor``). """ problem = simulation.translate() run_request = simulation._run_request() @@ -91,7 +92,7 @@ def _attached(simulation: Simulation, state: np.ndarray) -> tuple[Any, Any]: assert monitor is not None assert monitor.transverse is not None assert monitor.transverse.every_step - backend._bind_monitor(monitor) + bind_edge_monitor(backend, monitor) return backend, monitor.transverse @@ -117,9 +118,7 @@ def test_native_reads_a_collars_strip_and_current_as_the_host_does( state = _noise(problem, 67) backend, edge = _attached(simulation, state) try: - native = backend._edge_reading( - backend._native_state, edge, current=True, full=True - ) + native = edge_reading(backend, edge, current=True, full=True) host = edge.reduction.reading(state, current=True, full=True) finally: backend.close() @@ -137,7 +136,7 @@ def test_native_reads_a_collars_strip_and_current_as_the_host_does( # A later read uses only the collar's rate, from the rows a read can touch. backend, edge = _attached(simulation, state) try: - read = backend._edge_reading(backend._native_state, edge) + read = edge_reading(backend, edge) finally: backend.close() assert read.totals[1] > 0.0 @@ -172,9 +171,7 @@ def _line_current( state[:, 0, active[index]] = np.fft.fft(wave) backend, edge = _attached(simulation, state) try: - native = backend._edge_reading( - backend._native_state, edge, faces=False, current=True - ) + native = edge_reading(backend, edge, faces=False, current=True) finally: backend.close() return native.current, kappa, h, edge, space.n_x @@ -245,7 +242,7 @@ def test_the_strip_tells_a_packets_direction(kappa: float, reads_inward: bool) - state[:, 0, active[3]] = _packet(space, centre, kappa) backend, edge = _attached(simulation, state) try: - native = backend._edge_reading(backend._native_state, edge, full=True) + native = edge_reading(backend, edge, full=True) finally: backend.close() inward, windowed = native.strip[0] @@ -266,13 +263,13 @@ def test_a_small_batch_reads_what_one_batch_reads( state = _noise(problem, 71) backend, edge = _attached(simulation, state) try: - whole = backend._edge_reading(backend._native_state, edge, full=True) + whole = edge_reading(backend, edge, full=True) finally: backend.close() monkeypatch.setattr(transverse_monitor, "_STRIP_BATCH_BYTES", 2**12) backend, edge = _attached(simulation, state) try: - small = backend._edge_reading(backend._native_state, edge, full=True) + small = edge_reading(backend, edge, full=True) finally: backend.close() budget = 4 * fft_bound(state.shape[0] * state.shape[2]) @@ -417,7 +414,7 @@ def test_a_collar_run_brings_no_state_to_the_host(route: str) -> None: warnings.simplefilter("ignore", BoundaryWarning) output = runner.run(field, progress="none") assert isinstance(runner.backend, NativeBackend) - to_host, from_host = cast("Any", runner.backend)._native_state.crossed_bytes() + to_host, from_host = cast("Any", runner.backend)._diagnostics()["crossed_bytes"] record = cast("Any", output).outcome.execution["boundary_monitor"]["transverse"] assert record["reads"] > 0 assert to_host == 0 @@ -445,7 +442,7 @@ def test_a_lit_node_reads_the_collars_rate_from_its_design() -> None: state[:, 0, active[3]] = phase backend, edge = _attached(simulation, state) try: - read = backend._edge_reading(backend._native_state, edge) + read = edge_reading(backend, edge) finally: backend.close() expected = rate[node] * float(np.asarray(space.spatial_weights)[node]) @@ -551,9 +548,7 @@ def test_the_smallest_node_chunk_reads_what_the_default_reads(route: str) -> Non state = _noise(problem, 83) backend, edge = _attached(simulation, state) try: - whole = backend._edge_reading( - backend._native_state, edge, current=True, full=True - ) + whole = edge_reading(backend, edge, current=True, full=True) finally: backend.close() budget = 20 * 16 * problem.shape[1] * problem.grids.n_to @@ -561,9 +556,7 @@ def test_the_smallest_node_chunk_reads_what_the_default_reads(route: str) -> Non assert node_chunk(small) < node_chunk(simulation) backend, edge = _attached(small, state) try: - read = backend._edge_reading( - backend._native_state, edge, current=True, full=True - ) + read = edge_reading(backend, edge, current=True, full=True) finally: backend.close() assert read.strip.tobytes() == whole.strip.tobytes() @@ -708,7 +701,7 @@ def launch(name: str) -> tuple[dict[str, Any], int | None]: monitor=record, ) crossed = ( - backend._native_state.crossed_bytes()[0] if name == "native" else None + backend._diagnostics()["crossed_bytes"][0] if name == "native" else None ) return cast("dict[str, Any]", record["transverse"]), crossed finally: @@ -730,9 +723,11 @@ def launch(name: str) -> tuple[dict[str, Any], int | None]: np.testing.assert_allclose(handed[0], judged[0], rtol=1e-10, atol=1e-30) -def test_a_resume_with_no_monitor_record_crosses_once() -> None: +def test_a_resume_with_no_monitor_record_crosses_no_state() -> None: # The one launch whose clean columns the load didn't form: a resumed state with its - # draw, whose run has no record of the monitor, so it's judged here as a launch. + # draw, whose run has no record of the monitor, so it's judged here as a launch. The + # load keeps its host copy of the state, so the judging forms them from that and + # nothing crosses back (SEP 52). simulation = collar_case("line", noise="input") problem = simulation.translate() run_request = simulation._run_request() @@ -768,7 +763,7 @@ def test_a_resume_with_no_monitor_record_crosses_once() -> None: export=None, observations=2, ) - assert backend._native_state.crossed_bytes()[0] == state.nbytes + assert backend._diagnostics()["crossed_bytes"][0] == 0 finally: backend.close() @@ -791,7 +786,7 @@ def with_an_empty_line(*args: Any) -> tuple[Any, ...]: monkeypatch.setattr(transverse_monitor, "_edge_lines", with_an_empty_line) backend, edge = _attached(simulation, state) try: - read = backend._edge_reading(backend._native_state, edge, full=True) + read = edge_reading(backend, edge, full=True) held = edge.reduction.reading(state, full=True) _, n_pol, n_omega = problem.shape assert backend.memory_ledger()["transverse_edge"] == ( diff --git a/tests/backends/test_native_edge_reading.py b/tests/backends/test_native_edge_reading.py index a147c334c..4c0f2911c 100644 --- a/tests/backends/test_native_edge_reading.py +++ b/tests/backends/test_native_edge_reading.py @@ -15,6 +15,7 @@ import numpy as np import pytest +from backends.native_edge import bind_edge_monitor, edge_reading from bounds import fft_bound, higham_gamma from capability_routes import LENGTH, SPATIAL_GRID from capability_routes import ROUTES as CASES @@ -43,6 +44,7 @@ "native" not in available(), reason="native is not installed" ) NativeBackend = pytest.importorskip("solprop_native.backend").NativeBackend +_testing = cast("Any", pytest.importorskip("solprop_native._core"))._testing ROUTES = ("radial", "cartesian", "line", "planar") @@ -71,7 +73,7 @@ def _attached(simulation: Simulation, state: np.ndarray) -> Any: """Return a native backend loaded with `state` and watched by the edge. The state is loaded into the backend's native state and the monitor bound there, - as the native session binds its own (the backend's ``_bind_monitor``). + as the native session binds its own (``backends.native_edge.bind_edge_monitor``). """ problem = simulation.translate() run_request = simulation._run_request() @@ -90,7 +92,7 @@ def _attached(simulation: Simulation, state: np.ndarray) -> Any: monitor = simulation._boundary_monitor() assert monitor is not None assert monitor.transverse is not None - backend._bind_monitor(monitor) + bind_edge_monitor(backend, monitor) return backend, monitor.transverse @@ -103,7 +105,7 @@ def _read_both( state = _noise_state(problem.shape, np.asarray(problem.grids.active_mask), 41) backend, edge = _attached(simulation, state) try: - native = backend._edge_reading(backend._native_state, edge, full=full) + native = edge_reading(backend, edge, full=full) host = edge.reduction.reading(state, full=full) finally: backend.close() @@ -140,10 +142,10 @@ def test_native_reads_a_state_it_holds_without_changing_it(route: str) -> None: state = _noise_state(problem.shape, np.asarray(problem.grids.active_mask), 43) backend, edge = _attached(simulation, state) try: - before = backend._native_state.field_to_host() - backend._edge_reading(backend._native_state, edge, full=True) - backend._edge_reading(backend._native_state, edge) - after = backend._native_state.field_to_host() + before = _testing.field(backend._workspace) + edge_reading(backend, edge, full=True) + edge_reading(backend, edge) + after = _testing.field(backend._workspace) finally: backend.close() # The reading works on the scratch: the state's own bits don't move. @@ -176,7 +178,7 @@ def test_one_lit_node_reaches_only_its_own_faces( state[:, 0, int(np.nonzero(active)[0][0])] = phase.reshape(-1) backend, edge = _attached(simulation, state) try: - native = backend._edge_reading(backend._native_state, edge, full=True) + native = edge_reading(backend, edge, full=True) host = edge.reduction.reading(state, full=True) finally: backend.close() @@ -231,7 +233,7 @@ def test_two_polarisations_read_as_the_host_reads(route: str) -> None: state = _noise_state(problem.shape, np.asarray(problem.grids.active_mask), 47) backend, edge = _attached(simulation, state) try: - native = backend._edge_reading(backend._native_state, edge, full=True) + native = edge_reading(backend, edge, full=True) host = edge.reduction.reading(state, full=True) finally: backend.close() @@ -351,7 +353,7 @@ def test_each_region_reads_what_its_definition_says(route: str) -> None: state = _noise_state(problem.shape, np.asarray(problem.grids.active_mask), 53) backend, edge = _attached(simulation, state) try: - native = backend._edge_reading(backend._native_state, edge, full=True) + native = edge_reading(backend, edge, full=True) finally: backend.close() assert native.faces is not None and native.totals is not None @@ -378,7 +380,7 @@ def test_the_grids_total_is_its_columns_by_parseval(route: str) -> None: state = _noise_state(problem.shape, np.asarray(problem.grids.active_mask), 59) backend, edge = _attached(simulation, state) try: - native = backend._edge_reading(backend._native_state, edge, full=True) + native = edge_reading(backend, edge, full=True) finally: backend.close() assert native.totals is not None and native.columns is not None @@ -417,7 +419,7 @@ def test_a_nearly_cancelling_radial_read_stays_within_its_absolute_budget() -> N state[:, 0, :] = beam[:, None] * active[None, :] backend, edge = _attached(simulation, state) try: - native = backend._edge_reading(backend._native_state, edge, full=True) + native = edge_reading(backend, edge, full=True) finally: backend.close() assert native.faces is not None @@ -491,8 +493,8 @@ def test_a_field_free_default_run_crosses_no_state() -> None: with simulation.runner() as runner: output = runner.run(field, progress="none") assert isinstance(runner.backend, NativeBackend) - state = cast("Any", runner.backend)._native_state - to_host, from_host = state.crossed_bytes() + crossed = cast("Any", runner.backend)._diagnostics()["crossed_bytes"] + to_host, from_host = crossed outcome = cast("Any", output).outcome edge = outcome.execution["boundary_monitor"]["transverse"] assert edge["reads"] > 0 @@ -507,10 +509,12 @@ def test_the_crossing_count_sees_a_direct_copy() -> None: state = _noise_state(problem.shape, np.asarray(problem.grids.active_mask), 61) backend, _ = _attached(simulation, state) try: - native = backend._native_state - assert native.crossed_bytes() == (0, state.nbytes) - native.field_to_host() - assert native.crossed_bytes() == (state.nbytes, state.nbytes) + assert tuple(backend._diagnostics()["crossed_bytes"]) == (0, state.nbytes) + _testing.field(backend._workspace) + assert tuple(backend._diagnostics()["crossed_bytes"]) == ( + state.nbytes, + state.nbytes, + ) finally: backend.close() @@ -539,7 +543,7 @@ def test_the_edge_holds_memory_only_once_a_monitor_binds_it(route: str) -> None: monitor = simulation._boundary_monitor() assert monitor is not None assert monitor.transverse is not None - backend._bind_monitor(monitor) + bind_edge_monitor(backend, monitor) _, n_pol, n_omega = problem.shape expected = _transverse_edge_bytes( monitor.transverse.space, monitor.transverse.design, n_pol, n_omega @@ -602,7 +606,7 @@ def launch(backend: str) -> tuple[dict[str, Any], tuple[int, int] | None]: warnings.simplefilter("ignore", BoundaryWarning) output = cast("Any", runner.run(field, progress="none")) crossed = ( - cast("Any", runner.backend)._native_state.crossed_bytes() + cast("Any", runner.backend)._diagnostics()["crossed_bytes"] if backend == "native" else None ) @@ -664,7 +668,7 @@ def test_a_field_grid_reads_as_the_host_does() -> None: state = _noise_state(problem.shape, np.asarray(problem.grids.active_mask), 79) backend, edge = _attached(simulation, state) try: - native = backend._edge_reading(backend._native_state, edge, full=True) + native = edge_reading(backend, edge, full=True) host = edge.reduction.reading(state, full=True) finally: backend.close() @@ -701,8 +705,8 @@ def test_energy_in_one_extreme_bin_reads_as_the_host_does(where: str) -> None: state[nyquist, 0, active[0]] = 1.0 backend, edge = _attached(simulation, state) try: - native = backend._edge_reading(backend._native_state, edge, full=True) - held = backend._native_state.field_to_host().reshape(problem.shape) + native = edge_reading(backend, edge, full=True) + held = _testing.field(backend._workspace).reshape(problem.shape) host = edge.reduction.reading(held, full=True) finally: backend.close() @@ -729,7 +733,7 @@ def test_a_planar_channel_above_the_first_reads_its_own_column() -> None: state[column, 0, active[0]] = 1.0 backend, edge = _attached(simulation, state) try: - native = backend._edge_reading(backend._native_state, edge, full=True) + native = edge_reading(backend, edge, full=True) host = edge.reduction.reading(state, full=True) finally: backend.close() diff --git a/tests/backends/test_native_error_norm.py b/tests/backends/test_native_error_norm.py index d6f3eded4..2efc6537a 100644 --- a/tests/backends/test_native_error_norm.py +++ b/tests/backends/test_native_error_norm.py @@ -20,7 +20,7 @@ its own stages: the state's one-step bound over the controller's scale. Native's trials are its state's own (``rk_trial`` on the uploaded stage tables, -scored by ``rk_score`` or ``rk_weighted_score``), called on the backend's native state +scored by ``rk_score`` or ``weighted_score``), called on the backend's workspace directly: SEP 47 phase 5 retired the backend's driver calls, and a state after a real propagation is the one the backend's session leaves. """ @@ -37,7 +37,6 @@ from solprop.stepper import PIController native = pytest.importorskip("solprop_native") -core = pytest.importorskip("solprop_native._core") _testing = pytest.importorskip("solprop_native._core")._testing STEP_RELATIVE = 16 * EPS @@ -63,15 +62,18 @@ def _score(backend, run_request, partials): controller = run_request.stepper.controller partials = np.ascontiguousarray(partials, dtype=np.float64) if controller.weights is None: - return float(core.rk_score(partials, controller.rtol, controller.atol)) - state = backend._native_state - state.rk_weights_configure([float(value) for value in controller.weights]) - return float(state.rk_weighted_score(partials, controller.rtol, controller.atol)) + return float(_testing.rk_score(partials, controller.rtol, controller.atol)) + weights = np.ascontiguousarray(controller.weights, dtype=np.float64) + return float( + _testing.weighted_score( + backend._workspace, partials, controller.rtol, controller.atol, weights + ) + ) def _field(backend, problem): """Return native's state on the host, in the problem's shape.""" - return np.asarray(backend._native_state.field_to_host()).reshape(problem.shape) + return np.asarray(_testing.field(backend._workspace)).reshape(problem.shape) def _native_trial(problem, run_request, grid, dz): @@ -85,7 +87,7 @@ def _native_trial(problem, run_request, grid, dz): def _operands(backend, reference, problem, run_request, dz): """Return native's stages and state, and the reference's propagator.""" tableau = run_request.stepper.tableau - state = backend._native_state + state = backend._workspace shape = problem.shape stages = [ np.asarray(_testing.stage_to_host(state, index)).reshape(shape) @@ -124,7 +126,7 @@ def test_the_rk_norm_is_the_reference_norm_of_native_s_operands( stages, run_request.stepper.tableau.error_weights, propagator, dz ) before = problem.initial.field0 - backend._native_state.finish(dz) + _testing.finish(backend._workspace, dz) after = _field(backend, problem) wanted = reference._error_norm(carried, before, after) controller = run_request.stepper.controller @@ -177,7 +179,7 @@ def test_each_norm_is_read_from_its_own_state(capillary_problem, field_grid): load_native(backend, problem.initial.field0) partials = native_trial(backend, 0.0, dz) old, new = float(partials[0].sum()), float(partials[1].sum()) - backend._native_state.finish(dz) + _testing.finish(backend._workspace, dz) after = _field(backend, problem) finally: backend.close() @@ -220,7 +222,7 @@ def test_the_weighted_residual_divides_each_bin_before_the_norm( carried, rounding = _difference( stages, run_request.stepper.tableau.error_weights, propagator, dz ) - partials = _testing.weighted_error(backend._native_state, weights) + partials = _testing.weighted_error(backend._workspace, weights) got = math.sqrt(float(np.sum(partials))) finally: backend.close() @@ -288,23 +290,23 @@ def test_the_recycled_stage_is_the_one_it_replaces( backend = native.NativeBackend(problem, run_request, grid=field_grid) try: landed = run(backend, problem, run_request) - state = backend._native_state - assert state.fsal_ready + state = backend._workspace + assert backend._diagnostics()["fsal_ready"] z = float(landed.observations[-1].z) assert z == 0.02 history = [one for one in landed.histories if one.n_steps][-1] assert history.accepted[-1] dz = float(history.dz[-1]) - before = state.rk_source_evaluations + before = backend._diagnostics()["rk_source_evaluations"] native_trial(backend, z, dz) # Six evaluations: the first stage was not evaluated, it was recycled. - assert state.rk_source_evaluations == before + 6 + assert backend._diagnostics()["rk_source_evaluations"] == before + 6 recycled = np.asarray(_testing.stage_to_host(state, 0)).copy() # The same stage from scratch, at the same state and step. - state.clear_fsal() - before = state.rk_source_evaluations + _testing.clear_fsal(state) + before = backend._diagnostics()["rk_source_evaluations"] native_trial(backend, z, dz) - assert state.rk_source_evaluations == before + 7 + assert backend._diagnostics()["rk_source_evaluations"] == before + 7 fresh = np.asarray(_testing.stage_to_host(state, 0)).copy() gap = float(np.linalg.norm(recycled - fresh) / np.linalg.norm(fresh)) # The derivative's sensitivity to an elementwise relative perturbation of the diff --git a/tests/backends/test_native_far_field.py b/tests/backends/test_native_far_field.py index 96f39692d..de1586453 100644 --- a/tests/backends/test_native_far_field.py +++ b/tests/backends/test_native_far_field.py @@ -62,6 +62,9 @@ from solprop.translate.problem import Translation from solprop.translate.spatial import aperture_tables +_testing = pytest.importorskip("solprop_native._core")._testing +native_statistics = pytest.importorskip("solprop_native._statistics") + solprop_native = pytest.importorskip("solprop_native") NativeBackend = solprop_native.NativeBackend @@ -835,21 +838,33 @@ def test_the_native_refusals_name_what_is_missing(): unknown[0, 8] = 7.0 # a profile code past supergauss regions = np.empty((0, 4)) with pytest.raises(ValueError, match="flags"): - native.aperture_statistics(16, apertures, 2, regions, 1.0) + _testing.aperture_statistics(native, 16, apertures, 2, regions, 1.0) with pytest.raises(ValueError, match="profile"): - native.aperture_statistics(512, unknown, 2, regions, 1.0) + _testing.aperture_statistics(native, 512, unknown, 2, regions, 1.0) with pytest.raises(ValueError, match="rows"): - native.aperture_statistics(512, apertures[:, :-1], 2, regions, 1.0) + _testing.aperture_statistics( + native, 512, apertures[:, :-1], 2, regions, 1.0 + ) with pytest.raises(ValueError, match="regions"): - native.aperture_statistics(256, apertures, 2, np.empty((1, 3)), 1.0) + _testing.aperture_statistics( + native, 256, apertures, 2, np.empty((1, 3)), 1.0 + ) with pytest.raises(ValueError, match="NaN"): - native.aperture_statistics(256, apertures, 2, np.full((1, 4), np.nan), 1.0) + _testing.aperture_statistics( + native, 256, apertures, 2, np.full((1, 4), np.nan), 1.0 + ) with pytest.raises(TypeError): - native.aperture_statistics( - 512, apertures.astype(np.float32), 2, regions, 1.0 + _testing.aperture_statistics( + native, 512, apertures.astype(np.float32), 2, regions, 1.0 ) # The far-field statistics without tables formed for them. with pytest.raises(BackendError, match="tables"): - owner._far_field_statistics({"beam_spectrum"}, StatsSpec(names=("energy",))) + native_statistics.lower( + problem, + StatsSpec(names=("energy",)), + ("beam_spectrum",), + grid=grid, + z_end=float(run_request.stepper.z_end), + ) finally: owner.close() diff --git a/tests/backends/test_native_gpu.py b/tests/backends/test_native_gpu.py index 9e9f33978..a912928ec 100644 --- a/tests/backends/test_native_gpu.py +++ b/tests/backends/test_native_gpu.py @@ -128,7 +128,8 @@ def test_a_large_state_crosses_both_ways_through_the_ring_bit_for_bit( # The state's own crossings, each way. load_native(engine, field) assert engine.memory_ledger()["host_crossing_ring"] > 0 - back = engine._native_state.field_to_host().reshape(shape) + testing = cast("Any", pytest.importorskip("solprop_native._core"))._testing + back = testing.field(engine._workspace).reshape(shape) assert back.tobytes() == field.tobytes() # A session's load and its launch plane's export. observed = launch(engine, problem, run_request, field=field).field diff --git a/tests/backends/test_native_held_plasma.py b/tests/backends/test_native_held_plasma.py index c7d633c31..1c80cddca 100644 --- a/tests/backends/test_native_held_plasma.py +++ b/tests/backends/test_native_held_plasma.py @@ -50,7 +50,7 @@ def test_the_held_current_lands_in_the_band_and_plans_once(name, rule): ledger = backend.memory_ledger() native_trial(backend, 0.0, 0.0, field=problem.initial.field0) native_trial(backend, 0.0, 0.0, field=np.zeros_like(problem.initial.field0)) - assert np.count_nonzero(_testing.stage_to_host(backend._native_state, 0)) == 0 + assert np.count_nonzero(_testing.stage_to_host(backend._workspace, 0)) == 0 # A second evaluation neither plans nor grows a resident source buffer. assert backend.memory_ledger() == ledger finally: diff --git a/tests/backends/test_native_held_projection_budget.py b/tests/backends/test_native_held_projection_budget.py index 05683c155..467977211 100644 --- a/tests/backends/test_native_held_projection_budget.py +++ b/tests/backends/test_native_held_projection_budget.py @@ -146,7 +146,7 @@ def test_embedded_current_projection_accumulates_partial_chunks( backend = native.NativeBackend(problem, run_request, grid=grid, options=options) try: native_trial(backend, 0.0, 0.0, field=state) - raw = np.asarray(_testing.projected_to_host(backend._native_state, True)) + raw = np.asarray(_testing.projected_to_host(backend._workspace, True)) finally: backend.close() actual = raw.reshape(*expected.shape[:-1], grids.n_to // 2 + 1)[ diff --git a/tests/backends/test_native_low_storage.py b/tests/backends/test_native_low_storage.py index 897d127fb..121682703 100644 --- a/tests/backends/test_native_low_storage.py +++ b/tests/backends/test_native_low_storage.py @@ -58,6 +58,7 @@ solprop_native = pytest.importorskip("solprop_native") NativeBackend = solprop_native.NativeBackend +_testing = pytest.importorskip("solprop_native._core")._testing MARCH_ROWS = ( "state", @@ -260,10 +261,8 @@ def test_a_trial_step_on_a_low_storage_state_is_refused_by_name(): problem, run_request, grid, _ = cartesian_march("tabulate") backend = NativeBackend(problem, run_request, grid=grid, options=CARTESIAN_CHUNK) try: - state = load_native(backend, problem.initial.field0) - backend._staged_rows() - nodes = [float(node) for node in run_request.stepper.tableau.nodes] + workspace = load_native(backend, problem.initial.field0) with pytest.raises(RuntimeError, match=r"low-storage state .* no Runge-Kutta"): - state.rk_trial(0.0, run_request.stepper.dz_init, nodes, prepare_only=False) + _testing.rk_trial(workspace, 0.0, run_request.stepper.dz_init) finally: backend.close() diff --git a/tests/backends/test_native_march_admission.py b/tests/backends/test_native_march_admission.py index 19b4315df..48f7ea4f5 100644 --- a/tests/backends/test_native_march_admission.py +++ b/tests/backends/test_native_march_admission.py @@ -120,7 +120,7 @@ def test_a_representation_the_stage_tables_do_not_read_is_refused_at_admission( assert not backend_module.stage_tables_available(stripped) built_states = [] monkeypatch.setattr( - backend_module._core, "State", lambda *args: built_states.append(args) + backend_module._core, "Workspace", lambda *args: built_states.append(args) ) with pytest.raises(BackendError, match="does not read") as refused: NativeBackend(stripped, request, grid=simulation.grid, modes=simulation.modes) @@ -147,7 +147,7 @@ def test_the_untransported_witness_is_refused(): backend = built(on_route("capillary (pressure gradient)", Multistep())) try: with pytest.raises(BackendError, match="untransported"): - backend._adams_engine(Multistep(), "untransported") + backend._compensated(Multistep(), "untransported") finally: backend.close() diff --git a/tests/backends/test_native_march_rows.py b/tests/backends/test_native_march_rows.py index 5b149565b..41c1cf44a 100644 --- a/tests/backends/test_native_march_rows.py +++ b/tests/backends/test_native_march_rows.py @@ -47,7 +47,7 @@ def rows(implementation: type): ) try: if implementation is NativeBackend: - assert type(backend._resident).__name__ == "_ResidentAdams" + assert backend._diagnostics()["method"] == "adams" run = drive(Started(session)) finally: session.close() diff --git a/tests/backends/test_native_phi_moments.py b/tests/backends/test_native_phi_moments.py index 26f112794..8da88b3f9 100644 --- a/tests/backends/test_native_phi_moments.py +++ b/tests/backends/test_native_phi_moments.py @@ -105,7 +105,19 @@ def read_moments(module, grid, values): assert terms.shape[1] == 1 terms[0, 0, bins] = values payload.linear.phi_terms = terms - state = backend_module._core.State(payload) + # The resident history this test reads, uncompensated, with no steps kept for + # interpolation; its controller's scale is never read. + controller = run_request.stepper.controller + payload.adams = { + "slots": SLOTS, + "compensated": False, + "interpolate": False, + "fused": False, + "rtol": float(controller.rtol), + "atol": float(controller.atol), + "weights": np.empty(0), + } + state = backend_module._core.Workspace(payload) try: (phi_delta, *rest) = arrays step = np.zeros_like(phi_delta) @@ -117,12 +129,11 @@ def read_moments(module, grid, values): empty = np.empty(0, dtype=np.float64) width = SLOTS out = np.zeros((values.size, MAX_PHI_ORDER), dtype=complex) - state.adams_allocate(SLOTS, False, False) store = np.zeros((SLOTS, 1, n_omega), dtype=complex) store[0] = 1.0 for k in range(MAX_PHI_ORDER): - state.set_initial(zero, np.empty(0, dtype=complex)) - state.adams_rows_from_host("store", store) + _testing.load(state, zero, np.empty(0, dtype=complex)) + _testing.adams_rows_from_host(state, "store", store) corrector = np.zeros((width, width)) corrector[1, k] = 1.0 _testing.adams_exponential_trial( @@ -149,7 +160,7 @@ def read_moments(module, grid, values): _testing.adams_exponential_accept( state, 1.0, width - 1, np.empty(0, dtype=np.uint64), False ) - out[:, k] = np.asarray(state.field_to_host()).reshape(-1)[bins] + out[:, k] = np.asarray(_testing.field(state)).reshape(-1)[bins] finally: state.close() return out diff --git a/tests/backends/test_native_planar_statistics.py b/tests/backends/test_native_planar_statistics.py index 96da6a26f..346fea0d7 100644 --- a/tests/backends/test_native_planar_statistics.py +++ b/tests/backends/test_native_planar_statistics.py @@ -175,7 +175,7 @@ def finished(problem, run_request, grid, rows, dz, options=None): try: native = load_native(backend, problem.initial.field0) _testing.adopt(native, np.ascontiguousarray(rows.reshape(-1)), dz) - actual = native.field_to_host().reshape(problem.shape) + actual = _testing.field(native).reshape(problem.shape) finally: backend.close() return expected, actual diff --git a/tests/backends/test_native_rk_rows.py b/tests/backends/test_native_rk_rows.py index 38c320e2b..99143e2fc 100644 --- a/tests/backends/test_native_rk_rows.py +++ b/tests/backends/test_native_rk_rows.py @@ -117,6 +117,24 @@ def _refusal(call) -> str: return str(caught.value) +def _guarded(route: str, monkeypatch, **guard): + """Return a route's launched backend whose flow guard has `guard`'s constants. + + The guard is set once, where the workspace is built (``_flow_guard``), so a + changed certificate or Taylor scale is a backend built with it. + """ + built = backend_module._flow_guard + + def changed(flow): + record = built(flow) + assert record is not None + return record | guard + + with monkeypatch.context() as patch: + patch.setattr(backend_module, "_flow_guard", changed) + return runge_kutta(route) + + @pytest.mark.parametrize("route", FLOWS) def test_the_native_flow_guards_refuse_as_the_host_s(route, monkeypatch): """Each transcribed guard refuses where solprop's does, with its message. @@ -126,47 +144,41 @@ def test_the_native_flow_guards_refuse_as_the_host_s(route, monkeypatch): """ backend, problem, run_request = runge_kutta(route) try: - backend._staged_rows() flow = backend._flow - state = backend._native_state z, dz = steps(problem, run_request)[0] nodes = _nodes(run_request) - modes = int(flow.vectors.shape[-1]) - allowance = backend_module._flow_allowance(modes) section = int(scalars(problem, z, z + dz, helpers=backend.helpers).flow_section) fractions = np.array([*nodes, 1.0]) measured = np.asarray( - _testing.form_flow_actions(state, section, dz, fractions) + _testing.form_flow_actions(backend._workspace, section, dz, fractions) )[0] - if measured.size: - halved = dataclasses.replace(flow, condition_bound=flow.condition_bound / 2) - expected = _refusal( - lambda: check_flow_conditioning( - backend_module, halved, section, measured, dz - ) - ) - state.flow_guard_configure( - [float(v) for v in flow.row_sum], - [float(v) for v in np.ravel(halved.condition_bound)], - backend_module._TAYLOR_SCALE, - backend_module._MAX_FLOW_SQUARINGS, - allowance, + finally: + backend.close() + if measured.size: + halved = dataclasses.replace(flow, condition_bound=flow.condition_bound / 2) + expected = _refusal( + lambda: check_flow_conditioning( + backend_module, halved, section, measured, dz ) - assert _refusal(lambda: native_trial(backend, z, dz)) == expected - tiny = 1e-12 - # Both refuse at the first stage length past the scale, in the nodes' order. - first = next( - float(f) * dz * float(flow.row_sum[section]) for f in fractions if f ) - monkeypatch.setattr(backend_module, "_TAYLOR_SCALE", tiny) - expected = _refusal(lambda: flow_squarings(backend_module, first)) - state.flow_guard_configure( - [float(v) for v in flow.row_sum], - [float(v) for v in np.ravel(flow.condition_bound)], - tiny, - backend_module._MAX_FLOW_SQUARINGS, - allowance, + bound = np.asarray(halved.condition_bound, dtype=np.float64) + backend, _, _ = _guarded( + route, + monkeypatch, + condition_bound=np.ascontiguousarray(bound).reshape(flow.row_sum.size, -1), ) + try: + assert _refusal(lambda: native_trial(backend, z, dz)) == expected + finally: + backend.close() + tiny = 1e-12 + # Both refuse at the first stage length past the scale, in the nodes' order. + first = next(float(f) * dz * float(flow.row_sum[section]) for f in fractions if f) + monkeypatch.setattr(backend_module, "_TAYLOR_SCALE", tiny) + expected = _refusal(lambda: flow_squarings(backend_module, first)) + monkeypatch.undo() + backend, _, _ = _guarded(route, monkeypatch, taylor_scale=tiny) + try: assert _refusal(lambda: native_trial(backend, z, dz)) == expected finally: backend.close() @@ -186,7 +198,7 @@ def test_the_native_norm_is_the_host_s_to_rounding(slots, atol): rng = np.random.default_rng(slots) partials = np.ascontiguousarray(rng.uniform(0.0, 2.0, size=(3, slots))) for rtol in (1e-8, 1e-3): - found = core.rk_score(partials, rtol, atol) + found = _testing.rk_score(partials, rtol, atol) expected = _host_norm(partials, rtol, atol) # Only the order of each row's sum differs: a few ulps of each sum. assert found == pytest.approx(expected, rel=8 * slots * np.finfo(float).eps) @@ -219,7 +231,7 @@ def _first_attempt(route: str, controller: PIController): new = math.sqrt(float(partials[1].sum())) weighted = np.asarray( _testing.weighted_error( - backend._native_state, + backend._workspace, np.ascontiguousarray(controller.scale(old, new), dtype=np.float64), ) ) @@ -241,9 +253,9 @@ def test_the_weak_scale_is_reduced_natively(): expected = _host_norm(partials, 1e-6, 0.0) assert expected > 0.0 assert norm == pytest.approx(expected, rel=1e-14) - assert core.rk_score(np.ascontiguousarray(partials), 1e-6, 0.0) == pytest.approx( - expected, rel=1e-14 - ) + assert _testing.rk_score( + np.ascontiguousarray(partials), 1e-6, 0.0 + ) == pytest.approx(expected, rel=1e-14) def test_a_weighted_norm_is_the_host_s_to_rounding(): diff --git a/tests/backends/test_native_rk_traces.py b/tests/backends/test_native_rk_traces.py index 6249b688d..8e81b4fe3 100644 --- a/tests/backends/test_native_rk_traces.py +++ b/tests/backends/test_native_rk_traces.py @@ -29,6 +29,7 @@ from tests.backends.rk_traces import Scenario, _HostHarness, same_trace from solprop.backends import available +from solprop.backends.records import RungeKuttaPolicy from solprop.exceptions import BackendError, ConvergenceError from solprop.stepper.schedule import FixedSchedule, reached @@ -104,7 +105,7 @@ def _account_step(self, z: float, cursor: int, energies: Any = None) -> None: self._natural_count += 1 -def _policy_free(harness: _NativeHarness) -> dict[str, object]: +def _policy_free(harness: _NativeHarness) -> RungeKuttaPolicy: return TraceRungeKuttaMarch(harness)._policy() diff --git a/tests/backends/test_native_stage_tables.py b/tests/backends/test_native_stage_tables.py index 5e6873d32..2d05ed749 100644 --- a/tests/backends/test_native_stage_tables.py +++ b/tests/backends/test_native_stage_tables.py @@ -91,7 +91,7 @@ def test_every_route_is_staged(route): backend = backend_of(simulation, problem, run_request) try: assert backend._adams is not None - assert _testing.has_stage_tables(backend._native_state) + assert _testing.has_stage_tables(backend._workspace) finally: backend.close() @@ -101,10 +101,10 @@ def test_the_native_stage_scalars_are_solprop_s_bundle(route): simulation, problem, run_request = translated(route) backend = backend_of(simulation, problem, run_request) try: - state = backend._native_state + state = backend._workspace stages = run_request.stepper.tableau.n_stages for z0, z1 in positions(problem, run_request): - backend._hoist(z0) + backend._stages.hoist(z0) arrays, material = native_stage_rows(backend, z0, z1) expected = dict( zip( @@ -153,7 +153,7 @@ def test_the_native_rate_is_read_on_the_closing_side(): probes = [*edges, *np.linspace(edges[0], edges[-1], 11)] for z in probes: expected = rate_weights(linear, z, before=True, helpers=NATIVE) - found = _testing.adams_stage_rate(backend._native_state, float(z)) + found = _testing.adams_stage_rate(backend._workspace, float(z)) assert np.array_equal(np.asarray(found), expected), z finally: backend.close() diff --git a/tests/backends/test_native_stash_and_saving.py b/tests/backends/test_native_stash_and_saving.py index 611840b76..7bfadcf74 100644 --- a/tests/backends/test_native_stash_and_saving.py +++ b/tests/backends/test_native_stash_and_saving.py @@ -185,21 +185,19 @@ def step_by_step(backend, problem, run_request, *, recycle): next step's first, or dropped so that the next trial evaluates it afresh. Returns the state after the steps, and the steps taken. """ - backend._staged_rows() state = load_native(backend, problem.initial.field0) - nodes = [float(node) for node in run_request.stepper.tableau.nodes] schedule = run_request.stepper.schedule assert schedule is not None edges = np.asarray(schedule.edges) for z, end in itertools.pairwise(edges): dz = float(end - z) - state.rk_trial(float(z), dz, nodes, prepare_only=False) - state.finish(dz) + _testing.rk_trial(state, float(z), dz) + _testing.finish(state, dz) if recycle: _testing.promote_fsal(state) else: - state.clear_fsal() - field = np.asarray(state.field_to_host()).reshape(problem.shape).copy() + _testing.clear_fsal(state) + field = np.asarray(_testing.field(state)).reshape(problem.shape).copy() return field, edges.size - 1 @@ -242,7 +240,7 @@ def run(recycle): backend = NativeBackend(problem, run_request, grid=grid) try: field, taken = step_by_step(backend, problem, run_request, recycle=recycle) - return field, taken, backend._native_state.rk_source_evaluations + return field, taken, backend._diagnostics()["rk_source_evaluations"] finally: backend.close() @@ -260,7 +258,7 @@ def run(recycle): try: session = session_run(backend, problem, run_request) assert committed_steps(session) == taken - assert backend._native_state.rk_source_evaluations == evaluated + assert backend._diagnostics()["rk_source_evaluations"] == evaluated finally: backend.close() if "1" in { diff --git a/tests/backends/test_native_synthetic_operator.py b/tests/backends/test_native_synthetic_operator.py index 31dfd6a33..a7d4198b9 100644 --- a/tests/backends/test_native_synthetic_operator.py +++ b/tests/backends/test_native_synthetic_operator.py @@ -36,7 +36,6 @@ import pytest from backends.geometry_rows import SYNTHETIC_CASES, synthetic -from backends.low_storage_cases import MARCH from backends.synthetic_leaf_cases import ( KERR, free_leaf, @@ -48,6 +47,8 @@ from sessions.runs import run as session_run from solprop.backends.host.low_storage import HostLowStorageMarch from solprop.backends.numpy_ref import NumpyRefBackend +from solprop.backends.records import run_records +from solprop.backends.session import Start from solprop.exceptions import ConvergenceError pytestmark = [ @@ -60,7 +61,7 @@ ] solprop_native = pytest.importorskip("solprop_native") -backend_module = pytest.importorskip("solprop_native.backend") +_testing = pytest.importorskip("solprop_native._core")._testing NativeBackend = solprop_native.NativeBackend @@ -87,21 +88,24 @@ def resident_step(problem, run_request, grid): """Take the schedule's one step on native's resident low-storage engine. Returns the squared norm the engine hands the accept, and the state after the - backend's finish, as the low-storage march accepts a step. + state's finish, as the low-storage march accepts a step + (``_testing.low_storage_norms``). """ edges = np.asarray(run_request.stepper.schedule.edges) assert edges.size == 2, "one step" - dz = float(edges[1] - edges[0]) backend = NativeBackend(problem, run_request, grid=grid) try: - state = load_native(backend, problem.initial.field0) - engine = backend_module._ResidentLowStorage(backend, MARCH) - squared = engine.step(float(edges[0]), dz) - state.finish(dz) - field = np.asarray(state.field_to_host()).reshape(problem.shape) + workspace = load_native(backend, problem.initial.field0) + _testing.configure_march( + workspace, run_records(problem, run_request, Start.entrance(problem)) + ) + (squared,) = np.asarray( + _testing.low_storage_norms(workspace, [float(z) for z in edges]) + ).reshape(-1) + field = np.asarray(_testing.field(workspace)).reshape(problem.shape) finally: backend.close() - return squared, field + return float(squared), field @pytest.mark.parametrize(("case", "mode", "n_pol"), SYNTHETIC_CASES) diff --git a/tests/backends/test_native_widths.py b/tests/backends/test_native_widths.py index 47b582b5f..65104a726 100644 --- a/tests/backends/test_native_widths.py +++ b/tests/backends/test_native_widths.py @@ -414,8 +414,8 @@ def test_a_plane_s_widths_bring_only_numbers_across(n_pol, monkeypatch): The native session reduces the widths in its own pass (``session_statistics.cpp``); what crosses is the packed evaluation its plan unpacks, counted here. The session counts every field it exports, and the native - state every whole-state transfer to the host by any path - (``crossed_bytes()[0]``, solprop SEP 44): both stay at zero over the run. + state every whole-state transfer to the host by any path (its diagnostics' + ``crossed_bytes[0]``, solprop SEP 44): both stay at zero over the run. """ statistics = pytest.importorskip("solprop_native._statistics") grid, problem, run_request = _simulation( @@ -435,8 +435,8 @@ def counted(self, packed): with launched(backend, problem, request) as (session, observation): native = session.native # pyright: ignore[reportAttributeAccessIssue] assert native.status().exports == 0 - state = backend._native_state # pyright: ignore[reportAttributeAccessIssue] - assert state.crossed_bytes()[0] == 0 + diagnostics = backend._diagnostics() # pyright: ignore[reportAttributeAccessIssue] + assert diagnostics["crossed_bytes"][0] == 0 finally: backend.close() assert set(observation.stats) == set(WIDTHS) diff --git a/tests/backends/test_native_z_table.py b/tests/backends/test_native_z_table.py index 90783055d..d861e9374 100644 --- a/tests/backends/test_native_z_table.py +++ b/tests/backends/test_native_z_table.py @@ -48,6 +48,34 @@ def clenshaw_bound(table, z): return 8.0 * terms**2 * EPS * np.sum(np.abs(coefficients), axis=0) +def held(backend, z): + """Return the slot holding `z`'s values in the workspace, loading it if none does. + + The values are read through the one slot cache (``_testing.table_values``), and the + slot named by its exact content: an unloaded slot holds zeros and two positions' + values differ, so one slot matches. Reading the slots touches no cache entry. + """ + workspace = backend._workspace + tables = backend._z_tables + value = _testing.table_values(workspace, "phi", float(z)) + found = [ + slot + for slot in range(tables.slots) + if np.array_equal( + _testing.phase_sum_to_host(workspace, one_hot(tables.n_phi, slot)), value + ) + ] + assert len(found) == 1, found + return found[0] + + +def one_hot(count, slot): + """Return the weights selecting one slot of `count` terms.""" + row = np.zeros(count) + row[slot] = 1.0 + return row + + @pytest.fixture(scope="module") def tabulated(field_grid): """The capillary with both quantities on the z table, under the Adams march.""" @@ -67,15 +95,17 @@ def test_the_slots_hold_the_tables_values(tabulated, field_grid): ) for z in positions: for kind, table in (("phi", phi), ("prefactor", prefactor)): - got = tables.values(kind, z).reshape(table.value_shape) + got = _testing.table_values(backend._workspace, kind, z) + got = got.reshape(table.value_shape) want = table(z) bound = clenshaw_bound(table, z) # Each value against the host's within both evaluations' budgets. assert np.all(np.abs(got - want) <= 2 * bound), (kind, z) - assert tables.evaluations == len(positions) + assert _testing.table_evaluations(backend._workspace) == len(positions) # A position held in a slot is not evaluated again. - tables.load(positions[-tables.slots :]) - assert tables.evaluations == len(positions) + for z in positions[-tables.slots :]: + _testing.table_values(backend._workspace, "phi", z) + assert _testing.table_evaluations(backend._workspace) == len(positions) finally: backend.close() @@ -83,14 +113,14 @@ def test_the_slots_hold_the_tables_values(tabulated, field_grid): def test_the_phase_sum_of_two_slots_is_the_tables_difference(tabulated, field_grid): backend = NativeBackend(*tabulated, grid=field_grid) tables = backend._z_tables - native_state = backend._native_state + workspace = backend._workspace try: phi = tabulated.problem.linear.polynomial z0, z1 = 0.25 * LENGTH, 0.4 * LENGTH - slot_of = tables.load([z0, z1]) - row = tables.phi_row(slot_of, z0, z1) - assert sorted(row[row != 0].tolist()) == [-1.0, 1.0] - got = _testing.phase_sum_to_host(native_state, row).reshape(phi.value_shape) + first, second = held(backend, z0), held(backend, z1) + assert first != second + row = one_hot(tables.n_phi, second) - one_hot(tables.n_phi, first) + got = _testing.phase_sum_to_host(workspace, row).reshape(phi.value_shape) want = phi(z1) - phi(z0) # Two evaluations on each side, each within its budget, and one rounding of # the difference each. @@ -98,12 +128,9 @@ def test_the_phase_sum_of_two_slots_is_the_tables_difference(tabulated, field_gr np.abs(want) ) assert np.all(np.abs(got - want) <= bound) - # The host's exponent for a host engine: the same two slots, subtracted once. - bundle = backend._stage_scalars(z0, z1) - assert np.array_equal(backend._delta_phi(bundle).reshape(got.shape), got) # A step of no length weighs both slots by zero: an exact zero, structural. still = _testing.phase_sum_to_host( - native_state, tables.phi_row(slot_of, z1, z1) + workspace, one_hot(tables.n_phi, second) - one_hot(tables.n_phi, second) ) assert not np.any(still) finally: @@ -122,7 +149,7 @@ def test_the_rate_slot_holds_the_derivative_table(tabulated, field_grid): for z, before in ((edge, True), (edge, False), (0.5 * LENGTH, True)): row = native_rate_weights(backend, z, before=before) assert row.tolist() == [0.0] * tables.slots + [1.0] - got = backend._native_state.table_terms_to_host("phi", tables.rate_slot) + got = _testing.phase_sum_to_host(backend._workspace, row) want = phi_rate(tabulated.problem.linear, z, before=before) index = rate.interval_containing(z) if before and index > 0 and z <= float(rate.breakpoints[index]): @@ -196,16 +223,13 @@ def test_the_slots_are_reused_least_recently_used_first(tabulated, field_grid): try: count = tables.slots first = [LENGTH * index / (2 * count) for index in range(count)] - held = tables.load(first) - assert sorted(held.values()) == list(range(count)) + slots = {z: held(backend, z) for z in first} + assert sorted(slots.values()) == list(range(count)) # One new position takes the least recently used slot, the first position's; - # a call's own positions are never evicted by each other. - assert tables.load([LENGTH])[LENGTH] == held[first[0]] - again = tables.load([first[1], 0.9 * LENGTH]) - assert again[first[1]] == held[first[1]] - assert again[0.9 * LENGTH] == held[first[2]] - assert tables.evaluations == count + 2 - with pytest.raises(BackendError, match="more than the"): - tables.load([LENGTH * index / (3 * count) for index in range(count + 1)]) + # a position read again is the most recently used. + assert held(backend, LENGTH) == slots[first[0]] + assert held(backend, first[1]) == slots[first[1]] + assert held(backend, 0.9 * LENGTH) == slots[first[2]] + assert _testing.table_evaluations(backend._workspace) == count + 2 finally: backend.close() diff --git a/tests/backends/test_numpy_mixture_raman.py b/tests/backends/test_numpy_mixture_raman.py index 1c6d66d5e..f88d7d733 100644 --- a/tests/backends/test_numpy_mixture_raman.py +++ b/tests/backends/test_numpy_mixture_raman.py @@ -24,13 +24,32 @@ def raman_refreshes(backend): - """Read the selected backend's owned Raman kernel refresh counter.""" + """Read a backend's Raman kernel transforms: the reference's own, or the native + workspace's (``raman_kernel_transforms``).""" + if backend.name == "native": + return backend._diagnostics()["raman_kernel_transforms"] return backend._raman_transforms -def prepare_raman(backend, rates, densities): - """Exercise the actual cached Raman owner without a propagation.""" - backend._raman_spectrum(rates, densities) +def prepare_raman(backend, rates, densities=()): + """Prepare a backend's Raman kernel at `rates` and `densities`, without a step. + + The reference's memo returns its kernel; the native workspace prepares its own + (``_testing.prepare_raman``) and returns nothing, and a problem without a Raman + term has no kernel to prepare on either. + """ + if backend.name != "native": + return backend._raman_spectrum(rates, *((densities,) if densities else ())) + if not backend._problem.responses.raman_terms: + return None + _testing = pytest.importorskip("solprop_native._core")._testing + + _testing.prepare_raman( + backend._workspace, + np.ascontiguousarray(rates, dtype=np.float64), + np.ascontiguousarray(densities, dtype=np.float64), + ) + return None @pytest.fixture diff --git a/tests/backends/test_numpy_ref_multimode.py b/tests/backends/test_numpy_ref_multimode.py index 893565534..8eb8a1a3f 100644 --- a/tests/backends/test_numpy_ref_multimode.py +++ b/tests/backends/test_numpy_ref_multimode.py @@ -128,7 +128,7 @@ def scored_alarm(backend): """Read the last step's quadrature score from the backend's own owner. The reference keeps it on the backend; the native backend's state keeps the last - step's score its session's march left (``_core.State.quadrature_error``), which + step's score its session's march left (``_testing.quadrature_error``), which is what the warning of the retired step driver quoted. """ if backend.name == "numpy_ref": @@ -137,7 +137,7 @@ def scored_alarm(backend): _testing, ) - return _testing.quadrature_error(backend._native_state) + return _testing.quadrature_error(backend._workspace) ALARM = ("quadrature_error",) diff --git a/tests/backends/test_numpy_ref_raman.py b/tests/backends/test_numpy_ref_raman.py index eee7f7ccd..f1070eca7 100644 --- a/tests/backends/test_numpy_ref_raman.py +++ b/tests/backends/test_numpy_ref_raman.py @@ -62,6 +62,36 @@ ) from solprop.translate.responses import ResponseStage, prefactor_at + +def raman_refreshes(backend): + """Read a backend's Raman kernel transforms: the reference's own, or the native + workspace's (``raman_kernel_transforms``).""" + if backend.name == "native": + return backend._diagnostics()["raman_kernel_transforms"] + return backend._raman_transforms + + +def prepare_raman(backend, rates, densities=()): + """Prepare a backend's Raman kernel at `rates` and `densities`, without a step. + + The reference's memo returns its kernel; the native workspace prepares its own + (``_testing.prepare_raman``) and returns nothing, and a problem without a Raman + term has no kernel to prepare on either. + """ + if backend.name != "native": + return backend._raman_spectrum(rates, *((densities,) if densities else ())) + if not backend._problem.responses.raman_terms: + return None + _testing = pytest.importorskip("solprop_native._core")._testing + + _testing.prepare_raman( + backend._workspace, + np.ascontiguousarray(rates, dtype=np.float64), + np.ascontiguousarray(densities, dtype=np.float64), + ) + return None + + # 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): # the two agree to one round trip on the doubled grid, `fft_bound(2 n_to)` with its @@ -418,8 +448,8 @@ def test_the_kernel_is_transformed_once_per_change_of_the_decay_rates( 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 + prepare_raman(backend, rates) + transforms = raman_refreshes(backend) backend.close() assert transforms == expected @@ -429,7 +459,8 @@ 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 + rates = backend._stage_scalars(0.0, 0.0).raman_rates + assert prepare_raman(backend, rates) is None backend.close() @@ -899,7 +930,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 = raman_refreshes(backend) 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 846ce50df..c37b87b13 100644 --- a/tests/backends/test_on_axis_statistics.py +++ b/tests/backends/test_on_axis_statistics.py @@ -520,19 +520,6 @@ def test_a_device_s_row_reads_the_reference_s_axis(grid, table, name): _check_axis_row(grid, table, name) -class _StateRefused: - """A native state that refuses to bring its field across (solprop #359).""" - - def __init__(self, state): - self._state = state - - def field_to_host(self): - raise AssertionError("an on-axis statistic brought the state to the host") - - def __getattr__(self, name): - return getattr(self._state, name) - - @pytest.mark.parametrize("radial_rule", ["field_scale", "field_scale_radau"]) def test_the_native_axis_row_leaves_the_state_on_the_device(grid, table, radial_rule): pytest.importorskip("solprop_native") @@ -549,13 +536,16 @@ def test_the_native_axis_row_leaves_the_state_on_the_device(grid, table, radial_ # The session counts every field it exports, and the native state every # whole-state transfer to the host by any path (solprop SEP 44). native = session.native # pyright: ignore[reportAttributeAccessIssue] - state = backend._native_state # pyright: ignore[reportAttributeAccessIssue] + + def to_host() -> int: + return backend._diagnostics()["crossed_bytes"][0] # pyright: ignore[reportAttributeAccessIssue] + assert native.status().exports == 0 - assert state.crossed_bytes()[0] == 0 + assert to_host() == 0 values = _stats(observation) session.export(observation.ticket, IDENTITY) assert native.status().exports == 1, "the count sees a crossing" - assert state.crossed_bytes()[0] > 0, "the state's count sees a crossing" + assert to_host() > 0, "the state's count sees a crossing" assert np.all(values["on_axis_peak_ionisation_rate"] > 0) @@ -571,7 +561,7 @@ def test_the_native_row_refuses_a_matrix_that_is_not_one_or_two_rows(grid, table with closing( select("native", problem, run_request, grid=grid, modes=[mode]) ) as backend: - state = backend._native_state # pyright: ignore[reportAttributeAccessIssue] + state = backend._workspace # pyright: ignore[reportAttributeAccessIssue] with pytest.raises(RuntimeError, match="no initial field"): _testing.axis_spectrum(state, np.ones((1, 1))) load_native(backend, problem.initial.field0) diff --git a/tests/backends/test_polarised_runs.py b/tests/backends/test_polarised_runs.py index cbceee6a1..ede4a68c2 100644 --- a/tests/backends/test_polarised_runs.py +++ b/tests/backends/test_polarised_runs.py @@ -164,7 +164,7 @@ def problem_derivative(backend_class, problem, run_request, grid, modes): _testing, ) - derivative = np.asarray(_testing.stage_to_host(backend._native_state, 0)) + derivative = np.asarray(_testing.stage_to_host(backend._workspace, 0)) return derivative.reshape(2, -1) finally: backend.close() diff --git a/tests/backends/test_radial_absorber.py b/tests/backends/test_radial_absorber.py index 40021b7f9..bd62b4fa0 100644 --- a/tests/backends/test_radial_absorber.py +++ b/tests/backends/test_radial_absorber.py @@ -131,7 +131,7 @@ def test_spatial_absorber_derivative_matches_independent_bessel_operator( ) measured = np.asarray( - _testing.stage_to_host(backend._native_state, 0) + _testing.stage_to_host(backend._workspace, 0) ).reshape(start.shape) assert_allclose(measured[:, :, index], expected, rtol=0, atol=bound) record_metric( diff --git a/tests/backends/test_radial_nonlinear.py b/tests/backends/test_radial_nonlinear.py index 0e9037930..f9caddf52 100644 --- a/tests/backends/test_radial_nonlinear.py +++ b/tests/backends/test_radial_nonlinear.py @@ -133,7 +133,7 @@ def _native_first_stage(backend, problem): _testing, ) - return np.asarray(_testing.stage_to_host(backend._native_state, 0)).reshape( + return np.asarray(_testing.stage_to_host(backend._workspace, 0)).reshape( problem.shape ) diff --git a/tests/backends/test_records.py b/tests/backends/test_records.py index 0039ba3bf..b9cd06b3a 100644 --- a/tests/backends/test_records.py +++ b/tests/backends/test_records.py @@ -509,39 +509,6 @@ def test_an_edged_run_carries_its_edge_s_configuration(): # -- the native conversion ---------------------------------------------------------- -@needs_native -def test_native_reads_the_runge_kutta_policy_with_the_controller_s_fields(): - native_records = pytest.importorskip("solprop_native._records") - problem, request = _gnlse() - stepper = request.stepper - controller = stepper.controller - policy = runge_kutta_policy(problem, stepper) - breakpoints = np.asarray(problem.linear.phi_breakpoints) - assert native_records.rk_policy(policy) == { - "dz_min": stepper.dz_min, - "dz_max": stepper.dz_max, - "stretch": stepper.stretch, - "z_end": stepper.z_end, - "save_planes": list(PLANES), - "interpolate": False, - "hard_kinks": [float(z) for z in problem.linear.hard_kinks], - "breakpoints": [float(breakpoints[0]), float(breakpoints[-1])], - "landing_ulps": LANDING_ULPS, - "quiet_interval": None, - "safety": controller.safety, - "beta1": controller.beta1, - "beta2": controller.beta2, - "min_factor": controller.min_factor, - "max_factor": controller.max_factor, - "lag": controller.lag, - "reject_free": controller.reject_free, - "power": float(controller.estimator_order + 1), - "exponent": 1.0 / (controller.estimator_order + 1), - "start_growth": START_GROWTH, - "auto_init": stepper.auto_init, - } - - @needs_native def test_native_s_adams_march_holds_the_shared_policy(): native_backend = pytest.importorskip("solprop_native.backend") @@ -553,56 +520,3 @@ def test_native_s_adams_march_holds_the_shared_policy(): assert policy == records.policy finally: backend.close() - - -@needs_native -def test_native_reads_the_plane_plan_and_the_continuation(): - native_records = pytest.importorskip("solprop_native._records") - record = _earlier_record() - problem, request = _gnlse(schedule=_uniform()) - start = Start(field=None, z=PLANES[0], plane_index=1, plane_pending=False) - plan = native_records.session_plan( - run_records(problem, request, start).planes, - plane_statistics=None, - row_statistics=None, - monitor=None, - dense=None, - ) - assert plan["replay"] is True - assert (plan["next_plane"], plan["launch_pending"]) == (1, False) - assert plan["planes"].tolist() == list(PLANES) - simulation = _monitored() - monitor = simulation._boundary_monitor() - assert monitor is not None - held = native_records.continuation( - monitor_continuation( - monitor, {"record": record, "plane": True, "unwatched": [(0.2, 0.5)]} - ) - ) - assert held["plane"] is True - assert held["unwatched"] == [[0.2, 0.5]] - assert held["edge_record"] == {"record": True, "launch_energy": 1.0} - flat = held["record"] - assert flat["record"] and flat["collar_quiet"] and flat["steps"] == 12.0 - assert flat["unwatched"] == [[0.1, 0.2]] and flat["resumed_at"] == [0.1] - assert len(flat["planes"]) == len(PLANE_COLUMNS) - - -@needs_native -def test_native_reads_the_edge_s_configuration_by_field(): - native_records = pytest.importorskip("solprop_native._records") - simulation = radial_collar("numpy_ref", RungeKutta()) - problem = simulation.translate() - request = simulation._run_request().for_run( - stats=StatsSpec(), monitor=simulation._boundary_monitor() - ) - held = run_records(problem, request, _entrance(problem)).monitor - assert held is not None and held.edge is not None - values = native_records.edge_config(held.edge) - assert set(values) == {field.name for field in dataclasses.fields(held.edge)} - assert values["faces"] == list(held.edge.faces) - # The arrays cross as they are, not copied. - assert values["kappa"] is held.edge.kappa - config = native_records.monitor_config(held.config) - assert config["rate"] is held.config.rate - assert config["policy"] == held.config.policy diff --git a/tests/backends/test_resident_adams.py b/tests/backends/test_resident_adams.py index 20bb7299a..413cb1bcf 100644 --- a/tests/backends/test_resident_adams.py +++ b/tests/backends/test_resident_adams.py @@ -4,11 +4,11 @@ """SEP 16 phase 3b: the Adams history resident in Kokkos's engine (ADR-043). -Kokkos builds its own engine (``NativeBackend._resident``) for either formulation on -the modal routes when a native session starts its Adams march: the history's rows, the -trial arithmetic, the norms, adoption, transport and dense observation stay in the -native state. These tests pin -that every case takes the resident engine, since SEP 47's phase 5 the only one native +Kokkos builds its own engine (the workspace's method ``"adams"``) for either +formulation on the modal routes when a native session starts its Adams march: the +history's rows, the trial arithmetic, the norms, adoption, transport and dense +observation stay in the native state. These tests pin that every case takes the +resident engine, since SEP 47's phase 5 the only one native has (the host-engine comparisons went with the inherited driver's fallbacks), and hold its device-formed divisor to the reference's. The parity of either against the reference backend is the shared suites' @@ -48,7 +48,7 @@ def engine_of(route: str, integrator: Multistep) -> str: - """Return the name of the engine Kokkos's march takes on a route.""" + """Return the method of the engine Kokkos's march takes on a route.""" simulation = ROUTES[route](None) simulation.settings = type(simulation.settings)( **{ @@ -74,7 +74,7 @@ def engine_of(route: str, integrator: Multistep) -> str: backend, problem, run_request, entrance(problem), owns=False ) try: - return type(backend._resident).__name__ + return backend._diagnostics()["method"] finally: session.close() finally: @@ -96,14 +96,14 @@ def engine_of(route: str, integrator: Multistep) -> str: ) def test_both_formulations_are_resident_on_every_constant_route(route): # Every route here has a constant or separable operator. - assert engine_of(route, Multistep(formulation="interaction")) == "_ResidentAdams" - assert engine_of(route, Multistep(formulation="exponential")) == "_ResidentAdams" + assert engine_of(route, Multistep(formulation="interaction")) == "adams" + assert engine_of(route, Multistep(formulation="exponential")) == "adams" def test_a_varying_operator_is_resident_in_both_formulations(): route = "capillary (pressure gradient)" - assert engine_of(route, Multistep(formulation="interaction")) == "_ResidentAdams" - assert engine_of(route, Multistep(formulation="exponential")) == "_ResidentAdams" + assert engine_of(route, Multistep(formulation="interaction")) == "adams" + assert engine_of(route, Multistep(formulation="exponential")) == "adams" def test_a_divisor_formed_on_the_host_takes_the_same_steps(): @@ -133,7 +133,7 @@ def march(implementation): record: dict[str, object] = {} run = session_run(backend, problem, run_request, record=record) if implementation is NativeBackend: - assert type(backend._resident).__name__ == "_ResidentAdams" + assert backend._diagnostics()["method"] == "adams" calls = cast("dict[str, int]", record["response_calls"]) total = calls["startup"] + calls["predictor"] + calls["corrected"] return np.array(run.fields), total, run.attempts diff --git a/tests/backends/test_tdse_native.py b/tests/backends/test_tdse_native.py index 0d978a4a3..3e031ca35 100644 --- a/tests/backends/test_tdse_native.py +++ b/tests/backends/test_tdse_native.py @@ -381,7 +381,7 @@ def recording(field, z, purpose, out): raw.acknowledge(batch.sequence) batch = raw.advance(1, math.inf) seen["attempts"], seen["position"] = raw.status().attempts, raw.status().z - snapshot = raw.march_snapshot(batch.sequence, raw.status().generation) + snapshot = raw.snapshot((batch.sequence, raw.status().generation)) assert snapshot is not None seen["row"] = np.array(snapshot[2]["store"][0]).reshape(-1) finally: diff --git a/tests/backends/test_transverse_owner.py b/tests/backends/test_transverse_owner.py index 714371d91..daa293838 100644 --- a/tests/backends/test_transverse_owner.py +++ b/tests/backends/test_transverse_owner.py @@ -25,10 +25,10 @@ from __future__ import annotations +import dataclasses import importlib import math import warnings -from dataclasses import dataclass from typing import Any import numpy as np @@ -62,8 +62,28 @@ def _modules() -> tuple[Any, Any]: ) -def _native_records() -> Any: - return importlib.import_module("solprop_native._records") +def _edge_config(config: records.EdgeConfig) -> dict[str, object]: + """Return an edge's configuration as the test module's edge reads it (a dict).""" + values = {one.name: getattr(config, one.name) for one in dataclasses.fields(config)} + values["faces"] = list(config.faces) + return values + + +def _edge_resumption(held: records.EdgeResumption) -> dict[str, object]: + """Return an edge record's resumption as the test module's edge reads it.""" + out: dict[str, object] = {"record": held.record} + if not held.record: + return out + out.update(held.numbers) + for name in ("edge_baseline", "edge_max", "edge_max_raw"): + values = getattr(held, name) + if values is not None: + out[name] = list(values) + if held.reads is not None: + out["reads"] = held.reads + if held.transverse_status is not None: + out["transverse_status"] = held.transverse_status + return out def _space(geometry: str) -> LineGrid | FreeGrid | RadialGrid: @@ -105,7 +125,7 @@ def _design( ) -@dataclass +@dataclasses.dataclass class Readings: """The arrays a drawn reading is made of, scaled by the launch energy.""" @@ -138,7 +158,7 @@ def __init__( space, _design(space, design), budget, 10.0, 0.01, np.arange(1), K800 ) self.native = core.TransverseEdge( - _native_records().edge_config( + _edge_config( records.edge_config( self.python, steps=steps, declared=declared, reads=reads ) @@ -433,9 +453,7 @@ def test_a_resume_continues_the_record_as_solprop_does( pair = Pair(geometry, design) faces = len(pair.python._faces) # pyright: ignore[reportPrivateUsage] pair.python.resume(record) - pair.native.resume( - _native_records().edge_resumption(records.edge_resumption(record, faces)) - ) + pair.native.resume(_edge_resumption(records.edge_resumption(record, faces))) pair.launch(launch, z) pair.state(z, 1e-4) pair.record() @@ -611,9 +629,7 @@ def test_a_record_solprop_s_resume_ignores_is_ignored_alike(record): # reads nothing more: the maxima and the reads are not converted, nor refused. pair = Pair("line", "none") pair.python.resume(record) - pair.native.resume( - _native_records().edge_resumption(records.edge_resumption(record, 2)) - ) + pair.native.resume(_edge_resumption(records.edge_resumption(record, 2))) assert not pair.python.resumed and not pair.native.resumed pair.launch(Readings([0.0] * 4, [0.0] * 4, 0, 0, [1.0], [0.0], 0.0)) pair.record() diff --git a/tests/backends/test_vector_raman.py b/tests/backends/test_vector_raman.py index b847478cb..597a24b56 100644 --- a/tests/backends/test_vector_raman.py +++ b/tests/backends/test_vector_raman.py @@ -31,6 +31,35 @@ from vector_raman_tensor_oracle import BUDGETS, cartesian_direct, convolution_bound +def raman_refreshes(backend): + """Read a backend's Raman kernel transforms: the reference's own, or the native + workspace's (``raman_kernel_transforms``).""" + if backend.name == "native": + return backend._diagnostics()["raman_kernel_transforms"] + return backend._raman_transforms + + +def prepare_raman(backend, rates, densities=()): + """Prepare a backend's Raman kernel at `rates` and `densities`, without a step. + + The reference's memo returns its kernel; the native workspace prepares its own + (``_testing.prepare_raman``) and returns nothing, and a problem without a Raman + term has no kernel to prepare on either. + """ + if backend.name != "native": + return backend._raman_spectrum(rates, *((densities,) if densities else ())) + if not backend._problem.responses.raman_terms: + return None + _testing = pytest.importorskip("solprop_native._core")._testing + + _testing.prepare_raman( + backend._workspace, + np.ascontiguousarray(rates, dtype=np.float64), + np.ascontiguousarray(densities, dtype=np.float64), + ) + return None + + def test_reference_pass_rejects_three_physical_components(): with pytest.raises(BackendError, match="one or two physical components"): passes.raman_polarisation( @@ -229,18 +258,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 + prepare_raman(backend, bundle.raman_rates, bundle.raman_densities) + prepare_raman(backend, bundle.raman_rates, bundle.raman_densities) + assert raman_refreshes(backend) == 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 + prepare_raman(backend, tuple(rates), bundle.raman_densities) + assert raman_refreshes(backend) == 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) + prepare_raman(backend, tuple(rates), (2 * bundle.raman_densities[0],)) + assert raman_refreshes(backend) == 1 + len(rates) finally: backend.close() diff --git a/tests/driver/test_abandoned_step.py b/tests/driver/test_abandoned_step.py index 08aac6dad..7f34dcfd7 100644 --- a/tests/driver/test_abandoned_step.py +++ b/tests/driver/test_abandoned_step.py @@ -145,7 +145,7 @@ def plane(self, z, summary) -> None: def _abandon_natively(monkeypatch, *, after: int) -> None: """Fail the native session's step ``after + 1`` partway, its state overwritten. - The native engine's injected failure (``adams_march_fault``), armed as the session + The native engine's injected failure (``inject_fault``), armed as the session prepares the backend's state: the low-storage step raises after its passes and before its finish, the one way a native step is abandoned in flight. """ @@ -158,7 +158,7 @@ def arming(self, backend, start): ) prepared = prepare(self, backend, start) - _testing.adams_march_fault(backend._native_state, "trial", after, "backend") + _testing.inject_fault(backend._workspace, "trial", after, "backend") return prepared monkeypatch.setattr(session, "_prepare", arming) diff --git a/tests/driver/test_estimate.py b/tests/driver/test_estimate.py index 4f119a18b..df81bf3c3 100644 --- a/tests/driver/test_estimate.py +++ b/tests/driver/test_estimate.py @@ -140,11 +140,12 @@ 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) - monkeypatch.setattr( - constructed, - "_trial_step", - lambda *_: pytest.fail("a low-storage estimate took a trial step"), - ) + if hasattr(constructed, "_trial_step"): # the reference's; native has none + monkeypatch.setattr( + constructed, + "_trial_step", + lambda *_: pytest.fail("a low-storage estimate took a trial step"), + ) def counted(): taken.append(1) @@ -212,24 +213,31 @@ def _backend(simulation): ) -def _native_committed_nothing(problem, probed, fresh, dz): - """Assert a native probe left its loaded state; return the native state's trial. +def _native_trial(problem, fresh, dz): + """Return a fresh native workspace's trial from the launch, finished as kept. - The probed backend's native state holds the launch exactly, as a fresh native state - loaded with it does: nothing was committed. The trial is the same Runge-Kutta trial - from the launch, taken by a fresh native state itself on its staged rows and - finished as a kept step (SEP 47 phase 5: the native backend no longer steps or - observes outside its session). + The same Runge-Kutta trial from the launch the probe takes, taken by a fresh + native workspace itself on its stage tables and finished as a kept step (SEP 47 + phase 5: the native backend no longer steps or observes outside its session). """ assert problem.initial.noise0 is None - fresh._staged_rows() - state = load_native(fresh, problem.initial.field0) - loaded = state.field_to_host() - held = probed._native_state.field_to_host() - assert held.tobytes() == loaded.tobytes() + _testing = pytest.importorskip("solprop_native._core")._testing + workspace = load_native(fresh, problem.initial.field0) native_trial(fresh, float(problem.initial.z), dz) - state.finish(dz) - return np.asarray(state.field_to_host()).reshape(problem.shape) + _testing.finish(workspace, dz) + return np.asarray(_testing.field(workspace)).reshape(problem.shape) + + +def _native_committed_nothing(problem, probed, fresh): + """Assert a native probe left its loaded state, the probe closed. + + The probed backend's workspace holds the launch exactly, as a fresh workspace + loaded with it does: nothing was committed. + """ + _testing = pytest.importorskip("solprop_native._core")._testing + loaded = _testing.field(load_native(fresh, problem.initial.field0)) + held = _testing.field(probed._take_workspace()) + assert held.tobytes() == loaded.tobytes() @pytest.mark.parametrize("backend", BACKENDS) @@ -259,7 +267,7 @@ def test_a_timing_probe_commits_nothing_and_reads_back_its_trial(backend): with pytest.raises(BackendError, match="take a trial"): probe.field() if backend == "native": - trial = _native_committed_nothing(problem, probed, fresh, dz) + trial = _native_trial(problem, fresh, dz) else: # Nothing was committed: no attempt, the launch position, the loaded state. host_stepping(fresh).set_initial( @@ -283,6 +291,9 @@ def test_a_timing_probe_commits_nothing_and_reads_back_its_trial(backend): before = whole.copy() probe.trial(float(problem.initial.z), 0.25 * dz) assert np.array_equal(whole, before) + if backend == "native": + # Read once the probe is closed: it leases the workspace. + _native_committed_nothing(problem, probed, fresh) finally: probed.close() fresh.close() diff --git a/tests/driver/test_native_coupled_flow.py b/tests/driver/test_native_coupled_flow.py index 8069bfb93..a6e371084 100644 --- a/tests/driver/test_native_coupled_flow.py +++ b/tests/driver/test_native_coupled_flow.py @@ -155,7 +155,7 @@ def test_the_flow_s_native_actions_are_the_reference_s_within_the_formation_boun bound = formation_bound(case.problem, case.run_request, dz) backend = native_class()(case.problem, case.run_request, grid=case.grid) try: - native = backend._native_state + native = backend._workspace shape = (fractions.size, -1, reference.n_modes, reference.n_modes) for section in range(reference.frozen.shape[0]): measured = _testing.form_flow_actions(native, section, dz, fractions)[0] diff --git a/tests/driver/test_native_flow_marches.py b/tests/driver/test_native_flow_marches.py index 7b58a9165..c07748d9c 100644 --- a/tests/driver/test_native_flow_marches.py +++ b/tests/driver/test_native_flow_marches.py @@ -107,7 +107,7 @@ def test_the_flow_s_actions_are_the_reference_s_within_the_formation_bound( backend = native.NativeBackend(problem, run_request, grid=simulation.grid) worst = 0.0 try: - state = backend._native_state + state = backend._workspace shape = (fractions.size, -1, reference.n_modes, reference.n_modes) for section in range(reference.frozen.shape[0]): measured = _testing.form_flow_actions(state, section, dz, fractions)[0] @@ -202,7 +202,7 @@ def test_the_formed_actions_are_the_reference_s_on_either_route( monkeypatch.setattr(backend_module, "_host_flow", partial(_held, flow)) backend = native.NativeBackend(problem, run_request, grid=simulation.grid) try: - state = backend._native_state + state = backend._workspace _testing.form_flow_actions(state, 0, length, fractions) forward = _testing.flow_actions_to_host(state, inverse=False).reshape( count, n_active, n_modes, n_modes diff --git a/tests/driver/test_native_flow_pathological.py b/tests/driver/test_native_flow_pathological.py index baadae932..8891239f9 100644 --- a/tests/driver/test_native_flow_pathological.py +++ b/tests/driver/test_native_flow_pathological.py @@ -92,7 +92,7 @@ def formed(monkeypatch, problem, run_request, grid, held, dz): monkeypatch.setattr(native_backend, "_host_flow", lambda _: held) backend = NativeBackend(problem, run_request, grid=grid) try: - native = backend._native_state + native = backend._workspace n_modes = held.vectors.shape[-1] tableau = run_request.stepper.tableau fractions = np.array([*(float(node) for node in tableau.nodes), 1.0]) @@ -203,13 +203,12 @@ def test_the_spectral_norm_bounds_the_singular_value_to_its_rounding(monkeypatch def _native_partials(problem, run_request, grid, field, dz): """Return the error norm's partials of one native trial from `field`. - The native state itself, loaded with the field, scores the staged trial, as the - native backend's own trial does (SEP 47 phase 5). + The native workspace itself, loaded with the field, scores the trial on its stage + tables, as the native march's own trial does (SEP 47 phase 5). """ assert problem.initial.noise0 is None backend = NativeBackend(problem, run_request, grid=grid) try: - backend._staged_rows() load_native(backend, field) return native_trial(backend, 0.0, dz) finally: diff --git a/tests/driver/test_native_flow_session.py b/tests/driver/test_native_flow_session.py index 8b19860a0..6b53ff4cb 100644 --- a/tests/driver/test_native_flow_session.py +++ b/tests/driver/test_native_flow_session.py @@ -149,7 +149,7 @@ def test_a_wide_flow_takes_the_resident_engine_and_the_session(cases, modes): assert native_session.refusal(problem, request) is None backend = NativeBackend(problem, request, grid=case.grid) try: - assert type(backend._resident).__name__ == "_ResidentAdams" + assert backend._diagnostics()["method"] == "adams" # A CPU build's host passes' channel rows: one per bin, nine samples of every # channel; a device's passes hold none. if not DEVICE: @@ -353,19 +353,18 @@ def _resident(simulation: Simulation, problem: Any, request: Any) -> Any: profiles=simulation.profiles, modes=simulation.modes, ) - engine = backend._resident - assert type(engine).__name__ == "_ResidentAdams" + assert backend._diagnostics()["method"] == "adams" field = np.ascontiguousarray(problem.initial.field0, dtype=np.complex128) load_native(backend, field) - native_adams_start(backend, 0.0) - rows = { - name: np.broadcast_to(row[:1], row.shape).copy() - for name, row in native_adams_rows(backend).items() - } - engine.load_rows(rows, engine.shape) + native_adams_start(backend, 0.0, range(backend._adams.n_slots)) return backend +def _compensated(backend: Any) -> bool: + """Whether a native backend's resident Adams history carries a compensation.""" + return bool(backend._compensated(backend.request.stepper.integrator, "transported")) + + def _stencil(order: int) -> tuple[list[float], np.ndarray]: """Return a trial's nodes and rows over `order` samples, newest first. @@ -391,14 +390,18 @@ def _block_departure( ``coupled_moments`` on the engine's own exponent and carrier shift, relative to that matrix's 2-norm, at least one. """ - engine, state = backend._resident, backend._native_state + state = backend._workspace nodes, slots = _stencil(order) norms, shift = native_exponential_trial( backend, z, dz, nodes, slots, order, [order] ) assert np.all(np.isfinite(norms)) count = trial_tables( - nodes, order, [order], compensated=engine.compensated, helpers=backend.helpers + nodes, + order, + [order], + compensated=_compensated(backend), + helpers=backend.helpers, )[1].shape[0] assert bool(shift.size) is carrier expected = coupled_moments( @@ -544,14 +547,14 @@ def test_a_carry_past_thirty_squarings_is_refused_and_keeps_the_state( # it met them, and a trial over one step then forms. backend = _resident(simulation, problem, request) try: - engine, state = backend._resident, backend._native_state - assert engine.compensated + state = backend._workspace + assert _compensated(backend) dz = float(steps[0]) - field, rows = state.field_to_host().copy(), native_adams_rows(backend) + field, rows = _testing.field(state).copy(), native_adams_rows(backend) nodes, slots = _stencil(2) with pytest.raises(BackendError, match="a history sample's carry"): native_exponential_trial(backend, dz, dz, nodes, slots, 2, [2]) - assert state.field_to_host().tobytes() == field.tobytes() + assert _testing.field(state).tobytes() == field.tobytes() for name, row in native_adams_rows(backend).items(): assert row.tobytes() == rows[name].tobytes(), name nodes, slots = _stencil(1) @@ -699,7 +702,7 @@ def _round_trip(simulation, problem, middle, end): owns=True, ) first = NativeBackend(problem, request, **context) - assert type(first._resident).__name__ == "_ResidentAdams" + assert first._diagnostics()["method"] == "adams" taken = [] def take(session, batch) -> None: diff --git a/tests/driver/test_native_march_lifecycle.py b/tests/driver/test_native_march_lifecycle.py index f4adbb1fb..949f04c39 100644 --- a/tests/driver/test_native_march_lifecycle.py +++ b/tests/driver/test_native_march_lifecycle.py @@ -62,20 +62,19 @@ def with_fault(monkeypatch, stage: str, after: int, category: str) -> list[Any]: """Arm a native failure (or, for ``"sigint"`` and ``"sigterm"``, a signal raised in - the native call) when the run's march is first configured, before a session leases - the state; return the marches it was armed on.""" + the native call) when the first run's session is prepared, before it leases the + workspace; return the backends it was armed on.""" armed: list[Any] = [] - configure = NativeAdamsMarch._configure + prepare = NativeSession._prepare - def arming(self, *args): - configure(self, *args) + def arming(self, backend, start): + run = prepare(self, backend, start) if not armed: - _testing.adams_march_fault( - self._backend._native_state, stage, after, category - ) - armed.append(self) + _testing.inject_fault(backend._workspace, stage, after, category) + armed.append(backend) + return run - monkeypatch.setattr(NativeAdamsMarch, "_configure", arming) + monkeypatch.setattr(NativeSession, "_prepare", arming) return armed diff --git a/tests/driver/test_native_moving_guide_bound.py b/tests/driver/test_native_moving_guide_bound.py index 8bda0b220..13e933086 100644 --- a/tests/driver/test_native_moving_guide_bound.py +++ b/tests/driver/test_native_moving_guide_bound.py @@ -80,8 +80,7 @@ def source_at(implementation, problem, run_request, grid, positions): stepper = dataclasses.replace(run_request.stepper, integrator=Multistep()) backend = implementation(problem, run_request.with_stepper(stepper), grid=grid) try: - engine = backend._resident - assert type(engine).__name__ == "_ResidentAdams" + assert backend._diagnostics()["method"] == "adams" sources = [] for z in positions: load_native(backend, state) diff --git a/tests/driver/test_native_resume_history.py b/tests/driver/test_native_resume_history.py index fc2032715..b5064f39e 100644 --- a/tests/driver/test_native_resume_history.py +++ b/tests/driver/test_native_resume_history.py @@ -233,9 +233,8 @@ def assert_same_snapshot(found: MarchSnapshot | None, stored: MarchSnapshot) -> def test_the_resident_history_is_restored_exactly_and_continued(build_simulation, case): simulation = CASES[case](build_simulation, "native")() problem, request, first = opened(simulation, "native") - engine = first._resident - assert type(engine).__name__ == "_ResidentAdams" - shape = (engine.n_slots, *problem.shape) + assert first._diagnostics()["method"] == "adams" + shape = (first._adams.n_slots, *problem.shape) whole = Snapshots() baseline = run_session(first, problem, request, owns=True, between=whole) stored = whole.at_plane(0) @@ -331,7 +330,7 @@ def test_a_native_run_stopped_between_planes_continues_from_its_checkpoint( build_simulation, tmp_path, monkeypatch, caplog ): # The native march's failure is injected natively at a trial past the first - # plane (`adams_march_fault`): the run stops at its last accepted step, strictly + # plane (`inject_fault`): the run stops at its last accepted step, strictly # between two planes, and keeps the march's state beside the terminal checkpoint. from driver.test_native_march_lifecycle import ( # noqa: PLC0415 - needs native with_fault, diff --git a/tests/driver/test_native_rk_march.py b/tests/driver/test_native_rk_march.py index 50d3c1bde..29d41dd2f 100644 --- a/tests/driver/test_native_rk_march.py +++ b/tests/driver/test_native_rk_march.py @@ -148,17 +148,69 @@ def test_interpolated_planes(route): _held(lambda: runge_kutta_route(route, interpolate_planes=True)) +def _host_packed(backend, workspace, bundles, whole): + """Pack a z table's trial rows on the host, as the backend packed them once. + + The ``Phi`` table's positions are loaded into the workspace's slots in one call, + each stage's increment and value then the +-1 weights of its slots; the prefactor + a table's one-hot slot or the bundles' own weights; the other rows the bundles'. + """ + tables = backend._z_tables + stages = [*bundles, whole] + positions = [float(one.z0) for one in stages] + [float(one.z1) for one in stages] + wanted = list(dict.fromkeys(positions)) + slot_of = dict(zip(wanted, _testing.table_load(workspace, wanted), strict=True)) + + def one_hot(z, count): + row = np.zeros(count) + row[slot_of[float(z)]] = 1.0 + return row + + phi_delta = np.stack( + [ + one_hot(one.z1, tables.n_phi) - one_hot(one.z0, tables.n_phi) + for one in stages + ] + ) + phi_at = np.stack([one_hot(one.z1, tables.n_phi) for one in bundles]) + prefactor = ( + np.stack([one_hot(one.z1, tables.slots) for one in bundles]) + if tables.prefactor + else np.stack([one.prefactor for one in bundles]) + ) + arrays = tuple( + np.ascontiguousarray(values, dtype=np.float64) + for values in ( + phi_delta, + phi_at, + prefactor, + [one.density for one in bundles], + [one.taper_scale for one in bundles], + [one.preionisation for one in bundles], + [one.raman_rates for one in bundles], + ) + ) + material = { + "kerr_density": np.asarray([one.kerr_density for one in bundles]), + "plasma_densities": np.asarray([one.plasma_densities for one in bundles]), + "plasma_preionisation": np.asarray( + [one.plasma_preionisation for one in bundles] + ), + "raman_densities": np.asarray([one.raman_densities for one in bundles]), + } + return arrays, material + + def test_a_z_table_s_staged_trial_is_the_host_packed_trial(): """The z table's positions load into other slots, holding the same values. The native state forms a staged trial's stage rows itself (``rk_trial``), loading the z table's positions stage by stage; the host packs the same trial's rows from - solprop's stage scalars (``translate.stage.scalars_at`` into the backend's - ``_trial_arrays``) for the state's unstaged trial (``trial_step``), loading them - together. On one state the two trials are the same to the bit: their scored - partials and every stage. Both trials are called on the backend's native state - directly, loaded with the launch: SEP 47 phase 5 retired the private switch that - made the backend's own trial pack its rows on the host. + solprop's stage scalars (``translate.stage.scalars_at``), with the z table's + positions loaded together into the workspace's slots (``table_load``) and selected + by their +-1 weights, for the state's unstaged trial (``trial_step``). On one state + the two trials are the same to the bit: their scored partials and every stage. + Both trials are called on the backend's workspace directly, loaded with the launch. """ simulation = walk_off("native", RungeKutta()) problem = simulation.translate() @@ -168,8 +220,6 @@ def test_a_z_table_s_staged_trial_is_the_host_packed_trial(): problem, run_request, grid=simulation.grid, modes=simulation.modes ) try: - backend._staged_rows() - assert backend._rk_staged state = load_native(backend, problem.initial.field0) nodes = [float(node) for node in run_request.stepper.tableau.nodes] end = float(run_request.stepper.z_end) @@ -187,7 +237,7 @@ def test_a_z_table_s_staged_trial_is_the_host_packed_trial(): at=held, helpers=backend.helpers, ) - arrays, material = backend._trial_arrays(bundles, whole) + arrays, material = _host_packed(backend, state, bundles, whole) packed = np.asarray(_testing.trial_step(state, dz, *arrays, material)) assert staged.tobytes() == packed.tobytes(), z for index, stage in enumerate(stages): diff --git a/tests/driver/test_runner.py b/tests/driver/test_runner.py index 6148abb0d..a1bf2e271 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 @@ -657,7 +657,7 @@ def test_a_resident_adams_march_holds_no_host_copy_of_the_state(route): simulation.settings, integrator=Multistep() ) with simulation.runner() as runner: - assert getattr(runner.backend, "_resident", None) is not None + assert cast("Any", runner.backend)._diagnostics()["method"] == "adams" output = stored(runner.run(np.array(simulation._field0), progress="none")) assert "adams_host_state" not in runner.backend.memory_ledger() # What a stopped run reports is read from the engine when the session is asked diff --git a/tests/parity_ladder.py b/tests/parity_ladder.py index 450d10fa3..289bef96c 100644 --- a/tests/parity_ladder.py +++ b/tests/parity_ladder.py @@ -330,7 +330,7 @@ def projected(backend_class: type, built: Built) -> list[np.ndarray | None]: try: if backend.name == "native": native_source(backend, problem.initial.field0) - native = backend._native_state + native = backend._workspace from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] _testing, ) diff --git a/tests/sessions/runs.py b/tests/sessions/runs.py index 2ca32160d..05467ec26 100644 --- a/tests/sessions/runs.py +++ b/tests/sessions/runs.py @@ -27,10 +27,11 @@ :func:`watched_run` shape a request or read a run; - :func:`load_native`, :func:`native_trial`, :func:`native_source`, :func:`bind_native_monitor` and :func:`native_reading` reach a native backend's - state (``solprop_native._core.State``) for the kernel-level checks, as the native - session's march does; :func:`native_stage_rows` and :func:`native_rate_weights` - pack a trial's host rows, and :func:`native_adams_start`, :func:`native_adams_rows` - and :func:`native_exponential_trial` reach its resident Adams history, through the + workspace (``solprop_native._core.Workspace``) for the kernel-level checks, as + the native session's march does; :func:`native_stage_rows` and + :func:`native_rate_weights` pack a trial's host rows, and + :func:`native_adams_start`, :func:`native_adams_rows` and + :func:`native_exponential_trial` reach its resident Adams history, through the private test module (``solprop_native._core._testing``). ``native/tests/session_runs.py`` is the native test root's copy of the same names. @@ -885,9 +886,7 @@ def bind_native_monitor( return monitor -def native_reading( - backend: Any, monitor: BoundaryMonitor, field: np.ndarray | None = None -) -> BoundaryEnergies: +def native_reading(backend: Any, monitor: BoundaryMonitor) -> BoundaryEnergies: """Return a native state's boundary reading, as the native session reduces it. The five numbers, the split's removal since the last reading, what the last @@ -899,10 +898,8 @@ def native_reading( backend : solprop_native.NativeBackend The backend, its monitor bound (:func:`bind_native_monitor`). monitor : solprop.monitor.BoundaryMonitor - The monitor as bound (:func:`bind_native_monitor`). - field : numpy.ndarray or None, optional - A state to load first (:func:`load_native`, which unbinds the monitor: - bind it again after); the state as it stands by default. + The monitor as bound (:func:`bind_native_monitor`), after the state was + loaded (:func:`load_native`, which unbinds it). Returns ------- @@ -913,8 +910,6 @@ def native_reading( _testing, ) - if field is not None: - load_native(backend, field) reading = np.asarray(_testing.monitor_reading(backend._workspace), dtype=np.float64) reading = reading.reshape(-1) found = reading[6:10].copy() if monitor.split else None @@ -1055,8 +1050,8 @@ def _native_compensated(backend: Any) -> bool: return bool(backend._compensated(method, "transported")) -def native_adams_start(backend: Any, z: float) -> None: - """Evaluate a native backend's first Adams sample at its loaded state, into row 0. +def native_adams_start(backend: Any, z: float, slots: Sequence[int] = (0,)) -> None: + """Evaluate a native backend's first Adams sample at its loaded state, into `slots`. The native march's start-up (``engines::ResidentEngine``) taken alone, for the kernel-level checks that read one source sample: every stage row at `z` @@ -1070,6 +1065,8 @@ def native_adams_start(backend: Any, z: float) -> None: (:func:`load_native`). z : float The state's position, m. + slots : sequence of int, optional + The history rows that take the sample: row 0 by default. """ from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] _testing, @@ -1081,10 +1078,13 @@ def native_adams_start(backend: Any, z: float) -> None: workspace = backend._workspace backend._stages.hoist(z) arrays, material = native_stage_rows(backend, z, z) - with _envelope_errors(): - _testing.adams_start(workspace, 0, *arrays, material=material) - if _native_compensated(backend): - _testing.adams_compensation_start(workspace, 0, native_rate_weights(backend, z)) + compensated = _native_compensated(backend) + for slot in slots: + with _envelope_errors(): + _testing.adams_start(workspace, slot, *arrays, material=material) + if compensated: + rate = native_rate_weights(backend, z) + _testing.adams_compensation_start(workspace, slot, rate) def native_adams_rows(backend: Any) -> dict[str, np.ndarray]: diff --git a/tests/sessions/test_native_session.py b/tests/sessions/test_native_session.py index ff6e915fc..6bdf670f2 100644 --- a/tests/sessions/test_native_session.py +++ b/tests/sessions/test_native_session.py @@ -537,9 +537,7 @@ def test_the_native_export_is_apply_recipe_to_the_bit(): workspace, np.zeros(n, np.complex128), np.empty(0, np.complex128) ), "rk_march_run": lambda workspace, n: _testing.rk_march_run(workspace, {}, {}), - "adams_march_run": lambda workspace, n: _testing.adams_march_run( - workspace, {}, {} - ), + "adams_march_run": lambda workspace, n: _testing.adams_march_run(workspace, {}, {}), "inject_fault": lambda workspace, n: _testing.inject_fault( workspace, "trial", 0, "backend" ), diff --git a/tests/sessions/test_native_session_carrier_table.py b/tests/sessions/test_native_session_carrier_table.py index 0d41e584c..009d49d18 100644 --- a/tests/sessions/test_native_session_carrier_table.py +++ b/tests/sessions/test_native_session_carrier_table.py @@ -60,6 +60,7 @@ native_session = pytest.importorskip("solprop_native.session") native_backend = pytest.importorskip("solprop_native.backend") +_testing = pytest.importorskip("solprop_native._core")._testing pytestmark = [ pytest.mark.medium, @@ -350,21 +351,22 @@ def test_the_chord_is_a_varying_table_the_session_admits(): backend: Any = select("native", problem, request, **_context(simulation)) try: assert backend._adams._policy.carrier - # The table is the chord's whole description: a chord of kind ``table`` - # without one is refused when the tables are uploaded. tables = backend._stage_tables() assert tables is not None - # A chord kind the build does not know is refused, not cast. - for chord in (3, 4, -1): - with pytest.raises(ValueError, match="stage tables are inconsistent"): - backend._native_state.adams_stage_tables( + assert tables["chord"] == "table" + # A chord kind the build does not know is refused by the record's reader, not + # cast. + for chord in ("spline", 4, -1): + with pytest.raises(ValueError, match=r"stage\.Tables\.chord must name"): + _testing.round_trip( + "stage.Tables", tables | { "chord": chord, "chord_rate": 0.0, "chord_terms": [], "chord_table": None, - } + }, ) finally: backend.close() diff --git a/tests/sessions/test_native_session_device.py b/tests/sessions/test_native_session_device.py index a211f2a84..6f99bbaca 100644 --- a/tests/sessions/test_native_session_device.py +++ b/tests/sessions/test_native_session_device.py @@ -190,7 +190,7 @@ def test_the_device_session_repeats_itself_and_meets_the_reference(case, recipe) status = session.native.status() backend = session._backend # pyright: ignore[reportPrivateUsage] assert backend is not None - to_host, _ = backend._native_state.crossed_bytes() # pyright: ignore[reportPrivateUsage] + to_host, _ = backend._diagnostics()["crossed_bytes"] # pyright: ignore[reportPrivateUsage] session.close() assert_same_run(run, baseline) assert_meets_reference(run, reference, plane_bound=DEVICE_PLANE_BOUND) diff --git a/tests/sessions/test_native_session_history.py b/tests/sessions/test_native_session_history.py index b0e2420de..9fec74d79 100644 --- a/tests/sessions/test_native_session_history.py +++ b/tests/sessions/test_native_session_history.py @@ -484,12 +484,12 @@ def test_a_failure_between_batches_still_checkpoints_the_committed_state(): def _armed(monkeypatch, stage: str, after: int, category: str) -> None: - """Arm a native march fault when a native session configures its march. + """Arm a native march fault when a native session prepares its run. Parameters ---------- monkeypatch : pytest.MonkeyPatch - Restores the march's configuration. + Restores the session's preparation. stage : str ``"startup"``, ``"trial"`` or ``"accept"``. after : int @@ -497,14 +497,15 @@ def _armed(monkeypatch, stage: str, after: int, category: str) -> None: category : str The failure, or ``"sigint"`` or ``"sigterm"`` for a signal raised in the call. """ - march = native_backend._NativeAdamsMarch - configure = march._configure + session = native_session.NativeSession + prepare = session._prepare - def arming(self, *args: Any) -> None: - configure(self, *args) - _testing.adams_march_fault(self._backend._native_state, stage, after, category) + def arming(self: Any, backend: Any, start: Any) -> Any: + run = prepare(self, backend, start) + _testing.inject_fault(backend._workspace, stage, after, category) + return run - monkeypatch.setattr(march, "_configure", arming) + monkeypatch.setattr(session, "_prepare", arming) @needs_default_sigterm diff --git a/tests/sessions/test_native_session_low_storage.py b/tests/sessions/test_native_session_low_storage.py index 83beca03e..054e044dc 100644 --- a/tests/sessions/test_native_session_low_storage.py +++ b/tests/sessions/test_native_session_low_storage.py @@ -134,9 +134,7 @@ def __init__(self, *args: Any, after: int, **kwargs: Any) -> None: def _prepare(self, backend, start): """Prepare as the session does, then arm the native failure.""" prepared = super()._prepare(backend, start) - _testing.adams_march_fault( - backend._native_state, "trial", self._after, "backend" - ) + _testing.inject_fault(backend._workspace, "trial", self._after, "backend") return prepared diff --git a/tests/sessions/test_native_session_transverse.py b/tests/sessions/test_native_session_transverse.py index 1bb044acc..e2b09da17 100644 --- a/tests/sessions/test_native_session_transverse.py +++ b/tests/sessions/test_native_session_transverse.py @@ -386,12 +386,10 @@ def simulation() -> Simulation: finally: _counters.disable() reference, native = served - # A restart's launch is judged on the loaded state less the draw, which crosses - # once; a continued record's launch is not judged, and nothing crosses for it. - if continued: - assert crossings[1] == {} - else: - assert sum(crossings[1].values()) == 1, crossings[1] + # A restart's launch is judged on the loaded state less the draw, read on the host + # before the state crosses (SEP 52); a continued record's launch is not judged. + # Neither reads the state back. + assert crossings[1] == {} _compare(reference, native) assert native.record is not None edge = native.record["transverse"] diff --git a/tests/test_transverse_reads.py b/tests/test_transverse_reads.py index 9e496a531..cd6ee7b42 100644 --- a/tests/test_transverse_reads.py +++ b/tests/test_transverse_reads.py @@ -397,19 +397,6 @@ def test_the_scaled_miss_is_read_far_above_the_stop() -> None: assert max(record["edge_max"]) > 1e3 * STOP -def _driver_class(backend: str) -> type: - """Return the class of `backend`'s step driver, which holds its edge reading.""" - 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 - - return HostDriver - - @pytest.mark.parametrize( ("backend", "route"), [("numpy_ref", "host"), ("native", "session")], @@ -429,14 +416,23 @@ def test_a_plane_the_step_already_read_reduces_nothing_more( length = packet.length planes = [length / 4, length / 2, length] calls = {"readings": 0} - driver = cast("type[Any]", _driver_class(backend)) - edge_reading = driver._edge_reading + if route == "session": + from solprop_native.backend import ( # pyright: ignore[reportMissingImports] # noqa: PLC0415 + NativeBackend, + ) + + # The native backend holds no edge reading in Python to go through. + assert not hasattr(NativeBackend, "_edge_reading") + else: + from solprop.backends.host.driver import HostDriver # noqa: PLC0415 + + edge_reading = HostDriver._edge_reading - def counting(self: Any, *args: Any, **keywords: Any) -> _EdgeReading: - calls["readings"] += 1 - return edge_reading(self, *args, **keywords) + 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(HostDriver, "_edge_reading", counting) schedule = FixedSchedule.uniform(0.0, length, length / 8, save_planes=planes) with warnings.catch_warnings(): warnings.simplefilter("ignore", BoundaryWarning) diff --git a/tests/vector_raman_cases.py b/tests/vector_raman_cases.py index cfbf9a471..608592d3c 100644 --- a/tests/vector_raman_cases.py +++ b/tests/vector_raman_cases.py @@ -146,7 +146,6 @@ def result(backend_class, problem, run_request, grid, modes, options=CHUNK): else: assert backend.name == "native" assert problem.initial.noise0 is None - backend._staged_rows() state = load_native(backend, problem.initial.field0) native_trial(backend, 0.0, LENGTH / 8) from solprop_native._core import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports, reportMissingModuleSource] From 4f675c4fc7e135aa8f08f11ad74f73e1d88882cc Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 04:09:08 +0000 Subject: [PATCH 07/29] test(sessions): native's AcceptRecord carries each step's split sums (SEP 52) Co-Authored-By: Claude Opus 5.5 --- tests/sessions/test_split_collar_rules.py | 65 +++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/tests/sessions/test_split_collar_rules.py b/tests/sessions/test_split_collar_rules.py index 7c90a10a3..b7a32c4ec 100644 --- a/tests/sessions/test_split_collar_rules.py +++ b/tests/sessions/test_split_collar_rules.py @@ -37,6 +37,7 @@ import dataclasses import functools +import math from collections.abc import Mapping from typing import Any @@ -374,3 +375,67 @@ def resumed() -> Start: assert abs(float(fresh["raw_removed_fraction"]) - total) <= reading_tolerance( total, bound, STEPS ) + + +@pytest.mark.skipif("native" not in available(), reason="native is not installed") +@pytest.mark.parametrize("march", ["rk", "low-storage"]) +def test_native_s_accept_record_carries_each_step_s_sums(march): + """SEP 52 section 5.2: an accepted step's finish returns the split collar's sums. + + Native's engines (``_testing.engines``) report, in each step's ``AcceptRecord``, + what that step's split took and the power it found, measured where native measures + them, during the split, from the masked field before it. The removals of the steps + since the monitor was bound add up to what the next reading drains, and the + latest step's found sums are the ones that reading judges; the stiffness is not + formed natively. + """ + from solprop.backends.engines import AcceptRecord # noqa: PLC0415 + from solprop.backends.records import run_records # noqa: PLC0415 + from solprop.boundaries import SPLIT_RATE_BUCKETS # noqa: PLC0415 + + testing = pytest.importorskip("solprop_native._core")._testing + simulation = walking_fibre("native", MARCHES[march]) + problem, request, own = _backend(simulation) + try: + monitor = dataclasses.replace( + simulation._boundary_monitor(), crossing=problem.split_crossing + ) + assert monitor.split + workspace = own._workspace + field = np.ascontiguousarray(problem.initial.field0).reshape(-1) + testing.load(workspace, field, np.empty(0, dtype=np.complex128)) + testing.configure_march( + workspace, run_records(problem, request, Start.entrance(problem)) + ) + crossing = problem.split_crossing + occupancy = None + if crossing is not None: + occupancy = { + "buckets": np.ascontiguousarray(crossing.buckets, np.uint8).ravel(), + "count": SPLIT_RATE_BUCKETS, + } + testing.bind_monitor(workspace, own._monitor_binding(monitor), None, occupancy) + schedule = request.stepper.schedule + assert schedule is not None + engines = testing.engines(workspace) + records: list[AcceptRecord] = [] + try: + for z, dz in zip(schedule.edges[:3], schedule.steps[:3], strict=True): + engines.rk_trial(float(z), float(dz)) + records.append(engines.rk_accept(float(dz))) + finally: + engines.close() + reading = np.asarray(testing.monitor_reading(workspace)).reshape(-1) + finally: + own.close() + removed = [record.removed for record in records] + assert all(value > 0.0 for value in removed) + assert all(math.isnan(record.stiffness) for record in records) + # One sum of three per-step sums against the accumulator's sum of the same + # chunks' terms, in another association: three additions' rounding. + assert reading[5] == pytest.approx(sum(removed), rel=3 * np.finfo(float).eps) + found = records[-1].found + assert found is not None + assert found.shape == (4,) + # The same view, read twice: the latest step's found sums, exactly. + np.testing.assert_array_equal(found, reading[6:10]) From a70d32b9afc660421f8d41667f25aaa2bca1f392 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 04:25:39 +0000 Subject: [PATCH 08/29] build(native): generate the whole _core and _testing stubs with stubgen (SEP 52) problem_stub.py now writes _core.pyi and _core_testing.pyi whole from nanobind.stubgen; the bindings name each record argument and result with nb::sig (the run start and probe start, the export recipe, the monitor continuation, the run records, the protocol records, the batch arrays), and --check holds both stubs. The broken adams_host benchmark, which reached the deleted _ResidentAdams, goes. Co-Authored-By: Claude Opus 5.5 --- benchmarks/adams_host.py | 227 ------- native/include/solprop_native/workspace.hpp | 10 +- native/scripts/problem_stub.py | 228 ++++--- native/src/bindings.cpp | 375 +++++++---- native/src/solprop_native/_core.pyi | 655 +++++++++----------- native/src/solprop_native/_core_testing.pyi | 561 +++++++++-------- tests/sessions/test_split_collar_rules.py | 6 +- 7 files changed, 1013 insertions(+), 1049 deletions(-) delete mode 100644 benchmarks/adams_host.py diff --git a/benchmarks/adams_host.py b/benchmarks/adams_host.py deleted file mode 100644 index 8cf006350..000000000 --- a/benchmarks/adams_host.py +++ /dev/null @@ -1,227 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""Time an exponential Adams run's host side per trial (SEP 39 section 7.6). - -The host time of a trial is the Adams march's wall time less the native ``adams_*`` -calls it makes, measured with those two wrappers alone: per-piece wrappers on every -host function inflate the total by about half, so they are for the split between -pieces, not for the sum. The run is one benchmark case, built, warmed up and timed by -the suite's own worker (:func:`benchmarks.worker.timed_run`) in a fresh process under -the suite's thread pools. - -Usage:: - - uv run python -m benchmarks.adams_host CASE [--width N] [--length F] [--stepper S] - [--step-planes N] [--row-period N] - -It prints one JSON record: the wall time, the accepted and rejected steps and the -source calls. The native backend is required. Every run is the native execution -session's, whose march is not ``_NativeAdamsMarch``'s ``march_to``, so the record has -the host and native time per trial in microseconds only for a march that calls it; its -``wall_seconds`` and the session's counters (``benchmarks.native_session``) are the -comparison. The host-stage and host-march arms that compared SEP 39's phases on one -build were retired with the transitional bridge they ran on (SEP 47 section 6.3, -phase 5); the identical-input traces of the test suite -(``tests/backends/adams_traces.py``) hold the native march to solprop's decisions. -``--step-planes N`` adds a natural stop every N accepted steps and ``--row-period N`` -an energy row every N accepted steps (``StatsSpec.periodic``): with N = 1 each is a host -event at every step, the frequent-event shapes of SEP 39 section 7.6 (#273). A busy -boundary monitor is `argon_blueshift_envelope`'s own. -""" - -from __future__ import annotations - -import argparse -import dataclasses -import json -import os -import subprocess -import sys -import time -from typing import Any - -from benchmarks.system import thread_environment - -__all__ = ["HostTotals", "install", "main"] - -CHILD = "_SOLPROP_ADAMS_HOST_CHILD" -"""Set in the fresh process the command runs the case in.""" - - -class HostTotals: - """The march's wall time and its native Adams calls' time, in seconds.""" - - def __init__(self) -> None: - self.march = 0.0 - self.native = 0.0 - - -def install() -> HostTotals: - """Wrap the Adams march and the resident engine's native calls with two timers. - - Returns - ------- - HostTotals - The totals the wrappers add to. - """ - # Optional, and imported after the pools are set. - import solprop_native.backend # noqa: PLC0415 # pyright: ignore[reportMissingImports] - - backend = solprop_native.backend - - totals = HostTotals() - - def timed(method: Any, key: str) -> Any: - def wrapper(*args: Any, **keywords: Any) -> Any: - started = time.perf_counter() - try: - return method(*args, **keywords) - finally: - setattr( - totals, key, getattr(totals, key) + time.perf_counter() - started - ) - - return wrapper - - # Every native run's march is the native backend's (SEP 39), which runs the - # Python march itself when it is not admitted; the native march's one call a host - # event is its native time. - native_march = backend._NativeAdamsMarch - native_march.march_to = timed(native_march.march_to, "march") # pyright: ignore[reportAttributeAccessIssue] - native_march._native_run = timed(native_march._native_run, "native") # pyright: ignore[reportAttributeAccessIssue] - - class Native: - """The native state, its ``adams_*`` calls timed and the rest passed on.""" - - def __init__(self, native: Any) -> None: - object.__setattr__(self, "_native", native) - - def __getattr__(self, name: str) -> Any: - value = getattr(self._native, name) - if not name.startswith("adams_"): - return value - - def timed(*args: Any, **keywords: Any) -> Any: - started = time.perf_counter() - try: - return value(*args, **keywords) - finally: - totals.native += time.perf_counter() - started - - return timed - - initialise = backend._ResidentAdams.__post_init__ - - def post_init(self: Any) -> None: - initialise(self) - object.__setattr__(self, "native", Native(self.native)) - - backend._ResidentAdams.__post_init__ = post_init - return totals - - -def _run( - case: str, - stepper: str, - width: int, - fraction: float, - *, - step_planes: int = 0, - row_period: int = 0, -) -> dict[str, Any]: - """Run the case in this process and return its record.""" - # Before any other OpenMP runtime on macOS. - import solprop_native # noqa: F401, PLC0415 # pyright: ignore[reportMissingImports, reportUnusedImport] - - from benchmarks.builders import build # noqa: PLC0415 - from benchmarks.registry import CASES # noqa: PLC0415 - from benchmarks.worker import timed_run, warm_up # noqa: PLC0415 - from solprop.backends import select # noqa: PLC0415 - from solprop.driver.run import field_retention # noqa: PLC0415 - from solprop.stats import StatsSpec # noqa: PLC0415 - - totals = install() - configuration = CASES[case].configuration(stepper, width, "native", fraction) - simulation = build(configuration) - settings = simulation.settings - if step_planes: - settings = dataclasses.replace(settings, step_planes=step_planes) - if row_period: - # The case's own statistics are kept, with an energy row between the planes. - spec = settings.stats if settings.stats is not None else StatsSpec() - spec = dataclasses.replace( - spec, - names=tuple(dict.fromkeys((*spec.names, "energy"))), - periodic=("energy",), - period=row_period, - ) - settings = dataclasses.replace(settings, stats=spec) - simulation.settings = settings - problem = simulation.translate() - request = simulation._run_request() - engine = select( - "native", - problem, - request, - grid=simulation.grid, - modes=simulation.modes, - profiles=simulation.profiles, - options=simulation.settings.execution_options(), - ) - try: - retention = field_retention( - request, simulation.settings.fields, simulation.settings.field_planes - ) - warm_up(engine, problem, configuration["warmup"] * configuration["stop"]) - totals.march = totals.native = 0.0 - record, _ = timed_run(simulation, problem, engine, retention) - finally: - engine.close() - trials = record["accepted"] + record["rejected"] - record.update( - case=case, - stepper=stepper, - width=width, - fraction=fraction, - step_planes=step_planes, - row_period=row_period, - ) - if totals.march > 0.0: - record["host_us_per_trial"] = 1e6 * (totals.march - totals.native) / trials - record["native_us_per_trial"] = 1e6 * totals.native / trials - return record - - -def main(argv: list[str] | None = None) -> int: - """Run one case in a fresh process and print its record.""" - parser = argparse.ArgumentParser(description="SEP 39: an Adams run's host time") - parser.add_argument("case") - parser.add_argument("--width", type=int, default=1) - parser.add_argument("--length", type=float, default=1.0) - parser.add_argument("--stepper", default="default") - parser.add_argument("--step-planes", type=int, default=0) - parser.add_argument("--row-period", type=int, default=0) - args = parser.parse_args(argv) - if os.environ.get(CHILD) == "1": - record = _run( - args.case, - args.stepper, - args.width, - args.length, - step_planes=args.step_planes, - row_period=args.row_period, - ) - print(json.dumps(record)) - return 0 - environment = thread_environment(args.width, dict(os.environ)) - environment[CHILD] = "1" - command = [sys.executable, "-m", "benchmarks.adams_host", *sys.argv[1:]] - if argv is not None: - command = [sys.executable, "-m", "benchmarks.adams_host", *argv] - return subprocess.call(command, env=environment) - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/native/include/solprop_native/workspace.hpp b/native/include/solprop_native/workspace.hpp index afa4a63ec..6d6b62655 100644 --- a/native/include/solprop_native/workspace.hpp +++ b/native/include/solprop_native/workspace.hpp @@ -188,7 +188,8 @@ struct Occupancy { using O = Occupancy; using E = fields::Extent; return fields::table( - "Occupancy", fields::array("buckets", &O::buckets, fields::Dtype::uint8, E::any()), + "Occupancy", + fields::array("buckets", &O::buckets, fields::Dtype::uint8, E::any()), fields::value("count", &O::count)); } @@ -210,8 +211,8 @@ struct Occupancy { } /** The transverse edge's tables where the state lives (solprop SEP 44), a run's: the - faces', the clip's and the totals' weights, a reduction's synthesis (empty for none), - the first row, and a requested collar's lines. */ + faces', the clip's and the totals' weights, a reduction's synthesis (empty for + none), the first row, and a requested collar's lines. */ struct EdgeBinding { std::vector faces; std::vector clip; @@ -741,7 +742,8 @@ class Workspace { void apply(const Setup& setup); void require_built() const; void require_open() const; - void bind_run_monitor(const MonitorBinding& monitor, const std::optional& edge); + void bind_run_monitor(const MonitorBinding& monitor, + const std::optional& edge); /** The march a session runs: from the run's policy and schedule and the stage tables, its engine over the state, its dense output when `dense`, and its state at the start. */ diff --git a/native/scripts/problem_stub.py b/native/scripts/problem_stub.py index ed7bf855d..fd4b6a0db 100644 --- a/native/scripts/problem_stub.py +++ b/native/scripts/problem_stub.py @@ -2,25 +2,24 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""Write the bound problem's part of ``_core.pyi`` from ``nanobind.stubgen``. - -The extension binds ``FieldFamily`` and the nested ``Problem`` aggregates; stubgen -writes each field as a property and its setter, typed by the array caster. This keeps -the setter's type as a plain attribute, so the stub stays short and strict pyright -accepts the adapter's assignments, and replaces the text between the stub's markers. -``--check`` exits 1 instead when the committed stub differs (the native lint stage). - -The private test module ``_core._testing`` (solprop SEP 52) has a hand-written stub, -``_core_testing.pyi``, whose records stubgen would type only as bare ``dict``; -``--check`` also holds its names, and each class's members, to the built module's. +"""Write ``_core.pyi`` and ``_core_testing.pyi`` from ``nanobind.stubgen``. + +Both stubs are generated whole (solprop SEP 52 section 5.3): the extension's module +and its private test module ``_core._testing``. The bindings give each record argument +and result a signature naming its Python record (``nb::sig``), so the stubs stay +typed; this script only rewrites stubgen's spellings into the stubs' own: an array +caster's ``Annotated[NDArray[...], ...]`` as ``npt.NDArray[...]``, a bare ``dict``, +``tuple`` or ``list`` with its parameters, a problem group's property and setter as a +plain attribute (an array field is copied in and out: assign a whole array), and the +imports each stub uses. ``--check`` exits 1 instead when a committed stub differs (the +native lint stage). """ -import ast import re import subprocess import sys -from collections.abc import Iterable from pathlib import Path +from types import ModuleType from nanobind.stubgen import StubGen @@ -28,86 +27,143 @@ STUB = Path(__file__).resolve().parents[1] / "src/solprop_native/_core.pyi" TESTING_STUB = STUB.with_name("_core_testing.pyi") -BEGIN = ( - "# Generated by native/scripts/problem_stub.py from nanobind.stubgen.\n" - "# Array fields are copied in and out: assign a whole array, since an item\n" - "# assigned through a read copy changes nothing.\n" -) -END = "\n# End of the generated problem stub.\n" +HEADER = """\ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +# Generated by native/scripts/problem_stub.py from nanobind.stubgen: do not edit. +""" PAIR = re.compile( - r"@property\n\s*def (\w+)\(self\) -> .+: \.\.\.\n\n" - r"\s*@\1\.setter\n\s*def \1\(self, arg: (.+), /\) -> None: \.\.\." + r"@property\n(\s*)def (\w+)\(self\) -> (.+): \.\.\.\n\n" + r"\s*@\2\.setter\n\s*def \2\(self, arg: (.+), /\) -> None: \.\.\." ) - - -def generated() -> str: - """Return the problem's stub section, formatted as ruff formats a stub.""" - stub = StubGen(core, quiet=True, include_docstrings=False) - for name in ("FieldFamily", "Problem"): - stub.put(getattr(core, name), name) - text = PAIR.sub(r"\1: \2", stub.get()) - text = text.replace("numpy.typing.NDArray[numpy.", "npt.NDArray[np.") - text = text[text.index("class FieldFamily") :] - text = re.sub(r"\n\n( +\w+: )", r"\n\1", text) - text = re.sub(r"(def __init__\(self\) -> None: \.\.\.)\n\n", r"\1\n", text) - formatted = subprocess.run( - [sys.executable, "-m", "ruff", "format", "--stdin-filename", str(STUB), "-"], - input=text, - capture_output=True, - text=True, - check=True, - ).stdout - return BEGIN + formatted + END - - -def _public(names: Iterable[str]) -> set[str]: - """Return the names that do not start with an underscore, and ``__init__``.""" - return {name for name in names if not name.startswith("_") or name == "__init__"} - - -def testing_drift() -> list[str]: - """Return how ``_core_testing.pyi``'s names differ from ``_core._testing``'s.""" - tree = ast.parse(TESTING_STUB.read_text(encoding="utf-8")) - stub: dict[str, set[str] | None] = {} - for node in tree.body: - if isinstance(node, ast.FunctionDef): - stub[node.name] = None - elif isinstance(node, ast.ClassDef): - stub[node.name] = { - item.name for item in node.body if isinstance(item, ast.FunctionDef) - } - module = core._testing # pyright: ignore[reportPrivateUsage] - drift = [ - f"{name}: {'not in the stub' if name not in stub else 'not in the module'}" - for name in sorted(_public(dir(module)) ^ set(stub)) +ARRAY = re.compile(r"Annotated\[NDArray\[numpy\.(\w+)\], dict\(") +IMPORTS = { + "enum.": "import enum", + "Any": "from typing import Any", + "overload": "from typing import overload", + "Mapping": "from collections.abc import Mapping", + "Sequence": "from collections.abc import Sequence", + "Callable": "from collections.abc import Callable", + "np.": "import numpy as np", + "npt.": "import numpy.typing as npt", + "solprop.backends.records.": "import solprop.backends.records", + "solprop.backends.engines.": "import solprop.backends.engines", +} + + +def _arrays(text: str) -> str: + """Return `text` with each array caster's annotation as ``npt.NDArray[np.X]``.""" + out: list[str] = [] + position = 0 + while (match := ARRAY.search(text, position)) is not None: + out.append(text[position : match.start()]) + out.append(f"npt.NDArray[np.{match.group(1)}]") + # Skip the caster's `dict(...)` and the closing bracket, parentheses balanced. + depth, index = 1, match.end() + while depth: + depth += {"(": 1, ")": -1}.get(text[index], 0) + index += 1 + position = index + 1 + out.append(text[position:]) + return "".join(out) + + +def _body(module: ModuleType, names: list[str] | None = None) -> str: + """Return stubgen's stub of `module`'s names, in the stubs' spellings, no imports.""" + stub = StubGen(module, quiet=True, include_docstrings=False) + for name in names if names is not None else sorted(vars(module)): + if name.startswith("__") or name == "_testing": + continue + stub.put(getattr(module, name), name) + text = _arrays(stub.get()) + text = PAIR.sub(r"\2: \4", text) + lines = [ + line + for line in text.splitlines() + if not line.startswith(("import ", "from ")) + ] + text = "\n".join(lines).strip() + "\n" + replacements = { + "numpy.typing.NDArray[numpy.": "npt.NDArray[np.", + "collections.abc.": "", + "typing.": "", + "solprop_native._core.": "", + } + for old, new in replacements.items(): + text = text.replace(old, new) + text = re.sub(r"\bdict\b(?!\[)", "dict[str, Any]", text) + text = re.sub(r"\btuple\b(?!\[)", "tuple[Any, ...]", text) + text = re.sub(r"\blist\b(?!\[)", "list[Any]", text) + return text + + +def _imports(body: str, extra: list[str]) -> str: + """Return the import lines `body` uses, and `extra`.""" + lines = sorted({line for token, line in IMPORTS.items() if token in body}) + return "\n".join(["from __future__ import annotations", "", *lines, *extra]) + "\n" + + +def _formatted(text: str, path: Path) -> str: + """Return `text` with its imports sorted and formatted, as ruff leaves a stub.""" + ruff = [sys.executable, "-m", "ruff"] + for command in ( + ["check", "--fix", "--select", "I", "--quiet", "--exit-zero"], + ["format"], + ): + text = subprocess.run( + [*ruff, *command, "--stdin-filename", str(path), "-"], + input=text, + capture_output=True, + text=True, + check=True, + ).stdout + return text + + +def generated() -> dict[Path, str]: + """Return both stubs' text, formatted as ruff formats a stub.""" + body = _body(core) + extra = [ + "", + "# The private test module, bound as the submodule `_testing` (solprop SEP 52):", + "# its stub is `_core_testing.pyi`; the extension has no `_core_testing`.", + "from solprop_native import _core_testing", + "", + "_testing = _core_testing", ] - for name, members in stub.items(): - bound = getattr(module, name, None) - if members is not None and isinstance(bound, type): - drift.extend( - f"{name}.{member}: differs between the stub and the module" - for member in sorted(_public(vars(bound)) ^ members) - ) - return drift + main = HEADER + "\n" + _imports(body, extra) + "\n" + body + testing = _body(core._testing) # pyright: ignore[reportPrivateUsage] + bound = sorted( + name + for name in vars(core) + if not name.startswith("_") and re.search(rf"\b{name}\b", testing) + ) + testing_extra = [f"from solprop_native._core import {', '.join(bound)}"] + private = ( + HEADER + + "# The private test module `solprop_native._core._testing` (solprop SEP 52 " + "section 6.5):\n# the entry points only solprop's own tests reach. It promises" + " nothing.\n\n" + + _imports(testing, testing_extra) + + "\n" + + testing + ) + return {STUB: _formatted(main, STUB), TESTING_STUB: _formatted(private, STUB)} def main(argv: list[str]) -> int: - """Rewrite the section, or with ``--check`` report whether it is stale.""" - text = STUB.read_text(encoding="utf-8") - # The section runs from the marker's first line to the end marker. - start = text.index(BEGIN.splitlines(keepends=True)[0]) - end = text.index(END, start) + len(END) - head, current, tail = text[:start], text[start:end], text[end:] - fresh = generated() - if drift := testing_drift(): - print(f"{TESTING_STUB.name} disagrees with _core._testing:", *drift, sep="\n ") + """Write both stubs, or with ``--check`` report whether either is stale.""" + stale = [] + for path, text in generated().items(): + if path.read_text(encoding="utf-8") != text: + if "--check" not in argv: + path.write_text(text, encoding="utf-8") + stale.append(path.name) + if stale and "--check" in argv: + print(f"{', '.join(stale)} stale: run native/scripts/problem_stub.py") return 1 - if "--check" in argv: - if current != fresh: - print(f"{STUB.name} is stale: run native/scripts/problem_stub.py") - return 1 - return 0 - STUB.write_text(head + fresh + tail, encoding="utf-8") return 0 diff --git a/native/src/bindings.cpp b/native/src/bindings.cpp index 0a9832650..4c044b9c8 100644 --- a/native/src/bindings.cpp +++ b/native/src/bindings.cpp @@ -596,7 +596,8 @@ void bind_problem(nb::module_& module_) { "collections.abc.Mapping[str, object] | None"); bind_setup(problem, "adams", &native::Setup::adams, "collections.abc.Mapping[str, object] | None"); - bind_setup(problem, "low_storage", &native::Setup::low_storage, "object | None"); + bind_setup(problem, "low_storage", &native::Setup::low_storage, + "solprop.backends.records.LowStorageSettings | None"); bind_setup(problem, "occupancy", &native::Setup::occupancy, "collections.abc.Mapping[str, object] | None"); bind_setup(problem, "crossing_workers", &native::Setup::crossing_workers, "int"); @@ -1183,8 +1184,8 @@ class ScriptedRkMarch { public: ScriptedRkMarch(const nb::object& policy, const RealInput norms, const double h0, const RealInput steps, const RealInput edges) - : policy_(native::to_native(native::records::read( - policy, "policy"))), + : policy_(native::to_native( + native::records::read(policy, "policy"))), norms_(real_vector(norms)), h0_(h0), schedule_{.steps = real_vector(steps), .edges = real_vector(edges)} {} nb::dict run(const nb::dict state_values, const nb::dict bounds_values) { @@ -1286,8 +1287,8 @@ using Ticket = std::pair; namespace solprop_native { -// An export's conversion (`solprop.backends.export.ExportRecipe`) with the route's power -// weight at the ticket's position, none unless `power`. +// An export's conversion (`solprop.backends.export.ExportRecipe`) with the route's +// power weight at the ticket's position, none unless `power`. struct ExportRecipe { bool power = false; bool optics = false; @@ -1334,8 +1335,9 @@ class BoundSession { // Takes the session's lock: bound with the interpreter lock released. void acknowledge(const std::uint64_t sequence) { session().acknowledge(sequence); } // Fill `out` with the pending ticket's field, converted by `recipe` natively. - void export_field(const Ticket ticket, const nb::handle recipe, - nb::ndarray, nb::c_contig, nb::device::cpu> out) { + void + export_field(const Ticket ticket, const nb::handle recipe, + nb::ndarray, nb::c_contig, nb::device::cpu> out) { const auto held = native::records::read(recipe, "recipe"); const std::size_t n = session().elements(); if (out.size() != n) @@ -1373,7 +1375,8 @@ class BoundSession { // (None without one) and the quadrature peak, drained since the last read. nb::dict records() { std::optional monitor; - std::optional> edge; + std::optional> + edge; std::optional cap; double peak = 0.0; { @@ -1385,8 +1388,8 @@ class BoundSession { } nb::dict out; out["monitor"] = monitor ? nb::object(watch_record_to(*monitor)) : nb::none(); - out["edge"] = edge ? nb::object(native::bindings::transverse_record_to(edge->first, - edge->second)) + out["edge"] = edge ? nb::object(native::bindings::transverse_record_to( + edge->first, edge->second)) : nb::none(); out["cap"] = cap ? nb::object(nb::float_(*cap)) : nb::none(); out["quadrature_peak"] = peak; @@ -2221,10 +2224,12 @@ class TestState { const std::span destination) const { open_state().stage_to_host(stage, destination); } - [[nodiscard]] std::vector projected_to_host(const bool coarse) const { + [[nodiscard]] std::vector + projected_to_host(const bool coarse) const { return open_state().projected_to_host(coarse); } - [[nodiscard]] std::vector weighted_error(const std::vector& scale) const { + [[nodiscard]] std::vector + weighted_error(const std::vector& scale) const { return open_state().weighted_error(scale); } std::vector form_flow_actions(const std::size_t section, const double dz, @@ -2233,7 +2238,8 @@ class TestState { workspace_->forget_flow_key(); return state.form_flow_actions(section, dz, fractions); } - [[nodiscard]] std::vector flow_actions_to_host(const bool inverse) const { + [[nodiscard]] std::vector + flow_actions_to_host(const bool inverse) const { return open_state().flow_actions_to_host(inverse); } [[nodiscard]] std::vector adams_block_to_host() const { @@ -2242,7 +2248,8 @@ class TestState { [[nodiscard]] std::vector adams_exponent_to_host() const { return open_state().adams_exponent_to_host(); } - [[nodiscard]] native::stage::Trial stage_trial(const double z0, const double z1) const { + [[nodiscard]] native::stage::Trial stage_trial(const double z0, + const double z1) const { return workspace_->stage_trial(z0, z1); } [[nodiscard]] std::vector stage_rate(const double z) const { @@ -2284,8 +2291,9 @@ class TestState { } [[nodiscard]] std::vector statistics(const std::uint64_t flags, const std::vector& windows, - const std::vector& on_axis, const double density, const double taper, - const double preionisation, const double intensity_factor, + const std::vector& on_axis, const double density, + const double taper, const double preionisation, + const double intensity_factor, const std::vector& channel_preionisation, const std::vector& power_weight) const { return open_state().statistics(flags, windows, on_axis, density, taper, @@ -2415,7 +2423,8 @@ nb::object accept_record(native::GeneralState& state) { return engines_module().attr("AcceptRecord")(); const std::vector found(sums->begin() + 1, sums->end()); return engines_module().attr("AcceptRecord")( - "removed"_a = (*sums)[0], "found"_a = nb::cast(real_output(found, 1)).attr("reshape")(-1)); + "removed"_a = (*sums)[0], + "found"_a = nb::cast(real_output(found, 1)).attr("reshape")(-1)); } nb::object boundary_reading(const std::vector& values) { @@ -2464,21 +2473,26 @@ void bind_engines(nb::module_& testing) { const nb::gil_scoped_release release; return engine.trial(z, dz); }) - .def("rk_accept", - [](TestEngines& self, const double dz) { - auto& engine = self.runge_kutta(); - { - const nb::gil_scoped_release release; - engine.accept(dz); - } - return accept_record(self.state()); - }) + .def( + "rk_accept", + [](TestEngines& self, const double dz) -> nb::object { + auto& engine = self.runge_kutta(); + { + const nb::gil_scoped_release release; + engine.accept(dz); + } + return accept_record(self.state()); + }, + nb::sig("def rk_accept(self, dz: float) -> " + "solprop.backends.engines.AcceptRecord")) .def("rk_extend", [](TestEngines& self, const double z, const double dz) { self.runge_kutta().extend(z, dz); }) - .def("rk_reading", - [](TestEngines& self) { - return boundary_reading(self.runge_kutta().reading()); - }) + .def( + "rk_reading", + [](TestEngines& self) { + return boundary_reading(self.runge_kutta().reading()); + }, + nb::sig("def rk_reading(self) -> solprop.backends.engines.BoundaryReading")) .def_prop_ro("rk_in_flight", [](TestEngines& self) { return self.runge_kutta().in_flight(); }) // The Adams protocol (`AdamsEngine`). @@ -2500,21 +2514,25 @@ void bind_engines(nb::module_& testing) { } return real_output(std::move(norms), 1); }) - .def("adams_accept", - [](TestEngines& self, const double dz, const std::size_t free, - const nb::handle held, const nb::handle kept) { - auto& engine = self.adams(); - const auto stencil = stencil_from(held); - std::vector entries; - for (const auto entry : nb::cast(kept)) - entries.push_back( - native::records::read(entry, "kept")); - { - const nb::gil_scoped_release release; - engine.accept(dz, free, stencil, entries); - } - return accept_record(self.state()); - }) + .def( + "adams_accept", + [](TestEngines& self, const double dz, const std::size_t free, + const nb::handle held, const nb::handle kept) { + auto& engine = self.adams(); + const auto stencil = stencil_from(held); + std::vector entries; + for (const auto entry : nb::cast(kept)) + entries.push_back( + native::records::read(entry, "kept")); + { + const nb::gil_scoped_release release; + engine.accept(dz, free, stencil, entries); + } + return accept_record(self.state()); + }, + nb::sig("def adams_accept(self, dz: float, free: int, held: object, kept: " + "collections.abc.Sequence[solprop.backends.engines.HistoryEntry]) " + "-> solprop.backends.engines.AcceptRecord")) .def("adams_chord_phase", [](TestEngines& self, const double z1, const double z2) { return self.adams().chord_phase(z1, z2); @@ -2535,8 +2553,11 @@ void bind_engines(nb::module_& testing) { throw std::invalid_argument("an attempt's outcome is 0, 1 or 2"); self.adams().end_attempt(static_cast(outcome)); }) - .def("adams_reading", - [](TestEngines& self) { return boundary_reading(self.adams().reading()); }); + .def( + "adams_reading", + [](TestEngines& self) { return boundary_reading(self.adams().reading()); }, + nb::sig( + "def adams_reading(self) -> solprop.backends.engines.BoundaryReading")); testing.def( "engines", [](BoundWorkspace& workspace) { @@ -2563,7 +2584,9 @@ void bind_engines(nb::module_& testing) { return real_output(std::move(values), 1); }, "workspace"_a, "plan"_a, "z"_a); - testing.def("round_trip", &round_trip, "name"_a, "value"_a); + testing.def("round_trip", &round_trip, "name"_a, "value"_a, + nb::sig("def round_trip(name: str, value: object) -> dict[str, " + "typing.Any]")); } // The private `_testing` module (solprop SEP 52 section 6.5): every entry point that @@ -2734,7 +2757,9 @@ void bind_testing(nb::module_& testing) { [](native::watch::Monitor* self, const nb::handle config) { new (self) native::watch::Monitor(watch_config_from(config)); }, - "config"_a) + "config"_a, + nb::sig("def __init__(self, config: solprop.backends.records.MonitorConfig) " + "-> None")) .def( "resume", [](native::watch::Monitor& self, const nb::handle record, const bool plane, @@ -2746,7 +2771,11 @@ void bind_testing(nb::module_& testing) { "unwatched"); self.resume(native::to_native(held), plane, stretches); }, - "record"_a, "plane"_a, "unwatched"_a) + "record"_a, "plane"_a, "unwatched"_a, + nb::sig( + "def resume(self, record: solprop.backends.records.Resumption, plane: " + "bool, unwatched: collections.abc.Sequence[tuple[float, float]]) -> " + "None")) .def( "launch", [](native::watch::Monitor& self, const RealInput reading, const double z, @@ -2805,7 +2834,8 @@ void bind_testing(nb::module_& testing) { const RealInput phi_at, const RealInput prefactor, const RealInput density, const RealInput taper, const RealInput preionisation, const RealInput raman_rates, const nb::object material, - const bool prepare_only) { TestState self(owner); + const bool prepare_only) { + TestState self(owner); if (self.raman() && (raman_rates.ndim() != 2 || raman_rates.shape(0) != self.stages() || raman_rates.shape(1) != self.raman_terms())) @@ -2848,7 +2878,8 @@ void bind_testing(nb::module_& testing) { "material"_a = nb::none(), "prepare_only"_a = false); testing.def( "adopt", - [](BoundWorkspace& owner, const ComplexInput field, const double dz) { TestState self(owner); + [](BoundWorkspace& owner, const ComplexInput field, const double dz) { + TestState self(owner); const auto held = complex_vector(field); const nb::gil_scoped_release release; self.adopt(held, dz); @@ -2856,7 +2887,8 @@ void bind_testing(nb::module_& testing) { "workspace"_a, "field"_a.noconvert(), "dz"_a); testing.def( "stage_to_host", - [](BoundWorkspace& owner, const std::size_t stage) { TestState self(owner); + [](BoundWorkspace& owner, const std::size_t stage) { + TestState self(owner); const auto count = self.elements(); auto storage = native::crossing::host_buffer(2 * count); { @@ -2870,7 +2902,8 @@ void bind_testing(nb::module_& testing) { "workspace"_a, "stage"_a); testing.def( "projected_to_host", - [](BoundWorkspace& owner, const bool coarse) { TestState self(owner); + [](BoundWorkspace& owner, const bool coarse) { + TestState self(owner); std::vector values; { const nb::gil_scoped_release release; @@ -2881,7 +2914,8 @@ void bind_testing(nb::module_& testing) { "workspace"_a, "coarse"_a = false); testing.def( "weighted_error", - [](BoundWorkspace& owner, const RealInput scale) { TestState self(owner); + [](BoundWorkspace& owner, const RealInput scale) { + TestState self(owner); std::vector partials; const auto held_scale = real_vector(scale); { @@ -2894,7 +2928,8 @@ void bind_testing(nb::module_& testing) { testing.def( "form_flow_actions", [](BoundWorkspace& owner, const std::size_t section, const double dz, - const RealInput fractions) { TestState self(owner); + const RealInput fractions) { + TestState self(owner); const auto held_fractions = real_vector(fractions); std::vector measured; { @@ -2906,7 +2941,8 @@ void bind_testing(nb::module_& testing) { "workspace"_a, "section"_a, "dz"_a, "fractions"_a.noconvert()); testing.def( "flow_actions_to_host", - [](BoundWorkspace& owner, const bool inverse) { TestState self(owner); + [](BoundWorkspace& owner, const bool inverse) { + TestState self(owner); std::vector values; { const nb::gil_scoped_release release; @@ -2919,7 +2955,8 @@ void bind_testing(nb::module_& testing) { // exponent, observations for tests. testing.def( "adams_block_to_host", - [](BoundWorkspace& owner) { TestState self(owner); + [](BoundWorkspace& owner) { + TestState self(owner); std::vector values; { const nb::gil_scoped_release release; @@ -2930,7 +2967,8 @@ void bind_testing(nb::module_& testing) { "workspace"_a); testing.def( "adams_exponent_to_host", - [](BoundWorkspace& owner) { TestState self(owner); + [](BoundWorkspace& owner) { + TestState self(owner); std::vector values; { const nb::gil_scoped_release release; @@ -2952,7 +2990,8 @@ void bind_testing(nb::module_& testing) { const RealInput sample_preionisation, const RealInput sample_raman_rates, const nb::dict sample_material, const RealInput spans, const RealInput comp_predictor, const RealInput comp_corrector, - const RealInput comp_rows, const RealInput rate, const RealInput carrier) { TestState self(owner); + const RealInput comp_rows, const RealInput rate, const RealInput carrier) { + TestState self(owner); auto weights = exponential_weights(slots, predictor, corrector, rows); carrier_frame(weights, carrier, weights.width - 1); const auto rate_weights = real_vector(rate); @@ -3010,7 +3049,8 @@ void bind_testing(nb::module_& testing) { [](BoundWorkspace& owner, const double z, const double dz, const RealInput nodes, const IndexInput slots, const std::size_t order, const std::vector& orders, const bool compensated, - const RealInput carrier) { TestState self(owner); + const RealInput carrier) { + TestState self(owner); auto weights = exponential_weights_at(nodes, slots, order, orders, compensated); carrier_frame(weights, carrier, weights.width - 1); const double end = z + dz; @@ -3024,12 +3064,13 @@ void bind_testing(nb::module_& testing) { } return real_output(std::move(norms), 1); }, - "workspace"_a, "z"_a, "dz"_a, "nodes"_a.noconvert(), "slots"_a.noconvert(), "order"_a, - "orders"_a, "compensated"_a, "carrier"_a.noconvert()); + "workspace"_a, "z"_a, "dz"_a, "nodes"_a.noconvert(), "slots"_a.noconvert(), + "order"_a, "orders"_a, "compensated"_a, "carrier"_a.noconvert()); testing.def( "adams_exponential_accept", [](BoundWorkspace& owner, const double dz, const std::size_t free, - const IndexInput dense, const bool interpolate) { TestState self(owner); + const IndexInput dense, const bool interpolate) { + TestState self(owner); auto slopes = adams_rows(dense); slopes.width = interpolate ? slopes.width + 1 : 0; const nb::gil_scoped_release release; @@ -3041,7 +3082,8 @@ void bind_testing(nb::module_& testing) { [](BoundWorkspace& owner, const std::size_t slot, const RealInput phi_delta, const RealInput phi_at, const RealInput prefactor, const RealInput density, const RealInput taper, const RealInput preionisation, - const RealInput raman_rates, const nb::dict material) { TestState self(owner); + const RealInput raman_rates, const nb::dict material) { + TestState self(owner); const auto scalars = adams_scalars(phi_delta, phi_at, prefactor, density, taper, preionisation, raman_rates, material); const nb::gil_scoped_release release; @@ -3052,21 +3094,31 @@ void bind_testing(nb::module_& testing) { "preionisation"_a.noconvert(), "raman_rates"_a.noconvert(), "material"_a); testing.def( "adams_compensation_start", - [](BoundWorkspace& owner, const std::size_t slot, const RealInput rate) { TestState self(owner); + [](BoundWorkspace& owner, const std::size_t slot, const RealInput rate) { + TestState self(owner); const auto weights = real_vector(rate); const nb::gil_scoped_release release; self.open_state().adams_compensation_start(slot, weights); }, "workspace"_a, "slot"_a, "rate"_a.noconvert()); testing.def( - "adams_hold", [](BoundWorkspace& owner) { TestState self(owner); self.open_state().adams_hold(); }, + "adams_hold", + [](BoundWorkspace& owner) { + TestState self(owner); + self.open_state().adams_hold(); + }, "workspace"_a); testing.def( - "adams_restore", [](BoundWorkspace& owner) { TestState self(owner); self.open_state().adams_restore(); }, + "adams_restore", + [](BoundWorkspace& owner) { + TestState self(owner); + self.open_state().adams_restore(); + }, "workspace"_a); testing.def( "adams_rows_to_host", - [](BoundWorkspace& owner, const std::string& name) { TestState self(owner); + [](BoundWorkspace& owner, const std::string& name) { + TestState self(owner); auto& state = self.open_state(); const auto extents = state.adams_row_extents(name); // The array's own storage is written once, as the host engine's copy is. @@ -3088,7 +3140,8 @@ void bind_testing(nb::module_& testing) { "workspace"_a, "name"_a); testing.def( "adams_stage_scalars", - [](BoundWorkspace& owner, const double z0, const double z1) { TestState self(owner); + [](BoundWorkspace& owner, const double z0, const double z1) { + TestState self(owner); const auto trial = self.stage_trial(z0, z1); const auto& step = trial.step; // The first stage row's values; the test of the native evaluation reads @@ -3114,21 +3167,30 @@ void bind_testing(nb::module_& testing) { "workspace"_a, "z0"_a, "z1"_a); testing.def( "adams_stage_rate", - [](BoundWorkspace& owner, const double z) { TestState self(owner); return self.stage_rate(z); }, "workspace"_a, - "z"_a); + [](BoundWorkspace& owner, const double z) { + TestState self(owner); + return self.stage_rate(z); + }, + "workspace"_a, "z"_a); testing.def( "has_stage_tables", - [](BoundWorkspace& owner) { TestState self(owner); return self.has_stage_tables(); }, "workspace"_a); + [](BoundWorkspace& owner) { + TestState self(owner); + return self.has_stage_tables(); + }, + "workspace"_a); testing.def( "table_rate_at", - [](BoundWorkspace& owner, const double z, const bool before) { TestState self(owner); + [](BoundWorkspace& owner, const double z, const bool before) { + TestState self(owner); const nb::gil_scoped_release release; self.table_rate_at(z, before); }, "workspace"_a, "z"_a, "before"_a); testing.def( "phase_sum_to_host", - [](BoundWorkspace& owner, const RealInput weights) { TestState self(owner); + [](BoundWorkspace& owner, const RealInput weights) { + TestState self(owner); const auto held = real_vector(weights); auto& state = self.open_state(); std::vector values; @@ -3139,16 +3201,24 @@ void bind_testing(nb::module_& testing) { return complex_output(values, {self.columns(), values.size() / self.columns()}); }, "workspace"_a, "weights"_a.noconvert()); - testing.def("promote_fsal", [](BoundWorkspace& owner) { TestState self(owner); self.promote_fsal(); }, "workspace"_a); + testing.def( + "promote_fsal", + [](BoundWorkspace& owner) { + TestState self(owner); + self.promote_fsal(); + }, + "workspace"_a); testing.def( "adams_march_run", - [](BoundWorkspace& owner, const nb::dict march, const nb::dict bounds) { TestState self(owner); + [](BoundWorkspace& owner, const nb::dict march, const nb::dict bounds) { + TestState self(owner); return self.march_run(march, bounds); }, "workspace"_a, "march"_a, "bounds"_a); testing.def( "rk_march_run", - [](BoundWorkspace& owner, const nb::dict march, const nb::dict bounds) { TestState self(owner); + [](BoundWorkspace& owner, const nb::dict march, const nb::dict bounds) { + TestState self(owner); return self.rk_march_run(march, bounds); }, "workspace"_a, "march"_a, "bounds"_a); @@ -3169,7 +3239,9 @@ void bind_testing(nb::module_& testing) { owner.workspace().configure_march( native::records::read(records, "records")); }, - "workspace"_a, "records"_a); + "workspace"_a, "records"_a, + nb::sig("def configure_march(workspace: solprop_native._core.Workspace, " + "records: solprop.backends.records.RunRecords) -> None")); // Load a start into the state as a run would, for the tests that step it directly. testing.def( "load", @@ -3188,7 +3260,8 @@ void bind_testing(nb::module_& testing) { auto storage = native::crossing::host_buffer(2 * count); { const nb::gil_scoped_release release; - state.field_to_host({reinterpret_cast(storage.get()), count}); + state.field_to_host( + {reinterpret_cast(storage.get()), count}); } return complex_buffer_output(std::move(storage), {self.columns(), count / self.columns()}); @@ -3213,7 +3286,8 @@ void bind_testing(nb::module_& testing) { }, "workspace"_a, "quiet"_a); // A Runge-Kutta trial on the stage tables at the setup's nodes, as the march takes - // it (solprop SEP 45 phase 2): its partials `(3, slots)`, its stages kept in the state. + // it (solprop SEP 45 phase 2): its partials `(3, slots)`, its stages kept in the + // state. testing.def( "rk_trial", [](BoundWorkspace& owner, const double z, const double dz) { @@ -3250,7 +3324,8 @@ void bind_testing(nb::module_& testing) { auto& slots = workspace.z_slots(); if (!slots.present()) throw std::logic_error("no z table's slots were configured"); - const auto known = native::names(static_cast(nullptr)); + const auto known = + native::names(static_cast(nullptr)); const auto found = std::ranges::find_if( known, [&kind](const auto& entry) { return kind == entry.first; }); if (found == known.end()) @@ -3261,8 +3336,8 @@ void bind_testing(nb::module_& testing) { const std::size_t slot = slots.load(state, {z}).front(); values = state.table_terms_to_host(found->second, slot); } - return complex_output(values, - {workspace.columns(), values.size() / workspace.columns()}); + return complex_output( + values, {workspace.columns(), values.size() / workspace.columns()}); }, "workspace"_a, "kind"_a, "z"_a); // The slot each position's z-table value is held in, evaluating only those no slot @@ -3372,9 +3447,8 @@ void bind_testing(nb::module_& testing) { native::records::read(monitor, "monitor"); const auto tables = native::records::read>(edge, "edge"); - const auto buckets = - native::records::read>(occupancy, - "occupancy"); + const auto buckets = native::records::read>( + occupancy, "occupancy"); auto& state = owner.workspace().state(); // Holding the interpreter lock: a strip's plan goes through FFTW's planner. state.bind_monitor(weights.weights, weights.column_weights); @@ -3387,7 +3461,11 @@ void bind_testing(nb::module_& testing) { state.bind_edge_lines(*tables->lines); } }, - "workspace"_a, "monitor"_a, "edge"_a.none(), "occupancy"_a.none()); + "workspace"_a, "monitor"_a, "edge"_a.none(), "occupancy"_a.none(), + nb::sig("def bind_monitor(workspace: solprop_native._core.Workspace, monitor: " + "collections.abc.Mapping[str, object], edge: " + "collections.abc.Mapping[str, object] | None, occupancy: " + "collections.abc.Mapping[str, object] | None) -> None")); testing.def( "edge_reading", [](BoundWorkspace& owner, const bool faces, const bool whole, const bool totals, @@ -3409,7 +3487,8 @@ void bind_testing(nb::module_& testing) { [](BoundWorkspace& owner, const std::uint64_t flags, const RealInput windows, const RealInput on_axis, const double density, const double taper, const double preionisation, const double intensity_factor, - const nb::object channel_preionisation, const nb::object power_weight) { TestState self(owner); + const nb::object channel_preionisation, const nb::object power_weight) { + TestState self(owner); const auto held_weight = power_weight.is_none() ? std::vector{} : real_vector(exact_array(power_weight)); @@ -3433,8 +3512,9 @@ void bind_testing(nb::module_& testing) { "channel_preionisation"_a = nb::none(), "power_weight"_a = nb::none()); testing.def( "spatial_statistics", - [](BoundWorkspace& owner, const std::uint64_t flags, const double intensity_factor, - const double z) { TestState self(owner); + [](BoundWorkspace& owner, const std::uint64_t flags, + const double intensity_factor, const double z) { + TestState self(owner); std::vector values; { const nb::gil_scoped_release release; @@ -3445,7 +3525,8 @@ void bind_testing(nb::module_& testing) { "workspace"_a, "flags"_a, "intensity_factor"_a, "z"_a); testing.def( "planned_statistics", - [](BoundWorkspace& owner, const BoundStatisticsPlan& plan, const double z) { TestState self(owner); + [](BoundWorkspace& owner, const BoundStatisticsPlan& plan, const double z) { + TestState self(owner); const auto& held = plan.plan(); std::vector values; { @@ -3459,7 +3540,8 @@ void bind_testing(nb::module_& testing) { "plane_fluence_trace", [](BoundWorkspace& owner, const double center_x, const double center_y, const double dx, const double dy, const double extent, const double spacing, - const std::size_t n_radii, const RealInput cosines, const RealInput sines) { TestState self(owner); + const std::size_t n_radii, const RealInput cosines, const RealInput sines) { + TestState self(owner); if (cosines.ndim() != 1 || sines.ndim() != 1) throw std::invalid_argument("fluence rings must be one-dimensional"); const auto held_cosines = real_vector(cosines); @@ -3472,11 +3554,12 @@ void bind_testing(nb::module_& testing) { } return real_output(std::move(values), 1); }, - "workspace"_a, "center_x"_a, "center_y"_a, "dx"_a, "dy"_a, "extent"_a, "spacing"_a, - "n_radii"_a, "cosines"_a.noconvert(), "sines"_a.noconvert()); + "workspace"_a, "center_x"_a, "center_y"_a, "dx"_a, "dy"_a, "extent"_a, + "spacing"_a, "n_radii"_a, "cosines"_a.noconvert(), "sines"_a.noconvert()); testing.def( "axis_spectrum", - [](BoundWorkspace& owner, const RealInput matrix) { TestState self(owner); + [](BoundWorkspace& owner, const RealInput matrix) { + TestState self(owner); if (matrix.ndim() != 2) throw std::invalid_argument("an on-axis matrix must be two-dimensional"); const auto held = real_vector(matrix); @@ -3490,7 +3573,8 @@ void bind_testing(nb::module_& testing) { "workspace"_a, "matrix"_a.noconvert()); testing.def( "monitor_reading", - [](BoundWorkspace& owner) { TestState self(owner); + [](BoundWorkspace& owner) { + TestState self(owner); std::vector values; { const nb::gil_scoped_release release; @@ -3500,7 +3584,11 @@ void bind_testing(nb::module_& testing) { }, "workspace"_a); testing.def( - "quadrature_error", [](BoundWorkspace& owner) { TestState self(owner); return self.quadrature_error(); }, + "quadrature_error", + [](BoundWorkspace& owner) { + TestState self(owner); + return self.quadrature_error(); + }, "workspace"_a); } @@ -3514,23 +3602,26 @@ NB_MODULE(_core, module_) { const nb::exception backend_refusal(module_, "BackendRefusal"); module_.doc() = "Private nanobind seam for solprop-native"; - module_.def("available_device_memory", []() -> nb::object { + module_.def( + "available_device_memory", + []() -> nb::object { #ifdef KOKKOS_ENABLE_CUDA - std::size_t free_bytes = 0; - std::size_t total_bytes = 0; - if (cudaMemGetInfo(&free_bytes, &total_bytes) != cudaSuccess) - throw std::runtime_error("cannot query CUDA free memory"); - return nb::int_(free_bytes); + std::size_t free_bytes = 0; + std::size_t total_bytes = 0; + if (cudaMemGetInfo(&free_bytes, &total_bytes) != cudaSuccess) + throw std::runtime_error("cannot query CUDA free memory"); + return nb::int_(free_bytes); #elif defined(KOKKOS_ENABLE_HIP) - std::size_t free_bytes = 0; - std::size_t total_bytes = 0; - if (hipMemGetInfo(&free_bytes, &total_bytes) != hipSuccess) - throw std::runtime_error("cannot query HIP free memory"); - return nb::int_(free_bytes); + std::size_t free_bytes = 0; + std::size_t total_bytes = 0; + if (hipMemGetInfo(&free_bytes, &total_bytes) != hipSuccess) + throw std::runtime_error("cannot query HIP free memory"); + return nb::int_(free_bytes); #else - return nb::none(); + return nb::none(); #endif - }); + }, + nb::sig("def available_device_memory() -> int | None")); // solprop issue #595: a captured plan's execution alone, against estimate's. module_.def( "time_fft_plan", @@ -3555,14 +3646,17 @@ NB_MODULE(_core, module_) { // FFTW's wisdom as text, for the plan store the adapter owns // (solprop_native._wisdom). None where there is none to keep: a device build, // which plans with the device FFT, or a provider without FFTW's wisdom. - module_.def("export_fftw_wisdom", []() -> nb::object { + module_.def( + "export_fftw_wisdom", + []() -> nb::object { #if defined(KOKKOS_ENABLE_CUDA) || defined(KOKKOS_ENABLE_HIP) - return nb::none(); + return nb::none(); #else - std::string text = native::export_fftw_wisdom(); - return text.empty() ? nb::none() : nb::cast(std::move(text)); + std::string text = native::export_fftw_wisdom(); + return text.empty() ? nb::none() : nb::cast(std::move(text)); #endif - }); + }, + nb::sig("def export_fftw_wisdom() -> str | None")); bind_problem(module_); // solprop SEP 47: the native execution session and its compact event records. const nb::exception lifecycle_error( @@ -3643,11 +3737,21 @@ NB_MODULE(_core, module_) { nb::class_(module_, "SessionBatch") .def_ro("sequence", &BatchRecord::sequence) .def_ro("event", &BatchRecord::event) - .def_ro("attempts", &BatchRecord::attempts) - .def_ro("row_z", &BatchRecord::row_z) - .def_ro("row_step", &BatchRecord::row_step) - .def_ro("row_values", &BatchRecord::row_values) - .def_ro("plane_stats", &BatchRecord::plane_stats); + .def_ro("attempts", &BatchRecord::attempts, + nb::for_getter( + nb::sig("def attempts(self) -> numpy.typing.NDArray[numpy.float64]"))) + .def_ro("row_z", &BatchRecord::row_z, + nb::for_getter( + nb::sig("def row_z(self) -> numpy.typing.NDArray[numpy.float64]"))) + .def_ro("row_step", &BatchRecord::row_step, + nb::for_getter( + nb::sig("def row_step(self) -> numpy.typing.NDArray[numpy.int64]"))) + .def_ro("row_values", &BatchRecord::row_values, + nb::for_getter(nb::sig( + "def row_values(self) -> numpy.typing.NDArray[numpy.float64]"))) + .def_ro("plane_stats", &BatchRecord::plane_stats, + nb::for_getter(nb::sig( + "def plane_stats(self) -> numpy.typing.NDArray[numpy.float64]"))); nb::class_(module_, "SessionStatus") .def_ro("z", &native::session::Status::z) .def_ro("plane_index", &native::session::Status::plane_index) @@ -3676,15 +3780,24 @@ NB_MODULE(_core, module_) { nb::call_guard()) .def("request_snapshot", &BoundSession::request_snapshot) .def("status", &BoundSession::status) - .def("march_state", &BoundSession::march_state, "since"_a) + .def("march_state", &BoundSession::march_state, "since"_a, + nb::sig("def march_state(self, since: int) -> dict[str, typing.Any] | None")) .def("fail_outside", &BoundSession::fail_outside) // solprop SEP 52 section 5.3: a ticket is `(sequence, generation)`; a recipe is // `{"power", "optics", "weight"}`. - .def("export", &BoundSession::export_field, "ticket"_a, "recipe"_a, "out"_a) - .def("snapshot", &BoundSession::snapshot, "ticket"_a) + .def("export", &BoundSession::export_field, "ticket"_a, "recipe"_a, "out"_a, + nb::sig("def export(self, ticket: tuple[int, int], recipe: " + "collections.abc.Mapping[str, object], out: " + "numpy.typing.NDArray[numpy.complex128]) -> None")) + .def("snapshot", &BoundSession::snapshot, "ticket"_a, + nb::sig("def snapshot(self, ticket: tuple[int, int]) -> tuple[dict[str, " + "typing.Any], numpy.typing.NDArray[numpy.complex128], dict[str, " + "numpy.typing.NDArray[numpy.complex128]]] | None")) .def("noise_phase", &BoundSession::noise_phase, "ticket"_a, "z"_a) .def("records", &BoundSession::records) - .def("continue_monitor", &BoundSession::continue_monitor, "continuation"_a) + .def("continue_monitor", &BoundSession::continue_monitor, "continuation"_a, + nb::sig("def continue_monitor(self, continuation: " + "solprop.backends.records.MonitorContinuation) -> None")) .def("close", &BoundSession::close, nb::call_guard()); // solprop SEP 52 section 5.3: the new seam -- one workspace a problem, one run record // a start, the probe, and the tables every record is read by. @@ -3700,13 +3813,19 @@ NB_MODULE(_core, module_) { nb::class_(module_, "Workspace") .def(nb::init(), "problem"_a) .def("start", &BoundWorkspace::start, "run"_a, - "host_source"_a.none() = nb::none(), nb::keep_alive<0, 1>()) + "host_source"_a.none() = nb::none(), nb::keep_alive<0, 1>(), + nb::sig("def start(self, run: collections.abc.Mapping[str, object], " + "host_source: object | None = None) -> Session")) .def("probe", &BoundWorkspace::probe, "start"_a, - "host_source"_a.none() = nb::none(), nb::keep_alive<0, 1>()) + "host_source"_a.none() = nb::none(), nb::keep_alive<0, 1>(), + nb::sig("def probe(self, start: collections.abc.Mapping[str, object], " + "host_source: object | None = None) -> Probe")) .def("diagnostics", &BoundWorkspace::diagnostics) .def_prop_ro("closed", &BoundWorkspace::closed) .def("close", &BoundWorkspace::close_from_python); - module_.def("configure_runtime", &configure_runtime, "record"_a); + module_.def("configure_runtime", &configure_runtime, "record"_a, + nb::sig("def configure_runtime(record: collections.abc.Mapping[str, " + "object]) -> dict[str, str]")); module_.def("schemas", &schemas); auto testing = module_.def_submodule("_testing", "Private entry points for solprop's own tests"); diff --git a/native/src/solprop_native/_core.pyi b/native/src/solprop_native/_core.pyi index 24d1ab960..7b29de3d6 100644 --- a/native/src/solprop_native/_core.pyi +++ b/native/src/solprop_native/_core.pyi @@ -2,6 +2,8 @@ # # SPDX-License-Identifier: GPL-3.0-or-later +# Generated by native/scripts/problem_stub.py from nanobind.stubgen: do not edit. + from __future__ import annotations import enum @@ -10,16 +12,20 @@ from typing import Any, overload import numpy as np import numpy.typing as npt +import solprop.backends.records -# The private test module, bound as the submodule `_testing` (solprop SEP 52), has its -# own hand-written stub; the extension has no `_core_testing` attribute. +# The private test module, bound as the submodule `_testing` (solprop SEP 52): +# its stub is `_core_testing.pyi`; the extension has no `_core_testing`. from solprop_native import _core_testing _testing = _core_testing -# Generated by native/scripts/problem_stub.py from nanobind.stubgen. -# Array fields are copied in and out: assign a whole array, since an item -# assigned through a read copy changes nothing. +class BackendRefusal(Exception): + pass + +class EnvelopeConvergenceError(Exception): + pass + class FieldFamily(enum.Enum): field_real = 0 @@ -27,486 +33,488 @@ class FieldFamily(enum.Enum): envelope = 2 +class Probe: + def trial(self, z: float, dz: float) -> float: ... + def field(self) -> npt.NDArray[np.complex128]: ... + @property + def trials(self) -> int: ... + @property + def evaluations(self) -> int: ... + @property + def low_storage(self) -> bool: ... + @property + def z(self) -> float: ... + @property + def closed(self) -> bool: ... + def close(self) -> None: ... + class Problem: def __init__(self) -> None: ... + class Dims: def __init__(self) -> None: ... + n_omega: int + n_t: int + n_to: int + n_modes: int + n_pol_state: int + n_pol_transform: int + n_nodes: int + node_chunk: int + family: FieldFamily class Grid: def __init__(self) -> None: ... + crop_index: npt.NDArray[np.uint64] + active_mask: npt.NDArray[np.bool_] + norm_mask: npt.NDArray[np.bool_] + omega_window: npt.NDArray[np.float64] + omega: npt.NDArray[np.float64] + power_weight: npt.NDArray[np.float64] + time_window: npt.NDArray[np.float64] + time_window_derivative: npt.NDArray[np.float64] + carrier: npt.NDArray[np.complex128] + dt_fine: float + dt: float class Spatial: def __init__(self) -> None: ... + n_x: int + n_y: int + k_squared: npt.NDArray[np.complex128] + k_squared_low: npt.NDArray[np.complex128] + numerator: npt.NDArray[np.complex128] + clamped: npt.NDArray[np.complex128] + kperp_sq: npt.NDArray[np.float64] + kperp_sq_low: npt.NDArray[np.float64] + frame: npt.NDArray[np.float64] + spectral_rate: npt.NDArray[np.float64] + user_rate: npt.NDArray[np.float64] + absorber_rate: npt.NDArray[np.float64] + kperp_rate: npt.NDArray[np.float64] + evanescent_rate: float + k_x: npt.NDArray[np.float64] + k_y: npt.NDArray[np.float64] + far_field_slots: int + n_p: int + kappa_sq: npt.NDArray[np.complex128] + absorber_matrix: npt.NDArray[np.float64] + spectral_weights: npt.NDArray[np.float64] + on_axis: npt.NDArray[np.complex128] class Flux: def __init__(self) -> None: ... + k_squared: npt.NDArray[np.complex128] + k_squared_low: npt.NDArray[np.complex128] + kperp_sq: npt.NDArray[np.float64] + kperp_sq_low: npt.NDArray[np.float64] + table: bool + closure: bool class Stepper: def __init__(self) -> None: ... + n_stages: int + tableau_matrix: npt.NDArray[np.float64] + tableau_nodes: npt.NDArray[np.float64] + solution_weights: npt.NDArray[np.float64] + error_weights: npt.NDArray[np.float64] + first_same_as_last: bool + weighted_controller: bool + modified_noise: bool + low_storage: bool + low_storage_stage_register: bool + low_storage_flows: int + low_storage_tiled_input: bool class Linear: def __init__(self) -> None: ... + n_phi_terms: int + n_prefactor_terms: int + phi_table: bool + prefactor_table: bool + phi_terms: npt.NDArray[np.complex128] + prefactor_terms: npt.NDArray[np.complex128] class Absorber: def __init__(self) -> None: ... + in_stage: bool + split_step: bool + fine: npt.NDArray[np.float64] + coarse: npt.NDArray[np.float64] class Transform: def __init__(self) -> None: ... + synthesis_matrix: npt.NDArray[np.float64] + projection_matrix: npt.NDArray[np.float64] + projection_coarse_matrix: npt.NDArray[np.float64] + synthesis: float + projection: float class Kerr: def __init__(self) -> None: ... + nonlinear: bool + coefficient: float + self_factor: float + conjugate_factor: float + harmonic_factor: float + take_real: bool class Plasma: def __init__(self) -> None: ... + enabled: bool + envelope: bool + gated: bool + stash: bool + envelope_rule_nodes: npt.NDArray[np.float64] + envelope_rule_weights: npt.NDArray[np.float64] + envelope_drude_factor: npt.NDArray[np.float64] + envelope_loss_factor: npt.NDArray[np.complex128] + charge_mass_ratio: float + ionisation_potential: float + log_field_min: float + d_log_field: float + field_min: float + field_max: float + rate_max: float + rate_intervals: int + rate_coefficients: npt.NDArray[np.float64] + n_channels: int + band: bool + taps: npt.NDArray[np.float64] + channel_parameters: npt.NDArray[np.float64] + channel_coefficients: npt.NDArray[np.float64] class Raman: def __init__(self) -> None: ... + enabled: bool + thg: bool + tensor_capable: bool + n_terms: int + fraction: float + epsilon0: float + undamped: npt.NDArray[np.float64] + tensor_weights: npt.NDArray[np.float64] + n_components: int + row_component: npt.NDArray[np.float64] + component_fraction: npt.NDArray[np.float64] class General: def __init__(self) -> None: ... + enabled: bool + real_form: bool + map_intervals: int + map_n_deg: int + components: int + nodes: int + node_chunk: int + responses: int + terms: int + pad_scale: float + epsilon0: float + synthesis: npt.NDArray[np.complex128] + projection: npt.NDArray[np.complex128] + frequency_factor: npt.NDArray[np.complex128] + delayed_spectrum: npt.NDArray[np.complex128] + tensor: npt.NDArray[np.float64] + delayed_tensor: npt.NDArray[np.float64] + node_response: npt.NDArray[np.uint64] class Flow: def __init__(self) -> None: ... + enabled: bool + active: int + sections: int + terms: int + slot: npt.NDArray[np.uint64] + frozen: npt.NDArray[np.complex128] + residual_terms: npt.NDArray[np.complex128] + left: npt.NDArray[np.complex128] + right: npt.NDArray[np.complex128] + eigenvalues: npt.NDArray[np.complex128] + route: npt.NDArray[np.uint64] + fallback_vectors: npt.NDArray[np.complex128] + fallback_triangular: npt.NDArray[np.complex128] class Dispersive: def __init__(self) -> None: ... + enabled: bool + symmetric: bool + form: int + inputs: npt.NDArray[np.float64] + term_multipliers: npt.NDArray[np.float64] + coefficients: npt.NDArray[np.float64] + pair_constants: npt.NDArray[np.float64] + quartics: npt.NDArray[np.float64] + input_scale: npt.NDArray[np.float64] + output_scale: npt.NDArray[np.float64] + term_rows: npt.NDArray[np.uint64] + term_channels: npt.NDArray[np.uint64] + group_offsets: npt.NDArray[np.uint64] + group_members: npt.NDArray[np.uint64] + group_keys: npt.NDArray[np.uint64] + node_region: npt.NDArray[np.uint64] stage_tables: Mapping[str, object] | None + z_slots: Mapping[str, object] | None + z_tables: Sequence[Mapping[str, object]] + flow_guard: Mapping[str, object] | None + runge_kutta: Mapping[str, object] | None + adams: Mapping[str, object] | None - low_storage: object | None - monitor: Mapping[str, object] | None - edge: Mapping[str, object] | None + + low_storage: solprop.backends.records.LowStorageSettings | None + + occupancy: Mapping[str, object] | None + + crossing_workers: int + dims: Problem.Dims + grid: Problem.Grid + spatial: Problem.Spatial + flux: Problem.Flux + stepper: Problem.Stepper + linear: Problem.Linear + absorber: Problem.Absorber + transform: Problem.Transform + kerr: Problem.Kerr + plasma: Problem.Plasma + raman: Problem.Raman + general: Problem.General + flow: Problem.Flow + dispersive: Problem.Dispersive + cpu_execution: dict[str, int | bool] + fft_planning: dict[str, object] def validate(self) -> None: ... -# End of the generated problem stub. - -class State: - # The problem is `backend._lower` of a validated - # `solprop.translate.problem.PropagationProblem`: its shared grid, operator, - # response and source components, with the route variant the adapter visited - # (solprop SEP 47 section 6.2); `n_modes` and `n_pol_state` are the state's - # `(n_modes, n_pol, n_omega)`. `set_initial` takes, and `field_to_host` and the - # Adams rows return, that layout as contiguous elements, which the adapter - # reshapes. - def __init__(self, problem: Problem) -> None: ... - def set_initial( - self, - field: npt.NDArray[np.complex128], - noise: npt.NDArray[np.complex128], - ) -> None: ... - def rk_trial( - self, z: float, dz: float, nodes: list[float], prepare_only: bool = False - ) -> npt.NDArray[np.float64]: ... - def prepare_raman( - self, - rates: npt.NDArray[np.float64], - densities: npt.NDArray[np.float64] | None = None, - ) -> None: ... - def aperture_statistics( - self, - flags: int, - apertures: npt.NDArray[np.float64], - exponent: int, - regions: npt.NDArray[np.float64], - intensity_factor: float, - ) -> npt.NDArray[np.float64]: ... - def low_storage_step( - self, - dz: float, - phi_delta: npt.NDArray[np.float64], - phi_at: npt.NDArray[np.float64], - prefactor: npt.NDArray[np.float64], - density: npt.NDArray[np.float64], - taper: npt.NDArray[np.float64], - preionisation: npt.NDArray[np.float64], - raman_rates: npt.NDArray[np.float64], - material: dict[str, npt.NDArray[np.float64] | int], - rebuild_table: bool, - ) -> float: ... - def adams_allocate( - self, slots: int, compensated: bool = False, interpolate: bool = True - ) -> None: ... - def adams_scale( - self, rtol: float, atol: float, weights: npt.NDArray[np.float64] - ) -> None: ... - def adams_stage_tables(self, tables: dict[str, object]) -> None: ... - def adams_march_configure( - self, - policy: dict[str, object], - fused: bool, - compensated: bool, - interpolate: bool, - steps: npt.NDArray[np.float64], - edges: npt.NDArray[np.float64], - ) -> None: ... - def bind_host_source(self, owner: object | None) -> None: ... - def rk_march_configure( - self, - policy: dict[str, object], - nodes: list[float], - rtol: float, - atol: float, - steps: npt.NDArray[np.float64], - edges: npt.NDArray[np.float64], - ) -> None: ... - def low_storage_configure( - self, flows: int, separable: bool, origin: float - ) -> None: ... - def start_session( - self, kind: str, state: dict[str, object], plan: dict[str, object], z: float - ) -> Session: ... - def rk_weights_configure(self, weights: list[float]) -> None: ... - def rk_weighted_score( - self, partials: npt.NDArray[np.float64], rtol: float, atol: float - ) -> float: ... - def flow_guard_configure( - self, - row_sum: list[float], - condition_bound: list[float], - taylor_scale: float, - max_squarings: int, - allowance: float, - ) -> None: ... - def adams_row_names(self) -> list[str]: ... - def adams_rows_from_host( - self, name: str, rows: npt.NDArray[np.complex128] - ) -> None: ... - def table_upload( +class Session: + def advance(self, work_limit: int, deadline: float) -> SessionBatch: ... + def acknowledge(self, sequence: int) -> None: ... + def request_stop(self) -> None: ... + def request_snapshot(self) -> tuple[Any, ...]: ... + def status(self) -> SessionStatus: ... + def march_state(self, since: int) -> dict[str, Any] | None: ... + def fail_outside(self) -> SessionBatch | None: ... + def export( self, - kind: str, - edges: npt.NDArray[np.float64], - lower: float, - upper: float, - coefficients: npt.NDArray[np.complex128], - ) -> None: ... - def table_slots( - self, phi: bool, prefactor: bool, slots: int, rate: bool + ticket: tuple[int, int], + recipe: Mapping[str, object], + out: npt.NDArray[np.complex128], ) -> None: ... - def table_load(self, positions: list[float]) -> list[int]: ... - def table_evaluations(self) -> int: ... - def table_terms_to_host( - self, kind: str, slot: int + def snapshot( + self, ticket: tuple[int, int] + ) -> ( + tuple[ + dict[str, Any], + npt.NDArray[np.complex128], + dict[str, npt.NDArray[np.complex128]], + ] + | None + ): ... + def noise_phase( + self, ticket: tuple[int, int], z: float ) -> npt.NDArray[np.complex128]: ... - def finish(self, dz: float) -> None: ... - def clear_fsal(self) -> None: ... - def set_absorber_quiet(self, quiet: bool) -> None: ... - def bind_monitor( - self, - weights: npt.NDArray[np.float64], - column_weights: npt.NDArray[np.float64], - ) -> None: ... - def unbind_monitor(self) -> None: ... - def bind_occupancy(self, buckets: npt.NDArray[np.uint8], count: int) -> None: ... - def field_to_host(self) -> npt.NDArray[np.complex128]: ... - def bind_edge( - self, - faces: npt.NDArray[np.float64], - clip: npt.NDArray[np.float64], - totals: npt.NDArray[np.float64], - synthesis: npt.NDArray[np.float64], - first_row: int, - ) -> None: ... - def crossed_bytes(self) -> tuple[int, int]: ... - def bind_edge_lines( - self, - axes: npt.NDArray[np.uint64], - counts: npt.NDArray[np.uint64], - positions: npt.NDArray[np.uint64], - windows: npt.NDArray[np.float64], - inward: npt.NDArray[np.uint64], - factors: npt.NDArray[np.float64], - measures: npt.NDArray[np.float64], - onsets: npt.NDArray[np.uint64], - steps: npt.NDArray[np.float64], - k_min: float, - scale: npt.NDArray[np.float64], - batch_bytes: int, + def records(self) -> dict[str, Any]: ... + def continue_monitor( + self, continuation: solprop.backends.records.MonitorContinuation ) -> None: ... - def edge_reading( - self, faces: bool, whole: bool, totals: bool, strip: bool, current: bool - ) -> tuple[ - npt.NDArray[np.float64], npt.NDArray[np.float64], npt.NDArray[np.float64], float - ]: ... - def set_crossing_workers(self, workers: int) -> None: ... - @property - def dispersive_path(self) -> dict[str, bool]: ... - def memory_ledger(self) -> dict[str, int]: ... - @property - def planning_seconds(self) -> float: ... - @property - def raman_planning_seconds(self) -> float: ... - @property - def raman_fft_provider(self) -> str: ... - @property - def raman_fft_tasks(self) -> dict[str, int]: ... - @property - def execution_sizing(self) -> dict[str, dict[str, int]]: ... - @property - def cpu_execution(self) -> dict[str, int | bool]: ... - @property - def fft_planning(self) -> dict[str, object]: ... - @property - def raman_kernel_transforms(self) -> int: ... - @property - def fsal_ready(self) -> bool: ... + def close(self) -> None: ... + +class SessionBatch: @property - def rk_source_evaluations(self) -> int: ... + def sequence(self) -> int: ... @property - def axis_scans(self) -> int: ... - def quadrature_peak(self) -> float: ... + def event(self) -> SessionEvent: ... @property - def synthesis_provider(self) -> str: ... + def attempts(self) -> npt.NDArray[np.float64]: ... @property - def projection_provider(self) -> str: ... + def row_z(self) -> npt.NDArray[np.float64]: ... @property - def gemm_shape_policy(self) -> str: ... + def row_step(self) -> npt.NDArray[np.int64]: ... @property - def response_team_size(self) -> int: ... + def row_values(self) -> npt.NDArray[np.float64]: ... @property - def closed(self) -> bool: ... - def close(self) -> None: ... - -def build_record() -> dict[str, str | bool | int | None]: ... -def export_fftw_wisdom() -> str | None: ... -def fit_blas_threads(threads: int) -> str: ... -def register_host_blas() -> None: ... -def rk_score(partials: npt.NDArray[np.float64], rtol: float, atol: float) -> float: ... -def initialize_runtime( - threads: int, - kernels: int = 0, - fft: int = 0, - raman_fft: int = 0, - raman_tail_fft: int = 0, - band_tiles: int = -1, -) -> None: ... -def reference_stream_copies(elements: int, warm: int, repeats: int) -> list[float]: ... -def time_fft_plan(key: str, wisdom: str, effort: str) -> dict[str, float]: ... -def configure_native_spin(milliseconds: int) -> None: ... -@overload -def clenshaw_points( - z: npt.NDArray[np.float64], - edges: npt.NDArray[np.float64], - lower: float, - upper: float, - c: npt.NDArray[np.float64], - out: npt.NDArray[np.float64], -) -> int: ... -@overload -def clenshaw_points( - z: npt.NDArray[np.float64], - edges: npt.NDArray[np.float64], - lower: float, - upper: float, - c: npt.NDArray[np.complex128], - out: npt.NDArray[np.complex128], -) -> int: ... -def basis_rows( - points: npt.NDArray[np.float64], - upper: float, - integrate: bool, - rows: npt.NDArray[np.float64], - weights: npt.NDArray[np.float64], -) -> None: ... -def trial_tables( - nodes: npt.NDArray[np.float64], - order: int, - orders: list[int], - compensated: bool, - predictor: npt.NDArray[np.float64], - corrector: npt.NDArray[np.float64], - factored: npt.NDArray[np.float64], - spans: npt.NDArray[np.float64], - carried: npt.NDArray[np.float64], - endpoint: npt.NDArray[np.float64], - defects: npt.NDArray[np.float64], -) -> None: ... -def available_device_memory() -> int | None: ... - -class EnvelopeConvergenceError(RuntimeError): ... -class BackendRefusal(RuntimeError): ... -class SessionLifecycleError(RuntimeError): ... + def plane_stats(self) -> npt.NDArray[np.float64]: ... class SessionEvent: @property @@ -550,21 +558,8 @@ class SessionEvent: @property def notice(self) -> dict[str, Any]: ... -class SessionBatch: - @property - def sequence(self) -> int: ... - @property - def event(self) -> SessionEvent: ... - @property - def attempts(self) -> npt.NDArray[np.float64]: ... - @property - def row_z(self) -> npt.NDArray[np.float64]: ... - @property - def row_step(self) -> npt.NDArray[np.int64]: ... - @property - def row_values(self) -> npt.NDArray[np.float64]: ... - @property - def plane_stats(self) -> npt.NDArray[np.float64]: ... +class SessionLifecycleError(RuntimeError): + pass class SessionStatus: @property @@ -595,103 +590,65 @@ class SessionStatus: def buffer_bytes(self) -> int: ... class StatisticsPlan: - def __init__(self, values: dict[str, object]) -> None: ... + def __init__(self, values: dict[str, Any]) -> None: ... @property def packed_size(self) -> int: ... -class Session: - def advance(self, work_limit: int, deadline: float) -> SessionBatch: ... - def acknowledge(self, sequence: int) -> None: ... - @overload - def export( - self, - sequence: int, - generation: int, - power: bool, - optics: bool, - weight: npt.NDArray[np.float64] | None, - out: npt.NDArray[np.complex128], - ) -> None: ... - @overload - def export( - self, - ticket: tuple[int, int], - recipe: Mapping[str, object], - out: npt.NDArray[np.complex128], - ) -> None: ... - def snapshot( - self, ticket: tuple[int, int] - ) -> ( - tuple[ - dict[str, Any], - npt.NDArray[np.complex128], - dict[str, npt.NDArray[np.complex128]], - ] - | None - ): ... - def noise_phase( - self, ticket: tuple[int, int], z: float - ) -> npt.NDArray[np.complex128]: ... - def records(self) -> dict[str, Any]: ... - def continue_with(self, continuation: object) -> None: ... - def request_stop(self) -> None: ... - def request_snapshot(self) -> tuple[int, bool]: ... - def status(self) -> SessionStatus: ... - @property - def elements(self) -> int: ... - def monitor_record(self) -> dict[str, Any] | None: ... - def monitor_cap(self) -> float | None: ... - def quadrature_peak(self) -> float: ... - def continue_monitor( - self, - record: dict[str, object], - plane: bool, - unwatched: list[list[float]], - edge_record: dict[str, object], - ) -> None: ... - def edge_record(self) -> dict[str, Any] | None: ... - def march_state(self, since: int) -> dict[str, Any] | None: ... - def march_snapshot( - self, sequence: int, generation: int - ) -> ( - tuple[ - dict[str, Any], - npt.NDArray[np.complex128], - dict[str, npt.NDArray[np.complex128]], - ] - | None - ): ... - def table_phi( - self, sequence: int, generation: int, z: float - ) -> npt.NDArray[np.complex128]: ... - def fail_outside(self) -> SessionBatch | None: ... - def close(self) -> None: ... - -# solprop SEP 52 section 5.3: one workspace a problem, one run record a start. -class Probe: - def trial(self, z: float, dz: float) -> float: ... - def field(self) -> npt.NDArray[np.complex128]: ... - @property - def trials(self) -> int: ... - @property - def evaluations(self) -> int: ... - @property - def low_storage(self) -> bool: ... - @property - def z(self) -> float: ... - @property - def closed(self) -> bool: ... - def close(self) -> None: ... - class Workspace: def __init__(self, problem: Problem) -> None: ... - def start(self, run: object, host_source: object | None = None) -> Session: ... - def probe(self, start: object) -> Probe: ... + def start( + self, run: Mapping[str, object], host_source: object | None = None + ) -> Session: ... + def probe( + self, start: Mapping[str, object], host_source: object | None = None + ) -> Probe: ... def diagnostics(self) -> dict[str, Any]: ... - def unbind_host_source(self) -> None: ... @property def closed(self) -> bool: ... def close(self) -> None: ... -def configure_runtime(record: object) -> dict[str, str]: ... -def schemas() -> dict[str, dict[str, Any]]: ... +def available_device_memory() -> int | None: ... +def basis_rows( + points: npt.NDArray[np.float64], + upper: float, + integrate: bool, + rows: npt.NDArray[np.float64], + weights: npt.NDArray[np.float64], +) -> None: ... +def build_record() -> dict[str, Any]: ... +@overload +def clenshaw_points( + z: npt.NDArray[np.float64], + edges: npt.NDArray[np.float64], + lower: float, + upper: float, + c: npt.NDArray[np.float64], + out: npt.NDArray[np.float64], +) -> int: ... +@overload +def clenshaw_points( + z: npt.NDArray[np.float64], + edges: npt.NDArray[np.float64], + lower: float, + upper: float, + c: npt.NDArray[np.complex128], + out: npt.NDArray[np.complex128], +) -> int: ... +def configure_runtime(record: Mapping[str, object]) -> dict[str, str]: ... +def export_fftw_wisdom() -> str | None: ... +def reference_stream_copies(elements: int, warm: int, repeats: int) -> list[float]: ... +def schemas() -> dict[str, Any]: ... +def time_fft_plan(key: str, wisdom: str, effort: str) -> dict[str, Any]: ... +def trial_tables( + nodes: npt.NDArray[np.float64], + order: int, + orders: Sequence[int], + compensated: bool, + predictor: npt.NDArray[np.float64], + corrector: npt.NDArray[np.float64], + factored: npt.NDArray[np.float64], + spans: npt.NDArray[np.float64], + carried: npt.NDArray[np.float64], + endpoint: npt.NDArray[np.float64], + defects: npt.NDArray[np.float64], +) -> None: ... diff --git a/native/src/solprop_native/_core_testing.pyi b/native/src/solprop_native/_core_testing.pyi index 6affbc299..6152cb44e 100644 --- a/native/src/solprop_native/_core_testing.pyi +++ b/native/src/solprop_native/_core_testing.pyi @@ -2,50 +2,158 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -# The private test module `solprop_native._core._testing` (solprop SEP 52 section 6.5), -# imported as `from solprop_native._core import _testing`: the entry points only -# solprop's own tests reach. A `State` method that moved here takes the state first. -# `native/scripts/problem_stub.py --check` holds the names here to the module's. +# Generated by native/scripts/problem_stub.py from nanobind.stubgen: do not edit. +# The private test module `solprop_native._core._testing` (solprop SEP 52 section 6.5): +# the entry points only solprop's own tests reach. It promises nothing. from __future__ import annotations -from collections.abc import Sequence +from collections.abc import Mapping, Sequence from typing import Any import numpy as np import numpy.typing as npt +import solprop.backends.engines +import solprop.backends.records -from solprop_native._core import State, StatisticsPlan, Workspace +from solprop_native._core import StatisticsPlan, Workspace -def trial_step( - state: State, +class Engines: + def field(self) -> npt.NDArray[np.complex128]: ... + def stage(self, index: int) -> npt.NDArray[np.complex128]: ... + def load( + self, field: npt.NDArray[np.complex128], noise: npt.NDArray[np.complex128] + ) -> None: ... + def close(self) -> None: ... + def rk_trial(self, arg0: float, arg1: float, /) -> float: ... + def rk_accept(self, dz: float) -> solprop.backends.engines.AcceptRecord: ... + def rk_extend(self, arg0: float, arg1: float, /) -> None: ... + def rk_reading(self) -> solprop.backends.engines.BoundaryReading: ... + @property + def rk_in_flight(self) -> bool: ... + def adams_start(self, arg: float, /) -> None: ... + def adams_trial( + self, arg0: float, arg1: float, arg2: object, / + ) -> npt.NDArray[np.float64]: ... + def adams_accept( + self, + dz: float, + free: int, + held: object, + kept: Sequence[solprop.backends.engines.HistoryEntry], + ) -> solprop.backends.engines.AcceptRecord: ... + def adams_chord_phase(self, arg0: float, arg1: float, /) -> float: ... + def adams_step_carrier(self, arg: int, /) -> object: ... + def adams_begin_attempt(self, arg: int, /) -> None: ... + def adams_end_attempt(self, arg: int, /) -> None: ... + def adams_reading(self) -> solprop.backends.engines.BoundaryReading: ... + +class Monitor: + def __init__(self, config: solprop.backends.records.MonitorConfig) -> None: ... + def resume( + self, + record: solprop.backends.records.Resumption, + plane: bool, + unwatched: Sequence[tuple[float, float]], + ) -> None: ... + def launch( + self, + reading: npt.NDArray[np.float64], + z: float, + floor: float = 0.0, + floor_regions: npt.NDArray[np.float64] | None = None, + ) -> dict[str, Any]: ... + def due(self, z: float) -> bool: ... + def skip(self, z: float) -> None: ... + def step( + self, reading: npt.NDArray[np.float64], z: float, plane: bool = False + ) -> dict[str, Any]: ... + def plane(self, z: float) -> None: ... + def note_collar(self, left_out: bool) -> None: ... + def finish(self) -> dict[str, Any]: ... + def record(self) -> dict[str, Any]: ... + def watch_state(self) -> dict[str, Any]: ... + @property + def stale(self) -> bool: ... + @property + def collar_quiet(self) -> bool: ... + @property + def step_cap(self) -> float: ... + @property + def rests(self) -> bool: ... + def steps_to_check(self) -> int: ... + +class ScriptedMarch: + def __init__( + self, + policy: dict[str, Any], + norms: npt.NDArray[np.float64], + carrier_rate: float, + steps: npt.NDArray[np.float64], + edges: npt.NDArray[np.float64], + ) -> None: ... + def run(self, state: dict[str, Any], bounds: dict[str, Any]) -> dict[str, Any]: ... + def log(self) -> list[Any]: ... + +class ScriptedRkMarch: + def __init__( + self, + policy: object, + norms: npt.NDArray[np.float64], + h0: float, + steps: npt.NDArray[np.float64], + edges: npt.NDArray[np.float64], + ) -> None: ... + def run(self, state: dict[str, Any], bounds: dict[str, Any]) -> dict[str, Any]: ... + def log(self) -> list[Any]: ... + def used(self) -> int: ... + +class TransverseEdge: + def __init__(self, config: dict[str, Any]) -> None: ... + def resume(self, record: dict[str, Any]) -> None: ... + def launch( + self, + reading: dict[str, Any], + z: float, + sums: tuple[float, float] | None = None, + noise: dict[str, Any] | None = None, + ) -> dict[str, Any]: ... + def read( + self, reading: dict[str, Any], z: float, sums: tuple[float, float] | None = None + ) -> dict[str, Any]: ... + def proceed(self) -> dict[str, Any]: ... + def step(self, current: float, z: float) -> None: ... + def ceiling(self) -> float: ... + def due(self, z: float, proposal: float) -> bool: ... + def wants_read(self, z: float) -> bool: ... + def launch_sums(self, columns: npt.NDArray[np.float64]) -> tuple[Any, ...]: ... + def read_sums(self, gap: float) -> tuple[Any, ...]: ... + def record(self) -> dict[str, Any]: ... + @property + def next_read(self) -> float: ... + @property + def every_step(self) -> bool: ... + @property + def resumed(self) -> bool: ... + @property + def pending(self) -> bool: ... + @property + def status(self) -> int: ... + +def adams_block_to_host(workspace: Workspace) -> npt.NDArray[np.complex128]: ... +def adams_compensation_start( + workspace: Workspace, slot: int, rate: npt.NDArray[np.float64] +) -> None: ... +def adams_exponent_to_host(workspace: Workspace) -> npt.NDArray[np.complex128]: ... +def adams_exponential_accept( + workspace: Workspace, dz: float, - phi_delta: npt.NDArray[np.float64], - phi_at: npt.NDArray[np.float64], - prefactor: npt.NDArray[np.float64], - density: npt.NDArray[np.float64], - taper: npt.NDArray[np.float64], - preionisation: npt.NDArray[np.float64], - raman_rates: npt.NDArray[np.float64], - material: dict[str, npt.NDArray[np.float64] | int] | None = None, - prepare_only: bool = False, -) -> npt.NDArray[np.float64]: ... -def adopt(state: State, field: npt.NDArray[np.complex128], dz: float) -> None: ... -def stage_to_host(state: State, stage: int) -> npt.NDArray[np.complex128]: ... -def projected_to_host( - state: State, coarse: bool = False -) -> npt.NDArray[np.complex128]: ... -def weighted_error( - state: State, scale: npt.NDArray[np.float64] -) -> npt.NDArray[np.float64]: ... -def form_flow_actions( - state: State, section: int, dz: float, fractions: npt.NDArray[np.float64] -) -> npt.NDArray[np.float64]: ... -def flow_actions_to_host(state: State, inverse: bool) -> npt.NDArray[np.complex128]: ... -def adams_block_to_host(state: State) -> npt.NDArray[np.complex128]: ... -def adams_exponent_to_host(state: State) -> npt.NDArray[np.complex128]: ... + free: int, + dense: npt.NDArray[np.uint64], + interpolate: bool, +) -> None: ... def adams_exponential_trial( - state: State, + workspace: Workspace, dz: float, slots: npt.NDArray[np.uint64], predictor: npt.NDArray[np.float64], @@ -59,7 +167,7 @@ def adams_exponential_trial( taper: npt.NDArray[np.float64], preionisation: npt.NDArray[np.float64], raman_rates: npt.NDArray[np.float64], - material: dict[str, npt.NDArray[np.float64] | int], + material: dict[str, Any], sample_phi_delta: npt.NDArray[np.float64], sample_phi_at: npt.NDArray[np.float64], sample_prefactor: npt.NDArray[np.float64], @@ -67,7 +175,7 @@ def adams_exponential_trial( sample_taper: npt.NDArray[np.float64], sample_preionisation: npt.NDArray[np.float64], sample_raman_rates: npt.NDArray[np.float64], - sample_material: dict[str, npt.NDArray[np.float64] | int], + sample_material: dict[str, Any], spans: npt.NDArray[np.float64], comp_predictor: npt.NDArray[np.float64], comp_corrector: npt.NDArray[np.float64], @@ -76,21 +184,33 @@ def adams_exponential_trial( carrier: npt.NDArray[np.float64], ) -> npt.NDArray[np.float64]: ... def adams_exponential_trial_at( - state: State, + workspace: Workspace, z: float, dz: float, nodes: npt.NDArray[np.float64], slots: npt.NDArray[np.uint64], order: int, - orders: list[int], + orders: Sequence[int], compensated: bool, carrier: npt.NDArray[np.float64], ) -> npt.NDArray[np.float64]: ... -def adams_exponential_accept( - state: State, dz: float, free: int, dense: npt.NDArray[np.uint64], interpolate: bool +def adams_hold(workspace: Workspace) -> None: ... +def adams_march_run( + workspace: Workspace, march: dict[str, Any], bounds: dict[str, Any] +) -> dict[str, Any]: ... +def adams_restore(workspace: Workspace) -> None: ... +def adams_rows_from_host( + workspace: Workspace, name: str, rows: npt.NDArray[np.complex128] ) -> None: ... +def adams_rows_to_host( + workspace: Workspace, name: str +) -> npt.NDArray[np.complex128]: ... +def adams_stage_rate(workspace: Workspace, z: float) -> list[float]: ... +def adams_stage_scalars( + workspace: Workspace, z0: float, z1: float +) -> dict[str, Any]: ... def adams_start( - state: State, + workspace: Workspace, slot: int, phi_delta: npt.NDArray[np.float64], phi_at: npt.NDArray[np.float64], @@ -99,51 +219,81 @@ def adams_start( taper: npt.NDArray[np.float64], preionisation: npt.NDArray[np.float64], raman_rates: npt.NDArray[np.float64], - material: dict[str, npt.NDArray[np.float64] | int], + material: dict[str, Any], ) -> None: ... -def adams_compensation_start( - state: State, slot: int, rate: npt.NDArray[np.float64] +def adopt( + workspace: Workspace, field: npt.NDArray[np.complex128], dz: float ) -> None: ... -def adams_hold(state: State) -> None: ... -def adams_restore(state: State) -> None: ... -def adams_rows_to_host(state: State, name: str) -> npt.NDArray[np.complex128]: ... -def adams_stage_scalars( - state: State, z0: float, z1: float -) -> dict[str, list[float]]: ... -def adams_stage_rate(state: State, z: float) -> list[float]: ... -def has_stage_tables(state: State) -> bool: ... -def table_rate_at(state: State, z: float, before: bool) -> None: ... -def phase_sum_to_host( - state: State, weights: npt.NDArray[np.float64] -) -> npt.NDArray[np.complex128]: ... -def promote_fsal(state: State) -> None: ... -def adams_march_run( - state: State, march: dict[str, object], bounds: dict[str, object] -) -> dict[str, Any]: ... -def rk_march_run( - state: State, march: dict[str, object], bounds: dict[str, object] -) -> dict[str, Any]: ... -def adams_march_fault(state: State, stage: str, after: int, category: str) -> None: ... -def statistics( - state: State, +def aperture_statistics( + workspace: Workspace, flags: int, - windows: npt.NDArray[np.float64], - on_axis: npt.NDArray[np.float64], - density: float, - taper: float, - preionisation: float, + apertures: npt.NDArray[np.float64], + exponent: int, + regions: npt.NDArray[np.float64], intensity_factor: float, - channel_preionisation: npt.NDArray[np.float64] | None = None, - power_weight: npt.NDArray[np.float64] | None = None, ) -> npt.NDArray[np.float64]: ... -def spatial_statistics( - state: State, flags: int, intensity_factor: float, z: float +def axis_spectrum( + workspace: Workspace, matrix: npt.NDArray[np.float64] +) -> npt.NDArray[np.complex128]: ... +def bind_monitor( + workspace: Workspace, + monitor: Mapping[str, object], + edge: Mapping[str, object] | None, + occupancy: Mapping[str, object] | None, +) -> None: ... +def clear_fsal(workspace: Workspace) -> None: ... +def configure_march( + workspace: Workspace, records: solprop.backends.records.RunRecords +) -> None: ... +def edge_reading( + workspace: Workspace, + faces: bool, + whole: bool, + totals: bool, + strip: bool, + current: bool, +) -> tuple[Any, ...]: ... +def engines(workspace: Workspace) -> Engines: ... +def evaluate( + workspace: Workspace, plan: StatisticsPlan, z: float ) -> npt.NDArray[np.float64]: ... -def planned_statistics( - state: State, plan: StatisticsPlan, z: float +def field(workspace: Workspace) -> npt.NDArray[np.complex128]: ... +def finish(workspace: Workspace, dz: float) -> None: ... +def flow_actions_to_host( + workspace: Workspace, inverse: bool +) -> npt.NDArray[np.complex128]: ... +def fluence_block_widths( + plan: StatisticsPlan, block: npt.NDArray[np.float64] +) -> tuple[Any, ...]: ... +def forget_fftw_wisdom() -> None: ... +def form_flow_actions( + workspace: Workspace, section: int, dz: float, fractions: npt.NDArray[np.float64] ) -> npt.NDArray[np.float64]: ... +def half_width( + t: npt.NDArray[np.float64], power: npt.NDArray[np.float64], outer: bool +) -> float: ... +def has_stage_tables(workspace: Workspace) -> bool: ... +def import_fftw_wisdom(text: str) -> bool: ... +def inject_fault( + workspace: Workspace, stage: str, after: int, category: str +) -> None: ... +def line_fluence_widths( + x: npt.NDArray[np.float64], samples: npt.NDArray[np.float64], e2_fraction: float +) -> tuple[Any, ...]: ... +def load( + workspace: Workspace, + field: npt.NDArray[np.complex128], + noise: npt.NDArray[np.complex128], +) -> None: ... +def low_storage_norms( + workspace: Workspace, positions: Sequence[float] +) -> npt.NDArray[np.float64]: ... +def monitor_reading(workspace: Workspace) -> npt.NDArray[np.float64]: ... +def phase_sum_to_host( + workspace: Workspace, weights: npt.NDArray[np.float64] +) -> npt.NDArray[np.complex128]: ... def plane_fluence_trace( - state: State, + workspace: Workspace, center_x: float, center_y: float, dx: float, @@ -154,198 +304,105 @@ def plane_fluence_trace( cosines: npt.NDArray[np.float64], sines: npt.NDArray[np.float64], ) -> npt.NDArray[np.float64]: ... -def axis_spectrum( - state: State, matrix: npt.NDArray[np.float64] +def planned_statistics( + workspace: Workspace, plan: StatisticsPlan, z: float +) -> npt.NDArray[np.float64]: ... +def prepare_raman( + workspace: Workspace, + rates: npt.NDArray[np.float64], + densities: npt.NDArray[np.float64], +) -> None: ... +def projected_to_host( + workspace: Workspace, coarse: bool = False ) -> npt.NDArray[np.complex128]: ... -def monitor_reading(state: State) -> npt.NDArray[np.float64]: ... -def quadrature_error(state: State) -> float: ... -def watch_check( - policy: dict[str, object], - state: dict[str, object], - reading: npt.NDArray[np.float64], - z: float, -) -> dict[str, Any]: ... -def watch_due( - policy: dict[str, object], state: dict[str, object], z: float -) -> bool: ... -def watch_split_limit( - policy: dict[str, object], occupancy: npt.NDArray[np.float64] -) -> float: ... -def half_width( - t: npt.NDArray[np.float64], power: npt.NDArray[np.float64], outer: bool -) -> float: ... -def strict_witness( - a: float, b: float, c: float -) -> tuple[float, float, float, float, float, float, float, float, float, float]: ... +def promote_fsal(workspace: Workspace) -> None: ... +def quadrature_error(workspace: Workspace) -> float: ... +def quadrature_peak(workspace: Workspace) -> float: ... def radial_fluence_widths( radius: npt.NDArray[np.float64], fluence: npt.NDArray[np.float64], weights: npt.NDArray[np.float64], axis_fluence: float, e2_fraction: float, -) -> tuple[float, float, float]: ... -def fluence_block_widths( - plan: StatisticsPlan, block: npt.NDArray[np.float64] -) -> tuple[float, float, float]: ... -def line_fluence_widths( - x: npt.NDArray[np.float64], samples: npt.NDArray[np.float64], e2_fraction: float -) -> tuple[float, float, float]: ... +) -> tuple[Any, ...]: ... def reference_fft3_pairs( values: npt.NDArray[np.complex128], warm: int, pairs: int ) -> list[float]: ... -def scoped_openmp_default() -> int: ... +def rk_march_run( + workspace: Workspace, march: dict[str, Any], bounds: dict[str, Any] +) -> dict[str, Any]: ... +def rk_score(partials: npt.NDArray[np.float64], rtol: float, atol: float) -> float: ... +def rk_trial(workspace: Workspace, z: float, dz: float) -> npt.NDArray[np.float64]: ... +def round_trip(name: str, value: object) -> dict[str, Any]: ... def scoped_block_time() -> int: ... -def forget_fftw_wisdom() -> None: ... -def import_fftw_wisdom(text: str) -> bool: ... +def scoped_openmp_default() -> int: ... +def set_absorber_quiet(workspace: Workspace, quiet: bool) -> None: ... +def spatial_statistics( + workspace: Workspace, flags: int, intensity_factor: float, z: float +) -> npt.NDArray[np.float64]: ... +def stage_to_host(workspace: Workspace, stage: int) -> npt.NDArray[np.complex128]: ... +def statistics( + workspace: Workspace, + flags: int, + windows: npt.NDArray[np.float64], + on_axis: npt.NDArray[np.float64], + density: float, + taper: float, + preionisation: float, + intensity_factor: float, + channel_preionisation: object | None = None, + power_weight: object | None = None, +) -> npt.NDArray[np.float64]: ... +def strict_witness(a: float, b: float, c: float) -> tuple[Any, ...]: ... +def table_evaluations(workspace: Workspace) -> int: ... +def table_load(workspace: Workspace, positions: Sequence[float]) -> list[int]: ... +def table_rate_at(workspace: Workspace, z: float, before: bool) -> None: ... +def table_values( + workspace: Workspace, kind: str, z: float +) -> npt.NDArray[np.complex128]: ... +def trial_step( + workspace: Workspace, + dz: float, + phi_delta: npt.NDArray[np.float64], + phi_at: npt.NDArray[np.float64], + prefactor: npt.NDArray[np.float64], + density: npt.NDArray[np.float64], + taper: npt.NDArray[np.float64], + preionisation: npt.NDArray[np.float64], + raman_rates: npt.NDArray[np.float64], + material: object | None = None, + prepare_only: bool = False, +) -> npt.NDArray[np.float64]: ... def vector_exp(x: npt.NDArray[np.float64], out: npt.NDArray[np.float64]) -> None: ... -def vector_log(x: npt.NDArray[np.float64], out: npt.NDArray[np.float64]) -> None: ... -def vector_sincos( - x: npt.NDArray[np.float64], - sine: npt.NDArray[np.float64], - cosine: npt.NDArray[np.float64], -) -> None: ... def vector_exp_complex( a: npt.NDArray[np.float64], b: npt.NDArray[np.float64], real: npt.NDArray[np.float64], imag: npt.NDArray[np.float64], ) -> None: ... - -class TransverseEdge: - def __init__(self, config: dict[str, object]) -> None: ... - def resume(self, record: dict[str, object]) -> None: ... - def launch( - self, - reading: dict[str, object], - z: float, - sums: tuple[float, float] | None = None, - noise: dict[str, object] | None = None, - ) -> dict[str, Any]: ... - def read( - self, - reading: dict[str, object], - z: float, - sums: tuple[float, float] | None = None, - ) -> dict[str, Any]: ... - def proceed(self) -> dict[str, Any]: ... - def step(self, current: float, z: float) -> None: ... - def ceiling(self) -> float: ... - def due(self, z: float, proposal: float) -> bool: ... - def wants_read(self, z: float) -> bool: ... - def launch_sums(self, columns: npt.NDArray[np.float64]) -> tuple[float, float]: ... - def read_sums(self, gap: float) -> tuple[float, float]: ... - def record(self) -> dict[str, Any]: ... - @property - def next_read(self) -> float: ... - @property - def every_step(self) -> bool: ... - @property - def resumed(self) -> bool: ... - @property - def pending(self) -> bool: ... - @property - def status(self) -> int: ... - -class Monitor: - def __init__(self, config: dict[str, object]) -> None: ... - def resume( - self, - record: dict[str, object], - plane: bool, - unwatched: list[list[float]], - ) -> None: ... - def launch( - self, - reading: npt.NDArray[np.float64], - z: float, - floor: float = 0.0, - floor_regions: npt.NDArray[np.float64] | None = None, - ) -> dict[str, Any]: ... - def due(self, z: float) -> bool: ... - def skip(self, z: float) -> None: ... - def step( - self, reading: npt.NDArray[np.float64], z: float, plane: bool = False - ) -> dict[str, Any]: ... - def plane(self, z: float) -> None: ... - def note_collar(self, left_out: bool) -> None: ... - def finish(self) -> dict[str, Any]: ... - def record(self) -> dict[str, Any]: ... - def watch_state(self) -> dict[str, Any]: ... - @property - def stale(self) -> bool: ... - @property - def collar_quiet(self) -> bool: ... - @property - def step_cap(self) -> float: ... - @property - def rests(self) -> bool: ... - def steps_to_check(self) -> int: ... - -class ScriptedMarch: - def __init__( - self, - policy: dict[str, object], - norms: npt.NDArray[np.float64], - carrier_rate: float, - steps: npt.NDArray[np.float64], - edges: npt.NDArray[np.float64], - ) -> None: ... - def run( - self, state: dict[str, object], bounds: dict[str, object] - ) -> dict[str, Any]: ... - def log(self) -> list[dict[str, Any]]: ... - -class ScriptedRkMarch: - def __init__( - self, - policy: dict[str, object], - norms: npt.NDArray[np.float64], - h0: float, - steps: npt.NDArray[np.float64], - edges: npt.NDArray[np.float64], - ) -> None: ... - def run( - self, state: dict[str, object], bounds: dict[str, object] - ) -> dict[str, Any]: ... - def log(self) -> list[dict[str, Any]]: ... - def used(self) -> int: ... - -# solprop SEP 52 section 6.5: native's engines through solprop's protocols -# (`solprop.backends.engines`), each method prefixed by its engine, with read-backs. -class Engines: - def __init__(self) -> None: ... # made by `engines(workspace)` alone - def field(self) -> npt.NDArray[np.complex128]: ... - def stage(self, index: int) -> npt.NDArray[np.complex128]: ... - def load( - self, field: npt.NDArray[np.complex128], noise: npt.NDArray[np.complex128] - ) -> None: ... - def close(self) -> None: ... - def rk_trial(self, z: float, dz: float) -> float: ... - def rk_accept(self, dz: float) -> Any: ... - def rk_extend(self, z: float, dz: float) -> None: ... - def rk_reading(self) -> Any: ... - @property - def rk_in_flight(self) -> bool: ... - def adams_start(self, z: float) -> None: ... - def adams_trial( - self, z: float, dz: float, stencil: Any - ) -> npt.NDArray[np.float64]: ... - def adams_accept( - self, dz: float, free: int, stencil: Any, kept: Sequence[Any] - ) -> Any: ... - def adams_chord_phase(self, z1: float, z2: float) -> float: ... - def adams_step_carrier( - self, order: int - ) -> npt.NDArray[np.float64] | list[float]: ... - def adams_begin_attempt(self, cost: int) -> None: ... - def adams_end_attempt(self, outcome: int) -> None: ... - def adams_reading(self) -> Any: ... - -def engines(workspace: Workspace) -> Engines: ... -def inject_fault( - workspace: Workspace, stage: str, after: int, category: str +def vector_log(x: npt.NDArray[np.float64], out: npt.NDArray[np.float64]) -> None: ... +def vector_sincos( + x: npt.NDArray[np.float64], + sine: npt.NDArray[np.float64], + cosine: npt.NDArray[np.float64], ) -> None: ... -def evaluate( - workspace: Workspace, plan: StatisticsPlan, z: float +def watch_check( + policy: dict[str, Any], + state: dict[str, Any], + reading: npt.NDArray[np.float64], + z: float, +) -> dict[str, Any]: ... +def watch_due(policy: dict[str, Any], state: dict[str, Any], z: float) -> bool: ... +def watch_split_limit( + policy: dict[str, Any], occupancy: npt.NDArray[np.float64] +) -> float: ... +def weighted_error( + workspace: Workspace, scale: npt.NDArray[np.float64] ) -> npt.NDArray[np.float64]: ... -def round_trip(name: str, value: object) -> dict[str, Any]: ... +def weighted_score( + workspace: Workspace, + partials: npt.NDArray[np.float64], + rtol: float, + atol: float, + weights: npt.NDArray[np.float64], +) -> float: ... diff --git a/tests/sessions/test_split_collar_rules.py b/tests/sessions/test_split_collar_rules.py index b7a32c4ec..0e420ef01 100644 --- a/tests/sessions/test_split_collar_rules.py +++ b/tests/sessions/test_split_collar_rules.py @@ -397,9 +397,9 @@ def test_native_s_accept_record_carries_each_step_s_sums(march): simulation = walking_fibre("native", MARCHES[march]) problem, request, own = _backend(simulation) try: - monitor = dataclasses.replace( - simulation._boundary_monitor(), crossing=problem.split_crossing - ) + watched = simulation._boundary_monitor() + assert watched is not None + monitor = dataclasses.replace(watched, crossing=problem.split_crossing) assert monitor.split workspace = own._workspace field = np.ascontiguousarray(problem.initial.field0).reshape(-1) From 5a4eb9c83b7f72e7ad19b61f7bb9090ba0b65d12 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 04:28:29 +0000 Subject: [PATCH 09/29] test(native): every designated initializer of the workspace's setup Co-Authored-By: Claude Opus 5.5 --- native/tests/native/test_workspace.cpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/native/tests/native/test_workspace.cpp b/native/tests/native/test_workspace.cpp index 79808ad4d..93f8473b4 100644 --- a/native/tests/native/test_workspace.cpp +++ b/native/tests/native/test_workspace.cpp @@ -81,8 +81,8 @@ native::Setup runge_kutta_setup() { tables.prefactor_high = 2.0; tables.density = constant_table({1.0}); setup.stage_tables = tables; - setup.runge_kutta = - native::RungeKuttaConfig{.nodes = {0.0}, .rtol = 1e-6, .atol = 1e-12}; + setup.runge_kutta = native::RungeKuttaConfig{ + .nodes = {0.0}, .rtol = 1e-6, .atol = 1e-12, .weights = {}, .dense_weights = {}}; return setup; } From ee3fc8e51824c0a08429c5877c7f16c4d57ac8a7 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 04:32:00 +0000 Subject: [PATCH 10/29] docs(native): the binding's rules; a changelog fragment for the workspace seam (SEP 52) Co-Authored-By: Claude Opus 5.5 --- .../sep-0052-native-workspace.changed.md | 1 + native/AGENTS.md | 27 ++++++++++++----- native/README.md | 29 +++++++++++++++++++ 3 files changed, 49 insertions(+), 8 deletions(-) create mode 100644 changelog.d/sep-0052-native-workspace.changed.md diff --git a/changelog.d/sep-0052-native-workspace.changed.md b/changelog.d/sep-0052-native-workspace.changed.md new file mode 100644 index 000000000..3ffe3eda1 --- /dev/null +++ b/changelog.d/sep-0052-native-workspace.changed.md @@ -0,0 +1 @@ +solprop-native's private extension takes one workspace per backend, built from one problem record that carries every set-once table, and starts each run from one run record and each timing probe from the run's start (SEP 52): the per-call configuration of the old native state is gone, records cross by field table and are refused by field path, and both stubs of the extension are generated. A backend whose low-storage timing probe advanced its registers now refuses a further run or probe by name instead of running from the discarded registers. diff --git a/native/AGENTS.md b/native/AGENTS.md index 174a5f37c..96a009d1d 100644 --- a/native/AGENTS.md +++ b/native/AGENTS.md @@ -126,7 +126,7 @@ the gate. execution-space instances. Dispatch top-level kernels through `launch::parallel_for`, `parallel_reduce` and `parallel_scan` (`include/solprop_native/launch.hpp`), which pass a device kernel's functor as its launch argument; team-level loops stay `Kokkos::`. -- Allocate field-sized views, scratch and FFT plans once, when a state is constructed. +- Allocate field-sized views, scratch and FFT plans once, when a workspace is built. A trial step performs no allocation, planning, logging, Python call or unplanned fence. The one exception is the host source hook (solprop SEP 49, `include/solprop_native/host_source.hpp`): on a CPU build, a bound host source is @@ -134,7 +134,7 @@ the gate. binding layer takes the interpreter lock for each call; device builds refuse it. - Keep data resident in the execution space until it is observed; `field_to_host` is the explicit synchronous boundary. Every persistent allocation appears in - `memory_ledger()` with its real size in bytes. + the memory ledger (`Workspace.diagnostics()`) with its real size in bytes. - Use `KokkosFFT::Normalization::none` and keep solprop's explicit scaling. Do not hand-roll transforms, reductions, scans, sorts, random number generators or other facilities that Kokkos, Kokkos Kernels or Kokkos-FFT supply. @@ -185,11 +185,20 @@ the gate. - The contract with solprop is its kernel contract, whose fields solprop's frozen tables hold. The backend inherits no solprop driver: a run is its native session (`session.py`), and the load, the Adams record and the timing probe are its own - (`_load.py`, `backend.py`, `_probe.py`). `check_build()` refuses, in an editable + (`_load.py`, `backend.py`, `_probe.py`). A backend holds one `_core.Workspace`, + built from one `_core.Problem` with every set-once table; a run starts from one run + record and the probe from the run's start (solprop SEP 52 section 5.3), and nothing + configures the workspace after it is built. `check_build()` refuses, in an editable checkout, an extension built from other sources than `native/` (`build_info().source_digest`; `cmake/SourceDigest.cmake` and `_source_digest` compute it, and stay in step). It records solprop's version without comparing it; never pin solprop's version. +- A record that crosses declares its fields once, in a field table beside its C++ + definition (`include/solprop_native/fields.hpp`), and is read by the one converter + (`src/records.hpp`), never by a hand-written dictionary reader; `_core.schemas()` + exports the tables, which a test holds to the Python records. A binding only + converts, releases the GIL and forwards: logic goes in the C++ library, where ctest + reaches it. - Accept the documented NumPy dtype, rank, shape and C-contiguity exactly and refuse hidden O(n) conversions. Read-only input is valid. Returned host arrays own their memory. @@ -198,11 +207,13 @@ the gate. - Release the GIL around long native work and hold it while touching Python objects. Never call Python from a Kokkos or OpenMP worker, or during teardown. - Public Python has complete annotations, NumPy-style docstrings, `__all__`, `py.typed` - and a complete stub for the private extension; its bound problem's part is generated - (`scripts/problem_stub.py`, checked in the lint stage). An entry point only solprop's - tests reach goes in the extension's private `_testing` submodule (solprop SEP 52), - which ships in the wheel and promises nothing; its stub, `_core_testing.pyi`, is - held to the module's names by the same check. Install a `NullHandler`; never + and a complete stub for the private extension, generated whole with its `_testing` + stub by nanobind's stubgen (`scripts/problem_stub.py`, checked in the lint stage): + a binding that takes or returns a record names its Python type with `nb::sig`, and a + stub is regenerated, never edited. An entry point only solprop's tests reach goes in + the extension's private `_testing` submodule (solprop SEP 52), which ships in the + wheel and promises nothing; one that touches the state takes the workspace first. + Install a `NullHandler`; never configure the root logger or print diagnostics from library code. - Thread settings are read once, at import. Never change process thread settings (or a BLAS thread pool) after import. diff --git a/native/README.md b/native/README.md index c534e4fe6..c083f8586 100644 --- a/native/README.md +++ b/native/README.md @@ -123,6 +123,35 @@ and solprop's metadata pins it to solprop's own version. The version recorded at CMake configure) is provenance only. The TDSE electronic response is refused by name before anything is allocated; TDSE propagation uses `backend="numpy_ref"`. +### The binding + +The private extension `_core` is a thin seam (solprop SEP 52 section 5.3): + +- **One workspace, one run record.** A backend builds one `_core.Problem`, which + carries every table, guard and setting fixed for the workspace, and one + `_core.Workspace` from it for its life. Each run starts from one record + (`Workspace.start(run)`), and the timing probe from the run's start + (`Workspace.probe(start)`); `Workspace.diagnostics()` returns every fact the + metadata reads. A session or probe leases the workspace until it closes. +- **Records by field table.** Each C++ record declares its fields once, beside its + definition (`include/solprop_native/fields.hpp`), and one converter + (`src/records.hpp`) reads a dataclass, mapping or tuple into it, refusing a missing + or unknown field, a wrong dtype, rank or extent relation, or a strided array by the + field's path before copying anything. `_core.schemas()` exports every table, and a + test holds each Python record to its table. Input arrays are copied in; returned + arrays own their storage. +- **Bindings only marshal.** A binding converts, releases the interpreter lock and + forwards. The lease, the coupled flow's guard, the marches' construction and the + probe live in the C++ library (`native::Workspace`, `src/workspace.cpp`), where the + native tests reach them. +- **`_testing` promises nothing.** The test-only entry points live in the submodule + `_core._testing`, shipped in the wheel for solprop's own tests; they take the + workspace first and may change with any commit. +- **Generated stubs.** `_core.pyi` and `_core_testing.pyi` are generated whole by + nanobind's stubgen (`scripts/problem_stub.py`; `--check` in the lint stage). A binding + that takes or returns a record names its Python type with `nb::sig`, so the stubs + stay typed: edit the binding and regenerate, never the stub. + ### Native source coverage Build coverage in a separate build directory and Python environment. On Linux select From 0921ac5a8fdf938e4798b0d5c6903c5630b2e684 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 04:36:00 +0000 Subject: [PATCH 11/29] build(native): the stub script within the line length Co-Authored-By: Claude Opus 5.5 --- native/scripts/problem_stub.py | 15 +++++---------- native/src/solprop_native/_core.pyi | 4 ++-- 2 files changed, 7 insertions(+), 12 deletions(-) diff --git a/native/scripts/problem_stub.py b/native/scripts/problem_stub.py index fd4b6a0db..f4cdd3be0 100644 --- a/native/scripts/problem_stub.py +++ b/native/scripts/problem_stub.py @@ -71,7 +71,7 @@ def _arrays(text: str) -> str: def _body(module: ModuleType, names: list[str] | None = None) -> str: - """Return stubgen's stub of `module`'s names, in the stubs' spellings, no imports.""" + """Return stubgen's stub of `module`'s names in the stubs' spellings, no imports.""" stub = StubGen(module, quiet=True, include_docstrings=False) for name in names if names is not None else sorted(vars(module)): if name.startswith("__") or name == "_testing": @@ -80,9 +80,7 @@ def _body(module: ModuleType, names: list[str] | None = None) -> str: text = _arrays(stub.get()) text = PAIR.sub(r"\2: \4", text) lines = [ - line - for line in text.splitlines() - if not line.startswith(("import ", "from ")) + line for line in text.splitlines() if not line.startswith(("import ", "from ")) ] text = "\n".join(lines).strip() + "\n" replacements = { @@ -127,8 +125,8 @@ def generated() -> dict[Path, str]: body = _body(core) extra = [ "", - "# The private test module, bound as the submodule `_testing` (solprop SEP 52):", - "# its stub is `_core_testing.pyi`; the extension has no `_core_testing`.", + "# The private test module, bound as the submodule `_testing` (SEP 52): its", + "# stub is `_core_testing.pyi`; the extension has no `_core_testing`.", "from solprop_native import _core_testing", "", "_testing = _core_testing", @@ -145,10 +143,7 @@ def generated() -> dict[Path, str]: HEADER + "# The private test module `solprop_native._core._testing` (solprop SEP 52 " "section 6.5):\n# the entry points only solprop's own tests reach. It promises" - " nothing.\n\n" - + _imports(testing, testing_extra) - + "\n" - + testing + " nothing.\n\n" + _imports(testing, testing_extra) + "\n" + testing ) return {STUB: _formatted(main, STUB), TESTING_STUB: _formatted(private, STUB)} diff --git a/native/src/solprop_native/_core.pyi b/native/src/solprop_native/_core.pyi index 7b29de3d6..ca1804cf9 100644 --- a/native/src/solprop_native/_core.pyi +++ b/native/src/solprop_native/_core.pyi @@ -14,8 +14,8 @@ import numpy as np import numpy.typing as npt import solprop.backends.records -# The private test module, bound as the submodule `_testing` (solprop SEP 52): -# its stub is `_core_testing.pyi`; the extension has no `_core_testing`. +# The private test module, bound as the submodule `_testing` (SEP 52): its +# stub is `_core_testing.pyi`; the extension has no `_core_testing`. from solprop_native import _core_testing _testing = _core_testing From 09f1ad0b418459c6f5981248409029261a954827 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 04:52:06 +0000 Subject: [PATCH 12/29] perf(native): a run's initial field crosses once, borrowed for the start (SEP 52) The converter reads a std::span field as a view of the caller's array, valid for the call; RunStart's field and noise are such views, which Workspace::start loads straight into the state, so a large field is no longer copied into the record first (kerr_beam_192's low-storage window was 4.6 % slower on an EPYC 7763 with the copy). The probe keeps its own copy, which it reloads after a read-back. Also the tests the cluster sweep found: the carrier frame's host exponent (NativeBackend._delta_phi, host path), the session-failure test's lowering with its setup, and the plane plan's buffer constants, now the run records'. Co-Authored-By: Claude Opus 5.5 --- native/include/solprop_native/fields.hpp | 12 +++++++++++- native/include/solprop_native/workspace.hpp | 15 ++++++++------- native/src/records.hpp | 13 ++++++++++--- native/src/solprop_native/backend.py | 13 +++++++++++++ native/src/workspace.cpp | 5 ++++- native/tests/test_session_failure.py | 5 ++++- tests/driver/test_scan_stop_progress.py | 6 ++++-- tests/sessions/test_native_session.py | 7 +++++-- 8 files changed, 59 insertions(+), 17 deletions(-) diff --git a/native/include/solprop_native/fields.hpp b/native/include/solprop_native/fields.hpp index c8192b26e..0e44fbfc2 100644 --- a/native/include/solprop_native/fields.hpp +++ b/native/include/solprop_native/fields.hpp @@ -8,6 +8,7 @@ #include #include #include +#include #include #include #include @@ -76,15 +77,24 @@ template [[nodiscard]] constexpr Dtype element_dtype() noexcept { } /** The element an array field stores: a vector's, or an optional vector's (an array - that may be `None`). */ + that may be `None`), or a borrowed span's: a view of the Python array itself, valid + only while the call that read it runs, for a large array the call consumes at once + (a run's initial field), so that it is not copied twice. */ template struct ArrayElement; template struct ArrayElement> { using type = T; static constexpr bool optional = false; + static constexpr bool borrowed = false; }; template struct ArrayElement>> { using type = T; static constexpr bool optional = true; + static constexpr bool borrowed = false; +}; +template struct ArrayElement> { + using type = T; + static constexpr bool optional = false; + static constexpr bool borrowed = true; }; /** One axis of an array field: free (`any`), a literal (`fixed`), or a symbol with an diff --git a/native/include/solprop_native/workspace.hpp b/native/include/solprop_native/workspace.hpp index 6d6b62655..a66cda909 100644 --- a/native/include/solprop_native/workspace.hpp +++ b/native/include/solprop_native/workspace.hpp @@ -487,15 +487,16 @@ struct HistoryRow { } /** What one run starts from (`Workspace::start`): its records, the initial field and - noise as the state takes them (`set_initial`), the march's state at the start (the - Adams march's or the Runge-Kutta march's, none for a fresh state of its own), a - resumed history's rows, the statistics plans, the monitor's launch readings of the - input noise (its floor: energy, then four regions' shares; and the edge's), and the - run's monitor weights and edge tables where the state lives. */ + noise as the state takes them (`set_initial`), borrowed from the caller for the + call, the march's state at the start (the Adams march's or the Runge-Kutta march's, + none for a fresh state of its own), a resumed history's rows, the statistics plans, + the monitor's launch readings of the input noise (its floor: energy, then four + regions' shares; and the edge's), and the run's monitor weights and edge tables where + the state lives. */ struct RunStart { RunRecordsRecord records; - std::vector field; - std::vector noise; + std::span field; + std::span noise; std::optional adams; std::optional runge_kutta; std::vector rows; diff --git a/native/src/records.hpp b/native/src/records.hpp index 4af3973c1..fb9205501 100644 --- a/native/src/records.hpp +++ b/native/src/records.hpp @@ -361,6 +361,12 @@ void read_array(const fields::Array& field, nb::handle value, R* out, relate(borrowed.shape, field.extents.data(), N, symbols, path); if (out == nullptr) return; + if constexpr (Traits::borrowed) { + // A view of the caller's array, which it keeps alive for the call. + out->*field.member = std::span( + static_cast(borrowed.data), borrowed.count); + return; + } std::vector held(borrowed.count); static_assert(std::is_trivially_copyable_v); if (borrowed.count != 0) @@ -595,14 +601,15 @@ template nb::object write_array(const fields::Array& field, const R& record, const Symbols& symbols) { using Traits = fields::ArrayElement; - const std::vector* values = nullptr; + std::span held; if constexpr (Traits::optional) { if (!(record.*field.member)) return nb::none(); - values = &*(record.*field.member); + held = *(record.*field.member); } else { - values = &(record.*field.member); + held = record.*field.member; } + const auto* values = &held; std::vector shape{values->size()}; if constexpr (N == 0 && HasShapes) { const auto found = record.shapes.find(field.name); diff --git a/native/src/solprop_native/backend.py b/native/src/solprop_native/backend.py index e72f8b142..fa4a9b0bc 100644 --- a/native/src/solprop_native/backend.py +++ b/native/src/solprop_native/backend.py @@ -97,6 +97,7 @@ node_kerr_tensor, ) from solprop.translate.linop import ( + delta_phi, power_weight_at, unitary_phase, ) @@ -811,6 +812,18 @@ def _unitary_phase(self, bundle: StageScalars) -> RealArray: return unitary_phase(self._problem.linear, bundle.z1) return np.imag(combine(bundle.phi_at, self._terms.phi)) + def _delta_phi(self, bundle: StageScalars) -> ComplexArray: + """Return the stage's exponent formed on the host from the native terms. + + The bundle's weights over the fixed terms, or the operator's own increment where + it has none (a z table's, which the workspace holds in its slots). + """ + 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 _stage_scalars(self, z0: float, z1: float) -> StageScalars: """Return one stage's scalars (`StageCache.scalars`).""" return self._stages.scalars(z0, z1) diff --git a/native/src/workspace.cpp b/native/src/workspace.cpp index 0750897ac..cbab71a08 100644 --- a/native/src/workspace.cpp +++ b/native/src/workspace.cpp @@ -923,7 +923,10 @@ std::unique_ptr Workspace::probe(RunStart start) { // Adams workspace's probe takes Runge-Kutta trials, which read none of them. if (kind() != MethodKind::adams) configure_march(start.records); - return probe(std::move(start.field), std::move(start.noise), start.records.planes.z); + // The probe keeps the start to load again after a read-back: its own copy. + return probe(std::vector(start.field.begin(), start.field.end()), + std::vector(start.noise.begin(), start.noise.end()), + start.records.planes.z); } stage::Trial Workspace::stage_trial(const double z0, const double z1) { diff --git a/native/tests/test_session_failure.py b/native/tests/test_session_failure.py index a3fd0e517..87ad3fc1b 100644 --- a/native/tests/test_session_failure.py +++ b/native/tests/test_session_failure.py @@ -46,7 +46,10 @@ def test_an_unresolved_launch_statistic_ends_the_run_as_a_convergence_error( payload.plasma.envelope_rule_nodes = nodes def corrupt_payload(*args: object, **keywords: object) -> _core.Problem: - return payload + # The backend's own lowering, its set-once data included, with the bad rule. + built = _lower(*args, **keywords) # pyright: ignore[reportArgumentType] + built.plasma.envelope_rule_nodes = nodes + return built monkeypatch.setattr(adapter, "_lower", corrupt_payload) owner = NativeBackend( diff --git a/tests/driver/test_scan_stop_progress.py b/tests/driver/test_scan_stop_progress.py index a869b7d59..77017b885 100644 --- a/tests/driver/test_scan_stop_progress.py +++ b/tests/driver/test_scan_stop_progress.py @@ -262,8 +262,10 @@ def test_local_stop_mid_point_is_not_committed_and_a_rerun_computes_it(tmp_path) @pytest.mark.skipif("native" not in available(), reason="native is not installed") def test_local_stop_reaches_a_one_plane_native_adams_point(tmp_path): - native = pytest.importorskip("solprop_native.session") - most = native.CALL_ATTEMPTS + pytest.importorskip("solprop_native.session") + from solprop.backends import records # noqa: PLC0415 + + most = records.CALL_ATTEMPTS def build(point): # More steps than a native call's bound, and no plane until the last of them. diff --git a/tests/sessions/test_native_session.py b/tests/sessions/test_native_session.py index 6bdf670f2..18b22e7f7 100644 --- a/tests/sessions/test_native_session.py +++ b/tests/sessions/test_native_session.py @@ -638,8 +638,11 @@ def test_a_full_chunk_buffer_yields_and_changes_nothing(monkeypatch): problem, run_request = _case(rtol=1e-12, step_planes=0, period=1, dz_init=1e-2) request = run_request baseline = drive(_native_session(problem, request), export=CONSUMER) - monkeypatch.setattr(native_session, "ATTEMPT_CAPACITY", 3) - monkeypatch.setattr(native_session, "ROW_CAPACITY", 2) + # The plane plan's buffers, which the run records size (SEP 52 phase 2). + from solprop.backends import records # noqa: PLC0415 + + monkeypatch.setattr(records, "ATTEMPT_CAPACITY", 3) + monkeypatch.setattr(records, "ROW_CAPACITY", 2) run = drive(_native_session(problem, request), export=CONSUMER) assert_same_run(run, baseline) chunks = [ From 877da66c8a2a8c04a005e1c6586a8499e76ab4cf Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 05:08:31 +0000 Subject: [PATCH 13/29] perf(native): a run reads the workspace's live counters, not its diagnostics Workspace.counters() returns the on-axis scans, the Runge-Kutta stage evaluations and the z-table positions alone; a session's start and close read the axis scans from it instead of the whole diagnostics record (92 us each on an EPYC 7763 at 32 threads). Co-Authored-By: Claude Opus 5.5 --- native/src/bindings.cpp | 11 +++++++++++ native/src/solprop_native/_core.pyi | 1 + native/src/solprop_native/session.py | 4 ++-- 3 files changed, 14 insertions(+), 2 deletions(-) diff --git a/native/src/bindings.cpp b/native/src/bindings.cpp index 4c044b9c8..0061082e6 100644 --- a/native/src/bindings.cpp +++ b/native/src/bindings.cpp @@ -1759,6 +1759,16 @@ class BoundWorkspace final : public Owned { : std::vector{}; return out; } + // The live counters alone, cheap enough to read at every run's start and close: the + // on-axis row scans, the Runge-Kutta stage evaluations and the z-table positions. + [[nodiscard]] nb::dict counters() const { + const auto& state = workspace_->built(); + nb::dict out; + out["axis_scans"] = state.axis_scans(); + out["rk_source_evaluations"] = state.rk_source_evaluations(); + out["table_evaluations"] = workspace_->z_slots().evaluations; + return out; + } [[nodiscard]] bool closed() const noexcept { return workspace_->closed(); } // Closes a session or probe that leases the workspace first. Python-free: the runtime // calls it at shutdown, after the interpreter. @@ -3821,6 +3831,7 @@ NB_MODULE(_core, module_) { nb::sig("def probe(self, start: collections.abc.Mapping[str, object], " "host_source: object | None = None) -> Probe")) .def("diagnostics", &BoundWorkspace::diagnostics) + .def("counters", &BoundWorkspace::counters) .def_prop_ro("closed", &BoundWorkspace::closed) .def("close", &BoundWorkspace::close_from_python); module_.def("configure_runtime", &configure_runtime, "record"_a, diff --git a/native/src/solprop_native/_core.pyi b/native/src/solprop_native/_core.pyi index ca1804cf9..542ca1f9a 100644 --- a/native/src/solprop_native/_core.pyi +++ b/native/src/solprop_native/_core.pyi @@ -603,6 +603,7 @@ class Workspace: self, start: Mapping[str, object], host_source: object | None = None ) -> Probe: ... def diagnostics(self) -> dict[str, Any]: ... + def counters(self) -> dict[str, Any]: ... @property def closed(self) -> bool: ... def close(self) -> None: ... diff --git a/native/src/solprop_native/session.py b/native/src/solprop_native/session.py index c6064f762..4665dcf8b 100644 --- a/native/src/solprop_native/session.py +++ b/native/src/solprop_native/session.py @@ -529,7 +529,7 @@ def __init__( driver = self._driver(backend) # The on-axis row scans this session's statistics make: the workspace's # count, less what earlier runs on the backend made (SEP 19). - self._axis_scans = int(driver._diagnostics()["axis_scans"]) + self._axis_scans = int(driver._workspace.counters()["axis_scans"]) with _envelope_errors(): self._native = driver._take_workspace().start( run, host_source=driver._host_source @@ -1222,7 +1222,7 @@ def _axis_scan_count(self) -> int: if backend is None or backend.closed: return self._axis_scans_closed try: - scans = int(backend._diagnostics()["axis_scans"]) # pyright: ignore[reportPrivateUsage] + scans = int(backend._workspace.counters()["axis_scans"]) # pyright: ignore[reportPrivateUsage] except RuntimeError: # The state was closed under the session. return self._axis_scans_closed From 2402d86229a36d46d4607dd543ad21d11ab27ce4 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 05:31:00 +0000 Subject: [PATCH 14/29] perf(native): read a record in one pass, by interned names and cached types A run's records cross at every start, so the converter's cost is a run's: it read each record twice (a check pass, then a copy), asked every number's type for its module and name by string to rule out NumPy's bool, looked each field up by a fresh name string, rebuilt a dataclass's field names, and formed every array refusal's text before checking. It now reads once into a record a refusal discards, compares the type with NumPy's bool type looked up once, gets fields by interned names, holds each dataclass type's names and its checked table, and words a refusal only when it raises. RunRecords' round trip went 16.9 -> 6.3 us and a workspace's start and close 26.4 -> 16.5 us on an Apple M5 Max. The benchmark worker's window can take the whole run, the load included (SOLPROP_BENCHMARK_WINDOW=run, for ab's per-arm environment): a build that loads the state in the session's start then times the same work as one that loads it before. The recorded history's window is unchanged. Co-Authored-By: Claude Opus 5.5 --- benchmarks/worker.py | 13 ++++++ native/src/records.cpp | 97 +++++++++++++++++++++++++++++++++--------- native/src/records.hpp | 37 +++++++++++----- 3 files changed, 116 insertions(+), 31 deletions(-) diff --git a/benchmarks/worker.py b/benchmarks/worker.py index c241c2760..65298ae64 100644 --- a/benchmarks/worker.py +++ b/benchmarks/worker.py @@ -22,6 +22,7 @@ import importlib import importlib.metadata import logging +import os import shutil import sys import tempfile @@ -45,6 +46,7 @@ __all__ = [ "HOST_SPACES", "SNAPSHOT_CAPACITY", + "WINDOW_SETTING", "Diagnostics", "count", "emit", @@ -242,6 +244,12 @@ def __exit__(self, kind: type[BaseException] | None, *rest: object) -> None: raise SuiteError(msg) +WINDOW_SETTING = "SOLPROP_BENCHMARK_WINDOW" +"""``run`` times a run from before its load (``ab --baseline-env`` and +``--candidate-env``); unset, the window starts once the backend's load returns, as the +recorded history's does.""" + + def timed_run( simulation: Simulation, problem: PropagationProblem, @@ -311,6 +319,11 @@ def timed_run( problem, engine, handler, start=Start.entrance(problem), **observed ) before, loaded_at = loaded.calls, loaded.ended + if os.environ.get(WINDOW_SETTING) == "run": + # The whole run, its load included: two builds that load the state at + # different points (before the session, or in its start) then time the + # same work. The history's window stays the default. + loaded_at = began ended = time.perf_counter_ns() seconds = (ended - loaded_at) * 1e-9 after = source_calls(engine) diff --git a/native/src/records.cpp b/native/src/records.cpp index fa06094f3..5c3f7839e 100644 --- a/native/src/records.cpp +++ b/native/src/records.cpp @@ -7,7 +7,10 @@ #include #include +#include +#include #include +#include namespace solprop_native::records { @@ -30,12 +33,12 @@ std::string child(const std::string& path, const std::size_t index) { bool is_bool(const nb::handle value) { if (PyBool_Check(value.ptr())) return true; - // NumPy's bool scalar. - const auto type = - nb::borrow(reinterpret_cast(Py_TYPE(value.ptr()))); - return nb::hasattr(type, "__module__") && - nb::cast(nb::str(type.attr("__module__"))) == "numpy" && - nb::cast(nb::str(type.attr("__name__"))) == "bool"; + // NumPy's bool scalar, its type looked up once (under the interpreter lock, which + // every conversion holds): asking each number's type for its module and name by + // string cost most of a run record's conversion. + static PyObject* const numpy_bool = + nb::object(nb::module_::import_("numpy").attr("bool_")).release().ptr(); + return reinterpret_cast(Py_TYPE(value.ptr())) == numpy_bool; } bool is_integer(const nb::handle value) { return PyIndex_Check(value.ptr()) != 0; } @@ -56,13 +59,59 @@ bool is_mapping(const nb::handle value) { !is_sequence(value)); } +namespace { + +/** A dataclass type's field names, read once a type and held for the process (types are + long-lived; the cache holds a reference to each). Under the interpreter lock. */ +const std::vector* dataclass_names(PyTypeObject* type) { + static std::map> cache; + const auto found = cache.find(type); + if (found != cache.end()) + return &found->second; + const auto handle = nb::handle(reinterpret_cast(type)); + std::vector names; + for (const auto key : + nb::borrow(handle.attr("__dataclass_fields__")).keys()) + names.push_back(nb::cast(key)); + Py_INCREF(handle.ptr()); + return &cache.emplace(type, std::move(names)).first->second; +} + +/** A field name as an interned Python string, made once a name (the names are the + tables' literals, so their addresses identify them). */ +PyObject* interned(const char* name) { + static std::map cache; + const auto found = cache.find(name); + if (found != cache.end()) + return found->second; + PyObject* text = PyUnicode_InternFromString(name); + if (text == nullptr) + throw nb::python_error(); + return cache.emplace(name, text).first->second; +} + +std::set>& checked_pairs() { + static std::set> pairs; + return pairs; +} + +} // namespace + +bool checked(PyTypeObject* type, const char* table) { + return checked_pairs().contains({type, table}); +} + +void mark_checked(PyTypeObject* type, const char* table) { + checked_pairs().insert({type, table}); +} + Source::Source(const nb::handle value, const std::string& path) : value_(value) { - const auto type = nb::handle(reinterpret_cast(Py_TYPE(value.ptr()))); - if (nb::hasattr(type, "__dataclass_fields__") && - !nb::isinstance(value)) { - for (const auto key : - nb::borrow(type.attr("__dataclass_fields__")).keys()) - names_.push_back(nb::cast(key)); + PyTypeObject* type = Py_TYPE(value.ptr()); + if (PyType_HasFeature(type, Py_TPFLAGS_TYPE_SUBCLASS) == 0 && + PyObject_HasAttrString(reinterpret_cast(type), + "__dataclass_fields__") != 0) { + dataclass_ = true; + names_ = dataclass_names(type); return; } if (is_mapping(value)) { @@ -73,7 +122,7 @@ Source::Source(const nb::handle value, const std::string& path) : value_(value) for (const auto key : nb::steal(keys)) { if (!nb::isinstance(key)) type_refusal(path, "must have str keys"); - names_.push_back(nb::cast(key)); + owned_.push_back(nb::cast(key)); } return; } @@ -88,7 +137,7 @@ Source::Source(const nb::handle value, const std::string& path) : value_(value) bool Source::has(const char* name, const std::size_t index) const { if (positional_) return index < size_; - for (const auto& entry : names_) + for (const auto& entry : *names_) if (entry == name) return true; return false; @@ -99,7 +148,10 @@ nb::object Source::get(const char* name, const std::size_t index) const { return nb::borrow(value_)[index]; if (mapping_) return value_[name]; - return value_.attr(name); + PyObject* found = PyObject_GetAttr(value_.ptr(), interned(name)); + if (found == nullptr) + throw nb::python_error(); + return nb::steal(found); } namespace { @@ -146,20 +198,23 @@ std::string shape_text(const std::vector& shape) { Borrowed borrow(const nb::handle value, const fields::Dtype dtype, const std::size_t rank, const std::string& path) { using Any = nb::ndarray; - const std::string wanted = fields::dtype_name(dtype); - const std::string axes = rank == 0 ? "" : " of rank " + std::to_string(rank); + // The refusals' wording, formed only when one is raised. + const auto wanted = [dtype] { return std::string(fields::dtype_name(dtype)); }; + const auto axes = [rank] { + return rank == 0 ? std::string() : " of rank " + std::to_string(rank); + }; Any array; if (!nb::try_cast(value, array, false)) - type_refusal(path, "must be a C-contiguous " + wanted + " array" + axes); + type_refusal(path, "must be a C-contiguous " + wanted() + " array" + axes()); if (array.dtype() != numpy_dtype(dtype)) - type_refusal(path, "must be a C-contiguous " + wanted + " array" + axes + + type_refusal(path, "must be a C-contiguous " + wanted() + " array" + axes() + ", not another dtype"); Borrowed out; out.shape.resize(array.ndim()); for (std::size_t axis = 0; axis < array.ndim(); ++axis) out.shape[axis] = array.shape(axis); if (rank != 0 && array.ndim() != rank) - value_refusal(path, "must be a C-contiguous " + wanted + " array" + axes + + value_refusal(path, "must be a C-contiguous " + wanted() + " array" + axes() + ", given shape " + shape_text(out.shape)); // C order, element strides: an axis of one may take any stride; a stride of zero // elsewhere is an overlapping (broadcast) view. @@ -171,7 +226,7 @@ Borrowed borrow(const nb::handle value, const fields::Dtype dtype, for (std::size_t axis = array.ndim(); axis-- > 0;) { const std::size_t size = out.shape[axis]; if (!empty && size != 1 && array.stride(axis) != static_cast(count)) - value_refusal(path, "must be a C-contiguous " + wanted + " array" + axes + + value_refusal(path, "must be a C-contiguous " + wanted() + " array" + axes() + ", not a strided or overlapping view"); if (size != 0 && count > std::numeric_limits::max() / size) value_refusal(path, "has a size whose product overflows"); diff --git a/native/src/records.hpp b/native/src/records.hpp index fb9205501..0140b2d7c 100644 --- a/native/src/records.hpp +++ b/native/src/records.hpp @@ -30,11 +30,14 @@ * (`solprop_native/fields.hpp`) and writes the record back as a dictionary, and the * schema export of every table. * - * Reading takes two passes over the input, both under the interpreter lock: the first - * checks every field -- a missing or unknown field, a wrong type or dtype, an array - * that is not C-contiguous or overlaps itself, a wrong rank, extents that disagree with - * their relations, a size whose product overflows -- and allocates nothing; the second - * copies each value into the record's own storage. Inputs are borrowed for the call: + * Reading takes one pass over the input, under the interpreter lock, into a new + * record: each field is checked -- a missing or unknown field, a wrong type or dtype, + * an array that is not C-contiguous or overlaps itself, a wrong rank, extents that + * disagree with their relations, a size whose product overflows -- before its value is + * copied, and a refusal discards the record, so nothing reaches native state from a + * malformed one. A dataclass type's field names are read once and held, and each field + * is looked up by an interned name, since a run's records cross at every start. Inputs + * are borrowed for the call: * read-only arrays are admitted, since nothing writes them. A refusal names the * field's path (`run.records.planes.planes`). Arrays written back own their storage * through a capsule. @@ -69,7 +72,11 @@ class Source { [[nodiscard]] bool has(const char* name, std::size_t index) const; [[nodiscard]] nb::object get(const char* name, std::size_t index) const; /** The given names (empty for a tuple). */ - [[nodiscard]] const std::vector& names() const { return names_; } + [[nodiscard]] const std::vector& names() const { return *names_; } + /** Whether the input is a dataclass instance, whose type's fields were read once. */ + [[nodiscard]] bool dataclass() const { return dataclass_; } + /** The input's type. */ + [[nodiscard]] PyTypeObject* type() const { return Py_TYPE(value_.ptr()); } [[nodiscard]] bool positional() const { return positional_; } [[nodiscard]] std::size_t size() const { return size_; } @@ -78,7 +85,10 @@ class Source { bool positional_ = false; bool mapping_ = false; std::size_t size_ = 0; - std::vector names_; + bool dataclass_ = false; + // A dataclass type's names, held for the process; a mapping's, owned here. + const std::vector* names_ = &owned_; + std::vector owned_; }; /** A checked array: its data, shape and dtype, borrowed for the conversion. */ @@ -164,6 +174,12 @@ template std::vector table_names() { return out; } +/** Whether a dataclass type was already found to name exactly the fields of the table + named `table`, a pointer that identifies it (one conversion checks each pair once). + */ +[[nodiscard]] bool checked(PyTypeObject* type, const char* table); +void mark_checked(PyTypeObject* type, const char* table); + /** Whether `source` names exactly `R`'s fields (every one, nothing else). */ template bool matches(const Source& source) { const auto wanted = table_names(); @@ -402,7 +418,7 @@ template void read_record(nb::handle value, R* out, const std::string& value_refusal(path, std::string("is a ") + table.name + " of " + std::to_string(wanted.size()) + " fields, given " + std::to_string(source.size())); - } else { + } else if (!source.dataclass() || !checked(source.type(), table.name)) { for (const auto& name : source.names()) { bool known = false; for (const char* entry : wanted) @@ -411,6 +427,8 @@ template void read_record(nb::handle value, R* out, const std::string& value_refusal(path, std::string("has an unknown field '") + name + "' for a " + table.name); } + if (source.dataclass()) + mark_checked(source.type(), table.name); } Symbols symbols; std::size_t index = 0; @@ -489,9 +507,8 @@ template void read_record(nb::handle value, R* out, const std::string& }); } -/** Read `value` into a new `R`: check everything, then copy. */ +/** Read `value` into a new `R`, which a refusal discards. */ template R read(nb::handle value, const std::string& path) { - read_value(value, static_cast(nullptr), path); R out{}; read_value(value, &out, path); return out; From 2ead06656e3f0ab4cf68290f5aaf883e441a53b7 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 05:54:23 +0000 Subject: [PATCH 15/29] perf(native): per-plane metadata and cap reads stop draining the state (SEP 52) A run records its execution metadata at every plane and reads the split collar's cap at every batch. The metadata read the whole diagnostics record each time (58 us on an EPYC 7763: the memory ledger, the CPU record, the planning); it now reads the workspace's facts once it is built and only its live counters (Workspace.counters, which gains the Raman transforms and the recycled stage) after. Session.records takes the names it is asked for, so the cap alone no longer drains the quadrature peak with a fence or converts the monitor's record, and a run without a monitor reads no cap at all; the monitor's record leaves the peak to the alarm's check. Co-Authored-By: Claude Opus 5.5 --- native/src/bindings.cpp | 49 +++++++++++++++++++--------- native/src/solprop_native/_core.pyi | 2 +- native/src/solprop_native/backend.py | 6 +++- native/src/solprop_native/session.py | 25 ++++++++------ 4 files changed, 55 insertions(+), 27 deletions(-) diff --git a/native/src/bindings.cpp b/native/src/bindings.cpp index 0061082e6..d07f93d8f 100644 --- a/native/src/bindings.cpp +++ b/native/src/bindings.cpp @@ -1373,26 +1373,40 @@ class BoundSession { // SEP 52: every record the session keeps, in one, each read under the session's // lock: the monitor's and the edge's (None without them), the split collar's cap // (None without one) and the quadrature peak, drained since the last read. - nb::dict records() { + nb::dict records(const std::optional>& names) { + // Only the records asked for: the quadrature peak drains the state's score with a + // fence, and the monitor's record is a dictionary of its every number, so a reader + // that wants the cap alone (at every batch) takes neither. + const auto wanted = [&names](const char* name) { + return !names || std::ranges::find(*names, name) != names->end(); + }; std::optional monitor; std::optional> edge; std::optional cap; - double peak = 0.0; + std::optional peak; { const nb::gil_scoped_release release; - monitor = session().monitor_record(); - edge = session().edge_record(); - cap = session().monitor_cap(); - peak = session().quadrature_peak(); + if (wanted("monitor")) + monitor = session().monitor_record(); + if (wanted("edge")) + edge = session().edge_record(); + if (wanted("cap")) + cap = session().monitor_cap(); + if (wanted("quadrature_peak")) + peak = session().quadrature_peak(); } nb::dict out; - out["monitor"] = monitor ? nb::object(watch_record_to(*monitor)) : nb::none(); - out["edge"] = edge ? nb::object(native::bindings::transverse_record_to( - edge->first, edge->second)) - : nb::none(); - out["cap"] = cap ? nb::object(nb::float_(*cap)) : nb::none(); - out["quadrature_peak"] = peak; + if (wanted("monitor")) + out["monitor"] = monitor ? nb::object(watch_record_to(*monitor)) : nb::none(); + if (wanted("edge")) + out["edge"] = edge ? nb::object(native::bindings::transverse_record_to( + edge->first, edge->second)) + : nb::none(); + if (wanted("cap")) + out["cap"] = cap ? nb::object(nb::float_(*cap)) : nb::none(); + if (peak) + out["quadrature_peak"] = *peak; return out; } // solprop SEP 47 section 5.5: the Adams march's state with the orders of its @@ -1759,14 +1773,17 @@ class BoundWorkspace final : public Owned { : std::vector{}; return out; } - // The live counters alone, cheap enough to read at every run's start and close: the - // on-axis row scans, the Runge-Kutta stage evaluations and the z-table positions. + // The live counters alone, cheap enough to read at every run's start and close and + // every plane's metadata: the on-axis row scans, the Runge-Kutta stage evaluations, + // the z-table positions, the Raman kernel's transforms and the recycled stage. [[nodiscard]] nb::dict counters() const { const auto& state = workspace_->built(); nb::dict out; out["axis_scans"] = state.axis_scans(); out["rk_source_evaluations"] = state.rk_source_evaluations(); out["table_evaluations"] = workspace_->z_slots().evaluations; + out["raman_kernel_transforms"] = state.raman_kernel_transforms(); + out["fsal_ready"] = state.fsal_ready(); return out; } [[nodiscard]] bool closed() const noexcept { return workspace_->closed(); } @@ -3804,7 +3821,9 @@ NB_MODULE(_core, module_) { "typing.Any], numpy.typing.NDArray[numpy.complex128], dict[str, " "numpy.typing.NDArray[numpy.complex128]]] | None")) .def("noise_phase", &BoundSession::noise_phase, "ticket"_a, "z"_a) - .def("records", &BoundSession::records) + .def("records", &BoundSession::records, "names"_a.none() = nb::none(), + nb::sig("def records(self, names: collections.abc.Sequence[str] | None = " + "None) -> dict[str, typing.Any]")) .def("continue_monitor", &BoundSession::continue_monitor, "continuation"_a, nb::sig("def continue_monitor(self, continuation: " "solprop.backends.records.MonitorContinuation) -> None")) diff --git a/native/src/solprop_native/_core.pyi b/native/src/solprop_native/_core.pyi index 542ca1f9a..7b6bf66cb 100644 --- a/native/src/solprop_native/_core.pyi +++ b/native/src/solprop_native/_core.pyi @@ -494,7 +494,7 @@ class Session: def noise_phase( self, ticket: tuple[int, int], z: float ) -> npt.NDArray[np.complex128]: ... - def records(self) -> dict[str, Any]: ... + def records(self, names: Sequence[str] | None = None) -> dict[str, Any]: ... def continue_monitor( self, continuation: solprop.backends.records.MonitorContinuation ) -> None: ... diff --git a/native/src/solprop_native/backend.py b/native/src/solprop_native/backend.py index fa4a9b0bc..1c7fc95cb 100644 --- a/native/src/solprop_native/backend.py +++ b/native/src/solprop_native/backend.py @@ -447,6 +447,9 @@ def __init__( self._applied_execution = ExecutionRecord.from_native( diagnostics["cpu_execution"] ) + # The workspace's facts that its build fixes, for every metadata record; its + # counters are read live (`Workspace.counters`). + self._facts: dict[str, Any] = dict(diagnostics) # solprop SEP 49: the TDSE response is the march's host source, handed to each # run and probe; the driver owns the binding and closes it. self._tdse_binding = tdse_binding @@ -975,7 +978,8 @@ def metadata(self) -> dict[str, object]: (:func:`_build_facts`); the native state's counters are read at every call. """ facts = _build_facts() - native = self._diagnostics() + # The workspace's fixed facts, read once it was built, and its live counters. + native = self._facts | self._workspace.counters() work: dict[str, object] = { "backend": self.name, "propagator_mode": self._propagator_mode, diff --git a/native/src/solprop_native/session.py b/native/src/solprop_native/session.py index 4665dcf8b..7ea7fa907 100644 --- a/native/src/solprop_native/session.py +++ b/native/src/solprop_native/session.py @@ -832,7 +832,7 @@ def _check_quadrature(self, event: Event) -> None: """ if self.closed: return - self._native_records() + self._native_records("quadrature_peak") peak, self._pending_peak = self._pending_peak, math.nan if peak > QUADRATURE_ALARM and not self._alarm_reported: self._alarm_reported = True @@ -840,13 +840,16 @@ def _check_quadrature(self, event: Event) -> None: if isinstance(event, ObservationReady): self._alarm_reported = False - def _native_records(self) -> dict[str, Any]: - """Return the native session's records (``Session.records``). + def _native_records(self, *names: str) -> dict[str, Any]: + """Return the native session's records (``Session.records``), `names` or all. - Each read drains the quadrature peak the state kept since the last, which is - held here until the next alarm check (`_check_quadrature`) and for the record. + A read that takes the quadrature peak drains the score the state kept since the + last, which is held here until the next alarm check (`_check_quadrature`) and + for the record. """ - records = cast("dict[str, Any]", self._native.records()) + records = cast("dict[str, Any]", self._native.records(list(names) or None)) + if "quadrature_peak" not in records: + return records peak = float(records["quadrature_peak"]) if not math.isnan(peak): if not peak <= self._quadrature_peak: @@ -867,7 +870,7 @@ def _translate( chunk = self._history(batch.attempts) rows = self._chunk_rows(batch) if not self._declared_logged: - edge = self._native_records()["edge"] + edge = self._native_records("edge")["edge"] self._declared_logged = edge is None or _transverse.log_declared(edge) return chunk, self._event(batch, receipt, chunk, rows) @@ -1262,7 +1265,7 @@ def monitor_record(self) -> Mapping[str, object] | None: monitor = self._monitor if monitor is None: return None - records = self._native_records() + records = self._native_records("monitor", "edge") native = records["monitor"] if native is None: return None @@ -1286,7 +1289,9 @@ def monitor_cap(self) -> float: float The cap, m. """ - cap = self._native_records()["cap"] + if self._monitor is None: + return math.inf + cap = self._native_records("cap")["cap"] return math.inf if cap is None else float(cap) def continue_monitor(self, continuation: Mapping[str, object]) -> None: @@ -1755,7 +1760,7 @@ def _log_finish(self) -> None: if self._finish_logged or self._monitor is None: return self._finish_logged = True - records = self._native_records() + records = self._native_records("monitor", "edge") edge = records["edge"] if edge is not None: _transverse.log_finish(edge) From a65c96ad99dff9f6e61ccdc3d0d57f6db4eb3f6e Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 06:45:04 +0000 Subject: [PATCH 16/29] test: engine-level parity over both backends' engines; records by name (SEP 52) - tests/backends/test_engine_parity.py: each case written once against RungeKuttaEngine or AdamsEngine and played on both backends' engines (tests/engine_pairs.py: the reference's own engines over its workspace, native's through _testing.engines): rejected and accepted Runge-Kutta trials, the first step's stage registers, the split collar's sums in AcceptRecord and the boundary reading; a dense extension; the low-storage in-flight interval; and the reference march's own Adams calls replayed on the interaction formulation with transported history, the exponential one and the carrier frame (step_carrier, chord_phase). SEP 25 budgets from march_bounds, each term held clear of its bound. - The tests found native's protocol records two-dimensional (occupancy, the Adams norms, the carrier rotations): one-dimensional now. _testing.engines gives a dense configuration's Runge-Kutta engine its extension holder (Workspace::trial_engine(dense), which the session's method now shares). - The estimate's native trial and the whole-trial norm test go through the engines. - The converter reads an enumeration by its name only; the Adams march's history crosses with its identities named, and the watch state is written by its table. [skip ci] Co-Authored-By: Claude Opus 5.5 --- native/include/solprop_native/workspace.hpp | 11 +- native/src/bindings.cpp | 62 ++-- native/src/records.hpp | 7 +- native/src/solprop_native/_core_testing.pyi | 2 +- native/src/solprop_native/backend.py | 3 +- native/src/solprop_native/session.py | 4 +- native/src/workspace.cpp | 36 +- native/tests/test_workspace.py | 17 + tests/backends/native_trace_marches.py | 6 +- tests/backends/test_engine_parity.py | 366 ++++++++++++++++++++ tests/backends/test_native_error_norm.py | 13 +- tests/driver/test_estimate.py | 16 +- tests/engine_pairs.py | 332 ++++++++++++++++++ 13 files changed, 798 insertions(+), 77 deletions(-) create mode 100644 tests/backends/test_engine_parity.py create mode 100644 tests/engine_pairs.py diff --git a/native/include/solprop_native/workspace.hpp b/native/include/solprop_native/workspace.hpp index a66cda909..b1948030f 100644 --- a/native/include/solprop_native/workspace.hpp +++ b/native/include/solprop_native/workspace.hpp @@ -730,8 +730,15 @@ class Workspace { /** The z table's `Phi` at `z`, through the one slot cache, for `holder`. */ std::vector table_phi(const void* holder, double z); /** The configured march's engines over the state, for an engine-level test: the - Runge-Kutta (or low-storage) engine and the Adams engine. */ - std::unique_ptr trial_engine(); + Runge-Kutta (or low-storage) engine and the Adams engine. With `dense`, a + Runge-Kutta engine's extensions go to a dense output it holds there, as a dense + run's do. */ + std::unique_ptr + trial_engine(std::unique_ptr* dense = nullptr); + /** Whether the configured Runge-Kutta trial has the tableau's dense weights. */ + [[nodiscard]] bool extends() const noexcept { + return !low_storage_ && runge_kutta_ && !runge_kutta_->dense_weights.empty(); + } /** The low-storage replay's engine over the state, its type kept for a test that reads its squared norms. */ std::unique_ptr low_storage_engine(); diff --git a/native/src/bindings.cpp b/native/src/bindings.cpp index d07f93d8f..766c3df45 100644 --- a/native/src/bindings.cpp +++ b/native/src/bindings.cpp @@ -810,6 +810,18 @@ ComplexOutput complex_buffer_output(native::crossing::HostBuffer storage, owner}; } +/** `values` as a one-dimensional array that owns them. */ +RealOutput vector_output(std::vector values) { + auto storage = std::make_unique(std::move(values)); + auto* pointer = storage.get(); + nb::capsule owner(pointer, [](void* value) noexcept { + const std::unique_ptr held(static_cast(value)); + }); + static_cast(storage.release()); // the capsule owns it now + const std::array shape{pointer->size()}; + return {pointer->data(), shape.size(), shape.data(), owner}; +} + RealOutput real_output(std::vector values, const std::size_t rows) { if (rows == 0 || values.size() % rows != 0) throw std::invalid_argument("native output has an invalid packed shape"); @@ -873,16 +885,7 @@ native::watch::State watch_state_from(const nb::dict values) { } nb::dict watch_state_to(const native::watch::State& state) { - nb::dict out; - out["has_last"] = state.has_last; - out["last_z"] = state.last_z; - out["since"] = state.since; - out["busy"] = state.busy; - out["quiet_run"] = state.quiet_run; - out["quiet"] = state.quiet; - out["warned"] = state.warned; - out["cap"] = state.cap; - return out; + return native::records::write_record(state); } // solprop SEP 47 section 6.4: the owning boundary monitor's configuration, the record @@ -999,14 +1002,9 @@ march::State march_state_from(const nb::dict values) { state.last_rejected = nb::cast(values["last_rejected"]); state.collar_was_quiet = nb::cast(values["collar_was_quiet"]); state.cursor = nb::cast(values["cursor"]); - for (const auto entry : nb::cast(values["history"])) { - const auto parts = nb::cast(entry); - state.history.push_back({.z = nb::cast(parts[0]), - .identity = nb::cast(parts[1]) - ? march::Identity::predicted - : march::Identity::accepted, - .row = nb::cast(parts[2])}); - } + for (const auto entry : nb::cast(values["history"])) + state.history.push_back( + native::records::read(entry, "state.history")); const auto ledger = nb::cast(values["ledger"]); state.ledger.startup = nb::cast(ledger["startup"]); state.ledger.predictor = nb::cast(ledger["predictor"]); @@ -1038,7 +1036,7 @@ nb::dict march_state_to(const march::State& state) { out["cursor"] = state.cursor; nb::list history; for (const auto& entry : state.history) - history.append(nb::make_tuple(entry.z, entry.identity == march::Identity::predicted, + history.append(nb::make_tuple(entry.z, native::records::write_value(entry.identity), entry.row)); out["history"] = history; nb::dict ledger; @@ -2369,9 +2367,10 @@ class TestEngines { workspace.require_unleased(); // Each engine the workspace's configuration makes; one it cannot make is absent. try { - runge_kutta_ = workspace.trial_engine(); + runge_kutta_ = workspace.trial_engine(workspace.extends() ? &dense_ : nullptr); } catch (const std::logic_error&) { runge_kutta_.reset(); + dense_.reset(); } try { adams_ = workspace.adams_engine(); @@ -2390,6 +2389,7 @@ class TestEngines { if (owner_ == nullptr) return; runge_kutta_.reset(); + dense_.reset(); adams_.reset(); owner_->release(this); owner_ = nullptr; @@ -2434,6 +2434,8 @@ class TestEngines { private: native::Workspace* owner_; + /** Where a dense configuration's Runge-Kutta engine holds its extensions. */ + std::unique_ptr dense_; std::unique_ptr runge_kutta_; std::unique_ptr adams_; }; @@ -2449,9 +2451,8 @@ nb::object accept_record(native::GeneralState& state) { if (!sums) return engines_module().attr("AcceptRecord")(); const std::vector found(sums->begin() + 1, sums->end()); - return engines_module().attr("AcceptRecord")( - "removed"_a = (*sums)[0], - "found"_a = nb::cast(real_output(found, 1)).attr("reshape")(-1)); + return engines_module().attr("AcceptRecord")("removed"_a = (*sums)[0], + "found"_a = vector_output(found)); } nb::object boundary_reading(const std::vector& values) { @@ -2460,11 +2461,10 @@ nb::object boundary_reading(const std::vector& values) { const std::vector regions(values.begin() + 1, values.begin() + 5); nb::object occupancy = nb::none(); if (values.size() > native::watch::reading_head) - occupancy = nb::cast(real_output( - std::vector(values.begin() + native::watch::reading_head, values.end()), - 1)); - return engines_module().attr("BoundaryReading")( - values[0], nb::cast(real_output(regions, 1)).attr("reshape")(-1), occupancy); + occupancy = nb::cast(vector_output(std::vector( + values.begin() + native::watch::reading_head, values.end()))); + return engines_module().attr("BoundaryReading")(values[0], vector_output(regions), + occupancy); } /** A Python `adams_core.Stencil` as the march's. */ @@ -2539,7 +2539,7 @@ void bind_engines(nb::module_& testing) { const nb::gil_scoped_release release; engine.trial(z, dz, stencil, norms.data()); } - return real_output(std::move(norms), 1); + return vector_output(std::move(norms)); }) .def( "adams_accept", @@ -2566,9 +2566,7 @@ void bind_engines(nb::module_& testing) { }) .def("adams_step_carrier", [](TestEngines& self, const std::size_t order) { - auto values = self.adams().step_carrier(order); - return values.empty() ? nb::cast(std::vector{}) - : nb::cast(real_output(std::move(values), 1)); + return vector_output(self.adams().step_carrier(order)); }) .def("adams_begin_attempt", [](TestEngines& self, const std::uint64_t cost) { diff --git a/native/src/records.hpp b/native/src/records.hpp index 0140b2d7c..dbd76b4b3 100644 --- a/native/src/records.hpp +++ b/native/src/records.hpp @@ -243,16 +243,13 @@ template void read_value(nb::handle value, T* out, const std::string& attribute = value.attr("name"); name = attribute; } + // By name only (SEP 52 section 5.3): an integer would tie the Python side to the + // C++ enumerators' values. if (nb::isinstance(name)) { const auto text = nb::cast(name); for (const auto& [label, entry] : table) if (text == label) held = entry; - } else if (is_integer(value)) { - const auto number = nb::cast(value, true); - for (const auto& [label, entry] : table) - if (static_cast(entry) == number) - held = entry; } if (!held) { std::string labels; diff --git a/native/src/solprop_native/_core_testing.pyi b/native/src/solprop_native/_core_testing.pyi index 6152cb44e..01cad1526 100644 --- a/native/src/solprop_native/_core_testing.pyi +++ b/native/src/solprop_native/_core_testing.pyi @@ -43,7 +43,7 @@ class Engines: kept: Sequence[solprop.backends.engines.HistoryEntry], ) -> solprop.backends.engines.AcceptRecord: ... def adams_chord_phase(self, arg0: float, arg1: float, /) -> float: ... - def adams_step_carrier(self, arg: int, /) -> object: ... + def adams_step_carrier(self, arg: int, /) -> npt.NDArray[np.float64]: ... def adams_begin_attempt(self, arg: int, /) -> None: ... def adams_end_attempt(self, arg: int, /) -> None: ... def adams_reading(self) -> solprop.backends.engines.BoundaryReading: ... diff --git a/native/src/solprop_native/backend.py b/native/src/solprop_native/backend.py index 1c7fc95cb..35cf320ea 100644 --- a/native/src/solprop_native/backend.py +++ b/native/src/solprop_native/backend.py @@ -1889,8 +1889,7 @@ def start_state(self, z: float, proposal: float, cursor: int) -> dict[str, objec "collar_was_quiet": self._collar_was_quiet, "cursor": int(cursor), "history": [ - (entry.z, entry.identity == "predicted", entry.slot) - for entry in self._history + (entry.z, entry.identity, entry.slot) for entry in self._history ], "ledger": {name: getattr(ledger, name) for name in _MARCH_COUNTERS}, "watch": dict(FRESH_WATCH), diff --git a/native/src/solprop_native/session.py b/native/src/solprop_native/session.py index 7ea7fa907..d9db6f63a 100644 --- a/native/src/solprop_native/session.py +++ b/native/src/solprop_native/session.py @@ -1121,9 +1121,7 @@ def march_snapshot(self, ticket: ExportTicket) -> MarchSnapshot | None: rejections=int(state["rejections"]), last_rejected=bool(state["last_rejected"]), positions=np.array([entry[0] for entry in history], dtype=np.float64), - identities=tuple( - "predicted" if entry[1] else "accepted" for entry in history - ), + identities=tuple(str(entry[1]) for entry in history), slots=np.array([entry[2] for entry in history], dtype=np.int64), rows={name: row.reshape(len(row), *shape) for name, row in rows.items()}, collar_was_quiet=bool(state["collar_was_quiet"]), diff --git a/native/src/workspace.cpp b/native/src/workspace.cpp index cbab71a08..b691acdb7 100644 --- a/native/src/workspace.cpp +++ b/native/src/workspace.cpp @@ -651,16 +651,30 @@ MethodKind Workspace::kind() const noexcept { return MethodKind::runge_kutta; } -std::unique_ptr Workspace::trial_engine() { +std::unique_ptr +Workspace::trial_engine(std::unique_ptr* const dense) { auto& general = built(); if (low_storage_) return low_storage_engine(); if (!runge_kutta_) throw std::logic_error("the native Runge-Kutta trial is not configured"); - return std::make_unique( + auto engine = std::make_unique( general, [this](const double z, const double dz) { return staged_trial(z, dz, false); }, runge_kutta_->rtol, runge_kutta_->atol, runge_kutta_->weights); + if (dense != nullptr) { + if (!stage_tables_) + throw std::logic_error("a session's dense output needs the stage tables"); + auto holder = std::make_unique( + general, *stage_tables_, stage_anchor_, runge_kutta_->dense_weights); + // The engine holds each crossing step's extension through it; the caller keeps + // both, the engine released first. + auto* held = holder.get(); + engine->set_extension( + [held](const double z, const double dz) { held->hold(z, dz); }); + *dense = std::move(holder); + } + return engine; } std::unique_ptr Workspace::low_storage_engine() { @@ -723,23 +737,7 @@ session::Method Workspace::method(const MethodKind kind, } if (!runge_kutta_) throw std::logic_error("the native Runge-Kutta march is not configured"); - auto engine = std::make_unique( - general, - [this](const double z, const double dz) { return staged_trial(z, dz, false); }, - runge_kutta_->rtol, runge_kutta_->atol, runge_kutta_->weights); - if (dense) { - if (!stage_tables_) - throw std::logic_error("a session's dense output needs the stage tables"); - auto holder = std::make_unique( - general, *stage_tables_, stage_anchor_, runge_kutta_->dense_weights); - // The engine holds each crossing step's extension through it; both live in the - // method, the engine released first. - auto* held = holder.get(); - engine->set_extension( - [held](const double z, const double dz) { held->hold(z, dz); }); - method.dense = std::move(holder); - } - method.engine = std::move(engine); + method.engine = trial_engine(dense ? &method.dense : nullptr); return method; } diff --git a/native/tests/test_workspace.py b/native/tests/test_workspace.py index dfa4382e8..3419c82ce 100644 --- a/native/tests/test_workspace.py +++ b/native/tests/test_workspace.py @@ -272,6 +272,23 @@ def test_the_converter_refuses_a_malformed_record_by_its_path( _testing.round_trip("stage.Table", table) +@pytest.mark.parametrize("kind", ["phi", 0, 1]) +def test_an_enumeration_is_read_by_its_name_only(kind: object) -> None: + # An enumerator's integer would tie the Python records to the C++ values. + table = { + "kind": kind, + "edges": np.array([0.0, 1.0]), + "lower": 0.0, + "upper": 1.0, + "coefficients": np.ones((1, 2, 3), dtype=np.complex128), + } + if isinstance(kind, str): + assert _testing.round_trip("ZTable", table)["kind"] == kind + return + with pytest.raises(ValueError, match=r"ZTable\.kind must name one of"): + _testing.round_trip("ZTable", table) + + def test_the_converter_admits_read_only_arrays_and_copies_them() -> None: table = _table() coefficients = cast(np.ndarray, table["coefficients"]) diff --git a/tests/backends/native_trace_marches.py b/tests/backends/native_trace_marches.py index e314131d4..90b748f8c 100644 --- a/tests/backends/native_trace_marches.py +++ b/tests/backends/native_trace_marches.py @@ -434,10 +434,8 @@ def _synchronise(self, result: dict[str, Any]) -> None: self._last_rejected = bool(state["last_rejected"]) self._collar_was_quiet = bool(state["collar_was_quiet"]) self._history = [ - Derivative( - float(z), None, "predicted" if predicted else "accepted", int(slot) - ) - for z, predicted, slot in state["history"] + Derivative(float(z), None, identity, int(slot)) + for z, identity, slot in state["history"] ] ledger = self.ledger for name, value in state["ledger"].items(): diff --git a/tests/backends/test_engine_parity.py b/tests/backends/test_engine_parity.py new file mode 100644 index 000000000..3021f7e81 --- /dev/null +++ b/tests/backends/test_engine_parity.py @@ -0,0 +1,366 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""Native's engines against the reference's, through solprop's engine protocols. + +SEP 52 sections 6.5 and 7: each case is written once against +:class:`~solprop.backends.engines.RungeKuttaEngine` or +:class:`~solprop.backends.engines.AdamsEngine` and played on both backends' engines +over a loaded workspace (``engine_pairs``). The Runge-Kutta case takes rejected and +accepted trials, reads the stage registers, the accept's split collar's sums and the +boundary reading; the low-storage case its in-flight interval; the Adams cases replay +the calls the reference's own march made on a run -- the startup, rejected trials, +accepts with the history they keep, the carrier chord and the step's carrier rotations +-- on the interaction formulation with transported history, the exponential one, and +the exponential one in the carrier frame. + +**Budgets** (SEP 25, fixed before the comparison). Each step's both-sides rounding is +``tests/march_bounds.py``'s one-step share of :func:`march_bounds.march_bound` at the +case's measured nonlinear phase, ``s``; after ``k`` matched steps the states agree to +``k s`` normwise. A trial's scaled norm divides the embedded difference by about +``rtol ||a||``, so its rounding and the states' departure reach it as ``k s / rtol``, +times ``(1 + W Phi / S)`` for the departure's own effect on the stages (``W`` the +step's weights, ``Phi / S`` its share of the phase). The split collar's sums and the +boundary reading are quadratic in the field: four times the field's budget +(:data:`march_bounds.STATISTIC_FACTOR`). A stage register is one evaluation's rounding +(:func:`march_bounds.evaluation_rounding`) with the margin, plus three times the step's +budget for the cubic response to its input's departure; it is compared on the first +step only, where no recycled stage is involved. + +**Non-vacuity.** Every compared term is asserted to exceed its bound by a wide factor, +and the split sums' measurement point is shown to matter: the same reduction of the +finished field (after the split) misses native's sum by more than the bound. +""" + +from __future__ import annotations + +import math +from contextlib import ExitStack +from typing import Any + +import numpy as np +import pytest + +from backend_corpus_cases import CARRIER, FIXED_ADAMS, capillary, walking_fibre +from bounds import EPS, assert_within, step_evaluations +from engine_pairs import AdamsCall, Opened, opened, play_adams, record_adams +from march_bounds import ( + MARGIN, + STATISTIC_FACTOR, + evaluation_rounding, + march_bound, + measured_scales, +) +from solprop.backends.engines import AcceptRecord, BoundaryReading +from solprop.backends.registry import available +from solprop.driver import Simulation +from solprop.stepper import LowStorageRungeKutta, Multistep, RungeKutta + +pytestmark = pytest.mark.skipif( + "native" not in available(), reason="the native backend is not installed" +) + +BACKENDS = ("numpy_ref", "native") + +STEPS = 3 +"""Accepted steps each Runge-Kutta case takes.""" + +ADAMS_ACCEPTS = 6 +"""Accepted steps each Adams case replays: past the startup, into a full history.""" + +WIDE = 100.0 +"""How many bounds a compared term must exceed to mean something.""" + + +class Budget: + """A case's budgets, from its measured phase, fixed before anything is compared.""" + + def __init__(self, simulation: Simulation, steps: int | None = None) -> None: + problem = simulation.translate() + request = simulation._run_request() + phi, kappa = measured_scales(simulation) + phi = max(phi, 0.1) + schedule = request.stepper.schedule + total = int(schedule.n_steps) if schedule is not None else int(steps or 1) + whole = march_bound( + problem, request, total, phi=phi, kappa=kappa, backend="native" + ) + self.step = whole / total + self.rtol = float(request.stepper.controller.rtol) + self.departure = 1.0 + step_evaluations(request) * phi / total + self.stage = ( + MARGIN + * kappa + * evaluation_rounding( + int(problem.grids.n_to), + int(problem.transform.n_nodes), + int(problem.shape[0]), + raman=bool(problem.flags.has_raman), + plasma=bool(problem.flags.has_plasma), + ) + + 3 * self.step + ) + + def field(self, k: int) -> float: + """The states' normwise budget after `k` matched steps.""" + return k * self.step + + def norm(self, k: int) -> float: + """A scaled norm's absolute budget at the `k`-th trial.""" + return k * self.step * self.departure / self.rtol + + +def _check_norm(native: float, reference: float, bound: float, what: str) -> None: + assert reference > WIDE * bound, f"{what}: the norm is too small to compare" + assert abs(native - reference) <= bound, ( + f"{what}: {native!r} against {reference!r}, bound {bound:.3g}" + ) + + +def _check_record( + native: AcceptRecord, + reference: AcceptRecord, + bound: float, + what: str, +) -> float: + """The split collar's sums of one accepted step, as the reference took them. + + Each sum weighs the field's energy over part of the window by weights of at most + one, so the states' normwise departure bounds it absolutely, relative to the + state's energy (``found[0]``), not to the sum: `bound` times the energy. Returns + that absolute bound on the removal. + """ + assert reference.found is not None and native.found is not None, what + energy = float(reference.found[0]) + limit = bound * energy + # What the collar took must stand well clear of what the bound allows. + assert reference.removed > 10 * limit, f"{what}: the collar took too little" + assert abs(native.removed - reference.removed) <= limit, what + assert_within(native.found, reference.found, limit, scale=1.0, what=what) + return limit + + +def _check_reading( + native: BoundaryReading, reference: BoundaryReading, bound: float, what: str +) -> None: + """A boundary reading: its weighted energies bounded relative to the state's.""" + limit = bound * reference.total + assert reference.total > 0.0 + assert abs(native.total - reference.total) <= limit, what + assert np.max(reference.regions) > 0.0, what + assert_within(native.regions, reference.regions, limit, scale=1.0, what=what) + assert reference.occupancy is not None and native.occupancy is not None, what + assert_within(native.occupancy, reference.occupancy, limit, scale=1.0, what=what) + + +# -- the Runge-Kutta engine --------------------------------------------------------- + + +def _runge_kutta_case(case: Opened, simulation: Simulation) -> list[dict[str, Any]]: + """Take :data:`STEPS` steps, each after a rejected trial; what each read.""" + engine = case.runge_kutta + assert engine is not None + request = simulation._run_request() + schedule = request.stepper.schedule + assert schedule is not None + n_stages = request.stepper.tableau.n_stages + steps = [] + for index in range(STEPS): + z, dz = float(schedule.edges[index]), float(schedule.steps[index]) + before = case.field() + rejected = engine.trial(z, 0.5 * dz) + norm = engine.trial(z, dz) + # The commit contract, on each backend: a trial commits nothing. + assert np.array_equal(case.field(), before) + assert not engine.in_flight + stages = [case.stage(i) for i in range(n_stages)] if index == 0 else [] + record = engine.accept(dz) + assert math.isnan(record.stiffness) + steps.append({ + "dz": dz, + "rejected": rejected, + "norm": norm, + "stages": stages, + "record": record, + "field": case.field(), + "reading": engine.reading(), + }) # fmt: skip + return steps + + +@pytest.mark.medium +def test_a_runge_kutta_engine_steps_reads_and_splits_as_the_reference_s() -> None: + simulation = walking_fibre("numpy_ref", RungeKutta()) + budget = Budget(simulation) + with ExitStack() as stack: + played = {} + monitors = {} + for backend in BACKENDS: + case = stack.enter_context( + opened(walking_fibre(backend, RungeKutta()), backend) + ) + played[backend] = _runge_kutta_case(case, simulation) + monitors[backend] = case.monitor + launch = simulation.translate().initial.field0 + for k, (ours, theirs) in enumerate( + zip(played["native"], played["numpy_ref"], strict=True), start=1 + ): + what = f"step {k}" + _check_norm(ours["rejected"], theirs["rejected"], budget.norm(k), what) + _check_norm(ours["norm"], theirs["norm"], budget.norm(k), what) + for index, (stage, expected) in enumerate( + zip(ours["stages"], theirs["stages"], strict=True) + ): + assert_within(stage, expected, budget.stage, what=f"{what} stage {index}") + assert_within(ours["field"], theirs["field"], budget.field(k), what=what) + statistic = STATISTIC_FACTOR * budget.field(k) + limit = _check_record(ours["record"], theirs["record"], statistic, what) + _check_reading(ours["reading"], theirs["reading"], statistic, what) + # The sums are the masked field's before the split: the same reduction of the + # finished field, after it, is another number by more than the bound. + monitor = monitors["numpy_ref"] + assert monitor is not None + after = float(monitor.split_sums(theirs["field"], ours["dz"])[0]) + assert abs(after - ours["record"].removed) > 10 * limit, what + # The stages were read, and the state moved by far more than its budget. + assert len(played["native"][0]["stages"]) > 1 + moved = np.linalg.norm(played["numpy_ref"][-1]["field"] - launch) + assert moved > WIDE * budget.field(STEPS) * np.linalg.norm(launch) + + +def test_a_dense_extension_leaves_the_trial_and_its_accept_alone() -> None: + # `extend` holds the trial's continuous extension for a dense observation, which + # only the session reads; through the protocol, a held extension changes neither + # the committed state nor what the accept commits, on either backend. + simulation = capillary("numpy_ref", RungeKutta(), interpolated=True) + budget = Budget(simulation, steps=1) + dz = float(simulation._run_request().stepper.dz_init) + found = {} + for backend in BACKENDS: + with opened( + capillary(backend, RungeKutta(), interpolated=True), backend + ) as case: + engine = case.runge_kutta + assert engine is not None + before = case.field() + engine.trial(0.0, dz) + engine.extend(0.0, dz) + assert np.array_equal(case.field(), before) + engine.accept(dz) + found[backend] = case.field() + assert_within(found["native"], found["numpy_ref"], budget.field(1)) + + +# -- the low-storage engine ----------------------------------------------------------- + + +@pytest.mark.medium +def test_a_low_storage_engine_is_in_flight_and_commits_as_the_reference_s() -> None: + simulation = walking_fibre("numpy_ref", LowStorageRungeKutta()) + budget = Budget(simulation) + schedule = simulation._run_request().stepper.schedule + assert schedule is not None + played: dict[str, list[tuple[AcceptRecord, np.ndarray]]] = {} + for backend in BACKENDS: + with opened(walking_fibre(backend, LowStorageRungeKutta()), backend) as case: + engine = case.runge_kutta + assert engine is not None + played[backend] = [] + for index in range(STEPS): + z, dz = float(schedule.edges[index]), float(schedule.steps[index]) + assert not engine.in_flight + # "Not estimated": the step overwrites the state, the register A. + assert engine.trial(z, dz) == 0.0 + assert engine.in_flight + record = engine.accept(dz) + assert not engine.in_flight + played[backend].append((record, case.field())) + for k, ((ours, field), (theirs, expected)) in enumerate( + zip(played["native"], played["numpy_ref"], strict=True), start=1 + ): + what = f"step {k}" + # The stiffness diagnostic is the reference engine's alone (SEP 52 5.2). + assert math.isfinite(theirs.stiffness) and theirs.stiffness > 0.0 + assert math.isnan(ours.stiffness) + assert_within(field, expected, budget.field(k), what=what) + _check_record(ours, theirs, STATISTIC_FACTOR * budget.field(k), what) + + +# -- the Adams engine --------------------------------------------------------------- + +ADAMS = { + "interaction": lambda backend: capillary( + backend, Multistep(variable_order=False, formulation="interaction"), modes=3 + ), + "exponential": lambda backend: capillary(backend, FIXED_ADAMS), + "carrier": lambda backend: capillary(backend, CARRIER, interpolated=True), +} +"""The Adams cases: retained-history transport and the split collar; the exponential +formulation and the split collar; the exponential formulation in the carrier frame, +adaptive, whose trials form carrier rotations.""" + + +@pytest.mark.medium +@pytest.mark.parametrize("name", list(ADAMS)) +def test_an_adams_engine_replays_the_reference_s_march_as_the_reference_does( + name: str, monkeypatch: pytest.MonkeyPatch +) -> None: + simulation = ADAMS[name]("numpy_ref") + calls = record_adams(simulation, monkeypatch, accepts=ADAMS_ACCEPTS) + accepts = sum(call.name == "accept" for call in calls) + assert accepts == ADAMS_ACCEPTS + budget = Budget(simulation, steps=accepts) + played = {} + for backend in BACKENDS: + with opened(ADAMS[name](backend), backend) as case: + played[backend] = play_adams(case, calls) + _compare_adams(name, calls, played["native"], played["numpy_ref"], budget) + + +def _compare_adams( + name: str, + calls: list[AdamsCall], + ours: list[tuple[str, Any]], + theirs: list[tuple[str, Any]], + budget: Budget, +) -> None: + """Hold native's replay to the reference's, call by call.""" + # The single-mode capillary's collar takes about 1e-11 of the energy at a step, + # below what the states' budget can resolve; the three-mode one's group delays + # put a thousand times more there. The carrier case has the in-stage collar. + split = name == "interaction" + k = 1 + carriers = 0 + for (call, value), (other, expected) in zip(ours, theirs, strict=True): + assert call == other + what = f"{name} {call} at step {k}" + if call == "trial": + reference = np.asarray(expected) + bound = budget.norm(k) + assert reference[0] > WIDE * bound, f"{what}: the norm is too small" + np.testing.assert_allclose(value, reference, rtol=0.0, atol=bound) + elif call == "accept": + (record, field), (wanted, state) = value, expected + assert_within(field, state, budget.field(k), what=what) + if split: + _check_record(record, wanted, STATISTIC_FACTOR * budget.field(k), what) + k += 1 + elif call == "chord_phase": + assert value == pytest.approx(expected, rel=64 * EPS, abs=64 * EPS) + else: + reference = np.asarray(expected) + assert np.shape(value) == reference.shape, what + if reference.size: + carriers += 1 + # A rotation's phase, the shift times a node's span, carries its + # chord's rounding: a few eps of the shift, rad. + assert reference[0] != 0.0, f"{what}: no carrier shift" + tolerance = 64 * EPS * max(1.0, abs(float(reference[0]))) + np.testing.assert_allclose(value, reference, rtol=0.0, atol=tolerance) + if name == "carrier": + assert carriers > 0, "no trial formed carrier rotations" + if name == "interaction": + # The transport is exercised: accepts kept more than one entry. + kept = [len(call.args[3]) for call in calls if call.name == "accept"] + assert max(kept) > 1 diff --git a/tests/backends/test_native_error_norm.py b/tests/backends/test_native_error_norm.py index 387a00edb..bbce0a231 100644 --- a/tests/backends/test_native_error_norm.py +++ b/tests/backends/test_native_error_norm.py @@ -154,11 +154,20 @@ def test_the_rk_norm_is_the_reference_norm_of_native_s_operands( def test_a_whole_trial_scores_as_the_reference_s_trial_does( capillary_problem, field_grid, dz, record_property ): - """Each backend's own stages: the state's one-step rung over the scale.""" + """Each backend's own engine and stages: the state's one-step rung over the scale. + + Both trials go through solprop's ``RungeKuttaEngine`` protocol: the reference's + engine over its workspace, native's over its own (``_testing.engines``). + """ problem, run_request = _problem(capillary_problem) reference = NumpyRefBackend(problem, run_request, grid=field_grid) - backend, score = _native_trial(problem, run_request, field_grid, dz) + backend = native.NativeBackend(problem, run_request, grid=field_grid) try: + engines = _testing.engines(load_native(backend, problem.initial.field0)) + try: + score = engines.rk_trial(0.0, dz) + finally: + engines.close() load_reference(reference) wanted, _ = reference_trial(reference, 0.0, dz) finally: diff --git a/tests/driver/test_estimate.py b/tests/driver/test_estimate.py index 0fc3270d3..fcc3e3e50 100644 --- a/tests/driver/test_estimate.py +++ b/tests/driver/test_estimate.py @@ -14,7 +14,7 @@ from builders import load_reference, reference_trial from capability_routes import ROUTES -from sessions.runs import load_native, native_trial +from sessions.runs import load_native from solprop.backends.numpy_ref.engines import NumpyRungeKutta from solprop.backends.registry import available, select from solprop.backends.session import SessionError, Start @@ -220,15 +220,17 @@ def _native_trial(problem, fresh, dz): """Return a fresh native workspace's trial from the launch, finished as kept. The same Runge-Kutta trial from the launch the probe takes, taken by a fresh - native workspace itself on its stage tables and finished as a kept step (SEP 47 - phase 5: the native backend no longer steps or observes outside its session). + native workspace's own engine (``_testing.engines``, SEP 52) and accepted. """ assert problem.initial.noise0 is None _testing = pytest.importorskip("solprop_native._core")._testing - workspace = load_native(fresh, problem.initial.field0) - native_trial(fresh, float(problem.initial.z), dz) - _testing.finish(workspace, dz) - return np.asarray(_testing.field(workspace)).reshape(problem.shape) + engines = _testing.engines(load_native(fresh, problem.initial.field0)) + try: + engines.rk_trial(float(problem.initial.z), dz) + engines.rk_accept(dz) + return np.asarray(engines.field()).reshape(problem.shape) + finally: + engines.close() def _native_committed_nothing(problem, probed, fresh): diff --git a/tests/engine_pairs.py b/tests/engine_pairs.py new file mode 100644 index 000000000..919ce4839 --- /dev/null +++ b/tests/engine_pairs.py @@ -0,0 +1,332 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""Both backends' engines over a loaded workspace, through solprop's protocols. + +SEP 52 section 6.5: a parity case is written once, against +:class:`~solprop.backends.engines.RungeKuttaEngine` and +:class:`~solprop.backends.engines.AdamsEngine`, and run on each backend's engines. The +reference's are its own (:class:`~solprop.backends.numpy_ref.engines.NumpyRungeKutta`, +:class:`~solprop.backends.low_storage.HostLowStorage`, +:class:`~solprop.backends.numpy_ref.multistep.HostHistory`) over its workspace; +native's are its workspace's C++ engines, reached through the private test module +(``_testing.engines``), whose prefixed methods :class:`NativeRungeKutta` and +:class:`NativeAdams` dispatch onto the protocols' names. Each backend is loaded with the +problem's launch, configured with the run's records and, when asked, watched by the +case's boundary monitor, as a session's start leaves it. + +- :func:`opened` builds one backend's :class:`Opened` engines for a simulation; +- :func:`record_adams` records the Adams calls the reference's march makes on a run, a + script :func:`play_adams` replays on either backend's engine. +""" + +from __future__ import annotations + +import dataclasses +from collections.abc import Callable, Iterator, Sequence +from contextlib import contextmanager +from dataclasses import dataclass +from typing import Any, cast + +import numpy as np +import pytest + +from builders import load_reference +from sessions.runs import bare, bind_native_monitor, load_native, run +from solprop.backends.adams_core import Stencil +from solprop.backends.engines import ( + AcceptRecord, + AdamsEngine, + AttemptOutcome, + BoundaryReading, + HistoryEntry, + RungeKuttaEngine, +) +from solprop.backends.records import run_records +from solprop.backends.registry import select +from solprop.backends.session import Start +from solprop.driver import Simulation +from solprop.monitor import BoundaryMonitor +from solprop.stepper import LowStorageRungeKutta, Multistep + +__all__ = [ + "AdamsCall", + "NativeAdams", + "NativeRungeKutta", + "Opened", + "opened", + "play_adams", + "record_adams", +] + + +class NativeRungeKutta: + """Native's Runge-Kutta or low-storage engine as a ``RungeKuttaEngine``.""" + + def __init__(self, engines: Any) -> None: + self._engines = engines + + def trial(self, z: float, dz: float) -> float: + """Form a trial; return its scaled norm (0.0 for the low-storage step).""" + return float(self._engines.rk_trial(z, dz)) + + def accept(self, dz: float) -> AcceptRecord: + """Finish and commit the trial.""" + return self._engines.rk_accept(dz) + + def extend(self, z: float, dz: float) -> None: + """Hold the trial as a dense extension.""" + self._engines.rk_extend(z, dz) + + def reading(self) -> BoundaryReading: + """Return the committed state's boundary reading.""" + return self._engines.rk_reading() + + @property + def in_flight(self) -> bool: + """Whether a step that overwrites the state was left partway.""" + return bool(self._engines.rk_in_flight) + + +class NativeAdams: + """Native's Adams engine as an ``AdamsEngine``.""" + + def __init__(self, engines: Any) -> None: + self._engines = engines + + def start(self, z: float) -> None: + """Evaluate the history's first sample into row 0.""" + self._engines.adams_start(z) + + def trial(self, z: float, dz: float, stencil: Stencil) -> np.ndarray: + """Form a trial; return its scored orders' norms.""" + return np.asarray(self._engines.adams_trial(z, dz, stencil), dtype=np.float64) + + def accept( + self, dz: float, free: int, stencil: Stencil, kept: Sequence[HistoryEntry] + ) -> AcceptRecord: + """Adopt the held trial into row `free`.""" + return self._engines.adams_accept(dz, free, stencil, list(kept)) + + def chord_phase(self, z1: float, z2: float) -> float: + """Return the carrier chord's largest phase over the interval, rad.""" + return float(self._engines.adams_chord_phase(z1, z2)) + + def step_carrier(self, order: int) -> np.ndarray: + """Return the last trial's packed carrier rotations.""" + return np.asarray(self._engines.adams_step_carrier(order), dtype=np.float64) + + def begin_attempt(self, cost: int) -> None: + """Reserve an attempt's host-source calls.""" + self._engines.adams_begin_attempt(cost) + + def end_attempt(self, outcome: AttemptOutcome) -> None: + """End an attempt.""" + self._engines.adams_end_attempt(int(outcome)) + + def reading(self) -> BoundaryReading: + """Return the committed state's boundary reading.""" + return self._engines.adams_reading() + + +@dataclass +class Opened: + """One backend's engines over its loaded, configured workspace. + + ``field`` reads the committed state and ``stage`` a Runge-Kutta trial's stage + register, each in the problem's shape; ``monitor`` is the monitor as bound, or + ``None`` when the case is not watched. + """ + + backend: str + shape: tuple[int, ...] + runge_kutta: RungeKuttaEngine | None + adams: AdamsEngine | None + field: Callable[[], np.ndarray] + stage: Callable[[int], np.ndarray] + monitor: BoundaryMonitor | None + + +@contextmanager +def opened( + simulation: Simulation, backend: str, *, watched: bool = True +) -> Iterator[Opened]: + """Open `backend` on a simulation, its engines over the loaded launch. + + The reference's engines are the ones its next run would build; native's are its + workspace's, leased for the block (no session can start meanwhile). + """ + problem = simulation.translate() + request = simulation._run_request() + made = cast( + "Any", + select( + backend, + problem, + request, + grid=simulation.grid, + modes=simulation.modes, + profiles=simulation.profiles, + options=simulation.settings.execution_options(), + ), + ) + shape = tuple(problem.shape) + integrator = request.stepper.integrator + monitor = simulation._boundary_monitor() if watched else None + try: + if backend == "numpy_ref": + yield _reference(made, problem, integrator, monitor, shape) + else: + yield from _native(made, problem, request, integrator, monitor, shape) + finally: + made.close() + + +def _reference( + made: Any, problem: Any, integrator: Any, monitor: Any, shape: tuple[int, ...] +) -> Opened: + """The reference's engines over its workspace, loaded and watched.""" + load_reference(made) + workspace = made.workspace + if monitor is not None: + monitor = dataclasses.replace( + monitor, crossing=problem.split_crossing if monitor.split else None + ) + workspace.bind_monitor(monitor) + runge_kutta: Any = None + adams: Any = None + if isinstance(integrator, Multistep): + adams = made.march._engine + elif isinstance(integrator, LowStorageRungeKutta): + runge_kutta = made.march.engine + else: + runge_kutta = made._runge_kutta(workspace) + + def stage(index: int) -> np.ndarray: + return np.asarray(runge_kutta.stages[index]).reshape(shape) + + return Opened( + "numpy_ref", + shape, + runge_kutta, + adams, + lambda: np.array(workspace.committed()).reshape(shape), + stage, + monitor, + ) + + +def _native( + made: Any, + problem: Any, + request: Any, + integrator: Any, + monitor: Any, + shape: tuple[int, ...], +) -> Iterator[Opened]: + """Native's engines over its workspace, loaded, configured and watched.""" + _testing = pytest.importorskip("solprop_native._core")._testing + workspace = load_native(made, problem.initial.field0) + _testing.configure_march( + workspace, run_records(problem, request, Start.entrance(problem)) + ) + if monitor is not None: + monitor = bind_native_monitor(made, problem, monitor) + engines = _testing.engines(workspace) + try: + adams = NativeAdams(engines) if isinstance(integrator, Multistep) else None + yield Opened( + "native", + shape, + None if adams is not None else NativeRungeKutta(engines), + adams, + lambda: np.asarray(engines.field()).reshape(shape), + lambda index: np.asarray(engines.stage(index)).reshape(shape), + monitor, + ) + finally: + engines.close() + + +@dataclass(frozen=True) +class AdamsCall: + """One call an Adams march made on its engine: the method's name and arguments.""" + + name: str + args: tuple[Any, ...] + + +def record_adams( + simulation: Simulation, monkeypatch: pytest.MonkeyPatch, *, accepts: int +) -> list[AdamsCall]: + """Record the calls the reference's Adams march makes, up to `accepts` accepts. + + A run of the simulation on the reference, the calls of its + :class:`~solprop.backends.numpy_ref.multistep.HostHistory` copied as they are + made: the startup, every trial (the rejected ones too), every accept with the + history it keeps, and each carrier read. + """ + from solprop.backends.numpy_ref.multistep import HostHistory # noqa: PLC0415 + + calls: list[AdamsCall] = [] + + def spy(name: str, copy: Callable[..., tuple[Any, ...]]) -> None: + original = getattr(HostHistory, name) + + def recorded(engine: Any, *args: Any) -> Any: + calls.append(AdamsCall(name, copy(*args))) + return original(engine, *args) + + monkeypatch.setattr(HostHistory, name, recorded) + + def stencil(value: Stencil) -> Stencil: + return Stencil( + list(value.nodes), np.array(value.rows), value.order, list(value.orders) + ) + + spy("start", lambda z: (float(z),)) + spy("trial", lambda z, dz, held: (float(z), float(dz), stencil(held))) + spy( + "accept", + lambda dz, free, held, kept: (float(dz), int(free), stencil(held), list(kept)), + ) + spy("chord_phase", lambda z1, z2: (float(z1), float(z2))) + spy("step_carrier", lambda order: (int(order),)) + problem = simulation.translate() + request = simulation._run_request() + made = select( + "numpy_ref", + problem, + request, + grid=simulation.grid, + modes=simulation.modes, + profiles=simulation.profiles, + options=simulation.settings.execution_options(), + ) + run(made, problem, bare(request), owns=True, export=None) + monkeypatch.undo() + taken = 0 + for index, call in enumerate(calls): + taken += call.name == "accept" + if taken == accepts: + return calls[: index + 1] + return calls + + +def play_adams(opened: Opened, calls: Sequence[AdamsCall]) -> list[tuple[str, Any]]: + """Replay recorded Adams calls on one backend's engine; what each returned. + + An accept's entry carries its :class:`AcceptRecord` and the committed state after + it; a startup returns nothing and is not listed. + """ + engine = opened.adams + assert engine is not None, "the case is not an Adams march" + found: list[tuple[str, Any]] = [] + for call in calls: + value = getattr(engine, call.name)(*call.args) + if call.name == "accept": + found.append((call.name, (value, opened.field()))) + elif call.name != "start": + found.append((call.name, value)) + return found From aa2498794a189343c6fe46f9fa4bd71b509dc72d Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 06:50:02 +0000 Subject: [PATCH 17/29] chore(native): cite the reference's session and workspace, not the deleted driver; drop an unused _testing binding (SEP 52) The native comments and docstrings still cited HostDriver's members, which milestone 3 deleted: each now names the member that does the same work (HostSession, RungeKuttaMarch, NumpyWorkspace, RungeKuttaDense, HostLowStorage). _testing.set_absorber_quiet had no user. [skip ci] Co-Authored-By: Claude Opus 5.5 --- native/include/solprop_native/dense.hpp | 2 +- native/include/solprop_native/dense_output.hpp | 2 +- native/include/solprop_native/session.hpp | 2 +- native/include/solprop_native/statistics_plan.hpp | 2 +- native/src/adams_march.cpp | 2 +- native/src/bindings.cpp | 6 ------ native/src/general/trial.cpp | 2 +- native/src/low_storage.cpp | 2 +- native/src/rk_march.cpp | 10 +++++----- native/src/session_edge.cpp | 4 ++-- native/src/session_statistics.cpp | 6 +++--- native/src/solprop_native/_core_testing.pyi | 1 - native/src/solprop_native/_host_source.py | 2 +- native/src/solprop_native/_load.py | 7 ++++--- native/src/solprop_native/_statistics.py | 5 +++-- native/src/solprop_native/_watch.py | 2 +- native/src/solprop_native/session.py | 4 ++-- tests/backends/native_trace_marches.py | 6 +++--- 18 files changed, 31 insertions(+), 36 deletions(-) diff --git a/native/include/solprop_native/dense.hpp b/native/include/solprop_native/dense.hpp index 1a4b8d3a3..96e6b0b63 100644 --- a/native/include/solprop_native/dense.hpp +++ b/native/include/solprop_native/dense.hpp @@ -19,7 +19,7 @@ * dense_output.hpp) are solprop's own observations transcribed: the Adams march's * interpolant over the last accepted step (`HostHistory.observe`), and DOPRI5's * continuous extension of Hairer, Norsett and Wanner II.6 carried to the plane by the - * linear flow (`HostDriver._observe_inside`). + * linear flow (`RungeKuttaDense.observe`). * * Python-free and Kokkos-free: host code only. */ diff --git a/native/include/solprop_native/dense_output.hpp b/native/include/solprop_native/dense_output.hpp index f796464d0..14abd1271 100644 --- a/native/include/solprop_native/dense_output.hpp +++ b/native/include/solprop_native/dense_output.hpp @@ -81,7 +81,7 @@ class AdamsDense final : public session::Dense { }; /** DOPRI5's continuous extension in the interaction picture (solprop's - `HostDriver._dense_record` and `_observe_inside`): the accepted step's extension is + `RungeKuttaDense`, `numpy_ref/dense.py`): the accepted step's extension is contracted from the state before it and the step's stages before the step is finished (`hold`, which the Runge-Kutta engine's `extend` calls), evaluated at the plane's fraction and carried there by the linear flow. */ diff --git a/native/include/solprop_native/session.hpp b/native/include/solprop_native/session.hpp index 34632b63a..f34573ebc 100644 --- a/native/include/solprop_native/session.hpp +++ b/native/include/solprop_native/session.hpp @@ -39,7 +39,7 @@ * * The scheduler's decisions -- which plane is next, when a step plane, a statistics * row, a bounded yield or a snapshot falls due, and the reached and replay tolerances - * -- are solprop's `DriverSession`, `HostDriver` and `solprop.backends.host.driver` + * -- are solprop's `DriverSession` and `solprop.backends.host.session` * functions, transcribed. Like the marches they are compiled strict (no contraction, no * fast-math) in their own translation unit, so they round as solprop's Python does; * that unit also holds the export, whose recipe is `solprop.backends.export`'s diff --git a/native/include/solprop_native/statistics_plan.hpp b/native/include/solprop_native/statistics_plan.hpp index 125b211d5..045f8513a 100644 --- a/native/include/solprop_native/statistics_plan.hpp +++ b/native/include/solprop_native/statistics_plan.hpp @@ -155,7 +155,7 @@ struct Plan { std::vector weight; RealTable weight_table; // The on-axis synthesis at the reference position, rows times modes, which the - // taper rescales (`HostDriver._on_axis_synthesis`), and the taper's table. + // taper rescales (`NumpyWorkspace._on_axis_synthesis`), and the taper's table. std::vector on_axis; RealTable taper; // The on-axis plasma statistics (solprop SEP 19): the pad scale their row carries diff --git a/native/src/adams_march.cpp b/native/src/adams_march.cpp index 9010bf4e3..720111b41 100644 --- a/native/src/adams_march.cpp +++ b/native/src/adams_march.cpp @@ -691,7 +691,7 @@ Result run(const Policy& policy, State& state, Engine& engine, const Bounds& bou result.reason = Reason::reached; return result; } - // A replay's next step is its schedule's (`HostDriver._next_step`). + // A replay's next step is its schedule's (`HostSession._next_step`). const double ahead = !bounds.replay ? state.proposal diff --git a/native/src/bindings.cpp b/native/src/bindings.cpp index 766c3df45..63ed282e8 100644 --- a/native/src/bindings.cpp +++ b/native/src/bindings.cpp @@ -3304,12 +3304,6 @@ void bind_testing(nb::module_& testing) { "clear_fsal", [](BoundWorkspace& owner) { owner.workspace().state().clear_fsal(); }, "workspace"_a); - testing.def( - "set_absorber_quiet", - [](BoundWorkspace& owner, const bool quiet) { - owner.workspace().state().set_absorber_quiet(quiet); - }, - "workspace"_a, "quiet"_a); // A Runge-Kutta trial on the stage tables at the setup's nodes, as the march takes // it (solprop SEP 45 phase 2): its partials `(3, slots)`, its stages kept in the // state. diff --git a/native/src/general/trial.cpp b/native/src/general/trial.cpp index 95309f6b5..1d035df7a 100644 --- a/native/src/general/trial.cpp +++ b/native/src/general/trial.cpp @@ -4759,7 +4759,7 @@ void GeneralWorkspace::adams_exponential_observe(const double xi, const double d // // DOPRI5's continuous extension (Hairer, Norsett and Wanner, II.6) in the step's // interaction picture, as solprop's `extension_coefficients`, `extension_value` and -// `HostDriver._observe_inside` form it: with `v0` the state at the step's anchor, `k_i` +// `RungeKuttaDense.observe` form it: with `v0` the state at the step's anchor, `k_i` // its stages in the anchor's frame and `v1 - v0 = h sum_i b_i k_i`, the coefficients // `v0`, `v1 - v0`, `h k1 - (v1 - v0)`, `(v1 - v0) - h k7 - (h k1 - (v1 - v0))` and // `h sum_i d_i k_i`, evaluated at the fraction theta as `r1 + theta (r2 + (1 - theta) diff --git a/native/src/low_storage.cpp b/native/src/low_storage.cpp index 86532d7d1..42d82b880 100644 --- a/native/src/low_storage.cpp +++ b/native/src/low_storage.cpp @@ -185,7 +185,7 @@ ResidentLowStorage::ResidentLowStorage(GeneralState& state, const stage::Tables& double ResidentLowStorage::trial(const double z, const double dz) { // In flight from here to the finish: the state is overwritten in place - // (`HostDriver._in_flight`, set before the engine's step). + // (`HostLowStorage.in_flight`, set before the engine's step). in_flight_ = true; double key = std::numeric_limits::quiet_NaN(); bool rebuild = false; diff --git a/native/src/rk_march.cpp b/native/src/rk_march.cpp index 359593807..094b89af8 100644 --- a/native/src/rk_march.cpp +++ b/native/src/rk_march.cpp @@ -285,9 +285,9 @@ Result run(const Policy& policy, State& state, Engine& engine, if (bounds.watch && bounds.owner == nullptr) watch::validate(bounds.watch_policy); if (bounds.replay) { - // `HostDriver._replay_to` (SEP 45 phase 4): the schedule's steps as given, never - // rejected, each recorded after its commit with its raw norm; a non-finite norm - // stops the run, the step uncommitted. + // `RungeKuttaMarch.replay_to` (SEP 45 phase 4): the schedule's steps as given, + // never rejected, each recorded after its commit with its raw norm; a non-finite + // norm stops the run, the step uncommitted. const std::size_t n_steps = schedule.steps.size(); if (schedule.edges.size() != n_steps + 1) throw std::invalid_argument("a schedule has one edge more than its steps"); @@ -333,7 +333,7 @@ Result run(const Policy& policy, State& state, Engine& engine, result.reason = march::Reason::reached; return out; } - // A replay's next step is its schedule's (`HostDriver._next_step`). + // A replay's next step is its schedule's (`HostSession._next_step`). if (host_event(state.cursor < n_steps ? schedule.steps[state.cursor] : 0.0) || bounded()) return out; @@ -342,7 +342,7 @@ Result run(const Policy& policy, State& state, Engine& engine, return out; } // Interpolated planes are stepped across: the march lands on the run's end and its - // kinks (`HostDriver._march_to`), and returns the step that crosses the target. + // kinks (`RungeKuttaMarch.march_to`), and returns the step that crosses the target. const bool dense = policy.landings.interpolate; const double z_end = dense ? policy.landings.z_end : target; // A stop already requested ends the call before its first attempt. diff --git a/native/src/session_edge.cpp b/native/src/session_edge.cpp index 563f67797..53de02546 100644 --- a/native/src/session_edge.cpp +++ b/native/src/session_edge.cpp @@ -3,7 +3,7 @@ // SPDX-License-Identifier: GPL-3.0-or-later // The native session's transverse edge actions (solprop SEP 40 section 5.3, SEP 47 -// sections 5.3 and 6.4): `HostDriver.attach_monitor`'s launch of the edge, +// sections 5.3 and 6.4): `HostSession._attach`'s launch of the edge, // `_read_transverse` at a committed endpoint and at a plane, and the barrier each // warning makes. The edge itself is `transverse::Edge`; the readings are the resident // state's (`Resident::edge_reading`), so nothing here returns to Python. @@ -21,7 +21,7 @@ namespace solprop_native::session { double Session::next_step() const { - // `HostDriver._next_step`: a replay's scheduled step, none past its end, else the + // `HostSession._next_step`: a replay's scheduled step, none past its end, else the // controller's proposal. return std::visit( [this](const auto& method) { diff --git a/native/src/session_statistics.cpp b/native/src/session_statistics.cpp index 986dded29..178e02252 100644 --- a/native/src/session_statistics.cpp +++ b/native/src/session_statistics.cpp @@ -284,8 +284,8 @@ void axis(GeneralState& state, const Plan& plan, const double z, const double ta peaks[c] = rows[2 * (node * n_channels + c) + 1]; } } else { - // `axis_row_matrix(problem, HostDriver._on_axis_synthesis(modes))`: the matrix at - // the reference position times the taper at z, then the pad scale; a state with + // `axis_row_matrix(problem, NumpyWorkspace._on_axis_synthesis(modes))`: the matrix + // at the reference position times the taper at z, then the pad scale; a state with // two polarisations takes the profile's magnitude. std::vector scaled = plan.on_axis; for (double& value : scaled) { @@ -405,7 +405,7 @@ void temporal(GeneralState& state, const Plan& plan, const double z, const doubl (flags & weighted) != 0U ? power_weight(plan, z) : std::vector{}; std::vector on_axis; if ((flags & temporal_intensity) != 0U) { - // `HostDriver._on_axis_synthesis`: the matrix at the reference position times + // `NumpyWorkspace._on_axis_synthesis`: the matrix at the reference position times // the taper at z. on_axis = plan.on_axis; if (plan.taper.present()) diff --git a/native/src/solprop_native/_core_testing.pyi b/native/src/solprop_native/_core_testing.pyi index 01cad1526..299ca69f3 100644 --- a/native/src/solprop_native/_core_testing.pyi +++ b/native/src/solprop_native/_core_testing.pyi @@ -336,7 +336,6 @@ def rk_trial(workspace: Workspace, z: float, dz: float) -> npt.NDArray[np.float6 def round_trip(name: str, value: object) -> dict[str, Any]: ... def scoped_block_time() -> int: ... def scoped_openmp_default() -> int: ... -def set_absorber_quiet(workspace: Workspace, quiet: bool) -> None: ... def spatial_statistics( workspace: Workspace, flags: int, intensity_factor: float, z: float ) -> npt.NDArray[np.float64]: ... diff --git a/native/src/solprop_native/_host_source.py b/native/src/solprop_native/_host_source.py index 0b7ee0580..9069c5b9a 100644 --- a/native/src/solprop_native/_host_source.py +++ b/native/src/solprop_native/_host_source.py @@ -124,7 +124,7 @@ def take(self) -> BaseException | None: return error def _prefactor(self, bundle: StageScalars) -> Any: - """Return the stage prefactor as the reference forms it (`HostDriver`).""" + """Return the stage prefactor as the reference's workspace forms it.""" if bundle.prefactor is None or self._terms.prefactor is None: return prefactor_at(self._problem.responses, bundle.z1) return combine(bundle.prefactor, self._terms.prefactor) diff --git a/native/src/solprop_native/_load.py b/native/src/solprop_native/_load.py index c24579b90..686f5c93b 100644 --- a/native/src/solprop_native/_load.py +++ b/native/src/solprop_native/_load.py @@ -19,9 +19,10 @@ - :func:`propagator_mode`: the run's flow treatment (SEP 24 section 4.3); the quiet-collar rule is solprop's (:func:`solprop.backends.records.collar_rests`). -Each is the reference's arithmetic (``solprop.backends.host.driver.HostDriver``), -operation for operation, as the step driver the native backend inherited until SEP 47 -phase 5 had it; its runs are bitwise those of that driver. +Each is the reference's arithmetic +(``solprop.backends.numpy_ref.workspace.NumpyWorkspace``), operation for operation, +as the step driver the native backend inherited until SEP 47 phase 5 had it; its runs +are bitwise those of that driver. """ from __future__ import annotations diff --git a/native/src/solprop_native/_statistics.py b/native/src/solprop_native/_statistics.py index 97487265b..feb236ffd 100644 --- a/native/src/solprop_native/_statistics.py +++ b/native/src/solprop_native/_statistics.py @@ -676,7 +676,7 @@ def _shape( def _on_axis(modes: Sequence[Mode]) -> np.ndarray: """Return the mode set's synthesis on the axis at the reference position. - ``HostDriver._on_axis_synthesis`` before its taper: the single node ``r = 0`` of + ``NumpyWorkspace._on_axis_synthesis`` before its taper: the single node ``r = 0`` of :func:`~solprop.modes.quadrature.on_axis_rule`, rows x and y. """ rule = on_axis_rule(modes[0].dimlimits(0.0)[0]) @@ -1056,7 +1056,8 @@ def lower( - ``apertures``: a spatial route's far-field tables packed for the native pass (the adapter's ``_aperture_payload``): the apertures, the regions and the exponent. - ``on_axis``: the mode set's synthesis on the axis at the reference position, when - the caller already built it (``HostDriver._on_axis``); built here otherwise. + the caller already built it (``NumpyWorkspace._on_axis_synthesis``); built here + otherwise. - ``z_end``: the run's last plane, m, which a profile statistic's table must reach. - ``planes``: every position the plane statistics will be taken at, when the run fixes them all before it starts; ``zdw`` is then searched exactly there diff --git a/native/src/solprop_native/_watch.py b/native/src/solprop_native/_watch.py index 2bb755145..d7877e4d6 100644 --- a/native/src/solprop_native/_watch.py +++ b/native/src/solprop_native/_watch.py @@ -171,7 +171,7 @@ def notice_error(check: BoundaryCheck, notice: Notice) -> BaseException: def _split_crossing_message(z: float, cap: float, step: float) -> str: """Return the message of a fixed schedule refused by the split collar's cap. - The reference's text (``HostDriver._refuse_scheduled_crossing``), for the cap + The reference's text (``HostSession._refuse_scheduled_crossing``), for the cap the native session holds (SEP 47 section 6.4). - ``z``: where the cap was read, m. diff --git a/native/src/solprop_native/session.py b/native/src/solprop_native/session.py index d9db6f63a..de98ed0eb 100644 --- a/native/src/solprop_native/session.py +++ b/native/src/solprop_native/session.py @@ -999,7 +999,7 @@ def noise_phase(self, ticket: ExportTicket) -> np.ndarray | None: """Return the noise phase at a pending observation, ``Im Phi`` there. Formed on the host from the problem's scalar tables, as the backend's own - observation forms it (``HostDriver._noise_phase``); a z table's, which the + observation forms it (``NumpyWorkspace.noise_phase``); a z table's, which the leased state holds, is its slot at the plane, read through the native session under its lock as the backend reads it (``NativeBackend._unitary_phase``). @@ -1209,7 +1209,7 @@ def execution_record(self) -> Mapping[str, object]: record["native_session"] = native monitor = self.monitor_record() if monitor is not None: - # Where the driver's record carries its monitor's (`HostDriver.metadata`). + # Where the driver's record carries its monitor's (`HostSession.metadata`). record["boundary_monitor"] = monitor return record diff --git a/tests/backends/native_trace_marches.py b/tests/backends/native_trace_marches.py index 90b748f8c..87276e099 100644 --- a/tests/backends/native_trace_marches.py +++ b/tests/backends/native_trace_marches.py @@ -519,8 +519,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 ---------- @@ -684,7 +684,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. From 6041fff8d689adf5c631453542d09f79a50ac706 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 06:54:12 +0000 Subject: [PATCH 18/29] docs: the native seam, engine-level parity and ADR-079 (SEP 52 phase 5) backends.md (the binding, the z tables' slots, the Adams march's start record), architecture.md section 9, kernel-contract.md (the occupancy and the Adams march's start record, the engine's parity), benchmarking.md (the whole-run window), testing.md (engine-level parity), stepper.md (the low-storage probe), native/README.md, a ledger entry for the seam's A/B in benchmarks.md, and ADR-079 (proposed until the SEP is Final). The native headers no longer cite the deleted adapter's _ZTables, _ResidentLowStorage and _score_trial. [skip ci] Co-Authored-By: Claude Opus 5.5 --- docs/dev/architecture.md | 6 ++- docs/dev/backends.md | 46 +++++++++++++---- docs/dev/benchmarking.md | 7 +++ docs/dev/benchmarks.md | 36 ++++++++++++- docs/dev/decisions.md | 51 +++++++++++++++++++ docs/dev/kernel-contract.md | 16 +++--- docs/dev/stepper.md | 6 +-- docs/dev/testing.md | 27 +++++++++- native/README.md | 18 ++++--- native/include/solprop_native/engines.hpp | 4 +- native/include/solprop_native/low_storage.hpp | 10 ++-- .../include/solprop_native/stage_tables.hpp | 9 ++-- native/src/solprop_native/session.py | 2 +- 13 files changed, 197 insertions(+), 41 deletions(-) diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md index 68bb9e64a..23fc84379 100644 --- a/docs/dev/architecture.md +++ b/docs/dev/architecture.md @@ -610,7 +610,11 @@ class Backend(Protocol): response teams, deterministic plasma scans and device reductions and is qualified on data-centre NVIDIA GPUs; the HIP build is qualified on AMD Instinct GPUs, with the HIP sanitizer run still outstanding. The private state is read only by the backend's own - session and timing probe. Its floating-point licence is + session and timing probe. The binding is small (SEP 52, ADR-079): a `_core.Workspace` + built from one `_core.Problem`, a run started from one run record (`start(run)`), the + probe (`probe(start)`) and one `diagnostics()` record; every record crosses by its + field table, the binding only marshals, and test-only entry points live in the + private `_core._testing`. Its floating-point licence is [SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)'s: contraction by default, strict opt-outs for the protected helpers (stable increments, small-argument functions, defects, compensated sums), reassociation only on the loops of a kernel that asks for it, diff --git a/docs/dev/backends.md b/docs/dev/backends.md index 3c292b14f..58d17253b 100644 --- a/docs/dev/backends.md +++ b/docs/dev/backends.md @@ -60,8 +60,10 @@ state-sized operation, the engines a march asks of it, the marches, and the sess (§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. +`_core.Problem`, `_core.Workspace` over its resident state, `rk::Engine` and +`march::Engine`, its compiled marches and `session.cpp`, of which `HostSession` is the +Python counterpart. Both read the same run records (`solprop.backends.records`), built +once per run by shared code; native's cross the seam by field table (§4). 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). @@ -146,11 +148,12 @@ the bundle's floats and nothing about the representation reaches the backend ([kernel-contract.md §3](kernel-contract.md)). The contract's z-table fallback has no such split, so `PropagationProblem.device_ready` is false for it. NumPy evaluates the general representation directly. The native CPU build gives the table the split itself (SEP 29 section 6.6): its coefficients -are uploaded once (`table_upload`, `include/solprop_native/z_table.hpp`), and before each -native call the adapter (`_ZTables`) has the table evaluated at that call's distinct -positions into term slots of the state's size (`table_evaluate`, a strict Clenshaw pass -per position), least recently used first so that a step's end is not evaluated again as -the next step's anchor. The stage weights select the slots: `ΔΦ` is `e_1 - e_0`, a value +cross once, in the workspace's `Problem` (its `z_tables`, uploaded where the workspace is +built; `include/solprop_native/z_table.hpp`), and each trial has the table evaluated at +its distinct positions into term slots of the state's size (`stage::ZSlots` in +`stage_tables.hpp`, a strict Clenshaw pass per position), least recently used first so +that a step's end is not evaluated again as the next step's anchor; no position crosses +the seam. The stage weights select the slots: `ΔΦ` is `e_1 - e_0`, a value `e_1`, so every consumer of the terms -- the Runge-Kutta stages, the low-storage flows, the resident Adams phase and the noise -- runs unchanged, and an increment is one rounded subtraction of two values, as on the host. The phase sums skip a zero weight, @@ -210,7 +213,7 @@ operation (SEP 52 §5.1). The backend builds a fresh march and engines for each | `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 `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 Adams march, `native/src/adams_march.cpp` | Adams, adaptive and replayed, compiled (ADR-060) | the resident engine (`engines::ResidentEngine`, a `march::Engine`), the march's state from the run record (`_NativeAdamsMarch.start_state`) | | 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 | @@ -1390,7 +1393,32 @@ two packages are released together, and solprop's metadata pins this one to its up by name. Since SEP 47 phase 5 the native backend is a resource holder: it lowers the problem, loads a start (`solprop_native._load`), keeps its Adams march's record and times its trials (`timing_probe`, `solprop_native._probe`) itself, inherits no step driver, and serves every run -through its session. In an editable +through its session. + +**The binding** (SEP 52 §5.3, ADR-079). A backend builds one `_core.Problem`, which carries +every set-once table, guard and geometry (the stage, z and flux tables, the flow guard's +certificate, the controller weights, the low-storage settings), and one `_core.Workspace` +from it for its life. A run starts from one run record, `Workspace.start(run)`: the shared +run records (`solprop.backends.records.RunRecords`), the initial field and noise, a +resume's march state and history rows, the statistics plans, and the monitor's weights and +the edge's tables. The timing probe is `Workspace.probe(start)`, and `diagnostics()` is the +one record of metadata, memory, sizing, planning and crossed bytes, beside the live +`counters()` a run reads at its start and close. Nothing configures a workspace after it is +built. Each C++ record that crosses declares its fields once, beside its definition +(`include/solprop_native/fields.hpp`), and one converter (`src/records.hpp`) reads a +dataclass, mapping or tuple into it by that table, refusing a missing or unknown field, a +wrong dtype, rank or extent relation, a strided array and an integer for an enumeration by +the field's path before anything is allocated; `_core.schemas()` exports the tables and a +test holds each Python record to its table. The binding unit only converts, releases the +interpreter lock and forwards: the lease between workspace and session, the coupled-flow +guard and the marches' entry points live in `native::Workspace` (`workspace.hpp`), where +ctest reaches them. Test-only entry points are in the private `_core._testing` submodule, +which promises nothing; `_testing.engines(workspace)` exposes the workspace's engines, +which the tests wrap in solprop's engine protocols (`tests/engine_pairs.py`). The whole +stub, `_core.pyi` with `_core_testing.pyi`, is generated by nanobind's `stubgen` +(`native/scripts/problem_stub.py`, checked by the native gate). + +In an editable checkout it also recomputes the digest of `native/CMakeLists.txt` and the C++ under `native/src` and `native/include`, once per process, and refuses an extension built from anything else (`BuildInfo.source_digest`, ADR-068), which catches a C++-only change too. It records the repository diff --git a/docs/dev/benchmarking.md b/docs/dev/benchmarking.md index 863972a0f..c1514080b 100644 --- a/docs/dev/benchmarking.md +++ b/docs/dev/benchmarking.md @@ -268,6 +268,13 @@ uv run python -m benchmarks ab --set tracking --threads 16 --production 16 \ The same command with `SOLPROP_CALIBRATION=off` in both arms is its A/A control. +**The window.** A timed run starts once the backend's load of the launch returns, as the +recorded history's does. `SOLPROP_BENCHMARK_WINDOW=run`, given to both arms with +`--baseline-env` and `--candidate-env`, starts it before the load, so that a build that +loads the state inside the session's start (native's `Workspace.start(run)` since SEP 52) +is timed over the same work as one that loads it before. The tracking history never +sets it. + Selection works as for `track`. `--length` runs that fraction of each guide, from the entrance, for quick iteration. Each round runs every configuration once with each build, one worker each, and alternates which build goes first; `--rounds` sets the diff --git a/docs/dev/benchmarks.md b/docs/dev/benchmarks.md index 959fd91d3..d34ec2fc1 100644 --- a/docs/dev/benchmarks.md +++ b/docs/dev/benchmarks.md @@ -1228,7 +1228,7 @@ maths change (a500d2d). The SEP's §3.3 reads these figures. where it is not the whole, timed by the suite's worker after its warm-up. - The default stepper and `RungeKutta()` interleaved over three rounds of fresh processes, the order reversed every round; medians reported. -- Host time per trial: `python -m benchmarks.adams_host CASE [--length F]` (SEP 39), +- Host time per trial: `python -m benchmarks.adams_host CASE [--length F]` (SEP 39; removed by SEP 52), the march's wall time less its native `adams_*` calls, with no other wrappers. - The per-piece split comes from one run with `perf_counter` wrappers on about twenty-five host functions, which inflate the total by about half, so it gives the @@ -3086,6 +3086,40 @@ The shape rule alone (pack off) gave `line` 0.91 and 0.90 (Xeon 18 and 36) and 0 0.98-1.02. `he_rdw_averaged` and `h2_raman_averaged`, whose code is unchanged, ranged 0.92-1.12 on the Xeon between runs of either arm: the per-process modes of #81. +### The native workspace seam (SEP 52) + +[SEP 52](seps/sep-0052-backend-shape.md)'s phase 4 replaced the native binding's +configuration calls with one `Problem` and one run record per start, and the per-step +probe paths with the workspace's own probe; the marches did not change. Measured on an +exclusive node of two AMD EPYC 7763 (32 cores), `--threading bound`, `--calibrate none`, +three rounds of three repeats, the milestone's base against the branch, ratios of the +per-round medians (below one is faster): + +| case | default window, `--length 0.05` | whole run (`SOLPROP_BENCHMARK_WINDOW=run`) | +|---|---|---| +| `gnlse_soliton` | 1.042 / 1.008 / 1.014 | 1.020 / 1.004 / 1.027 | +| `rdw` | 0.996 / 0.983 / 0.991 | 0.992 / 0.989 / 0.994 | +| `radial_filament_256` | 1.004 / 1.004 / 0.995 | 1.022 / 1.001 / 1.029 | +| `kerr_beam_192` | 1.007 | | + +Each cell lists the three rounds' ratios. Every arm took the same +steps. The default window starts after the load, which the branch moved into the +session's start, so the whole-run window (from before the load; [benchmarking.md](benchmarking.md#comparing-two-builds-while-iterating)) +is the like-for-like reading. Timed from a built backend, a whole run cost 1.9 % more +under Runge–Kutta, 2.1 % under low-storage and 1.9 % under Adams, the start's one +converted record; a scan's preparation 0.5–1 % more. The probe's open, trial and read +cost 3.4 % more under Runge–Kutta and 2.5 % under Adams and 8 % less under low-storage; +a trial alone is unchanged under Runge–Kutta and Adams and 16 % faster under +low-storage. Peak resident memory moved by at most 1 MB. Two costs were removed on the +way: a run's initial field is read where it is rather than copied into the record +(`kerr_beam_192`'s low-storage window had been 4.6 % slower), and a run reads the +workspace's live counters, not its whole diagnostics record, at its start, close and +planes. No device build was run (the device targets were compiled only). + +The host-trial timer of the earlier Adams entries, `benchmarks.adams_host`, was removed +with it: it reached the deleted per-step adapter, and the native march leaves it nothing +to time. Those entries stand as recorded. + ## Reference tables These tables back the indicative results above. diff --git a/docs/dev/decisions.md b/docs/dev/decisions.md index 47361ac70..18112333c 100644 --- a/docs/dev/decisions.md +++ b/docs/dev/decisions.md @@ -2347,3 +2347,54 @@ Withdrawn (development-process record, not a design decision). the hook and the worker with manufactured providers; compatibility with an installed Pyroraptor is checked by hand ([SEP 49](seps/archive/sep-0049-tdse-on-native.md), section 7.4), and the worker's handshake refuses a mismatched protocol or execution space. + +## ADR-079 — One backend shape; no groups or unit axis; a native seam that only marshals + +- **Status:** proposed, with [SEP 52](seps/sep-0052-backend-shape.md) (accepted + 2026-11-15 in PR #850); accepted when the SEP is `Final`. Amends ADR-003 (the state + has no leading axis of one). +- **Context:** after SEP 47 both backends kept one external contract, but behind it they + were built differently. Native composed a workspace, engines, marches and a session in + C++; the reference was an inheritance stack (`NumpyRefBackend` on `HostDriver`, steered + by halt hooks). The fixed-schedule `Batch` executor and its groups built a complete + native backend per member and fused nothing, yet kept a group protocol, a group service + loop, a native group session and a leading axis of one on every trajectory array. The + native binding had grown to about 220 bound names, about 400 configuration names in 15 + to 20 calls, about 21 hand-written record converters and a hand-written stub. +- **Decision:** + - *One shape, two implementations.* Each backend has a lowering, a workspace that holds + the state and does every state-sized operation, engines that mirror the C++ interfaces + (`solprop.backends.engines`: `RungeKuttaEngine`, which the low-storage step implements + with a destructive trial, and `AdamsEngine`), marches that own their state, and a + session that owns the schedule, the monitor and the events. Both read the same run + records, built once per run by shared code (`solprop.backends.records`). + `HostDriver` is deleted; `HostSession` is the Python counterpart of `session.cpp`. + An accepted step's finish returns the split collar's sums in its `AcceptRecord`, and + the session accumulates them. + - *No groups, no unit axis.* `Batch`, every group path and the group protocols are + removed; `Local`, `Pool`, `Queue` and `Slurm` run scans. A trajectory's arrays have + no leading axis of one anywhere: translation's value tables, the boundary functions, + the memory ledgers and the stored `MarchSnapshot` (output schema 3). + - *The native seam.* A workspace is built from one `_core.Problem` with every set-once + table, and a run starts from one run record (`Workspace.start(run)`; the probe is + `Workspace.probe(start)`); nothing configures a workspace after it is built. Records + cross **by field table**: each C++ record declares its fields once beside its + definition and one converter reads and writes them, refusing a malformed field by its + path before allocating, with enumerations by name only; `_core.schemas()` exports the + tables and a test holds the Python records to them. **Bindings only marshal**: + convert, release the interpreter lock and forward; logic lives in the C++ library, + where ctest reaches it. **`_core._testing` promises nothing**: it ships in the wheel + for solprop's own tests, and exposes the workspace's engines, which the tests run + through the same protocols as the reference's. **The stub is generated** whole by + nanobind's `stubgen` and checked by the native gate. +- **Why:** one structure for one design lets the reference serve line by line as the + source for native's session, lets an engine-level parity case be written once and run + on both backends, and removes the group paths that cost memory for no speed. Field + tables keep the Python dataclass as the one definition of a record, needed without + native installed, while the C++ side only describes it; a schema test removes the + drift that hand-written converters allowed. +- **Consequences:** a script that imports `Batch` fails at import. A snapshot written + before output schema 3 is refused by name. The reference's numbers did not move (SEP 52 + milestone 3: bitwise on its corpus). Native's step time moved within its scatter, and + a run's start costs one converted record (SEP 52 milestone 4). The `_testing` module is + free to change with the tests. diff --git a/docs/dev/kernel-contract.md b/docs/dev/kernel-contract.md index 22f8f1174..57c5fe17a 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 (`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 | +| `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: the buckets in the run's start record, 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. @@ -1316,11 +1316,15 @@ monitor-cadence and distance returns are then not asked for. **What solprop does with a call.** The native session makes the calls, holds the march's state between them natively and turns each call's rows and readings into its events (SEP -47); the record `_NativeAdamsMarch` hands it the policy and the start's history once. The -decision-trace tests drive the march a call at a time over a scripted host backend -(`tests/backends/native_trace_marches.py`), booking each row as the reference books its -attempts, and hold its decisions, its monitor's watch state and its errors to the -reference's. +47); the policy and the start's history cross once, in the run's start record +(`Workspace.start(run)`: the run records' `MarchPolicy` and the march state +`_NativeAdamsMarch.start_state` forms, its history entries' identities by name). The +decision-trace tests drive the march a call at a time over a scripted engine +(`_core._testing.ScriptedMarch`, from `tests/backends/native_trace_marches.py`), booking +each row as the reference books its attempts, and hold its decisions, its monitor's +watch state and its errors to the reference's. The engine itself, `march::Engine`, is +held to the reference's `HostHistory` through solprop's `AdamsEngine` protocol +(`_core._testing.engines`, `tests/backends/test_engine_parity.py`). **Rounding.** The decisions are compiled without contraction or fast-math in their own translation unit and call no elementary function but `pow`, so that they round as diff --git a/docs/dev/stepper.md b/docs/dev/stepper.md index 11c4cbf2c..3e07cf99b 100644 --- a/docs/dev/stepper.md +++ b/docs/dev/stepper.md @@ -275,9 +275,9 @@ position) and one fold: `HostLowStorageMarch` replays a schedule and nothing else, mirroring `HostAdamsMarch`'s 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, +(SEP 52 §5.2). The native backend holds no such march in Python: a timing probe's +trial is one step of the workspace's own low-storage engine (`Workspace.probe`, which +closes the workspace afterwards, SEP 52 §5.5). 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 schedule, and each step is one in-place native step whose stage scalars, the table keys of `table_steps` and the flows' increments, the native state forms from its stage diff --git a/docs/dev/testing.md b/docs/dev/testing.md index c048deba0..1b676dde8 100644 --- a/docs/dev/testing.md +++ b/docs/dev/testing.md @@ -209,7 +209,32 @@ the engine under the real march and the real session ([SEP 52](seps/sep-0052-bac 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. + under SEP 52 §4's rule. Native's marches run over its own scripted engines + (`_core._testing.ScriptedMarch`, `ScriptedRkMarch`). + +### Engine-level parity + +Below a whole run, the backends are compared engine by engine, through the protocols both +implement (`solprop.backends.engines`: `RungeKuttaEngine`, `AdamsEngine`; SEP 52 §6.5). +A case is written once against the protocol and played on each backend's engines over a +workspace loaded with the launch, configured with the run's records and watched by the +case's monitor (`tests/engine_pairs.py`): the reference's own engines over its +`NumpyWorkspace`, and native's from the private `_core._testing.engines(workspace)`, +whose prefixed methods `NativeRungeKutta` and `NativeAdams` put behind the protocols' +names. `tests/backends/test_engine_parity.py` takes rejected and accepted Runge–Kutta +trials, the stage registers, a dense extension, the low-storage step's in-flight interval, +the split collar's sums in each `AcceptRecord` and the boundary reading; its Adams cases +record the calls the reference's own march makes on a run (`engine_pairs.record_adams`: +the startup, every trial, each accept with the history it keeps, the carrier chord and +rotations) and replay them on both engines. Every comparison is held to a SEP 25 budget +from `tests/march_bounds.py`, fixed before the run: `k` matched steps' share of +`march_bound` for the state, that over `rtol` for a scaled norm, four times it against +the state's energy for a sum over part of the window. Each compared term is also asserted +to stand well clear of its bound, so a zero or misplaced term fails (the split sums +against the same reduction of the finished field, for example). The state-level entry +points of `_testing` (a trial's partials, the stage rows, the flow actions, the +statistics) stay for the tests of what the protocols do not expose; they promise +nothing. ### Budgets and timing assertions diff --git a/native/README.md b/native/README.md index c083f8586..62814199a 100644 --- a/native/README.md +++ b/native/README.md @@ -120,8 +120,8 @@ extension was compiled from, with this directory's sources. Rebuild with `uv sync --reinstall-package solprop-native` when it refuses; a wheel carries no sources, and solprop's metadata pins it to solprop's own version. The version recorded at configure time (`solprop_version_built_against`: the repository's version, or `unknown` for a direct -CMake configure) is provenance only. The TDSE electronic response is refused by name -before anything is allocated; TDSE propagation uses `backend="numpy_ref"`. +CMake configure) is provenance only. The TDSE electronic response runs on CPU builds +only (solprop SEP 49); a device build refuses it by name before anything is allocated. ### The binding @@ -136,17 +136,21 @@ The private extension `_core` is a thin seam (solprop SEP 52 section 5.3): - **Records by field table.** Each C++ record declares its fields once, beside its definition (`include/solprop_native/fields.hpp`), and one converter (`src/records.hpp`) reads a dataclass, mapping or tuple into it, refusing a missing - or unknown field, a wrong dtype, rank or extent relation, or a strided array by the - field's path before copying anything. `_core.schemas()` exports every table, and a - test holds each Python record to its table. Input arrays are copied in; returned - arrays own their storage. + or unknown field, a wrong dtype, rank or extent relation, a strided array or an + enumeration given by anything but its name, by the field's path before copying + anything. `_core.schemas()` exports every table, and a test holds each Python record + to its table. Input arrays are copied in, except a run's initial field and noise, + which the start reads where they are, for its load only; returned arrays own their + storage. - **Bindings only marshal.** A binding converts, releases the interpreter lock and forwards. The lease, the coupled flow's guard, the marches' construction and the probe live in the C++ library (`native::Workspace`, `src/workspace.cpp`), where the native tests reach them. - **`_testing` promises nothing.** The test-only entry points live in the submodule `_core._testing`, shipped in the wheel for solprop's own tests; they take the - workspace first and may change with any commit. + workspace first and may change with any commit. `_testing.engines(workspace)` leases + the workspace's Runge-Kutta (or low-storage) and Adams engines, which solprop's + tests run through the same engine protocols as the reference's. - **Generated stubs.** `_core.pyi` and `_core_testing.pyi` are generated whole by nanobind's stubgen (`scripts/problem_stub.py`; `--check` in the lint stage). A binding that takes or returns a record names its Python type with `nb::sig`, so the stubs diff --git a/native/include/solprop_native/engines.hpp b/native/include/solprop_native/engines.hpp index 97a9743e9..1c940a942 100644 --- a/native/include/solprop_native/engines.hpp +++ b/native/include/solprop_native/engines.hpp @@ -93,8 +93,8 @@ class ResidentRungeKutta final : public rk::Engine { ResidentRungeKutta(GeneralState& state, Trial trial, double rtol, double atol, const std::vector& weights); double trial(double z, double dz) override; - /** solprop SEP 45 phase 4: a weighted controller's norm, `_score_trial`'s weighted - path with its sums in order. */ + /** solprop SEP 45 phase 4: a weighted controller's norm, the reference's weighted + path (`passes.error_norm`) with its sums in order. */ static double weighted_norm(GeneralState& state, const std::vector& partials, double rtol, double atol, const std::vector& weights); diff --git a/native/include/solprop_native/low_storage.hpp b/native/include/solprop_native/low_storage.hpp index fceb521d5..304bf250a 100644 --- a/native/include/solprop_native/low_storage.hpp +++ b/native/include/solprop_native/low_storage.hpp @@ -23,8 +23,8 @@ * * Each function performs the operations of the solprop function it is named after in * the same order: `table_steps` and `schedule_key` of `solprop.backends.low_storage`, - * and `scalars`, the arrays the native backend's `_ResidentLowStorage.step` packs from - * its bundles before its native call. The translation unit is compiled without + * and `scalars`, the arrays `HostLowStorage` forms from its stage bundles, as the + * native backend's adapter once packed them. The translation unit is compiled without * contraction on every build, as the marches' are. * * A step is accepted in place: from its first pass to its finish the state is neither @@ -37,7 +37,7 @@ namespace solprop_native::rk::low_storage { /** The flows a step holds and where its operator starts, as the native backend's - adapter resolved them (`_ResidentLowStorage`). */ + lowering resolves them into its `Problem`. */ struct Config { /** The native problem's `low_storage_flows`: 0 recomputes every flow per element, 1 holds a constant operator's table, 2 a varying operator's `P` and `Q`. */ @@ -77,7 +77,7 @@ inline constexpr std::size_t evaluations = 4; double dz); /** - * A step's scalars from `z` over `dz`, as `_ResidentLowStorage.step` packs them: each + * A step's scalars from `z` over `dz`, as `HostLowStorage` forms them: each * of the start, the midpoint and the end read as its own anchor, the end's row repeated * to the tableau's stages; the increment's rows the flows' -- a separable operator's * half steps, or a varying operator's `Phi(z_m) - Phi(z)` and `Phi(z + h) - Phi(z_m)` @@ -103,7 +103,7 @@ namespace solprop_native::engines { * natively, scoring 0.0 ("not estimated") or, when the field diverged, the accepted * state's non-finite squared norm; the accept is the backend's finish and the * accepted-step hook. A constant operator's table is rebuilt only where the schedule's - * key changes, as `_ResidentLowStorage` keeps it. + * key changes, as `HostLowStorage` keeps it. */ class ResidentLowStorage final : public rk::Engine { public: diff --git a/native/include/solprop_native/stage_tables.hpp b/native/include/solprop_native/stage_tables.hpp index a761b5c32..ffb2adbfd 100644 --- a/native/include/solprop_native/stage_tables.hpp +++ b/native/include/solprop_native/stage_tables.hpp @@ -273,7 +273,7 @@ struct Tables { } /** - * A z table's position slots (solprop's `_ZTables`, SEP 29 G1), least recently used + * A z table's position slots (solprop SEP 29 G1), least recently used * first: the positions a trial reads are evaluated into the native state's term slots * only where no slot holds them, so a step's end, the next step's anchor, is evaluated * once. Both Adams marches and every other consumer share this one cache, and its @@ -308,7 +308,7 @@ struct ZSlots { /** * Return each of `positions`' slots, evaluating in one call those no slot holds: - * `_ZTables.load`, the slots touched in the same order. + * the slots touched in the order the positions are given. */ std::vector load(GeneralState& state, const std::vector& positions) { @@ -359,8 +359,7 @@ struct ZSlots { return out; } - /** Evaluate `D(z)` into the rate slot unless it holds it already (`_ZTables.rate`). - */ + /** Evaluate `D(z)` into the rate slot unless it holds it already. */ void rate(GeneralState& state, const double z, const bool before) { if (rate_known && rate_z == z && rate_before == before) return; @@ -673,7 +672,7 @@ inline std::vector rate(const Tables& tables, const double z, if (tables.phi == Terms::constant) return {1.0}; if (tables.phi == Terms::table) { - // `_ZTables.rate`: `D(z)` evaluated into its slot, one at that slot. + // `D(z)` evaluated into its slot, one at that slot. tables.z_slots->rate(*tables.z_state, z, before); std::vector out(tables.z_slots->n_phi(), 0.0); out[tables.z_slots->rate_slot()] = 1.0; diff --git a/native/src/solprop_native/session.py b/native/src/solprop_native/session.py index de98ed0eb..e734f1727 100644 --- a/native/src/solprop_native/session.py +++ b/native/src/solprop_native/session.py @@ -1037,7 +1037,7 @@ def noise_phase(self, ticket: ExportTicket) -> np.ndarray | None: raise SessionError(str(error)) from None except (ValueError, IndexError, RuntimeError) as error: # Too many positions, one outside the table's span, or no table of - # `Phi`: the backend's error, as `_ZTables.load` raises the first. + # `Phi`: the backend's error, as `stage::ZSlots` raises it. raise BackendError(str(error)) from error phase = np.imag(values).reshape(self._problem.shape) else: From 095e344d1eb98f21023a3731b7c3336d17291f9b Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 06:57:12 +0000 Subject: [PATCH 19/29] chore: remove two stray arrays a test collection wrote at the root [skip ci] Co-Authored-By: Claude Opus 5.5 --- -q.npy | Bin 262272 -> 0 bytes -q.npz | Bin 20070 -> 0 bytes 2 files changed, 0 insertions(+), 0 deletions(-) delete mode 100644 -q.npy delete mode 100644 -q.npz diff --git a/-q.npy b/-q.npy deleted file mode 100644 index f8603d5bb5020d5a4b811cd3d5fecbda2c90b6b6..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 262272 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/E^k)uhos5K|yv`qapNSjS| zURk4onR{5<9_VbKGSiHfv=fArbw*U=Tofe~{bm1PrhE{5eIDuj<#=NLzQi_S z?TpBOJ4p#=Qyw=zI^!gs}6I`4l7Vg;u10mCVJT%KL*8+m8|G4|2gYh)QF_u9t6cd0 z-O}}T`rqjHs9kwjumof?`uahPp8*f7itR43;U?ZNZKd%99ys&YWa{}_TG-JjVUTx~ z8e7uvA9@{MGRgYA47;HGuL5@N9a|`jul{g6;bXW`$va6eal@N0>;1;N=D_3* zJbN|_C^H+=YS&)F;!YmC5|--`S5wmuNAqMZ)}{b`JPMEh3t#mI5beh*^}k(%>&U zb)0A>*3p02=?97r^q^4Vt5ctg)_~y<&sRlq52X3`pM#Jh9ZY1(Ir-l%4lF#CuCe0*y#BjJud)9@g^!Sj!e9T%7KQxKj4iLZ9gU&pO8h`J@4-+i|wv$LcZuz!VZtouo ztj66xe2jJmDVV(*t-U3RmtUE4tsvDT;P&;~Jj_f`wypbzhBM)w$~Qp< zwkZ&$@-!mE$airQKGj#HL*taUDh1@BGQMJ9~g9)*s#Nsk6quIF7$xrk2P<)2~TGy z&C=W4zGe{l>iSL2`x7Yo&F|m6#KSZy_%XVGjt?3{{dSVMOAp;m!~R;GnFskMER?T< z+41E zm2+lN_)Oma(>JpCh~HAJyz+nm$@SQtt(k0T@nX)qALc@&)}QDe=F1+t=tr;Doh*^``dEsHMl!mCv@7~65B*G&{FKbd6-+h_()HADm6 zShGTdJzZsNkFH%{#;V1Gy}oUIU>`4|stL(qEx7HQ)E{jF zFS_9yZRbV-BVaGNqR53=DB5^p_A)@wKWA~ub`}L}zTSw<<;HT~u3nFRK!sT!@!2Vo zp6Is{Y6-3>;x*O^3AZF12r1t450~G31qZuA>Gr;5hMQqk@<+(|b?8g{&D1;^?5ODa z@r4OD)H5q$=O=kwZjxJt36IHAyE(?rKBqvKKm7v@1tAQs3)A2V|VrwB@xOi z?F`dCF$Kcyk_9f*hoRjex%Ll6%tP<0R_W z>@XznT+9=;KS<@AG?(>W;up?5%xe8}8TnMc+LWfGgL?6olcUmB(LA*otv95=l!51; z7sd~Pz-nG37{+XPEgM7S1J-9JCk=!2!=a3z>KqSLH@*awnd7UB80Zj`h zn|pG&@y3@%U&X`3=g$7~dU!1HOQpAktrW1pNWUd}hgB+U8@4V{S-%ecJgAvLx|}dr zr>s?I2kCLX$+Ke~;l(yy5_?1b{YLd7t@IV1d{ChM#^14_S+eh|rS_2YPGj)UAzF};3vt0rmZygt-!Q_!z594y zmNVna7X+Qx`6-}&F0-xeff~^A%$LPqb@$PaXT+S)jG|@M7@B2uN4U zR=;#-1!Zb5kJDajL(NjM%A+bj!E5=-TOl{NVXPXj#i{H6K#!NdwR-CeFpIR?7i3M1 z`8R#42AM>moEV!k)?miYR#^h4Iasg|>+yd5P)c}qaer_adCzE7NSRv|jH2kYqhs6W zxp0o5LQ;%%0oW;M*>ixC1x}bsyyT$egqk&B2Wq)!aPlEi_)rwX@8#U~{+8l~*VNBH z%g|T{`^N;rHFBt-^@PYZR*q*VP$=kG$Da*k=d`K`B)7nW@xO1)Rt50oHIaoI7p6eP zcz;$&g&k73U1)zo&U=}u#g(26!tmyfGsis+ETRUE$e{UT zKB!;yH_l9z0dB0#aw{v$AhBJ^eDmxq@cC8A>yLf7vDcJ%Ypxv)WH;{GV^Avrk1~%{ ziI8&#|9)}4j|qHO$J_qhuYfghN>@Z5b#TFXneAYKv7Oj^!!-NXb+TuzYg{BUB}(Qf zMz0A~0@MDyl7($HH_%+=+Qocv9*u)nI`NJW^R3bS;P$n#32sJ#Fx9$~}yPTRtXH)7j(%%Tf=QN=V*2nqro_9;RzpP2$1-!d>QC3{F(Ft0NK2K>mb7JY& zJ(GQAY>*;dhrfxp3GnYq@t+ta`*~Kj!LuKEF%zTqr78Aq5K_+3I~To;VrHYH2G7p} zj`j4R8#dq3z2EM!cL-0#`|E#~{<%@%F!7z{S0^~IM|qp}pQJ&s;qgSaD3uGoQQ3h% za8cp(M)uMsc9JufxP59?7)5vWYHx$%T(B|y)3&V7GWaj=Qt!m`OynNGGFG~W1}0QJ zYoz`=2ab+hdXjpN6B;S#hR&afMpoZ%p2*)#fy-riXVv#oK+U=@$MRl?LtmzF2DeTw zJToD|%V*pKl8?QODIj~;PKWB42ClKg)mmxi9b_&b(zWm9>*4`47a_)EW+;W1UHFsj z3kHGYSXvroUJv>vB38aKxrDq*lzt5hT^b+6Hy6dpw zOVb537TSF9vWsg&8+Q+S-zzWrpnwI_9(3|0qEGzvdF3nqE1RgVWRD*oB{P&w$d&!J zy9Jrr}%4Cx20orr)!9A#Mw=9-jJRD}`eOJ$Ns; zn>qD2G873Jh>BSPhg27rwCC7xo|NFU<^=I2sr+6$zD@4W{Sl1|gb(mvPNdU@j373O zE?#qa!UE6B?#cO&l>WLeA6SDz<#^gzj4Z?_X=^*zu?jew;M8!05-wK96M-bU}J_ z(Q6m%R5IGDQ_F(y^fjdMTou8#1q;Va@Bcx?<8GJV2(E!Jh6d?9gy(5)a80I^H2n6K-O%HJbcRnUMUyH3E!|&=TV-tck!elke}QW#VpW zkN8ML{RRIGoDeqJECZjVz4lv<5YFo5mmk*e%i`hEZnc?88F;qs~9{J1;ccmw3a3pR4qb7zcXH$y6 zMx23{;hj=YZSuTRG<6o$NV4BQvq}D5Q*~sTNI!Pgi0fWd!VY|Wzq3?%E#Uzhiu$67 z9q@i`rcU4I#C3^V z&-B7IaP{zN>8)~V{Kl`Q+`DQgPOzBhTI>_X=buH02;}fV!^HzaH4*f%dza^#Bg!)P z`)8Jwo?#iN##5AW9@?NJR%!j}Hn=L{z%TK^-k|){qoM=)&#)*Qs0wsxqLN)OVWL{r%sH6&6KU z_jg--&glc7rdH^BD6awqlOx+#zevJ>3poQa%jDxbt2`X=SH&!%2P`MK)SxXRhx(o_ zZMZf;m6mO&37^&0#ZE>a!SAdDFY3t1Ln%Ei6&YbwocU-TxRVld>WcWXNA@40ri8(> z@w3Ti594c!6?!lCOT$0?+)gFBYS{JnY*U-aA3f zV_yYpnHP41A2RxLu;sZX<~rv#8WchW)#S|WMBNTS<>tq5?$%!DcxRcx=*V7d>`9ZH zyeI=5x%2az3ste#Gtodt{siRn*qKH1!UIJ0o%#G1_g-KmET5oHc+0V34WA@SdO%W| zLF*CU8NhOWvo!OdD(pG(;`kjwS(q$o&OBe$hq7m1JykMDMq$r+TAxc2uEif&n!x{5 zp~Ho`Bj4S6QF?9OlvOv`lPVALqNP&9rN;T?CoAMIo|H+vK{E|}WB=>F=#+&VS@uc& zH6nSmgjQzTt0j;zxWB5n@&_`^4iTt)ScNn>_P?w(P=XPUCgmoPG)%d!$09nuibN)! zoxRD_0O)4Rm0m=wqUdZPp*NSlqVlUOwq<1AdqzZaEwr!$wZ1icbkKzoa?0qY?;v?* zw5Vm7uIDNOHxfTq4=#Z?u2a9~AASP{QDPO-9#q&`VB@u@PY=qK-2d;?{aF-g65Q*{ za1c)ndJa=NYhdq+v+)iNzrY>V<@3fVgCIql?TFptCK#2Hh%h|43@YE~d)>IS1m@~T z{+7I%17Ch>sq@LSsI(784Yz|)CJr<+SC)i}mDcx)XU zTh~8Y@>K?Ya%t6|5T%93TfUoB1~cN->%J7zf)wy$!x+oLnRPHVC5c!LuK+u}D&_|k zwB&raXm&GC4hLFCT^uFcod&B7cb94kd z_u%pA+9jYeQyMUI=ntsD#><<*Q^0Cjn|7UWPMMgCCQaq~LB2yvMa-o}03UeED5eu{ zf*1FS#iQN$kEoNNyo@BgaaZ2;2elwP)8?A*t*C~5PbAaZ-jKwMUNkdvyJmsNP{@I7 zn`$)EF;~dFDTZB_vfRHW%R(_8A2jl*9thGl%Ks<9fdeD2@=A}*pnv5hbt7z>i0REo z*GT3SaOb*wg7U3)^qFbp{gIDTXy`yb8?|Xas+T+vVj%h#iA+A-eonk=D-s4{yKYNE zfwe!%=SS)AnazQ`=(nsezauP6V1gfaOJ6$Fd5Qx6?VDY?8T|*S7Pvo2`LPaS{6!KQ zgnLop{beI{IzBu}RUY7YlgtOTb=%U5mx1gdii)w7PGtVMKRbDpyubgW+>hp1;jRqI z^`>m)pPfUI~%A6F%%}tkzPIj$=M^juGda-1l610!y0qJ1}hP>ycoLoeI zj{AOKog6{}^bEu_oQHdga8E}#2p6S`W9N1sw zrQEm-E1V7-zE!{%hcaDE+J4`o$F@w|U1ljg=rBKeF`&wbUvLT?JSE?ON(#?f^ewER zo}d%^W0y#-D=FKxJVd!*y_`#{eNq2$=1 zNnlIqHsteJ5Z~fAKFUM(k*IgB_DWc<0*y~&p9(q~Q1oFF*T0TS$UExfDIUH7F!*9k znayPrJ^mFY|GDZPG7LMeX+Y*0pA<7IWcA2i@{sVG=dOJ~)2`!n$qRB0`ERew$kTQd z`8YjhQGX6(w_n#tOCX$!4^*iJDa)vPI^^P$H=W>1GDS>W%{rpu?Ou8nAPid#Bh;Q{ zO@I$Ua>2cCg)vRZv4WGNhs#!&s3O`qk3On6c#EIv0IBf}{}5F-D4ma|b|bvtOW__% z0cVy_e{93n$plK6&=V-4S+@Dy7ilV?#raVurpNt_}`D^!wFHzu`SH(469fQD3 zZt4D=WU^-woae6dW*$gIo{C3HLijwGoI1u9@rdjLjF+}B zNm9WMeC*F+F+VJEV&HA(_#Z{*;g9wAhhck<$KHEyqNL8Lq+x_ak)lW+otu{^q5#0F9ty5~xBlvMiWM!M$0cPleFLM>2qJt{c^TGPk z+?Y{v^QyZ&Hx3K?{qVL3C!ShWo-R%82WzI*7O%9Mz*n!$$aB}|aD}qWygK(6wCmi# z%a%G^*r4>}zd4=pT((KXJgv|`n1g}b8Xba#U z+~3=*&+ubiQ6aPFlXURHWUzY+c|NmDaXikU?*l~%;e6S|`>QN!&(pSZ2K-o9?4W=B z6D-qEx~1&-Aj7r$p5{&TSV1_?ysWz&-2)7aS>PNXMfSavxjwBUKAYe4nOP?83S)iL1OG(3J$uw@J*d~e7mLp zE2nRn1R@dQf&~q9_-p00+Bb?~(0OvpS1V~9C^b}-%wAqX1|k3XA1`8nswu|TJ1iDZ zYUq;psW4htA@S^dNF?!?TADrk+|r0HEVfN2DD&WpQGZ3!F3+LBx5wk9jVpnSISqC0 z_Z6V|fJ$GFW(;Y1=~|SQa$w2r^b{FgPMA}AQP0nS3yUcp2;csY?A_DCJ<>ZyQTv(k zQ#S7kkiOpIvnE}{=l0k0xa`RlbgJDebE1a^<~GKMG!aZ@pJjz$rTsa|-Y2ZM z_eGzWA>s1fY1-QpXwC!~uZEQAc2eNMJ)KV02_ks;wAD@}{Y6mLtLJP$ysNQBu?gkZ z=FuMi^hdf)y&y%JEu!%(Kb}9_5;~p20lf?A92T4YfqIv%eWr_i_|8%G9-W|nK=Ou+ zpHF!maDM(%IFj(uE;3v2C=AY{P5UQ9pI%bK#)IRwuNDO0g-zwT9bW_?P01ba`KMI) znQq({K~V}E9ymCd!7l~Z8CsZ})>@E4&)uy10|Gd;$5!Cm2o1i^o0S)&xD2Xwzo#lZ z8bohIlg>NDi{X+lOtPo1Q9&Krz`k@g3gO@m(=)d7!gH^ue8u-M!;b5$L!1Y<&|txM zf*(5{9Ns3z)upis*50H(_!!Ru6D1vlZ+p?;VuSSPAd5-BB5!J!NizkeU#IfBdeGwI zLPyv+omWxvQ0dSW*G-@r#JP1$ln*x2i5Trvq{emqr#@RcGT_v+Ow#KbT}Q!+@mx9%Tq2vxGJP?nMF&%d!~i1KhP7xx;m;U*Vkr&t^CF8%*t}G zy}9I?&07KN&-f_w_8bHL+G)^q?l&XU_&)L9Q&(DevtX9%*z0*93_d1ZKO;!`T&>6d z5bs_7OuWiQ5#b~qKJ5FX_ZRAL`?PEO@FH^DDfIH%9yTa8<(Tb~-%9gjZvOURS%%0%JeF@WgXGFj$e`nP=#+L+5~a z%(^iCs5s~?J;V&z^d3sL7Xf} zmhZs(f8ec`+3R{UHvF8jTgbj#3ODU@ zd&h(wd!)7t9FwQV&%Q>;8j?LQcdBR7O?nF4B`r0C#V9{%NtdBKY0j?lR2~!fEzT+HTd#4H+Z1KS*rk#`GTFJEkl} zajJUZ{^2fu$TZl?VL9E8++4=%{;XaCOrF7o#m6_$dUo~Q)>_hIFe@(<+$6j|(XxdP zO+t8nOg}NllX%(&gR&elCIRPEU2%x95VZSkF-NVtivF_I*XRDDUP+gG7F}$kv)0ukC{!DjA_z?^faT1UIhF0 zs7Jn}9tR$o`)+*RL(WSca^F~TWpQlfiI)!~dx1*>gU{LaB5=9=CG#Zdv4P#0T$yGh z|G2LFK%Q^~vRF*}6TZ&@fuK%xmaa{33CjNSa}vOZuRHwv@6!az%3L1a|6&{{zGU^W zKg)@uyWLl^jw?ae(?_cAlD>hXT2iuy!#YY=+(|Y!g776Aajvo?=f-bVncTm)@$3Fl z)3+ZR(CCCa)5i?r=gzx#)U%!qzNGx}C{&<=J03P$UZ`Y(M&lKpFSM!P>bqYIElNT- zkkzcoF;x&6XO;bU#vzYeWSBg94aPx7U$EQRHR8#j%KhnRBTVuJGI=iRFHwovs_eUd zA*iYpA08XQi?c#ci_zNV0<_@dop?+NzZVW;*4N{~Iwr9pqH&Dy-ns=&Al|@tt>>aS zjtD?BHhgiZT^-tr+SXqqoSyh;o=g0i?C|WVY0+U;Dk$i!mV89vFPihUaxTD&K$veV z;DM10HvTj*x?hv<+><8WYI9KV(aWA+lV4F|L7Ci+UC-F?#XljmH@g>r(q#31at{WT zO)GWDcbM_>A776(-{Hnr1XFH~nTo+O@#U(vPfNf^`=vJ1-A$xw&RyhIItnPi=(VH6 zrjd8m+|VL}4E#B~R2eA53X^q;_F@P2X1@CUuA+l zvE{Vi^0;A-)4kGM!m$Y~&y8f!=EU0!496!&xZ&q_Y*EzWf56mW{=ADLsK77wmKXbpHt9>6e9m*iuYKyY!wOjYWbnJ2JpY-3Zw1S1w4waCH(v!c z__57btF0-Lm-JCqK4EGn3r)9*=yTaPaH!MnJ^q&@@UYaRE$w(Kh!U`UM|W!lHT2DW zPxv!|&VCl%IsRuJrF1@HnI~MW%F>wSfcg*-=!QaJ9u_Wj@^tAPHT z?g60+b_nPDuFm`&LpOfr>icR)W8`)*Ws7$TP#R7q?Y3maukO4yojp2=WM|6L8oSu> z_3#6Ykqk_5;9d2{yoy!u?TYivTZ4A+h5k&-FpmTt8CMGzyvhh?C~o(zafm~+<7MYU zT>An4tw*Q2y;$&@nhchEG%KJW&5w3igdcuR-0Ht?!vZx7J?5uvc**?lyxj)wM7RE4 z(J*ahgbOL2^waxR!HI&jg1PrB_?8DtpPL~Kb_-6BF`HNeJG1K8`*o->`gZv#hcTJk zO{#wGKSDe6bucg45x;uOappD2GgaB#+o>(}vdbY`Lc z!Gn`rFg@8)bnfZ~lG1PyzY-{kO;|p*1(EwQr@habP6#WcciAPZcWxY+x+>WmA)M** zHby~O$sX{l=!ibuw>1z(-B#ooPY3;U?IxYi3*ma_s;?G*X<$+fL#ErWVQ}S#z5IE9 zc4&JnI_)I!02lrI^zBLQ7eMvv@GgrG8vLJv11+dzhDo9AwnnmiFqQkmE4FKsC?hpP zGAOPCJXP1$vKL{6PWSX}LOGc+%YG%5H?J0f7^91FYa=zZ*iWZ}`8eQ@sIu}nYXNL> zNHXW~9g;UQ^AmgI!-Mw>{mjx+{e_14%pA_1xrZ<7 zCv)_pSLW!T8p&^HFC{3(5N@Ywky3|M%o5mhNKCkDq8T)(vQ3FG(!>2f9)ACk!38^3 zW{tX+dGJ(G>_}cdGx&wMg;X=B_cPw=>zhIBd?h+rf7!4>$Fb14T1Ncj{lHiG zS2CD#f#KO6@i}ng-1gnRe-^-R+cxPq6#?8U_l*5N;vsl$nx`Fgf(9D2Fr_-pucJF` zA7vlVDB#}Xon7nS=rQfPNXZ?<_o^Jtv24Jy3J$%XRlcdK2*ZV)%f@F};56`OJW@yI z(rfw8S{@I9AN*-^do_gbA+q-_JWTB{Q#Lm8=(-BQPQv9U%s<#f(o~_+Hvqa ze}c+xn2II%{YD(8eh!>bWP@gd8M=qm38{NqSn`1)G8aB=+FNfVh3Tm^%wH$2plM6N zEzzi(zn;ue+4xCG?`hrzk-tImM^$XQsZyg$}dOe zbHL$D*G5%NA!v0;nhk|K0pztPx=FmjHOswpoU)*D$ZP#RK zgftVz7wwMNn|GkIDxy6BlCy}m+wQC+nQIpCjbzVn+d?lok?SL$1+XjC%1UH#1$C}1 z+50_WfW6O8F!YS@;PGGXDdK-;QE~x$<9$gs$X{Uy-UW-}a4y>B(b^GoxA%?hb)P=O zW_QLi<=pz1!36; zedfPO8qzi%vWX+lFFy(AN#ATCXq%f)+m=K6l>x7~KoL9sbzftD0V@+W6yEEVafJ~& zJihSr`r`u{Eo^=oI>{Z=2;EJv`PiL8&LO%J3HQD=0^27Q zmrf^cqK6Yv2Xoaa7 zrM_dF;p6>jTx=IVRBGgZf@j0JXQ*HmqB*|uirl6AM(ifcc{i_8qF(qJo>6F z2)Tzt0+OrhdY-57wX25%>xCEZUlympDQ4ve$B03Y@u~ip;^Yj{DH)j= zBRL7B9dX-^r?SK9Pan6K4>96uHf`CIu5lDq$ty_h(hH15Qi_HM|M97k_=9MlML_vF z@7AKciXP_P>q}evN4{StZW-&&A{E!GmM3meL9<0+naI#a)ZEObZd$yCp2x1)&y(D5 zcIDES#y0ZvTNOOZPxD|J(I)Wtbe%A z9#J-YVCd4X%tUs){anbA&3C*|KVVRmPj?mEK2UnMV;kuky4EUd9R3cz-E0eio80hL zxnRh(U0Fy-ar@=CO$N*pVSDDG0O=V;Ryu{cb3=}(+YOE(jL=_C$n~$HC_eM~r*?P* zANJI&r70O-11;+^Ii;C@!J%8jmdUQH*m1{!HvSkctba$Z@~0K?`TE*eZ<71BW5~mZ zJSCEAF$=mBIJk~jQ}IsrI5B)f?ciqX(LTUzxbv)|FPYz39vFIfo*&=P*m4Qen#Hex(}+BmwFkpZwsGOF(Fp-ZI3;10%2L|yUv&5ZOLL5M z2L+3BxC%MR2w-9JzxO|{Gs5K0j;U4_!f+rh)vM-`Aa*>SdRVA+7KNRBzi5*w3P)5< zdKWR1-iUPB5Oc&BDzqqxxO9S-+yjNvT?t<*RnaO^Sd9jzEq2X|N{irFJF}N1TJ*SQ zUb3x7hX!ht7P~SLF0kjrRln!AmQj3lgLt`}Bxc}n;V|7P3U54?XRW>@0iP}AC|Zzn z()n^6KM){u2@^4^DhRbCNVH?NKwR=|JIB>r5};%Q$q5WrpnI!Y{IZ z65c}gN5>p%F3$nw%(faKjS(bTSMIzon-)6VzQ)c&a_$Mnfr=>)r_qfu6fOOT1{!@a z3Y8z_hAUnpq3)gH_(v{pouR%q{-ej|C}PczC+ejCD87(`N9yUqHM9p2*J$8aptTZ~ z;3>fkm*w!)N{7B?4FxFiL*9m$_#XIF*uy_vRK_J%sqHb00{EhKgWZK7TD)&EgYgf^ z$H!(1igb7NgHZ8+x8C!k=(}l$W2|lunoVzL_+`q3g*49`oqWU$XDV)&@2_FUyKR&X z44X+|$;>Yg>^(?NWZlWYmhd%yI9}S)NS;S^u~nxk7-TVTL}Y>86VkW0ch>vP#7c5{ zojrPDjCeS#eC(4r;q(W$o)&#R2Y$9c7v-K=KyrDn0xI@%V%?$0*ZMrwXqyD{N85lF za8iHW%zt(S*`AL`TOmDojXAK5Kr@j>SA@3I@nc{Mlv`!AVUI{4B1 zbj4~JBNi8qYOW^FGux=g+E4p9vFAI{D~v)~FzxT5v_;|(*!5P0|0V|y-iYEqJT8c=auQhA`CVBh ze2%M@JA2fv8KJ&q;GXZ^tDq*ATAQg`4wAq&P~FLX!GVB`!13XOL8+w85pO> z^@D{rtp!5xaNF;NORADEY^S`e@ZCAUHgK4eK8oa3GadESC7y#AhnczQS8_1Qej)dr zH$Oa`p!|Z1iumxt&qaQs=EvT&MN2W)L}69D)(4(mewf>5|BHI}hRKu_*0c&ni@%nDsp;D`BLw)N=3&lY*1hUiww{ua1#~@8y5Fytcyc%zE+?%q;r3^OrebRR(BtYOF^eAqKzp81m_57?1YG1Y z8``2kpNq~O3I%JZY{wsM+dUhg&A~GomayRSHP<<#IwYa9iPzrOO{67im8ufsG!_PP{B3xyfIBf0{TLp^eD<6t(er zFm=&tLY}o9Nxc*r7<@^MOS4{et=bF1>|-KtPp7q`a}T;tRY(6tLF{h#Z=NAu@Lo4j zF)Au}#eh?Ojm-P4sKPU;;0!t#yf(Ijj~Dh$Iw8fsOmN@T9_O|XLh!qBVfz6F34C70 z#_8>LX>4|KAH(%1;)T2_?`5eq2fiC*uphOjV7v4Hbwlq*sJelrltEq?p5Crt`KXs3 ze%UKp(nx&OyY&ma$3m!J&>lX0Ytbz*{lZMT!D&Q#R_yYqm&*DxCk~)F^)gL^ z_=>z8i(imF|MHApR+ptDu77t`eqfI<=Dc)oWt`+}OK;0}*KILDj_W~GV!{`NR}@dDuL0(v$*1r#160?h zeJJKFi7nwm^z$()0tsRz+faUZ;P{2>1%AX+y6ow{_bBmh>nW}sV5@$|_6HfsFXm%UFwQHtaRR?cG=@imKDK{ze z^FiX+vD~b5C~h9@&L_$GLt>C_j5aO6fgAD<`zMNItRP>9dB?mrv^ZlhuQ+cv;qiDn z=vwXKgwEpAG5a*Au=$=H%FI1%SU$Lhvy3taMo%VuH!qshAca60aoEtb6RQq zcpGUOu8}@O#Ax~0R8}==+u_DPevcdahTa;bgo)!-?i$zjr_^{OA)q-teHlG-ckBP- z$_5LIKO}rr5XMcnj}~={Qe%Obp%Z$(GEkyC*=@#A4r+87Nemt$zJiOHULT@_aa7Mm zPXj4In7CI*c)FGs(wi=9UteiQ34$sYy;kPXyO=-uE;O{5N2`B*q>y+ePXjfujUWHV zo?#TB$cCjBjp~(HMBt~%w~@nhEHL-_i!*NX!g&0Y(@*;I#J|$x5Gflk3p+JDL?6@6 zpjR}ngsGDSam}Kmt?wyDEQrr~NsWub7nMFw%n%bS{{AiJ|MR*qXbmqk4}-h$Q$hLL zMQ~3T88Tn|jU@bZhL5%r?-#mY-LNQvIbR+AVcO$|d^XqsW7g1xf@ZQQ|9=PjYiIe1y6~uVK zQ$a2;8`OTe$h-KP1yfzk4L<8n@~rd6_FS9#gw{Q$VxT11(qz@%kAFzW8g152@b+?v*8;ALc>DNPmHifxBt$-PqYc0lfexb(J zj(Vd!D#JkY+7ugoPbK)PDcQi!$_{hHHvVnQR)Xx#fL7U`Q((u0Q8p?XLdEm1b_G(; zf&RZ<{Iy4_fViZ+b3k4{2=x46IJsjIbO;9}Xf3Uyuw0R98uI+P5TLxcEcpi*W;d6q zoZ`Y>k9P`6ed5HHt4HaD77==AI&$LAfhmw%eeOo8)dJe9U2o)Zo&(aqYo>MFM)vHD zMID1lg!}6Ebxd?-9`L-$<-J);xD2`vUe1`zqV-3bQO}CmAlsf71`&V)Kf2yJ;k~^E z#25*G%6q#A>dbg(K9b!3>x#S7;f~Ze$irBfTW%f|Gg&sp8uQ}_`nmqJYE~?MoyA(O zY6G3GviWH;_8al!?(2m6HbK{6qG3)zeFS4Jq=ZRM46@X#!yz zeX{?(7r=D)OP@V>!V2$wQIj_(Jc*W@;=ycEwD<|9R@i?5v~Yivot#WBH4KPZ=-4yH z3DumR7D^coBdylFm!oVONU0_CL53yCbvD1*b&BN3^fvCT=g;xrCR(k7a@kd&j7Drv1_JX^p7>~FR=D**m} zT3LM^EVxCy^oaT5JoxBA_cCdj2a2B3lRuh4&ONX81=f-Li1+cnv^Fy;C?fp6pkRFl z<=k6(X?vIf9-b;>{ueEV4QD>Kc#%Gp^=S<&LoNYm1jZx1<0v?3bs~6$@C4F?gFQdT ztpksfEQ|B+NG{4cKwvvLVXD!$_C0iB9AKsD{MH+(zs zovWNZ>~c~9-lh9DuCyx;rG$!qdalU>nZuedUrM}*${6GSGax-pg99d#`!cCvkMNIz z=L~ds`Gdaqkwz|9rY695KS%(!o>?FJc9a(<92j8B{w;vBKd3o2c2e*Kf41Tq*Vyq} z-iU+R#4oPQm1g5QNWt?%t(BMf#Ietmt;rCt1T?>L2A^*zp;N9yYdHg`k#accYoroefp%>BqLD>wijpqc3EJB1pXoy5Kg=*e(puv zv&fuXm+hwSwkf1aC%oIsj|v7`99!G;-2l38T|5~J7%+GJlepW2KWKCzf3q--2Wr|} zo;f-|fkG4!Yvt22kgYmFYm1%}m);7>_T#KCU!y`TE-y5hW3< z8QJo=zHb3AjWx@u`fs2R9RcIvM8duK`*P&&3kvLN)H4o8qbO71v49fkm;R!nv?R&# z!mXnW%_naVo^ZbCr4~<4n4fs{je_y^QcZ>Kpnz~HCB`>3g9~I+O2UuXEC?rAm)SfGN*DD)OH~twZAeE=p4H*xl#1U52!v zJMZah_!d1B{Pc;1=Aj~NW!6**cr6Z<&c4b0M7$<(ZT+fFPZ?lwYm9o~IVN0u#r1=K zE*Eqa_NhK7%!4Cxw1~{HW3vKxsamQU9abFF>HFYw2aQP-3e4z0) z<`GjfnjhJltxz|QehDVKmPM0!&wXzBr__Z1ta$hRG2ca?J-tY)9{UyH1Vs62&&dP+AhTCSkqLUg4)l|$g$ zna^)Q@EU5a`(<%~oY%9RpP5jX%HRkk538JM1~_$|^~j247oa#494l`Xf`^j!_rL3+ z!n;zl_UmcVvU(Y5PBCJ|dpZZwf5wi0@5&c9&Kggn|K6x` zP7u%iGub_q@K|olB{P-(!bb>d*j5FUZ==SYjSq)*YcgVOk&zFUzkVaGBD(lPDx+Zk zq^O18)FR>iPmh zV5hT^%6c^wq+b2*eHYGx&YhjEMSY8a>u~)*XGIS>d+TqIBbjrEH%1NJ+L#0a#W#;f zJm7*kQ7|iOjTbxmC*StCN{dr}ex{p>md0Rna(6HBKe!y>J8SPi3x8Id`9CLq@0-%9 z!OzG%HL~}H^xeT)pjOmJd1PFN%W9hCRm~Rs*QEX;y5~#_$0^3P!J+ft*~uP>=30f>bw>d!l{t{`Qdyvtiv_(^n{TB zd>b73X@-Lq(rTU;mPR zw}zB+u5@X{^1|3^^Y^Y|-;lM}=w#Px;(1Zzi_ShV1N!!Iw1=N)2Y)X4@zyhRqEMB9 zZMQHhmOUc9JYGrzU+{c7R%cA+yJPBuo{}pdvy3aEyYL?hF~1=lN%p00=n9$W1HPfe z)8et21}mtCp*dn(`x+Pt=(~SXhKPLD?)kNE^gzy;6Yvi>4F<=G2FY9rS z13rU3F|Ip_zhier+OtL;%&L9aN9->bKGeqlw{vz1#Z(@kfAd!e(v=D|Gi59y=aIYi z`~5LUzOFq$;PXh0_hSp!2=S9n=~=cl%%XR8aw@gU0@zSS#==vbaKe}+RP$Y^p^Q*C zw*&{tVKdoD1-;s@DGUn+l2!9~=1miyK<^KXrH_&w!VYW79m* zDm4C>CCUB7Jg8r^P%ax|f%iE|$CVc6(V4{>CDyWP;4Ai6N=-5sZI4=bp^n%f+KRuw z>skfKpd>E)q^%+KrVU>&b1rP;U0R{PgK)Hq2gS3L`#|`h(w?xn0aPp+-jgOg1I`xR zlUETFhV#*tQ+Fg6kv6r9x|ljUuKIcB_mChJoH)(CH;253x2`aIuadqk94P8D+dYBk zLQSP7YKD=haT?`-;5hJKKd|$I+9dd>zCfSCwTPCtZwfCg4uB@Am%NeNwm@Qb$kU|R zA(Woz{P^EVI;=l5bWn7b6W*)0+c$rM%&-y zCS@8p_>1?&amhkt={X+Lttp64hEA2++0CQ--!c=fNwLC%X+Bm*EQRpy6B-QeWWTJa z^N{-187f?;&qHIeT@rRh)6!?(oo=i4VQ|>-40A5#KLg zICi;^4c@jkS31|V0p1p#JLDECfFHbh#jNm=2j57Fl-V6mdgl{u z%sUT!ESFW1CTOthqO!2{TqX(#l1y&+umonixjVI@hJhs`)zd^HCaf3wbb;#*BQ|-H zpUhSz0k7?I%I1gkaL~Z#Kw}3#cK-7|=GnVCKvNMbbK6K5`o(aYSZ=W3pYAaS_cN@3 zuxq?_ZEFnhhzajvzV&~I*5FUF=RPXjRCQ+j>!vVPyZC6J+2u9ppFjHEi`-kc>u!jB za}|WP3kJ1ietbCN>G$NG%gx~3nRCpa-jVr09ZucF+lkb&X>3@|EP-7*j&DK*Nl(YX zNnpcV* zp%Z2_??aF8S>G3ASrdUw=Z@+e?k`8&p;es^s|XJzRm;xc4HdpW*KosIoCmhOvN_@_ zI0I_#8wupTkisYT%^vm|XT{fA2HF+<7+`d3O-_C)E4(!3ZaHz4g4d(ud~f!(f+5Rf zCo{`=P;l^0#8uKmE2DWSkkUp4wVs`5et(w-Z*Q_v+xL?Z#%XZ}^WB*xfA{A{Z;DPK zm%Ph@=joYn1Hb>mibpkg6CB3YyTpxoX9cWE{^X-8+ghV-yk}6WmK7yd@*jA7>*!dg zrzDo|F>@LiX23z`wH)}H`0%|?k;a)lOQ7Vuh!1jc#+y{~$u6@kTmYu->y(9LHe!eV<_l+;q84};Zfl-ScFpTU2m#kB6dh_G{ zhx3k?oW-#|7nj;>9vA#xbLmKSa0~d)(57wMnN;L#aD2Dab9#6b8}|E;OrXHoy6YB) zq_I@oNTAad3M^$iB_cw;M^%+PPraXVW1FKENu}BAX#38-ffp$h=%SQM8b7nB{z#6> zh4T!se?BAkPW}?$Qa$%l$AlG2+e(UR(9+^6kzqqw#p>rTuW}LIH9u-O#g8w4E}r!9 zC!Z@fm0x|gXffTdzH>KB`LMok;)+Aa2-0ab+FcgUjO`!P+S(rCBe$Z%8g=~@0D0~YM}AN;78$&6{P?mHSu zI0!RZZ&TQZR>0B4&iJ{(YOty=e(!qa0_waM^RIuB8S?tpx(N_((b1*Ou&zs+;IwC2 zcu40AT5`U7_HW8tWM^-DVvEd8_r$w-Tu$M}oYVK?<*qW|zb|K7sE!eTlGyhTrl*;) zbVjICd{rf|PPod34^zYCE{mmKMRfR{=JEKvnPId_6Y+8vIq!0GZFd)EJ zzqo64esh{ZpmBv6rBvl03$Nj0Ru}lOg0bj!QYyy3 zq8MEDSlRI-oyc7enW=IACCYsfO$q!UzO!`iPkOvLykM^2Ko3u*2keuX9Y$+)0-9ZU z>p&FZ$KJPo0~;rWszVeO=)UvCQDNfGX$iPA;t@bRm7Pale=s4Qq#M`Ey5-h^>Uc+q zG`R;ZJQ0x%&KL!a25;APS~25~7B2Fx`Ye!Ipo+Pj>;rrb`)M9?4A3XJH?G!d z@sW7q>3DI&yw-tmYhojFG!lM;z|bm#c_f8{ESScxE_XkzOZPj#_*6lM}Y0N9r>*I&EbKs<=>Z(+&J#N5at8Orp!rmIj`ayZ?qNO$P7kKbF1e*a$czL^58MY@x(w zOksySSs>L1DeWx@9$Xrv*U8;Z2YUsg69;`8NN=eu)g(a*Z#D(p-B!balitJtyTBn3 zG9GmKdZGZHYJMBXUcm=1-%QNC#>N57(GTi;l0T@(5ozbElfoC7*EFwwTsnRtd}8%{JEP^w+yb>lWw{FPOR=XK8_YT9?r0ZmH4)*JgzwuVVSQLCird>&r-*P6L? zG>!_(6jBvQej%KQtfvWYx|p%)g>u8+yv@jh=1+IR8x1%g6kW7=Q3Gq)$SY18D?s2g zTej{qjO;w(=B`FdLH?V0?|aHb@#)RT?=FNRmHBY~!tZP9kf}!^X5C5vbL?yEqI)Na zKQB&YpOj&S<=p8%KlyEkW5*Iks}C~Zb{>xvvr}VWf;v5KpQsGxWJ+|Z{!bdxJYk>> z+{24w)dm$+2PNTW{n#DDZ+Bp6ztd}iiSkfeoU(BAIpMR?##R4yR>pSherP{EdA|fo z<{rC9jm0YY#GbqzLY$Jh>IrsK@JX%*YsG>*Za5*at6Wk8M&EC{Yr#2-$~Q86?i-5W zs_m+{OoI`_XxCfDm-z7~`t7UPLo;ae?v)jdY8j{%{4KMxitG<=Y;>f4+dzLg+m)L5 zo5A9h;?{` zILW<+oK`>uT8`)SAMBEbJ#n>ueIeU0omn977MT-d@eZe_@N2=0fxX|0<$0ke z*&qK}qQz<%*p7;&6a{@hw|u0P4jQZ9^=tSf2FH3LIXIgn@P<=s>e%xQ5S*i$KzSes zZ>&|8C5tSA3fai%$is^G=`9N%k5@d{x=~Z~gBUYBv-ozOlo~nDE1yu4>muHzX>)!* z4sLu_$IbHkb0KJUfPww~*ev?3>hdGy0Sz{>YF$rnVZt1BW0btSY2euBCadB{fp7F8 z&Z^x|#6QeZ%$py{;9Oxd8nJF+e6p?0_vd9fc+0SJkqhy_B#LLz zqOus4RyiN|TYeawcJbXE@?8OD=v6O`|C5Bu+)}l{wO`QF%kS}m!3+`-9{ugPYZEw+ zF2&qZ7zV0`$}R~=eg|o%*4I~B*U>E;F&LFX<|GM7e<;8e?xOznP2{3>MW^7svI z{FIufezKYuUc9esz}HLWYt7HH&m9rLcCmlk{aVCu?=P+hTly8yNqgG=?%p}@XU0jj zj=Vp7=wiQnZVBT;-9YO++8IzJd&Ti!jwCc!?hjRgR9NZYNuQ8SS{N_P=xez-1!|YH zl6kWD;hF8pv>gdzIK zpF2IKv4<0??|s-3WJrZ|KIlA~zxWqK_npmI6kx@Bk4$&-A<`Gowu<@7$AtfUP!1jA z?m@eR=FSX6tpTIJ{VJ!R4kcz|k2p z;gTZU>A3l%I)hmhpMPGOkMuy>k`+?+9AU;Uc~4@=9h@*}=|Szy%{648;cI3|`q;lQB6C$4en50GX2BC{{22iacx@=)_C9sK3*s<6;Pfx7m4j;?MO z!mUZEe$?c?&G2;_U5g4e-tIL&s=Konppxg`?cJ#1%PX6==)LC=gK_By=ZHnjy}s1IDZ*Vm11+!Y(TM)nW;G8=@3^aY_}KxWgx6a&_M zGkd~r+W@#X&N)gWKyn+_*vC#ZZ`qd1mNydcqu$<`!SA^iQGiMq@` zFh4)E#PM?l1m}O7r}>Y9OB8Km9-kjVOO-0Gwd@$6ad}DCzehho>D$qj3z@U%@iLEG z6DunYXfHQY-_HyGbr=4g3Sfo5?}Y|c?i0p)Tjp+vtTRCCM_alY&zcb~WqFs^zl?Ss zthp6>gC4uCHRRFmBz}6Ew-=rn(!+7ZdoPX%(&O~}_QK^KG`MnVvjxZxpt>g}i|cn- z;enK@5kKO$-3Se{3V~eERDp6z?${Uz{$|7Rd6{@2)IMmkkbAfptH;TiXp*lf+f_9m zvk4r3n>KTHuORPhC*s;C*vUSWXXieB;>nWxw%e&}3rJToCptc92HBxbo0rZL@6k`| z_3S7fvX|H%eE-fGx>@?=LEt_LwiqOM2yM!F`*4w58DdV~d9akGR)< zKK$QmasK9&c*K6P{!1?FI`FHilJ0;~_~Xm?>yqCDahY3<3Eg8!cyw=xu(sn5AY3p$ ze&#=F!q4vbYa&fN&)wzm`E-luTQsZx)fIYZZ}I(w#wP~+$e!-P)-yUBxKy>rg`Ni* z|8r=klM=+roD6&%sl50Zed4K;>O5GnN^95i<27J>&re$8Q-W}1YsA6cTL5$ER@faF z=f>v+XXgICUjbFQfrd8iY|uO;qgy@yFFKJV%fr7z7&->4YTa_31J3RaE)Q?a1M5#* z6}N4faNU(U31jzZl-yrjG0V&dBQ9?33n1Lb@OINX!Pg1rT5kPeNiQFEFt)sDJIV~* z1SXz_?3o3*Z`4f67|Q@(@>h=w#Cv(uAzt_G@E^2MOQ{uiC43mJl;p=6R8S`AVtHmg z6BNc4EUAMF=*ldK%G0pIpXcMnVls+Q=?>O`^QSnmHj`#w^i4Xf?rS0(tX>T$Cuu^5 zjK_#CVe~{tDHk?$$+A@mrh+x+J`3e3JOw)%mO77zE~6bczco2d?VpRH?YYr5g*#u0*cBcszfq4Fr7m428R(9POId(rF38ksn}#_N_Y-{ z%zU@y-YP1%Yt&_DpFJ%cFA6`gyq6X0vY6_X&V50zAGIi7(i4Sob#ncjo_|oK&S!g` zei|I5rVP~giQt>M3Kf2%B(L48xGh_b4!*0Qp8kBN4lGqYy0tz|!DZ@Cr_Noc$6@oT zVi&4d{zuVyhjaP8aU35XdvDn*BP4w#bq=M>C@Ml4D9S34m8{aHrC}ty5=EkQP9l5n zO$gb0&)@m|-{tDMJf7#A`+mP)FL;*5&d=I`8-B})6p!d&#hwh$51b&BuL- zxPD1>@eoG zaO=#SDG+&5_=twB z@CDy9zsYC@IDfV&*V~PF2&8{sW>XWuF~@K5HC$%U~O=!}ZP(S{SAL{lEPg0=VQ-z%@lHt<96DV_d|wU_#ju(kJneYadwbx&!Ej3S`9ZI1)n6b z{wQ5zlh!a${KQn#Ej@wUU&@}=?_q<%NjG**l5<@x-K>PSwg48^*?D#Qu|CjwW7iFD zKW@lhoh2ewG6ZhD*As~O#e@6w-Ye)?t%2+R?NTXX$ps554Vjk3WWVke^CvKH6Udq^ zSHByigEEe@vKpIJDBpWgZ@Ym2-oNTSV=qC$cBa|lNA^qr4dZ^7{;LA8Z_32RnRwMt zw&Ar3PcGd2=+L!Z1|C>4UT>zmLUJ9N&0?W?v*>W$ui&rVV)$IhsbZ^Z9Pk{}@-|-L zf;2>Rpqw#4c=`&WLl-%*d*Fzd^h0Kx+IMy3J?U=?#OK>A;$^f=%^^L0bQP5tB=+}3 zHGmsmtI|vPL?GYc&xXG86g**ew@he<5Y`^Q>}c!G2kWz(zzGd1ys$cHU%HKar}RUj z@_&fpJT8q9@zD+BB{|S=W1ST`7u04sT^52IW1rqXtR4c=$xCaKHsWyC>(}gV@^i>I z?W08?;cD(C77`axR{ZXwh+n8X2b5)a*r0fI0$@HG%}4HBIJVwGk?B1jHe`+FX&_vw zv5$1k1#ADnAMN!{<**6FyI1#zIP3yfjHKc{_A_GBMnNMy)d?D|H|){g-vEXkX<4s9 zF8)t-O}lGdSsFC>%nOJ3t-};plRt5e|5p_-+b0o| zG9w7}DragrW(Ba)z(L;b>pZaI9hNe!7R5Qdjh21n9IUT8q?0bsg(bew`QD)A!tI`$ zbVi&MIR7e#r;&L6qO<0uPqXmhy0T5rqrx)yyQ#!dH95C!7U$6>6wd(n!1}&$lHa^q z(zb;yQ3j8?$+qsl=?lhM>-eDJ5@@HBhy#CU;jm%Uj0*WZg)wLC{*PA%SL#n`nlf== zj>|zuZEi9{=aeIVRy;S5^_&FlPr~n!U)W(T_g4xpeL7lv`{Nj3?jD?yAROJ77m9lA zt$I*{j$im0;-3Oe=@b6s?^Y&;JM#2fdhD(GV|FA-2)DMr3koq2hxE+%w4SEW!GBKm z8d=A<@$+&Mb)jSA=U)p-e9*Cmfc#}OF-zjpkA*; zemgiq?J)%=zfhLe;TC~gk5`BJ$S`4kqn6L5+ZI5Ww_3ds>A!^MJimS*mkG-k2}juw zt_9pPeaU%}8II}tSC%G|b6EMue^wE!xLtTYLM(9<6&?K~tM-uxUfUt~+1G=-AL5

uJ1Fyt-uZY@t@`>;#E1f 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 XErK{{z$E5H{05)C^uAKQT@d*nv~Z?0 diff --git a/-q.npz b/-q.npz deleted file mode 100644 index b55cf701b8f0cdf4a1d68656d1a8c3562b85e4e5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 20070 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 r=rT4~tLtASDrv1FYgy}=fFW7S&oh Date: Mon, 16 Nov 2026 07:13:40 +0000 Subject: [PATCH 20/29] docs(sep-0052): report milestone 4 (phases 4 and 5) [skip ci] Co-Authored-By: Claude Opus 5.5 --- docs/dev/seps/sep-0052-backend-shape.md | 197 ++++++++++++++++++++++++ 1 file changed, 197 insertions(+) diff --git a/docs/dev/seps/sep-0052-backend-shape.md b/docs/dev/seps/sep-0052-backend-shape.md index 8879d08a9..700df76f9 100644 --- a/docs/dev/seps/sep-0052-backend-shape.md +++ b/docs/dev/seps/sep-0052-backend-shape.md @@ -1310,6 +1310,203 @@ Tests: about 3,300 lines added and 2,000 removed. 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. +### Milestone 4 (phases 4 and 5) — 2026-11-16 + +Branch `feature/sep-0052-backend-shape-p4`, stacked on milestone 3, by Opus 5.5 (AI) for +John Travers. Phase 4 was developed by AI agents in two steps on branches off milestone 2, +the new seam beside the old one (4A) and the adapter moved onto it with the old seam +deleted (4B); they were merged onto milestone 3, where the engine-level parity tests, the +remaining cleanup and phase 5's documentation were done. + +**Scope.** 4A: the field-table records, workspace, probe and schemas (`14cd4f38`), the +march and watch records read by their tables (`35dfa32e`), the engines and the fault hook +over a workspace (`218aabb4`, `e81c220a`). 4B: the adapter on `Workspace`, `start(run)` +and `probe(start)` with the `State` seam deleted (`6b4716d6`), the native tests ported and +the split sums in native's `AcceptRecord` (`da4b5e69`, `4f675c4f`, `5a4eb9c8`), the +generated stubs (`a70d32b9`, `0921ac5a`), the binding's rules and changelog fragment +(`ee3fc8e5`), and the per-run start cost (`09f1ad0b`, `877da66c`, `2402d862`, +`2ead0665`). On milestone 3: the merge (`67af9d32`), the engine-level parity tests and +records by name (`a65c96ad`), stale citations and an unused binding (`aa249879`), the +documentation and ADR-079 (`6041fff8`), and two stray files removed (`095e344d`). + +**Delivered, phase 4.** + +- *Records by field table.* Each C++ record that crosses declares its fields once beside + its definition (`include/solprop_native/fields.hpp`); one converter + (`src/records.hpp`) reads a dataclass, mapping or tuple into it and writes it back, + refusing a missing or unknown field, a wrong dtype, rank or extent relation, a strided + or overlapping array and an overflowing size by the field's path before anything is + allocated. An enumeration is read by its name only (the Adams march's history entries + now cross with their identities named). `_core.schemas()` exports every table and a + test holds the Python records to them; `_testing.round_trip` round-trips each. +- *One `Problem`, one workspace, one run record.* `Problem` absorbs the set-once data + (the stage, z and flux tables, the flow guard's certificate, the controllers, the + low-storage settings). `_core.Workspace(problem)` lives as long as the backend; a run + starts with `start(run)` from one `RunStart` (the run records, the field and noise, a + resume's march state and history rows, the statistics plans, the monitor's weights and + the edge's tables); the probe is `probe(start)`; `diagnostics()` is the one record of + metadata, memory, sizing, planning and crossed bytes, and `counters()` the live counts + a run reads at its start, close and planes. `State`, its configure, upload, bind and + metadata names, `start_session`, the per-step probe paths (`_trial_step`, + `_ResidentLowStorage`, `_ZTables`' per-position evaluation), `_ResidentAdams`, + `solprop_native/_records.py` and the old converters are gone. +- *Logic out of the binding unit.* The lease, the coupled-flow guard, the marches' + construction and entry points, the run and the probe are `native::Workspace` + (`workspace.hpp`, `src/workspace.cpp`), with ctest coverage + (`native/tests/native/test_workspace.cpp`). +- *Generated stubs.* `_core.pyi` and `_core_testing.pyi` are generated whole by + nanobind's `stubgen` (`native/scripts/problem_stub.py`, `--check` in the gate); each + record argument and result names its Python dataclass with `nb::sig`. +- *The split sums in native's `AcceptRecord`.* `_testing.engines(workspace).rk_accept` + and `adams_accept` return the finish's sums (`GeneralState::split_sums`, read without + draining). +- *Engine-level parity* (§6.5, §7): `tests/backends/test_engine_parity.py`, each case + written once against `RungeKuttaEngine` or `AdamsEngine` and played on both backends' + engines over a loaded, configured, watched workspace (`tests/engine_pairs.py`: the + reference's own engines, native's through `_testing.engines` behind thin protocol + wrappers). Covered: rejected and accepted Runge–Kutta trials with their norms, the + first step's stage registers, the commit contract on each side, the accept's split + sums and the boundary reading over three steps of the walking fibre; a dense extension + that leaves the trial and its accept alone; the low-storage step's in-flight interval + and commit; and, for Adams, the calls the reference's own march made on a run (startup, + rejected trials, accepts with the history they keep, the carrier chord and the step's + carrier rotations) replayed on both engines for the interaction formulation with + transported history (three-mode capillary, split collar), the exponential formulation, + and the exponential formulation in the carrier frame. Budgets are SEP 25's from + `tests/march_bounds.py`, fixed before the comparison: `k` steps' share of + `march_bound` for the state, that over `rtol` for a scaled norm, four times it against + the state's energy for the split sums and readings. Each compared term is asserted to + stand well clear of its bound, and the split sums' measurement point is shown to matter + (the same reduction of the finished field misses native's sum by more than ten + bounds). The tests found three of native's protocol records two-dimensional (the + reading's occupancy, the Adams norms, the carrier rotations); they are one-dimensional + now. `_testing.engines` gives a dense configuration's Runge–Kutta engine its extension + holder (`Workspace::trial_engine(dense)`, which the session's method now shares). +- *Ported to the engines:* the estimate's native trial (`tests/driver/test_estimate.py`) + and the whole-trial norm test (`tests/backends/test_native_error_norm.py`). + +**Delivered, phase 5.** `backends.md` (the binding, the z tables' slots, the native Adams +march's start record; §1 and the marches table had been updated in milestone 3), +`architecture.md` §9, `kernel-contract.md` (the occupancy and the Adams march's start +record, the engine's parity; §3 and §8 had been updated in milestones 2 and 3), +`benchmarking.md` (the whole-run window `SOLPROP_BENCHMARK_WINDOW=run`), `testing.md` +(engine-level parity; the scripted engines were milestone 3's), `stepper.md` (the +low-storage probe), `native/README.md` (the binding's rules, which 4B started), a ledger +entry for the seam's A/B in `benchmarks.md` (which also records that +`benchmarks.adams_host` was removed), and ADR-079, *proposed* until this SEP is `Final`. +`conventions.md` §6 and `scans.md` needed nothing more (milestones 2 and 1). The native +comments and docstrings that still cited the deleted `HostDriver`, `_ZTables`, +`_ResidentLowStorage` and `_score_trial` now name the members that do that work. + +**Tests (§7 inventory).** 4B removed `State` (55 bound names), its configure, upload and +bind calls, the metadata properties, `start_session` and the per-step probe bindings; +every caller was ported to the workspace or `_testing` in `da4b5e69` (88 test files +changed in 4B, no test deleted). Here: `_testing.set_absorber_quiet` had no user and is +deleted; `tests/test_transverse_monitor.py` still imported the deleted host driver +(milestone 3's sweep did not collect it) and reads the workspace's function now. + +**Deviations from Part I.** + +- The monitor's weights and the edge's tables travel in the run's start record, not in + `Problem`: they depend on the run's monitor, which a reused workspace's runs may change. +- A low-storage probe closes the workspace afterwards (§5.5's exception), where the old + per-step path left the backend's state in place. +- `_testing.engines` exposes the protocols' methods under `rk_` and `adams_` prefixes on + one object; the protocol wrappers are the tests' (`tests/engine_pairs.py`). +- `Workspace.counters()` and `Session.records(names)` (only the names asked for) were + added for the per-run cost; `Session.march_state` stays. +- `basis_rows` and `trial_tables` stay in `_core`: the native `Helpers` record (SEP 29 + §6.6) names them as the backend's basis and tables, and the helper-ownership tests use + them, though no production path now calls them on a native run (the march is + compiled). Moving them into `_testing` would put a production module on `_testing`, or + drop the record's basis half; that is left to the maintainer. +- The decision-trace runners' dictionaries (`march_state`, `rk_state`, `bounds`, + `result`, the watch record and judgement, the transverse edge's, `trial_from`, + `adams_scalars`) stay hand-written, except the watch state, now written by its table + and the history entries, now read by `march.Entry`'s. The rest carry layouts their + Python consumers read (packed result rows, integer reason and verdict codes, optional + keys) that a table would change on both sides for no production gain; the session's + snapshot and `march_state` read two of them. + +**Decisions.** + +- The engine-level parity tests compare sums over part of the window absolutely, against + the state's energy, since the states' budget is normwise over the whole state. For the + single-mode capillary the split collar takes about 1e-11 of the energy at a step, below + what that budget resolves, so its split sums are compared on the three-mode case only. +- Stage registers are compared on the first step only, where no recycled stage is + involved. + +**Verification.** On an Apple M5 Max (CPU editable build, four workers): after the merge +and native rebuild, the corpus (unchanged, not regenerated), the collar rules, the +decision traces (Runge–Kutta, Adams, native marches, watch), the frozen surfaces +(`test_driver.py`, `test_engines.py`, `test_records.py`), the engine tests, all of +`tests/sessions` (400 passed, 118 skipped by thread count) and the 45 files both sides +had changed; after each later change, the engine-parity tests (6), the traces, the +corpus, the session-history and snapshot modules and `native/tests/test_workspace.py`, +`test_backend.py`, `test_api_contract.py` and `test_session_failure.py`; ruff, +basedpyright, clang-format, the docstring and size checks, codespell, `tests/test_seps.py`, +the structure-figure tests and `native/scripts/problem_stub.py --check`. SWEEP_RESULTS + +4B's measurements, on an exclusive node of two AMD EPYC 7763 (32 cores) of a Slurm +cluster, `--threading bound`, `--calibrate none`, three rounds of three repeats, ratios +branch/base by round: `ab --length 0.05` in the default window, `gnlse_soliton` +1.042/1.008/1.014, `rdw` 0.996/0.983/0.991, `radial_filament_256` 1.004/1.004/0.995; in +the whole-run window (`SOLPROP_BENCHMARK_WINDOW=run`, which includes the load the branch +moved into the session's start), `gnlse_soliton` 1.020/1.004/1.027, `rdw` +0.992/0.989/0.994, `radial_filament_256` 1.022/1.001/1.029; `kerr_beam_192` 1.007. No +median slowdown above 3 % beyond its scatter. From a built backend a whole run cost ++1.9 % under Runge–Kutta, +2.1 % low-storage and +1.9 % Adams; a scan's preparation ++0.5–1 %. The probe's open, trial and read cost +3.4 % (Runge–Kutta), +2.5 % (Adams) and +−8 % (low-storage); a trial alone is unchanged under Runge–Kutta and Adams and 16 % faster +under low-storage. Peak resident memory moved by at most 1 MB. The device targets were +compiled only, not run (D5); a later device campaign runs the GPU lane on the new seam. + +**Cost.** `poe size --all` (Python): total 268,538 → 267,809 lines; `solprop_native` +14,154 before the SEP → 11,655 (estimate 10,000–11,000); `backends` 24,834 before the +SEP → 24,862, and `driver` 27,203 → 26,453 (that figure includes unrelated changes merged +from main), against an estimate of 19,000–20,500 for `backends` with the group parts of +`driver`: missed, because the workspace's operations became public and documented in +milestone 3 (about 840 more lines of public docstrings) and the records and protocols +added about 1,450 lines in milestone 2; `backends`' code lines alone are 11,472. Binding +units (C++): `bindings.cpp` 4,559 → 3,861, of which roughly 1,700 bind `_testing` (the +test state and engines, the scripted marches and their dictionaries), with +`bindings_transverse.cpp` (308, the `TransverseEdge` owner, test-only) and `helpers.cpp` +(172) unchanged, against an estimate of 1,500–2,000: production is about 2,100 plus +helpers. The converter is `records.hpp` and `records.cpp`, 1,088 lines, with the +`fields.hpp` descriptors (210), against an estimate of about 400. The logic moved out of +the binding unit is `native::Workspace`, 955 + 789 lines of library. The hand-written +stub (953 lines before the SEP) is gone: `_core.pyi` (655) and `_core_testing.pyi` (407) +are generated. + +**Open questions.** Q3: decided per test. Ported to the engines where the protocol +reaches what the test checks (the estimate's trial, the whole-trial norm); kept on +`_testing`'s state-level functions where it does not (a trial's partials and their +reduction, the stage rows, the flow actions, an Adams trial over a full synthetic +history and its block read-back, the stash); moved to ctest: the workspace's lease and +setup (4B). Q5: no reference simplification moved a number; none was taken. + +**Issues to update or close at merge** (not touched here): + +- #110: narrow to the integrator–tolerance split and the route union. +- #618: fixed (the unit axis, milestone 2). +- #171 and #828: moot (the groups are gone). +- #344: the naming fixed (milestone 3's march-neutral workspace operations). +- #107: recommend closing. +- #356: note that it needs its own group interface, since none remains. + +**Handoff.** The SEP stays `In progress` for the maintainer's review. The `Final` +commit must: set **Status** to `Final` and **Implementation** to name this pull request; +fill **Manual pages** (the scans guide; `docs/dev/backends.md`, `testing.md`, +`benchmarking.md`, `decisions.md` ADR-079; `native/README.md`); flip ADR-079's status to +accepted; `git mv docs/dev/seps/sep-0052-backend-shape.md +docs/dev/seps/archive/sep-0052-backend-shape.md`; move its row in +`docs/dev/seps/index.md` to the archived table and its toctree entry to the archive's; +update the roadmap's SEP 52 line; and fix the links that name its old path, from +`docs/dev/decisions.md` (ADR-079), `docs/dev/benchmarks.md`, `docs/dev/testing.md`, +`docs/dev/backends.md` and any other `seps/sep-0052-backend-shape.md` reference (a grep +finds them), then run `tests/test_seps.py` and `poe docs`. + ## Part III — History - 2026-11-15: Drafted, from a review of the native binding's use in production and of the From 72502d9898df79729cca7614879d273cf071fd89 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 07:27:07 +0000 Subject: [PATCH 21/29] 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 ef79026ac7ee4354bc7799f123347ca2fc2d4134 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 07:39:50 +0000 Subject: [PATCH 22/29] docs(sep-0052): milestone 4's verification [skip ci] Co-Authored-By: Claude Opus 5.5 --- docs/dev/seps/sep-0052-backend-shape.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/dev/seps/sep-0052-backend-shape.md b/docs/dev/seps/sep-0052-backend-shape.md index 700df76f9..5a856a7ba 100644 --- a/docs/dev/seps/sep-0052-backend-shape.md +++ b/docs/dev/seps/sep-0052-backend-shape.md @@ -1446,7 +1446,20 @@ had changed; after each later change, the engine-parity tests (6), the traces, t corpus, the session-history and snapshot modules and `native/tests/test_workspace.py`, `test_backend.py`, `test_api_contract.py` and `test_session_failure.py`; ruff, basedpyright, clang-format, the docstring and size checks, codespell, `tests/test_seps.py`, -the structure-figure tests and `native/scripts/problem_stub.py --check`. SWEEP_RESULTS +the structure-figure tests, `native/scripts/problem_stub.py --check` and `poe docs` +(clean). On a 32-core AMD EPYC 7763 node of a Slurm cluster (GCC 16.2, CPU wheel, one +thread a worker), after merging milestone 3's CI fixes: the native GoogleTest suite +(passed), and `tests/backends`, `tests/driver`, `tests/sessions`, `tests/output`, +`tests/stepper`, the top-level `tests/test_*.py` (12,274 passed, two failures) and +`native/tests` (674 passed). The two failures: `test_convergence_records`'s writer +check, which needs the whole suite collected and passes in a full run; and +`test_native_session_history.py::test_a_noisy_run_on_a_z_table_meets_the_reference[input-runge-kutta]`, +whose adaptive run's step positions are held to 1e-6 relative and missed by 1.3e-6 at +three steps. That one is intermittent: run alone on the same build it failed once and +passed once, it passes on milestone 3's tip and fails on this milestone's first merge +alone, and it passes inside its file; milestone 2 saw it fail once under load. It is a +tolerance tighter than an adaptive comparison's envelope, not a seam change, and is +worth an issue. 4B's measurements, on an exclusive node of two AMD EPYC 7763 (32 cores) of a Slurm cluster, `--threading bound`, `--calibrate none`, three rounds of three repeats, ratios From 7869786a154e52daec6facbeef7132a2070e5207 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 07:42:04 +0000 Subject: [PATCH 23/29] docs(sep-0052): link milestone 4's pull request Co-Authored-By: Claude Opus 5.5 --- docs/dev/seps/sep-0052-backend-shape.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/dev/seps/sep-0052-backend-shape.md b/docs/dev/seps/sep-0052-backend-shape.md index 5a856a7ba..f1e9e6f42 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` ([#858](https://github.com/LupoLab/solprop/pull/858)); (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` ([#859](https://github.com/LupoLab/solprop/pull/859)); started 2026-11-15 | | **Manual pages** | — | ## Part I — Proposal @@ -1312,8 +1312,10 @@ the rows install) are covered only if CI's coverage lane says so. ### Milestone 4 (phases 4 and 5) — 2026-11-16 -Branch `feature/sep-0052-backend-shape-p4`, stacked on milestone 3, by Opus 5.5 (AI) for -John Travers. Phase 4 was developed by AI agents in two steps on branches off milestone 2, +Branch `feature/sep-0052-backend-shape-p4` +([#859](https://github.com/LupoLab/solprop/pull/859)), stacked on milestone 3, by Opus 5.5 +(AI) for John Travers. +Phase 4 was developed by AI agents in two steps on branches off milestone 2, the new seam beside the old one (4A) and the adapter moved onto it with the old seam deleted (4B); they were merged onto milestone 3, where the engine-level parity tests, the remaining cleanup and phase 5's documentation were done. From 8e9b3f473a71a2d184b660ad7eb36a7bf82fd474 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 08:10:48 +0000 Subject: [PATCH 24/29] refactor(native): basis_rows and trial_tables are test entry points in _testing The compiled Adams march forms its Lagrange basis and coefficient tables in C++, so no production path reached their bindings (maintainer's decision). The native helper record names only the Chebyshev rows; Helpers.basis is optional and refuses by name on a record without one, and the Helpers.tables slot, which only the native record filled, goes with numpy_ref's one-call branch. tests/native_lagrange.py reaches the C++ through _testing for the plain-form and exact-table comparisons; the stubs are regenerated. Co-Authored-By: Claude Opus 5.5 --- docs/dev/backends.md | 18 ++-- docs/dev/seps/sep-0052-backend-shape.md | 12 ++- native/src/helpers.cpp | 4 +- native/src/solprop_native/_core.pyi | 20 ---- native/src/solprop_native/_core_testing.pyi | 20 ++++ native/src/solprop_native/_helpers.py | 105 +++----------------- src/solprop/_helpers.py | 62 ++++-------- src/solprop/backends/numpy_ref/multistep.py | 10 +- tests/backends/test_adams_table_oracle.py | 18 +++- tests/backends/test_helper_ownership.py | 32 +++--- tests/driver/test_native_flow_session.py | 3 +- tests/native_lagrange.py | 79 +++++++++++++++ tests/test_helpers.py | 53 +++++----- 13 files changed, 210 insertions(+), 226 deletions(-) create mode 100644 tests/native_lagrange.py diff --git a/docs/dev/backends.md b/docs/dev/backends.md index 58d17253b..678a89474 100644 --- a/docs/dev/backends.md +++ b/docs/dev/backends.md @@ -172,18 +172,16 @@ 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 session, its -Adams march, its engines and the native backend's own load and resident engine pass it -down. `numpy_ref` takes +Adams march and its engines pass it down. `numpy_ref` takes `PLAIN`, the uncompiled Python forms, so the oracle never runs the compiled code it -checks; `native` takes its own -`NATIVE`, C++ transcriptions (`native/include/solprop_native/chebyshev.hpp` and -`lagrange_basis.hpp`). Both perform the same operations in the same order under +checks; `native` takes its own `NATIVE`, the C++ transcription of the Chebyshev rows +(`native/include/solprop_native/chebyshev.hpp`), which its adapter still evaluates for +the stage scalars at a plane. Both perform the same operations in the same order under strict arithmetic, so the rows a table keeps for its last positions are shared whichever -filled them. A record may add a third operation, an exponential Adams trial's -coefficient tables in one call (`Helpers.tables`, the composition of -`backends.numpy_ref.multistep.trial_tables` over its own basis): `NATIVE` has it, in C++ beside -the basis (`trial_tables` in `lagrange_basis.hpp`), so its resident engine forms every -table of a trial in one call rather than a dozen; `PLAIN` composes them. Translation runs +filled them. `NATIVE` names no Adams basis: the compiled Adams march forms its basis and +a trial's coefficient tables in C++ (`basis_rows` and `trial_tables` in +`lagrange_basis.hpp`), and their bindings are private test entry points in +`_core._testing`, which `tests/test_helpers.py` holds to the plain forms. Translation runs before any backend exists and needs nothing compiled: `clenshaw` and `PiecewiseChebyshev.__call__` without a record are NumPy's, and the shared functions' defaults are `PLAIN`. A z table's state-sized evaluation diff --git a/docs/dev/seps/sep-0052-backend-shape.md b/docs/dev/seps/sep-0052-backend-shape.md index f1e9e6f42..1d0250022 100644 --- a/docs/dev/seps/sep-0052-backend-shape.md +++ b/docs/dev/seps/sep-0052-backend-shape.md @@ -1417,11 +1417,13 @@ deleted; `tests/test_transverse_monitor.py` still imported the deleted host driv one object; the protocol wrappers are the tests' (`tests/engine_pairs.py`). - `Workspace.counters()` and `Session.records(names)` (only the names asked for) were added for the per-run cost; `Session.march_state` stays. -- `basis_rows` and `trial_tables` stay in `_core`: the native `Helpers` record (SEP 29 - §6.6) names them as the backend's basis and tables, and the helper-ownership tests use - them, though no production path now calls them on a native run (the march is - compiled). Moving them into `_testing` would put a production module on `_testing`, or - drop the record's basis half; that is left to the maintainer. +- `basis_rows` and `trial_tables` moved into `_testing` (the maintainer's decision, + 2026-11-16). The compiled Adams march forms its basis and tables in C++, so no + production path reached their bindings. The native `Helpers` record now names only the + Chebyshev rows; `Helpers.basis` is optional and refuses by name on a record without + one, and the `Helpers.tables` slot, which only the native record filled, is gone. + `tests/test_helpers.py` holds the C++ basis and tables to the plain forms through + `_testing`. - The decision-trace runners' dictionaries (`march_state`, `rk_state`, `bounds`, `result`, the watch record and judgement, the transverse edge's, `trial_from`, `adams_scalars`) stay hand-written, except the watch state, now written by its table diff --git a/native/src/helpers.cpp b/native/src/helpers.cpp index 57f549279..fc682565c 100644 --- a/native/src/helpers.cpp +++ b/native/src/helpers.cpp @@ -154,9 +154,9 @@ void bind_helpers(nb::module_& module_, nb::module_& testing) { module_.def("clenshaw_points", &clenshaw_points>, "z"_a.noconvert(), "edges"_a.noconvert(), "lower"_a, "upper"_a, "c"_a.noconvert(), "out"_a.noconvert()); - module_.def("basis_rows", &basis_rows, "points"_a.noconvert(), "upper"_a, + testing.def("basis_rows", &basis_rows, "points"_a.noconvert(), "upper"_a, "integrate"_a, "rows"_a.noconvert(), "weights"_a.noconvert()); - module_.def("trial_tables", &trial_tables, "nodes"_a.noconvert(), "order"_a, + testing.def("trial_tables", &trial_tables, "nodes"_a.noconvert(), "order"_a, "orders"_a, "compensated"_a, "predictor"_a.noconvert(), "corrector"_a.noconvert(), "factored"_a.noconvert(), "spans"_a.noconvert(), "carried"_a.noconvert(), "endpoint"_a.noconvert(), diff --git a/native/src/solprop_native/_core.pyi b/native/src/solprop_native/_core.pyi index 7b6bf66cb..6671a7a43 100644 --- a/native/src/solprop_native/_core.pyi +++ b/native/src/solprop_native/_core.pyi @@ -609,13 +609,6 @@ class Workspace: def close(self) -> None: ... def available_device_memory() -> int | None: ... -def basis_rows( - points: npt.NDArray[np.float64], - upper: float, - integrate: bool, - rows: npt.NDArray[np.float64], - weights: npt.NDArray[np.float64], -) -> None: ... def build_record() -> dict[str, Any]: ... @overload def clenshaw_points( @@ -640,16 +633,3 @@ def export_fftw_wisdom() -> str | None: ... def reference_stream_copies(elements: int, warm: int, repeats: int) -> list[float]: ... def schemas() -> dict[str, Any]: ... def time_fft_plan(key: str, wisdom: str, effort: str) -> dict[str, Any]: ... -def trial_tables( - nodes: npt.NDArray[np.float64], - order: int, - orders: Sequence[int], - compensated: bool, - predictor: npt.NDArray[np.float64], - corrector: npt.NDArray[np.float64], - factored: npt.NDArray[np.float64], - spans: npt.NDArray[np.float64], - carried: npt.NDArray[np.float64], - endpoint: npt.NDArray[np.float64], - defects: npt.NDArray[np.float64], -) -> None: ... diff --git a/native/src/solprop_native/_core_testing.pyi b/native/src/solprop_native/_core_testing.pyi index 299ca69f3..9ea3d4042 100644 --- a/native/src/solprop_native/_core_testing.pyi +++ b/native/src/solprop_native/_core_testing.pyi @@ -235,6 +235,13 @@ def aperture_statistics( def axis_spectrum( workspace: Workspace, matrix: npt.NDArray[np.float64] ) -> npt.NDArray[np.complex128]: ... +def basis_rows( + points: npt.NDArray[np.float64], + upper: float, + integrate: bool, + rows: npt.NDArray[np.float64], + weights: npt.NDArray[np.float64], +) -> None: ... def bind_monitor( workspace: Workspace, monitor: Mapping[str, object], @@ -372,6 +379,19 @@ def trial_step( material: object | None = None, prepare_only: bool = False, ) -> npt.NDArray[np.float64]: ... +def trial_tables( + nodes: npt.NDArray[np.float64], + order: int, + orders: Sequence[int], + compensated: bool, + predictor: npt.NDArray[np.float64], + corrector: npt.NDArray[np.float64], + factored: npt.NDArray[np.float64], + spans: npt.NDArray[np.float64], + carried: npt.NDArray[np.float64], + endpoint: npt.NDArray[np.float64], + defects: npt.NDArray[np.float64], +) -> None: ... def vector_exp(x: npt.NDArray[np.float64], out: npt.NDArray[np.float64]) -> None: ... def vector_exp_complex( a: npt.NDArray[np.float64], diff --git a/native/src/solprop_native/_helpers.py b/native/src/solprop_native/_helpers.py index 4fb62d852..c6d262584 100644 --- a/native/src/solprop_native/_helpers.py +++ b/native/src/solprop_native/_helpers.py @@ -2,109 +2,34 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The native backend's per-stage and per-step evaluations, for solprop's shared code. - -solprop's driver, Adams march and engines take the stage tables' Chebyshev rows and -the Adams basis from the backend that runs them (``NativeBackend.helpers``, solprop -SEP 29 section 6.6), so that a native run never reaches solprop's Python forms -and the NumPy reference never reaches this package. :data:`NATIVE` is this backend's -record: the C++ transcriptions in ``include/solprop_native/chebyshev.hpp`` and -``lagrange_basis.hpp``, which perform solprop's operations in its order under strict -arithmetic. The record also forms an exponential Adams trial's coefficient tables in -one call (``Helpers.tables``), which the resident Adams engine reads every trial. +"""The native backend's per-stage evaluations, for solprop's shared code. + +solprop's shared stage code takes a stage table's Chebyshev rows from the backend that +runs it (``NativeBackend.helpers``, solprop SEP 29 section 6.6), so that a native run +never reaches solprop's Python forms and the NumPy reference never reaches this +package. :data:`NATIVE` is this backend's record: the C++ transcription in +``include/solprop_native/chebyshev.hpp``, which performs solprop's operations in its +order under strict arithmetic. + +The record names no Adams basis. The native Adams march is compiled and forms its +Lagrange basis and coefficient tables in C++ (``lagrange_basis.hpp``) every trial, so no +production path evaluates them in Python (solprop SEP 52); their bindings are private +test entry points in ``_core._testing``, which check them against solprop's plain forms. """ from __future__ import annotations -import numpy as np -import numpy.typing as npt -from solprop._helpers import BasisFunction, Helpers, PointsFunction, TablesFunction +from solprop._helpers import Helpers, PointsFunction from . import _core __all__ = ["NATIVE"] -def _basis( - points: npt.NDArray[np.float64], upper: float, integrate: bool -) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]: - """Return the Lagrange basis on `points`: its coefficients, or its integrals. - - - ``points``: the distinct nodes, float64, C-contiguous, at most 32 of them. - - Returns: the coefficients, shape ``(n, n)`` (zero when integrating), and the - integrals, shape ``(n,)`` (unset when not). - """ - count = points.shape[0] - rows = np.empty((count, count)) - weights = np.empty(count) - _core.basis_rows(points, upper, integrate, rows, weights) - return rows, weights - - -def _tables( - nodes: npt.NDArray[np.float64], order: int, orders: list[int], compensated: bool -) -> tuple[ - npt.NDArray[np.float64], - npt.NDArray[np.float64], - npt.NDArray[np.float64], - npt.NDArray[np.float64], - npt.NDArray[np.float64], - npt.NDArray[np.float64], - npt.NDArray[np.float64], -]: - """Return an exponential Adams trial's coefficient tables, formed in one call. - - - ``nodes``: the history's normalised positions, newest first, float64, - C-contiguous. - - Returns: solprop's ``trial_tables``: the predictor, corrector and factored defect - rows, then the compensation's spans, weights and defect rows, empty when not - compensated. - """ - width = 1 + max(orders) - count = len(orders) - predictor = np.empty((order, order)) - corrector = np.empty((width, width)) - factored = np.empty((count, 2 * width)) - if compensated: - spans, carried = np.empty(width - 1), np.empty(order) - endpoint, defects = np.empty(order + 1), np.empty((count, width)) - else: - spans, carried, endpoint, defects = ( - np.empty(0), - np.empty(0), - np.empty(0), - np.empty((0, 0)), - ) - _core.trial_tables( - nodes, - order, - orders, - compensated, - predictor, - corrector, - factored, - spans, - carried, - endpoint, - defects, - ) - return predictor, corrector, factored, spans, carried, endpoint, defects - - def _load_points() -> PointsFunction: """Return the native Chebyshev rows binding.""" return _core.clenshaw_points -def _load_basis() -> BasisFunction: - """Return the native Adams basis.""" - return _basis - - -def _load_tables() -> TablesFunction: - """Return the native trial tables.""" - return _tables - - -NATIVE = Helpers("native", _load_points, _load_basis, _load_tables) +NATIVE = Helpers("native", _load_points) """The native backend's helper record (``NativeBackend.helpers``).""" diff --git a/src/solprop/_helpers.py b/src/solprop/_helpers.py index cc3d9f188..fc146a987 100644 --- a/src/solprop/_helpers.py +++ b/src/solprop/_helpers.py @@ -21,10 +21,10 @@ perform the same IEEE operations in the same order, strict (no contraction, no reassociation; SEP 25 section 4.2), so they agree to the last bit wherever their arithmetic is IEEE. -A record may also form a whole exponential Adams trial's coefficient tables in one -call (:attr:`Helpers.tables`), the composition of -:func:`solprop.backends.numpy_ref.multistep.trial_tables` over its own basis, which its -resident engine reads every trial; a record without it composes them from the basis. +A backend whose Adams march is compiled names no basis: the native backend's march +forms its basis and coefficient tables in C++ (SEP 52), and its record carries only the +Chebyshev rows its adapter still evaluates. The C++ basis is checked against the plain +form through ``solprop_native._core._testing``. Translation is not a backend's: it runs before any backend exists and builds the problem every backend receives, so it needs nothing compiled, and the shared functions' @@ -49,7 +49,6 @@ "BasisFunction", "Helpers", "PointsFunction", - "TablesFunction", ] PointsFunction = Callable[ @@ -72,26 +71,6 @@ ``(n,)`` (unset when not). """ -TablesFunction = Callable[ - [np.ndarray, int, list[int], bool], - tuple[ - np.ndarray, - np.ndarray, - np.ndarray, - np.ndarray, - np.ndarray, - np.ndarray, - np.ndarray, - ], -] -"""``tables(nodes, order, orders, compensated) -> tables``: a trial's tables at once. - -The contract of :func:`solprop.backends.numpy_ref.multistep.trial_tables`, whose -composition over the record's own basis it performs in one call, with the same -operations in the same order: ``nodes`` float64 ``(n,)`` and C-contiguous, newest first; -the result is that function's seven arrays. -""" - @dataclass(frozen=True) class Helpers: @@ -106,18 +85,14 @@ class Helpers: What the record is, for messages and tests. load_points : collections.abc.Callable Returns the :data:`PointsFunction`. - load_basis : collections.abc.Callable - Returns the :data:`BasisFunction`. - load_tables : collections.abc.Callable or None, optional - Returns the :data:`TablesFunction`, for a record that forms an exponential - Adams trial's tables in one call; ``None``, the default, composes them from - the basis. + load_basis : collections.abc.Callable or None, optional + Returns the :data:`BasisFunction`; ``None``, the default, for a backend whose + Adams march is compiled and evaluates no basis in Python. """ name: str load_points: Callable[[], PointsFunction] = field(repr=False) - load_basis: Callable[[], BasisFunction] = field(repr=False) - load_tables: Callable[[], TablesFunction] | None = field(default=None, repr=False) + load_basis: Callable[[], BasisFunction] | None = field(default=None, repr=False) @functools.cached_property def points(self) -> PointsFunction: @@ -126,17 +101,20 @@ def points(self) -> PointsFunction: @functools.cached_property def basis(self) -> BasisFunction: - """Return the Lagrange basis on an Adams formula's nodes.""" - return self.load_basis() - - @functools.cached_property - def tables(self) -> TablesFunction | None: - """Return an exponential Adams trial's tables in one call, if the record has it. + """Return the Lagrange basis on an Adams formula's nodes. - - Returns: the :data:`TablesFunction`, or ``None``: the tables are then composed - from :attr:`basis`. + - Raises: ``BackendError`` for a record without one, whose backend's Adams + march is compiled. """ - return None if self.load_tables is None else self.load_tables() + if self.load_basis is None: + from solprop.exceptions import BackendError # noqa: PLC0415 - no cycle + + msg = ( + f"the {self.name} helper record has no Adams basis: its backend's " + "Adams march is compiled and forms its basis itself" + ) + raise BackendError(msg) + return self.load_basis() def _plain_points() -> PointsFunction: diff --git a/src/solprop/backends/numpy_ref/multistep.py b/src/solprop/backends/numpy_ref/multistep.py index 1f7f0e65b..cc07fdc93 100644 --- a/src/solprop/backends/numpy_ref/multistep.py +++ b/src/solprop/backends/numpy_ref/multistep.py @@ -2420,10 +2420,9 @@ def trial_tables( """Return all of an exponential trial's coefficient tables, for a resident engine. :func:`exponential_tables`' three and, compensated, :func:`compensation_tables`' - four, composed over the record's basis; a record that forms them in one call - (``Helpers.tables``, the native backend's) performs the same operations in the - same order, so the tables are the same, read once a trial instead of from a dozen - small calls. + four, composed over the record's basis, read once a trial instead of from a dozen + small calls. The native march forms the same tables in C++ with the same + operations in the same order. Parameters ---------- @@ -2445,9 +2444,6 @@ def trial_tables( compensation's spans, predictor, corrector and defect rows, shapes ``(0,)`` and ``(0, 0)`` when not compensated. """ - one_call = helpers.tables - if one_call is not None: - return one_call(np.asarray(nodes, dtype=np.float64), order, orders, compensated) predictor, corrector, factored = exponential_tables( nodes, order, orders, helpers=helpers ) diff --git a/tests/backends/test_adams_table_oracle.py b/tests/backends/test_adams_table_oracle.py index 6ba02f660..b8ff6a98c 100644 --- a/tests/backends/test_adams_table_oracle.py +++ b/tests/backends/test_adams_table_oracle.py @@ -31,6 +31,7 @@ import numpy as np import pytest +from native_lagrange import native_basis_record, native_tables from solprop._helpers import PLAIN, Helpers from solprop.backends.numpy_ref.multistep import fused_tables, trial_tables @@ -70,7 +71,12 @@ def _stencils() -> list[tuple[tuple[float, ...], int, tuple[int, ...]]]: def _records() -> list[Helpers]: - return [] if NATIVE is None else [NATIVE] + """Return the records held to the exact tables beside the plain forms. + + Native's names no basis (its Adams march is compiled); the test record carries its + C++ basis, and its trial tables are formed by the C++ call the march makes. + """ + return [] if NATIVE is None else [native_basis_record()] # ------------------------------------------------------------------ exact tables @@ -168,9 +174,13 @@ def _computed( ) -> dict: """Return the same tables as `helpers` forms them, as rows of floats.""" listed = list(nodes) - predictor, corrector, factored, spans, carried, endpoint, defects = trial_tables( - listed, order, list(orders), compensated=True, helpers=helpers - ) + if helpers.name == "native": + tables = native_tables(np.asarray(listed), order, list(orders), True) + else: + tables = trial_tables( + listed, order, list(orders), compensated=True, helpers=helpers + ) + predictor, corrector, factored, spans, carried, endpoint, defects = tables fused_predictor, fused_corrector, fused_defects = fused_tables( listed, order, list(orders), helpers=helpers ) diff --git a/tests/backends/test_helper_ownership.py b/tests/backends/test_helper_ownership.py index cd198cf98..824c0c156 100644 --- a/tests/backends/test_helper_ownership.py +++ b/tests/backends/test_helper_ownership.py @@ -48,9 +48,8 @@ "runge-kutta": RungeKutta(), "low-storage": LowStorageRungeKutta(), } -"""Each march: the Adams ones read the basis or the record's trial tables (the -native record forms an exponential trial's in one call), every one reads the stage -tables.""" +"""Each march: the reference's Adams marches read the basis (the native Adams march +forms its basis in C++ and its record names none), every one reads the stage tables.""" class ForbiddenHelperError(AssertionError): @@ -58,12 +57,12 @@ class ForbiddenHelperError(AssertionError): def forbid(monkeypatch, record): - """Make each of a record's operations raise, the one-call tables included.""" + """Make each of a record's operations raise, a basis it does not name included.""" def refuse(*_): raise ForbiddenHelperError(record.name) - for name in ("points", "basis", "tables"): + for name in ("points", "basis"): monkeypatch.setitem(record.__dict__, name, refuse) @@ -79,13 +78,13 @@ def refuse(*_): def count(monkeypatch, record): """Count a record's calls; return the tally. - A record without the one-call tables keeps none, and its tally stays at zero. + A record that names no basis keeps none, and its tally stays at zero. """ - tally = {"points": 0, "basis": 0, "tables": 0} + tally = {"points": 0, "basis": 0} for name in tally: - function = getattr(record, name) - if function is None: + if name == "basis" and record.load_basis is None: continue + function = getattr(record, name) def counted(*arguments, _name=name, _function=function): tally[_name] += 1 @@ -136,20 +135,15 @@ def test_the_reference_runs_only_the_plain_forms(monkeypatch, integrator): tally = count(monkeypatch, _helpers.PLAIN) propagate(NumpyRefBackend, prepared) assert tally["points"] > 0, tally - adams = tally["basis"] + tally["tables"] - assert adams > 0 or not integrator.startswith("adams"), tally + assert tally["basis"] > 0 or not integrator.startswith("adams"), tally def assert_native_helpers_ran(tally, integrator): """Assert what a native run's helper tally shows of its march.""" assert tally["points"] > 0, tally - if integrator.startswith("adams"): - # A staged trial forms its tables in the native state from its nodes alone - # (SEP 39 phases 1 and 3), in either formulation: none crosses from the host. - assert tally["tables"] == 0, tally - return - adams = tally["basis"] + tally["tables"] - assert adams > 0 or not integrator.startswith("adams"), tally + # A staged trial forms its basis and tables in the native state from its nodes + # alone (SEP 39 phases 1 and 3; SEP 52), in either formulation: none crosses. + assert tally["basis"] == 0, tally @pytest.mark.parametrize("integrator", INTEGRATORS) @@ -205,7 +199,7 @@ def test_a_native_z_table_run_uses_only_its_own_helpers(monkeypatch, integrator) forbid_one_point(monkeypatch) tally = count(monkeypatch, NATIVE) propagate(native.NativeBackend, prepared) - assert tally["tables"] == 0, tally + assert tally["basis"] == 0, tally @pytest.mark.parametrize( diff --git a/tests/driver/test_native_flow_session.py b/tests/driver/test_native_flow_session.py index 6b53ff4cb..2b4b67e6b 100644 --- a/tests/driver/test_native_flow_session.py +++ b/tests/driver/test_native_flow_session.py @@ -64,6 +64,7 @@ to_planes, ) from sessions.runs import run as run_session +from solprop._helpers import PLAIN from solprop.backends.events import ObservationReady, Outcome from solprop.backends.exponential import carrier_reference from solprop.backends.numpy_ref import NumpyRefBackend @@ -401,7 +402,7 @@ def _block_departure( order, [order], compensated=_compensated(backend), - helpers=backend.helpers, + helpers=PLAIN, )[1].shape[0] assert bool(shift.size) is carrier expected = coupled_moments( diff --git a/tests/native_lagrange.py b/tests/native_lagrange.py new file mode 100644 index 000000000..bfe4a4b0f --- /dev/null +++ b/tests/native_lagrange.py @@ -0,0 +1,79 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""Native's Lagrange basis and Adams trial tables, reached for tests. + +The compiled Adams march forms its basis and a trial's coefficient tables in C++ +(``lagrange_basis.hpp``) every trial, and the native helper record names neither (SEP +52). These wrappers reach the same C++ through its private test bindings +(``solprop_native._core._testing``), so that tests can hold it to solprop's plain forms +and to the exact tables. Call them only where solprop-native is installed. +""" + +from typing import Any + +import numpy as np + +from solprop._helpers import Helpers + + +def _testing() -> Any: + """Return the native extension's private test module.""" + from solprop_native import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] + _core, # pyright: ignore[reportMissingModuleSource] + ) + + return _core._testing + + +def native_basis(points: np.ndarray, upper: float, integrate: bool): + """Return native's Lagrange basis on `points`: its coefficients, or its integrals. + + The C++ basis the compiled Adams march forms every trial, through its private test + binding (``_core._testing.basis_rows``); the native record names no basis. + """ + testing = _testing() + count = points.shape[0] + rows, weights = np.empty((count, count)), np.empty(count) + testing.basis_rows(points, upper, integrate, rows, weights) + return rows, weights + + +def native_tables(nodes: np.ndarray, order: int, orders: list[int], compensated: bool): + """Return native's exponential Adams trial tables, formed in one C++ call. + + The arrays of :func:`solprop.backends.numpy_ref.multistep.trial_tables`, in its + order, through the private test binding (``_core._testing.trial_tables``). + """ + testing = _testing() + width, count = 1 + max(orders), len(orders) + predictor, corrector = np.empty((order, order)), np.empty((width, width)) + factored = np.empty((count, 2 * width)) + if compensated: + spans, carried = np.empty(width - 1), np.empty(order) + endpoint, defects = np.empty(order + 1), np.empty((count, width)) + else: + spans, carried, endpoint = np.empty(0), np.empty(0), np.empty(0) + defects = np.empty((0, 0)) + testing.trial_tables( + nodes, + order, + orders, + compensated, + predictor, + corrector, + factored, + spans, + carried, + endpoint, + defects, + ) + return predictor, corrector, factored, spans, carried, endpoint, defects + + +def native_basis_record() -> Helpers: + """Return a test record whose basis is native's C++ one, its rows the plain ones.""" + from solprop._helpers import PLAIN # noqa: PLC0415 - beside the record it copies + + return Helpers("native", lambda: PLAIN.points, lambda: native_basis) diff --git a/tests/test_helpers.py b/tests/test_helpers.py index 5d9632738..822219599 100644 --- a/tests/test_helpers.py +++ b/tests/test_helpers.py @@ -18,9 +18,11 @@ import pytest from bounds import EPS, assert_within, gamma +from native_lagrange import native_basis, native_tables from solprop._helpers import PLAIN, Helpers from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.multistep import trial_tables +from solprop.exceptions import BackendError from solprop.stepper.multistep import integrated_weights, lagrange_coefficients from solprop.translate.chebyshev import build @@ -37,6 +39,7 @@ needs_native = pytest.mark.skipif(NATIVE is None, reason="solprop-native is absent") + EDGES = np.array([0.0, 0.3, 0.45, 1.0, 1.75]) """Four unequal intervals of a 1.75 m span.""" @@ -146,8 +149,7 @@ def refuse(*_): pytest.fail("a default reached a compiled record") for record in records(): - for name in ("points", "basis"): - monkeypatch.setitem(record.__dict__, name, refuse) + monkeypatch.setitem(record.__dict__, "points", refuse) 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) @@ -205,16 +207,17 @@ def load() -> Any: assert not calls assert record.points is record.points assert len(calls) == 1 - # Without its own tables a record composes them from its basis. - assert record.tables is None - assert Helpers("probe", load, load, load).tables is not None + assert record.basis is record.basis assert len(calls) == 2 -def test_only_the_native_record_forms_the_tables_in_one_call(): - assert PLAIN.tables is None +def test_a_record_without_a_basis_refuses_one_by_name(): + """A backend whose Adams march is compiled evaluates no basis in Python.""" + with pytest.raises(BackendError, match="probe helper record has no Adams basis"): + _ = Helpers("probe", lambda: PLAIN.points).basis if NATIVE is not None: - assert NATIVE.tables is not None + with pytest.raises(BackendError, match="native helper record"): + _ = NATIVE.basis # ------------------------------------------------------------ Chebyshev rows @@ -280,12 +283,12 @@ def test_a_tables_positions_through_the_native_record(imaginary): # ---------------------------------------------------------------- Adams basis -@pytest.mark.parametrize("helpers", records(), ids=lambda record: record.name) +@needs_native @pytest.mark.parametrize("upper", [1.0, 0.37, 1.6]) @pytest.mark.parametrize("nodes", node_sets(), ids=lambda nodes: f"{nodes.size}") -def test_basis_agrees_with_the_plain_form(helpers, upper, nodes, record_property): +def test_the_native_basis_agrees_with_the_plain_form(upper, nodes, record_property): rows_plain, weights_plain = PLAIN.basis(nodes, upper, True) - rows, weights = helpers.basis(nodes, upper, True) + rows, weights = native_basis(nodes, upper, True) # Integrating, the rows are zero: a structural contract, exact. assert not np.any(rows) and not np.any(rows_plain) assert_within( @@ -296,7 +299,7 @@ def test_basis_agrees_with_the_plain_form(helpers, upper, nodes, record_property what="weights", ) coefficients_plain, _ = PLAIN.basis(nodes, upper, False) - coefficients_, _ = helpers.basis(nodes, upper, False) + coefficients_, _ = native_basis(nodes, upper, False) assert_within( coefficients_, coefficients_plain, @@ -313,8 +316,8 @@ def test_basis_agrees_with_the_plain_form(helpers, upper, nodes, record_property ) -@pytest.mark.parametrize("helpers", [PLAIN, *records()], ids=lambda record: record.name) -def test_the_shared_functions_take_the_record(helpers): +def test_the_shared_functions_take_the_record(): + helpers = PLAIN nodes = np.array([1.0, 0.0, -1.0, -2.0]) # Adams-Moulton 4, times 24: a few operations on quarters, well inside 64 EPS. assert_within( @@ -394,19 +397,17 @@ def table_bounds( ) -@pytest.mark.parametrize("helpers", records(), ids=lambda record: record.name) +@needs_native @pytest.mark.parametrize("compensated", [False, True]) @pytest.mark.parametrize(("order", "orders"), TRIALS, ids=str) -def test_the_trial_tables_agree_with_the_plain_form( - helpers, compensated, order, orders, record_property +def test_the_native_trial_tables_agree_with_the_plain_form( + compensated, order, orders, record_property ): nodes = history_nodes(max(orders) + 1) plain = trial_tables( nodes.tolist(), order, orders, compensated=compensated, helpers=PLAIN ) - tables = trial_tables( - nodes.tolist(), order, orders, compensated=compensated, helpers=helpers - ) + tables = native_tables(nodes, order, orders, compensated) names = ("predictor", "corrector", "factored") compensation = ("spans", "carried", "endpoint", "defects") bounds = table_bounds(nodes, order, orders) @@ -453,18 +454,18 @@ def test_the_native_bindings_refuse_hidden_conversions(): core.clenshaw_points(z, EDGES[:1], 0.0, 1.75, c[:0], out) points = np.zeros(33) with pytest.raises(ValueError, match="exceed"): - core.basis_rows(points, 1.0, True, np.empty((33, 33)), np.empty(33)) + core._testing.basis_rows(points, 1.0, True, np.empty((33, 33)), np.empty(33)) with pytest.raises(ValueError, match="must be"): - core.basis_rows(points[:3], 1.0, True, np.empty((3, 2)), np.empty(3)) + core._testing.basis_rows(points[:3], 1.0, True, np.empty((3, 2)), np.empty(3)) with pytest.raises(TypeError): - core.basis_rows( + core._testing.basis_rows( points[:3].astype(np.float32), 1.0, True, np.empty((3, 3)), np.empty(3) ) nodes = np.array([0.0, -1.0, -2.0]) empty, rows = np.empty(0), np.empty((0, 0)) def tables(order, orders, *arrays): - core.trial_tables( + core._testing.trial_tables( nodes, order, orders, False, *arrays, empty, empty, empty, rows ) @@ -475,7 +476,7 @@ def tables(order, orders, *arrays): with pytest.raises(ValueError, match="must be"): tables(2, [2, 1, 3], np.empty((2, 2)), np.empty((4, 4)), np.empty((3, 4))) with pytest.raises(ValueError, match="must be"): - core.trial_tables( + core._testing.trial_tables( nodes, 1, [1], @@ -489,7 +490,7 @@ def tables(order, orders, *arrays): rows, ) with pytest.raises(TypeError): - core.trial_tables( + core._testing.trial_tables( nodes.astype(np.float32), 1, [1], From 514b5d1817e5757fbd7bdf45a71c90d60cbb4a8a Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 09:14:34 +0000 Subject: [PATCH 25/29] fix(native): the strict native type check on the new seam's code and tests The aperture packer moves to the session that calls it, a dead device helper and an unneeded cast go, the session status indexes its tables by int, and the workspace tests type their spoiled records, comparisons and counts. Co-Authored-By: Claude Opus 5.5 --- native/src/solprop_native/backend.py | 49 +-------------- native/src/solprop_native/session.py | 46 +++++++++++++- native/tests/test_backend.py | 5 +- native/tests/test_free.py | 4 +- native/tests/test_workspace.py | 94 +++++++++++++++------------- 5 files changed, 100 insertions(+), 98 deletions(-) diff --git a/native/src/solprop_native/backend.py b/native/src/solprop_native/backend.py index 35cf320ea..9f0f2e3f1 100644 --- a/native/src/solprop_native/backend.py +++ b/native/src/solprop_native/backend.py @@ -72,7 +72,6 @@ from solprop.profiles import ZProfile from solprop.spatial import ( FAR_FIELD_STATISTICS, - ApertureTables, ) from solprop.stats import ( StatsSpec, @@ -833,7 +832,7 @@ def _stage_scalars(self, z0: float, z1: float) -> StageScalars: def _diagnostics(self) -> dict[str, Any]: """Return the workspace's facts and counters (``Workspace.diagnostics``).""" - return cast("dict[str, Any]", self._workspace.diagnostics()) + return self._workspace.diagnostics() def _monitor_binding(self, monitor: BoundaryMonitor) -> dict[str, object]: """Return a run's boundary monitor weights where the state lives (SEP 21). @@ -1191,12 +1190,6 @@ def _build_facts() -> _BuildFacts: ) -def _required(values: RealArray | None, name: str) -> RealArray: - if values is None: - raise BackendError(f"device-ready problem has no {name}") - return values - - def _require_initial_array(field: object, shape: tuple[int, ...]) -> None: if not isinstance(field, np.ndarray): raise TypeError("field must be a NumPy ndarray") @@ -2265,46 +2258,6 @@ def _flow_allowance(modes: int) -> float: return 1.0 + 64.0 * modes * float(np.finfo(float).eps) -_APERTURE_CONSTANTS = 11 -"""The constants before an aperture row's scale row (``far_field.hpp``).""" - - -def _aperture_payload( - tables: ApertureTables | None, n_omega: int -) -> tuple[RealArray, RealArray, int]: - """Pack far-field tables as the native pass reads them (solprop SEP 23 section 6). - - Returns the ``(n_apertures, 11 + n_omega)`` aperture rows (centre x and y, the - half-width and half-height, the two stretches, the reciprocal edge width, the edge - or order, the profile and shape codes, the distance, then the scale row - ``z c / omega`` that every backend reads to the bit), the ``(n_regions, 4)`` boxes - and the exponent; empty tables without any. - """ - if tables is None: - return np.empty((0, _APERTURE_CONSTANTS + n_omega)), np.empty((0, 4)), 2 - assert tables.half_heights is not None - assert tables.stretches is not None - constants = np.column_stack( - ( - tables.centres, - tables.half_widths, - tables.half_heights, - tables.stretches, - tables.inverse_widths, - tables.edges, - tables.profile_codes, - tables.shape_codes, - tables.distances, - ) - ) - apertures = np.ascontiguousarray(np.hstack((constants, tables.scale))) - return ( - apertures, - np.ascontiguousarray(tables.regions, dtype=np.float64), - tables.exponent, - ) - - def _refined_record( problem: PropagationProblem, stepper: StepperSettings, diff --git a/native/src/solprop_native/session.py b/native/src/solprop_native/session.py index e734f1727..196485986 100644 --- a/native/src/solprop_native/session.py +++ b/native/src/solprop_native/session.py @@ -158,7 +158,6 @@ _FLOOR, # pyright: ignore[reportPrivateUsage] FRESH_WATCH, NativeBackend, - _aperture_payload, # pyright: ignore[reportPrivateUsage] _envelope_errors, # pyright: ignore[reportPrivateUsage] _raise_native, # pyright: ignore[reportPrivateUsage] ) @@ -179,6 +178,7 @@ from solprop.modes.protocol import Mode from solprop.monitor import BoundaryMonitor from solprop.profiles import ZProfile + from solprop.spatial import ApertureTables from solprop.stats import StatsSpec from solprop.stepper.multistep import MarchPolicy from solprop.translate.problem import PropagationProblem, StepperSettings @@ -200,6 +200,46 @@ ObservationKind.STEP, ObservationKind.NATURAL, ) +_APERTURE_CONSTANTS = 11 +"""The constants before an aperture row's scale row (``far_field.hpp``).""" + + +def _aperture_payload( + tables: ApertureTables | None, n_omega: int +) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64], int]: + """Pack far-field tables as the native pass reads them (solprop SEP 23 section 6). + + Returns the ``(n_apertures, 11 + n_omega)`` aperture rows (centre x and y, the + half-width and half-height, the two stretches, the reciprocal edge width, the edge + or order, the profile and shape codes, the distance, then the scale row + ``z c / omega`` that every backend reads to the bit), the ``(n_regions, 4)`` boxes + and the exponent; empty tables without any. + """ + if tables is None: + return np.empty((0, _APERTURE_CONSTANTS + n_omega)), np.empty((0, 4)), 2 + assert tables.half_heights is not None + assert tables.stretches is not None + constants = np.column_stack( + ( + tables.centres, + tables.half_widths, + tables.half_heights, + tables.stretches, + tables.inverse_widths, + tables.edges, + tables.profile_codes, + tables.shape_codes, + tables.distances, + ) + ) + apertures = np.ascontiguousarray(np.hstack((constants, tables.scale))) + return ( + apertures, + np.ascontiguousarray(tables.regions, dtype=np.float64), + tables.exponent, + ) + + _STATES = ( SessionState.READY, SessionState.PENDING, @@ -724,8 +764,8 @@ def status(self) -> SessionStatus: plane_index=status.plane_index, attempts=status.attempts, rejected=status.rejected, - state=_STATES[status.state], - outcome=_OUTCOMES[status.outcome], + state=_STATES[int(status.state)], + outcome=_OUTCOMES[int(status.outcome)], ) def advance( diff --git a/native/tests/test_backend.py b/native/tests/test_backend.py index edd775a32..e4c5a9fb1 100644 --- a/native/tests/test_backend.py +++ b/native/tests/test_backend.py @@ -12,7 +12,7 @@ import math import re from types import SimpleNamespace -from typing import NoReturn, cast +from typing import Any, NoReturn, cast import numpy as np import numpy.typing as npt @@ -760,9 +760,10 @@ def test_native_raman_rates_refuse_wrong_dtype_and_shape( """The diagnostic preparation seam has the same exact-array contract as trials.""" workspace = _core.Workspace(_raman_native_payload(raman_case)) none = np.empty(0, dtype=np.float64) + single: Any = np.zeros(1, dtype=np.float32) try: with pytest.raises(TypeError): - _testing.prepare_raman(workspace, np.zeros(1, dtype=np.float32), none) + _testing.prepare_raman(workspace, single, none) with pytest.raises(ValueError, match="shape"): _testing.prepare_raman(workspace, np.zeros((1, 1), dtype=np.float64), none) finally: diff --git a/native/tests/test_free.py b/native/tests/test_free.py index bc2025382..2dd054e2f 100644 --- a/native/tests/test_free.py +++ b/native/tests/test_free.py @@ -6,7 +6,7 @@ from __future__ import annotations -from typing import Any +from typing import Any, cast import numpy as np import pytest @@ -279,7 +279,7 @@ def test_adams_rows_cross_to_the_host_and_back_exactly( with pytest.raises(ValueError, match="must have shape"): _testing.adams_rows_from_host(state, "store", rows.reshape(3, -1)) with pytest.raises(TypeError): - _testing.adams_rows_from_host(state, "store", rows.real.copy()) + _testing.adams_rows_from_host(state, "store", cast("Any", rows.real.copy())) with pytest.raises(TypeError): _testing.adams_rows_from_host(state, "store", np.asfortranarray(rows)) with pytest.raises(ValueError, match="unknown Adams history row"): diff --git a/native/tests/test_workspace.py b/native/tests/test_workspace.py index 3419c82ce..6c7993350 100644 --- a/native/tests/test_workspace.py +++ b/native/tests/test_workspace.py @@ -147,12 +147,16 @@ def _same(left: object, right: object) -> None: _same(value, right_map[key]) elif isinstance(left, np.ndarray): assert isinstance(right, np.ndarray) - assert right.dtype == left.dtype - np.testing.assert_array_equal(right.reshape(left.shape), left) + left_array = cast("np.ndarray[Any, np.dtype[Any]]", left) + right_array = cast("np.ndarray[Any, np.dtype[Any]]", right) + assert right_array.dtype == left_array.dtype + np.testing.assert_array_equal(right_array.reshape(left_array.shape), left_array) elif isinstance(left, (list, tuple)): assert isinstance(right, list) - assert len(right) == len(left) # pyright: ignore[reportUnknownArgumentType] - for one, other in zip(left, right, strict=True): # pyright: ignore[reportUnknownArgumentType] + left_items = cast("list[object] | tuple[object, ...]", left) + right_items = cast("list[object]", right) + assert len(right_items) == len(left_items) + for one, other in zip(left_items, right_items, strict=True): _same(one, other) elif isinstance(left, float) and math.isnan(left): assert isinstance(right, float) @@ -229,42 +233,45 @@ def _table(n_edges: int = 3) -> dict[str, object]: } -@pytest.mark.parametrize( - ("spoil", "error", "message"), - [ - (lambda t: t.pop("lower"), ValueError, r"stage\.Table\.lower is missing"), - (lambda t: t.update(extra=1), ValueError, "unknown field 'extra'"), - ( - lambda t: t.update(coefficients=np.zeros((2, 2, 1), dtype=np.float32)), - TypeError, - r"coefficients must be a C-contiguous float64 array of rank 3", - ), - ( - lambda t: t.update(coefficients=np.zeros((2, 2))), - ValueError, - "of rank 3", - ), - # The right element count with its axes swapped breaks the relation. - ( - lambda t: t.update(coefficients=np.zeros((1, 2, 2))), - ValueError, - r"axis 0 gives n_edges = 2, where the record has 3", - ), - ( - lambda t: t.update(coefficients=np.zeros((2, 4, 1))[:, ::2]), - ValueError, - "not a strided or overlapping view", - ), - ( - lambda t: t.update(coefficients=np.broadcast_to(np.zeros(1), (2, 2, 1))), - ValueError, - "not a strided or overlapping view", - ), - (lambda t: t.update(lower="0"), TypeError, r"stage\.Table\.lower must be a"), - ], -) +type _Spoil = typing.Callable[[dict[str, Any]], object] + +_SPOILED: list[tuple[_Spoil, type[Exception], str]] = [ + (lambda t: t.pop("lower"), ValueError, r"stage\.Table\.lower is missing"), + (lambda t: t.update(extra=1), ValueError, "unknown field 'extra'"), + ( + lambda t: t.update(coefficients=np.zeros((2, 2, 1), dtype=np.float32)), + TypeError, + r"coefficients must be a C-contiguous float64 array of rank 3", + ), + ( + lambda t: t.update(coefficients=np.zeros((2, 2))), + ValueError, + "of rank 3", + ), + # The right element count with its axes swapped breaks the relation. + ( + lambda t: t.update(coefficients=np.zeros((1, 2, 2))), + ValueError, + r"axis 0 gives n_edges = 2, where the record has 3", + ), + ( + lambda t: t.update(coefficients=np.zeros((2, 4, 1))[:, ::2]), + ValueError, + "not a strided or overlapping view", + ), + ( + lambda t: t.update(coefficients=np.broadcast_to(np.zeros(1), (2, 2, 1))), + ValueError, + "not a strided or overlapping view", + ), + (lambda t: t.update(lower="0"), TypeError, r"stage\.Table\.lower must be a"), +] +"""Ways to spoil a stage table: each refusal names the field's path.""" + + +@pytest.mark.parametrize(("spoil", "error", "message"), _SPOILED) def test_the_converter_refuses_a_malformed_record_by_its_path( - spoil: Any, error: type[Exception], message: str + spoil: _Spoil, error: type[Exception], message: str ) -> None: table = _table() spoil(table) @@ -352,7 +359,8 @@ def _run_start(backend: Any, problem: Any, request: Any) -> dict[str, object]: resume=start.resume, ) proposal = float(request.stepper.dz_init) - adams = runge_kutta = None + adams: Any = None + runge_kutta: dict[str, object] | None = None if isinstance(request.stepper.integrator, Multistep): adams = backend._adams.start_state(loaded.z, proposal, loaded.cursor) else: @@ -424,7 +432,7 @@ def test_a_workspace_runs_a_session_as_the_old_seam_does( backend.close() try: session = workspace.start(start) - fields, terminal = _drive(session, int(np.prod(problem.shape))) + fields, terminal = _drive(session, math.prod(problem.shape)) session.close() assert terminal.outcome == 1 # completed old_planes = old.all_planes() @@ -448,7 +456,7 @@ def test_a_workspace_is_reused_across_starts_and_its_arrays_outlive_it( second_start = _run_start(backend, problem, request) finally: backend.close() - n = int(np.prod(problem.shape)) + n = math.prod(problem.shape) session = workspace.start(first_start) # The launch's batch, taken by hand: its arrays are kept past everything below. batch = session.advance(1, 3600.0) @@ -625,7 +633,7 @@ def test_an_injected_fault_fails_the_run_at_its_stage(phase_a_case: PhaseACase) # The second step's trial fails, after the first committed. _testing.inject_fault(workspace, "trial", 1, "value") session = workspace.start(start) - _, terminal = _drive(session, int(np.prod(problem.shape))) + _, terminal = _drive(session, math.prod(problem.shape)) session.close() assert terminal.outcome == 3 # failed assert "injected" in terminal.message From 1b54a6747ba6a6a387dc0e186cdd8ef7d86b1b4a Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 10:20:51 +0000 Subject: [PATCH 26/29] fix(native): device compilers and clang-tidy accept the field tables and workspace GCC (as the CUDA host compiler) read the member-pointer declarations as parenthesised: they are aliases now. The marches' entry points read their optionals checked, and the probe takes its start by reference. Co-Authored-By: Claude Opus 5.5 --- native/include/solprop_native/fields.hpp | 15 ++++++++++----- native/include/solprop_native/workspace.hpp | 2 +- native/src/bindings.cpp | 4 ++-- native/src/workspace.cpp | 17 ++++++++++------- 4 files changed, 23 insertions(+), 15 deletions(-) diff --git a/native/include/solprop_native/fields.hpp b/native/include/solprop_native/fields.hpp index 0e44fbfc2..3175d4526 100644 --- a/native/include/solprop_native/fields.hpp +++ b/native/include/solprop_native/fields.hpp @@ -117,30 +117,35 @@ struct Extent { /** A field whose conversion follows its member's type. */ template struct Value { + using Pointer = Member Record::*; const char* name; - Member Record::* member; + Pointer member; }; /** An optional value held as a flag beside it: `None` clears the flag. */ template struct Flagged { + using FlagPointer = bool Record::*; + using Pointer = Member Record::*; const char* name; - bool Record::* flag; - Member Record::* member; + FlagPointer flag; + Pointer member; }; /** An array of `Element` stored flat in a vector, C order. `Rank` zero takes any rank, and the record keeps the shape in its `shapes` map when it has one. */ template struct Array { + using Pointer = Element Record::*; // a std::vector of the stored element const char* name; - Element Record::* member; // a std::vector of the stored element + Pointer member; Dtype dtype; std::array extents; }; /** A count the arrays' extents give: set from `symbol`, never read from Python. */ template struct Count { + using Pointer = Member Record::*; const char* symbol; - Member Record::* member; + Pointer member; }; /** A record's table: its name and its fields, in order. */ diff --git a/native/include/solprop_native/workspace.hpp b/native/include/solprop_native/workspace.hpp index b1948030f..9ef2b7047 100644 --- a/native/include/solprop_native/workspace.hpp +++ b/native/include/solprop_native/workspace.hpp @@ -714,7 +714,7 @@ class Workspace { /** A probe from a run's start (SEP 52 section 5.5): its field, noise and position, and, for the low-storage replay, the policy's landings and the schedule its table keys come from. Its march state, history and monitor are not read. */ - std::unique_ptr probe(RunStart start); + std::unique_ptr probe(const RunStart& start); // -- what the old seam's accessors read [[nodiscard]] const std::optional& stage_tables() const noexcept { diff --git a/native/src/bindings.cpp b/native/src/bindings.cpp index 63ed282e8..0ab331348 100644 --- a/native/src/bindings.cpp +++ b/native/src/bindings.cpp @@ -1729,12 +1729,12 @@ class BoundWorkspace final : public Owned { return std::make_unique(std::move(started), workspace_->columns()); } std::unique_ptr probe(const nb::handle run, const nb::object& host) { - auto held = records::read(run, "start"); + const auto held = records::read(run, "start"); bind_host(host); std::unique_ptr probe; { const nb::gil_scoped_release release; - probe = workspace_->probe(std::move(held)); + probe = workspace_->probe(held); } return std::make_unique(std::move(probe), workspace_->columns()); } diff --git a/native/src/workspace.cpp b/native/src/workspace.cpp index b691acdb7..7d58accea 100644 --- a/native/src/workspace.cpp +++ b/native/src/workspace.cpp @@ -745,10 +745,11 @@ march::Result Workspace::run_adams(march::State& state, const march::Bounds& bou require_unleased(); if (!march_policy_ || !stage_tables_) throw std::logic_error("the native Adams march is not configured"); - engines::ResidentEngine engine(this->state(), *stage_tables_, stage_anchor_, - march_fused_, march_compensated_, march_interpolate_, - fault_); - return march::run(*march_policy_, state, engine, bounds, march_schedule_); + const auto& policy = march_policy_.value(); + const auto& tables = stage_tables_.value(); + engines::ResidentEngine engine(this->state(), tables, stage_anchor_, march_fused_, + march_compensated_, march_interpolate_, fault_); + return march::run(policy, state, engine, bounds, march_schedule_); } rk::Result Workspace::run_rk(rk::State& state, const march::Bounds& bounds) { @@ -757,11 +758,13 @@ rk::Result Workspace::run_rk(rk::State& state, const march::Bounds& bounds) { throw std::logic_error("the native Runge-Kutta march is not configured"); if (!runge_kutta_) throw std::logic_error("the native Runge-Kutta trial is not configured"); + const auto& policy = rk_policy_.value(); + const auto& trial = runge_kutta_.value(); engines::ResidentRungeKutta engine( this->state(), [this](const double z, const double dz) { return staged_trial(z, dz, false); }, - runge_kutta_->rtol, runge_kutta_->atol, runge_kutta_->weights); - return rk::run(*rk_policy_, state, engine, bounds, rk_schedule_); + trial.rtol, trial.atol, trial.weights); + return rk::run(policy, state, engine, bounds, rk_schedule_); } void Workspace::load(const std::span field, @@ -915,7 +918,7 @@ std::unique_ptr Workspace::probe(std::vector field, return std::make_unique(*this, std::move(field), std::move(noise), z); } -std::unique_ptr Workspace::probe(RunStart start) { +std::unique_ptr Workspace::probe(const RunStart& start) { require_open(); // The low-storage replay's landings and table keys come from the run's records; an // Adams workspace's probe takes Runge-Kutta trials, which read none of them. From 2872c3512064a12f8c404f1cfe39ad7315947a37 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 10:53:02 +0000 Subject: [PATCH 27/29] fix(native): nvcc compiles the problem groups' setters; the workspace test checks its optional nvcc's front end does not discard an if-constexpr requires branch inside the setter lambda, so a group's shape is kept through two overloads instead. Co-Authored-By: Claude Opus 5.5 --- native/src/bindings.cpp | 24 ++++++++++++++++-------- native/tests/native/test_workspace.cpp | 3 ++- 2 files changed, 18 insertions(+), 9 deletions(-) diff --git a/native/src/bindings.cpp b/native/src/bindings.cpp index 0ab331348..a4565b134 100644 --- a/native/src/bindings.cpp +++ b/native/src/bindings.cpp @@ -516,6 +516,19 @@ void bind_setup(nb::class_& problem, const char* name, nb::for_setter(nb::arg("value").none())); } +/** Keep an array's shape on a group that holds its layouts (`shapes`), for + `Problem::validate`; a group without one keeps none. Overloads rather than an + `if constexpr` inside the setter, which nvcc's front end does not discard. */ +template +auto keep_shape(Group& group, const char* label, std::vector& shape, int) + -> decltype(group.shapes, void()) { + group.shapes[label] = std::move(shape); +} + +template +void keep_shape(Group& /*group*/, const char* /*label*/, + std::vector& /*shape*/, long) {} + /** One group of the problem's fields, bound as a nested class from its field table (solprop SEP 52 section 5.3): scalars read and written as they are, arrays as exact arrays (`exact_vector`) of the table's rank, or of any rank where it gives none. A @@ -544,14 +557,9 @@ void bind_group(const nb::handle scope, const char* name, const std::string& pat label, [member](const Group& self) { return array_of(self.*member); }, [member, label, where = path + "." + label](Group& self, const nb::handle value) { - if constexpr (requires { self.shapes; }) { - std::vector shape; - self.*member = exact_vector(value, where, rank, &shape); - self.shapes[label] = std::move(shape); - } else { - static_cast(label); - self.*member = exact_vector(value, where, rank); - } + std::vector shape; + self.*member = exact_vector(value, where, rank, &shape); + keep_shape(self, label, shape, 0); }, nb::for_getter(nb::rv_policy::automatic), nb::for_setter(nb::sig(setter.c_str()))); diff --git a/native/tests/native/test_workspace.cpp b/native/tests/native/test_workspace.cpp index 93f8473b4..20dea2f80 100644 --- a/native/tests/native/test_workspace.cpp +++ b/native/tests/native/test_workspace.cpp @@ -138,7 +138,8 @@ TEST(Workspace, TheSetupIsAppliedWhenTheWorkspaceIsBuilt) { TEST(Workspace, StageTablesOfAnotherTableauAreRefused) { auto setup = runge_kutta_setup(); - setup.stage_tables->n_stages = 2; + ASSERT_TRUE(setup.stage_tables.has_value()); + setup.stage_tables.value().n_stages = 2; EXPECT_THROW(native::Workspace(with_setup(envelope_problem(), setup)), std::invalid_argument); } From 3732fe20c80434667590ef7107c0d21cb83d76c0 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 11:43:00 +0000 Subject: [PATCH 28/29] fix(native): clang-tidy accepts the new binding and record converter code The export recipe's table is internal to the binding unit; engine and session accessors are nodiscard; copies and searches use ranges; record fields are matched with any_of/all_of; a refusal's message is appended rather than concatenated; an optional array is read checked. The dependent typenames nvcc needs keep their NOLINT, as chebyshev.hpp's do. Co-Authored-By: Claude Opus 5.5 --- native/src/bindings.cpp | 44 +++++++++++++++++++++++------------------ native/src/records.cpp | 18 +++++++++++------ native/src/records.hpp | 17 ++++++++++------ 3 files changed, 48 insertions(+), 31 deletions(-) diff --git a/native/src/bindings.cpp b/native/src/bindings.cpp index a4565b134..c41345d91 100644 --- a/native/src/bindings.cpp +++ b/native/src/bindings.cpp @@ -520,14 +520,14 @@ void bind_setup(nb::class_& problem, const char* name, `Problem::validate`; a group without one keeps none. Overloads rather than an `if constexpr` inside the setter, which nvcc's front end does not discard. */ template -auto keep_shape(Group& group, const char* label, std::vector& shape, int) - -> decltype(group.shapes, void()) { +auto keep_shape(Group& group, const char* label, std::vector& shape, + int /*preferred*/) -> decltype(group.shapes, void()) { group.shapes[label] = std::move(shape); } template void keep_shape(Group& /*group*/, const char* /*label*/, - std::vector& /*shape*/, long) {} + std::vector& /*shape*/, long /*fallback*/) {} /** One group of the problem's fields, bound as a nested class from its field table (solprop SEP 52 section 5.3): scalars read and written as they are, arrays as exact @@ -1293,6 +1293,8 @@ using Ticket = std::pair; namespace solprop_native { +namespace { + // An export's conversion (`solprop.backends.export.ExportRecipe`) with the route's // power weight at the ticket's position, none unless `power`. struct ExportRecipe { @@ -1308,6 +1310,8 @@ struct ExportRecipe { fields::array("weight", &R::weight, fields::Extent::any())); } +} // namespace + } // namespace solprop_native namespace { @@ -1327,7 +1331,7 @@ class BoundSession { BoundSession(BoundSession&&) = delete; BoundSession& operator=(BoundSession&&) = delete; - native::session::Session& session() const { return run_->session(); } + [[nodiscard]] native::session::Session& session() const { return run_->session(); } // The advance runs without the interpreter lock; its batch becomes a record with it. BatchRecord advance(const std::size_t work_limit, const double deadline) { @@ -2241,8 +2245,9 @@ class TestState { return owner_->raman_terms(); } [[nodiscard]] bool raman() const noexcept { return owner_->raman(); } - std::vector trial_step(const double dz, const native::TrialScalars& scalars, - const bool prepare_only) const { + [[nodiscard]] std::vector trial_step(const double dz, + const native::TrialScalars& scalars, + const bool prepare_only) const { auto& state = open_state(); if (prepare_only) { state.prepare_trial(dz, scalars); @@ -2265,8 +2270,9 @@ class TestState { weighted_error(const std::vector& scale) const { return open_state().weighted_error(scale); } - std::vector form_flow_actions(const std::size_t section, const double dz, - const std::vector& fractions) const { + [[nodiscard]] std::vector + form_flow_actions(const std::size_t section, const double dz, + const std::vector& fractions) const { auto& state = open_state(); workspace_->forget_flow_key(); return state.form_flow_actions(section, dz, fractions); @@ -2402,31 +2408,31 @@ class TestEngines { owner_->release(this); owner_ = nullptr; } - native::GeneralState& state() const { + [[nodiscard]] native::GeneralState& state() const { if (owner_ == nullptr) throw std::logic_error("the engines are closed"); return owner_->leased_state(this); } - native::rk::Engine& runge_kutta() const { - state(); + [[nodiscard]] native::rk::Engine& runge_kutta() const { + static_cast(state()); if (!runge_kutta_) throw std::logic_error("this workspace has no Runge-Kutta engine"); return *runge_kutta_; } - native::march::Engine& adams() const { - state(); + [[nodiscard]] native::march::Engine& adams() const { + static_cast(state()); if (!adams_) throw std::logic_error("this workspace has no Adams engine"); return *adams_; } - ComplexOutput field() const { + [[nodiscard]] ComplexOutput field() const { const std::size_t count = owner_ == nullptr ? 0 : owner_->elements(); auto storage = native::crossing::host_buffer(2 * count); state().field_to_host({reinterpret_cast(storage.get()), count}); return complex_buffer_output(std::move(storage), {owner_->columns(), count / owner_->columns()}); } - ComplexOutput stage(const std::size_t index) const { + [[nodiscard]] ComplexOutput stage(const std::size_t index) const { const std::size_t count = owner_ == nullptr ? 0 : owner_->elements(); auto storage = native::crossing::host_buffer(2 * count); state().stage_to_host(index, @@ -2485,11 +2491,11 @@ native::march::Stencil stencil_from(const nb::handle value) { if (nodes.size() != rows.size() || nodes.size() > native::march::max_history || orders.size() > native::march::max_orders) throw std::invalid_argument("a stencil's nodes and rows are one per held entry"); - std::copy(nodes.begin(), nodes.end(), stencil.nodes.begin()); - std::copy(rows.begin(), rows.end(), stencil.rows.begin()); + std::ranges::copy(nodes, stencil.nodes.begin()); + std::ranges::copy(rows, stencil.rows.begin()); stencil.held = nodes.size(); stencil.order = nb::cast(value.attr("order")); - std::copy(orders.begin(), orders.end(), stencil.orders.begin()); + std::ranges::copy(orders, stencil.orders.begin()); stencil.n_orders = orders.size(); return stencil; } @@ -3353,7 +3359,7 @@ void bind_testing(nb::module_& testing) { throw std::logic_error("no z table's slots were configured"); const auto known = native::names(static_cast(nullptr)); - const auto found = std::ranges::find_if( + const auto* const found = std::ranges::find_if( known, [&kind](const auto& entry) { return kind == entry.first; }); if (found == known.end()) throw std::invalid_argument("a z table is phi, prefactor, rate or flux"); diff --git a/native/src/records.cpp b/native/src/records.cpp index 5c3f7839e..a222fca74 100644 --- a/native/src/records.cpp +++ b/native/src/records.cpp @@ -6,6 +6,7 @@ #include +#include #include #include #include @@ -137,10 +138,8 @@ Source::Source(const nb::handle value, const std::string& path) : value_(value) bool Source::has(const char* name, const std::size_t index) const { if (positional_) return index < size_; - for (const auto& entry : *names_) - if (entry == name) - return true; - return false; + return std::ranges::any_of(*names_, + [name](const auto& entry) { return entry == name; }); } nb::object Source::get(const char* name, const std::size_t index) const { @@ -262,8 +261,15 @@ void relate(const std::vector& shape, const fields::Extent* extents const auto& extent = extents[axis]; const std::size_t size = shape[axis]; const auto refuse_axis = [&](const std::string& why) { - value_refusal(path, "has shape " + shape_text(shape) + ", and its layout is " + - relation + ": axis " + std::to_string(axis) + " " + why); + std::string message = "has shape "; + message += shape_text(shape); + message += ", and its layout is "; + message += relation; + message += ": axis "; + message += std::to_string(axis); + message += " "; + message += why; + value_refusal(path, message); }; if (extent.fixed_size) { if (size != extent.literal) diff --git a/native/src/records.hpp b/native/src/records.hpp index dbd76b4b3..3070a2ddd 100644 --- a/native/src/records.hpp +++ b/native/src/records.hpp @@ -9,6 +9,7 @@ #include #include +#include #include #include #include @@ -187,10 +188,8 @@ template bool matches(const Source& source) { return source.size() == wanted.size(); if (source.names().size() != wanted.size()) return false; - for (const char* name : wanted) - if (!source.has(name, 0)) - return false; - return true; + return std::ranges::all_of( + wanted, [&source](const char* name) { return source.has(name, 0); }); } template void read_value(nb::handle value, T* out, const std::string& path); @@ -199,7 +198,7 @@ template void read_variant(nb::handle value, Variant* out, const std::string& path) { const Source source(value, path); bool found = false; - const auto attempt = [&]() { + const auto attempt = [&] { if (found || !matches(source)) return; found = true; @@ -278,6 +277,8 @@ template void read_value(nb::handle value, T* out, const std::string& if (out != nullptr) *out = nb::cast(value); } else if constexpr (IsOptional::value) { + // nvcc still needs the `typename` that C++20 makes redundant on the dependent type. + // NOLINTNEXTLINE(readability-redundant-typename) using Inner = typename T::value_type; if (value.is_none()) { if (out != nullptr) @@ -326,6 +327,8 @@ template void read_value(nb::handle value, T* out, const std::string& read_value(items[index], out == nullptr ? nullptr : &(*out)[index], child(path, index)); } else if constexpr (IsVector::value) { + // nvcc still needs the `typename` that C++20 makes redundant on the dependent type. + // NOLINTNEXTLINE(readability-redundant-typename) using Element = typename T::value_type; if (!is_sequence(value)) type_refusal(path, "must be a sequence"); @@ -361,6 +364,8 @@ template void read_array(const fields::Array& field, nb::handle value, R* out, Symbols& symbols, const std::string& path) { using Traits = fields::ArrayElement; + // nvcc still needs the `typename` that C++20 makes redundant on the dependent type. + // NOLINTNEXTLINE(readability-redundant-typename) using Element = typename Traits::type; if constexpr (Traits::optional) { if (value.is_none()) { @@ -619,7 +624,7 @@ nb::object write_array(const fields::Array& field, const R& record, if constexpr (Traits::optional) { if (!(record.*field.member)) return nb::none(); - held = *(record.*field.member); + held = (record.*field.member).value(); } else { held = record.*field.member; } From 78de0821b320b5bb963954a84a0e0e29c6d60f00 Mon Sep 17 00:00:00 2001 From: John Travers Date: Mon, 16 Nov 2026 12:06:35 +0000 Subject: [PATCH 29/29] fix(native): MSVC builds the z-table search; tidy takes a char MSVC's std::array iterator is a class, not a pointer, so the search keeps a plain auto with the qualified-auto check silenced and its reason. Co-Authored-By: Claude Opus 5.5 --- native/src/bindings.cpp | 3 ++- native/src/records.cpp | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/native/src/bindings.cpp b/native/src/bindings.cpp index c41345d91..b959b63df 100644 --- a/native/src/bindings.cpp +++ b/native/src/bindings.cpp @@ -3359,7 +3359,8 @@ void bind_testing(nb::module_& testing) { throw std::logic_error("no z table's slots were configured"); const auto known = native::names(static_cast(nullptr)); - const auto* const found = std::ranges::find_if( + // NOLINTNEXTLINE(readability-qualified-auto): an iterator, a class on MSVC + const auto found = std::ranges::find_if( known, [&kind](const auto& entry) { return kind == entry.first; }); if (found == known.end()) throw std::invalid_argument("a z table is phi, prefactor, rate or flux"); diff --git a/native/src/records.cpp b/native/src/records.cpp index a222fca74..0c9a35da5 100644 --- a/native/src/records.cpp +++ b/native/src/records.cpp @@ -267,7 +267,7 @@ void relate(const std::vector& shape, const fields::Extent* extents message += relation; message += ": axis "; message += std::to_string(axis); - message += " "; + message += ' '; message += why; value_refusal(path, message); };