# qiskit.tools.qcvv.tomography module¶

Quantum Tomography Module

Description:

This module contains functions for performing quantum state and quantum process tomography. This includes: - Functions for generating a set of circuits to

extract tomographically complete sets of measurement data.
• Functions for generating a tomography data set from the results after the circuits have been executed on a backend.
• Functions for reconstructing a quantum state, or quantum process (Choi-matrix) from tomography data sets.
Reconstruction Methods:
Currently implemented reconstruction methods are - Linear inversion by weighted least-squares fitting. - Fast maximum likelihood reconstruction using ref [1].

References

[1] J Smolin, JM Gambetta, G Smith, Phys. Rev. Lett. 108, 070502 (2012).
Open access: arXiv:1106.5458 [quant-ph].
Workflow:

The basic functions for performing state and tomography experiments are: - tomography_set, state_tomography_set, and process_tomography_set

all generates data structures for tomography experiments.
• create_tomography_circuits generates the quantum circuits specified
in a tomography_set for performing state tomography of the output
• tomography_data extracts the results after executing the tomography
circuits and returns it in a data structure used by fitters for state reconstruction.
• fit_tomography_data reconstructs a density matrix or Choi-matrix from
the a set of tomography data.
class TomographyBasis[source]

Bases: dict

Dictionary subsclass that includes methods for adding gates to circuits.

A TomographyBasis is a dictionary where the keys index a measurement and the values are a list of projectors associated to that measurement. It also includes two optional methods prep_gate and meas_gate:

• prep_gate adds gates to a circuit to prepare the corresponding basis projector from an initial ground state.
• meas_gate adds gates to a circuit to transform the default Z-measurement into a measurement in the basis.

With the exception of built in bases, these functions do nothing unless they are specified by the user. They may be set by the data members prep_fun and meas_fun. We illustrate this with an example.

Example

A measurement in the Pauli-X basis has two outcomes corresponding to the projectors:

Xp = [[0.5, 0.5], [0.5, 0.5]] Xm = [[0.5, -0.5], [-0.5, 0.5]]
We can express this as a basis by
BX = TomographyBasis( {‘X’: [Xp, Xm]} )
To specifiy the gates to prepare and measure in this basis we :

 def BX_prep_fun(circuit, qreg, op):

bas, proj = op if bas == “X”:

if proj == 0:
circuit.u2(0., np.pi, qreg) # apply H
else: # proj == 1
circuit.u2(np.pi, np.pi, qreg) # apply H.X
def BX_prep_fun(circuit, qreg, op):
if op == “X”:
circuit.u2(0., np.pi, qreg) # apply H
We can then attach these functions to the basis using:
BX.prep_fun = BX_prep_fun BX.meas_fun = BX_meas_fun.
Generating function:

A generating function tomography_basis exists to create bases in a single step. Using the above example this can be done by:  BX = tomography_basis({‘X’: [Xp, Xm]},

prep_fun=BX_prep_fun, meas_fun=BX_meas_fun)
meas_fun = None
meas_gate(circuit, qreg, op)[source]

Add measurement gates to a circuit.

Parameters: circuit (QuantumCircuit) – circuit to add measurement to. qreg (tuple(QuantumRegister,int)) – quantum register being measured. op (str) – the basis label for the measurement.
prep_fun = None
prep_gate(circuit, qreg, op)[source]

Add state preparation gates to a circuit.

Parameters: circuit (QuantumCircuit) – circuit to add a preparation to. qreg (tuple(QuantumRegister,int)) – quantum register to apply to. (preparation) – op (tuple(str, int)) – the basis label and index for the op. (preparation) –
build_wigner_circuits(circuit, phis, thetas, qubits, qreg, creg)[source]

Create the circuits to rotate to points in phase space :param circuit: The circuit to be appended with tomography

state preparation and/or measurements.
Parameters: phis (np.matrix[[complex]]) – phis thetas (np.matrix[[complex]]) – thetas qubits (list[int]) – a list of the qubit indexes of qreg to be measured. qreg (QuantumRegister) – the quantum register containing qubits to be measured. creg (ClassicalRegister) – the classical register containing bits to store measurement outcomes. A list of names of the added wigner function circuits. list QiskitError – if circuit is not a valid QuantumCircuit.
count_keys(n)[source]

Generate outcome bitstrings for n-qubits.

Parameters: n (int) – the number of qubits. A list of bitstrings ordered as follows: Example: n=2 returns [‘00’, ‘01’, ‘10’, ‘11’]. list
create_tomography_circuits(circuit, qreg, creg, tomoset)[source]

Add tomography measurement circuits to a QuantumProgram.

The quantum program must contain a circuit ‘name’, which is treated as a state preparation circuit for state tomography, or as teh circuit being measured for process tomography. This function then appends the circuit with a set of measurements specified by the input tomography_set, optionally it also prepends the circuit with state preparation circuits if they are specified in the tomography_set.

For n-qubit tomography with a tomographically complete set of preparations and measurements this results in $4^n 3^n$ circuits being added to the quantum program.

