# Visualization¶

trueq.visualization.general.multiply_lightness(color, amount=0.5)

Modifies a color by multiplying (1-lightness) by the given amount. Numbers less than 1 result in a lighter color, and numbers greater than 1 result in a darker color.

https://gist.github.com/ihincks/6a420b599f43fcd7dbd79d56798c4e5a

multiply_lightness("g", 0.3)
multiply_lightness("#F034A3", 0.6)
multiply_lightness((0.3, 0.55, 0.1), 0.5)

Parameters
• color (str | tuple) – A matplotlib color string, hex string, or RGB tuple.

• amount (float) – The amount to multiply (1-lightness) of the input color by.

Returns

An RGB tuple.

Return type

tuple

trueq.visualization.general.plot_mat(mat, xlabels=2, ylabels=2, show_values=True, ax=None)

Plots a complex matrix with labeling with the following properties:

1. Color is dictated by the complex angle of each cell.

2. Transparency (alpha) is decided by the magnitude of each cell.

3. Size of plot scales based on shape of mat.

phase = [np.exp(1j * t *np.pi) for t in np.linspace(0, 1, 16)]
plot_mat(np.outer(phase, phase))

Parameters
• mat (numpy.ndarray-like) – A real or complex matrix.

• xlabels (int | Iterable | None) – Either None, an iterable of labels for the x-axis, or the dimension of the subsystems where the x axis labels are the computational basis states as inferred from the size of mat. If None, the axis will be labelled by the numbers that index the columns.

• ylabels (int | Iterable | None) – Either None, an iterable of labels for the y-axis, or the dimension of the subsystems where the x axis labels are the computational basis states as inferred from the size of mat. If None, the axis will be labelled by the numbers that index the rows.

• show_values (bool) – Whether to show the numeric values of the matrix in each cell.

• ax (matplotlib.Axis) – An existing axis to plot on. If not given, a new figure will be created.

Note

The following methods and classes typically should not be invoked by users. Their plotting methods are exposed dynamically by the attributes trueq.CircuitCollection.plot and trueq.parameters.ParameterCollection.plot.

class trueq.visualization.plotters.Plotter

Represents a function that performs a plotting operation either on a ParameterCollection or a CircuitCollection (with data).

abstract static applies_to_parameters(keys)

A fast check that determines whether these parameters are broadly compatible with this plotting function. The plotting function is still allowed to raise (and indeed, it is encouraged) if it sees something it doesn’t like; this method is an a priori check that determines which plotters are automatically recommended to users.

Parameters

keys – Keys of the trueq.parameters.ParameterCollection.

Return type

bool

abstract static applies_to_circuits(keys)

A fast check that determines whether these circuits are broadly compatible with this plotting function. The plotting function is still allowed to raise (and indeed, it is encouraged) if it sees something it doesn’t like; this method is an a priori check that determines which plotters are automatically recommended to users.

This method should usually check to see if at least some data is present.

Parameters

keys – Keys of the trueq.parameters.CircuitCollection.

Return type

bool

abstract static plot()

Plots the given ParameterCollection or CircuitCollection.

static axes(n_plots, axes=None, n_columns=1, axis_size=(4, 3.5), gs_options=None)

Returns an iterable of at least n_plots matplotlib axes. If axes are given, those axes are returned (and repeated if there are not enough of them). If no axes are given, new axes on a grid are created using given parameters.

import trueq as tq
import matplotlib.pyplot as plt

circuits = tq.make_srb([0, 1, 2, 3], [4, 100])

# plot all decays on one axis
fig = plt.figure()
circuits.plot.raw(axes=plt.gca())

# plot all decays on two axes in a particular order
fig = plt.figure(figsize=(12, 4))
ax1, ax2 = plt.subplot("121"), plt.subplot("122")
circuits.plot.raw(axes=[ax1, ax2, ax2, ax1])

Parameters
• n_plots (int) – How many subfigures there will nominally be.

• axes (Iterable) – An iterable of existing axes. If none are provided, new axes are created. Note that axis instances can be repeated in this list if you want to force the combination of subfigures that would normally be distinct.

• n_columns (int) – If new axes are made, how many columns in the grid to use.

• axis_size (tuple) – A shape tuple to use to determine the size of each subfigure.

• gs_options (dict) – Options to pass to matplotlib.gridspec.GridSpec.

Returns

A tuple (axiter, finalize) where axiter is an iterator over axes, and finalize is a method to be called before the plotting function returns (this does file saving and layout tightening).

Return type

tuple

static savefig(filename, fig=None)

