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.

Calibrations¶

class Calibrations(coupling_map=None, control_channel_map=None, libraries=None, add_parameter_defaults=True, backend_name=None, backend_version=None)[source]¶

A class to manage schedules with calibrated parameter values. Schedules are intended to be fully parameterized, including the index of the channels. See the module-level documentation for extra details. Note that only instances of ScheduleBlock are supported.

Initialize the calibrations.

Calibrations can be initialized from a list of basis gate libraries, i.e. a subclass of BasisGateLibrary. As example consider the following code:

cals = Calibrations(
        libraries=[
            FixedFrequencyTransmon(
                basis_gates=["x", "sx"],
                default_values={duration: 320}
            )
        ]
    )

Deprecated since version 0.8: The class qiskit_experiments.calibration_management.calibrations.Calibrations is deprecated as of qiskit-experiments 0.8. It will be removed no earlier than 3 months after the release date. Due to the deprecation of Qiskit Pulse, support for pulse gate calibrations has been deprecated.

Parameters:

coupling_map (List[List[int]] | None) – The device’s coupling map. Each sub-list describes connected qubits For example, the coupling map of a fully pairwise-connected backend with three qubits is [[0, 1], [1, 0], [1, 2], [2, 1], [2, 0], [0, 2]].
control_channel_map (Dict[Tuple[int, ...], List[ControlChannel]] | None) – A configuration dictionary of any control channels. The keys are tuples of qubits and the values are a list of ControlChannels that correspond to the qubits in the keys. If a control_channel_map is given then the qubits must be in the coupling_map.
libraries (List[BasisGateLibrary] | None) – A list of library instances from which to get template schedules to register as well as default parameter values.
add_parameter_defaults (bool) – A boolean to indicate weather the default parameter values of the given libraries should be used to populate the calibrations. By default this value is True but can be set to false when deserializing a calibrations object.
backend_name (str | None) – The name of the backend that these calibrations are attached to.
backend_version (str | None) – The version of the backend that these calibrations are attached to.

Attributes

backend_name¶: Return the name of the backend.

backend_version¶: Return the version of the backend.

default_inst_map¶: Return the default and up to date instruction schedule map.

drive_freq¶: Parameter object for qubit drive frequency.

Deprecated since version 0.6: The property qiskit_experiments.calibration_management.calibrations.Calibrations.drive_freq is deprecated as of qiskit-experiments 0.6. It will be removed no earlier than 3 months after the release date. The drive_freq is moved to FixedFrequencyTransmon basis gate library.

libraries¶: Return the libraries used to initialize the calibrations.

meas_freq¶: Parameter object for qubit measure frequency.

Deprecated since version 0.6: The property qiskit_experiments.calibration_management.calibrations.Calibrations.meas_freq is deprecated as of qiskit-experiments 0.6. It will be removed no earlier than 3 months after the release date. The meas_freq is moved to FixedFrequencyTransmon basis gate library.

parameters¶

Return a mapping between parameters and parameter keys.

Returns a dictionary mapping parameters managed by the calibrations to the schedules and qubits and parameter names using the parameters. The values of the dict are sets containing the parameter keys. Parameters that are not attached to a schedule will have None in place of a schedule name.

schedule_dependency¶: Return the schedule dependencies in the calibrations.

Methods

add_parameter_value(value, param, qubits=None, schedule=None, update_inst_map=True)[source]¶

Add a parameter value to the stored parameters.

This parameter value may be applied to several channels, for instance, all DRAG pulses may have the same standard deviation.

Parameters:

value (int | float | complex | ParameterValue) – The value of the parameter to add. If an int, float, or complex is given then the timestamp of the parameter value will automatically be generated and set to the current local time of the user.
param (Parameter | str) – The parameter or its name for which to add the measured value.
qubits (int | Tuple[int, ...]) – The qubits to which this parameter applies.
schedule (ScheduleBlock | str) – The schedule or its name for which to add the measured parameter value.
update_inst_map (bool) – Update the instruction schedule map if True (the default).

Raises:

CalibrationError – If the schedule name is given but no schedule with that name exists.

add_schedule(schedule, qubits=None, num_qubits=None)[source]¶

Add a schedule block and register its parameters.

Schedules that use Call instructions must register the called schedules separately.

Parameters:

schedule (ScheduleBlock) – The ScheduleBlock to add.
qubits (int | Tuple[int, ...]) – The qubits for which to add the schedules. If None or an empty tuple is given then this schedule is the default schedule for all qubits and, in this case, the number of qubits that this schedule act on must be given.
num_qubits (int | None) – The number of qubits that this schedule will act on when exported to a circuit instruction. This argument is optional as long as qubits is either not None or not an empty tuple (i.e. default schedule).

Raises:

