ClassicalShadows

class ClassicalShadows(num_qubits: int, *, measurement_layout: list[int] | None = None, measurement_twirl: bool = False, shot_repetitions: int = 1, insert_barriers: bool = False, seed: int | Generator | None = None)[source]

Bases: LocallyBiasedClassicalShadows

A classical shadows POVM.

This is a special case of the LocallyBiasedClassicalShadows, where the bias is taken to be uniform. That is, there is an equal probability to perform a measurement in the Z, X and Y bases.

The example below shows how you construct a classical shadows POVM. It plots a visual representation of the POVM’s definition to exemplify the equal measurement probabilities.

>>> from povm_toolbox.library import ClassicalShadows
>>> povm = ClassicalShadows(2, measurement_twirl=True, shot_repetitions=10)
>>> print(povm)
ClassicalShadows(num_qubits=2)
>>> povm.definition().draw_bloch()
<Figure size 1000x500 with 2 Axes>

(Source code, png, hires.png, pdf)

../_images/povm_toolbox-library-ClassicalShadows-1.png

Initialize a classical shadows POVM.

Parameters:

  • num_qubits (int) – the number of qubits.

  • measurement_layout (list[int] | None) – optional list of indices specifying on which qubits the POVM acts. See measurement_layout for more details.

  • measurement_twirl (bool) – whether to randomly twirl the measurements. For each single-qubit projective measurement, random twirling is equivalent to randomly flipping the measurement. This is equivalent to randomly taking the opposite Bloch vector in the Bloch sphere representation.

  • shot_repetitions (int) – number of times the measurement is repeated for each sampled PVM. More precisely, a new PVM is sampled for all shots (i.e. the number of times as specified by the user via the shots argument of the method POVMSampler.run()). Then, the parameter shot_repetitions states how many times we repeat the measurement for each sampled PVM (default is 1). Therefore, the effective total number of measurement shots is shots multiplied by shot_repetitions.

  • insert_barriers (bool) – whether to insert a barrier between the composed circuits. This is not done by default but can prove useful when visualizing the composed circuit.

  • seed (int | Generator | None) – optional seed to fix the numpy.random.Generator used to sample PVMs. The user can also directly provide a random generator. If None, a random seed will be used.

Attributes

rotation_angles: np.ndarray

The angles indicating the rotation to obtain the MUB from an otherwise LBCS POVM.

bias

The sampling bias for each PVM per qubit.

angles

The angles defining each PVM. These are stored as pairs of (theta, phi) and correspond to the parameters of the UGate instance used to rotate the canonical Z-measurement into an arbitrary projective measurement.

measurement_twirl

Whether twirling of the PVMs is enabled.

shot_repetitions

The number of times the measurement is repeated for each sampled PVM. More precisely, a new PVM is sampled for all shots (i.e. the number of times as specified by the user via the shots argument of the method POVMSampler.run()). Then, this attribute states how many times we repeat the measurement for each sampled PVM (default is 1). Therefore, the effective total number of measurement shots is shots multiplied by shot_repetitions.

num_qubits: int

The number of logical qubits in the system.

measurement_layout: list[int] | None

An optional list of indices specifying on which qubits the POVM acts.

If None, two cases can be distinguished:

  1. if a circuit supplied to the compose_circuits() has been transpiled, its final transpile layout will be used as default value,

  2. otherwise, a simple one-to-one layout list(range(num_qubits)) is used.

insert_barriers: bool

Whether to insert a barrier between the original circuit and the measurement circuit produced by this POVM implementation.

measurement_circuit: QuantumCircuit

The QuantumCircuit actually implementing this POVM’s measurement.

Inherited Attributes

classical_register_name: str = 'povm_measurement_creg'

The name given to the classical bit register in which the POVM outcomes are stored.

The DataBin container result object will have an attribute with this name, which will contain the raw measurement data.

Inherited Methods

compose_circuits(circuit: QuantumCircuit) → QuantumCircuit

Compose the circuit to sample from, with the measurement circuit.

If the measurement circuit requires some ancilla qubits, this method will inspect the input circuit. If the input circuit has some idling qubits available, they will be used as ancilla measurement qubits. If not enough idling qubits are available, this method will add the necessary number of qubits to the input circuit before composing it with the measurement circuit.

Parameters:

circuit (QuantumCircuit) – The quantum circuit to be sampled from.

Raises:

  • ValueError – if the number of qubits specified by self.measurement_layout does not match the number of qubits on which this POVM implementation acts.

  • CircuitError – if an error has occurred when adding the classic register, used to save POVM results, to the input circuit.

Returns:

The composition of the supplied quantum circuit with the measurement_circuit of this POVM implementation.

Return type:

QuantumCircuit

definition() → ProductPOVM

Return the corresponding quantum-informational POVM representation.

Return type:

ProductPOVM

get_povm_counts_from_raw(data: DataBin, povm_metadata: MetadataT, *, loc: int | tuple[int, ...] | None = None) → ndarray | Counter

Get the POVM counts.

Parameters:

  • data (DataBin) – The raw sampled data.

  • povm_metadata (MetadataT) – The associated metadata.

  • loc (int | tuple[int, ...] | None) – an optional location to slice the bitstrings.

Returns:

The POVM counts.

Return type:

ndarray | Counter

get_povm_outcomes_from_raw(data: DataBin, povm_metadata: MetadataT, *, loc: int | tuple[int, ...] | None = None) → ndarray | list[tuple[int, ...]]

Get the POVM bitstrings.

Parameters:

  • data (DataBin) – The raw sampled data.

  • povm_metadata (MetadataT) – The associated metadata.

  • loc (int | tuple[int, ...] | None) – an optional location to slice the bitstrings.

Returns:

The POVM bitstrings.

Return type:

ndarray | list[tuple[int, …]]

reshape_data_bin(data: DataBin) → DataBin

Reshapes the provided data.

This method should reshape the provided data to the output dimensions expected by the end-user. That is, the dimensions should match those of the qiskit.primitives.SamplerPubLike object provided by the user when submitting their primitive job.

Parameters:

data (DataBin) – The raw primitive result data still shaped according to the internally submitted POVMSamplerJob.

Returns:

A new data structure of the correct shape.

Return type:

DataBin

to_sampler_pub(circuit: QuantumCircuit, circuit_binding: BindingsArray, shots: int, *, pass_manager: StagedPassManager | None = None) → tuple[SamplerPub, RPMMetadata]

Append the measurement circuit(s) to the supplied circuit.

This method takes a supplied circuit and appends the measurement circuit(s) to it. If the measurement circuit is parametrized, its parameters values should be concatenated with the parameter values associated with the supplied quantum circuit.

Warning

The actual number of measurements executed will depend not only on the provided shots value but also on the value of shot_repetitions.

Parameters:

  • circuit (QuantumCircuit) – A quantum circuit.

  • circuit_binding (BindingsArray) – A bindings array.

  • shots (int) – A specific number of shots to run with.

  • pass_manager (StagedPassManager | None) – An optional transpilation pass manager. After the supplied circuit has been composed with the measurement circuit, the pass manager will be used to transpile the composed circuit.

Returns:

A tuple of a sampler pub and a dictionary of metadata which includes the POVMImplementation object itself. The metadata should contain all the information necessary to extract the POVM outcomes out of raw bitstrings.

Return type:

tuple[SamplerPub, RPMMetadata]