MathViz

A domain-specific language for mathematical animations

Website • Features • Installation • Quick Start • Editor • Contributing

---

MathViz is a modern programming language designed specifically for creating mathematical animations. It extends Python with a clean, math-first syntax and compiles to pure Python with first-class Manim integration.

Features

• Unicode Math Operators — Write math naturally: ∈, ⊆, ∪, ∩, ∞, π, ≤, ≥, ≠
• Clean Syntax — Modern block syntax with let, fn, scene, and pattern matching
• Manim Integration — First-class support for creating mathematical animations
• Static Analysis — Built-in check, analyze, typecheck, lint, and fmt commands
• Module System — Multi-file projects with use imports
• Desktop Editor — Cross-platform editor with live preview (Tauri + React)
• VS Code Extension — Syntax highlighting, snippets, and bracket matching for VS Code
• Auto-update — Automatic update detection with PyPI version check
• Fast Iteration — REPL mode and file watcher for rapid development

Installation

Using pipx (Recommended)

pipx install mathviz

Using pip

pip install mathviz

From source

git clone https://github.com/CyberSnakeH/MathViz.git
cd MathViz
uv sync --dev

Prerequisites

• Python 3.12 or higher
• Manim (for animations)
• LaTeX (optional, for math rendering)

Quick Start

Hello World

Create a file hello.mviz:

fn main() {
    println("Hello, MathViz!")
}

Run it:

mathviz exec hello.mviz

Your First Animation

Create animation.mviz:

from manim import Circle, Create, FadeOut

scene CircleAnimation {
    fn construct(self) {
        let circle = Circle()
        circle.set_color(BLUE)

        self.play(Create(circle))
        self.wait(1)
        self.play(FadeOut(circle))
    }
}

Run with preview:

mathviz run animation.mviz --preview

Language Features

// Variables with type inference
let x = 42
let name = "MathViz"
let pi = 3.14159

// Functions with type annotations
fn add(a: int, b: int) -> int {
    return a + b
}

// Pattern matching
let result = match x {
    0 -> "zero"
    1 -> "one"
    _ -> "other"
}

// For loops with ranges
for i in 0..10 {
    println(i)
}

// List comprehensions
let squares = [x^2 for x in 1..=10]

// Unicode math
let is_member = 5 ∈ {1, 2, 3, 4, 5}
let union = {1, 2} ∪ {3, 4}

CLI Reference

# Compile to Python
mathviz compile file.mviz -o output.py

# Run with Manim (animations)
mathviz run file.mviz --preview

# Execute script (no Manim)
mathviz exec file.mviz

# Static analysis
mathviz check file.mviz      # Syntax check
mathviz typecheck file.mviz  # Type check
mathviz analyze file.mviz    # Full analysis
mathviz lint file.mviz       # Linter

# Formatting
mathviz fmt file.mviz

# Development
mathviz watch src/           # Watch mode
mathviz repl                 # Interactive REPL

# Project management
mathviz new my-project       # Create new project
mathviz build                # Build project
mathviz test                 # Run tests

VS Code Extension

Install the MathViz extension for VS Code with syntax highlighting, 18 code snippets, and smart bracket matching.

cd vscode-mathviz
npx @vscode/vsce package
code --install-extension mathviz-0.1.0.vsix

Open any .mviz or .mvz file and the extension activates automatically.

Editor

MathViz includes a cross-platform desktop editor built with Tauri and React.

Features

• Syntax highlighting for .mviz files
• Live animation preview
• Integrated terminal
• File explorer
• Command palette (Ctrl+P)

Keyboard Shortcuts

Shortcut	Action
F5	Run with Manim
F6	Execute script
F8	Compile only
Ctrl+S	Save
Ctrl+P	Command palette
Ctrl+B	Toggle sidebar
Ctrl+J	Toggle terminal

Running the Editor

cd editor
npm install
npm run tauri dev

Building

npm run tauri build

Binaries will be in editor/src-tauri/target/release/bundle/.

Project Structure

MathViz/
├── src/mathviz/          # Compiler and runtime
│   ├── compiler/         # Lexer, parser, codegen
│   ├── utils/            # Errors, diagnostics
│   └── cli.py            # CLI entry point
├── editor/               # Desktop editor (Tauri)
│   ├── src/              # React frontend
│   └── src-tauri/        # Rust backend
├── vscode-mathviz/       # VS Code extension
│   ├── syntaxes/         # TextMate grammar
│   └── snippets/         # Code snippets
├── examples/             # Example programs
├── tests/                # Test suite
└── docs/                 # Documentation

Examples

Explore the examples/ directory:

• hello_world.mviz — Basic syntax
• circle_animation.mviz — Simple animation
• set_operations.mviz — Unicode math
• venn_diagram.mviz — Complex animation
• multimodule/ — Multi-file project

Development

Running Tests

uv run pytest

Code Quality

# Format
uv run ruff format src tests

# Lint
uv run ruff check src tests

# Type check
uv run mypy src

Language Server

pip install -e ".[lsp]"
mathviz-lsp

Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

• Development environment setup
• Code style and conventions
• Commit message guidelines
• Testing requirements
• Pull request process

Quick start:

# Fork and clone
git clone https://github.com/CyberSnakeH/MathViz.git
cd MathViz

# Create a branch
git checkout -b feature/my-feature

# Make changes, then submit a PR

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Manim Community — The animation engine
• Tauri — Desktop app framework
• Monaco Editor — Code editor

---

Made with ❤️ by CyberSnakeH