Circuit cutting release notes

0.10.0

Prelude

This release adds compatibility with Qiskit SDK 2.0.

New Features

This release adds utility functions and a how-to guide for performing circuit cutting with SparsePauliOp observables, rather than a PauliList of observables.

Upgrade Notes

Qiskit SDK 1.3.1 or higher is now required. Qiskit SDK 2.0 is now supported.

Other Notes

This addon is now marked as being incompatible with Qiskit 1.3.0, as the second cutting tutorial fails to execute due to a bug in Qiskit 1.3.0. See discussion in issue #714 for more information.

0.9.0

Prelude

The most notable change in this release is that the package has been renamed to qiskit-cutting-addon. It also marks the removal of this package’s original implementation of wire cutting, CutQC.

New Features

A new minimum_reached field has been added to the metadata outputted by circuit_knitting.cutting.find_cuts() to check if the cut-finder found a cut scheme that minimized the sampling overhead. Note that the search algorithm employed by the cut-finder is guaranteed to find the optimal solution, that is, the solution with the minimum sampling overhead, provided it is allowed to run long enough. The user is free to time-restrict the search by passing in suitable values for max_backjumps and/or max_gamma to OptimizationParameters. If the search is terminated prematurely in this way, the metadata may indicate that the minimum was not reached, even though the returned solution was actually the optimal solution. This would mean that the search that was performed was not exhaustive enough to prove that the returned solution was optimal.
When specifying instances of OptimizationParameters that are inputted to circuit_knitting.cutting.find_cuts(), the user can now control whether the cut-finder looks only for gate cuts, only for wire cuts, or both, by setting the bools gate_lo and wire_lo appropriately. The default value of both of these is set to True and so the default search considers the possibility of both gate and wire cuts.

Upgrade Notes

This package now requires updated versions of some dependencies: qiskit 1.1 or later, and qiskit-ibm-runtime 0.24.0 or later.
The search engine inside the automated cut-finder has been primed to avoid extraneous searches and is therefore expected to run faster.
The CutQC subpackage has been removed, along with its two associated utility modules, circuit_knitting.utils.metrics and circuit_knitting.utils.conversion. Users are now encouraged to use the automatic cut-finding and gate/wire cutting from the circuit_knitting.cutting package.
The behavior of separate_circuit() and partition_problem() have changed so that idle qubits are discarded by default. Previously, each idle qubit was placed in its own subcircuit if partition_labels was not provided.

0.7.1

Prelude

The 0.7.1 release provides a workaround to ensure that the experiments generated by the circuit cutting workflow will execute on IBM Quantum’s hardware backends.

Bug Fixes

Added a workaround so that the classical registers in the generated circuits will always contain at least one bit. This is currently necessary for the experiments to be able to reach IBM Quantum’s hardware backends due to an openqasm parser issue.

Other Notes

The generate_cutting_experiments() function has been optimized for faster execution.

0.7.0

Prelude

The 0.7 release introduces an automated cut finding code for the new circuit cutting workflow. With this milestone, the older cutting workflow (CutQC) is now deprecated. Additionally, this is the first CKT release to support version 2 of the Qiskit Runtime primitives. User are encouraged to migrate to v2 primitives as soon as possible.

New Features

Added a cut-finder function, circuit_knitting.cutting.find_cuts(), for automatically identifying locations to place LO gate and wire cuts such that the circuit is separable and runnable, given the maximum number of qubits per subcircuit as a parameter. The cut-finder will search for cut schemes which minimize the sampling overhead. Note, however, that for larger circuits, the number of cuts needed to separate the circuit will naturally grow larger, leading to an exponentially increasing sampling overhead. For instances of wire cuts, the cut-finder assumes no qubit reuse. Therefore, for each wire cut, a new wire is added to the circuit. In addition, the cut-finder requires that every gate in an input circuit be at most a two qubit gate. The search algorithm used by the cut-finder to identify cut locations is Dijkstra’s best first search algorithm which is guaranteed to find solutions with the lowest sampling overhead, provided any user-specified value for the maximum number of allowed backjumps or for the maximum sampling overhead does not prematurely stop the search. If the user wishes to time-restrict the search when running the cut-finder on large circuits, they can specify a maximum sampling overhead and/or a maximum number of allowed backjumps, in which case the cut-finder will return a valid albeit suboptimal cut scheme.
Circuit cutting reconstruction can now interpret the PrimitiveResult object, which is returned by version 2 of the sampler primitive (BaseSamplerV2). See the migration guide for details on upgrading to version 2 of the Qiskit primitives.

Upgrade Notes

CKT now requires updated versions of some dependencies: qiskit 1.0 or later, qiskit-aer 0.14.0 or later, and qiskit-ibm-runtime 0.23.0 or later.
The code in the circuit_knitting.cutting.qpd.qpd submodule has been split into three separate files. If you were importing directly from this submodule, you will now need to import from circuit_knitting.cutting.qpd instead.

