# Visualization

Qiskit visualizes circuits, sampled counts, ideal states, and backend layouts. Plotting is analysis support, not a substitute for numerical validation.

## Install Plotting Dependencies

```bash
uv pip install "qiskit[visualization]==2.5.0"
```

The text circuit drawer works with the core package. Matplotlib, Pillow, LaTeX helpers, and notebook integrations depend on the selected output.

## Circuit Drawers

### Text

```python
from qiskit import QuantumCircuit

circuit = QuantumCircuit(3)
circuit.h(0)
circuit.cx(0, 1)
circuit.cx(1, 2)

print(circuit.draw(output="text", fold=-1))
```

Text output is the most reliable choice for logs, tests, and terminal-only environments.

### Matplotlib

```python
figure = circuit.draw(
    output="mpl",
    style="iqp",
    fold=40,
    idle_wires=False,
)
figure.savefig(
    "circuit.svg",
    bbox_inches="tight",
)
```

Keep the returned `Figure`; calling `savefig()` on an unrelated current figure can save the wrong plot.

Useful options:

```python
circuit.draw(
    output="mpl",
    reverse_bits=False,
    initial_state=True,
    plot_barriers=True,
    fold=30,
)
```

`reverse_bits` changes display order, not circuit semantics.

### LaTeX

```python
latex_image = circuit.draw(output="latex")
latex_source = circuit.draw(output="latex_source")
```

LaTeX rendering requires an appropriate local TeX installation. Prefer SVG from the Matplotlib drawer when a full TeX toolchain is unavailable.

## Custom Circuit Styles

```python
style = {
    "displaycolor": {
        "h": ("#648fff", "#ffffff"),
        "cx": ("#785ef0", "#ffffff"),
        "measure": ("#dc267f", "#ffffff"),
    },
    "fontsize": 11,
    "subfontsize": 8,
}

figure = circuit.draw(output="mpl", style=style)
```

Built-in style names can change. `iqp` and `bw` are useful starting points in Qiskit 2.5.

Use color plus labels or structure; do not make color the only way to distinguish operations.

## Count Histograms

```python
from qiskit.visualization import plot_histogram

figure = plot_histogram(
    counts,
    sort="value_desc",
    bar_labels=True,
    title="Bell-state samples",
)
figure.savefig(
    "counts.png",
    dpi=300,
    bbox_inches="tight",
)
```

Compare datasets:

```python
figure = plot_histogram(
    [ideal_counts, noisy_counts, hardware_counts],
    legend=["ideal", "noise model", "hardware"],
    figsize=(10, 5),
)
```

Normalize explicitly when comparing runs with different shot counts:

```python
def normalize_counts(counts):
    total = sum(counts.values())
    return {
        bitstring: count / total
        for bitstring, count in counts.items()
    }
```

Label whether bars are counts, frequencies, or quasi-probabilities. Sampler V2 returns shot data, not V1 quasi-distributions.

## Statevector and Density-Matrix Plots

Construct ideal states only for circuits without measurements, resets, or unsupported classical control:

```python
from qiskit.quantum_info import DensityMatrix, Statevector

state = Statevector.from_instruction(unitary_circuit)
density_matrix = DensityMatrix(state)
```

Available plotters:

```python
from qiskit.visualization import (
    plot_bloch_multivector,
    plot_state_city,
    plot_state_hinton,
    plot_state_paulivec,
    plot_state_qsphere,
)

plot_bloch_multivector(state)
plot_state_city(density_matrix)
plot_state_hinton(density_matrix)
plot_state_paulivec(density_matrix)
plot_state_qsphere(state)
```

Dense state memory grows exponentially:

- statevector: \(2^n\) complex amplitudes,
- density matrix: \(4^n\) complex entries.

Do not construct a dense state solely to make a plot when the system size is not tractable.

## Single Bloch Vector

```python
from qiskit.quantum_info import Statevector
from qiskit.visualization import plot_bloch_vector

state = Statevector.from_label("+")
figure = plot_bloch_vector(
    state.to_bloch(),
    title="|+>",
)
```

A reduced qubit from an entangled state may be mixed and appear inside the Bloch sphere. A per-qubit Bloch view does not show multipartite entanglement.

