Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
ab6595a
Delete unused native fft, multiply_phase and Adams entry points
jtravs Nov 16, 2026
c59a6d4
Include launch.hpp where it is used, not through core.hpp
jtravs Nov 16, 2026
0c81a73
Drop dead adapter constants, stale _records citations, a timing script
jtravs Nov 16, 2026
c6e980c
Split core.hpp and core.cpp into concept-named headers
jtravs Nov 16, 2026
89a1ed5
Move the host FFTW policy and wisdom to fftw_wisdom.hpp/.cpp
jtravs Nov 16, 2026
048689e
Move the seam's set-once and run records to run_records.hpp
jtravs Nov 16, 2026
a79d3f7
Give session::Resident its own header for engines.hpp
jtravs Nov 16, 2026
b37e813
Move the ledger's allocator queries out of general/kernels.hpp
jtravs Nov 16, 2026
8ca1959
Share the setup-time extent checks and uploads in setup_data.hpp
jtravs Nov 16, 2026
65b8efb
Name the spatial statistics flags beside StatisticsFlag
jtravs Nov 16, 2026
b7a7568
Rename src/general/workspace.hpp to general_workspace.hpp
jtravs Nov 16, 2026
9c2a862
Rename dense.hpp, the session::Dense interface, to session_dense.hpp
jtravs Nov 16, 2026
dd4f8dd
Rename dense_output.hpp to dense.hpp, the header dense.cpp implements
jtravs Nov 16, 2026
3d6038f
Rename session_statistics.cpp to statistics_plan.cpp
jtravs Nov 16, 2026
51857e2
Rename src/helpers.cpp/.hpp to bindings_helpers.cpp/.hpp
jtravs Nov 16, 2026
7db2e0e
refactor(native): split the lowering and march protocol from backend
jtravs Nov 16, 2026
d6445cf
refactor(native): move the build record to _build.py
jtravs Nov 16, 2026
63828d2
Merge S4c: split the native adapter's lowering, march and build modules
jtravs Nov 16, 2026
84d9255
Drop the native lowering's unused empty-noise constant
jtravs Nov 16, 2026
f7e7819
Put statistics_plan.cpp's own header first, as clang-format orders it
jtravs Nov 16, 2026
373b1a1
Merge S2: give the native headers concept-named boundaries
jtravs Nov 16, 2026
73e43de
Move native C++ files into domain directories
jtravs Nov 16, 2026
3650dfa
Include the standard headers the split native headers use
jtravs Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 29 additions & 27 deletions docs/dev/backends.md

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions docs/dev/benchmarks.md
Original file line number Diff line number Diff line change
Expand Up @@ -310,7 +310,7 @@ Every medium width serial instead lost 2.8 times on averaged helium (EPYC geomet
1.08); every medium width full, the FFTs included, gained on resolved cases but lost on the
averaged ones (EPYC 0.94, Xeon 0.90 with averaged helium 1.22).

The promotion applies everywhere but macOS (`stable_kernel_team` in `core.hpp`). On an
The promotion applies everywhere but macOS (`stable_kernel_team` in `cpu_execution.hpp`). On an
18-core Apple M5 Max, whose cores are of two kinds, the 11207-element Adams passes of
`argon_blueshift` at 18 threads instead of four took the window from 3.0 to 3.2 s, and
`h2_raman_averaged` at 18 threads ran 0.86 of `main`'s time without the promotion
Expand Down Expand Up @@ -1473,7 +1473,7 @@ grows as an attempt gets cheaper, and it is above 0.1 % on the two smallest grid
### The Adams passes on x86-64 lanes

