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

View Source

Visualization functions for quantum simulation results.

This module provides a clean API facade for all visualization capabilities, delegating to specialized sub-modules:

Visualization Types

Probability Plots

  • plot/2 - Plot probability distribution from simulation results
  • histogram/2 - Plot raw probability tensors

Measurement Counts

  • plot_counts/2 - Visualize measurement outcome frequencies (works with both local simulation and Qx.Remote hardware results)

Bloch Sphere

Circuit Diagrams

  • circuit/2 - Generate SVG circuit diagrams with IEEE notation

State Tables

Output Formats

Most functions support multiple output formats via the :format option:

  • :vega_lite - Interactive charts for LiveBook (default for plots)
  • :svg - Standalone SVG (works everywhere)
  • :auto - Auto-detect best format (for tables)
  • :text - Plain text tables
  • :html - HTML tables
  • :markdown - Markdown tables with Kino support

Examples

# VegaLite plot in LiveBook
result = Qx.run(circuit)
Qx.Draw.plot(result)

# SVG output for saving to file
Qx.Draw.plot(result, format: :svg)

# Circuit diagram
svg = Qx.Draw.circuit(circuit, "My Circuit")
File.write!("circuit.svg", svg)

# State table
Qx.Draw.state_table(register, precision: 4, hide_zeros: true)

Summary

Functions

bloch_sphere(qubit, options \\ [])

Visualizes a single qubit state on the Bloch sphere.

circuit(circuit, title \\ nil)

Draws a quantum circuit diagram as SVG.

histogram(probabilities, options \\ [])

Creates a histogram from a raw probability tensor.

plot(result, options \\ [])

Plots the probability distribution from a simulation result.

plot_counts(result, options \\ [])

Plots measurement counts as a bar chart.

state_table(register_or_state, options \\ [])

Displays a quantum state as a formatted table.

Functions

bloch_sphere(qubit, options \\ [])

Visualizes a single qubit state on the Bloch sphere.

The Bloch sphere is a geometrical representation of pure qubit states.

Parameters

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

Options

  • :format - Output format (:svg, :vega_lite) (default: :vega_lite)
  • :title - Plot title (default: "Bloch Sphere")
  • :size - Sphere size (default: 400)

Examples

q = Qx.Qubit.new() |> Qx.Qubit.h()
Qx.Draw.bloch_sphere(q)

# SVG output
Qx.Draw.bloch_sphere(q, format: :svg)

circuit(circuit, title \\ nil)

Draws a quantum circuit diagram as SVG.

Parameters

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

Returns

SVG string representing the complete circuit diagram.

Examples

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

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

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

  • :format - Output format (:svg, :vega_lite) (default: :vega_lite)
  • :title - Plot title (default: "Probability Histogram")
  • :width - Plot width (default: 400)
  • :height - Plot height (default: 300)

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

  • :format - Output format (:svg, :vega_lite) (default: :vega_lite)
  • :title - Plot title (default: "Quantum State Probabilities")
  • :width - Plot width (default: 400)
  • :height - Plot height (default: 300)

Examples

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

# SVG output
Qx.Draw.plot(result, format: :svg, title: "Bell State")

plot_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.Remote.run/3).

Parameters

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

Options

  • :format - Output format (:svg, :vega_lite) (default: :vega_lite)
  • :title - Plot title (default: "Measurement Counts")
  • :width - Plot width (default: 400)
  • :height - Plot height (default: 300)

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.plot_counts(result)

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 - Either a Qx.Register struct or an Nx.Tensor state vector
  • options - Optional formatting parameters (default: [])

Options

  • :format - Output format (:auto, :text, :html, :markdown) (default: :auto)
  • :precision - Number of decimal places (default: 3)
  • :hide_zeros - Hide states with near-zero probability (default: false)

Examples

register = Qx.Register.new(2)
Qx.Draw.state_table(register)

# Custom format
Qx.Draw.state_table(register, format: :html, precision: 4)