Visualization

Color palette for circuit diagrams.

Default gate box size (side length).

Default horizontal spacing between gates.

Default vertical spacing between qubit wires.

Default wire stroke width.

TrainingHistory

Stores the training history including losses per epoch and per step.

Fields

• train_losses::Vector{Float64}: Average training loss per epoch
• val_losses::Vector{Float64}: Validation loss per epoch
• step_train_losses::Vector{Float64}: Training loss per step (per image processed)
• basis_name::String: Name of the basis being trained

Abstract base type for internal circuit layout specifications.

Entangled QFT circuit specification.

MERA circuit specification.

QFT circuit specification (1D when n_col_qubits == 0, 2D otherwise).

TEBD circuit specification.

_draw_controlled_gate!(ax, x, y_ctrl, y_target, label; color=CIRCUIT_COLORS.phase_gate)

Draw a controlled gate: a control dot at y_ctrl, a vertical wire, and a gate box at y_target.

_draw_entangle_layer!(ax, x_start, m, n, phases, y_offset_row, y_offset_col)

Draw entanglement gates connecting row and column qubits.

Arguments

• ax: CairoMakie axis
• x_start: horizontal position for the first gate
• m: number of row qubits
• n: number of column qubits
• phases: entanglement phase values
• y_offset_row: vertical offset for row qubits
• y_offset_col: vertical offset for column qubits

Returns

• x_pos: the horizontal position after the last gate drawn

_draw_gate!(ax, x, y, label; color=CIRCUIT_COLORS.hadamard, size=CIRCUIT_GATE_SIZE)

Draw a colored gate box centred at (x, y) with a text label.

_draw_legend!(ax, x, y, items)

Draw a gate colour legend. items is a vector of (color, symbol, description) tuples.

_draw_mera_layer!(ax, x_start, n_qubits, phases, y_offset)

Draw hierarchical MERA disentangler and isometry gates for a group of qubits. Matches the actual circuit structure in _mera_single_dim: k = log2(n_qubits) layers with stride s = 2^(l-1) at each layer l.

Layer l has npairs = nqubits ÷ (2s) pairs of gates:

• Disentanglers: control q1 = 2p·s+2, target q2 = mod1(2p·s+s+2, n_qubits)
• Isometries: control q1 = 2p·s+1, target q2 = 2p·s+s+1

Arguments

• ax: CairoMakie axis
• x_start: horizontal position for the first gate
• n_qubits: number of qubits in this MERA layer (must be power of 2)
• phases: phase values for each gate
• y_offset: vertical offset applied to all qubit positions

Returns

• x_pos: the horizontal position after the last gate drawn

_draw_qft_layer!(ax, x_start, n_qubits, y_offset)

Draw QFT gates (Hadamard + controlled M_k phase gates) for a group of qubits.

Arguments

• ax: CairoMakie axis
• x_start: horizontal position for the first gate
• n_qubits: number of qubits in this QFT layer
• y_offset: vertical offset applied to all qubit positions

Returns

• x_pos: the horizontal position after the last gate drawn

_draw_qubit!(ax, y, x_start, x_end, label_in, label_out)

Draw a horizontal qubit wire from x_start to x_end at vertical position y, with input label on the left and output label on the right.

_draw_tebd_layer!(ax, x_start, n_qubits, phases, y_offset)

Draw TEBD nearest-neighbour two-qubit gates in a ring topology.

Arguments

• ax: CairoMakie axis
• x_start: horizontal position for the first gate
• n_qubits: number of qubits in this TEBD layer
• phases: phase values for each gate
• y_offset: vertical offset applied to all qubit positions

Returns

• x_pos: the horizontal position after the last gate drawn

_draw_two_qubit_gate!(ax, x, y1, y2, label, phase; color=CIRCUIT_COLORS.entangle_gate, show_phase=true)

Draw a two-qubit gate connecting wires at y1 and y2: two dots, a connecting wire, a gate box at the midpoint, and an optional phase annotation.

_plot_circuit(spec::_EntangledQFTCircuitSpec; output_path=nothing)

Render a full Entangled QFT circuit diagram. Shows QFT blocks for row and column qubits with entanglement gates placed according to spec.entangle_position.

Arguments

• spec::_EntangledQFTCircuitSpec: circuit layout specification
• output_path: optional file path; when provided the figure is saved as PNG

Returns

• Figure: the CairoMakie figure object

_plot_circuit(spec::_MERACircuitSpec; output_path=nothing)

