solprop.calibration#

Calibrating the native backend to its machine (SEP 46).

The native backend’s CPU execution settings (how each operation threads, how idle threads wait, how wide the team is) are fitted to the machine by a bounded, one-off measurement, kept in a per-user store and applied by every later run, which records the settings it used in its metadata (calibration). Without a profile the native backend runs its built-in table. This package’s own functions read, show, export, import and clear profiles without loading the native extension: MachineProfile, profile, store_directory, export_profile, import_profile, clear, and calibrate, which measures one.

Modules: controller (the measurement: children, rounds, deadline, publication), child (one candidate’s timing process), selection (the statistical rule), grain (operation-grain candidates), problems (the synthetic problems), first_use (calibrating on first use and for a scan), refine (fitting one simulation) and command (solprop calibrate). The manual page is docs/guide/performance/calibration.md; the design is docs/dev/backends.md (section 3.4a).

class solprop.calibration.MachineProfile(fingerprint, generation, created, level, allocation, exact, process, workspace, fitted_under, evidence, source)[source]#

Bases: object

The calibration this process would apply, and its evidence.

Attributes:
fingerprintstr

The machine and build’s store key.

generationstr

The published generation’s name.

createdstr

When it was published, ISO 8601 in UTC.

levelstr

The level that measured the row: "quick", "standard" or "thorough".

allocationMapping[str, object]

The allocation class the row was measured in.

exactbool

Whether that is this process’s own class. A row of the nearest smaller class supplies workspace settings only.

processMapping[str, object]

The row’s process settings (pool width, waiting policy).

workspaceMapping[str, object]

The row’s workspace settings, each a field of the native execution record.

fitted_underMapping[str, object]

The process settings the workspace settings were validated under.

evidenceMapping[str, object]

What was measured, and why each setting was kept.

sourcepathlib.Path or None

The generation file read.

allocation: Mapping[str, object]#
created: str#
evidence: Mapping[str, object]#
exact: bool#
fingerprint: str#
fitted_under: Mapping[str, object]#
generation: str#
level: str#
process: Mapping[str, object]#
source: Path | None#
workspace: Mapping[str, object]#
solprop.calibration.calibrate(level='standard', budget=None)[source]#

Calibrate this machine’s native backend for the process’s allocation.

Child processes measure the candidate settings under one deadline; the result is published in the user’s store only if it was validated (SEP 46 section 6.5), and later runs apply it. solprop calibrate is the same from the command line.

Parameters:
levelstr, optional

"quick" (about 30 s), "standard" (about two minutes) or "thorough" (about seven minutes).

budgetfloat or None, optional

The deadline in seconds, the level’s when None.

Returns:
solprop.calibration.controller.CalibrationReport

Each setting chosen beside its built-in value, the evidence, and whether it was published.

solprop.calibration.clear(environ=None)[source]#

Forget this machine and build’s profiles and stored FFT plans.

The user’s store loses the profiles, their refinements and the plans runs measured (wisdom.json, solprop ADR-076), and the file SOLPROP_FFTW_WISDOM keeps for this build, when the variable is set, goes too. A calibration in progress keeps its claim. Read-only directories are not touched.

Parameters:
environMapping[str, str] or None, optional

The environment; the process’s when None.

Returns:
int

The files removed.

solprop.calibration.export_profile(path, environ=None)[source]#

Write this machine and build’s published generation to path.

The file can be imported elsewhere (import_profile()) or placed in a directory listed in SOLPROP_CALIBRATION_PATH, for example a cluster’s profiles for each node type.

Parameters:
pathpathlib.Path

The JSON file to write.

environMapping[str, str] or None, optional

The environment; the process’s when None.

Returns:
pathlib.Path

The generation file that was exported.

Raises:
CalibrationError

When no generation was published for this machine and build.

solprop.calibration.import_profile(path, environ=None)[source]#

Publish an exported generation in the user’s store.

Parameters:
pathpathlib.Path

A file written by export_profile().

environMapping[str, str] or None, optional

The environment; the process’s when None.

Returns:
bool

Whether the generation is for this machine and build, so that it applies here; another fingerprint’s is kept for the store’s other machines.

Raises:
CalibrationError

When the file is not a generation of this format.

solprop.calibration.profile(environ=None)[source]#

Return the calibration this process would apply, or None.

None means the native backend runs its built-in table: no profile was published for this machine and build, none has a row for this allocation, or SOLPROP_CALIBRATION=off.

Parameters:
environMapping[str, str] or None, optional

The environment; the process’s when None.

Returns:
MachineProfile or None

The profile, its row and evidence.

solprop.calibration.store_directory(environ=None)[source]#

Return the user’s calibration store: the platform’s user cache directory.

Parameters:
environMapping[str, str] or None, optional

The environment; the process’s when None.

Returns:
pathlib.Path

SOLPROP_CACHE_DIR when set; otherwise $XDG_CACHE_HOME/solprop or ~/.cache/solprop on Linux, ~/Library/Caches/solprop on macOS and %LOCALAPPDATA%\solprop\Cache on Windows.

Examples

>>> store_directory({"SOLPROP_CACHE_DIR": "/tmp/solprop"}).as_posix()
'/tmp/solprop'

Modules

child

A calibration child: one candidate's process settings, timed on request (SEP 46).

command

solprop calibrate: measure, show, export, import or forget a profile (SEP 46).

controller

The calibration controller: children, rounds, a deadline and publication (SEP 46).

first_use

Calibrating automatically on first use (SEP 46 sections 5 and 6.10).

grain

Operation-grain candidates from the work sizes the calibration problems run (SEP 46).

problems

The calibration's synthetic problems (SEP 46 section 6.3).

refine

Stage 2: refine the workspace settings for one simulation (SEP 46 section 6.6).

selection

The calibration's statistical rule: which setting replaces the table (SEP 46).