CalibrationError – If schedule is not an instance of ScheduleBlock.
CalibrationError – If a schedule has assigned references.
CalibrationError – If several parameters in the same schedule have the same name.
CalibrationError – If the schedule name starts with the prefix of ScheduleBlock.
CalibrationError – If the schedule calls subroutines that have not been registered.
CalibrationError – If a Schedule is Called instead of a ScheduleBlock.
CalibrationError – If a schedule with the same name exists and acts on a different number of qubits.

calibration_parameter(parameter_name, qubits=None, schedule_name=None)[source]¶

Return a parameter given its keys.

Returns a Parameter object given the triplet parameter_name, qubits and schedule_name which uniquely determine the context of a parameter.

Parameters:

parameter_name (str) – Name of the parameter to get.
qubits (int | Tuple[int, ...]) – The qubits to which this parameter belongs. If qubits is None then the default scope is assumed and the key will be an empty tuple.
schedule_name (str) – The name of the schedule to which this parameter belongs. A parameter may not belong to a schedule in which case None is accepted.

Returns:

The parameter that corresponds to the given arguments.

Return type:

calibration parameter

Raises:

CalibrationError – If the desired parameter is not found.

config()[source]¶

Return the settings used to initialize the calibrations.

Deprecated since version 0.6: The method qiskit_experiments.calibration_management.calibrations.Calibrations.config() is deprecated as of qiskit-experiments 0.6. It will be removed no earlier than 3 months after the release date. Configuration data for Calibrations instance is deprecate. Please use ExperimentEncoder and ExperimentDecoder to serialize and deserialize this instance with JSON format.

Returns:: The config dictionary of the calibrations instance.
Raises:: CalibrationError – If schedules were added outside of the __init__ method. This will remain so until schedules can be serialized.
Return type:: Dict[str, Any]

classmethod from_backend(backend, libraries=None, add_parameter_defaults=True)[source]¶

Create an instance of Calibrations from a backend.

Parameters:

backend (Backend) – A backend instance from which to extract the qubit and readout frequencies (which will be added as first guesses for the corresponding parameters) as well as the coupling map.
libraries (List[BasisGateLibrary] | None) – A list of libraries from which to get template schedules to register as well as default parameter values.
add_parameter_defaults (bool) – A boolean to indicate whether the default parameter values of the given library should be used to populate the calibrations. By default, this value is True.

Returns:

An instance of Calibrations instantiated from a backend.

Return type:

Calibrations

classmethod from_config(config)[source]¶

Restore Calibration from config data.

Deprecated since version 0.6: The method qiskit_experiments.calibration_management.calibrations.Calibrations.from_config() is deprecated as of qiskit-experiments 0.6. It will be removed no earlier than 3 months after the release date. This method will be removed and no alternative will be provided.

Parameters:: config (Dict) – Configuration data.
Returns:: Calibration instance restored from configuration data.
Return type:: Calibrations

get_inst_map(group='default', cutoff_date=None)[source]¶

Get an Instruction schedule map with the calibrated pulses.

If the group is ‘default’ and cutoff date is None then the automatically updated instruction schedule map is returned. However, if these values are different then a new instruction schedule map is populated based on the values.

Parameters:

group (str) – The calibration group from which to draw the parameters. If not specified this defaults to the ‘default’ group.
cutoff_date (datetime) – Retrieve the most recent parameter up until the cutoff date. Parameters generated after the cutoff date will be ignored. If the cutoff_date is None then all parameters are considered. This allows users to discard more recent values that may be erroneous.

Returns:

An instruction schedule map with parameters updated up to the desired cutoff date and from the desired calibration group.

Return type:

InstructionScheduleMap

get_parameter_value(param, qubits, schedule=None, valid_only=True, group='default', cutoff_date=None)[source]¶

Retrieves the value of a parameter.

Parameters may be linked. get_parameter_value() does the following steps:

Retrieve the parameter object corresponding to (param, qubits, schedule).
The values of this parameter may be stored under another schedule since schedules can share parameters. To deal with this, a list of candidate keys is created internally based on the current configuration.
Look for candidate parameter values under the candidate keys.
Filter the candidate parameter values according to their date (up until the cutoff_date), validity and calibration group.
Return the most recent parameter.

Parameters:

param (Parameter | str) – The parameter or the name of the parameter for which to get the parameter value.
qubits (int | Tuple[int, ...]) – The qubits for which to get the value of the parameter.
schedule (ScheduleBlock | str | None) – The schedule or its name for which to get the parameter value.
valid_only (bool) – Use only parameters marked as valid.
group (str) – The calibration group from which to draw the parameters. If not specified this defaults to the ‘default’ group.
cutoff_date (datetime) – Retrieve the most recent parameter up until the cutoff date. Parameters generated after the cutoff date will be ignored. If the cutoff_date is None then all parameters are considered. This allows users to discard more recent values that may be erroneous.

