Qiskit SDK 2.2 release notes

2.2.1

Prelude

Qiskit 2.2.1 is a small patch release that fixes several bugs identified in the 2.2.0 release.

Transpiler Upgrade Notes

• The maximum call and trial limits for the exact-matching run of VF2PostLayout at optimization_level=3 have been reduced to avoid excessive runtimes for highly symmetric trial circuits being mapped to large coupling maps.

Bug Fixes

• DAGCircuit.apply_operation_back(), apply_operation_back() and circuit_to_dag() will now add new edges in a deterministic order. The previous behavior could cause certain transpiler passes (such as SabreSwap) to traverse the DAG in non-deterministic orders.

• DAGCircuit.apply_operation_front() can no longer insert invalid self loops when handling nodes that include classical conditions.

• Fixed an issue with pickle support for the SabreSwap where a SabreSwap instance would error when being pickled after the SabreSwap.run() method was run. Fixed #15071.

• Fixed an issue where is_unitary() was not properly respecting the input tolerance values when checking if an operator is unitary. The method now correctly uses the provided atol and rtol parameters when simplifying the operator and checking if it equals the identity. This fixes #14107.

2.2.0

Prelude

The Qiskit v2.2 adds several enhancements for the C API and the transpiler as well as many other improvements and bug fixes. The major features of this new release are:

• C API transpile function: The C API now includes a function for transpiling a quantum circuit: qk_transpile(). This function is equivalent to the Python transpile() function for a standalone C context.
• Litinski transformation pass: A new transformation pass LitinskiTransformation that implements the transform described arXiv:1808.02892. This is pass is typically used in compilation for fault tolerant architectures.
• Angle bound support for targets: The Target class now supports specifying bounds for the allowed values for parameterized operations added to the target. When an instruction is added to the Target you can add the optional argument angle_bounds to specify the higher and lower bounds for parameterized rotation gates. A new transpiler pass WrapAngles was added to enforce the angle constraints as part of a transpilation pipeline.

The v2.2 release series is the final minor release series with support Python 3.9. The minimum supported Rust version use to build Qiskit from source is now Rust v1.85, raised from 1.79 in 2.1.0. For more information about the above and other changes made, please see the release notes below and review the updated documentation.

C API Features

• Added new standalone transpiler pass functions to the C API. These functions take in a QkCircuit to run the pass on and are equivalent to calling an instantiated pass.

  Transpiler pass	C API Counterpart
  BasisTranslator	qk_transpiler_pass_standalone_basis_translator()
  CommutativeCancellation	qk_transpiler_pass_standalone_commutative_cancellation()
  ConsolidateBlocks	qk_transpiler_pass_standalone_consolidate_blocks()
  ElidePermutations	qk_transpiler_pass_standalone_elide_permutations()
  CheckGateDirection	qk_transpiler_pass_standalone_check_gate_direction()
  GateDirection	qk_transpiler_pass_standalone_gate_direction()
  InverseCancellation	qk_transpiler_pass_standalone_inverse_cancellation()
  Optimize1qGatesDecomposition	qk_transpiler_standalone_optimize_1q_sequences()
  RemoveDiagonalGatesBeforeMeasure	qk_transpiler_pass_standalone_remove_diagonal_gates_before_measure()
  RemoveIdentityEquivalent	qk_transpiler_pass_standalone_remove_identity_equivalent()
  SabreLayout	qk_transpiler_pass_standalone_sabre_layout()
  Split2QUnitaries	qk_transpiler_pass_standalone_split_2q_unitaries()
  UnitarySynthesis	qk_transpiler_pass_standalone_unitary_synthesis()
  VF2Layout	qk_transpiler_pass_standalone_vf2_layout()

• The QkTarget type can now represent targets that support parameterized QkGate types that accept any parameter value. Previously, these gates could only be added to the target with a fixed angle value supported by using qk_target_entry_new_fixed() to create the QkTargetEntry. Now, the qk_target_entry_new() function can be used with parameterized gates. When it is used with parameterized gates, this function indicates that the gate in the target supports any value for all of the gate’s parameters. For example:

  #include <qiskit.h>
   
  QkTarget *target = qk_target_new(5);
  QkTargetEntry *rz_entry = qk_target_entry_new(QkGate_RZ);
  for (uint32_t i = 0; i < 5; i++) {
      uint32_t qargs[1] = {i};
      qk_target_entry_add_property(rz_entry, qargs, 1, 1.2e-6, 1.3e-9);
  }
  qk_target_add_instruction(target, rz_entry);
   
  // Clean up after using target
  qk_target_free(target);

  This creates a 5 qubit target that will accept an RZ gate on any qubit with any parameter value being supported by that gate.

• Added qk_obs_apply_layout() to apply new qubit layouts to a QkObs observable. This function takes the observable, the new qubit indices, and an output number of qubits. Importantly, this function allows applying transpile layouts, usually given as QkTranspileLayout by a transpiler pass, to an observable. For example:

  // get the number of output qubits -- transpile_layout is a QkTranspileLayout*
  uint32_t num_output_qubits = qk_transpile_layout_num_output_qubits(transpile_layout);
   
  // get the layout including the ancillas (hence the ``false`` in the function call)
  uint32_t *layout = malloc(sizeof(uint32_t) * num_output_qubits);
  qk_transpile_layout_final_layout(transpile_layout, false, layout);
   
  // apply the layout -- obs is a QkObs*
  int exit = qk_obs_apply_layout(obs, layout, num_output_qubits);
   
  // free the layout array
  free(layout);

• Added a new function qk_transpile() to the Qiskit C API. This function is used for transpiling quantum circuits in a standalone C context without using Python. This is the last major component needed in the C API for typical hardware execution workflows using Qiskit.

  This function mirrors the preset pass managers that are used for the Python transpiler except for some passes and functionality is skipped if it is not relevant for circuits constructed using the C API. This makes the function only suitable for standalone C contexts.

• Added a new type QkTranspileLayout to the C API. This type is used for reasoning about the permutations caused by the transpiler.

Circuits Features

• A new method, QuantumCircuit.ensure_physical(), is provided to ensure that a circuit is defined over physical qubits, with the qubit indices referring to physical qubits. See the new discussion on abstract- and physical-circuit representations in the documentation for more detail on the metadata concepts. The concepts of “abstract” and “physical” circuits are not at all new to Qiskit, just the explicit documentation.

• The Duration class has gained a new ps variant, which can be used to represent a duration in picoseconds.

• Improved PauliEvolutionGate.control(), PauliEvolutionGate.power() and PauliEvolutionGate.inverse() to return more efficient representations in terms of a PauliEvolutionGate. For computing the controlled and exponentiated versions of the evolution gate this change leads to significantly shallower circuits and lower gate counts compared to the previously used generic mechanisms. The inverse decomposition does not change but is now generated more efficiently and allows for better compiler optimizations.

• A new fast-path method ParameterExpression.bind_all() is added to support the use-case of binding many different ParameterExpression instances to numeric values using the same mappings dictionary. The existing bind() method has a large amount of overhead and unnecessary allocations, since it always returns a ParameterExpression for typing consistency.

OpenQASM Features

• Added partial support for defcal symbols in the OpenQASM3 exporter. This enables downstream packages to export custom instructions that operate on both quantum and classical bits using qiskit.qasm3.dumps(). Users can now define custom instructions (e.g., a CustomMeasure that acts on a qubit and returns a classical bit) and specify their behavior using DefcalInstruction. These defcals are passed to the exporter via the implicit_defcals argument in qiskit.qasm3.dumps().

  For example:

  from qiskit.circuit import Instruction, QuantumCircuit
  from qiskit.qasm3 import dumps
  from qiskit.qasm3.exporter import DefcalInstruction, types
   
  custom_measure = Instruction("measure_2", 1, 1, [])
  qc = QuantumCircuit(1, 1)
  qc.h(0)
  qc.append(custom_measure, [0], [0])
  qc.measure(0, 0)
   
  defcals = {
      "measure_2": DefcalInstruction("measure_2", 0, 1, types.Bool()),
  }
   
  out_qasm = dumps(qc, implicit_defcals=defcals)
  print(out_qasm)

  Would output the following valid OpenQASM3 string:

  OPENQASM 3.0;
  bit[1] c;
  qubit[1] q;
  h q[0];
  c[0] = measure_2 q[0];
  c[0] = measure q[0];

  This approach assumes that the grammar definition for the defcal is provided externally (e.g., in a header file), although such a file is not strictly required for the exporter to function.

• The functions qasm3.loads() and qasm3.load() now have an extra argument called num_qubits. If provided, the functions will return circuits that will have qubits equal to num_qubits. If not provided, the returned circuit will have qubits equal to the maximum index seen in the serialized circuit. Refer to #14435 for more details

QPY Features

• Added a setting named min_qpy_version in the user configuration file. When set, it defines the minimum allowed QPY version for qpy.load(). If the format version of a QPY file is lower than the minimum_qpy_version than the minimum_qpy_version setting it will raise an exception.

• Introduced QPY format version 16. This new version introduces a new circuit start table to the file header which contains the byte offsets of the start of each circuit in a QPY file. This allows for a potentially more efficient loading of circuits from QPY files, and a potentially multi-threaded Rust implementation in the future. Additionally, the new format version adds support for the new DURATION variant of picoseconds.

Quantum Information Features

• Added the PauliLindbladMap.drop_qubits() and PauliLindbladMap.keep_qubits() methods to trace subsystems out of Pauli Lindblad maps.

• Added methods QubitSparsePauli.to_pauli() and QubitSparsePauliList.to_pauli_list(), which convert the sparse objects into the corresponding dense versions, Pauli and PauliList, respectively.

• Added the PhasedQubitSparsePauli and PhasedQubitSparsePauliList classes. These classes represent a single Pauli operator and a list of Pauli operators respectively stored in qubit-sparse format. These classes are very similar to QubitSparsePauli and QubitSparsePauliList, except they additionally contain phase information.

• Added the method QubitSparsePauliList.to_dense_array(). This returns the list as an array of integers with the values of Pauli.

Synthesis Features

• Added new synthesis algorithm for ModularAdderGate that requires no ancillary qubits and has better CX count compared to adder_qft_d00():

  • adder_modular_v17()