Render a full MERA circuit diagram with disentangler and isometry layers.

Arguments

• spec::_MERACircuitSpec: circuit layout specification
• output_path: optional file path; when provided the figure is saved as PNG

Returns

• Figure: the CairoMakie figure object

_plot_circuit(spec::_QFTCircuitSpec; output_path=nothing)

Render a full QFT circuit diagram. Produces a 1D layout when spec.n_col_qubits == 0 and a 2D layout (row + column QFT blocks separated by a dashed line) otherwise.

Arguments

• spec::_QFTCircuitSpec: circuit layout specification
• output_path: optional file path; when provided the figure is saved as PNG

Returns

• Figure: the CairoMakie figure object

_plot_circuit(spec::_TEBDCircuitSpec; output_path=nothing)

Render a full TEBD circuit diagram with nearest-neighbour gates in ring topology.

Arguments

• spec::_TEBDCircuitSpec: circuit layout specification
• output_path: optional file path; when provided the figure is saved as PNG

Returns

• Figure: the CairoMakie figure object

ema_smooth(values::Vector{Float64}, alpha::Float64) -> Vector{Float64}

Compute exponential moving average for smoothing noisy loss curves.

Arguments

• values::Vector{Float64}: Raw values to smooth
• alpha::Float64: Smoothing factor in (0, 1). Higher values = more smoothing. Common values: 0.6 (light), 0.9 (heavy), 0.95 (very heavy).

Returns

• Vector{Float64}: Smoothed values (same length as input)

plot_circuit(basis::AbstractSparseBasis; output_path=nothing)

Generate a professional circuit diagram for a sparse basis.

Arguments

• basis::AbstractSparseBasis: the basis whose circuit to visualize
• output_path: optional file path to save the figure (PNG recommended)

Returns

• Figure: the CairoMakie figure object

Example

basis = QFTBasis(3, 3)
fig = plot_circuit(basis)

# Save to file
plot_circuit(basis; output_path="qft_circuit.png")

plot_circuit(basis::EntangledQFTBasis; output_path=nothing)

Draw an Entangled QFT circuit diagram showing QFT blocks and entanglement gates.

Arguments

• basis::EntangledQFTBasis: the entangled QFT basis to visualize
• output_path: optional file path to save the figure

Returns

• Figure: the CairoMakie figure object

plot_circuit(basis::MERABasis; output_path=nothing)

Draw a MERA circuit diagram showing disentangler and isometry layers.

Arguments

• basis::MERABasis: the MERA basis to visualize
• output_path: optional file path to save the figure

Returns

• Figure: the CairoMakie figure object

plot_circuit(basis::QFTBasis; output_path=nothing)

Draw a QFT circuit diagram for the given QFTBasis. Produces a 1D layout when the basis has zero column qubits, and a 2D layout otherwise.

Arguments

• basis::QFTBasis: the QFT basis to visualize
• output_path: optional file path to save the figure

Returns

• Figure: the CairoMakie figure object

plot_circuit(basis::TEBDBasis; output_path=nothing)

Draw a TEBD circuit diagram showing nearest-neighbour two-qubit gates in ring topology.

Arguments

• basis::TEBDBasis: the TEBD basis to visualize
• output_path: optional file path to save the figure

Returns

• Figure: the CairoMakie figure object

plot_training_comparison(histories::Vector{TrainingHistory}; kwargs...)

Plot training loss curves for multiple bases on the same plot for comparison.

Arguments

• histories::Vector{TrainingHistory}: Vector of training histories to compare

Keyword Arguments

• title::String: Plot title (default: "Training Loss Comparison")
• xlabel::String: X-axis label (default: "Epoch")
• ylabel::String: Y-axis label (default: "Loss")
• yscale::Function: Y-axis scale function (default: log10)
• size::Tuple{Int,Int}: Figure size (default: (1000, 600))
• loss_type::Symbol: Type of loss to plot (:train, :validation, or :both, default: :both)

Returns

• Makie.Figure: The generated figure

Example

using ParametricDFT
basis1, hist1 = train_basis(QFTBasis, images; m=5, n=5, epochs=3)
basis2, hist2 = train_basis(TEBDBasis, images; m=5, n=5, epochs=3)
histories = [
    TrainingHistory(hist1.train_losses, hist1.val_losses, hist1.step_train_losses, "QFT"),
    TrainingHistory(hist2.train_losses, hist2.val_losses, hist2.step_train_losses, "TEBD")
]
fig = plot_training_comparison(histories)
save("training_comparison.png", fig)