Returns:

The value of the parameter.

Return type:

value

Raises:

CalibrationError – If there is no parameter value for the given parameter name and pulse channel.

get_schedule(name, qubits, assign_params=None, group='default', cutoff_date=None)[source]¶

Get the template schedule with parameters assigned to values.

All the parameters in the template schedule block will be assigned to the values managed by the calibrations unless they are specified in assign_params. In this case the value in assign_params will override the value stored by the calibrations. A parameter value in assign_params may also be a ParameterExpression.

# Get an xp schedule with a parametric amplitude
sched = cals.get_schedule("xp", 3, assign_params={"amp": Parameter("amp")})

# Get an echoed-cross-resonance schedule between qubits (0, 2) where the xp echo gates
# are referenced schedules but leave their amplitudes as parameters.
assign_dict = {("amp", (0,), "xp"): Parameter("my_amp")}
sched = cals.get_schedule("cr", (0, 2), assign_params=assign_dict)

Parameters:

name (str) – The name of the schedule to get.
qubits (int | Tuple[int, ...]) – The qubits for which to get the schedule.
assign_params (Dict[str | ParameterKey, ParameterExpression | float | int | complex]) – The parameters to assign manually. Each parameter is specified by a ParameterKey which is a named tuple of the form (parameter name, qubits, schedule name). Each entry in assign_params can also be a string corresponding to the name of the parameter. In this case, the schedule name and qubits of the corresponding ParameterKey will be the name and qubits given as arguments to get_schedule.
group (str | None) – The calibration group from which to draw the parameters. If not specified this defaults to the ‘default’ group.
cutoff_date (datetime) – Retrieve the most recent parameter up until the cutoff date. Parameters generated after the cutoff date will be ignored. If the cutoff_date is None then all parameters are considered. This allows users to discard more recent values that may be erroneous.

Returns:

A copy of the template schedule with all parameters assigned.

Return type:

schedule

Raises:

CalibrationError – If the name of the schedule is not known.
CalibrationError – If a parameter could not be found.

get_template(schedule_name, qubits=None)[source]¶

Get a template schedule.

Allows the user to get a template schedule that was previously registered. A template schedule will typically be fully parametric, i.e. all pulse parameters and channel indices are represented by Parameter.

Parameters:

schedule_name (str) – The name of the template schedule.
qubits (Tuple[int, ...] | None) – The qubits under which the template schedule was registered.

Returns:

The registered template schedule.

Raises:

CalibrationError – If no template schedule for the given schedule name and qubits was registered.

Return type:

ScheduleBlock

has_template(schedule_name, qubits=None)[source]¶

Test if a template schedule is defined

Parameters:

schedule_name (str) – The name of the template schedule.
qubits (Tuple[int, ...] | None) – The qubits under which the template schedule was registered.

Returns:

True if a template exists for the schedule name for the given qubits

Return type:

bool

inst_map_add(instruction_name, qubits, schedule_name=None, assign_params=None)[source]¶

Update a single instruction in the instruction schedule map.

This method can be used to update a single instruction for the given qubits but it can also be used by experiments that define custom gates with parameters such as the Rabi experiment. In a Rabi experiment there is a gate named “Rabi” that scans a pulse with a custom amplitude. Therefore we would do

cals.inst_map_add("Rabi", (0, ), "xp", assign_params={"amp": Parameter("amp")})

to temporarily add a pulse for the Rabi gate in the instruction schedule map. This then allows calling transpile(circ, inst_map=cals.default_inst_map).

Parameters:

instruction_name (str) – The name of the instruction to add to the instruction schedule map.
qubits (Tuple[int]) – The qubits to which the instruction will apply.
schedule_name (str | None) – The name of the schedule. If None is given then we assume that the schedule and the instruction have the same name.
assign_params (Dict[str | ParameterKey, ParameterExpression | float | int | complex] | None) – An optional dict of parameter mappings to apply. See for instance get_schedule() of Calibrations.

classmethod load(file_path)[source]¶

Retrieves the parameterized schedules and pulse parameters from the given location.

Deprecated since version 0.6: qiskit_experiments.calibration_management.calibrations.Calibrations.load()’s argument files is deprecated as of qiskit-experiments 0.6. It will be removed no earlier than 3 months after the release date. Instead, use the argument file_path, which behaves identically.

Parameters:: file_path (str) – Path to file location.
Returns:: Calibration instance restored from the file.
Return type:: Calibrations

load_parameter_values(file_name='parameter_values.csv')[source]¶

Load parameter values from a given file into self._params.

Deprecated since version 0.6: The method qiskit_experiments.calibration_management.calibrations.Calibrations.load_parameter_values() is deprecated as of qiskit-experiments 0.6. It will be removed no earlier than 3 months after the release date. Loading and saving calibrations in CSV format is deprecated.

