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報告錯誤