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:
objectThe 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.
- 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 calibrateis 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 fileSOLPROP_FFTW_WISDOMkeeps 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 inSOLPROP_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.Nonemeans the native backend runs its built-in table: no profile was published for this machine and build, none has a row for this allocation, orSOLPROP_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_DIRwhen set; otherwise$XDG_CACHE_HOME/solpropor~/.cache/solpropon Linux,~/Library/Caches/solpropon macOS and%LOCALAPPDATA%\solprop\Cacheon Windows.
Examples
>>> store_directory({"SOLPROP_CACHE_DIR": "/tmp/solprop"}).as_posix() '/tmp/solprop'
Modules
A calibration child: one candidate's process settings, timed on request (SEP 46). |
|
|
|
The calibration controller: children, rounds, a deadline and publication (SEP 46). |
|
Calibrating automatically on first use (SEP 46 sections 5 and 6.10). |
|
Operation-grain candidates from the work sizes the calibration problems run (SEP 46). |
|
The calibration's synthetic problems (SEP 46 section 6.3). |
|
Stage 2: refine the workspace settings for one simulation (SEP 46 section 6.6). |
|
The calibration's statistical rule: which setting replaces the table (SEP 46). |