Table of Contents
Shortcuts



Release Notes

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

  • Adds 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 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.

  • Adds 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

  • Fixes 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.

  • Fix 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 <https://github.com/Qiskit/qiskit-experiments/issues/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.

  • Adds 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.

  • Adds 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.

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

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

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

  • Adds 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.

  • Adds 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.

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

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

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

  • Adds 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.

  • Adds 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 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 propatation 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

  • Fixes 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.

  • Fix 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.

  • Fixes 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.

  • Fixes 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.

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

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

  • Fixes 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).

  • Fixes 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.

  • Add 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.

  • Add 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.

  • Adds 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.

  • 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.

  • Adds 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.

  • Adds 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.

  • Adds 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).

  • Adds 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 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.

  • Fixes 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.

  • 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.