Deprecation Notes

The circuit_knitting.cutting.cutqc package is deprecated and will be removed no sooner than Circuit Knitting Toolbox 0.8.0. The wire cutting functionality in the circuit_knitting.cutting package is what will be maintained going forward. Additionally, there is a new automated gate and wire cut-finding functionality in the circuit_knitting.cutting.automated_cut_finding module. A tutorial has been added to demonstrate automated cut-finding.

Other Notes

The cutting tutorials have been rephrased with the goal of reconstructing the expectation value of a single SparsePauliOp with many terms, rather than multiple independent Pauli observables.
The circuit cutting explanation document has been expanded significantly.

0.6.0

Upgrade Notes

The minimum supported version of qiskit is now 0.45.0, and the minimum supported version of qiskit-ibm-runtime is now 0.12.2. CKT also now explicitly requires a version of qiskit less than 1.0, as there is no guarantee that the current version of CKT will work with Qiskit 1.0.
Removed the circuit_knitting.cutting.qpd.QPDBasis.from_gate method, which has been deprecated since the 0.3 release. QPDBasis.from_instruction() should be used instead.
Removed the circuit_knitting_toolbox import path. Users should now import from circuit_knitting instead.
Removed the circuit_knitting.cutting.decompose_gates function, which has been deprecated since the 0.3 release. cut_gates() should be used instead.
Removed the circuit_knitting.cutting.cutting_evaluation module, which has been deprecated since the 0.4 release. Users should first call circuit_knitting.cutting.generate_cutting_experiments() to generate the subexperiment circuits and then submit these circuits directly to the desired Sampler(s).
Removed the circuit_knitting.cutting.qpd.generate_qpd_samples function, which has been deprecated since the 0.3 release. generate_qpd_weights() should be used instead.
Removed the circuit_knitting.cutting.qpd.qpdbasis_from_gate function, which has been deprecated since the 0.3 release. qpdbasis_from_instruction() should be used instead.
The generate_cutting_experiments() function now performs some optimizations on the generated circuits before returning them to the user. In particular, it performs the RemoveResetInZeroState, RemoveFinalReset, and ConsolidateResets passes, so that circuits with cut wires and no re-used qubits are transformed into subexperiments that contain no Resets. This allows such circuits to work on a greater variety of hardware backends.

Bug Fixes

It is now possible to serialize SingleQubitQPDGates using qpy, but some other issues with serialization and deserialization still remain. See issue #455 for details.

Other Notes

Removed the entanglement forging tool, as the Qiskit application modules are no longer supported, and packages in Qiskit-Extensions may not have dependency on those modules. With this change, CKT no longer depends on qiskit-algorithms or Qiskit Nature.

0.5.0

Prelude

The primary purpose of this release is to swap the order of the classical registers in the circuits generated the circuit_knitting.cutting module. With this change, "observable_measurements" now comes before "qpd_measurements", and there is no longer a need to insert num_qpd_bits into the result metadata by hand.

Upgrade Notes

CKT now depends on the qiskit-algorithms package. This new package replaces the qiskit.algorithms module, which was deprecated in Qiskit 0.44.
The order of the classical registers in the generated experiments has been swapped. The "observable_measurements" register now comes first, and the "qpd_measurements" register now comes second. As a result of this change, it is no longer necessary to manually insert num_qpd_bits into the metadata for each experiment’s result.
Removed the circuit_knitting.cutting.wire_cutting module. Users are now expected to import from the circuit_knitting.cutting.cutqc module instead.

Other Notes

qiskit-nature is now pinned to version 0.6.X, as the entanglement forging code has not yet been updated to work with Qiskit Nature 0.7.0. Compatibility with Qiskit Nature 0.7.0 is tracked by issue #406.

0.4.0

Prelude

The primary goal of this release is to modify the circuit cutting workflow to enable direct use of the Sampler primitive. Previously, the Sampler was called in execute_experiments(), a function which is now deprecated in favor of generate_cutting_experiments().

New Features

Added a module, circuit_knitting.cutting.cutting_experiments, which is intended to hold functions used for generating the quantum experiments needed for circuit cutting. This module will initially hold one function, generate_cutting_experiments(), which can be used to generate quantum experiments, given an input circuit containing BaseQPDGate instances, some observables, and a number of times the joint quasi-probability distribution for the cuts should be sampled.

Upgrade Notes

