Calibration

cubie.batchsolving.calibration.run_calibration(parent: Any, initial_values: Any, parameters: Any, drivers: Any | None = None, duration: float = 1.0, settling_time: float = 0.0, t0: float = 0.0, grid_type: str = 'verbatim', apply: bool = True, verbose: bool = True, auto_size: bool = True, waves: int = 5, target_ms: float = 20.0, max_parallel: int = 4, fix_constant_parameters: bool = True) → CalibrationResult[source]

Race solver configurations for a solver and pick the fastest.

Parameters:

  • parent – The configured Solver whose system, tolerances, and output configuration every candidate shares.

  • initial_values – Initial state values for each integration run, as accepted by Solver.solve().

  • parameters – Parameter values for each run, as accepted by Solver.solve().

  • drivers – DriverSamples replacing the solver’s configured samples.

  • duration – Total integration time candidates are ranked on.

  • settling_time – Warm-up period before recording outputs.

  • t0 – Initial integration time.

  • grid_type – Strategy for constructing the integration grid from inputs. Only used when dict inputs trigger grid construction.

  • apply – Apply the winner’s configuration to parent when True.

  • verbose – Print per-candidate progress lines.

  • auto_size – Race a batch sized for target_ms solves at duration; False races the given batch.

  • waves – Waves of the most concurrent candidate the batch starts at.

  • target_ms – Kernel milliseconds per timed solve the batch is sized for.

  • max_parallel – Maximum compilations to run in parallel.

  • fix_constant_parameters – Compile in every dict entry and every row of a full-height parameter array that holds one value, as Solver.solve() does.

Returns:

Winner, ranking, and every candidate measurement. A candidate that fails to build or integrate is reported as dropped with its error message.

Return type:

CalibrationResult

Raises:

ValueError – No driver samples for a driven system; waves under 1; target_ms under 10 or not finite.

class cubie.batchsolving.calibration.CalibrationResult(candidates: List[CandidateResult], winner: CandidateResult | None, ranking: List[CandidateResult], features: Dict[str, Any], applied_settings: Dict[str, Any])[source]

Bases: object

Complete calibration report.

Parameters:

  • candidates (List[cubie.batchsolving.calibration.CandidateResult]) – Every candidate measurement from every stage, in run order.

  • winner (cubie.batchsolving.calibration.CandidateResult | None) – Fastest candidate of the top success tier, or None when no candidate was timed.

  • ranking (List[cubie.batchsolving.calibration.CandidateResult]) – Every timed configuration: the top success tier by time, then the rest by time.

  • features (Dict[str, Any]) – System description (sizes, precision, tolerances, …) accompanying the measurements.

  • applied_settings (Dict[str, Any]) – Settings applied to the calling solver, empty when nothing was applied.

applied_settings: Dict[str, Any]
candidates: List[CandidateResult]
features: Dict[str, Any]
ranking: List[CandidateResult]
summary() → str[source]

Return a formatted table of every candidate measurement.

to_records() → List[Dict[str, Any]][source]

Return flat per-candidate dictionaries for tabular export.

winner: CandidateResult | None
class cubie.batchsolving.calibration.CandidateResult(spec: CandidateSpec, stage: str, times_ms: Tuple[float, ...] = (), failures: int = 0, runs: int = 0, dropped: bool = False, reason: str = '')[source]

Bases: object

Measured outcome for one candidate.

Parameters:

  • spec (cubie.batchsolving.calibration.CandidateSpec) – The candidate configuration measured.

  • stage (str) – Name of the race stage the measurement belongs to.

  • times_ms (Tuple[float, ...]) – Kernel milliseconds of every timed solve.

  • failures (int) – Runs with a nonzero status code.

  • runs (int) – Trajectory count each solve integrated.

  • dropped (bool) – Whether the candidate could not be timed.

  • reason (str) – Why the candidate was dropped, empty otherwise.

property best_ms: float

Lowest measured solve time, inf when never timed.

dropped: bool
property failure_fraction: float

Failed runs as a fraction of the trajectory count.

failures: int
reason: str
runs: int
spec: CandidateSpec
stage: str
property success_rate: float

Share of the batch that integrated without a status flag.

property timed: bool

Whether the candidate has a time.

times_ms: Tuple[float, ...]
class cubie.batchsolving.calibration.CandidateSpec(label: str, family: str, algorithm: str, settings: Tuple[Tuple[str, Any], ...] = ())[source]

Bases: object

One candidate configuration in the calibration race.

Parameters:

  • label (str) – Human-readable identifier shown in reports.

  • family (str) – Algorithm family key ("erk", "dirk", "firk", or "rosenbrock").

  • algorithm (str) – Tableau alias passed to the solver as algorithm.

  • settings (Tuple[Tuple[str, Any], ...]) – (name, value) pairs of solver keyword overrides.

algorithm: str
family: str
property key: Tuple[str, Tuple[Tuple[str, Any], ...]]

Identity of the configuration, independent of its label.

label: str
settings: Tuple[Tuple[str, Any], ...]
property settings_dict: Dict[str, Any]

Settings pairs as a keyword-argument dictionary.

property solver_settings: Dict[str, Any]

The algorithm and settings as one Solver.update dict.