Parameters: circuit (QuantumCircuit) – The circuit to be appended with tomography state preparation and/or measurements. qreg (QuantumRegister) – the quantum register containing qubits to be measured. creg (ClassicalRegister) – the classical register containing bits to store measurement outcomes. tomoset (tomography_set) – the dict of tomography configurations. A list of quantum tomography circuits for the input circuit. list QiskitError – if circuit is not a valid QuantumCircuit

Example

For a tomography set specifying state tomography of qubit-0 prepared by a circuit ‘circ’ this would return:  ['circ_meas_X(0)', 'circ_meas_Y(0)', 'circ_meas_Z(0)']  For process tomography of the same circuit with preparation in the SIC-POVM basis it would return:  [

‘circ_prep_S0(0)_meas_X(0)’, ‘circ_prep_S0(0)_meas_Y(0)’, ‘circ_prep_S0(0)_meas_Z(0)’, ‘circ_prep_S1(0)_meas_X(0)’, ‘circ_prep_S1(0)_meas_Y(0)’, ‘circ_prep_S1(0)_meas_Z(0)’, ‘circ_prep_S2(0)_meas_X(0)’, ‘circ_prep_S2(0)_meas_Y(0)’, ‘circ_prep_S2(0)_meas_Z(0)’, ‘circ_prep_S3(0)_meas_X(0)’, ‘circ_prep_S3(0)_meas_Y(0)’, ‘circ_prep_S3(0)_meas_Z(0)’
fit_tomography_data(tomo_data, method='wizard', options=None)[source]

Reconstruct a density matrix or process-matrix from tomography data.

If the input data is state_tomography_data the returned operator will be a density matrix. If the input data is process_tomography_data the returned operator will be a Choi-matrix in the column-vectorization convention.

Parameters: tomo_data (dict) – process tomography measurement data. method (str) – the fitting method to use. Available methods: ’wizard’ (default) ’leastsq’ options (dict or None) – additional options for fitting method. The fitted operator. numpy.array
Available methods:
• ‘wizard’ (Default): The returned operator will be constrained to be

positive-semidefinite.

Options: - ‘trace’: the trace of the returned operator.

The default value is 1.

• ‘beta’: hedging parameter for computing frequencies from
zero-count data. The default value is 0.50922.
• ‘epsilon: threshold for truncating small eigenvalues to zero.
The default value is 0
• ‘leastsq’: Fitting without positive-semidefinite constraint.

Options: - ‘trace’: Same as for ‘wizard’ method. - ‘beta’: Same as for ‘wizard’ method.

Raises: Exception – if the method parameter is not valid.
marginal_counts(counts, meas_qubits)[source]

Compute the marginal counts for a subset of measured qubits.

Parameters: counts (dict) – the counts returned from a backend ({str: int}). meas_qubits (list[int]) – the qubits to return the marginal counts distribution for. A counts dict for the meas_qubits.abs Example: if counts = {‘00’: 10, ‘01’: 5} marginal_counts(counts, [0]) returns {‘0’: 15, ‘1’: 0}. marginal_counts(counts, [0]) returns {‘0’: 10, ‘1’: 5}. dict
process_tomography_set(meas_qubits, meas_basis='Pauli', prep_qubits=None, prep_basis='SIC')[source]

Generate a dictionary of process tomography experiment configurations.

This returns a data structure that is used by other tomography functions to generate state and process tomography circuits, and extract tomography data from results after execution on a backend.

A quantum process tomography set is created by specifying a preparation

basis along with a measurement basis. The preparation basis may be a user defined tomography_basis, or one of the two built in basis ‘SIC’ or ‘Pauli’. - SIC: Is a minimal symmetric informationally complete preparation

basis for 4 states for each qubit (4 ^ number of qubits total preparation states). These correspond to the |0> state and the 3 other vertices of a tetrahedron on the Bloch-sphere.
• Pauli: Is a tomographically overcomplete preparation basis of the six
eigenstates of the 3 Pauli operators (6 ^ number of qubits total preparation states).
Args:

meas_qubits (list): The qubits being measured. meas_basis (tomography_basis or str): The qubit measurement basis.

The default value is ‘Pauli’.
prep_qubits (list or None): The qubits being prepared. If None then
meas_qubits will be used for process tomography experiments.
prep_basis (tomography_basis or str): The qubit preparation basis.
The default value is ‘SIC’.
Returns:

dict: A dict of tomography configurations that can be parsed by create_tomography_circuits and tomography_data functions for implementing quantum tomography experiments. This output contains fields “qubits”, “meas_basis”, “prep_basus”, circuits”.  {

‘qubits’: qubits (list[ints]), ‘meas_basis’: meas_basis (tomography_basis), ‘prep_basis’: prep_basis (tomography_basis), ‘circuit_labels’: (list[string]), ‘circuits’: (list[dict]) # prep and meas configurations
state_tomography_set(qubits, meas_basis='Pauli')[source]

Generate a dictionary of state tomography experiment configurations.

This returns a data structure that is used by other tomography functions to generate state and process tomography circuits, and extract tomography data from results after execution on a backend.

Quantum State Tomography:
Be default it will return a set for performing Quantum State Tomography where individual qubits are measured in the Pauli basis. A custom measurement basis may also be used by defining a user tomography_basis and passing this in for the meas_basis argument.
Quantum Process Tomography:

A quantum process tomography set is created by specifying a preparation basis along with a measurement basis. The preparation basis may be a user defined tomography_basis, or one of the two built in basis ‘SIC’ or ‘Pauli’. - SIC: Is a minimal symmetric informationally complete preparation

basis for 4 states for each qubit (4 ^ number of qubits total preparation states). These correspond to the |0> state and the 3 other vertices of a tetrahedron on the Bloch-sphere.
• Pauli: Is a tomographically overcomplete preparation basis of the six
eigenstates of the 3 Pauli operators (6 ^ number of qubits total preparation states).
Parameters: qubits (list) – The qubits being measured. meas_basis (tomography_basis or str) – The qubit measurement basis. The default value is ‘Pauli’. A dict of tomography configurations that can be parsed by create_tomography_circuits and tomography_data functions for implementing quantum tomography experiments. This output contains fields “qubits”, “meas_basis”, “circuits”.  { ’qubits’: qubits (list[ints]), ‘meas_basis’: meas_basis (tomography_basis), ‘circuit_labels’: (list[string]), ‘circuits’: (list[dict]) # prep and meas configurations dict
tomography_basis(basis, prep_fun=None, meas_fun=None)[source]

Generate a TomographyBasis object.

See TomographyBasis for further details.abs

Parameters: prep_fun (callable) – the function which adds preparation gates to a circuit. meas_fun (callable) – the function which adds measurement gates to a circuit. A tomography basis. TomographyBasis
tomography_circuit_names(tomo_set, name='')[source]

Return a list of tomography circuit names.

The returned list is the same as the one returned by create_tomography_circuits and can be used by a QuantumProgram to execute tomography circuits and extract measurement results.

Parameters: tomo_set (tomography_set) – a tomography set generated by tomography_set. name (str) – the name of the base QuantumCircuit used by the experiment. (tomography) – A list of circuit names. list
tomography_data(results, name, tomoset)[source]

Return a results dict for a state or process tomography experiment.

Parameters: results (Result) – Results from execution of a process tomography circuits on a backend. name (string) – The name of the circuit being reconstructed. tomoset (tomography_set) – the dict of tomography configurations. A list of dicts for the outcome of each process tomography measurement circuit. list
tomography_set(meas_qubits, meas_basis='Pauli', prep_qubits=None, prep_basis=None)[source]

Generate a dictionary of tomography experiment configurations.

This returns a data structure that is used by other tomography functions to generate state and process tomography circuits, and extract tomography data from results after execution on a backend.

Quantum State Tomography:
Be default it will return a set for performing Quantum State Tomography where individual qubits are measured in the Pauli basis. A custom measurement basis may also be used by defining a user tomography_basis and passing this in for the meas_basis argument.
Quantum Process Tomography:

A quantum process tomography set is created by specifying a preparation basis along with a measurement basis. The preparation basis may be a user defined tomography_basis, or one of the two built in basis ‘SIC’ or ‘Pauli’. - SIC: Is a minimal symmetric informationally complete preparation

basis for 4 states for each qubit (4 ^ number of qubits total preparation states). These correspond to the |0> state and the 3 other vertices of a tetrahedron on the Bloch-sphere.
• Pauli: Is a tomographically overcomplete preparation basis of the six
eigenstates of the 3 Pauli operators (6 ^ number of qubits total preparation states).
Parameters: meas_qubits (list) – The qubits being measured. meas_basis (tomography_basis or str) – The qubit measurement basis. The default value is ‘Pauli’. prep_qubits (list or None) – The qubits being prepared. If None then meas_qubits will be used for process tomography experiments. prep_basis (tomography_basis or None) – The optional qubit preparation basis. If no basis is specified state tomography will be performed instead of process tomography. A built in basis may be specified by ‘SIC’ or ‘Pauli’ (SIC basis recommended for > 2 qubits). A dict of tomography configurations that can be parsed by create_tomography_circuits and tomography_data functions for implementing quantum tomography experiments. This output contains fields “qubits”, “meas_basis”, “circuits”. It may also optionally contain a field “prep_basis” for process tomography experiments.  { ’qubits’: qubits (list[ints]), ‘meas_basis’: meas_basis (tomography_basis), ‘circuit_labels’: (list[string]), ‘circuits’: (list[dict]) # prep and meas configurations # optionally for process tomography experiments: ‘prep_basis’: prep_basis (tomography_basis) dict QiskitError – if the Qubits argument is not a list.
wigner_data(q_result, meas_qubits, labels, shots=None)[source]

Get the value of the Wigner function from measurement results.

Parameters: q_result (Result) – Results from execution of a state tomography circuits on a backend. meas_qubits (list[int]) – a list of the qubit indexes measured. labels (list[str]) – a list of names of the circuits shots (int) – number of shots The values of the Wigner function at measured points in phase space list