The circuit-knitting-toolbox Python package now depends on qiskit rather than qiskit-terra. This should have no user-visible effects, but it is something to keep in mind if one sees dependency errors when upgrading CKT.
The execute_experiments() function now returns a SamplerResult instance for each circuit partition, rather than the 3D list of quasi-distributions returned previously. The quasi-distribution for each subexperiment can be accessed via the quasi_dists field of SamplerResult. The number of QPD bits contained in each subexperiment will be included in the num_qpd_bits field of the metadata dictionary for each experiment result. The output of this function is still valid as input to reconstruct_expectation_values().
reconstruct_expectation_values() now takes, as its first argument, a SamplerResult instance or a dictionary mapping partition labels to SamplerResult instances. This new results argument replaces the old quasi_dists argument. The SamplerResult instances are expected to contain the number of QPD bits used in each circuit input to the Sampler. This should be specified in the num_qpd_bits field of the experiment result metadata.

Deprecation Notes

The execute_experiments() function has been deprecated. Going forward, users should first call generate_cutting_experiments() to generate the subexperiment circuits and then submit these circuits directly to the desired Sampler(s). The tutorials have been updated with this new workflow.

0.3.0

Prelude

The 0.3.0 release introduces significant new features while maintaining backwards compatibility with the 0.2.0 release. The most striking change in this release is the shortened module names: circuit_knitting_toolbox has been renamed to circuit_knitting, entanglement_forging has been renamed to forging, and circuit_cutting has been renamed to cutting. The new circuit cutting module contains significant enhancements, including support for wire cutting and for the cutting of arbitrary two-qubit gates.

New Features

The circuit cutting module now supports the cutting of arbitrary two-qubit gates. This is supported via a KAK decomposition, using Qiskit’s TwoQubitWeylDecomposition, following the method in arXiv:2006.11174.

Additionally, this release adds explicit support (i.e., without relying on a KAK decomposition) for the following gates:
- CHGate
- CYGate
- CSGate
- CSXGate
- CSdgGate
- CPhaseGate
- ECRGate
- SwapGate
- iSwapGate
- DCXGate
partition_problem() now works even if partition_labels is not explicitly provided. In this case, the labels are determined automatically from the connectivity of the input circuit. For the sake of determining connectivity, TwoQubitQPDGates are ignored, as these instructions are already marked for cutting. To support this workflow, this release also introduces a new method, TwoQubitQPDGate.from_instruction(), which allows one to create a TwoQubitQPDGate that wraps a given instruction.
Dynamic Definition code has been added to the cutqc module. See pull request #285 for details.
Users may now bypass experiments associated with the Hartree-Fock bitstring and replace their results with a specified Hartree-Fock value using the hf_energy class field in circuit_knitting.forging.EntanglementForgingGroundStateSolver. Refer to the explanatory material <Fixing the Hartree-Fock Bitstring> for more information.
generate_qpd_weights() now returns a mixture of exact and sampled weights when appropriate. Specifically, it exactly evaluates all weights greater than or equal to 1 / num_samples and samples from the remaining weights (ones which are below this threshold). Previously, this function would only return exact weights if all weights were greater than or equal to 1 / num_samples; otherwise, all weights were sampled. The new behavior is expected to improve performance on non-uniform quasi-probability decompositions, e.g. for cut instantiations of RXXGate, RYYGate, RZZGate, CRXGate, CRYGate, and CRZGate away from $\theta=\pi/2$ .
The circuit_knitting.cutting module now supports wire cutting. There is a new tutorial that explains how to use it.

Upgrade Notes

execute_experiments() no longer creates separate jobs for each subcircuit by default. Now, separate jobs are only created if separate BaseSampler instances are provided for each circuit partition.
Numpy 1.23.0 or later is now required. The kron() method in earlier versions has known performance issues, and this method is used heavily by the CutQC wire cutting module.
The dependency on the qiskit.opflow module has been removed from entanglement forging. With this change, Qiskit Nature 0.6.0 is now required. However, Qiskit Nature 0.6.0 is incompatible with Quantum Serverless, so users that wish to use entanglement forging with Quantum Serverless must remain on version 0.2 of the Circuit Knitting Toolbox until issue #108 is resolved.
BaseQPDGate instances in subcircuits returned from partition_circuit_qubits() and partition_problem() will now have labels prefixed with “cut”, rather than “qpd”.

Deprecation Notes

decompose_gates() is deprecated and will be removed no sooner than v0.4.0. Users should migrate to the identical cut_gates() function.
generate_qpd_samples() has been renamed to generate_qpd_weights(). The original name will be removed no sooner than version 0.4 of the Circuit Knitting Toolbox.
QPDBasis.from_gate() has been renamed to QPDBasis.from_instruction(). The original name is deprecated and will be removed no sooner than CKT v0.4.0.
The top-level name for imports has been renamed from circuit_knitting_toolbox to circuit_knitting. Furthermore, the following renames have occurred one level deeper:
- circuit_knitting_toolbox.entanglement_forging has been moved to circuit_knitting.forging.
- circuit_knitting_toolbox.circuit_cutting has been moved to circuit_knitting.cutting.
The old import locations are now deprecated and will be removed in a future release of the Circuit Knitting Toolbox.

