Source code for solprop.calibration.child

# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later

"""A calibration child: one candidate's process settings, timed on request (SEP 46).

The controller starts one child per candidate process setting, with the setting in its
environment. :func:`main` (``python -m solprop.calibration.child CPUS``) pins the
process to its CPUs (:func:`pin`) before the native runtime starts, then :func:`serve`
answers JSON-line requests on standard input and output (``prepare``, ``time``,
``sizing``, ``capture``, ``regions``, ``exit``), one reply line each, through a
``_Session`` that holds the built problems and a backend per workspace record. A child
never calibrates and never reads a profile. The request protocol is in
``docs/dev/backends.md`` (section 3.4a).
"""

from __future__ import annotations

import io
import json
import os
import statistics
import sys
import time
import warnings
from collections.abc import Callable, Iterable, Mapping, Sequence
from typing import TYPE_CHECKING, Any, cast

if TYPE_CHECKING:
    from solprop_native._execution import (  # pyright: ignore[reportMissingImports]
        ExecutionRecord,
    )
    from solprop_native.backend import (  # pyright: ignore[reportMissingImports]
        NativeBackend,
    )

__all__ = ["main", "pin", "serve"]


[docs] def pin(cpus: Sequence[int]) -> None: """Pin this process to `cpus` before the native runtime starts. Linux sets its affinity mask; Windows its process affinity mask (CPUs of the first processor group); macOS has no affinity, and is left alone. Parameters ---------- cpus : sequence of int Logical CPUs; empty leaves the process as it is. """ if not cpus: return if hasattr(os, "sched_setaffinity"): os.sched_setaffinity(0, cpus) elif sys.platform == "win32": # pragma: no cover - Windows import ctypes # noqa: PLC0415 - Windows only mask = sum(1 << cpu for cpu in cpus if cpu < 64) # A private handle on the DLL, so that declaring the types touches no one # else's; a HANDLE and a DWORD_PTR are pointer wide. kernel = ctypes.WinDLL("kernel32") kernel.GetCurrentProcess.restype = ctypes.c_void_p kernel.SetProcessAffinityMask.argtypes = (ctypes.c_void_p, ctypes.c_size_t) kernel.SetProcessAffinityMask(kernel.GetCurrentProcess(), mask)
_PLANS_PER_PROBLEM = 4 """About how many transforms a calibration problem plans, for sharing a budget.""" _SHORTEST_LIMIT = 0.05 """The shortest per-plan time limit worth a problem's capture, in seconds.""" class _Session: """The child's problems, and the backends built for each record.""" def __init__(self) -> None: self.problems: dict[str, tuple[Any, Any]] = {} self.backends: dict[ tuple[str, str], tuple[NativeBackend, Callable[[], object]] ] = {} def backend( self, name: str, record: Mapping[str, object] | None, planning: Mapping[str, object] | None = None, ) -> Callable[[], object]: """Return the trial step of problem `name` under `record`, built once. - ``record``: a native execution record, or ``None`` for the process's own. - ``planning``: an FFT planning (``fft_planning``), or ``None`` for the plan policy. """ key = self._key(name, record, planning) if key not in self.backends: from solprop_native._execution import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] ExecutionRecord, ) from solprop_native.backend import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] NativeBackend, ) from solprop.backends.session import Start # noqa: PLC0415 simulation, problem = self.problems[name] execution: ExecutionRecord | None = ( None if record is None else ExecutionRecord.from_native(record) ) backend = NativeBackend( problem, simulation.run_request(), grid=simulation.grid, modes=simulation.modes, profiles=simulation.profiles, cpu_execution=execution, fft_planning=planning, options=simulation.settings.execution_options(), ) step = backend.timing_probe(Start.entrance(problem)).trial step() self.backends[key] = (backend, step) return self.backends[key][1] @staticmethod def _key( name: str, record: Mapping[str, object] | None, planning: Mapping[str, object] | None = None, ) -> tuple[str, str]: """Return the cache key of problem `name`'s backend under a setup. - Returns: the problem and its setup as JSON. """ return name, json.dumps([record, planning], sort_keys=True) def prepare(self, problems: Mapping[str, float]) -> dict[str, object]: """Build each problem at its scale and time one step of each. - Returns: each problem's fastest step and shape, the process settings in force, its CPUs, and its execution and built-in records. """ import solprop_native # noqa: PLC0415 # pyright: ignore[reportMissingImports] from solprop.calibration.problems import build # noqa: PLC0415 report: dict[str, object] = {} for name, scale in problems.items(): simulation = build(name, float(scale)) problem = simulation.translate() self.problems[name] = (simulation, problem) step = self.backend(name, None) # The fastest of a few steps: the first ones still fault pages in. seconds = [] for _ in range(3): begun = time.perf_counter() step() seconds.append(time.perf_counter() - begun) report[name] = {"step": min(seconds), "shape": list(problem.shape)} return { "problems": report, "process": solprop_native.PROCESS.record(), "cpus": sorted(os.sched_getaffinity(0)) if hasattr(os, "sched_getaffinity") else [], "execution": solprop_native.EXECUTION.native(), "builtin": solprop_native.BUILTIN_EXECUTION.native(), } def time( self, name: str, repeats: int, record: Mapping[str, object] | None, planning: Mapping[str, object] | None = None, ) -> float: """Return the seconds a trial step of `name` takes under `record`. Two untimed steps first bring the problem's arrays back into the caches, which another child's window has just used. - ``record``: a native execution record, or ``None`` for the process's own. - ``planning``: an FFT planning, or ``None`` for the plan policy. - Returns: seconds per step. """ step = self.backend(name, record, planning) for _ in range(2): step() begun = time.perf_counter() for _ in range(repeats): step() return (time.perf_counter() - begun) / repeats def capture( self, effort: str, limit: float, record: Mapping[str, object] | None, budget: float | None = None, ) -> dict[str, object]: """Plan every problem's transforms alone at `effort`; return their wisdom. Each transform is seeded from no wisdom, within `limit` seconds, and its wisdom kept by its plan key (SEP 46 section 6.7). The workspaces built are closed: only the wisdom is wanted. Within a `budget`, each problem's plans share what is left of it, at most `limit` each, and the problems it leaves no time for are skipped and listed. - ``effort``: the FFTW planning effort, ``"measure"``. - ``limit``: FFTW's planning time limit per transform, in seconds. - ``budget``: the seconds the whole capture may take; none bounds it but `limit`. - Returns: ``wisdom`` by plan key, each key's ``groups`` and the problems containing it (``problems``), the problems skipped for want of time (``skipped``), the seconds spent (``seconds``), and each plan's execution alone (``alone``: the seconds of the captured plan and of the same transform at estimate, ``_core.time_fft_plan``; solprop issue #595). """ from solprop_native import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] _core, # pyright: ignore[reportUnknownVariableType] ) from solprop_native._execution import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] ExecutionRecord, ) from solprop_native.backend import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] NativeBackend, ) wisdom: dict[str, str] = {} groups: dict[str, str] = {} contains: dict[str, list[str]] = {} skipped: list[str] = [] begun = time.perf_counter() names = list(self.problems) for index, name in enumerate(names): simulation, problem = self.problems[name] each = limit if budget is not None: left = budget - (time.perf_counter() - begun) # A problem plans a few transforms: share what is left among them. each = min(limit, left / (_PLANS_PER_PROBLEM * (len(names) - index))) if each < _SHORTEST_LIMIT: skipped.extend(names[index:]) break backend = NativeBackend( problem, simulation.run_request(), grid=simulation.grid, modes=simulation.modes, profiles=simulation.profiles, cpu_execution=None if record is None else ExecutionRecord.from_native(record), fft_planning={ "mode": "capture", "capture_effort": effort, "time_limit": each, }, options=simulation.settings.execution_options(), ) try: found = backend._diagnostics()["fft_planning"] finally: backend.close() wisdom |= cast(dict[str, str], found["captured"]) for key, group in cast(dict[str, str], found["groups"]).items(): groups[key] = group contains.setdefault(name, []).append(key) # Each plan alone, as its capture chose it and at estimate, to tell a plan that # loses in the step from one that is slower alone (issue #595). alone = { key: cast(dict[str, float], _core.time_fft_plan(key, text, effort)) for key, text in wisdom.items() } return { "wisdom": wisdom, "groups": groups, "problems": contains, "skipped": skipped, "seconds": time.perf_counter() - begun, "alone": alone, } def sizing(self, record: Mapping[str, object] | None) -> dict[str, object]: """Return each problem's operations as its workspace sizes them. - ``record``: a native execution record, or ``None`` for the process's own. - Returns: each problem's ``execution_sizing``: work and width by operation. """ found: dict[str, object] = {} for name in self.problems: self.backend(name, record) backend = self.backends[self._key(name, record)][0] found[name] = backend.metadata()["execution_sizing"] return found def close(self) -> None: """Close every backend.""" for backend, _ in self.backends.values(): backend.close() self.backends.clear() def _regions(elements: int, repeats: int) -> dict[str, float]: """Return the cost of a parallel region at the process's width, in seconds. The median of `repeats` timed scaled copies of `elements` complex values on the kernels' execution space (``reference_stream_copies``), and of single-element copies, whose cost is the region's own. - Returns: ``copy`` and ``empty``: the median seconds of each. """ from solprop_native import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] _core, ) copies = _core.reference_stream_copies(elements, 20, repeats) empty = _core.reference_stream_copies(1, 20, repeats) return {"copy": statistics.median(copies), "empty": statistics.median(empty)}
[docs] def serve(requests: Iterable[str], replies: io.TextIOBase) -> None: """Answer requests until ``exit`` or the end of input. Parameters ---------- requests : Iterable[str] JSON lines, one request each. replies : io.TextIOBase One JSON line written per request. """ session = _Session() try: for line in requests: if not line.strip(): continue request = json.loads(line) op = request.get("op") if op == "exit": replies.write(json.dumps({"ok": True}) + "\n") replies.flush() return try: if op == "prepare": answer: object = session.prepare(request["problems"]) elif op == "time": answer = session.time( request["problem"], int(request["repeats"]), request.get("record"), request.get("planning"), ) elif op == "capture": answer = session.capture( request["effort"], float(request["limit"]), request.get("record"), None if request.get("budget") is None else float(request["budget"]), ) elif op == "sizing": answer = session.sizing(request.get("record")) elif op == "regions": answer = _regions(int(request["elements"]), int(request["repeats"])) else: raise ValueError(f"unknown request {op!r}") reply: dict[str, object] = {"ok": answer} except Exception as error: reply = {"error": f"{type(error).__name__}: {error}"} replies.write(json.dumps(reply) + "\n") replies.flush() finally: session.close()
[docs] def main(argv: Sequence[str] | None = None) -> int: """Pin, then serve the controller on the process's standard streams. The protocol keeps a private copy of standard output; anything else the process or the native runtime prints goes to standard error. Parameters ---------- argv : sequence of str or None, optional ``[CPUS]``; the process's own arguments when ``None``. Returns ------- int Zero. """ arguments = list(sys.argv[1:] if argv is None else argv) cpus = [int(cpu) for cpu in arguments[0].split(",") if cpu] if arguments else [] pin(cpus) # The synthetic problems' own warnings (an absorber on a small ladder size, say) # concern nothing the user built. warnings.simplefilter("ignore") protocol = os.fdopen(os.dup(1), "w", encoding="utf-8") os.dup2(2, 1) sys.stdout = sys.stderr serve(sys.stdin, protocol) return 0
if __name__ == "__main__": # pragma: no cover - run as a module by the controller raise SystemExit(main())