Release Notes

0.9.0

Prelude

The Qiskit Experiments 0.9.0 release primarily provides compatibility with version 2.0 of the [Qiskit SDK](https://www.ibm.com/quantum/qiskit). A major change is the removal the previously deprecated support for pulse experiments and calibration due to the removal of Qiskit Pulse in Qiskit 2.0. Some other smaller changes were also needed to adapt to Qiskit 2.0 as described below. Additionally, previously deprecated code related curve fitting and restless measurements was removed. Some additional code paths have been marked as deprecated, particularly relating to ExperimentData.analysis_results() as described below.

New Features

  • Curve analysis helper functions utils.inverse_weighted_variance, utils.sample_weighted_average, and utils.shot_weighted_average were documented as public. These functions were present in previous releases but not documented as public.

  • Classes MeasLevel and MeasReturnType were added to enumerate the supported measurement levels (kerneled or classified) and return types (averaged or not) for the results of jobs run by experiments. Previously, private classes of Qiskit were inadvertently used for these purposes but they were removed in Qiskit 2.0.

Upgrade Notes

  • The way that warnings about deprecated arguments are issued has been updated to be more reliable. Previously, warnings would not be issued for deprecated arguments that were left with their default values or that were used in internal calls by other functions in the package. The result of the old behavior was mainly that arguments to ExperimentData.add_analysis_results() and ExperimentData.analysis_results() that should have previously been issuing pending deprecation warnings did not. This release still proceeds with upgrading those pending deprecations to full deprecations.

  • In preparation for Qiskit 2.0, references to BackendV1 have been guarded so that they do not cause import errors. BackendV1 is still supported for now, but support will be removed in a future release.

  • LocalReadouMitigator now provides a more specific warning if it is used with a backend without a properties() method or with a backend that does not the require readout error properties.

  • ExperimentData was updated to handle changes to qiskit.result.Result in Qiskit 2.0. With Qiskit 2.0, the result header is a dict instead of a custom class. Qiskit Experiments uses this header to store metadata about experiments’ circuits and now handles both the dict and class forms.

  • A performance issue in QuantumVolume was addressed. When Qiskit Aer is installed, QuantumVolume uses qiskit_aer.AerSimulator to simulate the outcomes of the quantum volume circuits to determine the heavy output probabilities. In its default instantiation, AerSimulator regenerates its qiskit.transpiler.Target every time it is accessed and this generation takes an appreciable amount of time. Because the target was being accessed separately for every circuit, this overhead could accumulate to over a minute in the standard 100 circuit experiment. This overhead was reduced by processing all the circuits in one pass.

  • Previously deprecated experiments involving pulse gate calibrations have been removed, due to the upcoming removal of Qiskit Pulse in Qiskit 2.0. These experiments include QubitSpectroscopy, EFSpectroscopy, Rabi, EFRabi, ResonatorSpectroscopy, RoughDrag, StarkRamseyXY, StarkRamseyXYAmpScan, StarkP1Spectroscopy, CrossResonanceHamiltonian, EchoedCrossResonanceHamiltonian, BaseCalibrationExperiment, RoughFrequencyCal, RoughEFFrequencyCal, FrequencyCal, FineFrequencyCal, RoughDragCal, FineXDragCal, FineSXDragCal, FineDragCal, FineAmplitudeCal, FineXAmplitudeCal, FineSXAmplitudeCal, HalfAngleCal, RoughAmplitudeCal, RoughXSXAmplitudeCal, and EFRoughXSXAmplitudeCal. The associated analysis and helper classes like ResonanceAnalysis, CrossResonanceHamiltonianAnalysis, DragCalAnalysis, ResonatorSpectroscopyAnalysis, and StarkCoefficients were also removed.

  • Also due to the deprecation of Qiskit Pulse, support for providing pulse gate calibrations to excite higher levels has been removed from MultiStateDiscrimination.

  • The Calibrations class and all of Qiskit Experiments’ calibration support (including gate libraries and calibration updaters and experiments) have been removed. The calibrations features were based on adjusting parameters of pulses used in gates. With the removal of pulse support in Qiskit 2.0, it no longer was feasible to keep support for features that rely on pulse gate calibrations.

  • The methods of BackendData and BackendTiming that involved pulse gate features have been removed. The removed methods were control_channel, drive_channel, measure_channel, acquire_channel, min_length, pulse_alignment, acquire_alignment, drive_freqs, and meas_freqs of BackendData and round_pulse and pulse_time of BackendTiming.

  • qiskit-dynamics has been removed from the extras extra of the package. This means that pip install qiskit-experiments[extras] will no longer install qiskit-dynamics. PulseBackend and SingleTransmonTestBackend still require qiskit-dynamics to be installed, so it must be installed separately. The reason for this change is that Qiskit Experiments aims to keep compatibility with the latest Qiskit and so will not require a package that pins the Qiskit version while Qiskit Dynamics plans to pin to Qiskit version 1.

  • The previously deprecated support for running experiments with restless measurements has been removed. The RestlessMixin class has been removed from the package and thus has also been removed from classes like RamseyXY and StandardRB on which it was previously applied.

  • The deprecated analysis option return_fit_parameters has been removed from CurveAnalysis and CompositeCurveAnalysis. This change means that the fit parameter analysis result that started with @Parameters will no longer be included in the set of analysis results. Code calling ExperimentData.analysis_results() with a numerical index, rather than a result name or using dataframe=True (the recommended pattern) may find a different result than it did before. Fit parameters should be accessed using ExperimentData.artifacts() to retrieve the fit_parameters artifact.

Deprecation Notes

  • The results argument to ExperimentData.add_analysis_results(), which had previously been marked as pending deprecation, has now been marked as deprecated. The preferred form going forward is to create analysis results by passing individual properties directly as keyword arguments to the method rather than creating separate analysis result objects and passing them to the method. To reflect the fact that a single result is added per call in this way, the method ExperimentData.add_analysis_result() has been added as an alternative to ExperimentData.add_analysis_results().

  • Passing False to ExperimentData.analysis_results() for the dataframe argument has been deprecated. Previously, passing False had been marked as pending deprecation. To preserve backwards compatibility, the default value of dataframe remains False but a future release could change the default to True. Because this is a major change to the interface, it is not planned that the default will change in the next three months (the shortest allowed deprecation cycle).

    A previously common pattern was to retrieve a single result by name from an ExperimentData object expdata like:

    result = expdata.analysis_results("T1")
print(f"T1 is {result.value}")

    which makes use of implicit returning the result directly instead of a list when there is only one match. With dataframe=True, the dataframe is not implicitly truncated so the first match must be selected. pandas.DataFrame.iloc can be used to select the first match. The following block is equivalent to the previous example:

    result = expdata.analysis_results("T1", dataframe=True)
print(f"T1 is {result.iloc[0].value}")

  • The ScatterTable properties data_allocation and labels and method get_subset_of have been deprecated. data_allocation was renamed to series_id. labels can be found by looking at the series_name of the scatter table’s dataframe. Data subsets can be obtained using ScatterTable.filter() in place of get_subset_of.

  • Support for using BackendV1 with Qiskit Experiments is deprecated. Some code paths will generate warnings when using BackendV1 but not all cases are checked. Support is planned to be removed along all support for Qiskit 1 in a future release near the end of support for Qiskit 1.4.

  • FineZXAmplitude has been deprecated. It was not deprecated along with the other pulse-related experiments in the previous Qiskit Experiments release, but it requires an ZX rotation of \(\pi / 2\) which is not easily realizable on any known providers without pulse calibrations.

  • PulseBackend and SingleTransmonTestBackend have been deprecated. These backend classes use Qiskit Dynamics to simulate quantum circuits using Qiskit Pulse with pulse-level simulation and were mainly intended for testing purposes. With the removal of pulse features in Qiskit 2.0, these classes can no longer be maintained. Their deprecation was missed in the previous round of pulse feature deprecation. While the classes are kept for one more release cycle, they require Qiskit less than 2.0 in order to function.

  • The data processing nodes RestlessNode, RestlessToCounts, and RestlessToIQ have been deprecated. These deprecations follow on the removal of RestlessMixin and complete the deprecation of restless measurement code from qiskit-experiments. In principle, users may copy the code of these deprecated nodes and use it to create a custom restless data processor for use on experiments even without support in the base Qiskit Experiments package.

API Changes for Experiment Authors

  • The Python package configuration has been moved from setup.py to pyproject.toml. As part of this move, the separate requirements files have also been moved into pyproject.toml. See the CONTRIBUTING.md file in the source repository for information on setting up a development environment if not using tox (which should continue working the same way).

0.8.2

Prelude

Qiskit Experiments 0.8.2 is a minor update to 0.8.1 to fix an issue with tracking the job status of Qiskit IBM Runtime jobs.

Bug Fixes

  • This release contains a single fix for ExperimentData job status handling.

Experiment Data Fixes

API Changes for Experiment Authors

0.8.1

Prelude

Qiskit Experiments 0.8.1 is a minor update to 0.8.0 to improve compatibility with dependencies Qiskit and CVXPY. References to code in these dependencies were updated to avoid triggering deprecation warnings, so that the code will continue to work as new versions of Qiskit and CVXPY are released. Additional examples were added to the documentation, and some typos were corrected.

New Features

Upgrade Notes

  • The readout error mitigation experiments LocalReadoutError and CorrelatedReadoutError have been updated to generate instances of the new LocalReadoutMitigator and CorrelatedReadoutMitigator classes. The experiments should continue to work as before, but any code that was using, for example, isinstance() to check object type would need to be updated to check against the Qiskit Experiments classes instead of the old Qiskit classes.

  • Minor adjustments were made to Qiskit Experiments internals to avoid deprecation warnings when using Qiskit 1.3. See #1482 and #1491.

Bug Fixes

  • Fixed ExperimentData not inferring the credentials for the IBM experiment service from a QiskitRuntimeService instance as it used to do for qiskit-ibm-provider. Previously, the IBM experiment service was set up in the ExperimentData constructor, but now it is done on first attempt to use the service, allowing more time for the service to be set explicitly or for other attributes to be set that help with inferring the credentials.

API Changes for Experiment Authors

Other Notes

0.8.0

Prelude

In this release we added support for the Qiskit primitives. Qiskit Experiments will execute circuits using qiskit_ibm_runtime.SamplerV2 by default.

Upgrade Notes

  • When only a backend is set on an experiment, qiskit_experiments.framework.BaseExperiment.run() now defaults to wrapping the backend in a qiskit_ibm_runtime.SamplerV2 and using that to execute the circuits. A new sampler argument is also accepted by run() to allow for a custom qiskit.primitives.BaseSamplerV2 instance to be used for circuit execution. run() also accepts a backend_run option which will cause the old backend.run path to be used for circuit execution. However, the backend.run() method is scheduled to be removed from qiskit-ibm-runtime in the near future.

Deprecation Notes

  • Experiments involving pulse gate calibrations have been deprecated, due to the upcoming deprecation of Qiskit Pulse in Qiskit 2.0. These experiments include QubitSpectroscopy, EFSpectroscopy, Rabi, EFRabi, ResonatorSpectroscopy, RoughDrag, StarkRamseyXY, StarkRamseyXYAmpScan, StarkP1Spectroscopy, CrossResonanceHamiltonian, EchoedCrossResonanceHamiltonian, RoughFrequencyCal, RoughEFFrequencyCal, FrequencyCal, FineFrequencyCal, RoughDragCal, FineXDragCal, FineSXDragCal, FineDragCal, FineAmplitudeCal, FineXAmplitudeCal, FineSXAmplitudeCal, HalfAngleCal, RoughAmplitudeCal, RoughXSXAmplitudeCal, and EFRoughXSXAmplitudeCal.

  • Also due to the deprecation of Qiskit Pulse, support for providing pulse gate calibrations to excite higher levels has been deprecated from MultiStateDiscrimination.

  • The Calibrations class and all of Qiskit Experiments’ calibration support is deprecated. The calibrations features were based on adjusting parameters of pulses used in gates. With the deprecation of Qiskit Pulse, these features are now also deprecated.

  • Support for running experiments in restless mode using the RestlessMixin is deprecated. With improvements in the reliability of IBM Quantum’s qubit initialization, circuit exectuion has already become reasonably fast and restless measurements do not add much performance improvement. It is expected that the restless features are little used as there has been no recent user feedback about them.

Bug Fixes

  • Qiskit Experiments was updated to be compatible with Qiskit 1.2, including removing references to QuantumCircuit._parameter_table which prevented randomized benchmarking and layer fidelity experiments from running.

0.7.0

Prelude

The Qiskit Experiments 0.7 release adds the Layer Fidelity experiment and makes some fixes and improvements.

New Features

  • Add a new experiment class LayerFidelity to measure layer fidelity and EPLG (error per layered gate), which is a holistic benchmark to characterize the full quality of the devices at scale.

    It has an experimental feature: its circuits() exceptionally returns circuits on physical qubits (not virtual qubits as usual). Its analysis class LayerFidelityAnalysis returns AnalysisResultData which contains several extra entries to help additional analyses: e.g. qubits to ease the query of sub-analysis results and reason to tell users why the quality of the analysis was "bad".

    For example, the syntax for pulling out the individual fidelities looks like below.

    df = exp_data.analysis_results(dataframe=True)
df[(df.name=="ProcessFidelity") & (df.qubits==(59, 60))].value

    See an example notebook for more examples such as how to select a best possible qubit chain to measure and how to plot EPLG as a function of (sub)chain length.

  • Added an option to plot residuals for single-figure experiments, which is enable by setting plot_residuals to True.

  • Introduced sub_plot_heights_list and sub_plot_widths_list attributes in PlotStyle for customizable subplot sizes where each list needs to sum up to 1. This feature currently works only for experiments with no subplots.

Known Issues

  • Fit parameters are not populated in composite curve analysis results and are found only in the fit summary artifact. In a future release, they will be removed from all analysis result objects and live in the artifacts only.

Upgrade Notes

  • Changes in behavior that users should be aware of when upgrading Qiskit Experiments to this version are listed below in subsections by functional area.

Package Upgrades

  • Several deprecated modules, methods, functions, and options have been removed and will no longer work:

    • The visualization module of CurveAnalysis has been replaced by the standalone visualization module. The LegacyCurveCompatDrawer has been removed from visualization.

    • The curve_drawer option to CompositeCurveAnalysis has been replaced by the plotter in the visualization module.

    • The SeriesDef dataclass has been removed and replaced by the LMFIT module.

    • The CurveData dataclass has been removed and replaced by ScatterTable’s DataFrame representation.

    • random_cliffords() and random_clifford_circuits() have been removed from CliffordUtils and replaced by StandardRB.__sample_sequence().

    • beta has been renamed to outcome_prior in the tomography utility function binomial_weights().

    • The return_data_points option has been removed from curve analysis. Data points are now automatically provided in ExperimentData objects via the curve_data artifact.

    • The default value of flatten_results in composite experiments has changed to True.

Deprecation Notes

  • Accessing experiment data artifacts by numerical index has been deprecated. Use the name or ID of the artifact instead.

Bug Fixes

  • Fixed a bug in EPG (error per gate) computation in RBAnalysis where it fails with a TypeError for backends with ECR gate as a 2-qubit basis gate (e.g. IBM Eagle processors). See #1419. for the details of the bug.

  • The gate counting for EPG in the RB analysis code was not including the inverse, so that the total number of operations per Clifford was incorrect, leading to incorrect reporting of EPG from EPC. Fixed by adding +1 for the inverse gate.

Other Notes

  • Added minimal working code examples to many experiment API pages, especially characterization experiments. The minimal working code example is a code snippet which users can copy and paste to run the experiment. Users are required to specify a backend to use the code example. By default, the backend used in the examples is a simulator such as FakeManilaV2.

0.6.1

Prelude

Qiskit Experiments 0.6.1 is a minor bug fixes release.

Bug Fixes

  • ExperimentData was updated so that running analysis a second time with replace_results=True does not result in the figure_names property having incorrect data (both old and new figure names if the names changed). See #1430.

  • BaseAnalysis was updated to respect figure_names as a keyword argument to the run() method. Previously, this argument was ignored and figure_names could only be set as an analysis option prior to calling run(). See #1430.

  • Removed a FakeBackendV2 import path which would have been incompatible with Qiskit 1.1 and above. See #1420.

0.6.0

Prelude

Qiskit Experiments 0.6 introduces numerous features and improvements. It is compatible with Qiskit 1.0. Notable changes include: refactoring the analysis results to a pandas DataFrame-based AnalysisResultTable, the ability to add artifacts of serializable data to ExperimentData, and refactoring curve fit data into a new DataFrame-based ScatterTable container that is stored by default as an artifact in ExperimentData along with the summary of fit results. New experiments include StarkP1Spectroscopy, StarkRamseyXY, and StarkRamseyXYAmpScan. StandardRB and InterleavedRB were significantly improved. The supported provider for running jobs on IBM backends is now qiskit-ibm-runtime. Using qiskit-ibm-provider is still supported but its use is deprecated.

New Features

  • New features are listed below in subsections by functional area.

New Experiments

  • New experiment StarkRamseyXY has been added. This is a variant of the RamseyXY experiment that characterizes the qubit frequency offset under a Stark tone drive.

  • New experiment StarkRamseyXYAmpScan has been added. This is a variant of the StarkRamseyXY experiment to estimate the required tone amplitude to cause a particular Stark shift. This experiment scans tone amplitude while fixing the Stark tone length, and fits the result with the dedicated fitter StarkRamseyXYAmpScanAnalysis.

  • New experiment StarkP1Spectroscopy has been added. This is a variant of T1 experiment to conduct spectroscopy of qubit relaxation at different qubit frequencies. The spectroscopy data is just visualized with the dedicated analysis StarkP1SpectAnalysis. A developer may subclass this analysis class to perform custom analysis on the spectroscopy data.

Experiment Library Features

  • Updated InterleavedRB so that it only accepts interleaved_element consisting only of instructions supported by the backend of interest.

Experiment Class Features

  • A new method BaseExperiment.job_info() has been added that will output the number of jobs the experiment is expected to be split into based on the provided backend. Refer to issue #1247 for more details.

  • experiment_type can now be easily set and retrieved from the experiment object post-construction using the experiment_type property and setter.

Analysis Class Features

  • Added a broadcast option to CompositeAnalysis. When broadcast=True is passed, this option will be applied to child experiment analyses within the class. This means it will iterate through the child analysis classes and apply the given option to each of them.

  • The generate_figures parameter has been added to CompositeAnalysis to control figure generation. By default, generate_figures is always, meaning figures will always be generated. If generate_figures is set to selective, then only figures for analysis results of bad quality will be generated. If generate_figures is set to never, then figures will never be generated. This behavior can be overridden for individual analyses by setting the analysis option plot for CurveAnalysis.

Experiment Data Features

  • Figures in ExperimentData objects can now be accessed without the .svg extension.

  • ExperimentData has been upgraded to store analysis result data in a table format with the new inline container AnalysisResultTable. In this release, the ExperimentData.analysis_results() method still returns a conventional list of AnalysisResult for backward compatibility, however, when you call the method with new argument dataframe=True it returns analysis results all in one piece with the table format. For example,

    exp = StandardRB((0,), lengths, backend)
experiment_data = exp.run().block_for_results()

experiment_data.analysis_results(dataframe=True, columns="default")

    Information contained in the returned table can be filtered with columns argument, which may take either all, default, minimal, or list of column names. Returning a list of AnalysisResult will be deprecated in a future release along with the dataframe option.

    Related to this update, ExperimentData.add_analysis_results() method now takes keyword arguments keyed on the table column names, in addition to the argument of results which is either AnalysisResult or a list of it. This allows users and developers to bypass creation of AnalysisResult instance for registering new entry in the ExperimentData instance.

    Note that the conventional AnalysisResult is originally a payload object for saving an analysis result in a remote database, as it implements a REST API for the IBM Experiment Service, which is not necessary at all in the context of experiment data analysis. In a future release, AnalysisResult will be hidden from Qiskit Experiments users.

  • ExperimentData.save() now uses the multithreading capability of the experiment service to enable faster saving times.

  • The start_datetime property of ExperimentData is now being set to the time the experiment data was created.

  • The end_datetime property of ExperimentData is now being set to the latest time a successful job terminated.

  • The creation_datetime and updated_datetime properties of ExperimentData are now being read from the server when saving the experiment.

  • All the datetime properties are now stored in UTC and converted to local time when using getters.

  • ExperimentData.save() can now raise exceptions when saving fails, unless the suppress_errors flag is set (on by default).

  • Experiments run via the qiskit-ibm-runtime provider can now be saved to and loaded from the cloud service.

Curve Fit Features

  • ScatterTable has been introduced as a drop-in replacement of CurveData.

    This is a data format to store intermediate data in curve analysis built on top of the pandas DataFrame. Each table row corresponds to a single data point, and the table contains all data points generated by the CurveAnalysis. All properties and methods of CurveData are implemented for backward compatibility, but these will be removed in the future release.

  • New analysis option fit_category is added to CurveAnalysis subclasses. This option controls which data subset within the ScatterTable is used for the curve fitting.

Calibration Features

  • A JSON data format has been added for saving a Calibrations instance. This leverages a custom JSON encoder and decoder to serialize the entire calibration data including user provided schedule templates. Output JSON data is formatted into the standard data model which is intentionally agnostic to the calibration data structure.

Visualization Features

  • The MplDrawer visualization backend has been upgraded so that it can take list of options for xlim, ylim, xval_unit, yval_unit, xval_unit_scale, and yval_unit_scale. New figure options sharex and sharey are also added. The new options are used to unkink the configuration of sub axes, and default to True for backward compatibility. By disabling these options, an experiment author can write an analysis class that generates a multi-axes figure with different plot ranges.

  • The QuantumVolumeAnalysis analysis class was updated to use QuantumVolumePlotter for its figure generation. The appearance of the figure should be the same as in previous releases, but now it is easier to customize the figure by setting options on the plotter object. See #1348.

  • New figure options were added to the visualization module: xscale and yscale. They represent parameters to the Matplotlib functions set_xscale and set_yscale: log, linear, symlog, logit, and quadratic (the latter is an additional support for quadratic scaling).

Known Issues

  • Copied ExperimentData objects don’t save their analysis results to the cloud service. See #1396.

Upgrade Notes

  • Changes in behavior that users should be aware of when upgrading Qiskit Experiments to this version are listed below in subsections by functional area.

Package Upgrades

  • Several deprecated methods and options have been removed and will no longer work:

    • Passing the qubits keyword argument or an integer qubit index to experiments is no longer allowed. Use physical_qubits keyword argument with a sequence type input.

    • The scipy_linear_lstsq and scipy_gaussian_lstsq fitters for the StateTomographyAnalysis and ProcessTomographyAnalysis classes have been removed. Use the cvxpy_linear_lstsq() and cvxpy_gaussian_lstsq() fitters instead.

    • Curve fit solvers curve_fit() and multi_curve_fit() as well as fit functions bloch_oscillation_x(), bloch_oscillation_y(), and bloch_oscillation_z() have been removed. Use the LMFIT library instead.

    • The flat_top_widths argument and experiment option of the CrossResonanceHamiltonian experiment and its subclass have been removed. Use durations instead.

    • The DumpedOscillationAnalysis class has been renamed to DampedOscillationAnalysis.

  • Dropped support for Python 3.7 and added support for Python 3.12.

  • The dependency on qiskit-terra was replaced with a dependency on qiskit. This change follows the move in upstream Qiskit to rename qiskit-terra to qiskit. The minimum required version was increased from 0.24 for qiskit-terra to 0.45 for qiskit. For more information on the renaming of Qiskit, see the Qiskit repository renaming plan and the Qiskit 1.0 migration guide.

  • With the impending deprecation of the qiskit-ibm-provider package, support for qiskit-ibm-provider is now deprecated and will be removed in the next release. Users should migrate to qiskit-ibm-runtime following the runtime migration guide. qiskit-ibm-runtime is not listed as a dependency for compatibility reasons, but users will need it to run experiments on IBM backends.

Experiment Library Upgrades

  • HalfAngleCal was changed from updating the complex amplitude of the pulse, to updating the angle in the (amp, angle) representation. When used with the FixedFrequencyTransmon library, it will continue to work seamlessly in the new representation. However, when the experiment is used with custom built pulses, which rely on the old convention of complex amp (with no angle parameter) - the experiment will fail. Most reasonable cases will raise a detailed CalibrationError explaining the change and the way to adjust to it. Some edge cases - like a custom built pulse with an angle parameter which doesn’t conform to the naming convention of Qiskit’s ScalableSymbolicPulse class, or using a loaded calibration with complex amp - will result in updating the wrong parameter.

Experiment Class Upgrades

  • Removed unnecessary circuit metadata from the builtin experiment classes. Circuit metadata such as the associated qubit indices and experiment type are separately stored in the experiment metadata, and never used in the analysis. Removal of unnecessary circuit metadata compresses the job payload and thus is expected to benefit scalability.

Curve Fit Upgrades

  • The behavior of CurveAnalysis data processing was changed. It used to raise DataProcessorError error when it encounters an experiment result which cannot be classified into any fit model, but this restriction was relaxed and the analysis continues with unclassified data. Unclassified data is just stored as-is in the ScatterTable with the null class ID assigned. Such data is ignored in the rest of analysis steps such as formatting, fitting, and visualization.

Calibration Upgrades

  • The representation of pulses in the FixedFrequencyTransmon library was changed from complex amplitude to (amp, angle) representation. All pulses now include an angle parameter, and the default values of amp are set as type float instead of complex.

  • The variables __drive_freq_parameter__ and __readout_freq_parameter__ have been removed from Calibrations. These variables were given special treatment which is inconsistent with the framework. To replace them a mechanism to define and add parameters without a schedule has been added to the basis gate library. This has the added benefit of making the API of frequency calibration experiments more consistent with the other calibration experiments. Calibration developers can now add parameters to their library that are not attached to a schedule in a meaningful way.

Deprecation Notes

  • Executing composite experiment and composite analysis with flatten_results=False by default was deprecated. To create child experiment data, please explicitly set flatten_results=False. The default value of flatten_results will be changed to True in the next release.

  • BackendData.is_simulator has been deprecated. BackendV2 does not provide a standard interface for determining if a backend uses a simulator. Calling code must determine if a backend uses a simulator through some other means. Qiskit Experiments does not treat simulator-backed backends differently from hardware backed ones.

  • Setting the option return_data_points to True in curve analysis has been deprecated. Data points are now automatically provided in ExperimentData objects via the curve_data artifact.

  • Direct access to the curve fit summary in ExperimentData has moved from analysis_results() to artifacts(), where values are stored in the data attribute of ArtifactData objects. For example, to access the chi-squared of the fit, expdata.analysis_results(0).chisq is deprecated in favor of expdata.artifacts("fit_summary").data.chisq. In a future release, the curve fit summary will be removed from analysis_results() and the option return_fit_parameters will be removed. For more information on artifacts, see the artifacts how-to.

  • Using numerical indices with ExperimentData.analysis_results(), including both integers and slices, is now deprecated. Access analysis results by analysis result name or ID instead.

  • Saving Calibrations instance into CSV file was deprecated. This only provides serialization for limited set of calibration data, and loading from the local file is not supported.

  • Calibrations.schedule_information() was deprecated. This method returns attached calibration templates in the string format, but this cannot be converted back to the original Qiskit representation. Now better serialization is provided with Calibrations.save() with JSON mode and it internally dumps these schedule in through QPY format.

  • Calibrations.load_parameter_values() was deprecated. Since saving Calibrations instance into the CSV format was deprecated, the required data file to invoke this method will be no longer generated in future calibrations instance. Full calibration instance roundtrip is now supported with the save and load method.

  • Calibrations.config() and Calibrations.from_config() were deprecated. Now canonical data representation is generated for calibration by the newly introduced save_utils module, and the legacy configuration dictionary is no longer used for JSON encoding.

Bug Fixes

  • Bug fixes are listed below in subsections by functional area.

Experiment Library Fixes

  • Fixed a bug in rb_decay() where it unintentionally raises an IndexError if all y values are below b value so that it returns 0 for the case.

  • The HalfAngle experiment’s circuits were changed so that they use combinations of rz and x instead of the less standard y gate. This change allows HalfAngle to be run on IBM backends directly. Previously, it could only be run through the HalfAngleCal subclass in combination with a Calibrations instance containing a custom calibration for the y gate. Fixes issue #1233.

  • Fixed a bug in circuit generation for three or more qubit Randomized Benchmarking where sampled Cliffords may be changed during their circuits synthesis (in the worst case, the resulting circuits may use qubits not in physical_qubits). See issue #1279 for additional details.

  • Resolved a serialization issue that affected Rabi experiments when running it through the backend provider using custom amplitudes provided as a numpy array.

  • Resolved an issue that caused QV experiments to fail when executed via the backend provider using Qiskit for calculating ideal probabilities instead of Aer.

  • Resolved a serialization issue that affected DRAG experiments with integral beta values specified.

Experiment Data Fixes

  • Fixed pickle deserialization of ExperimentData objects. Previously, ExperimentData objects could be serialized and deserialized using Python’s pickle module, but deserialized objects were not completely restored and an exception would be raised when doing some operations like running analysis on the restored object. See #1326.

  • Fixed a bug in ExperimentData._add_job_data() that caused job id related test fails.

  • Fixed a bug in ExperimentData which caused experiment saves to the cloud service to fail when the metadata is large.

Visualization Fixes

  • Figures loaded from the experiment service are now rendered correctly in Jupyter Notebook.

API Changes for Experiment Authors

  • Added the _create_figures() method to the CurveAnalysis base class. A curve analysis subclass can overwrite this method to customize the output figures. The method is called with the ScatterTable containing all intermediate data points generated during the curve analysis.

  • Added the QiskitExperimentsTestCase.assertEqualExtended() method for generic equality checks of Qiskit Experiments class instances in unittests. This is a drop-in replacement of calling the assertTrue with QiskitExperimentsTestCase.json_equiv(). Note that some Qiskit Experiments classes may not officially implement equality check logic, although objects may be compared during unittests. Extended equality check is used for such situations.

  • The following unittest test case methods will be deprecated:

    • QiskitExperimentsTestCase.json_equiv()

    • QiskitExperimentsTestCase.ufloat_equiv()

    • QiskitExperimentsTestCase.analysis_result_equiv()

    • QiskitExperimentsTestCase.curve_fit_data_equiv()

    • QiskitExperimentsTestCase.experiment_data_equiv()

    One can now use the is_equivalent() function instead. This function internally dispatches the logic for equality check.

  • The default behavior of QiskitExperimentsTestCase.assertRoundTripSerializable() and QiskitExperimentsTestCase.assertRoundTripPickle() when check_func is not provided was upgraded. These methods now compare the decoded instance with is_equivalent(), rather than delegating to the native assertEqual unittest method. One writing a unittest for serialization no longer need to explicitly set checker function.

  • A device_component field that contains a list of device components used in the experiment has been added to experiment metadata. Experiments with non-qubit components should override the default value of all qubit components. See the custom experiments tutorial for more details.

Other Notes

  • Display a warning when running an analysis on ExperimentData objects which do not contain data.

  • Qiskit 0.23.0 began phasing out support of complex parameters in the Pulse module. Mainly, all library symbolic pulses were converted from complex amplitude representation to a duo of real (float) parameters (amp, angle). To avoid problems, Qiskit Experiments adopted this convention.

    Changes were made to FixedFrequencyTransmon and HalfAngleCal (see upgrade section). With the exception of HalfAngleCal, all library experiments should continue to function as they did before (even with complex amp). When used with the FixedFrequencyTransmon library, HalfAngleCal will also continue working as before.

    Eventually, support for complex parameters will be dropped altogether, and it is thus pending deprecation - including for saving and loading calibration data with complex values.

  • A new set of optional dependencies have been split off from the developer dependencies and can be installed separately as qiskit-experiments[extras]. These are packages that enable optional experiment features such as scikit-learn-based discriminators. Qiskit Dynamics and Qiskit Aer have also been marked as optional in this manner.

  • Figure names have been updated to include qubit indices up to the first five device components in the experiment, with format StandardRB_Q0_Q1_Q2_Q3_Q5_b4f1d8ad.svg. For composite experiments where flatten_results is set to True, the head of the figure name is now the class name of the experiment instead of ParallelExperiment or BatchExperiment, such that the figure name is the same when flatten_results is False. The behavior when a figure name is repeated and overwrite is False has changed from throwing an exception to appending a numerical suffix to the figure name like StandardRB_Q0_Q1_Q2_Q3_Q5_b4f1d8ad-1.svg.

  • Figure metadata now includes experiment_type and device_components.

0.5.4

Prelude

Qiskit Experiments 0.5.4 is a minor improvement and fixes release.

Bug Fixes

  • Fixed calculation of weight for curve fitting. Previously the weights of data points to obtain the residual of fit curve were computed by the inverse of the error bars of y data. This may yield significant weights on certain data points when their error bar is small or zero, and this can cause the local overfit to these data points. To avoid this edge case of small error bars, computed weights are now clipped at 90 percentile. This update might slightly change the outcome of fit.

Other Notes

  • Removed the reset instruction from the beginning of tomography experiments. Since qubits are usually reset between circuits, this change should have no impact on tomography experiments, but it should allow backends that do not provide a reset instruction to run tomography experiments. See #1250.

0.5.3

Prelude

Qiskit Experiments 0.5.3 is a minor improvement and fixes release.

New Features

  • A new experiment option circuit_order was added to InterleavedRB. It allows to change the order of the reference and the interleaved circuits and hence slightly alter the impact of noise on interleaved RB results. The default value is set to "RIRIRI" that alternate a reference and an interleaved circuit.

Bug Fixes

  • Changed the ordering of circuits generated by InterleavedRB back to RIRIRI (R: Reference, I: Interleaved) order. It was accidentally changed into RRRIII order in #898. Before that, it had been RIRIRI order.

0.5.2

Prelude

Qiskit Experiments 0.5.2 is a minor bug fix and performance improvement release.

New Features

  • A new method qiskit_experiments.calibration_management.Calibrations.has_template() has been added to Calibrations to check if a template schedule exists for a particular set of qubits.

Bug Fixes

  • FineXDragCal and EFRoughXSXAmplitudeCal were updated to attach sx and x calibrations to their circuits, respectively. Previously, they only attached the x and x12 calibrations that they were calibrating. See issue #1158.

Other Notes

  • The performance of experiment analysis for parallel experiments has been improved significantly due to improved results marginalization. See PR #1144 for more details.

0.5.1

Prelude

Qiskit Experiments 0.5.1 is a minor bug fix release.

Bug Fixes

  • Added a missing backend parameter to RoughEFFrequencyCal and exposed it in the experiment library.

  • Fixed error generating circuits for BaseCalibrationExperiment subclasses when the backend instance had no coupling map. Fixed #1116.

  • Fixed a deprecated Matplotlib MarkerStyle usage in the visualization module that was causing warnings in Matplotlib 3.6+.

0.5.0

Prelude

The Qiskit Experiments 0.5 release brings various improvements and bug fixes. Notable changes include the visualization module for drawing figures, which replaces the previous plotting functionality. The speed of randomized benchmarking experiments has been significantly improved. The qubit and qubits input to experiments has been regularized to physical_qubits, and support for qiskit-ibmq-provider has been deprecated in favor of qiskit-ibm-provider. New experiments added include MultiStateDiscrimination, ZZRamsey, MitigatedStateTomography, and MitigatedProcessTomography, along with significant improvements to other tomography experiments. The documentation has been significantly refactored and introductory tutorials have been added.

New Features

  • Added new class T1KerneledAnalysis. This class is used for the T1 experiment with the option meas_level=MeasLevel.KERNELED. The analysis normalizes the data and fixes its orientation.

  • Added a new visualization module to plot figures and draw onto figure canvases. The new module contains plotters and drawers, which integrate with CurveAnalysis but can be used independently of the analysis classes. This module replaces the old and now deprecated qiskit_experiments.curve_analysis.visualization submodule.

  • Added a new IQ plotting class IQPlotter for plotting IQ/level-1 data (individual shots and their average) and a discriminator that classifies the data into states.

  • Added a new image() method to BaseDrawer and MplDrawer to plot two-dimensional images on a figure canvas.

  • New BaseCurveAnalysis option average_method has been added. This option modifies an averaging technique for y values over the same x values. It defaults to sample for the RB experiments and shots_weighted for the rest of analysis. Previously the setup was hardcoded in the _format_data method of the analysis class, and no statistical difference has been introduced with introduction of this option.

  • A new basis gate library called EchoedCrossResonance has been added.

  • Added a new initial_circuit option to ResonatorSpectroscopy for appending before measurements. This can be used to run resonator spectroscopy with different qubit states.

  • Added a new sklearn discriminator class SkQDA.

  • Added pulse simulator backends PulseBackend and subclass SingleTransmonTestBackend that use Qiskit Dynamics to simulate pulse schedules included in the calibrations attached to transpiled quantum circuits. The backend is capable of simulating level one (IQ) and level two (counts) data. The main purpose of this backend is to make the test suite more realistic and allow for tutorials that do not require hardware backends.

  • qiskit-experiments has been marked as compatible with Python 3.11 in the package metadata. qiskit-experiments currently tests against Python 3.7, 3.8, 3.9, 3.10, and 3.11.

  • The algorithm to estimate fit parameter guesses in RamseyXYAnalysis has been upgraded. The previous algorithm was not robust to experiment outcomes with low frequency, where Ramsey X and Y curves almost remain at P=1.0 and 0.5, respectively. The new algorithm also offers reliable initial guesses for such situations. In addition, the number of frequency guesses has been increased to cover the uncertainty of FFT.

  • Added a backend init kwarg to the LocalReadoutError and CorrelatedReadoutError experiments, and the physical_qubits kwarg has been made optional. If a backend is supplied without specifying physical qubits, the experiment will be initialized on all qubits for the backend.

  • Added a new experiment option for batch experiments called separate_jobs. If set to True, then circuits of different sub-experiments will be routed to different jobs. Default value is False.

  • Added a max_circuits experiment option to BaseExperiment to allow specifying the max number of circuits per job when running an experiment. If set to None (default), the max circuits per job is determined by the backend. If both the option value and backend value are not None, the miniminum of the two values will be used for job splitting.

  • Added backend, analysis, and target init kwargs to the StateTomography and ProcessTomography experiments. These allow specifying the intended backend, a custom analysis class, or a custom target for fidelity calculations when initializing the experiments.

  • Improved LocalMeasurementBasis and LocalPreparationBasis tomography basis classes support for initializing a noisy basis for performing state preparation and measurement error mitigated StateTomography and ProcessTomography experiments.

    For preparation bases, a noisy reset operation on a specific qubit, or subset of qubits, can now be input as a quantum channel, and the noisy prepared states are generated by applying the ideal instructions to the noisy initial state.

    For measurement bases, a noisy POVM or quantum channel can be supplied for the 0-index basis (typically the Z-basis), and other bases index POVMs will be generated by applying the ideal inverse instructions to the noisy POVMS.

  • Added support for conditional tomographic reconstruction to the StateTomography and ProcessTomography experiments.

    There are three types of conditioning that can be used independently or together in any combination for reconstruction of a state or channel as a list of components conditional on these values.

    The conditional_circuit_clbits init option can be used to specify any subset of clbits in an tomography circuit containing clbits to be conditioned on when peforming the tomographic reconstruction. The conditioning outcome value of the clbits is stored in the analysis results extra field.

    The conditional_measurement_indices analysis option can be used to condition on the measurement basis index and outcome value of a specific subset of tomographic basis measurements. The conditioning basis index and outcome value are both stored in the analysis results extra field.

    The conditional_preparation_indices analysis option can be used to condition on the preparation basis index of a specific subset of tomographic basis preprations. The conditioning basis index is stored in the analysis results extra field.

  • Adds an option to StateTomographyAnalysis and ProcessTomographyAnalysis to bootstrap error bars on state and process fidelity analysis results. This can be activated by setting the target_bootstrap_samples analysis option to a value.

    Note that bootstrapping involves re-running the full tomography fit on re-samples of tomography outcome data for each measurement basis and hence the total analysis time will increase linearly with the number of bootstrap samples.

  • The CrossResonanceHamiltonian experiment and its subclass now accept durations with default values. Note that values should be provided in units of seconds rather than samples, and must include pulse ramps at edges. Default values with linear increment are generated according to new experiment options, min_duration, max_duration, and num_durations, when the durations are not explicitly provided. The default values are chosen by assuming a ZX rate of around 1 MHz which is typical for IBM Quantum backends. User can update these option values as well as provide full durations to tailor experiment settings to their device. Total durations should be carefully chosen not to overflow the waveform memory when the experiment is run on a real hardware. With this update, the minimum example code to run this experiment might be

    from qiskit_experiments.library.characterization import CrossResonanceHamiltonian

expr = CrossResonanceHamiltonian(qubits=(0, 1), amp=0.3, backend=backend)
exp_data = expr.run()

    where the durations to scan are implicitly set by experiment options.

  • A new experiment ZZRamsey has been added to measure the ZZ coefficient between a pair of qubits.

Known Issues

  • The PulseBackend only supports single qubit operations and will be upgraded in the future.

Upgrade Notes

  • Several deprecated methods and options have been removed and will no longer work:

    • BaseExperiment.analysis_options has been removed. experiment.analysis.options should be used instead.

    • The __analysis_class__ attribute of BaseAnalysis has been removed. Use the analysis kwarg of BaseExperiment.__init__ to specify a default analysis class.

    • The component_experiment_data() method has been removed from ExperimentData and replaced by ExperimentData.child_data().

    • The CompositeExperiment.component_analysis method has been removed. Component analysis classes should be directly accessed using CompositeAnalysis.component_analysis().

    • The library argument to Calibrations has been removed and replaced by libraries.

    • The class attribute CurveAnalysis.__fixed_parameters__ has been removed. The fixed_parameters analysis option should be set instead.

    • The method CurveAnalysis._data() has been removed.

    • The CurveAnalysis attribute __series__ has been removed and is replaced by the constructor argument.

    • The FineDragAnalysis, FineFrequencyAnalysis, and FineHalfAngleAnalysis analysis classes have been removed and replaced by ErrorAmplificationAnalysis.

    • Randomized benchmarking utility functions get_error_dict_from_backend(), count_ops(), gates_per_clifford(), calculate_1q_epg(), and calculate_2q_epg() have been removed from RBUtils and replaced by methods in the RB experiment and analysis themselves.

    • The error_dict analysis option of RBAnalysis has been removed and merged into the analysis option gate_error_ratio.

  • Transpilation in the calibration experiments has been upgraded. Calibration experiments define a carefully chosen set of gates and pulses that the transpiler should not modify. If these gates are modified by transpilation the results may be unusable. BaseCalibrationExperiment now defines its own transpilation to ensure a proper execution of the experiments. Transpile options are no longer needed for calibration experiments.

  • The default transpile option value of optimization_level for RB experiments (StandardRB and InterleavedRB) was changed from 0 to 1 in order to reduce the number of gates in transpiled circuit and hence circuit generation/excution time and circuit sample variance in P(0) value. This is not an API change but, after this change, you will observe slower decay curves than before if you use the default configuration. And if you want to reproduce the results you obtained before this change, you may need to set optimization_level=0 with set_transpile_options().

  • qiskit-ibmq-provider is deprecated and has been dropped as a requirement. Interactions with IBM backends should use the qiskit-ibm-provider package instead (must be installed separately; see the migration guide for more details).

  • The qiskit_experiments.test.t2hahn_backend.T2HahnBackend was refactored to use the simulator from qiskit-aer which provides better performance. As part of the refactoring, support was removed for passing qubit parameters (e.g. t2hahn, frequency, initialization_error, etc.) as single element lists when the backend has more than one qubit. These arguments need to be passed as numbers that apply to all qubits or sequences of numbers with one entry for each qubit. If passing numbers for a backend to represent more than one qubit, at least one parameter must be passed as a sequence or the num_qubits parameter must be passed to indicate how many qubits the backend should simulate. Additionally, passing None for these arguments was deprecated. The value that makes that option have no effect should be used instead (for example, 0.0 for initialization_error).

  • Renamed the qubits, measurement_qubits, and preparation_qubits init kwargs of StateTomography, ProcessTomography, and TomographyExperiment to physical_qubits, measurement_indices and preparation_indices respectively. This is to make the intended use of these kwargs more clear as the measurement and preparation args refer to the index of circuit qubits in the physical qubits list, not the physical qubit values themselves.

  • The automatic overriding of the default CVXPY SDP solver for the cvxpy_gaussian_lstsq() and cvxpy_linear_lstsq() has been disabled and will now use the default SDP solver of CVXPY unless a custom solver is set using the fitter_options analysis options.

  • The weights kwarg of the cvxpy_linear_lstsq() and scipy_linear_lstsq() tomography fitters has been changed to accept a weights array the same shape as the supplied outcome_data array.

  • The Tphi has been changed to use T2Hahn as the default T2 estimate because it provides a more meaningful measurement on superconducting devices. An option t2type has been added to allow the user to toggle between using \(T_2^*\) from T2Ramsey by specifying “ramsey” or \(T_2\) from T2Hahn, which is the default value “hahn”.

Deprecation Notes

  • Providing data_sort_key directly to the LMFIT model to instantiate CurveAnalysis has been deprecated. This option is not officially supported by the LMFIT, and thus curve analysis cannot guarantee this option is properly managed in all LMFIT model subclasses.

  • Experiment constructor arguments qubit and qubits have been renamed physical_qubits. For the qubit case, the argument type has changed from an integer to a sequence with a single integer. For example, FineXAmplitude(0) becomes FineXAmplitude([0]).

  • The qubits, measurement_qubits, and preparation_qubits init kwargs of StateTomography, ProcessTomography, and TomographyExperiment have been deprecated. They have been replaced with kwargs physical_qubits, measurement_indices and preparation_indices respectively. The renamed kwargs have the same functionality as the deprecated kwargs.

  • The flat_top_widths argument and experiment option of CrossResonanceHamiltonian experiment and its subclass have been deprecated and will be removed in Qiskit Experiments 0.6.

  • Two helper methods CliffordUtils.random_cliffords() and CliffordUtils.random_clifford_circuits() have been deprecated. Their functionality are now incorporated into StandardRB.__sample_sequence().

Bug Fixes

  • Fixed a bug where old analysis results were saved in the case of a failed analysis. Now analysis results will be cleared before running _run_analysis(). As a result, when analysis fails, an empty analysis result will be saved to the database service.

  • Updated querying of Backend metadata to support the look up of qubit T1 and measurement drive frequency, in order to support BackendV2 backends. The look up of the latter is qiskit-ibm-provider specific. This change fixed errors failing to find these properties when using ResonatorSpectroscopy (issue #1099) and when using restless measurements with BackendV2 backends.

  • Fixed a bug where redoing DragCalAnalysis.run() generated wrong fit models.

  • Fixed a bug where CurveAnalysis tests would fail with matplotlib 3.6.0 owing to a deprecated function call used in MplCurveDrawer. The new MplCurveDrawer no longer uses the deprecated function.

  • Fixed a bug where Calibrations was not updated when calibration experiments were run through the composite experiment framework.

  • Fixed a bug in the LocalReadoutError experiment where analysis would fail when run on an ideal simulator with no readout error. See Issue #992 for additional details.

  • The importing of scikit-learn was moved from module-level imports inside of try blocks to dynamic imports at first usage of the scikit-learn specific feature. This change should avoid errors in the installation of scikit-learn from preventing a user using features of qiskit-experiments that do not require scikit-learn. See #1050.

  • Fixed BackendData.coupling_map() and BackendData.drive_freqs() raising exceptions when the underlying backend has None for its coupling and qubit property entries. Also, changed BackendData.control_channel() to return an empty list rather than None when there is no control channel data. See #1035.

  • Fixed qpy serialization and deserialization of tomography experiments. The barrier instructions in tomography experiments were created with the wrong Python type which qpy did not support. This issue was most acute when using qiskit-ibm-provider which submits circuits to the provider using qpy. There could have been subtler issues with circuit timing using a different provider if the barriers were not separating important circuit instructions. See #1060.

  • A RuntimeWarning will no longer be generated by numpy when running a data processor on level one data. See #1071.

  • Fixed a bug where the EchoedCrossResonanceHamiltonian experiment overestimated Hamiltonian coefficients by a factor of 2.

API Changes for Experiment Authors

  • To map experiment result data to a particular LMFIT model in CurveAnalysis, an author must provide the data_subfit_map analysis option rather than directly binding data_sort_key with the target LMFIT model. The data_subfit_map option is a dictionary keyed on the model name. For example,

    class MyAnalysis(CurveAnalysis):

  def __init__(self):
    super().__init__(
      models=[
        lmfit.models.ExpressionModel(expr="x+a0", name="expr1"),
        lmfit.models.ExpressionModel(expr="x+a1", name="expr2"),
      ]
    )

  @classmethod
  def _default_options(cls) -> Options:
    options = super()._default_options()
    options.data_subfit_map = {"expr1": {"tag": "1"}, "expr2": {"tag": "2"}}
    return options

    As shown in above, the dictionary that had been attached to each LMFIT model is now moved to the data_subfit_map option.

Other Notes

  • The package documentation has been updated with introductory tutorials and how-tos for solving specific problems. It is now refactored into four sections: learning tutorials, how-to guides, experiment manuals, and the API references.

  • The internal curve analysis helper functions in curve_analysis.data_processing have been moved to curve_analysis.utils.

  • The Calibrations class has been updated to use the reference mechanism in Qiskit Pulse in which a schedule can refer to another schedule only by name.

  • An analysis option reps in DragCalAnalysis was dropped. Now analysis is bootstrapped with circuit metadata and setting this value no longer impacts the analysis result. This upgrade doesn’t introduce any breaking API change for existing experiments.

  • Improved the performance of circuit generation in 1Q/2Q randomized benchmarking experiments (about 10x speedup). That is mainly achieved by the following two updates in their implementation:

    • Custom transpilation of circuits (mapping circuits to physical qubits without using transpile),

    • Integer-based Clifford operations (especially sparse lookup table with triplet decomposition for 2Q Clifford circuits).

  • NumPy runtime warning for zero division has been suppressed in CurveAnalysis. This warning could occur in the edge case where the experiment data may contain data point with zero uncertainty. Such data point is safely ignored by LMFIT, since it may apply infinite fit weight. This runtime warning suppression makes standard error cleaner.

0.4.0

Prelude

The Qiskit Experiments 0.4 release includes major improvements to the CurveAnalysis class and other bug fixes and improvements. The database service has switched to the qiskit-ibm-experiment provider. Several new data processing nodes have been added.

New Features

  • Added a new class, BackendData, which provides a common access inferface for both BackendV1 and BackendV2 data fields, since those classes do not share the same interface. The BackendData can be called on a backend and used immediately, and it is also automatically stored as the _backend_data field of BaseExperiment. Note that not all data fields are currently accessible via BackendData; to access additional fields, the corresponding method should be added to BackendData with correct treatment for both V1 and V2 backends.

  • The CurveAnalysis class has been modified to delegate the core fitting functionality to the LMFIT package. Fit curves are specified using LMFIT Model objects. For multi-curve fitting a list of models can be used.

    A new analysis option fit_method has been added to allow a user to select the fitting algorithm used by the LMFIT minimizer. The default fit method is "least_squares". Analysis class author can flexibly define new analysis instance with LMFIT Model objects. See LMFIT documentation for user guide.

  • New curve analysis baseclass CompositeCurveAnalysis has been added. This curve analysis variant offers a framework to fit experiment outcomes with different independent fit models. For example, if you define an experiment scanning a parameter with different conditions, e.g. with different control qubit states in some two-qubit gate experiment, the composite curve analysis can implement the experiment with simpler code compared with writing a conventional batch experment. See class documentation for more details.

  • New options filter_data has been added to CurveAnalysis and its subclass. This dictionary provides a set of required metadata so that the analysis can filter experiment results input to the fitter. Curve analysis checks experiment result metadata, originating in the experiment circuit metadata, and the measure outcomes with matched metadata are only used for the fitting.

  • The figure_title option has been added. This allows user to show an arbitrary string in the output figure title. See the example code below to learn how to set the option.

    exp = MyExperiment(...)
exp.analysis.drawer.set_options(figure_title="Qubit0")

  • plot_options has been added. This was conventionally included in the SeriesDef dataclass, which was static and not configurable. Now end-user can update visual representation of curves through this option. This option is a dictionary that defines three properties, for example,

    exp = MyExperiment(...)
exp.analysis.drawer.set_options(
  plot_options={
    "curve1": {"color": "r", "symbol": "o", "canvas": 0},
    "curve2": {"color": "b", "symbol": "x", "canvas": 1},
  }
)

    The dictionary is keyed on the curve name that should match with the name property of the LMFIT models provided to the curve analysis. color and symbol are the color and marker of the curves and the scatter plots, respectively. canvas specifies the sub-axis index, which is available when multi-axis plot is enabled.

  • A new data processing node DiscriminatorNode is added. This node wraps a pre-trained discriminator so that discrimination can be built into the data processing chain. The discriminator node is initialialized from a discriminator or list thereof which are objects that must have a predict method predict(x) -> y as is common in SKlearn. Here, x is a list of IQ points and y are the labels assigned to each point.

  • A new data processing node RestlessToIQ is added to process restless level one data, i.e., IQ data, in addition to the existing abstract class RestlessNode and RestlessToCounts for processing restless counts.

Upgrade Notes

  • Several deprecated methods and options have been removed and will no longer work:

    • BaseExperiment.set_analysis_options() has been removed and should be replaced with BaseAnalysis.set_options().

    • The curve_plotter option for CurveAnalysis.set_options() has been removed and replaced with curve_drawer.

    • The curve_fitter option for CurveAnalysis.set_options() has been removed, now you can directly override _run_curve_fit() instead.

    • Setting style and drawer options with CurveAnalysis.set_options() has been disabled. Analyses should use drawer.set_options instead.

    • The FitVal class has been removed and replaced with the uncertainties package.

    • Boolean values for the analysis kwarg in BaseExperiment.run() have been disabled. Use analysis=default instead of analysis=True, and analysis=None instead of analysis=False.

    • BaseExperiment.run_analysis() has been removed. Use BaseAnalysis.run() instead.

    • BaseExperiment._postprocess_transpiled_circuits() is removed. Use BaseExperiment._transpiled_circuits() instead.

    • BaseExperiment.set_analysis_options() method has been deprecated, use the BaseAnalysis.set_options() method for the experiments analysis class instead.

    • The timeout kwarg of ExperimentData.add_data() has been removed. Timeout for adding jobs is now handled by the ExperimentData.add_jobs() method.

    • Adding data from jobs using ExperimentData.add_data() has been disabled. This method should now only be used to add data from Qiskit result objects or raw data dicts. Job data should now be added using ExperimentData.add_jobs() instead.

  • A new result class CurveFitResult is introduced. This class stores a richer context of curve fitting overview with several extra statistics. This is the minimum attributes of the LMFIT MinimizerResult with some extention. Fit parameters in UFloat representation are also stored while keeping the correlation information, which is accessible with the .ufloat_params property. Note that the value of the first analysis result entry titled with @Parameters_* has been replaced with this data format. This entry had been just a list of fit values in Python float format with covariance matrix separately stored in .extra metadata. Comparing with the conventional data, new class CurveFitResult provides users with a better understanding of the analysis outcome. New object has prettyprint mechanism.

  • The RoughDrag characterization experiment has been upgraded with more flexibility. This experiment combines multiple DRAG parameter scans (curves) for different unit sequence reptitions. Conventionally this number is limited to three curves, however, now we can define more than three curves. The corresponding fit model is dynamically generated based on new fit option reps in the associated analysis DragCalAnalysis. This may sometimes provide better accuracy for estimating the DRAG beta parameter.

  • The implementations of several methods in BaseCurveAnalysis have been moved to its subclass CurveAnalysis. BaseCurveAnalysis._run_data_processing(), BaseCurveAnalysis._format_data(), and BaseCurveAnalysis._run_curve_fit() have been turned into abstract methods, and BaseCurveAnalysis._generate_fit_guesses() has been moved to CurveAnalysis. There is no net upgrade on the behavior of curve analysis subclasses, since BaseCurveAnalysis is an abstract class.

  • The handling of communication with the database has been transferred to the new qiskit-ibm-experiment package and does not rely on the soon to be deprecated qiskit-ibmq-provider package. In addition, The ExperimentData and DbExperimentData classes were merged, and the inner handling of experiment data was somewhat simplified. This should not have any effect on the current codebase and its usage of ExperimentData.

  • Added a FigureData class for adding metadata to analysis result figures. Figures added to ExperimentData are now stored using this class. The raw image object (SVG or matplotlib.Figure) can be accessed using the FigureData.figure attribute.

    Note that currently metadata is only stored locally and will be discarded when saved to the cloud experiment service database.

  • The DumpedOscillationAnalysis class has been deprecated and will be removed soon. Use the DampedOscillationAnalysis class going forward.

Deprecation Notes

  • Multiple methods, classes and functions in curve analysis have been deprecated and replaced with using functionality of the LMFIT library. These include:

    • Curve fit solver curve_fit() and multi_curve_fit()

    • Dataclass of the curve fit result FitData()

    • Some fit functions dedicated to a particular curve analysis in the module fit_function. Now curve analysis author can define arbitrary fit functions callable or string with LMFIT models, not limited to functions in this module.

Bug Fixes

  • Fixed a bug that caused analysis to sometimes run after job or previous analysis failure.

  • The .init_params value of the CurveFitResult has been fixed. This value was copied from the LMFIT MinimizerResult.init_values, however this is not the initial parameters set to the solver. Now correct initial parameters are set to CurveFitResult.init_params.

  • Fixed broken curve analysis output figure when multi canvas mode is enabled. Currently this feature is only used by CrossResonanceHamiltonianAnalysis. It has been plotting all series data in the same canvas due to the bug.

  • Initial guess function for the randomized benchmarking analysis rb_decay() has been upgraded to give accurate estimate of the decay function base.

  • The enable_restless() method of the RestlessMixin class now has the non-default option to supress errors when T1 values are lower than the repetition dely. This allows users to accomodate cases when backends report erronous T1 values.

  • Do not adjust timing constraints in experiments T1, T2Hahn, T2Ramsey, and RamseyXY. This adjustment was needed to supply missing timing constraints information for IBM backends but is not needed now and can lead to problems (see #881).

0.3.1

New Features

  • The class MockIQBackend for testing has been updated to support multiple qubits. It now takes lists of IQ cluster centers and widths as input, and specific backends are now defined as subclasses of MockIQExperimentHelper.

Bug Fixes

  • Fixes a bug where instantiating the CrossResonanceHamiltonian experiment without specifying the cr_gate and backend init kwargs raises an exception.

  • Fixes a visualization error in the figure produced during analysis of CrossResonanceHamiltonian when multi-canvas plotting mode is enabled.

  • Fixes an issue with marginalization of kerneled and discriminated memory in CompositeAnalysis not working correctly. This fixes ParallelExperiments not working correctly for level-1 measurement data.

  • Fixes a bug with JSON serialization of ExperimentData due to Qiskit backend and service objects not being JSON serializable. These properties are now set to None in the serialized experiment data.

0.3.0

Prelude

The Qiskit Experiments 0.3 release includes several bug fixes and improvements and several new experiments added to the library. Added experiments include readout error, resonator spectroscopy, two-qubit fine amplitude, and several characterization experiments. Experiments can now be run restlessly without resetting. There are also numerous changes and improvements to the BaseExperiment, ExperimentData, CurveAnalysis, and composite experiment classes to improve JSON serialization, handling of metadata, accessing the status of jobs and experiments, and the storing and loading of experiments to and from the IBM experiment database service.

New Features

  • The curve fit parameter guess function rb_decay() has been added. This improves the initial parameter estimation of randomized benchmark experiments.

  • Added a flatten_results init kwarg to CompositeAnalysis, CompositeExperiment, ParallelExperiment, and BatchExperiment that if set to True flattens all analysis results and figures from component experiment analysis into the main ExperimentData container, and does not save the individual child data components.

    Note that for nested composite experiments setting flatten_results=True will recursively set the same value for all component experiments that are also composite experiments.

  • MplCurveDrawer has been added for curve analysis visualization. This class instance is JSON serializable with the experiment encoder and it implements public methods to draw analysis results in several different formats. Its instance is attached to CurveAnalysis instance as an analysis options curve_plotter. This class is a drop-in replacement of MplDrawSingleCanvas and MplDrawMultiCanvasVstack. This instance has dedicated drawing options. New option subplots, which is a tuple of two integer representing (n_rows, n_cols), defines arbitrary 2D array subplots without using MplDrawMultiCanvasVstack.

  • Drawing options are moved from CurveAnalysis.options to MplCurveDrawer.options.

  • Added a BaseExperiment._finalize() method to BaseExperiment which is after configuring any runtime options, backend, or analysis classes but before generation and execution of experiment circuits during BaseExperiment.run.

    This method is intended to be overridden in experiment subclasses if they need to configure any analysis or runtime options based on a combination of properties of the experiment, for example some combination of backend, experiment and run options.

  • Improved handling of job and analysis processes in ExperimentData(). Verbose logging information on execution of analysis callbacks in an experiment can enabled by setting the qiskit_experiments log level to DEBUG.

  • Added ExperimentData.jobs() method for returning a list of Qiskit Jobs for a running or finished experiment.

  • Added ExperimentData.job_status() method for returning the status of Qiskit Job execution for an experiment. This returns a JobStatus enum class value.

  • Added ExperimentData.cancel_analysis() method to allow cancelling pending analysis callbacks. Note that analysis callbacks that have already started running cannot be cancelled.

  • Added ExperimentData.add_jobs() method for adding one or more Qiskit jobs to experiment data. This method takes an optional timeout kwarg that when used will automatically cancel all non-finished jobs that exceed the alloted time.

  • Added enum classes for experiment, job, and analysis status.

  • Exposed and expanded the class FakeService. The fake service will allow enhanced testing of qiskit-experiments and external packages.

  • A new mixin class RestlessMixin is added that enables experiments to run in restless measurement mode, where the qubits are not reset after each measurement.

  • A new data processing node to marginalize qubit counts is introduced. This node is, for instance, used in the data processing of a fine ZX amplitude experiment run with restless measurements.

  • A new fine amplitude experiment for two qubits is added. This experiment accepts a two-qubit gate with on rotation angle as parameter.

  • Added two new experiments (LocalReadoutError and CorrelatedReadoutError) for characterizing the readout error of devices.

  • Added a new experiment ResonatorSpectroscopy to run spectroscopy on readout resonators. This is done by attaching a custom pulse-schedule to the measure instruction. Note that the resonator spectroscopy experiment may cause errors on backends that do not support circuit instructions with measurement schedules attached to them.

  • A new data processing node ToAbs is introduced to take the absolute value of IQ points. This node is needed to analyse readout resonator spectroscopy IQ data since it rotates around in the IQ plane but can also be used in other contexts.

  • Added support for JSON serialization of ExperimentData objects. These objects can be serialized using the ExperimentEncoder and ExperimentDecoder classes.

    Note that serialization of general experiment results requires that the individual option values and analysis result types are themselves JSON serializable using the encoder and decoder classes.

  • Added support for pickling ExperimentData objects using the Python pickle module.

  • Added a T2Hahn class for composing and running Hahn Echo experiment to estimate T2.

  • Added a T2HahnAnalysis class for analyzing experiment data from T2Hahn.

  • Added a T2HahnBackend class for testing which simulates T2 noise statistics.

  • Added new tomography basis classes LocalPreparationBasis and LocalMeasurementBasis for constructing N-qubit bases from the tensor product of 1-qubit instructions. These classes can optionally be initialized with custom qubit-specific density matrix or POVM element states for respectively for tomographic reconstruction.

  • Added a new experiment Tphi. It computes the pure dephasing time and is computed as \(1/T_\varphi = 1/T_{2*} - 1/2T_1\). It is implemented as a composite experiment with sub-experiments T1 and T2Ramsey. The new classes are: Tphi - class defining the Tphi experiment.

    TphiAnalysis - class for Tphi analysis.

    TphiBackend - fake backend for running a Tphi experiment, based on the fake backends for T1 and T2Ramsey.

  • Added BaseExperiment._transpiled_circuits() which returns a list of experiment circuits, transpiled. It can be overridden to define custom transpilation.

  • The all curve fit plot generated by the CurveAnalysis shows a confidence interval properly computed with error propagation. By default it shows 1 sigma and 3 sigma region but you can customize this via the style option of the curve analysis subclass. The PlotterStyle dataclass has been updated with new attribute plot_sigma which takes a list of tuple(float, float) specifying a pair of sigma and transparency.

  • DataProcessor and DataAction are now JSON serializable with the qiskit experiments default encoder. This allows one to retrieve a configured processor from the record and re-analyze loaded data with the processor. Trained nodes are serialized with accquired parameters so that the loaded processor can continue to process new data.

Upgrade Notes

  • Experiment CrossResonanceHamiltonian and its subclasses have been upgraded. Now its instance can generate circuits without setting backend for just checking experiment sequence. The sequence with actual parameters is generated after the backend is set. In addition, now experiments can take cr_gate in the constractor which is Gate type subclass taking a single parameter (flat-top width). If one inputs a HamiltonianGate subclass with cross resonance Hamiltonian, experiment can be simulated with Aer QASM simulator.

  • BaseCurveAnalysis class has been added as a superclass of CurveAnalysis. The new base class doesn’t define the _run_analysis() abstract method and it cannot conduct analysis by itself, however it defines several subroutines that can be combined to build a custom fitting process in the subclass. This allows more flexibility to write custom curve analysis by directly inheriting from the new base class. See BaseCurveAnalysis for details. See also Issue 737 for discussion.

  • The method CurveAnalysis._generate_fit_guesses() has been upgraded with a new method signature. Now this method is called with curve_data argument that provides dataset which is used for curve fitting. If you define custom CurveAnalysis subclass in your codestack, you may need to upgrade the method. See BaseCurveAnalysis for details.

  • Arguments of FitData have been updated to take x_data and y_data instead of x_range and y_range.

  • The computation of error per gates (EPGs) from EPC in RBAnalysis has been upgraded. To compute these values from a single EPC value obtained by the experiment, we should provide a guess of contribution per basis gate to the depolarization. This ratio has been extracted from backend properties with RBUtils.get_error_dict_from_backend(), but this approach may result in unreproducible EPG outcomes under certain circumstances. See PR 762 for more details. Not this error ratio is provided from a hard-coded lookup table, and the user can still provide custom values with analysis option gate_error_ratio. One can skip computation of EPGs by setting the option to False.

  • RBAnalysis has been upgraded to compute corrected EPC for 2Q RB. When the analysis option epg_1_qubit is provided, it returns two EPG analysis results, with and without correction for underlying single qubit depolarization channels. New result is added under the name EPC_corrected.

  • Changed the Tphi experiment and TphiAnalysis to combine the component analysis results so that it runs as a single experiment returning \(T_\phi\), \(T_1\), and \(T_2^\ast\) analysis results.

  • The component experiment circuits of ParallelExperiment and BatchExperiment are now explicitly transpiled using the respective component experiments transpile_options() before being combined into the composite circuits returned by the BaseExperiment.circuits method.

    Any transpile options set directly on the ParallelExperiment or BatchExperiment will also be applied as a transpile option to each component experiment.

  • The circuits returned by the ParallelExperiment.circuits() method of parallel circuits will now always be the combined circuits circuits of the transpiled circuits of the individual component experiments transpiled with that experiments transpile options.

  • New default CurveAnalysis analysis option fixed_parameters has been added. We can directly exclude parameters from the fit model of the particular analysis instance, rather than defining a new class to define the class attribute CurveAnalysis.__fixed_parameters__.

  • The function get_processor() of the data processing package has an updated signature to make the method easy to extend. This will allow a more flexible creation of data processors.

  • The signature of the outcome_data argument of the tomography fitter functions in library.tomography has been changed from a list of NumPy ndarray vectors of non-zero observed frequencies into a single ndarray matrix containing the observed frequencies of all possible measurement outcomes for the measurement bases.

  • The FineAmplitude experiment is refactored for more flexibility. Furthermore, the FineAmplitudeAnalysis class is upgraded to accept 0/1 calibration circuits to better fit the amplitude A of the ping-pong pattern.

  • The processing of meas_level=2 data in the function get_processor() is generalized to data processing of experiments with more than one qubit.

  • The ParallelExperiment and BatchExperiment composite experiments have been changed to no longer return analysis results containing information about sub-experiments. Instead, use the child_data() method to retrieve sub-experiments of a given composite experiment.

  • The RB data processing flow is updated to align it with the recent refactoring of the get_processor() function. The RB analysis will now use the get_processor() function to choose the suitable data processor.

  • The job_metadata field has been removed from BaseExperiment. Experiments which needed job metadata for analysis should now directly override the .BaseExperiment._metadata method to store the required job metadata.

    Individual experiments using CurveAnalysis based analysis have been updated to store the meas_level and meas_return run options in metadata if they have been set in the experiment for use in setting the data processor during analysis.

  • The BaseExperiment._additional_metadata method has been removed, and experiments should now directly override the BaseExperiment._metadata method to add additional experiment metadata to the run experiment data.

  • Changed the signature of the circuit() and matrix() methods of tomography basis classes to require a qubits kwarg for specifying the specific physical qubits that the basis is being applied to.

  • The CurveAnalysis class has been updated to use the covariance between fit parameters in the error propagation. This will provide more accurate standard error for your fit values.

  • The data format of analysis result data value has been replaced from FitVal to uncertainties.ufloat from the Python uncertainties package to support error propagation for post analysis computation.

    expdata = T1(0, delays, backend).run()
fit_t1 = expdata.analysis_results("T1").value

assert isinstance(fit_t1, UFloat)

new_value = fit_t1 / 2
new_value.std_dev  # show new standard error value

    Now fit_t1 value is an uncertainties.ufloat instance with new properties nominal_value and std_dev, and you can directly apply mathematical operation to this object. The new error value is predicted by linear error propagation theory. Note that you no longer need to separately compute the standard error.

    This computation is offered by the uncertainties package which is a requirement since from Qiskit Experiments v0.2. The functions supporting error propagation is also available in uncertainties.umath.

  • In the analysis result object, FitVal.unit property has been moved to DbAnalysisResultV1.extra as metadata.

Deprecation Notes

  • Several protected methods of CurveAnalysis intended to be overriden or directly be used by subclass have been deprecated. CurveAnalysis._data() has been deprecated without alternative method to make CurveAnalysis state cleaner. Now relevent curve analysis methods requiring curve data are called with the curve_data argument. CurveAnalysis._extra_database_entry() has also been deprecated. This method becomes a part of CurveAnalysis._create_analysis_results(). Analysis class author can override this method to inject a code to create custom analysis results.

  • Calling RBUtils methods have been deprecated and will be removed after 0.4.

  • The CompositeExperiment.component_analysis() method has been deprecated. Component analysis classes should now be directly accessed from a CompositeAnalysis() object using the :meth:.`CompositeAnalysis.component_analysis` method.

  • Conventional curve visualization classes MplDrawSingleCanvas, MplDrawMultiCanvasVstack and the stylesheet PlotterStyle have been deprecated and now replaced with MplCurveDrawer. These classes had been attached to the analysis instance as a curve_plotter which is a string and mapped to the class method .draw at runtime via :FitResultPlotters: Enum. It was almost impossible to track the code and hurted the readability. In addition, this implementation was problematic due to dependency on the raw data points saved in an instance variable. See qiskit-experiments/#737 for details.

  • Class attribute CurveAnalysis.__fixed_parameters__ has been deprecated and support for the instantiation of the class with this attribute will be dropped soon. In addition, the fixed parameter value defined as a standalone analysis option has been deprecated. Please set fixed_parameters option instead. This is a python dictionary of fixed parameter values keyed on the fit parameter names.

  • Analysis class FineDragAnalysis has been deprecated. Now you can directly set fixed parameters to the ErrorAmplificationAnalysis instance as an analysis option.

  • Analysis class FineFrequencyAnalysis has been deprecated. Now you can directly set fixed parameters to the ErrorAmplificationAnalysis instance as an analysis option.

  • Analysis class FineHalfAngleAnalysis has been deprecated. Now you can directly set fixed parameters to the ErrorAmplificationAnalysis instance as an analysis option.

  • The library argument to Calibrations has been deprecated in favour of a new argument called libraries.

  • Adding data from jobs using ExperimentData.add_data() has been deprecated. This method should now only be used to add data from Qiskit Result objects or raw data dicts. Job data should now be added using the new ExperimentData.add_jobs() method instead.

  • BaseExperiment._postprocess_transpiled_circuits is deprecated and will be removed in the 0.4.0 release. Use BaseExperiment._transpiled_circuits() instead.

  • The FitVal class had been deprecated and being replaced with the uncertainties package. When loading saved experiments or analysis results any FitVal s will be implicitly converted into UFloat which should be re-saved to ensure these experiments can be reloaded in the future.

Bug Fixes

  • Fixed a bug in the InterleavedRB experiment where a Delay instruction, or a Clifford circuit containing delay instructions, could not be used as the interleaved element.

  • Fixed built-in tomography fitter functions cvxpy_linear_lstsq(), cvxpy_gaussian_lstsq(), scipy_linear_lstsq(), scipy_gaussian_lstsq(), linear_inversion() to make the measurement_basis kwarg optional so that these functions could be used for fitting raw tomography fitter data with preparation data but no measurement data.

  • Fixed bug in TomographyAnalysis when accumulating count data from repeated circuits using the same preparation and measurement basis configuration.

  • ExperimentData.save() should now fail gracefully when experiment metadata failed to save instead of crashing.

  • The link to the experiment entry in the database service shown after saving is now by default obtained from the service, not hard-coded.

  • The FineZXAmplitude now works properly with restless measurements.

  • Fixed a bug with the ProcessTomography where the default target channel analysis option was computed incorrectly if not all qubits were prepared and measured, and the preparations and measurements were applied to different subsets of qubits.

    See Issue 758 for details.

  • Fixed a bug with the ProcessTomographyAnalysis where analysis would raise an exception if the number of prepared and measurement qubits are not equal.

    See Issue 757 for details.

  • The initial guess function exp_decay(), which estimates an exponent of the decay curve by taking the natural logarithm of the y values, has been updated to handle exceptions when some y values are negative.

  • Fixed a bug with JSON deserialization using the ExperimentDecoder failing to decode custom user classes defined in the __main__ scope of python scripts and notebooks.

  • Fixed bug in CompositeAnalysis where analysis of nested composite experiments could raise a RuntimeError.

  • Fixed a bug in TomographyAnalysis where the basis elements of unobserved measurement outcomes were not being included in the fitter objective function for least-squares fitters (CVXPY and SciPy). This would lead to lower than expected fit fidelities when fitting data with many zero count outcomes (typically synthetic data from ideal simulation).

  • Fixed issue with the CVXPY ProcessTomography analysis fitter functions cvxpy_linear_lstsq() and cvxpy_gaussian_lstsq() where the trace preserving constraint was not being applied to the fit functions by default and required being explicitly passed as a solver_option. Now all CVXPY process tomography experiments will have this option set to True by default unless a user explicitly disables it by setting the solver_option to False.

  • Cloud database experiment links no longer display when there was an error saving to the API.

  • The ResonanceAnalysis class has been switched from a Gaussian fit to a Lorentzian fit function. Furthermore, the Gaussian fitting capability is preserved by moving the Gaussian fitting to a new class called GaussianAnalysis. Note that the previous analysis can be used by doing:

    spec = ResonatorSpectroscopy(qubit, backend)
spec.analysis = GaussianAnalysis()

    where GaussianAnalysis is imported from curve_analysis.

  • A bug related to single-shot data in the SVD data processing node is fixed.

  • Poor python instance representation of DataAction has been upgraded to show all information contained in the class instance.

API Changes for Experiment Authors

  • Refactored some of the internal CVXPY code in qiskit_experiments.library.tomography.fitters.cvxpy_utils used by the CVXPY tomography fitters to make it easier to generate complex variable SDP optimization problems.

  • The assertExperimentDone() function has been added to test.base.QiskitExperimentsTestCase. This assertion will check if all threads in the experiment data are successfuly completed. This function calls block_for_results() and then checks if the experiment status returns DONE after execution. It is highly recommended to use this test right after each experiment execution to detect program malfunction, which is particularly relevant to python multi-threading in multi-platform.

  • New module qiskit_experiments.warnings has been added. This module implements several decorator functions to raise user-friendly deprecation warning and some also patch the decorated logic to implements new logic for backport. See decorator function documentations for details.

  • Data handling of training parameters in TrainableDataAction has been upgraded for the JSON serialization. Updated class implements _default_parameters(), set_parameters(), and parameters() methods, where the training parameters are managed with Options instance. A node developer must implement _default_parameters() class method to automatically populate the JSON configuration dictionary.

Other Notes

  • Default fit bounds for d_theta parameter of qiskit_experiments.curve_analysis.ErrorAmplificationAnalysis class has been updated from [-pi, pi] to [-0.8 pi, 0.8 pi]. This change will improve the bad fit when the error value is really close to zero. This has sometimes yielded in d_theta ~ pi rather than zero. Though 0.8 is the empirical factor, this is okey for most situations since the amplification analysis is applied to experiments in the small error regime (this is often sufficiently smaller than pi).

0.2.0

Prelude

The Qiskit Experiments 2.0 release includes several bug fixes and improvements and many new experiments added to the library. Added experiments include a full suite of single-qubit gate calibration and characterization experiments, and two-qubit Cross-resonance Hamiltonian characterization experiments. There are also numerous changes and improvements to the base classes in framework and calibration_management to make developing new experiments easier, to improve JSON serialization, and to improve storing and loading experiments for the IBM experiment database service.

New Features

  • You can now change the default matplotlib backend used for generated figures by setting qiskit_experiments.framework.matplotlib.default_figure_canvas to the desired canvas. Note that it has to be a canvas for one of the non-interactive backend. For example, you can set default_figure_canvas to FigureCanvasAgg to use the AGG backend.

  • Added the replace_results kwarg to run() with default value of replace_results=False.

    If analysis is run with replace_results=True then any analysis results and figures in the experiment data will be cleared and replaced with the new analysis results. Saving this experiment data will replace any previously saved data in a database service using the same experiment ID.

    If analysis is run with replace_results=False and the experiment data being analyzed has already been saved to a database service, or already contains analysis results or figures, a copy with a unique experiment ID will be returned containing only the new analysis results and figures. This data can then be saved as its own experiment to a database service.

  • Added backend as an optional __init__ kwarg for all experiments to allow setting the backend at initialization. The backand can also be set and retrieved from the experiment object after construction using the backend() property and setter.

    When using the backend kwarg of run() to specify a backend this will temporarily override any currently set backends for that single execution.

  • Added ExperimentConfig dataclass for storing the configuration of an experiment. This configuration can be obtained by using the config() property. Experiments can also be reconstructed from their configuration using the from_config() class method.

  • Added automatic job splitting to BaseExperiment for execution of experiments with a larger number of circuits than can be run in a single job on the target backend. This enables running large experiments on legacy and non-IBM backends that don’t handle job splitting automatically.

  • Added support for JSON serialization to qiskit_experiments.calibration_management.BasisGateLibrary.

  • Simplified the update library for calibration experiments by merging this functionality into the qiskit_experiments.calibration_management.BaseCalibrationExperiment.

    Future releases may fully deprecate the qiskit_experiments.calibration_management.update_library.BaseUpdater in favour of moving its functionality into the BaseCalibrationExperiment.

  • The qiskit_experiments.data_processing.Probability data processing node has been enhanced to compute the estimated mean and standard deviation of a measured outcome probability using a Bayesian update of a a Beta distribution prior from the observed measurement outcomes. The default prior is an uninformative prior. The user can also provide a custom prior for the probability distribution.

  • Added add_analysis_callback() method to ExperimentData for adding a post-processing analysis function to run as a callback after currently executing experiment jobs are finished.

  • Added a block kwarg with default value block=True to the qiskit_experiments.framework.ExperimentData.analysis_results() method. If this is True then calling analysis_results() will block to wait for all running analysis callbacks to finish before returning results. This prevents issues where trying to retrieve analysis results before analysis was finished would raise an error that the result could not be found.

    Note that in the case of ParallelExperiment and BatchExperiment blocking or calling analysis_results on the parent experiment should be performed before attempting to access results in the component experiment data containers to ensure the component analysis callbacks have been initialized.

  • The ExperimentData class can now store child ExperimentData containers. Child data can either be added at initialization using the child_data kwarg or added later using the add_child_data() method. Child ExperimentData can be accessed using the child_data() method.

  • Added a copy() method to ExperimentData which allows making a copy of an experiment data container with a new experiment ID, new result IDs, and new figure names, generated for the copy.

    This method has a kwarg option copy_results that can be set to False to only copy the experiment data() and metadata, but not the analysis results and figures.

  • Added support for saving and loading qiskit_experiments.framework.ParallelExperiment and qiskit_experiments.framework.BatchExperiment experiment data and all component experiment data and results from the IBM experiments database service. Changing the share level of the parent composite experiment will also change the share level of all component experiments.

    When saving composite experiments each component experiment analysis results and figures will be saved under a unique experiment ID. Note that these component experiments do not save any of the marginalized circuit result data. The unmarginalized circuit result data is saved in the parent componsite experiments.

  • Added a collection of experiments for performing single-qubit gate characterization and calibration. The new experiments are

    • Rabi: This experiment scans the amplitude of a pulse and measures the qubit population. This allows us to determine the amplitude that creates, for example, an X gate and/or a SX gate.

    • RoughXSXAmplitudeCal: The calibration version of Rabi. It extracts the amplitudes needed to implement an X gate an a SX gate. This type of calibration is a rough amplitude calibration since the resulting parameter value is typically not very precises.

    • FineAmplitude: This experiment repeats a rotation a variable number of times to amplify over- and under-rotations. The resulting ping-pong pattern in the qubit population is fit to determine the error in the rotation angle. This experiment has specializations for X (FineXAmplitude) and SX (FineSXAmplitude) gates.

    • FineAmplitudeCal: The calibration version of FineAmplitude. It will update the amplitude of the pulse according to the measurred deviation. This experiment has specializations for X (FineXAmplitudeCal) and SX (FineSXAmplitudeCal) gates.

    • RoughDrag: This experiment scans the DRAG parameter of a repeated sequence of rotation and anti-rotation. If the DRAG parameter does not have the correct value phase errors will accumulate and the repeated sequece of gates will not return the qubit to the ground state.

    • RoughDragCal: The calibration version of RoughDrag.

    • FineDrag: This experiment iterates the gate sequence Rp - Rm where Rp is a rotation around an axis and Rm is the same rotation but in the opposite direction. This sequence amplifies phase errors due to the presence of higher excited states. This experiment has specializations for X (FineXDrag) and SX (FineSXDrag) gates.

    • FineDragCal: The calibration version of FineDrag. This will update the DRAG parameter in the instance of the :class:`~qiskit_experiments.calibration_management.Calibrations class. This experiment has specializations for X (FineXDragCal) and SX (FineSXDragCal) gates.

    • QubitSpectroscopy: This experiment performs spectroscopy by applying a frequency shift to a long pulse. This experiment is typically used to identify the resonance frequency of the qubit.

    • RoughFrequencyCal the calibration version of QubitSpectroscopy. This gives us a first rough estimate of the qubits frequency.

    • RamseyXY: This experiment performs a Ramsey-XY experiment which allows us to measure the frequency of the qubit. This experiment is sensitive to the sign of the frequency offset from the main transition. It is a more precise measurement than spectroscopy.

    • FrequencyCal: This is the calibration version of RamseyXY.

    • FineFrequency: This experiment performs an error amplifying sequence to measure the frequency of the qubit. This is done with delay instructions with a variable length and RZ gates.

    • FineFrequencyCal: This is the calibration version of FineFrequency.

    • HalfAngle: This experiment measures the amount by which the SX and X gates are not parallel. Such errors can occur due to phase errors. For example, the non-linearities in the mixer’s skew for \(\pi/2\) pulses may be different from the \(\pi\) pulse.

    • HalfAngleCal: This is the calibration version of HalfAngle.

  • Two cross-resonance Hamiltonian tomography experiments have been added to the qiskit_experiments.library.

    • qiskit_experiments.library.CrossResonanceHamiltonian

    • qiskit_experiments.library.EchoedCrossResonanceHamiltonian

    These experiments estimates the IX, IY, IZ, ZX, ZY, ZZ Hamiltonian term coefficients of the cross-resonance Hamiltonian, using either a single-tone cross-resonance gate (CrossResonanceHamiltonian) or an echoed cross-resonance gate (EchoedResonanceHamiltonian).

  • Added a qiskit_experiments.library.ReadoutAngle characterization experiment. This experiment computes the average of the angles of the IQ clusters of the ground and excited states.

  • StandardRb and InterleavedRb experiments now compute error as part of the error-per-gate computation.

Known Issues

  • Curve analysis may have imperfection in the uncertainty propagation computation. Fit paramters consist of the nominal part and standard error, however, the correlation of these paramters are not precisely taken into account. This sometimes result in the overestimation of the confidence interval of fit curves, or overestimation of the standard error of some analysis values computed with multiple fitting parameters. This issue will be solved in the version 0.3. See qiskit-experiments/#551 for details.

Upgrade Notes

  • The default matplotlib backend used for generated figures was changed from AGG to SVG.

  • Due to changes in JSON serialization it is possible that some experiments saved to the IBM Experiments database service using the Qiskit Experiments 0.1 API may not be able to be loaded using Qiskit Experiments 0.2.

  • Changed run() to run asynchronously using the add_analysis_callback(). Previously analysis was only run asynchronously if it was done as part of an experiments run().

  • The BackendCalibrations class has bas been removed and its functionality has been merged into the qiskit_experiments.calibration_management.Calibrations class. Users should now use the Calibrations class which can be instantiated from a backend by using the from_backend() method.

  • The CompositeExperimentData class has been removed and its functionality integrated into the ExperimentData class. A composite ExperimentData can now be created by initializing with a list of child ExperimentData containers using the child_data kwarg.

  • The callback and **kwarg arguments have been removed from add_data() To add a callback function to run after experiment jobs have finished executing use the add_analysis_callback() method instead.

  • All qiskit_experiments.library experiments have been changed to work with fixed SI units: Hz for frequency, seconds for delays, and backend dt for pulse widths and durations. Previous experiments with unit kwargs in their init functions have had this kwarg removed.

  • The qubits intitialization argument for StandardRb, InterleavedRb, QuantumVolume, StateTomography, and ProcessTomography no longer accepts interger values for specifying a range of qubits. and must now contain an explicit sequence of qubits.

  • The behavior of the seed initialization kwarg of the StandardRB, InterleavedStandardRB, QuantumVolume experiments has been modified.

    In the new version the seed value is used as to initialize a Numpy random number generator object as numpy.random.default_rng(seed=seed) each time the experiments circuits method is called. This change means that using a fixed seed value will result in the same circuits being generated each time an experiment is run, if no other experiment options are changed.

    To generate different new random circuits each time an experiment is run the (default) value of seed=None should be used. To reproduce equivalent functionality to the previous version behavior of differnet circuits being generated each time run is called with a fixed seed you must now set a new fixed seed value between each call to run using experiment.set_experiment_options(seed=value).

Deprecation Notes

  • Using the __analysis_class__ class attrbiute to define a default BaseAnalysis class in a BaseExperiment subclass has been deprecated. A default analysis class instance should now be passed to the initialization method of BaseExperiment instead.

Bug Fixes

  • The qiskit_experiments.data_processing.Probability data processing node will no longer return exactly 0 or 1 for a probability estimate. This fixes an issue where this could cause division by 0 when computing weights during curve fitting analysis.

  • Fixed a bug in StandardRB and InterleavedRB where the variance in the estimated error per Clifford did not scale correctly with the number of sampled RB sequences.

    See Issue 428 for details.

API Changes for Experiment Authors

  • The qiskit_experiments.framework.BaseAnalysis class has been changed to be an initialized class.

    This class now stores its set analysis options using the set_options() and options() and _default_options methods. The signature of the abstract method _run_analysis that must be implemented by subclasses has been changed to remove the **kwargs.

    Note that the state of this class should only be used to store option values and derived configuration. The run() and _run_analysis methods should not change the state of the instance.

  • Added a _set_backend method to BaseExperiment that is called when a backend is set via initalization or the backend setter. This can be overridden in experiment subclasses if required. For example this could be used to extract any needed configuration or properties from the specified backend, or to update experiment options of configuration based on the backend.

  • calibration experiments have been changed so that each experiment is a subclass of a characterization experiment.

    Calibration experiments should now be constructed as subclasses of both the relevant characterization experiment and the new qiskit_experiments.calibration_management.BaseCalibrationExperiment abstract base class.

    This new base class implements the functionality to manage schedules stored in instances of the qiskit_experiments.calibration_management.Calibrations class and implements a framework where calibration experiments can specify an update() method to update the parameters that they are designed to calibrate.

  • There have been several changes to the qiskit_experiments.curve_analysis.CurveAnalysis class which may effect developers implementing experiments using curve analysis.

    These include:

    • Default data pre-processing for curve fit data has been added to CurveAnalysis. The input data to the analysis is averaged over the same x values and sorted by x values. This processing is necessary to correctly analyze an experimental data which has duplicate x values.

    • The handling of user provided initial guesses and fit boundaries has been changed so that subclasses no longer need to use user provided option values. Propagation of user values is now handled by the base class.

    • The subclass method name to provide these initial guesses for curve fitting has bee changed from _setup_fitting to _generate_fit_guesses(). See the documentation for more details.

    • Tick labels and fit parameters shown in the fit result plot generated by qiskit_experiments.curve_analysis.CurveAnalysis subclasses are formatted with unit with prefactor scalings. For example, 1e7 can now be displayed as 10 MHz.

      To enable this change, all experiments using CurveAnalysis or a subclass analysis class should set analysis options xval_unit and yval_unit.

  • A model_description fields has been added to the qiskit_experiments.curve_analysis.SeriesDef dataclass. This field stores the string representation of the fit model of the curve and will be stored in the experiments analysis result extra field.