PsiAnimator-MCP

Un servidor para simulación y animación de física cuántica, utilizando QuTip para cálculos y Manim para visualizaciones.

GitHub

Prueba este MCPPatrocinado

Documentación

PsiAnimator-MCP

Servidor de Simulación y Animación de Física Cuántica

Un servidor de Protocolo de Contexto de Modelo (MCP) que integra QuTip (Quantum Toolbox en Python) para cálculos de física cuántica con Manim (Motor de Animación Matemática) para visualización.

Características

🔬 Motor de Física Cuántica: Gestión completa de estados, evolución temporal y herramientas de medición
🎬 Animaciones Manim: Visualizaciones de calidad de publicación con escenas específicas de cuántica
🔌 Integración MCP: Integración perfecta con clientes compatibles con MCP
🧮 Computación Científica: Construido sobre NumPy, SciPy y QuTip para precisión
📊 Tipos de Visualización: Esferas de Bloch, funciones de Wigner, tomografía de estados, circuitos
🎓 Enfoque Educativo: Perfecto para la educación e investigación en mecánica cuántica

Instalación

Instalación Rápida

Opción 1: Instalación de una línea (Unix/macOS)

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

Opción 2: PowerShell (Windows)

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

Opción 3: pip (cuando esté disponible en 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]"

Opción 4: Desde el código fuente

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

Requisitos Previos

Python ≥ 3.10
Git (para instalación de desarrollo)

Para funciones de animación:

LaTeX (para renderizado matemático avanzado)
FFmpeg (para generación de video)
Biblioteca gráfica Cairo (para renderizado de alta calidad)

Opciones de Instalación Explicadas

🚀 Instalación Principal (Recomendada para la mayoría de usuarios)

pip install psianimator-mcp

Incluye todas las funciones de computación cuántica
Funcionalidad del servidor MCP
QuTip, NumPy, SciPy para física cuántica
Funciona inmediatamente sin dependencias del sistema

🎬 Instalación de Animación (Para visualización)

pip install "psianimator-mcp[animation]"

Todo lo de la instalación principal
Manim para generar animaciones
Requiere dependencias del sistema (LaTeX, FFmpeg)
Mayor tiempo de descarga e instalación

🔧 Instalación de Desarrollo

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

Por Qué la Animación es Opcional

Las funciones de animación (Manim) se mantienen opcionales porque:

Dependencias Pesadas: Manim requiere LaTeX, FFmpeg y Cairo que pueden ocupar varios GB
Complejidad de Instalación: Las dependencias del sistema pueden fallar en diferentes plataformas
Separación de Casos de Uso: Muchos usuarios solo necesitan computación cuántica, no visualización
Fiabilidad de CI/Pruebas: Las funciones principales pueden probarse sin dependencias del sistema
Espacio en Disco: La instalación principal es ~100MB frente a ~2GB+ con la pila completa de animación

Dependencias

Dependencias principales (instaladas automáticamente):

QuTip ≥ 4.7.0 (cálculos de física cuántica)
MCP ≥ 1.0.0 (Protocolo de Contexto de Modelo)
NumPy, SciPy, matplotlib (computación científica)
Pydantic, aiohttp (framework web asíncrono)

Dependencias de animación (extras opcionales):

Manim ≥ 0.18.0 (animaciones matemáticas)
h5py ≥ 3.9.0 (almacenamiento de datos)
pandas ≥ 2.0.0 (análisis de datos)

Configuración Posterior a la Instalación

Después de la instalación, ejecute el comando de configuración:

psianimator-mcp setup

Esto:

Creará el directorio de configuración (~/.config/psianimator-mcp/)
Copiará el archivo de configuración de ejemplo
Probará la instalación y mostrará la disponibilidad de funciones
Proporcionará instrucciones de integración con Claude Desktop

Verificación de la Instalación

Compruebe el estado de su instalación:

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

Salidas esperadas:

✅ Core: OK, Animation: True - Instalación completa con animaciones
✅ Core: OK, Animation: False - Solo instalación principal

Solución de Problemas

Errores de Importación

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

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

Dependencias de Animación

# 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

Integración con Claude Desktop

Configuración Automática

Genere la configuración de Claude Desktop:

psianimator-mcp claude-config

Configuración Manual

Añada a su archivo de configuración de 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 Claude Desktop después de los cambios de configuración.

Inicio Rápido

1. Iniciar el Servidor

Predeterminado (sirve mediante protocolo MCP):

psianimator-mcp

Transporte stdio explícitamente:

psianimator-mcp serve --transport stdio

Transporte WebSocket:

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

2. Probar la Instalación

psianimator-mcp test

3. Ejemplo 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())

Herramientas MCP

1. `create_quantum_state`

Crear estados cuánticos de varios tipos:

Estados puros: |ψ⟩ (vectores ket)
Estados mixtos: ρ (matrices de densidad)
Estados coherentes: |α⟩ (oscilador armónico)
Estados comprimidos: incertidumbre reducida
Estados térmicos: temperatura finita
Estados de Fock: número de fotones definido

2. `evolve_quantum_system`

Evolución temporal con múltiples métodos:

