Qx.Draw (Qx - Quantum Computing Simulator v0.10.1)

Visualization for quantum simulation results.

Utility module: reached from Qx.* in normal use — every function here has a Qx.draw_* facade delegate (Qx.draw/2 fronts plot/2).

Every function returns one static artifact type in every environment (spec/api-design-principles.md §6):

Function	Returns	Livebook renders via
`plot/2`	`VegaLite.t()`	kino_vega_lite
`counts/2`	`VegaLite.t()`	kino_vega_lite
`histogram/2`	`VegaLite.t()`	kino_vega_lite
`bloch/2`	`Qx.Draw.Image`	`Kino.Render`
`circuit/2`	`Qx.Draw.Image`	`Kino.Render`
`state_table/2`	`Qx.Draw.StateTable`	`Kino.Render`

Nothing here requires Livebook. In a standalone application the VegaLite specs feed any Vega renderer, and the Image/StateTable artifacts expose their raw SVG/text/markdown as fields — write them to files, serve them, or print them.

The three VegaLite-returning functions need the optional :vega_lite dependency and raise Qx.MissingDependencyError naming the fix when it's absent. The SVG and table artifacts have no dependency at all.

Summary

Functions

bloch(qubit, options \\ [])

Visualizes a single qubit state on the Bloch sphere.

circuit(circuit, title \\ nil)

Draws a quantum circuit diagram.

counts(result, options \\ [])

Plots measurement counts as a bar chart.

histogram(probabilities, options \\ [])

Creates a histogram from a raw probability tensor.

plot(result, options \\ [])

Plots the probability distribution from a simulation result.

state_table(register_or_state, options \\ [])

Displays a quantum state as a formatted table.

Functions

bloch(qubit, options \\ [])

Visualizes a single qubit state on the Bloch sphere.

Parameters

qubit - Single qubit state tensor (2-element c64 tensor)
options - Optional plotting parameters (default: [])

Options

:title - Plot title (default: "Bloch Sphere")
:size - Sphere size (default: 400)

Returns

A Qx.Draw.Image artifact carrying the SVG. Livebook renders it inline; standalone applications read image.svg.

Examples

state = Qx.create_circuit(1) |> Qx.h(0) |> Qx.get_state()
image = Qx.Draw.bloch(state, title: "Plus state")
File.write!("bloch.svg", image.svg)

circuit(circuit, title \\ nil)

Draws a quantum circuit diagram.

Parameters

circuit - Qx.QuantumCircuit struct to visualize
title - Optional circuit title (default: nil)

Returns

A Qx.Draw.Image artifact carrying the SVG diagram (IEEE notation). Livebook renders it inline; standalone applications read image.svg.

Examples

qc = Qx.create_circuit(2, 2)
|> Qx.h(0)
|> Qx.cx(0, 1)
|> Qx.measure(0, 0)
|> Qx.measure(1, 1)

image = Qx.Draw.circuit(qc, "Bell State Circuit")
File.write!("bell.svg", image.svg)

counts(result, options \\ [])

Plots measurement counts as a bar chart.

Works with results from both local simulation (Qx.run/2) and remote hardware execution (Qx.Hardware.run/3).

Parameters

result - Simulation result containing measurement counts
options - Optional plotting parameters (default: [])

Options

:title - Plot title (default: "Measurement Counts")
:width - Plot width (default: 400)
:height - Plot height (default: 300)

Returns

A VegaLite.t() chart specification.

Raises

Qx.MissingDependencyError - if the optional :vega_lite dependency is not available

Examples

qc = Qx.create_circuit(2, 2)
|> Qx.h(0) |> Qx.cx(0, 1)
|> Qx.measure(0, 0) |> Qx.measure(1, 1)
result = Qx.run(qc)
Qx.Draw.counts(result)

histogram(probabilities, options \\ [])

Creates a histogram from a raw probability tensor.

Parameters

probabilities - Nx tensor of probabilities (must sum to 1.0)
options - Optional plotting parameters (default: [])

Options

:title - Plot title (default: "Probability Histogram")
:width - Plot width (default: 400)
:height - Plot height (default: 300)

Returns

A VegaLite.t() chart specification.

Raises

Qx.MissingDependencyError - if the optional :vega_lite dependency is not available

Examples

qc = Qx.create_circuit(2) |> Qx.h(0) |> Qx.h(1)
probs = Qx.get_probabilities(qc)
Qx.Draw.histogram(probs)

plot(result, options \\ [])

Plots the probability distribution from a simulation result.

Parameters

result - Simulation result map containing probabilities
options - Optional plotting parameters (default: [])

Options

:title - Plot title (default: "Quantum State Probabilities")
:width - Plot width (default: 400)
:height - Plot height (default: 300)

Returns

A VegaLite.t() chart specification.

Raises

Qx.MissingDependencyError - if the optional :vega_lite dependency is not available

Examples

qc = Qx.create_circuit(2) |> Qx.h(0) |> Qx.cx(0, 1)
result = Qx.run(qc)
Qx.Draw.plot(result, title: "Bell State")

state_table(register_or_state, options \\ [])

Displays a quantum state as a formatted table.

Shows basis states with their complex amplitudes and probabilities.

Parameters

register_or_state - An Nx.Tensor state vector (an internal calc-engine register struct also works)
options - Optional formatting parameters (default: [])

Options

:precision - Number of decimal places (default: 3)
:hide_zeros - Hide states with near-zero probability (default: false)

Returns

A Qx.Draw.StateTable artifact with :text, :markdown, and :html renderings as fields. Livebook renders the markdown; to_string/1 gives the text table.

Examples

state = Qx.create_circuit(2) |> Qx.h(0) |> Qx.cx(0, 1) |> Qx.get_state()
table = Qx.Draw.state_table(state)
table.text
# => "Basis State | Amplitude ..."