Saves the given or current figure to disk as the given filename. Saves as a PNG if no filename is given.

Parameters
• filename (str) – The filename to save as.

• fig (matplotlib.Figure | None) – A matplotlib figure to save, or None to use the current figure.

class trueq.visualization.plotters.PlottingSuite(parent)

A collection of Plotters, which are accessible as methods of instances of this class. Which plotters are present in the namespace is dependent on the parent object passed in at initialization. For example, a plotting function to do with XRB will only be present if the given parent has data for XRB.

Parameters

parent (ParameterCollection | CircuitCollection) – A circuit collection or parameter collection to store plotters for.

class trueq.visualization.plotters.RawPlot

Very generic plotter that overlays exponential fits onto lightly processed data.

Note

This class typically should not be invoked directly by users; the main plotting method is exposed dynamically by the attributes trueq.CircuitCollection.plot and trueq.parameters.ParameterCollection.plot if relevant.

static applies_to_circuits(keys)

A fast check that determines whether these circuits are broadly compatible with this plotting function. The plotting function is still allowed to raise (and indeed, it is encouraged) if it sees something it doesn’t like; this method is an a priori check that determines which plotters are automatically recommended to users.

This method should usually check to see if at least some data is present.

Parameters

keys – Keys of the trueq.parameters.CircuitCollection.

Return type

bool

static applies_to_parameters(keys)

A fast check that determines whether these parameters are broadly compatible with this plotting function. The plotting function is still allowed to raise (and indeed, it is encouraged) if it sees something it doesn’t like; this method is an a priori check that determines which plotters are automatically recommended to users.

Parameters

keys – Keys of the trueq.parameters.ParameterCollection.

Return type

bool

static plot(fit, labels=None, n_columns=3, axes=None, filename=None, **filter)

Plots a summary of raw data for each applicable circuit collection. Also fits all applicable data to exponential curves and displays this too.

These plots are diagnostic tools which can quickly tell you if your sequence lengths are way off, or if there has been some systematic error in data entry or circuit conversion to your format.

Parameters
• fit (ParameterCollection | CircuitCollection) – A collection of circuits or their fit.

• labels (Iterable) – A list of labels (or list of lists of labels) specifying which qubit subset (or list of qubit subsets) to marginalize over.

• axes (Iterable) – An iterable of existing axes. If none are provided, new axes are created. Note that axis instances can be repeated in this list if you want to force the combination of subfigures that would normally be distinct, see axes() for an example.

• n_columns (int) – If new axes are made, how many columns in the grid to use.

• filename (str) – An optional filename to save the file as. The extension determines the filetype; common choices are “.png”, “.pdf”, and “.svg”. If no extension is given, PNG is chosen.

• filter – A filter to apply to the datastructure, for example, circuits.fit(protocol="SRB").

class trueq.visualization.plotters.ComparisonPlot

Very generic plotter that compares like parameters across subsystems of a multi-system register. One subplot is made per parameter.

Note

This class typically should not be invoked directly by users; the main plotting method is exposed dynamically by the attributes trueq.CircuitCollection.plot and trueq.parameters.ParameterCollection.plot if relevant.

static applies_to_circuits(keys)

A fast check that determines whether these circuits are broadly compatible with this plotting function. The plotting function is still allowed to raise (and indeed, it is encouraged) if it sees something it doesn’t like; this method is an a priori check that determines which plotters are automatically recommended to users.

This method should usually check to see if at least some data is present.

Parameters

keys – Keys of the trueq.parameters.CircuitCollection.

Return type

bool

static applies_to_parameters(keys)

A fast check that determines whether these parameters are broadly compatible with this plotting function. The plotting function is still allowed to raise (and indeed, it is encouraged) if it sees something it doesn’t like; this method is an a priori check that determines which plotters are automatically recommended to users.

Parameters

keys – Keys of the trueq.parameters.ParameterCollection.

Return type

bool

static plot(fit, params=None, labels=None, axes=None, filename=None, **filter)

For each parameter (across all protocols) found in the circuit’s fit, adds a subplot that compares these quantities across subregisters. By default, the comparison is done over all single qubits of the given circuit collection.

>>> circuits.plot.comparison(["r", "A"])

Parameters
• fit (CircuitCollection) – A collection of circuits or their fit.

• labels (Iterable) – A list of labels (or list of lists of labels) specifying which qubit subset (or list of qubit subsets) to marginalize over.

• axes (Iterable) – An iterable of existing axes. If none are provided, new axes are created. Note that axis instances can be repeated in this list if you want to force the combination of subfigures that would normally be distinct, see axes() for an example.