## Backend Topology and Errors

```python
from qiskit.visualization import plot_error_map, plot_gate_map

gate_map_figure = plot_gate_map(backend)
error_map_figure = plot_error_map(backend)
```

These plots reflect the backend snapshot exposed by the provider. Record the retrieval time and backend.

Plot a compiled circuit's physical placement:

```python
from qiskit.visualization import plot_circuit_layout

layout_figure = plot_circuit_layout(
    isa_circuit,
    backend,
)
```

Use `isa_circuit.layout` for program logic. A plot is for inspection, not a machine-readable mapping.

## Before-and-After Circuit Comparison

```python
import matplotlib.pyplot as plt

figure, axes = plt.subplots(
    nrows=2,
    figsize=(14, 7),
    constrained_layout=True,
)

circuit.draw(
    output="mpl",
    ax=axes[0],
    fold=-1,
)
axes[0].set_title("Logical circuit")

isa_circuit.draw(
    output="mpl",
    ax=axes[1],
    fold=-1,
)
axes[1].set_title(
    f"ISA circuit on {backend.name}"
)

figure.savefig(
    "logical-vs-isa.svg",
    bbox_inches="tight",
)
```

For very wide circuits, save separate figures rather than shrinking labels until unreadable.

## Parameter and Convergence Plots

Qiskit returns numerical arrays; use Matplotlib directly for scientific plots:

```python
import matplotlib.pyplot as plt

figure, axis = plt.subplots()
axis.plot(iterations, objective_values, marker="o")
axis.set(
    xlabel="Objective evaluation",
    ylabel="Energy (hartree)",
    title="VQE convergence",
)
axis.grid(alpha=0.25)
figure.savefig(
    "vqe-convergence.svg",
    bbox_inches="tight",
)
```

Include uncertainty bars when repeated runs or estimator standard deviations are available:

```python
axis.errorbar(
    parameter_values,
    expectation_values,
    yerr=standard_deviations,
    fmt="o-",
    capsize=3,
)
```

Do not interpret optimizer history as statistically independent samples.

## Publication Output

Prefer vector formats for circuit diagrams and line art:

```python
figure.savefig(
    "figure.svg",
    bbox_inches="tight",
    metadata={"Creator": "Qiskit 2.5 workflow"},
)
figure.savefig(
    "figure.pdf",
    bbox_inches="tight",
)
```

For raster output:

```python
figure.savefig(
    "figure.png",
    dpi=300,
    bbox_inches="tight",
)
```

Include in the caption:

- logical or transpiled status,
- backend if transpiled,
- measurement basis,
- shot count or precision,
- mitigation configuration,
- whether data are ideal, modeled, or hardware-derived.

## Removed Visualization Patterns

Do not use:

- `qiskit.tools.jupyter.QuantumCircuitComposer` from old examples,
- pulse schedule drawings based on `qiskit.pulse`,
- nonexistent `plot_state_density` helpers,
- V1 quasi-distribution examples presented as Sampler V2 output.

`qiskit.pulse` was removed in Qiskit 2.0. Use current fractional-gate or Qiskit Dynamics documentation for control-model research.

## Troubleshooting

### Matplotlib output is unavailable

Install the pinned visualization extra and verify the active interpreter:

```bash
uv pip install "qiskit[visualization]==2.5.0"
python -c "import sys, matplotlib; print(sys.executable, matplotlib.__version__)"
```

### Notebook displays nothing

Return the `Figure` as the final expression or call:

```python
import matplotlib.pyplot as plt

plt.show()
```

### LaTeX drawer fails

Use `output="mpl"` or `output="text"` unless a complete TeX toolchain is intentionally installed.

### Count labels look reversed

Qiskit prints count strings with the highest-index classical bit on the left. Convert explicitly before mapping characters to qubit-indexed variables.

### Backend plot fails

Confirm the object is a compatible `BackendV2` and that the visualization extra is installed. Some third-party backends do not provide every field expected by IBM-oriented plotting functions.

### Plot is too large

- set `fold`,
- hide idle wires,
- split logical modules,
- export to SVG,
- include structural metrics in text rather than forcing every instruction into one figure.