PsiAnimator-MCP

Quantum Physics Simulation and Animation Server

A Model Context Protocol (MCP) server that integrates QuTip (Quantum Toolbox in Python) for quantum physics computations with Manim (Mathematical Animation Engine) for visualization.

Features

• 🔬 Quantum Physics Engine: Complete state management, time evolution, and measurement tools

• 🎬 Manim Animations: Publication-quality visualizations with quantum-specific scenes

• 🔌 MCP Integration: Seamless integration with MCP-compatible clients

• 🧮 Scientific Computing: Built on NumPy, SciPy, and QuTip for accuracy

• 📊 Visualization Types: Bloch spheres, Wigner functions, state tomography, circuits

• 🎓 Educational Focus: Perfect for quantum mechanics education and research

Installation

Quick Install

Option 1: One-line install (Unix/macOS)

Option 2: PowerShell (Windows)

Option 3: pip (when available on PyPI)

Option 4: From source

Prerequisites

• Python ≥ 3.10

• Git (for development installation)

For animation features:

• LaTeX (for advanced mathematical rendering)

• FFmpeg (for video generation)

• Cairo graphics library (for high-quality rendering)

Installation Options Explained

🚀 Core Installation (Recommended for most users)

• Includes all quantum computation features

• MCP server functionality

• QuTip, NumPy, SciPy for quantum physics

• Works immediately without system dependencies

🎬 Animation Installation (For visualization)

• Everything from core installation

• Manim for generating animations

• Requires system dependencies (LaTeX, FFmpeg)

• Larger download and installation time

🔧 Development Installation

Why Animation is Optional

Animation features (Manim) are kept optional because:

• Heavy Dependencies: Manim requires LaTeX, FFmpeg, and Cairo which can be several GB

• Installation Complexity: System dependencies can fail on different platforms

• Use Case Separation: Many users only need quantum computation, not visualization

• CI/Testing Reliability: Core features can be tested without system dependencies

• Disk Space: Core installation is ~100MB vs ~2GB+ with full animation stack

Dependencies

Core dependencies (automatically installed):

• QuTip ≥ 4.7.0 (quantum physics computations)

• MCP ≥ 1.0.0 (Model Context Protocol)

• NumPy, SciPy, matplotlib (scientific computing)

• Pydantic, aiohttp (async web framework)

Animation dependencies (optional extras):

• Manim ≥ 0.18.0 (mathematical animations)

• h5py ≥ 3.9.0 (data storage)

• pandas ≥ 2.0.0 (data analysis)

Post-Installation Setup

After installation, run the setup command:

This will:

• Create configuration directory (~/.config/psianimator-mcp/)

• Copy example configuration file

• Test installation and show feature availability

• Provide Claude Desktop integration instructions

Verifying Installation

Check your installation status:

Expected outputs:

• ✅ Core: OK, Animation: True - Full installation with animations

• ✅ Core: OK, Animation: False - Core installation only

Troubleshooting

Import Errors

Animation Dependencies

Claude Desktop Integration

Automatic Configuration

Generate Claude Desktop configuration:

Manual Configuration

Add to your Claude Desktop configuration file:

Windows: %USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/claude-desktop/claude_desktop_config.json

Note: Restart Claude Desktop after configuration changes.

Quick Start

1. Start the Server

Default (serves via MCP protocol):

Stdio transport explicitly:

WebSocket transport:

2. Test Installation

3. Basic Usage Example

MCP Tools

1. create_quantum_state

Create quantum states of various types:

• Pure states: |ψ⟩ (ket vectors)

• Mixed states: ρ (density matrices)

• Coherent states: |α⟩ (harmonic oscillator)

• Squeezed states: reduced uncertainty

• Thermal states: finite temperature

• Fock states: definite photon number

2. evolve_quantum_system

Time evolution with multiple methods:

• Unitary: Schrödinger equation (closed systems)

• Master equation: Lindblad form (open systems)

• Monte Carlo: Quantum trajectories

• Stochastic: Continuous measurement

3. measure_observable

Quantum measurements and analysis:

• Expectation values: ⟨O⟩

• Variances: Δ²O

• Probability distributions: P(outcome)

• Correlation functions: ⟨A⟩⟨B⟩

4. animate_quantum_process

Generate Manim animations:

• Bloch sphere evolution: Qubit dynamics

• Wigner functions: Phase space representation

• State tomography: Density matrix visualization

• Circuit execution: Gate sequence animation

• Energy levels: Population dynamics

5. quantum_gate_sequence

Apply quantum gates with visualization:

• Single-qubit gates: Pauli, Hadamard, rotations

• Two-qubit gates: CNOT, CZ, SWAP

• Parameterized gates: RX, RY, RZ with custom angles

• Circuit visualization: Step-by-step animation

6. calculate_entanglement

Compute entanglement measures:

• Von Neumann entropy: S(ρ) = -Tr(ρ log ρ)

• Concurrence: Two-qubit entanglement measure

• Negativity: Partial transpose criterion

• Mutual information: I(A:B)

Configuration

Configure via environment variables or MCPConfig:

Environment Variables

Configure PsiAnimator-MCP via environment variables:

Server Configuration:

• PSIANIMATOR_CONFIG - Path to configuration file

• PSIANIMATOR_TRANSPORT - Transport protocol (stdio/websocket)

• PSIANIMATOR_HOST - Host for WebSocket transport

• PSIANIMATOR_PORT - Port for WebSocket transport

Quantum Settings:

• PSIANIMATOR_QUANTUM_PRECISION - Quantum computation precision

• PSIANIMATOR_MAX_HILBERT_DIM - Maximum Hilbert space dimension

• PSIANIMATOR_OUTPUT_DIR - Output directory for animations

Example:

CLI Commands

PsiAnimator-MCP provides several CLI commands:

Command Examples

Start with custom config:

WebSocket mode:

Verbose logging:

Examples

Comprehensive examples are provided in the examples/ directory:

• basic_usage.py - Core functionality walkthrough

• Bell state creation and entanglement analysis

• Harmonic oscillator coherent state evolution

• Multi-qubit quantum circuits

Run examples:

Development

Setup Development Environment

Run Tests

Code Quality

Architecture

Limitations

• Animation rendering requires sufficient system resources

• Large Hilbert spaces (>1024 dimensions) may impact performance

• Some advanced quantum error correction features are not yet implemented

License

MIT License - see LICENSE for details.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development guidelines

• Code standards

• Testing requirements

• Pull request process

Support

• Documentation: See docs/API_REFERENCE.md

• Examples: Check examples/ directory

• Issues: Report bugs via GitHub issues