• filename (str) – An optional filename to save the file as. The extension determines the filetype; common choices are “.png”, “.pdf”, and “.svg”. If no extension is given, PNG is chosen.

• filter – A filter to apply to the datastructure, for example, circuits.fit(protocol="SRB").

Params params

A list of strings, specifying which parameter names should be included in the plot.

class trueq.visualization.plotters.InfidelityCompPlot

Plots the ‘r’ parameter measured by SRB and the ‘ru’ parameter measured by XRB.

Note

This class typically should not be invoked directly by users; the main plotting method is exposed dynamically by the attributes trueq.CircuitCollection.plot and trueq.parameters.ParameterCollection.plot if relevant.

static applies_to_circuits(keys)

A fast check that determines whether these circuits are broadly compatible with this plotting function. The plotting function is still allowed to raise (and indeed, it is encouraged) if it sees something it doesn’t like; this method is an a priori check that determines which plotters are automatically recommended to users.

This method should usually check to see if at least some data is present.

Parameters

keys – Keys of the trueq.parameters.CircuitCollection.

Return type

bool

static applies_to_parameters(keys)

A fast check that determines whether these parameters are broadly compatible with this plotting function. The plotting function is still allowed to raise (and indeed, it is encouraged) if it sees something it doesn’t like; this method is an a priori check that determines which plotters are automatically recommended to users.

Parameters

keys – Keys of the trueq.parameters.ParameterCollection.

Return type

bool

static plot(fit, axes=None, filename=None)

Shows all infidelities as measured by SRB. If XRB data is also present, the quantity $$r_u$$ defined by

$0\leq r_u =\frac{d-1}{d}(1- \sqrt{u}) \leq r$

is also shown. Here, $$0\leq r$$ is the infidelity as measured by SRB, and $$0\leq u\leq 1$$ is the unitarity.

Parameters
• fit (ParameterCollection | CircuitCollection) – A collection of circuits or their fit.

• axes (Iterable) – An iterable of existing axes. If none are provided, new axes are created. Note that axis instances can be repeated in this list if you want to force the combination of subfigures that would normally be distinct, see axes() for an example.

• filename (str) – An optional filename to save the file as. The extension determines the filetype; common choices are “.png”, “.pdf”, and “.svg”. If no extension is given, PNG is chosen.

class trueq.visualization.plotters.IncoherencePlot

Plots the ‘inc’ parameter measured by SRB and XRB.

Note

This class typically should not be invoked directly by users; the main plotting method is exposed dynamically by the attributes trueq.CircuitCollection.plot and trueq.parameters.ParameterCollection.plot if relevant.

static applies_to_circuits(keys)

A fast check that determines whether these circuits are broadly compatible with this plotting function. The plotting function is still allowed to raise (and indeed, it is encouraged) if it sees something it doesn’t like; this method is an a priori check that determines which plotters are automatically recommended to users.

This method should usually check to see if at least some data is present.

Parameters

keys – Keys of the trueq.parameters.CircuitCollection.

Return type

bool

static applies_to_parameters(keys)

A fast check that determines whether these parameters are broadly compatible with this plotting function. The plotting function is still allowed to raise (and indeed, it is encouraged) if it sees something it doesn’t like; this method is an a priori check that determines which plotters are automatically recommended to users.

Parameters

keys – Keys of the trueq.parameters.ParameterCollection.

Return type

bool

static plot(fit, axes=None, filename=None)

Plots the fraction of noise that is incoherent. This is don by comparing the infidelity, as measured by SRB, to the unitarity, as measured by XRB. The unitarity is scaled such that its upper bound is the infidelity, according to the formula

$0\leq r_u =\frac{d-1}{d}(1- \sqrt{u}) \leq r$

where $$0\leq r$$ is the infidelity, and $$0\leq u\leq 1$$ is the unitarity. This plotter shows the ratio, $$\text{inc}=r_u/r$$, which is 1 when the noise is completely incoherent, and 0 when the noise is completely unitary.

Parameters
• fit (ParameterCollection | CircuitCollection) – A collection of circuits or their fit.

• axes (Iterable) – An iterable of existing axes. If none are provided, new axes are created. Note that axis instances can be repeated in this list if you want to force the combination of subfigures that would normally be distinct, see axes() for an example.

• filename (str) – An optional filename to save the file as. The extension determines the filetype; common choices are “.png”, “.pdf”, and “.svg”. If no extension is given, PNG is chosen.

class trueq.visualization.plotters.IRBCompPlot

Plots parameters fit from IRB.

Note

