Psi Animator MCP

PsiAnimator MCP

量子物理仿真与动画服务器

集成了模型上下文协议（MCP）的服务器 QuTip （Python中的Quantum Toolbox）用于量子物理计算 马尼姆 （数学动画引擎）用于可视化。

特性

• 🔬 量子物理引擎：完整的状态管理、时间演化和测量工具
• 🎬 人偶动画：具有量子特定场景的出版物质量可视化
• 🔌 MCP集成：与MCP兼容客户端无缝集成
• 🧮 科学计算：基于NumPy、SciPy和QuTip构建，以提高准确性
• 📊 可视化类型：布洛赫球、维格纳函数、状态层析成像、电路
• 🎓 教育重点：非常适合量子力学教育和研究

安装

快速安装

选项1：一行安装（Unix/macOS）

curl -fsSL https://raw.githubusercontent.com/username/PsiAnimator-MCP/main/scripts/install.sh | bash

选项2:PowerShell（Windows）

iwr https://raw.githubusercontent.com/username/PsiAnimator-MCP/main/scripts/install.ps1 | iex

选项3:pip（在PyPI上可用时）

# 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]"

选项4：来源

git clone https://github.com/username/PsiAnimator-MCP.git
cd PsiAnimator-MCP
./scripts/install.sh --from-source

先决条件

• Python≥3.10
• Git（用于开发安装）

对于动画功能：

• LaTeX（用于高级数学渲染）
• FFmpeg（用于视频生成）
• 开罗图形库（用于高质量渲染）

安装选项说明

🚀 核心安装 （推荐给大多数用户）

pip install psianimator-mcp

• 包括所有量子计算功能
• MCP服务器功能
• 量子物理学的QuTip、NumPy、SciPy
• 无需系统依赖即可立即工作

🎬 动画装置 （用于可视化）

pip install "psianimator-mcp[animation]"

• 从核心安装到一切
• 用于生成动画的Manim
• 需要系统依赖关系（LaTeX、FFmpeg）
• 下载和安装时间更长

🔧 开发安装

git clone https://github.com/username/PsiAnimator-MCP.git
cd PsiAnimator-MCP
pip install -e ".[dev,animation]"

为什么动画是可选的

动画功能（Manim）保持可选，因为：

• 严重依赖：Manim需要LaTeX、FFmpeg和Cairo，可以是几GB
• 安装复杂性：系统依赖关系可能在不同平台上失败
• 用例分离：许多用户只需要量子计算，而不需要可视化
• CI/测试可靠性：核心功能可以在没有系统依赖的情况下进行测试
• 磁盘空间：核心安装约为100MB，而具有完整动画堆栈的约为2GB

依赖项

核心依赖关系 （自动安装）：

• QuTip≥4.7.0（量子物理计算）
• MCP≥1.0.0（模型上下文协议）
• NumPy、SciPy、matplotlib（科学计算）
• Pydantic，aiohttp（异步web框架）

动画依赖关系 （可选附加功能）：

• Manim≥0.18.0（数学动画）
• h5py≥3.9.0（数据存储）
• pandas≥2.0.0（数据分析）

安装后设置

安装后，运行setup命令：

psianimator-mcp setup

这将：

• 创建配置目录(~/.config/psianimator-mcp/)
• 复制示例配置文件
• 测试安装并显示功能可用性
• 提供Claude Desktop集成说明

验证安装

检查您的安装状态：

python -c "import psianimator_mcp; print(f'✅ Core: OK, Animation: {psianimator_mcp.is_animation_available()}')"

预期产出：

• ✅ Core: OK, Animation: True -带动画的完整安装
• ✅ Core: OK, Animation: False -仅安装核心

故障排除

导入错误

# If you get "No module named 'psianimator_mcp'"
pip install psianimator-mcp

# If you get animation-related errors
pip install "psianimator-mcp[animation]"

动画依赖关系

# 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桌面集成

自动配置

生成Claude桌面配置：

psianimator-mcp claude-config

手动配置

添加到您的Claude Desktop配置文件中：

窗户： %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

