gcubed.linearisation.workspace_calibration

Offline host calibration for state-space-form workspace preferences.

The command benchmarks complete build-197 state-space-form construction under several explicit workspace caps. It then profiles the fastest candidate once and writes a host-local profile containing representative operation shapes, the active BLAS signature and thread count, and a measured BLAS workspace allowance. Normal model solution only reads this artifact; it performs no implicit timing trials.

DEFAULT_CALIBRATION_CAPS_GIB: tuple[float, ...] = (0.25, 0.5, 0.75, 1.0)

Build-197 cap sweep used when no candidate list is supplied.

def select_fastest_candidate( benchmark_results: Sequence[Mapping[str, typing.Any]]) -> Mapping[str, typing.Any]:

Return the candidate with the lowest median then mean duration.

Args: benchmark_results: Completed performance-regression artifacts.

Returns: Fastest candidate mapping.

Raises: ValueError: Raised when no result is supplied or a timing is not positive. KeyError: Raised when a required summary field is absent. TypeError: Raised when a summary is not a mapping.

def build_workspace_performance_profile( events: Sequence[Mapping[str, typing.Any]], *, model_id: str, selected_workspace_cap_bytes: int, benchmark_results: Sequence[Mapping[str, typing.Any]]) -> dict[str, typing.Any]:

Build a versioned local profile from one real-model profile run.

Args: events: Parsed memory-profiler JSONL events from the selected candidate. model_id: Build-197 model supplying representative operation shapes. selected_workspace_cap_bytes: Winning explicit calibration cap. benchmark_results: Candidate performance artifacts used for selection.

Returns: JSON-compatible host profile accepted by :func:load_workspace_performance_profile.

Raises: ValueError: Raised for a non-197 model, an invalid cap, missing operation events, or inconsistent BLAS metadata. KeyError: Raised when required profiler fields are absent. TypeError: Raised when profiler fields have incompatible types.

def run_host_calibration( model_id: str, *, output_file: pathlib.Path, evidence_directory: pathlib.Path, caps_gib: Sequence[float] = (0.25, 0.5, 0.75, 1.0), repetitions: int = 3, repository_root: pathlib.Path | None = None) -> dict[str, typing.Any]:

Benchmark build-197 candidates and write a host-local profile.

Args: model_id: Build-197 model identifier, normally 6W_197. output_file: Destination JSON profile. evidence_directory: Directory for candidate timings and one JSONL run. caps_gib: Positive explicit cap candidates. repetitions: Fresh-process trials for each cap. repository_root: Optional gcubedcode repository root.

Returns: Written profile mapping.

Raises: ValueError: Raised for invalid model, caps, or repetition count. FileNotFoundError: Raised when the focused benchmark test is absent. RuntimeError: Raised when a benchmark/profile subprocess fails. OSError: Propagated when subprocesses or artifact writes fail.

def main(argv: Sequence[str] | None = None) -> int:

Run host calibration from command-line arguments.

Args: argv: Optional argument sequence excluding the executable name.

Returns: Zero after writing the profile.

Raises: Exceptions from :func:run_host_calibration are intentionally propagated with actionable diagnostics.