circuit_knitting.cutting.generate_cutting_experiments

generate_cutting_experiments(circuits, observables, num_samples)[source]

Generate cutting subexperiments and their associated coefficients.

If the input, circuits, is a QuantumCircuit instance, the output subexperiments will be contained within a 1D array, and observables is expected to be a PauliList instance.

If the input circuit and observables are specified by dictionaries with partition labels as keys, the output subexperiments will be returned as a dictionary which maps each partition label to a 1D array containing the subexperiments associated with that partition.

In both cases, the subexperiment lists are ordered as follows:

\([sample_{0}observable_{0}, \ldots, sample_{0}observable_{N-1}, sample_{1}observable_{0}, \ldots, sample_{M-1}observable_{N-1}]\)

The coefficients will always be returned as a 1D array – one coefficient for each unique sample.

Parameters:

  • circuits (QuantumCircuit | dict[Hashable, QuantumCircuit]) – The circuit(s) to partition and separate

  • observables (PauliList | dict[Hashable, PauliList]) – The observable(s) to evaluate for each unique sample

  • num_samples (int | float) – The number of samples to draw from the quasi-probability distribution. If set to infinity, the weights will be generated rigorously rather than by sampling from the distribution.

Return type:

tuple[list[QuantumCircuit] | dict[Hashable, list[QuantumCircuit]], list[tuple[float, WeightType]]]

Returns:

A tuple containing the cutting experiments and their associated coefficients. If the input circuits is a QuantumCircuit instance, the output subexperiments will be a sequence of circuits – one for every unique sample and observable. If the input circuits are represented as a dictionary keyed by partition labels, the output subexperiments will also be a dictionary keyed by partition labels and containing the subexperiments for each partition. The coefficients are always a sequence of length-2 tuples, where each tuple contains the coefficient and the WeightType. Each coefficient corresponds to one unique sample.

Raises:

  • ValueError – num_samples must be at least one.

  • ValueError – circuits and observables are incompatible types

  • ValueError – SingleQubitQPDGate instances must have their cut ID appended to the gate label so they may be associated with other gates belonging to the same cut.

  • ValueError – SingleQubitQPDGate instances are not allowed in unseparated circuits.