Unitario: Ecuación de Schrödinger (sistemas cerrados)
Ecuación maestra: Forma de Lindblad (sistemas abiertos)
Monte Carlo: Trayectorias cuánticas
Estocástico: Medición continua

3. `measure_observable`

Mediciones y análisis cuánticos:

Valores esperados: ⟨O⟩
Varianzas: Δ²O
Distribuciones de probabilidad: P(resultado)
Funciones de correlación: ⟨A⟩⟨B⟩

4. `animate_quantum_process`

Generar animaciones Manim:

Evolución en esfera de Bloch: Dinámica de qubits
Funciones de Wigner: Representación en espacio de fases
Tomografía de estados: Visualización de matriz de densidad
Ejecución de circuitos: Animación de secuencia de compuertas
Niveles de energía: Dinámica de poblaciones

5. `quantum_gate_sequence`

Aplicar compuertas cuánticas con visualización:

Compuertas de un qubit: Pauli, Hadamard, rotaciones
Compuertas de dos qubits: CNOT, CZ, SWAP
Compuertas parametrizadas: RX, RY, RZ con ángulos personalizados
Visualización de circuitos: Animación paso a paso

6. `calculate_entanglement`

Calcular medidas de entrelazamiento:

Entropía de Von Neumann: S(ρ) = -Tr(ρ log ρ)
Concurrencia: Medida de entrelazamiento de dos qubits
Negatividad: Criterio de transposición parcial
Información mutua: I(A:B)

Configuración

Configure mediante variables de entorno o 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"
)

Variables de Entorno

Configure PsiAnimator-MCP mediante variables de entorno:

Configuración del Servidor:

PSIANIMATOR_CONFIG - Ruta al archivo de configuración
PSIANIMATOR_TRANSPORT - Protocolo de transporte (stdio/websocket)
PSIANIMATOR_HOST - Host para transporte WebSocket
PSIANIMATOR_PORT - Puerto para transporte WebSocket

Configuración Cuántica:

PSIANIMATOR_QUANTUM_PRECISION - Precisión de computación cuántica
PSIANIMATOR_MAX_HILBERT_DIM - Dimensión máxima del espacio de Hilbert
PSIANIMATOR_OUTPUT_DIR - Directorio de salida para animaciones

Ejemplo:

export PSIANIMATOR_TRANSPORT=websocket
export PSIANIMATOR_PORT=3001
psianimator-mcp

Comandos CLI

PsiAnimator-MCP proporciona varios 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

Ejemplos de Comandos

Iniciar con configuración personalizada:

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

Modo WebSocket:

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

Registro detallado:

psianimator-mcp serve -vvv

Ejemplos

Se proporcionan ejemplos completos en el directorio examples/:

basic_usage.py - Recorrido por la funcionalidad principal
Creación de estados de Bell y análisis de entrelazamiento
Evolución de estado coherente del oscilador armónico
Circuitos cuánticos de múltiples qubits

Ejecutar ejemplos:

python examples/basic_usage.py

Desarrollo

Configurar el Entorno de Desarrollo

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

Ejecutar Pruebas

pytest tests/

Calidad del Código

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

Arquitectura

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

Limitaciones

El renderizado de animaciones requiere suficientes recursos del sistema
Los espacios de Hilbert grandes (>1024 dimensiones) pueden afectar el rendimiento
Algunas funciones avanzadas de corrección de errores cuánticos aún no están implementadas

Licencia

Licencia MIT - consulte LICENSE para más detalles.

Contribuciones

¡Agradecemos las contribuciones! Consulte CONTRIBUTING.md para:

Directrices de desarrollo
Estándares de código
Requisitos de prueba
Proceso de solicitudes de extracción

Soporte

Documentación: Consulte docs/API_REFERENCE.md
Ejemplos: Revise el directorio examples/
Problemas: Reporte errores mediante los issues de GitHub

PsiAnimator-MCP

Documentación

PsiAnimator-MCP

Características

Instalación

Instalación Rápida

Opción 1: Instalación de una línea (Unix/macOS)

Opción 2: PowerShell (Windows)

Opción 3: pip (cuando esté disponible en PyPI)

Opción 4: Desde el código fuente

Requisitos Previos

Opciones de Instalación Explicadas

Por Qué la Animación es Opcional

Dependencias

Configuración Posterior a la Instalación

Verificación de la Instalación

Solución de Problemas

Integración con Claude Desktop

Configuración Automática

Configuración Manual

Inicio Rápido

1. Iniciar el Servidor

2. Probar la Instalación

3. Ejemplo de Uso Básico

Herramientas MCP

1. create_quantum_state

2. evolve_quantum_system

3. measure_observable

4. animate_quantum_process

5. quantum_gate_sequence

6. calculate_entanglement

Configuración

Variables de Entorno

Comandos CLI

Ejemplos de Comandos

Ejemplos

Desarrollo

Configurar el Entorno de Desarrollo

Ejecutar Pruebas

Calidad del Código

Arquitectura

Limitaciones

Licencia

Contribuciones

Soporte

1. `create_quantum_state`

2. `evolve_quantum_system`

3. `measure_observable`

4. `animate_quantum_process`

5. `quantum_gate_sequence`

6. `calculate_entanglement`