PsiAnimator-MCP

Um servidor para simulação e animação de física quântica, utilizando QuTip para cálculos e Manim para visualizações.

Documentação

PsiAnimator-MCP

Servidor de Simulação e Animação de Física Quântica

Um servidor Model Context Protocol (MCP) que integra QuTip (Quantum Toolbox em Python) para cálculos de física quântica com Manim (Motor de Animação Matemática) para visualização.

Recursos

🔬 Motor de Física Quântica: Gerenciamento completo de estados, evolução temporal e ferramentas de medição
🎬 Animações Manim: Visualizações de qualidade de publicação com cenas específicas para quântica
🔌 Integração MCP: Integração perfeita com clientes compatíveis com MCP
🧮 Computação Científica: Construído sobre NumPy, SciPy e QuTip para precisão
📊 Tipos de Visualização: Esferas de Bloch, funções de Wigner, tomografia de estados, circuitos
🎓 Foco Educacional: Perfeito para educação e pesquisa em mecânica quântica

Instalação

Instalação Rápida

Opção 1: Instalação em uma linha (Unix/macOS)

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

Opção 2: PowerShell (Windows)

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

Opção 3: pip (quando disponível no 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]"

Opção 4: A partir do código-fonte

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

Pré-requisitos

Python ≥ 3.10
Git (para instalação de desenvolvimento)

Para recursos de animação:

LaTeX (para renderização matemática avançada)
FFmpeg (para geração de vídeo)
Biblioteca gráfica Cairo (para renderização de alta qualidade)

Opções de Instalação Explicadas

🚀 Instalação Principal (Recomendada para a maioria dos usuários)

pip install psianimator-mcp

Inclui todos os recursos de computação quântica
Funcionalidade do servidor MCP
QuTip, NumPy, SciPy para física quântica
Funciona imediatamente sem dependências de sistema

🎬 Instalação de Animação (Para visualização)

pip install "psianimator-mcp[animation]"

Tudo da instalação principal
Manim para gerar animações
Requer dependências de sistema (LaTeX, FFmpeg)
Download maior e tempo de instalação mais longo

🔧 Instalação de Desenvolvimento

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

Por que a Animação é Opcional

Os recursos de animação (Manim) são mantidos opcionais porque:

Dependências Pesadas: Manim requer LaTeX, FFmpeg e Cairo, que podem ocupar vários GB
Complexidade de Instalação: Dependências de sistema podem falhar em diferentes plataformas
Separação de Casos de Uso: Muitos usuários precisam apenas de computação quântica, não de visualização
Confiabilidade de CI/Testes: Recursos principais podem ser testados sem dependências de sistema
Espaço em Disco: A instalação principal é ~100MB vs ~2GB+ com a pilha completa de animação

Dependências

Dependências principais (instaladas automaticamente):

QuTip ≥ 4.7.0 (cálculos de física quântica)
MCP ≥ 1.0.0 (Model Context Protocol)
NumPy, SciPy, matplotlib (computação científica)
Pydantic, aiohttp (framework web assíncrono)

Dependências de animação (extras opcionais):

Manim ≥ 0.18.0 (animações matemáticas)
h5py ≥ 3.9.0 (armazenamento de dados)
pandas ≥ 2.0.0 (análise de dados)

Configuração Pós-Instalação

Após a instalação, execute o comando de configuração:

psianimator-mcp setup

Isso irá:

Criar o diretório de configuração (~/.config/psianimator-mcp/)
Copiar o arquivo de configuração de exemplo
Testar a instalação e mostrar a disponibilidade de recursos
Fornecer instruções de integração com Claude Desktop

Verificando a Instalação

Verifique o status da sua instalação:

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

Saídas esperadas:

✅ Core: OK, Animation: True - Instalação completa com animações
✅ Core: OK, Animation: False - Apenas instalação principal

Solução de Problemas

Erros de Importação

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

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

Dependências de Animação

# 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

Integração com Claude Desktop

Configuração Automática

Gere a configuração do Claude Desktop:

psianimator-mcp claude-config

Configuração Manual

Adicione ao seu arquivo de configuração do 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"
      }
    }
  }
}

Nota: Reinicie o Claude Desktop após alterações de configuração.

Início Rápido

1. Inicie o Servidor

Padrão (serve via protocolo MCP):

psianimator-mcp

Transporte stdio explicitamente:

psianimator-mcp serve --transport stdio

Transporte WebSocket:

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

2. Teste a Instalação

psianimator-mcp test

3. Exemplo de Uso Básico

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

Ferramentas MCP

1. `create_quantum_state`

Crie estados quânticos de vários tipos:

Estados puros: |ψ⟩ (vetores ket)
Estados mistos: ρ (matrizes densidade)
Estados coerentes: |α⟩ (oscilador harmônico)
Estados comprimidos: incerteza reduzida
Estados térmicos: temperatura finita
Estados de Fock: número definido de fótons

2. `evolve_quantum_system`

Evolução temporal com múltiplos métodos:

