PsiAnimator-MCP

# PsiAnimator-MCP **Quantum Physics Simulation and Animation Server** A Model Context Protocol (MCP) server that integrates [QuTip](https://qutip.org/) (Quantum Toolbox in Python) for quantum physics computations with [Manim](https://www.manim.community/) (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) ```bash curl -fsSL https://raw.githubusercontent.com/username/PsiAnimator-MCP/main/scripts/install.sh | bash ``` #### Option 2: PowerShell (Windows) ```powershell iwr https://raw.githubusercontent.com/username/PsiAnimator-MCP/main/scripts/install.ps1 | iex ``` #### Option 3: pip (when available on PyPI) ```bash # Core installation (quantum computation only) pip install psianimator-mcp # Full installation with animation support pip install "psianimator-mcp[animation]" # Development installation pip install "psianimator-mcp[dev,animation]" ``` #### Option 4: From source ```bash git clone https://github.com/username/PsiAnimator-MCP.git cd PsiAnimator-MCP ./scripts/install.sh --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) ```bash pip install psianimator-mcp ``` - Includes all quantum computation features - MCP server functionality - QuTip, NumPy, SciPy for quantum physics - Works immediately without system dependencies **🎬 Animation Installation** (For visualization) ```bash pip install "psianimator-mcp[animation]" ``` - Everything from core installation - Manim for generating animations - Requires system dependencies (LaTeX, FFmpeg) - Larger download and installation time **🔧 Development Installation** ```bash git clone https://github.com/username/PsiAnimator-MCP.git cd PsiAnimator-MCP pip install -e ".[dev,animation]" ``` ### 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: ```bash psianimator-mcp setup ``` 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: ```bash python -c "import psianimator_mcp; print(f'✅ Core: OK, Animation: {psianimator_mcp.is_animation_available()}')" ``` Expected outputs: - `✅ Core: OK, Animation: True` - Full installation with animations - `✅ Core: OK, Animation: False` - Core installation only ### Troubleshooting **Import Errors** ```bash # If you get "No module named 'psianimator_mcp'" pip install psianimator-mcp # If you get animation-related errors pip install "psianimator-mcp[animation]" ``` **Animation Dependencies** ```bash # Ubuntu/Debian sudo apt-get install texlive-latex-base ffmpeg libcairo2-dev # macOS brew install mactex ffmpeg cairo # Windows # Install MiKTeX, FFmpeg from official websites ``` ## Claude Desktop Integration ### Automatic Configuration Generate Claude Desktop configuration: ```bash psianimator-mcp claude-config ``` ### 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` ```json { "mcpServers": { "psianimator-mcp": { "command": "python3", "args": ["-m", "psianimator_mcp.cli", "serve"], "env": { "PSIANIMATOR_CONFIG": "~/.config/psianimator-mcp/config.json" } } } } ``` **Note:** Restart Claude Desktop after configuration changes. ## Quick Start ### 1. Start the Server **Default (serves via MCP protocol):** ```bash psianimator-mcp ``` **Stdio transport explicitly:** ```bash psianimator-mcp serve --transport stdio ``` **WebSocket transport:** ```bash psianimator-mcp serve --transport websocket --port 3000 ``` ### 2. Test Installation ```bash psianimator-mcp test ``` ### 3. Basic Usage Example ```python import asyncio from psianimator_mcp.tools.quantum_state_tools import create_quantum_state from psianimator_mcp.tools.measurement_tools import measure_observable from psianimator_mcp.server.config import MCPConfig async def basic_example(): config = MCPConfig() # Create a qubit in |0⟩ state result = await create_quantum_state({ 'state_type': 'pure', 'system_dims': [2], 'parameters': {'state_indices': [0]}, 'basis': 'computational' }, config) state_id = result['state_id'] # Measure ⟨σz⟩ measurement = await measure_observable({ 'state_id': state_id, 'observable': 'sigmaz', 'measurement_type': 'expectation' }, config) print(f"⟨σz⟩ = {measurement['measurement_results']['expectation_value']}") asyncio.run(basic_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`: ```python from psianimator_mcp.server.config import MCPConfig config = MCPConfig( quantum_precision=1e-12, max_hilbert_dimension=1024, animation_cache_size=100, output_directory="./output", render_backend="cairo" ) ``` ### 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: ```bash export PSIANIMATOR_TRANSPORT=websocket export PSIANIMATOR_PORT=3001 psianimator-mcp ``` ## CLI Commands PsiAnimator-MCP provides several CLI commands: ```bash psianimator-mcp # Start server (default: stdio) psianimator-mcp serve # Start server with options psianimator-mcp config # Show current configuration psianimator-mcp setup # Run post-installation setup psianimator-mcp test # Test installation psianimator-mcp claude-config # Generate Claude Desktop config psianimator-mcp examples # Show usage examples psianimator-mcp version # Show version psianimator-mcp --help # Show help ``` ### Command Examples **Start with custom config:** ```bash psianimator-mcp serve --config /path/to/config.json ``` **WebSocket mode:** ```bash psianimator-mcp serve --transport websocket --host 0.0.0.0 --port 8080 ``` **Verbose logging:** ```bash psianimator-mcp serve -vvv ``` ## 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: ```bash python examples/basic_usage.py ``` ## Development ### Setup Development Environment ```bash git clone https://github.com/username/PsiAnimator-MCP.git cd PsiAnimator-MCP pip install -e ".[dev]" pre-commit install ``` ### Run Tests ```bash pytest tests/ ``` ### Code Quality ```bash black src/ tests/ isort src/ tests/ mypy src/ ``` ## Architecture ``` PsiAnimator-MCP/ ├── src/psianimator_mcp/ │ ├── server/ # MCP server implementation │ ├── quantum/ # Quantum physics engine │ ├── animation/ # Manim visualization components │ └── tools/ # MCP tool implementations ├── tests/ # Comprehensive test suite ├── examples/ # Usage examples └── docs/ # Documentation ``` ## 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](LICENSE) for details. ## Contributing We welcome contributions! Please see [CONTRIBUTING.md](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