Q-CTRL Visualizer Python package¶

Top-level package for the Q-CTRL Visualizer.

The public API of this package consists only of the objects exposed through this top-level package. Direct access to sub-modules is not officially supported, so may be affected by backwards-incompatible changes without notice.

qctrlvisualizer.get_qctrl_style() → Dict[str, Any]¶

Returns a dictionary representing the Q-CTRL styling in Matplotlib format.

The returned dictionary is suitable for passing to Matplotlib functions such as matplotlib.style.use or matplotlib.style.context.

Returns: The dictionary representing the Q-CTRL style.
Return type: dict

qctrlvisualizer.plot_controls(figure, controls, polar=True, smooth=False)¶

Creates a plot of the specified controls.

Parameters

figure (matplotlib.figure.Figure) – The matplotlib Figure in which the plots should be placed. The dimensions of the Figure will be overridden by this method.
controls (dict) –
The dictionary of controls to plot. The keys should be the names of the controls, and the values the list of segments representing the pulse of that control. Each such segment must be a dictionary with ‘value’ and ‘duration’ keys, giving the value (in Hertz, possibly complex) and duration (in seconds) of that segment of the pulse. For example, the following would be a valid controls input:
```
{
 'Clock': [
     {'duration': 1.0, 'value': -0.5},
     {'duration': 1.0, 'value': 0.5},
     {'duration': 2.0, 'value': -1.5},
 ],
 'Microwave': [
     {'duration': 0.5, 'value': 0.5 + 1.5j},
     {'duration': 1.0, 'value': 0.2 - 0.3j},
 ],
}
```
polar (bool, optional) – The mode of the plot when the values appear to be complex numbers. Plot magnitude and angle in two figures if set to True, otherwise plot I and Q in two figures. Defaults to True.
smooth (bool, optional) – Whether to plot the controls as samples joined by straight lines, rather than as piecewise-constant segments. Defaults to False.

Raises

ValueError – If any of the input parameters are invalid.

qctrlvisualizer.plot_discriminator(discriminator: Any, axs=None, show_boundary: bool = False, show_fitting_data: bool = True, flag_misclassified: bool = False, qubits_to_plot: List[int] = None, title: bool = True)¶

Creates plots for a specified discriminator.

Parameters

discriminator (Union[List[IQDiscriminationFitter], IQDiscriminationFitter]) – A discriminator or list of discriminators
axs (np.ndarray) – matplotlib axes (default: {None})
show_boundary (bool) – Show decision boundary (default: {False})
show_fitting_data (bool) – Show/plot data used to fit discriminator (default: {True})
flag_misclassified (bool) – Plot misclassified points (default: {False})
qubits_to_plot (List[int]) – Which qubits to include (default: {None})
title (bool) – Include title in plots (default: {True})

Returns

the axes object used for the plot as well as the figure handle. The figure handle returned is None iff axs is passed.

Return type

Union[List[axes], axes], figure)

Raises

ValueError – If qubit is not in the qubit_mask
ValueError – If not enough axes instances are passed. Requires 1 per qubit.
ValueError – If show_boundary is True for multi-qubit cases.
ValueError – If expected state lables cannot be cast to floats.

qctrlvisualizer.plot_filter_functions(figure, filter_functions)¶

Creates a plot of the specified filter functions.

Parameters

figure (matplotlib.figure.Figure) – The matplotlib Figure in which the plots should be placed. The dimensions of the Figure will be overridden by this method, but may be subsequently modified by the caller if desired.
filter_functions (dict) –
The dictionary of filter functions to plot. The keys should be the names of the filter functions, and the values the list of samples representing that filter function. Each such sample must be a dictionary with ‘frequency’, ‘inverse_power’, and ‘inverse_power_uncertainty’ (optional) keys, giving the frequency (in Hertz) at which the sample was taken, the inverse power (in seconds) of the filter function at the sample, and the optional uncertainty of that inverse power (in seconds).

The key ‘inverse_power_precision’ can be used instead of ‘inverse_power_uncertainty’. If both are provided then the value corresponding to ‘inverse_power_uncertainty’ is used.

If the uncertainty of an inverse power is provided, it must be non-negative.

For example, the following would be a valid filter_functions input:
```
{
 'Primitive': [
     {'frequency': 0.0, 'inverse_power': 15.},
     {'frequency': 1.0, 'inverse_power': 12.},
     {'frequency': 2.0,
      'inverse_power': 3.,
      'inverse_power_uncertainty' 0.2},
 ],
 'CORPSE': [
     {'frequency': 0.0, 'inverse_power': 10.},
     {'frequency': 0.5, 'inverse_power': 8.5},
     {'frequency': 1.0,
      'inverse_power': 5.,
      'inverse_power_uncertainty' 0.1},
     {'frequency': 1.5, 'inverse_power': 2.5},
 ],
}
```

Raises

ValueError – If any of the input parameters are invalid.

qctrlvisualizer.plot_sequences(figure, seq)¶

Creates plot of dynamical decoupling sequences.

Parameters

figure (matplotlib.figure.Figure) – The matplotlib Figure in which the plots should be placed. The dimensions of the Figure will be overridden by this method.
seq (dict) – The dictionary of controls to plot. Works the same as the dictionary for plot_controls, but takes ‘offset’ instead of ‘duration’ and ‘rotation’ instead of ‘value’. Rotations can be around any axis in the XY plane. Information about this axis is encoded in the complex argument of the rotation. For example, a pi X-rotation is represented by the complex number 3.14+0.j, whereas a pi Y-rotation is 0.+3.14j. The argument of the complex number is plotted separately as the azimuthal angle.

qctrlvisualizer.plot_smooth_controls(figure, controls, polar=True)¶

Creates a plot of the specified smooth controls.

Parameters

figure (matplotlib.figure.Figure) – The matplotlib Figure in which the plots should be placed. The dimensions of the Figure will be overridden by this method.
controls (dict) –
The dictionary of controls to plot. The keys should be the names of the controls, and the values the list of samples representing the pulse of that control. Each such sample must be a dictionary with ‘value’ and ‘time’ keys, giving the value (in Hertz, possibly complex) and time (in seconds) of that sample of the pulse. The times must be in increasing order. For example, the following would be a valid controls input:
```
{
 'Clock': [
     {'time': 0.0, 'value': -0.5},
     {'time': 1.0, 'value': 0.5},
     {'time': 3.0, 'value': -1.5},
 ],
 'Microwave': [
     {'time': 0.5, 'value': 0.5 + 1.5j},
     {'time': 2.0, 'value': 0.2 - 0.3j},
 ],
}
```
polar (bool, optional) – The mode of the plot when the values appear to be complex numbers. Plot magnitude and angle in two figures if set to True, otherwise plot I and Q in two figures. Defaults to True.

Raises

ValueError – If any of the input parameters are invalid.

qctrlvisualizer.plot_xdata(discriminator: Any, axs: numpy.ndarray, results: Any)¶

Add the relevant IQ data from the Result, or list of results, to the given axes as a scatter plot.

Parameters

discriminator (BaseIQDiscriminator) – An arbitrary Q-CTRL discriminator that follows the defined interface and has fit and discriminate methods.
axs (Union[np.ndarray, axes]) – The axes to use for the plot. If the number of axis instances provided is less than the number of qubits then only the data for the first len(axs) qubits will be plotted.
results (Union[Result, List[Result]]) – The discriminators get_xdata will be used to retrieve the x data from the Result or list of Results.

Raises

ValueError – Not enought axes are provided. Requires one per qubit discriminated.