Unitário: Equação de Schrödinger (sistemas fechados)
Equação mestra: forma de Lindblad (sistemas abertos)
Monte Carlo: Trajetórias quânticas
Estocástico: Medição contínua

3. `measure_observable`

Medições e análises quânticas:

Valores esperados: ⟨O⟩
Variâncias: Δ²O
Distribuições de probabilidade: P(resultado)
Funções de correlação: ⟨A⟩⟨B⟩

4. `animate_quantum_process`

Gere animações Manim:

Evolução na esfera de Bloch: Dinâmica de qubits
Funções de Wigner: Representação no espaço de fase
Tomografia de estados: Visualização da matriz densidade
Execução de circuitos: Animação de sequência de portas
Níveis de energia: Dinâmica de populações

5. `quantum_gate_sequence`

Aplique portas quânticas com visualização:

Portas de qubit único: Pauli, Hadamard, rotações
Portas de dois qubits: CNOT, CZ, SWAP
Portas parametrizadas: RX, RY, RZ com ângulos personalizados
Visualização de circuitos: Animação passo a passo

6. `calculate_entanglement`

Calcule medidas de emaranhamento:

Entropia de Von Neumann: S(ρ) = -Tr(ρ log ρ)
Concorrência: Medida de emaranhamento de dois qubits
Negatividade: Critério de transposição parcial
Informação mútua: I(A:B)

Configuração

Configure via variáveis de ambiente ou 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"
)

Variáveis de Ambiente

Configure o PsiAnimator-MCP via variáveis de ambiente:

Configuração do Servidor:

PSIANIMATOR_CONFIG - Caminho para o arquivo de configuração
PSIANIMATOR_TRANSPORT - Protocolo de transporte (stdio/websocket)
PSIANIMATOR_HOST - Host para transporte WebSocket
PSIANIMATOR_PORT - Porta para transporte WebSocket

Configurações Quânticas:

PSIANIMATOR_QUANTUM_PRECISION - Precisão da computação quântica
PSIANIMATOR_MAX_HILBERT_DIM - Dimensão máxima do espaço de Hilbert
PSIANIMATOR_OUTPUT_DIR - Diretório de saída para animações

Exemplo:

export PSIANIMATOR_TRANSPORT=websocket
export PSIANIMATOR_PORT=3001
psianimator-mcp

Comandos CLI

O PsiAnimator-MCP fornece vários comandos 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

Exemplos de Comandos

Iniciar com configuração personalizada:

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

Modo WebSocket:

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

Registro detalhado (verbose):

psianimator-mcp serve -vvv

Exemplos

Exemplos abrangentes são fornecidos no diretório examples/:

basic_usage.py - Demonstração da funcionalidade principal
Criação de estados de Bell e análise de emaranhamento
Evolução de estado coerente do oscilador harmônico
Circuitos quânticos multi-qubit

Execute os exemplos:

python examples/basic_usage.py

Desenvolvimento

Configurar Ambiente de Desenvolvimento

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

Executar Testes

pytest tests/

Qualidade de Código

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

Arquitetura

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

Limitações

A renderização de animações requer recursos de sistema suficientes
Espaços de Hilbert grandes (>1024 dimensões) podem impactar o desempenho
Alguns recursos avançados de correção de erros quânticos ainda não foram implementados

Licença

Licença MIT - veja LICENSE para detalhes.

Contribuição

Aceitamos contribuições! Consulte CONTRIBUTING.md para:

Diretrizes de desenvolvimento
Padrões de código
Requisitos de teste
Processo de pull request

Suporte

Documentação: Consulte docs/API_REFERENCE.md
Exemplos: Verifique o diretório examples/
Problemas: Reporte bugs via issues do GitHub

PsiAnimator-MCP

Documentação

PsiAnimator-MCP

Recursos

Instalação

Instalação Rápida

Opção 1: Instalação em uma linha (Unix/macOS)

Opção 2: PowerShell (Windows)

Opção 3: pip (quando disponível no PyPI)

Opção 4: A partir do código-fonte

Pré-requisitos

Opções de Instalação Explicadas

Por que a Animação é Opcional

Dependências

Configuração Pós-Instalação

Verificando a Instalação

Solução de Problemas

Integração com Claude Desktop

Configuração Automática

Configuração Manual

Início Rápido

1. Inicie o Servidor

2. Teste a Instalação

3. Exemplo de Uso Básico

Ferramentas MCP

1. create_quantum_state

2. evolve_quantum_system

3. measure_observable

4. animate_quantum_process

5. quantum_gate_sequence

6. calculate_entanglement

Configuração

Variáveis de Ambiente

Comandos CLI

Exemplos de Comandos

Exemplos

Desenvolvimento

Configurar Ambiente de Desenvolvimento

Executar Testes

Qualidade de Código

Arquitetura

Limitações

Licença

Contribuição

Suporte

1. `create_quantum_state`

2. `evolve_quantum_system`

3. `measure_observable`

4. `animate_quantum_process`

5. `quantum_gate_sequence`

6. `calculate_entanglement`