RandomizedProjectiveMeasurements¶

class RandomizedProjectiveMeasurements(num_qubits: int, bias: ndarray, angles: ndarray, *, 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: POVMImplementation[RPMMetadata]

A general randomized projective measurements POVM.

The example below shows how you construct a RPM POVM. It plots a visual representation of the POVM’s definition to exemplify the different randomization for each qubit.

>>> import numpy as np
>>> from povm_toolbox.library import RandomizedProjectiveMeasurements
>>> povm = RandomizedProjectiveMeasurements(
...     2,
...     bias=np.array([[0.1, 0.6, 0.3], [0.5, 0.25, 0.25]]),
...     angles=np.array([
...         [np.pi/6, 5*np.pi/6, -np.pi/4, -np.pi/2, -np.pi/2, np.pi/4],
...         [np.pi/3, np.pi/3, -np.pi/3, np.pi/3, np.pi/3, -np.pi/3],
...     ]),
... )
>>> print(povm)
RandomizedProjectiveMeasurements(num_qubits=2, bias=array([[0.1 , 0.6 , 0.3 ], [0.5 , 0.25, 0.25]]),
    angles=array([[[ 0.52359878,  2.61799388],
        [-0.78539816, -1.57079633],
        [-1.57079633,  0.78539816]],
       [[ 1.04719755,  1.04719755],
        [-1.04719755,  1.04719755],
        [ 1.04719755, -1.04719755]]]))
>>> povm.definition().draw_bloch()
<Figure size 1000x500 with 2 Axes>

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

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

Initialize a randomized projective measurements POVM.

Parameters:

num_qubits (int) – the number of qubits.
bias (np.ndarray) – can be either 1D or 2D. If 1D, it should contain float values indicating the bias for measuring in each of the PVMs. I.e., its length equals the number of PVMs. These floats should sum to 1. If 2D, it will have a new set of biases for each qubit.
angles (np.ndarray) – can be either 1D or 2D. If 1D, it should be a flatten array containing float values to indicate the different angles of each PVM. I.e. its length equals two times the number of PVMs (since we have 2 angles per PVM). If 2D, it will have a new set of angles for each qubit. The angles are expected to be pairs of angles (theta, phi) for each PVM and correspond to the parameters of the UGate instance used to rotate the canonical Z-measurement into an arbitrary projective measurement. Note that this differs from the angles expected during the initialization of a MutuallyUnbiasedBasesMeasurements instance, where a unique triplet of angles (theta, phi, lam) is expected for each qubit.
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 PVMs are sampled according to the probability distribution(s) specified by bias. The user can also directly provide a random generator. If None, a random seed will be used.

Raises:

ValueError – If the shape of bias is not compatible with the shape of angles.
ValueError – If the shape of bias is not compatible with num_qubits.
ValueError – If there is a negative value in the probability distribution(s) specified by bias.
ValueError – If the probability distribution(s) specified by bias don’t sum up to 1.
ValueError – If the shape of angles is not compatible with num_qubits.
TypeError – If the type of seed is not valid.

Attributes

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:

if a circuit supplied to the compose_circuits() has been transpiled, its final transpile layout will be used as default value,
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.

Methods

definition() → ProductPOVM[source]¶

Return the corresponding quantum-informational POVM representation.

Return type:: ProductPOVM

reshape_data_bin(data: DataBin) → DataBin[source]¶

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][source]¶

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]

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

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, …]]