[jtravs]

Stacked on #766 (chore/docstring-diet): review that first; this PR's diff is against it.

Implements ADR-077 ("Two backends, binary64 only", docs/dev/decisions.md): retires single and mixed precision, the backend tiers and plugin rows, and the reference-only methods native refused by name, and decouples the native adapter from numpy_ref.

The decisions (ADR-077)

• solprop computes in IEEE 754 binary64 only; single and mixed precision are retired (supersedes ADR-054 and ADR-061, amends ADR-064 and ADR-068, withdraws SEP 48).
• Exactly two backends: native (required, what auto selects, CPUs and GPUs, every feature but the TDSE response) and numpy_ref (the numerical reference). No tier system, no plugin rows, no other backend.
• numpy_ref's end state is a slim test and development reference, specified by a later SEP; until then ADR-068's rules stand (a feature lands on both backends; Final needs parity on numpy_ref and native CPU).
• The reference-only methods go: CF4 coupled-flow sections, ComparisonMultistep with its Hermite and Milne variants, and PIController subclasses that override its decisions (PIController is final).
• The precision field and CF4's settings leave the hashed configuration in one release, so resume identity changes once.

Lane A: binary64 only, two backends, the precision key

• Removes numpy_ref/single.py, numpy_ref/transforms.py, translate/precision.py, the precision= keyword everywhere it was accepted (Simulation, prop_*, recipes, service, GUI), the precision refusals and BuildInfo.precision, the single-precision guide page, gallery example and recipe example.
• Collapses backends/registry.py to a fixed table of the two backends: no BackendEntry, plugin loading, FAR_FIELD_BACKENDS or REMOVED_BACKENDS (a recorded retired name still opens and resumes a file).
• Removes the hashed "precision" key from the run record (precision-resume-key.breaking.md).
• Deleted tests: tests/backends/test_single_precision.py, tests/translate/test_precision.py, tests/driver/test_retired_backend_runs.py and tests/data/retired_backends/; and, by name (each kept, adapted or removed with its reason in the lane's record):
  • test_summary::test_precision_is_the_state_s, test_monitor::test_a_single_precision_split_reads_the_physical_removal, test_grid::test_a_single_precision_interface_grid_is_the_double_one
  • test_interface_defaults: test_the_single_precision_tolerance_rule, test_single_precision_admits_the_adams_method, test_a_default_tolerance_is_resolved_again_in_the_other_precision, test_a_named_tolerance_is_kept_in_the_other_precision, test_a_copy_in_single_precision_resolves_auto_again (removed); four more adapted and renamed
  • test_plane_adoption::test_a_kept_single_precision_plane_never_changes, ::test_the_widened_single_precision_state_is_owned_and_has_the_same_bits; test_session_records::test_an_owned_single_precision_field_is_converted_once_and_left_alone; test_transverse_backends::test_numpy_ref_s_binary32_path_carries_the_radial_collar
  • the "single"/complex64 parametrisations of test_transverse_monitor, test_plane_adoption, test_resume_history, test_reference_independence, test_metadata, test_destination_export, test_interface_defaults
  • registry: test_group_seam::test_a_registered_backend_runs_its_own_group_through_the_seam, ::test_the_lockstep_runner_is_the_registered_row_s, ::test_a_row_without_a_device_is_refused_a_required_device_by_name; test_registry::test_construct_refuses_a_registry_entry_without_an_implementation

Lane B: retire the reference-only methods; native gated plasma form

• ComparisonMultistep and the reference's general Adams path (Hermite, Milne, PECE, matched pairs) are removed; Multistep is the one Adams method.
• PIController is @final, so native's controller-override refusal goes.
• CF4 sections (translate/coupled.py, _cf4_action, CoherentWall.method/fallback/growth_limit, their capability and recipe rows) are removed.
• The dead spectral_responses leaf and has_spectral_responses flag go; the delayed-response channels are checked once, at translation.
• The private gated plasma benchmark runs on native as a test-only form. Parity against the reference: about 3e-15 relative, against allowances of 2e-12 to 1e-10; the Luna comparison tests now run on native with their tolerances unchanged.
• Deleted tests: tests/translate/test_cf4.py (whole module) and tests/test_display/CoherentWallCF4.txt; and
  • comparison family: test_exponential_march::test_comparison_variants_keep_the_interaction_formulation, test_multistep_march::test_an_unfused_method_holds_no_history_rows, ::test_dense_observation_matches_landing, ::test_variable_order_pece_one_order_higher_takes_the_general_path, test_native_march_admission::test_every_comparison_variant_is_refused_before_allocation, test_native_resume_history::test_a_march_that_cannot_carry_its_history_warns_on_resume, test_resume_history::test_the_general_path_refuses_a_snapshot_it_cannot_install, test_sep12_sep14_integration::test_corrected_provider_failure_checkpoints_the_previous_accepted_state, tests/stepper/test_multistep.py (test_any_change_to_a_comparison_variant_restarts_its_history, test_defect_constants_and_milne_factor, test_multistep_name, test_multistep_refuses_out_of_range), test_run_request::test_only_the_comparison_family_is_reference_only
  • controller: test_native_rk_admission::test_a_controller_that_overrides_a_decision_is_refused_before_allocation, test_native_session::test_a_reference_only_run_reaches_no_session
  • CF4: 13 tests of test_coherent_capillary (test_a_cf4_*, test_cf4_*, test_the_growth_guard_*, test_the_executor_and_the_estimator_*, test_the_step_doubling_defect_*, test_the_vector_taper_converges_at_each_methods_own_order, test_a_mixed_flow_runs_each_section_by_its_own_method, test_prop_capillary_runs_a_cf4_wall_end_to_end_and_records_its_guards, test_the_reference_measures_the_cf4_factors_against_the_declared_bound, test_the_cf4_record_needs_its_declaration), test_moving_guide::test_the_reference_refuses_a_cf4_flow_beside_moving_maps, test_native_coupled_flow::test_cf4_is_refused_by_name_at_the_backend_and_the_entry_point, native/tests/test_coupled_flow.py::test_cf4_is_refused_by_name, test_exponential_march::test_the_formulation_refuses_a_cf4_section, test_admission::test_a_section_method_the_caller_has_not_built_is_refused_by_its_name
  • spectral responses: native/tests/test_backend.py::test_unsupported_contracts_are_refused_by_name, test_numpy_ref_backend::test_a_declared_term_this_backend_cannot_execute_is_refused_by_name

Lane C: decouple native from numpy_ref; seam deletions

Native's adapter now imports nothing from solprop.backends.numpy_ref (git grep -n numpy_ref -- native/src finds only prose), and importing solprop_native.backend, .session and .group loads no numpy_ref module at all.

What moved where:

Was	Now
numpy_ref.admission (refuse_general_route, refuse_coupled_flow, run under each backend's name)	translate/admission.py, check_general_route, run once by PropagationProblem.validate (and so validate_run); a TranslationError naming solprop. Checks validate already makes (the regional component count, n_pol beside tables, a response without tables) are not repeated
refuse_general_leaves (for a separately built backend)	removed
numpy_ref.general_modal.node_kerr_tensor, node_kerr_form, node_delayed_maps	translate/general.py, with no refusals of their own (validation has them)
general_planned_chunk, general_node_chunk, general_dispersive_buffers, *_PER_GENERAL_NODE	backends/node_chunk.py
numpy_ref.backend.QUADRATURE_ALARM and two copies of the warning	translate/modal.py: QUADRATURE_ALARM and warn_quadrature, on the solprop.translate.modal logger
the coupled flow's Schur factors, derived twice (_coupled_flow_maps, native _decomposed_flow)	translate/coupled.py: CoupledFlowFactors, coupled_flow_factors; each backend adds only its masks and native its eigenbasis
backends/multistep.py CallLedger, budget_error, _Derivative, source_absent	backends/ledger.py (Derivative now public)
the rest of backends/multistep.py (reference-only)	backends/numpy_ref/multistep.py
backends/populations.py axis_populations (through the reference passes)	backends/numpy_ref/populations.py; axis_refusal and axis_node stay neutral
CompiledResponses.response_order (stored)	a derived property; native's _refuse_omitted_stages and the reference passes' missing-leaf and out-of-sequence refusals go
the 17 *_FIELDS tuples and _check_seam in solprop_native/__init__.py	removed with their tests; the frozen tables of tests/backends/test_driver.py hold the seam, and the watch policy's and state's names live with the trace tests. check_build keeps the source digest and the build checks

Also: the generated docs/auto_examples/index.rst drops the deleted performance gallery; tests/data/shard_weights.json drops modules that no longer exist; docs/dev/backends.md §2/§3.8/§4, kernel-contract.md, architecture.md, native/AGENTS.md ("Scope", public names) and native/README.md describe the new homes; the size ratchets are tightened to this branch's figures; the Adams trace harness's fake engine takes lane B's one-argument start, and two settings tests that still expected the Adams march's refusal of a third backend now expect the registry's (test_compiled_multistep, test_multistep_march).

docs/auto_examples/index.rst drops the deleted performance gallery. One full poe docs build (sphinx-gallery regenerates the index on every build) wrote it byte for byte as committed. The same build found two archived SEPs (33 and 36) still linking the retired single-precision pages, now unlinked, and one unqualified cross-reference, now qualified.

Not done, and why

• The varying-metric statistics refusal (native _statistics.metric_refusal) stays in native. Moving it to translation would make numpy_ref refuse statistics it computes today (test_a_varying_metric_s_statistics_are_refused_by_native_before_allocation asserts it does), and a run's prepare(problem, request) path does not run validate_run, so translation alone would not cover a request's new statistics. It needs prepare to validate the request, a session change of its own. axis_refusal has the same shape (four raise sites).
• The assembly's route-specific refusals of the modified noise model beside a coupled flow (split block, moving guide, coherent wall, in translate/problem.py) remain beside the admission's; consolidating them changes three user-facing messages.
• _require_initial_array is kept: the load copies the start with np.ascontiguousarray(..., dtype=complex128), so without it a complex64 start would be upcast silently rather than refused, and the start is user-reachable. No other adapter re-check of what exact_array enforces was found.
• C++ comments in native/src/general.cpp, flow_functions.hpp and lagrange_basis.hpp still name backends/multistep.py; editing them changes the source digest and needs a rebuild, so they are left for the next C++ change.
• backends/low_storage.py imports backends/host/driver.py, so importing native still loads the reference's host driver module (not numpy_ref); that goes with backends/host/ in SEP 49.

Review fixes (after fdd6989)

• The general route's derivations (node_kerr_tensor, node_kerr_form, node_delayed_maps) call the same rule as the admission, translate.general.check_regional_responses, so no tensor is built from a record the route cannot read.
• PropagationProblem.validate checks the general leaves' consistency first, as admission.py documents, then the route's policy. A leaf of the wrong type (translate.admission.check_leaf_types) or a mis-shaped certificate row (ModalMetricTables.check_rows) is refused by name. Tests that spoiled leaves past the old order now freeze their arrays or name the structural refusal.
• A recipe's retired keys get their reason and fix (recipe.registry.RETIRED_KEYWORDS): precision (binary64 only; precision = "double" is dropped so old recipes load), a grid's transforms (SEP 47), and CoherentWall's method, growth_limit and fallback (CF4). The changelog notes agree. The GUI needs no migration: a saved double-precision document loads, a single-precision one is refused with the reason, and an unavailable backend is already shown as named until another is picked.
• Service protocol 2: the run_options reply's new shape is refused by version at the handshake.
• The native adapter refuses the gated benchmark on an envelope plasma with a named BackendError before building; the engine's check stays as a safety net, and the Problem flag is already commented as test-only (no C++ changed).
• Derivative is documented and frozen (nothing reassigns its fields); source_absent takes a PropagationProblem.
• response_order is a functools.cached_property.
• _CoupledFlow and _HostFlow extend CoupledFlowFactors with their own fields only.

Kept: native/src/solprop_native/_budget.py. Replacing the copy with imports from solprop._process was reverted (80dd994): the native wheel must import without solprop, and its isolated smoke test (native-wheel, the python-3-15 wheel lanes) failed with ModuleNotFoundError: No module named 'solprop'. native/AGENTS.md says so again.

Breaking changes

• precision= is gone from Simulation, prop_*, recipes and the service; BuildInfo.precision is gone.
• CF4: CoherentWall(method=..., fallback=..., growth_limit=...) and the "cf4" section method are gone.
• ComparisonMultistep is gone; PIController is final (subclassing it raises StepperError).
• Resume identity changes once (the hashed "precision" key and CF4's settings leave the configuration): a run started on an earlier release finishes on it.
• The general route's and the coupled flow's refusals are TranslationErrors from the problem's validation (previously each backend's BackendError); solprop.backends.numpy_ref.admission is removed; moved names are listed in changelog.d/native-numpy-ref-decoupled.breaking.md.
• CompiledResponses(response_order=...) is no longer accepted: the order is derived from the leaves.
• The service protocol is 2: a front end and a kernel of different versions refuse each other at the handshake.
• solprop_native no longer exports the *_FIELDS tuples.

Verification

On the shared Mac, targeted only: ruff check and format, basedpyright (0 errors), native strict pyright (0 errors), poe docstrings, poe size-check, codespell on the changed files, git diff --check, poe changelog-check. Tests with -n 4 on every changed module, among them native/tests/test_api_contract.py, test_backend.py, test_general_modal.py, test_coupled_flow.py, and tests/backends/test_admission.py, test_general_modal.py, test_driver.py, test_node_chunk.py, test_native_march_traces.py, tests/driver/test_coherent_capillary.py, test_native_flow_refusals.py, test_native_flow_session.py, test_native_coupled_flow.py, test_native_flow_marches.py, test_moving_guide.py, test_split_block.py, tests/sessions/test_native_quadrature_alarm.py, test_native_load.py, test_native_session.py, test_native_session_statistics.py, tests/translate/test_problem.py, test_general_leaves.py, test_general_route.py, test_compiled_responses.py, the exponential and Adams march modules, tests/test_process.py. No C++ changed, so native was not rebuilt. No tolerance changed. The full, slow and coverage lanes are left to CI.

Size

git diff --shortstat chore/docstring-diet: 254 files changed, 3496 insertions(+), 16623 deletions(-) (lane C alone, from the merge of the diet: 108 files changed, 2278 insertions(+), 3265 deletions(-))

poe size on this branch:

package      files   total    code  pub doc  priv doc  comment  blank  __all__  sect priv  doc>body
(top-level)     32   36740   17008    13674      2891      668   2499      724          2       494
backends        33   24744   11597     8884      2128      644   1491      286          0       423
calibration     10    4411    2644     1007       327       78    355       67          0        33
coupling        10    9381    5253     2654       791       99    584      128          0        82
driver          29   26286   15329     5958      2979      578   1442      167          9       190
modes           18   19447    9252     7346      1373      446   1030      238          0       260
nonlinear       11   12485    5315     5635       682      162    691      164          0       182
output          14   12787    6502     4216       932      240    897      157          0       163
physdata        13    9496    3894     4263       538      134    667      171          0       155
plotting         6    2484    1179      926       151       41    187       76          0        31
processing      14    8969    4143     3369       746      153    558      214          1       120
recipe          12    9610    6040     2386       415      121    648      123          0        76
service         28   10132    5210     3482       434      155    851      176          0       126
stepper          7    3575    1384     1828        57       97    209       91          0        49
translate       31   34863   18617    11271      2648      585   1742      420          0       312
total          268  225410  113367    76899     17092     4201  13851     3202         12      2696

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 solprop | 🛠️ Build #35834407 | 📁 Comparing 1acdffc against latest (78d57c4)

  🔍 Preview build  

385 files changed · + 9 added · ± 359 modified · - 17 deleted

+ Added

• api/generated/solprop.backends.ledger.html
• api/generated/solprop.backends.numpy_ref.multistep.html
• api/generated/solprop.backends.numpy_ref.populations.html
• api/generated/solprop.translate.admission.html
• _modules/solprop/backends/ledger.html
• _modules/solprop/translate/admission.html
• dev/seps/archive/sep-0048-julia-backend.html
• _modules/solprop/backends/numpy_ref/multistep.html
• _modules/solprop/backends/numpy_ref/populations.html

± Modified

• genindex.html
• py-modindex.html
• sg_execution_times.html
• _modules/index.html
• api/species.html
• api/transport.html
• auto_examples/index.html
• dev/accuracy.html
• dev/architecture.html
• dev/backends.html
• and 349 more...

- Deleted

• api/generated/solprop.backends.host.general.html
• api/generated/solprop.backends.multistep.html
• api/generated/solprop.backends.numpy_ref.admission.html
• api/generated/solprop.backends.numpy_ref.single.html
• api/generated/solprop.backends.numpy_ref.transforms.html
• api/generated/solprop.translate.precision.html
• auto_examples/performance/index.html
• auto_examples/performance/plot_01_single_precision.html
• auto_examples/performance/sg_execution_times.html
• dev/seps/sep-0048-julia-backend.html
• and 7 more...

[codecov]

Codecov Report

❌ Patch coverage is 97.99270% with 11 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/solprop/translate/admission.py	92.74%	6 Missing and 3 partials ⚠️
src/solprop/recipe/registry.py	87.50%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!