Note

This is the documentation for the current state of the development branch of Qiskit Experiments. The documentation or APIs here can change prior to being released.

BaseCalibrationExperiment

class BaseCalibrationExperiment(calibrations, *args, schedule_name=None, cal_parameter_name=None, updater=None, auto_update=True, **kwargs)

A mixin class to create calibration experiments.

This abstract class extends a characterization experiment by turning it into a calibration experiment. Such experiments allow schedule management and updating of an instance of Calibrations. Furthermore, calibration experiments also specify an auto_update variable which, by default, is set to True. If this variable, is True then the run method of the experiment will call block_for_results() and update the calibrations instance once the backend has returned the data.

This mixin class inherits from the BaseExperiment class since calibration experiments by default call block_for_results(). This ensures that the next calibration experiment cannot proceed before the calibration parameters have been updated. Developers that wish to create a calibration experiment must subclass this base class and the characterization experiment. Therefore, developers that use this mixin class must pay special attention to their class definition. Indeed, the first class should be this mixin and the second class should be the characterization experiment since the run method from the mixin must be used. For example, the rough frequency calibration experiment is defined as

RoughFrequencyCal(BaseCalibrationExperiment, QubitSpectroscopy)

This ensures that the run method of RoughFrequencyCal will be the run method of the BaseCalibrationExperiment class. Furthermore, developers must explicitly call the __init__() methods of both parent classes.

Developers should strive to follow the convention that the first two arguments of a calibration experiment are the qubit(s) and the Calibrations instance.

If the experiment uses custom schedules, which is typically the case, then developers may chose to use the get_schedules() method when creating the circuits for the experiment. If get_schedules() is used then the developer must override at least one of the following methods used by get_schedules() to set the schedules:

1. _get_schedules_from_options()

2. _get_schedules_from_calibrations()

3. _get_schedules_from_defaults()

These methods are called by get_schedules().

The update_calibrations() method is responsible for updating the values of the parameters stored in the instance of Calibrations. Here, BaseCalibrationExperiment provides a default update methodology that subclasses can override if a more elaborate behaviour is needed. At the minimum the developer must set the variable _updater which should have an update method and can be chosen from the library qiskit_experiments.calibration_management.update_library. See also qiskit_experiments.calibration_management.update_library.BaseUpdater. If no updater is specified the experiment will still run but no update of the calibrations will be performed.

Setup the calibration experiment object.

Parameters:

• calibrations (Calibrations) – The calibrations instance with which to initialize the experiment.

• args – Arguments for the characterization class.

• schedule_name (str | None) – An optional string which specifies the name of the schedule in the calibrations that will be updated.

• cal_parameter_name (str | None) – An optional string which specifies the name of the parameter in the calibrations that will be updated. If None is given then no parameter will be updated. Subclasses may assign default values in their init.

• updater (Type[BaseUpdater] | None) – The updater class that updates the Calibrations instance. Different calibration experiments will use different updaters.

• auto_update (bool) – If set to True (the default) then the calibrations will automatically be updated once the experiment has run and block_for_results() will be called.

• kwargs – Keyword arguments for the characterization class.

Attributes

analysis

Return the analysis instance for the experiment.

Note

Analysis instance set to calibration experiment is implicitly patched to run calibration updater to update the parameters in the calibration table.

backend

Return the backend for the experiment

calibrations

Return the calibrations.

experiment_options

Return the options for the experiment.

experiment_type

Return experiment type.

num_qubits

Return the number of qubits for the experiment.

physical_qubits

Return the device qubits for the experiment.

run_options

Return options values for the experiment run() method.

transpile_options

Return the transpiler options for the run() method.

Methods

abstract circuits()

Return a list of experiment circuits.

Returns:

A list of QuantumCircuit.

Return type:

List[QuantumCircuit]

Note

These circuits should be on qubits [0, .., N-1] for an N-qubit experiment. The circuits mapped to physical qubits are obtained via the internal _transpiled_circuits() method.

config()

Return the config dataclass for this experiment

Return type:

ExperimentConfig

copy()

Return a copy of the experiment

Return type:

BaseExperiment

classmethod from_config(config)

Initialize an experiment from experiment config

Return type:

BaseExperiment

job_info(backend=None)

Get information about job distribution for the experiment on a specific backend.

Parameters:

backend (Backend) – Optional, the backend for which to get job distribution information. If not specified, the experiment must already have a set backend.

Returns:

A dictionary containing information about job distribution.

• ”Total number of circuits in the experiment”: Total number of circuits in the experiment.

• ”Maximum number of circuits per job”: Maximum number of circuits in one job based on backend and experiment settings.

• ”Total number of jobs”: Number of jobs needed to run this experiment on the currently set backend.

Return type:

dict

Raises:

QiskitError – if backend is not specified.

run(backend=None, sampler=None, analysis='default', timeout=None, backend_run=None, **run_options)

Run an experiment and perform analysis.

Parameters:

• backend (Backend | None) – Optional, the backend to run on. Will override existing backend settings.

• sampler (BaseSamplerV2 | None) – Optional, the sampler to run the experiment on. If None then a sampler will be invoked from previously set backend

• analysis (BaseAnalysis | None) – Optional, a custom analysis instance to use for performing analysis. If None analysis will not be run. If "default" the experiments analysis() instance will be used if it contains one.

• timeout (float | None) – Time to wait for experiment jobs to finish running before cancelling.

• backend_run (bool | None) – Use backend run (temp option for testing)

• run_options – backend runtime options used for circuit execution.

Returns:

The experiment data object.

Raises:

QiskitError – If experiment is run with an incompatible existing ExperimentData container.

Return type:

ExperimentData

set_experiment_options(**fields)

Set the experiment options.

Parameters:

fields – The fields to update the options

Raises:

AttributeError – If the field passed in is not a supported options

set_run_options(**fields)

Set options values for the experiment run() method.

Parameters:

fields – The fields to update the options

See also

The Setting options for your experiment guide for code example.

set_transpile_options(**fields)

Add a warning message.

Note

If your experiment has overridden _transpiled_circuits and needs transpile options then please also override set_transpile_options.

update_calibrations(experiment_data)

Update parameter values in the Calibrations instance.

The default behaviour is to call the update method of the class variable __updater__ with simplistic options. Subclasses can override this method to update the instance of Calibrations if they require a more sophisticated behaviour as is the case for the Rabi and FineAmplitude calibration experiments.