plot_training_comparison_steps(histories::Vector{TrainingHistory}; kwargs...)

Plot per-step training loss curves for multiple bases on the same plot.

Arguments

• histories::Vector{TrainingHistory}: Vector of training histories to compare

Keyword Arguments

• title::String: Plot title (default: "Step Training Loss Comparison")
• xlabel::String: X-axis label (default: "Step")
• ylabel::String: Y-axis label (default: "Loss")
• yscale::Function: Y-axis scale function (default: log10)
• size::Tuple{Int,Int}: Figure size (default: (1000, 600))
• smoothing::Float64: EMA smoothing factor in (0, 1), 0 disables smoothing (default: 0.0)

Returns

• Makie.Figure: The generated figure

Example

using ParametricDFT
histories = [hist_qft, hist_entangled, hist_tebd]
fig = plot_training_comparison_steps(histories; smoothing=0.8)
save("step_comparison.png", fig)

plot_training_grid(histories::Vector{TrainingHistory}; kwargs...)

Create a grid of individual training loss plots for multiple bases.

Arguments

• histories::Vector{TrainingHistory}: Vector of training histories to plot

Keyword Arguments

• title::String: Overall title (default: "Training Loss Comparison")
• yscale::Function: Y-axis scale function (default: log10)
• size::Tuple{Int,Int}: Total figure size (default: (1200, 800))
• layout::Union{Nothing, Tuple{Int,Int}}: Grid layout (default: auto)

Returns

• Makie.Figure: The generated grid figure

Example

using ParametricDFT
histories = [hist1, hist2, hist3]  # TrainingHistory objects
fig = plot_training_grid(histories, layout=(2, 2))
save("training_grid.png", fig)

plot_training_loss(history::TrainingHistory; kwargs...)

Plot training and validation loss curves for a single basis.

Arguments

• history::TrainingHistory: Training history to plot

Keyword Arguments

• title::String: Plot title (default: "Training Loss - $(history.basis_name)")
• xlabel::String: X-axis label (default: "Epoch")
• ylabel::String: Y-axis label (default: "Loss")
• yscale::Function: Y-axis scale function (default: log10)
• size::Tuple{Int,Int}: Figure size (default: (800, 500))

Returns

• Makie.Figure: The generated figure

Example

using ParametricDFT
basis, history = train_basis(QFTBasis, images; m=5, n=5, epochs=3)
hist = TrainingHistory(history.train_losses, history.val_losses,
                       history.step_train_losses, "QFT")
fig = plot_training_loss(hist)
save("qft_training_loss.png", fig)

plot_training_loss_steps(history::TrainingHistory; kwargs...)

Plot per-step training loss curve for a single basis.

Arguments

• history::TrainingHistory: Training history to plot

Keyword Arguments

• title::String: Plot title (default: "Step Training Loss - $(history.basis_name)")
• xlabel::String: X-axis label (default: "Step")
• ylabel::String: Y-axis label (default: "Loss")
• yscale::Function: Y-axis scale function (default: log10)
• size::Tuple{Int,Int}: Figure size (default: (800, 500))
• smoothing::Float64: EMA smoothing factor in (0, 1), 0 disables smoothing (default: 0.0)

Returns

• Makie.Figure: The generated figure

Example

using ParametricDFT
basis, history = train_basis(QFTBasis, images; m=5, n=5, epochs=3)
hist = TrainingHistory(history.train_losses, history.val_losses, history.step_train_losses, "QFT")
fig = plot_training_loss_steps(hist; smoothing=0.8)
save("qft_step_loss.png", fig)

save_training_plots(histories::Vector{TrainingHistory}, output_dir::String; prefix::String="", smoothing::Float64=0.6)

Generate and save all training visualization plots to a directory.

Arguments

• histories::Vector{TrainingHistory}: Vector of training histories
• output_dir::String: Directory to save plots

Keyword Arguments

• prefix::String: Prefix for filenames (default: "")
• smoothing::Float64: EMA smoothing factor for step-level plots (default: 0.6). Set to 0.0 to disable smoothed plots.

Returns

• Vector{String}: Paths to saved plot files

Example

using ParametricDFT
histories = [
    TrainingHistory(hist1.train_losses, hist1.val_losses, hist1.step_train_losses, "QFT"),
    TrainingHistory(hist2.train_losses, hist2.val_losses, hist2.step_train_losses, "TEBD")
]
save_training_plots(histories, "output/"; smoothing=0.8)