Optimisation

cubie.batchsolving.optimize.run_optimization(parent: Any, initial_values: Any, parameters: Any, drivers: Dict[str, 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) → OptimizeResult[source]

Time the solver’s candidate kernels on copies; 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 – Time-domain sampled driver values.

  • 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 – How many waves the auto_size setting sets your batch size to fill.

  • target_ms – Target kernel runtime that auto_size sets your integration duration to.

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.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 – Batch size the launch shapes are typed at; None uses the staged batch.

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, 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]

Every timed launch, fastest first.

runs: int
summary() → str[source]

Return a formatted table of every launch measurement.

class cubie.batchsolving.optimize.LaunchResult(settings: Dict[str, Any], blocksize: int, resident_blocks: int | None, blocks_per_sm: int = 0, times_ms: Tuple[float, ...] = (), excluded: bool = False)[source]

Bases: object

Timings of one candidate at one launch.

Parameters:

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

  • blocksize (int) – Threads per block of the launch.

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

  • excluded (bool) – Whether the launch was dropped as slow.

property best_ms: float

Lowest solve time, inf when never solved.

blocks_per_sm: int
blocksize: int
excluded: bool
property label: str

Candidate settings and launch as one line.

resident_blocks: int | None
settings: Dict[str, Any]
property timed: bool

Whether the launch has a ranking time.

times_ms: Tuple[float, ...]