draw_mpl

`eigenkit.core.draw_mpl`

Matplotlib drawer for CircuitSpec, which does not depend on the provider.

It draws a circuit diagram: gates as boxes with labels, controls as filled dots, the targets of controlled-NOT (CNOT) and multi-controlled X (MCX) gates as ⊕, SWAP gates as crossed wires and, optionally, measurement meters at the end of the wires that the observables act on.

Like the text drawer in draw.py, the picture is built from the CircuitSpec intermediate representation (IR) and the observables of the circuit, never from the compiled backend object. The drawing is therefore the same whichever provider ran the circuit. It uses draw._layout to place the gates in columns, so the matplotlib and the text drawings stay consistent.

matplotlib is an optional dependency, and it is imported only when draw_mpl is called. A core installation does not install it. Install it with eigenkit[viz].

The styles come in light and dark pairs, selected by name:

"default": black on white.
"eigen": the brand palette. Each gate is coloured by its kind: violet for rotations, cyan for H and the block gates, and blue for the meters.
"roles": the outline of each gate is coloured by its role (encoding, trainable or fixed), with a legend.

Each of them has a "-dark" variant ("default-dark", "eigen-dark", "roles-dark") for dark backgrounds. These variants have a transparent canvas and light strokes, so they work on any dark shade. There is also "eigen-universal": a single transparent image of filled gate chips, which can be read on both light and dark pages.

The styles are plain dictionaries in _STYLES, where a new theme can be added. The wires are drawn only in the gaps between gates, so no wire shows through the label of a gate.

`draw_mpl(spec, *, observables=None, decimals=3, show_params=True, show_measurements=True, fontsize=_DEFAULT_FONTSIZE, style='default', legend=True, ax=None)`

Draw spec as a matplotlib circuit diagram.

Parameters:

Name	Type	Description	Default
`spec`	`CircuitSpec`	The circuit to draw.	required
`observables`	`Optional[Sequence[Observable]]`	The observables whose Pauli support sets the wires that end with a measurement meter. Pass `None`, or `show_measurements=False`, to draw no meters. Default: `None`.	`None`
`decimals`	`int`	The number of significant digits of constant gate angles. Default: `3`.	`3`
`show_params`	`bool`	If `True`, the angle of each parametrised gate is written in its box (for example `RX` above `w_0`). Default: `True`.	`True`
`show_measurements`	`bool`	If `True` and `observables` is given, a meter is drawn on each measured wire. Default: `True`.	`True`
`fontsize`	`float`	The font size of the gate names. The angle labels are smaller. Default: `13.0`.	`_DEFAULT_FONTSIZE`
`style`	`str`	The name of a style: `"default"` (black on white), `"eigen"` (the brand palette, where gates are coloured by kind: rotations, `H` and block gates, and meters), `"roles"` (gate outlines coloured by role: encoding, trainable or fixed) or `"eigen-universal"` (one image for light and dark pages). Each of them except the last has a `"-dark"` variant (for example `"eigen-dark"`) for dark backgrounds. A style dictionary can also be passed. Default: `"default"`.	`'default'`
`legend`	`bool`	If `True`, the `"roles"` styles draw a legend that maps each colour to its role. Styles that do not colour gates by role ignore it. Default: `True`.	`True`
`ax`	`'Optional[Axes]'`	An existing matplotlib `Axes` to draw into. If it is not given, a new figure and axes are created, with a size that fits the circuit. The `background` of a style is applied only to a figure that `draw_mpl` creates. When you pass your own `ax`, set the face colour of its figure yourself: the `"-dark"` styles draw in light colours and need a dark background to be readable. Default: `None`.	`None`

Returns:

Type	Description
`'tuple[Figure, Axes]'`	The `(figure, axes)` pair. Save the figure with `figure.savefig(...)`. A figure that `draw_mpl` creates is not registered with pyplot, so `plt.show()` does not display it.

`measured_qubits(observables)`

Return every qubit that any of observables acts on (their Pauli support).

Parameters:

Name	Type	Description	Default
`observables`	`Sequence[Observable]`	The observables to measure.	required

Returns:

Type	Description
`set[int]`	The index of every qubit that the observables act on.