Skip to content

Installation Guide

This guide provides detailed instructions for installing SuperQuantX in various environments and configurations.

🖥️ System Requirements

Operating System

  • Linux: Ubuntu 18.04+, CentOS 7+, or any recent distribution
  • macOS: 10.14 (Mojave) or later
  • Windows: Windows 10 or Windows 11

Python Requirements

  • Python: 3.10, 3.11, or 3.12
  • pip: 21.0 or later (for proper dependency resolution)

Python Version Important

SuperQuantX requires Python 3.10+ due to dependencies in quantum frameworks. Python 3.9 and earlier are not supported.

Hardware Requirements

  • RAM: Minimum 4GB, recommended 8GB+
  • Storage: At least 2GB free space for full installation
  • CPU: Any modern x64 processor
  • GPU: Optional, but recommended for large quantum simulations

🚀 Installation Methods

This installs SuperQuantX with the built-in simulator backend:

pip install superquantx

What you get: - Core SuperQuantX functionality - Built-in quantum simulator - Basic quantum algorithms - Visualization tools

Perfect for: - Learning quantum computing - Small experiments - Testing SuperQuantX features

Method 2: Backend-Specific Installation

Install SuperQuantX with specific quantum computing frameworks:

pip install superquantx[pennylane]

Includes: - Core SuperQuantX - PennyLane quantum ML framework - Lightning simulator (fast C++ backend) - Automatic differentiation support

pip install superquantx[qiskit]

Includes: - Core SuperQuantX - Qiskit quantum framework - Qiskit Aer simulator - IBM Quantum runtime support

pip install superquantx[cirq]

Includes: - Core SuperQuantX - Cirq quantum framework - Cirq simulators

pip install superquantx[braket]

Includes: - Core SuperQuantX - Amazon Braket SDK - AWS quantum hardware access

# Install multiple backends at once
pip install superquantx[pennylane,qiskit,cirq]

# Or install all quantum backends
pip install superquantx[all-backends]

Method 3: Development Installation

For contributing to SuperQuantX or customizing the framework:

# Clone the repository
git clone https://github.com/SuperagenticAI/superquantx.git
cd superquantx

# Install in development mode
pip install -e .[dev]

# Or with all features for development
pip install -e .[full-dev]

What you get: - Editable installation - All development tools (testing, linting, etc.) - All quantum backends - Documentation building tools

🔧 Advanced Installation Options

Always use virtual environments to avoid package conflicts:

# Create virtual environment
python -m venv superquantx-env

# Activate (Linux/macOS)
source superquantx-env/bin/activate

# Activate (Windows)
superquantx-env\Scripts\activate

# Install SuperQuantX
pip install superquantx[pennylane]

# Create conda environment
conda create -n superquantx python=3.11
conda activate superquantx

# Install SuperQuantX
pip install superquantx[pennylane]

# Install uv (if not installed)
pip install uv

# Create project with uv
uv init my-quantum-project
cd my-quantum-project

# Add SuperQuantX as dependency
uv add superquantx[pennylane]

# Activate environment and run
uv run python your_script.py

Docker Installation

Run SuperQuantX in a containerized environment:

FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    g++ \
    && rm -rf /var/lib/apt/lists/*

# Install SuperQuantX
RUN pip install superquantx[pennylane,qiskit]

# Set working directory
WORKDIR /workspace

# Copy your code
COPY . .

# Run your quantum program
CMD ["python", "your_quantum_script.py"]

# Build and run
docker build -t superquantx-app .
docker run -it superquantx-app

Jupyter Notebook Installation

For interactive quantum computing:

# Install SuperQuantX with Jupyter support
pip install superquantx[pennylane] jupyter

# Start Jupyter
jupyter notebook

# Or use JupyterLab
pip install jupyterlab
jupyter lab

✅ Verify Installation

After installation, verify everything works correctly:

Basic Verification

import superquantx as sqx

# Check version
print(f"SuperQuantX version: {sqx.__version__}")

# List available backends
backends = sqx.list_available_backends()
print(f"Available backends: {backends}")

# Test basic functionality
backend = sqx.get_backend('simulator')
circuit = backend.create_circuit(n_qubits=2)
circuit = backend.add_gate(circuit, 'H', 0)
circuit = backend.add_gate(circuit, 'CNOT', [0, 1])
circuit = backend.add_measurement(circuit)
result = backend.execute_circuit(circuit, shots=100)
print(f"Test successful! Results: {result['counts']}")

Backend-Specific Tests

try:
    import superquantx as sqx
    backend = sqx.get_backend('pennylane')
    print("✅ PennyLane backend available")

    # Test QML functionality
    qsvm = sqx.QuantumSVM(backend='pennylane')
    print("✅ PennyLane QML algorithms working")
except ImportError as e:
    print(f"❌ PennyLane not available: {e}")

try:
    import superquantx as sqx
    backend = sqx.get_backend('qiskit')
    print("✅ Qiskit backend available")

    # Test circuit functionality
    circuit = backend.create_circuit(n_qubits=2)
    circuit = backend.add_gate(circuit, 'H', 0)
    print("✅ Qiskit circuits working")
except ImportError as e:
    print(f"❌ Qiskit not available: {e}")

import superquantx as sqx

# Run comprehensive test
test_results = sqx.run_diagnostics()
print("🔍 Diagnostic Results:")
for backend_name, status in test_results.items():
    status_icon = "✅" if status["available"] else "❌"
    print(f"{status_icon} {backend_name}: {status['message']}")

🐛 Troubleshooting Installation

Common Issues and Solutions

Python Version Issues

Problem: SuperQuantX requires Python 3.10+

Solutions: 

# Check Python version
python --version

# Install Python 3.11 using pyenv
curl https://pyenv.run | bash
pyenv install 3.11.0
pyenv global 3.11.0

# Or use conda
conda install python=3.11

Package Conflicts

Problem: Conflicting dependencies detected

Solutions: 

# Create fresh virtual environment
python -m venv fresh_env
source fresh_env/bin/activate  # or fresh_env\Scripts\activate on Windows

# Install with no-cache to ensure fresh packages
pip install --no-cache-dir superquantx[pennylane]

Backend Installation Issues

Problem: Failed to install quantum backend

Solutions: 

# Update pip first
pip install --upgrade pip

# Install backends individually
pip install pennylane
pip install superquantx[pennylane]

# For system-specific issues, install system dependencies
# Ubuntu/Debian:
sudo apt-get install build-essential

# macOS:
xcode-select --install

# Windows: Install Visual Studio Build Tools

Import Errors

Problem: ModuleNotFoundError: No module named 'superquantx'

Solutions: 

# Verify installation
pip list | grep superquantx

# Reinstall if needed
pip uninstall superquantx
pip install superquantx

# Check Python path
python -c "import sys; print(sys.path)"

Performance Optimization

For Large Simulations

# Install with optimized backends
pip install superquantx[pennylane]

# For Intel CPUs, install Intel MKL
pip install mkl mkl-service

# For NVIDIA GPUs with CUDA
pip install cupy-cuda11x  # or cupy-cuda12x

Memory Optimization

import superquantx as sqx

# Configure for memory-efficient simulations
sqx.configure(
    max_qubits=20,          # Limit qubit count
    memory_limit="4GB",     # Set memory limit
    optimization_level=2    # Enable optimizations
)

🚀 Next Steps

Once installation is complete:

  1. Try the Quick Start Guide - Get running in 5 minutes
  2. Build Your First Program - Step-by-step tutorial
  3. Configure SuperQuantX - Customize your setup
  4. Explore Tutorials - Learn quantum computing

📞 Getting Help

If you encounter issues:

Installation Success!

Great job installing SuperQuantX! You're now ready to explore the fascinating world of quantum computing. Start with our Quick Start Guide for immediate hands-on experience.