diff --git a/.github/scripts/apt-mirrors.sh b/.github/scripts/apt-mirrors.sh new file mode 100644 index 000000000..d956001ab --- /dev/null +++ b/.github/scripts/apt-mirrors.sh @@ -0,0 +1,13 @@ +#!/usr/bin/env bash +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# SPDX-License-Identifier: GPL-3.0-or-later + +set -euo pipefail + +# The runner's Azure mirror repeatedly failed DNS resolution before our gates (#757). +# Keep its official Ubuntu archive/security fallbacks and the existing signed sources. +# Runner configuration: actions/runner-images, images/ubuntu/scripts/build/configure-apt-sources.sh +mirrors=/etc/apt/apt-mirrors.txt +if [[ -f "$mirrors" ]]; then + sudo sed -i '/azure\.archive\.ubuntu\.com/d' "$mirrors" +fi diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b4383c042..49a96b9bc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -43,6 +43,7 @@ jobs: outputs: lanes: ${{ steps.diff.outputs.lanes }} device: ${{ steps.diff.outputs.device }} + julia: ${{ steps.diff.outputs.julia }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: @@ -84,6 +85,33 @@ jobs: device=false fi echo "device=$device" | tee -a "$GITHUB_OUTPUT" + # Linux checks Julia on every non-documentation change, including GUI-only + # changes. macOS adds a change-triggered run for its source and integration. + # Read both sides of the pipe fully: grep -q can cause an upstream SIGPIPE + # under pipefail and turn a real match into a false result on a large diff. + julia=true + if [ -f changed.txt ] && ! grep -vE '^docs/|\.md$' changed.txt | grep -E '^julia/|^src/solprop/backends/julia/|^tests/backends/julia/|^tools/check_julia\.py$|^tests/test_check_julia\.py$|^hatch_build\.py$|^pyproject\.toml$|^uv\.lock$|^\.github/workflows/(ci|julia)\.yml$' > /dev/null; then + julia=false + fi + echo "julia=$julia" | tee -a "$GITHUB_OUTPUT" + + julia-linux: + needs: [changes, native-wheel] + if: needs.changes.outputs.lanes == 'full' || needs.changes.outputs.lanes == 'gui' + uses: ./.github/workflows/julia.yml + with: + runner: ubuntu-24.04 + native-artifact: native-wheel-linux-x86_64 + + julia-macos: + needs: [changes, native-wheel] + if: >- + (needs.changes.outputs.lanes == 'full' || needs.changes.outputs.lanes == 'gui') + && needs.changes.outputs.julia == 'true' + uses: ./.github/workflows/julia.yml + with: + runner: macos-15 + native-artifact: native-wheel-macos-arm64 docs-tests: needs: [changes, native-wheel] @@ -103,6 +131,7 @@ jobs: path: wheelhouse - name: Install the native runtime libraries run: | + bash .github/scripts/apt-mirrors.sh sudo apt-get update sudo apt-get install --yes libfftw3-dev - run: uv python install 3.14 @@ -159,6 +188,7 @@ jobs: path: wheelhouse - name: Install the native runtime libraries run: | + bash .github/scripts/apt-mirrors.sh sudo apt-get update sudo apt-get install --yes libfftw3-dev - run: uv python install 3.14 @@ -207,6 +237,7 @@ jobs: - if: steps.cache.outputs.cache-hit != 'true' && runner.os == 'Linux' name: Install the native toolchain run: | + bash .github/scripts/apt-mirrors.sh sudo apt-get update sudo apt-get install --yes cmake g++-14 libfftw3-dev ninja-build pkg-config - if: steps.cache.outputs.cache-hit != 'true' && runner.os == 'Linux' @@ -326,6 +357,7 @@ jobs: path: wheelhouse - name: Install the native runtime libraries run: | + bash .github/scripts/apt-mirrors.sh sudo apt-get update sudo apt-get install --yes libfftw3-dev - run: uv python install 3.14 @@ -391,6 +423,7 @@ jobs: path: wheelhouse - name: Install the native runtime libraries run: | + bash .github/scripts/apt-mirrors.sh sudo apt-get update sudo apt-get install --yes libfftw3-dev - run: uv python install 3.14 @@ -488,6 +521,7 @@ jobs: path: wheelhouse - name: Install the native runtime libraries run: | + bash .github/scripts/apt-mirrors.sh sudo apt-get update sudo apt-get install --yes libfftw3-dev - run: uv venv --python 3.14 @@ -561,6 +595,7 @@ jobs: node-version: "26" - name: Install the native toolchain run: | + bash .github/scripts/apt-mirrors.sh sudo apt-get update sudo apt-get install --yes clang-tidy cmake g++-14 libfftw3-dev ninja-build pkg-config - run: uv python install 3.14 @@ -593,6 +628,7 @@ jobs: run: | curl -fsSL https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb -o keyring.deb sudo dpkg -i keyring.deb + bash .github/scripts/apt-mirrors.sh sudo apt-get update sudo apt-get install --yes --no-install-recommends cmake g++-14 libfftw3-dev libopenblas-dev ninja-build pkg-config cuda-compiler-12-8 cuda-libraries-dev-12-8 df -h / @@ -641,6 +677,7 @@ jobs: echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/rocm/apt/7.2 noble main" | sudo tee /etc/apt/sources.list.d/rocm.list # Ubuntu has an older hipcc whose version number sorts higher than AMD's. printf 'Package: *\nPin: origin repo.radeon.com\nPin-Priority: 1001\n' | sudo tee /etc/apt/preferences.d/rocm + bash .github/scripts/apt-mirrors.sh sudo apt-get update sudo apt-get install --yes --no-install-recommends cmake libfftw3-dev libopenblas-dev ninja-build pkg-config g++-14 hip-dev hipcc rocm-llvm rocm-device-libs rocm-cmake rocfft-dev rocblas-dev echo "ROCM_PATH=/opt/rocm" >> "$GITHUB_ENV" @@ -691,6 +728,7 @@ jobs: # Qt's offscreen platform still loads EGL, OpenGL, xkbcommon and fontconfig. - if: runner.os == 'Linux' run: | + bash .github/scripts/apt-mirrors.sh sudo apt-get update sudo apt-get install --yes libegl1 libgl1 libxkbcommon0 libfontconfig1 libdbus-1-3 - if: runner.os == 'Linux' @@ -730,6 +768,8 @@ jobs: - static - docs - native-wheel + - julia-linux + - julia-macos - test - slow - slow-macos diff --git a/.github/workflows/julia.yml b/.github/workflows/julia.yml new file mode 100644 index 000000000..89b755310 --- /dev/null +++ b/.github/workflows/julia.yml @@ -0,0 +1,130 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +name: Julia + +on: + workflow_call: + inputs: + runner: + description: GitHub-hosted runner matching the native wheel artifact + required: true + type: string + native-artifact: + description: Matching native-wheel artifact from this CI run + required: true + type: string + schedule: + - cron: "23 4 * * 1" + +permissions: + contents: read + +# Called jobs share their caller's workflow name. Include the runner so the Linux +# and macOS calls cannot cancel each other or the parent CI workflow. +concurrency: + group: julia-${{ github.workflow }}-${{ github.ref }}-${{ inputs.runner || 'macos-15' }} + cancel-in-progress: true + +env: + UV_NO_SYNC: "1" + SOLPROP_FFTW_PLAN: estimate + SOLPROP_TEST_JULIA: "1" + SOLPROP_TEST_TYPECHECK: "0" + JULIA_CPU_TARGET: generic + JULIA_LOAD_PATH: "@:@stdlib" + JULIA_REVISE_POLL: "1" + PYTHONDONTWRITEBYTECODE: "1" + +jobs: + julia: + name: Julia ${{ matrix.stage }} (${{ inputs.runner || 'macos-15' }}) + runs-on: ${{ inputs.runner || 'macos-15' }} + # The combined Linux gate reached two hours while its adapter suite progressed. + # Give each complete stage its own bound; retain every check and failure (#712). + timeout-minutes: 180 + strategy: + fail-fast: false + matrix: + stage: [engine, adapter] + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 # both distributions derive their version from tags + - name: Select the private Julia depot + run: | + echo "SOLPROP_JULIA_DEPOT=$RUNNER_TEMP/solprop-julia" >> "$GITHUB_ENV" + echo "JULIA_DEPOT_PATH=$RUNNER_TEMP/solprop-julia" >> "$GITHUB_ENV" + - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3 + with: + enable-cache: true + - run: uv python install 3.14 + - name: Read and validate the committed Julia pins + id: pins + run: uv run --no-project --python 3.14 python tools/check_julia.py metadata + - uses: julia-actions/setup-julia@da908477b5db94c10ffce8cfea9f2b3b9d5db687 # v3 + with: + version: ${{ steps.pins.outputs.julia }} + show-versioninfo: true + - name: Cache the private Julia depot + uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: ${{ env.SOLPROP_JULIA_DEPOT }} + key: >- + julia-v1-${{ runner.os }}-${{ runner.arch }}-${{ steps.pins.outputs.julia }}-${{ + steps.pins.outputs.PythonCall }}-generic-${{ hashFiles('julia/Project.toml', + 'julia/bridge.toml', 'julia/src/**', 'julia/ext/**', 'julia/scripts/**', + 'julia/environments/**', '!julia/environments/**/*.md') }} + - name: Install native runtime libraries + if: runner.os == 'Linux' + run: | + bash .github/scripts/apt-mirrors.sh + sudo apt-get update + sudo apt-get install --yes libfftw3-dev + - name: Download the native wheel from this CI run + if: github.event_name != 'schedule' + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: ${{ inputs.native-artifact }} + path: wheelhouse + - name: Install Python and the matching native wheel + if: github.event_name != 'schedule' + run: | + uv sync --locked --extra julia --no-install-package solprop-native + uv pip install --no-deps wheelhouse/*.whl + # Scheduled runs have no native-wheel producer. Each stage builds it locally; + # pull requests always use CI's already-qualified artifact. + - name: Install the weekly native toolchain + if: github.event_name == 'schedule' + run: brew install llvm ninja fftw libomp + - name: Build the native package for the weekly run + if: github.event_name == 'schedule' + run: uv sync --locked --extra julia + - name: Validate native coexistence prerequisites + run: >- + uv run --no-sync python -c + "from solprop_native import check_build; check_build()" + - name: Publish and verify the managed CPU setup + run: uv run --no-sync python tools/check_julia.py setup + - name: Check Runic formatting + if: matrix.stage == 'engine' + run: uv run --no-sync python tools/check_julia.py format + - name: Run CPU Core tests with bounds checking + if: matrix.stage == 'engine' + run: uv run --no-sync python tools/check_julia.py core + - name: Run Aqua and blocking JET error analysis + if: matrix.stage == 'engine' + run: uv run --no-sync python tools/check_julia.py quality + # SEP 48 permits omitting the optional Tier 3 adapter from the default coverage + # lane. This separate Julia lane qualifies it, including real runtime subprocess + # probes; their presence and explicit opt-in are mandatory. + # Binary32 qualification remains an explicit `check_julia.py precision` + # command after the maintainer selected the binary64 CPU/CUDA baseline. + # Engine regressions, public refusals and every binary64 suite still run. + - name: Run binary64 Julia adapter and runtime subprocess tests + if: matrix.stage == 'adapter' + run: uv run --no-sync python tools/check_julia.py python + - name: Refuse changes to committed Julia inputs + if: always() + run: git diff --exit-code -- julia diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index aadbd9e83..d5946127e 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -250,6 +250,7 @@ jobs: path: wheelhouse - name: Install HDF5 for h5py's source build run: | + bash .github/scripts/apt-mirrors.sh sudo apt-get update sudo apt-get install --yes libhdf5-dev pkg-config - run: uv python install 3.15 diff --git a/AGENTS.md b/AGENTS.md index 64a84980c..2d3fa3c76 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,6 +39,10 @@ rather than style, ask rather than guess. ## Commands +The optional Julia engine is developed under `julia/` and ships inside `solprop`. +Changes there also follow [`julia/AGENTS.md`](julia/AGENTS.md); its current phase, +ownership and verification evidence are in [`julia/IMPLEMENTATION.md`](julia/IMPLEMENTATION.md). + | Task | Command | |---|---| | Sync environment | `uv sync` builds and installs the native backend from `native/` (editable), and needs a C++20 compiler; `--extra gui --group gui-test` adds the front end from `gui/` with its test plugin. A sync removes every extra it does not name; `uv sync --inexact` keeps a hand-installed Pyroraptor. `uv run --no-project tools/setup_light.py` is the lightweight setup, with no native package and no compiler: then `UV_NO_SYNC=1` or an activated environment, and `SOLPROP_TEST_BACKEND=numpy_ref`. It supports the reference backend and the lint, type, test and documentation checks; `auto` refuses there, and a native change needs a native build. After that setup, `uv run --no-sync poe fetch-wheel` installs the wheel CI built, with no compiler, and refuses one that doesn't fit this tree (`docs/dev/contributing.md`) | diff --git a/benchmarks/track.py b/benchmarks/track.py index f227328a5..d6e800ecb 100644 --- a/benchmarks/track.py +++ b/benchmarks/track.py @@ -39,7 +39,7 @@ thread_environment, ) -BACKENDS = ("numpy_ref", "native") +BACKENDS = ("numpy_ref", "native", "julia") """The backends a benchmark can name.""" REPEAT_TOLERANCE = 1e-9 @@ -205,8 +205,14 @@ def summarise( # unchecked: no evidence of consistency, never a pass. same_steps = None if any(None in pair for pair in steps) else len(steps) == 1 difference = result["repeat_difference"] + wall_times = [item.get("wall_seconds") for item in result["repetitions"]] return { **base, + "timing_boundary": last.get("timing_boundary"), + "wall_median_s": None + if any(value is None for value in wall_times) + else statistics.median(wall_times), + "prepared_runtime": result.get("prepared_runtime"), "median_s": statistics.median(times), "min_s": min(times), "max_s": max(times), @@ -222,6 +228,7 @@ def summarise( and result["finite"] is True and (device or native_threads in (None, values["threads"])), "source_evaluations": last["source_evaluations"], + "source_counter": last.get("source_counter"), "peak_rss_gib": result["peak_rss_bytes"] / 2**30, "device_gib": None if result.get("device_bytes") is None diff --git a/benchmarks/worker.py b/benchmarks/worker.py index 5006c9833..8a6fdaf71 100644 --- a/benchmarks/worker.py +++ b/benchmarks/worker.py @@ -28,10 +28,11 @@ import time import traceback import warnings -from collections.abc import Iterator +from collections.abc import Callable, Iterator, Mapping from contextlib import contextmanager from pathlib import Path -from typing import TYPE_CHECKING, Any +from types import TracebackType +from typing import TYPE_CHECKING, Any, cast from benchmarks.records import ( Record, @@ -45,6 +46,7 @@ __all__ = [ "HOST_SPACES", "SNAPSHOT_CAPACITY", + "TIMING_BOUNDARY", "Diagnostics", "count", "emit", @@ -59,11 +61,13 @@ if TYPE_CHECKING: import numpy as np - from solprop.backends.protocol import Backend + from solprop.backends.protocol import Backend, ExecutionBackend + from solprop.backends.session import PreparedExecution, RunSession, Start from solprop.driver import Simulation from solprop.monitor import BoundaryMonitor from solprop.output.schema import FieldRetention, Output from solprop.translate.problem import PropagationProblem + from solprop.translate.run_request import RunRequest def emit(kind: str, **values: object) -> None: @@ -162,16 +166,18 @@ def records(self) -> list[Record]: ] -def source_calls(engine: Backend) -> int | None: - """Read the backend's source-evaluation ledger, or ``None`` if it has none.""" - metadata = engine.metadata() - value = metadata.get("source_evaluations") - if isinstance(value, int): - return value - ledger = metadata.get("response_calls") - if isinstance(ledger, dict): - return sum(int(ledger[key]) for key in ("startup", "predictor", "corrected")) - return None +def source_calls(record: Mapping[str, object], counter: str) -> int | None: + """Read an actual source counter from a session's execution record. + + A missing counter stays unavailable. The Adams ``response_calls`` ledger is + logical work and cannot substitute for actual invocations. + """ + value = record.get(counter) + if value is None: + return None + if not isinstance(value, int) or isinstance(value, bool) or value < 0: + raise SuiteError(f"invalid session source counter {counter}: {value!r}") + return value def integrator_label(integrator: object) -> str: @@ -193,49 +199,203 @@ def integrator_label(integrator: object) -> str: """Snapshot generations a repetition's store holds: every one a case asks for.""" -class _Loaded: - """Note when a run's session finishes loading its backend, and the counts then. +TIMING_BOUNDARY = "prepared.start.return.v1" +"""Propagation starts when the generic prepared execution returns its session.""" + - The run's session loads the launch inside ``run_problem`` (SEP 47), and the load - resets the backend's counters and masks and uploads the state. The timed window - and the counted evaluations start where they always did: once the state is - loaded, before the output opens and the launch plane is saved. Within the block - the backend's ``set_initial`` is wrapped to read the clock and the counter as it - returns; it is restored on exit. +class _Forward: + """Expose a live protocol member, including to runtime structural checks. - Attributes - ---------- - ended : int - ``time.perf_counter_ns()`` when the load returned. - calls : int or None - The backend's source evaluations just after the load (:func:`source_calls`). + ``__getattr__`` alone is invisible to runtime-checkable protocols. These + descriptors forward the original bound methods/properties without copying + mutable lifecycle facts or requiring writable attributes on the target. + Dynamic types are confined to these transparent benchmark proxies. """ - def __init__(self, engine: Backend) -> None: - self._engine = engine - self.ended = 0 - self.calls: int | None = None + def __set_name__(self, _owner: type, name: str) -> None: + self.name = name + + def __get__(self, instance: _Proxy | None, _owner: type | None = None) -> Any: + return self if instance is None else getattr(instance._target, self.name) + + +class _Proxy: + def __init__(self, target: object, timing: _Started) -> None: + self._target = target + self._timing = timing + + def __getattr__(self, name: str) -> Any: + # Optional session extensions, e.g. march_refusal, retain their semantics. + return getattr(self._target, name) + + @property + def __class__(self) -> type: + # The service loop still recognizes transitional sessions with isinstance. + # Preserve that existing path as well as the structural protocol surface. + return type(self._target) + + @__class__.setter + def __class__(self, _value: type) -> None: + raise SuiteError("a benchmark proxy cannot change its target's class") + + +class _Owner(_Proxy): + name = _Forward() + request = _Forward() + metadata = _Forward() + march_export_refusal = _Forward() + edge_memory = _Forward() + timing_probe = _Forward() + available_device_memory = _Forward() + memory_ledger = _Forward() + close = _Forward() + closed = _Forward() + start_group = _Forward() + + def prepare( + self, problem: PropagationProblem, request: RunRequest + ) -> PreparedExecution: + prepared = cast("ExecutionBackend", self._target).prepare(problem, request) + return cast("PreparedExecution", _Prepared(prepared, self._timing)) + + +class _Prepared(_Proxy): + backend = _Forward() + metadata = _Forward() + memory_ledger = _Forward() + close = _Forward() + + def start(self, start: Start, **keywords: Any) -> RunSession: + if self._timing.started_at is not None: + raise SuiteError("one timed run must start exactly one session") + session = cast("PreparedExecution", self._target).start(start, **keywords) + self._timing.started_at = time.perf_counter_ns() + wrapped = _Session(session, self._timing) + try: + self._timing.begin(session.execution_record()) + except BaseException: + # A returned session is owned even if reading its first record fails. + wrapped.close() + raise + return cast("RunSession", wrapped) + + +class _Session(_Proxy): + finished = _Forward() + closed = _Forward() + status = _Forward() + advance = _Forward() + acknowledge = _Forward() + export = _Forward() + noise_phase = _Forward() + request_snapshot = _Forward() + march_snapshot = _Forward() + march_snapshot_nbytes = _Forward() + march_export_refusal = _Forward() + execution_record = _Forward() + monitor_record = _Forward() + continue_monitor = _Forward() + undelivered = _Forward() + pending_ticket = _Forward() + + def _finish( + self, release: Callable[[], None], active: BaseException | None + ) -> None: + failure: BaseException | None = None + try: + if not self._timing.captured: + self._timing.end(cast("RunSession", self._target).execution_record()) + except BaseException as error: + failure = error + try: + release() + except BaseException as error: + if failure is None: + failure = error + else: + failure.add_note(f"session cleanup also failed: {error!r}") + if failure is not None: + if active is None: + raise failure + if failure is not active: + active.add_note( + f"benchmark session finalization also failed: {failure!r}" + ) + for note in getattr(failure, "__notes__", ()): + active.add_note(note) + + def close(self) -> None: + self._finish(cast("RunSession", self._target).close, sys.exception()) + + def __enter__(self) -> RunSession: + cast("RunSession", self._target).__enter__() + return cast("RunSession", self) + + def __exit__( + self, + kind: type[BaseException] | None, + error: BaseException | None, + trace: TracebackType | None, + ) -> None: + self._finish( + lambda: cast("RunSession", self._target).__exit__(kind, error, trace), error + ) + - def _load(self, *args: object, **keywords: object) -> None: - type(self._engine).set_initial(self._engine, *args, **keywords) # pyright: ignore[reportArgumentType] - self.calls = source_calls(self._engine) - self.ended = time.perf_counter_ns() +class _Started: + """Observe one generic start and its session counters without mutating either.""" + + def __init__(self, engine: ExecutionBackend) -> None: + self._engine = engine + self.started_at: int | None = None + self.counter: str | None = None + self.before: int | None = None + self.after: int | None = None + self.execution: Record = {} + self.captured = False + + @property + def engine(self) -> ExecutionBackend: + # Do not retain the proxy: it points back here, and a cycle would keep the + # underlying owner alive beyond the caller's explicit lifecycle. + return cast("ExecutionBackend", _Owner(self._engine, self)) + + def begin(self, record: Mapping[str, object]) -> None: + self.counter = next( + ( + name + for name in ("attempted_source_evaluations", "source_evaluations") + if record.get(name) is not None + ), + None, + ) + self.before = ( + None if self.counter is None else source_calls(record, self.counter) + ) - def __enter__(self) -> _Loaded: - self._engine.set_initial = self._load # type: ignore[method-assign] # pyright: ignore[reportAttributeAccessIssue] - return self + def end(self, record: Mapping[str, object]) -> None: + self.after = ( + None if self.counter is None else source_calls(record, self.counter) + ) + self.execution = metadata_value(dict(record)) + self.captured = True - def __exit__(self, kind: type[BaseException] | None, *rest: object) -> None: - del self._engine.set_initial # pyright: ignore[reportAttributeAccessIssue] - if kind is None and not self.ended: - msg = "the run never loaded its backend, so nothing was timed" - raise SuiteError(msg) + def evaluations(self) -> int | None: + if self.started_at is None: + raise SuiteError("the run never returned a session from prepared.start") + if not self.captured: + raise SuiteError("the run never closed its started session") + if self.before is None or self.after is None: + return None + if self.after < self.before: + raise SuiteError("the session's source counter decreased during the run") + return self.after - self.before def timed_run( # noqa: PLR0913 - the run and how it is observed simulation: Simulation, problem: PropagationProblem, - engine: Backend, + engine: ExecutionBackend, retention: FieldRetention, monitor: BoundaryMonitor | None = None, *, @@ -243,7 +403,11 @@ def timed_run( # noqa: PLR0913 - the run and how it is observed scratch: Path | None = None, snapshots: int | None = None, ) -> tuple[Record, np.ndarray | None]: - """Time one complete run from the launch; return its counts and final field. + """Time from generic ``prepared.start`` return through the run's close. + + ``wall_seconds`` additionally includes run preparation and session start. Both + source counter readings come from the same returned session; missing actual + counters stay unavailable. Historical builds without this start boundary refuse. `monitor` is a fresh boundary monitor, attached as ``Simulation.run`` attaches one; ``None`` runs without the boundary checks. `output` is ``"memory"`` or @@ -259,6 +423,11 @@ def timed_run( # noqa: PLR0913 - the run and how it is observed from solprop.output.hdf5 import HDF5Output, open_file # noqa: PLC0415 Start = _session_start() # noqa: N806 - the class, or None before SEP 47 + if Start is None: + raise SuiteError( + "benchmark timing requires prepared.start; this historical build " + "has no common session-start boundary" + ) if (output == "hdf5" or snapshots is not None) and scratch is None: raise SuiteError("a run to HDF5 or with snapshots needs a scratch directory") @@ -284,39 +453,32 @@ def timed_run( # noqa: PLR0913 - the run and how it is observed "snapshots": controller, "boundary_monitor": monitor, } + timing = _Started(engine) began = time.perf_counter_ns() - if Start is None: - # A build from before SEP 47's sessions: run_problem takes a loaded backend, - # so the load comes first and the window starts after it, as it did then. - engine.set_initial(problem.initial.field0, None, z=problem.initial.z) - before = source_calls(engine) - loaded_at = time.perf_counter_ns() - run_problem(problem, engine, handler, **observed) - else: - loaded = _Loaded(engine) - with loaded: - run_problem( - problem, engine, handler, start=Start.entrance(problem), **observed - ) - before, loaded_at = loaded.calls, loaded.ended + run_problem( + problem, timing.engine, handler, start=Start.entrance(problem), **observed + ) ended = time.perf_counter_ns() - seconds = (ended - loaded_at) * 1e-9 - after = source_calls(engine) + evaluations = timing.evaluations() + assert timing.started_at is not None # evaluations validates the required boundary + seconds = (ended - timing.started_at) * 1e-9 if isinstance(handler, HDF5Output) and path is not None: handler = open_file(path) try: accepted = np.asarray(handler["step_history/accepted"], dtype=bool) record: Record = { "seconds": seconds, + "timing_boundary": TIMING_BOUNDARY, "accepted": int(accepted.sum()), "rejected": int((~accepted).sum()), - "source_evaluations": None - if before is None or after is None - else after - before, + "source_evaluations": evaluations, + "source_counter": timing.counter, + "source_evaluations_before": timing.before, + "source_evaluations_after": timing.after, + "execution": timing.execution, "z": float(handler["z"][-1]), "planes": handler.n_saved, - # The whole run_problem call, the load and any session preparation - # before it included, for an end-to-end comparison across the change. + # The whole run_problem call, including its preparation and start. "wall_seconds": (ended - began) * 1e-9, "rows": _periodic_rows(handler), } @@ -439,7 +601,7 @@ def _repetition( configuration: Record, simulation: Simulation, problem: PropagationProblem, - engine: Backend | None, + engine: ExecutionBackend | None, retention: FieldRetention | None, scratch: Path, ) -> tuple[Record, np.ndarray | None]: @@ -472,7 +634,13 @@ def _repetition( case.workload, simulation, scratch, configuration["fields"] ) seconds = (time.perf_counter_ns() - started) * 1e-9 - return {"seconds": seconds, "source_evaluations": None, **record}, final + return { + "seconds": seconds, + "wall_seconds": seconds, + "timing_boundary": "workload.call.v1", + "source_evaluations": None, + **record, + }, final finally: shutil.rmtree(scratch, ignore_errors=True) @@ -481,7 +649,7 @@ def _counted( configuration: Record, simulation: Simulation, problem: PropagationProblem, - engine: Backend | None, + engine: ExecutionBackend | None, retention: FieldRetention | None, root: Path, ) -> Record: @@ -500,7 +668,7 @@ def _warm( configuration: Record, simulation: Simulation, problem: PropagationProblem, - engine: Backend | None, + engine: ExecutionBackend | None, retention: FieldRetention | None, root: Path, ) -> float: @@ -517,7 +685,9 @@ def _warm( return time.perf_counter() - started -def warm_up(engine: Backend, problem: PropagationProblem, until: float) -> None: +def warm_up( + engine: ExecutionBackend, problem: PropagationProblem, until: float +) -> None: """Warm a backend up, untimed, through a session from the problem's launch. The session observes the launch plane, with its statistics and its field, so that @@ -529,11 +699,12 @@ def warm_up(engine: Backend, problem: PropagationProblem, until: float) -> None: Start = _session_start() # noqa: N806 - the class, or None before SEP 47 if Start is None: # Before SEP 47: load, march and observe the backend directly. - engine.set_initial(problem.initial.field0, None, z=problem.initial.z) + driver = cast("Backend", engine) + driver.set_initial(problem.initial.field0, None, z=problem.initial.z) if until > problem.initial.z: - engine.propagate_to(until) - engine.observe(field=True) - engine.stats(_before_request(problem).stats_spec) + driver.propagate_to(until) + driver.observe(field=True) + driver.stats(_before_request(problem).stats_spec) return from solprop.backends.events import ObservationReady # noqa: PLC0415 from solprop.backends.export import ExportRecipe # noqa: PLC0415 @@ -577,6 +748,22 @@ def _repeat_difference(finals: list[np.ndarray]) -> float | None: return max(float(np.linalg.norm(final - finals[0])) / scale for final in finals) +def _prepared_runtime(engine: ExecutionBackend | None) -> Record: + """Read effective ownership and loaded-pool facts after numerical preparation. + + The initial provenance event intentionally imports no optional execution runtime. + A session-only owner may load its runtime, provider and thread pools during + preparation, so those actual facts need a later, separately labelled snapshot. + Per-session execution records additionally carry their plans and counters. + """ + from threadpoolctl import threadpool_info # noqa: PLC0415 + + return { + "execution": None if engine is None else metadata_value(engine.metadata()), + "libraries": threadpool_info(), + } + + def measure( configuration: Record, repeats: int, @@ -659,6 +846,7 @@ def measure( warmup = _warm( configuration, simulation, problem, engine, retention, root / "warm" ) + prepared_runtime = _prepared_runtime(engine) free_warm = _device_free(configuration) repetitions = [] finals = [] @@ -692,6 +880,7 @@ def measure( # Another workload constructs its backends inside each repetition. "backend_seconds": backend_seconds, "warmup_seconds": warmup, + "prepared_runtime": prepared_runtime, "repetitions": repetitions, "peak_rss_bytes": peak_rss(), # The run's workspace stays allocated, so the drop in free memory from diff --git a/changelog.d/737-power-log-roundoff.fixed.md b/changelog.d/737-power-log-roundoff.fixed.md new file mode 100644 index 000000000..91bb3a5a7 --- /dev/null +++ b/changelog.d/737-power-log-roundoff.fixed.md @@ -0,0 +1,4 @@ +Preserve small refractivity changes in the logarithmic modal power conversion. Short +entrance windows of a helium pressure gradient now use the mode's cancellation-free +refractivity with `log1p`, avoiding a spurious unresolved endpoint expansion without +relaxing its interpolation tolerance ([#737](https://github.com/LupoLab/solprop/issues/737)). diff --git a/changelog.d/dense-request-admission.fixed.md b/changelog.d/dense-request-admission.fixed.md new file mode 100644 index 000000000..b79fd2267 --- /dev/null +++ b/changelog.d/dense-request-admission.fixed.md @@ -0,0 +1,3 @@ +Recheck dense-output exclusions when preparing an adapted run request: a split +temporal collar, coupled flow or modified noise now refuses before session allocation, +as it already did during initial assembly (#682). diff --git a/changelog.d/julia-blas.added.md b/changelog.d/julia-blas.added.md new file mode 100644 index 000000000..a3be7d3ac --- /dev/null +++ b/changelog.d/julia-blas.added.md @@ -0,0 +1,3 @@ +Share controllable host BLAS limits across Julia preparation and host-construction +lifetimes. Record actual widths and restore them only after the last owner releases +the library, including interrupted or abandoned Julia preparations. diff --git a/changelog.d/julia-dense-periodic.fixed.md b/changelog.d/julia-dense-periodic.fixed.md new file mode 100644 index 000000000..b0f0ab84f --- /dev/null +++ b/changelog.d/julia-dense-periodic.fixed.md @@ -0,0 +1,3 @@ +Keep Julia dense-output periodic rows in the same delivery chunk as their accepted +attempt. Endpoint statistics are sampled before an interior plane can drain that +attempt; owed planes still precede snapshots and further trials (#687). diff --git a/changelog.d/julia-df32-adams.added.md b/changelog.d/julia-df32-adams.added.md new file mode 100644 index 000000000..fec35fc48 --- /dev/null +++ b/changelog.d/julia-df32-adams.added.md @@ -0,0 +1,5 @@ +Add internal CPU DF32 exponential Adams sessions with certified complete factors, +selected portable-history binding and explicit field-reset reasons, under +[SEP 48](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/sep-0048-julia-backend.md). +Completed restarts preserve raw history without another source evaluation. Public +binary32 and device admission remain unavailable while qualification continues. diff --git a/changelog.d/julia-linear-flow-alias.fixed.md b/changelog.d/julia-linear-flow-alias.fixed.md new file mode 100644 index 000000000..73cd62907 --- /dev/null +++ b/changelog.d/julia-linear-flow-alias.fixed.md @@ -0,0 +1,4 @@ +The optional Julia engine now refuses linear-flow and propagator buffers that overlap +through foreign array headers or alias retained preparation storage, before modifying +either input or output. Independent in-place and strided outputs remain supported +([#691](https://github.com/LupoLab/solprop/issues/691)). diff --git a/changelog.d/julia-preparation.added.md b/changelog.d/julia-preparation.added.md new file mode 100644 index 000000000..8aff2d732 --- /dev/null +++ b/changelog.d/julia-preparation.added.md @@ -0,0 +1,17 @@ +Attach binary64 Julia transverse monitoring to the session event contract, preserving +original noise-floor references and the first explicitly supplied continuation. +Face-stop messages retain the actual earlier warning coordinate +([#692](https://github.com/LupoLab/solprop/issues/692), +[#693](https://github.com/LupoLab/solprop/issues/693)). + +Keep measured CPU FFTW plans under verified Julia/library/machine identities, refresh +offers for each start and include Julia plans in calibration clearing. Failed cache +writes preserve usable numerical preparation; unexpected adoption failures release +their owners ([#694](https://github.com/LupoLab/solprop/issues/694), +[#695](https://github.com/LupoLab/solprop/issues/695)). + +Add Julia-owned timing probes for estimates without a propagation session. Closing +the execution owner closes its probes; cleanup preserves the initiating failure +([#696](https://github.com/LupoLab/solprop/issues/696)). These remain internal +integration milestones of [SEP 48](docs/dev/seps/sep-0048-julia-backend.md), with public +selection and broader precision/device qualification still in progress. diff --git a/changelog.d/julia-reached-planes.fixed.md b/changelog.d/julia-reached-planes.fixed.md new file mode 100644 index 000000000..c15fb9edb --- /dev/null +++ b/changelog.d/julia-reached-planes.fixed.md @@ -0,0 +1,4 @@ +Deliver Julia save planes that are already reached under the landing tolerance before +snapshots or another numerical trial, without repeating endpoint services. Adjacent +requested planes retain separate indices and receipts +([#679](https://github.com/LupoLab/solprop/issues/679)). diff --git a/changelog.d/julia-spatial.added.md b/changelog.d/julia-spatial.added.md new file mode 100644 index 000000000..00d98e7bd --- /dev/null +++ b/changelog.d/julia-spatial.added.md @@ -0,0 +1,4 @@ +Attach scalar radial, Cartesian and line binary64 Julia sessions, including physical +transverse absorption, flux statistics and spatial exports, under SEP 48. Julia owns +their numerical work and retains request-specific observation storage. Binary32, +device and complete transverse-monitor qualification remain in progress. diff --git a/changelog.d/julia-split-dense.added.md b/changelog.d/julia-split-dense.added.md new file mode 100644 index 000000000..0ba5c25bd --- /dev/null +++ b/changelog.d/julia-split-dense.added.md @@ -0,0 +1,3 @@ +Add scalar modal binary64 Julia split temporal absorption and adaptive DOPRI5 dense +observations under SEP 48. Split finishing runs without statistics or monitoring; +dense exports, snapshots and periodic rows follow the shared session contract. diff --git a/changelog.d/native-group-driver-contract.fixed.md b/changelog.d/native-group-driver-contract.fixed.md new file mode 100644 index 000000000..8f025cf23 --- /dev/null +++ b/changelog.d/native-group-driver-contract.fixed.md @@ -0,0 +1,2 @@ +Validate the native adapter's `start_group` dependency as part of its driver contract, +so an incompatible solprop installation is refused by name ([#654](https://github.com/LupoLab/solprop/issues/654)). diff --git a/changelog.d/sep-0048-blas-rollback.fixed.md b/changelog.d/sep-0048-blas-rollback.fixed.md new file mode 100644 index 000000000..98ed0d3fb --- /dev/null +++ b/changelog.d/sep-0048-blas-rollback.fixed.md @@ -0,0 +1,4 @@ +Preserve the initiating error and retain a retry owner when acquiring host BLAS limits +and rolling them back both fail. A later acquisition on the same thread restores the +pending request before applying new limits, preventing a permanently orphaned width +or Accelerate mode ([#697](https://github.com/LupoLab/solprop/issues/697)). diff --git a/changelog.d/sep-0048-default-statistics.added.md b/changelog.d/sep-0048-default-statistics.added.md new file mode 100644 index 000000000..de2601326 --- /dev/null +++ b/changelog.d/sep-0048-default-statistics.added.md @@ -0,0 +1,5 @@ +Julia CPU runs support the default field-plasma integration diagnostics and complete +species density, peak-rate and final ionised-inventory statistics. Diagnostics combine +global maxima across channels and chunks; inventory retains physical transverse +measure and preionisation. Plane-only cadence and passive species are preserved +(SEP 48, #702). diff --git a/changelog.d/sep-0048-device-controls.added.md b/changelog.d/sep-0048-device-controls.added.md new file mode 100644 index 000000000..463aceb88 --- /dev/null +++ b/changelog.d/sep-0048-device-controls.added.md @@ -0,0 +1,6 @@ +Add per-run `SimulationSettings.device` execution selection and forward it through +recipes, runners and spawned scan builders. Native choices must match the installed +build; NumPy and the currently qualified Julia backend accept CPU only. Keep device +and backend options outside scientific and restart identities, preserve recipe +execution options in Python export, and rebuild reused runners when execution choices +change (SEP 48; #703, #705). diff --git a/changelog.d/sep-0048-flow-tables.added.md b/changelog.d/sep-0048-flow-tables.added.md new file mode 100644 index 000000000..f450d80da --- /dev/null +++ b/changelog.d/sep-0048-flow-tables.added.md @@ -0,0 +1,5 @@ +Julia low-storage runs support session-owned propagator tables with exact interval +keys. Automatic selection tabulates constant operators; execution metadata records +the effective choice. Other integrator families retain recomputation. This completes +the cached-flow path needed by the standard short-window benchmark cases (#704), +as part of SEP 48. diff --git a/changelog.d/sep-0048-julia.added.md b/changelog.d/sep-0048-julia.added.md new file mode 100644 index 000000000..e57d7cd16 --- /dev/null +++ b/changelog.d/sep-0048-julia.added.md @@ -0,0 +1,88 @@ +Add explicit setup and status commands for the optional Julia engine, with pinned bridge +versions, immutable source copies and verified offline artifact inventories, as part of +[SEP 48](docs/dev/seps/sep-0048-julia-backend.md). Its numerical sessions and device +qualification remain in progress on the implementation branch. + +Enable `backend="julia"` for the admitted binary64 CPU routes. Node budgets account +for source and observation array payloads together, bind to each actual run request, +and report their fixed-storage and opaque-plan exclusions explicitly. Prepared requests +share immutable numerical data while retaining independent chunk capacities. + +Evaluate the four resolved-modal on-axis plasma statistics from independent fine-grid +observations, retaining both real field components and refusing nonproportional +envelope axis maps. Add physical energy, analytic flux and spectral flux for constant +unit modal power weights. Foreign array overlaps are refused before any observation +or reduction writes ([#713](https://github.com/LupoLab/solprop/issues/713)). + +Use the common `prepared.start` return boundary for ordinary benchmark repetitions +on every execution owner, with an explicit timing-boundary identifier and separate +preparation-inclusive wall time. Actual source counters come from the same session; +logical-only counts remain unavailable as invocation measurements. + +Add owned `SimulationSettings.backend_options`, forwarded through execution options +and spawned workers without changing scientific hashes. Backends refuse unsupported +option keys before workspace construction. + +Backend selection now exposes session ownership independently of the legacy numerical +operation surface. Single runs and fixed-schedule groups use their backend's own +factories, so the optional Julia adapter can keep all numerical marching in Julia. +Failed group construction preserves entrance fields and caller-owned backends for +retry ([#623](https://github.com/LupoLab/solprop/issues/623)). + +Julia fixed-schedule groups now keep member scheduling in Julia and publish complete +common windows through the shared service interface. Interrupted construction preserves +the original starts; failed publication retains chunks for retry without repeating +numerical work. Stops and failures preserve actual member positions and one shared +primary error. Mixed Runge–Kutta tableaux refuse before consuming starts +([#676](https://github.com/LupoLab/solprop/issues/676), +[#677](https://github.com/LupoLab/solprop/issues/677)). + +The binary64 Julia session runs scalar modal fields and envelopes through the +shared event and output services, with adaptive or fixed Runge–Kutta and landed +exponential Adams stepping, +bounded attempt delivery, cooperative stops, snapshots and validated destination +exports. Kerr, Raman and plasma responses retain independent represented profiles; +operators, prefactors and power weights support constant, table and expansion forms. +The source owns bounded node scratch and refuses overlapping caller buffers before +numerical writes. Broader route, method, observation and device support remains under +implementation. + +Scalar modal plane and periodic statistics execute inside Julia, with request-owned +catalogues, profile tables and windows. Event copies are transactional, preserve rows +after cleanup and retry undelivered chunks without numerical replay. Missing embedded +quadrature diagnostics remain NaN; closed sessions release their request preparation +([#653](https://github.com/LupoLab/solprop/issues/653), +[#662](https://github.com/LupoLab/solprop/issues/662)). + +Julia also owns temporal monitoring and its warning and stop decisions. Closed +events carry detached records; failed copies can retry without duplicating rows. +Resumed runs retain the original launch, removal totals and monitor history, with +the first supplied continuation taking precedence over an output-record fallback. + +Binary64 Julia input-noise sessions add the selected per-start draw only at a fresh +launch, retain it for resumed monitor floors, and export detached cumulative phase +arrays at the selected observation coordinate. Modified and binary32 noise remain +refused. Draw application protects the active-mask storage before any candidate write +([#678](https://github.com/LupoLab/solprop/issues/678)). +Field and phase caches retain their original ticket and owner across Python callbacks, +so a completed copy cannot repopulate a replacement or closed session +([#680](https://github.com/LupoLab/solprop/issues/680)). + +Adams preserves shared control policy, exact logical budget charges, actual source-call +counts and compact accepted-order records across event yields and resumes. Portable +binary64 snapshots transfer raw accepted state and full history stores losslessly; +compatible Julia/NumPy/native CPU continuation adds no startup charge. Field-only resets preserve +cumulative budgets and record incompatible history explicitly. The remaining restart +and device qualification matrix is still in progress. +Adaptive Adams dense planes retain their own selected field and coordinate while the +committed march remains ahead. Power conversion and statistics use the observation +coordinate; interior fields refuse future endpoint history, and snapshots wait for +all owed planes before copying a committed checkpoint. +Cumulative counters refuse before overflow or unrecordable work, preserving their +saved values ([#658](https://github.com/LupoLab/solprop/issues/658)). + +The fixed low-storage RK4IP session owns its register updates and prescribed itinerary. +Its record separates attempted from committed source calls, and in-flight failures +poison the field without discarding actual work counts. Matched-history RK and Adams +comparisons use checked discrete-stage and retained-source bounds, including the effect +of windowing ([#656](https://github.com/LupoLab/solprop/issues/656)). diff --git a/coverage-cpu.ini b/coverage-cpu.ini index 11f8aa59f..06f8d38de 100644 --- a/coverage-cpu.ini +++ b/coverage-cpu.ini @@ -7,6 +7,9 @@ [run] source = solprop branch = True +# SEP 48: the optional Tier 3 Julia adapter has its own runtime/device lane; +# every other solprop module retains the required 100% statement/branch gate. +omit = */solprop/backends/julia/* [report] fail_under = 100 diff --git a/docs/api/index.md b/docs/api/index.md index 1d16c8c03..7a243859f 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -84,6 +84,7 @@ species tabulated scans transport +julia ``` ## Complete generated reference diff --git a/docs/api/julia.md b/docs/api/julia.md new file mode 100644 index 000000000..8ee8f8af9 --- /dev/null +++ b/docs/api/julia.md @@ -0,0 +1,18 @@ +# Julia setup and status + +The optional backend's [setup manual](../guide/performance/julia.md) describes installation, +published identities and runtime limitations. These Python functions expose the same +explicit setup and filesystem-only inspection as `solprop julia setup` and +`solprop julia status`. Importing this interface does not initialize Julia. + +```{eval-rst} +.. autofunction:: solprop.backends.julia.setup + +.. autofunction:: solprop.backends.julia.status + +.. autofunction:: solprop.backends.julia.select_setup + +.. autoclass:: solprop.backends.julia.SetupRecord + +.. autoclass:: solprop.backends.julia.SetupStatus +``` diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md index 5c39df0e2..cb3d6dc03 100644 --- a/docs/dev/architecture.md +++ b/docs/dev/architecture.md @@ -220,6 +220,7 @@ against `src/solprop` by `tests/test_structure_figures.py`. | `translate/` | Validated `PropagationProblem` and its route union (`translate/routes.py`); parameter expansions and z tables; modal/radial/Cartesian transforms and the hybrid planar one (slab modes in x × FFT in y, `translate/planar.py`); dense tracked modal tables, the general modal route and the coupled-flow and metric records (`translate/general.py`, `translate/coupled.py`); the spatial plane measure (`translate/flux.py`, the `FluxPlan` of schema 35); the persisted frame integral and the filled input port of a problem's entrance (`translate/coupling.py`); response tables, masks and stage bundles | T | | `backends/` | Registry and protocols, shared step and batch drivers, scalar bodies, spatial and population statistics | B | | `backends/numpy_ref/` | Reference execution | B | +| `backends/julia/` | Optional Julia setup, owned descriptor lowering and session adapter; Julia owns numerical marching and buffers (SEP 48 implementation in progress) | B | | `backends/host/` | The reference's own step driver, Adams and low-storage marches, fixed-schedule group and run session ([SEP 47](seps/sep-0047-run-ownership.md) phase 2); the inherited drivers in `backends/` remain the native bridge's until its session replaces them | B | | `stepper/`, `log.py`, `stats.py` | Tableaux, controllers, schedules, progress reporters and statistics specifications | D | | `driver/`, `driver/executors/`, `scan.py` | Simulation and convenience interfaces, scan/batch orchestration, Local/Pool/Queue/Slurm execution and scan CLI | D | @@ -228,6 +229,11 @@ against `src/solprop` by `tests/test_structure_figures.py`. | `processing/`, `plotting/`, `sol.py` | Field, spectrum, time, coherence, compression, mixture and scan analysis; a saved plane read back as a field plane or a fluence map (`processing/planes.py`), and a field plane's file form (`processing/plane_file.py`); propagation/statistics plots and spectrograms; the interactive session namespace, the one module whose import has side effects | X | | `service/` | Front-end support, above every other layer: the messages between a front end and solprop, the kernel process that answers a front end's checks, previews and readings of a results file as plain data, each run as a job that keeps its record in its folder, and the helper and connection that reach a machine's runs over SSH ([the front end's design](gui/design.md), sections 13.3 and 13.4). Not part of the user API and outside the stability promise; nothing else in solprop imports it | X | +CLI argument registration uses standard-library-only helpers, including +`_julia_cli.py`; an unrelated help or calibration command does not import the +backend package or numerical libraries. Julia setup/status implementation is imported +only when the dispatcher executes that command. + `solprop-native` is the backend's second distribution, built from `native/` in this repository at solprop's own version, and a required dependency of solprop pinned to that version ([SEP 43](seps/archive/sep-0043-retire-numba-cpu.md)). It depends on the seam, diff --git a/docs/dev/backends.md b/docs/dev/backends.md index ec143d664..a55752a62 100644 --- a/docs/dev/backends.md +++ b/docs/dev/backends.md @@ -27,13 +27,27 @@ stay distinct, and the registry finds the processor baseline out by running the package's own pure-Python check by path, without importing the package. This selection policy changes no kernel-contract member (ADR-029). -The protocol is drawn at the level of operations on the state, because an `xp`-style abstraction over +The production selection returns an `ExecutionBackend`: an owner of prepared resources, +execution metadata and resource accounting. Single runs use +`owner.prepare(problem, request).start(start, ...)`; groups use +`owner.start_group(members, problems, requests, starts, ...)`. Each backend chooses its +own session and group implementation. The shared dispatcher contains no backend-name +branch and never invokes legacy numerical operations on a new session backend. + +`Backend` extends this ownership protocol with the legacy numerical operations used +by the NumPy reference and transitional native adapters. A Julia execution owner does +not implement placeholder `set_initial`, `propagate_to`, `observe` or `stats` methods. +Its session owns the numerical state and returns the events the service loop handles. +Native's group factory retains its existing native-session admission and transitional +fallback; that choice belongs to native, alongside its single-session factory. + +The legacy protocol is drawn at the level of operations on the state, because an `xp`-style abstraction over `numpy`/`jax.numpy`/`cupy` would force every backend to keep the array compiler's structure (out-of-place transforms, separate scaling passes, materialised stages, one reduction per statistic), and that structure is precisely what a fast backend exists to change. ```python -class Backend(Protocol): +class Backend(ExecutionBackend, Protocol): name: str max_batch: int # 1 for backends that step one problem reads_transverse_edge: bool # whether a requested real-space collar can run on it diff --git a/docs/dev/benchmarking.md b/docs/dev/benchmarking.md index cd5a1791f..7d2709e63 100644 --- a/docs/dev/benchmarking.md +++ b/docs/dev/benchmarking.md @@ -62,6 +62,30 @@ pools are set in the environment before any scientific import. The worker: so it includes the plane observations, the statistics and the boundary checks: what a user's run costs. +Ordinary single-run repetitions record +`timing_boundary="prepared.start.return.v1"`. Their `seconds` window starts immediately +after `backend.prepare(problem, request).start(...)` returns and ends when +`run_problem(...)` returns. It includes launch and subsequent event servicing, +observations, statistics, boundary checks, exports, output and session closure, plus +the harness's initial and final execution-record reads. Preparation, launch loading +and other work performed before the prepared start returns are outside this window. +`wall_seconds` separately spans the entire `run_problem(...)` call, including preparation +and start. Construction, translation, backend construction and warm-up remain separate. + +Reference, native and Julia CPU owners use this same protocol boundary; the harness +no longer wraps legacy `set_initial`. Historical builds without prepared sessions +refuse this timing mode. Records from the earlier load boundary use a different timing +window. Repeated-input, scan and group workloads retain their whole-workload window, +identified as `workload.call.v1`. + +Source-call evidence reads one actual counter before and after the same session. +It prefers attempted invocations where low-storage sessions distinguish them from +committed calls. Missing actual counters remain unavailable; Adams's logical +`response_calls` ledger stays in metadata and does not stand in for invocations. +Initial provenance stays lazy. A separate `prepared_runtime` snapshot and each +repetition's final `execution` record retain the effective setup, provider, threads +and plans available after preparation. + The result is the median of the repeats, with the minimum and maximum beside it, the accepted and rejected steps, the source evaluations, the peak resident memory, and the integrator and tolerances the run actually used. Repeats of one configuration take the diff --git a/docs/dev/benchmarks.md b/docs/dev/benchmarks.md index db95096f4..424e785b0 100644 --- a/docs/dev/benchmarks.md +++ b/docs/dev/benchmarks.md @@ -3384,6 +3384,174 @@ RDW and argon directions. No shared dimension threshold or pool policy is change explicit overrides and global caps retain their existing semantics. A 36-core sizing confirmation is unnecessary because no sizing change is retained. +## Julia CPU entrance windows: initial partial campaign + +On 2026-11-11, SEP 48 source `08721c9d` compared the native and Julia CPU backends +on an exclusively allocated AMD EPYC 7763. One physical processor supplied 64 cores, +placed in contiguous core order across its four NUMA domains; the serial comparison +used one thread. Both backends used the same source tree and Python environment. +The native build used GCC 16.2, `x86-64-v3`, FFTW 3.3.11 and OpenBLAS 0.3.34. +Julia 1.13.3 used its generic CPU target and JuliaCall/PythonCall 0.9.37. Python was +3.14.6, NumPy 2.5.2 and SciPy 1.18.1. BLAS pools were limited to one thread; +calibration was off and FFT planning used `estimate`. + +The command was `python -m benchmarks ab --set tracking --threads 1,production +--production 64 --length 0.001 --rounds 3 --repeats 3 --calibrate none`, with native +as baseline and Julia as candidate. Each arm used the same interpreter. These are +entrance windows, not full propagation timings. The two completed cases each took +11 accepted steps and no rejected steps; the soliton ended at 0.0013278075458959399 m +and Raman/shock at 0.00015 m. Native used 67 source evaluations per window and Julia +77, so matching step counts do not imply matching source work. Endpoint-source +reuse is tracked in [#711](https://github.com/LupoLab/solprop/issues/711). + +| Case | Threads | Native window, s | Julia window, s | Julia/native | Native wall, s | Julia wall, s | +|---|---:|---:|---:|---:|---:|---:| +| GNLSE soliton | 1 | 0.017639 | 0.036531 | 2.086 | 0.018028 | 0.053706 | +| GNLSE Raman/shock | 1 | 0.106808 | 0.243718 | 2.281 | 0.107722 | 0.296913 | +| GNLSE soliton | 64 | 0.018020 | 0.038453 | 2.129 | 0.018439 | 0.054802 | +| GNLSE Raman/shock | 64 | 0.075261 | 0.186809 | 2.483 | 0.076340 | 0.249715 | + +Times are medians of the three round medians, each with three repetitions; ratios +are medians of paired round ratios. The narrower window starts after session +preparation, whereas `wall_seconds` includes preparation for that run. Neither +includes the benchmark worker's first warmup. Julia's first soliton warmup took +78.86 s; subsequent fresh-worker warmups for these cases took 24.24–28.09 s. These +combined warmups are not an isolated measurement of runtime initialization or +compilation. Managed CPU setup took 142.12 s with a populated dependency depot, +whose resulting total size was 2,114,060 KiB; this is not a clean-install download +size. The harness reported no busy samples. + +The other plasma windows refused the missing default statistics tracked in +[#702](https://github.com/LupoLab/solprop/issues/702), and both Kerr-beam windows +refused propagator tables tracked in +[#704](https://github.com/LupoLab/solprop/issues/704). The general-modal GRIN case +refused its explicitly unsupported route. These failures are retained and the +campaign exits unsuccessfully. The completion fixes require a new campaign with +the original settings. These four comparisons establish neither complete CPU +qualification nor a performance conclusion for other problems or devices. + +## Julia CPU entrance windows: complete preliminary matrix + +On 2026-11-11, source `5fc63437537c21efcffc128fbbdca6887918019a` repeated the +CPU comparison after the missing-statistics and propagator-table fixes. Hardware, +physical-core placement, toolchains, BLAS limits and planning settings match the +preceding partial campaign. The same tracking entrance-window command selected the +12 admitted cases, excluding only the general-modal GRIN route's named refusal. +There are 24 configurations: one thread and a 64-core budget, each with three paired +rounds and three repetitions per arm. The reported budget is a maximum; it does not +mean every kernel or FFT uses all those threads. + +| Case | Budget | Native window, s | Julia window, s | Julia/native | Paired range | Native wall, s | Julia wall, s | +|---|---:|---:|---:|---:|---:|---:|---:| +| `argon_blueshift` | 1 | 0.085465 | 0.537911 | 6.292 | 6.248–6.327 | 0.086601 | 0.799895 | +| `argon_blueshift` | 64 | 0.030964 | 0.082478 | 2.679 | 2.578–2.761 | 0.032053 | 0.285441 | +| `argon_blueshift_averaged` | 1 | 0.020565 | 0.046641 | 2.268 | 2.251–2.292 | 0.021653 | 0.271889 | +| `argon_blueshift_averaged` | 64 | 0.020110 | 0.042976 | 2.149 | 2.117–2.155 | 0.021199 | 0.212028 | +| `argon_blueshift_envelope` | 1 | 0.017380 | 0.036921 | 2.124 | 2.118–2.138 | 0.018426 | 0.161491 | +| `argon_blueshift_envelope` | 64 | 0.018458 | 0.027130 | 1.475 | 1.470–1.483 | 0.019545 | 0.174185 | +| `ctc` | 1 | 0.508556 | 2.980813 | 5.824 | 5.788–5.903 | 0.510720 | 3.331174 | +| `ctc` | 64 | 0.620764 | 0.673524 | 1.083 | 1.074–1.094 | 0.627335 | 1.017897 | +| `gnlse_raman_shock` | 1 | 0.107923 | 0.241130 | 2.246 | 2.234–2.247 | 0.108834 | 0.374934 | +| `gnlse_raman_shock` | 64 | 0.076223 | 0.188322 | 2.475 | 2.411–2.524 | 0.077345 | 0.233165 | +| `gnlse_soliton` | 1 | 0.017719 | 0.036907 | 2.078 | 2.063–2.093 | 0.018136 | 0.054434 | +| `gnlse_soliton` | 64 | 0.018019 | 0.038132 | 2.116 | 2.021–2.210 | 0.018406 | 0.056144 | +| `h2_raman_averaged` | 1 | 0.028172 | 0.076353 | 2.711 | 2.699–2.720 | 0.029242 | 0.299173 | +| `h2_raman_averaged` | 64 | 0.027105 | 0.049977 | 1.861 | 1.659–2.166 | 0.028117 | 0.339609 | +| `he_rdw_averaged` | 1 | 0.028725 | 0.063802 | 2.221 | 2.209–2.228 | 0.030023 | 0.278600 | +| `he_rdw_averaged` | 64 | 0.026436 | 0.051773 | 1.968 | 1.937–1.985 | 0.027721 | 0.309934 | +| `kerr_beam_192` | 1 | 4.304301 | 9.748890 | 2.271 | 2.248–2.487 | 4.372070 | 12.768153 | +| `kerr_beam_192` | 64 | 0.404335 | 5.171880 | 13.067 | 10.488–13.102 | 0.411927 | 7.920632 | +| `kerr_beam_384` | 1 | 44.239090 | 76.840021 | 1.737 | 1.736–1.748 | 44.832512 | 92.826727 | +| `kerr_beam_384` | 64 | 2.165997 | 44.918612 | 20.630 | 20.275–21.446 | 2.223893 | 60.633271 | +| `radial_filament_256` | 1 | 1.027121 | 34.292459 | 32.985 | 32.895–33.877 | 1.028677 | 34.789658 | +| `radial_filament_256` | 64 | 3.965175 | 1.478619 | 0.374 | 0.341–0.392 | 3.981603 | 1.902705 | +| `rdw` | 1 | 0.165777 | 1.183254 | 7.121 | 7.066–7.160 | 0.168346 | 1.534540 | +| `rdw` | 64 | 0.330032 | 0.161092 | 0.488 | 0.486–0.497 | 0.334924 | 0.465325 | + +Times are medians of round medians; each round median contains three repetitions. +Ratios and their ranges use paired round ratios, so the median ratio need not equal +the quotient of the displayed median times. `wall_seconds` includes preparation for +the run; neither window includes the worker's first warmup. Julia's combined +fresh-worker warmups range from 24.88 to 110.52 s across these cases. They combine +runtime entry, compilation and an initial propagation, and are not isolated startup +or compilation measurements. Setup took 132.20 s with an existing dependency depot; +the populated depot then occupied 2,281,236 KiB. This is not a fresh download size. + +| Case | End position, m | Accepted / rejected | Source evaluations, native / Julia | +|---|---:|---:|---:| +| `argon_blueshift` | 0.0002 | 17 / 2 | unavailable / 20 | +| `argon_blueshift_averaged` | 0.0002 | 17 / 2 | unavailable / 20 | +| `argon_blueshift_envelope` | 0.0002 | 11 / 0 | unavailable / 12 | +| `ctc` | 0.00013 | 16 / 2 | unavailable / 19 | +| `gnlse_raman_shock` | 0.00015 | 11 / 0 | 67 / 77 | +| `gnlse_soliton` | 0.001327807546 | 11 / 0 | 67 / 77 | +| `h2_raman_averaged` | 0.0004 | 25 / 2 | unavailable / 28 | +| `he_rdw_averaged` | 0.0015 | 14 / 1 | unavailable / 16 | +| `kerr_beam_192` | 2e-09 | 1 / 0 | 4 / 4 | +| `kerr_beam_384` | 2e-09 | 1 / 0 | 4 / 4 | +| `radial_filament_256` | 3e-05 | 12 / 0 | unavailable / 13 | +| `rdw` | 0.0015 | 14 / 1 | unavailable / 16 | + +All 432 timed repetitions are finite; the harness records no busy samples. Each +configuration has matching accepted/rejected counts across both arms, but native +source counters are unavailable for the Adams cases. The saved round-zero final +fields differ by relative L2 norms from 3.16e-17 to 1.27e-15. These are measured +comparisons, not a replacement for converged-reference qualification. The soliton +and Raman/shock source-count difference remains the endpoint-reuse work in +[#711](https://github.com/LupoLab/solprop/issues/711). + +The full campaign reached its external deadline with three third-round pairs +unfinished. Its exit status remains 124. A bounded continuation on the same physical +allocation, source, environment and placement reran only those three pairs (RDW, +helium averaged RDW and argon averaged blueshift, all at budget 64). The continuation +finished successfully in 613.56 s. The combined result retains 138 original complete +arm samples and six continuation samples; partial original pairs are preserved +separately. Round order and paired aggregation use the original harness rules. +The timeout is an incomplete campaign collection, with no reported failed numerical +case; it is not relabelled as a successful original job. + +Most modal windows remain slower than native. Julia's wider-budget radial and RDW +wins coexist with native slowdowns at that budget; comparison against each backend's +best measured width gives a different conclusion. Cartesian scaling and serial +radial cost require profiling before assigning a cause. These preliminary results +are tracked in [#729](https://github.com/LupoLab/solprop/issues/729). They +qualify neither the later binary32 work nor any device, and no CPU default or +floating-point policy is changed from these ratios. + +## Julia CUDA artifact preparation and offline primitives + +On 2026-11-11, source `5fc63437` prepared a separate CUDA environment on a CPU +allocation with no GPU. Julia 1.13.3 and JuliaCall/PythonCall 0.9.37 resolved CUDA.jl +6.5.1 and CUDA runtime 13.4. Explicit setup, identity publication and artifact +inventory verification completed in 508.56 s; the isolated depot occupied +4,442,809,795 bytes. This includes the CPU and CUDA package/artifact closure. + +The first device qualification used an NVIDIA A40 with driver 595.71.05 and +compute capability 8.6. A separate Linux user/network namespace exposed only the +loopback interface. The child closed its inherited scheduler socket before importing +the application, checked the namespace identity and retained no inherited sockets. +CPU runtime initialization, subsequent CUDA extension loading, binary32 and binary64 +broadcast, a 16-by-16 matrix product, and 16-point complex FFT/inverse round trips +all passed without networking. CPU and GPU references used the same represented +inputs and explicit positive rounding budgets. Device scalar indexing was disabled. + +| Operation | Time, s | +|---|---:| +| Artifact inventory preflight | 1.033 | +| Fresh-process CPU runtime entry | 5.387 | +| Additional CUDA package loading | 3.820 | +| First successful broadcast, matrix product and FFT checks | 17.515 | + +These are one-process startup observations, not propagation benchmarks or pristine +compilation timings. An earlier offline attempt loaded both package environments +successfully before the test harness used an invalid top-level FFTW import; the +successful run therefore reused populated compilation caches. The earlier failures +also retain a denied syscall-tracer attempt and an inherited-socket assertion. The +final test uses kernel network isolation; it does not claim a measured count of +network syscall attempts. Separate missing-artifact tests check refusal before any +runtime import. Actual CUDA propagation and comparison with native remain pending; +these A40 measurements do not select tuning for GPUs with full-rate binary64 units. + ## The run record's cost [#309](https://github.com/LupoLab/solprop/issues/309) measured how a run's record grows with diff --git a/docs/dev/decisions.md b/docs/dev/decisions.md index 0d5d06e3e..5a54ac9b7 100644 --- a/docs/dev/decisions.md +++ b/docs/dev/decisions.md @@ -2228,3 +2228,118 @@ Withdrawn (development-process record, not a design decision). the earlier opt-in file are not read. Measured threaded rows stay off by default: a plan measured once now costs nothing after, which leaves the policy's threaded-rows effort for the maintainer. + +## ADR-077 — Python enters the Julia backend only on main + +- **Status:** accepted by the maintainer, 2026-11-10; runtime qualification in progress + under SEP 48 and [#620](https://github.com/LupoLab/solprop/issues/620). +- **Context:** Julia 1.13.3 with JuliaCall/PythonCall 0.9.37 can deadlock when a Python + worker enters Julia while Python main waits. This occurs in a warmed CPU-only GC + probe, not just device package loading, and was reproduced on macOS arm64 and Linux + x86-64. A GIL-free call alone does not fix it. Parking main with internal Julia GC + APIs fixed one diagnostic but still failed concurrent GIL/GC contention. The pinned + bridge offers no qualified supported fix. Its wrappers also enter Julia through + destruction, representation, buffer release and exception formatting. +- **Decision:** every Julia-facing operation belongs to Python main in each process. + Refuse Python workers before acquiring runtime locks. Preserve Julia's synchronous + internal parallelism and spawned simulation processes. The raw C atomic stop setter + remains usable from any Python thread. Setup and status remain Python operations. + A process-owned registry retains wrappers and borrowed buffers; handle finalizers + enqueue integer identities only. Main releases abandoned owners at a later boundary, + and all owners before Julia's shutdown hook. Explicit close is required for prompt + resource release. Raw wrappers stay inside narrow bridge helpers, never in public + exports or escaping tracebacks. Format engine failures on main, clear their exception + graphs and unwound frames there, and raise fresh Python-only exceptions. Guard + recursive preparation, bridge entry and owner release. +- **Consequences:** Python thread pools cannot call the Julia backend directly; spawned + workers run on their own main threads. Julia CPU/GPU parallelism is unchanged by this + Python ownership rule. Allocating Julia tasks must finish before the bounded call + returns; vendor background services need separate qualification. This amends SEP 48 + Part I §7.2, as recorded in Part II. It does not change the independent SIGTERM policy + (#610), physics, floating-point policy or required numerical validation. Future bridge + versions may relax the restriction only after the failing probes and full lifecycle + tests pass; a version change alone is not evidence of safety. + +## ADR-078 — Supervise forced termination of embedded Julia + +- **Status:** accepted by the maintainer, 2026-11-10; qualification deferred while + SEP 48's numerical core is implemented. +- **Context:** Julia 1.13.3 can intercept SIGTERM despite restored Python handlers. + During GC its asynchronous fatal-exit path may also stall. The macOS arm64 packaged + runtime probe observed a 180-second stall, and a bounded control reproduced one + with solprop's Python owner-cleanup hook unregistered. A second SIGTERM ended that + control. Julia's [pinned signal listener](https://github.com/JuliaLang/julia/blob/v1.13.3/src/signals-unix.c#L1097-L1119) + explicitly anticipates a first fatal exit stalling; this is not evidence that + removing solprop's ownership hooks fixes it. +- **Decision:** keep the embedded Julia 1.13.3 runtime and its required signal + machinery. Accept fatal SIGTERM and intermittent stalled fatal shutdown. A process + supervisor requiring bounded termination must enforce a deadline outside the Julia + process and escalate to SIGKILL. Normal cancellation remains cooperative through the + lifetime-owned atomic stop flag; actual Python SIGINT handling remains required. +- **Consequences:** SIGTERM cannot promise final output or a checkpoint, and closing + the Julia session does not remove the process-wide limitation. A second SIGTERM is + not the promised hard bound. The maintainer directs numerical implementation to + proceed before further runtime investigation. Existing failed probes remain visible; + no timeout is relabelled as a passed first-signal-exit test. The eventual supervisor + tests must distinguish prompt exit from explicit forced termination and verify child + cleanup. [Issue #610](https://github.com/LupoLab/solprop/issues/610) remains open for + a supported improvement with stable Julia 1.14 and compatible packages. + +## ADR-079 — Verify Julia's CPU BLAS provider and lease its real controls + +- **Status:** accepted during SEP 48 implementation, 2026-11-11. +- **Context:** Julia's libblastrampoline supports forwarding to system Accelerate, + but forwarding and a generic BLAS thread-count request do not establish which + library executes each ABI or how Apple controls its threads. The pinned trampoline + does not implement Apple's documented calling-thread mode API. Accelerate's modes + are automatic and single; automatic is not a known numerical width. +- **Decision:** verify the new LAPACK symbols, both integer ABIs and the documented + mode controls before forwarding. Retain OpenBLAS for missing symbols and verify + representative real/complex GEMM and GESV owners. Missing platform capabilities keep + OpenBLAS with an explicit reason. Each Julia preparation leases single mode on the + acquiring Python main thread; overlapping owners share the existing lease manager + and the last release restores the exact original enum. Ordinary independent BLAS + libraries retain their count-based leases. Provider, ABI, fallback and actual thread + scope are copied into execution metadata. Failed acquisition and rollback retain + an owned retry on the acquiring thread, preserving the initiating failure (#697). +- **Consequences:** the qualified Accelerate path requires its macOS 15 threading + API. All framework callers on that OS thread share the mode, including NumPy and + native; this is not private Julia state. Worker-thread BLAS would require its own + call-scoped control before admission. Current parallel matrix maps are Julia kernels. + Tests verify actual BLAS/LAPACK products, missing-symbol fallback, zero warmed GEMM + allocation, overlapping lifetimes, restoration and detached metadata. These checks + establish provider behavior, not a comparative performance result. +- **Sources:** Apple's [mode setter](https://developer.apple.com/documentation/accelerate/blassetthreading(_:)) + and [mode getter](https://developer.apple.com/documentation/accelerate/blasgetthreading()), + the installed public `vecLib/thread_api.h`, and the pinned trampoline's + [thread-control implementation](https://github.com/JuliaLinearAlgebra/libblastrampoline/blob/v5.15.0/src/threading.c). + +## ADR-080 — Qualify binary32 elementary functions at an explicit boundary + +- **Status:** accepted during SEP 48 implementation, 2026-11-11. +- **Context:** the reduced plasma log-coordinate correction (738) calls + `log1p(Float32)` and consumes its Float32 result. Julia 1.13.3's CPU helpers use + binary64 internally, as does the existing `expm1(Float32)` primitive. A caller's + LLVM without binary64 instructions does not prove that its callees use only + binary32. The numerical derivation needs a returned-value error bound, while + device compilation also needs an implementation that the selected device supports. +- **Decision:** keep response-owned arrays and arithmetic in binary32, and name + each elementary-function API and its separately checked error hypothesis. CPU + library internals may use a wider scalar type. Do not describe a caller-only + inspection as a transitive arithmetic-width proof, introduce explicit binary64 + response buffers, or silently evaluate a device primitive on the host. The + protected in-house DF32 arithmetic helpers retain their strict binary32 graph, + explicit FMA, rounding and range requirements. Inspect and qualify each actual + vendor specialization independently; CPU accuracy and compilation are not + evidence for Metal, CUDA or ROCm. +- **Consequences:** the plasma correction retains its original spline, quadrature, + convergence threshold and clipping policy. Its derivation names the local + `log1p` hypothesis and propagates that error through the reduced coordinate and + spline. Finite MPFR witnesses check that hypothesis on the qualified inputs; + they are not a proof over every vendor's domain. [Issue #751](https://github.com/LupoLab/solprop/issues/751) + retains the direct-callee inspection and remaining device work. This boundary + changes no physics, default, binary32 noise admission or numerical envelope. +- **Sources:** Julia 1.13.3's [logarithm helpers](https://github.com/JuliaLang/julia/blob/v1.13.3/base/special/log.jl) + were checked against the installed source and emitted direct-callee arithmetic. + The error derivation and primitive references are in + `julia/PLASMA_CYCLE_PRECISION.md` and `julia/DF32_BOUNDS.md`. diff --git a/docs/dev/dependencies.md b/docs/dev/dependencies.md index 461700234..db3cbd58e 100644 --- a/docs/dev/dependencies.md +++ b/docs/dev/dependencies.md @@ -84,6 +84,28 @@ package index. Evaluated against glibc's `libmvec` (2 ulp, and reachable from GC through fast-math or hand-written vector declarations) and Intel's MKL (faster on Intel only, by at most 1.5 times, and a large dependency); see ADR-059. +## The optional Julia engine + +[SEP 48](seps/sep-0048-julia-backend.md) defines the optional pure-Julia numerical +engine and its separate application environments. Its committed manifests pin a joint +CPU/device resolution; PythonCall and vendor packages remain weak engine dependencies. +The numerical package directly uses FFTW, KernelAbstractions, AcceleratedKernels, +Polyester, Atomix and PrecompileTools, with Julia's LinearAlgebra and Libdl standard +libraries. Libdl supplies verified system BLAS symbol discovery; its compat bound is +`1`, matching the non-upgradable standard library bundled with the pinned Julia release. + +**Adapt** and **StrideArraysCore** are direct dependencies for the bounded CPU scalar +launcher. Adapt recursively converts immutable closure captures, including nested +closures and tuples; StrideArraysCore supplies the same `PtrArray` storage views used +by Polyester. The launcher roots every original captured array while adapting and +executing the complete synchronous batch. This avoids allocating Polyester's argument +wrapper when a scalar body captures arrays. It refuses an adapted body that still +contains managed references. These dependencies already belonged to the pinned closure; +making the imports explicit adds no package or artifact. Adapt's 4.8 floor preserves +the generated recursive closure adaptation used by the allocation checks; +StrideArraysCore's `PtrArray` API uses the existing 0.5 series. The manifests retain +Adapt 4.8.0 and StrideArraysCore 0.5.9. + ## The desktop front end (`gui` extra) `solprop-gui` is the repository's third distribution, built from `gui/` and installed diff --git a/docs/dev/figures/backends.svg b/docs/dev/figures/backends.svg index fffb5414b..253fadf89 100644 --- a/docs/dev/figures/backends.svg +++ b/docs/dev/figures/backends.svg @@ -1,6 +1,6 @@ + width="1200" height="903.5" viewBox="0 0 1200 903.5"> - + One seam, a shared driver, and the backends behind them backends.md §1: the protocol is drawn at the level of operations on the propagated state, never at the array-namespace level. A backend is constructed from a validated PropagationProblem and host arrays and returns host arrays; its buffers, layout and plans are private. - + the seam · backends.protocol.Backend prepare bind a problem and its run request; each start opens a session -set_initial -the state and the noise realisation, host to device, once -set_progress -the observer each attempted step reports to; never an input -set_stop -the flag polled between trials, or none -attach_monitor -watch the time window's edges from here on -edge_memory -what reading a grid's edge will hold, for an estimate -propagate_to -the driver's way in, returning a StepSummary -observe -host arrays: the field at the plane and the step history -restore_call_ledgers -resume cumulative calls; numerical history starts afresh -march_snapshot -the Adams history for a resume, or None -march_snapshot_nbytes -its size, copying nothing -march_export_refusal -why the march cannot carry its history, or None -restore_march -continue the history, or say why it starts afresh -timing_probe -single trials from a start, committing nothing, for timing -stats -one fused pass, a dict of small host arrays -metadata -what the execution was: pools, plans, digests, propagator mode -memory_ledger -every named buffer and its size -available_device_memory -free device bytes for batch admission; None on hosts -close -idempotent - - -backends.registry.select(name, problem, grid=, modes=, profiles=) - -HostDriver (reference) · StepDriver (native bridge) -the march and the landing -_march_to -the replay -_replay_to · _schedule_index_at -the history -_record · observe -the progress reporter -set_progress -the statistics channel -_take_step_stats · stats -the noise -_noise_field · _noise_at · _noise_phase -the per-stage bundle -_hoist · _stage_scalars · _delta_phi · _unitary_phase - -the stepper it drives -stepper.tableau -DOPRI5, Tsit5, the order-condition checks -stepper.controller -PIController: propose, accepts, rejection_factor, -equivalent_norm -stepper.schedule -landing, discover, calibrate, replay -what a backend supplies -_trial_step · _apply_mask · _finish · _begin_plane -· _on_accepted_step - - - -numpy_ref · the oracle -plain NumPy and scipy.fft -one named function per pass -the general representation, the z table included -propagator_mode auto → tabulate -_trial_step · _apply_mask · _finish · _observed_field - - - -native · what auto selects -solprop-native distribution, native/ -C++20 Kokkos + persistent Kokkos-FFT plans -one native call per seven-stage trial -OpenMP on CPUs; CUDA and HIP on GPUs -_trial_step · _apply_mask · _finish · _observed_field -Three things every backend owes beyond the methods: deterministic reductions, the device form of the stage, and the driver's bookkeeping. The error norm is control flow, so -a sum whose association depends on the thread count forks the trajectory. +start_group +open member sessions on one compatible fixed schedule +set_initial +the state and the noise realisation, host to device, once +set_progress +the observer each attempted step reports to; never an input +set_stop +the flag polled between trials, or none +attach_monitor +watch the time window's edges from here on +edge_memory +what reading a grid's edge will hold, for an estimate +propagate_to +the driver's way in, returning a StepSummary +observe +host arrays: the field at the plane and the step history +restore_call_ledgers +resume cumulative calls; numerical history starts afresh +march_snapshot +the Adams history for a resume, or None +march_snapshot_nbytes +its size, copying nothing +march_export_refusal +why the march cannot carry its history, or None +restore_march +continue the history, or say why it starts afresh +timing_probe +single trials from a start, committing nothing, for timing +stats +one fused pass, a dict of small host arrays +metadata +what the execution was: pools, plans, digests, propagator mode +memory_ledger +every named buffer and its size +available_device_memory +free device bytes for batch admission; None on hosts +close +idempotent + + +backends.registry.select(name, problem, grid=, modes=, profiles=) + +HostDriver (reference) · StepDriver (native bridge) +the march and the landing +_march_to +the replay +_replay_to · _schedule_index_at +the history +_record · observe +the progress reporter +set_progress +the statistics channel +_take_step_stats · stats +the noise +_noise_field · _noise_at · _noise_phase +the per-stage bundle +_hoist · _stage_scalars · _delta_phi · _unitary_phase + +the stepper it drives +stepper.tableau +DOPRI5, Tsit5, the order-condition checks +stepper.controller +PIController: propose, accepts, rejection_factor, +equivalent_norm +stepper.schedule +landing, discover, calibrate, replay +what a backend supplies +_trial_step · _apply_mask · _finish · _begin_plane +· _on_accepted_step + + + +numpy_ref · the oracle +plain NumPy and scipy.fft +one named function per pass +the general representation, the z table included +propagator_mode auto → tabulate +_trial_step · _apply_mask · _finish · _observed_field + + + +native · what auto selects +solprop-native distribution, native/ +C++20 Kokkos + persistent Kokkos-FFT plans +one native call per seven-stage trial +OpenMP on CPUs; CUDA and HIP on GPUs +_trial_step · _apply_mask · _finish · _observed_field +Backends own their numerical state, execution and exact work accounting. Independent reductions and adaptive trajectories may differ within their derived numerical bounds +(SEP 25); controller decisions on identical recorded readings remain exact. \ No newline at end of file diff --git a/docs/dev/figures/build.py b/docs/dev/figures/build.py index 27180365d..91254f0f6 100644 --- a/docs/dev/figures/build.py +++ b/docs/dev/figures/build.py @@ -751,6 +751,7 @@ class Layer(NamedTuple): "tdse", ), ), + Module("backends/julia/", ("backend", "command")), ), "D": ( Module("log.py"), @@ -1215,6 +1216,7 @@ class Pass(NamedTuple): SEAM_METHODS = ( ("prepare", "bind a problem and its run request; each start opens a session"), + ("start_group", "open member sessions on one compatible fixed schedule"), ("set_initial", "the state and the noise realisation, host to device, once"), ("set_progress", "the observer each attempted step reports to; never an input"), ("set_stop", "the flag polled between trials, or none"), @@ -2605,10 +2607,10 @@ def backends() -> drawsvg.Drawing: "host arrays; its buffers, layout and plans are private." ) footer = ( - "Three things every backend owes beyond the methods: deterministic " - "reductions, the device form of the stage, and the driver's bookkeeping. The " - "error norm is control flow, so a sum whose association depends on the thread " - "count forks the trajectory." + "Backends own their numerical state, execution and exact work accounting. " + "Independent reductions and adaptive trajectories may differ within their " + "derived numerical bounds (SEP 25); controller decisions on identical " + "recorded readings remain exact." ) top = header_height(subtitle) + 20 gap = 44.0 diff --git a/docs/dev/figures/layers.svg b/docs/dev/figures/layers.svg index e0dc2ad9c..a582570d1 100644 --- a/docs/dev/figures/layers.svg +++ b/docs/dev/figures/layers.svg @@ -1,6 +1,6 @@ + width="1200" height="1915.5" viewBox="0 0 1200 1915.5"> - + The layers of solprop, and every module in each Bands and colours from architecture.md §3 and decisions.md ADR-001; modules from src/solprop. Arrows point from the layer that imports to the layer it imports. @@ -171,12 +171,12 @@ text { font-family: Inter, "Helvetica Neue", Helvetica, Arial, sans-serif; fill: plasma_source · envelope_plasma raman · masks · precision · tdse tdse_source · run_request - - -B -backends -may import -numpy; the native package in native/ + + +B +backends +may import +numpy; the native package in native/ backends/ protocol · registry · driver @@ -195,119 +195,122 @@ text { font-family: Inter, "Helvetica Neue", Helvetica, Arial, sans-serif; fill: transforms · single · admission envelope_plasma · general_modal tdse - - -D -driver -may import -P, T -B through the seam, h5py - -log.py - -stats.py - -stepper/ -tableau · runge_kutta · multistep -low_storage · controller · schedule - -output/ -schema · capability · memory -callback · hdf5 · tdse_archive -snapshots · scan · scan_artifacts -resumable - -scan.py - -calibration/ -command · controller · first_use -child · grain · problems · refine -selection - -driver/executors/ -local · pool · queue · slurm -batch - -driver/ -simulation · run · summary -interface · scaffold · mixtures -material_output · tdse -tdse_consistency · scan · batch -defaults · estimate · plane_view -service - -recipe/ -core · document · errors · export -metadata · paths · pins · preview -provenance · quantity · registry - -cli.py - - -X -processing / plotting -may import -numpy, scipy -matplotlib, D (outputs) -T (table identities) - -processing/ -beams · axes · fields · spectra -time · coherence · compression -mixtures · modal · planes -plane_file · scans - -plotting/ -propagation · statistics -spectrograms · style · geometry - -sol.py - -capabilities.py - -service/ -agent · beam · beams · client -design · explore · figures · frames -handlers · install · job · kernel -launch · machines · messages -postprocess · recipes · record -reduce · results · run · runs -scan_reductions · sheet · states -waveguide · worker - -processing/ -windows + +backends/julia/ +backend · command + + +D +driver +may import +P, T +B through the seam, h5py + +log.py + +stats.py + +stepper/ +tableau · runge_kutta · multistep +low_storage · controller · schedule + +output/ +schema · capability · memory +callback · hdf5 · tdse_archive +snapshots · scan · scan_artifacts +resumable + +scan.py + +calibration/ +command · controller · first_use +child · grain · problems · refine +selection + +driver/executors/ +local · pool · queue · slurm +batch + +driver/ +simulation · run · summary +interface · scaffold · mixtures +material_output · tdse +tdse_consistency · scan · batch +defaults · estimate · plane_view +service + +recipe/ +core · document · errors · export +metadata · paths · pins · preview +provenance · quantity · registry + +cli.py + + +X +processing / plotting +may import +numpy, scipy +matplotlib, D (outputs) +T (table identities) + +processing/ +beams · axes · fields · spectra +time · coherence · compression +mixtures · modal · planes +plane_file · scans + +plotting/ +propagation · statistics +spectrograms · style · geometry + +sol.py + +capabilities.py + +service/ +agent · beam · beams · client +design · explore · figures · frames +handlers · install · job · kernel +launch · machines · messages +postprocess · recipes · record +reduce · results · run · runs +scan_reductions · sheet · states +waveguide · worker + +processing/ +windows T → P physics objects B → T delta_phi, prefactor_at, the stage bundle - - -D → B backends.select, then the seam - - -X → D a saved run, through the Output protocol - + + +D → B backends.select, then the seam + + +X → D a saved run, through the Output protocol + - -1 - + +1 + - -2 - + +2 + - -3 - + +3 + - -4 -1 Simulation calls translate.assemble -2 the driver builds the grid, the modes, the pulse and the responses -3 the statistics path: a backend is handed grid, modes and profiles at construction: the one import of P that architecture.md §3 allows B, types and constants, never a physics object -4 processing.modal takes the run's own ModalTransformTables beside the handler: a general modal file records what its reference is and not the arrays, so the reference is rebuilt in T and read in X -The package-wide modules carry no layer letter: __init__.py · exceptions.py + +4 +1 Simulation calls translate.assemble +2 the driver builds the grid, the modes, the pulse and the responses +3 the statistics path: a backend is handed grid, modes and profiles at construction: the one import of P that architecture.md §3 allows B, types and constants, never a physics object +4 processing.modal takes the run's own ModalTransformTables beside the handler: a general modal file records what its reference is and not the arrays, so the reference is rebuilt in T and read in X +The package-wide modules carry no layer letter: __init__.py · exceptions.py \ No newline at end of file diff --git a/docs/dev/roadmap.md b/docs/dev/roadmap.md index 83c5016e2..525cf75d5 100644 --- a/docs/dev/roadmap.md +++ b/docs/dev/roadmap.md @@ -49,7 +49,7 @@ being implemented. exception; APIs may be freely broken for a cleaner design, with callers, tests and documentation updated together and a changelog listing. -- [SEP 48 — A Julia backend](seps/sep-0048-julia-backend.md): an optional +- [SEP 48 — A Julia backend](seps/sep-0048-julia-backend.md), in progress: an optional `backend="julia"` at Tier 3, one Julia engine for CPUs and NVIDIA, AMD and Apple GPUs in binary64 and binary32 (input noise in binary64 only), owning SEP 47's whole execution session. `pip install solprop` is unchanged; the `julia` extra adds only `juliacall`, and `solprop julia diff --git a/docs/dev/seps/index.md b/docs/dev/seps/index.md index 8468a70e3..582558874 100644 --- a/docs/dev/seps/index.md +++ b/docs/dev/seps/index.md @@ -34,7 +34,7 @@ Proposals that are active, in draft, accepted, in progress or deferred. | [17](sep-0017-gas-two-photon-ionisation.md) | Broadband two-photon continuum response beside strong-field ionisation | Accepted | Feature | | [32](sep-0032-raman-maxwell-bloch.md) | Raman Maxwell–Bloch dynamics | Draft | Feature | | [47](sep-0047-run-ownership.md) | Backend-owned execution sessions | In progress | Change | -| [48](sep-0048-julia-backend.md) | A Julia backend: one engine for CPUs and GPUs, in both precisions | Accepted | Feature | +| [48](sep-0048-julia-backend.md) | A Julia backend: one engine for CPUs and GPUs, in both precisions | In progress | Feature | SEP 13, the standalone numerical prerequisite for SEP 12, SEP 14, which carried it to the compiled backends, and SEP 16, which unified the multistep family and made it the diff --git a/docs/dev/seps/sep-0048-julia-backend.md b/docs/dev/seps/sep-0048-julia-backend.md index 0020302db..00320bc1c 100644 --- a/docs/dev/seps/sep-0048-julia-backend.md +++ b/docs/dev/seps/sep-0048-julia-backend.md @@ -6,7 +6,7 @@ | **Title** | A Julia backend: one engine for CPUs and GPUs, in both precisions | | **Author** | John Travers | | **Drafting agent** | Opus 5.5; GPT-6 (acceptance revisions, 2026-11-10) | -| **Status** | Accepted | +| **Status** | In progress | | **Review status** | Reviewed | | **Reviewers** | John Travers (human); GPT-6 (AI) | | **Type** | Feature | @@ -15,8 +15,8 @@ | **Requires** | SEPs 25, 33, 46 and 47 | | **Supersedes** | — | | **Superseded-by** | — | -| **Implementation** | — | -| **Manual pages** | — | +| **Implementation** | [PR #611](https://github.com/LupoLab/solprop/pull/611), `feature/sep-0048-julia-backend` | +| **Manual pages** | [Julia backend](../../guide/performance/julia.md) | ## Part I — Proposal @@ -1391,8 +1391,519 @@ records each decision where it applies: ## Part II — Implementation record +### Runtime ownership amendment — 2026-11-10 + +The maintainer accepted an implementation amendment to §7.2's subsequent Python +worker-thread safety requirement: every operation that enters Julia runs on Python's +main thread in each process. Other Python threads receive a named refusal before any +runtime call or lock wait. Julia's own synchronous CPU parallelism and spawned worker +processes remain supported; the raw atomic stop setter still works from any thread. +Setup and status do not enter the embedded runtime. + +The reason is a reproducible Julia 1.13.3/PythonCall 0.9.37 GC deadlock. A warmed pure +CPU function that allocates and explicitly collects completes on main, but hangs when +called from a Python worker while main waits. Independent macOS probes reproduced it +with one and two Julia threads, and a two-thread Linux probe corroborated it. Releasing +the GIL alone does not fix it. A diagnostic using internal GC-state manipulation fixed +one package-load case but still deadlocked under concurrent GIL/GC contention; no such +workaround is adopted. [Issue #620](https://github.com/LupoLab/solprop/issues/620) +records the evidence. This is separate from the accepted SIGTERM limitation in #610. + +The boundary covers destruction and exception formatting as well as explicit calls. +Process-owned registries retain Julia wrappers and borrowed Python buffers. Foreign +finalizers enqueue integer identities; main releases them at a later boundary or before +Julia shutdown. Bridge failures become Python-only exceptions after the original +exception graph and unwound frames are cleared on main. Public exports own Python +storage. ADR-077 records the durable design. Qualification is still in progress; this +amendment does not declare phase 1 complete or claim any numerical/session parity. + +### Signal supervision and implementation order — 2026-11-10 + +The maintainer accepted a further SIGTERM limitation: Julia's fatal shutdown may stall +during GC, so an external supervisor must enforce a SIGKILL deadline when bounded +termination is required. A macOS arm64 probe stalled for 180 seconds, and an independent +bounded control reproduced a stall with the Python owner-cleanup hook unregistered. +Neither SIGTERM nor SIGKILL promises final output. Cooperative cancellation and actual +Python SIGINT handling retain their requirements. ADR-078 and +[issue #610](https://github.com/LupoLab/solprop/issues/610) record the policy and follow-up. + +The maintainer subsequently directed core implementation to proceed from the +experiment's numerical kernels, deferring remaining runtime investigation until after +implementation. This explicitly removes the incomplete subprocess gate from the +critical path for phase 2; it does not claim that the gate passed. Existing failures +and the passing 36-case macOS non-SIGTERM matrix remain recorded. Independent numerical +review, integration, short reference witnesses and required accuracy checks continue. + +### CPU implementation milestones — 2026-11-10 + +The internal binary64 scalar modal adapter now constructs Julia-owned Runge–Kutta, +exponential Adams and fixed low-storage RK4IP sessions through the SEP 47 execution +owner contract. Julia owns stepping, control, bounded attempts and numerical failures; +Python translates descriptors and services closed events. Kerr, Raman and plasma use +their independent represented profiles. Plane and periodic scalar statistics now attach +through request-specific immutable preparation and session-owned work. Generation-checked +copies publish complete host payloads atomically, retain failed-copy retries and preserve +delivered arrays after close. The unavailable embedded quadrature diagnostic remains NaN. +The temporal monitor and dense numerical leaves have separate tests; their Python +attachment remains in progress. + +Portable Adams history copies raw accepted state, all engine rows and actual selected +sample coordinates into detached host buffers. Shared history keys gate restoration; +execution identities do not. Cumulative logical budgets and compact order records +survive both full-history and field-only resumes. Twelve managed-runtime witnesses cover +Julia continuation, both directions with the NumPy reference and native CPU, +plain/compensated storage, lifetime checks and budget/counter-capacity refusal before +new work. Dense and cross-precision restart cases remain to be qualified. The complete +phase 2 report will follow its remaining route, +observation, group, noise, conformance and measurement work; this milestone does not +declare any implementation phase complete. + +The scalar DF32 primitives have passed independent algorithm/source review, including +normalization ties, protected CPU instruction checks and zero warmed allocations. +Their finite-intermediate assumptions do not establish a propagation domain. The +transcendental/range analysis remains a separate phase 3 requirement. Fixed-group replay +and terminal replacement hooks preserve chunks and actual positions; the complete group +coordinator and transport still require integration and review. + +### Temporal monitoring and group integration — 2026-11-11 + +Temporal monitoring now runs inside the numerical session, including continuation, +warning barriers and exactly-once detached records. Fixed-schedule groups use Julia's +member coordinator and publish complete common windows through Python's shared session +services. Numerical stepping and member scheduling remain in Julia. Admission checks +the complete Runge–Kutta tableau before consuming any entrance. Interrupted construction +rolls back original starts; interrupted acknowledgments and repeated publication +failures retain copied work without advancing or duplicating chunks (#676, #677). +Actual member positions, Adams accounting and monitor rows survive forced termination. + +Independent group review is complete. Sixteen real managed-runtime cases pass on +macOS arm64 with two Julia threads; seven independent transaction tests and three +shared ledger tests pass. The focused numerical group suite passes 659 bounds-enabled +assertions, and Aqua/JET passes 16 checks over 1,199 definitions. The same milestone +passes targeted types, docstrings, formatting, spelling and documentation checks. +These are integration milestones; the remaining admitted spatial routes, split collar, +input noise, dense attachment and qualification still block phase 2 completion. + +### Dense Adams observations and binary64 input noise — 2026-11-11 + +Adaptive Adams now delivers every crossed plane from its retained accepted window +without replacing the committed state. Statistics, phase and power conversion use the +selected observation coordinate. Interior planes refuse the endpoint's future history; +snapshots drain the owed planes before copying the committed endpoint. Replay and +split/interpolation refusals are unchanged. Independent scheduler/attachment review +and short refined-reference witnesses pass. + +All three CPU methods accept binary64 input noise. Julia copies the selected per-start +draw, adds it only at a fresh problem launch, applies the active mask and retains the +draw for monitor floors on resume. Cumulative phase exports preserve represented +absolute offsets. Modified noise and all binary32 noise remain refused. No random +generator, physical coefficient or noise model is introduced. The shared initial-state +and cumulative-phase contracts were checked against the NumPy implementation. + +Independent review passes 1,340 bounds-enabled noise/session assertions and eight +typed callback-publication witnesses. The latter exposed #680: a callback between a +foreign copy and publication could populate the wrong event's cache. Export caches +now retain the full ticket and are replaced at acknowledgment, terminal replacement +or close; an interrupted copy can publish only to its original cache. A separately +reviewed input-only noise-floor bound propagates absolute transform and reduction +errors through the energy ratio and passes 19 perturbation/range witnesses. + +The integrated macOS arm64 selection passes 100 real managed-runtime cases, and its +affected typed selection passes 149. Core numerical tests and the corrected isolated +inventory invocation pass 111,597 assertions in 251 sets. The initial invocation +errors omitted required startup/import context; no source workaround was made. +Aqua/JET passes 16 checks with all 1,236 definitions analyzed, none cached. Targeted +types, docstrings, formatting, spelling and Sphinx pass. These remain integration +milestones: remaining routes, split/RK dense attachment, preparation and performance +records still block phase 2 completion; later phases continue on the same branch. + +### DOPRI5 dense observations and split temporal absorption — 2026-11-11 + +Adaptive DOPRI5 now receives the shared continuous-extension weights and retains its +own accepted window. All observed fields, statistics and exports use the requested +plane coordinate while the committed state stays monotone. Independent leaf review +passes 779 bounds-enabled assertions, including actual NumPy extension witnesses, +endpoint conditioning (#681), exact copies and zero warmed allocation. + +Scalar modal split absorption uses the existing accepted-step service independently +of statistics or monitoring. The coarse amplitude factor is applied once, after the +initial mask and before the final mask; the same rate is excluded from the nonlinear +source. Twenty-three real field/envelope cases cover three integrators, one/eight +steps, independent uniform decay, observer combinations, field restart and a quiet +monitor whose split still removes the expected energy. Existing physics defaults and +the split method's order are unchanged. The test bound converts the declared +componentwise FFT envelope to the norm used by its contraction argument (#686). + +Common conformance exposed a periodic-row ownership bug (#687): deferring endpoint +rows until after dense planes could separate them from their accepted attempt. The +corrected ordering follows SEP 47: endpoint rows precede the first dense plane, while +all owed planes precede snapshots and another trial. The first plane consumes its +previous-stage quadrature diagnostic; another plane without new source work sees NaN. +Shared validation also rechecks dense exclusions after request adaptation (#682). + +The repaired managed-runtime selection passes 53 dense, monitor and common-conformance +cases, with 22 named skips for bitwise repetition and pending transverse attachment. +The complete bounds-enabled Core suite passes 112,291 assertions in 264 sets; +Aqua/JET passes 16 checks over all 1,253 definitions with none cached. Independent +adapter review and 12 additional typed admission checks pass. The spatial source leaf +is independently approved with 4,154 assertions, including 440 actual NumPy witnesses; +its public preparation and observation attachment remains in progress. +These are partial phase 2 milestones; remaining preparation, route and performance +qualification still precedes phase completion. + +The recoverable assignment and verification record is `julia/IMPLEMENTATION.md`. +The full primary-source DF32 analysis and per-vendor qualification remain in phases 3 +and 4. All implementation changes remain on the single draft PR #611. + +### Representative CPU precompilation — 2026-11-11 + +The engine now precompiles three small owned CPU session paths covering field RK, +envelope Adams and low-storage stepping, material responses, observations and a monitor. +Normal imports do not execute the workload. Cache construction retains no global mutable +workspace, changes no thread or planner policy and loads no Python or vendor extension. +The public-path preparation and thread specializations remain independently qualified. + +Independent bounds-enabled review passed 601 prerequisite assertions and 106 workload +assertions. Author Aqua/JET passed all 16 checks with 1,225 analyzed definitions and +zero cached roots, plus concrete workload analysis. A native-target Apple arm64 cache +diagnostic measured 22.67 s to build a 67.54 MB engine image. Its next-process first +three-session execution took 6.93 ms, compared with 20.26 s when only the workload macro +was disabled. These representative cache measurements do not replace the mandatory +quiet-machine startup and propagation campaign. Generic-target CI qualification, +FFT-plan persistence and shared BLAS leases remain outstanding. + +### Scalar spatial session attachment — 2026-11-11 + +Radial, Cartesian and line numerical preparations now create complete binary64 CPU +sessions through the same shared preparation contract. Python copies translated inputs +once; Julia owns reconstruction, material sources, physical transverse loss, stepping +and spatial observations. Cartesian layouts retain the translated x-fast ordering and +use FFTs rather than dense spatial maps. Radial maps retain their quadrature and temporal +padding factors. Spatial export preserves its own measure; it does not synthesize or +apply modal power weights. + +The flux observation descriptor is independent of the marching generator. Energy, +local and on-axis intensity, on-axis spectrum and beam widths use its represented +closure and the shared normalization. Same-field bounds separate SI quantities and +condition width thresholds on checked margins, under the qualified componentwise CPU +FFT model. Numerical exports now validate their actual source and flow preparation +identity, rather than a shared absent-weight sentinel (#690). + +The affected managed selections pass 104 cases across runs: 73 spatial cases and 31 +modal observation/split regressions. These include short linear and Kerr runs, three +reference refinements for nonlinear accuracy, material-free physical absorption, +absolute input-noise phase at a nonzero launch and foreign-preparation rejection. +An initial reference-harness mistake asked for a stage-only quadrature diagnostic in +the saved-field collector; correcting that request made all 18 statistics comparisons +pass, without a production workaround. The two-thread bounds-enabled Core passes +116,924 assertions in 294 sets, including zero-allocation physical temporal splitting. +Integrated Aqua/JET passes all 16 checks over 1,409 definitions, with no cached roots. +Transverse monitoring, remaining preparation controls and the complete route/material +qualification matrix still precede phase 2 completion. + +### Transverse services, FFT persistence and estimates — 2026-11-11 + +The binary64 spatial session now owns transverse launch assessment, accepted-step +readings, warning/stop barriers and continuation. Its noise-floor reference retains +the original unmasked clean columns; a resumed checkpoint with no edge record uses +the masked current field and original draw. Explicit continuation selection is +separate from lifecycle resumption, so a selected absent record cannot later be +replaced by a fallback (#693). Python formats detached records and preserves the +earlier warning position in a face-stop message (#692). + +CPU source, temporal/spatial and Raman transforms use actual-array FFT planning. +Each start receives an isolated context, checks offers against verified loaded +libraries and artifact identities, and publishes successful measurements through an +atomic cache. Later starts refresh process/file offers; calibration clearing handles +Julia records too (#694). Optional file-write failure does not invalidate a prepared +session, and unexpected adoption failure releases numerical ownership (#695). +Preparation-only wisdom maps are released after facts are copied; no uncounted copy +of the persistent cache remains in a running session. Metadata counts distinct +transform keys. The precompile workload explicitly uses estimate-only contexts. + +The execution owner supplies a separate Julia timing probe, retaining its own copied +load, stages, norm, source and flow. It constructs no controller, observation or march +history. Embedded candidates receive their usual boundary treatments once at host +readback; low-storage probes update discarded registers and expose no trial field. +Start handover and main-thread cleanup retain ownership, and a cleanup failure cannot +replace the initiating exception (#696). + +Independent reviews cover the Julia leaves and each Python integration. The actual +managed bridge passes 34 new transverse, timing and cache cases. The bounds-checked +Core selection passed 119,300 assertions in 323 sets before its final inventory module; +that module then passed all 34 assertions in seven sets under the required isolated +startup flags. The first Core command omitted those flags, and the first isolated +retry omitted its usual TOML import; neither failure required a production change. +Integrated Aqua/JET passes 16 checks over 1,544 definitions, none cached. The affected +typed Python/SEP selection passes 455 tests with three declared process-SEP skips. +Sphinx builds successfully. Whole-package Python analysis has no errors and the three +existing local native-stub warnings. CPU provider selection, budgeted node planning, +remaining route/material witnesses and measurements still precede phase 2 completion. + +### CPU providers and combined materials — 2026-11-11 + +CPU initialization now verifies its BLAS/LAPACK provider before publishing the runtime. +On supported macOS systems it forwards both integer ABIs to Accelerate while retaining +OpenBLAS for missing symbols. The documented single/automatic calling-thread control +requires macOS 15 or later; older or incomplete platforms retain OpenBLAS and record +why. This qualifies the proposal's macOS preference to a controllable implementation. +Preparation leases preserve overlapping users and restore the exact previous mode. +All callers of Accelerate on that OS thread share its mode. ADR-079 records the control +boundary and metadata; no new external package is needed. Libdl is now an explicit +standard-library dependency, and all affected manifests were mechanically regenerated. + +Independent provider checks cover actual real/complex BLAS/LAPACK products, both ABIs, +missing-symbol fallback and zero warmed GEMM allocation. The final Julia selection +passes 133 bounds-enabled assertions with two threads. Four actual managed cases +verify overlapping preparation lifetimes, provider metadata and persistent FFT reuse. +The shared acquisition review found #697: a simultaneous setter/rollback failure could +orphan a request before returning its lease. The corrected boundary roots the lease +before mutation, preserves the primary error and retries only on its acquiring thread. +The affected Python selection passes 109 tests; an independent two-pool interruption +witness also passes. The final leaf quality gate passes 16 Aqua/JET checks over all +1,560 definitions with none cached. These checks establish provider behavior; quiet +machine performance measurements remain outstanding. + +The combined-material matrix passes 20 actual CPU sessions: field and envelope on +averaged, multimode, radial, Cartesian and line routes; independent material gradients +and uncoupled modal tapers; and alternate RK, Adams and low-storage marches. Every case +contains two plasma populations and two independent Raman components. Eight-step runs +are compared with separate 16/32-step reference refinements under accuracy envelopes +fixed before comparison. The one-micrometre window resolves the field carrier for all +methods. Independent review checked nonzero observables, species additivity, refinement +and admitted statistics. This is an accuracy qualification, not a formal convergence +order measurement. CPU measurements and the remaining preparation integration still +precede phase 2 completion. + +### Public CPU selection, node budgets and timing boundary — 2026-11-11 + +The registry now selects `julia` lazily for the admitted scalar binary64 CPU routes. +The bridge is checked by availability probing; explicit setup selection and numerical +allocation occur during preparation. The existing default backend remains unchanged. +Public settings admit the supported RK, exponential Adams and fixed low-storage methods. +This CPU selection is brought forward from phase 4 so initial measurements can use the +standard public benchmark harness. Device selection and binary32 remain separate gates. + +The Julia-specific node inventory bounds retained source, population-observation and +transverse-trace array payloads together. It separately reports fixed/full-volume +work, opaque FFT plans and storage outside the node budget. Plans bind to the actual +prepared request, including statistics or monitors attached after owner construction. +Cheap immutable preparation records share their scientific arrays while keeping each +request's selected chunk. A one-node shortfall refuses before runtime initialization. +The reviewed planner passes 23 pure and 38 managed inventory cases; four actual public +integrator/request cases and 14 standalone binding assertions also pass. A public +simulation and common benchmark smoke complete separately. The initial settings-test +fixture omitted required settings; its corrected focused check passes. + +Ordinary benchmark windows now begin at the generic `prepared.start` return, labelled +`prepared.start.return.v1`, for all owners. Preparation-inclusive `wall_seconds` is +retained separately. Transparent proxies preserve session ownership, protocol members, +metadata errors and closure; counters are read from the same session before release. +Logical Adams charges do not substitute for unavailable actual invocation counts. +The independently reviewed slice passes 106 typed tests and 23 affected session tests; +actual reference/native smoke tests and the Julia integration smoke pass. These are +functional checks, not quiet-machine performance measurements. Earlier load-boundary +records use a different timing window and are not directly interchangeable. + +CI at `162da950` completed the coverage report successfully. Required failures remain +visible: #699 addresses Windows collection of POSIX-only test constants, and #700 +tracks an asynchronous stop/resume test assumption. One macOS shard passed all 7,229 +tests but failed artifact upload after a DNS error. The next CI push must re-establish +all gates; neither these corrections nor the CPU smoke complete phase 2 measurements. + +### Binary32 composition and certified DF32 attachment — 2026-11-11 + +The binary32 source, marching, observation, monitor, split-absorption and physical +export paths compose internally. Precision/scales are shared immutable inputs; +mutable state and transport buffers remain session-owned. The retained-owner matrix +passes 84 managed cases plus 27 pure cases. Independent factory review adds 178 actual +PythonCall checks and seven registry checks. The corrected integrated Core aggregate +passes 156,695 assertions in 484 testsets, bounds enabled at two threads; Aqua/JET +passes 16 checks across all 2,067 definitions with none cached. These counts identify +the aggregate before the subsequent Python DF32 attachment. + +The short CPU32 qualification matrix has 59 distinct successful cases across targeted +runs, with zero enabled skips. Review found that raw squared-amplitude bands were +not physical spectral energy (734). The corrected 32-case subset uses the existing +modal power weights and spatial flux functional, including the actual final position, +and passes at unchanged tolerances. An independent point-spectrum witness adds 46 +exact-rational band, endpoint, position and partition assertions across ten route/grid +combinations. The historical SEP 33 Part II raw metric is not reinterpreted here. +The complete Adams-versus-RK admission comparison remains additional work. + +Certified DF32 landed RK and low-storage flows retain original coefficients, actual +replay lengths and complete trial coordinates. Their two-bank publication precedes +source calls or accepted-state mutation. The Python attachment lowers once, binds each +actual start and preserves transfer identity through PythonCall; Julia owns all trials +and certificates. It refuses unqualified Adams, dense, spatial and tabulated flow by +name. Completed starts invent no step. The owner inventories its detached operator +copy and every flow bank. Public binary32 selection remains closed. + +Independent attachment review passes 101 typed pure tests, ten managed propagation, +range-refusal and restart cases, six additional actual factory ownership/refusal +witnesses, and six group cases. Groups retain independent member fields and report +actual member progress when a later member refuses a phase. Ordinary replay accuracy +uses settled binary64 references and the fixed SEP 33 envelopes, while unchanged +fields, delivered counts and ownership are checked structurally. No device or +long-distance qualification is inferred. + +`julia/DF32_BOUNDS.md`, `WIDE_ASSEMBLY.md`, `DF32_INTEGRATION.md` and +`DF32_EXECUTION.md` record the arithmetic graph, primary-source hypotheses and derived +bounds. Complete arithmetic papers and relevant supplement definitions were inspected; +the formal supplement was not recompiled. Finite-underflow and transcendental bounds +are explicitly derived here rather than attributed to unlimited-exponent results. +Complete Adams factors, DF32 dense/spatial assembly and vendor execution remain open. + +The binary64 CPU measurement matrix now contains 144 samples and 432 timed repetitions +on an exclusive AMD EPYC 7763, at one and 64 physical cores. The benchmark ledger +records every short window, paired ratio, preparation-inclusive wall and limitation. +The original collection timeout is retained; a bounded continuation completed only +three missing pairs with the same source and placement. No performance ratio is an +acceptance threshold. Full phase 2/3 qualification and required CI remain unfinished. + +### Certified landed DF32 Adams and portable history — 2026-11-11 + +The reviewed complete-factor flow now attaches to the internal Python preparation +and session boundary. It certifies nonuniform coefficients, phi absolute errors, +transported sampled rates and complete source/compensation/defect factors before +narrowing. Certification precedes startup source charges and accepted-state writes. +Two fixed banks and all rate-provenance storage are inventoried; warmed leaf trials +retain zero allocation in the reviewed CPU witnesses. The independent leaf review +passes 26,755 distinct assertions, including MPFR and exact-rational checks, conditional +FFT/source sensitivity bounds, retained-history ages and generated arithmetic. + +Python detaches and preflights a candidate portable history using the engine's actual +compatibility checks before its age enters phase admission. Incompatible history +selects a named field reset. The immutable binding and actual restore consume the +same selected data; neither rereads discarded caller rows. The portable schema carries +no previous wide type, so imported rate provenance is explicitly unknown and its +error is reconstructed from the represented operator and actual saved values. +No scientific hash, physical scaling, raw storage type or noise policy changes. + +Independent integration review found and corrected two boundary cases: a completed +compensated restart needs no numerical rate certificates (747), and the history +coordinate enclosure must include admitted predictor coordinates beyond the rounded +landing endpoint (748). Completed starts retain raw history without inventing a phase, +trial or source call. The established layout, alias and numerical-refusal ordering is +preserved. A direct inconsistent factory call cannot silently discard supplied history. + +The managed regression run passes 51 cases, comprising 23 new Adams cases and 28 +existing history, RK, low-storage and group regressions. Six independent factory +witnesses cover accepted sample slack, completed history and actual raw/canonical +replay endpoints. Two further group cases pass for mixed plain/compensated members +and a phase refusal before any seed source call. Targeted Julia checks pass 998 +assertions; unfiltered CPU Aqua/JET +passes 16 checks with all 2,217 definitions analyzed and none cached. Pure boundary +and CI-inventory checks pass 204 cases. Earlier constructor, fixture and source-identity +failures remain recorded alongside the corrected results. Public binary32 admission, +DF32 dense/spatial execution, physical admission comparisons and devices remain open. +The numerical derivations and conditional hypotheses are in `julia/DF32_ADAMS.md`. + +### Vendor execution and transform foundations — 2026-11-11 + +CUDA and Metal execution/FFT foundations have independent source and device review. +They retain explicit task/context/queue ownership, protect caller and plan buffers, +and preserve owners until error-path synchronization completes. CUDA's actual NVIDIA +A40 suite passes 418 assertions under network isolation. Metal's Apple M5 Max suite +and independent witnesses pass 308 assertions. These establish the tested execution +and transform behavior. Complete propagation and numerical qualification remain open. + +Both vendor quality runs pass Aqua but fail unfiltered JET and concrete analyses +(741, 745). CUDA foreign-context coexistence and released native-cache retention remain +open (733, 736). Metal's native FFT graph-cache/workspace retention is unmeasured (743), +and unsupported odd real lengths and high transform axes refuse before planning (744). +Metal precise arithmetic probes exhibit subnormal loss, including a normal-input FMA +correction, so the current DF32 gradual-underflow proof does not qualify that device +(739). No floating-point policy or required gate is relaxed. ROCm foundation and all +complete vendor sessions remain under implementation. + +### Reduced plasma coordinates and repeated CPU32 admission — 2026-11-11 + +The reviewed binary32 plasma lookup now retains reduced logarithmic coordinates +and low words instead of subtracting two rounded absolute logarithms. The spline, +cycle quadrature, clipping and convergence tolerance are unchanged. Independent +review passes 37,243 distinct assertions, including MPFR error witnesses, the +failing neighborhood and zero warmed allocation. ADR-080 makes the CPU Float32 +elementary-function boundary explicit: library internals may widen, whereas owned +response arithmetic and arrays remain binary32. Protected DF32 helpers retain +their strict graph, and each vendor needs independent arithmetic qualification (751). + +The unchanged six-case Adams-versus-RK campaign now completes every candidate after +the shared logarithmic power-weight correction (737) and plasma correction (738). +Both argon field and envelope cases pass at both tolerances. Both helium rows pass +every absolute accuracy envelope but fail SEP 33's twice-RK criterion (753). The +independent binary64 reference check now also halves the step cap: 16 versus 32 +accepted steps differ by at most `2.514e-15` across the scored metrics. Candidate +windows, method policy and thresholds are unchanged. The complete evidence and +remaining comparison are in `julia/CPU_SINGLE_ADAMS_QUALIFICATION.md`; the failure +remains an ordinary required test and public binary32 admission remains closed. + +### Maintainer-approved completion baseline — 2026-11-11 + +The maintainer narrowed this implementation's completion target to **binary64 CPU +and CUDA**, deferring Metal and ROCm/HIP. Binary32/DF32 CPU is secondary: finish the +already reviewed RK dense engine attachment, preserve the existing implementation +and exact evidence, and defer its remaining qualification and public admission. +The accepted Part I remains the historical full proposal; this recorded scope +amendment supersedes its all-vendor/all-precision merge requirement for this PR. +The binary64 CPU/CUDA baseline still requires its complete session contract, +supported physics/method catalogue, independent review, measurements and green gates. + +Metal's subnormal incompatibility (739) and vendor qualification work (743–745), +ROCm's hardware/quality work (750), and the unfinished binary32/DF32 qualification +remain deferred work, with no tolerance relaxation or claim of successful execution. +The current narrow-precision state and exact outstanding tasks are recorded in +`julia/DEFERRED.md`. In particular, both helium Adams comparisons remain failures +of the unchanged twice-RK rule (753). Deferred qualification is explicitly separate +from the baseline gate; admission/refusal and retained-code regression tests remain. + +The maintainer also directed that new issues track only work the implementation PR +will leave unresolved. In-PR defects and their corrections belong in its working +record and review, rather than separate issues. + +### Binary64 CPU checkpoint and implementation pause — 2026-11-11 + +The maintainer requested a recoverable pause after narrowing completion to binary64 +CPU and CUDA. Public CPU selection is usable for the admitted scalar modal/spatial +session catalogue. Package/runtime, session and service implementations are retained; +final full qualification, isolated startup/worker measurements and the required CI +gates remain outstanding. No phase is declared Final at this checkpoint. + +The reviewed CUDA source, RK/low-storage, storage, export and selected-execution bridge +work is integrated. Raman/plasma factories and RK dense observations retain the shared +CPU/device numerical recipes. Device Adams is frozen pending independent review; +statistics/temporal construction is an unfinished draft, and spatial attachment has +not started. The maintainer reaffirmed one numerical implementation with backend +allocation, launch, transform and transfer primitives; the Julia working rules now +make that boundary explicit. Metal, ROCm/HIP and unfinished binary32/DF32 qualification +remain deferred under the preceding amendment. + +Actual A40 qualification of a fixed intermediate source snapshot reports 2,663 passes, +nine retained-payload assertion failures and three private-runner import errors. +The march, modal source and export leaves pass their executed numerical checks. +Independent review verifies the test correction for pinned CUDA allocation padding; +its hardware rerun remains pending. Unfiltered vendor JET still fails and blocks +qualification. The latest inspected CI passes static checks but Linux package-install +DNS failures still prevent required gates from running. No failed or unrun check is +claimed green. The current plan, integrated milestones, evidence and exact remaining +work are in `julia/IMPLEMENTATION.md`; this pause leaves PR 611 in draft. + ## Part III — History +- 2026-11-11: The maintainer selected binary64 CPU/CUDA as the completion baseline, + with Metal, ROCm/HIP and remaining binary32/DF32 work deferred as recorded in Part II. + +- 2026-11-10: The maintainer accepted external hard-kill supervision for stalled Julia + SIGTERM shutdown and directed numerical implementation to proceed before further + runtime investigation; Part II and ADR-078 record both decisions. +- 2026-11-10: The maintainer accepted main-thread-only Python entry into Julia after + the phase 1 probes reproduced a worker-thread GC deadlock. Part II and ADR-077 record + the amendment and ownership requirements; Part I remains the accepted historical text. +- 2026-11-10: Proposal accepted and merged in PR #609 at `04e72192`, after GitHub CI + and the required documentation preview passed. Implementation began on the single + feature branch; its ownership, partial milestones and remaining qualification are + recorded in `julia/IMPLEMENTATION.md`. No implementation phase is declared complete + by the package foundation alone. - 2026-11-10: Drafted by Opus 5.5 for John Travers, after a feasibility analysis of PR #559. The maintainer chose an explicit setup over a first-use install, all three GPU vendors and binary32 at merge, and Runic, Aqua and JET as the blocking Julia tools. diff --git a/docs/dev/tooling.md b/docs/dev/tooling.md index eea8b5cd1..5db3519f6 100644 --- a/docs/dev/tooling.md +++ b/docs/dev/tooling.md @@ -240,6 +240,18 @@ jaxtyping hook) run in the coverage lane only; the other test lanes set - **no-native** (Linux): a few modules of the default lane with no native package and `SOLPROP_TEST_BACKEND=numpy_ref`: that `backend="auto"` refuses there, and a real run on `numpy_ref` by name. +- **julia** (Linux on non-documentation changes; macOS arm64 on Julia changes and + weekly): two independent stages each publish and verify the pinned CPU setup and + check coexistence with the matching native package. The engine stage runs Runic, + bounds-checked Core tests, Aqua and unfiltered JET error analysis. The adapter stage + runs the complete Python Julia suite, runtime subprocess probes and shared session + conformance, then verifies that every mandatory module produced passing results. + Both stages check that committed Julia inputs stayed unchanged, including after a + failed check; neither stage cancels its sibling on failure. Each has a three-hour + bound because the former combined Linux job exhausted two hours while progressing + through its adapter tests (#712). This separate lane covers the optional Tier 3 + adapter's explicit omission from default Python coverage; the rest of solprop + retains the required 100 % coverage gate. - **native-quality** (Linux, three jobs): `uv run poe check-native`, the native package's gate (`native/scripts/check.sh`), split by `SOLPROP_NATIVE_CHECK_STAGES`. The jobs are its lint and strict types, clang-format and its pytest suite (`lint pytest`); diff --git a/docs/guide/numerics/linear-operator.md b/docs/guide/numerics/linear-operator.md index a1e645c18..a207bc267 100644 --- a/docs/guide/numerics/linear-operator.md +++ b/docs/guide/numerics/linear-operator.md @@ -23,7 +23,11 @@ where $a$ is the internal vacuum-normalised modal amplitude, $N_m$ the nonlinear explicit constant index a run declares in its place. The saved amplitude is the true-power $b=\sqrt w a$ ([power, energy and intensity](../results/power-and-intensity.md)); the logarithmic term keeps its energy right where $w$ varies along z, and vanishes for a constant fill and -on the GNLSE mapping. The **dispersion operator** +on the GNLSE mapping. Near unity, its logarithm is evaluated as +`log1p(Re(n_eff - 1))`, using the mode's cancellation-free refractivity. This preserves +small changes along a pressure gradient instead of interpolating the rounding noise +introduced by first adding unity. Positive indices far from unity retain the ordinary +logarithm of the validated power weight. The **dispersion operator** $$ D_m(\omega, z) = -\mathrm{i}\bigl(\beta_m(\omega, z) - \beta_0(z) - \beta_1(z)(\omega - \omega_0)\bigr) diff --git a/docs/guide/performance/devices.md b/docs/guide/performance/devices.md new file mode 100644 index 000000000..c59d8227b --- /dev/null +++ b/docs/guide/performance/devices.md @@ -0,0 +1,81 @@ +# Execution devices + +Choose a device in `SimulationSettings.device`. It controls where a backend executes; +it does not change the translated scientific problem. The names are `"cpu"`, +`"cuda"`, `"rocm"` and `"metal"`. The default, `None`, accepts the backend's default +target. Unsupported choices raise a named error before numerical preparation. + +| Backend | `device=None` | Explicit device | +|---|---|---| +| `native` or `auto` | The installed native build's target | Must match that build: `cpu`, `cuda`, or `rocm` for a HIP build | +| `numpy_ref` | CPU | `cpu` | +| `julia` | CPU | Currently `cpu`; GPU execution remains refused until each extension is qualified | + +`auto` still selects native, without fallback. Setting `device="cpu"` on a CUDA +native build refuses; it does not switch the build or select another backend. Metal +requires `precision="single"` (binary32); this requirement alone does not enable its +currently unqualified Julia execution path. Backend setup and precision admission are +separate checks. See [native builds](building-native.md), [Julia](julia.md) and +[single precision](single-precision.md) for the qualified numerical routes. + +```python +from solprop.driver import SimulationSettings + +settings = SimulationSettings( + save_planes=[0.001], + dz_max=0.0001, + dz_init=0.00001, + backend="numpy_ref", + device="cpu", +) +assert settings.execution_options().device == "cpu" +``` + +Device and `backend_options` travel with the existing settings through runs, reusable +runners and spawned scan workers. Each options mapping is copied. For example, a +Julia setup identity is supplied as `backend_options={"setup_id": "..."}`. The chosen +backend validates its options; another backend does not silently ignore them. + +These execution choices may change after translation. They stay outside scientific, +configuration and restart hashes, so changing a device does not change which physical +calculation a file describes. Execution metadata records the effective device. A runner +retains its preparation's owned execution choices: changing them requires a new runner. +Scan workers rebuild a cached runner when a later point selects different execution +choices, including a different setup identity or node budget. + +## Recipes + +Use the same execution table on every route: + +```toml +[execution] +device = "cpu" +backend_options = { setup_id = "published-setup-identity" } +``` + +The mapping in this example is a Julia option; keep it empty for a backend that does +not accept it. A recipe writes `device = "none"` for the default selection. Python +export writes Python `None` and preserves the options mapping. A recipe's scan builder +passes these settings to each point without starting a backend in the parent process. + +The older object-route spelling `[build.settings].backend_options` remains accepted. +If both spellings appear they must be equal; conflicting mappings refuse by name. +Resolved recipes write the current mapping only in `[execution]`, and changing these +choices retains the recipe and its scientific identity. + +## Require a GPU in a job + +`SOLPROP_REQUIRE_DEVICE` is a guard on a selected target, not a device selector: + +| Value | Required effective target | +|---|---| +| `cuda` | Native or Julia CUDA | +| `hip` | Native HIP or Julia ROCm, both named `rocm` by settings | +| `metal` | Julia Metal | +| `any` | Any of these GPU targets | + +An unset or empty value imposes no GPU requirement. The guard never redirects a CPU +request, loads a GPU package on its own, or enables an unqualified extension. A native +GPU build must also report a visible device. Leave the variable unset for CPU runs. + +This execution control follows [SEP 48](../../dev/seps/sep-0048-julia-backend.md). diff --git a/docs/guide/performance/index.md b/docs/guide/performance/index.md index 814c70f53..37e05732d 100644 --- a/docs/guide/performance/index.md +++ b/docs/guide/performance/index.md @@ -19,7 +19,9 @@ measurement rules and indicative results, and calibration backends +devices native +julia building-native resources progress diff --git a/docs/guide/performance/julia.md b/docs/guide/performance/julia.md new file mode 100644 index 000000000..1747e8480 --- /dev/null +++ b/docs/guide/performance/julia.md @@ -0,0 +1,382 @@ +# The optional Julia backend + +Julia support is being implemented under [SEP 48](../../dev/seps/sep-0048-julia-backend.md). +The package and explicit setup commands are available on its implementation branch. +Numerical sessions and device qualification remain in progress; installing a device +environment does not establish that its propagation kernels are qualified. + +The maintainer-approved completion baseline is binary64 CPU and CUDA. CPU selection +is available on the implementation branch; CUDA sessions are still being integrated +and qualified. Metal, ROCm/HIP, and public binary32 execution with either wide +arithmetic option are deferred. DF32 replaces selected wide intermediates alongside +binary32 state and FFTs; it is not a separate whole-state precision. Their +internal implementation and test evidence do not make them supported selections. + +Select the prepared CPU engine with `SimulationSettings(backend="julia", ...)`. +`backend_options={"setup_id": identity}` selects an explicit published setup; omitting +the identity requires exactly one compatible setup. Availability checks probe the +bridge installation without importing Julia; the first preparation verifies setup. + +The current integration supports scalar modal fields and envelopes in binary64 +with Kerr, Raman and plasma responses and Runge–Kutta or exponential Adams stepping, +including adaptive and fixed replay schedules. Fixed schedules also support the +three-register low-storage RK4IP method, which records no embedded error estimate. +Constant, tabulated and expanded +operators, prefactors and power weights keep their full represented variation. Each +material response uses its own density, decay and preionisation profiles; taper scaling +follows the translated mode map. +Scalar radial, Cartesian and line propagation is also attached. Radial propagation +retains its translated quadrature and padding factors; Cartesian and line propagation +use spatial FFTs and the represented longitudinal root. A physical transverse absorber +remains a source term even when no material response is present. Spatial exports retain +their spatial measure and do not apply the modal power-normalization flag. +Julia owns the stepping loop, error control, bounded attempt history and event barriers. +Plane and periodic scalar modal statistics are evaluated inside Julia from the current +field. The packed catalogue, frequency windows and independently represented material +profiles belong to each run request. Periodic cadence counts accepted steps and is +unchanged by event yields. A failed copy can retry the same closed chunk; acknowledgment +drains it only after its complete values are owned by Python. Already delivered rows +remain readable after session cleanup. +Temporal monitoring also belongs to Julia: launch checks, accepted-step cadence, +guard decisions and cumulative removal are evaluated there. Python formats the +shared record and warning types from the numerical facts. A warning pauses at a +closed service barrier, with a valid export ticket if a warning filter turns it +into an error. Monitor continuation restores its original launch, cumulative totals +and saved rows; it does not judge a resumed launch again. The first continuation +supplied in `Start` takes precedence over a later output-record fallback. Monitor +metadata remains readable after the session closes. +Binary64 input noise uses the supplied draw without generating another realisation. +Julia adds it once at a fresh problem launch and applies the active-band mask; a +resumed field already contains its draw and never receives it again. The draw remains +available for the monitor's noise floor. Phase exports evaluate the cumulative unitary +phase at the selected observation coordinate, including a dense plane, and preserve +represented absolute offsets. Each start selects its own draw, so reusing preparation +does not reuse an earlier start's replacement noise. Modified noise and every binary32 +noise configuration remain refused. +Snapshots, cooperative stops and field exports use the same session contract as other +backends. An acknowledged event invalidates its export ticket; arrays already returned +to Python remain valid. Failed output consumers can recover an undelivered history chunk +once, without repeating numerical work. + +Fixed-schedule groups use Julia's member-session coordinator. Members must share the +method and complete tableau, itinerary, landed observation planes, shape, precision, +norm mask, statistics policy and execution choices. Construction validates these +before consuming any entrance field; interrupted construction leaves the original +starts and caller-owned backends available for retry. Julia chooses every member turn; +Python publishes a complete common window and copies each member chunk once. A failed +publication retains its assembled chunks for retry without further numerical work. +Stops and failures preserve each member's actual committed position, history and +available field ticket, and share one primary error. Closing the group closes its +adopted owners. Group resume and interpolated group planes remain refused. + +Adams receives its controller and landing constants from the shared resolved method +policy. Its execution record distinguishes logical response-call charges from actual +source invocations, including structurally absent sources, and retains compact accepted +order counts. A spent call budget stops before the next trial and carries the last +accepted field. Portable binary64 Adams snapshots retain that raw state, every history +row, the selected sample positions and the next controller state. Compatible history +continues without an extra startup evaluation; cumulative charges and compact orders +also survive a field-only restart. History identity uses the shared method key, not a +Julia setup, thread count or backend name. Incompatible keys, precision or store layouts +produce the shared explicit field-reset reason before any history is installed. +Short fixed-history continuation between Julia, the NumPy reference and native CPU is +tested in both directions involving Julia. Plain and compensated stores retain every +row exactly. Adaptive Adams can retain its accepted step and evaluate all crossed +observation planes without replacing the committed state or calling the source again. +Statistics and field conversion use the plane's own coordinate. An interior plane has +no portable history from the endpoint ahead of it; it can restart from its exported +field. Snapshot requests wait until the owed planes are delivered, then save the +committed endpoint and its history. Dense output remains incompatible with fixed replay +and split temporal absorption, as in the shared policy. + +Adaptive DOPRI5 uses the shared continuous-extension weights for the same dense +observation contract. Other tableaus without a shared extension refuse interpolation. +Endpoint periodic rows accompany their accepted attempt before the first crossed +plane is delivered; later dense planes do not repeat those rows. A plane consumes the +previous stage's quadrature diagnostic, so another plane reached without new source +work reports that diagnostic as unavailable. Both dense methods pass the common +session ordering, snapshot and bounded-yield checks. + +Scalar modal runs also support the existing `split_step` temporal absorber. It applies +one coarse-time amplitude factor `exp(-alpha*dz/2)` after each accepted trial, between +the initial and final active-band masks. It is a one-sided Lie split with its existing +order limitation; the default in-stage scheme is unchanged. Split finishing attaches +even when no statistic or boundary monitor is requested, and a quiet monitor verdict +never omits this factor. The split rate does not also enter the nonlinear source. + +Low-storage execution records preserve the established `source_evaluations` count +of committed steps and separately report `attempted_source_evaluations` and completed +`norm_evaluations`. If an in-place trial fails, its attempted calls remain visible and +its field is poisoned, so no field-export ticket is issued. + +Low-storage propagation accepts `propagator_mode="tabulate"`. A session owns one +factor table for a constant linear operator, or two for a represented varying one. +Constant tables match the actual floating-point interval length exactly; varying +tables match both endpoints. An interval change rebuilds the factors without +interpolation or a step tolerance. `auto` tabulates constant low-storage flows; +other method families continue to recompute, as reported in execution metadata. + +Default field-plasma diagnostics (`plasma_undershoot`, `plasma_work_defect`, and +`plasma_boundary_level`) use a fresh population scan of the observed field. Each +ratio divides separate global maxima over all channels and nodes, after combining +chunks. These diagnostics and the three species inventory/peak rows are plane-only. +`species_ionisation_energy` reports final ionised inventory in J/m, including the +initial preionised fraction. It uses the physical transverse weights and represented +area/taper at that plane; it is distinct from newly deposited ionisation work. +Passive species keep their catalogue positions and zero ionisation potential. + +The four `on_axis_*` plasma statistics reconstruct the fine-grid axis field +independently at each saved plane. They require a resolved modal plasma route and +the original physical modes. Field simulations retain both real Cartesian field +components. Envelope simulations admit a scalar envelope along a fixed real +polarisation direction: the represented axis-map rows must be exactly proportional, +including zero rows. A general elliptical envelope refuses by name. These rows are +plane-only and do not reuse the last nonlinear stage's populations. + +For represented constant unit modal power weights, `physical_energy`, `analytic_flux` +and `spectral_flux` are available. Other weight representations refuse these three +names; use `energy` and `peak_power_total` for weighted modal power. Spectral flux +uses its per-angular-frequency density weights in J/(rad/s), independently of the +Parseval endpoint weights. Physical energy and analytic flux also support periodic +rows; spectral flux is plane-only. + +Public CPU selection uses the same preparation and session contract as the other +backends. Unsupported combinations refuse by name before session allocation. +The current session supports in-stage and split temporal absorption. Transverse monitor +attachment now uses the same event barriers as temporal monitoring. It retains original +clean launch columns for noise-floor subtraction, restores per-face cumulative totals, +and uses the first explicitly supplied continuation, including an absent edge record. +An older checkpoint without an edge continuation initializes its baseline from the +resumed field. Python formats the shared warnings and summaries from detached Julia +readings; it does not recompute edge decisions. Vector +polarisation, tensor Raman, general modal and planar routes, coupled flows, TDSE and +dispersive Kerr remain outside SEP 48's admitted scope and refuse by name. +`SimulationSettings.node_budget` bounds the retained numerical array payload that grows +with the source node chunk, population observations and transverse trace chunk together. +The planner uses each actual prepared request, including statistics or monitors added +after construction. Immutable numerical inputs remain shared; each prepared request +keeps its own capacity. A budget smaller than one node refuses before Julia starts. +The default budgets are 64 MiB for modal/radial work and 1 GiB for Cartesian/line work. +The lower-level `ExecutionOptions.node_chunk` overrides the budget for controlled +measurements, capped at the physical node count. These execution choices do not alter +scientific identities. + +This is an array-payload budget, not a total process-memory limit. Metadata separately +reports fixed and full-volume workspace arrays, the component inventory, opaque FFT +plans and exclusions. Immutable preparation, state/history/export storage, bounded +transport records, object overhead and temporary planning allocations remain outside +the node budget. The complete retained-memory ledger remains available separately. + +The scalar statistics catalogue includes spectral centroids, energies and frequency +windows, peak powers, temporal widths, material profiles and populations, and on-axis +peak intensity when the original physical modes are supplied. The quadrature diagnostic +is NaN at launch and when no distinct embedded projection exists. Short same-field CPU +comparisons use explicit transform and reduction bounds and certify temporal-width +brackets separately; they do not assign a generic relative tolerance to material rates. +Complete route/catalogue qualification remains part of phase 2. +Spatial saved-field observations include physical flux energy, peak and on-axis +intensity, on-axis spectrum and beam widths. Their closure uses a separately translated +flux descriptor, including its own material representation. The on-axis spectrum uses +the shared spectral-density normalization. Width comparisons require stable peak and +threshold-crossing margins; a generic relative tolerance does not certify them. + +Binary32 remains unavailable through public backend selection while qualification +continues. Its internal CPU paths now include material responses, observations and +monitors; short tests compare physical energy bands and other observables against +refined binary64 references. Binary32 input noise remains refused. + +The reviewed double-float exponential, phase-reduction and phi-function kernels have +conservative function domains and explicit underflow assumptions. Internal landed +RK and low-storage sessions now bind the original operator and actual start, then +certify each actual trial in Julia before source work. Short field-restart and group +checks also pass. The internal landed Adams flow also forms certified complete factors +and binds only compatible portable history, preserving explicit field-reset reasons. +Completed restarts retain raw history without evaluating another source or factor. +The complete restart matrix, dense and spatial execution still need qualification +before public selection. Admission must include actual replay steps, +every represented operator interval and restored history, including the arithmetic +that forms each exponent before the functions receive it. + +The engine precompiles representative serial CPU sessions during explicit setup. This +reduces first-use compilation for those paths; new shapes, responses and thread +configurations may still compile on their first use. The workload changes no process +thread policy and stores no mutable simulation state. + +CPU preparation shares solprop's host BLAS limits. The default is one BLAS thread; +`SOLPROP_BLAS_THREADS` requests another width within the process budget. Overlapping +construction and Julia preparations retain the narrowest active request, and release +restores the previous width only after the last owner finishes. Metadata records the +actual controllable libraries and their current widths. OpenBLAS is the provider on +Linux and other supported platforms. On macOS with the new LAPACK ABI and documented +calling-thread controls (macOS 15 or later), Julia forwards BLAS/LAPACK to Accelerate +and retains OpenBLAS for symbols Accelerate does not provide. Missing capabilities +leave OpenBLAS selected, with the reason recorded in execution metadata. + +Accelerate offers automatic or single-thread mode, so a Julia preparation keeps it in +single-thread mode even when a larger BLAS width was requested. That mode belongs to +Python's main OS thread and affects all Accelerate callers there, including NumPy and +native code using the same framework. Independent BLAS libraries keep their ordinary +count limits. The last preparation restores the exact previous Apple mode; metadata +records the requested width, actual single mode and its calling-thread scope. Julia's +worker threads do not inherit this setting; the current engine's parallel matrix maps +use its own kernels. See [ADR-079](../../dev/decisions.md#adr-079--verify-julias-cpu-blas-provider-and-lease-its-real-controls). + +CPU starts plan against their own transform arrays and keep successful FFTW measurements +in the calibration store. Cache identities include the actual loaded FFT libraries and +their inventoried artifacts, Julia and engine versions, CPU topology, target and effective +preferences. Each transform key includes its shape, strides, transform kind, precision, +alignment and actual planner thread count. Reusing a prepared execution refreshes its +offers, including plans measured by earlier starts in the same process. +`SOLPROP_FFTW_PLAN` selects `estimate`, `measure` (the default) or `patient`. +`SOLPROP_CALIBRATION=off` retains new plans only in the process unless an explicit +`SOLPROP_FFTW_WISDOM` path is supplied. That override names a Julia-specific file beside +the requested path. Invalid or unusable cache files produce a warning and leave planning +available. A failed optional file write also leaves successful numerical preparation +usable. `solprop calibrate --clear` removes compatible plans for the current topology +and forgets process offers, without loading Julia or changing already-created plans. +Execution metadata reports measured, applied and reused **distinct transform keys**, +cache rejections and whether a file was supplied or written. Wisdom strings are released +after construction; the session retains only its actual plans and compact metadata. + +The internal execution owner also supplies isolated timing probes for cost estimates. +Julia owns their loaded field, stages, source, norms and accepted-step finishing. A probe +creates no session, monitor, history or output event, and a normal embedded trial does +not advance its loaded state. Its field readback is an owning host copy available once +per trial. Low-storage probes update discarded registers and have no readable trial +field. Closing the execution owner closes its probes before releasing preparation. + +## Install and inspect + +The extra installs the Python bridge, JuliaCall. Julia and its packages are installed +only by an explicit setup command: + +```sh +pip install "solprop[julia]" +solprop julia setup +solprop julia status +``` + +The [Python setup interface](../../api/julia.md) provides the same operations for scripts. + +Setup uses Julia 1.13.3 and matching JuliaCall/PythonCall 0.9.37. An existing Julia +executable can be supplied with `--julia`; another patch in the 1.13 series is recorded +as untested. A different minor series requires new manifests and qualification. +Installing solprop without the extra, importing solprop, and selecting another backend +do not initialize Julia. + +The default setup prepares the CPU environment. Add a device explicitly: + +```sh +solprop julia setup --device cuda +solprop julia setup --device rocm +solprop julia setup --device metal +``` + +Metal requires macOS on Apple silicon. ROCm requires a discoverable system installation; +missing required ROCm libraries are reported before runtime startup. +The qualification targets are Linux x86-64 and macOS arm64. CPU setup also installs on +Linux aarch64 and Windows x64, which remain unqualified; Windows arm64 is refused. +CUDA on Linux aarch64 refuses until setup identity distinguishes Jetson from SBSA and +records the selected driver platform. These use different artifacts in the pinned +[CUDA runtime selector](https://github.com/JuliaBinaryWrappers/CUDA_Runtime_jll.jl/blob/CUDA_Runtime-v0.25.0%2B3/.pkg/platform_augmentation.jl#L463-L499) +and [driver selector](https://github.com/JuliaBinaryWrappers/CUDA_Driver_jll.jl/blob/CUDA_Driver-v13.5.0%2B0/.pkg/platform_augmentation.jl#L27-L62). + +CUDA setup can fetch a specified toolkit without a GPU, for a later compute-node run: + +```sh +solprop julia setup --device cuda --cuda-runtime 13.4 +``` + +The default toolkit release is recorded in the bundled CUDA environment. When sharing +a process with a native backend built against a system CUDA toolkit, prepare Julia with +`--cuda-local` so both use that toolkit. This requires the toolkit on the setup host. + +## Published identities + +Every successful setup prints an immutable identity. Status lists all published +identities, their source and bridge versions, installed devices, CPU target, depot size, +and any reason they cannot be used. Setup keeps an owned source copy, so removing the +Python environment that created it does not remove the engine. + +Changed engine sources, preferences or installed device selections produce a different +identity. Selection without an explicit identity requires exactly one compatible setup; +ambiguity reports the available IDs. The session interface selects an +identity through the `setup_id` backend option and records it as execution metadata. + +`SimulationSettings.backend_options` carries backend-specific execution choices. It +defaults to an independently owned empty mapping, and preparation takes another owned +copy through `settings.execution_options()`. These choices survive spawned workers and +may be replaced after translation without changing the scientific configuration or +restart identity. The selected backend refuses unsupported keys before constructing a +workspace. The Julia adapter admits `setup_id` and `wide`; the existing native and +NumPy reference backends accept no backend-specific keys. +Recipes that construct `SimulationSettings` carry this mapping under +`build.settings.backend_options`; TOML round trips and Python export preserve it. + +The first preparation fixes the process's runtime, depot and installed environment +stack. A different setup, another depot, or a device installed after initialization +requires a fresh process. Every Julia-facing operation must run on Python's main thread +in each process, including preparation, device loading, advancement, export and close. +Calls from Python worker threads refuse before entering Julia. Julia's own parallel +CPU work remains supported; use spawned processes for concurrent simulations. Setup, +status and cancellation requests do not enter the embedded runtime and can be used +from other threads. Do not fork a process after Julia has initialized. An initialization +or extension-loading failure requires a fresh process because the runtime cannot be +safely unloaded. + +Close each prepared execution and session explicitly on main. Abandoned Julia handles +are retained until the next main-thread operation or process shutdown, so Python garbage +collection on another thread cannot destroy Julia objects there. Returned public arrays +own Python storage, and engine errors are formatted on main before leaving the adapter. +This restriction avoids a reproduced Julia 1.13.3/PythonCall 0.9.37 garbage-collection +deadlock on both macOS and Linux; [issue #620](https://github.com/LupoLab/solprop/issues/620) +records the evidence and the accepted scope change. + +## Offline and cluster use + +Setup downloads the selected package and artifact closure, verifies it, and publishes +an inventory only after precompilation succeeds. Runtime startup and a new device +extension check the installed stack before loading. Missing artifacts refuse with a +setup command; runtime execution does not repair them by downloading. + +`SOLPROP_JULIA_DEPOT` selects a private depot outside the default calibration store. +For a heterogeneous CPU allocation, choose a compatible compilation target when +preparing it: + +```sh +solprop julia setup --cpu-target generic +``` + +Status reports the CPU name and target used for precompilation. Julia validates native +code caches and recompiles when necessary at load. Sources, manifests, preferences and +artifact contents remain part of the installation's identity. Do not edit them in a +published setup or add Julia artifact overrides, alternate preference files or workspace +configuration. Explicit setup can restore entirely missing shared trees; existing +corrupt trees refuse. Prepare a fresh private depot when the original cannot be repaired +without altering published inputs. + +## Cancellation and signals + +```{warning} +Once Julia initializes, SIGTERM may terminate the entire process without delivering +pending output or writing a final checkpoint. This also applies to custom or ignored +Python SIGTERM handlers, while the process is idle, and after a Julia session closes. +Fatal shutdown can also stall during garbage collection. A supervisor that needs a +bounded process lifetime must enforce an external deadline and send SIGKILL if the +process has not exited. Neither signal guarantees a final checkpoint. +``` + +Graceful cancellation uses cooperative stop tokens. The bridge preserves the +application's actual SIGINT handler, including an ignored handler, for Python Ctrl-C +handling. Julia keeps the signal machinery needed by its threaded garbage +collector; disabling that machinery is not a supported workaround. + +The maintainer accepted both limitations for Julia 1.13.3. A second SIGTERM ended one +diagnostic stall, but it is not the hard deadline mechanism. Use cooperative stop tokens +for normal cancellation and an external process supervisor for forced termination. +[Issue #610](https://github.com/LupoLab/solprop/issues/610) tracks revisiting it with stable +Julia 1.14 and compatible device packages. An upgrade alone is not evidence that signal +preservation is fixed. + +The complete scope, qualification requirements and implementation reports are in +[SEP 48](../../dev/seps/sep-0048-julia-backend.md). diff --git a/docs/guide/performance/resources.md b/docs/guide/performance/resources.md index 36e518cc1..22b13a5c4 100644 --- a/docs/guide/performance/resources.md +++ b/docs/guide/performance/resources.md @@ -33,7 +33,7 @@ error. Under Slurm, `sacct` reports such a job as `OUT_OF_MEMORY`. To see the size first, {py:meth}`~solprop.driver.simulation.Simulation.estimate` builds the backend and reports what it holds; a backend's -{py:meth}`~solprop.backends.protocol.Backend.memory_ledger` names every buffer, so you +{py:meth}`~solprop.backends.protocol.ExecutionBackend.memory_ledger` names every buffer, so you can see which one to shrink: fewer channels or nodes for the maps and the reference, a narrower frequency window for all of them. Nothing is ever approximated to fit. {py:meth}`~solprop.driver.simulation.Simulation.output_bytes` gives the output's size alone, diff --git a/hatch_build.py b/hatch_build.py index 63833296d..cc99c73c3 100644 --- a/hatch_build.py +++ b/hatch_build.py @@ -2,23 +2,28 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""Pin ``solprop-native`` and the ``gui`` extra to this release's own distributions. +"""Pin sibling distributions and bundle the optional Julia engine. solprop, solprop-native and solprop-gui are released together from one repository at one version (SEP 29), so solprop requires exactly that native version (SEP 43), and ``solprop[gui]`` that front end. The version is the repository's (hatch-vcs), known only when the metadata is built, so the runtime dependencies are written here. They are -dynamic rather than a pin over a static list: a wheel built from the sdist runs no -hooks, and reads only dynamic fields from the sdist's metadata. +dynamic rather than a pin over a static list: a wheel built from the sdist reads +dynamic fields from its metadata without rerunning the metadata hook. The separate +build hook includes the Julia package inputs and their engine digest in each wheel. """ +import runpy +import tempfile +from pathlib import Path from typing import Any +from hatchling.builders.hooks.plugin.interface import BuildHookInterface from hatchling.metadata.plugin.interface import MetadataHookInterface class NativePinHook(MetadataHookInterface): - """Write the dependencies, with native pinned, and the two extras.""" + """Write the dependencies, with native pinned, and the optional extras.""" PLUGIN_NAME = "custom" @@ -68,3 +73,61 @@ def update(self, metadata: dict[str, Any]) -> None: extras = metadata.setdefault("optional-dependencies", {}) # The desktop front end, from gui/ at this same version. extras["gui"] = [f"solprop-gui=={metadata['version']}"] + # PythonCall in the prepared Julia environments must match exactly. The + # base distribution never imports or installs this optional bridge. + extras["julia"] = ["juliacall==0.9.37"] + + +class JuliaBundleHook(BuildHookInterface): + """Ship the engine and its build-time digest without importing solprop.""" + + PLUGIN_NAME = "custom" + _temporary: tempfile.TemporaryDirectory[str] | None = None + + def initialize(self, version: str, build_data: dict[str, Any]) -> None: + """Add the Julia sources, environment inputs and exact digest to a wheel. + + Parameters + ---------- + version : str + Hatch's build version, including ``editable``. + build_data : dict + Hatch's mutable build configuration. + """ + del version + if self.target_name != "wheel": + return + root = Path(self.root) + bundle = root / "julia" + source = runpy.run_path(str(root / "src/solprop/backends/julia/_source.py")) + digest = source["engine_digest"](bundle) + self._temporary = tempfile.TemporaryDirectory(prefix="solprop-julia-build-") + digest_file = Path(self._temporary.name) / "_engine_digest.txt" + digest_file.write_text(digest + "\n", encoding="utf-8") + target = "solprop/backends/julia" + force_include = build_data.setdefault("force_include", {}) + force_include[str(digest_file)] = f"{target}/_engine_digest.txt" + # An explicit source inventory excludes developer records, caches and + # local evidence, including when building from a worktree or an sdist. + for path in sorted(source["bundle_files"](bundle)): + relative = path.relative_to(bundle).as_posix() + force_include[str(path)] = f"{target}/_bundle/{relative}" + + def finalize( + self, version: str, build_data: dict[str, Any], artifact_path: str + ) -> None: + """Remove only the temporary digest after Hatch has copied it. + + Parameters + ---------- + version : str + Hatch's build version. + build_data : dict + The completed build configuration. + artifact_path : str + The resulting wheel or source archive. + """ + del version, build_data, artifact_path + if self._temporary is not None: + self._temporary.cleanup() + self._temporary = None diff --git a/julia/ADAMS_PRECISION.md b/julia/ADAMS_PRECISION.md new file mode 100644 index 000000000..ae6e6e3c4 --- /dev/null +++ b/julia/ADAMS_PRECISION.md @@ -0,0 +1,209 @@ +# Adams precision implementation boundary + +This numerical leaf implements binary32 state with binary64-wide factors. It is not +public precision, session, physical-scale, device or DF32 admission. Sessions, bridge +records, portable history and public selection remain separate. The existing +binary64 numerical graph is preserved. + +## Storage and scalar contract + +`AdamsHistory`, `AdamsWork` and `AdamsDense` accept `AbstractMatrix{Complex{T}}`, +with `T` equal to `Float32` or `Float64`. State, source, predictor, candidate, defects +and retained sampled states use `Complex{T}`. Exponents, moments and sampled rates +always use `ComplexF64`. Geometry, polynomial coefficients and controller inputs +remain host binary64. Binary32 seeding, trials and dense reads convert their scalar +coordinates and steps to binary64 before validation, coefficient generation or +callbacks. The exponent callback receives the actual rounded pair `(z, z+h)`. The +numerical step remains `h`. These inputs are not identified after endpoint rounding. + +Copies refuse different state precisions before mutation. The binary32 norm adds +one Float32 mantissa and one integer exponent per row, and four Float32 reduction +entries per column. Binary64 keeps its existing two Float64 entries per column and +has no denominator scratch. All arrays belong to the existing recursive ledger. + +Binary32 does not keep unscaled transported sources: `carried` has zero planes. +`endpoint_compensation` retains its existing shape but is zero and unused on that +path. The source/state/rate history remains the actual sampled history. No generator +is narrowed or replaced by a derivative at another position. + +## Complete factors and protected defects + +Let `x` be the represented cumulative exponent over the actual endpoint pair, +`h` the supplied step and `c[j,k]` the prepared binary64 polynomial coefficients. +For each source sample, the binary32 graph first forms the complete wide factor + +```math +w_j = h\sum_{k=0}^{q} c_{jk} k!\varphi_{k+1}(x). +``` + +It rounds `w_j` once to complex binary32, multiplies the state-precision source, +and accumulates in complex binary32. The homogeneous factor is likewise evaluated +wide and rounded before multiplying state. There is no implicit binary64 state +accumulator. Binary64 retains the original monomial-first graph; these are different +floating-point evaluation orders of the same represented polynomial integral. + +A defect keeps the divided difference factored. For weights `a_j`, choose integer +`e` from `frexp(max(abs(a_j)))`. Form the protected state-precision difference +`sum(Float32(2^-e*a_j)*F_j)` in the original sample order. Multiply it by the once +narrowed complete factor `h*2^e*sum(b_k*k!*phi_(k+1)(x))`. Do not distribute that +factor across the subtractive difference. Weight underflow, when present, belongs +to the additive absolute rounding budget; it is not treated as exact arithmetic. + +For compensation, the mathematical identity is + +```math +h b_j e^{s_j x}(D_j-x/h)Y_j + = [b_j e^{s_j x}(hD_j-x)]Y_j. +``` + +`D_j` and `Y_j` are the actual stored rate and sampled state. Prediction and +correction use `s_j=1-theta_j`; an endpoint sample has `s_j=0`. The graph keeps the +wide multiplication `h*D_j` and subtraction of `x` separate, combines the complete +coefficient including `b_j` and transport, then narrows before its state product. +It recomputes that coefficient for predictor, corrector and defect terms. This +avoids an artificial range limit on an unscaled carried source. + +The ordinary binary64 product/subtraction can round to zero when the exact real +values of its supplied inputs have a nonzero residual. That result is a rounded +arithmetic zero, not a proof of an exact-real zero. In particular, it cannot waive +transport-domain validation. Exact zero weight, or both zero rate and zero phase, +are structural zero factors and need no transport. No FMA residual refinement or +DF32 claim is implicit in this graph. + +## Exponent-separated binary64 arithmetic + +Internal `_AdamsWideFactor` records a complex binary64 mantissa and an integer +power of two. Addition aligns exponents, then normalizes; multiplication operates +on normalized mantissas and adds exponents. It does not restore an intermediate +value to the binary64 exponent range. Consequently finite scalar coefficients such +as `h`, rates and polynomial weights may rescue underflowing or overflowing +intermediate products before final narrowing. The mantissa is ordinary binary64, +not an exact expansion. Alignment can discard tiny components, and cancellation +still carries an absolute error based on the pre-cancellation contributions. + +For transport, write `a=Re(s*x)` and choose +`n=round(a/ln2_hi)` (round to nearest, ties to even). For `|a|<=2^20`, compute + +```math +r = \operatorname{fl}(\operatorname{fma}(-n,\ell_h,a) + -\operatorname{fl}(n\ell_l)),\qquad + e^{s x}=2^n e^{r+i\,\operatorname{Im}(sx)}. +``` + +The constants are derived by rounding `log(BigFloat(2))` at 512-bit precision: + +- `ln2_hi = 0x1.62e42fefa39efp-1 = RN64(log(2))`; +- `ln2_lo = 0x1.abc9e3b39803fp-56 = RN64(log(2)-ln2_hi)`; +- the remaining absolute residual is at most `2^-109`. + +These are a derivation from the defining logarithm, not copied empirical tuning +constants. Tests independently regenerate both words and bound the residual. The +reduction is the exact identity `exp(a)=2^n*exp(a-n*log(2))`; it does not require +`n` to be the exact nearest quotient. Here `|n|<2^21`, exactly representable as +binary64, and the residual remains below one in magnitude. The checked interval +makes the integer conversion safe before `unsafe_trunc` is used. + +Writing `u=2^-53`, `eta=2^-1074`, the reduction error is bounded componentwise by + +```math +|\widehat r+n\log 2-a| + \le u|a-n\ell_h|+u|n\ell_l|+ + u(|a-n\ell_h|+|n\ell_l|)(1+u) + +|n|2^{-109}+3\eta/2. +``` + +The first term is the single rounded FMA result, the second the low-word product, +and the third the final subtraction. Exponential sensitivity multiplies this +absolute argument error by `exp(a)*expm1(error)/error`. Formation of `s*x` has its +own ordinary component multiplication error. Accuracy of the binary64 complex +exponential and phi implementation remains an explicit function-error hypothesis, +qualified by their independent witnesses; operation counts alone do not prove libm. + +Only the compensation graph uses this reduction. For `a < -2^20`, its remaining +finite factors have magnitude less than `2^3100`: `|hD-x|<2^2050`; a +prepared weight is less than `2^1024`, and a dense integral sums at most seven +terms with `0 2^20`, every nonzero computed normalized difference and nonzero finite +weight has product magnitude greater than `2^-32768`. A deliberately loose +computed-arithmetic bound suffices: each nonzero binary64 coefficient is at least +`2^-1074`, an inverse integer is at least `1/7`, and there are at most seven +multiplications by `xi>=2^-1074`. Allowing another 1074 exponent bits at each of +seven normalized Horner additions gives a dense-weight lower bound greater than +`2^-16400`. (An underflowed smaller aligned addend cannot cancel a nonzero dominant +one.) The product `hD` and subtraction of `x`, with another full 1074-bit allowance +for normalized complex cancellation, give a nonzero difference greater than +`2^-3300`. One further 1074-bit allowance for the final complex product still +leaves ample room above `2^-32768`. Thus the complete factor +cannot fit binary32. This side refuses before considering a cancellation-rounded +zero difference. Infinite positive transport, or a nonfinite imaginary transport, +also refuses. A negative infinite real transport selects the same underflow tail. +Phi factors do not occur in this transport-tail branch; their separate moment +sums stay exponent-separated until narrowing. These tail bounds use this finite +graph only, not arbitrary products or cancellation between different sample +contributions. Exact structural zero factors are exempt. + +## Error accounting and domain limits + +For either precision, write `gamma_n=n*u/(1-n*u)`. For binary32 let +`u32=2^-24`, `eta32=2^-149`. Each rounded real operation has absolute error at most +`u*abs(exact_result)+eta/2`, provided its computed result is finite. For complex +multiplication, sum the two absolute real products before cancellation in each +component. Powers of two are exact except for underflow; after alignment or +normalization the additive error is multiplied by the stored exponent. Propagate +these local bounds through the graph using absolute products and sums. + +In particular a compensation bound must retain `|hD|+|x|`, multiplied by the +absolute transport and weight, even when `hD-x` nearly cancels. Source factors +retain the sum of absolute polynomial-moment contributions. The defect bound +retains `sum|a_j F_j| * sum|b_k M_k|`, not the magnitude of the small resulting +defect. Errors in host coefficient generation, nodes, endpoint coordinates and +function values are separate inputs to that propagation. The existing coefficient +and phi tests qualify those inputs for the matched fixtures; they are not assumed +exact in a claim about an ideal continuous method. + +The committed matched-integral fixtures use at most seven samples, small finite +phases, independently evaluated 256-bit defining-series moments, and the actual +represented host coefficients. Their predeclared `gamma_(32*(q+1))` state budget +(`gamma_(64*(q+1))` for normalized defects) plus `gamma_8192` wide budget is applied +to those absolute contributions. The fixed eight-step witness propagates its +per-step allowance through the absolute two-register PEC matrix. These are +matched-history rounding tests, not global adaptive-error promises. Ill-conditioned +compensation may have a large absolute bound despite a small answer. + +A complete factor that cannot narrow finitely, a nonfinite callback result, or a +nonfinite state product/sum causes a named refusal before `work.ready=true`. +Scratch may contain an incomplete trial; accepted state and history are unchanged. +The interface does not promise closure merely because a mathematical final sum is +finite: a required state-precision product can overflow before later cancellation. +Coefficients still obey the existing finite binary64 preparation contract. There +is no new normal-range restriction on individual polynomial coefficients or steps. + +## Dense output, norms and integration obligations + +Dense output combines `h*k!*xi^(k+1)*phi_(k+1)(xi*x)` before narrowing. Powers of +`xi` also use exponent-separated wide arithmetic. The C32 ordinary compensation +integrals use a normalized binary64 Horner recurrence too; they are never restored +to an underflowing scalar before multiplication by the transported rate difference. +Its unused scalar `weights` scratch is cleared, without evaluating that unscaled +integral a second time. +The binary64 path retains its original ordinary-integral values. Exact endpoints +copy committed +state, including signed zeros. The existing strong-damping rule for compensated +bins with `Re(x)<-1` uses homogeneous flow before reading irrelevant source/rate +arrays. Dense storage and copying preserve wide rate precision. + +Norms use only the old state's masked magnitude, while checking all old and +candidate entries for finiteness, including excluded rows. The binary32 reduction +uses max-normalized components and Sum2s from Ogita, Rump and Oishi (2005), +Algorithm 4.1 and Proposition 4.5, DOI +[10.1137/030601818](https://doi.org/10.1137/030601818), through the existing reviewed +`march_precision.jl` helpers. The denominator uses a Float32 mantissa and integer +exponent; the small final merge is host binary64. Inactive score outputs are zero. + +The master must attach physical scaling, portable history, session metadata, +controller policy and public admission separately. No input-noise, all-binary32 +wide arithmetic, GPU or DF32 path is enabled here. A future DF32 attachment must +use actual `WideOperation` certificates for every transported and compensated +expression, including restored sampled rates and replay lengths; narrowing an +already assembled binary64 phase is not that implementation. diff --git a/julia/ADAMS_SESSION_PRECISION.md b/julia/ADAMS_SESSION_PRECISION.md new file mode 100644 index 000000000..07a7ca386 --- /dev/null +++ b/julia/ADAMS_SESSION_PRECISION.md @@ -0,0 +1,92 @@ +# Precision in Adams sessions and observations + +`AdamsSession` and `AdamsObservationWork` accept stored `ComplexF32` or +`ComplexF64` matrices. The caller supplies +`arithmetic=SourceArithmetic(T; state_exponent, field_exponent)`; the default is +`SourceArithmetic(Float64)`. This matches the shared +[precision contract](PRECISION.md) and the +[Adams numerical arithmetic](ADAMS_PRECISION.md). This internal CPU attachment +adds no public precision or device admission. + +The session checks the exact state type, a known modal or spatial source's full +arithmetic record, and `LinearFlow.state_type` before copying the launch or +allocating session work. An explicit binary32 record is required for a binary32 +state. Both scale exponents must agree with the source. Generic Julia callbacks +remain responsible for the same precision and scale contract. The session and +its dense owner retain the record, and retention refuses a different record before +invalidating an existing observation. + +The input launch and absolute tolerance already have their selected internal +scale. The constructor copies and hard-masks the stored launch in its supplied +precision. It performs no physical conversion. The source, sample-state, +predictor, candidate, defect and observed-field storage follows state precision. +Sampled operator rates and exponents remain binary64. Scalar coordinates, +coefficients, control readings, final norm scalars and attempt rows retain the +existing binary64 contract. The separate norm scaling scratch from the numerical +leaf remains visible to the common retained-array memory ledger. + +## Numerical and delivery behavior + +This attachment calls the existing predictor/evaluate/correct leaf with the same +selected history and policy. The binary32 leaf computes complete factors in +binary64 before narrowing, including represented-operator compensation; its range +and conditioning restrictions remain those in `ADAMS_PRECISION.md`. In particular, +this attachment neither removes a factor refusal nor infers DF32 closure from a +small final phase. The old-state norm and full-state finite checks are unchanged. + +The same bounded scheduler owns adaptive rejection, fixed replay, landing, +launch/plane/snapshot receipts, stop and failure events. Source invocations are +counted immediately before callback entry. Logical startup and predictor charges +remain distinct from actual calls for a structurally absent source. Observation +and delivery perform no extra source evaluations. Arithmetic retention introduces +no new controller choice, restart, accepted sample or order-selection decision. + +Dense windows retain the already accepted corrector polynomial and its source and +sample-state arrays in state precision, plus wide rates and exponents. Observation +uses an independently owned state-precision field and never replaces the committed +field. Exact starts and canonical endpoints copy retained stored arrays. A validated +positive gap above the raw endpoint also copies the finished endpoint without +extrapolation. Interior observations use the qualified Adams numerical leaf and +check finiteness before applying hard-mask zeros. The arithmetic record has no +array storage; each retained dense array is counted once by `session_memory`. + +Portable history is a separate boundary. Its accepted state is the **raw scaled +state**, losslessly widened to complex128; source and sampled-state rows retain +complex64 for single precision, while rates retain complex128. No history array +receives a physical scale factor here. Physical field export applies the scale at +its own boundary. Callers must also prepare observation services with matching +precision and scales; this constructor does not convert service workspaces. + +## Qualification + +Focused tests use eight-step windows, task budgets one and two, and bounds checking. +They exercise fixed orders one and four, adaptive rejection, source and budget +failures, snapshots, bounded delivery, represented cumulative compensation and dense +planes. Exact assertions cover ownership, scales, dtype, counters, receipt validity, +raw copies and hard-mask zeros. Warmed advancement requires zero allocations. +The directly affected binary64 suites retain their original numerical bounds. + +For a constant linear operator and constant source, the order-one solution is +compared with its independent MPFR closed form. The comparison bounds complete +old-state and source contributions before cancellation; the declared operation +budget includes wide factor evaluation and one binary32 narrowing. Adaptive dense +solutions use a fixed short-window accuracy envelope against analytic solutions +for `y'=a*y+b*z` and `y'=a*z*y+b*z`, not a claim that local `rtol` bounds global error. + +A real four-point modal FFT/Kerr fixture reduces independently to +`N(A)=-i*|A|^2*A/64` for its sole occupied DC bin. Its MPFR reference carries the +actual order-one PEC source register across all eight steps. For `|A|<=3`, the +source Jacobian norm is at most `L=27/64`. In the error norm +`max(|delta A|, |delta sampled source|/L)`, one step has induced majorant +`1+h*L+(h*L)^2/2`: the two rows of the nonnegative error matrix sum to that value +and `1+h*L`. A fixed local absolute budget is propagated with this majorant and +includes the initial source evaluation. This bound assumes the qualified finite +four-point FFT component error of at most `8u` times the absolute input sum; operation +counting alone does not establish FFT or transcendental accuracy. Two distinct +state/field exponent pairs test the physical source scaling independently from +stored session ownership. + +Public single-precision admission, portable-history conversion, Python transport, +physical export, binary32 service attachment and DF32/device execution remain +separate integration obligations. No timing or device qualification follows from +these CPU allocation and accuracy checks. diff --git a/julia/AGENTS.md b/julia/AGENTS.md new file mode 100644 index 000000000..2763b3634 --- /dev/null +++ b/julia/AGENTS.md @@ -0,0 +1,82 @@ +# Working on SolpropJulia + +Read the root `AGENTS.md`, `docs/dev/architecture.md`, `docs/dev/conventions.md`, +and SEP 48 before changing this package. The accepted SEP defines the scope; these +rules apply to every implementing and reviewing agent in this directory. + +## Ownership and interfaces + +- Julia receives translated arrays and immutable run policy, never physics objects. + The engine owns the complete session: stepping, controller, history, monitors, + statistics, snapshots and export. Python lowers inputs and services events. +- The PythonCall bridge is a package extension. The engine has no Python dependency + and tests independently. No host loop drives Julia trials or finishes statistics. +- All Python entry into Julia is on that process's main thread (ADR-077 and SEP 48 + Part II). Julia's own synchronous parallel work remains supported. Finish allocating + tasks before returning; qualify any vendor background service separately. Keep raw + wrappers inside the narrow bridge helper, registry handles in outer Python frames, + and returned arrays in owned Python storage. Only the raw atomic stop setter runs + on arbitrary Python threads. Destructors and exception formatting also count as entry. +- Follow SEP 47's merged preparation/session contract. Do not inherit `StepDriver`, + import native lowering, duplicate policy on the problem, or add legacy dispatch. +- Admission refuses unsupported routes, responses, methods, precision and options by + name before allocating state. Internal failures use specific exception types; the + adapter preserves their cause in `BackendError` or `ConvergenceError`. + +## Julia code + +- Use explicit imports, concrete or parametric struct fields, and small functions. + Kernel bodies capture only values and arrays and are generic over the admitted + scalar and array types. Keep CPU and device behavior in one numerical implementation. +- Keep one numerical routine and operation sequence for each feature on CPU and GPU. + Specialize allocation, launches, transforms, copies and compact readback in the + execution layer; do not add parallel device versions of source, method or statistic + recipes. Shared arithmetic helpers alone are insufficient if the surrounding + numerical dispatch and ordering are duplicated. Precision-specific algorithms and + measured vendor optimizations need their own explicit numerical justification. +- Qualify the actual Polyester loop forms at one and multiple threads. Its pinned + macro can confuse locals with Base constants (`values` is one); use unambiguous + local names or a verified singleton callback. Issue #621 records the reproducer. +- Use Runic without configuration. Wrap lines at 92 characters manually; Runic does + not enforce that limit. Aqua and JET error analysis are blocking. `JET.report_opt` + is advisory; fix straightforward instabilities in changed hot code. +- Document only the public surface (declared `public`, exported, or bridge entry + points): signature, imperative summary, arguments/keywords, returns and exceptions + as applicable, with shapes, SI units and valid ranges. Internal helpers use comments + only when a mathematical choice, protection or measured behavior needs explaining. +- Every code file has the repository's SPDX copyright and GPL-3.0-or-later header. + Every dependency has a compat bound. GPU packages and PythonCall are weak + dependencies with extensions. Generate manifests; do not hand-edit them. + +## Numerics and memory + +- Follow SEPs 25 and 33. Contraction is permitted where intended; no umbrella + `@fastmath`, approximate-function flags or flush-to-zero. Protect error-free DF32 + primitives from contraction and reassociation except their explicitly required FMA. +- Derive and cite each numerical bound. Distinguish matched-history rounding, + adaptive accuracy, and exact decisions on identical recorded readings. Preserve + structural zeros, lossless copies, integer accounting and transport invariants. +- Input noise is binary64 only. All binary32 paths refuse noise; Metal also refuses + binary64. A DF32 phase guard includes actual replay steps and retained history. +- Preparation may allocate; warmed CPU advancement allocates nothing. Preallocate + event storage and work buffers, bound their capacity, and list all retained storage + in the memory ledger. No Python objects, callbacks or logging in numerical kernels. +- Use `@inbounds` only where measured, on the narrowest expression, with a reason. + Run tests with bounds checking enabled. Test kernel device safety on CPU as well. +- Stop/snapshot requests and exports obey lifetime ownership. Stop access is atomic; + detach listeners before releasing the owner. A failed advance poisons the session. + +## Development and evidence + +- Respect the exclusive ownership recorded in `IMPLEMENTATION.md`. Make changes in + a dedicated worktree; integrate coherent commits into the single SEP 48 branch. + Do not edit another agent's files without a recorded ownership handoff. +- During iteration run Runic, `GROUP=Core` Julia tests, and directly affected Python + tests and static checks. Full gates, slow tests and coverage run in GitHub CI. +- Qualify about ten steps or seconds-long windows. Record each benchmark's window, + hardware, revision, execution identity, thread count and preparation-inclusive time. + Never infer one vendor's tuning from another's result. +- An independent reviewer checks each implementation package before integration. + Append actual checks, limitations and next actions to the implementation record; + complete phase reports belong in SEP Part II. A generated implementation is not + qualified until integration and the required tests pass. diff --git a/julia/CPU_SINGLE_ADAMS_QUALIFICATION.md b/julia/CPU_SINGLE_ADAMS_QUALIFICATION.md new file mode 100644 index 000000000..0c7478dbb --- /dev/null +++ b/julia/CPU_SINGLE_ADAMS_QUALIFICATION.md @@ -0,0 +1,175 @@ +# Short CPU binary32 Adams admission checks + +This record fixes the windows, references and criteria before the comparisons in +`tests/backends/julia/test_cpu_single_adams.py`. It applies SEP 33 section 7.3 to +internal CPU binary32 state with binary64 wide arithmetic. It does not enable the +public precision registry or qualify DF32, devices or long-distance survival. + +## Windows fixed before comparison + +Every window runs from zero to **100 micrometres**, with adaptive stepping, +`dz_init = dz_max = 12.5 micrometres`, no replay, no dense observations and no +noise. The material profiles retain their original full-guide coordinates; they +are not compressed onto the qualification window. These are short entrance +dynamics of the actual configurations, not developed dispersive-wave or +blue-shift spectra. + +| Case | Full guide and launch | Temporal grid | +| --- | --- | --- | +| Helium dispersive-wave configuration | 125 µm capillary radius, 1.5 m guide, 0.8 to 0 bar, two resolved HE modes; 275 µJ, 7.5 fs FWHM, 800 nm | Field, 90 nm to 4 µm, 400 fs | +| Argon plasma configuration | 13 µm radius, 0.2 m guide, 1.7 bar, one resolved mode, no modal loss; 3 µJ, 30 fs FWHM, 800 nm | Field, 300 nm to 4 µm, 400 fs | +| Argon envelope plasma configuration | Same argon guide and pulse | Envelope, 300 nm to 4 µm, 400 fs | + +These are the physical configurations in SEP 33's survival record, reduced only +in propagated distance. The public capillary constructor supplies material data, +plasma rule, quadrature and boundary defaults, with `plasma=True` explicitly +selecting the declared plasma response (envelope plasma is opt-in). Both methods +and references share one translated scientific descriptor. Changing the method does not rebuild those +data or choose different physical defaults. Absolute tolerance remains the +constructor's value; the compared relative tolerances are `1e-6` and `1e-5`. + +## References and metrics + +For each case the initial binary64 DOPRI5 reference pair is `rtol=1e-9` and +`1e-10`. Their discrepancy must be no greater than one tenth of each envelope +below, on every scored component. If needed, the predeclared refinement ladder is +`(1e-10, 1e-11)` then `(1e-11, 1e-12)`. If none settles, the test fails without +qualifying either candidate. This is reference refinement, not a change to the +candidate tolerance, window, metric or envelope. +The reference also halves the step cap independently: its first pair takes caps +of `STEP/2` and `STEP/4`, and later pairs halve these again. This prevents tighter +tolerances from comparing two identical eight-step capped trajectories. Candidate +step limits remain the original `STEP = 12.5 micrometres`. + +| Metric | Fixed relative envelope | +| --- | --- | +| Whole physical exported field, normwise L2 | `1e-3` | +| Physical energy in each of 32 equal active-frequency bands | `1e-2` | +| Total physical energy | `1e-4` | +| Each reported modal peak-power row | `1e-3` | +| Final ionised fraction | `1e-3` | + +Bands use the corrected canonical physical-energy reducer described in +`CPU_SINGLE_QUALIFICATION.md`, evaluated at the actual final coordinate, including +frequency- and position-dependent modal power weights. Only bands with reference +energy at least `1e-4` of the largest are scored, exactly the fixed -40 dB rule. +Band sums must also match total energy under the positive-reduction allowance. +The total-energy and peak-power readouts are the actual session statistics. + +The single-gas ionised fraction is `electron_density / density`, using the +statistics' physical gas density at the final coordinate. It is scored only where +the reference exceeds `1e-6`; all excluded values and their reason are recorded. +A structurally absent plasma response is reported as absent. There is no guessed +density, replacement of a zero by a floor, or tolerance fitted to an observed +discrepancy. For another zero-valued reference observable, zero candidate values +have zero error and nonzero values have infinite relative error. + +At each tolerance, **every scored Adams error must be at most twice the RK +error**, component by component, and both methods must lie within every fixed +envelope. If an RK error is exactly zero, the corresponding Adams error must also +be exactly zero. Small positive RK errors retain their actual value; there is no +comparison floor. Population and band significance come only from the settled +reference and the fixed rules above. + +## Evidence and limits + +JUnit properties record every component error, the reference tolerance pair, +population exclusions and each run's actual attempts, acceptances, rejections and +source evaluations. All failed components are collected before the assertion so +one failed metric cannot conceal another. A failed numerical execution remains a +failed test with its work record. No failure is converted to a skip or expected +failure. + +Run this module through the managed Julia lane, using the exact-source setup +identity and `SOLPROP_TEST_JULIA=1`. Its default lane uses the existing explicit +opt-in skip reason. Full gates and long survival runs are outside this short +qualification. These three windows alone cannot qualify the complete SEP 33 +survival campaign or justify changing the default tolerance floor. + +## Recorded CPU result + +On 2026-11-11, macOS arm64, Julia 1.13.3/PythonCall 0.9.37 and two Julia threads, +the final typed six-case run produced **two passes and four failures**, with no +skips. It used the published Julia source at `7c534c92` and the same Python +translation at `8d52d715`. Every fixed envelope and the exact twice-RK rule remain +unchanged in the failing test package. + +| Case | `rtol` | Result | RK attempts / rejected / source evaluations | Adams attempts / rejected / source evaluations | +| --- | --- | --- | --- | --- | +| Argon field | `1e-6` | All scored criteria pass | 8 / 0 / 56 | 12 / 1 / 13 | +| Argon field | `1e-5` | All scored criteria pass | 8 / 0 / 56 | 10 / 1 / 11 | +| Argon envelope | Both | Cycle-quadrature failure | 0 / 0 / 2 | 0 / 0 / 2 | +| Helium field | Both | Shared translation failure | Not started | Not started | + +For the passing argon field rows, the largest componentwise Adams/RK error ratios +were 1.018 and 1.734 respectively (rounded upward for this report). The final +reference fraction was about `6.6409e-4`, above the fixed population threshold. +The complete unrounded errors and selected band indices are in the test's JUnit +properties. Both argon binary64 reference pairs completed in eight capped steps +and agreed exactly. They satisfy the prescribed tolerance-refinement comparison; +because the cap binds, this does not constitute an independent step-size +convergence study. + +The helium translation fails while resolving the logarithmic power-weight +endpoint expansion on its unchanged parameter box, before any reference or +candidate session starts ([issue 737](https://github.com/LupoLab/solprop/issues/737)). +The envelope candidates exhaust the unchanged cycle rules, reporting +`PlasmaQuadratureFailure` in channel 1: node 3/sample 336 for RK and node 4/sample +442 for Adams ([issue 738](https://github.com/LupoLab/solprop/issues/738)). The +failure payload does not contain the final two moments or their residual. + +An additional control ran the identical argon envelope descriptor and candidate +requests through NumPy's binary32 backend. All four method/tolerance combinations +completed eight accepted attempts with finite exports and preserved input. RK +reported 56 source evaluations; Adams reported its separate charged ledger, +startup 1 and predictor 8, with no rejection or restart. Its ledger is not +relabelled as a physical source counter. The NumPy oracle evaluates envelope +cycle moments and populations in binary64 from the binary32 field before rounding; +this control therefore isolates the failure to Julia's pointwise cycle path, +without yet identifying which error contribution prevents refinement. No physical +quadrature budget was changed: orders 64/128/256/512, `moment_rtol=2e-6` and +`negligible_rate=1e-30` throughout. + +The three-case Adams admission is **not qualified** while these failures remain. +The tests keep them as ordinary failures, without expected-failure markers or a +different scientific configuration. + +## Repeated campaign after the translation and plasma fixes + +At integration source `e690ef30`, the independently reviewed fixes for 737 and 738 +permit every candidate to finish. The repeated six-case run on the same machine, +Julia/bridge versions, two Julia threads and one BLAS thread reports **four passes +and two failures**. Both argon configurations pass at both tolerances. Helium +passes every fixed absolute accuracy envelope but fails the unchanged twice-RK +criterion at both tolerances ([issue 753](https://github.com/LupoLab/solprop/issues/753)). +No failure is skipped or relabelled. + +The independently halved reference caps produce 16 and 32 accepted steps for all +three cases, with no rejection. Their largest componentwise discrepancy is +`2.514e-15`, well below the candidate errors. The reference fraction is scored by +the original threshold, and physical band selection remains unchanged. + +| Helium metric, both tolerances | RK relative error | Adams relative error | +| --- | ---: | ---: | +| First scored spectral band | `3.4889247365e-8` | `9.2940281582e-8` | +| Total energy | `2.2831598569e-8` | `1.2866533335e-7` | +| First modal peak | `6.5479168304e-8` | `1.8439222520e-7` | +| Scored ionised fraction | `1.5657767282e-7` | `8.1408392073e-7` | + +Both helium methods accept eight steps without rejection; RK evaluates 56 sources +and Adams nine. The complete JUnit properties retain every component, including +the passing metrics. The test invocation takes 325.58 seconds including first-use +compilation; this is a qualification duration, not a propagation benchmark. +Investigation continues against identical NumPy binary32 controls and matched +discrete histories. Public admission remains closed while the criterion fails. + +The identical NumPy binary32 controls subsequently complete all four helium +method/tolerance combinations in eight accepted steps without rejection and pass +the twice-RK comparison. At either tolerance their RK/Adams relative errors are +`4.5348263114e-8 / 9.8154508249e-9` for energy and +`4.2791685420e-7 / 3.3168936331e-8` for the scored fraction. All other metrics pass +as well. Julia's physical bands are already recomputed from its exported field +through the canonical NumPy reducer, so the failed band comparison includes a +field-advancement difference; it cannot be attributed solely to Julia's statistic +implementation. This control isolates a remaining implementation comparison, not +a new error allowance or a general proof of a numerical defect. diff --git a/julia/CPU_SINGLE_QUALIFICATION.md b/julia/CPU_SINGLE_QUALIFICATION.md new file mode 100644 index 000000000..e5b5652cf --- /dev/null +++ b/julia/CPU_SINGLE_QUALIFICATION.md @@ -0,0 +1,133 @@ +# CPU binary32 session qualification + +`tests/backends/julia/test_cpu_single.py` exercises the internal `JuliaBackend` +through the managed PythonCall bridge. State, source and observation work use +binary32; the controller, coordinates and linear phase use binary64. Physical +exports remain complex128. These tests do not enable public registry selection, +DF32 phase arithmetic or a device, and do not replace those qualifications. + +## Short execution matrix + +The material witnesses use the existing scalar two-species test mixture, with two +Raman components, independent instantaneous or cycle-averaged plasma channels, +nonzero preionisation and Kerr response. The material constants define synthetic +test functions, not fitted atomic data. The march is one micrometre, with eight +candidate steps. Both field and envelope grids cover averaged, multimode, radial, +Cartesian and line routes. Cartesian witnesses additionally exercise Tsit5, +exponential Adams and fixed low-storage RK4IP beside DOPRI5. Modal witnesses also +carry independent density/linewidth profiles and an uncoupled taper. +Separate eight-micrometre witnesses exercise Kerr-only, Kerr/Raman and plasma +sources. +Physical peak power or intensity and spatial beam widths are compared on every +route at both temporal grid kinds. + +Separate adaptive cases use the two accepted relative tolerances, `1e-6` and +`1e-5`, on the averaged field and envelope routes with DOPRI5, Tsit5 and Adams. +Their maximum step is one eighth of the short interval. This is a qualification +window, not a changed physics or controller default. The actual accepted and +rejected counts remain observable; no equality of adaptive histories is required. + +The service matrix covers an eight-step uniform split collar with RK, Adams and +low-storage stepping; sixteen dense soliton observation planes with DOPRI5 or +Adams, periodic energy and temporal monitoring; and all three scalar spatial +monitor maps. Tsit5 has no continuous extension and is tested only with landed +observations. Noise is absent throughout. The tests check the actual execution +precision, eight bytes +per retained complex state entry, immutable launch data, finite physical exports, +hard-mask zeros, source-call accounting and exact observation/periodic cadence. + +## Accuracy criteria fixed before comparison + +The numerical acceptance uses the already accepted SEP 33 survival metrics, +described in [SEP 33](../docs/dev/seps/archive/sep-0033-single-precision-mlx.md), +section 7.3 and the Part II survival record. SEP 25 distinguishes these accuracy +envelopes from matched-history rounding bounds. Ordinary replay, and especially +variable-order Adams, is not assumed to have the same discrete history as the +reference method. + +| Quantity | Candidate accuracy envelope | Independent reference settlement | +| --- | --- | --- | +| Entire saved field, relative L2 | `1e-3` | `1e-9` | +| Physical energy in 32 equal-frequency active bands above -40 dB | `1e-2` relative | `1e-4` relative | +| Total physical energy | `1e-4` relative | `1e-8` relative | +| Peak power or intensity; spatial beam radius and FWHM | `1e-3` relative | `1e-8` relative | +| Species ionised fractions and electron densities | `1e-3` relative | `1e-8` relative | + +Each material reference uses the identical binary64 translated descriptor and +grid, with independent 16-step and 32-step DOPRI5 marches. The population fixtures +start at an ionised fraction of at least 0.03, above SEP 33's `1e-6` signal floor; +there is no discrepancy-dependent exclusion. All reported source-rate rows must +be finite, but this matrix does not assign a separate rate-accuracy envelope. +Dense soliton observations instead use landed 32-step and 64-step references at +the same sixteen positions. No local `rtol` is used as a global error estimate. +These fixed-step refinements qualify the short paths; they do not reproduce +SEP 33's entire survival campaign or its separate Adams-versus-RK twice-error +admission rule. That rule remains an additional prerequisite for public admission. + +The band metric uses physical energy at the final observation coordinate. Modal +bands use the oracle's `stats._poynting_statistics` with the represented +`power_weight_at(problem, z)`, including its frequency and position dependence. +Spatial bands use `backends.spatial.collect_spatial` on frequency-masked fields, +with the actual `FluxPlan.at(z)` and transverse spectral measure. This reducer +already owns the axial admittance and analytic-signal endpoint weights. No new +conversion constants or approximation of the medium are introduced. Units are +joules, or joules per metre on a line. The 32 half-open windows partition the +active band; the last window includes its final bin. The inactive field is zero. + +Every candidate and reference checks that the bands sum to the canonical total +energy. For these finite, normal, nonnegative-energy fixtures, with `N` complex +field entries, two evaluations of the positive reduction differ by at most +`2*gamma_(2*N+64)` times the total. Each product path uses fewer than 16 real +operations, at most `2*N` additions cover polarisation, column and chunk +reductions, and 32 more cover the bands. The bound includes both independent +reduction orders and is required to remain below `1e-8`. Actual binary64 session +energy is compared independently with the same bound; binary32 session energy +uses the already declared `1e-4` physical-energy accuracy envelope. These checks +run on both temporal grids and all five routes, including the modal profile and +taper cases. + +This corrects the original raw squared-amplitude band metric +([issue 734](https://github.com/LupoLab/solprop/issues/734)). SEP 33 Part I requires +spectral energy; its historical Part II table describes a sum of squared +amplitudes across columns. That historical measurement is not reinterpreted as +physical energy here. The current tests use the accepted Part I definition and +leave prior evidence unchanged. + +For the source-free uniform split test, the independent solution is +`a(z) = exp(D*z - alpha*z/2)*a(0)`: a scalar temporal multiplier commutes with the +lossless spectral operator. The field and energy envelopes above are checked at +every delivered plane, including the exact physical energy decay. A quiet monitor +must not omit the required split finish. + +Spatial launch-monitor face shares use the existing transverse bridge test's +conditional coarse-transform and positive-reduction model, recomputed with +binary32 unit roundoff `u = 2^-24`: + +`8*gamma_(64*(n_columns+n_omega))`, where `gamma_k = k*u/(1-k*u)`. + +The test requires this positive bound to remain below `0.01`. Its absolute scale +is the positive total launch energy, including weak faces. The model includes the +qualified finite FFT/twiddle error hypothesis and launch normalization; counting +operations alone is not a proof of a vendor FFT's accuracy. No relative accuracy +for a tiny face or monitor threshold-decision equivalence is inferred. + +## Running and interpreting the checks + +Publish a managed CPU setup for the exact source, then set `SOLPROP_TEST_JULIA=1`, +`SOLPROP_TEST_JULIA_SETUP_ID` and `SOLPROP_JULIA_DEPOT` as in the Julia runtime lane. +Run only the directly affected module during development: + +```sh +uv run --no-sync pytest tests/backends/julia/test_cpu_single.py +``` + +With the opt-in absent, the existing declared runtime-lane skip reason applies. +An enabled lane must execute the tests; a missing setup identity is an assertion +failure. A native installation is not needed for these Julia-versus-NumPy checks. +No cold-start timings from this module are benchmark results. Full gates and +coverage remain CI responsibilities. + +The final qualification record must state the source revision, setup identity, +thread width, executed test count and any failures. Passing this small matrix +establishes those short CPU paths only; it does not claim long-distance survival, +all conditioning regimes, changed noise admission, DF32 or GPU qualification. diff --git a/julia/CUDA_BRIDGE.md b/julia/CUDA_BRIDGE.md new file mode 100644 index 000000000..f4c4d5e24 --- /dev/null +++ b/julia/CUDA_BRIDGE.md @@ -0,0 +1,37 @@ +# Selected execution at the PythonCall boundary + +`prepare_modal` accepts an optional fourth execution name. CPU remains the default; +CUDA uses the already loaded vendor extension and its first device. The public +backend admission remains CPU-only until the complete CUDA catalogue is qualified. +Spatial device preparation still refuses explicitly. Neither bridge selection nor +device loading adds fields to the scientific descriptor or resume identity. + +The Python preparation transaction forwards its selected target to runtime setup +selection and to the Julia factory. CPU preparation retains its shared BLAS lease +and FFTW planning cache. Device preparation acquires neither, and a device start +cannot attach CPU FFTW planning. Constructor failure releases unpublished owners; +deferred interrupts still observe a fully published preparation. + +Scalar material, density, taper and decay profiles are evaluated by Julia host +control and retain host tables. Modal prefactors and power weights use execution-aware +constructors to upload their separately owned numerical tables. Linear-operator +tables already follow their own selected execution. Expansion flow scratch is now +allocated through that execution as well. No Python loop evaluates a source or step. + +An uploaded starting field is checked for finiteness in its owned stream using one +integer status per column. This avoids an ambient vendor reduction or full-field +download. The common session constructor still copies and hard-masks its owned +initial state. Host input and CPU advancement retain their original numerical graph. +Every session supplies its actual field shape to transactional device-export storage, +including spatial preparations without modal power weights. + +Focused Python transaction/BLAS/FFT/group checks pass 84 tests, and changed-file +typing reports no errors or warnings. The launch/source/march engine tests pass +272 bounds-enabled assertions, including 16 checks with a model that refuses host +indexing of its device field. Six real managed Julia CPU cases pass: bounded eight-step +replay, represented operator/prefactor tables and expansions, and exact destination +recipes. Their reference is NumPy; no native-backend qualification is claimed by +this isolated lightweight environment. CPU Aqua/JET passes 16 checks, with all +2,292 definitions analyzed and none cached. Actual CUDA bridge execution remains +pending; the Raman/plasma execution-aware factories and the device service catalogue +are separate integration work. diff --git a/julia/CUDA_EXPORT.md b/julia/CUDA_EXPORT.md new file mode 100644 index 000000000..475dc3ed8 --- /dev/null +++ b/julia/CUDA_EXPORT.md @@ -0,0 +1,44 @@ +# Binary64 device field export + +The device export follows the same retained-generation contract and physical recipe +as CPU export: optional modal square-root scaling, then optional optics conjugation +and alternating frequency sign. Globally unit weights skip the complex product; +mixed weights retain its explicit zero terms for every cell. Spatial exports keep +their existing rule of ignoring modal power conversion. + +Each device session owns a complex binary64 staging field, an equally shaped host +mirror and two integer facts per column on both sides. The first fact identifies +invalid weights or a nonfinite staged result; the second identifies nonunit weights. +Weight tables and expansions remain on the execution device. Only validity/identity +facts cross to the host before the complete physical field is downloaded. + +The caller's destination must be writable detached host storage of the exact field +shape. Validate the receipt, retained-storage independence, execution and all values +before copying into it. A failed numerical recipe or partial device download changes +only session-owned scratch; the pending generation remains available for retry. The +engine does not consume that generation until acknowledgement. + +For `r` frequency rows and `c` columns, transfer scratch owns `32*r*c + 32*c` bytes +on a 64-bit host: both complex fields and both two-row integer summaries. Existing +power-weight values, coefficients and prepared data are additional owners. The usual +memory ledger includes every buffer and deduplicates shared owners. CPU export keeps +its existing two-pass recipe and allocates no new transfer scratch. + +`test/device_export.jl` exercises host orchestration, exact signed zeros, retained +storage, generation failures, compact transfer sizes, partial-copy failures and retry. +`test/cuda_export.jl` repeats the numerical and address-space checks with scalar +indexing disabled on actual CUDA. Host-model results do not establish CUDA support; +this internal leaf does not change public device admission. + +The author host run passes 169 new orchestration assertions plus 61 existing +power-weight assertions. The affected CPU session, transfer and precision consumers +pass 2,469 assertions across 67 testsets, including their warmed zero-allocation +checks. CPU Aqua/JET passes 16 checks with all 2,253 definitions analyzed and none +cached. These checks use bounds-enabled Julia 1.13.3 with two threads. An initial +constructor-dispatch collision was corrected before this final run by explicitly +typing the execution-aware table overload. Actual CUDA execution remains pending. +Independent review additionally exposed an explicit-weight header overlapping the +staging field. Such weights now refuse before any summary or staging write; genuine +foreign offset-header tests verify unchanged output, scratch, weights and generation, +followed by successful retry with detached weights. The CUDA witness includes the +same retained-address boundary and awaits hardware execution. diff --git a/julia/CUDA_FOUNDATION.md b/julia/CUDA_FOUNDATION.md new file mode 100644 index 000000000..63b998c2a --- /dev/null +++ b/julia/CUDA_FOUNDATION.md @@ -0,0 +1,209 @@ +# CUDA execution and transform foundation + +This package slice implements owned CUDA execution and dense temporal/spatial FFTs. +It does not open CUDA propagation admission. Sources, adaptive norms, numerical +statistics and monitors, history/export transport, and the Python device factory +still require their separate device integration and qualification under SEP 48. +The CPU numerical implementations and public physics defaults are unchanged. + +## Execution ownership + +`device_execution(Val(:cuda), device_index, tasks; check_body=false)` selects a +zero-based device ordinal and returns the existing `KernelExecution` with an +extension-owned concrete backend. The backend retains the primary CUDA context +and a private stream. `tasks` remains the host CPU budget; GPU launch geometry is +selected by the pinned KernelAbstractions backend. + +Each allocation, transfer, kernel and transform enters the retained context/stream +using CUDA.jl's scoped APIs and restores its caller's CUDA.jl task-local state in +`finally`, including on failure. A completed call has synchronized that stream. +No process-global workspace, scalar-indexing policy, math mode, or FFTW planning +policy is changed. +The execution owner and its arrays must remain alive through the synchronous call. +A session-level close/release policy is outside this foundation slice. +The tests establish task-local restoration after CUDA.jl state exists. They do not +establish restoration of an independently installed raw foreign driver context on +first entry. First-entry and native CUDA coexistence qualification remains tracked +in [#733](https://github.com/LupoLab/solprop/issues/733) before public device admission. + +The pinned backend is explicitly constructed with `always_inline=true` and +`fastmath=false`. CUDA.jl's default fast-math setting otherwise follows Julia's +command-line mode and can flush Float32 subnormals. The column launcher gives each +column one sequential body; the pointwise launcher visits every row/column pair. +CUDA adapts captured arrays to device arguments. The extension validates capture +storage/context first, including nested tuples and scalar records; a pointer-backed +array is not considered an inert scalar merely because its wrapper is `isbits`. +Raw host, CUDA and LLVM pointer captures refuse because they cannot establish an +owning array or the selected context, including inside otherwise scalar records. +The CPU PtrArray capture adaptation is never used on this path. + +Device allocations use `CuArray{T,N,DeviceMemory}` explicitly, preserving element +type and dimensions. This avoids inheriting an ambient unified-memory preference. +The initial storage scope is dense CuArray device memory. Known host array views +can be copied during `upload` preparation, but device views are not silently staged +through the host. Kernel captures and FFT buffers must use the admitted dense form. + +`copy_device!` requires exact shape/type agreement and one selected context. An +identical source/destination is an exact numerical no-op. All other byte overlap, +including offset foreign headers, refuses before writes. Address comparisons are +context-aware, use unsigned differences rather than wrapping address endpoints, +and include the actual element width. `copy_host!` is device-to-host only and requires +a dense Julia `Array` destination with the same shape/type. These helpers neither +restore physical field scales nor apply power weights or Fourier conventions. +The broader session alias/export policy remains a separate integration boundary. + +## Dense FFT ownership and normalization + +`TemporalFFT` accepts dense device matrices of matching binary32 or binary64 +precision. Real samples use the leading `n_time ÷ 2 + 1` spectrum; complex samples +retain `n_time` frequencies. The forward cuFFT transform has the internal negative +DFT sign. The backward plan is unnormalized, and the existing inverse API applies +`1/n_time` exactly once. Both out-of-place directions preserve their input. + +`SpatialFFT` accepts a dense complex device array and strictly increasing, nonempty +axis indices. Other axes are independent batches. Forward and backward transforms +are raw; the inverse applies the reciprocal product of the transformed dimensions +once. The plan wrappers retain the execution owner and validate context, precision, +shape, placement and overlap before calling cuFFT. Inverse calls require the exact +prepared execution owner, preventing a transform followed by scaling on another +stream or device. Planning preserves the supplied numerical buffers. +Both prepared and replacement buffers must have base pointers aligned to the +complex element width (8 bytes for binary32, 16 bytes for binary64). In particular, +real-transform input/output pointers need complex alignment under NVIDIA's API; +a dense foreign header with only scalar alignment refuses before planning or writes. +Retained real-transform scratch is checked by the same application guard. This is +separate from the pinned wrapper's repair of misaligned external batch starts. + +The pinned cuFFT implementation has two relevant storage properties: + +- `plan_rfft` retains a complex buffer for its possible inverse interface even when + forward `mul!` does not use that buffer. `plan_brfft` retains another complex input + preservation buffer. This slice counts both arrays, by owner identity, through a + narrowly dispatched memory traversal. It does not traverse arbitrary CUDA handles. +- cuFFT's public `mul!` allocates dense staging for non-dense inputs/outputs, and real + transforms with misaligned external batch starts can allocate temporary arrays. + The admitted temporal axis-1 and complex dense spatial layouts avoid those paths. + Wrapped non-dense arrays are refused during preparation rather than accepted with + hidden repeated allocations. + +Each wrapper also stores `workspace_bytes::Int`, queried once with `cufftGetSize` +after plan construction inside the owned context. The pinned `CuFFTPlan` has no +workspace-size field: `cufftMakePlan` returns a size, but its `handle_ctor` discards +that value and retains cuFFT's default automatic allocation. The post-construction +query supplies the current native work-area requirement; conversion to the ledger's +`Int` is checked. A named `.workspace` ledger entry is counted once per raw-plan +identity, separately from its numerical buffer. Repeated transform execution neither +queries the size nor changes the native work-area configuration. Direct-query and +shared-wrapper/buffer tests cover this accounting correction +([#735](https://github.com/LupoLab/solprop/issues/735)). + +The visible plan-buffer payloads and queried active native work areas are included. +CUDA allocator reservations, object overhead, other opaque handle allocations and +driver memory are separate process overhead; no RSS or complete device-memory bound +is claimed. Releasing a Julia plan also does not imply that its native work area is +immediately freed. In pinned cuFFT 6.5.1, `unsafe_free!(plan)` calls +`cufftReleasePlan`, which defers returning the handle to the process-wide +`idle_handles` cache. CUDACore's `HandleCache` destroys idle handles on its +purge/reclaim path. Its default `gc_threshold=32` requests collection when many +handles are active; it is neither an idle-handle limit nor a byte bound. The cache +exposes active/idle counts, not all internal allocation sizes. This foundation does +not mutate that vendor-global cache on session close. Repeated shape preparation, +release and reclamation require separate process-memory measurements tracked in +[#736](https://github.com/LupoLab/solprop/issues/736). +FFTW wisdom and the CPU FFT planning context have no role in these CUDA plans. + +## Numerical qualification model + +The launch/copy tests use exactly representable integer arithmetic, exact masks and +copy/no-op/ownership assertions. A Float32 minimum-normal times one half checks +that the actual compiled pointwise path preserves a representable subnormal. +This is a necessary compiler witness, not complete DF32 qualification. + +The small radix-two FFT witnesses compare the device result against a direct DFT +formed from the represented input with 256-bit arithmetic. Their explicitly stated +model assumes componentwise rounded butterflies/products and twiddle components +accurate to two unit roundoffs. A conservative `gamma(64*n)` sum-of-input-magnitudes +budget covers the tested real splitting, complex products and radix-two stages; +a separate additive minimum-subnormal term accounts for gradual underflow. The +multiaxis witness uses an outward-rounded per-axis recurrence. With a current exact +element-magnitude bound `M`, error bound `E`, axis length `n` and `g=gamma(64*n)`, +one raw transform updates `M` to `n*M` and bounds its error by +`n*(E + g*(M+E)) + 64*n*eta`, where `eta` is the smallest subnormal. This accounts +for propagation of earlier error and the perturbed inputs of the next transform. +The forward and reverse sequences are composed before dividing by the transform +volume, with an additional `eta/2` for the final dyadic scaling. These bounds are +fixed from lengths and input magnitudes before comparing any device discrepancy. +These finite cases test that model; operation counting alone does not prove every +cuFFT plan's twiddle error or an arbitrary transform-size guarantee. + +Warm repeated-call checks distinguish device array allocation from Julia host +allocation. `CUDA.@allocated` must report zero repeated device allocation after +specialization; host-side compiler/plan/driver bookkeeping is reported separately. +The tests also preserve input arrays and exercise same-context alternate streams, +foreign offset overlaps, unsupported layouts, wrong precision and failed-call state +restoration. When more than one device is available, additional context-mismatch +checks run; a one-device pass does not claim multi-device qualification. + +## Focused device invocation + +Use a managed CUDA setup whose pinned packages and artifacts have already been +materialized on a CPU-only host. Run on an allocated GPU node with networking +blocked by the campaign supervisor; `JULIA_PKG_OFFLINE` alone is not a network +sandbox. No package installation occurs in this runner. + +```sh +JULIA_PKG_OFFLINE=true JULIA_NUM_THREADS=2 JULIA_LOAD_PATH='@:@stdlib' \ + julia --startup-file=no --check-bounds=yes --project=julia/environments/cuda \ + -e 'using Test; import CUDA; import SolpropJulia; @assert CUDA.functional(); + include("julia/test/cuda_execution.jl"); + include("julia/test/cuda_transforms.jl")' +``` + +The selected device test files fail when CUDA is unavailable; the CPU test aggregate +must not include them implicitly. Record the engine revision, Julia/package/toolkit/ +driver versions, device model, compilation warmup, and host/device allocation facts. +The first implementation record must distinguish actual GPU results from local +syntax, host-boundary and package-analysis checks. No CUDA engine performance or +full-session parity claim follows from this foundation alone. + +## Observed qualification and remaining blockers + +The first complete device run used an NVIDIA A40 (compute capability 8.6), Julia +1.13.3, CUDA.jl 6.5.1, CUDA runtime 13.4.0 and driver API 13.5.0. With bounds enabled, +two Julia threads and kernel-level network isolation, all 418 assertions in the eight +focused execution/transform test sets passed. This includes the actual native +workspace query, foreign-header alignment refusals, input preservation, gradual +underflow witness and zero repeated device-allocation checks. It does not qualify +multiple devices or complete propagation sessions. + +The separate unfiltered device quality run failed and remains a qualification +blocker. Aqua passed all 11 checks. JET analyzed 2,067 core and 51 extension definitions; +the core report contained 76 possible errors, the extension package also reported +errors, and all six concrete device-call checks failed. The concrete traces include +CUDACore's `stream_wait` calling `context!` with a possible `Nothing`, and +`synchronize` calling `mark_completed!` with a possible `Nothing`. Core analysis also +reaches CPU-only Polyester and AcceleratedKernels paths with device arrays. These +reports have not been filtered or suppressed. The foundation remains internal while +vendor inference and shared device-port work are resolved; neither full vendor +quality nor public CUDA session admission is claimed. + +## Sources checked + +The implementation was checked against the exact installed packages selected by the +committed manifests, using primary package source: + +- [CUDA.jl 6.5.1](https://github.com/JuliaGPU/CUDA.jl/tree/v6.5.1): CUDACore + `src/CUDAKernels.jl`, `src/array.jl`, and `lib/cudadrv/state.jl` define explicit + compilation flags, typed device storage, context identity and scoped restoration. +- The same pinned distribution's cuFFT `src/fft.jl` defines plan buffers, input + preservation, dense/strided execution, and external-batch alignment behavior; + `src/wrappers.jl` selects automatic native work-area allocation and caches released + handles. CUDACore `src/utils/cache.jl` defines deferred return, the active-handle + collection threshold and idle-handle purge behavior. +- [NVIDIA's cuFFT API, sections 3.7 and 3.8.1](https://docs.nvidia.com/cuda/cufft/) + specifies the completed-plan workspace query and default automatic allocation. +- [NVIDIA's cuFFT API, sections 3.9.2 and 3.9.3](https://docs.nvidia.com/cuda/cufft/) + specifies complex-type alignment for both real-transform pointers. +- [KernelAbstractions](https://github.com/JuliaGPU/KernelAbstractions.jl) supplies the + indexed kernel and backend launch interface. Numerical loop bodies retain the + engine's existing scalar operations; no new propagation method is introduced. diff --git a/julia/CUDA_LOW_STORAGE.md b/julia/CUDA_LOW_STORAGE.md new file mode 100644 index 000000000..1ab721dee --- /dev/null +++ b/julia/CUDA_LOW_STORAGE.md @@ -0,0 +1,142 @@ +# Binary64 CUDA low-storage replay + +This internal method slice keeps the fixed midpoint RK4 interaction-picture method +and its public Julia signatures. CPU binary32 and binary64 use the previous operation +graph and allocation policy. A non-CPU execution requires binary64 before workspace +allocation. This does not open public CUDA selection or qualify a complete material +source, observation service, export bridge, or vendor runtime. + +## Numerical and lifecycle boundary + +`LowStorageWork(execution, state, RK4IPTableau(); norm_mask)` owns the three existing +work matrices. `low_storage_trial!` still invokes four complete source evaluations +and four forward linear flows, with the same register assignments, coefficients, +positions and protected scale/sum-of-squares recurrence. The diagonal-flow derivation +and references remain SEP 24 sections 4.2–4.3 and the `RK4IPTableau` docstring. + +Device preparation adds two `DeviceReadback` records, with the exact preparing +execution retained. `norm_readback.device` is the existing `norm_parts` matrix and +`finite_readback.device` is the existing `finite_columns` vector. The column kernel +uses device arrays; the existing binary64 host merge receives only these summaries. +The finite flags inspect every stored field entry, including rows outside the norm +mask. A wrong execution, incompatible workspace, retained alias or unsupported +writable output layout refuses before numerical entry. + +`LowStorageSession` reuses the common scheduler. Launch, fixed replay edges, hard +masks, snapshots, stop requests and acknowledgment generations retain their original +ordering. The state is marked in flight before the first source call. Source, flow, +norm or candidate-finishing failure poisons that state; accepted-step service failure +occurs after a valid field and attempt record commit. Attempted source calls are +recorded before entry and committed source counts increase only after finishing. +There is no rollback buffer, adaptive error estimate, new controller or dense output. + +## Storage and transfers + +For `r` spectral rows and `c` columns, the logical binary64 workspace array data is: + +| Owner | Shape and element type | Bytes | +|---|---|---:| +| Three work registers | three `(r,c)` ComplexF64 arrays | `48*r*c` | +| Norm mask | `(r,)` Bool | `r` | +| Device norm partials | `(2,c)` Float64 | `16*c` | +| Device finite flags | `(c,)` Bool | `c` | +| Persistent host partials | `(2,c)` Float64 | `16*c` | +| Persistent host flags | `(c,)` Bool | `c` | + +The logical device-plus-host total is `48*r*c + r + 34*c`. Pinned CUDACore +rounds each nonempty device allocation up to four bytes; therefore the actual +retained CUDA payload plus host mirrors is +`48*r*c + 4*cld(r,4) + 33*c + 4*cld(c,4)`. The two rounded terms are the +device Bool mask and finite flags; the Float64 and ComplexF64 arrays are already +aligned. For `r=17`, `c=3`, this is 2,571 bytes. CPU binary64 retains +`48*r*c + r + 17*c`, without mirrors or vendor padding. See the pinned allocator +reference in [CUDA_STORAGE.md](CUDA_STORAGE.md). These counts exclude the separately owned +session field, masks in `MarchNorm`, linear-flow/source storage and bounded attempt +records. Shared owner-aware ledger traversal deduplicates the readback device aliases. +GPU allocator reservations and vendor process state are not array payload. + +Each norm copies exactly `17*c` bytes to its persistent host mirrors. Linear-flow +and finished-candidate status use the existing, separately accounted per-column +integer failure readback. Advancement does not download a complete field. Test +readouts deliberately do so only at an observation boundary after advancement. +The warmed CPU path remains allocation-free; this statement is not an assertion +that vendor launch machinery allocates no Julia or driver objects. + +## Independent short-step witness and bound + +The committed witness has the scalar commuting equation `u' = D*u + g*u`, +`D = -1/4 + i/2`, `g = i/8`, and one or eight equal steps over `L = 1/32 m`. +The initial real and imaginary components are small dyadic fractions. Step lengths, +midpoints and exponent inputs are exactly representable. A structural mask sets one +row to exact zero. Eliminating the midpoint interaction-picture variables gives the +independent discrete map + +```text +u_n = [exp(D*h) * P4(g*h)]^n * u_0 +P4(x) = 1 + x + x^2/2 + x^3/6 + x^4/24. +``` + +The reference evaluates this expression with 256-bit MPFR arithmetic, then rounds +once for a binary64 readout. It does not repeat the implementation's register loop. +This is a matched-discrete-method witness, so it measures rounding rather than the +RK4 truncation error relative to the continuous equation. + +The bound assumes round-to-nearest binary64 arithmetic with no overflow or underflow +for these fixture operands, and a componentwise relative error at most `16*u` for +the two nonzero components of `exp(D*h/2)`, where `u = 2^-53`. The CUDA test checks +that primitive hypothesis against MPFR at each actual half-step input before using +the bound. It is not a universal claim about the vendor complex exponential. The +tabulated and direct flow paths use the same factors; cached reuse adds no operation. + +Per cell and step, four complex source products and four complex flow products use +at most 48 scalar operations. The first, two middle and final register updates use +at most 28. Four non-dyadic divisions form the sixth/third coefficients. Reserving +eight more operations for phase products and 32 rounding equivalents for each of +the four qualified complex exponential factors gives at most 216. The bound uses +256 per step, leaving slack for the coefficient and final-reference rounding. FMA +contraction may remove rounding steps and does not need a larger count here. + +Replacing every real/imaginary arithmetic contribution by its absolute value bounds +the expanded scalar register graph by +`M = sum(abs(real(u0))) + sum(abs(imag(u0)))` times +`exp((abs(real(D))+abs(imag(D))+abs(real(g))+abs(imag(g)))*L)`. +This follows from the positive-coefficient RK polynomial being bounded by its +exponential series. No reduction affects the fixed step sequence. A conservative +bound for two implementations, also covering the rounded independent readout, is + +```text +gamma(512*n) * M * exp((7/8)*L), gamma(k) = k*u/(1-k*u). +``` + +The same component one-norm envelope bounds the reported Euclidean difference. +The test evaluates the bound at 256 bits and converts outward to binary64. All +quantities are finite and far from the normal/subnormal boundary in this fixture. +This argument does not qualify nonlinear material sources, different histories, +adaptive schedules, arbitrary exponential operands or binary32 device work. + +The norm witness separately compares the scaled sum-of-squares result with an MPFR +norm. Its conservative count `32*r*c + 16*c` covers division/squaring/addition, +column rescaling, the serial host merge and final square root on the bounded fixture. +It preserves the mask and independently tests finiteness outside that mask. + +## Qualification status + +The source-free host model counts every preparation allocation and norm readback, +checks exact payloads, foreign-offset aliases and repeated-index output refusal, +and exercises source and finishing failures through actual session hooks. It is +orchestration evidence, not device execution evidence. Existing CPU low-storage, +session and precision tests retain their unchanged arithmetic and warmed allocation +checks. The focused author run passed 2,322 distinct CPU assertions at two threads, +including timing-probe and preserved binary32 consumers. One inherited RK test +fixture needed its existing readback field appended in the private harness; the +low-storage implementation preserves its previous positional workspace constructor. +The new 115 host checks also passed at one thread. CPU Aqua/JET passed 16 checks +with all 2,248 definitions analyzed, plus eight concrete call analyses. + +`test/cuda_low_storage.jl` is an explicitly selected device leaf. It requires a +functional CUDA device, disables scalar indexing, and checks one/eight steps, +direct/tabulated flow, bounded yields, exact source accounting, compact storage, +failure poisoning, snapshots, stop receipts and context/stream restoration. Actual +device execution and unfiltered vendor quality remain separate mandatory evidence; +the initial host handoff does not claim that either has passed. The previously +recorded CUDA vendor-analysis failures remain visible under issue #741. diff --git a/julia/CUDA_RK_DENSE.md b/julia/CUDA_RK_DENSE.md new file mode 100644 index 000000000..b5a90d05a --- /dev/null +++ b/julia/CUDA_RK_DENSE.md @@ -0,0 +1,57 @@ +# Device execution for RK dense observations + +CPU and device execution use the same `retain_runge_kutta_observation!` and +`observe_runge_kutta!` routines. Coefficient formation, the stiff-bin decision, +the nested polynomial, represented phase, endpoint selection and hard masking +have one implementation. The device helper file supplies storage admission, +compact finite checks and buffer accounting; it defines no alternate RK method +or continuous extension. The existing CPU binary32 and DF32 paths are unchanged. + +The device constructor admits binary64 modal diagonal, represented and expansion +operators and validates their selected context before allocating work. Its five +coefficient fields, endpoint, observation, exponent, stiff flags and expansion +weights use the selected execution. The original CPU integer failure vector becomes +a device integer vector plus a persistent host mirror only for device execution. +Each finite check downloads one machine integer per column. Retention checks the +initial field, endpoint, stage array, represented exponent and formed coefficients; +it never downloads their numerical payloads. Memory reporting counts both mirrors. + +Retention and observation keep their existing argument and alias checks. A device +work object accepts only its prepared execution. Shape, storage and ownership admission +failures preserve the retained window; numerical or readback failure during retention +leaves that window unavailable. +The caller's initial field, stages and finished endpoint are read-only. Device copies +and zeroing use the common execution primitives. Exact endpoints and accepted positive +landing gaps copy the endpoint; interior numerical failure is checked before masking. +The session uses its existing dense-plane scheduling and delivery rules without +another controller, source invocation or field commit. + +The serial test model refuses host scalar access to numerical arrays, records compact +download sizes, and injects a partial readback failure. It covers different execution +owners, interior foreign headers, nonfinite masked bins, canonical endpoint gaps, +buffer accounting and a two-step session delivering interior planes. These are +orchestration checks, not CUDA arithmetic evidence. Actual CUDA tests disable scalar +indexing and check context/stream restoration, retained input bytes, compact storage, +the same numerical comparisons and warmed device allocation. + +Comparisons use an absolute envelope formed before cancellation from the actual +solution and continuous-extension weights. For each element, define the positive +coefficient envelopes `B2=h*sum(abs(b_i)*norm1(k_i))`, +`B3=h*norm1(k_1)+B2`, `B4=B2+h*norm1(k_N)+B3` and +`B5=h*sum(abs(d_i)*norm1(k_i))`. The nested evaluation envelope is +`norm1(y)+abs(t)*(B2+abs(s)*(B3+abs(t)*(B4+abs(s)*B5)))`, using the same recorded +binary64 `t` and `s` as both executions. The test computes this in MPFR and applies +`4*gamma_512`: two scalar graphs each have fewer than 128 operations, the remaining +allowance covers phase formation and the finite elementary-function hypothesis, +and the largest tested real phase is 1.2, whose gain is below four. This is conditional +on the binary64 elementary-function accuracy assumed by device qualification; it +does not prove arbitrary-range vendor transcendental accuracy. The inherited dense +tests independently check the polynomial with MPFR and its published midpoint +constraints. No observed discrepancy determines a tolerance. + +Initial validation passes 5,730 affected CPU/spatial/DF32 assertions. The final +source repeats 3,508 directly affected CPU/spatial/DF32 assertions and 334 model/RK +assertions, including 148 new transport/session checks. Final CPU Aqua/JET passes +16 checks with all 2,310 definitions analyzed and none cached. Independent review +is recorded at integration. Actual CUDA execution remains pending, and public +admission is unchanged. diff --git a/julia/CUDA_SOURCE.md b/julia/CUDA_SOURCE.md new file mode 100644 index 000000000..ea53af796 --- /dev/null +++ b/julia/CUDA_SOURCE.md @@ -0,0 +1,239 @@ +# Binary64 CUDA modal source composition + +This internal slice applies the existing scalar modal source graph on CUDA. It +does not change public device admission. The first milestone covers field and +envelope Kerr, including the analytic-field and envelope harmonic forms, constant +and represented prefactors, independent host material profiles, embedded modal +projection, and in-stage temporal absorption. The response attachment adds scalar +Raman and field/envelope plasma with the same independent profiles and represented +prefactors. Binary32 device sources refuse before source preparation allocates. + +The arithmetic is the same scalar contraction, Fourier convention and response +formula as the CPU path. No GEMM, reordered modal sum, vendor reduction or new +material convention is introduced. CPU signatures keep their defaults and +recurrence order. CUDA qualification requires actual device tests with scalar +indexing disabled; the host orchestration model does not qualify device code. + +## Preparation and ownership + +`ModalSourceGrid.crop_index` and `.omega` are owned host metadata. Source +preparation builds a separate execution-owned `SpectralPadding` from the index +map. Windows, masks, carriers and pointwise numerical buffers belong to the +selected execution. `ModalSourceMap` retains complete dense numerical maps; +`synthesize!` and `project!` accept `first_node=1` and an active local count. Each +chunk uses those full maps directly, without a noncontiguous array view or a +second copy of the map. Inactive local columns are overwritten with exact zeros. + +The map's `host_synthesis`, `host_projection` and `host_coarse_projection` remain +actual host preparation copies. Binary64 CPU records alias their numerical maps; +CUDA records have separate device and host owners. Both are included in the +ordinary memory traversal, with repeated owners counted once. + +`SourceProfile` tables remain host-owned scalar data. Their position evaluation +does not read the evolving field. Numerical prefactor tables use +`SourcePrefactor(execution, table, shape; arithmetic)`; this copies coefficients +and breakpoints under the selected execution. The existing two-argument table +constructor keeps its CPU behavior. Expansion terms and their weight table also +belong to the selected execution. Constant prefactors and all work arrays are +uploaded or allocated through the execution interface. + +All device fills and copies use the retained execution, including successful +embedded-source snapshots. Finite checking writes one first-failing row per +column and copies only that bounded integer vector to its persistent host mirror. +The first column, then first row, determines `NonfiniteSourceError`, exactly as +on CPU. No evolving time or spectral field is downloaded by a source call. + +Caller output and state must be disjoint from each other and every retained +source numerical owner. The check includes the numerical arrays exposed by +`_retained_storage` for both directions of every FFT plan. It does not traverse +opaque vendor handles. The ordinary ledger retains the plan's queried native +workspace separately from those arrays. Device arrays must be dense, live and +owned in the selected context; wrapped views are not silently staged. + +## Numerical witnesses and bounds + +The focused fixtures have 16 fine time samples, eight coarse time samples, two +modes and three nodes. They exercise chunks of one, two and three nodes, all +prefactor forms and both kinds of Kerr field reconstruction. The independent +reference performs direct 256-bit DFTs, complete modal matrix sums and the +explicit cubic response. It does not call the production FFT, contraction or +response helpers. Constant inputs, maps, material coefficients and profiles are +dyadic; complex harmonic carriers are treated as their supplied binary64 values. + +Let `R` bound the input maximum component modulus, `S` and `P` be the maximum +absolute row sums of the synthesis and projection, `m` the stored coarse-bin +count, and `n=16`. The conservative inverse gain `a=2mS/n` covers the real +Hermitian and analytic representations. On the tested position interval, density +is at most `9/8`, the Kerr coefficient is `1/8`, and the sum of the relevant +analytic cubic factors is at most one. All windows have magnitude at most one. +The represented prefactor's scalar multiplier is at most `5/4`. Thus, with +`F=max(abs(prefactor))*5/4`, + +```text +C(R) = F n P (9/64) (a R)^3, +L(R) = F n P 3(9/64) a^3 R^2 +``` + +bound the source magnitude and its maximum-norm Lipschitz constant. These +absolute envelopes are formed before any cancellation in inverse transforms, +maps, cubic terms, projection or the forward transform. + +For the finite transform fixtures, the qualification model assumes vendor +twiddle components within `2u`, correctly rounded ordinary scalar operations, +and gradual underflow. Butterfly counts alone do not establish that twiddle +hypothesis. The actual CUDA tests check the resulting outputs against the direct +MPFR references; no general cuFFT accuracy theorem is claimed. A conservative +8,192 component operations covers both 16-point transforms (including real +splitting), two-mode and three-node sums, cubic operations and the represented +degree-one scalar weights. The local source allowance is +`delta = gamma_8192*C(R) + 8192*eta`, with `u=2^-53`, `eta=2^-1074` and +`gamma_k=ku/(1-ku)`. The product cross terms are included by this single gamma +bound, rather than adding first-order estimates after cancellation. + +The one-step and eight-step witnesses use the actual two-stage Heun RK leaf and +the common fixed-step session, at `h=1/128 m` with exact zero linear flow. A +second MPFR reference applies precisely that discrete RK method, so no global +accuracy tolerance conceals a changed stage history. All exact and perturbed +stages stay strictly within `R=1`, checked with their propagated allowance. +For `L=L(1)`, the discrete map's Lipschitz constant is +`1+hL+(hL)^2/2 <= exp(2hL)`. The error recurrence is + +```text +E_0 = 0, +E_next = exp(2hL) E + gamma_256 (1+h C(1)) + h (2+hL) delta. +``` + +The represented Heun state/stage updates use fewer than 64 scalar operations +per cell, with exact zero linear flow. The checked `hL <= 1/4` limits the +second-stage amplification of those local update errors to less than two; +`gamma_256` conservatively combines those update and component contributions. +The last term includes the second evaluation's sensitivity to the first source +error. The MPFR computation verifies the second-stage unit-ball margin using +`(1+hL)E + h delta + gamma_256(1+hC(1))`, and the next accepted field using its +updated `E_next`. Hard-mask zeros, unchanged inputs, failure-row ordering and successful +call counts are exact structural contracts, not tolerance comparisons. + +The host model additionally checks compact transfer counts, hidden FFT-buffer +aliases, no device allocation for precision refusal, and warmed zero CPU +allocations. Actual CUDA tests separately report device allocation, task-local +context/stream restoration, real plan storage and the one/eight-step session +results. Host orchestration allocations and vendor caches are not inferred from +the device allocation counter. + + +## Raman and plasma preparation + +`ModalPlasmaChannel(execution::KernelExecution, channel, density, preionisation; +quadrature, arithmetic)` accepts the existing host binary64 channel and optional +cycle rule. It first calls the ordinary host preparation constructor on current +array values. A record validated earlier is insufficient: its array storage is +mutable. Only after fresh validation succeeds are its owned coefficient, node and +weight arrays uploaded. Three private clone hooks check the exact copied shapes +and element types and retain scalar metadata without inspecting device values. +The field integral taps follow the same validate-then-upload sequence. Public +rate, integral and cycle constructors retain their complete value validation. + +`ModalSourceData(execution::KernelExecution, grid, map, prefactor; ...)` validates +the selected numerical owners. For envelope plasma it copies only immutable mask, +Drude and loss coefficients to temporary host arrays and applies the existing +inactive-band rule. These copies are preparation work, not retained state or an +advance-time field transfer. The old data constructor retains CPU behavior and +refuses device plasma without the execution policy. The source workspace similarly +forms its held-current spectral coefficients from explicit preparation copies. +No default plasma cutoff, material coefficient, cycle tolerance, refinement rule, +window or transform normalization changes. + +Each Raman component retains a host coefficient execution. CPU sources keep their +original execution; device sources use one CPU thread and a one-thread host FFTW +plan for bounded kernel reconstruction. Scalar decay/density profiles and undamped +kernel rows stay on the host. Each source evaluation rebuilds the coefficient-only +spectrum and copies it into the same persistent device spectrum. The numerical +drive, convolution, polarisation, projection and both convolution FFTs remain on +the selected device. There is no transfer of an evolving source field. A device +planning context is not reused as a CPU coefficient-planning context. + +All added storage is explicit in the ordinary owner-deduplicating ledger: + +| Retained owner | Shape and type | +|---|---| +| Raman host kernel and transform input | `(2*n_time,n_terms)` and `(2*n_time,)` binary64 | +| Raman host spectrum | `(n_time+1,)` complex binary64 per component | +| Raman device spectrum | `(n_time+1,)` complex binary64 per component | +| Raman host decay and fraction arrays | two `(n_terms,)` binary64 arrays per component | +| Plasma device spline, integral or cycle arrays | exact translated shapes and binary64 types | +| Plasma compact failure scratch and host mirror | two `(2,node_chunk)` machine-integer arrays | + +The existing Raman drive/convolution buffers, plasma pointwise work and projected +streams keep their previous shapes; their allocations now explicitly use the +selected execution. FFT-owned arrays and queried native workspaces retain their +separate ledger rules. CPU binary64 Raman aliases its host/device spectrum as +before, and ordinary CPU plasma needs no new status array. + +## Plasma failure reporting + +Each node's device thread scans its completed status column in increasing sample +order and writes `(first_sample, first_code)` or `(0,0)`. The synchronous readback +contains exactly two integers per node. The host then scans nodes in increasing +order. Thus each chunk/channel retains the original first-node/first-sample +failure, including the global node offset. Failure raises before projection or +source publication; the next channel does not consume the failed result. Inactive +columns are overwritten by the existing plasma kernels and yield zero status. +Readback execution, shapes, writable storage and overlap are checked before the +compact scratch is written. No full status matrix or evolving field is downloaded. + +## Response qualification model + +The new fixtures retain the existing source test's independent direct DFT and +modal sums, explicit causal Raman convolution and analytic instantaneous rate +`W(E)=k*E²`. The scalar cycle mean is `k*abs(A)²/2` and its loss moment is `k*A`. +The running integral reference is the stated trapezoidal recurrence, independently +implemented. Two channels, independent piecewise-affine profiles, preionisation, +taper, embedded projections and temporal absorption are tested separately and +combined. Field analytic/real Raman drives use their existing factors. Device +status decisions and unchanged inputs are exact structural assertions. + +For these finite, well-conditioned inputs, the single-source comparison retains +`gamma_8192` times the pre-cancellation absolute contribution envelope from the +independent source reference. Here the tests conservatively use `eps(Float64)` +in that gamma instead of unit roundoff. This also covers the reference's finite +direct-DFT evaluation. It is conditional on the finite FFT/twiddle hypothesis +above and on binary64 elementary-function readings within two ulps at the tested +arguments. The log-spline coordinates have magnitude below 40 and the rate is far +below its ceiling. The reference checks every nodal magnitude, with its propagated +field allowance, strictly between both clipping thresholds. In the envelope cycle, +the omitted angular tail has mean rate at most `delta_rate=k*field_min²` and loss +moment at most `2*delta_rate/min(abs(A))`. Survival/fraction change by at most +`T*delta_rate`; explicit material and spectral gains propagate those terms to an +absolute source allowance. Each fixture checks that this allowance is below +one-sixteenth of its positive source budget. No relative agreement is asserted +for a cancelled result. The cycle +refinement budget is not enlarged. These fixture checks are not a proof of vendor +transcendental accuracy throughout an arbitrary material table. + +The one/eight-step response witnesses use the same actual Heun leaf, `h=1/128`, +zero linear generator and fixed positions inside the original profile spans. +They compare with an independently applied identical recurrence. Let `a` bound +the inverse-transform/synthesis/taper gain, `M=a*R`, `T` be the sample duration, +and `b` the forward-transform/projection/prefactor gain. A cubic term contributes +`3*c*M²` to the nodal Lipschitz bound. A Raman term contributes +`3*c*d*dt*sum(abs(kernel))*M²`, where `d` is its declared drive factor. For each +quadratic plasma rate, both survival and ionisation fraction derivatives are at +most `2*k*T*M` in the maximum norm. Their products with the field are therefore +bounded by `1+2*k*T*M²`. Multiply this by the explicit density, current-integral +length, material coefficients, windows and held-current/Drude/loss factors, sum +channels, then multiply by `a*b`. The separate temporal source is linear and its +operator bound is added. All profile extrema here occur at represented affine +endpoints; prefactor norms of these affine fixtures are convex. The test helper +adds a positive 512-operation outward margin to this preparation-only bound. + +The reference checks every accepted and intermediate stage inside `R=1`, including +its propagated error allowance, and checks `h*L <= 1/4`. For both local source +errors use twice the source allowance (candidate plus independent reference), and +propagate them with the same Heun Lipschitz multiplier as above. The same positive component +derivation bounds the absolute source contributions by `C=L(R)*R`; the test +checks this bound at every reference stage and uses it in both local source +allowances. State formation has a separate `gamma_256*(R+h*C)` allowance. +No fitted floor or observed +difference sets the budget. Actual CUDA results, allocation counters and scoped +context/stream preservation must pass the supplied device suite before hardware +qualification; a serial host model is evidence only for ownership/orchestration. diff --git a/julia/CUDA_STORAGE.md b/julia/CUDA_STORAGE.md new file mode 100644 index 000000000..3b2f6fd21 --- /dev/null +++ b/julia/CUDA_STORAGE.md @@ -0,0 +1,134 @@ +# CUDA storage and control readback + +This internal boundary connects numerical arrays to the existing Julia-owned +control and transport code. It adds no device session, physics route, reduction, +public backend admission or change to the CPU arithmetic graph. CUDA execution and +FFT limitations remain those in [CUDA_FOUNDATION.md](CUDA_FOUNDATION.md). + +## Address spaces and alias intervals + +`_transfer_storage_span(array)` retains its existing result: either `nothing` for +empty storage or a checked, half-open `(lo, hi)` tuple of machine addresses. Known +host wrappers still use their whole parent span conservatively. The new independent +`_transfer_storage_space(array)` classifies qualified storage: + +- Dense Julia Arrays and PythonCall arrays use `_HostStorageSpace()`; supported + wrappers inherit their parent's space. +- Dense device-memory CuArrays use a token containing the retained `CuContext`, + including its vendor context identity. Raw equal pointer integers in different + contexts do not establish overlap. +- Unknown storage refuses. CUDA mapped/unified memory does not inherit the dense + device-memory contract. A released nonempty array reference or invalid context + refuses before obtaining a numerical address. Existing empty alias semantics + remain unchanged. + +Only equal address spaces compare `Base.mightalias` or byte intervals. Mutable +gather-index dependencies are still checked in both directions, including across +different numerical-data spaces: a host output can corrupt a host index vector +used by a device-backed view. Known wrapper parents remain conservative; dense +derived CuArray headers carry their own occupied interval. Arbitrary gathered +writable layouts remain refused by the existing affine/injective guard. + +The CUDA accessor first validates `array.data[]`, which checks both the particular +reference and shared lifetime, then checks context validity and the complete header +extent against retained bytes. It reads the allocation pointer plus the checked +byte offset without acquiring a vendor stream or marking a pointer as escaped. +The element stride is `Base.elsize(array)`, including padding, rather than an +assumption that `sizeof(eltype(array))` is the array stride. These representations +were checked against [CUDACore 6.5.1 array storage][cuda-array] and +[GPUArrays 12.2.0 reference ownership][gpu-reference]. + +`_retained_storage(value)` is a narrow opaque-owner extension point, defaulting to +`()`. The generated engine owner walk follows its explicitly returned numerical +buffers; it does not reflect through vendor handles, caches or unrelated metadata. +For `CUDAFFTPlan`, a real-transform preservation array is returned when present; +complex plans return `()`. This brings plan scratch into caller alias checks +without treating the whole vendor runtime as session-owned data. + +## Allocation payload and memory ledgers + +`_memory_array_owner(array)` returns `(owner_key, payload_bytes)` independently of +alias intervals. The host default follows the same parent chain and counts the +same owning Array as before. The CUDA method returns the live retained `Managed` +allocation and `sizeof(managed)`, whose `DeviceMemory.bytesize` describes the full +explicit payload. Derived headers copy a DataRef but share this Managed owner; +views and reshapes therefore count the allocation once even when they expose only +part of it. This is distinct from their occupied alias intervals. + +Pinned CUDACore rounds each nonempty pool allocation up to a multiple of four +bytes so subword atomics cannot touch bytes beyond the allocation. The retained +payload includes this padding; a host mirror and a transfer contain only the +logical elements. For example, a 21-element UInt8 readback retains 24 device bytes +and 21 host bytes. The independent payload assertions use the pinned allocation +rule, rather than assuming twice the logical array size. See the +[CUDACore pool allocator][cuda-pool]. + +A foreign `unsafe_wrap` header has its own retained memory descriptor and declared +extent. It does not retain the external allocation's original owner, so its ledger +does not invent that owner or its size. The caller must retain the external storage +for the wrapper's full use. Multiple independent foreign wrappers are not presumed +to be the same retained owner just because their pointers overlap. + +cuFFT's active native workspace remains counted separately once per raw plan, and +its explicit preservation array follows the allocation-owner ledger. CUDA allocator +reservations, driver/context state and released vendor caches remain process +overhead; this interface neither estimates them nor promises zero process memory +after session close. See issues [735][workspace] and [736][cache]. + +## Persistent numerical readback and upload + +`DeviceReadback(execution, T, dimensions...)` prepares three public fields: + +| Field | Meaning | +| --- | --- | +| `device` | Owned zero-filled numerical scratch in the execution memory space. | +| `host` | Persistent dense host Array with exactly the same shape and dtype. | +| `execution` | The prepared execution policy to which both buffers belong. | + +CPU execution aliases `device === host`; the usual memory ledger counts that +single owner once. A qualified CUDA execution owns distinct device and host +payloads. Nonnegative dimensions and the padded byte count are checked before +allocation. Element types are fixed-size numbers. Buffers must not be replaced +or resized after preparation. + +`readback!(work, execution)` requires the exact prepared policy and returns +`work.host` after synchronous completion. It performs no reduction, conversion, +coordinate selection or controller decision. CPU readback is an exact no-op; +device readback copies into the existing mirror. Future norm/status users should +store bounded per-column or compact numerical summaries in `device`, not silently +download a full evolving state at every trial. + +`copy_upload!(destination, source, execution)` copies a dense host Array into an +already allocated matching destination, preserving shape, dtype and units. +The CUDA method validates destination lifetime/context before writes, scopes the +prepared CUDA.jl context/stream, and synchronizes before returning. Both owners +remain rooted while an error path drains queued work; a cleanup failure retains +both errors. The CPU method accepts matching dense Arrays, returns immediately +for the identical array and refuses other overlapping headers before writes. +`copy_device!` still means same-context device-to-device copying; `upload` still +allocates new ownership. No global workspace or vendor policy is modified. + +## Qualification scope + +`device_storage.jl` and `device_readback.jl` tests cover source-free host and fake +address spaces, symmetric foreign/index dependencies, unsupported/released storage, +opaque numerical owners, payload deduplication, pre-write copy refusals and zero +warmed CPU allocation. The separate `cuda_storage.jl` test leaf requires an actual +CUDA device with scalar indexing disabled in its test process. It covers real +derived/foreign headers, unequal dtypes, contexts, released references, persistent +readbacks, transfer-error completion, and actual export admission against retained +cuFFT scratch. Hardware execution is not implied by host tests. + +Actual device results and independent review must be recorded before this leaf is +called qualified. Existing unfiltered CUDA JET failures remain visible under +[741][quality]; no report filter, skip, or public-admission relaxation accompanies +this implementation. The shared storage completion is tracked in [752][storage]. + +[cuda-array]: https://github.com/JuliaGPU/CUDA.jl/blob/v6.5.1/CUDACore/src/array.jl +[gpu-reference]: https://github.com/JuliaGPU/GPUArrays.jl/blob/v12.2.0/src/host/abstractarray.jl +[workspace]: https://github.com/LupoLab/solprop/issues/735 +[cache]: https://github.com/LupoLab/solprop/issues/736 +[quality]: https://github.com/LupoLab/solprop/issues/741 +[storage]: https://github.com/LupoLab/solprop/issues/752 + +[cuda-pool]: https://github.com/JuliaGPU/CUDA.jl/blob/v6.5.1/CUDACore/src/resources/backends.jl diff --git a/julia/DEFERRED.md b/julia/DEFERRED.md new file mode 100644 index 000000000..62769cb60 --- /dev/null +++ b/julia/DEFERRED.md @@ -0,0 +1,88 @@ +# Deferred Julia scope + +The maintainer selected binary64 CPU and CUDA as the SEP 48 implementation baseline +on 11 November 2026. These records preserve unfinished work without admitting it or +making it a hidden requirement of that baseline. Public unsupported selections keep +their named refusals. No failed qualification has become a pass. + +## Binary32 CPU with binary64 wide arithmetic + +The modal/spatial kernels, three march families, observations and services have an +internal implementation. All 59 distinct short composition cases have passing latest +results, including the corrected 32-case physical spectral-band subset. The separate +six-case Adams-versus-RK physical campaign completes all cases: four pass, while both +helium cases meet every absolute envelope but fail the unchanged twice-RK criterion. +Independent 16/32-step binary64 references settle to at most `2.514e-15` across scored +metrics. Identical NumPy binary32 helium controls pass. See +[CPU_SINGLE_ADAMS_QUALIFICATION.md](CPU_SINGLE_ADAMS_QUALIFICATION.md) and issue 753. + +The reduced-log plasma correction and population ownership guard are independently +reviewed at `e690ef30` and `cd409ee3`. ADR-080 states the CPU elementary-function +boundary; it does not establish an all-Float32 implementation inside vendor libraries. + +Remaining: resolve the physical comparison, complete the precision/restart/admission +matrix and x86 measurements, review the final composition, then enable public admission +only after its required evidence passes. Binary32 input noise remains refused. + +Run the retained managed qualification explicitly with +`uv run --no-sync python tools/check_julia.py precision` after publishing a matching +setup and exporting its identity as for the baseline Julia lane. This command runs +all seven deferred numerical modules and treats every skip, failure or error as a +failure. The baseline `python` phase excludes those modules explicitly; it retains +binary64 sessions, public refusals, pure precision lowering and shared conformance. +The Julia engine Core regressions continue to exercise the retained arithmetic. + +## Binary32 CPU with DF32 wide arithmetic + +DF32 replaces selected wide intermediates; the evolving state and FFTs remain +binary32. It is not a separate whole-state precision or backend. + +Certified constant, cumulative-table and expansion flows are attached to internal +RK, low-storage and Adams sessions. Portable same-precision Adams history is tested +across the two wide types and supported backend crossings. The reviewed Adams leaf +has 26,755 independent assertions; its integrated bridge/history milestone is +`ed3a2fcb`, with 51 managed cases plus two group and six boundary cases passing. +The arithmetic remains conditional on the documented RN-even/FMA/gradual-underflow +hypotheses and actual per-operation certificates. + +RK dense output is independently reviewed at `990871fb` (integrated as `ad5ab855`): +2,423 independent assertions pass, including MPFR factors, query preservation, +ownership and zero warmed allocations. Its engine attachment is integrated at +`98f6af3e`; 2,419 directly affected bounds-enabled assertions pass. +Python dense attachment remains refused and deferred. + +Adams dense output is an explicitly unqualified isolated draft at `973fc351`; no +numerical test completed before it was stopped. It is not part of the integrated +implementation. Remaining work includes that dense leaf, separable spatial assembly, +tabulated execution, final restart/admission coverage and performance measurements. +The reviewed mathematical notes retain their exact domain and conservative refusals. + +## Metal + +The integrated execution/FFT foundation at `035ee5ac` passes 308 actual Apple M5 Max +checks, including independent ownership, queue and transform witnesses. Aqua passes; +unfiltered JET remains failed (745). Precise Float32 arithmetic loses subnormal values +in 20 of 136 checks, including a normal-input product's FMA residual (739). The current +DF32 proof therefore does not qualify this device. Native-cache accounting and +unsupported transform shapes remain recorded in 743 and 744. Complete propagation, +arithmetic replacement and device qualification are deferred; public admission stays +closed. No further Metal-specific work is required for the selected baseline. + +## ROCm/HIP + +The foundation is preserved outside the integration branch at `1a4d8aea`, followed +by the reviewed aligned-stride correction `ef4ee80e` and the capture draft/fix +`3c00734d`. The stride correction has 151 independent host assertions. The private +capture witness was resolved as address erasure during Julia type canonicalization, +rather than a production capture defect. No corrected HIP qualification or AMD +hardware test followed deferral, and no AMD rental has occurred. +Unfiltered JET remains failed (750). Full propagation and AMD qualification are +deferred; public admission stays closed. Common/CUDA capture corrections are +integrated separately and do not require these ROCm commits. + +## Existing runtime limitations + +Issues 610, 620 and 669 retain the accepted main-thread and signal boundaries and +remaining runtime failures. The earlier instruction to defer rare runtime diagnosis +until core implementation is complete still applies. Required baseline checks must +report their actual results; no deferred record silently waives a failing check. diff --git a/julia/DF32_ADAMS.md b/julia/DF32_ADAMS.md new file mode 100644 index 000000000..82c1ac198 --- /dev/null +++ b/julia/DF32_ADAMS.md @@ -0,0 +1,320 @@ +# Certified DF32 Adams execution + +This internal CPU package implements landed exponential Adams for binary32 state +and DF32 complete factors. It does not admit public DF32 execution, devices, +separable spatial operators, tabulation or dense output. The numerical assumptions +are those of [WIDE_ASSEMBLY.md](WIDE_ASSEMBLY.md) and +[DF32_BOUNDS.md](DF32_BOUNDS.md); state scaling follows +[PRECISION.md](PRECISION.md). Binary64-wide Adams retains its existing graph. + +## Frozen interfaces + +```julia +DF32AdamsFlow(execution, operator, state::AbstractMatrix{ComplexF32}, + spec::WideStartSpec, policy::AdamsControlPolicy; + history::Union{Nothing,WideStartHistory}=nothing, tabulate=false) + +DF32AdamsSeed(slot::Int, position::Float64) + +prepare_df32_adams_trial!(flow, history::AdamsHistory, stencil::AdamsStencil, + site::DF32TrialSite; seed::Union{Nothing,DF32AdamsSeed}=nothing) + +adams_trial!(work, state, position, step, history, stencil, source!, + trial::DF32AdamsTrial, rate!, execution; source_absent=false) +``` + +The token binds one owner, history, active generation, actual supplied step, raw +origin and canonical destination, actual replay cursor, selected orders and every +sample coordinate/kind/slot/generation. A virtual accepted seed lets startup and +restart certify the complete first trial before invoking its source. The same +policy selects landing and stencil; no Python code or alternate controller does so. + +## Targets and transaction + +Write `z1=fl64(z0+h)`, `x=Phi(z1)-Phi(z0)` and `Q=x/h`. The supplied `h`, the +represented endpoint distance and canonical landing stay distinct. For actual +sample coordinate `zj`, the source weight is +`h*sum(c[j,k]*k!*phi[k+1](x))`. Transported compensation is the complete factor +`b[j]*exp((h-(zj-z0))*Q)*(h*D[j]-x)`, multiplied once by its binary32 sampled state. +The stored rate `D[j]` keeps its explicit prior-error radius and exact knot side. +Neither a small final phase nor a cancellation-rounded zero proves intermediate +range. Every actual exponential/phi argument retains the reviewed exact word and +assembly-error limits. + +Two coefficient/operation banks stage preparation. Failure changes only inactive +scratch, preserving the active token, numerical work, source counters, accepted +field/history and live rate provenance. A successful precommit check reserves all +generation updates before the nonthrowing provenance publication. The existing +portable source/state/rate schema is unchanged and remains raw scaled storage. + +All host certificate data and all per-slot raw/rate/error matrices are CPU-owned +and counted, including adopted restored records. DF32 exponent/moment buffers +replace the same-size binary64 work buffers; this does not remove the additional +history-provenance cost. No complete-factor array cache or session-lifetime global +cache is introduced. Warmed advancement must allocate zero bytes. + +The complete-factor derivation, explicit arithmetic bounds, storage inventory and +qualification evidence are recorded below as the implementation is qualified. + +## Complete-factor graph and outward error recurrence + +All statements here are conditional on IEEE round-to-nearest binary32/binary64, +finite protected intermediate operations and gradual underflow. They reuse the +primitive proofs and the six primary algorithms cited in `DF32_BOUNDS.md`; they do +not extend those proofs to a device with a different underflow model. Set +`u=2^-24`, `eta=2^-150`. The per-cell host certificate is deliberately expensive: +it traverses the represented graph, every required phi value and every complete +factor. It is an explicit CPU range/error guard, not a performance qualification. + +### Represented coordinates, rates and coefficients + +The paired divided-difference Clenshaw graph from `WIDE_ASSEMBLY.md` evaluates +`Q=(Phi(z1)-Phi(z0))/h`. Its scalar bundle retains the rounding of `z1`, actual +endpoint separation, supplied `h`, normalized coordinates and cross-knot jumps. +It is used directly; no assembled binary64 exponent is converted to DF32. +The exact target of the linear factor is the represented cumulative difference +at the *supplied binary64 endpoints*. Canonical delivery coordinates do not replace +those endpoints. The transport scalar retains the error of both subtractions in +`h-(zj-z0)`. Old sample positions, including a slightly future newest sample or +an old restored sample, are checked against the actual start geometry. + +The host coefficient recurrence is the existing direct Lagrange product graph. +It propagates a radius through actual-coordinate subtraction, division by `h`, +node differences, polynomial products, product denominators and integration. +For division of `(a,ra)` by `(b,rb)`, require a strictly positive downward bound +`d=abs(b)-rb`; the inherited radius includes +`(ra+(abs(fl(a/b))+rounding)*rb)/d`. `WIDE_ASSEMBLY.md` derives the host rounding +term, including binary64 subnormals. A denominator interval containing zero or +an unrepresentable host coefficient/radius refuses the trial by name. Integration +uses the exact positive integer divisors 1 through 7. All host radii are retained +when splitting coefficients; no caller-supplied coefficient is treated as exact. + +For a restored rate, `reconstruct_wide_rate` first encloses the represented +one-sided derivative and adds the discrepancy of the *actual saved binary64 +value*. The DF32 conversion adds its own error. The numerical complete factor +uses that saved value, not a replacement derivative. The live record retains its +position, accepted/predicted side, origin-wide provenance and generation. New +seed/endpoint records similarly retain their actual binary64 stored value and its +conversion/evaluation radius. The normalized rate representation below is built +from that raw value and the full inherited radius. + +### Normalized products and gradual underflow + +A complete scalar is `(m,e)` with complex DF32 mantissa `m` and integer exponent +`e`, representing `2^e*m`. The supplied binary64 `h`, every coefficient and each +actual saved rate are normalized *before* splitting into DF32 words. This matters: +forming an unscaled tiny DF32 step or rate first can erase a contribution later +rescued by another factor. Each complex rate uses one common exponent; component +split residuals are carried independently. + +After each complex product/addition the high-word maximum is normalized with +`frexp`. For a component scaling by `2^k`, round each word and renormalize with the +protected Fast2Sum. Binary scaling of a normal result is exact. A subnormal word +loses at most `eta`; the pair contributes at most `2eta`, and the implementation +allows `3eta` to include renormalization. Therefore + +``` +r_scaled <= upward(2^k*r_original) + 3eta. +``` + +Every positive binary64 radius scaling is itself rounded upward, including when +it underflows. Relative exponent alignment in a sum uses the same formula; a lost +small addend is covered rather than assumed zero. Normalized complex operands have +component magnitudes at most one; component sums/products stay below four before +renormalization. The primitive finite-range hypotheses are therefore checked +locally. Integer exponents cannot approach the machine limit: the order is at most +six, a host operand contributes at most 1074 binary exponents, and this fixed graph +contains fewer than 256 successive scaling/product operations. Even the loose +`256*(1074+150)` bound fits a 32-bit signed integer. No dynamic expression tree or +arbitrary number of factors is admitted. + +For checked arithmetic, the existing `_WideBall` additions/products carry all +input radii and the primitive local errors. Numerical closures execute the same +DF32 graph without the host error records. A radius that cannot be represented in +binary64 is a named refusal even if a more sophisticated scaled-radius proof +might certify the result. This is a declared conservative domain limitation. + +This factor representation does not widen the prerequisite `WideStartBinding` and +`WideRate` domains. Original operator inputs, the represented divided difference +and raw-rate words still obey their finite intermediate bound, `floatmax(Float32)/32`. +For example, the complete-factor helper can represent a supplied `1e-300` step +times a `1e300` rate, but a restored session with that rate refuses in the existing +rate-binding preparation. A source call cannot occur before that refusal. No +binary64 numerical fallback expands this first package's domain. + +Final state coefficients are narrowed only after the complete product/sum. Dropping +the low word and scaling the high word has component error bounded by + +``` +2^e*r + u*2^e*(abs(m.hi)+abs(m.lo)) + 2^-148. +``` + +The absolute term covers the final subnormal rounding and a possible double-rounding +boundary. A nonfinite ComplexF32 result refuses before any state/source write. +Errors are absolute; cancellation can make the relative error arbitrarily large. + +### Absolute phi and exponential errors + +The coefficient calculation needs orders zero through seven. `_da_phi` evaluates +the same protected functions as `double_float_functions.jl`, and implements the +absolute recurrences of `DF32_BOUNDS.md` section 5. For an exact zero argument the +reciprocal-factorial error is at most `2u^2/k!`. In the small branch the reduced +argument has magnitude at most one half, the 24-term tail is below `2^-106`, and +at most three doubling recurrences are required. The certificate uses the +conservative analytic `exp(1/2)<2`, followed by the declared product/addition +recurrences; it includes the additive underflow allowances at every doubling. +For the large branch a certified component lower bound, at least 2.98, bounds +`1/abs(x)` without assuming a binary64 square-root accuracy bound. The restricted +inverse error is `32u^2/abs(x)+32*(1+2^21)*eta`. Forward phi recurrence retains +absolute errors through subtraction, including near zeros and the overlapping join. + +If argument error is `b`, the defining integral gives, for k>=1, + +``` +abs(phi_k(x+delta)-phi_k(x)) <= b*exp(max(0,Re(x)+b))/(k+1)!. +``` + +For k=0 use the same numerator without a factorial. The exact-word range and +`b<=2^-27` function admission remain mandatory. The exponential local relative +allowance is `8192u^2+2^40*eta`, as already proved in the function package. To bound +positive exponentials in the host certificate, use +`exp(t)<=2^ceil(3t/2)` for t>0 (since `log(2)>2/3`), and one otherwise. This avoids +borrowing an unproved host libm accuracy bound. All non-exact positive sums, +products and quotients in these bounds round outward. + +### Complete source, compensation and defect factors + +With exact Lagrange coefficients `c[j,k]`, the complete source coefficient is +`h*sum(c[j,k]*k!*phi_(k+1)(x))`. Coefficients and `h` retain their separate exponents +through the entire sum/product. The corresponding absolute factor certificate +includes coefficient formation, represented phase, phi recurrence, scaled sums +and final binary32 narrowing. The corrector's endpoint source is sampled at the +actual raw endpoint and at the *predictor* state. + +Compensation evaluates + +``` +b[j] * exp((h-(zj-z0))*Q) * (h * (D[j]-Q)). +``` + +This is exactly the declared target `b[j]*exp(...)*(h*D[j]-x)` since `x=h*Q`; +it changes the floating-point evaluation graph relative to binary64-wide Adams. +The normalized saved rate and Q are subtracted before multiplication by normalized +h, retaining their full radii. The bound therefore retains the uncancelled rate +contributions even if the computed difference is zero. Every actual transport +argument is certified even when a weight/difference rounds to zero; a zero cannot +bypass function-domain admission. + +Factored defects use the same divided-difference decomposition as binary32-wide +Adams. Write `w_j=2^e*wn_j`; narrow `wn_j` to binary32, sum `wn_j*N_j` in state +precision, and multiply once by the complete DF32 integral with the retained `2^e`. +This avoids unrepresentable individual divided-difference weights. The certificate +separately reports the largest normalized-weight error and complete-factor error. +For a state-error bound those quantities must be multiplied by the actual absolute +sample contributions and combined with the state summation error. A factor +certificate alone is not a global propagation error estimate or adaptive accuracy +claim. + +## Ownership, publication and retained storage + +A flow owns its original immutable operator plus one `WideStartBinding`. The latter +owns copied original operator/error/DF32 arrays; it is not a problem-wide cache. +Each live compensated slot retains three complex matrices of 16 bytes per cell: +raw binary64 values, DF32 words and binary64 component radii. It additionally +retains a normalized complex DF32/integer-exponent matrix: 24 bytes per cell on a +64-bit host. Thus each slot costs 72 bytes per cell, apart from scalar metadata. +Adopted restored records share their three original matrices with the binding; +they are counted once, not copied again. A concrete tuple makes these nested +matrices visible to the existing retained-storage traversal. + +Both banks each retain separate candidate seed and endpoint rate records of the +same four-matrix layout. These are required to leave live provenance untouched +on a failed or rejected trial. For maximum order q, each coefficient record has +three `(q+1)^2` matrices, three `3*(q+1)` matrices and five `(q+1)` vectors: +`3*(q+1)^2+14*(q+1)` elements total. Each bank retains host values/radii, +scaled checked values/radii and numerical DF32/exponents separately, plus a bounded +stencil, positions/kinds/generations, q+1 full scalar bundles and their numerical +projections, normalized defect weights and exponents. Actual element sizes are +reported by `sizeof`; tests bind every retained matrix to the session ledger. +The work exponent and moment arrays use 16-byte complex DF32 cells, replacing +same-size binary64 buffers. State/source/defect/norm buffers retain their existing +state precision. There is no field-sized complete-factor cache. Completed flows +retain the original immutable operator reference but allocate no wide-operator, +rate or coefficient banks and execute no fabricated trial. + +Preparation checks shapes, complete retained-owner aliases, actual history and +rate generations before numerical writes. Only the inactive bank changes while +certifying. Successful publication binds the token to the history owner, site, +selected slots/kinds/coordinates and generation. A refused plan preserves the last +active token. A successful later plan or acceptance invalidates an old token. +The seed's live generation capacity is checked before its source/accounting; an +acceptance precommit checks destination capacity and payload before field/history +writes. The subsequent owned-array copies and generation publication are +nonthrowing under the synchronous owner contract. A source failure retains actual +call accounting and the existing poisoned-session semantics. + +Restored portable history remains raw: source/sample-state arrays are ComplexF32, +accepted state transport widens raw values exactly, and rates stay ComplexF64. +No physical rescaling or schema change occurs in this package. Dense retain on a +DF32 workspace refuses, and dense/spatial/tabulate/device requests refuse during +preparation. Those are explicit first-package limits, not completed Phase 3 work. + +## Python session and history attachment + +The internal Julia owner selects `DF32AdamsFlow` for binary32 landed Adams with +`wide="df32"`. The PythonCall factory supplies the same resolved policy object to the +flow and session, plus the original operator, launch scales and actual start. Python +neither forms complete factors nor drives trials. Public binary32 selection stays +closed pending the full qualification matrix. + +Before phase binding, Python detaches candidate portable arrays and Julia applies +the same scalar, layout and numerical compatibility checks used by restoration. +The shared validator preserves the existing restore order: layout, retained alias, +then numerical values. An incompatible candidate produces the ordinary field-reset +reason and contributes no coordinates or rates to the phase domain. An unexpected +bridge failure raises; it cannot masquerade as a field reset. + +The binding owns another immutable snapshot of the selected data. The actual restore +uses that selection, rather than rereading caller-owned arrays. A disagreement between +preflight and restoration is an error. Stored zero-based slot indices, accepted/predicted +sample identities and every raw rate row retain their original meaning. The portable +schema carries no previous wide type, so the adapter records that provenance as unknown +for every import; it never establishes zero prior error. + +The history coordinate enclosure includes accepted landing slack and actual raw +predictor coordinates, even when one is slightly beyond the requested endpoint. +A completed start validates and restores raw history without preparing an operator, +rate certificates or factor banks. It performs no new numerical trial or source call. +The active-start rate-provenance requirements remain unchanged. + +Managed witnesses in `test_cpu_df32_adams.py` cover landed orders 1, 3 and 6, +adaptive runs, plain/compensated history, binary64-wide and NumPy binary32 continuation, +lossless raw stores, completed starts and invalid-history resets. Ordinary replay and +cross-wide comparisons use SEP 33 accuracy envelopes with independent binary64 +step-size refinement; transfer bytes and logical source charges remain structural. + +## Qualification scope + +The focused tests use exact-rational Vandermonde bases and independent 256-bit +defining series/integrals for all six Adams orders. Each complete-factor allowance +is fixed before comparison. An alternating-source history makes every scored +high-order defect nonzero; its contribution/error derivation must certify a bound +smaller than one quarter of the defect. The predictor/corrector tests propagate +source sensitivity separately from complete-factor errors. Rescued large/tiny +factor operands are distinguished from the narrower admitted binding domain. + +Actual eight-step plain/compensated and short adaptive sessions test work counts, +rejections, restarts, raw/canonical replay coordinates, sampled-rate discrepancies, +generation exhaustion, stale tokens and offset-buffer aliases. A scaled four-point +FFT/Kerr example uses an independent MPFR PEC recurrence and an explicitly stated +finite FFT/twiddle error hypothesis; it does not infer transform accuracy from an +operation count. The unchanged binary64 and binary32-wide64 Adams, dense and service +tests exercise the default hooks. Warmed advancement, factor preparation and +publication retain zero allocation on the tested CPU task budgets. + +Emitted numerical helper code is checked for binary32 arithmetic without binary64 +extension, unsafe floating-point flags, vendor transcendental calls or GC pool +allocation. This is evidence for those CPU helper specializations, not a device or +whole-call-graph claim. The CPU certificate still evaluates every retained cell and +factor before every trial; no throughput, public-admission or full-run accuracy +qualification follows from these short numerical witnesses. diff --git a/julia/DF32_ANALYSIS.md b/julia/DF32_ANALYSIS.md new file mode 100644 index 000000000..5cbfff6c0 --- /dev/null +++ b/julia/DF32_ANALYSIS.md @@ -0,0 +1,605 @@ +# DF32 phase and transcendental error analysis + +This is a preparatory analysis for [SEP 48](../docs/dev/seps/sep-0048-julia-backend.md), +not an implementation or a qualification report. It does not advance the session gate +or establish that any GPU satisfies the arithmetic hypotheses below. The derivations +are independent of the experimental implementation. + +The principal conclusions are: + +- A three-word binary32 expansion of `2π`, exact integer turns, exact product + transforms and accurate double-word subtraction give a small **absolute** reduction + error. For the construction below it is less than `38u²` radians when the selected + remainder is bounded by `22/7` and the turn count is at most `2²⁴`. +- Exponent assembly, not that reduction, can dominate the error at large phase. A + split of one already assembled binary64 value and a product of two independently + split values have different bounds. Cancellation in an expansion needs its own + condition measure. +- A sine/cosine pair followed by one Newton normalization does not remove its + first-order tangential error. A device library's accuracy must enter the budget. + An alternative full-wide exponential has a useful conditional bound derived below; + it still needs implementation, finite-range handling and device qualification. +- A relative bound for a `φ` function near a zero needs a conditioning factor. + Binary32's smallest normal is a range floor, not an estimate of cancellation error. + The error of the complete field increment must be bounded separately. +- The admissible phase ceiling is an output of these bounds and the chosen algorithm. + Neither the experimental `8u` propagator witness nor its sampled `φ` errors are a + universal implementation tolerance. + +## 1. Sources, notation and proof boundary + +Let `RN` denote binary32 round-to-nearest, ties-to-even, and let + +$$u=2^{-24},\qquad \eta=2^{-150},\qquad f_{\min}=2^{-126}.$$ + +Here `η` is half the smallest binary32 subnormal. A normalized double word represents +the **exact real sum** `x = xh + xl` and satisfies `xh = RN(xh + xl)`. The magnitude +condition on the low word alone does not replace this definition at ties. + +The following scalar bounds are the reusable inputs, not bounds for whole complex +expressions. They assume normalized inputs, the stated rounding order, correctly +rounded FMA and no exceptional exponent-range event: + +| Operation | Analysed algorithm | Relative error bound | +|---|---|---| +| DW + DW | AccurateDWPlusDW | `a = 3u²/(1−4u)` | +| DW + FP | DWPlusFP | `2u²` | +| DW × DW | DWTimesDW3, including the low-by-low product | `b < 4u²` | +| DW × FP | DWTimesFP3 | `2u²` | +| DW ÷ FP | DWDivFP3, nonzero divisor | `d = 3u²` | +| DW ÷ DW | DWDivDW3, nonzero divisor | `9.8u²` | + +Addition and division are from Joldes, Muller and Popescu, Algorithms 4, 6, 9, 15 +and 18 and their theorems [J17]. Multiplication uses Muller and Rideau's corrected +and improved Theorem 2.8 [MR22]. For DWDivDW3, the final product is DWTimesDW3: +the authors' formal supplement uses `DWTimesDW12`, whose definition includes the +low-by-low product. This resolves the conflicting algorithm name in J17 Algorithm 18. +The retrieved supplement requires `p ≥ 14`; binary32's `p = 24` satisfies it. + +Focused algorithm/theorem text and the corresponding supplement definitions were +checked. The Coq toolchain was **not** rerun. J17/MR22 establish scalar arithmetic +over an unlimited exponent range; they do not prove these transcendental functions, +GPU lowering, a phase ceiling or propagation accuracy. + +### Finite binary32 arithmetic + +For `TwoProd(a,b) = (RN(a*b), FMA(a,b,−RN(a*b)))`, a normal final product is not +enough to establish exactness of the residual. A sufficient condition from J17, +using leading-bit exponents `ea, eb`, is + +$$e_a+e_b\ge e_{\min}+p-1=-103,$$ + +with no overflow. Exact representability of the residual can also be established +directly for special operands. Zero factors are exact special cases. This condition +must be checked for the **actual product transforms**, not only the final function. + +With gradual underflow, a single RN operation admits an absolute model of the form +`|RN(t)−t| ≤ u|t| + η`. That does not extend a complete unlimited-exponent DW theorem +by adding one `η` at the end: every affected word operation and later amplification +must be accounted for. In particular: + +- Low-by-low products can underflow even when the high result is normal. +- A normalized pair loses its extra precision near the bottom of the binary32 range. + It cannot be treated as a 48-bit format with binary32's full exponent range. +- Multiplication by a power of two is exact only when its shifted result is + representable. Halving a tiny low word is not automatically exact. +- Division, complex squared norms and reciprocals need their own scaling/exception + policy. A naive `x²+y²` is not safe over the entire binary32 range. +- Exact zero, identity and masked-zero paths should bypass unnecessary arithmetic. + A deliberately omitted tiny term needs a derived absolute tail bound. + +The production choice must be either a proved safe range for each use, exact +power-of-two scaling with a proved reconstruction, or a word-level absolute-error +analysis of the exceptional range. Silent FTZ is not permitted by SEP 25. + +Apple's Metal Shading Language 4.1 specification permits subnormal flushing and +nearest-even or toward-zero rounding. Its precise single-precision `sin`, `cos` +and `exp` guarantee is only 4 ulp; fast math has different guarantees [MSL]. Thus +the language specification alone does not establish the DW hypotheses. Each +qualified compiler/device route needs the exactness, rounding and range probes +required by SEP 48; observed errors smaller than the specification are witnesses. +Passing probes alone does not strengthen a platform's guarantee over untested inputs. +The proof must identify its arithmetic assumptions and the ranges in which the +qualified route establishes them. + +## 2. Input representation and exponent assembly + +There are three different reference values: the mathematical operator, the +translated binary64 data, and the exact sum of the supplied DF32 words. Tests must +name their reference. The bounds below start from exact operations on the translated +data, with any translation/approximation error added separately. + +### One host assembly followed by one split + +Suppose a finite binary64 value `x` is converted using + +$$x_h=\operatorname{RN}_{32}(x),\qquad + x_l=\operatorname{RN}_{32}(x-x_h).$$ + +When the first rounding has the normal relative bound, the subtraction is exact in +binary64 and the residual rounding does not encounter the finite-range caveat, + +$$|(x_h+x_l)-x|\le u^2|x|.$$ + +If a binary64 assembly of a desired value `x*` has error `E64`, the bound becomes +`E64 + u²|x|`. The host assembly still needs its own cancellation bound; doing it +on the host does not erase that error. + +Normalize the pair after the split, for example with exact TwoSum. The raw two +conversions can fail the strong normalization condition at a tie. A binary64 +witness is `x = 1+3u−2⁻⁵²`: the first word is `1+2u`, the second rounds to `u`, +and RN of their exact sum is `1+4u`, not the first word. An exact normalization +preserves the represented sum and the bound above. The witness was checked with +binary32 conversions as well as by its binary exponent construction. + +### Device assembly + +For two split values representing `x*` and `y*`, with errors `Ex, Ey`, a DW product +has the conservative bound + +$$E_{xy}\le |x^*|E_y+|y^*|E_x+E_xE_y + +b(|x^*|+E_x)(|y^*|+E_y).$$ + +If both splits have the bound `u²` and the product uses DWTimesDW3, its leading +relative coefficient is `1 + 1 + 4 = 6`, not one. A truly exact binary32 factor +instead uses the DWTimesFP3 bound. Do not narrow an arbitrary binary64 step or +weight to binary32 and call that an exact factor. + +For a sum of `m` products `θ = Σ tj`, let `Ej` bound each product's absolute error. +Sequential accurate DW additions give the conservative bound + +$$E_\theta\le (1+a)^{m-1}\sum_j E_j + +\big((1+a)^{m-1}-1\big)\sum_j|t_j|.$$ + +This is useful even when the result nearly cancels. Expressing it as a relative +bound introduces `κ = Σ|tj|/|θ|`. Accurate addition prevents the sloppy-add +catastrophe; it cannot undo errors already present in its operands. + +Consequently, `H sup|Im L|` alone is not a bound on assembly error for an arbitrarily +cancelling representation of `L`. Admission also needs `Eθ`, or a conservative +term-magnitude bound that controls it. Constant and carrier-shifted combinations +should be assembled in binary64 and split once where the execution model permits. + +At the proposed candidate ceiling `Θ = 2²⁴·2π`, even a single split contributes as +much as `2πu` of absolute phase error. The corresponding two-split product bound +has leading contribution `12πu`. This explains why the same phase ceiling cannot +be assigned to all assembly paths without further analysis. + +## 3. Three-word `2π` reduction + +Write `τ = 2π` and generate successive RN32 residuals from a certified interval for +the mathematical constant, rather than splitting a binary64 approximation to it: + +$$t_1=\operatorname{RN}_{32}(\tau),\quad + t_2=\operatorname{RN}_{32}(\tau-t_1),\quad + t_3=\operatorname{RN}_{32}(\tau-t_1-t_2).$$ + +The resulting exact binary32 words are: + +| Word | Binary32 bit pattern | Exact hexadecimal value | +|---|---|---| +| `t1` | `0x40c90fdb` | `0x1.921fb6p+2` | +| `t2` | `0xb43bbd2e` | `−0x1.777a5cp−23` | +| `t3` | `0xa7f72ced` | `−0x1.ee59dap−48` | + +For `ρ = τ−(t1+t2+t3)`, exact rational interval arithmetic gives + +$$|\rho|<2^{-74};$$ + +its magnitude is approximately `4.2251996267949711e−23`. + +The calculation is reproducible without a floating-point value of π. Use +`τ = 32 atan(1/5) − 8 atan(1/239)`, with each arctangent enclosed by two successive +partial sums of its alternating rational series. Sixty-four terms give ample +separation from each binary32 rounding midpoint. After choosing a candidate word, +prove that the **entire** residual interval lies between its neighboring midpoints, +subtract that exact word from the interval, and repeat. The tangent addition formula +and the positive principal-angle interval establish the Machin identity used here. +The words, rounding intervals and strict `2⁻⁷⁴` bound were checked this way. + +### Integer selection is a separate obligation + +The turn count `n` must be an exact integer. For `|n| ≤ 2²⁴`, conversion to binary32 +is exact, so `TwoProd(Float32(n), tj)` supplies each exact two-word product. Their +nonzero operand exponents satisfy the sufficient residual condition above. + +A binary32 reciprocal/product followed by `round` is only a candidate turn count: +it need not select the mathematically nearest turn near a half-integer. Nor is +every integer just beyond `2²⁴` exactly representable in binary32. An implementation +must certify both the integer conversion and the remainder bound used below. + +One viable design uses an initial approximate integer, forms the accurate remainder, +then adjusts the integer by a few turns and recomputes the remainder from the original +phase. Accept either neighboring integer at an uncertain half-turn; periodicity +does not require a unique nearest integer. Certify `|r| ≤ 22/7` with the reduction +error included. This generous interval is just wider than `π`. Avoid a circular +test that assumes the reduction has already been exact. The candidate selection, +boundary handling and integer-overflow proof remain implementation work. + +### Reduction bound for a certified integer + +Let `x` be the exact supplied DF32 phase, `r = x−nτ`, `K ≥ |n|`, and `R ≥ |r|`. +Compute exact product expansions `Pj = n tj`, then + +$$r_1=\operatorname{DWAdd}(x,-P_1),\quad + r_2=\operatorname{DWAdd}(r_1,-P_2),\quad + \widehat r=\operatorname{DWAdd}(r_2,-P_3).$$ + +The exact partial remainders are bounded by + +$$R_1=R+K(|t_2|+|t_3|+|\rho|),\quad + R_2=R+K(|t_3|+|\rho|),\quad R_3=R+K|\rho|.$$ + +Propagating each accurate-add error yields + +$$|\widehat r-r|\le + a\big((1+a)^2R_1+(1+a)R_2+R_3\big)+K|\rho|. \tag{1}$$ + +For `K = 2²⁴`, `R = 22/7` and `|ρ| < 2⁻⁷⁴`, exact rational evaluation of this +upper bound is below `38u²` radians, approximately `1.327e−13`. This is a bound +relative to the supplied word pair, **not** to the phase before its split/assembly. +Add `Eθ` from section 2 for that comparison. The bound is not a proof that any +unimplemented reducer, integer-selection scheme or device realizes this sequence. + +## 4. The propagator pair + +Write the desired exponent as `z = a0+iθ`. Bound real assembly error by `Ea`, +phase assembly error by `Eθ`, and reduction error by `Er` from (1). + +### Binary32 sine/cosine and Newton normalization + +If the reduced pair is collapsed to one binary32 angle `t`, it adds at most +`u|rhat|+η` radians, subject to the usual range condition. Let +`q = (cos(t), sin(t))`, and let the library return `q+e` with `||e||₂ ≤ ε`. +The ideal Newton normalization is + +$$F(q+e)=(q+e)\frac{3-\|q+e\|_2^2}{2}.$$ + +Since `||q||₂=1`, expansion gives + +$$F(q+e)-q=e-q(q\cdot e)-e(q\cdot e) + -\tfrac12q\|e\|^2-\tfrac12e\|e\|^2,$$ + +and therefore + +$$\|F(q+e)-q\|_2\le\varepsilon+\tfrac32\varepsilon^2 + +\tfrac12\varepsilon^3. \tag{2}$$ + +The first-order radial error is removed; the tangential component remains. An +accurate norm and Newton step cannot turn a weak sine/cosine accuracy guarantee +into a strong phase guarantee. + +For a concrete implementation, let `EN` bound error in the computed squared norm, +and `D` bound error in the scalar correction `(1−||q+e||²)/2`. The correction error +adds at most `(1+ε)D` to (2); final FMA rounding adds its componentwise RN bound. +With exact square products and accurate DW addition, one may take +`EN ≤ a(1+ε)²`. If the subtraction of one is exact and the final scalar sum is RN, + +$$D\le\tfrac12\left[E_N+u(2\varepsilon+\varepsilon^2+E_N)+\eta\right].$$ + +These are explicit obligations on the implementation, including its use of FMA. +For `ε = κu`, the leading unit-vector budget is approximately + +$$E_\theta+E_r+(R+\kappa+1)u,$$ + +before magnitude evaluation and final magnitude-times-vector rounding. A safe +conversion of a `ν`-ulp componentwise library guarantee gives `κ ≤ 2ν` for normal +outputs. Apple's portable precise `ν = 4` guarantee alone leaves insufficient room +to prove the experimental `8u` witness by this bound. That is a limitation of the +guarantee and bound, not a claim that a measured device necessarily fails. + +The magnitude shortcut `exp(ah)·(1+al)` has separate errors: the library exponential, +rounding `1+al`, multiplication, and the Taylor defect + +$$|e^{a_l}-(1+a_l)|\le\tfrac12 a_l^2 e^{|a_l|}.$$ + +Both signs of the real exponent must be covered. Forming the backward value as the +reciprocal of the forward result adds a different error budget; it is not equivalent +to separately evaluating the two magnitudes. Likewise, a forward/backward product +or a long repeated-propagator drift test needs its own accumulated bound. + +### A conditional bound for a full-wide alternative + +A possible alternative evaluates the complete complex exponential in DF32 and +rounds the result once. This derivation does not select that implementation over the +candidate sine/cosine path; performance and the final proof must decide. + +Use the complex one-norm `|re|+|im|` for arithmetic estimates. Ordinary four-product +complex multiplication, with the verified real DW operations, has the bound + +$$\|\widehat{vw}-vw\|_1\le c\|v\|_1\|w\|_1, + \qquad c=b+a(1+b). \tag{3}$$ + +For complex squaring, its relative Euclidean error is at most `β = 2c`, because +`||v||₁² ≤ 2|v|²` and `|v²| = |v|²`. No cancellation factor is hidden here. + +Scale `w = a0+i rhat` exactly to `y = w/2ˢ` with `|y|₂ ≤ 1/2`. Select `s` using a +safe upper bound on the **whole word pairs**, not a potentially underestimated +binary32 norm of their high parts. The degree-18 Taylor polynomial, evaluated as +`Pm = 1 + y P(m+1)/m`, `m = 18,...,1`, `P19 = 1`, has analytic tail + +$$T\le e^{1/2}\frac{(1/2)^{19}}{19!}<2^{-75}.$$ + +For a conservative arithmetic bound use `r1 = 3/4 ≥ ||y||₁` and +`||Pm||₁ ≤ exp(r1) < 17/8`. Set + +$$Q=(1+a)(1+d)(1+c),\qquad E_{19}=0,$$ + +$$E_m\le Q\frac{r_1}{m}E_{m+1} + +(Q-1)\frac{r_1}{m}\frac{17}{8}+a. \tag{4}$$ + +This includes each multiplication, division by the exactly representable integer +`m`, and accurate addition of one. Exact rational evaluation at `u = 2⁻²⁴`, with +`b = 4u²`, gives `E1 < 37.209u²`. Since `|exp(y)| ≥ exp(−1/2) > 3/5`, take +`δ0 = (5/3)(E1 + 2⁻⁷⁵)` as the relative starting bound. + +After `s` squarings the relative bound is + +$$1+\delta_s\le(1+\delta_0)^{2^s}(1+\beta)^{2^s-1}. \tag{5}$$ + +For `s ≤ 6`, (5) is below `1.724e−11`; for `s ≤ 8`, below `6.909e−11`. +The latter is about `0.001160u`. These outward-rounded numerical bounds were +checked by rational evaluation of (4)–(5), not fitted to exponential samples. + +These numbers exclude argument assembly/reduction, exceptional ranges and the final +binary32 conversion. Argument perturbation `Δz` contributes at most +`exp(|Δz|)−1` in relative complex error; for a purely imaginary perturbation the +sharper bound is `|Δθ|`. A final componentwise binary32 conversion contributes +`u|value|₂+sqrt(2)η` as an absolute Euclidean error. + +For example, `|Re w| ≤ 87` and `|Im w| ≤ 22/7` need no more than eight halvings. +This is an illustrative conditional range, not an admitted range chosen by fiat. +The true real-part bounds must preserve both `exp(a0)` and `exp(−a0)` and every +intermediate. Even in this moderate range, tiny individual polynomial components +can invalidate the unlimited-exponent hypotheses; a finite-range implementation +must handle them before claiming (4)–(5). + +## 5. `φ` functions: tails, recurrence and conditioning + +For integer `k ≥ 1`, + +$$\varphi_k(z)=\sum_{m=0}^{\infty}\frac{z^m}{(m+k)!} + =\frac1{(k-1)!}\int_0^1 e^{(1-t)z}t^{k-1}\,dt,$$ + +with `φ0(z)=exp(z)` and `φk(0)=1/k!`. These definitions directly give + +$$\varphi_{k+1}(z)=\frac{\varphi_k(z)-1/k!}{z},\qquad + \varphi_k(z)=z\varphi_{k+1}(z)+1/k!,$$ + +and, by separating the integral or comparing power-series coefficients, + +$$\varphi_k(2z)=2^{-k}\left[ + e^z\varphi_k(z)+\sum_{j=1}^{k}\frac{\varphi_j(z)}{(k-j)!}\right]. \tag{6}$$ + +Only the exponential is periodic. Reducing the argument in the denominator of +the recurrence or evaluating `φk` at the reduced phase would compute the wrong +function. + +### Small-argument series + +For `|y|₂ ≤ r ≤ 1/2`, truncation after degree `M` satisfies + +$$|T_M|\le\frac{r^{M+1}}{(M+k+1)!} + \frac1{1-r/(M+k+2)}. \tag{7}$$ + +This follows from bounding the ratio of every later term. A small final term alone +is not a tail bound without such a ratio, and it says nothing about rounding already +accumulated in preceding terms. + +The integral supplies a nonzero lower bound in this disk: + +$$|\varphi_k(y)|\ge\frac{e^{-r}\cos r}{k!}.$$ + +Thus a relative bound is meaningful here. The ratio of the positive majorant +`exp(r)/k!` to this lower bound is at most `exp(2r)/cos(r)`. + +A production series should propagate the term error and the sum error separately. +Use (3), the DWDivFP3 bound for exact integer denominators, and the accurate-add +bound. Include errors in the initial `1/k!` coefficient; a coefficient formed in +binary64 and split has both its binary64 approximation error and its split error. +Multiplication by a pre-rounded reciprocal needs a different count than division +by an exact integer. Factorials should only be treated as exact binary32 factors +where representability has actually been established. + +Downward recurrence and each doubling (6) propagate **absolute** errors through +the sum of magnitudes of their terms, using the same multiplication/addition bounds. +An error budget for `φ0` is not automatically an error budget for every `φk`. + +### Upward recurrence + +Suppose `Eprev` bounds the absolute error of `φ(k−1)`, `C` bounds the error of +`c = 1/(k−1)!`, and `V` bounds error in a computed reciprocal `v = 1/z`. +Here `Eprev`, `C`, `V`, `Et` and `Ek` are absolute complex one-norm error bounds. +For exact `t = φ(k−1)−c`, the numerator error is bounded in the one-norm by + +$$E_t\le(1+a)(E_{\mathrm{prev}}+C)+a\|t\|_1.$$ + +After multiplication by the reciprocal, a valid bound is + +$$E_k\le\|v\|_1E_t+\|t\|_1V+E_tV + +c_{\mathrm{mul}}(\|v\|_1+V)(\|t\|_1+E_t), \tag{8}$$ + +where `c_mul` is (3), with no identification of the coefficient `c` and +`c_mul`. For `|z|₂ > 3`, `||1/z||₁ ≤ sqrt(2)/3`; this damps absolute error. +It does not guarantee small relative error at a zero of a resulting function. + +A reciprocal formed as `conj(z)/(re(z)²+im(z)²)` needs a positive-denominator +bound. Ignoring the finite-range exceptions, its denominator has relative error +at most `(1+b)(1+a)−1`; applying DWDivDW3 gives a reciprocal relative bound +`(1+9.8u²)/(1−[(1+b)(1+a)−1])−1`. This is approximately `16.8u²` and is +separate from the scalar division theorem. A scaled reciprocal is required outside +a range where those squares and residuals are representable. + +### Zeros and branch boundaries + +`φ1(2πin)=0` for nonzero integer `n`. More generally the relative input condition +number is `|z φk'(z)|/|φk(z)|`, which is unbounded near a zero. Accurate DW +subtraction cannot remove the error already present in a computed exponential. + +The integral gives a usable absolute input-error bound: + +$$|\varphi_k(z+\Delta z)-\varphi_k(z)| + \le |\Delta z|\frac{e^{\max(\operatorname{Re}z,0)+|\Delta z|}}{(k+1)!}. \tag{9}$$ + +For a concrete warning about an unconditioned relative test, choose the exact DF32 +input `x = t1+t2` from section 3 and consider `φ1(ix)`. Its exact phase distance +from `2π` is about `6.860497998e−15`. Replacing `2π` by the three-word constant +changes this tiny distance by approximately `4.2252e−23`, a relative change of +about `6.16e−9`, even before evaluating a polynomial. The experimental witness +coefficient `2⁻³⁶ max(1,|Im z|)` is only about `9.14e−11` there. This illustrates +why that witness cannot be promoted to a universal relative requirement for this +three-word algorithm. It is not a measured failure of a production function. +Indeed, even with exact exponential evaluation after the approximate reduction, the +relative error in this `φ1` evaluation is + +$$\frac{|\sin(\rho/2)|}{|\sin((x-\tau)/2)|}>6\times10^{-9}.$$ + +The strict inequality follows from the certified constant intervals and +`t−t³/6 ≤ sin(t) ≤ t` for these positive small arguments. The true `φ1` magnitude +is about `1.09e−15`, far above binary32's smallest normal, so that range floor +does not address the conditioning in this example. + +A branch at magnitude `B < π` has a useful mathematical property: for every +`|z|₂ ≤ B`, rotate the integral by `exp(−i Im(z)/2)` to obtain + +$$|\varphi_k(z)|\ge + \frac{e^{\min(\operatorname{Re}z,0)}\cos(|\operatorname{Im}z|/2)}{k!}>0.$$ + +This explains a possible series/recurrence split below `π`; it does not by itself +choose `B=3` or establish its best cost/error tradeoff. At a selected boundary, +qualify both algorithms and their overlapping bounds on neighboring representable +arguments. Their outputs need not be bitwise equal, but both must fit the same +function and downstream increment budget. + +The current public Adams limit is six predictor nodes; the corrector may need the +next moment. Qualification must use the maximum moment index actually requested by +the finalized predictor, corrector and defect tables, not infer it from the four +orders in an old witness. Tests at extra orders are useful arithmetic stress tests +but do not expand admission. + +### From scalar errors to a field increment + +For a representative increment + +$$I=h\sum_{j=0}^{N-1}j!\varphi_{j+1}(z)G_j,$$ + +the contribution from errors in the functions is bounded absolutely by + +$$|\Delta I|\le |h|\sum_{j=0}^{N-1}j!|G_j|E_{j+1},$$ + +before errors in `h`, `Gj`, coefficient multiplication, accumulation and state +rounding. Their budgets also use sums of magnitudes. A tiny `φj` does not make +its **absolute** contribution inaccurate; a small difference of large weighted +contributions can nevertheless be ill-conditioned. This is the distinction required +by SEP 33 §7.1 and SEP 25. A scalar relative-error problem and a protected +field-increment mixed bound must not be conflated. + +## 6. Phase-domain construction for real sessions + +For every exponential argument formed by the method, bound the relevant integral +of the actual represented operator, including history transport, stage frame changes, +carrier shifts and both signs of a propagator pair. For scalar transport, + +$$\left|\operatorname{Im}\int_a^b L(z)\,dz\right| + \le |b-a|\sup_{z\in[a,b]}|\operatorname{Im}L(z)|.$$ + +The following conservative span implements SEP 48's stated model. Its validity still +depends on verifying the finalized session's argument call sites and history capacity: + +- For a fixed schedule, `hmax` is the largest actual prescribed step that may be used, + not the adaptive request's `dz_max`. Landing/clipping may reduce it. +- For a fresh one-step session, use `H ≤ hmax`, capped by the remaining run length. + Verify that every admitted tableau's stage/frame differences lie in that span; + an outlying stage coefficient requires a corresponding factor. +- For fresh Adams history, use `(qmax+1)hmax`, capped by `zend−zstart`. Include + the neighboring-order/corrector work, not just the currently selected predictor. +- For a history resume, let `A = zstart−zoldest` for **every retained row that can + still be used**. A conservative bound is + `H = min(A+(qmax+1)hmax, zend−zoldest)`. A partially filled history can retain + samples from much larger old steps; replacing `A` with the new `dz_max` is wrong. +- Invalid, future, non-monotone or out-of-profile restored positions refuse before + arithmetic. Field-only restart has no retained history age. + +The supremum must cover frequencies/modes actually represented and all intersected +position intervals, including the restored past. For a polynomial interval, endpoints +and certified interior derivative extrema suffice. A maximum of interpolation samples +or unverified floating-point root estimates does not establish a bound. A convenient +conservative alternative is an outward-bounded Bernstein representation: its scalar +polynomial lies between its coefficient extrema on the interval. Account for rounding +when constructing those coefficients. Other representations need their own enclosure +or a named refusal. + +Track assembly error alongside the phase bound. A shifted operator can have a small +phase and a badly conditioned sum; an external frame-restoration exponential may use +the unshifted phase. Each is a distinct bound obligation. + +A practical admission decision therefore needs all of: + +1. A certified span and operator bound for every argument family. +2. A bound on input/split/assembly error, including cancellation. +3. The reducer's integer and remainder certificate. +4. Real-part and intermediate representability bounds for both exponent signs. +5. The chosen transcendental algorithm's bound, propagated into the increment budget. +6. A qualified compiler/device arithmetic mode satisfying that algorithm's hypotheses. + +Where a useful bound can be expressed as `c1 u + c2 |θ|u²`, choose the phase +ceiling from the allocated tolerance, the derived coefficients and the integer limit. +For a target `Etarget`, the formal inequality is + +$$|\theta|\le\frac{E_{\mathrm{target}}-c_1u}{c_2u^2},$$ + +only if its numerator is positive and all other conditions hold. Conditioning may +require an absolute assembly test instead of a single global `c2`. A refusal off +Metal should name `wide="binary64"`; Metal must refuse rather than silently degrade. + +## 7. What is established, and what remains + +Established by source reading or the derivations here: + +- The specific scalar arithmetic bounds and their unlimited-exponent hypotheses. +- Certified three-word constant bits, its strict residual bound and conditional (1). +- The effect of separate splits/products and cancellation on exponent assembly. +- Newton normalization's retained tangential error, and the vendor-bound limitation. +- The analytic Taylor tail, arithmetic recurrences (3)–(5), `φ` tail (7), recurrence + error form (8), input sensitivity (9), and the near-zero conditioning distinction. +- The need to include actual replay steps, retained history and interior extrema. + +Not established, and required before phase 3 can be considered complete: + +- An implemented/certified turn-selection routine, finite-range primitive policy, + selected `φ` branch/order strategy, or final phase and real-part admission constants. +- A compiler proof or device test of nearest-even, correctly rounded FMA/division, + preservation of required subnormal behavior, or absence of accidental binary64. +- A production transcendental implementation satisfying these exact operation counts. +- End-to-end field/statistic parity, bounded drift, survival, performance, or GPU + qualification. No random sample or high-precision comparison replaces the bounds. + +Implementation tests should include exact rational primitive references; BigFloat +function references with precision/convergence checks; integer-turn boundaries; +points on both sides of multiples of `2π`; tiny and cancelling low words; both sides +of the `φ` branch; largest admitted real/imaginary arguments; actual replay steps +exceeding `dz_max`; and restored old history. Exact structural zeros remain exact. +Use separately derived absolute/mixed budgets around roots, and retain the full +field-increment conditioning and propagation sensitivity in session tests. + +## References + +- [J17] M. Joldes, J.-M. Muller and V. Popescu, “Tight and Rigorous Error Bounds + for Basic Building Blocks of Double-Word Arithmetic,” *ACM TOMS* 44(2), article 15 + (2017), [doi:10.1145/3121432](https://doi.org/10.1145/3121432). + [Author manuscript](https://hal.science/hal-01351529v3). +- [MR22] J.-M. Muller and L. Rideau, “Formalization of Double-Word Arithmetic, + and Comments on ‘Tight and Rigorous Error Bounds for Basic Building Blocks of + Double-Word Arithmetic’,” *ACM TOMS* 48(1), article 9 (2022), + [doi:10.1145/3484514](https://doi.org/10.1145/3484514). + [Author manuscript](https://hal.science/hal-02972245v2), + [authors' formal supplement](https://www-sop.inria.fr/members/Laurence.Rideau/DW_arithmetic-submitted_paper_release.zip). + The checked manuscript is dated August 31, 2021; its pagination differs from the + publisher's typesetting. +- [MSL] Apple, *Metal Shading Language Specification*, version 4.1, June 4, 2026, + §§8.1–8.4 and Table 8.1, printed pp. 368–370, + [official specification](https://developer.apple.com/metal/Metal-Shading-Language-Specification.pdf). +- W. J. Cody and W. Waite, *Software Manual for the Elementary Functions* + (Prentice-Hall, 1980), is the historical reduction reference named by SEP 48. + Its full text was not checked for this analysis; (1) is a derivation for the + explicitly stated three-word algorithm, not a theorem attributed to that book. diff --git a/julia/DF32_BOUNDS.md b/julia/DF32_BOUNDS.md new file mode 100644 index 000000000..08d27bd95 --- /dev/null +++ b/julia/DF32_BOUNDS.md @@ -0,0 +1,518 @@ +# DF32 function bounds and initial domain + +This is the derivation for the initial SEP 48 phase 3 function leaves. It does not +admit a runtime, qualify a device, or replace SEP 33's buffer-range rules. The scalar +primitives in `src/double_float.jl` are independently reviewed; the separate leaves +are in `src/double_float_functions.jl`. Bounds were fixed analytically before +numerical comparisons; their additional finite-underflow proofs need independent +review as well as numerical witnesses. + +The initial domain is deliberately smaller than the nominal SEP 48 phase target: + +\[ + |\Re z|\le16,\qquad |\Im z|\le2^{20},\qquad + |\delta\Re z|+|\delta\Im z|\le u/8,\quad u=2^{-24}. +\] + +Here `z` is the exact real sum of the stored word pairs, and `delta z` is the +difference from the argument whose mathematical function is requested. The last +condition includes representation and assembly; a bound on the net phase alone +does not establish it. All exponents are dimensionless. + +## 1. Arithmetic model and source boundary + +The current derivation assumes binary32 round-to-nearest ties-to-even, correctly +rounded division and FMA, gradual underflow, and no overflow. No contraction or +reassociation is permitted except the explicit FMA operations. Set + +\[ + \eta=2^{-150},\qquad A=\frac{3u^2}{1-4u},\qquad \alpha=4u^2. +\] + +`eta` is half the least positive binary32 subnormal. A correctly rounded ordinary +product, division or FMA has absolute error at most `u*abs(exact_result)+eta`. +This is an error bound, not permission to enable flush-to-zero. + +The normalized-pair condition is `hi = RN(hi+lo)`, not just a magnitude inequality. +It implies `abs(lo) <= u*abs(hi)`; a subnormal high word necessarily has zero low +word. Internal results may contain subnormal words even though checked host +preparation deliberately refuses them. + +The six selected algorithms and their tighter bounds when all their original +hypotheses hold are from Joldes, Muller and Popescu [J17], with the multiplication +correction of Muller and Rideau [M22]. Algorithm 18's final multiplication is +Algorithm 12, `DWTimesDW3`: the printed name `DWTimesDW2` conflicts with its +algorithm number/proof, and the authors' formal supplement confirms Algorithm 12. +The formal division theorem uses `p >= 14`; binary32 satisfies it. + +The bounds below are additional conservative derivations for these exact graphs +with gradual underflow. They are not attributed to the papers' unlimited-exponent +theorems. Metal 4.1 permits toward-zero rounding and subnormal flushing [MSL]; +neither its language specification nor disabled fast math establishes this model. +A Metal path needs a separately established model and propagated allowance before +using these bounds. CPU evidence does not establish CUDA or ROCm behavior either. + +### 1.1 Addition and product transforms + +Every binary32 word is an integer multiple of `2^-149`. If the exact sum or +difference of two words is subnormal, it is already representable. Otherwise its +rounding is the same as in the unlimited-exponent format. Consequently, without +overflow, every addition/subtraction in TwoSum and Fast2Sum agrees with the +unlimited-exponent operation. Their exactness and the addition bounds carry over; +Fast2Sum still needs its exponent condition. + +TwoProd instead satisfies + +\[ + p+e=ab+\epsilon_p,\qquad |\epsilon_p|\le\eta. \tag{1} +\] + +The ideal residual is either representable or is rounded in the subnormal range. +A normal `p` alone is not sufficient for exactness: for +`a=b=(1+2^-23)*2^-63`, the normal rounded product loses residual `2^-172`. + +### 1.2 Conservative scalar bounds used by the functions + +Write `x`, `y` for exact pair values and `f` for a binary32 scalar. Under the model +above, with finite intermediate results: + +| Operation | Function-use absolute bound | +|---|---| +| DW + FP | `2u^2 * abs(x+f)` | +| DW + DW | `A * abs(x+y)` | +| DW x FP | `3u^2 * abs(x*f) + 3eta` | +| DW x DW | `7u^2 * abs(x*y) + 5eta` | +| DW / exact integer `m`, `1 <= m <= 32` | `8u^2 * abs(x/m) + 4eta` | +| DW / DW, positive `y`, `8 <= y.hi <= 2^42` | `16u^2 * abs(x/y) + (6abs(x)*(1+1/abs(y))+6)eta` | + +These constants deliberately exceed the no-underflow theorem constants. The last +two rows have restricted divisors; they are not new general division guarantees. + +For DW x FP, (1), the FMA error and exact final Fast2Sum give + +\[ + |E|\le2u^2|x_hf|+(2+2u)\eta + \le3u^2|xf|+3\eta. \tag{2} +\] + +For DW x DW put `P=abs(x.hi*y.hi)`. Expanding the rounded low product, two FMAs +and final low-word addition gives + +\[ + |E|\le(6u^2+8u^3+7u^4+4u^5+u^6)P + +(4+8u+4u^2+u^3)\eta. \tag{3} +\] + +Use `abs(x*y) >= (1-u)^2 P` to obtain the table entry. If `P` is normal, the +leading product dominates the final correction, so Fast2Sum is exact. If `P` is +subnormal, the high-product residual rounds to zero and the cross terms are at +most `u*P <= eta`; their nearest-even rounding is zero. The result is the leading +product and its lost low contribution is covered by the absolute allowance. +The analogous split establishes (2) when its leading product is subnormal. + +For integer division, allow rounding errors in both residual subtractions rather +than borrowing their unlimited-exponent exactness. With `R=abs(x.hi/m)`, direct +substitution in Algorithm 15 bounds its relative-size part by + +\[ + (7u^2+11u^3+10u^4+5u^5+u^6)R. +\] + +The absolute-underflow coefficient is below 4 for `1 <= m <= 32`. Since +`abs(x/m) >= (1-u)R`, the stated `8u^2` follows. If the leading quotient is +subnormal, multiplication by the exact integer has a representable residual; +the correction is at most one subnormal spacing. Fast2Sum therefore still has a +leading exponent at least as large as its correction, or has a zero first operand. + +For the restricted DW divisor, its first reciprocal is normal and the FMA +`1-y.hi*reciprocal` is exact: its nonzero residual is on a lattice no finer than +`2^-47`. The low-product rounding contributes at most +`u^2*(1+u)+eta`. If that product underflows, its magnitude is far smaller than a +nonzero high residual; the zero-high case is also valid for Fast2Sum. Otherwise +the authors' original Fast2Sum argument applies. Algorithm 18's corrected +reciprocal `v` consequently satisfies + +\[ + |yv-1|\le8u^2+4(1+|y|)\eta. \tag{4} +\] + +One way to check the constant is to set +`d=y*reciprocal-1`, with `abs(d)<=2u+u^2`. The exact Newton error is `-d^2/y`. +Add the low-product error, (2) for the correction, and DWPlusFP's `2u^2` bound. +The relative part is below `8u^2`; multiplying by `x` with (3) yields the final +table row. This proof uses the corrected Algorithm 12 final product. + +### 1.3 Complex operations + +Use componentwise accurate sums, and the four scalar products of the usual complex +product. Since + +\[ + \sqrt{(|ac|+|bd|)^2+(|ad|+|bc|)^2} + \le\sqrt2\,|a+ib|\,|c+id|, +\] + +the scalar bounds imply these convenient constants: + +\[ + \begin{aligned} + |E_{+}|&\le\alpha|x+y|,\\ + |E_{\times}|&\le\mu|xy|+\nu\eta, + &&\mu=15u^2,\quad\nu=15,\\ + |E_{/m}|&\le8u^2|x/m|+6\eta,&&1\le m\le32. + \end{aligned} \tag{5} +\] + +The product constant uses the sharper `A` when deriving it: +`sqrt(2)*(7u^2 + A*(1+7u^2)) < 15u^2`; the two scalar product allowances give +`10sqrt(2)*(1+A)eta < 15eta`. Adding the real scalar one has relative bound +`2u^2` in the complex norm. + +The computed squared modulus `d` has + +\[ + |d-|x|^2|\le11u^2|x|^2+11\eta. \tag{6} +\] + +For `2.99 <= abs(x) <= 2^21`, its positive high word is in the divisor interval +of (4). Forming `conj(x)/d` componentwise then gives + +\[ + |\widehat{x^{-1}}-x^{-1}| + \le32u^2/|x|+32(1+|x|)\eta. \tag{7} +\] + +No unscaled complex division is used outside this interval. + +## 2. Integer turn selection and three-word reduction + +Let `T=2pi`. Generate three words by successive nearest-even splitting of an +interval enclosing the mathematical constant, rather than splitting a rounded +binary64 constant: + +| Word | Float32 bits | Exact word lattice | +|---|---|---| +| `c1` | `0x40c90fdb` | integer x `2^-21` | +| `c2` | `0xb43bbd2e` | integer x `2^-46` | +| `c3` | `0xa7f72ced` | integer x `2^-71` | + +The constant remainder is positive and below `2^-74`. Directed 256-bit MPFR +intervals certify that both interval endpoints choose these same words and that +remainder bound. This is a derivation of the three-word scheme, not a claim about +an unread theorem in the Cody--Waite book. + +Use `r=RN32(1/T)`, `q=RN32(theta.hi*r)`, and nearest-even integer `n` to `q`. +For `abs(theta)<=2^20`, + +\[ + |q-\theta/T| + \le\frac{3u+u^2}{1-u}\frac{2^{20}}T+\eta < 1/32. \tag{8} +\] + +The absolute term covers a tiny quotient. Thus `n` is within one of a nearest +integer, `abs(n)<2^18`, and `abs(theta-n*T) < 17pi/16 < 27/8`. **No correction +branch is needed:** the exponential polynomial covers this slightly wider +remainder interval. Nearest-turn identity at half-turn boundaries is not required. +Conversion of this bounded integer to Float32 is exact. +The kernel first rounds `q` to an integral binary32 value, then uses a protected +`unsafe_trunc(Int32, ...)`: the proven bound makes this conversion exact and avoids +an unreachable allocating exception path inside the numerical kernel. + +Form each `n*cj` with TwoProd and subtract the exact product pairs with +AccurateDWPlusDW. Each nonzero product residual is at least `2^-71`, so these +particular products satisfy exact TwoProd even in finite binary32. If +`rj=theta-n*(c1+...+cj)`, three applications of the addition bound give + +\[ + E_R\le |n|\delta_T+ + A\big[(1+A)^2|r_1|+(1+A)|r_2|+|r_3|\big]<32u^2. \tag{9} +\] + +For a simple independent bound, use `abs(c2)<2^-22`, `abs(c3)<2^-47`, +`abs(n)<2^18` and `delta_T<2^-74`. They bound the three remainders by +`27/8+1/16+2^-29+2^-56`, `27/8+2^-29+2^-56` and `27/8+2^-56`. +The computed remainder has magnitude below `7/2`. When `n=0`, return the input +pair unchanged. + +## 3. Polynomial complex exponential + +After (9), the real part has magnitude at most 16 and the imaginary part less +than `7/2`. Choose a power-of-two scale so each component has magnitude at most +`1/4`; at most six halvings suffice. Exact comparison of a normalized pair with +these power-of-two thresholds avoids a rounded norm decision. Scale each word +once and normalize the pair; the complex scaling error is at most `3eta`. +The reduced argument has modulus below `1/2`. + +Use the degree-18 exponential polynomial in nested form: + +\[ + F_{19}=1,\qquad F_m=1+(y/m)F_{m+1},\quad m=18,\ldots,1. \tag{10} +\] + +Evaluate multiplication, division by the exact integer, then addition of real one +in that order. This avoids rounded reciprocal-factorial coefficients in the +exponential. Its truncation error is + +\[ + |e^y-F_1|\le e^{1/2}(1/2)^{19}/19!<2.586\times10^{-23}. +\] + +From (5), one multiplication/division pair has relative part at most `24u^2` +and absolute part at most `22eta`. Let `r=abs(y)<=1/2`. Propagating its error +through (10), with `abs(F_m)<=exp(r)`, bounds the polynomial error by + +\[ + e^r u^2\left[ + 2e^{(1+27u^2)r}+ + \frac{25}{1+27u^2}\big(e^{(1+27u^2)r}-1\big)\right] + +23\eta e^{(1+27u^2)r}. +\] + +Dividing by `abs(exp(y))>=exp(-r)` and including truncation gives the simple +relative bound `64u^2+64eta`. + +For each of at most six complex squarings, the relative error satisfies + +\[ + e_{j+1}\le(1+15u^2)(1+e_j)^2-1+2^{28}\eta. \tag{11} +\] + +The absolute term uses `abs(exp(argument))>2^-24` throughout the admitted real +range. Without underflow terms, (11) gives +`(1+64u^2)^64*(1+15u^2)^63-1 < 5042u^2`. Propagating its absolute terms, the +initial scaling error and (9) leaves the following deliberately rounded-up bound: + +\[ + \frac{|\widehat{e^z}-e^z|}{|e^z|} + \le B_E=8192u^2+2^{40}\eta. \tag{12} +\] + +This compares against the exact stored argument. Its difference from the requested +argument contributes at most `exp(abs(delta z))-1` separately. All high-word +products in this exponential stay far below binary32 overflow: the final norm is +less than `2^24`, and the unreduced phase never enters the polynomial. + +## 4. Corrected phasor and rounded propagator pair + +Evaluate (12) at `i*theta` and narrow its components once to binary32. Their +normwise error from the unit phasor is below `1.001u`. Compute their squared norm +using TwoProd on each component and accurate DW addition. Then form + +\[ + d=-\tfrac12\operatorname{RN}_{32} + ((N_h-1)+N_\ell),\qquad + (c',s')=(\operatorname{FMA}(c,d,c),\operatorname{FMA}(s,d,s)). +\] + +`N.hi-1` is an exact Sterbenz subtraction here. Equations (1) and the addition +bound imply the correction error is at most `4u^2+4eta`. If `v=q+e`, exact +radial correction leaves + +\[ + |v(1-(|v|^2-1)/2)-q| + \le |e|+\tfrac32|e|^2+\tfrac12|e|^3. +\] + +Including correction and final FMA rounding gives phasor error below `17u/8` +and squared-norm defect below `3u`. The correction removes radial first-order +error; no claim is made that it corrects phase error. No vendor sin/cos accuracy +assumption is used: both components come from the polynomial (10). + +Evaluate the positive magnitudes `exp(+Re z)` and `exp(-Re z)` using (12), then +narrow them to binary32. Their relative error is below `9u/8`. Multiplying each +by the corrected phasor, with conjugation for the backward pair, adds at most one +binary32 normwise rounding. Both magnitudes are normal in the chosen real range. +Component underflow is covered by the propagated absolute allowances. + +The pair error relative to the exact function of the stored argument is below +`9u/2`. Adding an assembly/input bound at most `u/8` gives **less than `5u`** +relative to each requested propagator. This leaves margin inside the accepted +`8u` target on this smaller domain. For a split-once constant, one convenient +form is `(9/2)u + 2u^2*(abs(Re z)+abs(Im z)) + 2B_host`, where `B_host` is the +host assembly's absolute error bound. +It is not a certificate for the nominal `2^24*2pi` phase domain. + +## 5. Phi functions: absolute bounds, including the join + +Use the defining series and integral, for `k >= 1`: + +\[ + \varphi_k(x)=\sum_{m\ge0}\frac{x^m}{(m+k)!} + =\frac1{(k-1)!}\int_0^1e^{(1-t)x}t^{k-1}\,dt. \tag{13} +\] + +They give `abs(phi_k(x)) <= exp(max(Re x,0))/k!` and +`phi_k'=phi_k-k*phi_(k+1)`. An argument perturbation of magnitude `b` contributes +at most `b*exp(max(Re x+b,0))/(k+1)!`; use `b*exp(Re x+b)` for order zero. +Near zeros these are absolute bounds. In particular, phi1 vanishes at nonzero +integer multiples of `2pi*i`; a relative-only tolerance is insufficient there. + +Provide orders `0:8`. Order zero alone uses (12). At exact zero return the stored +reciprocal-factorial tuple. Each nonexact table entry has representation bound +`2u^2/k!`, including binary64 preparation and its split. + +For the branch decision compute (6) and compare its high word with 9. The small +branch is valid for every argument of modulus at most 3.01, and the large branch +for every argument of modulus at least 2.99. Equation (6) and the high-word +rounding ensure the actual decision falls within these overlapping domains. +Thus both sides of the rounded join have independently valid bounds. + +### 5.1 Small branch + +Choose at most three halvings. Compare the high word of (6) with +`(1-4u)*4^s/4` to determine the scale. This downward margin dominates its squared +norm error and high-word rounding, ensuring `abs(y)<=1/2`. Scale words once as in +section 3; the equivalent full-argument perturbation is at most `24eta`. + +For highest requested order `N>=1`, use exactly 24 terms, `m=0:23`, with +`term_m=(term_(m-1)*y)/(m+N)`. The integer divisor is at most 31. Accurate complex +addition accumulates the terms. No data-dependent early stopping is assumed in +this first proof. If `S_N(r)=sum(r^m/(m+N)!,m>=0)`, + +\[ + B_N\le128u^2 S_N(r)+1024\eta+ + \frac{r^{24}}{(24+N)!\,[1-r/(25+N)]}. \tag{14} +\] + +To see the constants, term error is bounded by +`((1+2u^2)*(1+24u^2)^m-1)*abs(term_m)+30eta` for `m>0`. +Use `sum(m*r^m/(m+N)!) <= r*S_N(r)` and 23 additions with factor at most +`(1+4u^2)^23`. Their total is below (14). The tail is below `3.919e-33` at `N=1`. + +Obtain lower positive orders by `phi_k=1/k!+y*phi_(k+1)`. For rigorous error +propagation define a product bound using exact-magnitude bounds `U,V` and +absolute input-error bounds `B,C`: + +\[ + P(U,B,V,C)=(1+\mu)(UC+VB+BC)+\mu UV+\nu\eta. \tag{15} +\] + +Set `U_k=exp(max(Re y,0))/k!`, `c_k=1/k!`, `C_k=2u^2*c_k`. +The downward bound is + +\[ + B_k=(1+\alpha)[P(|y|,0,U_{k+1},B_{k+1})+C_k]+\alpha U_k. +\] + +Compute phi0 directly with (10), whose absolute error is bounded by +`(64u^2+64eta)*abs(exp(y))`. Raise the tuple through the exact identity + +\[ + 2^k\varphi_k(2y)=e^y\varphi_k(y)+ + \sum_{j=1}^k\frac{\varphi_j(y)}{(k-j)!}. \tag{16} +\] + +Apply (15) to each product. For every sum, with exact summand magnitude bounds +`U,V` and errors `B,C`, use `(1+alpha)*(B+C)+alpha*(U+V)`. +Multiply the resulting bound by `2^-k` and add `3eta` for the final exact-power +word scaling. Phi0's squaring uses (15) directly. Update the analytic `U_k` from +(13) after each of at most three doublings. Finally add `1024eta` for the initial +argument-scaling perturbation. This recurrence fixes each order's bound without +assuming a nonzero result or fitting a constant to tests. + +### 5.2 Large branch + +Set `U_0=exp(Re x)`, `B_0=B_E*U_0`, `V=1/abs(x)` and take the inverse bound `C` +from (7). For each order use the actual upward recurrence +`phi_k=(phi_(k-1)-1/(k-1)!)/x`. With + +\[ + W=U_{k-1}+c_{k-1},\quad + D=(1+\alpha)(B_{k-1}+C_{k-1})+\alpha W, +\] + +set `B_k=P(W,D,V,C)` and +`U_k=min(exp(max(Re x,0))/k!,W*V)`. This includes the cancellation in the +numerator. After either branch, add the argument-error bound following (13). +The difference of two branch evaluations at the same join argument is bounded +by the sum of their separately derived absolute bounds. + +The phase is reduced only inside `exp(x)`. Phi functions and their inverse +argument are not periodic and retain the original argument. + +## 6. Whole-run admission inputs owned by the session + +The master admission code must establish all of these before selecting this path: + +1. Bound every exponent argument's real part and phase by the domain above, + including the backward propagator and Adams transport of retained history. + Replay uses its actual longest prescribed step, not `dz_max`. An adaptive run + uses its admitted maximum. A fresh Adams span is at most `(q_max+1)*h_max`; + a resume adds the actual retained sample age and caps by the represented + distance from the oldest sample to the run end. +2. Bound the represented operator on complete intervals, including interior + extrema. Chebyshev absolute-coefficient bounds are conservative certificates; + a maximum of sampled values is not one. +3. Independently bound input/assembly error in the real-plus-imaginary norm by + `u/8`. Constant exponents assembled on the host and split once have split + error at most `u^2*(abs(real)+abs(imag))`, with host assembly error additional. +4. For a device sum of `n` real weights times complex terms, let + `S=sum(abs(weight)*(abs(real(term))+abs(imag(term))))`. Assuming each input + split has relative error at most `u^2`, a conservative assembled-word bound is + + `((1+10u^2)*(1+A)^(n-1)-1)*S + 10n*(1+A)^(n-1)*eta`, + + plus the independently propagated host/table-evaluation error. Cancellation + of the net exponent does not remove this contribution bound. A profile + evaluated by a recurrence needs that recurrence's own condition bound too. +5. Establish the arithmetic model on the selected device and preserve the stored + source identity, noise policy and same-precision history compatibility. + A portable history's actual sample coordinates, not snapped landing planes, + determine its retained age and coefficient arguments. + +Failure names the real-range, phase-range, assembly-budget or arithmetic-model +condition. Where available, it can name `wide="binary64"` as the alternative. +No single-precision noise or changed physics default follows from this document. + +## 7. Leaf API and qualification + +Host preparation: + +```julia +check_df32_function_argument(z::Complex{DF32}; input_error::Float64=0.0)::Nothing +``` + +It checks finite normalized words, the exact stored-component bounds and the +supplied finite nonnegative input-error bound. It does not discover that bound, +qualify hardware, or certify a future adaptive trajectory. Construction remains +through the existing `prepare_df32` scalar functions; session admission owns the +whole-run certificate. + +Protected allocation-free kernels, under that certificate: + +```julia +_df32_reduce_phase(theta::DF32)::DF32 +_df32_exp(z::Complex{DF32})::Complex{DF32} +_df32_sincos(theta::DF32)::Tuple{Float32,Float32} # sine, cosine +_df32_exp_pair(z::Complex{DF32})::Tuple{ComplexF32,ComplexF32} +_df32_phi_values(z::Complex{DF32}, ::Val{N}) # tuple, orders 0:N +``` + +No Base transcendental overload or runtime admission is added. New helpers remain +separate from the reviewed scalar algorithms. Tests must check directed constant +splits, turn boundaries and the selector allowance, exact zeros, both join paths, +phi zeros, cancellation, range refusals, subnormal intermediate witnesses, +operation-derived bounds against MPFR and zero warmed allocations. CPU generated +code must retain Float32 operations and explicit FMA without unsafe FP flags. +Numerical tests are witnesses to these bounds, not their derivation; device +qualification and complete propagation budgets remain separate requirements. + +## Primary sources + +- [J17] M. Joldes, J.-M. Muller and V. Popescu, *Tight and Rigorous Error Bounds + for Basic Building Blocks of Double-Word Arithmetic*, ACM TOMS 44(2), article 15 + (2017), [DOI](https://doi.org/10.1145/3121432), + [complete author text](https://hal.science/hal-01351529/document). +- [M22] J.-M. Muller and L. Rideau, *Formalization of Double-Word Arithmetic, and + Comments on "Tight and Rigorous Error Bounds for Basic Building Blocks of + Double-Word Arithmetic"*, ACM TOMS 48(1), article 9 (2022), + [DOI](https://doi.org/10.1145/3484514), + [complete author manuscript](https://hal.science/hal-02972245/document), + [formal supplement](https://www-sop.inria.fr/members/Laurence.Rideau/DW_arithmetic-submitted_paper_release.zip). +- [MSL] Apple, *Metal Shading Language Specification* 4.1, dated 2026-06-04, + sections 8.1--8.5 and Table 8.1, + [complete specification](https://developer.apple.com/metal/Metal-Shading-Language-Specification.pdf). + +Both complete arithmetic papers and the relevant supplement definitions were +checked. The supplement was not recompiled. The finite-underflow extensions and +function bounds in this document are new derivations requiring independent review. diff --git a/julia/DF32_DENSE.md b/julia/DF32_DENSE.md new file mode 100644 index 000000000..7fdf8a365 --- /dev/null +++ b/julia/DF32_DENSE.md @@ -0,0 +1,189 @@ +# Certified CPU DF32 dense observations + +The RK leaf retains the existing continuous extension for binary32 state and +certifies every represented phase in DF32. It is an internal CPU implementation, +not public single-precision, spatial, Adams-dense or device admission. The numerical +hypotheses and primitive/function bounds are those of +[WIDE_ASSEMBLY.md](WIDE_ASSEMBLY.md), [DF32_BOUNDS.md](DF32_BOUNDS.md) and +[DF32_EXECUTION.md](DF32_EXECUTION.md): RN-even arithmetic, explicit correctly +rounded FMA, finite protected intermediates and gradual underflow. No CPU evidence +establishes those hypotheses on a vendor device. + +## Construction and retained ownership + +```julia +RungeKuttaObservationWork(execution, state, tableau, dense_weights, + flow::DF32LinearFlow; arithmetic) +``` + +The ordinary work record and its coefficient algorithm are shared with the +binary64-wide path. `state` is already scaled `ComplexF32`, `arithmetic` retains +its original launch exponents, and `tableau` must equal the immutable translated +method bound by the flow. The dense weights remain translated input; Julia does +not select them from a stage count. Replay plus interpolation, per-step split +collars, other methods and unqualified operators keep their named refusals. + +The work's phase context borrows the exact immutable `WideStartBinding` created +for that flow. It holds two independent scalar operation records and a retention +generation. It borrows neither the mutable trial banks nor a trial token. Reusing +those banks cannot invalidate the retained accepted window. Direct mutation of +prepared operator, binding or work arrays is outside the ownership contract. + +The bounded numerical arrays are unchanged: five `ComplexF32` coefficient fields, +the exact finished endpoint, the observed field, one `ComplexF32` factor field, +one unpacked stiff mask, empty expansion-weight storage and one finite-check +integer per column. There is no additional full-field wide phase array. Each +scalar operation record retains its DF32 scalar bundle, host formation radii, +aggregate component errors, intermediate bound, coordinates and generation. +`runge_kutta_observation_memory` lists the owned arrays; shared binding arrays +remain counted once by the containing session's storage traversal. Scalar +metadata and object headers are separate from numerical array payload. + +The shared constructor hooks are `_rk_dense_admit(flow,state)` and +`_rk_dense_prepare(execution,state,tableau,dense_weights,flow; arithmetic)`. +Their `LinearFlow` defaults preserve the existing binary64-wide path. The +scheduler still owns admission of plane policy, endpoint commit, delivery, +warning continuation, snapshot priority and portable-history eligibility. + +## Actual intervals and certificate transaction + +For retained anchor `z`, supplied positive step `h` and raw endpoint +`r=fl64(z+h)`, the full-step branch uses + +\[ + X=\Phi(r)-\Phi(z). +\] + +For an actual interior requested coordinate `p`, the flow uses + +\[ + X_p=\Phi(p)-\Phi(z). +\] + +All supplied binary64 coordinates and operator data are exact operands of these +mathematical targets. The canonical landing is retained separately; it never +replaces `r` in the numerical expression. A query calls the existing paired +Clenshaw/expansion certificate with its actual `z,p` endpoints and the retained +`h`. It does not rescale the full-step phase, assume monotonicity or use an +endpoint maximum in place of the represented interior value. The correlated +same-interval graph and the cross-interval cancellation limits therefore remain +exactly those derived in `WIDE_ASSEMBLY.md`. + +Every queried argument retains the existing exact-word limits +`abs(Re)<=16`, `abs(Im)<=2^20` and summed assembly/input error at most `2^-27`. +An interior extremum may fail despite a certified full step. That is a named +observation failure before any factor or observed field write; the accepted +session endpoint, source work and history remain unchanged. + +Retention checks full-step phase and branch admission before changing readiness, +arrays or the previously retained scalar records. Only after success does it +publish the replacement scalar record and enter the ordinary coefficient/copy +path. Its existing nonfinite-input/coefficient failures still leave the new +window unavailable. A query similarly certifies into local scalar storage before +publishing its query record and filling factors. Certificate refusal preserves +the previous observed field and successful query record. No query advances the +flow's trial generation. Retention generation exhaustion refuses before mutation. + +## Certified stiff-bin decision + +The existing predicate is `abs(real(X))>1`. Let the checked real phase be a +normalized pair `v=hi+lo` with outward absolute radius `e`. Summing its words in +host binary64 produces `(c,ec)` using the existing host-error recurrence, then + +\[ + \ell=\operatorname{down}(c-(e+e_c)),\qquad + u=\operatorname{up}(c+(e+e_c)). +\] + +Thus the exact represented real phase lies in `[ell,u]`, including a low word +invisible to a rounded binary64 sum. The branch is certified nonstiff if +`-1<=ell` and `u<=1`, and stiff if `u<-1` or `ell>1`. Otherwise retention refuses +with `DF32 dense stiff-branch certificate straddles ±1`. It does not choose a +binary64 fallback or change the strict threshold. Exact threshold inputs and +sufficiently close neighbors can conservatively refuse; adjacent binary32 +values in the qualified fixtures are separated enough to admit. The numerical +mask then compares the same checked DF32 words exactly against one. + +This refusal is a conservative internal domain boundary, not a numerical-policy +change. If a required physical case reaches it, a sharper certificate or a +justified bound for both branch results is needed. No tolerance is fitted to +avoid it. + +## Shared polynomial and factor error + +The accepted stage derivatives remain binary32 values in the anchor's interaction +picture. The existing ordered contractions retain + +\[ +\begin{aligned} + r_1&=y_0,&r_2&=h\sum_j b_jk_j,&r_3&=hk_1-r_2,\\ + r_4&=r_2-hk_s-r_3,&r_5&=h\sum_j d_jk_j. +\end{aligned} +\] + +Interior nonstiff bins use +`P=r1+theta*(r2+(1-theta)*(r3+theta*(r4+(1-theta)*r5)))`, where +`theta=(p-z)/h`; stiff bins use the retained anchor. This is the existing +DOPRI5 continuous-extension form documented in `runge_kutta_observation.jl`, +with the same binary32 conversion, contraction and stage-sum order. The DF32 +change is confined to its represented linear factor. + +The factor kernel repeats the certified DF32 assembly and uses the corrected +forward propagator. `DF32_BOUNDS.md` establishes relative factor error below +`5u32`, including the separate `u32/8` assembly allowance. A computed exact zero +phase gives an exact unit factor after certification. The existing unit-factor +branch skips multiplication. No library binary64 exponential or binary64 +numerical phase is evaluated by this kernel. Host certificate arithmetic stays +binary64 as explicitly designed. + +Retention pays one complete phase-certificate traversal and a second checked +traversal for the branch, followed by the DF32 mask fill. Each interior query +pays its own complete host certificate and DF32 factor fill. This explicit CPU +cost is not a throughput claim or a reusable uniform certificate for devices. + +For the normal finite polynomial fixtures, fewer than 64 binary32 roundings lie +on a scalar coefficient/evaluation path, including translated-weight and step +conversion. `gamma128` additionally covers the final complex multiplication and +its certified factor error. The test forms an absolute majorant before every +signed stage contraction. If `B2,...,B5` bound the coefficient contributions and +`T,S` bound `abs(theta),abs(1-theta)`, use + +\[ + M=|y_0|_1+T(B_2+S(B_3+T(B_4+SB_5))). +\] + +Coordinate error is bounded separately by partial derivatives of the bivariate +polynomial in theta and its complement. The comparison allowance is +`exp(Re Xp)*(gamma128*M+(1+5u32)*Ecoordinate)` plus an explicit additive +subnormal allowance. To include all cross terms, write `c=sqrt(2)*gamma3` for +complex-product rounding. Since the polynomial's total degree is at most four +and `T,S` include their coordinate allowances, `Ecoordinate<=4M`. The coefficient +of `M` in the complete product bound is at most + +```text +(1+5u32)*(1+c)*gamma64 + 5u32 + 5c*(1+5u32) < gamma128. +``` + +The last term includes product rounding acting on both the polynomial and its +coordinate error. Thus the stated allowance does not drop either cross term. +Stiff bins use the anchor majorant. These bounds compare +independent represented arithmetic, not an adaptive global-error guarantee. +Short session witnesses separately bound recurrence amplification with absolute +stage sums and the matched scalar method, while keeping exact accounting and +endpoint copies structural. No bitwise agreement across task budgets or yields +is required. + +## Evidence and remaining scope + +Focused tests cover constant, cumulative Chebyshev and cancelling expansion +operators, independent MPFR polynomial/phase evaluation, actual queried interior +extrema, supplied-step versus endpoint subtraction, tiny positive landings, +threshold refusal/preservation, signed endpoint zeros and both raw/canonical +rounding directions. They also cover trial-bank reuse, retained foreign aliases, +invalid query/generation preservation, bounded inventory, adaptive dense delivery, +rejected and source-failed trials, and warmed allocations at one/two CPU threads. +Emitted IR checks are scoped to the owned numerical assembly/factor specialization; +its host certificate is deliberately outside that strict binary32 kernel boundary. + +Adams dense complete factors and selected rate-provenance retention are a separate +milestone. Public bridge admission and vendor qualification remain separate work. diff --git a/julia/DF32_EXECUTION.md b/julia/DF32_EXECUTION.md new file mode 100644 index 000000000..73b2c2351 --- /dev/null +++ b/julia/DF32_EXECUTION.md @@ -0,0 +1,172 @@ +# Certified DF32 trial flows + +This package connects the qualified CPU wide-assembly and function graphs to landed +binary32 RK and fixed low-storage RK4IP trials. It does not enable a public execution +option or a device. The accepted scope and arithmetic model remain SEP 48, +`DF32_BOUNDS.md`, `WIDE_ASSEMBLY.md` and `DF32_INTEGRATION.md`. + +## Frozen interfaces + +```julia +DF32LinearFlow(execution, operator, state::AbstractMatrix{ComplexF32}, + spec::WideStartSpec; tabulate=false) + +DF32TrialSite(origin::Float64, step::Float64, destination::Float64, + replay_index::Int) + +prepare_df32_trial!(flow::DF32LinearFlow, + scheme::Union{EmbeddedTableau,RK4IPTableau}, + site::DF32TrialSite)::DF32TrialFlow + +(trial::DF32TrialFlow)(output, input, origin::Float64, + destination::Float64)::Nothing +``` + +The flow constructs exactly one `WideStartBinding` from its retained original +operator and spec; there is no independently supplied operator/binding pair. It +retains that binding unchanged. State and source arithmetic are binary32 with the +spec's original-launch scales. CPU constant, represented cumulative and real-weight +expansion operators are admitted. The separate `DF32AdamsFlow` composition is described +in `DF32_ADAMS.md`. The engine's adaptive RK dense leaf is described in `DF32_DENSE.md`; +its Python attachment remains deferred. Tabulation and separable spatial operators +refuse during preparation. Other state precisions refuse by name. + +The site carries four independent facts: the actual accepted origin, supplied +positive step, canonical landed destination and replay cursor (zero for adaptive). +The canonical destination also remains inside the actual requested run, allowing +only the existing replay landing slack. The raw endpoint remains the actual +noncontracted `origin + step`; it is not replaced +by the canonical destination. RK stage coordinates use the actual supplied tableau. +RK4IP retains both separately computed half intervals. The replay cursor must identify +the actual supplied length and edge; adaptive sites have no fictitious minimum step. + +A prepared token binds the method, complete coordinate tuple, replay cursor and plan +generation. Both direct numerical trial entry and session advancement check it before +source calls or state/work writes. Direct callers first prepare a token and pass it +as the existing flow callback; passing an unprepared DF32 flow refuses immediately. +The session performs this preparation automatically after landing. Low-storage +preparation precedes its `in_flight` latch and first source invocation. + +## Transaction and arithmetic + +Each flow owns two fixed-capacity host banks of isbits operation projections. Each +retains the full DF32 scalar bundle, its scalar error bundle, exact endpoints/step and +numeric certificate radii/status; +the shared operator is retained only once. +The inactive bank receives a certificate for every anchor-to-stage/endpoint interval +(RK) or both half intervals (RK4IP). A refused certificate leaves the published bank +and generation unchanged. Publication follows all checks; a later successful plan +invalidates every earlier token before any output write. There is no per-session +history of plans, no field-sized factor cache and no allocation during warmed trials. + +Forward and backward applications use the same certified forward phase and choose +the corresponding result of `_df32_exp_pair`. The callback evaluates the protected +DF32 representation graph, forms that corrected pair, then multiplies its selected +ComplexF32 factor by ComplexF32 state. It never casts an already-assembled binary64 +phase or enters a binary64 transcendental. Only numerical DF32 arrays and isbits scalar +bundles enter the launched body; host certificate/range records stay outside it. +A structural zero interval copies the input exactly after admission and alias checks. +Each exactly zero assembled-phase lane also copies its input bits, including signed +zeros. This branch follows certification and never waives a range or error check. + +The existing certificate allows real/imaginary stored arguments up to 16 and 2^20, +and real-plus-imaginary assembly error at most 2^-27. Under the documented gradual +underflow/RN-even/FMA model, the corrected pair's relative error is below 5u for +u=2^-24. State-product and full-trial tests add their own arithmetic and sensitivity +allowances; this scalar pair bound is not a global propagation tolerance. These +function-domain bounds are necessary, not sufficient admission conditions. The +whole-expression certificate may refuse within them: a unit-step constant imaginary +phase of magnitude 2^20 currently exceeds the conservative u/8 assembly allowance. +Such a refusal remains explicit; this package does not relax the certificate or +claim the entire nominal function rectangle for arbitrary assembled inputs. + +Caller buffers must match the preparation's shape and ComplexF32 dtype. Output must +have an admitted writable layout; input/output must be disjoint or identical. Both +must be disjoint from the full flow ownership graph, including the original operator, +binding coefficient/error arrays, any retained saved-rate values, both operation +banks and failure scratch. Direct trial entry also checks every mutable state/workspace +array against that owner before any stage or source write. Checks precede all output +mutation. Finiteness is checked +outside launched bodies, preserving existing failure/poison accounting. + +## Shared hooks and ownership + +`source.jl` supplies default internal `_flow_shape`, `_inplace_flow`, +`_flow_arithmetic`, `_flow_start`, `_prepare_trial_flow` and `_check_trial_flow` hooks. +Existing LinearFlow and generic callback behavior remains unchanged. RK/low-storage +numerical entries check prepared tokens; their sessions prepare from actual landing facts. +No existing binary64 assembly, factor, stage or controller arithmetic changes. + +The parent integration owns module inclusion after `wide_binding.jl`, factories, +bridge records, exports, memory evidence and final public/device admission. This +package owns only `df32_flow.jl`, its focused test, this note, and the narrow hooks in +`source.jl`, `runge_kutta.jl`, `low_storage.jl`, `march.jl` and +`low_storage_session.jl`. + +## Storage and deferred work + +The original immutable operator arrays are shared with preparation. One owned +WideStartBinding retains DF32 coefficient/term arrays, binary64 error arrays and +breakpoints. Each active flow adds two bounded vectors of operation records and one +Int failure vector per column. Each isbits operation record occupies 400 bytes on +this 64-bit Julia ABI: 80 bytes of DF32 scalar metadata, 248 bytes of scalar radii, +32 bytes of aggregate certificate radii/status, and 40 bytes of coordinates/generation. +With N RK stages, the two banks occupy 800(N+1) payload bytes; RK4IP uses 1600 bytes. +The failure vector adds sizeof(Int)*n_columns bytes. Completed starts have empty banks. +Array headers and enclosing objects are separate host-object overhead, not numerical +payload. Tokens retain only their flow, site and generation. +All are explicit lifetime-owned inventory; no global cache or per-trial storage grows. +The general session ledger sees both banks and all binding arrays and excludes the +shared original operator. In this RK/low-storage package the binding's history +vectors are empty; the alias guard nevertheless visits saved matrices explicitly. + +Each preflight performs N+1 complete per-cell host certificate traversals for RK, +or two for RK4IP. Each actual flow application then repeats only the DF32 graph: +RK invokes 2N+2 flows (its zero-stage copies avoid graph evaluation), and RK4IP invokes +four. Polynomial degree and expansion-term count multiply that work. This CPU +implementation intentionally pays that certificate cost and makes no throughput or +device qualification claim. A reusable uniform certificate or explicit device-safe +strategy is still required before a device can use this boundary. + +The separate [DF32 Adams flow](DF32_ADAMS.md) now certifies actual nonuniform +coefficient formation, phi absolute error, transported sampled-rate provenance and +complete landed source/compensation/defect factors before narrowing. Its transaction +places certification before seed-source calls and history/ledger mutation. Dense +integrals remain additional work; binary64 exponent/moment callbacks do not establish +DF32 admission. + +Separable spatial operators also remain refused: the protected squared-wavevector +subtraction, branch at real(q)=0, complex square root, frame cancellation and loss +combination need their own bound. Host split-once preparation must retain an explicit +assembly radius; casting the current binary64 rate or phase supplies no such proof. +The current modal binding and function domains do not qualify that representation. + + +## Internal Python session attachment + +The direct Julia execution owner accepts `wide="df32"` for noise-free binary32 +modal landed RK, low-storage and Adams sessions. Public registry admission remains closed +until the complete phase 3 matrix qualifies. The owner copies the original operator +once; each start owns its exact run transfer and actual coordinate geometry. The +PythonCall factory receives that same transfer by identity, preserves original-launch +scales on field restart, and constructs `DF32LinearFlow` from the preparation's +original operator. Julia performs every actual-trial certificate before source work. +There is no Python numerical trial loop or binary64 phase fallback. Adams uses its +separate complete-factor flow and selected-history boundary described in +[DF32_ADAMS.md](DF32_ADAMS.md). Timing probes, dense observations, spatial operators +and tabulated flow still refuse by name. + +Managed CPU bridge tests cover eight replay steps for both methods, including RK +steps larger than the adaptive `dz_max`, at work limits 1 and 256. Same-grid binary64 +16/32-step refinement must settle at least 100 times inside SEP 33's field and energy +envelopes before comparison. Actual range failures preserve the accepted field and +perform no source work; completed starts invent neither a phase nor a trial. Field +restarts at the middle plane bind only the remaining replay and retain the original +amplitude scales. Every retained operator copy and operation bank is inventoried. +Two-member fixed-schedule group checks cover both wide types and both methods, +including exact delivery and preservation of a member whose phase certificate refuses. +Independent PythonCall witnesses also reject mismatched run identity and actual start +coordinates before consuming caller storage, then reuse the same preparation. +These RK/low-storage checks establish the stated short internal CPU paths; full phase 3 +admission, dense output and vendor execution remain additional work. Adams bridge +and portable-history qualification have their own focused witnesses. diff --git a/julia/DF32_INTEGRATION.md b/julia/DF32_INTEGRATION.md new file mode 100644 index 000000000..4338759f8 --- /dev/null +++ b/julia/DF32_INTEGRATION.md @@ -0,0 +1,230 @@ +# Binding DF32 arithmetic to an actual start + +This package binds the existing CPU whole-expression assembly to an actual request +and compatible restored history. It is an internal preparation boundary, not public +DF32 admission. The public adapter continues to refuse `wide="df32"` until every +admitted method and operator has a qualified numerical path. In particular, +separable spatial operators, complete Adams factors and dense observation remain +integration obligations. No device arithmetic or performance claim follows from a +CPU certificate. + +The numerical assumptions and existing leaf contracts are in +[WIDE_ASSEMBLY.md](WIDE_ASSEMBLY.md), [DF32_BOUNDS.md](DF32_BOUNDS.md) and +[PHASE_ADMISSION.md](PHASE_ADMISSION.md). The accepted execution scope is +[SEP 48](../docs/dev/seps/sep-0048-julia-backend.md); state arithmetic and scaling +follow [SEP 33](../docs/dev/seps/archive/sep-0033-single-precision-mlx.md). + +## Two boundaries + +Preparation binds the exact operator representation, method, actual accepted start, +remaining replay, configured maximum Adams order and actual retained coordinates. +It computes operand envelopes from those same inputs. A finite operand envelope is +not a whole-expression error certificate. Before a trial changes any numerical +field or calls a source, a later numerical integration must certify every exponent, +transport and complete compensated factor that the trial can evaluate. The checked +coordinates include the raw endpoint and actual stage positions; the supplied step +and the rounded endpoint distance remain distinct. + +This division permits a conservative CPU implementation without assuming that an +adaptive step has a positive lower bound. The controller's `dz_min` is not such a +bound: a forced landing can be shorter. A represented jump divided by that step, or +a large stale history interval, can cause a named numerical-domain refusal before +the trial. No refusal changes precision, discards history or chooses another method. + +## First package interfaces + +The first package owns only `_wide.py`, its Python tests, `wide_binding.jl`, its +Julia tests and this document. It changes no shared preparation, session, bridge, +export, history schema or module includes. + +The pure Python interface is: + +```python +DF32OperatorBinding(operator: CoefficientTransfer) + +bind_df32_start( + operator: CoefficientTransfer | DF32OperatorBinding, + run: RunTransfer, + start: float, + *, + history: MarchSnapshot | None = None, + origin_wide: Literal["binary64", "df32"] | None = None, +) -> DF32StartBinding +``` + +`DF32StartBinding` is a frozen record containing `operator: DF32OperatorBinding`, +`run`, `history`, +`operands: PhaseOperands` and `origin_wide`. The actual start is +`operands.spans.start`; the scientific precision/scales are `run.arithmetic`. +`origin_wide=None` means unknown provenance for old history and no provenance for +a fresh start. A known origin is execution metadata, not a scientific identity or +an assertion of zero numerical error. Binary64 scientific state refuses here; +this package binds only binary32 state with a DF32 wide type. + +`DF32OperatorBinding` always copies the supplied coefficient/table arrays into owned +read-only storage. Its `data: CoefficientTransfer` may then be shared across starts +under the immutable numerical-input contract. A read-only flag on an arbitrary +caller array does not prove ownership. Passing a raw descriptor to `bind_df32_start` +constructs this wrapper once. Run and history arrays are copied for the actual start, +and nested control/run/history records are rebuilt around those copies. History row +mappings become read-only. The same bound full +history must subsequently be restored; analyzing one snapshot and restoring another +is outside the contract. Directly re-enabling writes to an immutable prepared array +invalidates its preparation, as for the existing descriptor records. + +The Julia interfaces are: + +```julia +WideStartSpec(start::Float64, tableau::Union{Nothing,EmbeddedTableau}, + schedule::MarchSchedule; + geometry::Union{Nothing,WideGeometry}, arithmetic::SourceArithmetic, + method::Symbol, order_max::Int, source_absent::Bool) + +WideStartHistory(positions, identities, slots; + rates=nothing, origin_wide::Symbol=:unknown) + +prepare_wide_start(execution, operator, spec::WideStartSpec; + history::Union{Nothing,WideStartHistory}=nothing) -> WideStartBinding + +reconstruct_wide_rate(execution, prepared::WideOperator, position::Float64, values; + before::Bool=false, origin_wide::Symbol=:unknown) -> WideBoundRate +``` + +`WideStartSpec` retains the immutable tableau and schedule, actual start, geometry, +`SourceArithmetic{Float32}`, method (`:rk`, `:low_storage`, `:adams`), configured +maximum order (zero outside Adams), and structural source-absence fact. RK requires +its actual tableau; Adams and fixed RK4IP require `tableau=nothing`. No scheme is +invented for binding. The schedule +is immutable numerical input after construction. The supplied geometry is the +`PhaseSpans` lowering, not an error certificate. Preparation checks that it contains +the actual start/end, actual replay lengths/stages and retained samples. Subsequent +operations still check their exact supplied coordinates and step against it. + +The low-storage method requires fixed replay. A completed start at the exact final +coordinate uses `geometry=nothing`; its binding retains no numerical `WideOperator` +and cannot authorize an operation. It never invents a small positive step merely to +fit the active-run geometry constructor. The same binary64/strided storage contract +is checked on completed starts, without splitting values or imposing DF32 numerical +range on an operator that will not be used. + +`WideStartHistory` is a borrowed preparation-call record. Its binary64 positions, +UInt8 identities and Int64 slots are oldest first. Identities are accepted `0` and +predicted `1`; slots are portable zero-based indices into the full ComplexF64 rate +store of shape `(n_omega,n_columns,order_max+2)`. Plain Adams history retains the +same coordinate/kind/slot metadata with `rates=nothing`; its older sample ages still +constrain the binding. Read-only input arrays may overlap +one another because preparation copies selected values before retaining them. The +caller must keep all foreign owners alive for the complete call. The binding retains +no borrowed pointer. + +`WideStartBinding` retains the spec, an owned `WideOperator` or `nothing`, owned +history coordinate/kind/slot vectors and a concrete vector of `WideBoundRate` +records for selected restored rates. The latter +records preserve the saved binary64 matrix, its `WideRate` conversion/radii and the +origin-wide provenance. Position and knot side are carried by `WideRate`. Slot/kind +metadata remains in owned vectors on the binding. The actual stored rate is never +replaced by a fresh derivative. + +## Reconstructing a conservative saved-rate radius + +Let `r` be an actual saved binary64 component. Evaluate the bound representation's +derivative at the same sample coordinate and exact knot side to obtain a DF32 value +`d` with certified absolute error `e_d` relative to the exact represented derivative +`D`. Form, with outward arithmetic, + +\[ + e_r = e_d + |r-d|. +\] + +The triangle inequality gives `|r-D| <= e_r` without asserting how the old backend +computed `r`. The discrepancy includes all previous evaluation, storage and export +error, including an unrecorded wide type. The subtraction uses both DF32 words and +retains the binary64 subtraction/accumulation errors; it is not a rounded equality +test. Passing `e_r` to `restore_wide_rate` adds the new binary64-to-DF32 conversion +radius. A large discrepancy can make a later complete-factor certificate refuse. +It never licenses replacing `r`, resetting the history or claiming exact provenance. + +Accepted samples use the right-hand derivative at an exact knot; predicted samples +use the left-hand derivative, matching the existing stored sample kinds. If a future +portable format cannot establish this side, it must supply a conservative union of +the possible derivative bounds or refuse; it must not infer a side from proximity. + +Reconstruction allocates only during preparation. Failure does not mutate inputs or +an existing binding. Warmed `wide_operation` and writers retain their existing +zero-allocation contract. Rate refresh generations remain the authority for rejecting +stale operation certificates before writes. + +## Storage and lifetime + +There is no global binding cache. Each actual Start owns its binding. Existing +owned immutable operator wrappers may be shared, but the binding does not retain an +origin problem, factory or execution owner. The Python `transfer_memory` traversal +counts all retained arrays once and can exclude arrays already held by the parent +preparation. Additional copies are exactly the initial operator wrapper and each +start's run and full-history arrays described above; no historical field copies are +hidden in a scalar envelope. + +The Python start transfer and its copied full history are preparation-local. The +bridge must release them after it has restored the same snapshot and published the +owned Julia session. It may retain detached scalar evidence and the immutable +operator wrapper in the prepared owner. It must not place an actual start binding +or restored history in a problem-wide or session-lifetime metadata cache. + +The Julia inventory is explicit: the existing `WideOperator` coefficient/term +DF32 buffers, separate binary64 error buffers and edges; owned coordinates and slot/kind +vectors; and, per selected restored sample, one raw ComplexF64 matrix, one DF32 +matrix and one ComplexF64 radius matrix. Derivative/discrepancy temporaries are +preparation-local and are released. All these arrays are host CPU storage. They +cannot be read implicitly from a future device advancement kernel. + +Preparation converts every coefficient/term cell. Each selected restored rate +requires a complete certified derivative evaluation and discrepancy pass. The +existing operation certificate traverses every numerical cell before the writer +repeats the DF32 graph. These are explicit CPU costs, not a reusable uniform proof +or a device-safe admission strategy. + +## Required numerical integrations after this package + +1. A DF32 linear-flow implementation must assemble from the bound coefficients and + original scalar operands, then call the qualified function leaves. It must use + the corrected forward/backward pair where inverse cancellation is required. + Casting an already-assembled binary64 phase does not satisfy this requirement. +2. A pretrial plan must check all actual RK anchor/stage/endpoint flows and both + low-storage half flows before the first source call or in-place state mutation. + It must bind the current method coefficients and actual replay cursor. Reuse is + invalid after either the coordinate tuple or a retained-rate generation changes. + Writable outputs must be disjoint from the complete binding, including retained + original saved-rate matrices, not just one temporary `WideOperation` record. +3. Adams needs certificates for complete source and compensation factors, including + phi function absolute errors, coefficient formation, `h*D_j-L`, transport and + dense coordinate powers. Certifying the inverse-metre `D_j-Q` alone is + insufficient. The C32 graph must not narrow a large intermediate whose complete + factor is representable. Its state arrays remain C32 throughout. +4. RK and Adams dense observation must use the same bound arithmetic and retained + trial facts. A separate F64 dense phase path cannot inherit DF32 admission. +5. Separable spatial generators need their own protected wide assembly and error + provenance, including grazing cancellation. The initial modal binding refuses + them by name. Public DF32 stays closed until this admitted route is covered. +6. The master integration owns start/restore atomicity, lifetime and memory ledgers, + execution metadata, bridge conversion and the final public/device admission. + Restart metadata records both the requested new wide type and any known previous + wide type. Scientific and history hashes do not acquire an execution option. + +## Regression obligations + +The binding tests must retain the counterexamples established during design: + +- replay lengths larger than `dz_max` determine the phase domain; +- full represented intervals catch an interior extremum with small endpoints; +- configured maximum order and older retained samples determine history reach; +- adaptive cross-knot jumps cannot use a fictitious positive minimum step; +- mutation of a caller's writable array cannot invalidate a retained summary; +- a completed replay has no positive future step; +- separately rounded binary64 endpoints can erase a nonzero represented difference; +- a tiny cross-knot interval can fail assembly error even when its exact jump is zero; +- saved rates require a derived radius and keep their actual values; +- stale sample generations and failed certificates preserve every destination. + +These witnesses establish the necessity of the boundary. They are not a propagation +accuracy record. Whole-run tests, a conditional binary32 rounding budget and the +per-vendor arithmetic model remain later qualification obligations. diff --git a/julia/GPU_MARCH.md b/julia/GPU_MARCH.md new file mode 100644 index 000000000..7fdc55298 --- /dev/null +++ b/julia/GPU_MARCH.md @@ -0,0 +1,95 @@ +# Shared device march integration + +This internal slice attaches execution-owned storage to the existing binary64 +linear flow and RK march. Public device selection stays closed. Its source and +host tests establish orchestration behavior; actual CUDA tests, unfiltered vendor +quality and complete physical sessions remain separate requirements. + +## Execution and retained storage + +`LinearFlow` keeps the CPU exponent/failure layout unchanged. A device binary64 +flow validates its input owner before allocating its exponent, per-column failure +scratch and optional factor tables through the prepared execution. Its failure +scratch is a `DeviceReadback{...}`: numerical work writes one integer per column, +then the host inspects its persistent mirror in the original first-column, +first-row failure order. No numerical array is downloaded for that check. +Zero-distance table hits use the context-owned copy operation too. + +`RungeKuttaWork(state,tableau)` remains the CPU constructor. Its new overload +`RungeKuttaWork(execution,state,tableau)` uses that same path for CPU execution. +Device binary64 preparation owns every stage/field buffer through that execution +and retains a `DeviceReadback` for the existing `(4,n_columns)` norm partials. +Device binary32 work refuses before scratch allocation; its scaled tolerance +construction requires separate integration and qualification. + +The binary64 reduction graph is unchanged: each column first computes scaled +old/candidate sums of squares, the host merges the completed partials and forms +the common relative scale, then columns compute defect partials for a second +host merge. There is no vendor sum, field-sized host oracle or Python trial loop. +After candidate services, the same partial storage reports whether each column +is finite, preserving the existing finished-candidate failure before commit. +The prepared execution identity is checked before any partial writes. + +The recursive ledger sees each device array and its persistent host mirror. +For two-stage RK on binary64 state with `N=n_omega*n_columns`, the trial payload +is `8N*sizeof(ComplexF64) + 8*n_columns*sizeof(Float64)`: six field buffers, two +stage planes and two copies of four norm rows. This excludes the independently +owned accepted field, source, flow, preparation and vendor/runtime caches. CPU +keeps only one set of norm partials, with no additional mirror. The warmed CPU +advance allocation contract remains unchanged. + +## Numerical and lifecycle witnesses + +Host tests use a deliberately labelled execution model to count transfers and +allocation owners. They cover compact failure ordering, nonfinite entries outside +the norm mask, mismatched execution before writes, the device binary32 refusal, +cached/zero-distance flows and exact ledger bytes. They do not qualify GPU code. +Existing CPU RK, scaled binary32 norm, source, flow-table and session tests remain +in the affected regression set, including warmed advancement allocations. + +The explicit CUDA test disables scalar indexing in its own process. It advances +one and eight fixed Heun steps under both delivery limits and both table policies, +using the Julia scheduler. The source is the analytic scalar equation +`y' = (-1/4 + i/2)y + (i/8)y`, over `1/32 m`. This isolates execution and control; +it is not a modal FFT/Kerr propagation qualification. The exact discrete map is + +```math +y_{n+1}=e^{h(-1/4+i/2)} + \left(1+ih/8-\frac{(h/8)^2}{2}\right)y_n. +``` + +MPFR checks every nonzero exponential argument used by this binary step graph +against a predeclared `8*eps(Float64)` componentwise relative allowance. The CUDA +documentation reports observed elementary-function accuracy rather than a formal +all-input theorem; these concrete witnesses establish only their tested inputs. +There are fewer than 256 rounded scalar operations and elementary-error units per +cell and step in this two-stage graph, and its amplification over the window is +less than two. Comparing both implementations therefore uses +`2*gamma(512*n_steps)*norm(initial)` with binary64 unit roundoff. The same bound +also checks the independently evaluated discrete map. This is a matched-history +rounding witness, not an adaptive global-error estimate. + +Source and norm failure rows, exact work counts, receipt traces, context/stream +restoration and accepted-field preservation accompany the numerical checks. +The standalone witness reads its final field through an explicit owned copy. +The production physical export transaction is still additional work. + +The frozen host milestone passes 56 orchestration assertions and 808 directly +affected existing CPU assertions, including zero warmed advancement allocation. +CPU Aqua/JET passes 16 checks with all 2,242 definitions analyzed and none cached. +The explicit CUDA witness is prepared but has not yet run on a device; these host +results do not qualify its compilation, arithmetic, context or transfer behavior. + +## Remaining integration + +The modal source still needs context-owned allocation, full-map chunk offsets, +device coefficient staging and compact plasma failures. Dense observations, +statistics/monitors, splitting, input noise, spatial sources and the remaining +march families must use the same ownership/readback boundary. Host profiles and +scalar control policy remain host records; numerical fields remain on the device. +Actual A40 qualification and independent review are required before integration +is described as a tested GPU march. Other vendors require their own evidence. + +The primary arithmetic reference checked during development is NVIDIA's +[floating-point computation appendix](https://docs.nvidia.com/cuda/cuda-programming-guide/05-appendices/mathematical-functions.html). +Its observed-error caveat is retained; precise compilation alone is not an error proof. diff --git a/julia/IMPLEMENTATION.md b/julia/IMPLEMENTATION.md new file mode 100644 index 000000000..f371b8e86 --- /dev/null +++ b/julia/IMPLEMENTATION.md @@ -0,0 +1,169 @@ +# SEP 48 implementation + +Branch: `feature/sep-0048-julia-backend`; draft [PR 611](https://github.com/LupoLab/solprop/pull/611). +Proposal 609 merged at `04e72192`; Part I is frozen. Leave the completed implementation +ready for maintainer review, without merging it. + +**Paused checkpoint — 11 November 2026.** Binary64 CPU is available on this branch. +CUDA is partly integrated and remains closed to public selection. No new implementation +slice or compute campaign starts during the maintainer's requested pause. The last +code integration before this record is `8c7596cb`; CI results below identify the +revision actually checked. A checkpoint is not Final qualification. + +## Agreed scope and phase status + +The completion baseline is **binary64 CPU and CUDA**. Metal, ROCm/HIP and unfinished +binary32/DF32 qualification are deferred. DF32 supplies selected wide intermediates +for binary32 state and FFTs; it is not a whole-state backend mode. See +[DEFERRED.md](DEFERRED.md) for retained implementation and failed evidence. + +| Phase | Delivered | Still needed for this baseline | +|---|---|---| +| 1: package/runtime | Immutable setup identities, offline artifact checks, lazy bridge, ownership and packaging | Final installed-package/supervisor matrix; accepted runtime limitations remain explicit | +| 2: binary64 CPU | Public scalar modal, radial, Cartesian and line sessions; responses, methods, services, history and groups | Final complete conformance/CI; isolated startup and worker measurements | +| 3: binary32/DF32 | Substantial internal implementation, tests and numerical analysis retained | Unfinished qualification deferred; public selection stays closed | +| 4: devices | CUDA execution/FFT, storage, RK, low-storage, modal source and export integrations; initial actual A40 evidence | Adams integration, complete observations/monitors, spatial composition, end-to-end bridge/history/groups, vendor quality and measurements | +| 5: documentation/Final | Manual, design, decisions, release fragment and preliminary benchmark ledger | Final evidence, independent integration review, required green gates, archival/Final commit | + +Binary64 CPU supports scalar field/envelope Kerr, Raman and plasma, adaptive or replay +RK/Adams and fixed low-storage stepping, represented operators, dense observations, +statistics, temporal/transverse monitoring, portable Adams history, snapshots, input +noise and fixed-schedule groups. The [manual](../docs/guide/performance/julia.md) +records exact admission and refusals. Scientific defaults and hashes are unchanged. +Julia 1.13.3 and JuliaCall/PythonCall 0.9.37 remain pinned. + +## CPU use at this checkpoint + +From a checkout of this branch with the normal native build prerequisites: + +```sh +uv sync --extra julia +uv run solprop julia setup +uv run solprop julia status +``` + +Use `SimulationSettings(backend="julia", device="cpu", ...)` in an existing scalar +binary64 example. If status lists multiple compatible identities, select the intended +one with `backend_options={"setup_id": identity}`. Re-run setup after engine source +changes; begin a fresh Python process after selecting another runtime identity. +Julia entry belongs on Python's main thread. The accepted SIGTERM limitation requires +an external hard-kill deadline; ordinary cancellation remains cooperative. + +## Integration and review checkpoint + +All completed, independently reviewed integrations are on the one PR branch: + +- Storage/readback, capture guards and RK orchestration: `75d6849a`, `ba632416`, + `9e41cdb1`. +- Modal Kerr, low-storage and transactional export: `23fed2ab`, `900ce053`, + `bbdf0eda`, `f007e1b7`; selected-execution bridge: `2a1fdd4a`. +- Modal Raman/plasma and execution-aware factories: `2002886f`, `5b5ac0d1`. + Review adds 150 independent witnesses; the integrated engine passes 4,942 + assertions, and 16 actual managed CPU material/route cases pass. +- Shared RK dense observation: `eb0a3e69`. Author checks pass 3,508 affected + CPU/spatial/DF32 assertions and 334 model/RK assertions. Independent review passes + 475 assertions, including 141 original ownership, represented-operator and failure + witnesses. CPU Aqua/JET passes 16 checks, all 2,310 definitions analyzed, none cached. +- CUDA retained-payload test correction: `8c7596cb`. Independent source review + verifies pinned CUDACore four-byte allocation padding; no production code changes. + The corrected actual-device rerun remains pending. + +The final combined checkpoint passes 10,541 bounds-enabled Julia assertions across +42 testsets and six actual managed CPU replay/dense cases after publishing a fresh +setup. Documentation checks pass: spelling, whitespace, 349 SEP consistency tests +(three declared skips) and the Sphinx build. Two earlier private test-runner invocation +errors are retained in the evidence; the corrected aggregate exits successfully. + +Against current `main` (`ae65df6a`), cloc 2.10 counts 34,180 added production code +lines, 76 modified and 46 removed: a net increase of 34,134. This excludes blanks, +comments/docstrings, separate documentation, tests and manifests. It includes retained +deferred SEP 48 work, but excludes already merged SEP 47 work. This is a lexical +physical-line count, not a statement count or the minimum size of a CPU-only backend. + +Unintegrated work is deliberately **not** counted as delivered: + +| Frozen work | Checks already run | Exact next action | +|---|---|---| +| Binary64 device Adams method/dense mirrors | 10,896 distinct bounds-enabled CPU assertions; package and concrete JET | Independent review, then master integration and actual CUDA execution | +| Shared statistics/temporal readings draft | 540 bounds-enabled assertions including existing zero-allocation checks | Test workspace attachment, finish split/quadrature, then full affected regressions and independent review | +| Spatial source/operator attachment | Interface reviewed; implementation not started | Reuse existing generic source/operator recipes and selected storage after resumption | + +Every future author uses a separate worktree. The master owns architecture, shared +interfaces, bridge/registry, transfer records and integration. Services own numerical +statistics/monitor preparation; numerical work owns source/spatial composition; device +work owns Adams/storage and hardware qualification. Assign exclusive files again when +resuming; no agent is currently implementing another slice. + +## Hardware and CI evidence + +The latest actual A40 combined run reports **2,663 passes, nine assertion failures +and three runner errors**. March (167), modal source (1,595), export (157) and 58 +independent storage/march checks pass. The nine failures used logical array sizes +where the ledger correctly includes CUDA allocation padding. The three errors were a +missing module binding in the private runner. Reviewed test corrections and a corrected +runner exist; the original evidence remains failed until an actual rerun passes. +Unfiltered vendor quality also fails: Aqua passes 11 checks, core/extension JET report +76/38 possible errors, and all nine concrete analyses fail. These are qualification +blockers, not waived checks. No Adams, complete services or spatial CUDA result is +implied. Both A40 jobs have ended; no rental exists and campaign spend is US$0/US$50. + +At inspected CI head `de6111e9`, static checks (including types, docstrings, spelling, +licences and changelog), no-native tests and native wheel jobs pass. Several Linux +lanes fail during package installation before tests: removing the Azure mirror did +not resolve DNS failures for the official Ubuntu archive. Required CI is not green; +the remaining full matrix and the checkpoint push must be inspected after resumption. +Earlier Linux Julia shutdown failure #669 and accepted runtime boundaries stay visible. +The precise historical runs, failures and reviews remain in +[IMPLEMENTATION_HISTORY.md](IMPLEMENTATION_HISTORY.md). + +The preliminary CPU benchmark matrix covers 12 short cases at one and 64 physical +cores on AMD EPYC 7763: 144 samples, 432 repetitions, finite fields and matching step +counts. Results are mixed; there is no blanket speedup claim. The +[benchmark ledger](../docs/dev/benchmarks.md#julia-cpu-entrance-windows-complete-preliminary-matrix) +records windows and preparation-inclusive wall time. Isolated startup, spawned-worker, +CPU-to-GPU package loading and final CUDA measurements remain mandatory. + +## Resume in this order + +1. Read this record, `julia/AGENTS.md`, the manual, deferred scope and SEP Part II. + Inspect current PR/CI heads before editing. Preserve all unintegrated work until its + review and exact ownership are understood. +2. Resolve the current CI infrastructure failure and inspect the complete binary64 CPU + gate. Keep CPU usable while adding device transport; do not reopen deferred precision. +3. Review/integrate the frozen Adams work. Complete shared observations/monitors, + population/spatial services and spatial composition; connect history/groups and the + remaining factories. Keep public CUDA closed until the full path is qualified. +4. Run a new immutable, reviewed A40 snapshot with corrected runner/accounting tests. + Triage every unfiltered JET result; validate real GPU sessions, failure handling, + retained memory and CPU regressions. Do not reuse old job results for new sources. +5. Finish required short-window measurements and installed-package checks, then final + documentation, independent integration review and green gates. Only then prepare + Final and mark PR 611 ready. **Do not merge the implementation PR.** + +## Architectural decisions to preserve + +- One numerical routine and operation sequence per feature serves CPU and GPU. + Backend specialization belongs in allocation, launch, transforms, copies and compact + readback. Shared arithmetic helpers do not justify duplicated numerical recipes. +- Source, RK, low-storage and Adams audits confirm shared arithmetic. The pending + statistics draft now has one catalogue dispatcher and common family routines; + workspace/service attachment is still unfinished. AcceleratedKernels is imported + but unused in owned source. Reconcile that deliberately; do not rewrite protected + reductions merely to introduce a library call. +- Python lowers descriptors and services events; Julia owns the march, controller, + history, statistics, monitors, snapshots and export generations. Follow the merged + SEP 47 preparation/session contract; no native lowering or Python trial loop. +- Runtime identity includes immutable source, bridge, ordered environments, effective + preferences, depot and executable locations. Setup can download; runtime artifact + verification precedes Julia loading and execution performs no downloads. +- All Julia-facing Python operations, including cleanup and exception formatting, + run on the main thread. Only the lifetime-owned atomic stop setter runs elsewhere. + Keep the accepted SIGTERM/external-deadline policy and ADR-077/078 boundaries. +- `device`, `wide` and `setup_id` are execution choices outside scientific/resume hashes. + Input noise is binary64 only, added once at a fresh launch and never again on resume. +- Preserve SEP 25/33 comparison classes, strict arithmetic protections, zero warmed + CPU advancement allocation and complete retained-buffer accounting. Real vendor + allocation padding is distinct from logical transfer size and allocator reservations. +- New issues cover only work this PR will not resolve. Keep in-PR fixes in this record; + consolidate the earlier issue inventory when finalizing. Historical failures remain + visible and do not become passes through scope changes or documentation edits. diff --git a/julia/IMPLEMENTATION_HISTORY.md b/julia/IMPLEMENTATION_HISTORY.md new file mode 100644 index 000000000..ffd3296ca --- /dev/null +++ b/julia/IMPLEMENTATION_HISTORY.md @@ -0,0 +1,1394 @@ +# SEP 48 historical implementation notes + +This preserves the working record through commit `c35e35bd` on 11 November 2026. +Its status and assignment statements are historical. The current plan and ownership +are in [IMPLEMENTATION.md](IMPLEMENTATION.md); delivered milestone reports also live +in SEP 48 Part II. Keep prior failures and limitations when recording later results. + +# SEP 48 implementation + +Branch: `feature/sep-0048-julia-backend`. +Draft implementation [PR #611](https://github.com/LupoLab/solprop/pull/611). +Proposal [#609](https://github.com/LupoLab/solprop/pull/609) merged at `04e72192`. +The completed implementation is left ready for maintainer review, not auto-merged. + +## Current status + +Resumed on 11 November 2026 after the maintainer's brief network pause. +The binary64 CPU source, session and service path is integrated. Full phase 2 +qualification remains open. Device-selection and execution-option transport are +reviewed; actual device execution remains refused. The implementation stays in draft. + +Binary32 source composition, RK/low-storage/Adams marching, launch scales, physical +export and portable history are integrated and independently reviewed. The latest +transport milestone passes 81 pure Python tests, 3,338 affected Julia assertions and +23 managed binary64 history/public-CPU tests. Independent review adds 390 raw-history, +58 actual PythonCall mixed-buffer and 135 export/probe assertions. Complete physical +formatting now refuses overflow before destination writes (#718). Final Aqua/JET +passes all 16 checks, analyzing all 1,858 definitions with zero cached; changed Python +scope has zero type errors or warnings. Whole-package types retain three existing +missing-native-source warnings and zero errors. + +Spatial RK dense observation now accepts the existing separable line/Cartesian +operator (#719), retaining its protected root and branch assembly without a dense +operator copy. The master independently repeats 6,016 bounds-enabled assertions at +two threads. Author qualification adds a one-thread repeat and passing Aqua/JET +across all 1,861 definitions. Integration is `cd34de38`. + +Binary32 observation reductions and monitor calculations are independently approved +and integrated through `ff9dedf6`. Corrections preserve actual weighted products, +per-node fluence exponents, physical identity and retained-buffer aliases (#715–717). +The reviewer passes 3,895 assertions, including 2,672 additional product, weak-node +and alias witnesses; the author passes 1,223 assertions at both thread budgets and +Aqua/JET across all 1,897 definitions. Public binary32 selection stays closed until +the complete service and source paths compose. Derived observation exponents are bounded metadata, +separate from base amplitude scales (#721), integrated at `a8bb94ca`. Independent +review passes 439 assertions, including extreme finite restoration and subnormals. + +Reconstruction is independently approved and integrated at `0d7590f8` and `888e16ff`. +The reviewer passes 4,319 existing binary64, 2,591 new binary32 and 133 additional +scale, cadence, reuse and ownership assertions. All warmed allocation checks are zero. +The accepted coefficient-conversion contract retains an explicit absolute underflow +allowance for weak normalized coefficients; the note and witness do not promise a +small relative error for ill-conditioned input representation. Shared attachment +passes 134 composed Julia assertions, including eight-step propagation with split +statistics, and Aqua/JET passes 16 checks across all 2,011 definitions, zero cached. +Independent attachment review adds 178 actual PythonCall factory assertions and +seven registry controls. The complete retained-owner matrix passes all 84 managed +cases, with 27 accompanying pure tests, in 411.75 s. The broader integrated Julia +Core run found stale positional/synthetic test fixtures after the precision change +(#728). Their narrow corrections preserve the original negative/service behavior; +independent checks pass 414 transverse assertions and five nullable-record assertions. +The complete corrected aggregate now passes all 156,695 assertions in 484 testsets, +with bounds checking enabled and two Julia threads. It includes the reviewed DF32 +flows and execution extension declarations. The inventory test requires the documented +`--startup-file=no` runner flag; an earlier private tail invocation omitted it and +is retained as a harness failure. + +Binary32 quadrature is independently approved at `b6091f7b`: both maxima and sums +use state precision, with protected scaled reductions and a host physical ratio. +The master repeats 815 bounds-enabled assertions at two threads. Foreign storage +and index-owner aliases refuse before work (#722). Its five per-column entries are +included in the planner at their actual scalar size. + +DF32 actual-start and restored-rate binding is independently approved at `f6931a82`. +It retains actual replay lengths, configured Adams reach, old history coordinates +and original saved rates with conservative error provenance. Master review passes +986 bounds-enabled Julia assertions, including 207 independent cubic-derivative, +rate-radius and replay/history witnesses; 80 typed Python tests pass. Author +Aqua/JET passes 16 package checks plus five concrete calls across 1,885 definitions. +Completed starts validate storage without inventing a step (#723). Actual CPU DF32 +RK/low-storage flows are independently approved and integrated +at `5b93ef4e` and `f23b32f0`: 674 independent bounds-enabled assertions, zero warmed +allocations, and Aqua/JET across 2,026 definitions plus 13 concrete calls. The review +corrects exact zero-phase signed-zero copies (#727). Module inclusion is integrated +at `cadbad36`; the master passes 793 focused +assertions and Aqua/JET across all 2,067 definitions with zero cached. Factory +integration, complete Adams factors, dense output and spatial assembly remain open; +no public DF32 execution is claimed. + +Temporal split precision is independently approved through `dcc443bf`. Review found +and corrected a tiny-collar regression (#720): binary32 must use the existing SEP33 +`expm1` correction graph, with the original spectrum added only after transforming +the correction. The corrected leaf passes 522 authored and 566 independent assertions, +including candidate preservation after overflow and strided retries. Final Aqua/JET +passes 16 checks across all 1,949 definitions, zero cached. Binary64's original product +graph is unchanged. Shared observation factories now forward the exact precision +and amplitude scales; mismatched source, observation and transverse records refuse. + +The binary32 node-inventory update is qualified. The earlier eight managed source +cases stopped at the private descriptor guard; coherent lowering now admits their +noise-free scalar inputs. Actual retained-owner tests pass at two node capacities +for every admitted geometry and material family, including statistics, temporal splits +and transverse monitoring in both precisions. Fixed source +coefficient buffers and physical readouts remain host-wide; the inventory counts them +separately from narrow state scratch and integer exponent metadata. +Typed Python attachment and registry checks pass 183 tests; the separately enabled +84 managed cases also pass. Registry selection now checks the same precision table as settings +and availability before dependency or runtime entry (#726). + +The CPU campaign at `5fc63437` passes 23 managed CPU/inventory smoke checks. +All 24 configurations now have three paired rounds with three repetitions per arm: +144 arm samples and 432 timed repetitions. The original stage timeout is preserved; +a bounded continuation completed only the three unfinished third-round pairs with +identical source, environment and physical placement. All results are finite and +accepted/rejected counts match. Independent recomputation matches every paired median and ratio. The complete +timing, preparation-inclusive wall, window and accuracy records are in `docs/dev/benchmarks.md`; #729 tracks the measured +radial/Cartesian performance costs without assuming their causes. +CPU-only CUDA artifact preparation and isolated-network A40 loading, broadcast, +matrix multiplication and FFT round trips pass in both precisions. This is +artifact/primitive evidence, not device propagation qualification. No cloud resources +have been rented; spend remains zero. + +CI for `984444ce` has completed. Static checks, native quality, device compilation, +distribution wheels, Python platform and lowest-dependency tests, both slow lanes, +documentation and the no-native lane have passed. All six coverage shards pass; +their combined report identifies two unmeasured device-refusal statements (#725). +A focused correction passes 32 typed tests and confirms both lines are measured, +without changing coverage policy; the combined report awaits the next CI run. +Linux Julia Core and Aqua/JET pass, but the Python lane reports 1,274 passes and one +missing finalization-marker failure in the shutdown subprocess, then a post-summary +segmentation fault. Both observations remain on #669; runtime investigation stays +off the critical path under the maintainer's instruction. The failure remains a +qualification blocker and no assertion is suppressed. +macOS Julia Core and Aqua/JET pass, and its Python lane passes all 1,275 tests +with 20 declared skips. The final evidence verifier incorrectly required a pass from +a bitwise-repeat case which correctly takes the declared determinism skip (#731). +Its correction retains mandatory evidence for that case, rejects any failure even +when combined with a declared skip, and passes 67 focused verifier tests. +The Windows GUI lane found an immediate-resume event-log sharing violation after +424 passing tests; unrelated issue #724 retains the evidence. Earlier stale fixtures and the Windows skip declaration +were corrected and independently reviewed; local targeted checks pass 57 Python tests +and 105 Julia assertions. Required unfinished lanes remain visible. + +| Phase | Status | Evidence or prerequisite | +|---|---|---| +| Acceptance | Complete; Part I frozen | Final head `da2e699f` passed GitHub CI and required documentation preview; merged `04e72192` | +| 1: package and runtime | Setup/package integrated; remaining runtime qualification deferred | Maintainer directs core implementation to proceed; failures remain tracked | +| 2: CPU binary64 session | Scalar modal/spatial sessions, services, providers, FFT persistence, public selection and budgeted preparation are integrated; combined materials pass | Preliminary CPU matrix is complete; remaining conformance and CI failures precede completion | +| 3: CPU binary32 | DF32 primitives, conservative function leaf and operand analysis reviewed; full execution pending | Whole-expression and device admission remain unqualified | +| 4: devices | Pending | CPU gates and one qualification pass per vendor | +| 5: records and Final | Pending | All required capability, CI and measurement evidence | + +SEP 47's contract milestone is merged at `2e2490c2`. The completed Part B head, +`e9105523` from [#607](https://github.com/LupoLab/solprop/pull/607), is integrated at +`83da0ad5` under the maintainer's authorization to proceed before its CI fixes merge. +Its actual interfaces have been read: the descriptor/request split and generic +`Backend.prepare(problem, request).start(...)` are present. `assemble` returns +`Translation(problem, request)`, validation is `validate_run`, and preparation checks +`foreign_request`. Group construction now dispatches through an execution owner's factory, independently +of legacy numerical operations. The Julia owner now uses that contract directly; +public registry selection now exposes the admitted binary64 CPU composition. No new backend-name +branch belongs in the service/session dispatcher. +The subsequent Part B CI corrections at `f6921fae` are integrated at `10be2eff`. +The additional CI corrections at `55fdc423` are also integrated: they restore +request-owned arrays to the mixture baseline and remove nonportable hash literals. +The final documentation/skip corrections at `21b5808c` are integrated as well. +The final contract/coverage corrections at `f351d0a3` are integrated at `4dade535`. +PR #607 has now merged at `ae65df6a`; its complete reviewed head was already integrated. +The targeted merged selection passes 528 tests with 56 declared capability skips. +`RunSession.march_export_refusal()` is now explicit; Julia already implements it. +The legacy callers of this branch's new execution-owner protocol are corrected; +whole-package basedpyright reports zero errors and three existing native-stub warnings. +Explicit legacy selections retain their stronger type; general selection keeps the +session-only owner contract. No legacy Julia methods were added. + +## Ownership + +The master owns architecture, shared transfer records and session lifecycle, shared +Python integration, CI and packaging hooks, and this record. Implementation agents +receive disjoint files in separate worktrees after these rules are committed. +Assignments and ownership handoffs are recorded here before overlapping work begins. +An independent reviewer reviews each package they did not author before integration. + +Current assignments after resumption: + +| Owner | Exclusive files and task | +|---|---| +| Master | Architecture, shared execution/copy declarations, Python/Julia bridge and wide-flow attachment; node inventory, module/test inclusion, CI and compute records | +| CUDA agent | Attachment and fixture reviews complete; owns only `ext/SolpropJuliaCUDAExt.jl`, new `cuda_execution.jl` / `cuda_transforms.jl` extension and test files, and `CUDA_FOUNDATION.md` | +| Wide arithmetic agent | RK/low-storage package reviewed and integrated; read-only complete-Adams design, including seed-before-trial ordering and retained-rate provenance; shared interfaces frozen for `df32_adams.jl`, `adams.jl` and `adams_session.jl`; complete-factor implementation active | +| CPU qualification agent | DF32 independent review complete; new `tests/backends/julia/test_cpu_single.py` and `CPU_SINGLE_QUALIFICATION.md` only; actual binary32 methods, material routes and services against settled binary64 references | + +The maintainer explicitly moved remaining runtime investigation off the critical path +on 2026-11-10. Continue core implementation using the experiment's numerical work, +retaining the accepted main-thread boundary and visible runtime failures. This changes +the work order, not the accuracy requirements or a claim of completed qualification. + +The following table preserves earlier handoffs; completed assignments no longer confer +file ownership. + +| Assignment | Exclusive files | State | +|---|---|---| +| Numerical transform/Adams agent | New `transverse_observations.jl` and focused tests; transverse decision stages in `monitor.jl`; subsequent Julia service/transport hooks in `observation_session.jl`, `monitor_transfer.jl`, narrow launch hooks in `transfer.jl`, and new `ext/transverse.jl` | Reviewed attachment integrated at `ea4b8731`, first-selection correction at `70fa4d8e`; files return to master | +| Numerical services agent | New `trial_probe.jl`, `ext/trial_probe.jl` and focused tests | Reviewed leaf integrated at `d71d29cf`; Python adapter independently reviewed; files return to master | +| FFT attachment agent (rotated from review) | `execution.jl`, `transforms.jl`, the Raman planning block in `composition.jl`, focused new tests and the small explicit-planning precompile workload; one local `windows` narrowing in `observations.jl`; a typed scalar/rank barrier in `fft_plans.jl` | Reviewed attachment integrated at `2b2ef88c`; runtime/cache integration independently reviewed; files return to master | +| Master | All shared Python interfaces, Julia module/test inclusion, transfer records, integrators/session lifecycle, repository records and remote campaign | Integration and phase 2 shared interfaces | +| Independent reviewer | Production code read-only; independent transaction tests returned to master | Group, dense scheduler/adapter and corrected input-noise leaf approved; independent integration review continues | +| Wide arithmetic agent | New `wide_operators.jl`, its focused tests and `WIDE_ASSEMBLY.md` | Phase 3 whole-expression assembly and range/error certificate; shared interfaces require master agreement before dependent work | +| CPU provider agent | New `cpu_blas.jl`, `_accelerate.py` and focused tests | Reviewed leaf integrated at `5795fe65`; runtime/lease attachment reviewed, managed checks passed; files return to master | +| Preparation agent | New `_node_plan.py`, focused Python/Julia tests and `NODE_MEMORY.md`; narrow owned-window reshape correction in `observations.jl` | Derive Julia-specific chunk storage bounds and authoritative budget admission; master owns shared adapter integration | +| Source precision agent | `precision.jl`, `composition.jl`, `spatial_composition.jl`, `responses.jl`, `raman.jl`, `plasma.jl` and their focused tests | Binary32 source preparation/kernels under the shared `PRECISION.md` interface; no Python, transfer, session or observation edits | +| Observation precision agent | `observations.jl`, `spatial_observations.jl`, `transverse_observations.jl`, `statistics.jl`, `monitor.jl`, `observation_precision.jl`, `power_weights.jl` and focused tests | Binary32 pointwise work, protected reductions and host physical scaling; no source, Python or scheduling edits | +| Device-controls/review agent | Python execution settings/options, registry, host/native guards, recipe execution transport, runner compatibility and focused tests | Public CPU preparation independently approved; implementing device controls with Julia devices still refused; then review master march precision | +| Adams precision agent (rotated from review) | `src/adams.jl`, new `test/adams_precision.jl`, `ADAMS_PRECISION.md` | Binary32 state with binary64-wide phase/rate leaf under the explicit contract; no session, transfer, Python or inclusion edits | +| Session precision agent (rotated from source/review) | `src/march.jl`, `low_storage_session.jl`, `runge_kutta_observation.jl`, `trial_probe.jl`, new precision tests and `SESSION_PRECISION.md` | Binary32 RK/low-storage/dense/probe core with explicit arithmetic; master retains physical I/O, transfers, Adams session and public admission | + +The precompile workload uses only owned, small CPU arrays and existing numerical +constructors. It covers serial CPU session/source/observation dispatch without loading +Python or devices, retaining no global mutable workspace and publishing no calibration +files. Parallel specialization and cold-cache evidence are qualified separately; the +workload never changes the process's thread policy. Module inclusion remains master-owned. + +Phase 3's wide-operator slice will use paired Clenshaw differences on a single +represented interval. This evaluates the same cumulative polynomial difference while +retaining its correlation across endpoints, so a forced small step does not divide +two unrelated cumulative-error bounds by the step length. Actual rounded endpoint +distance remains distinct from the prescribed step. Cross-knot jumps and restored +sampled-rate provenance remain explicit certificate inputs. The first certificate +implementation is a conservative CPU operation check, not public DF32 or device +qualification; its per-cell cost and range limits require separate evidence. + +Spatial observations reuse the existing statistics and temporal-monitor reductions. +Their separate flux descriptor retains the actual represented material and protected +longitudinal-root inputs. Cartesian reconstruction uses transforms, never a dense +node-to-node map. Coarse electric/closure pairs are allocated only for selected needs; +fine population scratch is bounded by the node chunk. The master retains ownership +of Python lowering, preparation factories and shared session-service hooks. + +The temporary CI assignments for `restore_control!`, CPU allocation and source/monitor +constructors are complete and integrated after independent review. Their files return +to master ownership; further leaf changes require an explicit assignment. +The portable history leaf, sample tags and profile lowering also return to master +ownership after review. Observation preparation is request-specific: its catalogue, +monitor policy and profile context do not enter a problem-only preparation cache. +The dense-observation leaf is independently approved and integrated at `2660ce42`; +shared scheduler attachment remains master-owned. The history bridge milestone +`12613fc5` is pushed to the draft PR for full CI. +The DF32 scalar primitive commit `dff18fd1` is integrated as `1e9bc6a4` after +independent source and algorithm review. The reviewer passed 33,651 assertions, +including additional exact split/tie cases and CPU IR checks. These qualify only +the scalar operations under their stated finite-intermediate hypotheses, not a +propagation domain or vendor arithmetic. The monitor continuation fix `2216949e` +is integrated as `f54aff0b`; independent bounds-checked testing passed 3,884 +assertions, including recorded Python readings and zero-allocation checks. Missing +legacy quiet counts preserve the new launch settlement; explicit zero restores it. +These two filesets return to master ownership after review. + +The request-specific statistics bridge has passed integration and independent review. +Its first runtime pass found a PythonCall automatic-array-conversion dispatch gap; +a distinct Python copy entry now transposes the packed destination explicitly. +Transactional retries, buffer alias/admission and retained-array cleanup now pass. +Admitted spatial routes, preparation and measurements still block phase 2 completion. +The subsequent phases continue +without another approval step; the completed implementation PR remains unmerged. +The reviewer-authored statistic-bound helper is integrated at `8e8aa1c6` after +master review. It uses exact rational reduction bounds, a declared CPU FFT envelope, +and certified width brackets/slopes. Twenty-eight independent witnesses cover its +admission and 1,024 width perturbation corners. It does not bound material populations +or propagated-field errors. The master-owned group hooks are committed at `81b0bdde`; +the services agent independently passed all 55 new bounds-enabled assertions. +The group coordinator keeps Julia in charge of member advancement; Python assembles +only complete transport windows. Fresh entrance starts are required by the shared +group contract; portable-history groups are not admitted. +The numerical group leaf `cb8ace0e` is integrated at `340ea43c`. Independent review +passed 639 bounds-enabled assertions, including original witnesses for nonprogressing +near-coincident planes (#666) and zero-trial deadline turns (#667). Warmed advancement +allocates zero; the author's package/concrete quality checks pass. Its public compatibility, +transactional original-start adoption and complete Python windows have since passed +the integration milestone below. +The DF32 function API admits only the documented `abs(real(z)) <= 16`, +`abs(imag(z)) <= 2^20` domain with a separate `u/8` input-error budget. Protected +exponential, phasor and phi helpers implement that derivation; +neither whole-run admission nor device qualification is inferred from this decision. +The protected function leaf `5db7d4de` is integrated at `93ba2e53` after independent +review. The exact committed source passed 66,336 bounds-enabled assertions at two +threads, zero warmed allocations and 16 Aqua/JET checks over 1,063 definitions. +Independent qualification passed 157,543 assertions, including 78 emitted-code +checks and the separately reviewed finite-underflow proof. These results establish +the documented conservative CPU arithmetic domain only. Actual replay spans, +restored Adams history and represented-operator operand bounds are the next +certificate inputs; public binary32 admission and each device remain unqualified. +Operand analysis `1ea43509`, `9ed0d2a4` and `59252a3f` is integrated at +`1f0c3912`, `9ced7ba5` and `410442e0` after independent review. Sixty-five committed +tests and three independent rational suites pass, including 60 signed large-node +replay geometries checked through both APIs, 810 adaptive stage endpoints, and exact +polynomial/rate/jump bounds. Positive restored sample offsets and multiply/add stage +rounding are included (#675). This is preparation-time operand analysis only; full +input assembly, Clenshaw/subtraction/compensation and vendor arithmetic obligations +remain explicit. It does not enable binary32. +The Python group adapter is independently approved on the reviewed Julia coordinator. Julia +chooses every member turn; Python copies bounded transports and joins each member +chunk exactly once. Core group acknowledgment leaves member barriers held until the +next Julia turn. Starts and owners transfer only after all member construction succeeds. +Dense Adams attachment is independently approved with explicit observed-field/coordinate +selectors while committed state stays monotone. Endpoint periodic rows accompany their +accepted attempt before dense planes; snapshots follow all owed planes. The common +conformance suite exposed and corrected the former row deferral in #687. +Shared replay-plus-interpolation refusal remains +unchanged. +The temporal monitor transport `a7d77050` is integrated at `8c625d0b`, with its +Python publication/service adapter independently approved. Julia owns decisions and +totals; Python retains detached rows and formats the existing record/messages. +The first continuation is committed atomically with its numerical restore. A fallback +after launch acknowledgment retains the last published scalars until the next valid +generation. External attempt/start callbacks can request a snapshot while recursive +advance, acknowledgment and close still refuse. Exact regressions cover #672 and #673. +The new managed monitor/conformance selection passes 35 cases: eleven monitor cases +and 24 common contract cases. Thirty skips name unfinished dense/transverse capabilities +or inapplicable bitwise repetition; they do not qualify those missing capabilities. +The integrated bounds-enabled Core passes 110,066 assertions in 224 sets. The 240-test +typed affected selection, scoped types, docstrings, spelling and Sphinx pass. Integrated +Aqua/JET passes all 16 checks over 1,169 definitions. All 53 previous real core, history +and statistic bridge regressions also pass. The numerical monitor leaf's separate +Aqua/JET and bridge checks passed. +Linux CPU qualification of `23f38f03` passes all 53 bridge/history/statistic cases at +one thread (215.32 seconds) and eight threads (1,011.55 seconds) on an eight-core +allocation of AMD EPYC 7513 hardware with Julia 1.13.3 and GCC 16.2. The allocation +is shared; these preparation/compilation-inclusive test durations are correctness +evidence, not comparative kernel benchmarks. The job completed successfully and its +evidence was retrieved. Cloud spend remains zero. +The previous pushed head `5c18bb90` still fails Julia Linux and combined coverage in +GitHub CI. Coverage is down to four statements and four branches in group-owner +refusals; targeted regressions are next. No full-gate success is claimed. + +The foundation is committed at `540794bd`. Setup commits `6c569742`, `fadae531` and +`52269788` were independently reviewed and integrated as `9fe74c26`, `5cec895c` and +`5264160b`. Julia package commits `28fb628e` and `201d91d5` were independently reviewed +and integrated as `ea847fcd` and `773bd539`. Updated main is merged at `e2df6c7c`. +Issue [#610](https://github.com/LupoLab/solprop/issues/610) +tracks the accepted signal-handler limitation and intermittent SIGTERM-during-GC +shutdown hang. The maintainer accepted an external hard-kill deadline and then deferred +further runtime investigation until after core implementation. Earlier failures remain +preserved. The supervisor tests now exercise the accepted TERM-then-KILL deadline; +successful forced termination is recorded separately from voluntary Julia shutdown. + +## Decisions + +- The accepted SEP's scope is retained with binary64-only input noise. Every binary32 + path, including Metal, refuses noise. No physics default changes. +- Start with Julia 1.13.3 and matching JuliaCall/PythonCall 0.9.37. Sources and + manifests identify immutable setups; runtime execution downloads nothing. +- `SimulationSettings.backend_options` forwards `wide` and `setup_id` through the + existing execution options. Device/options are outside science and resume hashes. +- Every Python entry into Julia is main-thread-only; Julia's own synchronous parallel + work and spawned worker processes remain supported. The maintainer accepted this + amendment after worker GC deadlocks were reproduced on macOS and Linux (#620). + ADR-077 and SEP Part II record it. Runtime initialization remains serialized. + Preserve actual Python + SIGINT without restoring Julia's SIGINT thread mask. The maintainer accepts that, + after Julia starts, SIGTERM may terminate the whole process without final output, + including with custom or ignored handlers and while no session advances. Fatal + shutdown may stall; supervisors must enforce an external SIGKILL deadline. Keep + Julia 1.13.3; revisit a supported solution with stable 1.14 in #610. Normal + cooperative cancellation and actual SIGINT handling retain their strict contracts. +- The ordered project stack and effective preferences are immutable setup identity. + Adding a device publishes another identity. Only that stack and standard libraries + enter `LOAD_PATH`; user startup files and artifact overrides cannot alter it. +- A plain Julia `@cfunction` is unsuitable for a stop listener: first entry from a + foreign thread may allocate and wait for GC. Use a C-compatible atomic-store leaf + without Julia runtime entry. The Python bridge owns the C byte, and Julia borrows + its address; the standalone engine can own its own byte. The listener retains no + Julia wrapper, whose final destruction could enter Julia on the stopping thread. + Captured callbacks retain the byte after detachment; session close must reject or + wait for active readers. The process runtime retains the compiled leaf's code. +- Process identity includes resolved depot, engine, executable and ordered project + locations, not merely the content ID. Otherwise selection in a relocated depot + could validate different files from those the running runtime will load. +- A loaded foreign `libjulia` is refused before import. Actual Julia load/depot paths, + active project and thread pools are checked before loading the engine. Failed + startup or device loading poisons the process; a fork after startup refuses. +- Registry handles retain Julia wrappers and borrowed Python buffers until main-thread + release. Foreign finalizers enqueue integer IDs; shutdown releases every owner before + JuliaCall's hook. Raw wrappers stay inside narrow bridge helpers. Error formatting, + exception-graph clearing and unwound-frame cleanup happen on main before a fresh + Python-only failure escapes. Recursive preparation, bridge entry and owner release + refuse. Interrupted startup and cleanup are covered explicitly. +- Set `PYTHONDONTWRITEBYTECODE=1` before JuliaCall import for Julia precompilation + children that embed Python. The initialized host's bytecode policy stays unchanged; + managed PythonCall source trees must remain byte-identical after runtime use. +- Runtime keeps CPU first in the ordered environment stack. Strict precompilation + temporarily puts the active device environment first, after proving identical global + and per-package effective preferences, then restores the runtime order. This permits + weak-extension dependency lookup without changing the published runtime identity. +- CUDA setup on Linux aarch64 refuses until identity distinguishes Jetson/L4T from + SBSA. The pinned runtime and driver selectors choose different artifacts there; + the current OS/ISA identity cannot establish portability. CPU aarch64 setup remains + supported but unqualified, as SEP 48 specifies. +- Julia consumes only `RunRequest` policy through the generic preparation boundary. + It never inherits the legacy driver or uses a Python-over-Julia numerical loop. +- DF32 admission bounds actual exponent spans, including replay and restored Adams + history, over the complete represented operator interval. +- Numerical comparisons use SEP 25/33 classes, never blanket cross-backend bit identity. + Export structure and exact controller decisions retain their exact contracts. +- Statistics consume explicit numerical inputs for the actual committed or dense field; + they never reuse an unrelated RHS trial. Fixed packed output and notice buffers belong + to the session. Spectral centroid and Parseval weights remain separate. In addition to + the periodic-capable catalogue, support exactly the existing spatial plane defaults + `beam_radius`, `fwhm_r` and `on_axis_spectrum`, preserving their plane-only eligibility. + This small scope clarification avoids refusing ordinary admitted spatial defaults. +- Every completed trial records its actual attempt before a proposal-floor failure, + including an Adams rejection. The existing reference/native omission is tracked in + [#651](https://github.com/LupoLab/solprop/issues/651); controller decisions, charged + calls and accepted state remain unchanged. Preserve the historical trace corpus. +- Binary64 Adams coefficients and transported compensation are generated in Julia. + History retains actual predictor samples and their represented operator rates. Rate + evaluation differentiates the same cumulative operator with explicit knot-side choice. + The Adams norm scales by the old state; it reuses only the protected sum-of-squares + primitives from the Runge–Kutta leaf. Carrier-frame and interaction formulations remain + subject to the accepted admission table; no additional route is inferred from kernels. +- Measure preparation-inclusive `wall_seconds` beside kernel-window timing. Full + gates run in CI; local qualification uses targeted, short-window tests. + +## Next actions + +1. Finish independent review of request-specific node preparation and collect the + common benchmark window's actual Julia smoke evidence. +2. Retrieve the one/eight-thread Linux qualification, address required CI findings, + and complete the initial CPU startup, preparation and short-window timing record. +3. Complete binary32 execution and whole-expression DF32 bounds, then each vendor's + public selection/qualification and the phase 5 documentation/evidence gates. +4. Revisit deferred runtime issues after core implementation; preserve all failed + evidence and complete the accepted supervisor qualification before claiming it passed. + +## Verification log + +- Acceptance revision: changed-document codespell and `git diff --check` pass; + `pytest tests/test_seps.py`: 349 passed, 3 expected process-SEP skips; + Sphinx builds with warnings as errors in a lightweight environment. +- Independent acceptance review completed. Its requested setup-selection tests and + backend-options phase assignment are included in `5fb24689`. +- Independent Phase 1 architecture review identified environment-stack leakage, + artifact-selection hooks, partial initialization poisoning and the foreign-thread + stop-setter constraint above. The macOS arm64 standalone LLVM leaf probe executes + a release store correctly; full lifecycle, signal and threaded-GC probes remain. +- Separate macOS arm64 subprocess probes with Julia 1.13.3 and JuliaCall 0.9.37: + foreign-thread atomic cancellation during threaded GC passed, as did restored + custom Python SIGINT. Ignored and custom SIGTERM, restored either immediately or + after threaded work, all terminated the process. Julia's kqueue subscription + receives SIGTERM before ordinary signal disposition. Disabling Julia handlers + with two threads crashed during shutdown. The maintainer explicitly accepted the + SIGTERM limitation and kept 1.13.3; no signal-disabling workaround is adopted. +- Python setup: 175 targeted typed tests, complete owned statement/branch coverage, + ruff, basedpyright, numpydoc and spelling passed before integration. The final + symlinked-home correction passed its seven affected tests. Independent review + corrected loader aliases, workspace redirection, publication races and wheel pairing. +- Julia package candidate `28fb628e`: 2,299 Core assertions, Aqua/JET, Runic and bridge + ownership checks passed. An empty CPU depot installed 83 packages and 19 artifacts; + offline repeat, JuliaCall use and another verification produced identical inventories. + CPU-plus-Metal strict precompilation initially failed on LLVM's BFloat16s weak + extension. The reviewed setup-only ordering correction passed 2,315 Core assertions, + Aqua/JET, Runic and 17 bridge checks. A fresh CPU/Metal stack precompiled 110 + dependencies; its Metal inventory contains 87 packages and 19 artifacts. Inventories + stayed identical after offline JuliaCall use. GPU execution is not yet qualified. +- Master runtime: 35 targeted typed tests and basedpyright passed, covering initialization + races, poisoning, identity/location pinning, actual load paths, and stop lifetime. + Packaged subprocess, native-coexistence and device tests remain outstanding. +- Integrated Python setup/runtime: 220 targeted tests passed. CLI, recipe and resume + integration: 78 passed with two expected skips. Julia Core tests including the atomic + stop byte passed with bounds checking; runtime docstrings passed. Native coexistence + awaits a matching native build; no source-digest guard is bypassed. +- Foundation checks: ruff and whole-package basedpyright pass; the targeted Python + setup/runtime and SEP consistency selection passes 569 tests with three expected + process-SEP skips. This is not numerical parity evidence. +- Independent wheel review passed direct and source-archive builds, installed source + pairing and lazy import/status. Its incidental-file inclusion finding is corrected + with a shared declared-input list and a regression; independent injected-file direct + and source-archive wheel rebuilds now exclude all sentinels and have identical Julia + payloads. This smoke used an isolated no-dependency install with existing dependencies; + fresh dependency resolution remains in CI. The public setup API page fixes three unresolved + function references; Sphinx now passes with warnings as errors. +- Julia CI commits `48714ac3` and `ebd239bf` were independently approved and integrated + as `8e584d24` and `90453af2`. Their runner tests, static checks, actionlint and change + selection scenarios passed. Existing device-filter robustness is tracked separately + in [#612](https://github.com/LupoLab/solprop/issues/612). +- After integrating SEP 47 Part B, 268 targeted Julia/CI-runner/request tests passed. + A fresh native build completed; whole-package types remain blocked by the dependency + errors above, pending that PR's CI fixes. +- Packaged macOS runtime gate: the first 12 subprocess cases pass with no skips, + covering main-thread startup, concurrent initialization, one/two-thread GC and GIL + progress, raw foreign-thread stopping, last-owner reclamation, shutdown and offline + preflight. A further 14 signal/spawn cases and four native-coexistence cases passed. + Native-before-Julia and Julia-before-native both retained real FFT plans at one and + two threads through clean shutdown against SEP 47 Part B. +- Worker-first Metal loading timed out at 180 seconds. Native stack sampling places + the worker in Julia's package-image global safepoint while Python's main thread is + joining it. A GIL-free loader alone also hangs at one and two threads. This is a + blocking runtime qualification failure, separate from the accepted SIGTERM policy; + ordinary worker computation/GC and any proposed fix require independent probes. +- Independent CPU-only GC probes reproduced the same worker deadlock at one and two + Julia threads on macOS. Internal main-thread GC parking still deadlocked under GIL + contention and is rejected. The maintainer accepted the main-thread boundary; 60 + targeted owner/runtime/stop tests pass, including failure graphs, interrupted hook + registration, recursive entry and cleanup failures. Real runtime requalification + remains in progress; no worker support is claimed. +- The main-thread boundary passed independent code review and its deterministic + failure reproductions. All 597 targeted Julia/SEP tests pass, with three expected + process-SEP skips; targeted types, formatting, docstrings and spelling pass. The + current Sphinx build is blocked by two references in unchanged SEP 47 Part B files + (`driver_session.foreign_request` and a malformed `spatial` run-request attribute + link), alongside that dependency's outstanding type fixes. No Julia documentation + warning remains; integrate the dependency's corrections before qualification. +- Linux x86-64 package qualification at `83da0ad5` passed fresh installation, native + coexistence prerequisites, Runic, 2,328 bounds-enabled Core assertions and 13 Aqua/JET + checks. Hardware: AMD EPYC 7513, four physical CPUs with SMT disabled; GCC 16.2.0, + x86-64-v3 native target, Julia 1.13.3 with generic cached code. A separate two-thread + CPU diagnostic completed its main call in 0.183398 seconds but timed out its worker + call after ten seconds, corroborating #620. These are runtime probes, not benchmarks. +- Polyester 0.7.19's macro can confuse a local `values` argument with `Base.values`: + two-thread macOS arm64 execution fails in standalone Julia and JuliaCall. Renaming + the local to `buffer`, or using an explicit singleton callback, passes at one and two + threads. [#621](https://github.com/LupoLab/solprop/issues/621) records the twelve-case + probe matrix and requires a production-loop regression when that wrapper lands. +- Read-only donor audit reproduced a non-THG multimode Raman out-of-bounds padding + read under bounds checking. [#613](https://github.com/LupoLab/solprop/issues/613) + tracks its correction and regression in the production port; the prototype is not + accepted as proof of correctness. +- Additional planning review requires conditioning-aware bounds near zeros of phi + functions and corrects Metal's portable sine/cosine allowance to 4 ulp. Experimental + witnesses remain measurements; algorithm and admission constants are not qualified. +- The primary DF32 papers and authors' formal supplement were checked. The planned + family is AccurateDWPlusDW, DWTimesFP3, DWTimesDW3 (including low-by-low), DWDivFP3 + and DWDivDW3. The last algorithm's naming typo is resolved by its formal proof; + underflow/overflow guards and transcendental bounds still need qualification. +- No propagation or GPU qualification is claimed yet. +- Main-thread runtime milestone `fda416dc` is committed. Independently reviewed + subprocess probes `2fedad6b` were integrated as `a01efd1f`; their 48-case matrix keeps + every requirement active. The first revised macOS run passed 18 cases before a + one-thread, ignored-SIGTERM-during-GC case hung for 180 seconds and needed supervisor + SIGKILL. The original failure remains visible. + Julia's pinned fatal-signal source explicitly anticipates asynchronous shutdown + stalls. A control with the Python owner-cleanup hook unregistered also stalled and + exited after a second SIGTERM; five companion controls exited on the first signal. + The maintainer explicitly accepted external hard-kill supervision (ADR-078), then + deferred further runtime investigation until after the core implementation. +- The revised main-thread macOS non-SIGTERM matrix passed all 36 cases, with no skips, + in 163.40 seconds. It covers one/two threads, cancellation during Julia and Python GC, + owner destruction, sanitized failures, shutdown, exact SIGINT counts, native loading + in both orders, actual Metal import, offline preflight and spawned workers. This does + not qualify numerical parity or the revised SIGTERM supervisor policy. +- Owned backend-option transport and recipe metadata pass 483 directly affected + tests, including spawn/pickle, post-translation replacement, unchanged scientific + hashes, early unsupported-option refusal and recipe/Python export. Targeted types, + ruff, formatting, changed-file spelling and diff checks pass. SEP consistency passes + 349 tests with three expected process-SEP skips; the incremental Sphinx build passes. + This does not clear the separately recorded whole-package dependency failures. + +- Owned backend options at `d1feaa15` passed independent review, 483 targeted tests, + targeted typing and formatting. Scientific hashes and recipe/spawn transport retain + their intended separation; unsupported option keys refuse before workspace allocation. +- Execution-owner and transactional group construction passed independent review and + 170 targeted session/group/preparation/frozen-interface tests at one native thread, + with no skips. Targeted Python and native adapter typing pass. Issue #623's regressions + preserve entrance fields and caller-owned backends on failed construction, including + a second native child allocation failure followed by a successful retry. +- The historical Linux packaged runtime job at `a01efd1f` completed with 273 passed, + 23 failed and zero skipped tests. Logs and XML are retained; remaining runtime + investigation is deferred as directed. No additional runtime job was submitted. +- CPU execution and packed-array protections are integrated at `3cfd932b`, + `d93590f9` and `ba7bee7a`; transforms/tables/operators at `92b81eba` and `037f20e8`. + Independent review approved their one/four-thread bounds checks, reference DFTs, + polynomial/operator witnesses and zero warmed allocations. Issues #624 and #626 + record the packed-storage and temporal-buffer corrections. +- Reviewed Kerr/Raman/plasma leaves are integrated at `94803513` through `fd313d8f`. + Their 282 assertions passed at one/two threads; independent actual NumPy comparisons + passed 23 assertions with maximum scaled difference 2.73e-16. Response quality passed + 12 Aqua/JET availability checks and nine concrete JET error analyses. The Raman + padding and plasma scratch regressions address #613 and #622. +- The independently reviewed binary64 Runge–Kutta leaf passes 163 bounds-enabled + assertions at two threads, including convergence, stable norms and zero allocations. + Scalar control passes 55 unit assertions and 418 same-host exact recorded-reading + assertions, including all three transactional floor failures. History restoration + now retains its total accepted count explicitly. +- The first constant scalar envelope source composition passes independent DFT and + short nonlinear-phase convergence witnesses, with zero warmed allocations. Independent + review also compared the actual NumPy passes at one/two threads with fourfold padding, + two modes, three nodes, nonunit folded taper and Kerr density: 40 assertions pass. + This composition alone does not admit the remaining routes or session services. +- Integrated package Aqua/JET passes 13 checks using the prepared shared dependency + cache. Earlier attempts with an incomplete isolated cache failed to load matching + dependency/stdlib images; these were tooling failures, not suppressed quality findings. +- The first complete binary64 scalar Kerr/RK composition passes nine managed-runtime + integration tests on macOS arm64 at two Julia threads. Fixed replay uses an + operation-derived rounding budget; adaptive output meets a fixed global accuracy + envelope against a refined NumPy reference. The 128/256-step reference difference + is 9.04e-13 relative over two centimetres; a separate 256/512 refinement gives + 1.35e-14. Each reference window finishes in seconds. Shared output service tests + cover both retained and field-free output, without legacy Julia methods. +- Session-boundary and lowering tests pass 36 cases, including receipt/generation + refusal, exact-once undelivered chunks, retained exports, recursive callbacks, + interrupted acknowledgment and cleanup failures. The standalone march/transfer + tests pass 181 assertions. Export conversion passes 16 independent exact NumPy + recipe witnesses, including signed-zero preservation (#633). +- Adams and low-storage leaves pass independent actual-NumPy witnesses: 144 Adams + assertions over orders one through six, and 32 low-storage assertions over one/eight + steps and task budgets one/two. Focused allocation tests pass 278 Adams and 69 + low-storage assertions. Temporal monitoring passes 94 component assertions and + 1,552 identical recorded-reading assertions. Review corrected immutable bucket + aliasing (#634); integrated precompilation corrected a helper-name collision (#636). +- The execution-owner type integration passed 928 affected typed tests and 13 helper + cases; final legacy-selector deltas passed 129 and 44 cases. Independent review + found that the session's started notification follows launch delivery and therefore + cannot replace the benchmark's earlier load timestamp. The established benchmark + window is preserved; execution-only backend timing remains an explicit pending + capability tracked in [#638](https://github.com/LupoLab/solprop/issues/638). + The directly affected CI/benchmark selection passes 74 tests. Public and + internal adapter docstrings, scoped types, formatting and spelling pass. The refreshed + Sphinx build passes with warnings as errors. Independent review approved this first + CPU slice; the restored legacy benchmark tests pass 34 cases and both shared output + modes pass again. Final boundary/runner selection passes 77 cases; scoped typing has + zero errors or warnings. Complete integrated package quality now passes all 13 + Aqua/JET checks after using prepared, matching dependency images. Earlier child + precompilation errors remain recorded as tooling failures. +- Transverse monitoring is integrated at `187504ec` and `cae3e377` after independent + review. The final bounds-enabled two-thread monitor selection passes 191 assertions; + the combined numerical and actual-oracle witnesses pass 304 and 4,345 assertions. + Mismatched face metadata now refuses before mutation in both directions (#637). +- Modal observation interfaces are frozen before implementation: separate coarse + analytic statistics, coarse real/envelope monitoring, and fine physical population + reconstructions. Split monitoring captures the masked pre-split candidate, then + consumes it after split damping, final masking and commit. Numerical observation + work owns scratch only; session glue owns bounded rows, event cursors and delivery. +- The shared real power-weight evaluator is integrated at `92bb693a`: 61 bounds-enabled + assertions, independent review, zero warmed allocation, Aqua and concrete JET checks + pass. Destination exports and statistics use this one represented-value evaluator. +- General scalar modal sources are integrated at `12cc9f41` and `76331571`, after + independent review. The final one/two-thread selections pass 1,027/1,981 assertions; + 240 actual NumPy witnesses pass, including field/envelope, each response, independent + profiles, three prefactor forms, chunk remainders and in-stage absorption. Aqua and + eight concrete JET checks pass. Review corrected operand overlap (#639) and mixed- + profile allocations (#640), with zero warmed allocation preserved. A cancellation + regression verifies the strengthened absolute-input contribution envelope. +- Full modal Python lowering/bridge integration passed independent review. The former narrow + envelope source is retired; its defining-DFT, ownership and nonlinear-phase tests now + exercise the general source. The carried source/march/transfer selection passes 309 + bounds-enabled assertions. Pure lowering/session-boundary selection passes 41 tests; + scoped typing has zero errors or warnings. Nineteen managed-runtime tests pass on + macOS arm64 with two Julia threads, including all three scalar response families on + both grids, represented varying operators/prefactors, and actual-position power + exports. Short material runs compare eight steps with sixteen/thirty-two-step NumPy + references under explicit accuracy and refinement envelopes. No long propagation + is part of this qualification. Sphinx passes with warnings as errors. +- Independent review corrected destination overlap with any retained numerical buffer + before weight evaluation (#642), and duplicate accounting of Julia-owned stop + storage (#643). Views and reinterpreted arrays are covered; borrowed stop storage + remains counted. The reviewer passed 111 transfer assertions and the original three + reproducer assertions after the fixes. +- CI at `5ae085f2` exposed an unqualified test package's `conftest` collision and + Linux package-wide JET findings. Adding a package identity resolves the three-file + fixture collection; the narrow runtime selection collects all 31 tests. Owned JET + corrections are in progress and remain blocking. The earlier local Aqua/JET pass + does not qualify the failing Linux lane. +- The modal bridge milestone is committed at `4dfa7ab2`. Pure Adams policy is + integrated at `71289bf2` and `b4df31bf`: 3,754 bounds-enabled checks and 33,003 + exact assertions on captured reference decisions passed independent review. The + shortened-run admission retains later operator kinks without forcing later steps + (#644). The session composition, rather than the policy leaf, remains pending. +- Reviewed CI corrections at `1047779a` and `0903c874` constrain CPU allocation and + parallel dimensions, preserve overlapping controller-history restoration, and bind + transverse-state construction to prepared face metadata (#645). Their focused + four-thread and two-thread selections pass 585 and 195 assertions respectively. + Remaining package-wide JET findings are still being corrected. Quality runners + must import JET before the engine so definition tracking is active; the direct + runner now follows the same order as CI. +- Prepared factories now report their owned run-transfer arrays once and sessions + retain only the execution owner after copying policy into Julia (#646). Independent + review and the 43-test boundary/lowering selection cover multiple factories, + dropped factories and nonempty shared controller weights. +- Shared CI integration corrections (#648) preserve lightweight parser/calibration + imports, validate legacy choices in native measurement scripts, reflect inherited + methods and Julia modules in structure diagrams, and register exact justified skip + reasons. The 76-test CLI/calibration/collection selection and 364-test figure + selection pass. Native script types and focused Python types report zero errors; + Sphinx passes. Windows subprocess confirmation remains a GitHub CI check. +- The shared internal landed-session lifecycle is frozen in `SESSION_DESIGN.md`. + Independent review approved the `_MarchSession` dispatch and unchanged launch + validation extraction; 309 source/march/transfer assertions pass with bounds and + zero warmed advancement allocation. The numerical agent owns the next independent + Adams session composition; the master retains shared lifecycle and Python integration. +- Modal observation composition is integrated at `cdc657bb` and `a6a357e9` after + independent review: 1,269 focused assertions include actual NumPy comparisons and + warmed allocation checks. Population scans use only rates and preionisation, + independently of current/loss algebra (#647), and reject raw nonfinite exposure + before flooring (#649). Periodic rows and monitor event transport remain the next + session integration, not a completed public capability. +- The combined package, including observations and Adams policy, passes all 16 blocking + Aqua/JET checks on macOS arm64. JET analyses all 864 definitions. The quality runner + now imports JET before the engine and rejects empty definition tracking explicitly; + earlier local passes without this evidence do not substitute for this check. Runic + passes on the changed integration files. Linux confirmation remains in GitHub CI. +- Latest dependency skip/documentation integration passes 37 targeted tests with three + expected skips. Whole-package basedpyright reports zero errors and three existing + native-stub warnings; the final structure/session-boundary selection passes 391 + tests. The full CI rerun awaits the next batch push. +- After publishing a fresh immutable setup containing the combined package, all + nineteen real bridge tests pass again in 51.05 seconds on macOS arm64 with two + Julia threads. This rechecks actual source construction, advance and export after + the JET corrections and shared lifecycle integration. +- The common scheduler now resumes warnings at launch, accepted endpoints, plane + preparation and finish without repeating numerical work or losing a pending plane + or snapshot. Candidate finishing receives the actual landing endpoint between its + initial and final masks. The 425-assertion source/march/transport selection passes; + independent review adds a seventeen-assertion consecutive-warning witness (442 + total). Zero warmed no-service advancement allocation is preserved. Combined + Aqua/JET passes sixteen checks, analysing all 874 definitions. Real monitor bridge + attachment is still pending; this is lifecycle and numerical-hook evidence. +- The batch at `aaec5e92` is pushed. GitHub's static lane confirms typing but finds + missing docstrings on two overload stubs, where Ruff D418 forbids docstrings. Narrow + GL08 exceptions explain that boundary and leave the implementation fully checked; + both scoped validators now pass. Other full CI lanes are still running. +- Independently reviewed Adams session `fc121ef5` and observation services `86a39425` + are integrated at `ce20d587` and `4a1171ca`. The reviewer ran 648 bounds-enabled + assertions, including actual Adams with split damping and all warning, deferred-row, + plane, snapshot and completion continuations. The combined witness retained zero + warmed advancement allocation. Separate NumPy split witnesses also pass. +- The Python Adams integration now copies the complete shared policy once, preserves + actual replay steps beyond the adaptive ceiling, exports cumulative logical and + actual work counts, and copies each pending accepted-order chunk before acknowledgment. + A single immutable accounting publication binds its generation and compact order + record, so interruption or failed-copy retries cannot duplicate the chunk. Every + retained order buffer appears in the memory ledger. Portable Adams continuation is + explicitly refused until its history transfer is complete. +- A fresh immutable setup passes 24 real Python/Julia bridge tests in 65.84 seconds on + macOS arm64 with two Julia threads. New witnesses cover adaptive Adams against a + converged independent RK reference and exact call-budget failures for both active + and structurally absent sources, at work limits one and 256. The focused Python + lowering/boundary selection passes 60 tests with runtime type checks, including + interruption immediately before and after atomic publication; changed adapter types + report zero errors. + The combined Julia source/march/Adams/transfer selection passes 911 assertions; + all 16 Aqua/JET checks pass with 968 definitions analysed and none cached. Sphinx, + scoped docstrings, Runic, changed-file spelling and adapter types pass. Independent + bridge review is complete with no remaining code blocker. Broader fixed-history + parity witnesses remain a subsequent qualification slice. The 364 structure-figure + assertions also pass after the new private accounting record. +- Modal statistics audit finds all 17 publicly admitted periodic names represented. + Remaining work is lowering and delivery, the accepted-source quadrature alarm and + monitor restore distinctions. Unavailable quadrature diagnostics must preserve NaN + without permitting nonfinite physical fields (#653). A resumed monitor with no old + record and an old record without quiet counts need distinct restoration inputs. +- GitHub confirms native CUDA/HIP compilation, sanitizers, tidy and three wheel targets + at `aaec5e92`; the full matrix remains incomplete. Its native Python surface test + exposed a missing `start_group` contract entry (#654). The entry and missing-member + regression now pass seven targeted tests; the shared frozen signature was already + correct. The registry overload-docstring correction also remains in the next push. +- Adams bridge milestone `50b369f9` and native contract correction `441b47fe` are + pushed to the draft PR. The subsequent native quality lane passes. GitHub found one + test-only type-narrowing error on `ResponseBudgetError.field`; an explicit ndarray + assertion now preserves that API check. Whole-package typing reports zero errors + and three existing native-extension source warnings; the scoped adapter check has + zero errors or warnings. GitHub uses the freshly built extension for its full gate. +- Reviewed low-storage `5cfb3577`, unavailable-diagnostic correction `0739d9b8` and + stable quadrature leaf `78ffd086` are integrated at `b29849cc`, `a54b54ab` and + `b0a024d5`. Independent qualification passes 428 low-storage assertions, 144 focused + statistic assertions and 685 quadrature assertions, including a 256-bit norm oracle. + The alarm leaf is available; accepted-source scoring and notice attachment remain + master integration work. +- Low-storage bridge review is complete. A fresh managed setup passes all 33 real + bridge tests in 72.50 seconds on macOS arm64 with two Julia threads, including an + actual first-source overflow with attempted count one, committed count zero and no + field ticket. Sixty-two typed boundary/lowering tests pass. The combined numerical + selection passes 2,410 bounds-enabled assertions; all 16 Aqua/JET checks pass with + 994 definitions analysed and none cached. +- Fixed-history Adams comparisons at orders one, five and six now use input-only + positive polynomial-product envelopes, separate retained-source error propagation, + and a verified Wiener-norm radius. Review found that the earlier RK helper assumed + an analytic soliton peak without bounding discrete stages (#656). Both RK and RK4IP + now use absolute-tableau stage majorants and a verified radius with explicit + transform, combination and phase-formation budgets. All ten affected comparisons + pass with unchanged precomputed bounds; adaptive runs keep their independent + converged-reference envelopes. The time-window multiplier is included explicitly. +- Portable Adams sample identity means accepted versus predicted, not charged-call + ordinal. The next transfer slice uses explicit integer tags mapped to the existing + strings, exact full store copies, oldest-first selected positions and zero-based + portable slots. Only a fresh unadvanced session can restore; compatibility refusals + precede all writes. Python retains history-key, precision, noise and ledger policy. +- Portable history leaf `f6849fa0` is independently reviewed and integrated at + `aa06f03d`, following the reviewed sample-kind correction. Its two-thread, + bounds-enabled selection passes 1,034 assertions, including plain/compensated + continuation, full inactive-row copies, signed zeros, alias/lifecycle refusals and + zero warmed resumed-advance allocations. Its quality run passes all 16 checks with + 997 definitions analysed and none cached. +- Profile-statistic lowering `b8e3bd10` is independently reviewed and integrated at + `d7fe0ee7`. Thirty-eight focused typed tests pass independently; the author's broader + descriptor selection passes 54. Profiles retain their actual units and measured + approximation records without retaining originating callables. Extreme-range shared + Chebyshev transform overflow remains tracked in #657. +- The Python portable-history bridge passes twelve actual managed-runtime tests: + Julia-to-Julia and both directions involving NumPy/native CPU, exact raw/full-row + transfer, foreign-store resets, overlapping destination refusal, and restored + budget exhaustion without a trial. Twenty-two pure history tests and the existing + 64 typed boundary/lowering tests pass. A trillion-step compact order record restores + in one pair without per-step expansion. Broader dense/restart qualification + remains pending; no binary32 history is admitted by this binary64 composition. +- Independent bridge review found that a restored int64-limit counter could wrap on + its next increment (#658). Checked cumulative arithmetic and pre-trial capacity + checks now preserve the final representable trial and refuse subsequent work before + source evaluation. Independent witnesses pass 32 additional assertions. The final + numerical aggregate passes 3,103 bounds-enabled assertions; all 16 Aqua/JET checks + pass with 1,014 definitions analysed and none cached. Forty-two real core/history + tests pass together in 79.29 seconds, with the two native continuation witnesses and + compensated-history transfer passing in subsequent focused runs. The offset-view + alias regression also passes. The combined typed Python/CI-runner/SEP selection + passes 514 tests with three expected process-SEP skips; docstrings, spelling, Runic, + scoped types and the Sphinx build pass. The full GitHub matrix remains outstanding. +- The statistics bridge milestone passes independent production and test review. + Eight managed-runtime tests pass on macOS arm64 with two Julia threads: six + integrator/yield cases compare identical raw fields using operation-derived absolute + bounds, and two material cases validate catalogue transport and population identities. + All 45 existing core/history bridge cases pass after attachment. The bounds-enabled + Core aggregate passes 42,802 assertions in 193 sets, including the reviewed DF32, + dense, monitor-continuation and group-hook leaves; all 16 Aqua/JET checks pass with + 1,076 definitions analysed. The 170 typed boundary/lowering/CI-runner tests pass, + as do Runic, scoped types, docstrings, spelling, whitespace, 349 SEP checks (three + expected process-SEP skips) and Sphinx with warnings as errors. The earlier pushed + head's CI reports Julia Linux and combined coverage failures; their logs are being + investigated, and this local milestone does not claim a green full gate. +- CI run `42916416591` at `12613fc5` completed with failures in Julia Linux and the + combined coverage report. The Julia suite passed 465 cases but failed two known + first-SIGTERM-exit probes (#610) and a status test that incorrectly assumed its + parent process had never initialized Julia (#668). The status assertion now runs + in a bounded cold subprocess; four typed tests and independent review pass. + A subsequent pytest-process SIGSEGV is retained separately in #669 without a + claimed cause or fix. Runtime investigation remains deferred as directed. + The latest SEP 47 merge addresses several reported coverage gaps; the next CI + report must establish the remaining package-wide coverage result. +- The fixed-schedule Python group adapter passes independent production review and + 16 real managed-runtime tests, including matched solo trajectories, warning/stopping + outcomes, numerical budget failures and failed copies with Adams order/monitor rows. + Seven independently authored typed transaction cases cover deferred interrupts, + repeated publication failures and constructor rollback; three ledger publication + cases pass alongside them. The broader affected typed selection passes 132 tests. + The bounds-enabled numerical group selection passes 659 assertions, including zero + warmed allocation; all 16 Aqua/JET checks pass over 1,199 definitions, none cached. + Scoped types, docstrings, spelling, Ruff, Runic and Sphinx pass. Missing runtime gates + remain visible; no whole-package CI result is inferred from these checks. + The shared alias/layout correction is now exercised through the actual managed + PythonCall bridge in the mandatory Julia lane. Review and current runtime checks pass. +- Adaptive Adams dense scheduler `c527047a` is integrated as `6da9b9b7` after an + independent 1,327-assertion numerical review. The adapter uses authoritative observed + field/coordinate selectors for export and power conversion; no caller can request + committed history while a dense plane behind it is selected. Snapshots drain owed + observations before saving the endpoint. The independent attachment review passes + 2,291 bounds-enabled assertions, including forced-terminal coordinate changes and + an affine-weight export bound. All 85 real core/history/statistic/monitor/group/dense + cases pass, including an interior field-only restart and independent RK refinement. + The integrated Core suite passes 110,764 assertions in 244 sets. Aqua/JET passes all + 16 checks over 1,217 definitions; the affected typed selection passes 149 tests. + Replay/interpolation and split/interpolation refusals remain unchanged. +- Binary64 input noise is attached to all three session methods. Each start selects + its actual problem/override draw, copies it into owned Julia storage, and adds it + only at a fresh launch before observations or history. Resumes keep their field + and the draw's monitor floor. Phase exports use the observed coordinate and the + absolute cumulative operator, including direct/expanded offsets. Modified and + binary32 noise still refuse. Independent review passed 1,340 bounds-enabled + assertions and eight typed callback-publication tests. The callback tests exposed + and fixed #680: copied fields/phases cannot populate replacement or closed caches. + The separately reviewed noise-floor comparison bound propagates absolute FFT + and energy errors through both numerator and denominator; its 19 tests pass. + All 100 real core/history/statistic/monitor/group/dense/noise cases pass on macOS + arm64 with two Julia threads. The affected typed selection passes 149 tests. + Core numerical tests plus the isolated inventory rerun pass 111,597 assertions + in 251 sets; the first inventory invocation lacked `--startup-file=no`, and an + isolated retry needed its existing `Pkg`/`TOML` imports. Those command errors did + not require source changes. Aqua/JET passes 16 checks over 1,236 definitions, + none cached. Scoped types, docstrings, Ruff, Runic, spelling and Sphinx pass. + Whole-package CI, standard performance records and remaining routes are pending. +- DOPRI5 dense leaf `f4cf2ed4` and conditioning correction `844ac356` are integrated + as `0e9ff4ae` and `3e395988` after 779 independent bounds-enabled assertions. + Shared extension weights are copied from the actual tableau; endpoint rows and + dense planes retain their own coordinates. Common conformance exposed #687: + endpoint rows must accompany the accepted attempt before the first dense plane + drains it. The repaired source preserves warning continuation and snapshot order. + Core passes 112,291 assertions in 264 sets, including explicit diagnostic reset + without new source work. Aqua/JET passes 16 checks over 1,253 definitions, none + cached. The managed dense/monitor/common selection passes 53 cases and 22 declared + skips; all 23 split-collar cases pass. Initial split assertions incorrectly + assumed low-storage skips its zero source and that a quiet verdict meant actual + collar omission; tests now verify the actual call counts and continued damping. + No production workaround was required for those test assumptions. Independent + adapter review and 12 typed admission checks pass. The shared adapted-request + admission correction #682 is committed as `af3edeb9`. The combined typed selection + had 263 passes and one stale CI skip fixture; the corrected CI fixture's 56 tests + pass. Formatting, scoped types and documentation checks accompany this milestone. + +- Representative precompile prerequisite `6c50a522` and workload `d7b29ca1` were + independently approved and integrated as `b26309fc` and `3cc78d05`. The prerequisite + selection passed 601 bounds-enabled assertions; the workload review passed 106, + including preservation of a nondefault planner policy. Full author quality passed + 16 Aqua/JET checks with 1,225 definitions analyzed and none cached, plus a concrete + allocating-workload analysis. The three owned serial sessions exercise field RK, + envelope Adams and low-storage dispatch, responses, observations and monitoring. + A fresh native-target engine-cache diagnostic measured a 22.67 s cache build and + 67.54 MB image; first representative execution was 6.93 ms versus 20.26 s with only + the workload macro disabled. These are local Apple arm64 cache diagnostics, not + quiet-machine propagation benchmarks or complete public-path compilation claims. + Two-thread dispatch still compiled a small specialization. Generic-target CI and + the required startup/worker campaign remain pending. +- The latest pushed `dca5615e` completed all Python/native static, default, slow and + combined coverage checks successfully, including every coverage shard and the + coverage report. Both Julia jobs passed their engine tests and 774 Python checks, + with 30 declared skips, but each failed one first-SIGTERM-exit diagnostic through + the already recorded shutdown timeout. This remains visible under #610 and the + maintainer's deferred runtime work; no completed full gate is claimed. +- Scalar spatial session attachment passes 104 managed checks across the affected + selections: 73 spatial cases, 23 modal split cases and eight modal observation + regressions. Eighteen initial comparison tests mistakenly requested a stage-only + quadrature diagnostic from the saved-field reference collector; the corrected + reference selection passes all 18, with the actual unavailable diagnostic checked + separately. The production implementation needed no adjustment for that test error. + The full two-thread bounds-enabled Core passes 116,924 assertions in 294 sets. + Integrated Aqua/JET passes all 16 checks over 1,409 definitions, none cached. + The new physical temporal-split leaf passes 64 assertions, including zero warmed + allocations; constant spatial noise phase passes three. Pure spatial transfer and + width-conditioning checks pass 21 cases. Independent source/observation reviews + cover transform order, flux normalization, aliasing and conditioned width bounds. + Actual bridge regressions cover nonzero launch phase, material-free physical + absorption and foreign-preparation export rejection (#690). Additional preparation, + transverse monitoring and per-route material/service witnesses remain outstanding. +- Shared BLAS lifetime attachment is independently approved. Fresh discovery after + runtime loading joins `_process.acquire_host_blas`, including libraries absent from + an outer construction scope. The loaded native backend's private BLAS is excluded. + Main-thread registry cleanup owns release, and interrupted publication retains one + complete preparation or rolls back the unpublished resources. A foreign restoration + failure keeps a Python-only retry owner and preserves the primary failure. The + 127-test affected typed selection passes; independent review repeated 46 BLAS/runtime + cases, including both acquisition/release orders and abandoned-owner cleanup. + Actual controller widths are metadata. The separately planned macOS Accelerate + forwarding remains unimplemented; no provider-selection qualification is inferred. +- Linear-flow and propagator outputs now reject hidden foreign-header overlap and + inputs aliasing retained operator/exponent storage before any write (#691). + Focused bounds-enabled tests pass 40 flow and 15 propagator assertions, alongside + the existing operator/source checks. Independent original probes pass 28 assertions + at task budgets one and two, including offset foreign headers, negative strides, + exact in-place operation, failure preservation and zero warmed allocations. +- Transverse service attachment and explicit continuation selection are independently + approved at `ea4b8731` and `70fa4d8e`. The latter fixes #693: an explicitly missing + record is a selection, while constructor-only resumption may still receive its first + later fallback. The independent core/bridge review passed 1,180 distinct assertions; + the final 447-assertion selection and 16 Aqua/JET checks passed, with 1,477 definitions + analyzed and none cached. Master Python record lowering passed 42 independent typed + tests, including the #692 face-stop first-warning coordinate correction. Subsequent + factory/session review passed 118 typed Python checks and 139 actual PythonCall + assertions across three methods and geometries. Managed integration remains separate. +- The timing-probe leaf `d71d29cf` is independently approved: 472 bounds-enabled + assertions, including additional counter-capacity/failure cases and zero warmed + allocations. Author witnesses also include 94 NumPy comparisons. The master adapter + retains preparation through its probe owner, consumes a start only after construction, + returns owning read-once fields and closes live probes with the execution owner. + Its separate review identified #696, where a cleanup exception replaced an initiating + error; cleanup now preserves the original exception with a diagnostic note. +- FFT call-site attachment `2b2ef88c` is independently approved. The exact final author + selections passed 686 assertions at one thread and 866 at two, all warmed allocation + checks zero. Aqua/JET passed 16 checks plus two complete-workload checks, with 1,455 + definitions analyzed and none cached. Independent testing added odd-length transforms, + both precisions and nondefault global planner settings: 396 assertions passed. + Master bridge integration refreshes offers per start (#694), makes optional cache-write + failure nonfatal while cleaning unexpected adoption failures (#695), and releases all + preparation-only wisdom maps after detaching facts. Calibration clearing also removes + compatible Julia files and forgets process offers without importing either runtime. +- The `09fb770a` CI run passed all Python/native default, slow, documentation, wheel, + device-compile and combined coverage jobs inspected so far. Static checking exposed + test-only optional-type narrowing and an ambiguous bounds import, corrected locally. + Linux Julia passed 911 Python checks with 22 declared skips, but three SIGTERM cases + stalled in GC. The diagnostic still expects SIGTERM alone; it is being aligned with + the already accepted external SIGKILL deadline, retaining observed escalation facts + and failure for unverified startup or unsuccessful supervision. No runtime fix is + claimed, and #610 remains open. +- Combined managed integration passes 34 new cases: 21 transverse sessions, 11 timing + probes and two real cache publication/reuse transactions. The numerical Core selection + passes 119,300 assertions in 323 sets; the final inventory module passes 34 assertions + in seven sets separately with its required startup flags and imports. Earlier command + omissions are retained as failed harness attempts, not hidden or patched in production. + Integrated Aqua/JET passes 16 checks over 1,544 definitions, zero cached. The affected + Python/SEP selection passes 455 tests with three declared process-SEP skips. Sphinx + builds successfully. Whole-package Python checking has zero errors and three existing + local native-stub warnings; scoped changed-module checking is clean. +- The SIGTERM supervisor correction is integrated at `eb4835ff` and `ef0687e4` after + independent review and 36 focused tests. A controlled real child proves forced-kill + escalation; three actual managed-runtime smoke probes exited on TERM in roughly + 42–47 ms, so those probes did not reproduce the intermittent stall. The supervisor + records which signal completed shutdown and still fails unverified startup or an + unsuccessful hard deadline. This implements the accepted policy, not a runtime fix. +- The shared conformance and affected spatial/monitor/noise/group regression selection + passes 147 tests, with 20 explicit numerical-versus-bitwise skips and two stale + transverse capability skips. Both newly enabled transverse conformance cases then + pass separately. CI now requires them and the spatial, transverse, timing-probe and + FFT managed modules; only the explicit bitwise-repeatability skips remain allowed. +- Verified CPU provider attachment passes 133 independent bounds-enabled Julia + assertions and four actual managed preparation/cache checks. Both integer ABIs, + real/complex products and missing-symbol fallback are checked. Missing Apple + threading capabilities retain OpenBLAS; actual provider and calling-thread scope + are metadata. ADR-079 records the macOS 15 control boundary. Regenerated manifests + add only the Libdl dependency edge. Independent wiring review passes 113 typed + checks, including the corrected #697 acquisition/rollback ownership and orderly + main-thread retry. The final affected cleanup selection passes 78 tests. +- The combined material matrix passes all 20 managed cases. It covers field and + envelope on five routes, plural plasma/Raman, independent modal gradients and + uncoupled tapers, and alternate march families. Independently reviewed eight-step + accuracy envelopes require separately refined 16/32-step reference settlement; + no formal convergence-order result is inferred. The material module and actual + provider checks are now mandatory in the Julia lane. +- Wide assembly leaf `d6687bd7` is independently approved and integrated at + `1a653768`: 25,055 independent exact-rational, domain, ownership and IR assertions. + Author final numerical checks pass 9,960 at one thread and 18,930 at two, including + zero warmed allocations. This certifies conditional CPU operations only; public + binary32 execution, stored-history integration, device certification and performance + remain separate work. Combined provider/wide/window package quality passes all + 16 Aqua/JET checks over 1,644 definitions, none cached. +- Window ownership correction #698 is independently inspected and integrated at + `3138fa4c`; 52 repeated bounds-enabled assertions verify one storage owner, actual + window results and zero warmed allocation. The shared planner's 23 pure and 38 + managed inventory cases accompany its pending adapter integration. +- The `162da950` CI static lane identified seven missing private-helper docstrings. + Scoped validation passes after `72ee3e4c`. Documentation builds successfully; + the SEP selection passes 349 tests with three declared process-SEP skips. Full + CI and the current one/eight-thread Linux correctness campaign remain in progress. +- Public CPU selection and request-specific node binding pass 38 actual retained-array + inventory cases, three public integrator cases and an independent-capacity reuse case. + Fourteen standalone Julia assertions verify immutable input sharing and range refusal. + A complete public simulation and the common benchmark window pass separately. + The corrected focused settings fixture passes; the combined pure selection passes + 180 tests with five declared managed-runtime skips. Scoped types have zero errors or + warnings; documentation builds successfully and changed-file spelling passes. +- The benchmark slice is independently reviewed and integrated at `dd94898d`. + Generic `prepared.start` return is the versioned ordinary-run timing boundary; + preparation-inclusive wall time and same-session actual counters remain separate. + Author validation passes 106 typed tests and 23 affected session cases; master + integration includes actual Julia public-run smoke. No timing ratio is claimed yet. +- Required CI at `162da950` reports 100% package coverage. Windows collection failure + #699 is independently reviewed, integrated at `6c211acf`, and passes all 38 affected + tests including cold imports with absent signal constants. The unrelated service + scheduling assumption is tracked in #700. A macOS shard passes 7,229 tests but its + artifact upload fails DNS resolution; the next push must re-establish every gate. +- Source range/coefficient helpers are independently reviewed at `dd38b8bf` and + integrated at `25b9c775`. All 159 authored bounds assertions and 128 additional + extreme-scale, signed-zero, coefficient-order and transactional-refusal assertions + pass on the exact detached review tree. These are preparation helpers, not yet + public binary32 execution. The original shared arithmetic record stays unchanged. +- Service test correction #700 is reviewed and integrated at `43fb2b7c`. It waits on + the actual stop-file watcher at a selected saved plane and separately tests a stop + at the final plane. Both independent cases pass, preserving every saved array. + The author additionally passes all 50 affected service/helper-consumer checks. + Production behavior and signal policy are unchanged. A new metadata helper's missing + parameter/return docstrings were caught and corrected by the local fast check. + +- Independent public CPU review approves `f85d3b49`: 55 typed checks plus actual + reverse chunk adaptation, detached metadata, preparation/handle lifetime and + request-added monitors on three spatial geometries. No blocker remains within + the declared numerical node-array payload scope. +- Protected observation helpers `3c8e4333` are integrated at `93050175` after + independent review. The primary Ogita–Rump–Oishi paper's Algorithm 4.1, its + equivalence to 4.4 and Proposition 4.5 (including underflow) were checked. All 50 + authored and 399 independent exact-sum/scale assertions pass. A private harness + initially failed to expect deliberate overflow refusals; its correction changes + no production behavior. +- Protected plasma `d5e48bda` is independently approved and integrated. In addition + to the authored regression selection, 77 independent scaled-population and saturated + exposure assertions pass. #701 remains visible until the implementation merge. + Existing binary64 composition tests and actual NumPy-single prefix witnesses pass; + full binary32 material/session and vendor qualification remain pending. +- The eight-thread Linux correctness selection reached its 45-minute stage deadline + without completion. The one-thread selection passed 267 tests with 22 declared skips + at source `4ab7e15a`; two of those skips are already removed and tested locally. + The deadline is not a passing multithread qualification. The comparative CPU + campaign uses source `08721c9d`, one/64 physical cores on an otherwise idle AMD + EPYC 7763, three alternating rounds and three repeats of 0.001 entrance fractions. + It exposed missing default plasma statistics (#702) and low-storage flow-table + support (#704), now assigned. Failed windows are retained; no complete phase 2 + measurement or performance conclusion is claimed. +- Master binary32 RK/low-storage leaf now retains narrow state arithmetic and wide + coordinates/factors, with protected normalized norms. The focused leaf and existing + binary64 operator/RK/low-storage/source regressions pass; the final new march leaf + passes 85 assertions and the combined plasma selection passes 88. Warm RK, norm + and low-storage calls allocate zero. Aqua/JET passes 16 package checks over 1,711 + definitions, none cached, plus three concrete binary32 calls before the plasma + leaf is combined. Independent review and combined quality remain pending; public + single precision, complete session scaling and Adams are not enabled by this leaf. + + +## Working record before the 11 November pause checkpoint + +These status statements are historical; the pause checkpoint supersedes them. + +# SEP 48 implementation + +Branch: `feature/sep-0048-julia-backend`; draft [PR 611](https://github.com/LupoLab/solprop/pull/611). +Proposal 609 merged at `04e72192`; Part I is frozen. Leave the completed implementation +ready for maintainer review, without merging it. Latest inspected CI head: `cbf8e4d4`. + +**Completion baseline, amended by the maintainer on 11 November:** binary64 CPU and +CUDA. Metal, ROCm/HIP and unfinished binary32/DF32 qualification are deferred. The +reviewed RK dense engine attachment is complete; numerical work now targets CUDA. +See [DEFERRED.md](DEFERRED.md) for exact status; Part II records the scope amendment. +New issues are only for work this PR will leave unresolved. Track in-PR defects here. + +## Current plan and status — 11 November 2026 + +| Phase | Current status | Remaining qualification | +|---|---|---| +| 1: package and runtime | Immutable setup, offline artifacts, bridge and ownership implemented | Deferred runtime failures stay visible; final installed-package and supervisor matrix | +| 2: binary64 CPU | Complete scalar modal/spatial session, services, history, groups, providers and public CPU selection | Final conformance/CI and isolated startup/worker measurements | +| 3: binary32 and DF32 | Substantial internal implementation and reviewed RK dense engine attachment preserved | Remaining qualification is deferred outside the baseline | +| 4: devices | CUDA execution/FFT foundation tested; storage and complete sessions in progress | CUDA full sessions, vendor quality, measurements; Metal and ROCm/HIP deferred | +| 5: documentation and Final | Manual/design records evolving with implementation | Complete measurements, final integration review, required green gates, archival/Final commit | + +No implementation phase is declared complete while its required evidence is missing. +Binary32 and GPU public admission remain closed. Every binary32 route refuses noise; +scientific defaults and hashes are unchanged. Julia 1.13.3 and bridge 0.9.37 remain pinned. + +The complete preliminary binary64 CPU matrix covers 12 cases at one and 64 cores, +three paired rounds and three repetitions per arm: 144 samples and 432 repetitions. +All results are finite; accepted/rejected counts match. Timings, actual short windows, +preparation-inclusive wall and limitations are in the +[benchmark ledger](../docs/dev/benchmarks.md#julia-cpu-entrance-windows-complete-preliminary-matrix). +Results are mixed and do not support a blanket speedup claim. Issues 711 and 729 +retain endpoint-reuse and radial/Cartesian profiling follow-ups. + +## Active ownership + +Every author uses a separate worktree. Reviewers do not review their own work. +Shared interfaces and integration remain master-owned. + +| Owner | Exclusive active scope | +|---|---| +| Master | Shared interfaces, integration, CI and records; CUDA bridge, RK dense observation and portable history | +| Services agent | Independent bridge review, then modal statistics, temporal numerical readings/splits and quadrature | +| Numerical agent | CUDA Raman/plasma composition, narrow validated coefficient-copy hooks, source tests/note | +| Device agent | A40 storage qualification; binary64 Adams method/dense mirrors and tests | + +The RK dense leaf `990871fb` is independently approved and integrated as `ad5ab855`, +with its reviewed engine attachment at `98f6af3e`. Python DF32 dense admission remains +closed. Adams dense is an unqualified deferred draft at `973fc351`, outside this branch; +no numerical test completed before deferral. Its intended retained polynomial and +rate-provenance design is not qualified evidence. + +Reviewed CUDA storage/readback, capture guards and RK orchestration are integrated at +`75d6849a`, `ba632416` and `9e41cdb1`. Host execution-model tests pass; actual A40 +storage qualification is queued, and device RK qualification remains pending. +The reviewed Kerr source, low-storage method and transactional export are now +integrated at `23fed2ab`, `900ce053`, `bbdf0eda` and `f007e1b7`. The master connects +execution selection through the bridge in a separate worktree. Actual device +qualification and the rest of the CUDA session catalogue remain required. + +The RK/low-storage DF32 bridge attachment is independently approved: ten files covering +`backend.py`, `_session.py`, `_wide.py`, PythonCall launch/wide attachment, its focused +tests and `DF32_EXECUTION.md`, plus retained independent boundary and group witnesses. +It has no public admission change; shared integration remains master-owned. + +CPU32 qualification is independently approved and integrated at `13835cf1` and +`5fa7294c`. All +59 distinct short cases have successful latest results; the corrected 32-case physical +spectral-band subset passes at unchanged envelopes. Issue 734 preserves the original +metric defect and the distinction from historical SEP 33 measurements. +The master adds 46 exact-rational physical-band assertions and ten managed all-route +integration cases on the new bridge, all passing. The DF32 Adams leaf is integrated +at `dc90b8ef`, independently approved for its conditional internal CPU scope. Review +passes 26,755 distinct assertions, including all-order factors, MPFR enclosures, +failure preservation, actual FFT/Kerr, chunk invariance and emitted arithmetic. +Warmed allocation assertions are zero; exact-final Aqua/JET passes 16 checks with +2,211 definitions analyzed, none cached, plus 12 concrete calls. Bridge attachment, +dense/spatial and device execution remained separate work at that leaf milestone. +The bridge/history attachment is now independently approved. A 51-case managed run +passes 23 new Adams cases and 28 existing history/RK/low-storage/group regressions; +two additional Adams group cases and six independent factory-boundary cases pass. +The groups include different plain/compensated members and refusal before a seed +source call. Completed compensated history and accepted sample/landing slack are +corrected (747, 748), without changing active numerical policy or portable bytes. +Targeted Julia checks pass 998 assertions. Final CPU Aqua/JET passes 16 checks with +all 2,217 definitions analyzed and none cached; pure boundary/CI checks pass 204 cases. +Spelling, formatting, types, SEP consistency and the Sphinx build pass. The first +source-identity and group-fixture failures remain in the record; their corrected +checks do not relax numerical envelopes. Public admission remains closed. + +The six-case Adams-versus-RK campaign is committed at `e1d7b460`: argon field passes +both tolerances; helium initially failed shared translation (737), and Julia binary32 argon +envelope exhausts cycle quadrature (738). All four identical NumPy binary32 envelope +controls complete. These remain ordinary qualification failures. The capped binary64 +reference pairs agree exactly but still need an independent step-size refinement. +The independently reviewed 737 fix uses the existing cancellation-free refractivity +with `log1p`, without changing physical inputs or interpolation tolerances. Its +46 changed-module cases and 743 independent Decimal/validity/table probes pass; +the unchanged helium propagation comparison still needs to be repeated. +The reduced-log plasma correction is integrated at `e690ef30` after independent +review of 37,243 distinct bounds-enabled assertions, including MPFR comparisons, +unchanged quadrature criteria and zero warmed allocations. The physical failing +neighborhood passes 1,038 checks. ADR-080 states the CPU elementary-function API +boundary and the separate device obligation (751). The repeated six-case comparison +passes four cases; both helium rows finish within every absolute envelope but fail +the unchanged twice-RK rule (753). Independent 16/32-step binary64 references differ +by at most `2.514e-15`. Candidate windows, metrics and envelopes are unchanged. +Identical NumPy binary32 helium controls pass all four method/tolerance combinations. +The separate population ownership fix (749), integrated at `cd409ee3`, refuses +foreign-header overlap and non-injective workspace destinations before writes. +Independent review passes 299 bounds-enabled assertions with zero warmed allocation; +the author also passes 22,725 directly affected assertions and CPU Aqua/JET. + +CUDA foundation review corrected raw pointer capture (730), complex FFT alignment +(732) and active cuFFT workspace accounting (735). The integrated foundation at +`dfa8f656` passes 418 actual A40 assertions in eight testsets, under network isolation. +Unfiltered quality passes Aqua's 11 checks but fails core/extension JET and all six +concrete-call analyses (741); no full-device qualification is inferred. First-entry +foreign-context coexistence (733) and released vendor handle-cache retention (736) +remain explicit qualification work. Apple M5 Max probes find 20 subnormal failures +in 136 arithmetic checks despite precise compiler settings (739). Base Metal execution +and FFT work is independently reviewed and integrated at `035ee5ac`: 308 actual device +assertions pass, including 48 independent ownership, queue and transform checks. +Metal Aqua passes 11 checks, while unfiltered JET and all six concrete analyses fail +(745). Native graph-cache/workspace retention remains unmeasured (743). Independent +probes confirm normal-input cancellation and FMA residuals can flush to zero through +both owned kernel launch forms. DF32 Metal is not qualified. + +## Latest validation + +- The selected-execution bridge passes 84 pure Python checks, six managed CPU + cases against NumPy, 272 focused engine assertions and CPU Aqua/JET (16 checks; + all 2,292 definitions analyzed, none cached). Independent review approves the + bridge after 65 typed Python checks and 48 Julia assertions, including 32 original + ownership/refusal probes. Public CUDA admission remains closed. Device source and + service factory attachment are separate required work. +- CUDA source review passes 858 host assertions, including 194 independent + composition/session/ownership checks. Low-storage review passes 179 assertions, + including 64 independent extreme-norm, early-refusal and analytic-phase checks; + its author passes 2,322 affected CPU assertions and Aqua/JET. Export review passes + 362 assertions after correcting explicit power weights overlapping staging storage. + Its author passes 2,469 affected CPU assertions and Aqua/JET. No actual GPU result + is implied by these host checks. The inherited RK positional alias fixture now + includes its readback field; 431 affected assertions pass. +- The combined source/method/export tree passes 1,700 targeted assertions across + 41 testsets. CPU Aqua/JET passes 16 checks with all 2,294 definitions analyzed and + none cached. The complete gate still runs in CI; device tests remain pending. +- The amended baseline selector passes 79 committed tool tests and 104 independent + inventory/verifier checks. Actual opt-in collection selects 1,374 baseline cases + across 55 modules and exactly 118 deferred precision cases across seven modules; + all ten required Julia CPU conformance names remain in the baseline collection. + Missing, skipped, failed or errored mandatory tests still fail either command. +- The integrated RK dense attachment passes 2,419 bounds-enabled assertions across + 40 testsets. The subsequent device storage/RK integration passes 1,353 targeted + assertions; CPU Aqua/JET passes 16 checks with all 2,266 definitions analyzed and + none cached. These are CPU checks, not CUDA hardware evidence. +- CI at `cbf8e4d4` confirms the 15 qualification-test typing errors are corrected: + full typing has zero errors or warnings. Two missing helper docstrings are fixed + at `bbe2cfe3`; targeted docstring, lint and spelling checks pass, and independent + review confirms unchanged code semantics. Linux gates again + fail before tests because the runner's Azure package mirror cannot resolve (757). + The independently reviewed remedy at `fc877681` retains the runner's official + Ubuntu archive/security fallbacks and its signed source configuration. Actual + replacement CI remains required. +- Integrated Julia Core: 156,695 assertions in 484 testsets pass, bounds enabled, + two threads. Aqua/JET: 16 checks pass, all 2,067 definitions analyzed, none cached. +- Reviewed binary32 composition: 84 actual managed retained-owner cases plus 27 pure + cases pass; independent review adds 178 PythonCall factory and seven registry checks. +- Reviewed DF32 bridge: 101 typed pure tests and ten actual managed tests have passing + latest results, including refined binary64 references, phase refusals before source + work, completed starts and mid-plane field restarts. Six narrow-state group checks + also pass, including both wide types and independent member failure state. Independent + review repeats all 22 managed cases and adds the retained factory boundary witnesses. +- CPU-only CUDA artifact setup and isolated-network A40 package loading, broadcast, + GEMM and FFT primitives pass in both precisions. These precede extension qualification. +- CI at `984444ce`: Linux/macOS Julia Core and Aqua/JET pass. macOS Python passes + 1,275 tests with 20 declared skips; verifier correction 731 passes 67 independently + repeated tests. Linux Python passes 1,274 with one shutdown-finalization failure, + followed by a post-summary segmentation fault (669). +- Other inspected CI lanes pass except the combined coverage report's two missing + device-refusal lines (725, corrected without exclusions) and an unrelated Windows + GUI event-log sharing violation after 424 passes (724). Fresh full CI runs on + `c35e35bd`. That run exposes stale internal/public admission test expectations (740), + corrected and independently reviewed at `f1589c25`: 55 typed targeted tests pass, + without changing production admission. Windows GUI fails its resume test again; + the Linux Julia job passes Core and Aqua/JET, then reaches its two-hour job limit + during the still-progressing adapter suite (712). macOS completes 1,339 adapter + tests with 20 declared skips and the three stale spatial-admission failures already + corrected under 740. The next batch separates the complete engine and adapter + stages, each with a bounded three-hour allowance. No check is omitted and no + cancelled or failed gate is claimed green. + +Local checks are targeted; full gates, slow lanes and package coverage run in CI. +Previous failed fixtures, timeouts and harness invocations remain in the evidence. +The [historical record](IMPLEMENTATION_HISTORY.md) retains detailed earlier reviews, +source identities, validation counts and ownership handoffs. + +## Next actions + +1. Run the next actual CUDA source/method/export device snapshot; the combined host + regressions pass. No further binary32 campaign is on the baseline critical path. +2. Complete binary64 CUDA modal source, low-storage/Adams methods, observations, + export and shared services; integrate the selected-device bridge and registry. +3. Qualify actual CUDA kernels, ownership and complete session behavior on A40, + including vendor quality and CPU regression checks. +4. Finish binary64 CPU/CUDA, startup, setup/depot and spawned-worker measurements + on short windows. No AMD rental or Metal campaign is required for this baseline. +5. Reconcile final CI and SEP 47 interfaces, finish manual/design/ADR/release records, + complete integration review, then prepare Final and mark the one PR ready. + +The maintainer deferred rare runtime investigation until core implementation is done. +Issues 610, 620 and 669 retain the accepted boundaries and remaining failures; this +changes work order and does not turn a failed qualification into a pass. + +## Decisions + +- The maintainer reaffirmed a single device-generic numerical implementation. + The source and Adams audits confirm shared arithmetic; the latter compares eight + unchanged kernel bodies across seven functions. The pending statistics draft had + duplicate dispatch/finalization and is being consolidated before integration. + Keep device differences in allocation, launch, transform, copy and readback + primitives. The imported but unused AcceleratedKernels dependency and departure + from the experiment's shared reduction layer require reconciliation here. +- The maintainer narrowed completion to binary64 CPU/CUDA on 11 November. Defer + Metal, ROCm/HIP and unfinished binary32 execution with either wide arithmetic. + DF32 is a wide-intermediate choice for binary32 state, not a whole-state precision. + Deferred evidence stays explicit and public admission remains closed. +- The accepted SEP's scope is retained with binary64-only input noise. Every binary32 + path, including Metal, refuses noise. No physics default changes. +- Start with Julia 1.13.3 and matching JuliaCall/PythonCall 0.9.37. Sources and + manifests identify immutable setups; runtime execution downloads nothing. +- `SimulationSettings.backend_options` forwards `wide` and `setup_id` through the + existing execution options. Device/options are outside science and resume hashes. +- Every Python entry into Julia is main-thread-only; Julia's own synchronous parallel + work and spawned worker processes remain supported. The maintainer accepted this + amendment after worker GC deadlocks were reproduced on macOS and Linux (#620). + ADR-077 and SEP Part II record it. Runtime initialization remains serialized. + Preserve actual Python + SIGINT without restoring Julia's SIGINT thread mask. The maintainer accepts that, + after Julia starts, SIGTERM may terminate the whole process without final output, + including with custom or ignored handlers and while no session advances. Fatal + shutdown may stall; supervisors must enforce an external SIGKILL deadline. Keep + Julia 1.13.3; revisit a supported solution with stable 1.14 in #610. Normal + cooperative cancellation and actual SIGINT handling retain their strict contracts. +- The ordered project stack and effective preferences are immutable setup identity. + Adding a device publishes another identity. Only that stack and standard libraries + enter `LOAD_PATH`; user startup files and artifact overrides cannot alter it. +- A plain Julia `@cfunction` is unsuitable for a stop listener: first entry from a + foreign thread may allocate and wait for GC. Use a C-compatible atomic-store leaf + without Julia runtime entry. The Python bridge owns the C byte, and Julia borrows + its address; the standalone engine can own its own byte. The listener retains no + Julia wrapper, whose final destruction could enter Julia on the stopping thread. + Captured callbacks retain the byte after detachment; session close must reject or + wait for active readers. The process runtime retains the compiled leaf's code. +- Process identity includes resolved depot, engine, executable and ordered project + locations, not merely the content ID. Otherwise selection in a relocated depot + could validate different files from those the running runtime will load. +- A loaded foreign `libjulia` is refused before import. Actual Julia load/depot paths, + active project and thread pools are checked before loading the engine. Failed + startup or device loading poisons the process; a fork after startup refuses. +- Registry handles retain Julia wrappers and borrowed Python buffers until main-thread + release. Foreign finalizers enqueue integer IDs; shutdown releases every owner before + JuliaCall's hook. Raw wrappers stay inside narrow bridge helpers. Error formatting, + exception-graph clearing and unwound-frame cleanup happen on main before a fresh + Python-only failure escapes. Recursive preparation, bridge entry and owner release + refuse. Interrupted startup and cleanup are covered explicitly. +- Set `PYTHONDONTWRITEBYTECODE=1` before JuliaCall import for Julia precompilation + children that embed Python. The initialized host's bytecode policy stays unchanged; + managed PythonCall source trees must remain byte-identical after runtime use. +- Runtime keeps CPU first in the ordered environment stack. Strict precompilation + temporarily puts the active device environment first, after proving identical global + and per-package effective preferences, then restores the runtime order. This permits + weak-extension dependency lookup without changing the published runtime identity. +- CUDA setup on Linux aarch64 refuses until identity distinguishes Jetson/L4T from + SBSA. The pinned runtime and driver selectors choose different artifacts there; + the current OS/ISA identity cannot establish portability. CPU aarch64 setup remains + supported but unqualified, as SEP 48 specifies. +- Julia consumes only `RunRequest` policy through the generic preparation boundary. + It never inherits the legacy driver or uses a Python-over-Julia numerical loop. +- DF32 admission bounds actual exponent spans, including replay and restored Adams + history, over the complete represented operator interval. +- Numerical comparisons use SEP 25/33 classes, never blanket cross-backend bit identity. + Export structure and exact controller decisions retain their exact contracts. +- Statistics consume explicit numerical inputs for the actual committed or dense field; + they never reuse an unrelated RHS trial. Fixed packed output and notice buffers belong + to the session. Spectral centroid and Parseval weights remain separate. In addition to + the periodic-capable catalogue, support exactly the existing spatial plane defaults + `beam_radius`, `fwhm_r` and `on_axis_spectrum`, preserving their plane-only eligibility. + This small scope clarification avoids refusing ordinary admitted spatial defaults. +- Every completed trial records its actual attempt before a proposal-floor failure, + including an Adams rejection. The existing reference/native omission is tracked in + [#651](https://github.com/LupoLab/solprop/issues/651); controller decisions, charged + calls and accepted state remain unchanged. Preserve the historical trace corpus. +- Binary64 Adams coefficients and transported compensation are generated in Julia. + History retains actual predictor samples and their represented operator rates. Rate + evaluation differentiates the same cumulative operator with explicit knot-side choice. + The Adams norm scales by the old state; it reuses only the protected sum-of-squares + primitives from the Runge–Kutta leaf. Carrier-frame and interaction formulations remain + subject to the accepted admission table; no additional route is inferred from kernels. +- Measure preparation-inclusive `wall_seconds` beside kernel-window timing. Full + gates run in CI; local qualification uses targeted, short-window tests. diff --git a/julia/MARCH_PRECISION.md b/julia/MARCH_PRECISION.md new file mode 100644 index 000000000..50c356ad2 --- /dev/null +++ b/julia/MARCH_PRECISION.md @@ -0,0 +1,51 @@ +# Binary32 march arithmetic + +The CPU RK and low-storage leaves retain host binary64 positions and translated +tableau records. State, slopes, stage combinations, defects and norm products use +binary32. Each scalar stage weight and step multiplier rounds before entering its +pointwise kernel. Nonzero multipliers must fit the binary32 normal range; preparation +checks tableau coefficients and trial admission checks the actual step before writes. +This range boundary does not infer an admitted physical phase domain. + +`LinearFlow` forms and evaluates its represented exponent in binary64. Its exponential +rounds once to the state precision before multiplying the state. The stable linear +increment follows the same boundary, using the existing protected complex `expm1` +formula. Zero exponents preserve exact copies or zero increments. DF32-wide flows +require their separate whole-expression certificate and are not inferred here. + +## Protected norms + +For each column, first find the largest absolute real or imaginary component `m`. +For nonzero `m`, sum the squares of components divided by `m`, using the protected +Sum2s accumulator described in [observation arithmetic](OBSERVATION_PRECISION.md). +Normalized components are at most one, so finite inputs cannot overflow in their +products or sum. There are two terms per spectral row; workspace preparation checks +the strict `2*n_omega < 2^24` theorem hypothesis before allocation. A zero column has +zero scale and zero sum. Any nonfinite state entry rejects the norm, even outside its +mask. The small column merge and final square root use host binary64. + +For a weighted defect norm, the existing global magnitude supplies +`d_i = rtol * weight_i * magnitude + atol`, in stored state units. Construct these +scalars in host binary64, then retain `d_i = m_i*2^e_i` as a rounded binary32 mantissa +and an integer exponent per frequency. Defect ratios use binary32 `ldexp` and division; +no physical inverse-square weight is formed in binary32. A zero denominator and zero +defect contribute exact zero. A nonzero defect with zero denominator, a nonfinite +denominator, or an overflowing/nonfinite ratio yields a failed scalar norm. Gradual +underflow retains the additive underflow term in the reduction bound. All buffers are +reused and appear in the ordinary retained-array ledger. + +The error budget includes normalization divisions, squared products, the rounded +denominator, each column's Sum2s bound and the host merge. Applying only a merge bound +to rounded column sums would omit their earlier errors. Gradual underflow contributes +absolute terms bounded by half the smallest binary32 subnormal per inexact operation; +it is not flush to zero. Tests with columns differing by 260 binary exponents check +the protected reduction against binary64 reference readings and explicit bounds. + +## Qualification scope + +Short eight-step RK and low-storage witnesses compare with the analytic solution of +a split linear equation, with separate rounding and truncation terms. Existing +binary64 leaf tests retain their original bounds and convergence checks. Concrete +JET calls and warmed allocation checks cover binary32 RK trials, error norms and +low-storage trials. Full session scaling, Adams, portable history, DF32 and devices +remain separate integration work; this leaf does not enable public single precision. diff --git a/julia/METAL_FOUNDATION.md b/julia/METAL_FOUNDATION.md new file mode 100644 index 000000000..7998cb428 --- /dev/null +++ b/julia/METAL_FOUNDATION.md @@ -0,0 +1,214 @@ +# Internal Metal execution and transform foundation + +This extension supplies dense device storage, synchronous indexed launches, copies, +and temporal/spatial FFTs for the existing numerical interfaces. It does not admit +public Metal propagation sessions. Complete device source/reduction/history/service +composition and the DF32 arithmetic qualification remain separate prerequisites. + +## Task, device and queue ownership + +`device_execution(Val(:metal), device_index, tasks; check_body=false)` uses a +zero-based device ordinal and a positive host worker budget. It retains the preparing +Julia `Task`, the selected `MTLDevice` and that task/device's public `global_queue`. +Every operation refuses a different task before allocation or launch. Within the +owning task, it selects the retained device, verifies queue identity, performs the +operation, synchronizes and restores the prior task-local device in `finally`. +Closures and numerical owners remain rooted until synchronous completion, including +the failure cleanup path. No global queue is replaced and no private queue ownership +is promised. + +The pinned KernelAbstractions backend launches through Metal's current task/device +queue, and the MPSGraph FFT implementation uses that same queue explicitly. This +provides one ordering domain for pointwise operations, copies and transforms. The +foundation qualifies Metal.jl task-local state, not an unrelated foreign raw-driver +context. The Python bridge must independently demonstrate that its entries retain +the same Julia task before public admission. GPU asynchronous scheduling and graph +optimization are outside this first synchronous implementation. + +Only the two extension-owned kernel function types specialize +`KernelAbstractions.compiler_options`, with `fastmath=false` and `always_inline=true`. +Their workgroup and index-domain type parameters preserve the pinned KA `_Size` +invariant, avoiding the initial generic-method ambiguity tracked in +[#742](https://github.com/LupoLab/solprop/issues/742). No global method override changes +unrelated Metal or KA kernels. These flags do not imply gradual underflow on Apple +hardware. + +## Dense storage and copies + +Numerical arrays use explicit `Metal.PrivateStorage`. Shared host/device arrays and +wrapped device views are currently refused; host arrays and supported host views are +copied into independent private storage. Packed host Boolean arrays are expanded into +ordinary Boolean elements before upload. The element type is preserved, and pointer +fields, binary64, 128-bit integers and zero-size elements are refused. Nested kernel +captures must contain supported scalar values and validated dense private arrays. + +Device-to-device copies require identical shape and element type on the prepared +device. Exact object identity is a no-op; every other occupied-byte overlap refuses +before writes. Overlap uses GPU virtual addresses and byte offsets rather than Julia +array-header identity, including independently wrapped headers and unequal element +types. Device-to-host copies accept a matching owned dense Julia `Array`. Device +array spans must fit their retained `MTLBuffer` and have whole-element offsets. + +The ledger counts a retained `MTLBuffer` once even if multiple dense headers share +it, using the full buffer length. This deliberately distinguishes numerical array +payload from native objects, allocator reservations, command/compiler state and +framework caches. The public memory ledger has no claim about total process RSS or +all Apple GPU memory. + +## Transform semantics and retained memory + +Temporal plans transform dimension one of dense Float32 or ComplexF32 matrices. +Real transforms use `n_time÷2+1` complex rows; complex transforms use `n_time` rows. +Both directions preserve their input, and their buffers must be disjoint. The raw +negative-sign forward transform and raw backward transform retain the shared seam +convention. Inverse application multiplies by the prepared `Float32(1/n_time)` once. +No physical units, Fourier sign convention or amplitude scale is changed. +Real temporal lengths must be even: pinned Metal.jl's graph builder does not set +`roundToOddHermitean`, whose Apple default is false. Refuse an odd length before +planning rather than let the graph's even output shape disagree with the caller. + +Spatial plans transform a nonempty strictly increasing axis tuple within Julia +dimensions 1 through 4 of a rank-1 through rank-16 ComplexF32 array. The vendor API +supports only the four trailing tensor dimensions, which Metal.jl's reversed layout +maps to Julia's first four. All other dimensions are batches. Application is in place +and requires the same input/output array owner. The raw backward transform receives +one multiplication by the reciprocal transformed volume. Shape, precision, task, +device, offset representation and overlap are validated before calling MPSGraph. +Widening the odd-real and transformed-axis boundaries requires separate qualification +under [#744](https://github.com/LupoLab/solprop/issues/744). + +Preparation warms both directions on temporary zeroed arrays of the exact shapes, +preserving the supplied buffers. Those arrays are rooted through queue completion +on success and failure: the scoped warm closure captures both owners until cleanup +synchronization ends. The controlled enqueue-then-error/retry regression covers +[#746](https://github.com/LupoLab/solprop/issues/746). The arrays are not retained by +the plan wrappers. +Pinned `MtlFFTPlan` stores input/output +dimensions and axes, with an initially undefined inverse-plan cache; it stores no +explicit numerical work array or exposed native workspace byte count. Therefore its +numerical-array ledger entry is empty, **not** a zero native-workspace assertion. + +Metal.jl caches MPSGraph graphs by device and transform structure in a process-wide +dictionary without a source-level size limit. Its FFT graph has no constant arrays, +but MPSGraph compiler/cache/workspace memory remains opaque. Each execution also +constructs host feed/result dictionaries. The pinned source avoids compiled graph +executables because they retain every passed output buffer. This implementation +does not mutate the vendor-global cache on session close. Repeated shape preparation, +release and collection require separate measurements and a supported retention policy +under [#743](https://github.com/LupoLab/solprop/issues/743). Neither an empty plan-array +ledger nor `Metal.@allocated == 0` establishes complete native memory accounting. + +## Arithmetic qualification and the DF32 blocker + +The primary Metal Shading Language 4.1 specification permits flushing Float32 +subnormal inputs and outputs to zero (§8.1, p.368) and permits round-to-zero as well +as round-to-nearest-even (§8.2, p.368). It defines explicit `fma` as one correctly +rounded exact product-plus-add (p.206), while ordinary contraction is separately +controlled (§1.6.5). Thus `fastmath=false` alone cannot establish the error-free +transformation hypotheses used by the current DF32 implementation. + +The initial actual-device primitive probe ran on an Apple M5 Max with 40 GPU cores, +macOS 27.0.1, Julia 1.13.3, Metal.jl 1.12.0, GPUCompiler 2.21.0 and +KernelAbstractions 0.10.5. It tested 136 arithmetic/TwoSum/TwoProd/cancellation results +against independently rounded 256-bit expressions. Twenty checks failed, all involving +subnormal inputs, outputs or residuals. Normal positive/negative odd/even ties, +explicit FMA versus separately rounded multiply/add, and the tested DF32 cancellation +witness passed. Generated LLVM/AIR retained separate `fmul`/`fadd`, explicit +`air.fma.f32` and `air.compile.fast_math_disable`. + +Two failures require only normal inputs. First, +`2*floatmin(Float32) - nextfloat(floatmin(Float32))` should produce the largest +subnormal, bit pattern `0x007fffff`, but produced zero. Second, for +`a=b=ldexp(nextfloat(1f0),-50)`, the rounded product is normal (`0x0d800002`), while the +exact FMA product residual is `2^-146` (`0x00000008`); the device residual was zero. +Subnormal-input division also produced infinity when the gradually underflowing +reference remained finite. These are actual failures of the present DF32 hypotheses, +not a request to widen a rounding tolerance or assume a restricted domain. + +[#739](https://github.com/LupoLab/solprop/issues/739) preserves a standalone strict +reproducer and tracks the needed numerical design/qualification. Full DF32 support +remains blocked. The base execution and FFT checks below do not waive that failure. + +## Focused numerical checks + +Launch/copy witnesses use small exactly representable integers, hard masks and exact +ownership/no-op contracts. FFT witnesses compare represented binary32 input against +a direct DFT evaluated with 256-bit arithmetic. Their finite qualification model +assumes rounded butterfly/product operations and twiddle components accurate to two +unit roundoffs. This is a stated model tested on small transforms, not a proof of +arbitrary MPSGraph FFT sizes or undocumented vendor twiddle generation. + +For tested axis length `n`, let `g=gamma(64*n)`, exact element-magnitude bound `M` +and preceding element-error bound `E`. One raw transform uses the outward recurrence +`M_next=n*M` and +`E_next=n*(E + g*(M+E)) + 64*n*floatmin(Float32)`. +The count covers the tested radix-two stages, complex products and real splitting; +the last term explicitly permits flushed subnormal arithmetic rather than assuming +gradual underflow. Compose all forward and reverse axes before the final normalization. +The tested volumes are powers of two, so final normal scaling is exact and its +possible flushed result contributes less than one `floatmin(Float32)`. These budgets +are fixed from input magnitudes and shapes before comparing device discrepancies. + +Warmed `Metal.@allocated` checks count allocations visible to Metal.jl only. Host +bookkeeping and opaque framework memory are separate; CPU's zero-allocation +advancement requirement is not silently extended to all vendor host calls. Negative +tests preserve owners on wrong-task, wrong-shape/type, unsupported storage, +foreign-offset overlap and malformed offset refusals. One device does not qualify +multiple-device restoration or cross-device copies. + +The device test modules are explicit opt-in files; an unavailable Metal device fails +their prerequisite rather than skipping tests. The CPU aggregate must not load them +implicitly. A focused invocation using the pinned prepared Metal environment is: + +```sh +JULIA_PKG_OFFLINE=true JULIA_NUM_THREADS=2 JULIA_LOAD_PATH='@:@stdlib' \ + julia --startup-file=no --check-bounds=yes --project=julia/environments/metal \ + -e 'using Test; include("julia/test/metal_execution.jl"); + include("julia/test/metal_transforms.jl")' +``` + +## Observed foundation results and outstanding quality + +On the M5 Max environment recorded above, the final bounds-enabled two-thread device +suite passed 258 assertions in six test sets plus two device prerequisites. The tests +cover private storage, copied ownership, indexed/column launches, task and queue +boundaries, temporal/spatial normalization, independent byte-overlap and offset +checks, native-shape admission and preparation-failure cleanup. Warmed pointwise and +temporal-cycle calls each reported zero Metal.jl device-array allocation. For an +8-by-3 ComplexF32 fixture, the corresponding host allocation measurements were +1,376 bytes for one indexed launch, 7,712 bytes for one forward/normalized-inverse +cycle and 1,088 bytes for one device-to-host copy. These are bounded implementation +facts, not complete GPU memory measurements or a propagation benchmark. + +The unfiltered initialized-device quality run still **fails**. Aqua passed all 11 +checks. JET analyzed all 2,067 core and 59 extension definitions with zero cached; +it reported 55 possible core errors and 11 extension errors, and all six concrete +leaf call checks failed. Representative vendor traces use nullable Objective-C +device/command-buffer properties in `is_virtual`, `MTLLogState`, `maybe_collect`, +`commit!` and `pointer`. Broad package analysis also reaches unported core array/ +backend assumptions and vendor graph/command alternatives. No reports were filtered +or suppressed. These failures remain tracked in +[#745](https://github.com/LupoLab/solprop/issues/745). + +The numeric foundation, vendor quality, complete device sessions and DF32 are +separate qualification statements. Only the bounded foundation tests above passed; +public Metal selection remains closed while the other requirements are unresolved. + +## Primary sources checked + +- [Metal Shading Language 4.1 specification](https://developer.apple.com/metal/Metal-Shading-Language-Specification.pdf): + §§1.6.5, 8.1, 8.2 and the explicit `fma` definition were read directly, including + the printed rounding/denormal and FMA pages. +- [Metal.jl v1.12.0](https://github.com/JuliaGPU/Metal.jl/tree/v1.12.0): + `src/state.jl`, `src/MetalKernels.jl`, `src/compiler/execution.jl`, `src/array.jl`, + `src/memory.jl` and `src/pool.jl` define task-local device/queue selection, compiler + options, private array spans, ownership and the scope of allocation counters. +- [Metal.jl FFT implementation](https://github.com/JuliaGPU/Metal.jl/blob/v1.12.0/src/fft.jl) + and [MPSGraph execution](https://github.com/JuliaGPU/Metal.jl/blob/v1.12.0/lib/mpsgraphs/execution.jl) + define raw normalization, graph keys, queue ordering and cache ownership. +- [Apple's Hermitian-to-real transform](https://developer.apple.com/documentation/metalperformanceshadersgraph/mpsgraph/hermiteantorealfft(_:axes:descriptor:name:)) + and [odd-output flag](https://developer.apple.com/documentation/metalperformanceshadersgraph/mpsgraphfftdescriptor/roundtooddhermitean) + specify the trailing-four-dimension restriction and default even output shape. +- [KernelAbstractions v0.10.5](https://github.com/JuliaGPU/KernelAbstractions.jl/tree/v0.10.5): + `src/backend_launch.jl` and `src/nditeration.jl` define the owned compiler-options + hook and the workgroup/domain type invariants used by the extension. diff --git a/julia/NODE_MEMORY.md b/julia/NODE_MEMORY.md new file mode 100644 index 000000000..f30359474 --- /dev/null +++ b/julia/NODE_MEMORY.md @@ -0,0 +1,179 @@ +# Node workspace planning + +The Julia node planner budgets retained numerical array data whose capacity grows +with `node_chunk` or the attached transverse `trace_chunk`. The budget is an +execution choice, outside scientific and restart identities. An explicit chunk +wins over any budget and is capped to the physical node count. Otherwise the +shared route default or explicit byte budget admits a limit, then the same number +of passes is balanced with `ceil(nodes / ceil(nodes / limit))`. A budget smaller +than one node's complete listed storage refuses before Julia starts. + +This is not an RSS, total-session or FFTW-native-allocation bound. Fixed and +full-volume numerical work are reported separately. Immutable prepared tables, +method/state/history/input-noise/export storage, object and view headers, chunk +descriptor containers, allocator overhead, FFTW plan internals and temporary +planning copies are outside the node budget. FFTW plans remain named opaque +exclusions; neither `Base.summarysize(plan)` nor a column-equivalent multiplier +proves their native allocation size. No empirical multiplier is promoted to a bound. + +The fixed/full-volume inventory covers source and observation numerical scratch, +the packed plane values and quadrature diagnostic. Bounded transport rows and +scalar notice/continuation records are excluded: their capacity is a separate +session transport choice. The inventory does not claim to enumerate a complete +session. An attached monitor is charged regardless of its current quiet state, +and its optional fresh-noise/resume readings receive their maximum retained size. + +## Counting the source + +Let `T` be fine time samples, `N` coarse time samples, `F` coarse spectral bins, +and `Q` fine spectral bins +(`T/2+1` for fields, `T` for envelopes), `M` retained spectral columns, `X` physical +nodes and `K` the selected chunk. Let `r`, `c`, `i` and `b` be the real, complex, +index and status element widths. Binary64 uses 8, 16, 8 and 1 bytes; binary32 +uses 4, 8, 8 and 1. Host physical readings and coefficient work retain width `h=8` +(and `2*h` for complex coefficients). Let `s=r` for fields and `s=c` for envelopes. +Counts below are array payload +sizes; a repeated reference or view does not create another data array. + +- Modal/radial source nodes and polarisation cost `2*T*s*K`. The failure vector + costs `i*max(K,M)`, bounded by a separate `i*M` full-volume contribution plus + `i*K`. Coarse projection adds only full-volume work. +- Cartesian/line source nodes and polarisation cost `2*T*s*K`; its fine spectrum + and coarse gathered spectrum add `(Q+F)*c*K`. Its failure vector is `i*X`. +- A field source using analytic Kerr or any non-THG Raman component adds `T*c*K` + for modal/radial and `3*T*c*K` for Cartesian/line. The modal analytic synthesis + and spectrum are full-volume arrays, whereas their Cartesian counterparts are + chunk arrays. +- Any number of Raman components share one doubled real drive and one spectral + work array: `(2*T*r+(T+1)*c)*K`. Each component separately retains its doubled + time kernel, spectrum and two per-resonance vectors; those are fixed arrays. +- Field plasma adds `(7*r+b)*T*K` for rates, exposure, fraction, survival, + integrand, current, FIR work and status. Envelope plasma adds + `(4*r+c+b)*T*K`. Both add two source columns `2*T*s*K`. Cartesian/line also + holds two projected columns of that same chunk size; modal/radial projected + and optional coarse-projected columns are full-volume. Channels reuse these + workspaces; only the small channel-parameter array grows with channel count. + +These counts follow `ModalSource`, `CartesianSource`, `RadialSource`, +`_source_analytic`, `_source_raman` and `_source_plasma`. Temporal FFT wrappers +retain plans and scalar sizes, not a second owned numerical buffer pair. + +Let `C` be one when the source has a distinct embedded coarse projection and zero +otherwise. The modal base has full-volume payload +`(3+C)*T*M*s + Q*M*c + (1+2*C)*F*M*c + i*M`: modal samples and projections, +fine spectrum, prefactor/optional quadrature spectra, and the conservative fixed +portion of the failure vector. A radial source additionally holds `F*M*c+i*M` +for independent loss work. A Cartesian source has `F*X*c+i*X` for its band and +failures. Every source holds two padding maps, `i*(F+Q)` bytes. An expanded modal +prefactor adds one host binary64 vector of the represented expansion's term count. + +Analytic modal work adds `2*T*M*c` outside the chunk. Each Raman component retains +its host kernel, host spectrum and profile work, `(2*T+2*n_terms)*h+(T+1)*2*h`. +Binary64 aliases the convolution spectrum to its host spectrum; binary32 adds +an independent `(T+1)*c` narrowed spectrum. Plasma adds two complex spectral +factor vectors in state precision and two host binary64 parameters per channel; +modal/radial plasma also adds +`(2+2*C)*T*M*s` in projected columns. These allocations occur once per source, +not once per pass or physical node. + +## Observations and transverse services + +Population statistics recompute populations in independently owned scratch. Modal +and radial observations add `T*s*K`; Cartesian/line adds +`(T*s+(Q+F)*c)*K`. If a population channel exists, add `(5*r+b)*T*K` for the +population-only recurrence. Species densities and complete node-by-species +fraction/peak arrays are fixed/full-volume; their size does not decrease with +chunking. Analytic observations, spatial width/axis reconstruction and temporal +monitor/split buffers are also fixed or full-volume. + +All observation workspaces retain a coarse spectrum, `F*M*c`, a statistics power +matrix, `N*M*r`, two per-column reduction vectors, `2*M*r`, and a total-power +vector, `N*r`. Three complete per-node real vectors are present for spatial +observations and for modal population statistics. Selected packed statistic +values and the plane copy cost `2*width*h`; the quadrature alarm adds `5*M*r`. +Binary32 additionally retains `i*M` column exponents and `i*X` node exponents +where node statistics are present. These are independent owned arrays, not scalars. + +Modal observations always retain `F*M*r` power weights and, for an expanded +weight, one host binary64 term vector. Analytic samples plus spectra, both ordinary +and +power weighted, cost `4*N*M*c`; each requested window repeats that pair. The +coarse on-axis peak uses two complex matrices with at most two physical components, +bounded by `4*N*c` even though the propagated modal polarisation is scalar. +Population species densities cost `n_species*h`, and fractions/peaks cost +`2*X*n_species*r`. +Their fine modal reconstruction costs `(Q*c+T*s)*M`; the Cartesian version uses +the already-counted chunk spectra and a full `F*X*c` spatial band. Each owns its +two padding maps independently of the source. + +The four resolved-modal on-axis population rows own another independent fine +reconstruction: `(Q*c+T*s)*M`, at most `2*T*s` component samples, one `T*s` scalar +column, five `T*r` recurrence columns, `T` status bytes, one `n_species*h` density +vector and two `n_species*r` result vectors, +and `i*(F+Q)` padding indices. This storage is independent of the node chunk. +The original axis map and represented species profiles are immutable preparation; +FFT plans retain the stated opaque-storage exclusion. Envelope collinearity can +reduce the component allocation, but the planner conservatively charges both rows. + +Spatial observations retain `F*M*r` weights only for spectral statistics and +`F*M*c` closure values only when physical or axis reconstruction is requested. +A material-index vector costs `F*2*h` when present; it is host coefficient work. +Physical spectra/closures cost +`2*F*X*c`, plus `F*X*c` for the Cartesian band; analytic intensity adds +`4*N*X*c`. The axis pair costs `2*F*c`, plus `4*N*c` for axis intensity. The +radial-average scratch is bounded by `X*r`: its half-pixel lattice covers the +smaller physical axis, so it cannot exceed that axis's sample count or the total +number of physical nodes. Prepared width-grid angles and weights are immutable +preparation, outside this workspace inventory. + +A temporal monitor holds `F*M*c+N*M*s+N*r` plus two host binary64 occupancy +vectors of the complete shared split-rate bucket count, including empty buckets. +An attached split collar holds `N*h+N*M*s+F*M*c`; binary32 adds its `N*r` damping +corrections, evaluated from the wide rate/step with `expm1` before one narrowing. +The Cartesian split adds its independent `F*M*c` band. + +Selected field-plasma diagnostics retain `6*K*r+6*h`. Binary32 adds `3*K*i` +exponents; its physical aggregate maxima remain binary64. + +Every transverse line owns one complex twice-padded strip spectrum and, when an +onset stencil exists, three complex current rows. Its contribution is +`c*(2*strip_length+3*has_onset)*min(K,n_traces)`, conservatively bounded by the +same coefficient times `K`. Sum this over every line, since all workspaces coexist. +The spatial band, previous/noise column readings and complete node vector remain +full-volume. Optional resumed or noise data must not reduce the prepared bound. + +The transverse fixed/full-volume bound is `F*X*c+X*r+5*M*h+7*n_lines*h`. +The five per-column vectors conservatively cover previous/noise state, the live +reading, an optional noise reading and optional clean columns. Each global +reading has two strip columns per line; each line also owns a one-column, +one-line reading, adding three real elements. Plans and their work are not +multiplied by a guessed FFT allocation factor. + +## Qualification + +The focused planner suite has 23 pure tests and 38 managed-runtime cases. Each +managed case constructs actual independent Julia sessions at chunks one and +three, reads the public retained-owner ledger and closes them without advancing. +It checks both the positive payload increment against `2*per_node_bytes` and +each complete listed workspace payload against the fixed/full-volume sum plus +the selected chunk contribution. Chunk-descriptor arrays are explicitly removed +from the numerical payload: their shrinking count must not hide a missing growing +numerical buffer. FFT plan estimates are excluded independently by ledger name. + +The 24 material cases span field/envelope, modal/radial/Cartesian/line, and Kerr, +two separately labelled Raman components, or Kerr/Raman/plasma together. The +mixed cases attach independent population statistics; coarse analytic or spatial +intensity/width/axis statistics and the quadrature alarm are also present. The +12 transverse cases cover all three spatial geometries and both formulations, +with or without a collar. Resolved collars have nonempty padded FFT strips and +onset current work, plus optional input-noise and clean readings. Two additional +modal cases combine window and on-axis statistics, a distinct +embedded coarse projection, temporal monitoring and split damping. The window +views retain their shared data owner, so the public ledger counts each physical +array once rather than counting an aliased reshape again. + +The existing managed checks qualify retained CPU binary64 array payloads. Pure +binary32 checks distinguish narrow arrays from host coefficient/readout storage and +integer scaling metadata. Complete binary32 retained-owner comparisons await the +observation reconstruction attachment; the planner alone does not admit public +binary32 execution. These checks neither measure RSS nor qualify vendor plans. diff --git a/julia/OBSERVATION_PRECISION.md b/julia/OBSERVATION_PRECISION.md new file mode 100644 index 000000000..311545806 --- /dev/null +++ b/julia/OBSERVATION_PRECISION.md @@ -0,0 +1,245 @@ +# Observation arithmetic and physical scaling + +The binary32 observation path follows SEP 33's separation of stored numerical work +from physical host results. State and reconstruction arrays, per-time power, per-node +fluence and reduction work use binary32. Coordinates, represented host coefficient +evaluation, final packed statistics and monitor/control/continuation records use +binary64. A physical field is a stored field multiplied by its explicit power of two; +that scale is never formed inside a state-sized product or square. + +This document specifies the reduction primitives. Integration of each observation and +monitor family is qualified separately; the primitives do not establish FFT accuracy, +model accuracy, device compatibility or complete binary32 session support. + +## Protected sum and its admission + +`_Float32Sum()` is an immutable pair of binary32 numbers. `_float32_add(sum, value)` +uses the protected error-free `TwoSum` already used by DF32, followed by an ordinary +binary32 correction sum. `_float32_value(sum)` rounds the sum and its correction. +There is no reassociation, contraction or flush to zero in this computation. + +This is Sum2s, Algorithm 4.1 of Ogita, Rump and Oishi, *Accurate Sum and Dot Product*, +SIAM Journal on Scientific Computing 26(6), 1955–1988 (2005), +[doi:10.1137/030601818](https://doi.org/10.1137/030601818). The authors' primary +[paper](https://www.tuhh.de/ti3/paper/rump/OgRuOi05.pdf), Proposition 4.5, gives + +\[ + |\widehat s-s|\le u|s|+\gamma_{n-1}^{\,2}\sum_i |x_i|, + \qquad \gamma_k=\frac{ku}{1-ku},\quad u=2^{-24}, +\] + +for the exact sum of the supplied binary32 terms, provided `n*u < 1` and all +intermediates are finite. Its addition analysis includes gradual underflow. This is +not a bound for unrounded products supplied to the sum: product, coefficient, +normalization and transform errors must be included separately. + +`_float32_sum_count(n)` enforces `0 <= n < 2^24` before numerical work. A matrix-wide +bucket or strip reduction counts the whole pass, including entries filtered by a +bucket/bin predicate, so the admission does not depend on field values. Column and +node passes use their actual lengths. Boundary tests exercise `2^24-1` and `2^24` +without allocating giant arrays. No hierarchical reduction is currently implied. + +The accumulator is an isbits value usable by the shared synchronous launcher. A +caller merging rounded partial sums must propagate their individual errors as well +as the final merge error; it cannot apply the exact-input theorem only to the merge. +Final small host merges can use binary64 with a separately accounted host bound. + +## Normalization before products + +For a real or complex buffer, let `m` be the maximum magnitude of any real or imaginary +component. When `m > 0`, choose `e` from `frexp(m)` so `m*2^-e` lies in `[1/2,1)`. +An all-zero buffer uses `e=0`. Component maxima avoid overflowing the modulus of a +finite complex value. The normalized components lie in `[-1,1]`; squaring and paired +Hermitian products therefore do not overflow at finite input extremes. + +Weighted products use the actual participating factors to choose a scale. Independent +whole-buffer maxima are insufficient: a tiny sample paired with a large coefficient +can dominate the physical result even when that sample disappears after an unrelated +normalization. For a term with `k` nonzero real factors, write each represented input +exactly as `x_j = m_j * 2^e_j` using `frexp`, with `1/2 <= |m_j| < 1`. Round a wide +mantissa once to binary32, multiply the binary32 mantissas, and align the product to + +\[ + E=\max_i \sum_{j=1}^{k_i} e_{ij}, +\] + +where the maximum includes only nonzero products in this reduction. Zero products +cannot select the scale. The implementation admits at most eight factors per scalar +product. All mantissa intermediates are therefore normal, even when the original +factors are subnormal or their unscaled product would overflow. Only the final +power-of-two alignment can underflow. No binary64 sample product is formed. + +For binary64 inputs, at most `k` mantissa conversions and `k-1` products contribute +rounding, so before alignment + +\[ + |\widehat p-p| \le \gamma_{2k-1}|p|. +\] + +A binary32 input's mantissa conversion is exact and reduces this count. With gradual +underflow, alignment adds at most `eta/2`, where `eta=2^-149`, in the chosen normalized +units. Each Hermitian pair adds its real and imaginary products once; include that +addition's error and both absolute products before applying the Sum2s bound. The +largest nonzero normalized product has magnitude at least `2^-8` before rounding, +so this absolute-underflow allowance cannot hide loss of a dominant positive term. +Signed cancellation still requires an absolute-product bound; no uniform relative +accuracy near a zero signed sum is claimed. + +Spectral numerator and denominator, population mixtures and inventories, temporal +pairs, and each final monitor region use their own actual-product exponents. Monitor +region, split and transverse weighted sums start from original samples or spectra; +they do not amplify a previously normalized scratch value. A per-column or per-node +partial carries its own exponent until all amplifying factors have been applied. +Zero partials do not choose a later merge scale. Merges include both the partial's +prior error and the protected merge error. + +Spatial fluence retains one exponent per node and a separate common scale for the +absolute-magnitude error diagnostic. Moment reductions combine each node exponent +with its actual quadrature/coordinate products. Only the final unweighted profile +used for a half-height crossing or angular interpolation aligns nodes to a common +peak scale. At that point the normalized peak lies in `[1/2,1]`; alignment loses at +most `eta/2` per ordinate, and interpolation uses nonnegative weights summing to one. +There is no later large physical weight to amplify that loss. Its width effect must +still be divided by the bracket's crossing slope, as described below. This treatment +does not add a normal-range refusal for a weak spatial node. + +`_observation_restore` and `_observation_restore_ratio` combine binary64 mantissas and +integer exponents at the final host result boundary. They do not first form `2^e`, +a potentially overflowing product of physical coefficients, or its reciprocal. +Nonfinite inputs and unrepresentable finite-range results raise named errors before +publication; exact zero remains exact zero. Gradual underflow in the final binary64 +physical result is retained. + +## Homogeneity and conditioning + +Field amplitudes have degree one in the physical field scale. Power, energy, +intensity, fluence, raw spectral occupancy and split removed energy have degree two. +Widths, centroids, normalized occupancies and population fractions have degree zero; +their physical units come from the coordinate/profile/rate inputs. An on-axis map +converts stored state to stored physical field, so state and field exponents are not +interchangeable. Plasma evaluates rates using the physical nodal field exponent. + +A width is not uniformly well conditioned. Its discrete interpolation error includes +both ordinate/peak errors and division by the local crossing slope. Qualification +uses fixtures with an explicit nonzero slope or an independent conditioned interval; +an operation count alone does not bound a nearly flat half-maximum crossing. Existing +undefined-width NaNs remain catalogue results. They do not excuse nonfinite fields. + +FFT and synthesis error models are hypotheses of each composed test. Neither Sum2s +nor a count of floating-point operations proves the accuracy of generated twiddle +factors. Tests against an independently evaluated DFT or tighter numerical reference +remain required for the actual transform and route under qualification. + +## Numerical families and owned scratch + +The standalone statistics and monitor leaves now use these rules for binary32. +This does not open public session admission or qualify device execution. + +- `StatisticsWorkspace` retains binary32 per-time power, total power, per-column + energy/moment, per-node total/fluence/magnitude and radial-average buffers. One + Int exponent per column and per node, plus small scalar family exponents, accompany + them. The node metadata adds exactly `sizeof(Int)*n_nodes` retained array bytes. +- Spectral column reductions normalize actual weighted products; centroid numerator + and denominator have independent exponents. Per-bin spectral flux gives each bin + its own exponent. Temporal pairs preserve signed Hermitian products. Species + inventories scale actual node-weight/fraction products before multiplication. + Density, potential and physical transverse measure enter only at the final host + result boundary. Default identity admission is conservative when a weight exponent + is nonzero; explicit identity metadata must come from the original wide values. +- Transverse node energies, temporal power and strip/current products remain + binary32. Their final reading arrays, occupancy vectors and control scalars stay + binary64, with the same physical thresholds and continuation representation. +- `PlasmaDiagnosticWorkspace` owns six binary32 parts per active-node capacity and + three Int exponents per node. Its six global maxima are host binary64. Raw + exposure is normalized by its column envelope before differencing. If the exact + normalized increment is `d`, endpoint alignment and the subtraction give an + absolute error at most `u*abs(d) + (3/2+u)*eta`; taking each dip/rise maximum does + not amplify that absolute error. A tiny dip beside a large envelope may disappear + within this bound; per-extremum relative preservation is not claimed. The resulting + ratio also retains its denominator conditioning. Paid-work defect and fraction/field + integrands have separate actual-product scales. Inactive rates and zero fractions + cannot determine them. + The freed-fraction denominator remains unscaled and cannot disappear when the paid + work is large. All chunks and channels share one field scale, which + cancels from the boundary-level ratio. The paid-work sum uses `n_time-1` terms. +- `NormalizedObservationWeight` retains the immutable original binary64 direct + table/expansion for varying weights, or an independently owned normalized binary32 + constant. `ObservationWeightWorkspace` retains only one binary64 coefficient per + expansion term and scalar range/identity facts. Each varying element is evaluated + in binary64, normalized and rounded once; correlated cancellation is not moved + into binary32 Clenshaw arithmetic. Exact identity classification precedes narrowing. + +## Base scales and derived normalization metadata + +The base state and nodal-field powers remain in `[-1074,1023]`, exactly as in +`SourceArithmetic`; this admission is unchanged. A reconstructed closure or transverse +strip/stencil may instead carry a *derived* integer exponent. For example, a base +field exponent `100` and a normalized admittance exponent `1000` give closure exponent +`1100`. The latter is never materialized as `2^1100`. Two stored components `2^-100` +then give finite physical paired flux `2^1000` when the other field exponent is `100`. +Refusing the derived exponent as though it were a base scale would reject this finite +expression before its factorized restoration. + +Derived closure/strip/stencil exponents have magnitude at most `4*1074`. The four +blocks cover one base field scale, up to two finite binary64 preparation factors, +and the component normalization of the stored binary32 field. This is a bound on +integer metadata, not a new range promise for a materialized field or coefficient. +Preparation must account for each constituent explicitly. Each finite nonzero +binary64 factor has a `frexp` exponent with magnitude at most `1074`; binary32 has +the smaller bound `149`. All-zero products keep the existing sentinel and never +add it to another exponent. + +The integer audit uses `B=1074` and the actual fixed-depth paths below. The generic +product helper admits at most eight factors; its exponent sum therefore has magnitude +at most `8B`. A finite reduced value contributes at most another `B` when decomposed +at the final host boundary. Counting that value directly also covers any increase +from a protected sum; no unbounded running exponent accumulator exists. + +- Spatial paired results combine at most `B+4B` physical scale, `8B` product scale, + then `B+B` for the reduced value and final factor: at most `15B`. +- Strip energy combines at most `2B` sample-product scale and `2*(4B)` amplitude + metadata, then `B+2B+B` for the value, two factors and one divisor: at most `14B`. +- Rectified onset current combines at most `2B` sample-product scale and `2*(4B)` + amplitude metadata, then `B+B+2B` for the value, one factor and two divisors: + at most `14B`. +- Spatial width intermediates combine the three-factor node partial with a finite + partial and at most three coordinate/quadrature factors: at most `7B`. Differences + of these exponents give at most `14B`; final restoration remains below `16B`. + +The other spectral, population and temporal paths retain their original base-scale +admission. Their actual-product sums and fixed-depth partial merges remain below the +conservative common bound `32B=34368`, as do the rows above. Multiplication by two, +addition, subtraction, negation and the radial exponent split therefore cannot wrap +even a signed 32-bit `Int`. The widened checks run before any use of supplied metadata; +`typemin(Int)`, `typemax(Int)` and values just outside the derived range are refused +before output mutation. This reasoning applies to these bounded call graphs, not to +arbitrary repeated calls of the internal exponent helpers with unchecked integers. + +Final physical underflow is gradual. `_observation_restore` and its ratio counterpart +combine mantissas before one final `ldexp`; nonfinite or overflowing physical results +still raise before publication. Tests cover finite closure exponent `1100`, finite +strip/current restoration with the same exponent, unchanged base-scale refusal, +integer-boundary rejection, final physical overflow and zero warmed allocations. + +The binary64 branches retain their existing arithmetic order and array element +types. The new optional metadata is absent on those paths. Composition into modal, +spatial and transverse observation workspaces is a separate qualification milestone. + +## Wide-coefficient conversion is a separate error source + +The reduction contract starts from the supplied represented binary32 numerical +arrays. `source_narrow` retains the oracle's direct-fold admission. SEP 33 section 4.3 +bounds the block's well-scaled entries (within `2^-126` of its largest entry); it does +not promise uniform relative accuracy for every subnormal tail. A positive normalized +power weight may remain subnormal after its one wide-to-binary32 rounding. Its error +is an additive `eta/2` in normalized weight units, and must be multiplied by the +actual squared field or other participating factors in the composed error budget. + +For example, normalizing wide weights `(1, 3*eta/4)` rounds the second to `eta`. +A field supported only on that second entry can have a small rounding error relative +to the represented-weight reduction and a substantial relative difference from the +original wide-weight expression. The committed witness asserts these two bounds +separately. Product-aware reduction prevents additional avoidable loss; it cannot +recover information already discarded by the required coefficient conversion. +Existing preparation admission is preserved, and no uniform relative guarantee for +such original tiny weights is inferred. diff --git a/julia/OBSERVATION_RECONSTRUCTION.md b/julia/OBSERVATION_RECONSTRUCTION.md new file mode 100644 index 000000000..3ae01a553 --- /dev/null +++ b/julia/OBSERVATION_RECONSTRUCTION.md @@ -0,0 +1,144 @@ +# Precision and physical observation reconstruction + +This layer reconstructs the supplied observed field without reading mutable source +scratch or advancing propagation work. Its admitted scalar modal, radial, Cartesian +and line routes use the same prepared `SourceArithmetic` as their source. It does not +open public binary32 admission or qualify GPU execution. The reduction contract and +its error model are in [OBSERVATION_PRECISION.md](OBSERVATION_PRECISION.md). + +## State, field and coefficient powers + +Let the stored canonical spectrum be `s=a*2^-es`, where `es` is the state exponent. +If the immutable physical synthesis is `B`, preparation stores one rounded matrix +`Bs=round_T(B*2^(es-ef))`. Its output represents electric field divided by `2^ef`. +The same fold applies to each independent coarse/fine on-axis matrix. Radial coarse +synthesis first removes the already translated temporal padding factor; it never +reuses the fine population map as the coarse observation map. Cartesian and line +inverse transforms use their existing normalized raw DFT and one prepared scalar +state-to-field fold. Original binary64 matrices remain immutable and reachable for +provenance, later preparation and the storage ledger. + +Constant modal power weights are normalized and converted once at preparation; +their normalized binary32 array and range fact are retained. Varying weights retain +their original binary64 table or expansion. Each varying element is evaluated at +the observed coordinate in binary64, normalized, and rounded once. If its normalized +weight has exponent `ew`, a weighted temporal +pair and its spectral energy restore `2^(2es+ew)` only into their host result. +This does not move represented polynomial evaluation into binary32. + +Spatial flux follows the existing translated admittance, including the represented +low words and active-band branch. Evaluate `Y=c*sqrt(q)/omega` in host binary64 for +each coefficient at the actual observation coordinate. Normalize its complex +coefficient by a common exponent `ey`, then form the closure in binary32: + +\[ + C_s=\operatorname{round}_{32}(\overline{Y}\,2^{-e_y})s. +\] + +After the same spatial synthesis, electric and closure arrays represent physical +values divided by `2^ef` and `2^(ef+ey)`. Their signed Hermitian products restore +`2^(2ef+ey)`. Spectral power coefficients include their separately translated measure +and intensity factor, have their own normalization exponent, and use `2^(2es+ew)`. +There is no full-volume mutable binary64 admittance, closure or weight array. A +varying material retains only the existing one-complex-coefficient-per-frequency +host row. The finite derived exponent `ef+ey` need not itself be materializable as a +binary64 power; the bounded metadata/restoration proof is in the reduction document. + +Wide coefficient evaluation uses the existing binary64 operation order and finite +coefficient admission. Conversion error, including subnormal coefficient tails, is +separate from the subsequent represented-array reduction error. This implementation +does not promise uniform relative error for an original tiny coefficient. The +binary64 reconstruction branches retain their existing arithmetic graph. + +This coefficient-tail limitation can dominate a physical result. For example, an +unused admittance of `1` sets the global normalization, while an occupied bin has +admittance `1e-50` and stored amplitude `2^100`. The latter coefficient rounds to +zero. With an eight-sample transform and Parseval weight `1/8`, its wide-coefficient +energy is about `2.01e9`, while the represented-coefficient energy is zero. The +initial conversion's absolute `eta32/2` error, where `eta32=2^-149`, propagates to +`(eta32/2)*2^200/8`, about `1.41e14`; it covers that discrepancy but supplies no useful +relative accuracy. The reproducible test checks this separate conversion budget and +the exact represented zero. It does not enlarge the later product/reduction budget, +change physical admission, or claim that such ill-conditioned coefficient/field +combinations are accurately resolved in binary32. + +## Populations and monitors + +Fresh field/envelope populations use the independent fine temporal grid and map. +The rate helpers receive `field_exponent=ef`, so lookup sees the physical nodal field +without materializing an overflowing binary32 physical array. Fractions and per-node +peak rates remain binary32; species densities, physical measures, profiles and final +packed inventory are host binary64. Passive species retain exact zero columns. The +fine on-axis field route reconstructs both admitted real components; envelope rows +must satisfy the existing exact proportionality admission before scalar collapse. +No current-only coefficient enters population evaluation. + +Temporal monitors reconstruct the canonical coarse field and use `es`. Transverse +monitors reconstruct physical nodes using `ef`, but their canonical-column occupancy +uses `es`. Their physical reading, threshold, continuation and decision records stay +binary64. No implementation normalization exponent enters portable continuation. + +For a strip or onset stencil, determine the normalization exponent from each actual +nonzero component product of field, sample scale and (for a strip) window. Only then +form the binary32 sample buffer. This avoids losing a weak sample before an amplifying +weight. Each strip chunk uses the existing twice-padded raw forward DFT. All inactive +traces/padding are overwritten, and the complete derived amplitude exponent is passed +to the protected strip/current reduction. Small host chunk merges include prior +reduction error and their own binary64 rounding. Input noise remains binary64-only; +all existing binary64 noise/floor paths remain intact. + +## Storage ownership + +Let `r=sizeof(T)`, `c=2r`, `i=sizeof(Int)`, `F` be coarse frequencies, `N` coarse time, +`Q` fine frequencies, `U` fine time, `M` state columns, `X` physical nodes, `K` the +active node capacity, `S` complete species, `W` windows and `A` axis components. +These are retained numerical array data, not RSS or a bound on opaque FFT plans. + +- Common statistics scratch is `(N*M+N+2M+3X+R)*r`, where `R` is the prepared radial + average capacity. Binary32 adds `(M+X)*i` column/node exponents. Packed values and + scalar host decisions remain binary64. +- Modal coarse spectrum and power weight use `F*M*(c+r)`. An analytic pair has + `4NMc` bytes; window pairs have `4NMWc`; on-axis analytic input/output use `2NAc`. +- Modal/radial fine populations retain `(Q*c+U*s)*M` modal storage and `U*s*K` nodal + samples, where `s=r` for a field and `s=c` for an envelope. Population recurrence + uses `(5r+1)*U*K`; fractions/peaks use `2X*S*r`, and densities use `8S`. +- Fine on-axis populations retain `(Q*c+U*s)*M`, `U*(A+1)*s`, one-node recurrence, + `2S*r` fractions/peaks and `8S` densities. Diagnostic work adds `6K*r+3K*i` and + six binary64 aggregate maxima. Its dimensionless exposure ratios are unchanged. +- Spatial coarse spectrum uses `F*M*c`, optional normalized weights `F*M*r`, and + optional closure `F*M*c`. Physical electric/closure pairs use `2F*X*c`, plus + `F*X*c` Cartesian band storage when needed. Their analytic pair adds `4N*X*c`. + Axis pairs use `2F*c` and, when selected, `4N*c` analytic work. +- Cartesian/line fine populations retain a full `F*X*c` band plus chunk-dependent + `(Q+F)*K*c+U*K*s` and the same recurrence/species/diagnostic storage above. +- A temporal monitor retains `F*M*c+N*M*s+N*r`, plus two binary64 bucket reading + vectors. A transverse monitor retains its `F*X*c` band, `X*r` node scratch and + the existing small binary64 column/readout vectors. Each resolved line retains + `c*(2*n_strip+3*n_onset)*min(trace_chunk,n_traces)` bytes, with `n_onset` zero or one. + +Original and narrowed binary32 map/axis coefficient arrays are both owned; the +binary64 path aliases its original and executable copies. Immutable geometry, +profiles and wide coefficient vectors are also retained and discoverable through +preparation. `SourceRange`, arithmetic and line normalization facts are fixed scalar +records. Reshape views keep their original owner, so they add no duplicate array data. +All these owners remain discoverable to the shared ledger; no global mutable workspace +or borrowed observed field is retained. + +## Qualification model + +The tests use independent high-precision DFT sums, analytic quadratic ionisation and +explicit physical reference expressions. Transform comparisons assume the separately +qualified finite FFT/twiddle error model; an operation count alone cannot prove the +library's twiddle generation. The stated budgets combine field/coefficient rounding, +absolute pre-cancellation envelopes, products, protected reductions and final host +restoration. Width fixtures propagate ordinate and centroid errors through an +explicitly bounded crossing slope; dimensionless results are checked at non-unit +state and field scales. These are bounded numerical witnesses, not a claim of uniform +accuracy at arbitrary ill-conditioned zero flux or flat half-height crossings. + +Bounds-enabled tests also exercise reused/poisoned scratch, passive species, periodic +selection, noise refusal, exponent and arithmetic mismatch, retained input ownership, +complete inactive writes, both CPU task widths and zero warmed allocations. Package +Aqua/JET and concrete reconstructed calls are required before integration. Session +construction, method services, Python transport and public admission remain separate +integration gates. diff --git a/julia/PHASE_ADMISSION.md b/julia/PHASE_ADMISSION.md new file mode 100644 index 000000000..80a09f3f9 --- /dev/null +++ b/julia/PHASE_ADMISSION.md @@ -0,0 +1,238 @@ +# Represented phase operands before DF32 admission + +`solprop.backends.julia._phase_bounds` supplies conservative preparation-time operand +analysis. It does **not** admit DF32, choose a wide arithmetic implementation, initialize +Julia, or certify a propagator error. The current production operator assembly remains +binary64. A finite result from this analyzer is not permission to narrow that assembly. + +This distinction follows [SEP 48](../docs/dev/seps/sep-0048-julia-backend.md) and the +[protected-function derivation](DF32_BOUNDS.md). The latter proves conditional scalar +function bounds for already-prepared arguments. It does not prove the rounding error +of coordinates, represented coefficients, cumulative subtraction, expansion contraction, +or transported Adams compensation. + +## Inputs, ownership and output + +`phase_spans(run, start, history=...)` reads an already-resolved `RunTransfer` and the +actual accepted anchor. `operator_envelope(operator, spans)` reads a constant generator, +a full cumulative Chebyshev representation, or fixed complex terms with real cumulative +weights. `phase_operands(...)` combines those results and records missing proof inputs. +All positions and distances are metres; generator and sampled-rate bounds are inverse +metres; exponents and cumulative operator bounds are dimensionless. + +The records contain independent absolute real/imaginary bounds over **every computed +cell**, including inactive bins. They retain maximum polynomial degree and term count, +full represented values and derivatives, represented jumps, endpoint differences, and +uncancelled endpoint/expansion contributions. They deliberately contain no `approved` +field. An unavailable transported-argument bound is `None` with an explicit reason. + +The caller must prevent mutation during analysis. These immutable scalar summaries do +not retain, hash or freeze their input arrays. Any future certificate must bind the +actual prepared arrays, precision/scaling choices, history and arithmetic graph to its +result. Reusing a summary after changing those inputs is unsupported. + +An optional snapshot means **the already-compatible history that will be restored**. +The analyzer requires the shared history key, actual accepted anchor, valid current +order/rejection metadata, positive proposal, strictly increasing oldest-first actual +sample coordinates, unique in-range slots and accepted/predicted sample kinds. It uses +the shared newest-sample proximity rule without snapping a sample to the accepted +anchor. Full source stores have shape `(order_max+2, 1, n_modes, n_pol, n_omega)`; +compensated histories also require paired full state/rate stores of that shape. All +rows, including inactive slots, must be finite. Unknown row names refuse. State and +operator cell counts must agree. It reads the actual selected stored rates rather +than replacing them with derivatives of the current representation. + +These checks supplement, rather than replace, the shared schema and restore policy. +Precision compatibility, scaling, source identity, history-key construction, caller +choice of field-only restart, cumulative ledgers, controller compatibility and input +noise remain outside this analyzer. No history is silently discarded. Binary32 states +and binary64 stored rates can be analyzed without claiming that this combination is +admitted. Noise is never applied by the analyzer. + +## Actual march geometry + +Let `c = max(1, max(abs(tableau.nodes)))`. The current embedded RK graph only flows +between a step's anchor and each stage, and between that anchor and its endpoint; it +does not flow directly between arbitrary pairs of stages. Thus `c*h` bounds its exact +stage distances. No fixed stage count or restriction of nodes to `[0,1]` is assumed. +The four forward flows of the low-storage method fit the same conservative bound. + +For replay, the analyzer uses the **remaining supplied lengths**, not `dz_max`. It +checks authoritative accumulated edges under the shared replay allowance, locates the +actual resumed anchor, and bounds each binary64 multiply-then-add stage coordinate +using exact rational products and sums followed by directed rounding. Both the raw +`z+h` and the recorded destination are retained in the coordinate envelope. A resumed +anchor within the shared allowance is used as supplied for its first step. A replay +that does not cover the start/end or crosses the requested end refuses. +The returned `landing_slack` is enlarged by the exact distance of each stage-coordinate +enclosure from `z+c*h`, not merely the shared edge tolerance. This keeps large-node +product/addition rounding in the `c*h+2s` distance bound as well as the coordinate span +([#675](https://github.com/LupoLab/solprop/issues/675)). It does not enlarge the tolerance +used to admit a replay anchor or itinerary. + +For adaptive execution, the shared landing rule caps even a stretched step by +`dz_max`. A forced landing may be arbitrarily shorter than `dz_min`, so no positive +actual minimum step is asserted. The analyzer bounds endpoint arithmetic using + +\[ + |\operatorname{RN}_{64}(x)-x|\le u_{64}|x|+\eta_{64},\qquad + u_{64}=2^{-53},\quad\eta_{64}=2^{-1075}. +\] + +For a start `a` and end `b`, subtraction contributes at most +`e_gap = u64*(b-a)+eta64`. A raw endpoint is bounded above by +`b+e_gap+u64*abs(b+e_gap)+eta64`. For nodes outside `[0,1]`, the separate product and +sum errors are added to the exact extrema over anchors in `[a,b]` and steps no larger +than the ceiling. Nodes inside `[0,1]` are bounded by monotonicity between the anchor +and the raw endpoint. All these computations are rational before their outward +binary64 conversion. Overflow of a required finite bound refuses. + +Let `s` include the shared landing/replay allowance, `A=max_j(abs(z_j-start))` be the +actual retained coordinate radius, and `q` the configured maximum Adams order. A conservative +history distance is + +\[ + H=\min\{z_{\max}-z_{\min},\;A+(q+1)(c h_{\max}+2s)\}. +\] + +For a method without retained Adams history, use one step instead of `q+1`. The +complete coordinate envelope includes old sample coordinates and endpoint rounding; +it may extend beyond the requested run. It must remain inside each table's explicitly +admitted span, including that table's own outer-edge allowance. The `q+1` factor covers +the retained extra oldest sample and subsequent accepted samples before it is retired. +Rejections do not advance this history. Hard-kink resets can only shorten its age. +The initial radius includes a newest sample slightly after the accepted anchor, as +permitted by shared restore. An age-only bound would miss that positive offset when +future replay steps are much smaller than the restore proximity allowance. + +When replay supplies a positive `h_min`, the exact normalized-history multiplier obeys + +\[ + |1-(z_j-z)/h|\le 1+H/h_{\min}. +\] + +This is also sufficient for dense transport `|theta-(z_j-z)/h|`, `0<=theta<=1`. +The rounding error of forming that multiplier is a separate obligation. Adaptive +execution reports no multiplier bound because its actual `h_min` is unknown. + +## Complete represented intervals + +For one component on interval `[a_i,b_i]`, write + +\[ + P_i(z)=\sum_{k=0}^{d}p_{ik}T_k(x),\qquad + x=(2z-a_i-b_i)/(b_i-a_i). +\] + +The exact represented polynomial is the target here, not a rounded Clenshaw result. +For the part of this interval that can be read, set `X=max(1, max(abs(x)))`, including +any permitted outer-edge extrapolation. The identities +`T_k(cos(theta))=cos(k*theta)`, the corresponding second-kind representation, and +`T'_k=k U_(k-1)` give + +\[ + |P_i|\le \sum_k |p_{ik}|T_k(X),\qquad + |P'_i|\le\sum_{k\ge1}|p_{ik}|\frac{2kU_{k-1}(X)}{b_i-a_i}. +\] + +For `|x|<=1`, the factors are `1` and `2*k*k/(b_i-a_i)`. For `X>=1`, the hyperbolic +representations make the positive factors monotone. The analyzer evaluates their +three-term recurrences with exact rational arithmetic, then rounds upward. These +bounds cover interior extrema; endpoint sampling would miss, for example, `1-T_2`. +The identities and recurrences were checked against NIST DLMF +[equations 18.5.1–2](https://dlmf.nist.gov/18.5#i), +[Table 18.9.1](https://dlmf.nist.gov/18.9#T1), and +[equation 18.9.21](https://dlmf.nist.gov/18.9.E21). + +At a represented boundary the two polynomial limits need not coincide exactly. +For each cell/component, compute the actual coefficient-defined jump + +\[ + J_i=\left|\sum_k p_{ik}-\sum_k(-1)^k p_{i+1,k}\right| +\] + +using exact rational cancellation, and let `J` sum all jumps in the required span. +If `V` and `R` are the maximum value and derivative bounds across that span, any two +represented endpoints separated by at most `H` satisfy + +\[ + |P(z_1)-P(z_0)|\le \min(2V,\;H R+J). +\] + +This is the piecewise fundamental theorem of calculus plus all possible intervening +jumps. Both limits of a boundary are included. Physical continuity does not justify +setting `J=0`; exact represented continuity does. The arithmetic subtraction still +has operands bounded by `2V`, even when `H R+J` is very small. For a stored constant +generator `D`, there are no cumulative operands: the exact target is `(z1-z0)*D`. + +For an expansion `Phi(z)=sum_r T_r*w_r(z)` with real weights, apply the table bounds +to every `w_r` before combining. For each real/imaginary component, the value, rate, +jump and difference bounds are sums of `abs(component(T_r))` times the respective +weight bounds. The uncancelled assembly operand is +`sum_r abs(component(T_r)) * 2*V_r`, even when terms cancel in the final phase. +The retained coefficient magnitude is that of the fixed terms; the future conversion +proof must also inspect the original scalar weight coefficients. No complex-weight +extension is implied. + +## Outward calculation versus assembly error + +Scalar geometry, jumps and Chebyshev growth factors are exact rational calculations +on the supplied binary values before directed binary64 conversion. Positive array +sums/products use round-to-nearest binary64 followed by one `nextafter(...,+Inf)` +after **each** operation. This encloses the exact positive result, including a product +that rounds to zero under gradual underflow. Exact structural zero products/sums +remain zero. Maxima and minima of already-valid bounds preserve validity. Nonfinite +bounds refuse; no warning, infinity sentinel or FTZ policy substitutes for a bound. + +These are bounds on exact represented operands. They are not estimates of how +accurately a future DF32 kernel evaluates them. In particular, cumulative Clenshaw +needs an intermediate-register bound, coordinate-map and coefficient-conversion +errors, explicit FMA/contraction choices, an underflow allowance and endpoint +subtraction error. Expansion assembly additionally needs term conversion and the +specified contraction order. A small net phase supplies none of those proofs. + +## Transported compensation and remaining certificate inputs + +The implemented Adams numerical formula uses + +\[ + L=\Phi(z+h)-\Phi(z),\quad t_j=(z_j-z)/h,\quad + e^{(1-t_j)L},\quad D_{\rm ref}=L/h,\quad + D_j-D_{\rm ref}. +\] + +It does **not** generally replace `(1-t_j)*L` by `Phi(z+h)-Phi(z_j)` for a varying +operator. A history-distance-times-derivative envelope therefore cannot certify this +arithmetic graph. A represented jump contributes `J/h`; cumulative evaluation error +also becomes `error(L)/h`. Either can grow without bound as a landing step shrinks. +The returned transported argument is the step-argument bound multiplied by the known +replay multiplier, or `None` for adaptive compensation. Constant operators and a +structurally absent source do not use compensated history. Stored selected rates +are reported independently so a later proof cannot silently substitute a new value. + +Before enabling a DF32 route, a separate assembly certificate must establish: + +1. The immutable input/scaling identity and exact graph for every exponent, derivative, + normalized node, dense fraction and compensation operation. The existing binary64 + graph is context, not the promised wide graph. +2. Every intermediate range, supported conversion and gradual-underflow term for that + graph. A constant-distance multiplication may need a different proof from a pair + of cumulative Clenshaw evaluations and a difference of scalar weights. +3. Absolute argument error propagated through all operations, including cancellation, + represented jumps, actual replay lengths, old retained samples and stored-rate + provenance. For arbitrary short adaptive landings, a stable difference/integral + graph or a justified additional condition is necessary; `dz_min` is insufficient. +4. The protected functions' actual domains with margin for the propagated error. + The currently proved leaf requirements are `abs(Re)<=16`, `abs(Im)<=2^20`, and a + separate argument error no larger than `u/8`, `u=2^-24`, under the hypotheses in + [DF32_BOUNDS.md](DF32_BOUNDS.md). These are downstream requirements, not a pass + condition implemented by this analyzer. Phi orders and joining branches need the + same complete assembled-argument proof. +5. The selected device's rounding, explicit FMA/division and gradual-underflow behavior, + plus emitted-code checks. CPU evidence does not qualify Metal, CUDA or ROCm. + +The targeted tests use independent exact defining-polynomial recurrences, rational +endpoint/jump and directed-rounding witnesses, cancellation-heavy expansions, actual +replay schedules, resumed sample coordinates and malformed full stores. They test +these operand inequalities and refusals. They do not assert a whole-expression error +budget or public single-precision propagation qualification. diff --git a/julia/PLASMA_CYCLE_PRECISION.md b/julia/PLASMA_CYCLE_PRECISION.md new file mode 100644 index 000000000..8c6afeb79 --- /dev/null +++ b/julia/PLASMA_CYCLE_PRECISION.md @@ -0,0 +1,229 @@ +# Reduced logarithmic plasma coordinates + +This note records the binary32 numerical correction for [issue +#738](https://github.com/LupoLab/solprop/issues/738). It supplements +[SOURCE_PRECISION.md](SOURCE_PRECISION.md), whose physical scaling, clipping, +population and current contracts remain in force. Binary64 keeps its original +arithmetic graph. Neither the physical spline coefficients nor the cycle rules, +`moment_rtol`, negligible-rate floor or failure policy change. + +## Target and cancellation + +Let `a` be the positive stored binary32 field magnitude and `ef` its exact physical +power, so `E = a 2^ef`. A supplied spline interval `j` uses + +\[ + r_j=\log(a)+e_f\log2-L_0-jh,\qquad + P_j(r)=c_{3j}r^3+c_{2j}r^2+c_{1j}r+c_{0j}. +\] + +Here `L0` and `h > 0` are the original binary64 translated metadata, and the +coefficients are already narrowed binary32 inputs. The represented rate is +`exp(Pj(rj))`, subject to the unchanged physical cutoff and ceiling. Conversion +error of the coefficients is a separate input to a physical-model comparison. + +Computing `log(a)` and the shifted origin as single words before subtracting them +loses a small local offset through cancellation. In the reported argon case the +absolute logarithm is about 13; one binary32 logarithm ulp is then much larger +than the local-coordinate error allowed by the steep spline. Positive panel sums +can therefore fail the unchanged `2e-6` refinement test even though the same +represented spline and rules evaluated in binary64 converge. Increasing the +quadrature order does not repair that local arithmetic error. + +## Arithmetic graph and retained storage + +Preparation chooses integer `b = exponent(field_min)` by `frexp` of the finite +binary64 lower clipping field. Set `l = RN64(log(2))` and prepare normalized +two-word splits of `l`, `h`, and `fma(-b,l,L0)`. The private scalar record retains +these three `DF32` pairs and integer `ef-b`. Existing array records and public +constructors are unchanged. There is no additional retained array or mutable +binary64 field buffer. The existing six rate parameters remain available; the +binary32 path appends this scalar record. + +For each live field, exact `frexp` and, when necessary, one exact multiplication +by two give `a=m 2^e`, with `m` near `[sqrt(1/2),sqrt(2)]`. The implemented switch +is the represented binary32 `sqrt(1/2)`, so those endpoints have its rounding +allowance. Both `m` and one lie within a factor of two: `m-1` is exact by Sterbenz. +The kernel calls the existing binary32 `log1p(m-1)` and evaluates + +\[ + C=\operatorname{DWAdd}(\log1p(m-1), + \operatorname{DWMul}(e+e_f-b,l))-\operatorname{DW}(L_0-bl), + \qquad R_j=C-\operatorname{DWMul}(j,h). +\] + +All products/additions here are the reviewed explicit-FMA algorithms in +`double_float.jl`; this change implements no logarithm approximation. The exponent +sum is a small exactly representable integer under the existing finite field-scale +admission. Knot integers are split rather than silently rounded once. The kernel +then uses `Rj.hi` in the original three-FMA binary32 cubic and binary32 `exp`. + +Interval selection keeps both words of `C/h`. A power-of-two scaling first puts +the denominator high word in `[8,16)` and renormalizes both pairs. This uses the +restricted reciprocal proof already derived in [DF32_BOUNDS.md §1.2](DF32_BOUNDS.md), +instead of extending the unlimited-exponent division theorem to an arbitrary tiny +spacing. The integer floor uses the high-word integral part and the remaining +fraction plus low word separately; rounding a two-word quotient to one word before +flooring would lose the side of an integer boundary. The selected interval is +clamped to the existing endpoint intervals. + +## Hypotheses and coordinate allowance + +The arithmetic model is round-to-nearest ties-to-even binary32, correctly rounded +basic operations/FMA, gradual underflow and finite intermediates. Put +`u=2^-24`, `eta=2^-150`, and `A=3u²/(1-4u)`. Metal's distinct subnormal/rounding +rules are not qualified by these CPU witnesses. The host preparation checks +finite splits both before and after renormalization; a last-word tie at overflow +must not escape as an infinite pair. + +For a finite binary64 scalar `v` split by high word and rounded residual, the +absolute representation error is at most `u² abs(v)+eta`, including a tiny +residual that disappears. This source-local preparation deliberately permits that +gradual underflow; it does not weaken the separate `prepare_df32` API. The host +constant and reduced-origin errors are separate. For example, with exact `ln2`, + +\[ + E_l\le |\widehat l-\ln2|+u^2|\widehat l|+\eta, + \quad + E_o\le |b|\,|\widehat l-\ln2| + +u_{64}|L_0-b\widehat l|+\eta_{64} + +u^2|\operatorname{fma}(-b,\widehat l,L_0)|+\eta. +\] + +No independence of those correlated errors is assumed. An exact MPFR comparison +of these prepared inputs may replace the conservative right sides. It is input +representation error, not a fitted rate tolerance. + +For the local elementary function the finite CPU qualification checks + +\[ + |\widehat{\log1p(m-1)}-\ln m|\le2u|\ln m|+\eta. +\] + +This is an explicit elementary-function hypothesis, tested against MPFR at the +qualified inputs; disabling fast math is not a proof that every vendor meets it. +The [pinned Julia implementation][julia-log] accepts and returns Float32 but its +CPU `log1p` helpers use binary64 internally; the existing population `expm1` +primitive does too. [Issue #751](https://github.com/LupoLab/solprop/issues/751) +records direct-callee LLVM evidence. The accepted source-precision boundary is the +Float32 elementary API and its separately qualified returned-value error, together +with binary32 response arrays and owned arithmetic. This fix adds no explicit +binary64 numerical fallback or binary64 response buffer. Its caller LLVM check +stops at those elementary APIs and must not be described as transitive evidence +that every CPU instruction is binary32. The strict all-binary32 graph still holds +for the protected two-word arithmetic helpers. The improvement comes from local +reduction and retained low words, not a new logarithm approximation. + +A vendor specialization must compile without a host/Float64 fallback and satisfy +its own elementary-function and finite-range hypotheses before admission. The +CPU library implementation proves neither a device's arithmetic width nor its +accuracy. This explicit primitive boundary changes no physics, default or budget. + +The following recurrences specify the assembly bound completely. If `xhat` and +`yhat` are exact sums of the computed pairs with errors `Ex`, `Ey` relative to +their targets, use + +\[ + \begin{aligned} + E_{+}&=E_x+E_y+A|\widehat x+\widehat y|,\\ + E_{\times}&=|\widehat x|E_y+|\widehat y|E_x+E_xE_y + +7u^2|\widehat x\widehat y|+5\eta. + \end{aligned} +\] + +Apply these in the displayed graph order, starting with the metadata and local-log +errors above. The integer index split contributes its exact representation error +if its value is too large for two words. The final high-word selection adds +`u abs(Rj)+eta`. The addition and product bounds, including the additive underflow +term, are the reviewed derivations in DF32_BOUNDS §1; normal input words alone do +not establish the intermediate-range hypotheses. + +Interval selection has its own conditioning. Exact binary scaling can lose at +most `2eta` per pair, before exact renormalization. For scaled pair values `x,y`, +the restricted division adds + +\[ + 16u^2|x/y|+(6|x|(1+1/|y|)+6)\eta. +\] + +Input errors add `(Ex+abs(x/y)Ey)/(abs(y)-Ey)` when `Ey