• Added a new synthesis algorithm, synth_mcx_noaux_hp24(), for MCXGate that does not require any auxiliary qubits. This method produces a linear, rather than a quadratic number of CX gates, compared to the existing synth_mcx_noaux_v24() algorithm. In particular, the new method is better when the number of control qubits is greater than five. The algorithm is based on the paper “Compiling Conditional Quantum Gates without Using Helper Qubits” by Huang and Palsberg (https://dl.acm.org/doi/10.1145/3656436).

• Improved the qs_decomposition() function which was originally based on Shende et. al. (https://arxiv.org/abs/quant-ph/0406176). The new synthesis method is based on Krol and Al-Ars (https://arxiv.org/abs/2403.13692), and reduce the total number of CXGates of a general n-qubit unitary by $\frac{4^{n − 2} − 1}{3}$ CXGates. With the improved decomposition, a general 3-qubit unitary can be decomposed using 19 CXGates (rather than 20).

• Added synth_mcmt_xgate() to synthesize the multi-control multi-target gate when the base gate is XGate. It has a decomposition in linear number of CX gates and 0 ancilla qubits along with the high-level synthesis plugin MCMTSynthesisXGate.

Transpiler Features

• Added new high-level-synthesis plugin for synthesizing a ModularAdderGate:

  • ModularAdderSynthesisV17, based on adder_modular_v17().

  The ModularAdderSynthesisDefault has also been updated to follow the following sequence of modular adder synthesizers: "ModularAdder.qft_d00" when the number of qubits is $\leq 4$, "ModularAdder.modular_v17" in all other cases.

• Added a new transpiler pass LitinskiTransformation that implements the transform described in arXiv:1808.02892.

  The input to the pass is a circuit with Clifford and single-qubit RZ-rotation gates, and the output is a circuit with multi-qubit Pauli rotations (implemented as PauliEvolutionGate gates) followed by Clifford gates. The pass raises a TranspilerError exception if the circuit contains non-supported gates.

  The pass supports all of the Clifford gates in the list returned by get_clifford_gate_names(), namely ["id", "x", "y", "z", "h", "s", "sdg", "sx", "sxdg", "cx", "cz", "cy", "swap", "iswap", "ecr", "dcx"]. The list of supported RZ-rotations is ["t", "tdg", "rz"] (we automatically convert T and Tdg gates to RZ-rotations).

  In addition, the LitinskiTransformation constructor accepts an argument fix_clifford. When False (non-default), the returned circuit contains only PauliEvolutionGate gates, with the final Clifford gates omitted. Note that in this case the operators of the original and synthesized circuits will generally not be equivalent.

  For example:

  from qiskit.circuit import QuantumCircuit
  from qiskit.transpiler.passes import LitinskiTransformation
  from qiskit.quantum_info import Operator
   
  # The following quantum circuit consists of 5 Clifford gates
  # and two single-qubits RZ-rotation gates (note that Tdg is
  # an RZ-rotation).
  qc = QuantumCircuit(2)
  qc.cx(0, 1)
  qc.rz(0.1, 0)
  qc.cz(0, 1)
  qc.tdg(1)
  qc.h(1)
  qc.s(1)
  qc.cz(1, 0)
   
  # The transformed circuit consists of two PauliEvolution gates
  # and the same Clifford gates as in the original circuit.
  qct = LitinskiTransformation()(qc)
   
  # The circuits before and after the transformation are equivalent
  assert Operator(qc) == Operator(qct)

• Added a new high-level synthesis plugin MCXSynthesisNoAuxHP24 for MCXGate objects. Furthermore, the default synthesis plugin MCXSynthesisDefault for MCXGate objects was updated to always choose the best synthesis method depending on the available number of auxiliary qubits.

• Added support for a Target to specify angle bounds on instructions. Prior to this release a Target could specify that an operation that took a parameter either would allow any valid value or a specific value. For example, if RZGate(Parameter("theta")) were added to the target that would indicate an RZGate with any value for theta were allowed. While if RZGate(math.pi) were added to the target that would indicate RZGate that only $\pi$ is the only allowed value on the target. This new feature enables restricting the allowed angles to be any float value between a an inclusive bound. For example, you can add RZGate(math.pi) to a Target and restrict the angle value between the values 0 and $2\pi$.

  There are several methods available for working with the angle bounds on the target. The first is Target.add_instruction() which has a new angle_bounds keyword argument that is used to add an angle bound to an instruction in the Target. To work with angle bounds you will also want to register a callback function to the global WRAP_ANGLE_REGISTRY registry that will tell the transpiler and WrapAngles pass how to adjust gates for angle bounds. The callback function will take a list of arbitrary float values representing the gate angles from the circuit, as well as the qubit indices in the circuit the gate was operating on and it will return a DAGCircuit that represents an equivalent circuit for the gate with that angle but respecting the angle bounds and other Target constraints. For example:

  import math
   
  from qiskit.dagcircuit import DAGCircuit
  from qiskit.transpiler import target
  from qiskit.transpiler.passes.utils.wrap_angles import WRAP_ANGLE_REGISTRY
   
  target = Target(num_qubits=1)
  target.add_instruction(RZGate(Parameter("theta")), angle_bounds=[(-math.pi, math.pi)])
   
  def callback(angles: List[float], qubits: List[int]) -> DAGCircuit:
      """Callback function to wrap RZ gate angles
   
      Args:
          angles: The list of floating point parameter values for the instance of RZGate in
              the circuit
          qubits: The physical qubit indices that this gate is operating on
   
      Returns:
          The DAGCircuit of the equivalent circuit"""
   
      angle = angles[0]
      dag = DAGCircuit()
      dag.add_qubits([Qubit()])
      if angle > 0:
          divisor = math.pi
      else:
          divisor = -math.pi
      gate_counts = int(angles[0] // divisor)
      rem = angles[0] % divisor
      for _ in range(gate_counts):
          dag.apply_operation_back(RZGate(math.pi), [dag.qubits[0]], check=True)
      dag.apply_operation_back(rem, [dag.qubits[0]], check=True)
   
  WRAP_ANGLE_REGISTRY.add_wrapper("rz", callback)

  Target.has_angle_bounds() can be used to check whether there are any angle bounds set in the target, and Target.gate_has_angle_bounds().

  If you want to apply the angle bounds from a target to any gates in a circuit the WrapAngles transpiler pass should be used to do this.

• Added a new kwarg check_angle_bounds to the Target.instruction_supported() method. When set to True (the default) the method will check if the specified parameters also conforms to any angle bounds that may exist for the instruction being queried.

• Added a new transpiler pass WrapAngles which is used to apply angle constraints on gates in the Target. If a Target has defined angle bounds this pass will analyze all the parameters for the gates in the circuit and check that against the bounds specified in the target. For example, if a target contains a custom gate that has angle bounds the pass will decompose that gate into a gate which conforms to the bounds:

  from qiskit.circuit import Gate, Parameter, QuantumCircuit, Qubit
  from qiskit.dagcircuit import DAGCircuit
  from qiskit.transpiler import Target, WrapAngleRegistry
  from qiskit.transpiler.passes import WrapAngles
   
  class MyCustomGate(Gate):
   
      def __init__(self, angle):
          super().__init__("my_custom", 1, [angle])
   
  param = Parameter("a")
  circuit = QuantumCircuit(1)
  circuit.append(MyCustomGate(6.0), [0])
  target = Target(num_qubits=1)
  target.add_instruction(MyCustomGate(param), angle_bounds=[(0, 0.5)])
   
  def callback(angles, _qubits):
      angle = angles[0]
      if angle > 0:
          number_of_gates = angle / 0.5
      else:
          number_of_gates = (6.28 - angle) / 0.5
      dag = DAGCircuit()
      dag.add_qubits([Qubit()])
      for _ in range(int(number_of_gates)):
          dag.apply_operation_back(MyCustomGate(0.5), [dag.qubits[0]])
      return dag
   
  registry = WrapAngleRegistry()
  registry.add_wrapper("my_custom", callback)
  wrap_pass = WrapAngles(target, registry)
  res = wrap_pass(circuit)
  res.draw('mpl')

  

• DAGCircuit now has a manual implementation of __deepcopy__(). This is orders of magnitude faster than the previous implicit implementation from the pickle protocol, especially for large circuits. This also directly benefits compilation performance when running transpile() or running the preset pass managers returned by generate_preset_pass_manager() at optimization_level=3 as optimization level 3 internally deep copies the DAGCircuit for each iteration of the optimization loop in the optimization stage.

• A new method, DAGCircuit.make_physical(), is provided, which efficiently replaces the qubits in the DAGCircuit with the canonical physical-qubit register, potentially including expansion. A similar method, QuantumCircuit.ensure_physical() is also available.

• A new method, DAGCircuit.structurally_equal(), can be used to if two DAGCircuit instances have been created and modified in the exact same order. This is a much stronger test than the standard semantic equivalence check of the == overload, and can be used by transpiler-pass authors to verify that their modification orders are deterministic.

• Custom subclasses of BasePassManager can now modify their property_set attribute during their _passmanager_frontend() method, to seed initial properties. This provides symmetry, as it was previously only possible to read the final properties during _passmanager_backend().

• Added a new class OptimizationMetric which specifies the optimization criterion in the HighLevelSynthesis pass. Currently the two supported metrics are:

  • COUNT_2Q: optimizes the number of two-qubit gates.
  • COUNT_T: optimizes the number of T-gates, when transpiling into a Clifford+T basis set.

  The transpiler automatically selects the target metric based on the basis gate set, e.g. it will use COUNT_T if a Clifford+T basis set is detected. However, this class can not be currently set manually when running transpile() or running a preset pass manager generated by generate_preset_pass_manager().

• Added a new argument optimization_metric to the constructor for HighLevelSynthesis transpiler pass which takes an OptimizationMetric object. When set to COUNT_T, the pass chooses decompositions that are more suitable for the Clifford+T gate set.

• The default high-level synthesis plugins for ModularAdderGate and MultiplierGate produce better T-counts when transpiling into Clifford+T basis set.

• The default high-level synthesis plugin for MCXGate produces better T-counts when transpiling into Clifford+T basis set, provided at least 1 ancilla qubit is available.

• Added a default set of inverse gates for the InverseCancellation transpiler pass. Previously, an explicit list of gates or gate pairs to cancel was a required argument for the constructor of the pass object. Now this list is optional and if no list is provided the self inverse gates are:

  • CXGate
  • ECRGate
  • CYGate
  • CZGate
  • XGate
  • YGate
  • ZGate
  • HGate
  • SwapGate
  • CHGate
  • CCXGate
  • CCZGate
  • RCCXGate
  • CSwapGate
  • C3XGate

  and the inverse pairs:

  • TGate and TdgGate
  • SGate and SdgGate
  • SXGate and SXdgGate
  • CSGate and CSdgGate

  will be cancelled by the pass.

• Added a new argument to the InverseCancellation constructor, run_default, which when set to True will run the new default inverse cancellation gate list in addition to the any custom gates provided. This is intended for use cases where you want to run a custom set of inverse cancellations in addition to the default gates.

• TranspileLayout has two new methods: from_property_set() and write_into_property_set(), which formalize the current ad-hoc structure of transpilation properties, and how they are converted into a TranspileLayout. This makes it possible for passes during a transpiler pipeline to access what the TranspileLayout will be, modify it in the fully structured form, and then write it back out in canonical form.

  It is expected that in the future version 3.0 of Qiskit, the TranspileLayout (or something akin to it) will be a direct attribute of the DAGCircuit transpiler intermediate representation, and required by passes to be kept in sync with the rest of the DAGCircuit.

• Re-enabled running VF2PostLayout transpiler pass in the optimization stage for optimization_level=3 with the transpile() function and the generated pass manager objects returned by the generate_preset_pass_manager() function. The pass runs with strict_direction=True after all the physical optimizations performed in the stage to attempt and improve the layout one final time with the exact output circuit. This was previously enabled in Qiskit v2.1.0 but was reverted in 2.1.2 due to issues with the initial implementation. These issues have been fixed and the layout will be properly applied if a better one is found.

Visualization Features

• A new option, measure_arrows, has been added to the mpl and text backends for the circuit drawer qiskit.visualization.circuit_drawer() and qiskit.circuit.QuantumCircuit.draw(). When this option is set to True, the drawer will draw an arrow from the measure box to the classical bits below. This was the previous behavior in the drawers. If it is set to False, no arrows will be drawn and instead the classical register and bit being used by the measure will be indicated inside the measure box. This allows measure boxes to be stacked within a vertical layer.

  If no option is set, the default is True. The user can change the default in the user config file, by default in the ~/.qiskit directory, in the file settings.conf. Under the [Default] heading, a user can enter circuit_measure_arrows = False to change the default.

Upgrade Notes

• The minimum support Rust version for building Qiskit from source (including building the C API in standalone mode) has been increased from Rust 1.79 to Rust 1.85. This change was necessary to enable using a newer version of the Rust linear algebra library faer that is used inside Qiskit. There were issues identified when running Qiskit on Windows with the previous version of faer. These were fixed in the newer release, however a newer version of the Rust compiler is required to build the newer version of faer.

Circuits Upgrade Notes

• The circuit definition of ModularAdderGate has been upgraded to use adder_modular_v17(). To obtain the old behaviour, use the definition of adder_qft_d00() instead.

• The methods XGate.control(), CXGate.control(), CCXGate.control(), C3XGate.control(), C4XGate.control(), and MCXGate.control() no longer return an AnnotatedOperation when the argument annotated is set to True, and instead return the same explicit MCXGate that one would get when annotated is False. This is consistent with how the argument annotated is used across the standard circuit library, where we generally avoid introducing an AnnotatedOperation when a native gate class is already available. In practice, this leads to more efficient decompositions of control-annotated gates in the MCX family.

C API Upgrade Notes

• Most usage of uintptr_t` has been changed to size_t. Specifically the following usages have been changed:

  • QkOpCount::count
  • QkOpCounts::len
  • QkObsTerm::len
  • The return type of qk_circuit_num_instructions().
  • The index argument in qk_circuit_get_instruction().
  • The boundaries argument in qk_obs_new().
  • The return types of qk_obs_num_terms(), qk_obs_len(), and qk_obs_boundaries().
  • The return type of qk_target_entry_num_properties(), and qk_target_num_instructions().

  This change was necessary because the tool used to generate the C header files from Qiskit’s rust code, cbindgen was using uintptr_t by default in places where size_t more accurately aligned with the type usage in Rust. This change was made to make it more clear how the values in the C API are intended to be used.

QPY Upgrade Notes

• The default version of QPY emitted by qpy.dump() is now QPY format version 16. If you require a different format version you can use the version argument to specify an earlier format version.

Quantum Information Upgrade Notes

• SparsePauliOp.assign_parameters() will now set the dtype of the output coeffs array to complex if all parameters are fully bound to numeric values.

Synthesis Upgrade Notes

• The default values of the arguments opt_a1 and opt_a2 of qs_decomposition() are now opt_a1 = None and opt_a2 = None. The new defaults will choose the optimal value based on whether the input unitary for the mat argument is controlled or not to result in the minimal CXGate count by default. If you require the previous behavior you can explicitly call opt_a1 = True and opt_a2 = True to maintain the same behavior as previous releases.

Transpiler Upgrade Notes

• The circuit PassManager now always sets the properties original_circuit_indices and num_input_qubits before execution starts on individual passes. These are properties of the input circuit, which it was previously up to individual passes to set, often as a side effect of their primary purpose.

Circuits Deprecations

• The following classes in the circuit library are deprecated as of Qiskit 2.2 and will be removed in Qiskit 3.0. They have been replaced with modern gate equivalents.

  • ExactReciprocal --> ExactReciprocalGate
  • LinearAmplitudeFunction --> LinearAmplitudeFunctionGate
  • PhaseOracle --> PhaseOracleGate
  • PiecewisePolynomialPauliRotations --> PiecewisePolynomialPauliRotationsGate
  • QuantumVolume --> quantum_volume()

Bug Fixes

• ApplyLayout will now correctly handle the case of applying a zero-qubit Layout. Previously, it would claim that no layout had been set, even if the "layout" field of the PropertySet was equal to Layout().

• Fixed memory leakage issues during the creation of a QkOpCounts instance and during any calls to qk_opcounts_clear() whenever an empty instance is passed.

• Previously one could define an invalid PauliEvolutionGate from a list of operators, where the operators were not all defined on the same number of qubits. This is now fixed, and we now raise an error when the gate is defined:

  from qiskit.quantum_info import Pauli, SparsePauliOp
  from qiskit.circuit.library import PauliEvolutionGate
   
  pauli = Pauli("XYZ")  # 3 qubits
  op = SparsePauliOp(["XYIZ"], [1])  # 4 qubits
  evo = PauliEvolutionGate([pauli, op], time=1)

• Fixed an issue in the VF2Layout transpiler pass where even with a fixed seed set the output from the pass was potentially non-deterministic; specifically if the input circuit had any active qubits that only contained single qubit operations. Fixed #14729

• Fixed a bug in PassManager.run() where the callback function was not invoked when running with multiple circuits. The callback is now correctly triggered for each pass on each circuit, including in parallel execution.

• Fixed several problems in the CommutativeInverseCancellation transpiler pass. The pass now works correctly on circuits containing Clifford operations, control-flow operations, and non-invertible operations such as Initialize.

  In addition, the pass now always performs a syntactic (non-matrix-based) check first, when identifying inverse gate pairs. If the gates are not syntactically equal, the argument matrix_based is set to True, and the operation does not act on more than max_qubits qubits, then a matrix-based check is also performed. This slightly improves the reduction potential of the pass.

  Fixed #14407, #14635, and #14645.

• Fixed several issues in the CommutativeCancellation transpiler pass (and thereby in transpile()), where the global phase of the circuit was not updated correctly. In particular, merging an X-gate and an RX-gate introduced a phase mismatch, while removing a Pauli rotation gate with angle of the form $(2 + 4k)\pi$, $k \in \mathbb Z$ incorrectly produced a phase shift of $-1$.

• Fixed a problem in CommutationChecker, where standard controlled gates were not handled correctly if they were controlled on something other than the all-ones state. Fixed #14974

• Fixed a non-determinism in CommutativeCancellation. This did not affect the order returned by DAGCircuit.topological_nodes() or topological_op_nodes(), which typically should be used when node-order determinism is important, due to their built-in canonical sorting function. However, if inspecting the nodes by arbitrary order (DAGCircuit.op_nodes()) or the edge structure (DAGCircuit.edges()), the iteration order would be non-deterministic after a call to CommutativeCancellation.

• Fixed a bug in MCXGate.control(), where adding more controls to an open-controlled MCXGate did not take the ctrl_state of the controlled MCX gate into account, thus leading to an incorrect ctrl_state of the extended MCX gate. Note that the explicit MCX classes CXGate, CCXGate, C3XGate, and C4XGate were already handled correctly.

• Fixed the deprecation warning for Python 3.9 so that it correctly is identified as being caused by user code when importing Qiskit. Previously, it would not be identified as being caused by user code and this meant that Python’s default warning filters would not display the warning to the user.

• Fixed a bug in PhaseOracle, PhaseOracleGate and BitFlipOracleGate where trying to load from dimacs file raised a TypeError.

• Fixed a bug in the ElidePermutations transpiler pass, where the qubit mapping was not updated correctly in the presence of PermutationGates, leading to incorrect circuits and updates to the pass manager’s property set.

• Built-in transpiler passes that set the final_layout property will now correctly handle updating this field if it was already set. This can be observed as the method TranspileLayout.routing_permutation now returning a correct permutation after running more than one pass that sets final_layout.

  This did not affect any normal calls to transpile() or generate_preset_pass_manager() using Qiskit’s built-in plugins; no pipeline constructed in this form would attempt to set final_layout more than once.

• Fixed a bug in the HighLevelSynthesis pass where, if the circuit contained high level objects with classical registers, these would get mapped to the relative index in the object instead of the corresponding index in the outer circuit. The classical registers are now correctly mapped to the outer circuit index.

• Fixed a bug in Target.instruction_supported() where the check of instruction’s qubit order was skipped when the method was called with operation_name and parameters arguments that matched an existing instruction.

• Fixed the behavior of the max_trials argument for VF2Layout when set to None or a negative number. The pass was documented as limiting the search to being based on the size of the circuit or target if the option was set to None and as accepting negative values to specify an unbounded search. However in the 2.1.0 this behavior was incorrectly changed so that None ran an unbounded search and trying to use a negative number would raise an error. These oversights have been corrected so that the pass behaves as documented and is consistent with previous releases.

• Fixed a problem in high-level synthesis plugins MCXSynthesis1DirtyKG24 and MCXSynthesis2DirtyKG24 for MCXGate, where the plugins did not consider available clean auxiliary qubits as available dirty auxiliary qubits. In particular, the plugin MCXSynthesis2DirtyKG24 did not apply when one clean and one dirty auxiliary qubits were available.

• The PauliEvolutionGate.to_matrix() method now returns the exact matrix exponential $\exp(-it H)$, where $H$ is the operator and $t$ the time passed to the gate. This fixes an unexpected behavior, since the PauliEvolutionGate is documented to represent the exact time evolution, but previously the matrix was dependent on how the compiler approximates the time evolution. The to_matrix method is now consistent with the documentation.

• Fixed a performance regression when incrementally building ParameterExpression from combining a large number of sub-expressions. Fixed #14653

• Fixed a correctness bug when exporting circuits with delay instructions using ‘ps’ units to QASM3.

• Fixed an edge case in the display of the QFT circuit. Previously, when QFT.inverse() was called and then the attributes of the QFT circuit were modified, the QFT was displayed as "IQFT_dg". This was incorrect, and now it correctly shows "IQFT". Fixed #14758.

• Fixed a bug in the PauliEvolutionSynthesisRustiq plugin that produced incorrect circuits in the case that the operator of a PauliEvolutionGate contains objects of type SparseObservable.

  For example:

  from qiskit.circuit.library import PauliEvolutionGate
  from qiskit.quantum_info import SparseObservable, Operator
  from qiskit.transpiler.passes.synthesis.hls_plugins import PauliEvolutionSynthesisRustiq
   
  obs = SparseObservable.from_sparse_list([("1+XY", (0, 1, 2, 3), 1.5)], num_qubits=4)
  evo = PauliEvolutionGate(obs, 1)
  qct = PauliEvolutionSynthesisRustiq().run(evo)
  assert Operator(qct) == Operator(evo)

• Fixed an issue with the generate_preset_pass_manager() function where it would incorrectly ignore the timing constraints data contained in a Target object provided when the backend argument was not set. Fixed #14329

• Fixed a bug in ObservablesArray.coerce_observable() where an exception that an observable was not Hermitian was over-triggered. Observables equal to zero are not allowed and now invoke a graceful failure.

• qiskit.circuit.library.quantum_volume() was updated to handle a numpy.random.Generator as input for its seed argument. Previously, such a generator argument would result in a TypeError.

• QuantumCircuit.compose() will now correctly remap anyway variables and stretches used in Delay instructions when the var_remap argument is specified.

• SabreLayout uses a “dense subset” layout as one of its trials, following the same algorithm as DenseLayout. Previously, however, the version used by Sabre was assigning all virtual qubits, including dummy ancillas, to a physical qubit, compromising the effectiveness of the algorithm, but not its correctness. Sabre will now only use the virtual qubits defined by the user for this initial trial, which may result in small improvements in layout selection when averaged over large classes of circuit.

• Fixed a bug in SparsePauliOp.simplify() where the method removed Pauli terms based on their coefficients’ magnitudes before combining duplicates. This caused incorrect behavior in two key edge cases:

  1. When multiple identical Pauli terms had small coefficients that were individually below the simplification threshold but whose sum exceeded the threshold, those terms were incorrectly removed.
  2. When multiple identical Pauli terms had coefficients above the threshold but summed to near-zero, they were incorrectly kept.

  See #14194 for more detail.

• TranspileLayout.initial_index_layout() will now correctly handle the filter_ancillas=True argument if the virtual qubits in the initial_layout were not specified by the constructor in index order.

• VF2Layout and VF2PostLayout will now correctly include (arbitrary) layout assignments for completely idle qubits. Previously this might have been observed by calls to TranspileLayout.initial_index_layout() failing after a compilation.

• Fixed an issue in the VF2PostLayout transpiler pass. In certain situations when the pass is being run with the argument strict_direction=True there was a potential runtime scaling issue when the interaction graph of the circuit contained any qubits that only had 1 qubit operations. These mapping problems result in a combinatorial complexity for scoring that would lead to the pass almost always hitting the scoring timeout and typically not improving the layout. In strict_direction=False mode there is an optimized search implementation for these problems, but the additional constraints for strict_direction=True don’t make this approach viable. Instead in these cases VF2PostLayout will now skip the search since the layout problem isn’t viable for the pass.

Other Notes

• The implementation of Sabre routing used by SabreLayout and SabreSwap now compresses runs of nodes that will automatically become eligible for routing at the same time within its internal virtual-interaction representation. This improves the efficiency of the routing, reduces intermediate memory use, and avoids runs of 2q gates biasing the lookahead heuristic components.

2.1.0rc1

New Features

• Added C++ support for the C API. The generated header now allows calling objects and functions from C++ directly. For example, a 100-qubit observable with the term XYZ on the first 3 qubits can be constructed as

  #include <iostream>
  #include <complex>
  #include <vector>
  #include <qiskit.h>
   
  int main() {
      uint32_t num_qubits = 100;
   
      // Use smart pointer with custom deleter to manage QkObs memory
      QkObs *obs = qk_obs_zero(num_qubits);
   
      // Construct the observable term
      std::complex<double> coeff = 2.0;
      std::vector<QkBitTerm> bit_terms = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z};
      std::vector<uint32_t> indices = {0, 1, 2};
   
      QkObsTerm term {
          .coeff      = coeff,
          .len        = bit_terms.size(),
          .bit_terms  = bit_terms.data(),
          .indices    = indices.data(),
          .num_qubits = num_qubits
      };
   
      qk_obs_add_term(obs.get(), &term);
   
      // Print observable properties
      std::cout << "num_qubits: " << qk_obs_num_qubits(obs) << "\n";
      std::cout << "num_terms: "  << qk_obs_num_terms(obs)  << "\n";
   
      qk_obs_free(obs);
      return 0;
  }

  Note that std::complex<double> is compatible with QkComplex64.

• Improved synthesis of multi-controlled CZGate gates.

• Improved the default plugin for synthesizing AnnotatedOperation objects. The improvement is especially useful when creating and transpiling controlled circuits with controlled gates within them. For example:

  from qiskit.circuit import QuantumCircuit
  from qiskit.circuit.library import CXGate
  from qiskit.compiler import transpile
   
  inner = QuantumCircuit(5)
  inner.append(CXGate().control(3, annotated=True), [0, 1, 2, 3, 4])
  controlled_inner_gate = inner.to_gate().control(2, annotated=True)
  qc = QuantumCircuit(15)
  qc.append(controlled_inner_gate, [0, 1, 2, 3, 4, 5, 6])
  qct = transpile(qc, basis_gates=["cx", "u"])

  This code creates a quantum circuit qc that contains a 2-controlled quantum circuit with a 3-controlled CX-gate within it. With the improvement, the number of CX-gates in the transpiled circuit is reduced from 378 to 30. Note that by specifying annotated=True when defining control logic, the controlled gates are created as annotated operations. This avoids eager synthesis, allows the transpiler to detect that controlled_inner_gate is equivalent to a 6-controlled X-gate, and to choose the best synthesis method available for multi-controlled X-gates, in particular utilizing available ancilla qubits.

• The function adder_qft_d00() used for synthesize ModularAdderGate and HalfAdderGate gates now accepts an addional parameter annotated. If True, the inverse-QFT-gate within the adders is implemented as an annotated operations, allowing the transpiler to apply additional optimizations.

• Incorporated the SparseObservable class with the ObservablesArray class. * There is no change in behavior of existing methods of ObservablesArray, except for the method coerce_observable(), whose return type is changed to SparseObservable. * The new method apply_layout() performs an apply_layout operation on each observable in the array. * The new method equivalent() returns True if two arrays store equivalent observables. * The new methods get_sparse_observable() and sparse_observables_array() return information about the contents of the array. * Estimator pubs can now be defined using SparseObservable objects, in addition to the existing options of str, Pauli, SparsePauliOp, and Mapping[Union[str, Pauli], float]. However projective observables are not yet supported when executing circuits. Projective observables are 0, 1, +, -, r, l. Currently only Pauli’s are supported: I, X, Y, Z.

• Introduces the QubitSparsePauli, QubitSparsePauliList, and PauliLindbladMap classes. These classes represent, respectively, a single phase-less Pauli operator, a list of phase-less Pauli operators, and a Pauli Lindblad map, all stored in qubit-sparse format.

C API Features

• Added support for querying the Qiskit version via the C API using the following definitions:

  • QISKIT_VERSION: The version as human readable char* (e.g. "2.2.0").
  • QISKIT_VERSION_HEX: The version as HEX.
  • QISKIT_VERSION_MAJOR: The major version number.
  • QISKIT_VERSION_MINOR: The minor version number.
  • QISKIT_VERSION_PATCH: The patch version number.
  • QISKIT_RELEASE_LEVEL: The release level, e.g. 0xF for final or 0xC for release candidates.
  • QISKIT_RELEASE_SERIAL: The release serial, e.g. 1 for the first release candidate.
  • QISKIT_GET_VERSION_HEX: A macro returning the version a HEX, given major, minor, patch, level, and serial.

  For example, to check if the current version is at least 2.2.0, you can use:

  if (QISKIT_VERSION_HEX >= QISKIT_GET_VERSION_HEX(2, 2, 0, 0xF, 0)) {
      // Code for version 2.2.0 (final) or later
  }

Circuits Features

• Added a function random_circuit_from_graph() that generates a random circuit that induces the same interaction graph as the interaction graph specified by interaction_graph.

  The probability of randomly drawing an edge from the interaction graph as a two-qubit gate can be set by the user in the weight attribute of an edge in the input interaction graph. If the user does not set the probability, each edge is drawn uniformly, i.e. each two-qubit gate represented by an edge in the interaction graph has the same probability of getting added to the random circuit. If only a subset of edge probabilities are set, ValueError will be raised.

  This is an example where ‘cp_map’ is a list of edges with some arbitrary weights.

  from qiskit.circuit.random.utils import random_circuit_from_graph
  import rustworkx as rx
  pydi_graph = rx.PyDiGraph()
  n_q = 5
  cp_map = [(0, 1, 0.18), (1, 2, 0.15), (2, 3, 0.15), (3, 4, 0.22)]
  pydi_graph.add_nodes_from(range(n_q))
  pydi_graph.add_edges_from(cp_map)
  # cp_map can be passed in directly as interaction_graph
  qc = random_circuit_from_graph(interaction_graph = pydi_graph,
    min_2q_gate_per_edge = 1, 
    max_operands = 2, 
    measure = True, 
    conditional = True, 
    reset = True, 
    seed = 0, 
    insert_1q_oper = True, 
    prob_conditional = 0.21,
    prob_reset = 0.1)
  qc.draw(output='mpl')

  

• Added QuantumCircuit.has_control_flow() to check if a circuit contains any control flow operations.

• A new module qiskit.circuit.annotation and principle object Annotation have been added.

  Annotations are a way of tagging instructions (currently only BoxOp, in the initial implementation) with local, user-custom data. This data is intended to be consumed by custom transpiler passes. Annotations provide a way to attach data to specific instructions, rather than using the global-context object PropertySet during compilation.

  All Annotation objects have a namespace. This string key is used for lookups, so consumers can tell if they handle a particular annotation or not. There are currently no methods for querying any abstract semantics of an Annotation subclass, but these are expected to expand in the future.

  See qiskit.circuit.annotation for a full discussion of the capabilities and use cases.

• BoxOp instances (created by QuantumCircuit.box()) can now be annotated with custom Annotation instances. The equality of two boxes depends on the annotations being equal.

  Typically, this is achieved by passing a list of annotations as the sole positional argument when using QuantumCircuit.box() in context-manager form:

  from qiskit.circuit import annotation, QuantumCircuit
   
  class MyAnnotation(annotation.Annotation):
      namespace = "my.annotation"
   
      def __eq__(self, other):
          return isinstance(other, MyAnnotation)
   
  qc = QuantumCircuit()
  with qc.box([MyAnnotation()]):
      pass

• The C API for Qiskit has been extended with support for building and interacting with quantum circuits.

• Improve the synthesis of a multi-controlled U1Gate, so that it will not grow exponentially with the number of controls.

• The BoxOp.duration field can now be an expr.Expr node with type Duration, just like Delay.duration. This includes stretches.

• Adds an equivalence between an XXPlusYYGate and its decomposition into an RXXGate followed by an RYYGate to the equivalence library.

Primitives Features

• To make PrimitiveJob serializable, DataBin has been updated to be pickleable. As a result, PrimitiveResult is now also pickleable.

OpenQASM Features

• qasm3.dump() and qasm3.dumps() have a new annotation_handlers argument, which is used to provide instances of annotation.OpenQASM3Serializer to the OpenQASM 3 export process, which can serialize custom Annotation objects to OpenQASM 3.

• When qiskit_qasm3_import>=0.6.0 is installed, qasm3.load() and qasm3.loads() have a new annotation_handlers argument, which is used to provide instances of annotation.OpenQASM3Serializer to the OpenQASM 3 import process, which can deserialize custom Annotation objects from OpenQASM 3. This support is currently limited to box statements, as this is the only place Qiskit can represent annotations in its data model.

QPY Features

• QPY version 15 is released, including support for the new Annotation objects, with support from external serializers and deserializers. The format allows such serializers to be stateful, and safe places in the binary format are allocated for the custom state objects and custom annotation representations.

• qpy.dump() and qpy.load() now have an optional annotation_factories argument, which is used to provide constructor functions of annotation.QPYSerializer objects to handle Annotation subclasses. These must be supplied by the user, similar to metadata_serializer, as in general, Qiskit cannot know about all possible externally-defined Annotation objects.

• Added a new function get_qpy_version() to the qpy() module. This function will inspect a QPY file and retrieve the QPY format version used in the payload. The version is returned as an integer, which can be used for logging or debugging purposes. see #14201.

Synthesis Features

• Added new synthesis algorithm for HalfAdderGate that requires no ancillary qubits and has better CX count compared to adder_qft_d00():

  • adder_ripple_r25()

• Added new decompositions for MCXGate utilizing clean ancillae, improving circuit depth and efficiency:

  • synth_mcx_1_clean_kg24(), using 1 additional clean ancilla qubit
  • synth_mcx_1_dirty_kg24(), using 1 additional dirty ancilla qubit
  • synth_mcx_2_clean_kg24(), using 2 additional clean ancillary qubits
  • synth_mcx_2_dirty_kg24(), using 2 additional dirty ancillary qubits

  Example usage:

  from qiskit.synthesis.multi_controlled import synth_mcx_1_clean_kg24
   
  n_ctrls = 10
  qc = synth_mcx_1_clean_kg24(n_ctrls)
  qc.draw()

• The Quantum Shannon Decomposition (qs_decomposition()) includes an optimization that reduces the CXGate count in the case that the input unitary happens to be a controlled unitary.

• The synthesis function synth_mcx_1_clean_b95() now produces a circuit with fewer CX-gates.

• The SolovayKitaevDecomposition class has additional arguments in the initializer, which allows it to be directly constructed from a set of basis_gates and a depth for the basic approximations.

• Added SolovayKitaevDecomposition.save_basic_approximations() to save the set of basic approximations the class uses into a binary format. This change, in combination with the new initializer arguments, allows to skip the explicit use of generate_basic_approximations() and only rely on SolovayKitaevDecomposition.

• The standard equivalence library has additional equivalences for CSGate and CSdgGate. When transpiling to the [“cx”, “u”] basis set, the BasisTranslator transpiler pass now uses 2 CXGate gates instead of 3 for CSdgGate, and in addition reduces the number of single-qubit gates in both cases.

Transpiler Features

• The function generate_preset_pass_manager() now generates a special pass manager when the basis set consists of Clifford+T gates only. Formally, a Clifford+T basis set must contain either a TGate or TdgGate (or both), and only Clifford gates in addition. The full list of supported Clifford gates can be obtained using get_clifford_gate_names().

  For example:

  from qiskit.circuit import QuantumCircuit
  from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
  from qiskit.quantum_info import get_clifford_gate_names
   
  basis_gates = get_clifford_gate_names() + ["t", "tdg"]
  pm = generate_preset_pass_manager(basis_gates=basis_gates)
   
  qc = QuantumCircuit(1)
  qc.rx(0.8, 0)
  qct = pm.run(qc)
  print(qct.count_ops())

  Previously, the generated pass manager was not able to handle the example above, as it was not able to decompose single-qubit rotation gates of type UGate into Clifford+T gates. Instead, the new pass manager uses the the Solovay-Kitaev decomposition to approximate single-qubit rotation gates using H, T and Tdg gates, and calls the BasisTranslator transpiler pass to further translate the gates into the target basis set. The new pass manager also has other changes as to enable a more efficient translation into Clifford+T gates.

  It is important to note that the specified Clifford+T basis gate set should be universal, or else transpilation might not succeed. While the gate set ["h", "t", "tdg"]``or even ``["h", "t"] is sufficient for universality, it is recommended to add more Clifford gates to the set if possible, as otherwise the translation might be less efficient. For example, not including S-gate might trigger decomposing S-gates into pairs of T-gates (that is, decomposing Clifford gates into non-Clifford gates, which might not be the desired behavior).

  Here is an additional slightly larger example:

  from qiskit.circuit import QuantumCircuit
  from qiskit.circuit.library import QFTGate
  from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
   
  qc = QuantumCircuit(4)
  qc.append(QFTGate(4), [0, 1, 2, 3])
   
  basis_gates = ["cx", "s", "sdg", "h", "t", "tdg"]
  pm = generate_preset_pass_manager(basis_gates=basis_gates, optimization_level=2)
   
  qc = QuantumCircuit(4)
  qc.append(QFTGate(4), [0, 1, 2, 3])
   
  qct = pm.run(qc)
  print(qct.count_ops())

• Added new high-level-synthesis plugin for synthesizing a HalfAdderGate:

  • HalfAdderSynthesisR25, based on adder_ripple_rv_25().

  The HalfAdderSynthesisDefault has also been updated to follow the following sequence of half adder synthesizers: "HalfAdder.ripple_r25" when the number of qubits is $\leq 3$, "HalfAdder.ripple_c04" when 1 ancillary qubit is available, "HalfAdder.ripple_r25" in all remaining cases.

• Added multiple high-level-synthesis plugins for synthesizing an MCXGate:

  • MCXSynthesis1CleanKG24, based on synth_mcx_1_clean_kg24().
  • MCXSynthesis1DirtyKG24, based on synth_mcx_1_dirty_kg24().
  • MCXSynthesis2CleanKG24, based on synth_mcx_2_clean_kg24().
  • MCXSynthesis2DirtyKG24, based on synth_mcx_2_dirty_kg24().

  The MCXSynthesisDefault has also been updated to follow the following sequence of MCX synthesizers: “mcx.2_clean_kg24”, “mcx.1_clean_kg24”, “mcx.n_clean_m15”, “mcx.n_dirty_i15”, “mcx.2_dirty_kg24”, “mcx.1_dirty_kg24” “mcx.1_clean_b95”, “mcx.noaux_v24”.

• VF2PostLayout has been added at the end of the default optimization stage when using optimization level 3.

• Support for creation and interaction with the Target have been added to the Qiskit C API.

  Here’s an example of how it is used:

  #include <qiskit.h>
  #include <math.h>
  
  // Create a Target with space for 2 qubit operations
  QkTarget *target = qk_target_new(2);
  
  // Create a Target Entry for a CRX Gate with fixed parameters
  double crx_params[1] = {3.14};
  QkTargetEntry *cx_entry = qk_target_entry_new_fixed(QkGate_CRX, crx_params);
  
  // Add mapping between (0, 1) and properties duration of 1.93e-9 and error 3.17e-10.
  uint32_t qargs[2] = {0, 1};
  qk_target_entry_add(entry, qargs, 2, 1.93e-9, 3.17e-10);
  // Add mapping between (1, 0) and properties duration of 1.27e-9 and no error.
  uint32_t rev_qargs[2] = {1, 0};
  qk_target_entry_add(entry, rev_qargs, 2, 1.27e-9, NAN);
  
  // Add CRX entry to the target.
  QkExitCode result_crx = qk_target_add_instruction(target, entry);
  
  // Add global Y gate entry to the target
  QkExitCode result_crx = qk_target_add_instruction(target, qk_target_entry_new(QkGate_Y));

• Added a new OptimizeCliffordT transpiler optimization pass that merges pairs of consecutive T-gates into S-gates and pairs of consecutive Tdg-gates into Sdg-gates. This optimization is particularly effective for reducing T-count following Solovay-Kitaev decomposition, which produces multiple consecutive T or Tdg gates. For example:

  from qiskit.circuit import QuantumCircuit
  from qiskit.transpiler.passes import SolovayKitaev, OptimizeCliffordT
   
  qc = QuantumCircuit(1)
  qc.rx(0.8, 0)
   
  # Run Solovay-Kitaev pass on qc
  transpiled = SolovayKitaev()(qc)
  print(transpiled.count_ops().get("t", 0) + transpiled.count_ops().get("tdg", 0))
   
  # Run Clifford+T optimization
  optimized = OptimizeCliffordT()(transpiled)
  print(optimized.count_ops().get("t", 0) + optimized.count_ops().get("tdg", 0))

• Added the ContextAwareDynamicalDecoupling pass, which implements a context-aware dynamical decoupling based on Walsh-Hadamard sequences. The inserted delay sequences will be mutually orthogonal to sequences on neighboring qubits, and take into account control/target spectators of CX and ECR gates. See arXiv:2403.06852 for more information.

  Example:

  from qiskit.circuit.library import QFT
  from qiskit.transpiler import PassManager
  from qiskit.transpiler.passes import ALAPScheduleAnalysis, ContextAwareDynamicalDecoupling
  from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
  from qiskit_ibm_runtime.fake_provider import FakeSherbrooke
   
  num_qubits = 10
  circuit = QFT(num_qubits)
  circuit.measure_all()
   
  target = FakeSherbrooke().target
   
  pm = generate_preset_pass_manager(optimization_level=2, target=target)
  dd = PassManager([
      ALAPScheduleAnalysis(target=target),
      ContextAwareDynamicalDecoupling(target=target),
  ])
   
  transpiled = pm.run(circuit)
  with_dd = dd.run(transpiled)
   
  print(with_dd.draw(idle_wires=False))

• Adds DAGCircuit attributes num_stretches, num_captured_stretches, and num_declared_stretches.

• Added a new unitary synthesis plugin CliffordUnitarySynthesis that attempts to syntesize a given unitary gate by checking if it can be represented by a Clifford, in which case it returns a circuit implementing this unitary and consisting only of Clifford gates.

  The plugin is invoked by the UnitarySynthesis transpiler pass when the parameter method is set to "clifford".

  In addition, the parameter plugin_config of UnitarySynthesis can be used to pass the following plugin-specific parameters:

  • min_qubits: the minumum number of qubits to consider (the default value is 1).
  • max_qubits: the maximum number of qubits to consider (the default value is 3).

  For example:

  import math
   
  from qiskit.circuit import QuantumCircuit
  from qiskit.circuit.library import UnitaryGate
  from qiskit.quantum_info import Operator
  from qiskit.transpiler.passes import UnitarySynthesis
   
  # clifford unitary over 2 qubits
  c2 = QuantumCircuit(2)
  c2.h(0)
  c2.rz(math.pi / 4, 1)
  c2.rz(math.pi / 4, 1)
  c2.sdg(1)
  uc2 = UnitaryGate(Operator(c2).data)
   
  # non-clifford unitary over 2 qubits
  n2 = QuantumCircuit(2)
  n2.h(0)
  n2.rz(math.pi / 4, 1)
  n2.sdg(1)
  un2 = UnitaryGate(Operator(n2).data)
   
  # quantum circuit with two unitary gates
  qc = QuantumCircuit(3)
  qc.append(uc2, [2, 1])
  qc.append(un2, [0, 2])
   
  transpiled = UnitarySynthesis(method="clifford")(qc)

  Executing the code above resynthesized the first unitary gate into Clifford gates, while the second gate remains unchanged.

  If we modify the example above as follows:

  config = {"min_qubits": 3}
  transpiled = UnitarySynthesis(method="clifford", plugin_config=config)(qc)

  then both unitary gates remain unchanged.

Visualization Features

• Introduced custom styles for the dag_drawer() function. This allows you to pass a dictionary to the style parameter with custom attributes that changes the style of the DAG the function returns. For example:

  from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
  from qiskit.converters import circuit_to_dag
  from qiskit.visualization import dag_drawer
   
  q = QuantumRegister(3, 'q')
  c = ClassicalRegister(3, 'c')
  circ = QuantumCircuit(q, c)
  circ.h(q[0])
  circ.cx(q[0], q[1])
  circ.measure(q[0], c[0])
  circ.rz(0.5, q[1]).c_if(c, 2)
   
  dag = circuit_to_dag(circ)
   
  style = {
      "inputnodecolor": "pink",
      "outputnodecolor": "lightblue",
      "opnodecolor": "red",
  }
   
  dag_drawer(dag, style=style)

• Box instructions whose vertical spans do not overlap are now rendered in the same vertical slice, when possible.

Upgrade Notes

• The python-dateutil library is no longer a dependency of Qiskit. Since Qiskit 2.0.0 nothing in the library was actively using the library anymore and Qiskit didn’t actually depend on the library anymore. This release removes it from the dependency list so it is not automatically installed as a prerequisite anymore. If you were relying on Qiskit to install dateutil for you as a dependency you will now need to ensure you’re manually installing it (which is best practice for direct dependencies).

• sympy is no longer a requirement for installing Qiskit. After the migration to a Rust based symbolic engine for the ParameterExpression class the uses of SymPy are isolated to some visualization utilities, the TemplateOptimization transpiler pass, ParameterExpression.sympify() (which is explicitly for SymPy interoperability) and SparsePauliOp.simplify() if using parameterized coefficients. This functionality is not the most commonly used so SymPy is now treated as an optional dependency and those functions will raise a MissingOptionalLibrary exception if they’re used and SymPy is not installed.

• The dependency on symengine which was used for building ParameterExpression objects has been removed. It has been replaced by a internal symbolic engine and is no longer required for core functionality in Qiskit. The only exception is that symengine was embedded into QPY formats 10, 11, and 12 so it is still required if you are deserializing those formats. The dependency on symengine for qpy.load() was made explicitly optional in 2.0.0, but if you were previously relying on symengine getting installed by default for this functionality you will now need to manually install it to load the payload.

Circuits Upgrade Notes

• The circuit definition of HalfAdderGate has been upgraded to use adder_ripple_r25(). To obtain the old behaviour, use the definition of adder_qft_d00() instead.

• excitation_preserving() and ExcitationPreserving now use a single XXPlusYYGate where before it used an RXXGate followed by an RYYGate.

• The control method of UnitaryGate now uses qs_decomposition() instead of Isometry for decomposition. This change reduces the number of CXGate by approximately 2x.

• The definitions of certain standard gates have been updated according to the following principles:

  • When available, a definition using Clifford gates is preferred over one that includes non-Clifford gates.
  • When available, a definition using Clifford+T gates is preferred over one that includes UGate.
  • The use of PhaseGate is preferred over U1Gate.
  • The use of UGate is preferred over U2Gate and U3Gate.

  Crucially, the following invariant still holds: by recursively expanding gate definitions, any gate can be ultimately expressed using only the ["cx", "u"] basis.

• Qiskit now uses its own, Rust-based symbolic expression library to implement the internals of ParameterExpression and Parameter. As this is a new implementation of the core symbolic math engine used for ParameterExpression there might be minor differences in the exact behavior of some functionality. It should always produce equivalent results for the documented API. Please open an issue if there are any problems with correctness found.

Synthesis Upgrade Notes

• The synthesis function synth_mcx_1_clean_b95() now produces a circuit with fewer layers of wrappings.

• The serialization format in for basic approximations in the Solovay Kitaev algorithms has been changed from .npy to another binary format, based on Rust’s serde and bincode. All routines loading basic approximations (such as generate_basic_approximations(), SolovayKitaevDecomposition.load_basic_approximations() or the initializer of SolovayKitaev) still support loading the legacy format. Any new file, however, will be stored in the new format. If you relied on the old format, downgrade Qiskit to <2.2 and store the required files.

• The default values for SolovayKitaev (and related classes) have increased to depth=12 and reps=5. This is due to the underlying implementation now being in Rust, which allows us to increase the default precision, while still being significantly faster than the previous Python version.

Transpiler Upgrade Notes

• The built-in layout plugins for the present pass managers will no longer contain their principal component (e.g. a SabreLayout instance for the “sabre” stage) if no coupling constraints are provided. Previously, the plugins would construct invalid instances of their layout passes, under an assumption that separate logic would prevent the passes from executing and raising exceptions.

  This should have no meaningful effect on the use of the preset pass managers or the plugins, since it was already never valid to call the passes in an invalid state .

Deprecation Notes

• Support for running Qiskit with Python 3.9 has been deprecated and will be removed in the Qiskit 2.3.0 release. The 2.3.0 is the first release after Python 3.9 goes end of life and is no longer supported. [1] This means that starting in the 2.3.0 release you will need to upgrade the Python version you’re using to Python 3.9 or above.

  [1] https://devguide.python.org/versions/

C API Deprecations

• Deprecated the macro QISKIT_VERSION_NUMERIC in favor of the direct replacement QISKIT_GET_VERSION_HEX. This macro can be used to generate a hexanumeric version format from decimal version numbers.

Circuits Deprecations

• The circuit library underwent a refactoring in the Qiskit 1.3 release, in which alternatives for objects of type QuantumCircuit were provided that are either a Instruction or a Python function for construction. This refactoring allows the compiler to reason about high-level instructions, and reduces the overhead for circuits that do not require high-level optimizations.

  All QuantumCircuit subclasses are now deprecated in favor of their alternatives introduced in Qiskit 1.3. As part of this, the BlueprintCircuit is also deprecated. All have an extended deprecation period and will only be removed for Qiskit 3.0.

  The BlueprintCircuit does not have a direct replacement, instead use a QuantumCircuit directly or a function that generates circuits. See qiskit.circuit.library and the migration guide for more details, but some common circuits have the following replacements:

  • QFT --> QFTGate
  • TwoLocal --> n_local() (this is not a typo, this function covers the NLocal and TwoLocal functionality)
  • EfficientSU2 --> efficient_su2()
  • RealAmplitudes --> real_amplitudes()
  • ZZFeatureMap --> zz_feature_map()
  • QuantumVolume --> quantum_volume()
  • EvolvedOperatorAnsatz --> evolved_operator_ansatz()
  • MCXGrayCode --> synth_mcx_gray_code()
  • MCXRecursive --> synth_mcx_n_dirty_i15()
  • MCXVChain --> synth_mcx_n_clean_m15()

• The deprecated tuple-like interface for CircuitInstruction was not removed in this release as originally planned. It will be removed in Qiskit 3.0.0 instead. Instead, use the operation, qubits, and clbits named attributes.

Security Issues

• Fixed a security vulnerability in qpy.load() when loading payloads that use sympy to serialize ParameterExpression objects and other symbolic expressions. This potentially includes any QPY payload using QPY version < 10, and optionally 10, 11, and 12 depending on the symbolic encoding used in the serialization step (qpy.dump()).

Bug Fixes

• Fixes a bug where style=plain did not show circuit labels for the nodes of the DAG.

• Fixed a visualization bug in the text circuit drawer where post-transpilation control-flow operations could have their closing “bracket” rendered vertically out of order. See #14271 for more detail.

• Fixed a bug in the UnitarySynthesis transpiler pass, where the pass ignored the synth_gates parameter and only synthesized the unitary gates. The pass now correctly synthesizes all gates specified in the synth_gates parameter. Fixed #14343.

• Fixed edge-cases in the Makefile configuration for Windows, where the pre-defined environment variable OS did not match the output of the uname -s command.

• Fixed the name of the OrGate, that was set to “and” instead of “or”, and could have possibly led to several problems.

• Fixed an issue in the ConsolidateBlocks transpiler pass where it would fail to consolidate some blocks if the KAK gate selected (either directly or via the target) is supercontrolled and not CXGate. Fixed #14413

• Fixed a bug in DAGCircuit that would cause output Var nodes to become input nodes during deepcopy and pickling.

• Fixed an oversight in the Target class where setting a new value for the dt attribute and subsequently calling target.durations() would not show the updated dt value in the returned InstructionDurations object. This is now fixed through an invalidation of the internal target instruction durations cache in the dt setter.

• Added missing repr support for Duration.

• Added missing support for Python pickling of Duration. This was preventing parallel transpilation of circuits with delay() instructions that use duration expressions.

• Fixed a problem in BasisTranslator transpiler pass, where the global phase of the DAG was not updated correctly. Fixed #14074.

• Fixed a problem in HighLevelSynthesis transpiler pass that caused it to erroneously terminate early on certain circuits with control flow operations. Fixed #14338

• Fixed the construction of Instantaneous Quantum Polynomial time (IQP) circuits in IQP and by iqp(). The previous implementation incorrectly used powers of the $\sqrt{T}$ gate instead of powers of the $T$ gate.

• Fixed a bug in the PauliEvolutionSynthesisDefault and PauliEvolutionSynthesisRustiq plugins that modified the .synthesis attribute of the original circuit when setting preserve_order=False. The behavior of the plugins has been restored and the original circuit is now preserved throughout the transpilation pipeline.

• Fixed a bug in meth qpy.load where it could fail to deserialize circuits whose parameters had been re-assigned to parameters with the same names. Fixed #13720, #13720, and #13720.

• Fixed a bug in QPY (qiskit.qpy) where circuits containing gates of class MCMTGate would fail to serialize. See #13965.

• SabreLayout and SabreSwap will no longer panic when applying the routing result to a circuit that uses expr.Var or Stretch objects in a nested control-flow scope.

• SabreLayout will now correctly propagate a circuit’s name and metadata fields when performing as a joint layout and routing pass.

• Fixed a problem in the SolovayKitaevSynthesis unitary synthesis plugin, where repeatedly running the plugin with different basis gates incorrectly reused the basis gates from the first run only. The problem was due to ignoring the basis gates when caching basic approximations, and is now fixed.

• Fixed a problem in the SolovayKitaev transpiler pass where the pass could crash due to encountering a 180 degree rotation in the internal recursion, which was not handled correctly.

• Fixed a problem in the SolovayKitaev transpiler pass where the generated approximation could have a phase that differs by $\pi$ from the correct value. This resulted due to the internal $SO(3)$ representation, which requires additional handling to obtain the correct sign of the qubit gate matrix. Fixed #9552

• GenericBackendV2 now correctly allows BoxOp when control_flow=True.

• When synthesizing an MCXGate gate with 3 controls, the synthesis functon synth_mcx_n_dirty_i15() used to require one auxiliary qubit, producing a circuit with 5 qubits (3 control, 1 target, and 1 auxiliary). However, the actual synthesis algorithm does not make use of this auxiliary qubit. This behavior is now fixed: the synthesized circuit is over 4 qubits (3 control and 1 target), allowing to apply the synthesis function in a slighty larger number of cases.

• Circuits containing delays with stretches (see QuantumCircuit.add_stretch()) can now successfully compile using the preset pass-managers (transpile() and generate_preset_pass_manager()) when targetting a backend that has alignment constraints, for example IBM Quantum Eagle devices like ibm_sherbrooke.

• The fallback error heuristic in VF2Layout and VF2PostLayout, used when there were no reported error rates, could previously assign errors greater than one, and have unpredictable effects on the resulting layout scores.

Other Notes

• A new optional extra dependency variant qpy-compat was added. This target should be installed if you plan to load qpy files as it installs extra requirements used for loading QPY files using format versions < 13. If you are only using newer qpy format you do no need to install this. By default qpy.dump() only generates QPY >=13. You can install this new optional variant with pip install qiskit[qpy-compat]`

• The relative weights of the “basic” and “lookahead” components of the SabreSwap and SabreLayout heuristics have been modified when extended-set tracking is active (as it always is in SabreLayout, and is by default in SabreSwap). The heuristic component relating to the distance between qubits in an individual gate in the front layer now no longer weakens proportional to the number of gates in the front layer; this behavior was a historical choice, but at large circuit sizes, has the accidental effect of causing the front layer to be nearly ignored, which is disastrous for efficiency.

  The resulting routing improvements should be most noticeable for circuits that can frequently be stratified into layers of more than 20 parallel two-qubit gates.

• The Matplotlib circuit drawer will now insert less extraneous space inside the left edge when drawing BoxOp instances in circuits.

2.0.0rc1

Prelude

This release adds support for stretch variables to QuantumCircuit which are used to express relationships between instruction durations. For example, in order to ensure a sequence of gates between two barriers will be left-aligned, whatever their actual durations may be, we can do the following:

from qiskit import QuantumCircuit
from numpy import pi
 
qc = QuantumCircuit(5)
qc.barrier()
qc.cx(0, 1)
qc.u(pi/4, 0, pi/2, 2)
qc.cx(3, 4)
 
a = qc.add_stretch("a")
b = qc.add_stretch("b")
c = qc.add_stretch("c")
 
# Use the stretches as Delay duration.
qc.delay(a, [0, 1])
qc.delay(b, 2)
qc.delay(c, [3, 4])
qc.barrier()

For additional context and examples, refer to the OpenQASM 3 language specification.

New Features

• Support for the Linux aarch64 platform has been promoted to tier 1 support as documented in:

  /guides/install-qiskit#operating-system-support

  from its previous support level of tier 2 in the 1.x release series.

• Introduced a C API to build and interact with sparse observables. While the API surface in this release is fairly small, just covering the SparseObservable class this new API lays the foundation for Qiskit’s C interface.

  The detailed syntax and more information is available under the C API docs, but a minimal example to construct the 100-qubit observable X0 Y1 Z1 is:

  #include <complex.h>
  #include <qiskit.h>
  #include <stdint.h>
  #include <stdio.h>
   
  int main(int argc, char *argv[]) {
      // build a 100-qubit empty observable
      uint32_t num_qubits = 100;
      QkObs *obs = qk_obs_zero(num_qubits);
   
      // add the term 2 * (X0 Y1 Z2) to the observable
      complex double coeff = 2;
      QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z};
      uint32_t indices[3] = {0, 1, 2};
      QkObsTerm term = {coeff, 3, bit_terms, indices, num_qubits};
      qk_obs_add_term(obs, &term);
   
      // print some properties
      printf("num_qubits: %u\n", qk_obs_num_qubits(obs));
      printf("num_terms: %lu\n", qk_obs_num_terms(obs));
   
      // free the memory allocated for the observable
      qk_obs_free(obs);
   
      return 0;
  }

Circuits Features

• Added a new get_control_flow_name_mapping() convenience function that returns a mapping of Qiskit’s control-flow operation names to their corresponding class. Example usage:

  from qiskit.circuit import get_control_flow_name_mapping
   
  ctrl_flow_name_map = get_control_flow_name_mapping()
  if_else_object = ctrl_flow_name_map["if_else"]
   
  print(if_else_object)

  <class 'qiskit.circuit.controlflow.if_else.IfElseOp'>

• Added a new method, QuantumCircuit.estimate_duration(), to compute the estimated duration of a scheduled circuit output from the transpiler. This should be used if you need an estimate of the full circuit duration instead of the deprecated QuantumCircuit.duration attribute.

• The new BitFlipOracleGate and PhaseOracleGate have the same interface as PhaseOracle (except the evaluate_bitstring method). Bit-flip oracle gate synthesizes a bit flip oracle instead of a phase flip oracle, meaning it acts on one additional qubit and can be seen as applying a controlled X operation, where the control is the value of the expression encoded by the oracle.

  from qiskit import QuantumCircuit
  from qiskit.circuit.library.bit_flip_oracle import BitFlipOracleGate
  from qiskit.circuit.library.phase_oracle import PhaseOracleGate
  qc = QuantumCircuit(5)
  bool_expr = "(x0 & x1 | ~x2) & x4"
  oracle = BitFlipOracleGate(bool_expr)
  qc.compose(oracle, inplace=True)
  print(qc)

       ┌─────────────────────┐
  q_0: ┤0                    ├
       │                     │
  q_1: ┤1                    ├
       │                     │
  q_2: ┤2 (x0 & x1 | ~x2)... ├
       │                     │
  q_3: ┤3                    ├
       │                     │
  q_4: ┤4                    ├
       └─────────────────────┘

  print(qc.decompose())

  q_0: ──o────■────■──
         │    │    │  
  q_1: ──┼────o────■──
         │    │    │  
  q_2: ──o────o────┼──
         │    │    │  
  q_3: ──■────■────■──
       ┌─┴─┐┌─┴─┐┌─┴─┐
  q_4: ┤ X ├┤ X ├┤ X ├
       └───┘└───┘└───┘

  qc = QuantumCircuit(5)
  bool_expr = "(x0 & x1 | ~x2) & x4"
  oracle = PhaseOracleGate(bool_expr)
  qc.compose(oracle, inplace=True)
  print(qc)

       ┌───────────────┐
  q_0: ┤0              ├
       │               │
  q_1: ┤1              ├
       │  Phase oracle │
  q_2: ┤2              ├
       │               │
  q_3: ┤3              ├
       └───────────────┘
  q_4: ─────────────────

  print(qc.decompose())

  q_0: ─o──■──■─
        │  │  │ 
  q_1: ─┼──o──■─
        │  │  │ 
  q_2: ─o──o──┼─
        │  │  │ 
  q_3: ─■──■──■─
  
  q_4: ─────────

• Added a new argument approximation_degree to CommutationChecker.commute() and CommutationChecker.commute_nodes(), which allows to set the approximation threshold for when gates are said to commute. See the docstring of CommutationChecker for more detail.

• A new method, QuantumCircuit.noop(), allows qubits to be marked as explicitly used within a control-flow builder scope, without adding a corresponding operation to them.

• The classical realtime-expressions module qiskit.circuit.classical can now represent constant expressions. The Expr class now has a bool const attribute which indicates the expression’s const-ness. This allows us to enforce that expressions in certain contexts must be possible to evaluate at compile time.

  All Var expressions are considered to be non-const, while all Value expressions are const.

  An expression comprised only of other const expressions is also const:

  from qiskit.circuit.classical import expr
   
  assert expr.bit_and(5, 6).const

  An expression that contains any non-const expression is non-const:

  from qiskit.circuit.classical import expr, types
   
  assert not expr.bit_and(5, expr.Var.new("a", types.Uint(5)).const

• The classical realtime-expressions module qiskit.circuit.classical can now represent duration using the new types Duration.

  The module qiskit.circuit also has a new Duration class which can be used as a literal value within classical expressions.

  The lift() function can be used to create a value expression from a Duration instance:

  from qiskit.circuit import Duration
  from qiskit.circuit.classical import expr
   
  expr.lift(Duration.dt(1000))
  # Value(Duration.dt(1000), Duration())

• The classical realtime-expressions module qiskit.circuit.classical can now represent IEEE-754 double-precision floating point values using the new type Float.

  The lift() function can be used to create a value expression from a Python float:

  from qiskit.circuit.classical import expr
   
  expr.lift(5.0)
  # >>> Value(5.0, Float())

  This type is intended primarily for use in timing-related (duration and stretch) expressions. It is not compatible with bitwise or logical operations, though it can be used (dangerously) with these if first explicitly cast to something else.

• Reduce the number of two-qubit gates when decomposing some multi-controlled single-qubit unitary gates. For example,

  • For multi-controlled YGate on 10 qubits, we reduce the CXGate count by 56%,
  • For multi-controlled HGate on 10 qubits, we reduce the CXGate count by 56%,
  • For multi-controlled SXGate and SXdgGate on 10 qubits, we reduce the CXGate count by 80%,
  • For multi-controlled UGate on 10 qubits, we reduce the CXGate count by 31%.

• The classical realtime-expressions module qiskit.circuit.classical can now represent arithmetic operations add(), sub(), mul(), and div() on numeric and timing operands.

  For example:

  from qiskit.circuit import QuantumCircuit, ClassicalRegister, Duration
  from qiskit.circuit.classical import expr
   
  # Subtract two integers
  cr = ClassicalRegister(4, "cr")
  qc = QuantumCircuit(cr)
  with qc.if_test(expr.equal(expr.sub(cr, 2), 3)):
      pass
   
  # Multiply a Duration by a Float
  with qc.if_test(expr.less(expr.mul(Duration.dt(200), 2.0), Duration.ns(500))):
      pass
   
  # Divide a Duration by a Duration to get a Float
  with qc.if_test(expr.greater(expr.div(Duration.dt(200), Duration.dt(400)), 0.5)):
      pass

  For additional examples, see the module-level documentation linked above.

• UCGate now includes a mux_simp boolean attribute that enables the search for simplifications of Carvalho et al., implemented in _simplify(). This optimization, enabled by default, identifies and removes unnecessary controls from the multiplexer, reducing the number of CX gates and circuit depth, especially in separable state preparation with Initialize.

• The PauliEvolutionGate now natively supports SparseObservables as input. This efficiently allows to handle evolution under projectors, which are implemented as controls of a phase rotation and require less gates than explicitly expanding the projector in terms of Paulis. For example:

  from qiskit.circuit.library import PauliEvolutionGate
  from qiskit.quantum_info import SparseObservable
   
  obs = SparseObservable("001")
  evo_proj = PauliEvolutionGate(obs, time=1)
  print(evo_proj.definition.draw())

• A new expression node Stretch has been added to the classical expression system to represent stretch variables. To create a new stretch` variable, you can use :meth:`.QuantumCircuit.add_stretch`. The resulting expression is a constant expression of type :class:`~.types.Duration`, which can currently be used as the ``duration argument of a delay().

  The Stretch expression is most similar to the existing Var expression used to represent classical variables in a circuit, except it is constant and is always of type Duration. It can be used in other expressions (e.g. you can multiply it by a numeric constant) and QuantumCircuit provides full scoping support for it (e.g. it can be captured by or declared within a control flow scope).

• Added Gate versions of the single-register arithmetic gates, which allow the compiler to perform high-level optimizations compared to their QuantumCircuit variants. These are:

  • ExactReciprocalGate (replacing ExactReciprocal)
  • IntegerComparatorGate (replacing IntegerComparator)
  • LinearPauliRotationsGate (replacing LinearPauliRotations)
  • PiecewiseLinearPauliRotationsGate (replacing PiecewiseLinearPauliRotations)
  • PiecewiseChebyshevGate (replacing PiecewiseChebyshev)
  • PiecewisePolynomialPauliRotationsGate (replacing PiecewisePolynomialPauliRotations)
  • PolynomialPauliRotationsGate (replacing PolynomialPauliRotations)
  • LinearAmplitudeFunctionGate (replacing LinearAmplitudeFunction)
  • QuadraticFormGate (replacing QuadraticForm)
  • WeightedSumGate (replacing WeightedAdder)

Primitives Features

• Added to_bool_array() method to BitArray class that returns the bit array as a boolean NumPy array. The order argument can be used to specify the endianness of the output array.

• Expanded the docstring of ObservablesArray.tolist() to make it clear it might return a scalar in the case the observables array is of dimension 0.

Providers Features

• Added the ability to set the dt property of GenericBackendV2 in the class initializer with a new dt argument. Example usage:

  from qiskit.providers.fake_provider import GenericBackendV2
  backend = GenericBackendV2(
    num_qubits=5, 
    basis_gates=["cx", "id", "rz", "sx", "x"],
    dt= 2.22*e-10, 
    seed=42)

Quantum Information Features

• Added SparseObservable.to_sparse_list() to obtain a sparse list representation of a SparseObservable. For example:

  from qiskit.quantum_info import SparseObservable
   
  obs = SparseObservable.from_list([("+II", 1), ("-II", 1)])
  print(obs.to_sparse_list())  # [("+", [2], 1), ("-", [2], 1)]

• Added SparseObservable.as_paulis() to express a sparse observable in terms of Paulis only by expanding all projectors. For example:

  from qiskit.quantum_info import SparseObservable
   
  obs = SparseObservable("+-")
  obs_paulis = obs.as_paulis()  # 1/4 ( II + XI - IX - XX )

• Support construction of a SparsePauliOp from a SparseObservable via the new method SparsePauliOp.from_sparse_observable. It is important to remember that SparseObservables can efficiently represent projectors, which require an exponential number of terms in the SparsePauliOp.

• SparseObservable now supports operator composition using the compose() method, similar to other quantum_info classes. This is analagous to matrix multiplication, though the method is entirely matrix free.

• SparseObservable.BitTerm as a new attribute, label, which contains the single-character Python string used to represent the term in string labels.

• The method StabilizerState.expectation_value() can now accept an operator of type SparsePauliOp.

Synthesis Features

• Add a TwoQubitControlledUDecomposer that decomposes any two-qubit unitary in terms of basis two-qubit fractional gates, such as RZZGate (or two-gates gates which are locally equivalent to RZZGate up to single qubit gates).

  For example:

  from qiskit.circuit.library import RZZGate
  from qiskit.synthesis import TwoQubitControlledUDecomposer
  from qiskit.quantum_info import random_unitary
   
  unitary = random_unitary(4, seed=1)
  decomposer = TwoQubitControlledUDecomposer(RZZGate, euler_basis="ZXZ")
  circ = decomposer(unitary)
  circ.draw(output='mpl')

• Added synthesis functions synth_integer_comparator_2s() and synth_integer_comparator_greedy() to compile gates implementing an integer comparison, such as represented by IntegerComparatorGate. The corresponding high-level synthesis plugins are IntComparatorSynthesis2s and IntComparatorSynthesisNoAux. To let the compiler select the optimal decomposition based on the availably auxiliary qubits, use IntComparatorSynthesisDefault.

• Added synth_weighted_sum_carry() to synthesize WeightedSumGate objects. This is currently the only available synthesis method, with the corresponding high-level synthesis plugin WeightedSumSynthesisDefault.

Transpiler Features

• Added support for two-qubit fractional basis gates, such as RZZGate, to the ConsolidateBlocks transpiler pass. The decomposition itself is done using the TwoQubitControlledUDecomposer.

  For example:

  from qiskit import QuantumCircuit
  from qiskit.transpiler import generate_preset_pass_manager
  from qiskit.transpiler.passes import ConsolidateBlocks
   
  qc = QuantumCircuit(2)
  qc.rzz(0.1, 0, 1)
  qc.rzz(0.2, 0, 1)
  consolidate_pass = ConsolidateBlocks(basis_gates=["rz", "rzz", "sx", "x", "rx"])
  block = consolidate_pass(qc)  # consolidate the circuit into a single unitary block
  block.draw(output='mpl')
   
  pm = generate_preset_pass_manager(
      optimization_level=2, basis_gates=["rz", "rzz", "sx", "x", "rx"]
  )
  tqc = pm.run(qc)  # synthesizing the circuit into basis gates
  tqc.draw(output='mpl')

• Added support for two-qubit fractional basis gates, such as RZZGate, to the UnitarySynthesis transpiler pass. The decomposition is done using the TwoQubitControlledUDecomposer, and supports both standard and custom basis gates.

  For example:

  from qiskit import QuantumCircuit
  from qiskit.quantum_info import random_unitary
  from qiskit.transpiler.passes import UnitarySynthesis
  from qiskit.converters import circuit_to_dag, dag_to_circuit
   
  unitary = random_unitary(4, seed=1)
  qc = QuantumCircuit(2)
  qc.append(unitary, [0, 1])
  dag = circuit_to_dag(qc)
  circ = UnitarySynthesis(basis_gates=['rzz', 'rx', 'rz']).run(dag)
  dag_to_circuit(circ).draw(output='mpl')

• Added a new transpiler pass, LightCone that is used to get the lightcone of a circuit when measuring a subset of qubits or a specific Pauli string. For example if you had a circuit like:

  

  running the pass would eliminate the gates that do not affect the outcome.

  from qiskit.transpiler.passes.optimization.light_cone import LightCone
  from qiskit.transpiler.passmanager import PassManager
  from qiskit.circuit import QuantumCircuit
   
  qc = QuantumCircuit(3,1)
  qc.h(range(3))
  qc.cx(0,1)
  qc.cx(2,1)
  qc.h(range(3))
  qc.measure(0,0)
   
  pm = PassManager([LightCone()])
  new_circuit = pm.run(qc)
  new_circuit.draw("mpl")

  

• Added a new argument max_block_width to the class BlockCollector and to the transpiler passes CollectLinearFunctions and CollectCliffords. This argument allows to restrict the maximum number of qubits over which a block of nodes is defined.

  For example:

  from qiskit.circuit import QuantumCircuit
  from qiskit.transpiler.passes import CollectLinearFunctions
   
  qc = QuantumCircuit(5)
  qc.h(0)
  qc.cx(0, 1)
  qc.cx(1, 2)
  qc.cx(2, 3)
  qc.cx(3, 4)
   
  # Collects all CX-gates into a single block 
  qc1 = CollectLinearFunctions()(qc)
  qc1.draw(output='mpl')
   
  # Collects CX-gates into two blocks of width 3 
  qc2 = CollectLinearFunctions(max_block_width=3)(qc)
  qc2.draw(output='mpl')

• Added a new option, collect_from_back, to CollectMultiQBlocks. When set to True, the blocks are collected in the reverse direction, from the outputs towards the inputs of the circuit. The blocks are still reported following the normal topological order. This leads to an additional flexibility provided by the pass, and additional optimization opportunities when combined with a circuit resynthesis method.

• Added a new argument approximation_degree to CommutationAnalysis, which allows setting the approximation threshold for when gates are said to commute. See the class docstring for more information.

• A new transpiler pass, ContractIdleWiresInControlFlow, is available from qiskit.transpiler.passes. This pass removes qubits from control-flow blocks if the semantics allow this, and the qubit is idle throughout the control-flow operation. Previously, the routing stage of the preset pass managers might have done this as an accidental side-effect of how they worked, but the behavior is now more properly placed in an optimization pass.

• A new routing plugin stage is added, called "default". In Qiskit 2.0, this is simply an alias for the previous default "sabre". The underlying default algorithm may change over the course of the Qiskit 2.x series for some or all targets, but you can always set routing_method="sabre" explicitly to maintain the current behavior.

• A new translation plugin stage is added, called "default". In Qiskit 2.0, this is simply an alias for the previous default "translator". The underlying default algorithm may change over the course of the Qiskit 2.x series for some or all targets, but you can always set translation_method="translator" explicitly to maintain the current behavior.

• The HighLevelSynthesis transpiler pass now synthesizes objects of type AnnotatedOperation via the plugin interface.

• PassManager.run() now accepts a property_set argument, which can be set to a Mapping-like object to provide the initial values of the pipeline’s PropertySet. This can be used to recommence a partially applied compilation, or to reuse certain analysis from a prior compilation in a new place.

• The scheduling passes PadDelay and PadDynamicalDecoupling has new arguments on their constructors target and durations these are used to specify the Target or InstructionDurations respectively. This is required to provide the durations for the instructions in the circuit when this pass is run.

• Added a new method to the Target class has a new method, seconds_to_dt(). This is used to translate a duration in seconds to a number of discretized time steps of the system time resolution specified in the Target.dt attribute. This is typically useful for converting the InstructionProperties.duration value to units of dt.

• The synth_cnot_depth_line_kms() pass was ported into rust, with preliminary benchmarks pointing at a factor of 20x speedup.

• The synth_cx_cz_depth_line_my() pass was ported into rust, with preliminary benchmarks pointing at a factor of 70x speedup.

• The Split2QUnitaries transpiler pass has been upgraded to handle the case where the unitary in consideration can be written as a SWAP gate and two 1-qubit gates. In this case, it splits the unitary and also applies virtual swapping similar to what is done in ElidePermutations. This functionality can be controlled with a new argument, split_swap, on the constructor of :class`.Split2QUnitaries` which can be used to disable splitting swap equivalent gates.

Misc. Features

• qiskit.utils now contains utilities to provide better control and inspection of Qiskit’s multiprocessing parallelization settings. In particular, one can now use should_run_in_parallel() to query whether parallel_map() (and pass managers) will launch subprocesses for suitable inputs, and use the context manager should_run_in_parallel.override() to temporarily override most system and user configuration around this decision.

  An additional function, default_num_processes() reads the default maximum number of subprocesses that Qiskit will use for process-based parallelism.

• A new environment variable, QISKIT_IGNORE_USER_SETTINGS, now controls whether to read the user settings file on import qiskit. If set to the string true, the settings file will not be read. This is useful for isolating certain instances of Qiskit from the system environment, such as for testing.

Upgrade Notes

• Qiskit no longer supports Linux i686 and 32 bit Windows. Starting in Qiskit 2.0 a 64 bit platform is needed to run Qiskit. The user base for 32bit architectures is relatively small and as Qiskit continues to focus on improving performance to handle the increased scale in the complexity of quantum computing hardware maintaining support for 32 bit platforms is proving increasingly difficult. This coupled with the larger scientific/numeric Python community’s trend away from 32 bit platform support maintaining support for 32bit platforms is no longer viable. Qiskit 1.x will still continue to support 32 bit platforms, but starting in this 2.0.0 release Qiskit no longer supports these platforms, will not publish pre-compiled binaries for these platforms any longer, and there is no longer any guarantee of being able to build from source on 32 bit platforms.

• The minimum supported Rust version for building Qiskit from source is now 1.79. This has been raised from the previous minimum supported Rust version of 1.70 in the Qiskit 1.x release series.

• Increased the minimum threshold for when gates are assumed to be the identity in RemoveIdentityEquivalent from machine epsilon to 1e-12 to account for round-off errors in the fidelity calculation and for consistency with the other classes, such as CommutationAnalysis and TwoQubitWeylDecomposition.

• Updated the metric used to check commutations in CommutationChecker. Two gates are assumed to commute if the average gate fidelity of the commutation is above 1 - 1e-12. This value is chosen to account for round-off errors in the fidelity calculation and for consistency with RemoveIdentityEquivalent and TwoQubitWeylDecomposition. See the class docstring for more information.

• BlueprintCircuit.copy_empty_like() now returns an empty QuantumCircuit with the same number of qubits/clbits and the same metadata as the original circuit, instead of a BlueprintCircuit. This change is to mitigate unexpected behavior where dealing with an “empty” copy of a blueprint circuit would re-build the circuit data. Note that BlueprintCircuit.copy() still returns a BlueprintCircuit. Related: #13535

• Qiskit Pulse has been completely removed in this release, following its deprecation in Qiskit 1.3. This include all pulse module files, pulse visualization functionality, support for ScheduleBlock and pulse-gate serialization/deserialization capability in QPY, calibrations management in QuantumCircuit, Target and DAGCircuit and pulse-based fake backends. For more details about the removed components related to pulse, see the corresponding sections below.

  Note that Pulse migration to Qiskit Dynamics, as was the initial plan following the deprecation of Pulse, has been put on hold due to Qiskit Dynamics development priorities. Users wanting to use Qiskit Pulse as a frontend to supporting backends or in other uses-cases can still use it via Qiskit versions prior to 2.0, which include Pulse functionality.

• The functions sequence and schedule from the compiler module have been removed following their deprecation in Qiskit 1.3. They relied on being able to translate circuits to pulse using backend definitions, a capability that is no longer present. For this reason they have been removed with no proposed alternative. Note that this removals relate to the Pulse package which is also being removed in Qiskit 2.0.

Circuits Upgrade Notes

• Bit and Register as well as their subclassess are no longer guaranteed to be comparable using is checks, due to conversions to and from Python which may re-allocate each instance exposed to Python.

• Bit and Register (and their subclasses) can no longer be subclassed. This was never intended to be supported behavior, and doing so would cause unspecified behavior in Qiskit. It is no longer possible to do this as an implementation detail of the classes.

• It is no longer possible to create instances of the base Bit and Register classes is no longer possible. Directly instantiating these classes was clearly documented as something that was not supported and being able to do it was was just an implementation artifact of how the class heirarchy in previous releases. Starting in this release it is no longer possible to do this.

• The PhaseOracle no longer relies on the tweedledum library but might not be synthesized as effectively as before. BitFlipOracleGate was added as an alternative to directly synthesizing BooleanExpression, as this class is removed in Qiskit 2.0. A PhaseOracleGate was added and will replace PhaseOracle in Qiskit 3.0.

  The interface of PhaseOracle was simplified; it no longer accepts a synthesizer parameter, and the expression parameter can only be a string; ClassicalElement has been deprecated in Qiskit 1.4.

  PhaseOracle is used exactly as before:

  from qiskit.circuit.library.phase_oracle import PhaseOracle
  bool_expr = "(x0 & x1 | ~x2) & x4"
  oracle = PhaseOracle(bool_expr)
  print(oracle)

  q_0: ─o──■──■─
        │  │  │ 
  q_1: ─┼──o──■─
        │  │  │ 
  q_2: ─o──o──┼─
        │  │  │ 
  q_3: ─■──■──■─

• The method QuantumCircuit.measure_active() has changed the name of the classical register it creates, as the previous name conflicted with an OpenQASM reserved word. Instead of measure, it is now called meas, aligning with the register name used by measure_all().

• DAGCircuit.control_flow_op_nodes() now always returns a list, even if empty. Previously, it returned None if empty, and never returned the empty list, which required special handling. If you need to explicitly test for emptiness in both Qiskit 1.x and 2.x, you can do:

  control_flow_nodes = dag.control_flow_op_nodes()
  if not control_flow_nodes:
      # There are no control-flow nodes.
      pass

• The generic control method for gates now avoids attempting to translate gates into a supported basis, if the gate is already supported. This can slightly change the synthesis of the controlled gate, although it should not increase the two-qubit gate count.

• Converting a quantum circuit to a gate with converters.circuit_to_instruction() fails properly when given circuit contains control flow instructions.

• The internal function qiskit.circuit.add_control.add_control was removed, as it is not part of the public API. It had fragile preconditions to uphold and was a common source of bugs. Uses of add_control(SomeGate(...), ...) should change to SomeGate(...).control(...) using Gate.control() instead, which is far safer.

• The ParameterExpression.sympify() method can now raise a MissingOptionalLibrary exception if sympy is not installed. In the Qiskit 1.x releases sympy was always guaranteed to be installed, but starting in 2.x this is no longer a hard requirement and may only be needed if you are using this method. As this functionality explicitly requires sympy you will need to ensure you have sympy installed to use the method.

• The deprecated argument .dag for DAGNode and its subclasses DAGOpNode, DAGOutNode, and DAGInNode. dag was optional parameter when constructing these objects that was unused and ignored since the 1.3.0 release. The parameter was deprecated in 1.4 and has now been is removed.

• The QuantumCircuit methods:

  • cast
  • cbit_argument_conversion
  • cls_instances
  • cls_prefix
  • qbit_argument_conversion

  have been removed, following their deprecation in Qiskit 1.2. These methods were internal helper functions, and never intended to be public API. No replacement is provided.

• The deprecated attributes for Instruction and Gate: duration and unit have been removed. This includes setting the unit or duration arguments for any qiskit.circuit.Instruction or subclass. These attributes were deprecated in Qiskit 1.3.0 and were used to attach a custom execution duration and unit for that duration to an individual instruction. However, the source of truth of the duration of a gate is the BackendV2 Target which contains the duration for each instruction supported on the backend. The duration of an instruction is not something that’s typically user adjustable and is an immutable property of the backend. If you were previously using this capability to experiment with different durations for gates you can mutate the InstructionProperties.duration field in a given Target to set a custom duration for an instruction on a backend (the unit is always in seconds in the Target).

• The deprecated attribute for qiskit.circuit.Instruction and Gate: condition has been removed. These attributes were deprecated in the 1.3.0 release. This functionality has been superseded by the IfElseOp class which can be used to describe a classical condition in a circuit.

• The deprecated methods for Instruction and Gate: c_if and condition_bits have been removed. These methods were deprecated in the 1.3.0 release. This functionality has been superseded by the IfElseOp class which can be used to describe a classical condition in a circuit. For example, a circuit previously using Instruction.c_if() like:

  from qiskit.circuit import QuantumCircuit
   
  qc = QuantumCircuit(2, 2)
  qc.h(0)
  qc.x(0).c_if(0, 1)
  qc.z(1.c_if(1, 0)
  qc.measure(0, 0)
  qc.measure(1, 1)

  can be rewritten as:

  qc = QuantumCircuit(2, 2)
  qc.h(0)
  with expected.if_test((expected.clbits[0], True)):
      qc.x(0)
  with expected.if_test((expected.clbits[1], False)):
      qc.z(1)
  qc.measure(0, 0)
  qc.measure(1, 1)

• The deprecated method InstructionSet.c_if has been removed. This method was deprecated in the 1.3.0 release. This functionality has been superseded by the IfElseOp class which can be used to describe a classical condition in a circuit.

• As part of Pulse removal in Qiskit 2.0, the calibrations property has been removed from the QuantumCircuit, DAGCircuit and DAGDependency classes. In addition, the method has_calibration_for has been removed from the QuantumCircuit and DAGCircuit classes and add_calibration has been removed from QuantumCircuit.

• The classical_function was removed. This module was dependent on the tweedledum library which is no longer compatible with newer versions of Python. As an alternative, the PhaseOracleGate and BitFlipOracleGate classes can be used to generate circuits from boolean expressions.

• The internal representation of UnitaryGate has changed when they’re added to a QuantumCircuit. The object stored in the circuit will not necessarily share a common reference to the object added to the circuit anymore. This was never guaranteed to be the case and mutating the UnitaryGate object directly or by reference was unsound and always likely to corrupt the circuit, especially if you changed the matrix. If you need to mutate an element in the circuit (which is not recommended as it’s inefficient and error prone) you should ensure that you do something like:

  from qiskit.circuit import QuantumCircuit
  from qiskit.quantum_info import random_unitary
  from qiskit.circuit.library import UnitaryGate
  import numpy as np
   
  qc = QuantumCircuit(2)
  qc.unitary(np.eye(2, dtype=complex))
   
  new_op = UnitaryGate(random_unitary(2))
  qc.data[0] = qc.data[0].replace(operation=new_op)

  This also applies to DAGCircuit too, but you can use DAGCircuit.substitute_node() instead.

• The CircuitInstruction.params attribute for a CircuitInstruction that contains an UnitaryGate for its operation will no longer contain the underlying unitary matrix for the gate. This is because the internal representation of the gate no longer treats the matrix object as a parameter. If you need to access the matrix of the gate you can do this either via the CircuitInstruction.matrix or the UnitaryGate.params field of the CircuitInstruction.operation.

Primitives Upgrade Notes

• As a consequence of the removal of the BackendV1 model, the BackendSamplerV2 and BackendEstimatorV2 classes no longer accept inputs of type BackendV1 in their backend input argument.

• Primitive V1 implementations and V1-exclusive non-versioned type aliases, deprecated in Qiskit 1.2, have been removed. These interfaces have been superseded by their V2 counterparts. The removal includes the following classes implementing V1 interfaces:

  • Estimator, in favor of the V2 equivalent, StatevectorEstimator
  • Sampler, in favor of the V2 equivalent, StatevectorSampler
  • BackendEstimator, in favor of the V2 equivalent, BackendEstimatorV2
  • BackendSampler, in favor of the V2 equivalent, BackendSamplerV2

  As well as the following non-versioned type aliases:

  • BaseEstimator, alias for BaseEstimatorV1
  • BaseSampler, alias for BaseSamplerV1

  This removal does NOT affect the explicitly-versioned BaseEstimatorV1 and BaseSamplerV1 abstract interface definitions or related result and job classes, which have been kept to maintain backward compatibitily.

  In addition, the following utility functions have been removed. These functions were only used in Primitive V1 implementations:

  • init_circuit(), to initialize a circuit from a Statevector, use QuantumCircuit.initialize() instead,
  • init_observable(), use the constructor of SparsePauliOp instead,
  • final_measurement_mapping(), use QuantumCircuit.layout() and SparsePauliOp.apply_layout() to adjust an operator for a layout. Otherwise, use mthree.utils.final_measurement_mapping. See Mthree Utility functions for details.

Providers Upgrade Notes

• The configuration method of BasicSimulator has been removed following its deprecation in Qiskit 1.3. This method returned a BackendConfiguration instance, and this class was part of the deprecated BackendV1 workflow. The individual configuration elements can be retrieved directly from the backend or from the contained Target instance (backend.target).

• The run_experiment method of BasicSimulator has also been removed. This method took an instance of the QasmQobjExperiment class as an input argument, and the class has been deprecated since Qiskit 1.2.

• The BackendV1 model has been removed following its deprecation in Qiskit 1.2.0. This includes the BackendV1 class as well as related modules and utils, as they have been superseded by the BackendV2 model. The list of removed items includes:

  • BackendV1 class: the core of the removed model

  • All elements in qiskit/providers/models, as they were used to represent components of the BackendV1 model:

    • BackendConfiguration
    • BackendProperties
    • BackendStatus
    • QasmBackendConfiguration
    • PulseBackendConfiguration
    • UchannelLO
    • GateConfig
    • PulseDefaults
    • PulseQobjDef
    • Command
    • GateProperties
    • Nduv
    • JobStatus: This class has been superseded by the more widely used JobStatus
    • PulseDefaults

  • BackendV2Converter class: used to convert from BackendV1 to BackendV2

  • convert_to_target function: used to build a Target instance from legacy BackendV1 components (such as BackendConfiguration or BackendProperties)

  • BackendPropertyError and BackendConfigurationError: exceptions linked to removed classes

• The BasicSimulator backend no longer can simulate classical control flow. It only supported using .c_if()/.condition for modeling control flow, as this has now been removed from Qiskit’s data model it no longer can support control flow.

• All fake backend classes based on the deprecated BackendV1 have been removed from the providers.fake_provider module. These classes have been deprecated since Qiskit 1.2 and were part of the deprecated BackendV1 workflow. Their use in tests has been replaced with the GenericBackendV2 class, which allows to create custom instances of BackendV2 that implement a simulated BackendV2.run(). The removal affects:

  • Base classes:

    • FakeBackend
    • FakePulseBackend
    • FakeQasmBackend

  • Fake backends for special testing purposes: * Fake1Q * FakeOpenPulse2Q * FakeOpenPulse3Q

  • Legacy fake backends:

    • Fake5QV1
    • Fake20QV1
    • Fake7QPulseV1
    • Fake27QPulseV1
    • Fake127QPulseV1

• As part of Pulse removal in Qiskit 2.0, the following methods have been removed:

  • qiskit.providers.BackendV2.instruction_schedule_map
  • qiskit.providers.BackendV2.drive_channel
  • qiskit.providers.BackendV2.measure_channel
  • qiskit.providers.BackendV2.acquire_channel
  • qiskit.providers.BackendV2.control_channel

• As part of Pulse removal in Qiskit 2.0, pulse support has been removed from GenericBackendV2. This includes the ability to initialize the backend with custom calibrations (calibrate_instructions argument) and pulse channels information.

• Removed the abstract base classes Provider and ProviderV1 which have been deprecated since Qiskit 1.1.0. The abstraction provided by these interface definitions were not providing a huge value, solely just the attributes name, backends, and a get_backend() method. A _provider_, as a concept, will continue existing as a collection of backends. If you’re implementing a provider currently you can adjust your code by simply removing ProviderV1 as the parent class of your implementation. As part of this you probably would want to add an implementation of get_backend for backwards compatibility. For example:

  def get_backend(self, name=None, **kwargs):
    backend = self.backends(name, **kwargs)
    if len(backends) > 1:
      raise QiskitBackendNotFoundError("More than one backend matches the criteria")
    if not backends:
      raise QiskitBackendNotFoundError("No backend matches the criteria")
    return backends[0]

QPY Upgrade Notes

• The qpy.load() function can now raise a MissingOptionalLibrary exception if a QPY v10, v11, or v12 payload is passed in that is using symengine symbolic expressions and symengine is not installed. Or if sympy is not installed for any other QPY payload < v13. In the Qiskit 1.x releases symengine and sympy were always guaranteed to be installed, but starting in 2.x this is no longer a hard requirement and may only be needed if you’re deserializing a QPY file that was generated using symengine. Parsing these QPY payloads requires symengine (0.11.0 or 0.13.0) as it’s usage is baked into the format specification for QPY v10, v11, and v12 so if the payload requires it there is no option but to install a compatible version of symengine. Similarly, sympy was was used for ParameterExpression encoding for all QPY versions from 1 through 12.

• The minimum QPY compatibility version, QPY_COMPATIBILITY_VERSION, has been raised to 13 from 10 in the 1.x release. This version controls the minimum version of QPY that can be emitted by the qpy.dump() function. This means qpy.dump() can only emit QPY v13 and v14 in this release. QPY v13 is still compatible with Qiskit 1.3.x and 1.4.x which means payloads can be generated in Qiskit 2.x that can be loaded with the Qiskit 1.x release series still.

  This change was necessary as QPY versions 10 through 12 requires either the sympy and symengine libraries to generate a serialization for ParameterExpression objects, but in Qiskit 2.x neither library is required for the ParameterExpression object.

• With the removal of Pulse in Qiskit 2.0, support for serializing ScheduleBlock programs via the qiskit.qpy.dump() function has been removed. Users can still load payloads containing pulse gates using the qiskit.qpy.load() function, however those will be treated as opaque custom instructions. Loading ScheduleBlock payloads is not supported anymore and will result with a QpyError exception.

Synthesis Upgrade Notes

• The plugins for LinearFunction no longer raise an error if another object than LinearFunction is passed into the run method. Instead, None is returned, which is consistent with the other plugins. If you relied on this error being raised, you can manually perform an instance-check.

• The atomic_evolution argument to ProductFormula (and its subclasses QDrift, LieTrotter and SuzukiTrotter ) has a new function signature. Rather than taking some Pauli operator and time coefficient and returning the evolution circuit, the new function takes in an existing circuit and should append the evolution of the provided Pauli and given time to this circuit. This new implementation benefits from significantly better performance.

Transpiler Upgrade Notes

• The routing plugin stage name default is now reserved for the Qiskit built-in plugin of the same name.

• The default routing plugin stage is now "default". In Qiskit 2.0, this is simply an alias for the previous default "sabre". The underlying default algorithm may change over the course of the Qiskit 2.x series for some or all targets, but you can always set routing_method="sabre" explicitly to maintain the current behavior.

• The translation plugin stage name default is now reserved for the Qiskit built-in plugin of the same name.

• The default translation plugin stage is now "default". In Qiskit 2.0, this is simply an alias for the previous default "translator". The underlying default algorithm may change over the course of the Qiskit 2.x series for some or all targets, but you can always set translation_method="translator" explicitly to maintain the current behavior.

• The deprecated transpiler passes ASAPSchedule, ALAPSchedule, DynamicalDecoupling, and AlignMeasures have been removed. These passes were marked as deprecated. They have been replaced by the ALAPScheduleAnalysis, ASAPScheduleAnalysis, PadDynamicalDecoupling, and ConstrainedReschedule passes respectively which can be used instead.

• In the case that neither a target nor a set of basis gates are specified, the HighLevelSynthesis transpiler pass synthesizes circuits with annotated operations with fewer layers of wrappings than before (this happens, for instance, for the circuit produced by multiplier_cumulative_h18()).

• The keyword argument property_set is now reserved in BasePassManager.run(), and cannot be used as a kwarg that will be forwarded to the subclass’s conversion from the front-end representation to the internal representation.

• The following deprecated uses of the BackendProperties object in the transpilation pipeline have been removed in Qiskit 2.0:

  • backend_properties input argument in transpile()
  • backend_properties input argument in PassManagerConfig
  • backend_properties input argument in generate_preset_pass_manager()
  • backend_properties input argument in generate_routing_passmanager()
  • backend_properties input argument in generate_translation_passmanager()
  • backend_properties input argument Target.from_configuration()

  The following passes have also been updated to only accept a target instead of:

  • backend_prop input argument in DenseLayout
  • properties input argument in VF2Layout
  • properties and coupling_map input arguments in VF2PostLayout
  • backend_props input argument in UnitarySynthesis

  The BackendProperties class has been deprecated since Qiskit 1.2, as it was part of the BackendV1 workflow. Specific instruction properties such as gate errors or durations can be added to a Target upon construction through the Target.add_instruction() method, and communicated to the relevant transpiler passes through the target input argument.

• As a consequence of the removal of the BackendV1 model, the accepted input types of the following transpiler objects have been updated:

  • The generate_preset_pass_manager() and transpile() functions no longer accept inputs of type BackendV1 in their backend input argument.
  • The Target.from_configuration() method no longer accepts a backend_properties argument
  • The Target.target_to_backend_properties() method has been removed

• The ResetAfterMeasureSimplification transpiler pass now will use an IfElseOp to condition the execution of the XGate instead of setting a condition attribute on the gate. This is because the condition attribute has been removed from the Qiskit data model.

• The deprecated ConvertConditionsToIfOps transpiler pass has been removed. The underlying condition attribute of Instruction class has been removed so this transpiler pass no longer had anything to convert from. Instead you should directly use IfElseOp to classically condition the execution of an operation.

• The PadDelay and PadDynamicalDecoupling transpiler passes now require a new argument when constructed. Either target or durations need to be specified with a Target or InstructionDurations respectively. Without these the passes will not be able to determine the duration of instructions in the circuit and will error. Previously these passes would determine these values from the now removed duration attribute of Instruction objects.

• The previously deprecated argument propagate_condition on the DAGCircuit methods substitute_node_with_dag() and substitute_node() has been removed. These arguments were deprecated in Qiskit 1.4.0 and were removed because the larger removal of Instruction.condition it no longer served a purpose.

• The previously deprecated AlignMeasures transpiler pass has been removed. This pass was deprecated in Qiskit 1.1.0. Instead the ConstrainedReschedule pass should be used. ConstrainedReschedule performs the same function and also supports aligning to additional timing constraints.

• When calling generate_preset_pass_manager() or transpile() and specifying the instruction_durations argument with a list instead of an InstructionDurations object and the list specifies durations in units of dt a dt parameter is required if scheduling the circuit.

• Removed the deprecated DAGNode.sort_key attribute. This attribute was deprecated in the Qiskit 1.4.0 release. As the lexicographical topological sorting is done internally and rust and the sort key attribute was unused this was removed to remove the overhead from DAG node creation. If you were relying on the sort key you can reproduce it from a given node using something like:

  def get_sort_key(node: DAGNode):
      if isinstance(node, (DAGInNode, DAGOutNode)):
          return str(node.wire)
      return ",".join(
          f"{dag.find_bit(q).index:04d}" for q in itertools.chain(node.qargs, node.cargs)
      )

• The following transpile() and generate_preset_pass_manager() input arguments, deprecated since Qiskit 1.3 , have been removed from the API:

  • instruction_durations
  • timing_constraints

  In addition to this, the specification of custom basis gates through the basis gate argument of transpile() and generate_preset_pass_manager(), also deprecated in Qiskit 1.3, is no longer allowed, and a ValueError will be raised in these cases.

  The information formerly provided through these can still be specified via the backend or target arguments. You can build a Target instance with defined instruction durations doing:

  Target.from_configuration(..., instruction_durations=...)

  For specific timing constraints:

  Target.from_configuration(..., timing_constraints=...)

  And for custom basis gates, you can manually add them to the target or use .from_configuration with a custom name mapping, for example:

  from qiskit.circuit.library import XGate
  from qiskit.transpiler.target import Target
   
  basis_gates = ["my_x", "cx"]
  custom_name_mapping = {"my_x": XGate()}
  target = Target.from_configuration(
      basis_gates=basis_gates, num_qubits=2, custom_name_mapping=custom_name_mapping
  )

• The transpile() and generate_preset_pass_manager() interfaces now raise a UserWarning when providing a coupling_map and/or basis_gates along with a backend. In these cases there are multiple sources of truth, the user intentions are not always clear, and there can be conflicts that generate_preset_pass_manager() may not know how to resolve. In these cases, we highly encourage the creation of a custom target that combines the chosen constraints.

  One of these situations is the specification of a gate with 3 or more qubits in backend or basis_gates together with a custom coupling map. The coupling map does not provide the necessary connectivity details to be able to determine the action of the gate. In these cases, transpile() and generate_preset_pass_manager() now raise a ValueError.

• As part of Pulse removal in Qiskit 2.0, all pulse and calibration related functionality in the transpiler has been removed. This includes the following:

  The following passes and function have been removed:

  • qiskit.transpiler.passes.PulseGates pass
  • qiskit.transpiler.passes.ValidatePulseGates pass
  • qiskit.transpiler.passes.RXCalibrationBuilder pass
  • qiskit.transpiler.passes.RZXCalibrationBuilder pass
  • qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho pass
  • qiskit.transpiler.passes.EchoRZXWeylDecomposition pass
  • qiskit.transpiler.passes.NoramlizeRXAngle pass
  • qiskit.transpiler.passes.rzx_templates() function

  The inst_map argument has been removed from the following elements:

  • The generate_preset_pass_manager() and transpile() functions
  • The Target.from_configuration() method
  • The constructor of the PassManagerConfig class

  Calibration support has been removed:

  • calibration has been removed from the InstructionProperties ‘s constructor and is no longer a property of that class.
  • The has_calibration, get_calibration, instruction_schedule_map and update_from_instruction_schedule_map methods have been removed from the Target class.

• The deprecated StochasticSwap transpiler pass, and its associated built-in routing stage plugin “stochastic”, have been removed. These were marked as deprecated in the Qiskit 1.3.0 release. The pass has been superseded by the SabreSwap which should be used instead as it offers better performance and output quality. For example if the pass was previously invoked via the transpile function such as with:

  from qiskit import transpile
  from qiskit.circuit import QuantumCircuit
  from qiskit.transpiler import CouplingMap
  from qiskit.providers.fake_provider import GenericBackendV2
   
   
  qc = QuantumCircuit(4)
  qc.h(0)
  qc.cx(0, range(1, 4))
  qc.measure_all()
   
  cmap = CouplingMap.from_heavy_hex(3)
  backend = GenericBackendV2(num_qubits=cmap.size(), coupling_map=cmap)
   
  tqc = transpile(
      qc,
      routing_method="stochastic",
      layout_method="dense",
      seed_transpiler=12342,
      target=backend.target
  )

  this should be replaced with:

  tqc = transpile(
      qc,
      routing_method="sabre",
      layout_method="dense",
      seed_transpiler=12342,
      target=backend.target
  )

• The pass qiskit.transpiler.passes.CXCancellation was removed. It was deprecated in favor of class:.InverseCancellation, which is more generic. CXCancellation is fully semantically equivalent to InverseCancellation([CXGate()]).

• The SolovayKitaev transpiler pass no longer raises an exception on circuits that contain single-qubit operations without a to_matrix method (such as measures, barriers, control-flow operations) or parameterized single-qubit operations, but will leave them unchanged.

• Plugins for the translation stage of the preset compiler are now required to respect gate directionality in the Target in their output. Previously, transpile() and generate_preset_pass_manager() would generate a PassManager that contained fix-up passes if needed. You must now include these in your own custom stage, if your stage does not guarantee that it respects directionality.

  You can use the GateDirection pass to perform the same fix-ups that Qiskit used to do. For example:

  from qiskit.transpiler import PassManager
  from qiskit.transpiler.passes import GateDirection
  from qiskit.transpiler.preset_passmanagers.plugin import PassManagerStagePlugin
   
  class YourTranslationPlugin(PassManagerStagePlugin):
      def pass_manager(self, pass_manager_config, optimization_level):
          pm = PassManager([
              # ... whatever your current setup is ...
          ])
          # Add the two-qubit directionality-fixing pass.
          pm.append(GateDirection(
              pass_manager_config.coupling_map,
              pass_manager_config.target,
          ))
          return pm

• The preset pass managers no longer populate the implicit pre_optimization stage of their output StagedPassManager. You can now safely assign your own PassManager to this field. You could previously only append to the existing PassManager.

• The default value for the generate_routing_passmanager() argument seed_transpiler has changed from None to -1. This was done because this flag was only used to configure the VF2PostLayout transpiler pass in the output, and for that pass in particular the randomization typically only hurts performance and is not desirable. If you were relying on the previous default value you can restore this behavior by explicitly setting the argument seed_transpiler=None. If you were explicitly setting a seed value for this parameter there is no change in behavior.