🧠 SeeDL

Don't just train neural networks or run quantum circuits. See them.

The next-generation scientific visualization library for classical neural networks and quantum systems.

⚡ Quickstart  •  ✨ Why SeeDL?  •  🎨 Visual Gallery  •  🚀 Flagship Features  •  🔬 Complete Toolkit  •  🛡️ Scientific Rigor  •  📚 Docs

_{Zero required dependencies for the pure Python SVG core • Optional integrations for PyTorch, NumPy, Plotly, Matplotlib & Qiskit}

Real neurons. True signed synaptic weights. Live captured activations. Interactive 3D WebGL camera controls.

import seedl as sd
import torch.nn as nn
from qiskit import QuantumCircuit

# 1. Interactive 3D Neural Networks (orbit, pan, zoom & click neurons)
model = nn.Sequential(nn.Linear(2, 3), nn.ReLU(), nn.Linear(3, 1))
sd.see(model, view="3d")

# 2. Interactive 3D Bloch Sphere
sd.bloch("+")

# 3. Quantum Circuit Diagram & Evolution
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
sd.see(qc)

# 4. Bipartite Entanglement & von Neumann Entropy
bell_state = [1 / (2**0.5), 0, 0, 1 / (2**0.5)]
sd.entanglement(bell_state)

🌌 SeeDL 0.5.0: The Neural Observatory

SeeDL 0.5.0 introduces The Neural Observatory, an advanced laboratory suite for non-destructive execution graph tracing, multi-layer Transformer rollout, attribution benchmarking, gradient health diagnostics, quantum noise simulation, dataset intelligence, and publication-ready scientific reports.

Key Capabilities in 0.5.0:

• Neural Execution Tracing (sd.trace):
  • Non-destructive execution graph recording with runtime hook interception and optional torch.fx symbolic analysis.
  • Distinguishes verified explicit tensor pointers, storage views, and symbolic dependencies.
  • Guaranteed restoration of registered module buffers (including large buffers > 8192 elements), mixed training modes, and parameter gradients.
• Tensor Flow Visualization (sd.flow):
  • Interactive DAG explorer with layer-by-layer parameter, shape, duration, and activation telemetry.
• Transformer Attention Rollout (sd.attention_rollout, sd.attention_layers):
  • Abnar & Zuidema (2020) residual attention rollout tracking token information flow through multi-layer architectures.
  • Layer-by-layer attention matrix heatmaps and head-level dispersion diagnostics.
• Advanced Explainability (sd.compare_attributions):
  • Side-by-side attribution comparison between Saliency Maps, Integrated Gradients (completeness axiom verified), and SmoothGrad.
  • Pairwise Pearson correlation, Cosine similarity, and multi-method consensus.
• Gradient Health Diagnostics (sd.gradient_health):
  • Layer-by-layer norm diagnostics, gradient-to-weight ratios, vanishing/high gradient alerts, tied-weight transparency, and dead ReLU sparsity detection.
• Training Run Comparison (sd.compare_runs):
  • Two-run training comparison with step alignment, final deltas, pointwise absolute differences, and missing metric alerts.
• Quantum Noise Simulation (sd.quantum_noise):
  • Single-qubit open quantum system decoherence analysis via Kraus operators (depolarizing, amplitude damping, phase damping).
  • Single-qubit Bloch sphere trajectories, purity, coherence, and von Neumann entropy.
  • Bipartite two-qubit entanglement analysis (sd.entanglement) and Peres-Horodecki negativity computation (compute_two_qubit_negativity) are provided as separate analysis capabilities.
• Dataset Intelligence (sd.dataset_health, sd.dataset_drift):
  • Summary health profiles, numerical condition estimation, Population Stability Index (PSI), and Jensen-Shannon Divergence (JSD).
• Scientific Report Builder (sd.report):
  • Publication-grade offline reports embedding isolated, interactive visualization cards via sandboxed iframes with zero external CDN dependencies.
• Safe Analysis Serialization (sd.save_analysis, sd.load_analysis):
  • Pure JSON artifact serialization protected by SHA-256 canonical integrity hashes and strict schema validation.

Neural Observatory Quick Examples:

import torch
import torch.nn as nn
import seedl as sd

# 1. Trace and visualize execution topology
model = nn.Sequential(nn.Linear(10, 32), nn.ReLU(), nn.Linear(32, 2))
x = torch.randn(4, 10)
trace = sd.trace(model, x)
flow_view = sd.flow(trace)
flow_view.save("trace.html")

# 2. Audit gradient health before optimizer step
loss = model(x).sum()
loss.backward()
health_view = sd.gradient_health(model)
print(health_view.summary)

# 3. Simulate single-qubit noisy quantum channel decoherence
noise_view = sd.quantum_noise(channel="amplitude_damping", param=0.25, steps=10)
noise_view.save("quantum_noise.html")