{
  "mcpServers": {
    "psianimator-mcp": {
      "command": "python3",
      "args": ["-m", "psianimator_mcp.cli", "serve"],
      "env": {
        "PSIANIMATOR_CONFIG": "~/.config/psianimator-mcp/config.json"
      }
    }
  }
}

注： 配置更改后重新启动Claude Desktop。

快速开始

1.启动服务器

默认值（通过MCP协议服务）：

psianimator-mcp

标准运输明确：

psianimator-mcp serve --transport stdio

WebSocket传输：

psianimator-mcp serve --transport websocket --port 3000

2.测试安装

psianimator-mcp test

3.基本使用示例

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工具

1. create_quantum_state

创建各种类型的量子态：

• 纯态：.ψ⟩（ket向量）
• 混合状态：ρ（密度矩阵）
• 相干态：|α⟩（谐振子）
• 压缩态：减少不确定性
• 热状态：有限温度
• 福克州：确定光子数

2. evolve_quantum_system

多种方法的时间演化：

• 统一：薛定谔方程（闭系统）
• 主方程式：Lindblad形式（开放系统）
• 蒙特卡洛：量子轨迹
• 随机：连续测量

3. measure_observable

量子测量和分析：

• 期望值：⟨O⟩
• 总体的方差：Δ²O
• 概率分布：P（结果）
• 相关函数：⟨A⟪B⟩

4. animate_quantum_process

生成动画：

• 布洛赫球演化：Qubit动力学
• 维格纳函数：相空间表示
• 状态断层扫描：密度矩阵可视化
• 电路执行：门序列动画
• 能级：人口动态

5. quantum_gate_sequence

将量子门应用于可视化：

• 单量子比特门：泡利，阿达玛，旋转
• 两个量子比特门CNOT，CZ，SWAP
• 参数化闸门：RX、RY、RZ，具有自定义角度
• 电路可视化：逐步动画

6. calculate_entanglement

计算纠缠度量：

• VonNeumann熵S（ρ） = -Tr（ρ log ρ）
• 并发：双量子比特纠缠度量
• 消极性：部分转置标准
• 相互信息：I（A:B）

配置

通过环境变量进行配置或 MCPConfig:

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"
)

环境变量

通过环境变量配置PsiAnimator MCP：

服务器配置：

• PSIANIMATOR_CONFIG -配置文件的路径
• PSIANIMATOR_TRANSPORT -传输协议（stdio/webocket）
• PSIANIMATOR_HOST -WebSocket传输主机
• PSIANIMATOR_PORT -WebSocket传输端口

量子设置：

• PSIANIMATOR_QUANTUM_PRECISION -量子计算精度
• PSIANIMATOR_MAX_HILBERT_DIM -最大Hilbert空间维数
• PSIANIMATOR_OUTPUT_DIR -动画输出目录

例子：

export PSIANIMATOR_TRANSPORT=websocket
export PSIANIMATOR_PORT=3001
psianimator-mcp

CLI命令

PsiAnimator MCP提供了几个CLI命令：

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

命令示例

从自定义配置开始：

psianimator-mcp serve --config /path/to/config.json

WebSocket模式：

psianimator-mcp serve --transport websocket --host 0.0.0.0 --port 8080

详细日志记录：

psianimator-mcp serve -vvv

例子

综合示例见 examples/ 目录：

• basic_usage.py -核心功能演练
• 贝尔态的产生和纠缠分析
• 谐振子相干态演化
• 多量子比特量子电路

运行示例：

python examples/basic_usage.py

发展

设置开发环境

git clone https://github.com/username/PsiAnimator-MCP.git
cd PsiAnimator-MCP
pip install -e ".[dev]"
pre-commit install

运行测试

pytest tests/

代码质量

black src/ tests/
isort src/ tests/
mypy src/

建筑

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

局限性

• 动画渲染需要足够的系统资源
• 大Hilbert空间（>1024维）可能会影响性能
• 一些先进的量子纠错功能尚未实现

许可证

MIT许可证-请参阅 许可证 了解详情。

贡献

我们欢迎捐款！请看 贡献.md 用于：

• 开发指南
• 编码规范
• 测试要求
• 拉取请求流程

支持

• 文档：参见 docs/API_REFERENCE.md
• 例子：检查 examples/ 目录
• 问题：通过GitHub问题报告bug