# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""Stage 2: refine the workspace settings for one simulation (SEP 46 section 6.6).
The machine profile fits the native backend to the machine; :func:`refine` then fits it
to one costly simulation, returning a :class:`RefinementReport`. It times the
operation-grain moves of the simulation's own work sizes
(:mod:`solprop.calibration.grain`) by trial steps of fresh workspaces at
:data:`POSITIONS` positions along its length (``_Windows``), in :data:`ROUNDS`
interleaved rounds, never touching the simulation's state, output or callbacks; a
candidate's steps must agree with the base's to within :data:`ACCURACY` times the
run's relative tolerance. The result is stored under the simulation's execution
descriptor and applied by every later run with an equal one. The manual page is
``docs/guide/performance/calibration.md`` ("Refining one simulation"); the design is
``docs/dev/backends.md`` (section 3.4a).
"""
from __future__ import annotations
import dataclasses
import math
import random
import time
from collections.abc import Callable, Mapping
from dataclasses import dataclass, field
from pathlib import Path
from typing import TYPE_CHECKING, Literal, cast
import numpy as np
from solprop.backends.session import Start
from solprop.calibration import _native, grain, selection
from solprop.exceptions import CalibrationError
if TYPE_CHECKING:
from solprop.driver import Simulation
__all__ = ["ACCURACY", "POSITIONS", "ROUNDS", "RefinementReport", "refine"]
ROUNDS = 5
"""Interleaved rounds per comparison, as at the standard level."""
POSITIONS = 3
"""Trial-step windows along the simulation's length: its start, a third and two."""
ACCURACY = 10.0
"""How many times the run's relative tolerance a candidate's fields may differ by."""
[docs]
@dataclass(frozen=True)
class RefinementReport:
"""What a refinement measured and kept.
Attributes
----------
status : str
``"published"`` (a refinement was stored), ``"kept"`` (the machine profile
stays: no candidate won and was accurate), or ``"inconclusive"`` (too noisy,
too little time, or no machine profile to refine).
descriptor : str
The simulation's execution descriptor.
changes : Mapping[str, object]
The workspace settings stored over the process's record.
evidence : Mapping[str, object]
The noise, each candidate's verdict and accuracy, and the validation.
reason : str
Why.
seconds : float
The wall time taken.
path : pathlib.Path or None
The refinement file, if one was stored.
"""
status: Literal["published", "kept", "inconclusive"]
descriptor: str
changes: Mapping[str, object] = field(default_factory=dict[str, object])
evidence: Mapping[str, object] = field(default_factory=dict[str, object])
reason: str = ""
seconds: float = 0.0
path: Path | None = None
[docs]
def describe(self) -> str:
"""Return the report as lines for a terminal.
Returns
-------
str
The status, reason, changes and file.
"""
lines = [
f"refinement: {self.status} in {self.seconds:.1f} s ({self.descriptor})",
f" {self.reason}",
]
lines += [f" {name}: {value}" for name, value in self.changes.items()]
if self.path is not None:
lines.append(f" refinement: {self.path}")
return "\n".join(lines) + "\n"
class _Windows:
"""One record's backend on the simulation, and its trial steps along it.
- ``record``: a native execution record, or ``None`` for the process's own.
"""
def __init__(
self, simulation: Simulation, record: Mapping[str, int | bool] | None
) -> None:
from solprop_native._execution import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports]
ExecutionRecord,
)
from solprop_native.backend import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports]
NativeBackend,
)
problem = simulation.translate()
stepper = simulation.run_request().stepper
self.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),
# The run's own node chunk, so the windows time what the run executes.
options=simulation.settings.execution_options(),
)
self.probe = self.backend.timing_probe(Start.entrance(problem))
start = float(problem.initial.z)
end = float(max(stepper.save_planes, default=start))
self.dz = float(stepper.dz_init)
self.positions = (
[start]
if stepper.schedule is not None
else [
start + (end - start) * index / POSITIONS for index in range(POSITIONS)
]
)
self.low_storage = stepper.schedule is not None
def fields(self) -> list[np.ndarray]:
"""Return the field each window's trial step ends in, on the host.
A low-storage march advances its state with each step, so it has no fields
to compare and returns none.
"""
found: list[np.ndarray] = []
for z in self.positions:
if self.low_storage:
return []
self.probe.trial(z, self.dz)
found.append(self.probe.field())
return found
def time(self, repeats: int) -> float:
"""Return the seconds per trial step over the windows, after a warm-up."""
steps: list[Callable[[], object]] = (
[self.probe.trial]
if self.low_storage
else [(lambda z=z: self.probe.trial(z, self.dz)) for z in self.positions]
)
for step in steps:
step()
step()
begun = time.perf_counter()
for step in steps:
for _ in range(repeats):
step()
return (time.perf_counter() - begun) / (repeats * len(steps))
def close(self) -> None:
"""Close the backend."""
self.backend.close()
def _accurate(
found: list[np.ndarray], reference: list[np.ndarray], rtol: float
) -> bool:
"""Return whether `found` is finite and close to `reference`, window by window.
Close is within ``ACCURACY * rtol`` in the relative L2 norm.
"""
for mine, theirs in zip(found, reference, strict=True):
if not np.all(np.isfinite(mine)):
return False
scale = float(np.linalg.norm(theirs)) or 1.0
if float(np.linalg.norm(mine - theirs)) > ACCURACY * rtol * scale:
return False
return True
[docs]
def refine(
simulation: Simulation,
budget: float = 60.0,
*,
progress: Callable[[str], object] | None = None,
) -> RefinementReport:
"""Refine the native workspace settings for `simulation` (SEP 46 stage 2).
Parameters
----------
simulation : solprop.driver.Simulation
The simulation; it is translated if it is not already, and otherwise left
alone.
budget : float, optional
The deadline, in seconds.
progress : callable or None, optional
Called with a line of text as each stage starts.
Returns
-------
RefinementReport
What was kept and whether it was stored.
Raises
------
CalibrationError
For a budget that is not positive, or a simulation not on the native backend.
"""
started = time.monotonic()
report = _refine(simulation, budget, progress)
return dataclasses.replace(report, seconds=time.monotonic() - started)
def _candidates(
problem: object,
sizing: Mapping[str, object],
base: Mapping[str, int | bool],
threads: int,
) -> list[grain.Candidate]:
"""Return the grain candidates that change this simulation's widths.
- ``problem``: the translated problem, for its shape.
- ``sizing``: its workspace's ``execution_sizing`` under the base record.
"""
shape = cast(tuple[int, ...], getattr(problem, "shape")) # noqa: B009 - typed loosely
operations = grain.operations(sizing)
compact = ["simulation"] if math.prod(shape[:-1]) == 1 else []
return [
candidate
for candidate in grain.proposals(
base, {"simulation": operations}, threads, compact, limit=12
)
if candidate.setting == "compact"
or grain.affected(candidate.record(base), base, operations, threads)
]
def _rounds(
base: _Windows, windows: Mapping[str, _Windows], repeats: int, until: float
) -> dict[str, list[float | None]]:
"""Time interleaved rounds of every candidate's windows against the base's.
- Returns: ``again``, the base's A/A ratio, and each candidate's ratio to the base,
per round.
"""
generator = random.Random(5000)
ratios: dict[str, list[float | None]] = {"again": []}
ratios |= {name: [] for name in windows}
for _ in range(ROUNDS):
if time.monotonic() > until:
break
slots = [("base", base), ("again", base), *windows.items()]
generator.shuffle(slots)
seconds = {name: window.time(repeats) for name, window in slots}
for name in ratios:
ratios[name].append(seconds[name] / seconds["base"])
return ratios
def _together(
combined: _Windows, base: _Windows, repeats: int, noise: float
) -> selection.Validation:
"""Validate the admitted settings together against the base on fresh rounds."""
ratios: list[float | None] = []
for index in range(ROUNDS):
pair = [("combined", combined), ("base", base)]
if index % 2:
pair.reverse()
timed = {name: window.time(repeats) for name, window in pair}
ratios.append(timed["combined"] / timed["base"])
return selection.validate(
{"simulation": (ratios, [1.0] * len(ratios))}, noise, ROUNDS
)
def _refine(
simulation: Simulation,
budget: float,
progress: Callable[[str], object] | None,
) -> RefinementReport:
"""Carry out :func:`refine`; its report's seconds are set by the caller.
- ``budget``: the deadline, in seconds.
"""
if not budget > 0:
raise CalibrationError(f"a refinement's budget must be positive, got {budget}")
if simulation.settings.backend not in ("native", "auto"):
raise CalibrationError(
"a refinement fits the native backend; this simulation runs on "
f"{simulation.settings.backend!r}"
)
say = progress or (lambda _: None)
deadline = time.monotonic() + budget
import solprop_native as native # noqa: PLC0415 # pyright: ignore[reportMissingImports]
if native.PROFILE.fingerprint is None:
return RefinementReport(
"inconclusive", "", reason="SOLPROP_CALIBRATION=off: no profile to refine"
)
problem = simulation.translate()
rtol = float(simulation.run_request().stepper.controller.rtol)
base_record = cast(dict[str, int | bool], native.EXECUTION.native())
opened = [_Windows(simulation, None)]
base = opened[0]
try:
sizing = cast(dict[str, object], base.backend.metadata()["execution_sizing"])
key = native._profile.descriptor(
shape=problem.shape,
grid_kind=problem.grid_kind,
integrator=type(simulation.run_request().stepper.integrator).__name__,
sizing=sizing,
process=native.PROCESS,
fingerprint=native.PROFILE.fingerprint.digest,
)
candidates = _candidates(problem, sizing, base_record, native.PROCESS.threads)
evidence: dict[str, object] = {"candidates": [c.name for c in candidates]}
if not candidates:
return RefinementReport(
"kept", key, evidence=evidence, reason="no candidate changes a width"
)
say(f"building {len(candidates)} candidate workspaces")
windows = {
c.name: _Windows(simulation, c.record(base_record)) for c in candidates
}
opened += list(windows.values())
reference = base.fields()
accurate = {
name: _accurate(window.fields(), reference, rtol)
for name, window in windows.items()
}
repeats = max(2, min(500, round(0.1 / max(base.time(1), 1e-6))))
say("timing interleaved rounds")
ratios = _rounds(base, windows, repeats, deadline - 0.2 * budget)
ones = [1.0] * len(ratios["again"])
noise = selection.noise(ones, ratios["again"], ROUNDS)
if noise is None or noise > selection.NOISE_LIMIT:
return RefinementReport(
"inconclusive",
key,
evidence=evidence | {"noise": noise},
reason="too noisy or too little time to decide",
)
verdicts = {
name: selection.admit(ratios[name], ones, noise, ROUNDS) for name in windows
}
evidence |= {
"noise": noise,
"accurate": accurate,
"verdicts": {name: verdict.record() for name, verdict in verdicts.items()},
}
best = grain.best([c for c in candidates if accurate[c.name]], verdicts)
changes: dict[str, int | bool] = {}
for candidate in best:
changes |= candidate.changes
reason = "no accurate candidate won"
if best:
say(f"validating {len(best)} settings together")
combined = _Windows(simulation, {**base_record, **changes})
opened.append(combined)
validation = _together(combined, base, repeats, noise)
evidence["validation"] = validation.record()
reason = (
"the combination is inaccurate"
if not _accurate(combined.fields(), reference, rtol)
else "the combination's validation failed"
if not validation.passed
else ""
)
if reason:
return RefinementReport("kept", key, evidence=evidence, reason=reason)
store = _native.store.Store(_native.store.cache_directory())
path = store.publish_refinement(
native.PROFILE.fingerprint.digest,
key,
{
"created": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
"base": base_record,
"workspace": changes,
"evidence": evidence,
},
)
return RefinementReport(
"published",
key,
changes=changes,
evidence=evidence,
reason="admitted: " + ", ".join(candidate.name for candidate in best),
path=path,
)
finally:
for window in opened:
window.close()