[jtravs]

The first half of PR-5 of the lean-codebase plan: the native helpers, the bound problem struct and the workspace forwarders. Stacked on feature/two-backends-binary64, with chore/native-tooling merged in. It will be retargeted to main later. The split of general.cpp, close() by destruction, the decomposition of long functions and the dead-code removal (steps 4–7) come in a later PR.

What changed

• Messages. refuse<Error>(parts...) and concat(parts...) (include/solprop_native/refuse.hpp) replace about 40 hand-built "..." + std::to_string(n) refusals. Every message keeps its exact text.
• Build facts. include/solprop_native/build.hpp defines cuda, hip, device, host and openmp. Where both branches compile in every build, #if blocks become constants or if constexpr. Blocks that name device-only or host-only facilities keep their #if, and so does the Adams flow guard that nvcc needs.
• Width dispatch. dispatch_among and dispatch_width (include/solprop_native/dispatch.hpp) replace the four switch ladders: the band filter, the modal projection lanes, and the device Adams prediction and element.
• Forwarders. The private member template GeneralState::with_team(&GeneralWorkspace::f, args...) replaces the bodies of the 66 forwarders that opened the CPU team scope by hand. The declarations stay, because the pImpl keeps the workspace class out of the strict units.
• Bound problem. native::Problem's 161 fields are nested in 14 groups: dims, grid, spatial, flux, stepper, linear, absorber, transform, kerr, plasma, raman, general, flow and dispersive. Each group is bound with nb::class_, and FieldFamily with nb::enum_.
  • Vector fields take only exact NumPy arrays (float64, complex128, uint64 or bool, C-contiguous). Fields whose count is laid out beside them also require a fixed rank. Anything else is refused, and the message names the field.
  • Problem::validate() holds problem_from's presence and extent rules, with the same messages.
  • The adapter's _lower(problem, request, plan) replaces _native_problem, its dict and its payload helpers.
  • Check: before the dict path was removed, a temporary comparison lowered 851 problems from the native test suites. Every field matched the old dict bit for bit. The problems covered plasma, envelope, Raman, general modal, coupled flow, dispersive, free, planar and low-storage cases.
  • Tests: they now set struct fields instead of dict keys. No assertion or match= was removed and no tolerance changed.

Hot-path commits (for the A/B)

• 41f53f3c dispatch_width: the band filter (host and device), the modal projection lanes, and the device Adams prediction and element.
• 9b6eec2f build facts: the Adams block width, the accepted-step fence and the band league. The others are cold predicates.
• f7f5ddc2 with_team: every GeneralState call, trial_step and the Adams trials included, goes through std::invoke.
• 2da322d9 bound problem: a mechanical rename of problem_.x to problem_.group.x throughout general.cpp, kernels included.
• d8d3af10 refuse: the cold throw branches of the stage-table and z-table lookups and of prepare_trial.

Every commit is meant to give bitwise-identical results, field_difference 0.

Sizes

tools/size_report.py covers src/solprop, which this PR does not touch. For native/ (git diff --shortstat from the base: 40 files, +4839 / −4316):

	before	after
C++ (src, include, tests/native)	56,448	56,619
adapter Python	13,864	13,877
_core.pyi	715	946
native Python tests	13,567	13,675

The plan's savings are not reached yet. Most of them were to come from the part of step 2 that this PR leaves open (below).

Not done (step 2 remainder)

• Binding the march, watch, Runge-Kutta, session, transverse and stage-table structs with nb::class_, in place of the *_from and *_to dict conversions. Their dicts are produced and read in solprop as well as in the adapter.
• Splitting NB_MODULE into bind_state.cpp, bind_session.cpp and bind_build.cpp.
• Turning the BoundState lambdas into .def(&BoundState::f, nb::call_guard<...>()). Most lambdas convert NumPy inputs before releasing the GIL, so they first need an exact-array argument type.
• Generating _core.pyi with nanobind.stubgen, with a freshness check. While most of the seam is untyped dicts, a generated stub would type them as bare dict and break strict typing in the adapter. The problem's section of the stub was generated by stubgen, then written as plain attributes.

Verification (Mac, Apple Clang via Homebrew LLVM, editable Release build, OpenMP CPU)

• Native pytest modules, run with -n 4: test_api_contract, test_backend, test_envelope_plasma, test_mixtures, test_execution, test_band_plasma, test_session_failure, test_dispersive, test_free, test_envelope_statistics_refusal, test_coupled_flow, test_general_modal, test_radial, test_planning, test_raman_tail and test_batch.
• Native parity modules from tests/backends, also with -n 4: low storage, planar, far field, every statistic, dispersive Kerr, held plasma, node chunk, phi moments, z table, stage tables, march admission, rk/march traces, widths. Flow sessions and marches, resume history and helpers from tests/driver and tests/test_helpers.py ran too.
• GoogleTest in a Debug build: passed.
• ruff, the native pyright configuration (0 errors) and clang-format.
• clang-tidy on the changed sources. One finding was fixed in its own commit.
• Two local failures happen on this Mac without the change too, so they are not counted against it:
  • test_public_surface_is_exact: an uncommitted tree gives a .dYYYYMMDD version suffix.
  • test_response_column_boundary_preserves_full_and_tail_windows[19]: it fails the same way on main here.
• Not run here: CUDA and HIP compiles. The dispatch lambdas and the if constexpr facts are compiled on devices for the first time in the device-compile lanes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HAYtF5P9QqEd3HQx3WJkA3

[read-the-docs-community]

Documentation build overview

📚 solprop | 🛠️ Build #35835822 | 📁 Comparing ccf8d8d against latest (6136c60)

  🔍 Preview build  

151 files changed · + 8 added · ± 127 modified · - 16 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
• _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
• auto_examples/index.html
• dev/accuracy.html
• dev/architecture.html
• dev/backends.html
• dev/conventions.html
• dev/decisions.html
• and 117 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
• guide/performance/single-precision.html
• and 6 more...