solprop.calibration.refine#

Stage 2: refine the workspace settings for one simulation (SEP 46 section 6.6).

The machine profile fits the native backend to the machine; refine() then fits it to one costly simulation, returning a RefinementReport. It times the operation-grain moves of the simulation’s own work sizes (solprop.calibration.grain) by trial steps of fresh workspaces at POSITIONS positions along its length (_Windows), in ROUNDS interleaved rounds, never touching the simulation’s state, output or callbacks; a candidate’s steps must agree with the base’s to within 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).

Module Attributes

ROUNDS

Interleaved rounds per comparison, as at the standard level.

POSITIONS

Trial-step windows along the simulation's length: its start, a third and two.

ACCURACY

How many times the run's relative tolerance a candidate's fields may differ by.

Functions

refine(simulation[, budget, progress])

Refine the native workspace settings for simulation (SEP 46 stage 2).

Classes

RefinementReport(status, descriptor[, ...])

What a refinement measured and kept.

solprop.calibration.refine.ACCURACY = 10.0#

How many times the run’s relative tolerance a candidate’s fields may differ by.

solprop.calibration.refine.POSITIONS = 3#

Trial-step windows along the simulation’s length: its start, a third and two.

solprop.calibration.refine.ROUNDS = 5#

Interleaved rounds per comparison, as at the standard level.

class solprop.calibration.refine.RefinementReport(status, descriptor, changes=<factory>, evidence=<factory>, reason='', seconds=0.0, path=None)[source]#

Bases: object

What a refinement measured and kept.

Attributes:
statusstr

"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).

descriptorstr

The simulation’s execution descriptor.

changesMapping[str, object]

The workspace settings stored over the process’s record.

evidenceMapping[str, object]

The noise, each candidate’s verdict and accuracy, and the validation.

reasonstr

Why.

secondsfloat

The wall time taken.

pathpathlib.Path or None

The refinement file, if one was stored.

changes: Mapping[str, object]#
describe()[source]#

Return the report as lines for a terminal.

Returns:
str

The status, reason, changes and file.

descriptor: str#
evidence: Mapping[str, object]#
path: Path | None = None#
reason: str = ''#
seconds: float = 0.0#
status: Literal['published', 'kept', 'inconclusive']#
solprop.calibration.refine.refine(simulation, budget=60.0, *, progress=None)[source]#

Refine the native workspace settings for simulation (SEP 46 stage 2).

Parameters:
simulationsolprop.driver.Simulation

The simulation; it is translated if it is not already, and otherwise left alone.

budgetfloat, optional

The deadline, in seconds.

progresscallable 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.