# 4. Compile offline scientific report
report = sd.report(
    title="Neural Observatory Diagnostic Report",
    views=[flow_view, health_view, noise_view],
    author="Scientific Research Team",
)
report.save("diagnostic_report.html")

See the Official Release Notes and runnable examples in examples/.

✨ Why SeeDL?

SeeDL helps you inspect PyTorch models and quantum states in a notebook or browser. You can explore individual neurons and their connection weights, capture activations from a forward pass, browse CNN channels, and compare attention heads.

For training runs, record snapshots to revisit weights, activations, gradients, and outputs at a particular step. For quantum examples, inspect circuit evolution, Bloch vectors, and entanglement diagnostics.

Interactive views use Plotly. HTML exports work without a Python kernel, and the core SVG renderer has no required dependencies. The examples below show outputs from the library.

🎨 Interactive Visual Gallery

The gallery contains SeeDL exports from PyTorch models and quantum examples.

🎮 Interactive 3D Neural Network	📐 Precision 2D Synaptic Graph
Rotatable Plotly 3D WebGL with planar layer boundaries and camera presets	Signed synaptic connections: green/blue for positive weights, red/pink for negative
🎬 Forward Propagation Animation	🔍 Neuron-Level Dendrite Inspection
Step-by-step layer activation playback with Play/Pause, speed controls, and slider	Cyan incoming connections, amber outgoing connections, and real parameter HUD
⛰️ 3D Loss Landscapes	🌌 3D Latent Embeddings (PCA)
Sampled 2D parameter-slice surfaces with optimum markers and contour maps	Interactive dimensional reduction with cluster labels and variance metrics

Explore specialized architectures: CNN Feature Maps • Transformer Attention Hierarchy • Deep Networks in 3D • Pure SVG Fallback

⚡ Quickstart

1. Installation

# Recommended for Quantum + 3D WebGL:
pip install "seedl[quantum,plotly]"

# Recommended for Deep Learning + 3D WebGL:
pip install "seedl[torch,plotly]"

# Complete Scientific Suite:
pip install "seedl[all]"

# Lightweight core engine (Pure Python, zero third-party dependencies):
pip install seedl

Or using uv:

uv add "seedl[quantum,plotly]"
uv add "seedl[torch,plotly]"

git clone https://github.com/iamaritrasaha/seedl.git
cd seedl
uv sync --extra dev --extra all
uv run --extra dev --extra all pytest

2. From Zero to 3D in 30 Seconds

import torch
from torch import nn
import seedl as sd

# 1. Define any standard PyTorch neural network
model = nn.Sequential(
    nn.Linear(4, 8),
    nn.ReLU(),
    nn.Linear(8, 6),
    nn.ReLU(),
    nn.Linear(6, 2),
)

# 2. Provide a sample input tensor
x = torch.tensor([[0.5, -0.2, 1.4, -0.8]])

# 3. See your network!
sd.see(model)  # Clean 2D architecture diagram
sd.see(model, view="3d")  # Interactive 3D WebGL model
sd.see(model, input=x)  # Colors neurons by live activation responses
sd.see(model, input=x).explore()  # Step through computation layer-by-layer

3. Export & Share Anywhere

view = sd.see(model, input=x, view="3d")

# Save as a standalone, self-contained HTML file (zero server required!)
view.save("my_neural_network.html")

# Or save as a lightweight vector SVG
sd.see(model, backend="svg").save("architecture.svg")

🚀 Flagship Features

🔍 1. Direct 3D Neuron Selection & Dendrite Inspection

Hovering gives you quick stats, but clicking a neuron unlocks deep-dive telemetry directly in the 3D viewport. You can click any neuron directly with your mouse in standalone HTML or notebook environments, or select via code and dropdown menus:

# Direct 3D network exploration:
view = sd.see(model, input=x, view="3d")
# Click any neuron marker directly to isolate its connections and update HUD!

# Or programmatically select neuron index 2 in hidden layer 1:
view = sd.see(model, input=x, select_neuron=(1, 2), view="3d")

• Direct Viewport Interaction:
  • Click any neuron marker in the 3D scene to isolate its local dendritic neighborhood.
  • Camera Preservation: Clicking a neuron preserves your current orbit and pan camera orientation without jumping.
  • Click the empty background to clear selection and restore the full network overview.
