Candidate comparison

class cubie.batchsolving.comparison.ComparisonRunner(solver: Any, inits: Any = None, params: Any = None, duration: float = 0.0, settling_time: float = 0.0, t0: float = 0.0, verbose: bool = False, max_parallel: int = 4)

Bases: object

Switch one solver between candidates and time each on one batch.

The batch stays on the device; candidates apply over the configuration at open(), which close() restores.

Parameters:

• solver – The solver whose settings the candidates vary.

• inits – The (variable, run) grid to time on; None compiles only.

• params – The (variable, run) grid to time on; None compiles only.

• duration – Integration window of the timed solves.

• settling_time – Integration window of the timed solves.

• t0 – Integration window of the timed solves.

• verbose – Print progress lines.

• max_parallel – Maximum compilations to run in parallel.

_compile_in_pool(candidates: Sequence[Candidate]) → None

Compile candidates into the kernel cache in spawned workers.

_launch_blocks(blocksize: int | None, runs: int | None) → Tuple[int, int]

Return blocks per SM and runs per block of the current launch.

_reject(candidate: Candidate, error: str) → None

Record candidate as rejected with error.

static _stage(grid: ndarray) → Any

Upload grid; keep a grid with no variables on the host.

batch_cap() → int

Runs that fit in one chunk and in host memory.

close() → None

Restore the solver’s configuration and release the batch.

compile(candidates: Sequence[Candidate]) → List[Candidate]

Compile the candidates, pooled if cheaper than serially; return the accepted ones, a rejected one keeps its error.

concurrent_runs(blocksize: int | None = None) → int

Runs the current candidate’s launch executes at once.

emit(message: str) → None

Log message; print it when verbose.

failures() → int

Return the failed-run count of the last solve.

fit_batch(measured: float, target_ms: float, grow: bool, shrink: bool) → float

Move the batch once toward target_ms, up within batch_cap() if grow, down to the floor if shrink; return the kernel time at the staged batch.

geometry(blocksize: int | None) → Tuple[int, float]

Return blocks per SM and waves of the current launch.

open() → None

Arm event timing and record the solver’s configuration.

rejection(candidate: Candidate) → str

Return why candidate was rejected; empty when it was not.

select(candidate: Candidate) → None

Apply candidate over the opening configuration.

set_batch(runs: int | None = None) → None

Stage runs grid columns on the device, cycling if short.

size_batch(candidates: Sequence[Candidate], waves: int) → None

Stage the tail-safe batch at waves of the most concurrent candidate; keep the counts for fit_batch().

solve_ms(blocksize: int | None = None) → float

Solve the staged batch once; return its kernel milliseconds.

property staged_bytes: int

Device bytes of the staged grid.

time(candidates: Sequence[Candidate]) → List[CandidateTiming]

Time every candidate on the staged batch, forward then back.

Every candidate solves SOLVES_PER_ROUND times in each of ROUNDS rounds; the second round reverses the order. A rejected or failing candidate carries the error and no times.

warm() → float

Lift the clocks with the busy kernel; return its milliseconds.

cubie.batchsolving.comparison.rank_timings(timings: Sequence[CandidateTiming]) → List[CandidateTiming]

Order timed candidates: the top success tier by time, then the rest.

The top tier holds every candidate whose success rate is at least SUCCESS_TIER_FRACTION of the best success rate.

class cubie.batchsolving.comparison.Candidate(label: str, settings: Dict[str, Any] = NOTHING, blocksize: int | None = None, resident_blocks: int | None = None)

Bases: object

One configuration and launch to time.

Parameters:

• label (str) – Name shown in reports.

• settings (Dict[str, Any]) – Solver settings applied through Solver.update.

• blocksize (int | None) – Threads per block of the launch; None uses the solver’s.

• resident_blocks (int | None) – Blocks per SM held resident; None uses the solver’s.

blocksize: int | None

label: str

resident_blocks: int | None

settings: Dict[str, Any]

class cubie.batchsolving.comparison.CandidateTiming(candidate: Candidate, times_ms: Tuple[float, ...] = (), failures: int = 0, runs: int = 0, blocks_per_sm: int = 0, waves: float = 0.0, error: str = '')

Bases: object

Measured outcome of one candidate.

Parameters:

• candidate (cubie.batchsolving.comparison.Candidate) – The configuration timed.

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

• failures (int) – Runs with a nonzero status code in the last solve read.

• runs (int) – Trajectories each solve integrated.

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

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

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

property best_ms: float

Lowest kernel time, inf when never timed.

blocks_per_sm: int

candidate: Candidate

error: str

failures: int

runs: int

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

waves: float