Parameters:: file_name (str) – The name of the file that stores the parameters. Will default to parameter_values.csv.

parameters_table(parameters=None, qubit_list=None, schedules=None, most_recent_only=True, group=None)[source]¶

A convenience function to help users visualize the values of their parameter.

Parameters:

parameters (List[str]) – The parameter names that should be included in the returned table. If None is given then all names are included.
qubit_list (List[Tuple[int, ...]]) – The qubits that should be included in the returned table. If None is given then all channels are returned.
schedules (List[ScheduleBlock | str]) – The schedules to which to restrict the output.
most_recent_only (bool) – return only the most recent parameter values.
group (str | None) – If the group is given then only the parameters from this group are returned.

Returns:

A dictionary with the keys “data” and “columns” that can easily be converted to a data frame. The “data” are a list of dictionaries each holding a parameter value. The “columns” are the keys in the “data” dictionaries and are returned in the preferred display order.

Return type:

Dict[str, List[Dict] | List[str]]

remove_schedule(schedule, qubits=None)[source]¶

Remove a schedule that was previously registered.

Allows users to remove a schedule from the calibrations. The history of the parameters will remain in the calibrations.

Parameters:

schedule (ScheduleBlock) – The schedule to remove.
qubits (int | Tuple[int, ...]) – The qubits for which to remove the schedules. If None is given then this schedule is the default schedule for all qubits.

Raises:

CalibrationError – If other schedules depend on schedule.

save(file_type='json', folder=None, overwrite=False, file_prefix='', most_recent_only=False)[source]¶

Save the parameterized schedules and parameter value.

Note

Full round-trip serialization of a Calibrations instance is only supported in JSON format. This may be extended to other file formats in future version.

Deprecated since version 0.6: qiskit_experiments.calibration_management.calibrations.Calibrations.save()’s argument file_type is deprecated as of qiskit-experiments 0.6. It will be removed no earlier than 3 months after the release date. Full calibration saving is now supported in json format. csv is deprecated.

Parameters:

file_type (str) – The type of file to which to save. By default, this is a json. Other file types may be supported in the future.
folder (str) – The folder in which to save the calibrations.
overwrite (bool) – If the files already exist then they will not be overwritten unless overwrite is set to True.
file_prefix (str) – A prefix to add to the name of the files such as a date tag or a UUID.
most_recent_only (bool) – Save only the most recent value. This is set to False by default so that when saving to csv all values will be saved.

Raises:

CalibrationError – If the files exist and overwrite is not set to True.

schedule_information()[source]¶

Get the information on the schedules stored in the calibrations.

This function serializes the schedule by simply printing them.

Deprecated since version 0.6: The method qiskit_experiments.calibration_management.calibrations.Calibrations.schedule_information() is deprecated as of qiskit-experiments 0.6. It will be removed no earlier than 3 months after the release date. Saving calibration in csv format is deprecate as well as functions that support this functionality.

Returns:: A tuple, the first element is the header row while the second is a dictionary of the schedules in the calibrations where the key is an element of the header and the values are the name of the schedule, the qubits to which it applies, a string of the schedule.
Return type:: Tuple[List[str], List[Dict]]

schedules()[source]¶

Return the managed schedules in a list of dictionaries.

Returns:

A list of dictionaries with all the schedules in it. The key-value pairs are

qubits: the qubits to which this schedule applies. This may be an empty
tuple () if the schedule is the default for all qubits.
schedule: The schedule.
parameters: The parameters in the schedule exposed for convenience.

This list of dictionaries can easily be converted to a data frame.

Return type:

data

update_inst_map(schedules=None, qubits=None, group='default', cutoff_date=None, inst_map=None)[source]¶

Push all schedules from the Calibrations to the inst map.

This will create instructions with the same name as the schedules.

Parameters:

schedules (Set[str] | None) – The name of the schedules to update. If None is given then all schedules will be pushed to instructions.
qubits (Tuple[int, ...] | None) – The qubits for which to update the instruction schedule map. If qubits is None then all possible schedules defined by the coupling map will be updated. Note that this argument specifies a particular set of qubits to update instructions for. For example, if qubits is (2, 3) then only two-qubit instructions that apply to qubits 2 and 3 will be updated. Here, single-qubit instructions will not be updated.
group (str | None) – The calibration group from which to draw the parameters. If not specified this defaults to the ‘default’ group.
cutoff_date (datetime) – Retrieve the most recent parameter up until the cutoff date. Parameters generated after the cutoff date will be ignored. If the cutoff_date is None then all parameters are considered. This allows users to discard more recent values that may be erroneous.
inst_map (InstructionScheduleMap | None) – The instruction schedule map to update. If None is given then the default instruction schedule map (i.e. self._inst_map) will be updated.