Perm

Terminal-first sorting visualizer, benchmarker & trace debugger

Wireshark for sorting • htop for sorting • Blender-level observability

Features • Installation • Quick Start • Commands • Configuration • Plugins • Architecture • Benchmarks

Features

🎯 Core

13+ sorting algorithms - From Bubble to PDQSort, each fully instrumented
8 dataset generators - Random, reversed, nearly sorted, organ pipe, sawtooth, gaussian, adversarial
8 visualization modes - Bars (CAVA-style gradient), horizontal, dots, heatmap, braille, block, numeric, motion trails
Real-time metrics - Comparisons, swaps, writes, reads, allocations, recursion depth
Live complexity overlay - Watch O(n), O(n log n), O(n²) emerge in real-time

🔬 Analysis

Full operation tracing - Every compare, swap, write, read captured with msgspec
Statistical benchmarking - Warmup phase, outlier removal, percentile metrics
ELO tournament arena - Algorithms compete in round-robin with ELO ratings
Trace replay - Step forward/backward through any recorded sort with debugger-like controls

🖥 Terminal UI

Responsive Textual dashboard - Real-time updates at 60 FPS
Keyboard-driven - All controls accessible without a mouse
Theme support - Dark/light themes with rich color schemes
Live visualization - Watch sorting algorithms execute element-by-element

🔌 Extensibility

Plugin system - Add algorithms, datasets, and visualizers without modifying core
Multi-format export - JSON, CSV, Markdown, HTML
Session recording - Save and restore complete experiments

Installation

pip install perm # coming soon...

Or install from source:

git clone https://github.com/programmersd21/perm.git
cd perm
pip install -e ".[dev]"

Quick Start

Run the Terminal UI

perm-ui

Run a Single Sort

perm run --algorithm QuickSort --dataset Random --size 100

Watch Sort Animation (CAVA-style)

perm run --algorithm QuickSort --dataset Random --size 50 --viz

Cycle through visualization modes during animation:

perm run --algorithm QuickSort --dataset Random --size 50 --viz --viz-mode dots
perm run --algorithm QuickSort --dataset Random --size 50 --viz --viz-mode heatmap
perm run --algorithm QuickSort --dataset Random --size 50 --viz --viz-mode braille
perm run --algorithm QuickSort --dataset Random --size 50 --viz --viz-mode block

Adjust animation speed:

perm run --algorithm QuickSort --dataset Random --size 100 --viz --fps 60

Benchmark an Algorithm

perm benchmark --algorithm QuickSort --dataset Random --size 10000 --iterations 10

Run an Algorithm Tournament

perm arena BubbleSort QuickSort MergeSort --datasets Random Reversed --sizes 1000 5000

Replay a Trace

perm replay trace.permdata

Export Results

perm export --format json --algorithm QuickSort --dataset Random --size 10000

Commands

Command	Description
`perm run`	Run a single sort and display results. Use `--viz` for CAVA-style live animation, `--viz-mode` to switch visualizer, `--fps` to control speed
`perm benchmark`	Run statistically sound benchmarks
`perm arena`	Run algorithm tournaments with ELO rankings
`perm replay`	Replay a sorting trace
`perm datasets`	List or generate datasets
`perm export`	Export benchmark results
`perm plugins`	Manage plugins
`perm config`	View or edit configuration
`perm-ui`	Launch the Textual terminal UI

Configuration

Perm uses a perm.toml configuration file:

[perm]
theme = "dark"
fps = 60
visualizer = "heatmap"
dataset_size = 10000
benchmark_iterations = 10
benchmark_warmup = 3
trace_buffer_size = 1000000
replay_fps = 30
bar_max_elements = 200
export_dir = "./exports"
plugin_dirs = ["./plugins"]

Config file search order:

$PERM_CONFIG_DIR/perm.toml
./perm.toml
~/.config/perm/perm.toml
~/.perm.toml

Visualization Modes

Bars (CAVA-style)

