calibrate

Calibrate performance on this machine

Run calibration explicitly when you want PyVBMC to tune its performance for your machine:

import pyvbmc

profile = pyvbmc.calibrate()

The campaign uses synthetic inputs and its own random generators. It does not evaluate your model or consume the inference random stream. It usually takes tens of seconds; run it while the machine is otherwise quiet. Progress, the outcome and the cache location are printed unless verbose=False.

Each call requests a fresh campaign. If another calibration is already active, or the measurements cannot be completed or validated, calibrate returns the best compatible saved or in-process profile, or the standard profile when none is available. profile.status records the outcome and profile.source says where the settings came from. A failed campaign does not replace a valid saved record. Keeping the standard settings is also a successful outcome when the measurements find no reliable improvement.

To recalibrate, call pyvbmc.calibrate() again. Calibration never starts automatically during import, posterior evaluation, optimization or save/load.

Using the result

New VBMC runs use a compatible cached profile by default. This works the same way in Python scripts and Jupyter notebooks; the notebook kernel must use a compatible numerical environment. You may also provide the returned profile explicitly:

vbmc = pyvbmc.VBMC(
    log_density, x0, lower_bounds, upper_bounds,
    plausible_lower_bounds, plausible_upper_bounds,
    options={"performance_calibration": profile},
)

Set performance_calibration="off" in the options dictionary to use the standard chunk settings. Missing or incompatible cache records use the same settings, and the first such run of a Python session suggests calibrating unless display="off".

Each run keeps one profile through optimization, final boost and save/resume. Recalibration affects future unresolved runs, not an existing resolved run. Calling a PDF or entropy kernel on vbmc.vp before optimization resolves its profile early. Standalone VariationalPosterior objects use standard settings unless constructed with calibration=profile or calibration="cached".

Storage and reproducibility

Profiles are stored in the operating system’s per-user cache directory under pyvbmc/calibration/v1. On Windows this is normally beneath %LOCALAPPDATA%; macOS uses ~/Library/Caches and Linux uses the XDG cache root. Set PYVBMC_CACHE_DIR to override the PyVBMC cache root. The returned profile’s cache_path identifies its JSON record, including detailed measurement results, when persistence succeeded. It is None for a result that could not be saved. If the cache is unwritable, the returned profile remains usable in the current process.

Reuse checks the machine and numerical environment, including library versions, numerical backend and thread settings.

The profile contains three fixed budgets: PDF, entropy with gradients and entropy values. Calibration changes chunk sizes only; it does not change sample counts, inference tolerances or numerical results. The same seed gives the same trajectory with calibrated or standard settings. A saved run retains its profile, including when loaded on another machine.

pyvbmc.calibrate(*, verbose=True)

Measure and return performance settings for this machine.

Each call requests a fresh calibration campaign. If another campaign is active, or the measurements are incomplete or invalid, the call returns the best compatible saved or in-process profile, or the standard profile when none is available. The returned profile’s status records that outcome and its source records where the settings came from. A failed campaign does not replace a valid saved record. Importing PyVBMC and using a compatible cached profile do not run the campaign.

Parameters:

verbosebool, optional

Print the expected duration, campaign progress, whether faster settings were selected, and where the results were saved. The default is True.

Returns:

CalibrationProfile

Immutable settings together with compact outcome and cache metadata. A completed campaign has status "complete". A fallback has status "busy", "incomplete" or "invalid" and uses the best compatible saved, in-process or standard settings. The held-out measurements behind completed, persisted settings are in the JSON report named by cache_path.

Raises:

TypeError

If verbose is not a bool.

Notes

The selected budgets are attributes of the returned profile. A campaign takes tens of seconds, an estimate rather than a deadline. A five-minute watchdog stops further work only after a numerical call returns.

See also CalibrationProfile and VBMC options.