Bug Fixes

Fixed a bug in decompose_qpd_instructions() which would cause index errors if TwoQubitQPDGate indices were not specified in ascending order.
Fixed a bug in circuit_knitting.forging.EntanglementForgingGroundStateSolver which was causing AttributeErrors when instantiating the :class:circuit_knitting.forging.EntanglementForgingResult in certain conditions, such as when reducing the orbitals over which to solve.

0.2.0

Prelude

0.2.0 is centered around the addition of functions which allow for the easy implementation of a circuit cutting technique called gate cutting. For more details on circuit cutting, check out our explanation guide.

The foundation of the circuit_cutting package is the circuit_knitting_toolbox.circuit_cutting.qpd sub-package. The qpd package allows for easy transformation of QuantumCircuit gates and wires into elements which may be decomposed to a probabilistic set of basis gates. See QPDBasis and BaseQPDGate classes for more information.

Additionally, 0.2.0 includes a set of functions which allow for easy implementation of gate cutting workflows. These functions are built on top of the circuit_knitting_toolbox.circuit_cutting.qpd package. Like all circuit knitting techniques, gate cutting can be described as three consecutive stages: decomposition of a problem, execution of many subexperiments, and reconstruction of a simulated output of the original problem. These steps may be implemented with the circuit_cutting package using only a few primary functions, namely, the partition_problem(), decompose_gates(), execute_experiments(), and reconstruct_expectation_values() functions. Check out the tutorials for a look at a couple of example circuit cutting workflows.

New Features

Addition of a qpd package which allows for easy transformation of QuantumCircuit gates and wires into elements which may be decomposed to a probabilistic set of basis gates. See QPDBasis and BaseQPDGate classes for more information.
Addition of cutting_decomposition, cutting_execution, and cutting_reconstruction modules. These modules provide several functions which allow for easy implementation of gate cutting workflows, namely, the partition_problem(), decompose_gates(), execute_experiments(), and reconstruct_expectation_values() functions.

Known Issues

The circuit_cutting package only supports PauliList observables for calculating expectation values. Support for calculating expectation values for more observable types, including SparsePauliOp, is expected no sooner than 0.3.0.
The Samplers from Qiskit and Qiskit Aer do not support mid-circuit measurements in statevector mode. For more on generating exact quasi-distributions using the BaseSampler interface, check out our how-to guide.
The circuit_cutting package generally does not yet support input circuits with user-added classical bits, so by extension, it does not yet support dynamic circuits.

Upgrade Notes

Support for running with Python 3.7 has been removed. To run the Circuit Knitting Toolbox, you now need Python version 3.8 or higher.

Deprecation Notes

The circuit_knitting_toolbox.circuit_cutting.wire_cutting namespace is now deprecated. It has been renamed to circuit_knitting_toolbox.circuit_cutting.cutqc. Both gate and wire cutting for simulating expectation values will be implemented directly into the circuit_cutting package, and the circuit_cutting.cutqc package will remain available for users of the automatic cut finding and/or the full probability distribution reconstruction.

0.1.0

New Features

Support for Python 3.11.
Support for Qiskit Nature 0.5.

Upgrade Notes

The minimum supported version of each Qiskit dependency has been updated. This release depends on qiskit-terra>=0.23.3, qiskit-aer>=0.12.0, qiskit-nature>=0.5.2, and qiskit-ibm-runtime>=0.9.2. qiskit-ibmq-provider is now deprecated and is no longer required by the Circuit Knitting Toolbox.
Support for Qiskit Nature < 0.5 has been removed upon this release.

Users are now be required to use the qiskit_nature.second_q.problems.ElectronicStructureProblem, as input to the EntanglementForgingGroundStateSolver, rather than the deprecated qiskit_nature.problems.second_quantization.ElectronicStructureProblem.

For more information on migrating to Qiskit Nature 0.5, check out the Qiskit Nature migration guide.

For more information on adapting your entanglement forging workflows, check out the tutorials <Forging tutorials> and how-to guides <Forging how-tos>.
The ~circuit_knitting_toolbox.utils.IntegralDriver class has been removed. The new Qiskit Nature API allows for a more flexible build-up of the qiskit_nature.second_q.problems.ElectronicStructureProblem, and this driver is no longer needed.
DOcplex and cplex are now optional dependencies. They must be installed for automatic wire cut finding to work.

Deprecation Notes

Support for running with Python 3.7 has been deprecated. Future versions of the Circuit Knitting Toolbox will require Python 3.8 or higher.