Psianimator MCP

🚀 PsiAnimator-MCP

量子物理学のシミュレーションとアニメーションを行うサーバーです。量子物理学の計算にQuTip（Pythonによる量子ツールボックス）を、視覚化にManim（数学的アニメーションエンジン）を統合したModel Context Protocol (MCP) サーバーです。

✨ 主な機能

• 🔬 量子物理学エンジン：完全な状態管理、時間発展、測定ツールを備えています。
• 🎬 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 (Model Context Protocol)
• 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'✅ Core: OK, Animation: {psianimator_mcp.is_animation_available()}')"

期待される出力は以下の通りです。

• ✅ Core: OK, Animation: True - アニメーション付きの完全インストール
• ✅ Core: OK, Animation: 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をインストールします。

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を再起動してください。

🚀 クイックスタート

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

💻 使用例

基本的な使用法

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

高度な使用法

# 高度なシナリオでの使用例
# 例えば、複数の量子状態を作成し、時間発展させ、測定するなどの操作を行う
import asyncio
from psianimator_mcp.tools.quantum_state_tools import create_quantum_state
from psianimator_mcp.tools.evolve_quantum_system import evolve_quantum_system
from psianimator_mcp.tools.measurement_tools import measure_observable
from psianimator_mcp.server.config import MCPConfig

async def advanced_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']
    
    # 量子システムを時間発展させる
    evolved_state_id = await evolve_quantum_system({
        'state_id': state_id,
        'evolution_method': 'unitary',
        'time': 1.0
    }, config)
    
    # ⟨σz⟩を測定する
    measurement = await measure_observable({
        'state_id': evolved_state_id,
        'observable': 'sigmaz',
        'measurement_type': 'expectation'
    }, config)
    
    print(f"⟨σz⟩ = {measurement['measurement_results']['expectation_value']}")

asyncio.run(advanced_example())

📚 ドキュメント

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

量子ゲートを適用し、視覚化します。

• 1量子ビットゲート：パウリ、ハダマール、回転ゲート
• 2量子ビットゲート：CNOT、CZ、SWAP
• パラメータ付きゲート：RX、RY、RZ (カスタム角度)
• 回路の視覚化：ステップバイステップのアニメーション

6. calculate_entanglement

エンタングルメントの測定値を計算します。

• ヴォンノイマンエントロピー：S(ρ) = -Tr(ρ log ρ)
• コンカレンス：2量子ビットのエンタングルメント測定値
• ネガティビティ：部分転置基準
• 相互情報量：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

アーキテクチャ

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を使用してバグを報告してください。