viz

Documentation

Overview

Package viz renders quantum simulation results as SVG visualizations.

It provides three visualization types:

• Histogram / HistogramProb: bar charts of measurement counts or probabilities
• Bloch: single-qubit state rendered on the Bloch sphere
• StateCity: isometric 3D bar chart of density matrix elements

All outputs are self-contained SVG strings with no external dependencies. Each function comes in two forms: Foo returns a string, FprintFoo writes to an io.Writer.

Styling is controlled via WithStyle using DefaultStyle (light) or DarkStyle (dark).

Example (Bloch)

package main

import (
	"fmt"
	"math"
	"strings"

	"github.com/splch/goqu/viz"
)

func main() {
	// |+> state
	s := 1 / math.Sqrt(2)
	state := []complex128{complex(s, 0), complex(s, 0)}
	svg := viz.Bloch(state)
	fmt.Println(strings.Contains(svg, "<svg"))
}

Output:

true

Example (Histogram)

package main

import (
	"fmt"
	"strings"

	"github.com/splch/goqu/viz"
)

func main() {
	counts := map[string]int{"00": 512, "11": 488}
	svg := viz.Histogram(counts)
	fmt.Println(strings.Contains(svg, "<svg"))
}

Output:

true

Example (HistogramProb)

package main

import (
	"fmt"
	"strings"

	"github.com/splch/goqu/viz"
)

func main() {
	probs := map[string]float64{"00": 0.5, "11": 0.5}
	svg := viz.HistogramProb(probs)
	fmt.Println(strings.Contains(svg, "<svg"))
}

Output:

true

Example (StateCity)

package main

import (
	"fmt"
	"strings"

	"github.com/splch/goqu/viz"
)

func main() {
	// Single qubit |0><0| density matrix
	rho := []complex128{1, 0, 0, 0}
	svg := viz.StateCity(rho, 2)
	fmt.Println(strings.Contains(svg, "<svg"))
}

Output:

true

Index

• func Bloch(state []complex128, opts ...Option) string
• func FprintBloch(w io.Writer, state []complex128, opts ...Option) error
• func FprintHistogram(w io.Writer, counts map[string]int, opts ...Option) error
• func FprintHistogramProb(w io.Writer, probs map[string]float64, opts ...Option) error
• func FprintStateCity(w io.Writer, rho []complex128, dim int, opts ...Option) error
• func Histogram(counts map[string]int, opts ...Option) string
• func HistogramProb(probs map[string]float64, opts ...Option) string
• func StateCity(rho []complex128, dim int, opts ...Option) string
• type Option
  • func WithSize(width, height float64) Option
  • func WithSorted(sorted bool) Option
  • func WithStyle(s *Style) Option
  • func WithTitle(title string) Option
• type Style
  • func DarkStyle() *Style
  • func DefaultStyle() *Style

Examples

• Package (Bloch)
• Package (Histogram)
• Package (HistogramProb)
• Package (StateCity)

Functions

func Bloch

func Bloch(state []complex128, opts ...Option) string

Bloch returns an SVG rendering of a single-qubit state on the Bloch sphere. The state must have length 2.

func FprintBloch

func FprintBloch(w io.Writer, state []complex128, opts ...Option) error

FprintBloch writes an SVG Bloch sphere rendering to w.

func FprintHistogram

func FprintHistogram(w io.Writer, counts map[string]int, opts ...Option) error

FprintHistogram writes an SVG bar chart of measurement counts to w.

func FprintHistogramProb

func FprintHistogramProb(w io.Writer, probs map[string]float64, opts ...Option) error

FprintHistogramProb writes an SVG bar chart of measurement probabilities to w.

func FprintStateCity

func FprintStateCity(w io.Writer, rho []complex128, dim int, opts ...Option) error

FprintStateCity writes an SVG state city plot to w.

func Histogram

func Histogram(counts map[string]int, opts ...Option) string

Histogram returns an SVG bar chart of measurement counts.

func HistogramProb

func HistogramProb(probs map[string]float64, opts ...Option) string

HistogramProb returns an SVG bar chart of measurement probabilities.

func StateCity

func StateCity(rho []complex128, dim int, opts ...Option) string

StateCity returns an SVG isometric 3D bar chart of a density matrix. The rho slice must be row-major with length dim*dim, where dim is a power of 2.

Types

type Option

type Option func(*config)

Option configures visualization rendering.

func WithSize

func WithSize(width, height float64) Option

WithSize sets the SVG width and height in pixels.

func WithSorted

func WithSorted(sorted bool) Option

WithSorted controls whether histogram bars are sorted by bitstring. Default is true.

func WithStyle

func WithStyle(s *Style) Option

WithStyle sets the rendering style.

func WithTitle

func WithTitle(title string) Option

WithTitle sets an optional title displayed above the plot.

type Style

type Style struct {
	BackgroundColor string
	TextColor       string
	AxisColor       string
	GridColor       string
	FontFamily      string
	FontSize        float64

	// Histogram bar colors.
	BarFill   string
	BarStroke string

	// Bloch sphere colors.
	SphereStroke string
	StateColor   string

	// State city plot colors.
	RealFill   string
	ImagFill   string
	BarOutline string

	Padding float64
}

Style configures SVG rendering appearance for all visualizations.

func DarkStyle

func DarkStyle() *Style

DarkStyle returns a dark-theme style.

func DefaultStyle

func DefaultStyle() *Style

DefaultStyle returns a light-theme style.