Optimisation

cubie.batchsolving.optimize.run_optimization(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, force: bool = False, auto_size: bool = True, waves: int = 5, target_ms: float = 20.0, max_parallel: int = 4, compile_only: bool = False, fix_constant_parameters: bool = True) → OptimizeResult[source]

Time the solver’s candidate kernels on itself; apply the fastest.

Parameters:

  • parent – The configured Solver.

  • initial_values – Initial state values for each 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 – Integration time of the caller’s solves.

  • settling_time – Warm-up period before recording outputs.

  • t0 – Initial integration time.

  • grid_type – Grid strategy when dict inputs trigger grid construction.

  • apply – Apply the best launch’s settings to parent when True.

  • verbose – Print per-launch progress lines.

  • force – Vary the settings given explicitly or applied earlier too.

  • auto_size – True optimizes at an automatically selected batch size and duration to reduce runtime; False optimizes at your given batch size and duration.

  • waves – Waves of the launch with the most concurrent runs the auto_size batch starts at; the batch then moves to hit target_ms.

  • target_ms – Kernel milliseconds per timed solve auto_size aims for by raising the duration, never past yours, then the batch.

  • max_parallel – Maximum compilations to run in parallel.

  • compile_only – Compile the kernels but do not run them.

  • 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:

Best launch, every measurement, and the applied settings.

Return type:

OptimizeResult

Raises:

ValueError – waves under 1, or target_ms under 10 or not finite.

cubie.batchsolving.optimize.most_resident_runs(kernel: Any, blocksizes: Sequence[int] | None = None) → int[source]

Return the most runs resident at once over kernel’s launches.

cubie.batchsolving.optimize.launch_candidates(kernel: Any, blocksizes: Sequence[int] | None = None, runs: int | None = None) → Tuple[Tuple[int, int | None], ...][source]

Return the (blocksize, resident_blocks) launches worth timing.

Parameters:

  • kernel – A compiled BatchSolverKernel.

  • blocksizes – Block sizes to consider; None picks the measured set for shared-memory or local-only kernels.

  • runs – Runs in the timed launches; None sizes a full block.

Returns:

Launchable block sizes at the default residency, plus one and two blocks under natural occupancy for local frames.

Return type:

tuple

cubie.batchsolving.optimize.apply_launch(parent: Any, launch: LaunchResult) → Dict[str, Any][source]

Apply a launch’s settings, block size and residency to parent.

Returns:

The settings passed to parent.update.

Return type:

dict

class cubie.batchsolving.optimize.OptimizeResult(launches: List[LaunchResult], best: LaunchResult | None, applied_settings: Dict[str, Any], runs: int = 0, duration: float = 0.0)[source]

Bases: object

Complete optimisation report.

Parameters:

  • launches (List[cubie.batchsolving.optimize.LaunchResult]) – Every launch measured, in run order.

  • best (cubie.batchsolving.optimize.LaunchResult | None) – Fastest launch of the top success tier, or None when nothing was timed.

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

  • runs (int) – Trajectories each timed solve integrated.

  • duration (float) – Integration time each timed solve ran.

applied_settings: Dict[str, Any]
best: LaunchResult | None
duration: float
launches: List[LaunchResult]
property ranking: List[LaunchResult]

the top success tier by time, then the rest.

Type:

Every timed launch

runs: int
summary() → str[source]

Return a formatted table of every launch measurement.

class cubie.batchsolving.optimize.LaunchResult(settings: Dict[str, Any], blocksize: int | None, resident_blocks: int | None, blocks_per_sm: int = 0, times_ms: Tuple[float, ...] = (), failures: int = 0, runs: int = 0, waves: float = 0.0, error: str = '')[source]

Bases: object

Timings of one candidate at one launch.

Parameters:

  • settings (Dict[str, Any]) – The candidate’s unroll and placement settings.

  • blocksize (int | None) – Threads per block; None for a rejected candidate.

  • resident_blocks (int | None) – Blocks per SM held resident; None = the default residency.

  • blocks_per_sm (int) – Resident blocks per SM the driver reported.

  • times_ms (Tuple[float, ...]) – Timed solve times in milliseconds.

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

  • runs (int) – Trajectories each solve integrated.

  • waves (float) – Occupancy waves the batch filled at the launch.

  • error (str) – Why the launch could not be timed, empty when it was.

property best_ms: float

Lowest solve time, inf when never solved.

blocks_per_sm: int
blocksize: int | None
error: str
failures: int
classmethod from_timing(timing: CandidateTiming) → LaunchResult[source]

Build the launch record of one candidate timing.

property label: str

Candidate settings and launch as one line.

resident_blocks: int | None
runs: int
settings: Dict[str, Any]
property success_rate: float

Share of the batch that integrated without a status flag.

property timed: bool

Whether the launch has a time.

times_ms: Tuple[float, ...]
waves: float