org.soulspace.qclojure.adapter.visualization.common — org.soulspace/qclojure 0.1.0-SNAPSHOT

Common utilities for quantum visualization - shared calculations and data extraction.

This namespace contains shared functions used across different visualization formats. It focuses on pure data transformation and calculation, keeping format-specific rendering logic in the individual format namespaces.

calculate-bar-dimensions clj

(calculate-bar-dimensions chart-data total-width total-height)

Calculate bar dimensions for different chart formats.

Parameters:

• chart-data: Result from prepare-bar-chart-data
• total-width: Total available width
• total-height: Total available height

Returns: Map with dimension calculations for bars

calculate-phase-info clj

(calculate-phase-info state indices labels)

Calculate phase information for quantum state amplitudes.

Parameters:

• state: Quantum state
• indices: Indices to analyze
• labels: Corresponding labels

Returns: Vector of maps with :label and :phase-degrees

calculate-reference-distances clj

(calculate-reference-distances coords & {:keys [precision] :or {precision 2}})

Calculate distances from current state to reference states.

Parameters:

• coords: Current state coordinates from quantum-state-to-bloch-coordinates
• precision: Decimal places for distance values (default 2)

Returns: Vector of maps with :label and :distance for each reference state

calculate-state-summary clj

(calculate-state-summary state filtered-data)

Calculate summary information about quantum state.

Parameters:

• state: Quantum state
• filtered-data: Result from filter-significant-probabilities

Returns: Map with summary statistics

extract-amplitude-info clj

(extract-amplitude-info state
                        indices
                        labels
                        &
                        {:keys [precision] :or {precision 3}})

Extract detailed amplitude information for display.

Parameters:

• state: Quantum state
• indices: Indices of amplitudes to extract
• labels: Corresponding labels
• precision: Decimal places (default 3)

Returns: Vector of maps with :label, :amplitude, :magnitude, :phase, :probability

extract-state-probabilities clj

(extract-state-probabilities state)

Extract probability distribution from quantum state.

Parameters:

• state: Quantum state with :state-vector and :num-qubits

Returns: Vector of probabilities (real numbers) for each computational basis state

filter-significant-probabilities clj

(filter-significant-probabilities probabilities
                                  labels
                                  &
                                  {:keys [threshold max-count]
                                   :or {threshold 0.001 max-count 16}})

Filter probabilities above threshold and limit count.

Parameters:

• probabilities: Vector of probability values
• threshold: Minimum probability to include (default 0.001)
• max-count: Maximum number of states to include (default 16)

Returns: Map with :indices, :probabilities, :labels, and :summary info

format-amplitude-display clj

(format-amplitude-display amplitude & {:keys [precision] :or {precision 3}})

Format complex amplitude for human-readable display.

Parameters:

• amplitude: Complex amplitude (fastmath Vec2)
• precision: Decimal places for rounding (default 3)

Returns: String representation like '0.707+0.0i' or '0.5-0.3i'

format-bloch-coordinates clj

(format-bloch-coordinates coords & {:keys [precision] :or {precision 3}})

Format Bloch sphere coordinates for display.

Parameters:

• coords: Result from quantum-state-to-bloch-coordinates
• precision: Decimal places (default 3 for cartesian, 1 for angles)

Returns: Map with formatted coordinate strings

format-reference-distances clj

(format-reference-distances distance-data
                            &
                            {:keys [format] :or {format :inline}})

Format reference state distances as display text.

Parameters:

• distance-data: Result from calculate-reference-distances
• format: Output format (:inline or :list)

Returns: Formatted string

format-single-qubit-state clj

(format-single-qubit-state state & {:keys [precision] :or {precision 3}})

Format single-qubit quantum state as amplitude expression.

Parameters:

• state: Single-qubit quantum state
• precision: Decimal places (default 3)

Returns: String like '0.707|0⟩ + 0.707i|1⟩'

format-state-expression clj

(format-state-expression state
                         indices
                         labels
                         &
                         {:keys [precision] :or {precision 3}})

Format quantum state as amplitude expression.

Parameters:

• state: Quantum state
• indices: Indices of significant amplitudes to show
• labels: Corresponding basis state labels
• precision: Decimal places (default 3)

Returns: String like '0.707|0⟩ + 0.707|1⟩'

generate-basis-labels clj

(generate-basis-labels n-qubits)

Generate computational basis state labels for given number of qubits.

Parameters:

• n-qubits: Number of qubits in the system

Returns: Vector of basis state labels like [|00⟩ |01⟩ |10⟩ |11⟩] for 2 qubits

Examples: (generate-basis-labels 1) ;=> [|0⟩ |1⟩] (generate-basis-labels 2) ;=> [|00⟩ |01⟩ |10⟩ |11⟩]

generate-bloch-legend clj

(generate-bloch-legend format)

Generate legend text for Bloch sphere visualizations.

Parameters:

• format: Target format (:ascii or :svg)

Returns: String with appropriate legend information

generate-color-palette clj

(generate-color-palette n-colors & {:keys [scheme] :or {scheme :quantum}})

Generate color palette for quantum visualizations.

Parameters:

• n-colors: Number of colors needed
• scheme: Color scheme (:quantum, :rainbow, :monochrome)

Returns: Vector of color codes (format depends on target: hex for web, ANSI for terminal)

prepare-bar-chart-data clj

(prepare-bar-chart-data state
                        &
                        {:keys [threshold max-bars normalize]
                         :or {threshold 0.001 max-bars 16 normalize true}})

Prepare data for probability bar charts across different formats.

This function extracts and normalizes probability data in a format-agnostic way.

Parameters:

• state: Quantum state
• options: Chart options :threshold - Minimum probability threshold (default 0.001) :max-bars - Maximum number of bars (default 16) :normalize - Whether to normalize to max probability (default true)

Returns: Map with chart data:

• :probabilities - Filtered probability values
• :labels - Corresponding state labels
• :normalized - Normalized probabilities (0-1 scale)
• :max-probability - Maximum probability value
• :summary - Summary information

prepare-bloch-display-data clj

(prepare-bloch-display-data
  state
  coords
  &
  {:keys [show-coordinates show-distances precision format]
   :or {show-coordinates true show-distances true precision 3 format :ascii}})

Prepare all display data for Bloch sphere visualization.

This aggregates all the text and coordinate information needed by both ASCII and SVG formats, reducing code duplication.

Parameters:

• state: Single-qubit quantum state
• coords: Coordinates from quantum-state-to-bloch-coordinates
• options: Display options :show-coordinates - Include coordinate text (default true) :show-distances - Include reference distances (default true) :precision - Decimal places (default 3)

Returns: Map with formatted display strings and data