Beautiful gradient bars with state-colored highlights and smooth Unicode block edges:

▂▃▅▇█████▇▅▃▂▁

Gradient transitions from deep blue (bottom) → cyan (middle) → pale white (top).

Keybinding	Action
`Space`	Play/Pause animation
`→`	Step forward one frame
`←`	Step backward one frame
`Home`	Jump to start
`End`	Jump to end
`q` / `Escape`	Quit

Horizontal Bars

Left-to-right gradient bars, each row is one element:

████████████░░░░
██████░░░░░░░░░░
████████████████

Dots

· · • • ● ● · · •

Heatmap

░ ▒ ▓ █ ▓ ▒ ░

Braille

High-density dot-matrix rendering using Unicode braille characters:

⣀⣄⣆⣇⣤⣦⣧⣷⣿

Block

Multi-row block rendering with partial block characters:

████
████
 ██

Numeric

42 17 85 3 91 56

Motion Trails

Track element movement history with fading trails.

Algorithms

Category	Algorithm	Complexity
Basic	Bubble Sort	O(n²)
Basic	Selection Sort	O(n²)
Basic	Insertion Sort	O(n²)
Intermediate	Merge Sort	O(n log n)
Intermediate	Quick Sort	O(n log n)
Intermediate	Heap Sort	O(n log n)
Intermediate	Shell Sort	O(n log² n)
Advanced	TimSort	O(n log n)
Advanced	IntroSort	O(n log n)
Advanced	PDQSort	O(n log n)
Advanced	Radix Sort	O(nk)
Advanced	Bitonic Sort	O(log² n)
Advanced	Cycle Sort	O(n²)

Plugins

Create a file in the plugins/ directory:

from perm.plugins.base import AlgorithmPlugin
from perm.algorithms.base import SortAlgorithm

class MySort(SortAlgorithm):
    name = "MySort"
    def sort(self, data): return sorted(data)

class MyPlugin(AlgorithmPlugin):
    name = "my-sort"
    def get_algorithm(self): return MySort

See the Plugin Guide for details.

Architecture

┌──────────────────────────────────────────────────┐
│                   CLI (Typer)                     │
├──────────────────────────────────────────────────┤
│                   TUI (Textual)                   │
├──────────────────────────────────────────────────┤
│  Algorithms │ Datasets │ Tracing │ Metrics        │
│  Visualizer │ Benchmarks │ Arena │ Replay         │
│  Exporters │ Plugins │ Config                     │
└──────────────────────────────────────────────────┘

See Architecture Docs for details.

Benchmarks

QuickSort on 10,000 elements:

┌──────────────────────────────────────────────────┐
│  Mean:    1.234 ms     P95:    1.456 ms           │
│  Median:  1.210 ms     P99:    1.567 ms           │
│  StdDev:  0.089 ms                                │
│  Comparisons:  147,210   Swaps:  42,118           │
└──────────────────────────────────────────────────┘

Performance

100,000+ elements - Handled with ease
Millions of trace events - Efficient msgspec serialization
60 FPS visualization - Non-blocking async Textual rendering
Sub-millisecond timing - Nanosecond precision instrumentation

Contributing

Contributions are welcome! See the Developer Guide.

Fork the repository
Create a feature branch (git checkout -b feature/amazing)
Commit changes (git commit -am 'Add amazing feature')
Push to branch (git push origin feature/amazing)
Open a Pull Request

License

MIT

GitHub Topics

Add these 20 tags to the repository for discoverability:

sorting-visualization, sorting-algorithms, algorithm-visualization, terminal-app,
cli-tool, benchmarking, data-structures, python, textual, rich,
algorithm-analysis, performance-analysis, educational, developer-tools,
sorting-algorithm-visualizer, ascii-animation, cava-style, data-visualization,
profiling, debugger

Perm - The Sorting Observatory
_{Built with Python, Textual, Rich, NumPy, msgspec, and ❤️}

GeezerVison

Latest commit

History

Folders and files

Repository files navigation