class Calibration(sim, calib_pars=None, fit_args=None, custom_fn=None, par_samplers=None, n_trials=None, n_workers=None, total_trials=None, name=None, db_name=None, keep_db=None, storage=None, label=None, die=False, verbose=True)[source]#

Bases: Analyzer

A class to handle calibration of Covasim simulations. Uses the Optuna hyperparameter optimization library (, which must be installed separately (via pip install optuna).

Note: running a calibration does not guarantee a good fit! You must ensure that you run for a sufficient number of iterations, have enough free parameters, and that the parameters have wide enough bounds. Please see the tutorial on calibration for more information.

  • sim (Sim) – the simulation to calibrate

  • calib_pars (dict) – a dictionary of the parameters to calibrate of the format dict(key1=[best, low, high])

  • fit_args (dict) – a dictionary of options that are passed to sim.compute_fit() to calculate the goodness-of-fit

  • par_samplers (dict) – an optional mapping from parameters to the Optuna sampler to use for choosing new points for each; by default, suggest_float

  • custom_fn (func) – a custom function for modifying the simulation; receives the sim and calib_pars as inputs, should return the modified sim

  • n_trials (int) – the number of trials per worker

  • n_workers (int) – the number of parallel workers (default: maximum

  • total_trials (int) – if n_trials is not supplied, calculate by dividing this number by n_workers)

  • name (str) – the name of the database (default: ‘covasim_calibration’)

  • db_name (str) – the name of the database file (default: ‘covasim_calibration.db’)

  • keep_db (bool) – whether to keep the database after calibration (default: false)

  • storage (str) – the location of the database (default: sqlite)

  • label (str) – a label for this calibration object

  • die (bool) – whether to stop if an exception is encountered (default: false)

  • verbose (bool) – whether to print details of the calibration

  • kwargs (dict) – passed to cv.Calibration()


A Calibration object


sim = cv.Sim(datafile='data.csv')
calib_pars = dict(beta=[0.015, 0.010, 0.020])
calib = cv.Calibration(sim, calib_pars, total_trials=100)

New in version 3.0.3.


run_sim(calib_pars, label=None, return_sim=False)[source]#

Create and run a simulation


Define the objective for Optuna


Run a single worker


Run multiple workers in parallel


Remove the database file if keep_db is false and the path exists.

New in version 3.1.0.


Make a study, deleting one if it already exists

calibrate(calib_pars=None, verbose=True, **kwargs)[source]#

Actually perform calibration.

  • calib_pars (dict) – if supplied, overwrite stored calib_pars

  • verbose (bool) – whether to print output from each trial

  • kwargs (dict) – if supplied, overwrite stored run_args (n_trials, n_workers, etc.)


Print out results from the calibration


Parse the study into a data frame – called automatically


Convert the data to JSON.

New in version 3.1.1.


Plot sims, before and after calibration.

New in version 3.1.1: renamed from plot() to plot_sims().


Plot the trend in best mismatch over time.

New in version 3.1.1.


Plot every point in the calibration. Warning, very slow for more than a few hundred trials.

New in version 3.1.1.


Plot only the points with lowest mismatch. New in version 3.1.1.


Plot a fixed number of points in order across the results.

New in version 3.1.1.