Quasi-Probability Decomposition (QPD) (qiskit_addon_cutting.qpd)

Main quasiprobability decomposition functionality.

QPDBasis

Basis in which to decompose an operation.

BaseQPDGate

Base class for a gate to be decomposed using quasiprobability decomposition.

SingleQubitQPDGate

Single qubit gate to be decomposed using quasiprobability decomposition.

TwoQubitQPDGate

Two qubit gate to be decomposed using quasiprobability decomposition.
class WeightType(value)[source]

Bases: Enum

Type of weight associated with a QPD sample.

EXACT = 1

A weight given in proportion to its exact weight

SAMPLED = 2

A weight that was determined through some sampling procedure

generate_qpd_weights(qpd_bases, num_samples=1000)[source]

Generate weights from the joint quasiprobability distribution.

Each weight whose absolute value is above a threshold of 1 / num_samples will be evaluated exactly. The remaining weights – those in the tail of the distribution – will then be sampled from, resulting in at most num_samples unique weights.

Parameters:

  • qpd_bases (Sequence[QPDBasis]) – The QPDBasis objects from which to generate weights

  • num_samples (float) – Controls the number of weights to generate

Return type:

dict[tuple[int, ...], tuple[float, WeightType]]

Returns:

A mapping from a given decomposition to its weight. Keys are tuples of indices – one index per input QPDBasis. The indices correspond to a specific decomposition mapping in the basis.

Values are tuples. The first element is a number corresponding to the weight of the contribution. The second element is the WeightType, either EXACT or SAMPLED.

decompose_qpd_instructions(circuit, instruction_ids, map_ids=None, *, inplace=False)[source]

Replace all QPD instructions in the circuit with local Qiskit operations and measurements.

Parameters:

  • circuit (QuantumCircuit) – The circuit containing QPD instructions

  • instruction_ids (Sequence[Sequence[int]]) – A 2D sequence, such that each inner sequence corresponds to indices of instructions comprising one decomposition in the circuit. The elements within a common sequence belong to a common decomposition and should be sampled together.

  • map_ids (Sequence[int] | None) – Indices to a specific linear mapping to be applied to the decompositions in the circuit. If no map IDs are provided, the circuit will be decomposed randomly according to the decompositions’ joint probability distribution.

  • inplace (bool) – If True, the circuit will be modified in place.

Return type:

QuantumCircuit

Returns:

Circuit which has had all its BaseQPDGate instances decomposed into local operations.

The circuit will contain a new, final classical register to contain the QPD measurement outcomes (accessible at retval.cregs[-1]).

Raises:

  • ValueError – An index in instruction_ids corresponds to a gate which is not a BaseQPDGate instance.

  • ValueError – A list within instruction_ids is not length 1 or 2.

  • ValueError – The total number of indices in instruction_ids does not equal the number of BaseQPDGate instances in the circuit.

  • ValueError – Gates within the same decomposition hold different QPD bases.

  • ValueError – Length of map_ids does not equal the number of decompositions in the circuit.

qpdbasis_from_instruction(gate, /)[source]

Generate a QPDBasis object, given a supported operation.

All two-qubit gates which implement the to_matrix() method are supported. This should include the vast majority of gates with no unbound parameters, but there are some special cases (see, e.g., qiskit issue #10396).

The Move operation, which can be used to specify a wire cut, is also supported.

Return type:

QPDBasis

Returns:

The newly-instantiated QPDBasis object

Raises:

  • ValueError – Instruction not supported.

  • ValueError – Cannot decompose instruction with unbound parameters.

  • ValueError – to_matrix conversion of two-qubit gate failed.

Parameters:

gate (Instruction)