Psianimator MCP

🚀 PsiAnimator - MCP

一款集成量子物理计算与可视化功能的服务器，结合QuTip进行量子计算，利用Manim实现可视化展示

🚀 快速开始

1. 启动服务器

• 默认（通过MCP协议提供服务）：

psianimator-mcp

• 显式使用Stdio传输：

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()
    
    # 创建处于 |0⟩ 状态的量子比特
    result = await create_quantum_state({
        'state_type': 'pure',
        'system_dims': [2],
        'parameters': {'state_indices': [0]},
        'basis': 'computational'
    }, config)
    
    state_id = result['state_id']
    
    # 测量 ⟨σ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())

✨ 主要特性

• 🔬 量子物理引擎：具备完整的状态管理、时间演化和测量工具。
• 🎬 Manim动画：可生成具有出版质量的量子特定场景可视化效果。
• 🔌 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上可用时）

# 核心安装（仅量子计算）
pip install psianimator-mcp

# 包含动画支持的完整安装
pip install "psianimator-mcp[animation]"

# 开发安装
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（用于视频生成）
• Cairo图形库（用于高质量渲染）

安装选项说明

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

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（数据分析）

安装后设置

安装完成后，运行设置命令：

psianimator-mcp setup

这将：

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

验证安装

检查安装状态：

python -c "import psianimator_mcp; print(f'✅ 核心: OK, 动画: {psianimator_mcp.is_animation_available()}')"

预期输出：

• ✅ 核心: OK, 动画: True - 包含动画的完整安装
• ✅ 核心: OK, 动画: False - 仅核心安装

故障排除

导入错误

# 如果你遇到 "No module named 'psianimator_mcp'" 错误
pip install psianimator-mcp

# 如果你遇到与动画相关的错误
pip install "psianimator-mcp[animation]"

动画依赖项

# Ubuntu/Debian
sudo apt-get install texlive-latex-base ffmpeg libcairo2-dev

# macOS
brew install mactex ffmpeg cairo

# Windows
# 从官方网站安装MiKTeX、FFmpeg

💻 使用示例

基础用法

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()
    
    # 创建处于 |0⟩ 状态的量子比特
    result = await create_quantum_state({
        'state_type': 'pure',
        'system_dims': [2],
        'parameters': {'state_indices': [0]},
        'basis': 'computational'
    }, config)
    
    state_id = result['state_id']
    
    # 测量 ⟨σ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())

高级用法

# 此处可添加高级场景说明，例如使用更多复杂的量子操作和动画生成等
# 示例代码可根据实际情况补充

📚 详细文档

Claude Desktop集成

自动配置

生成Claude Desktop配置：

psianimator-mcp claude-config

手动配置

将以下内容添加到Claude Desktop配置文件中：

• 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

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

注意：配置更改后，请重启Claude Desktop。

MCP工具

1. create_quantum_state

创建各种类型的量子态：

• 纯态：|ψ⟩（态矢量）
• 混合态：ρ（密度矩阵）
• 相干态：|α⟩（谐振子）
• 压缩态：降低不确定性
• 热态：有限温度
• 福克态：确定的光子数

2. evolve_quantum_system

使用多种方法进行时间演化：

• 幺正演化：薛定谔方程（封闭系统）
• 主方程：林德布拉德形式（开放系统）
• 蒙特卡罗方法：量子轨迹
• 随机方法：连续测量

3. measure_observable

量子测量和分析：

• 期望值：⟨O⟩
• 方差：Δ²O
• 概率分布：P(结果)
• 关联函数：⟨A⟩⟨B⟩

4. animate_quantum_process

生成Manim动画：

• 布洛赫球演化：量子比特动力学
• 维格纳函数：相空间表示
• 状态层析：密度矩阵可视化
• 电路执行：门序列动画
• 能级：粒子数动力学

5. quantum_gate_sequence

应用量子门并可视化：

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

6. calculate_entanglement

计算纠缠度量：

• 冯·诺伊曼熵：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/websocket）
  • PSIANIMATOR_HOST - WebSocket传输的主机
  • PSIANIMATOR_PORT - WebSocket传输的端口
• 量子设置：
  • PSIANIMATOR_QUANTUM_PRECISION - 量子计算精度
  • PSIANIMATOR_MAX_HILBERT_DIM - 最大希尔伯特空间维度
  • PSIANIMATOR_OUTPUT_DIR - 动画输出目录

示例：

export PSIANIMATOR_TRANSPORT=websocket
export PSIANIMATOR_PORT=3001
psianimator-mcp

CLI命令

PsiAnimator - MCP提供了多个CLI命令：

psianimator-mcp                    # 启动服务器（默认：stdio）
psianimator-mcp serve              # 带选项启动服务器
psianimator-mcp config             # 显示当前配置
psianimator-mcp setup              # 运行安装后设置
psianimator-mcp test               # 测试安装
psianimator-mcp claude-config      # 生成Claude Desktop配置
psianimator-mcp examples           # 显示使用示例
psianimator-mcp version            # 显示版本
psianimator-mcp --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服务器实现
│   ├── quantum/         # 量子物理引擎
│   ├── animation/       # Manim可视化组件
│   └── tools/           # MCP工具实现
├── tests/               # 全面的测试套件
├── examples/            # 使用示例
└── docs/               # 文档

局限性

• 动画渲染需要足够的系统资源。
• 大希尔伯特空间（>1024维）可能会影响性能。
• 一些高级量子纠错功能尚未实现。

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE。

贡献

我们欢迎贡献！请参阅CONTRIBUTING.md了解：

• 开发指南
• 代码标准
• 测试要求
• 拉取请求流程

支持

• 文档：请参阅docs/API_REFERENCE.md
• 示例：查看examples/目录
• 问题反馈：通过GitHub issues报告错误