diff --git a/docker/Dockerfile b/docker/Dockerfile new file mode 100644 index 0000000..64c38b6 --- /dev/null +++ b/docker/Dockerfile @@ -0,0 +1,161 @@ +# Quantum Computing 101 - Unified Multi-Architecture Dockerfile +# Supports CPU, NVIDIA GPU (CUDA), and AMD GPU (ROCm) +# Best practices: Multi-stage build, build args, minimal layers + +# Build arguments for variant selection +ARG VARIANT=cpu +ARG PYTORCH_VERSION=2.8.0 +ARG CUDA_VERSION=12.9 +ARG CUDNN_VERSION=9 + +# ============================================================================= +# Stage 1: Base Image Selection +# ============================================================================= +FROM pytorch/pytorch:${PYTORCH_VERSION}-cuda${CUDA_VERSION}-cudnn${CUDNN_VERSION}-devel AS base-nvidia +FROM rocm/pytorch:latest AS base-amd +FROM python:3.12-slim AS base-cpu + +# Select appropriate base based on variant +FROM base-${VARIANT} AS base + +# ============================================================================= +# Stage 2: Common Setup - System Dependencies +# ============================================================================= +FROM base AS system-deps + +# Metadata +LABEL maintainer="Quantum Computing 101" +LABEL version="3.0" +LABEL description="Quantum computing educational platform with multi-GPU support" + +# Environment variables +ENV DEBIAN_FRONTEND=noninteractive \ + PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + MPLBACKEND=Agg \ + QC101_CONTAINER=1 \ + PIP_NO_CACHE_DIR=1 \ + PIP_DISABLE_PIP_VERSION_CHECK=1 + +# Install common system dependencies +RUN apt-get update && apt-get install -y --no-install-recommends \ + gcc \ + g++ \ + make \ + git \ + curl \ + wget \ + vim \ + htop \ + ca-certificates \ + && rm -rf /var/lib/apt/lists/* + +# ============================================================================= +# Stage 3: Python Environment Setup +# ============================================================================= +FROM system-deps AS python-setup + +# Upgrade pip and install build tools +RUN pip install --upgrade pip setuptools wheel + +# Create non-root user for security +RUN useradd --create-home --shell /bin/bash --uid 1000 qc101 + +WORKDIR /home/qc101/quantum-computing-101 + +# ============================================================================= +# Stage 4: Dependencies Installation (CPU Variant) +# ============================================================================= +FROM python-setup AS deps-cpu + +# Copy requirements +COPY docker/requirements/base.txt /tmp/requirements/base.txt +COPY docker/requirements/cpu.txt /tmp/requirements/cpu.txt + +# Install base dependencies +RUN pip install -r /tmp/requirements/base.txt + +# Install CPU-specific dependencies +RUN pip install -r /tmp/requirements/cpu.txt + +# ============================================================================= +# Stage 5: Dependencies Installation (NVIDIA GPU Variant) +# ============================================================================= +FROM python-setup AS deps-nvidia + +# NVIDIA-specific environment variables +ENV NVIDIA_VISIBLE_DEVICES=all \ + NVIDIA_DRIVER_CAPABILITIES=compute,utility \ + CUDA_VISIBLE_DEVICES=all \ + QISKIT_IN_PARALLEL=TRUE + +# Copy requirements +COPY docker/requirements/base.txt /tmp/requirements/base.txt +COPY docker/requirements/gpu-nvidia.txt /tmp/requirements/gpu-nvidia.txt + +# Install base dependencies (excluding qiskit-aer to avoid conflicts) +RUN sed '/^qiskit-aer/d' /tmp/requirements/base.txt > /tmp/requirements/base-no-aer.txt && \ + pip install -r /tmp/requirements/base-no-aer.txt + +# Install NVIDIA-specific dependencies (includes qiskit-aer-gpu) +RUN pip install -r /tmp/requirements/gpu-nvidia.txt + +# ============================================================================= +# Stage 6: Dependencies Installation (AMD GPU Variant) +# ============================================================================= +FROM python-setup AS deps-amd + +# ROCm-specific environment variables +ENV ROCM_VISIBLE_DEVICES=all \ + HIP_VISIBLE_DEVICES=all + +# Copy requirements +COPY docker/requirements/base.txt /tmp/requirements/base.txt +COPY docker/requirements/gpu-amd.txt /tmp/requirements/gpu-amd.txt + +# Install base dependencies +RUN pip install -r /tmp/requirements/base.txt + +# Install AMD-specific dependencies +RUN pip install -r /tmp/requirements/gpu-amd.txt + +# ============================================================================= +# Stage 7: Application Setup (Unified) +# ============================================================================= +FROM deps-${VARIANT} AS app-setup + +# Copy application code +COPY --chown=qc101:qc101 . /home/qc101/quantum-computing-101/ + +# Install the package in development mode +RUN pip install -e . + +# Create output directory +RUN mkdir -p /home/qc101/quantum-computing-101/outputs && \ + chown -R qc101:qc101 /home/qc101/quantum-computing-101/outputs + +# ============================================================================= +# Stage 8: Runtime Image (Final) +# ============================================================================= +FROM app-setup AS runtime + +# Switch to non-root user +USER qc101 + +# Set working directory +WORKDIR /home/qc101/quantum-computing-101/examples + +# Health check +HEALTHCHECK --interval=30s --timeout=15s --start-period=10s --retries=3 \ + CMD python -c "import qiskit; print('βœ… Container healthy')" || exit 1 + +# Resource optimizations +ENV OMP_NUM_THREADS=8 \ + MKL_NUM_THREADS=8 + +# Entrypoint script +COPY --chown=qc101:qc101 docker/entrypoint.sh /home/qc101/entrypoint.sh +RUN chmod +x /home/qc101/entrypoint.sh + +ENTRYPOINT ["/home/qc101/entrypoint.sh"] +CMD ["bash"] diff --git a/docker/Dockerfile.base b/docker/Dockerfile.base deleted file mode 100644 index c8e496e..0000000 --- a/docker/Dockerfile.base +++ /dev/null @@ -1,69 +0,0 @@ -# Base Dockerfile for Quantum Computing 101 -# Multi-stage build for optimized container sizes - -# Stage 1: Base Python environment with system dependencies -FROM python:3.12-slim as base - -# Set labels for metadata -LABEL maintainer="Quantum Computing 101" -LABEL version="1.0" -LABEL description="Base image for quantum computing educational examples" - -# Set environment variables -ENV PYTHONUNBUFFERED=1 -ENV PYTHONDONTWRITEBYTECODE=1 -ENV MPLBACKEND=Agg -ENV QC101_CONTAINER=1 - -# Install system dependencies -RUN apt-get update && apt-get install -y \ - gcc \ - g++ \ - libc6-dev \ - libffi-dev \ - libssl-dev \ - make \ - git \ - curl \ - && rm -rf /var/lib/apt/lists/* - -# Create non-root user for security -RUN useradd --create-home --shell /bin/bash qc101 -WORKDIR /home/qc101/quantum-computing-101 - -# Stage 2: Dependencies installation -FROM base as dependencies - -# Copy requirements files -COPY examples/requirements-core.txt /tmp/requirements-core.txt -COPY examples/requirements.txt /tmp/requirements.txt - -# Install Python dependencies -RUN pip install --no-cache-dir --upgrade pip setuptools wheel - -# Install core dependencies (for lightweight builds) -RUN pip install --no-cache-dir -r /tmp/requirements-core.txt - -# Stage 3: Full dependencies (for complete builds) -FROM dependencies as full-deps - -# Install all dependencies including cloud SDKs -RUN pip install --no-cache-dir -r /tmp/requirements.txt - -# Stage 4: Application code -FROM dependencies as app-base - -# Copy application code -COPY --chown=qc101:qc101 . /home/qc101/quantum-computing-101/ - -# Install the package -RUN pip install --no-cache-dir -e . - -# Switch to non-root user -USER qc101 - -# Set default working directory -WORKDIR /home/qc101/quantum-computing-101/examples - -# Default command -CMD ["python", "--version"] \ No newline at end of file diff --git a/docker/Dockerfile.cpu b/docker/Dockerfile.cpu deleted file mode 100644 index 10dde45..0000000 --- a/docker/Dockerfile.cpu +++ /dev/null @@ -1,71 +0,0 @@ -# CPU-Only Dockerfile for Quantum Computing 101 -# Lightweight container for CPU-based quantum simulations - -FROM python:3.12-slim - -# Set labels for metadata -LABEL maintainer="Quantum Computing 101" -LABEL version="1.0" -LABEL variant="cpu" -LABEL description="CPU-only quantum computing examples - lightweight and fast" - -# Set environment variables for CPU optimization -ENV PYTHONUNBUFFERED=1 -ENV PYTHONDONTWRITEBYTECODE=1 -ENV MPLBACKEND=Agg -ENV QC101_CONTAINER=1 -ENV QC101_VARIANT=cpu -ENV OMP_NUM_THREADS=4 -ENV MKL_NUM_THREADS=4 - -# Install system dependencies optimized for CPU -RUN apt-get update && apt-get install -y \ - gcc \ - g++ \ - libc6-dev \ - libffi-dev \ - libssl-dev \ - libopenblas-dev \ - liblapack-dev \ - make \ - git \ - curl \ - htop \ - && rm -rf /var/lib/apt/lists/* \ - && apt-get clean - -# Create non-root user for security -RUN useradd --create-home --shell /bin/bash --uid 1000 qc101 - -# Set working directory -WORKDIR /home/qc101/quantum-computing-101 - -# Copy requirements files -COPY docker/requirements/ /tmp/requirements/ - -# Install Python dependencies with CPU optimizations -RUN pip install --no-cache-dir --upgrade pip setuptools wheel && \ - pip install --no-cache-dir -r /tmp/requirements/cpu.txt - -# Copy application code -COPY --chown=qc101:qc101 . /home/qc101/quantum-computing-101/ - -# Install the package in development mode -RUN pip install --no-cache-dir -e . - -# Create output directory for results -RUN mkdir -p /home/qc101/quantum-computing-101/outputs && \ - chown -R qc101:qc101 /home/qc101/quantum-computing-101/outputs - -# Switch to non-root user -USER qc101 - -# Set default working directory to examples -WORKDIR /home/qc101/quantum-computing-101/examples - -# Health check to verify quantum computing stack -HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \ - CMD python -c "import qiskit; import numpy; print('Quantum Computing 101 CPU container healthy')" - -# Default command - show available examples -CMD ["python", "-c", "import sys; sys.path.append('..'); from utils.cli import main; main(['list'])"] \ No newline at end of file diff --git a/docker/Dockerfile.gpu-amd b/docker/Dockerfile.gpu-amd deleted file mode 100644 index b960e59..0000000 --- a/docker/Dockerfile.gpu-amd +++ /dev/null @@ -1,164 +0,0 @@ -# AMD ROCm GPU Dockerfile for Quantum Computing 101 -# Multi-stage build optimized for AMD GPU acceleration with ROCm - -# Stage 1: Base ROCm environment (Updated to latest ROCm 6.x with PyTorch) -FROM rocm/pytorch:latest as rocm-base - -# Set labels for metadata -LABEL maintainer="Quantum Computing 101" -LABEL version="2.0" -LABEL variant="gpu-amd" -LABEL description="AMD ROCm-accelerated quantum computing examples" - -# Set environment variables for ROCm optimization -ENV DEBIAN_FRONTEND=noninteractive -ENV PYTHONUNBUFFERED=1 -ENV PYTHONDONTWRITEBYTECODE=1 -ENV MPLBACKEND=Agg -ENV QC101_CONTAINER=1 -ENV QC101_VARIANT=gpu-amd -ENV ROCm_HOME=/opt/rocm -ENV HIP_VISIBLE_DEVICES=all -ENV ROCR_VISIBLE_DEVICES=all -ENV HSA_OVERRIDE_GFX_VERSION=10.3.0 - -# Update system and install development dependencies for Qiskit-Aer ROCm build -RUN apt-get update && apt-get install -y \ - gcc \ - g++ \ - libc6-dev \ - libffi-dev \ - libssl-dev \ - make \ - git \ - curl \ - htop \ - vim \ - wget \ - cmake \ - ninja-build \ - rocm-dev \ - rocm-libs \ - rccl-dev \ - hip-dev \ - rocthrust-dev \ - rocprim-dev \ - && rm -rf /var/lib/apt/lists/* \ - && apt-get clean - -# The latest ROCm/PyTorch image should already have Python 3.11+ -# Set up environment and verify Python version -RUN python --version && pip install --upgrade pip - -# Stage 2: Python dependencies -FROM rocm-base as python-deps - -# Upgrade pip and install build tools -RUN pip install --no-cache-dir --upgrade pip setuptools wheel - -# Copy requirements files -COPY docker/requirements/ /tmp/requirements/ - -# Install Python dependencies in optimal order for layer caching -# Install base requirements first (most stable) - excluding qiskit-aer for custom build -RUN sed '/^qiskit-aer/d' /tmp/requirements/base.txt > /tmp/requirements/base-no-aer.txt && \ - pip install --no-cache-dir -r /tmp/requirements/base-no-aer.txt - -# Install AMD-specific requirements (excluding qiskit-aer for custom build) -RUN sed '/^qiskit-aer/d; /^cupy-rocm/d' /tmp/requirements/gpu-amd.txt > /tmp/requirements/gpu-amd-no-aer.txt && \ - pip install --no-cache-dir -r /tmp/requirements/gpu-amd-no-aer.txt || \ - echo "⚠️ Some ROCm packages failed to install - using CPU fallbacks" - -# Set ROCm environment variables for building -ENV ROCM_PATH=/opt/rocm -ENV HCC_AMDGPU_TARGET=gfx803,gfx900,gfx906,gfx908,gfx90a,gfx942,gfx1030,gfx1100 -ENV AMDGPU_TARGETS=gfx803,gfx900,gfx906,gfx908,gfx90a,gfx942,gfx1030,gfx1100 - -# Clone and build Qiskit-Aer with ROCm support from source -RUN git clone https://github.com/Qiskit/qiskit-aer.git /tmp/qiskit-aer && \ - cd /tmp/qiskit-aer && \ - QISKIT_AER_PACKAGE_NAME='qiskit-aer-gpu-rocm' \ - python setup.py bdist_wheel -- \ - -DAER_THRUST_BACKEND=ROCM \ - -DAER_MPI=OFF \ - -DAER_ROCM_ARCH="gfx906 gfx908 gfx90a gfx942 gfx1030" \ - -DCMAKE_BUILD_TYPE=Release && \ - pip install --force-reinstall dist/qiskit_aer_gpu_rocm-*.whl && \ - rm -rf /tmp/qiskit-aer - -# Stage 3: Application setup -FROM python-deps as app-setup - -# Create non-root user for security -RUN useradd --create-home --shell /bin/bash --uid 1000 qc101 - -# Set working directory -WORKDIR /home/qc101/quantum-computing-101 - -# Copy application code (use .dockerignore to optimize) -COPY --chown=qc101:qc101 . /home/qc101/quantum-computing-101/ - -# Install the package in development mode -RUN pip install --no-cache-dir -e . - -# Create output directory for results -RUN mkdir -p /home/qc101/quantum-computing-101/outputs && \ - chown -R qc101:qc101 /home/qc101/quantum-computing-101/outputs - -# Stage 4: Final runtime image -FROM app-setup as runtime - -# Switch to non-root user -USER qc101 - -# Set default working directory to examples -WORKDIR /home/qc101/quantum-computing-101/examples - -# Create startup script for GPU info display -RUN echo '#!/bin/bash\n\ -echo "🐳 Quantum Computing 101 - AMD ROCm GPU Container"\n\ -echo "=================================================="\n\ -echo "ROCm Version: $(cat /opt/rocm/.info/version 2>/dev/null || echo \"Unknown\")"\n\ -if command -v rocm-smi &> /dev/null; then\n\ - echo "GPU Info:"\n\ - rocm-smi --showproductname --showmeminfo --showuse 2>/dev/null | head -10\n\ -else\n\ - echo "⚠️ rocm-smi not available - run with --device=/dev/kfd --device=/dev/dri"\n\ -fi\n\ -echo "PyTorch ROCm: $(python -c \"import torch; print(\"Available\" if torch.cuda.is_available() else \"Not Available\")\")"\n\ -echo "Qiskit-Aer ROCm: $(python -c \"from qiskit_aer import AerSimulator; sim = AerSimulator(method=\"statevector\", device=\"GPU\"); print(\"Available\" if \"GPU\" in str(sim.options.device) else \"CPU fallback\")\")"\n\ -echo "Qiskit Version: $(python -c \"import qiskit; print(qiskit.__version__)\")"\n\ -echo "=================================================="\n\ -echo "⚠️ Note: ROCm support is experimental in quantum computing"\n\ -echo " Most acceleration comes from PyTorch ML examples"\n\ -echo " Quantum simulations may fall back to optimized CPU"\n\ -echo "=================================================="\n\ -echo "Available examples:"\n\ -find . -name "*.py" -type f | grep -E "module[0-9]_" | head -5 | sed "s/^/ /"\n\ -echo " ... and $(find . -name "*.py" -type f | grep -E "module[0-9]_" | wc -l | tr -d " ") total examples"\n\ -echo ""\n\ -echo "Quick start:"\n\ -echo " python module1_fundamentals/01_classical_vs_quantum_bits.py"\n\ -echo " python module6_machine_learning/01_quantum_neural_network.py"\n\ -echo ""\n\ -echo "ROCm GPU Docker run command:"\n\ -echo " docker run --device=/dev/kfd --device=/dev/dri --group-add video quantum101:gpu-amd"\n\ -echo ""' > /home/qc101/startup.sh && chmod +x /home/qc101/startup.sh - -# Health check to verify ROCm and quantum computing stack -HEALTHCHECK --interval=30s --timeout=15s --start-period=10s --retries=3 \ - CMD python -c "import qiskit; import torch; \ - print('βœ… ROCm container healthy'); \ - print(f'PyTorch ROCm available: {torch.cuda.is_available()}'); \ - print(f'Qiskit version: {qiskit.__version__}')" || exit 1 - -# Set resource limits and optimizations -ENV OMP_NUM_THREADS=8 -ENV MKL_NUM_THREADS=8 -ENV HCC_AMDGPU_TARGET=gfx906,gfx908,gfx90a,gfx942,gfx1030 - -# Add ROCm to PATH -ENV PATH=$PATH:/opt/rocm/bin - -# Default command - show GPU info and available examples -CMD ["/home/qc101/startup.sh"] \ No newline at end of file diff --git a/docker/Dockerfile.gpu-nvidia b/docker/Dockerfile.gpu-nvidia deleted file mode 100644 index 03f0b05..0000000 --- a/docker/Dockerfile.gpu-nvidia +++ /dev/null @@ -1,131 +0,0 @@ -# NVIDIA CUDA GPU Dockerfile for Quantum Computing 101 -# Multi-stage build optimized for NVIDIA GPU acceleration - -# Stage 1: Base CUDA environment -FROM nvidia/cuda:12.9.1-cudnn-devel-ubuntu24.04 as cuda-base - -# Set labels for metadata -LABEL maintainer="Quantum Computing 101" -LABEL version="2.1" -LABEL variant="gpu-nvidia" -LABEL description="NVIDIA CUDA 12.9.1 with cuDNN accelerated quantum computing examples" - -# Set environment variables for CUDA optimization -ENV DEBIAN_FRONTEND=noninteractive -ENV PYTHONUNBUFFERED=1 -ENV PYTHONDONTWRITEBYTECODE=1 -ENV MPLBACKEND=Agg -ENV QC101_CONTAINER=1 -ENV QC101_VARIANT=gpu-nvidia -ENV NVIDIA_VISIBLE_DEVICES=all -ENV NVIDIA_DRIVER_CAPABILITIES=compute,utility -ENV CUDA_VISIBLE_DEVICES=all -ENV QISKIT_IN_PARALLEL=TRUE - -# Install system dependencies -RUN apt-get update && apt-get install -y \ - python3.12 \ - python3.12-dev \ - python3.12-venv \ - python3-pip \ - gcc \ - g++ \ - libc6-dev \ - libffi-dev \ - libssl-dev \ - libcublas-dev-12-9 \ - libcusparse-dev-12-9 \ - libcurand-dev-12-9 \ - libcusolver-dev-12-9 \ - libcufft-dev-12-9 \ - make \ - git \ - curl \ - htop \ - vim \ - && rm -rf /var/lib/apt/lists/* \ - && apt-get clean - -# Create symbolic links for python -RUN ln -sf /usr/bin/python3.12 /usr/bin/python && \ - ln -sf /usr/bin/python3.12 /usr/bin/python3 - -# Stage 2: Python dependencies -FROM cuda-base as python-deps - -# Upgrade pip and install build tools -RUN pip install --no-cache-dir --break-system-packages --ignore-installed --upgrade pip setuptools wheel - -# Copy requirements files -COPY docker/requirements/ /tmp/requirements/ - -# Install Python dependencies in optimal order for layer caching -# Install base requirements first (most stable) - excluding qiskit-aer to avoid conflicts -RUN sed '/^qiskit-aer/d' /tmp/requirements/base.txt > /tmp/requirements/base-no-aer.txt && \ - pip install --no-cache-dir --break-system-packages -r /tmp/requirements/base-no-aer.txt - -# Install NVIDIA-specific requirements (includes qiskit-aer-gpu) -RUN pip install --no-cache-dir --break-system-packages -r /tmp/requirements/gpu-nvidia.txt - -# Stage 3: Application setup -FROM python-deps as app-setup - -# Create non-root user for security -RUN useradd --create-home --shell /bin/bash --uid 1000 qc101 - -# Set working directory -WORKDIR /home/qc101/quantum-computing-101 - -# Copy application code (use .dockerignore to optimize) -COPY --chown=qc101:qc101 . /home/qc101/quantum-computing-101/ - -# Install the package in development mode -RUN pip install --no-cache-dir --break-system-packages -e . - -# Create output directory for results -RUN mkdir -p /home/qc101/quantum-computing-101/outputs && \ - chown -R qc101:qc101 /home/qc101/quantum-computing-101/outputs - -# Stage 4: Final runtime image -FROM app-setup as runtime - -# Switch to non-root user -USER qc101 - -# Set default working directory to examples -WORKDIR /home/qc101/quantum-computing-101/examples - -# Create startup script for GPU info display -RUN echo '#!/bin/bash\n\ -echo "🐳 Quantum Computing 101 - NVIDIA GPU Container"\n\ -echo "================================================"\n\ -echo "CUDA Version: $(nvcc --version | grep "release" | awk "{print \$6}" | cut -c2-)"\n\ -echo "GPU Count: $(nvidia-smi --query-gpu=count --format=csv,noheader,nounits | head -1)"\n\ -nvidia-smi --query-gpu=name,memory.total,utilization.gpu --format=csv,noheader\n\ -echo "PyTorch CUDA: $(python -c \"import torch; print(torch.cuda.is_available())\")"\n\ -echo "Qiskit Version: $(python -c \"import qiskit; print(qiskit.__version__)\")"\n\ -echo "Qiskit-Aer GPU: $(python -c \"from qiskit_aer import AerSimulator; sim = AerSimulator(method=\"statevector\", device=\"GPU\"); print(\"Available\" if \"GPU\" in str(sim.options.device) else \"CPU fallback\")\")"\n\ -echo "================================================"\n\ -echo "Available examples:"\n\ -find . -name "*.py" -type f | grep -E "module[0-9]_" | head -5 | sed "s/^/ /"\n\ -echo " ... and $(find . -name "*.py" -type f | grep -E "module[0-9]_" | wc -l | tr -d " ") total examples"\n\ -echo ""\n\ -echo "Quick start:"\n\ -echo " python module1_fundamentals/01_classical_vs_quantum_bits.py"\n\ -echo " python module6_machine_learning/01_quantum_neural_network.py"\n\ -echo ""' > /home/qc101/startup.sh && chmod +x /home/qc101/startup.sh - -# Health check to verify GPU and quantum computing stack -HEALTHCHECK --interval=30s --timeout=15s --start-period=10s --retries=3 \ - CMD python -c "import qiskit; import torch; import cupy; \ - assert torch.cuda.is_available(), 'CUDA not available'; \ - assert torch.cuda.device_count() > 0, 'No CUDA devices'; \ - print('βœ… GPU container healthy')" || exit 1 - -# Set resource limits and optimizations -ENV OMP_NUM_THREADS=8 -ENV MKL_NUM_THREADS=8 -ENV CUDA_CACHE_PATH=/tmp/cuda_cache - -# Default command - show GPU info and available examples -CMD ["/home/qc101/startup.sh"] \ No newline at end of file diff --git a/docker/README.md b/docker/README.md index 2f3bc13..31f3e41 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,385 +1,540 @@ -# 🐳 Docker Setup for Quantum Computing 101 v2.0 +# Quantum Computing 101 - Docker Setup Guide -This directory contains Docker configurations for running Quantum Computing 101 examples with comprehensive GPU support including both NVIDIA CUDA and AMD ROCm acceleration. +## Table of Contents +- [Overview](#overview) +- [Architecture](#architecture) +- [Quick Start](#quick-start) +- [Volume Mounting & Development Workflow](#volume-mounting--development-workflow) +- [Directory Structure](#directory-structure) +- [Environment Variables](#environment-variables) +- [Jupyter Lab Access](#jupyter-lab-access) +- [Advanced Configuration](#advanced-configuration) +- [Troubleshooting](#troubleshooting) +- [Migration Guide](#migration-guide) -## πŸš€ Quick Start +## Overview -### Prerequisites -- Docker installed and running -- For NVIDIA GPU: NVIDIA Docker runtime and CUDA-compatible drivers -- For AMD GPU: ROCm drivers and /dev/kfd, /dev/dri device access +This Docker setup provides a unified, flexible solution for running Quantum Computing 101 across different hardware configurations: -### CPU-Only (Recommended for Learning) -```bash -# Build and run CPU container -cd docker -./build.sh cpu -./run.sh -v cpu -e module1_fundamentals/01_classical_vs_quantum_bits.py +- **CPU Only**: Lightweight container for systems without GPU +- **NVIDIA GPU**: CUDA-accelerated quantum computing with PyTorch 2.8.0 + CUDA 12.9 +- **AMD GPU**: ROCm-accelerated quantum computing with latest ROCm PyTorch + +## Architecture -# Interactive session -./run.sh -v cpu -i +### Unified Dockerfile Approach + +The new `Dockerfile` uses multi-stage builds with build arguments to create different variants from a single source: + +``` +Base Images: +β”œβ”€β”€ CPU: python:3.12-slim +β”œβ”€β”€ NVIDIA: pytorch/pytorch:2.8.0-cuda12.9-cudnn9-devel +└── AMD: rocm/pytorch:latest + +Build Stages: +1. base β†’ Select base image variant +2. system-deps β†’ Install common system dependencies +3. python-setup β†’ Setup Python environment +4. deps-{variant} β†’ Install variant-specific dependencies +5. app-setup β†’ Copy application code +6. runtime β†’ Final optimized image ``` -### NVIDIA GPU Acceleration +### Benefits + +βœ… **Single Source of Truth**: One Dockerfile for all variants +βœ… **Reduced Duplication**: Shared stages minimize maintenance +βœ… **Build Arguments**: Flexible version control +βœ… **Layer Caching**: Optimized build times +βœ… **Best Practices**: Multi-stage, minimal layers, non-root user + +## Quick Start + +### Building Images + ```bash -# Build NVIDIA GPU container -cd docker -./build.sh gpu-nvidia +# Build CPU variant +./build-unified.sh cpu -# Run GPU-accelerated ML example -./run.sh -v gpu-nvidia -e module6_machine_learning/01_quantum_neural_network.py +# Build NVIDIA GPU variant +./build-unified.sh nvidia -# Interactive GPU session -./run.sh -v gpu-nvidia -i +# Build AMD GPU variant +./build-unified.sh amd + +# Build all variants +./build-unified.sh all + +# Build without cache +./build-unified.sh nvidia --no-cache ``` -### AMD ROCm GPU Acceleration +### Using Docker Compose + ```bash -# Build AMD ROCm container -cd docker -./build.sh gpu-amd +# Start CPU container +docker-compose up -d qc101-cpu + +# Start NVIDIA GPU container +docker-compose up -d qc101-nvidia + +# Start AMD GPU container +docker-compose up -d qc101-amd -# Run with ROCm acceleration -./run.sh -v gpu-amd -e module6_machine_learning/01_quantum_neural_network.py +# View logs +docker-compose logs -f qc101-nvidia -# Interactive ROCm session -./run.sh -v gpu-amd -i +# Stop containers +docker-compose down ``` -## πŸ“¦ Container Variants - -### 1. **quantum101:cpu** - Lightweight CPU-only -- **Base**: Python 3.12 slim -- **Size**: ~1.2GB -- **Hardware**: Any x86_64 with Docker -- **Use cases**: Learning, basic examples, development -- **Optimizations**: OpenBLAS, CPU-tuned linear algebra -- **Memory**: 1-4GB recommended - -### 2. **quantum101:gpu-nvidia** - NVIDIA CUDA Acceleration -- **Base**: NVIDIA CUDA 12.2 Ubuntu 22.04 -- **Size**: ~3.5GB -- **Hardware**: NVIDIA GPU + CUDA drivers + nvidia-docker -- **Use cases**: Large simulations (>15 qubits), quantum ML, research -- **GPU Memory**: 4GB+ recommended -- **Features**: - - CUDA 12.2+ with cuDNN - - GPU-accelerated Qiskit Aer simulator - - PyTorch with CUDA support - - CuPy for GPU array operations - - TensorBoard for ML visualization - -### 3. **quantum101:gpu-amd** - AMD ROCm Acceleration -- **Base**: ROCm 5.6 Ubuntu 22.04 -- **Size**: ~3.2GB -- **Hardware**: AMD GPU + ROCm drivers + device access -- **Use cases**: AMD GPU ML acceleration, ROCm development -- **GPU Memory**: 4GB+ recommended -- **Features**: - - ROCm 5.6 with HIP support - - PyTorch with ROCm support - - Limited Qiskit GPU acceleration (CPU fallback for most quantum ops) - - Experimental CuPy ROCm support - -### 4. **quantum101:base** - Development Base -- **Base**: Multi-stage optimized build -- **Use cases**: Custom extensions, advanced development - -## 🎯 Performance Comparisons - -### Quantum Simulation Benchmarks -| Operation | CPU (8 cores) | NVIDIA RTX 4080 | AMD RX 7900XT | Speedup (NVIDIA) | -|-----------|---------------|-----------------|---------------|------------------| -| 20-qubit simulation | 45s | 8s | 42s* | 5.6x | -| VQE optimization | 120s | 22s | 115s* | 5.5x | -| Quantum ML training | 300s | 35s | 85s | 8.6x | -| Grover's (15 qubits) | 12s | 3s | 11s* | 4x | - -*AMD ROCm acceleration limited by quantum computing framework support - -### Memory Usage by Variant -| Variant | Base Image | Dependencies | Runtime Peak | GPU Memory | -|---------|------------|--------------|--------------|------------| -| cpu | 120MB | 1.2GB | 2-4GB | N/A | -| gpu-nvidia | 2.1GB | 3.5GB | 4-8GB | 2-8GB | -| gpu-amd | 1.8GB | 3.2GB | 4-8GB | 2-8GB | - -## πŸ”§ Advanced Usage - -### Docker Compose (Multi-Service) +### Manual Docker Run + ```bash -# Start all services -docker-compose up -d +# CPU variant +docker run -it --rm \ + -v $(pwd)/../examples:/home/qc101/quantum-computing-101/examples \ + quantum-computing-101:cpu + +# NVIDIA GPU variant +docker run -it --rm \ + --gpus all \ + -v $(pwd)/../examples:/home/qc101/quantum-computing-101/examples \ + quantum-computing-101:nvidia + +# AMD GPU variant +docker run -it --rm \ + --device=/dev/kfd --device=/dev/dri \ + --group-add video --group-add render \ + -v $(pwd)/../examples:/home/qc101/quantum-computing-101/examples \ + quantum-computing-101:amd +``` + +## Volume Mounting & Development Workflow -# Start specific variant -docker-compose up quantum101-gpu-nvidia +### Current Setup -# Jupyter environments -docker-compose up jupyter-cpu # http://localhost:8888 -docker-compose up jupyter-gpu-nvidia # http://localhost:8889 -docker-compose up jupyter-gpu-amd # http://localhost:8890 +The `docker-compose.yml` configures volume mounts for seamless host-container development: -# Development container -docker-compose up quantum101-dev +```yaml +volumes: + - ../examples:/home/qc101/quantum-computing-101/examples + - ../outputs:/home/qc101/quantum-computing-101/outputs + - ../modules:/home/qc101/quantum-computing-101/modules:ro ``` -### Build Script Options +**What this means:** +- βœ… Edit files in `examples/` on host β†’ Changes appear instantly in container +- βœ… Container outputs save to `outputs/` β†’ Visible on host immediately +- βœ… `modules/` mounted read-only (`:ro`) β†’ Protected from container modifications + +### Development Workflows + +#### 1. Using Docker Compose (Recommended) + ```bash -# Build specific variants -./build.sh cpu # CPU-only (always available) -./build.sh gpu-nvidia # NVIDIA CUDA (requires nvidia-docker) -./build.sh gpu-amd # AMD ROCm (requires ROCm drivers) -./build.sh base # Development base -./build.sh all # All available variants -./build.sh clean # Remove all images - -# Build with hardware detection -./build.sh # Auto-detects available hardware +# Start container with volume mounts +cd docker +docker compose up qc101-nvidia + +# In another terminal, edit files on host +cd ../examples/module1_fundamentals +vim 01_classical_vs_quantum_bits.py + +# Changes are instantly available in container! ``` -### Run Script Options +#### 2. Interactive Development Workflow + ```bash -# Basic usage -./run.sh [OPTIONS] - -# Variants -./run.sh -v cpu # CPU-only -./run.sh -v gpu-nvidia # NVIDIA GPU -./run.sh -v gpu-amd # AMD ROCm - -# Modes -./run.sh -i # Interactive shell -./run.sh -j # Jupyter Lab -./run.sh -e MODULE/EXAMPLE.py # Run example -./run.sh -l # List examples -./run.sh --info # Hardware info - -# Examples with arguments -./run.sh -v gpu-nvidia -e module6_machine_learning/01_quantum_neural_network.py --epochs 50 -./run.sh -v cpu -e module1_fundamentals/01_classical_vs_quantum_bits.py --shots 10000 +# Start container in background +docker compose up -d qc101-nvidia + +# Exec into container +docker exec -it qc101-nvidia bash + +# Inside container - your edits from host are visible +cd /home/qc101/quantum-computing-101/examples +python module1_fundamentals/01_classical_vs_quantum_bits.py ``` -## πŸ› οΈ Requirements Architecture +#### 3. Jupyter Notebook with Volume Mounts -The new requirements system uses a modular approach for optimal Docker layer caching: +```bash +# Start with Jupyter +docker compose up qc101-nvidia +# Access Jupyter at http://localhost:8889 +# All notebooks saved in container β†’ Synced to host examples/ ``` -docker/requirements/ -β”œβ”€β”€ base.txt # Core quantum frameworks (Qiskit, Cirq, PennyLane) -β”œβ”€β”€ cpu.txt # CPU optimizations + base requirements -β”œβ”€β”€ gpu-nvidia.txt # NVIDIA CUDA packages + base requirements -└── gpu-amd.txt # AMD ROCm packages + base requirements + +### Advanced Volume Configurations + +#### Option A: Mount Entire Project (Full Development Mode) + +Edit `docker-compose.yml`: + +```yaml +volumes: + # Mount entire project for maximum flexibility + - ..:/home/qc101/quantum-computing-101 + # But exclude certain directories + - /home/qc101/quantum-computing-101/.git + - /home/qc101/quantum-computing-101/__pycache__ ``` -**Benefits:** -- **Layer Caching**: Base requirements cached separately from GPU-specific packages -- **Faster Builds**: Only GPU layers rebuilt when GPU requirements change -- **Smaller Images**: No unnecessary packages in each variant -- **Maintainability**: Clear separation of concerns +**Use when:** Developing library code, not just examples -## πŸŽ“ Educational Benefits +#### Option B: Selective File Mounting -### For Students -- **Zero Setup**: Docker handles all dependencies -- **Consistent Results**: Identical environment across all machines -- **Hardware Scaling**: Progress from CPU to GPU as needed -- **Cloud Ready**: Easy deployment to cloud GPU instances +```yaml +volumes: + # Mount specific files/directories only + - ../examples:/home/qc101/quantum-computing-101/examples + - ../outputs:/home/qc101/quantum-computing-101/outputs + - ../src:/home/qc101/quantum-computing-101/src + - ../tests:/home/qc101/quantum-computing-101/tests +``` -### For Educators -- **Classroom Deployment**: Students only need Docker -- **Resource Management**: CPU limits prevent system overload -- **Multi-Platform**: Works on Windows/Mac/Linux -- **Scalable**: Deploy to cloud for entire classes +**Use when:** You want precise control over what's mounted -### For Researchers -- **GPU Acceleration**: 5-8x speedup for large quantum simulations -- **Reproducible Research**: Exact environment sharing -- **Multi-GPU Support**: NVIDIA and AMD compatibility -- **Cloud Integration**: Easy scaling to cloud GPU clusters +#### Option C: Using .dockerignore -## 🚨 Hardware Requirements & Setup +Create `docker/.dockerignore`: -### NVIDIA GPU Setup -```bash -# Install NVIDIA Docker (Ubuntu) -distribution=$(. /etc/os-release;echo $ID$VERSION_ID) -curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - -curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list -sudo apt-get update && sudo apt-get install -y nvidia-docker2 -sudo systemctl restart docker +``` +.git +__pycache__ +*.pyc +.pytest_cache +.venv +node_modules +*.log +``` -# Test NVIDIA Docker -docker run --rm --gpus all nvidia/cuda:12.2-base-ubuntu22.04 nvidia-smi +Then mount entire project: +```yaml +volumes: + - ..:/home/qc101/quantum-computing-101 ``` -### AMD ROCm Setup +### Docker Run Command with Volume Mounts + +If not using docker-compose: + ```bash -# Install ROCm (Ubuntu 22.04) -wget -q -O - https://repo.radeon.com/rocm/rocm.gpg.key | sudo apt-key add - -echo 'deb [arch=amd64] https://repo.radeon.com/rocm/apt/5.6/ ubuntu main' | sudo tee /etc/apt/sources.list.d/rocm.list -sudo apt update && sudo apt install -y rocm-dev +# NVIDIA GPU variant +docker run -it --rm \ + --gpus all \ + -v "$(pwd)/../examples:/home/qc101/quantum-computing-101/examples" \ + -v "$(pwd)/../outputs:/home/qc101/quantum-computing-101/outputs" \ + -p 8889:8888 \ + quantum-computing-101:nvidia + +# CPU variant +docker run -it --rm \ + -v "$(pwd)/../examples:/home/qc101/quantum-computing-101/examples" \ + -v "$(pwd)/../outputs:/home/qc101/quantum-computing-101/outputs" \ + -p 8888:8888 \ + quantum-computing-101:cpu +``` + +### VS Code Dev Container Integration + +Create `.devcontainer/devcontainer.json`: + +```json +{ + "name": "Quantum Computing 101", + "dockerComposeFile": "../docker/docker-compose.yml", + "service": "qc101-nvidia", + "workspaceFolder": "/home/qc101/quantum-computing-101", + + "customizations": { + "vscode": { + "extensions": [ + "ms-python.python", + "ms-toolsai.jupyter", + "ms-python.vscode-pylance" + ], + "settings": { + "python.defaultInterpreterPath": "/opt/conda/bin/python", + "python.linting.enabled": true, + "python.linting.pylintEnabled": true + } + } + }, + + "mounts": [ + "source=${localWorkspaceFolder},target=/home/qc101/quantum-computing-101,type=bind,consistency=cached" + ], + + "remoteUser": "qc101" +} +``` + +Then in VS Code: `Ctrl+Shift+P` β†’ "Dev Containers: Reopen in Container" + +### Performance Considerations -# Add user to render group -sudo usermod -a -G render,video $USER -newgrp render +#### Linux/Mac (Native Docker) +- Volume mounts are fast (native filesystem) +- Use `consistency=cached` for better performance (macOS) -# Test ROCm access -ls -la /dev/kfd /dev/dri +#### Windows (WSL2) +- Store project in WSL2 filesystem (`/home/user/project`) +- Avoid mounting from `/mnt/c/` (slow) + +#### Example for Mac (Performance Tuning) +```yaml +volumes: + - ../examples:/home/qc101/quantum-computing-101/examples:cached + - ../outputs:/home/qc101/quantum-computing-101/outputs:delegated ``` -### Minimum Hardware Specifications -| Component | CPU Variant | NVIDIA GPU | AMD ROCm | -|-----------|-------------|------------|----------| -| RAM | 4GB | 8GB | 8GB | -| Storage | 5GB | 15GB | 12GB | -| CPU | 2 cores | 4+ cores | 4+ cores | -| GPU | None | 4GB+ VRAM | 4GB+ VRAM | +- `:cached` - Host writes, container reads (good for code) +- `:delegated` - Container writes, host reads (good for outputs) + +### Volume Mounting Best Practices + +1. **Use Docker Compose** for consistent volume configuration +2. **Mount only what you need** to avoid clutter +3. **Use read-only (`:ro`)** for reference materials +4. **Separate data volumes** for outputs and cache +5. **Add .dockerignore** to exclude unnecessary files +6. **Test both directions**: Hostβ†’Container and Containerβ†’Host writes -## πŸ›‘οΈ Security Features +### Quick Reference Table -- **Non-root Execution**: All containers run as user `qc101` (UID 1000) -- **Read-only Mounts**: Modules and examples mounted read-only by default -- **Resource Limits**: Memory and CPU constraints in docker-compose -- **Health Checks**: Automatic container health monitoring -- **Network Isolation**: Custom Docker network for service communication -- **Secure Defaults**: No hardcoded passwords or keys +| Scenario | Volume Mount | Description | +|----------|--------------|-------------| +| Edit examples | `../examples:/container/examples` | Live code editing | +| Save outputs | `../outputs:/container/outputs` | Persist results | +| Read-only docs | `../docs:/container/docs:ro` | Reference only | +| Full project | `..:/container/project` | Complete access | +| Named volume | `cache:/home/user/.cache` | Persistent cache | -## πŸ› Troubleshooting Guide +### Testing Your Volume Setup -### Common Build Issues ```bash -# Docker out of space -docker system prune -a -docker builder prune +# Test host β†’ container +echo "test from host" > ../examples/test.txt +docker exec qc101-nvidia cat /home/qc101/quantum-computing-101/examples/test.txt -# Permission denied -sudo chown -R $USER:$USER outputs/ -sudo usermod -a -G docker $USER +# Test container β†’ host +docker exec qc101-nvidia bash -c "echo 'test from container' > /home/qc101/quantum-computing-101/outputs/test.txt" +cat ../outputs/test.txt -# NVIDIA Docker not found -sudo systemctl restart docker -docker run --rm --gpus all nvidia/cuda:12.2-base-ubuntu22.04 nvidia-smi +# Cleanup +rm ../examples/test.txt ../outputs/test.txt ``` -### GPU Detection Issues -```bash -# NVIDIA: Check drivers and runtime -nvidia-smi -docker run --rm --gpus all nvidia/cuda:12.2-base-ubuntu22.04 nvidia-smi +## Directory Structure -# AMD: Check device access -ls -la /dev/kfd /dev/dri -groups | grep -E 'render|video' ``` +docker/ +β”œβ”€β”€ Dockerfile # Unified multi-variant Dockerfile +β”œβ”€β”€ docker-compose.yml # Multi-service compose configuration +β”œβ”€β”€ build-unified.sh # Unified build script +β”œβ”€β”€ entrypoint.sh # Container entry point +β”œβ”€β”€ requirements/ +β”‚ β”œβ”€β”€ base.txt # Common dependencies +β”‚ β”œβ”€β”€ cpu.txt # CPU-specific dependencies +β”‚ β”œβ”€β”€ gpu-nvidia.txt # NVIDIA GPU dependencies +β”‚ └── gpu-amd.txt # AMD GPU dependencies +β”œβ”€β”€ build.sh # [DEPRECATED] Old build script +β”œβ”€β”€ Dockerfile.base # [DEPRECATED] Old base Dockerfile +β”œβ”€β”€ Dockerfile.cpu # [DEPRECATED] Old CPU Dockerfile +β”œβ”€β”€ Dockerfile.gpu-nvidia # [DEPRECATED] Old NVIDIA Dockerfile +└── Dockerfile.gpu-amd # [DEPRECATED] Old AMD Dockerfile +``` + +## Requirements Files Structure + +### base.txt +Common dependencies for all variants: +- Qiskit core frameworks +- Scientific computing (NumPy, SciPy, Matplotlib) +- Machine learning (scikit-learn) +- Jupyter Lab + +### cpu.txt +CPU-optimized packages: +- PyTorch CPU version +- TensorFlow CPU version + +### gpu-nvidia.txt +NVIDIA GPU-optimized packages: +- CuPy (CUDA arrays) +- qiskit-aer-gpu (GPU-accelerated quantum simulation) +- PyTorch CUDA support +- CUDA tools and monitoring + +### gpu-amd.txt +AMD GPU-optimized packages: +- ROCm-specific tools +- qiskit-aer (with ROCm support) + +## Environment Variables + +### Common +- `QC101_VARIANT`: cpu|gpu-nvidia|gpu-amd +- `PYTHONUNBUFFERED=1`: Real-time Python output +- `MPLBACKEND=Agg`: Non-interactive matplotlib backend + +### NVIDIA-Specific +- `NVIDIA_VISIBLE_DEVICES=all`: Expose all GPUs +- `NVIDIA_DRIVER_CAPABILITIES=compute,utility`: GPU capabilities +- `CUDA_VISIBLE_DEVICES=all`: CUDA device visibility + +### AMD-Specific +- `ROCM_VISIBLE_DEVICES=all`: Expose all ROCm devices +- `HIP_VISIBLE_DEVICES=all`: HIP device visibility + +## Jupyter Lab Access + +Each variant runs Jupyter Lab on different ports to avoid conflicts: + +- CPU: http://localhost:8888 +- NVIDIA: http://localhost:8889 +- AMD: http://localhost:8890 -### Performance Issues +Start Jupyter Lab inside container: ```bash -# Monitor container resources -docker stats +jupyter lab --ip=0.0.0.0 --port=8888 --no-browser +``` + +## Advanced Configuration + +### Custom PyTorch/CUDA Versions -# Check GPU usage -nvidia-smi # NVIDIA -rocm-smi # AMD +Edit `build-unified.sh` or pass build args: + +```bash +docker build \ + --build-arg VARIANT=nvidia \ + --build-arg PYTORCH_VERSION=2.9.0 \ + --build-arg CUDA_VERSION=12.9 \ + --build-arg CUDNN_VERSION=9 \ + -t quantum-computing-101:nvidia-custom \ + -f docker/Dockerfile . +``` -# Container hardware info -./run.sh -v gpu-nvidia --info +### Multi-GPU Configuration + +```yaml +# docker-compose.yml +deploy: + resources: + reservations: + devices: + - driver: nvidia + device_ids: ['0', '1'] # Specific GPUs + capabilities: [gpu] ``` -### Port Conflicts +## Troubleshooting + +### NVIDIA GPU not detected + ```bash -# Find running services -netstat -tlnp | grep :888 -lsof -i :8888 +# Check NVIDIA driver +nvidia-smi -# Use alternative ports -./run.sh -j # Will auto-detect and use alternative port +# Check Docker NVIDIA runtime +docker run --rm --gpus all nvidia/cuda:12.9.1-base nvidia-smi + +# Install nvidia-container-toolkit if missing +sudo apt-get install -y nvidia-container-toolkit +sudo systemctl restart docker ``` -## πŸ“Š Container Orchestration Examples +### AMD GPU issues -### Development Workflow ```bash -# Terminal 1: Build all variants -./build.sh all +# Check ROCm installation +rocm-smi -# Terminal 2: Start Jupyter for development -./run.sh -v gpu-nvidia -j +# Verify device permissions +ls -l /dev/kfd /dev/dri -# Terminal 3: Run tests in CPU container -./run.sh -v cpu -e verify_examples.py +# Add user to video/render groups +sudo usermod -a -G video,render $USER +``` + +### Build failures + +```bash +# Clean Docker cache +docker builder prune -a + +# Rebuild without cache +./build-unified.sh nvidia --no-cache -# Terminal 4: Interactive debugging -./run.sh -v cpu -i +# Check disk space +df -h ``` -### Classroom Deployment +### Volume Mount Issues + +#### Permission Problems ```bash -# Teacher setup (cloud VM) -git clone https://github.com/your-repo/quantum-computing-101.git -cd quantum-computing-101/docker -./build.sh all - -# Deploy Jupyter for each student -for student in {1..30}; do - docker run -d --name qc101-student-$student \ - -p $((8888 + student)):8888 \ - -v ./student-$student:/home/qc101/workspace \ - quantum101:cpu \ - jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root -done +# Fix ownership if needed +docker exec -it qc101-nvidia chown -R qc101:qc101 /home/qc101/quantum-computing-101 ``` -### Research Scaling +#### Files Not Syncing ```bash -# Multi-GPU research setup -docker-compose -f docker-compose.yml -f docker-compose.research.yml up -d +# Restart container to remount volumes +docker compose restart qc101-nvidia -# Run parameter sweep across containers -for params in param1 param2 param3; do - ./run.sh -v gpu-nvidia -e module6_machine_learning/research_experiment.py --params $params & -done +# Or recreate container +docker compose down +docker compose up qc101-nvidia ``` -## πŸ“š Additional Resources +#### Check Mount Points +```bash +# Inside container, verify mounts +docker exec -it qc101-nvidia df -h +docker exec -it qc101-nvidia mount | grep qc101 +``` -### Documentation -- **[Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)** -- **[NVIDIA Container Toolkit](https://github.com/NVIDIA/nvidia-docker)** -- **[AMD ROCm Docker](https://rocmdocs.amd.com/en/latest/Installation_Guide/Docker.html)** +## Migration Guide -### Quantum Computing Frameworks -- **[Qiskit GPU Backend](https://qiskit.org/documentation/apidoc/aer_gpu.html)** -- **[Cirq Simulation](https://quantumai.google/cirq/simulate/simulation)** -- **[PennyLane Devices](https://pennylane.readthedocs.io/en/stable/introduction/devices.html)** +### From Old Structure to New -### Performance Optimization -- **[Docker BuildKit](https://docs.docker.com/develop/dev-best-practices/#use-multi-stage-builds)** -- **[GPU Memory Management](https://pytorch.org/docs/stable/notes/cuda.html#memory-management)** -- **[Quantum Circuit Optimization](https://qiskit.org/textbook/ch-quantum-hardware/error-correction-repetition-code.html)** +1. **Backup old files** (already done as `.old` files) +2. **Use new build script**: `./build-unified.sh` instead of `./build.sh` +3. **Update compose commands**: Use service names `qc101-cpu`, `qc101-nvidia`, `qc101-amd` +4. **Check requirements**: Verify your dependencies in consolidated `requirements/` files ---- +### Key Changes -## 🎯 Quick Reference Commands +- βœ… Single `Dockerfile` instead of 4 separate files +- βœ… Unified `build-unified.sh` script +- βœ… Updated `docker-compose.yml` with 3 services +- βœ… Centralized `entrypoint.sh` for all variants +- βœ… Improved layer caching and build times -### Essential Commands -```bash -# Build and run CPU variant -./build.sh cpu && ./run.sh -v cpu -i +## Performance Tips -# Build and run NVIDIA GPU variant -./build.sh gpu-nvidia && ./run.sh -v gpu-nvidia -i +1. **Use BuildKit**: `DOCKER_BUILDKIT=1 ./build-unified.sh nvidia` +2. **Parallel builds**: Build multiple variants simultaneously +3. **Volume mounts**: Use volumes for `examples/` and `outputs/` for hot-reloading +4. **Cache volumes**: Persistent pip cache across rebuilds -# Start Jupyter Lab (auto-detects available GPU) -./run.sh -j +## Contributing -# Run example with GPU acceleration -./run.sh -v gpu-nvidia -e module6_machine_learning/01_quantum_neural_network.py +When adding new dependencies: -# List all available examples -./run.sh -l +1. Add to appropriate `requirements/*.txt` file +2. Test build: `./build-unified.sh --no-cache` +3. Verify in container: `docker run -it quantum-computing-101:` +4. Update this README if needed -# Clean up everything -./build.sh clean -``` +## License -Ready to explore quantum computing with Docker! πŸš€βš›οΈ \ No newline at end of file +This Docker setup is part of the Quantum Computing 101 project. +See main project LICENSE for details. diff --git a/docker/build-unified.sh b/docker/build-unified.sh new file mode 100755 index 0000000..be2e981 --- /dev/null +++ b/docker/build-unified.sh @@ -0,0 +1,225 @@ +#!/bin/bash +# Quantum Computing 101 - Unified Build Script +# Supports CPU, NVIDIA GPU, and AMD GPU variants with best practices + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +BLUE='\033[0;34m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +# Script directory +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" + +# Default values +VARIANT="${1:-cpu}" +NO_CACHE="${2:-false}" +PYTORCH_VERSION="2.8.0" +CUDA_VERSION="12.9" +CUDNN_VERSION="9" + +# ============================================================================= +# Functions +# ============================================================================= + +print_header() { + echo -e "${BLUE}" + echo "🐳 Quantum Computing 101 - Docker Build System v3.0" + echo "=====================================================" + echo -e "${NC}" +} + +print_success() { + echo -e "${GREEN}[SUCCESS]${NC} $1" +} + +print_error() { + echo -e "${RED}[ERROR]${NC} $1" +} + +print_info() { + echo -e "${BLUE}[INFO]${NC} $1" +} + +print_warning() { + echo -e "${YELLOW}[WARNING]${NC} $1" +} + +check_docker() { + if ! command -v docker &> /dev/null; then + print_error "Docker is not installed" + exit 1 + fi + + if ! docker info &> /dev/null; then + print_error "Docker daemon is not running" + exit 1 + fi + + print_success "Docker is available and running" +} + +detect_gpu() { + local gpu_type="none" + + # Check for NVIDIA GPU + if command -v nvidia-smi &> /dev/null && nvidia-smi &> /dev/null; then + local gpu_count=$(nvidia-smi --list-gpus 2>/dev/null | wc -l) + print_success "NVIDIA GPU detected (${gpu_count} GPU(s))" >&2 + gpu_type="nvidia" + # Check for AMD GPU + elif [ -d "/opt/rocm" ] || command -v rocm-smi &> /dev/null; then + print_success "AMD ROCm GPU detected" >&2 + gpu_type="amd" + else + print_info "No GPU detected, CPU-only mode available" >&2 + gpu_type="cpu" + fi + + echo "$gpu_type" +} + +show_usage() { + cat << EOF +Usage: $0 [VARIANT] [OPTIONS] + +Build Docker images for Quantum Computing 101 + +VARIANTS: + cpu Build CPU-only image (default) + nvidia Build NVIDIA CUDA GPU image + amd Build AMD ROCm GPU image + all Build all variants + +OPTIONS: + --no-cache Build without using cache + --help Show this help message + +EXAMPLES: + $0 cpu # Build CPU variant + $0 nvidia # Build NVIDIA GPU variant + $0 amd # Build AMD GPU variant + $0 nvidia --no-cache # Build NVIDIA variant without cache + $0 all # Build all variants + +EOF + exit 0 +} + +build_image() { + local variant=$1 + local no_cache_flag="" + + if [ "$NO_CACHE" = "true" ] || [ "$NO_CACHE" = "--no-cache" ]; then + no_cache_flag="--no-cache" + print_info "Building without cache" + fi + + print_info "Building ${variant} variant..." + + local build_args="--build-arg VARIANT=${variant}" + + if [ "$variant" = "nvidia" ]; then + build_args="${build_args} --build-arg PYTORCH_VERSION=${PYTORCH_VERSION}" + build_args="${build_args} --build-arg CUDA_VERSION=${CUDA_VERSION}" + build_args="${build_args} --build-arg CUDNN_VERSION=${CUDNN_VERSION}" + fi + + local start_time=$(date +%s) + + if docker build \ + -f "${SCRIPT_DIR}/Dockerfile" \ + -t "quantum-computing-101:${variant}" \ + --target runtime \ + ${build_args} \ + ${no_cache_flag} \ + "${PROJECT_ROOT}"; then + + local end_time=$(date +%s) + local duration=$((end_time - start_time)) + + print_success "${variant} variant build completed in ${duration}s" + + # Show image info + local size=$(docker images "quantum-computing-101:${variant}" --format "{{.Size}}") + echo -e " ${BLUE}Image:${NC} quantum-computing-101:${variant}" + echo -e " ${BLUE}Size:${NC} $size" + echo "" + + return 0 + else + print_error "${variant} variant build failed" + return 1 + fi +} + +# ============================================================================= +# Main Script +# ============================================================================= + +print_header + +# Parse arguments +if [ "$1" = "--help" ] || [ "$1" = "-h" ]; then + show_usage +fi + +# Check for --no-cache flag +if [ "$2" = "--no-cache" ] || [ "$1" = "--no-cache" ]; then + NO_CACHE="true" +fi + +# Check Docker +check_docker + +# Detect GPU +GPU_TYPE=$(detect_gpu) + +# Validate variant selection +case "$VARIANT" in + cpu) + print_info "Building CPU-only variant" + ;; + nvidia) + if [ "$GPU_TYPE" != "nvidia" ]; then + print_warning "NVIDIA GPU not detected, but building NVIDIA variant anyway" + fi + print_info "Building NVIDIA CUDA GPU variant" + ;; + amd) + if [ "$GPU_TYPE" != "amd" ]; then + print_warning "AMD GPU not detected, but building AMD variant anyway" + fi + print_info "Building AMD ROCm GPU variant" + ;; + all) + print_info "Building all variants" + build_image "cpu" && \ + build_image "nvidia" && \ + build_image "amd" + + print_success "All variants built successfully" + exit 0 + ;; + *) + print_error "Unknown variant: $VARIANT" + echo "Valid variants: cpu, nvidia, amd, all" + echo "Use --help for more information" + exit 1 + ;; +esac + +# Build the selected variant +build_image "$VARIANT" + +print_success "Build complete!" +echo "" +echo "To run the container:" +echo " docker run -it --rm quantum-computing-101:${VARIANT}" +echo "" +echo "Or use Docker Compose:" +echo " docker-compose up qc101-${VARIANT}" diff --git a/docker/build.sh b/docker/build.sh deleted file mode 100755 index 17a9a85..0000000 --- a/docker/build.sh +++ /dev/null @@ -1,336 +0,0 @@ -#!/bin/bash -# Build script for Quantum Computing 101 Docker containers v2.0 -# Now supports CPU, NVIDIA CUDA, and AMD ROCm variants - -set -e # Exit on any error - -# Colors for output -RED='\033[0;31m' -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -BLUE='\033[0;34m' -PURPLE='\033[0;35m' -NC='\033[0m' # No Color - -# Function to print colored output -print_status() { - echo -e "${BLUE}[INFO]${NC} $1" -} - -print_success() { - echo -e "${GREEN}[SUCCESS]${NC} $1" -} - -print_warning() { - echo -e "${YELLOW}[WARNING]${NC} $1" -} - -print_error() { - echo -e "${RED}[ERROR]${NC} $1" -} - -print_gpu() { - echo -e "${PURPLE}[GPU]${NC} $1" -} - -# Function to check Docker availability -check_docker() { - if ! command -v docker &> /dev/null; then - print_error "Docker is not installed or not in PATH" - exit 1 - fi - - if ! docker info &> /dev/null; then - print_error "Docker daemon is not running" - exit 1 - fi - - print_success "Docker is available and running" -} - -# Function to check NVIDIA Docker support -check_nvidia_docker() { - if command -v nvidia-docker &> /dev/null || docker info | grep -q nvidia; then - # Additional check for nvidia-smi - if nvidia-smi &> /dev/null; then - local gpu_count=$(nvidia-smi --query-gpu=count --format=csv,noheader,nounits | head -1) - print_gpu "NVIDIA Docker support detected with $gpu_count GPU(s)" - return 0 - else - print_warning "NVIDIA Docker runtime detected but nvidia-smi failed" - return 1 - fi - else - print_warning "NVIDIA Docker support not detected" - return 1 - fi -} - -# Function to check AMD ROCm support -check_rocm_support() { - if [ -d "/opt/rocm" ] && command -v rocm-smi &> /dev/null; then - print_gpu "AMD ROCm installation detected" - return 0 - elif [ -e "/dev/kfd" ] && [ -e "/dev/dri" ]; then - print_gpu "AMD GPU devices detected (/dev/kfd and /dev/dri present)" - return 0 - else - print_warning "AMD ROCm support not detected (no /dev/kfd or /dev/dri devices)" - return 1 - fi -} - -# Function to build a specific variant -build_variant() { - local variant=$1 - local dockerfile=$2 - local tag=$3 - local description=$4 - - print_status "Building $description..." - - # Change to project root directory - cd "$(dirname "$0")/.." - - # Check if Dockerfile exists - if [ ! -f "docker/$dockerfile" ]; then - print_error "Dockerfile not found: docker/$dockerfile" - return 1 - fi - - # Build the image with build context optimization - local start_time=$(date +%s) - - if docker build \ - -f "docker/$dockerfile" \ - -t "$tag" \ - --build-arg BUILDKIT_INLINE_CACHE=1 \ - .; then - - local end_time=$(date +%s) - local duration=$((end_time - start_time)) - - print_success "$description build completed in ${duration}s" - - # Show image info - local size=$(docker images "$tag" --format "{{.Size}}") - local created=$(docker images "$tag" --format "{{.CreatedAt}}") - echo -e " ${BLUE}Tag:${NC} $tag" - echo -e " ${BLUE}Size:${NC} $size" - echo -e " ${BLUE}Created:${NC} $created" - - return 0 - else - print_error "$description build failed" - return 1 - fi -} - -# Function to build all variants -build_all() { - print_status "Building all available Quantum Computing 101 Docker variants..." - echo "" - - local success_count=0 - local total_count=0 - local variants_built=() - local variants_failed=() - - # Build CPU variant (always available) - ((total_count++)) - if build_variant "cpu" "Dockerfile.cpu" "quantum101:cpu" "CPU-only variant"; then - ((success_count++)) - variants_built+=("quantum101:cpu (CPU-only)") - else - variants_failed+=("quantum101:cpu (CPU-only)") - fi - echo "" - - # Build NVIDIA GPU variant (if available) - if check_nvidia_docker; then - ((total_count++)) - if build_variant "gpu-nvidia" "Dockerfile.gpu-nvidia" "quantum101:gpu-nvidia" "NVIDIA CUDA GPU variant"; then - ((success_count++)) - variants_built+=("quantum101:gpu-nvidia (NVIDIA CUDA)") - else - variants_failed+=("quantum101:gpu-nvidia (NVIDIA CUDA)") - fi - echo "" - fi - - # Build AMD ROCm variant (if available) - if check_rocm_support; then - ((total_count++)) - if build_variant "gpu-amd" "Dockerfile.gpu-amd" "quantum101:gpu-amd" "AMD ROCm GPU variant"; then - ((success_count++)) - variants_built+=("quantum101:gpu-amd (AMD ROCm)") - else - variants_failed+=("quantum101:gpu-amd (AMD ROCm)") - fi - echo "" - fi - - # Build base variant - ((total_count++)) - if build_variant "base" "Dockerfile.base" "quantum101:base" "Base development variant"; then - ((success_count++)) - variants_built+=("quantum101:base (Development)") - else - variants_failed+=("quantum101:base (Development)") - fi - - # Summary - echo "" - echo "==========================================" - print_status "Build Summary: $success_count/$total_count variants built successfully" - echo "" - - if [ ${#variants_built[@]} -gt 0 ]; then - print_success "Successfully built variants:" - for variant in "${variants_built[@]}"; do - echo -e " ${GREEN}βœ“${NC} $variant" - done - fi - - if [ ${#variants_failed[@]} -gt 0 ]; then - echo "" - print_error "Failed variants:" - for variant in "${variants_failed[@]}"; do - echo -e " ${RED}βœ—${NC} $variant" - done - fi - - if [ $success_count -eq $total_count ]; then - echo "" - print_success "πŸŽ‰ All available variants built successfully!" - echo "" - print_status "Available images:" - docker images quantum101 --format "table {{.Repository}}:{{.Tag}}\t{{.Size}}\t{{.CreatedAt}}" - echo "" - print_status "Quick start commands:" - echo -e " ${BLUE}CPU:${NC} ./run.sh -v cpu -i" - if check_nvidia_docker; then - echo -e " ${BLUE}NVIDIA GPU:${NC} ./run.sh -v gpu-nvidia -i" - fi - if check_rocm_support; then - echo -e " ${BLUE}AMD ROCm:${NC} ./run.sh -v gpu-amd -i" - fi - else - echo "" - print_warning "Some builds failed. Check the output above for details." - exit 1 - fi -} - -# Function to show usage -show_usage() { - echo "Usage: $0 [OPTION]" - echo "" - echo "Build Quantum Computing 101 Docker containers with GPU support" - echo "" - echo "Options:" - echo " cpu Build CPU-only variant (lightweight, always available)" - echo " gpu-nvidia Build NVIDIA CUDA GPU variant (requires NVIDIA Docker)" - echo " gpu-amd Build AMD ROCm GPU variant (requires AMD GPU devices)" - echo " base Build base development variant" - echo " all Build all available variants (default)" - echo " clean Remove all quantum101 images and containers" - echo " help Show this help message" - echo "" - echo "Examples:" - echo " $0 # Build all available variants" - echo " $0 cpu # Build only CPU variant" - echo " $0 gpu-nvidia # Build only NVIDIA GPU variant" - echo " $0 gpu-amd # Build only AMD ROCm variant" - echo " $0 clean # Clean up all images" - echo "" - echo "Hardware Requirements:" - echo " CPU variant: Any x86_64 system with Docker" - echo " NVIDIA variant: NVIDIA GPU + CUDA drivers + nvidia-docker" - echo " AMD variant: AMD GPU + ROCm drivers + /dev/kfd,/dev/dri access" -} - -# Function to clean up images -clean_images() { - print_status "Cleaning up Quantum Computing 101 Docker images and containers..." - - # Stop and remove containers - local containers=$(docker ps -a --filter "ancestor=quantum101" --format "{{.ID}}" 2>/dev/null || true) - if [ -n "$containers" ]; then - echo "$containers" | xargs docker rm -f - print_success "Removed containers" - fi - - # Remove images - local images=$(docker images quantum101 -q 2>/dev/null || true) - if [ -n "$images" ]; then - echo "$images" | xargs docker rmi -f - print_success "Removed images" - else - print_warning "No quantum101 images found to remove" - fi - - # Clean up build cache - docker builder prune -f > /dev/null 2>&1 || true - print_success "Cleaned build cache" -} - -# Main execution -main() { - local action=${1:-all} - - echo "🐳 Quantum Computing 101 Docker Builder v2.0" - echo "=============================================" - echo "" - - case $action in - cpu) - check_docker - build_variant "cpu" "Dockerfile.cpu" "quantum101:cpu" "CPU-only variant" - ;; - gpu-nvidia) - check_docker - if check_nvidia_docker; then - build_variant "gpu-nvidia" "Dockerfile.gpu-nvidia" "quantum101:gpu-nvidia" "NVIDIA CUDA GPU variant" - else - print_error "NVIDIA Docker support required for GPU builds" - echo "Install: https://github.com/NVIDIA/nvidia-docker" - exit 1 - fi - ;; - gpu-amd) - check_docker - if check_rocm_support; then - build_variant "gpu-amd" "Dockerfile.gpu-amd" "quantum101:gpu-amd" "AMD ROCm GPU variant" - else - print_error "AMD ROCm support required for AMD GPU builds" - echo "Ensure ROCm is installed and /dev/kfd, /dev/dri devices are available" - exit 1 - fi - ;; - base) - check_docker - build_variant "base" "Dockerfile.base" "quantum101:base" "Base development variant" - ;; - all) - check_docker - build_all - ;; - clean) - check_docker - clean_images - ;; - help|--help|-h) - show_usage - ;; - *) - print_error "Unknown option: $action" - echo "" - show_usage - exit 1 - ;; - esac -} - -# Run main function with all arguments -main "$@" \ No newline at end of file diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh new file mode 100755 index 0000000..492b60f --- /dev/null +++ b/docker/entrypoint.sh @@ -0,0 +1,44 @@ +#!/bin/bash +# Entrypoint script for Quantum Computing 101 containers + +set -e + +# Detect hardware and display information +echo "🐳 Quantum Computing 101 Container" +echo "====================================" + +# Detect variant +if command -v nvidia-smi &> /dev/null; then + echo "Platform: NVIDIA CUDA GPU" + echo "CUDA Version: $(nvcc --version | grep "release" | awk '{print $6}' | cut -c2- || echo 'N/A')" + nvidia-smi --query-gpu=name,memory.total --format=csv,noheader 2>/dev/null || echo "GPU info not available" + + # Check PyTorch CUDA + python -c "import torch; print(f'PyTorch CUDA Available: {torch.cuda.is_available()}')" 2>/dev/null || true +elif command -v rocm-smi &> /dev/null; then + echo "Platform: AMD ROCm GPU" + rocm-smi --showproductname 2>/dev/null || echo "ROCm GPU detected" + + # Check PyTorch ROCm + python -c "import torch; print(f'PyTorch ROCm Available: {torch.cuda.is_available()}')" 2>/dev/null || true +else + echo "Platform: CPU Only" +fi + +# Display Python and package versions +echo "" +echo "Python: $(python --version 2>&1)" +python -c "import qiskit; print(f'Qiskit: {qiskit.__version__}')" 2>/dev/null || echo "Qiskit: Not installed" +python -c "import numpy; print(f'NumPy: {numpy.__version__}')" 2>/dev/null || echo "NumPy: Not installed" + +echo "" +echo "====================================" +echo "Working directory: $(pwd)" +echo "" +echo "Quick start:" +echo " python module1_fundamentals/01_classical_vs_quantum_bits.py" +echo " jupyter lab --ip=0.0.0.0 --port=8888 --no-browser" +echo "" + +# Execute the command passed to docker run +exec "$@" diff --git a/docker/requirements/base.txt b/docker/requirements/base.txt index 7945763..36092ce 100644 --- a/docker/requirements/base.txt +++ b/docker/requirements/base.txt @@ -1,5 +1,8 @@ -# Base requirements for all Quantum Computing 101 variants -# Core quantum computing frameworks and scientific computing stack +# Docker Base Requirements for Quantum Computing 101 +# Purpose: Common dependencies for ALL Docker container variants (CPU, NVIDIA, AMD) +# Used by: docker/Dockerfile (all variants via multi-stage build) +# Sync: Keep version numbers aligned with examples/requirements.txt +# Note: Do not add variant-specific packages here (use cpu.txt, gpu-nvidia.txt, gpu-amd.txt) # Core quantum computing frameworks qiskit>=1.0.0 diff --git a/docker/requirements/cpu.txt b/docker/requirements/cpu.txt index 23e2051..e642459 100644 --- a/docker/requirements/cpu.txt +++ b/docker/requirements/cpu.txt @@ -1,19 +1,20 @@ -# CPU-specific requirements for Quantum Computing 101 -# Optimized for CPU-only quantum simulations +# Docker CPU-Only Requirements for Quantum Computing 101 +# Purpose: CPU-specific packages (no GPU acceleration) +# Base Image: python:3.12-slim +# Note: PyTorch CPU version is already included in the base image +# Extends: base.txt -# Include base requirements +# Include base quantum computing requirements -r base.txt -# CPU version of qiskit-aer (standard package) +# CPU version of Qiskit Aer simulator qiskit-aer>=0.14.0 -# CPU-optimized BLAS libraries (will be handled at system level in Dockerfile) -# Additional CPU performance packages could go here +# Machine learning tools +tensorboard>=2.15.0 -# CPU-only PyTorch for basic ML examples (if needed) -# torch>=2.1.0+cpu --index-url https://download.pytorch.org/whl/cpu -# torchvision>=0.16.0+cpu --index-url https://download.pytorch.org/whl/cpu - -# Memory profiling and performance tools -psutil>=5.9.0 -memory-profiler>=0.60.0 \ No newline at end of file +# Cloud platform integration +qiskit-ibm-runtime>=0.18.0 +qiskit-ibm-provider>=0.8.0 +amazon-braket-sdk>=1.74.0 +boto3>=1.34.0 diff --git a/docker/requirements/gpu-amd.txt b/docker/requirements/gpu-amd.txt index bdd0b5f..29c7471 100644 --- a/docker/requirements/gpu-amd.txt +++ b/docker/requirements/gpu-amd.txt @@ -1,35 +1,23 @@ -# AMD ROCm GPU requirements for Quantum Computing 101 -# Optimized for AMD GPU acceleration with ROCm 6.x +# Docker AMD ROCm GPU Requirements for Quantum Computing 101 +# Purpose: AMD ROCm-accelerated packages +# Base Image: rocm/pytorch:latest +# Note: PyTorch with ROCm is already included in the base image +# Extends: base.txt -# Include base requirements +# Include base quantum computing requirements -r base.txt -# AMD ROCm specific packages -# Note: PyTorch with ROCm is included in the base ROCm/PyTorch Docker image -# Additional ROCm packages for enhanced performance -# CuPy ROCm support (ROCm 6.x compatible) -cupy-rocm-5-0>=13.0.0 +# GPU-accelerated Qiskit Aer simulator (will use available GPU backend) +qiskit-aer-gpu>=0.14.0 -# GPU monitoring and utilities for ROCm -rocm-smi>=6.0.0 +# AMD ROCm utilities +rocm-smi-lib>=0.1.0 -# Memory and performance profiling for ROCm -py3nvml>=0.2.7 -psutil>=5.9.0 -memory-profiler>=0.60.0 - -# Additional ML and visualization tools +# Machine learning tools tensorboard>=2.15.0 -tensorboard-plugin-profile>=2.15.0 -# IBM Quantum cloud access (for Module 7) +# Cloud platform integration qiskit-ibm-runtime>=0.18.0 qiskit-ibm-provider>=0.8.0 - -# Cloud platform SDKs amazon-braket-sdk>=1.74.0 boto3>=1.34.0 - -# Note: Qiskit-Aer with ROCm support is built from source in Dockerfile -# PyTorch with ROCm comes pre-installed in the rocm/pytorch base image -# Most quantum acceleration comes from optimized linear algebra libraries \ No newline at end of file diff --git a/docker/requirements/gpu-nvidia.txt b/docker/requirements/gpu-nvidia.txt index 790aed0..05b138b 100644 --- a/docker/requirements/gpu-nvidia.txt +++ b/docker/requirements/gpu-nvidia.txt @@ -1,35 +1,29 @@ -# NVIDIA CUDA GPU requirements for Quantum Computing 101 -# Optimized for NVIDIA GPU acceleration - -# Include base requirements +# Docker NVIDIA GPU Requirements for Quantum Computing 101 +# Purpose: NVIDIA CUDA-accelerated packages +# Base Image: pytorch/pytorch:2.8.0-cuda12.9-cudnn9-devel +# CUDA Version: 12.9.1 with cuDNN 9 +# Note: PyTorch with CUDA is already included in the base image +# Extends: base.txt + +# Include base quantum computing requirements -r base.txt -# NVIDIA CUDA specific packages +# CuPy for GPU-accelerated NumPy operations (CUDA 12.x) cupy-cuda12x>=12.0.0 -# Install qiskit-aer-gpu instead of regular qiskit-aer for CUDA support -qiskit-aer-gpu>=0.14.0 - -# PyTorch with CUDA support (CUDA 12.4 is latest supported by PyTorch) ---index-url https://download.pytorch.org/whl/cu124 -torch -torchvision -torchaudio -# Additional ML and visualization tools -tensorboard>=2.15.0 -tensorboard-plugin-profile>=2.15.0 +# GPU-accelerated Qiskit Aer simulator +qiskit-aer-gpu>=0.14.0 # GPU monitoring and utilities gpustat>=1.1.1 nvidia-ml-py>=12.535.133 - -# Memory and performance profiling for GPU py3nvml>=0.2.7 -# IBM Quantum cloud access (for Module 7) +# Machine learning tools +tensorboard>=2.15.0 + +# Cloud platform integration qiskit-ibm-runtime>=0.18.0 qiskit-ibm-provider>=0.8.0 - -# Cloud platform SDKs amazon-braket-sdk>=1.74.0 -boto3>=1.34.0 \ No newline at end of file +boto3>=1.34.0 diff --git a/docker/run.sh b/docker/run.sh deleted file mode 100755 index b68ee07..0000000 --- a/docker/run.sh +++ /dev/null @@ -1,442 +0,0 @@ -#!/bin/bash -# Run script for Quantum Computing 101 Docker containers v2.0 -# Now supports CPU, NVIDIA CUDA, and AMD ROCm variants - -set -e # Exit on any error - -# Colors for output -RED='\033[0;31m' -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -BLUE='\033[0;34m' -PURPLE='\033[0;35m' -NC='\033[0m' # No Color - -# Function to print colored output -print_status() { - echo -e "${BLUE}[INFO]${NC} $1" -} - -print_success() { - echo -e "${GREEN}[SUCCESS]${NC} $1" -} - -print_warning() { - echo -e "${YELLOW}[WARNING]${NC} $1" -} - -print_error() { - echo -e "${RED}[ERROR]${NC} $1" -} - -print_gpu() { - echo -e "${PURPLE}[GPU]${NC} $1" -} - -# Default values -VARIANT="cpu" -INTERACTIVE=true -JUPYTER=false -EXAMPLE="" -MODULE="" -OUTPUTS_DIR="./outputs" - -# Function to check if image exists -check_image() { - local image=$1 - if docker images "$image" --format "{{.Repository}}:{{.Tag}}" | grep -q "$image"; then - return 0 - else - return 1 - fi -} - -# Function to ensure outputs directory exists -ensure_outputs_dir() { - if [ ! -d "$OUTPUTS_DIR" ]; then - mkdir -p "$OUTPUTS_DIR" - print_status "Created outputs directory: $OUTPUTS_DIR" - fi -} - -# Function to get GPU arguments based on variant -get_gpu_args() { - local variant=$1 - case $variant in - gpu-nvidia) - echo "--gpus all --runtime=nvidia" - ;; - gpu-amd) - echo "--device=/dev/kfd --device=/dev/dri --group-add video" - ;; - cpu|*) - echo "" - ;; - esac -} - -# Function to get port based on variant for Jupyter -get_jupyter_port() { - local variant=$1 - case $variant in - cpu) - echo "8888" - ;; - gpu-nvidia) - echo "8889" - ;; - gpu-amd) - echo "8890" - ;; - *) - echo "8888" - ;; - esac -} - -# Function to run interactive container -run_interactive() { - local image=$1 - local gpu_args=$(get_gpu_args "$VARIANT") - - print_status "Starting interactive $VARIANT container..." - - ensure_outputs_dir - - # shellcheck disable=SC2086 - docker run -it --rm \ - $gpu_args \ - -v "$(pwd)/examples:/home/qc101/quantum-computing-101/examples" \ - -v "$(pwd)/$OUTPUTS_DIR:/home/qc101/quantum-computing-101/outputs" \ - -v "$(pwd)/modules:/home/qc101/quantum-computing-101/modules:ro" \ - -w /home/qc101/quantum-computing-101/examples \ - -e PYTHONPATH=/home/qc101/quantum-computing-101 \ - --name "qc101-interactive-$VARIANT" \ - "$image" \ - /bin/bash -} - -# Function to run specific example -run_example() { - local image=$1 - local example_path=$2 - shift 2 # Remove image and example_path from arguments - local gpu_args=$(get_gpu_args "$VARIANT") - - print_status "Running example: $example_path" - print_status "Variant: $VARIANT" - - ensure_outputs_dir - - # Check if example file exists - if [ ! -f "examples/$example_path" ]; then - print_error "Example file not found: examples/$example_path" - exit 1 - fi - - # shellcheck disable=SC2086 - docker run --rm \ - $gpu_args \ - -v "$(pwd)/examples:/home/qc101/quantum-computing-101/examples" \ - -v "$(pwd)/$OUTPUTS_DIR:/home/qc101/quantum-computing-101/outputs" \ - -v "$(pwd)/modules:/home/qc101/quantum-computing-101/modules:ro" \ - -w /home/qc101/quantum-computing-101/examples \ - -e PYTHONPATH=/home/qc101/quantum-computing-101 \ - --name "qc101-example-$VARIANT-$$" \ - "$image" \ - python "$example_path" "$@" -} - -# Function to run Jupyter Lab -run_jupyter() { - local image=$1 - local gpu_args=$(get_gpu_args "$VARIANT") - local port=$(get_jupyter_port "$VARIANT") - - print_status "Starting Jupyter Lab on port $port (variant: $VARIANT)..." - ensure_outputs_dir - - # Check if port is already in use - if netstat -an 2>/dev/null | grep -q ":$port.*LISTEN" || lsof -i :$port &>/dev/null; then - print_warning "Port $port is already in use. Trying to find alternative..." - port=$((port + 10)) - print_status "Using alternative port: $port" - fi - - # Create workspace directory if not exists - local workspace_dir="workspace-$VARIANT" - mkdir -p "$workspace_dir" - - # Install Jupyter and run - # shellcheck disable=SC2086 - docker run -it --rm \ - $gpu_args \ - -p "$port:8888" \ - -v "$(pwd)/examples:/home/qc101/quantum-computing-101/examples" \ - -v "$(pwd)/$OUTPUTS_DIR:/home/qc101/quantum-computing-101/outputs" \ - -v "$(pwd)/modules:/home/qc101/quantum-computing-101/modules:ro" \ - -v "$(pwd)/$workspace_dir:/home/qc101/workspace" \ - -w /home/qc101/quantum-computing-101/examples \ - -e PYTHONPATH=/home/qc101/quantum-computing-101 \ - -e JUPYTER_ENABLE_LAB=yes \ - --name "qc101-jupyter-$VARIANT" \ - "$image" \ - bash -c " - echo 'πŸš€ Setting up Jupyter Lab environment...' - pip install --quiet jupyter jupyterlab ipywidgets - echo 'πŸ“Š Jupyter Lab will be available at: http://localhost:$port' - if [ '$VARIANT' != 'cpu' ]; then - echo 'πŸ”₯ GPU acceleration enabled for variant: $VARIANT' - fi - echo 'πŸ“ Examples: /home/qc101/quantum-computing-101/examples' - echo 'πŸ’Ύ Outputs: /home/qc101/quantum-computing-101/outputs' - echo 'πŸ“ Workspace: /home/qc101/workspace' - echo '' - jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root --NotebookApp.token='' --NotebookApp.password='' - " -} - -# Function to list available examples -list_examples() { - local image=$1 - - print_status "Available examples:" - - docker run --rm \ - -v "$(pwd)/examples:/home/qc101/quantum-computing-101/examples:ro" \ - -w /home/qc101/quantum-computing-101/examples \ - "$image" \ - bash -c " - echo 'Quantum Computing 101 - Available Examples:' - echo '===========================================' - find . -name '*.py' -type f | grep -E 'module[0-9]_' | sort | while read -r file; do - module=\$(echo \$file | cut -d'/' -f2) - example=\$(basename \$file) - echo \" \$file\" - done - echo '' - echo 'Usage examples:' - echo ' ./run.sh -v $VARIANT -e module1_fundamentals/01_classical_vs_quantum_bits.py' - echo ' ./run.sh -v $VARIANT -e module6_machine_learning/01_quantum_neural_network.py' - " -} - -# Function to show hardware info -show_hardware_info() { - local image=$1 - local gpu_args=$(get_gpu_args "$VARIANT") - - print_status "Hardware information for variant: $VARIANT" - - # shellcheck disable=SC2086 - docker run --rm \ - $gpu_args \ - "$image" \ - bash -c " - echo 'Container Hardware Information:' - echo '===============================' - echo 'Variant: $VARIANT' - echo 'CPUs: '\$(nproc) - echo 'Memory: '\$(free -h | awk '/^Mem:/ {print \$2}') - - case '$VARIANT' in - gpu-nvidia) - if command -v nvidia-smi &>/dev/null; then - echo 'GPU Info:' - nvidia-smi --query-gpu=name,memory.total,driver_version --format=csv,noheader,nounits - echo 'CUDA Available: '\$(python -c 'import torch; print(torch.cuda.is_available())' 2>/dev/null || echo 'PyTorch not available') - else - echo 'nvidia-smi not available' - fi - ;; - gpu-amd) - if command -v rocm-smi &>/dev/null; then - echo 'AMD GPU Info:' - rocm-smi --showproductname --showmeminfo | head -10 - else - echo 'rocm-smi not available, but ROCm devices should be accessible' - fi - echo 'PyTorch ROCm Available: '\$(python -c 'import torch; print(torch.cuda.is_available())' 2>/dev/null || echo 'PyTorch not available') - ;; - cpu) - echo 'CPU-only variant - no GPU acceleration' - ;; - esac - - echo 'Python Version: '\$(python --version) - echo 'Qiskit Version: '\$(python -c 'import qiskit; print(qiskit.__version__)' 2>/dev/null || echo 'Qiskit not available') - " -} - -# Function to show usage -show_usage() { - echo "Usage: $0 [OPTIONS]" - echo "" - echo "Run Quantum Computing 101 Docker containers with GPU support" - echo "" - echo "Options:" - echo " -v, --variant VARIANT Container variant: cpu, gpu-nvidia, gpu-amd (default: cpu)" - echo " -e, --example PATH Run specific example (e.g., module1_fundamentals/01_classical_vs_quantum_bits.py)" - echo " -m, --module MODULE List examples in specific module (e.g., module1_fundamentals)" - echo " -j, --jupyter Start Jupyter Lab environment" - echo " -i, --interactive Start interactive shell (default)" - echo " -o, --outputs DIR Output directory (default: ./outputs)" - echo " -l, --list List available examples" - echo " --info Show hardware information" - echo " -h, --help Show this help message" - echo "" - echo "Container Variants:" - echo " cpu Lightweight CPU-only (1.2GB, Python 3.12, OpenBLAS)" - echo " gpu-nvidia NVIDIA CUDA acceleration (3.5GB, CUDA 12.2, PyTorch GPU)" - echo " gpu-amd AMD ROCm acceleration (3.2GB, ROCm 5.6, PyTorch ROCm)" - echo "" - echo "Examples:" - echo " $0 # Interactive CPU container" - echo " $0 -v gpu-nvidia -i # Interactive NVIDIA GPU container" - echo " $0 -v gpu-amd -i # Interactive AMD ROCm container" - echo " $0 -e module1_fundamentals/01_classical_vs_quantum_bits.py # Run specific example" - echo " $0 -v gpu-nvidia -e module6_machine_learning/01_quantum_neural_network.py # GPU ML example" - echo " $0 -j # Start Jupyter Lab (CPU)" - echo " $0 -v gpu-nvidia -j # Start Jupyter Lab (NVIDIA GPU)" - echo " $0 -v gpu-amd -j # Start Jupyter Lab (AMD ROCm)" - echo " $0 -l # List all examples" - echo " $0 --info # Show hardware info" - echo "" - echo "Port Assignments:" - echo " CPU Jupyter: http://localhost:8888" - echo " NVIDIA Jupyter: http://localhost:8889" - echo " AMD ROCm Jupyter: http://localhost:8890" - echo "" - echo "Hardware Requirements:" - echo " cpu variant: Any x86_64 system with Docker" - echo " gpu-nvidia variant: NVIDIA GPU + CUDA drivers + nvidia-docker" - echo " gpu-amd variant: AMD GPU + ROCm drivers + /dev/kfd,/dev/dri access" -} - -# Parse command line arguments -while [[ $# -gt 0 ]]; do - case $1 in - -v|--variant) - VARIANT="$2" - shift 2 - ;; - -e|--example) - EXAMPLE="$2" - INTERACTIVE=false - shift 2 - ;; - -m|--module) - MODULE="$2" - shift 2 - ;; - -j|--jupyter) - JUPYTER=true - INTERACTIVE=false - shift - ;; - -i|--interactive) - INTERACTIVE=true - shift - ;; - -o|--outputs) - OUTPUTS_DIR="$2" - shift 2 - ;; - -l|--list) - INTERACTIVE=false - JUPYTER=false - EXAMPLE="list" - shift - ;; - --info) - INTERACTIVE=false - JUPYTER=false - EXAMPLE="info" - shift - ;; - -h|--help) - show_usage - exit 0 - ;; - *) - print_error "Unknown option: $1" - show_usage - exit 1 - ;; - esac -done - -# Validate variant -if [ "$VARIANT" != "cpu" ] && [ "$VARIANT" != "gpu-nvidia" ] && [ "$VARIANT" != "gpu-amd" ]; then - print_error "Invalid variant: $VARIANT. Must be 'cpu', 'gpu-nvidia', or 'gpu-amd'" - exit 1 -fi - -# Set image name -IMAGE="quantum101:$VARIANT" - -# Check if image exists -if ! check_image "$IMAGE"; then - print_error "Image $IMAGE not found. Please build it first:" - echo " cd docker && ./build.sh $VARIANT" - exit 1 -fi - -# Check hardware requirements for GPU variants -if [ "$VARIANT" = "gpu-nvidia" ]; then - if ! (command -v nvidia-docker &> /dev/null || docker info | grep -q nvidia); then - print_error "NVIDIA Docker runtime not found. GPU variant requires NVIDIA Docker." - print_status "Install NVIDIA Docker: https://github.com/NVIDIA/nvidia-docker" - exit 1 - fi - - if ! nvidia-smi &> /dev/null; then - print_error "nvidia-smi not found. Please install NVIDIA drivers." - exit 1 - fi - - print_gpu "NVIDIA Docker runtime detected" - -elif [ "$VARIANT" = "gpu-amd" ]; then - if [ ! -e "/dev/kfd" ] || [ ! -e "/dev/dri" ]; then - print_error "AMD GPU devices not found (/dev/kfd or /dev/dri missing)." - print_status "Ensure ROCm drivers are installed and GPU devices are accessible." - exit 1 - fi - - print_gpu "AMD ROCm devices detected" -fi - -# Header -echo "🐳 Quantum Computing 101 Runner v2.0" -echo "=====================================" -echo "Variant: $VARIANT" -echo "Image: $IMAGE" -echo "" - -# Main execution logic -if [ "$JUPYTER" = true ]; then - run_jupyter "$IMAGE" -elif [ -n "$EXAMPLE" ]; then - if [ "$EXAMPLE" = "list" ]; then - list_examples "$IMAGE" - elif [ "$EXAMPLE" = "info" ]; then - show_hardware_info "$IMAGE" - else - # Pass remaining arguments to the example - run_example "$IMAGE" "$EXAMPLE" "$@" - fi -elif [ -n "$MODULE" ]; then - print_status "Examples in $MODULE:" - docker run --rm \ - -v "$(pwd)/examples:/home/qc101/quantum-computing-101/examples:ro" \ - "$IMAGE" \ - find "./examples/$MODULE" -name '*.py' -type f 2>/dev/null | sort || \ - print_error "Module $MODULE not found" -elif [ "$INTERACTIVE" = true ]; then - run_interactive "$IMAGE" -else - print_error "No action specified" - show_usage - exit 1 -fi \ No newline at end of file diff --git a/examples/requirements-core.txt b/examples/requirements-core.txt index 54d6c84..64d0a3a 100644 --- a/examples/requirements-core.txt +++ b/examples/requirements-core.txt @@ -1,5 +1,8 @@ -# Core Requirements for Quantum Computing 101 -# Minimal dependencies needed to run basic examples (Modules 1-4) +# Core Requirements for Quantum Computing 101 (Minimal Install) +# Purpose: Minimal dependencies needed to run basic examples (Modules 1-4 only) +# Used by: Users who want lightweight installation without advanced features +# Note: Does not include ML frameworks, cloud SDKs, or Jupyter +# For full features, use requirements.txt instead # Core quantum computing framework qiskit>=1.0.0 diff --git a/examples/requirements-dev.txt b/examples/requirements-dev.txt index 9dbef5b..298eb33 100644 --- a/examples/requirements-dev.txt +++ b/examples/requirements-dev.txt @@ -1,4 +1,9 @@ -# Development requirements (extends requirements.txt) +# Development Requirements for Quantum Computing 101 Contributors +# Purpose: Testing, linting, documentation, and development tools +# Used by: Contributors, CI/CD testing pipelines, documentation builds +# Extends: requirements.txt (includes all runtime dependencies) +# Note: Not needed for running examples, only for development work + -r requirements.txt # Testing framework diff --git a/examples/requirements.txt b/examples/requirements.txt index 88cc8bf..dac3d3b 100644 --- a/examples/requirements.txt +++ b/examples/requirements.txt @@ -1,4 +1,8 @@ -# Requirements for Quantum Computing 101 Examples +# Local Development Requirements for Quantum Computing 101 Examples +# Purpose: Complete package set for running ALL examples WITHOUT Docker +# Used by: Local pip installation, CI/CD pipelines, manual setup +# Sync: Keep core packages aligned with docker/requirements/base.txt +# Note: Some packages (Jupyter, cloud SDKs) intentionally overlap with Docker for flexibility # Core quantum computing frameworks (required) qiskit>=1.0.0 @@ -38,9 +42,10 @@ boto3>=1.34.0 # azure-quantum>=0.28.0 # Optional - not actively used in current examples # Jupyter support (optional - for notebook development) -jupyter>=1.0.0 -ipywidgets>=8.1.0 -jupyterlab>=4.1.0 +# Note: Already included in Docker images. Uncomment for local Jupyter development: +# jupyter>=1.0.0 +# ipywidgets>=8.1.0 +# jupyterlab>=4.1.0 # Development and testing utilities (moved to requirements-dev.txt) # pytest>=7.4.0 diff --git a/setup.py b/setup.py index 35385dc..a841d3d 100644 --- a/setup.py +++ b/setup.py @@ -17,7 +17,13 @@ def read_readme(): # Read requirements from file def read_requirements(filename): with open(os.path.join("examples", filename), "r", encoding="utf-8") as fh: - return [line.strip() for line in fh if line.strip() and not line.startswith("#")] + return [ + line.strip() + for line in fh + if line.strip() + and not line.startswith("#") + and not line.startswith("-r") + ] setup( name="quantum-computing-101",