This class typically should not be invoked directly by users; the main plotting method is exposed dynamically by the attributes trueq.CircuitCollection.plot and trueq.parameters.ParameterCollection.plot if relevant.

static applies_to_circuits(keys)

A fast check that determines whether these circuits are broadly compatible with this plotting function. The plotting function is still allowed to raise (and indeed, it is encouraged) if it sees something it doesn’t like; this method is an a priori check that determines which plotters are automatically recommended to users.

This method should usually check to see if at least some data is present.

Parameters

keys – Keys of the trueq.parameters.CircuitCollection.

Return type

bool

static applies_to_parameters(keys)

A fast check that determines whether these parameters are broadly compatible with this plotting function. The plotting function is still allowed to raise (and indeed, it is encouraged) if it sees something it doesn’t like; this method is an a priori check that determines which plotters are automatically recommended to users.

Parameters

keys – Keys of the trueq.parameters.ParameterCollection.

Return type

bool

static plot(fit, axes=None, filename=None)

Plots data from an IRB experiment. Relevant information from associated SRB and XRB experiments is also shown, see the IRB guide for details.

Parameters
• fit (ParameterCollection | CircuitCollection) – A collection of circuits or their fit.

• axes (Iterable) – An iterable of existing axes. If none are provided, new axes are created. Note that axis instances can be repeated in this list if you want to force the combination of subfigures that would normally be distinct, see axes() for an example.

• filename (str) – An optional filename to save the file as. The extension determines the filetype; common choices are “.png”, “.pdf”, and “.svg”. If no extension is given, PNG is chosen.

class trueq.visualization.plotters.NRBars

Plots Noise reconstruction data as a series of bar plots.

Note

This class typically should not be invoked directly by users; the main plotting method is exposed dynamically by the attributes trueq.CircuitCollection.plot and trueq.parameters.ParameterCollection.plot if relevant.

static plot(fit, labels=None, n_annotate=4, cutoff=-1, ignore_errors=False, common_ylim=False, axes=None, n_columns=2, filename=None)

Plots the weights of Pauli errors in a Pauli noise map as a bar plot by sorting first by their weight (number of non-identity terms), and then by their magnitude.

Parameters
• fit (ParameterCollection | CircuitCollection) – A collection of circuits or their fit.

• labels (Iterable) – A list of labels (or list of lists of labels) specifying which qubit subset (or list of qubit subsets) to marginalize over.

• n_annotate (int) – The number of histogram bars to annotate with a Pauli string in each weight block.

• cutoff (float) – The minimum value of a Pauli probability to show a histogram bar for.

• ignore_errors (bool) – Whether to plot error bars.

• common_ylim (bool) – Whether all subplots should contain the same upper y-limit.

• axes (Iterable) – An iterable of existing axes. If none are provided, new axes are created. Note that axis instances can be repeated in this list if you want to force the combination of subfigures that would normally be distinct, see axes() for an example.

• n_columns (int) – If new axes are made, how many columns in the grid to use.

• filename (str) – An optional filename to save the file as. The extension determines the filetype; common choices are “.png”, “.pdf”, and “.svg”. If no extension is given, PNG is chosen.

class trueq.visualization.plotters.NRCmap

Plots Noise reconstruction data as a series of color maps.

Note

This class typically should not be invoked directly by users; the main plotting method is exposed dynamically by the attributes trueq.CircuitCollection.plot and trueq.parameters.ParameterCollection.plot if relevant.

static plot(fit, n_qubits=2, labels=None, single_scale=False, axes=None, n_columns=1, filename=None)

Plots the weights of Pauli errors in a Pauli noise map as a color map, where each column shows the marginal distribution of some subset of qubits.

Parameters
• fit (ParameterCollection | CircuitCollection) – A collection of circuits or their fit.

• n_qubits (int) – The number of qubits in each marginalized subset. A value of 1 will show single qubit marginal errors, a value of 2 will show two-qubit marginal errors, and so on.

• labels (Iterable) – A list of labels (or list of lists of labels) specifying which qubit subset (or list of qubit subsets) to marginalize over.

• single_scale (bool) – Whether all plots should use the same color scale.

• axes (Iterable) – An iterable of existing axes. If none are provided, new axes are created. Note that axis instances can be repeated in this list if you want to force the combination of subfigures that would normally be distinct, see axes() for an example.

• n_columns (int) – If new axes are made, how many columns in the grid to use.

• filename (str) – An optional filename to save the file as. The extension determines the filetype; common choices are “.png”, “.pdf”, and “.svg”. If no extension is given, PNG is chosen.