Getting Started — Jupyter Integration

Eigenvue integrates with Jupyter notebooks so you can explore algorithm visualizations right next to your own code and analysis.

Displaying a Visualization

Use eigenvue.jupyter() to render an interactive widget in any notebook cell:

import eigenvue

eigenvue.jupyter("quicksort", inputs={"array": [10, 3, 7, 1, 9, 5, 2, 8, 4, 6]})

When you run the cell, an inline widget appears containing the full Eigenvue visualizer — canvas, code panel, explanation panel, and playback controls.

Cell Output

The widget is rendered as an IFrame that embeds a local Flask server. You get the same playback controls available on the web app:

• Play / Pause — start or stop continuous playback.
• Step Forward / Step Back — advance or rewind one step at a time.
• Speed selector — choose 0.5x, 1x, 2x, or 4x.
• Progress bar — drag to jump to any step.
• Reset — return to the first step.

The IFrame resizes to fit the notebook output area. Scroll within the widget if your screen is narrow.

Multiple Visualizations

You can display several visualizations in the same notebook. Each call to eigenvue.jupyter() in a separate cell produces its own independent widget:

# Cell 1
import eigenvue

eigenvue.jupyter("bubble-sort", inputs={"array": [5, 1, 4, 2, 8]})

# Cell 2
eigenvue.jupyter("self-attention", inputs={"tokens": ["the", "cat", "sat"], "embeddingDim": 4})

Each widget maintains its own playback state, so you can compare algorithms side by side without interference.

Google Colab Compatibility

Eigenvue works in Google Colab. Install the package in a code cell and call eigenvue.jupyter() as usual:

!pip install eigenvue[jupyter]

import eigenvue

eigenvue.jupyter("dijkstra")

Colab needs one extra hop that other notebooks do not. Your kernel runs on a remote VM while the cell output is rendered by your own browser, so an address like 127.0.0.1:8000 would point at your machine rather than at the kernel. eigenvue.jupyter() detects Colab and publishes the port through google.colab.kernel.proxyPort, so the widget loads without any manual port configuration on your part.

Combining with Analysis

A common workflow is to collect step data with eigenvue.steps(), run your own analysis, and then display the visualization with eigenvue.jupyter() in the same notebook:

import eigenvue

# 1. Collect step data programmatically
inputs = {"array": [1, 3, 5, 7, 9, 11, 13, 15], "target": 13}
steps = eigenvue.steps("binary-search", inputs=inputs)

# 2. Analyse the results
midpoints = sum(1 for s in steps if s["id"] == "calculate_mid")

print(f"Total steps:     {len(steps)}")
print(f"Midpoints taken: {midpoints}")
print(f"Found at index:  {steps[-1]['state'].get('result')}")

# 3. Display the interactive visualization
eigenvue.jupyter("binary-search", inputs=inputs)

This pattern lets you quantify algorithm behaviour (step counts, comparisons, memory usage) and visually verify the results — all within a single notebook.