• Isolated Synaptic Wiring:
  • Incoming Connections: Highlighted in vivid cyan (#00e5ff, width 3.5, opacity 0.95).
  • Outgoing Connections: Highlighted in warm amber (#fbbf24, width 3.5, opacity 0.95).
  • Unrelated Network: Dimmed to 0.04 opacity so you can trace information flow instantly without visual clutter.
  • Target Node: Highlighted with a luminous gold halo ring.
• Parametric HUD Inspection Card:
  • Module name and mathematical operation (e.g. $z = W \cdot a + b \rightarrow \text{ReLU}()$).
  • Actual bias value and parameter status (trainable vs frozen).
  • True post-activation value and pre-activation ($z$) value for the chosen batch sample.
  • Parameter gradient availability and values.
  • Comprehensive sorted lists of incoming and outgoing connection weights.

🎬 2. Forward Propagation Animation Engine

Understand how inputs transform into representations across depth. By calling .explore(), SeeDL launches an interactive playback studio:

sd.see(model, input=x, view="3d").explore()

• Full Playback Controls:
  • ▶ Play: Automatically steps computation forward layer by layer.
  • ⏸ Pause: Freezes playback at any layer to allow manual inspection.
  • ⏮ Reset: Restores the global network overview.
  • Speed Presets: Toggle between 0.5x, 1x, and 2x animation speeds.
  • Layer Scrubber: Bidirectionally scrub through Input $\rightarrow$ Hidden 1 $\rightarrow$ Hidden 2 $\rightarrow$ Output.
• Live Activation Telemetry: As the animation advances, neurons light up with their actual recorded activation values, showing saturation and dead units clearly.

🌐 3. True 3D WebGL Architecture Exploration & Themes

SeeDL's 3D engine is powered by Plotly WebGL scatter and mesh primitives, built specifically for spatial intuition:

• Optimal Default Perspective: Opens with an ergonomic camera angle (eye=(-1.8, -2.4, 0.85)), providing immediate depth, clear layer spacing, and unoccluded connections.
• One-Click Camera Controls: Dedicated camera menu to trigger automated 360° Orbit, switch to planar Pan, or Reset view back to home coordinates.
• Planar Layer Guides: Dotted bounding boxes define layer boundaries in 3D space without obstructing connection sightlines.
• 5 Scientific Themes: scientific (deep space navy default), dark, light, minimal, and presentation.

🖼️ 4. 3D Spatial CNN Feature Map Stacks

For convolutional neural networks, SeeDL captures intermediate activations via PyTorch forward hooks and renders them as stacked 3D spatial planes along the depth axis:

# Pass any convolutional model and an image tensor:
sd.see(cnn_model, input=image_tensor, view="3d")

• Spatial Coordinate Planes: Feature map channels are preserved as $(H, W)$ 2D grids stacked across layer depth.
• Activation Intensity Mapping: Pixel markers reflect true forward-pass feature activations with continuous teal/viridis colormaps.
• Architecture Flow: Inter-layer bounding boxes show receptive field downsampling and channel expansion.

⚛️ 5. The Quantum Revolution: Quantum System Diagnostics

SeeDL 0.2.0 introduces a comprehensive quantum visualization subsystem with verified mathematical rigor:

Interactive 3D Bloch Sphere

Visualize any single-qubit statevector or density matrix with exact Cartesian coordinates $r_i = \text{Tr}(\rho \sigma_i)$:

# Pure states (r = 1.0) on the sphere surface:
sd.bloch([1 / 2**0.5, 1 / 2**0.5])  # |+> state on +X axis
sd.bloch([1 / 2**0.5, 1j / 2**0.5])  # |+i> state on +Y axis

# Mixed states (r < 1.0) inside the sphere:
rho_mixed = [[0.75, 0.0], [0.0, 0.25]]
sd.bloch(rho_mixed)  # Bloch vector length r = 0.5 inside sphere

Quantum Circuits & State Evolution

Render interactive circuit diagrams and track unitary evolution step-by-step:

from qiskit import QuantumCircuit

qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)

# Interactive circuit diagram with statevector evolution tracking:
sd.circuit(qc, simulate=True)

Bipartite Entanglement Diagnostics

Diagnose quantum correlations using automated partial traces and von Neumann entropy:

# Analyze a Bell pair (|00> + |11>) / sqrt(2):
bell = [1 / 2**0.5, 0.0, 0.0, 1 / 2**0.5]
sd.entanglement(bell)
# Yields exact von Neumann entropy: S(ρ_A) = 1.0000 bit (Maximally Entangled)

🔬 The Complete Toolkit

SeeDL is more than a multilayer perceptron viewer. It is a unified visual diagnostic suite for deep learning:

import seedl as sd

# Visualize 1D vectors, 2D weight matrices, or image tensors
sd.see(my_tensor)

# Inspect all layer activations from a forward pass:
sd.activations(model, input=x)

# Diagnose gradient health (vanishing / exploding gradients) after loss.backward():
loss.backward()
sd.gradients(model)

# Lightweight in-memory training metric tracker:
tracker = sd.watch(name="experiment_resnet")
tracker.log(epoch=1, loss=0.82, accuracy=0.64)
tracker.log(epoch=2, loss=0.55, accuracy=0.79)
sd.see(tracker)

# Compare multiple training runs side-by-side with automatic smoothing:
sd.compare(
    {"epoch": [1, 2, 3], "loss": [0.82, 0.55, 0.38]},
    {"epoch": [1, 2, 3], "loss": [0.90, 0.68, 0.52]},
    names=("AdamW (lr=1e-3)", "SGD (lr=1e-2)"),
)

# Saliency maps (vanilla backpropagation):
sd.explain(model, input=x, method="saliency")

# Integrated Gradients (path-integrated attribution):
sd.explain(model, input=x, method="integrated_gradients", steps=30)

# Self-attention & cross-attention token heatmaps:
sd.attention(
    attention_matrix,
    tokens=["The", "neural", "network", "learns", "features"],
)

# Multi-class prediction probabilities with target highlighting:
sd.predictions(
    logits_or_probs=[2.8, -0.4, 0.1, 1.2],
    labels=["airplane", "automobile", "bird", "cat"],
    task="classification",
)

# Evaluate a 2D parameter slice around current weights:
sd.loss_landscape(
    model,
    (x_batch, y_batch),
    loss_fn=nn.functional.cross_entropy,
    axes=(("weight", 0), ("bias", 0)),
    radius=1.5,
    steps=20,
    evaluate=True,  # Explicitly opt-in to loss surface evaluation
)

# 3D PCA dimensional reduction on hidden embeddings:
embeddings = torch.randn(64, 128)
sd.embeddings(embeddings, dimensions=3)

sd.learn("gradient_descent", lr=0.1, steps=15)
sd.learn("backpropagation")
sd.learn("activation_functions")
sd.learn("loss_functions")
sd.learn("attention")
sd.learn("convolution")

🛡️ Scientific Rigor & Integrity

SeeDL is engineered by scientists and engineers who value truthful representation over flashy illusions:

1. True Weights, Not Random Lines: Synaptic connections represent genuine model[layer].weight[out, in] scalar values. Edge color corresponds strictly to sign, and stroke thickness reflects normalized absolute magnitude.
2. Real Activations, Not Decorative Colors: When passing input=x, neuron node colorings reflect the exact floating-point tensor values captured by forward hooks during inference.
3. Computation Flow, Not "Particle Physics": Animation highlights denote the sequential order of matrix operations and activation functions. SeeDL will never render misleading particles or arbitrary pulses that misrepresent mathematical reality.
4. Zero Model State Tampering: When capturing activations or evaluating loss surfaces, SeeDL never mutates model parameters, device placement, or train/eval modes. Loss evaluations are performed safely under torch.no_grad() on explicitly cloned state copies.
5. Honest Architectural Fallbacks:
   • Supported feedforward networks receive full neuron-level visualization.
   • Convolutional networks (CNNs) display operation blocks with tensor channel dimensions.
   • Transformers and arbitrary DAGs display verified module hierarchy trees rather than guessing unprovable execution paths.
6. Graceful Large-Network Scaling: Networks exceeding 100 neurons or 1,500 connections are automatically protected by deterministic sampling limits with transparent disclosures in the visualization header.

📦 Rendering Backends

# Choose your backend explicitly:
sd.see(model, backend="plotly")  # Interactive Plotly WebGL
sd.see(model, backend="svg")  # Pure Python vector SVG
sd.see(model, backend="matplotlib")  # Publication-ready Matplotlib plot

📚 Documentation & Resources

• Official Website & Playground: Local preview, reproducible SeeDL 0.3.0 demos, documentation, and manual GitHub Pages deployment.
• Interactive Showcase Notebook: Complete, cell-by-cell walkthrough demonstrating 2D/3D networks, neuron selection, forward exploration, loss landscapes, and embeddings.
• Advanced 3D & Quantum Showcase: Deep-dive notebook demonstrating direct 3D neuron selection, CNN spatial maps, 3D Bloch spheres, quantum circuit evolution, Bell state entanglement, and density matrices.
• Visual Acceptance Specification: Comprehensive verification criteria, tested architectures, and capability boundaries.
• Examples Directory:
  • 01_quickstart.py: Zero-to-one API overview.
  • 02_model_and_training.py: Model inspection, metrics, and training loops.
  • 04_explainability_and_predictions.py: Interpretability and attributions.
• Release Notes: Version 0.1.0 changelog, design decisions, and roadmap.

🛠️ Contributing & Development

We welcome contributions, bug reports, and suggestions from the deep learning community!

# Clone repository
git clone https://github.com/iamaritrasaha/seedl.git
cd seedl

# Install development environment with uv
uv sync --extra dev --extra all

# Run test suite across CPU environment
uv run --extra dev --extra all pytest

# Code quality and static typing checks
uv run --extra dev ruff check .
uv run --extra dev ruff format --check .
uv run --extra dev mypy

# Validate build distributions
uv build --no-sources