The exponential Adams trial's predict and correct passes on a host block of 32 elements
held as lanes (`include/solprop_native/adams_phi.hpp`, `adams_lanes_*` in
held as lanes (`include/solprop_native/march/adams_phi.hpp`, `adams_lanes_*` in
`src/general/trial.cpp`) against the element-by-element form, at 740b24d. Before the change
the passes ran each element through latency-bound scalar strict code (the
phi-functions' series, Horner pass and squarings, the compensation and the defects),
Expand Down
6 changes: 3 additions & 3 deletions docs/dev/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -1116,7 +1116,7 @@ Withdrawn (development-process record, not a design decision).
qualified to their rounding budget and to SEP 16's work–precision cases.
- **Amendment, device builds:** the protected helpers are strict on CPU builds only.
CUDA and HIP builds leave the strict blocks empty (`SOLPROP_NATIVE_STRICT_FUNCTION`
and `SOLPROP_NATIVE_STRICT_BLOCK` in `native/include/solprop_native/fp.hpp`, under
and `SOLPROP_NATIVE_STRICT_BLOCK` in `native/include/solprop_native/runtime/fp.hpp`, under
`__CUDACC__` or `__HIPCC__`, which includes nvcc's host pass) and follow their
compilers' contraction defaults; `build_info().optimization_policy` records
"compiler-default contraction". On a device the φ series, the phase sums, the
Expand Down Expand Up @@ -1575,7 +1575,7 @@ Withdrawn (development-process record, not a design decision).
- Apple M5 Max: the system libm 3.25 ns; SLEEF's AdvSIMD functions gain nothing, and
Accelerate's vForce 1.3 times at 1.7 ulp.
- **Decision:**
- One private layer, `native/include/solprop_native/vmath.hpp`, gives the host kernels
- One private layer, `native/include/solprop_native/runtime/vmath.hpp`, gives the host kernels
batch `exp`, `log`, `sincos` and the complex exponential over contiguous arrays. A
kernel forms a block's arguments into a buffer, calls the layer once over it, and
finishes each element from the results. Converted: the Runge–Kutta stage entry, the
Expand Down Expand Up @@ -1639,7 +1639,7 @@ Withdrawn (development-process record, not a design decision).
contract's section 11 specifies them in full.
- `native` executes `Multistep()` in either formulation, the one-order-higher PEC
comparisons and replayed schedules on its resident engine for a run of attempts
per call (`native/src/adams_march.cpp`, compiled without contraction
per call (`native/src/march/adams_march.cpp`, compiled without contraction
or fast-math), returning only at a host event: a reached target, an accepted step
on which the driver has work, the monitor, the call's bound (256 attempts or
0.1 s), the budget, the floor or a native error. solprop books the call's attempts
Expand Down
2 changes: 1 addition & 1 deletion docs/dev/dependencies.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ solprop-native has no runtime dependency on solprop.
**SLEEF 3.9.0** ([sleef.org](https://sleef.org), Boost Software License 1.0) is the
native CPU build's host vector maths on x86-64 (ADR-059): vector `exp`, `log` and
`sincos`, its u10 functions (1.0 ulp over each function's domain), called over blocks
by `native/include/solprop_native/vmath.hpp`. It is fetched at its release tag like
by `native/include/solprop_native/runtime/vmath.hpp`. It is fetched at its release tag like
Kokkos (`FETCHCONTENT_SOURCE_DIR_SLEEF` names a local copy for an offline build), built
static as its own CMake project with only `libsleef` and the variants the layer calls
(SSE2, AVX2, AVX-512F on request; AdvSIMD on aarch64), and compiled into the extension, whose wheel
Expand Down
4 changes: 2 additions & 2 deletions docs/dev/kernel-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -619,7 +619,7 @@ it is prepared, from the problem and its `ExecutionOptions` -- an explicit `node
which is authoritative, or the automatic choice
(`solprop.backends.node_chunk.plan_node_chunk`) -- records it in its execution metadata,
and keeps it out of every identity and resume key. The native backend lowers the plan
further (`solprop_native.backend.native_node_chunk`: whole y rows on the planar kind, and
further (`solprop_native._device.native_node_chunk`: whole y rows on the planar kind, and
`device_node_chunk` for a device build's automatic plan: the host rule at a quarter of the
accelerator's free bytes, never fewer nodes than the host plan, solprop issue #361).

Expand Down Expand Up @@ -1341,7 +1341,7 @@ stripped extension labels only exported functions). The boundary checks above an
## 12. The Runge–Kutta march

*Normative from [SEP 45](seps/archive/sep-0045-native-rk-march.md) phase 3. `native` executes it
(`native/src/rk_march.cpp`), adaptive or replayed, with `PIController`'s norm, weighted or
(`native/src/march/rk_march.cpp`), adaptive or replayed, with `PIController`'s norm, weighted or
not, on CPU and device builds. `PIController` is final (ADR-077), so its decisions are
the only ones either backend takes.*

Expand Down
8 changes: 4 additions & 4 deletions docs/dev/stepper.md
Original file line number Diff line number Diff line change
Expand Up @@ -281,7 +281,7 @@ closes the workspace afterwards, SEP 52 §5.5). The native execution session ([S
`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
tables (`native/src/low_storage.cpp`), with no return to Python; a failure partway
tables (`native/src/march/low_storage.cpp`), with no return to Python; a failure partway
through a step leaves no consistent state, so the session's terminal event is poisoned
and claims no checkpoint. There is no estimate: the history's norm is 0.0, "not estimated". The step
is **in flight** from its start to its commit (the engine's `in_flight`, which the march
Expand Down Expand Up @@ -404,13 +404,13 @@ frozen-residual flow's generator applied once per sample.
**The native Runge–Kutta march** (ADR-069, [SEP 45](seps/archive/sep-0045-native-rk-march.md)):
`RungeKuttaMarch.march_to`'s decisions are pure functions of a `RungeKuttaPolicy`
(`backends/rk_core.py`), held to a decision corpus recorded before the refactor
(`tests/data/rk_traces.json.gz`), and `native` executes them (`native/src/rk_march.cpp`) on
(`tests/data/rk_traces.json.gz`), and `native` executes them (`native/src/march/rk_march.cpp`) on
its staged trial and native norm, a call of attempts at a time, returning only at a host
event and taking the boundary checks itself; the kernel contract's section 12 is the
interface. It covers interpolated planes (the step across a plane returns to solprop, which
holds its extension; in SEP 47's native session the march holds it through its engine,
`rk::Engine::extend`, finishes the step itself and the session observes the plane where the
state lives, `native/src/dense.cpp`), a replayed schedule, a coupled flow (its guards transcribed), a z table
state lives, `native/src/march/dense.cpp`), a replayed schedule, a coupled flow (its guards transcribed), a z table
the transverse edge (read on the host, as the Adams march reads it) and a weighted norm
(reduced natively in both loops), on CPU and device builds alike. `PIController` is final
(ADR-077): defining a subclass raises `StepperError`, so its decisions and its norm are the
Expand All @@ -424,7 +424,7 @@ record, `MarchPolicy`, formed by `march_policy` from the method and the settings
the decisions are pure functions of the policy, the march's state and a trial's norms
(`backends/adams_core.py`). The kernel contract's section 11 specifies them. `native`
executes `Multistep()` in either formulation and replayed schedules from that record on its resident engine
(`native/src/adams_march.cpp`), a run of attempts per call, and returns to solprop
(`native/src/march/adams_march.cpp`), a run of attempts per call, and returns to solprop
only at an event: the target reached or crossed, an accepted step on which the driver
has work (a statistics row, a natural stop), a boundary check whose verdict needs
solprop, the call's bound, the budget, the floor or a native error. The march takes the
Expand Down
2 changes: 1 addition & 1 deletion docs/dev/tooling.md
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ to it.
- `SOLPROP_THREADS`, the thread budget the native backend's pools stay within, and
`SOLPROP_OVERSUBSCRIBE`, which lets an explicit count exceed the CPUs (ADR-052).
- The native backend's plans and neighbours: `SOLPROP_FFTW_PLAN` (`estimate` in CI and
tests, `measure` by default, read by `native/include/solprop_native/fft_plan.hpp`),
tests, `measure` by default, read by `native/src/transforms/fftw_wisdom.cpp`),
`SOLPROP_FFTW_WISDOM` (a file name, beside which the native backend keeps the plans its
runs measure instead of the calibration store, ADR-076)
and `SOLPROP_BLAS_THREADS` (the width of the other BLAS libraries while a native
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/performance/building-native.md
Original file line number Diff line number Diff line change
Expand Up @@ -427,7 +427,7 @@ access, point it at source trees of the same versions:
The CPU kernels form their transcendentals (the stage and step propagators, the
exponential Adams method's flows, phi-functions and compensation, the ionisation rates
and fractions) in passes over blocks of elements through one layer,
`native/include/solprop_native/vmath.hpp` ([ADR-059](../../dev/decisions.md)). On x86-64
`native/include/solprop_native/runtime/vmath.hpp` ([ADR-059](../../dev/decisions.md)). On x86-64
it calls [SLEEF](https://sleef.org)'s vector functions, each within 1.0 ulp of the
correctly rounded value over its whole domain: AVX2 where the build's target has it (the
wheels' x86-64-v3 baseline and any local build on a processor from 2013 or later), SSE2
Expand Down
18 changes: 9 additions & 9 deletions native/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,12 +124,12 @@ the gate.
- Use RAII, Kokkos views, `Kokkos::complex`, device-callable math, named kernels and
allocations (`solprop_native.*` labels), explicit `LayoutRight` and explicit
execution-space instances. Dispatch top-level kernels through `launch::parallel_for`,
`parallel_reduce` and `parallel_scan` (`include/solprop_native/launch.hpp`), which pass
`parallel_reduce` and `parallel_scan` (`include/solprop_native/runtime/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 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
`include/solprop_native/runtime/host_source.hpp`): on a CPU build, a bound host source is
called from the thread that called `advance`, outside every parallel region, and the
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
Expand All @@ -150,13 +150,13 @@ the gate.
`fast` makes Clang ignore the pragmas). A protected block (a stable
increment, a small-argument function, a defect or a compensated sum) stays strict
with `SOLPROP_NATIVE_STRICT_FUNCTION` and `SOLPROP_NATIVE_STRICT_BLOCK`
(`include/solprop_native/fp.hpp`; GCC ignores `#pragma STDC FP_CONTRACT`) and spells
(`include/solprop_native/runtime/fp.hpp`; GCC ignores `#pragma STDC FP_CONTRACT`) and spells
its complex arithmetic with the `strict_*` helpers, since `Kokkos::complex`'s
operators keep their header's contraction when inlined. Reassociation is scoped to
the loops that need it. No umbrella fast-math, `nnan`/`ninf`, `nsz`, approximate
functions or reciprocals, or flush-to-zero; the `__FAST_MATH__` refusal stays.
The marches' and the session's strict files (`adams_march.cpp`, `watch.cpp`,
`rk_march.cpp`, `session.cpp`, `session_statistics.cpp`, `session_widths.cpp`,
`rk_march.cpp`, `session.cpp`, `statistics_plan.cpp`, `session_widths.cpp`,
`low_storage.cpp`, `transverse.cpp`, `session_edge.cpp`, `dense.cpp`) are compiled with
`-ffp-contract=off` and carry `#pragma GCC optimize("fp-contract=off")`, so that GCC
never inlines them into a contracting caller. Their probes are checked in the
Expand All @@ -167,7 +167,7 @@ the gate.
CUDA and HIP builds leave the strict blocks empty and follow their compilers'
contraction defaults, held to the measured device envelopes (solprop's ADR-049,
amended) until device round-to-nearest helpers land.
- A host kernel's hot transcendentals go through `include/solprop_native/vmath.hpp`
- A host kernel's hot transcendentals go through `include/solprop_native/runtime/vmath.hpp`
(solprop's ADR-059): form a block's arguments into a buffer, call the batch function
once over it, and finish each element from the results, behind
`if constexpr (vmath::vectorised)` where the per-element form is faster with the
Expand All @@ -185,17 +185,17 @@ 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`). A backend holds one `_core.Workspace`,
(`_load.py`, `_march.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`
(`build_info().source_digest`; `cmake/SourceDigest.cmake` and `_build._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()`
definition (`include/solprop_native/runtime/fields.hpp`), and is read by the one converter
(`src/bindings/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.
Expand Down
Loading
Loading