From 074d551f9d930eeb84cc25748b3fac9eacb57ce5 Mon Sep 17 00:00:00 2001 From: Stephen Shao Date: Tue, 30 Sep 2025 21:10:18 -0400 Subject: [PATCH 1/6] Refactor the docker build --- docker/Dockerfile | 161 +++++++++++++++ docker/Dockerfile.gpu-nvidia | 8 +- docker/README-NEW.md | 284 ++++++++++++++++++++++++++ docker/build-unified.sh | 225 +++++++++++++++++++++ docker/docker-compose.yml | 371 +++++++++++++++++++++++----------- docker/docker-compose.yml.old | 238 ++++++++++++++++++++++ docker/entrypoint.sh | 44 ++++ 7 files changed, 1207 insertions(+), 124 deletions(-) create mode 100644 docker/Dockerfile create mode 100644 docker/README-NEW.md create mode 100755 docker/build-unified.sh create mode 100644 docker/docker-compose.yml.old create mode 100644 docker/entrypoint.sh 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.gpu-nvidia b/docker/Dockerfile.gpu-nvidia index 03f0b05..b615267 100644 --- a/docker/Dockerfile.gpu-nvidia +++ b/docker/Dockerfile.gpu-nvidia @@ -2,7 +2,7 @@ # 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 +FROM nvidia/cuda:12.9.1-cudnn-devel-ubuntu24.04 AS cuda-base # Set labels for metadata LABEL maintainer="Quantum Computing 101" @@ -51,7 +51,7 @@ 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 +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 @@ -68,7 +68,7 @@ RUN sed '/^qiskit-aer/d' /tmp/requirements/base.txt > /tmp/requirements/base-no- 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 +FROM python-deps AS app-setup # Create non-root user for security RUN useradd --create-home --shell /bin/bash --uid 1000 qc101 @@ -87,7 +87,7 @@ 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 +FROM app-setup AS runtime # Switch to non-root user USER qc101 diff --git a/docker/README-NEW.md b/docker/README-NEW.md new file mode 100644 index 0000000..299ab8f --- /dev/null +++ b/docker/README-NEW.md @@ -0,0 +1,284 @@ +# Quantum Computing 101 - Docker Setup Guide + +## Overview + +This Docker setup provides a unified, flexible solution for running Quantum Computing 101 across different hardware configurations: + +- **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 + +### 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 +``` + +### 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 CPU variant +./build-unified.sh cpu + +# Build NVIDIA GPU variant +./build-unified.sh nvidia + +# Build AMD GPU variant +./build-unified.sh amd + +# Build all variants +./build-unified.sh all + +# Build without cache +./build-unified.sh nvidia --no-cache +``` + +### Using Docker Compose + +```bash +# 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 + +# View logs +docker-compose logs -f qc101-nvidia + +# Stop containers +docker-compose down +``` + +### Manual Docker Run + +```bash +# 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 +``` + +## Directory Structure + +``` +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 + +Start Jupyter Lab inside container: +```bash +jupyter lab --ip=0.0.0.0 --port=8888 --no-browser +``` + +## Advanced Configuration + +### Custom PyTorch/CUDA Versions + +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 . +``` + +### Multi-GPU Configuration + +```yaml +# docker-compose.yml +deploy: + resources: + reservations: + devices: + - driver: nvidia + device_ids: ['0', '1'] # Specific GPUs + capabilities: [gpu] +``` + +## Troubleshooting + +### NVIDIA GPU not detected + +```bash +# Check NVIDIA driver +nvidia-smi + +# 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 +``` + +### AMD GPU issues + +```bash +# Check ROCm installation +rocm-smi + +# Verify device permissions +ls -l /dev/kfd /dev/dri + +# 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 + +# Check disk space +df -h +``` + +## Migration Guide + +### From Old Structure to New + +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 + +- ✅ 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 + +## Performance Tips + +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 + +## Contributing + +When adding new dependencies: + +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 + +## License + +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..e183bad --- /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 | wc -l) + print_success "NVIDIA GPU detected (${gpu_count} GPU(s))" + gpu_type="nvidia" + # Check for AMD GPU + elif [ -d "/opt/rocm" ] || command -v rocm-smi &> /dev/null; then + print_success "AMD ROCm GPU detected" + gpu_type="amd" + else + print_info "No GPU detected, CPU-only mode available" + 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/docker-compose.yml b/docker/docker-compose.yml index 5690e0b..512678c 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -1,134 +1,265 @@ -version: '3.8' +version: '3.8'version: '3.8' + + + +# Quantum Computing 101 - Docker Compose Configurationservices: + +# Supports CPU, NVIDIA GPU, and AMD GPU variants # CPU-only variant for lightweight usage and learning -services: - # CPU-only variant for lightweight usage and learning quantum101-cpu: - build: - context: .. - dockerfile: docker/Dockerfile.cpu - image: quantum101:cpu - container_name: qc101-cpu - volumes: - - ../examples:/home/qc101/quantum-computing-101/examples - - ../outputs:/home/qc101/quantum-computing-101/outputs - - ../modules:/home/qc101/quantum-computing-101/modules:ro - working_dir: /home/qc101/quantum-computing-101/examples - environment: - - PYTHONPATH=/home/qc101/quantum-computing-101 - - MPLBACKEND=Agg - - QC101_VARIANT=cpu - networks: - - quantum-net - restart: unless-stopped - # CPU resource limits for fair sharing - deploy: - resources: - limits: - cpus: '4.0' - memory: 4G - reservations: - memory: 1G - # NVIDIA CUDA GPU variant for maximum acceleration - quantum101-gpu-nvidia: - build: - context: .. - dockerfile: docker/Dockerfile.gpu-nvidia - image: quantum101:gpu-nvidia - container_name: qc101-gpu-nvidia - volumes: - - ../examples:/home/qc101/quantum-computing-101/examples - - ../outputs:/home/qc101/quantum-computing-101/outputs - - ../modules:/home/qc101/quantum-computing-101/modules:ro - working_dir: /home/qc101/quantum-computing-101/examples - environment: - - PYTHONPATH=/home/qc101/quantum-computing-101 - - MPLBACKEND=Agg - - QC101_VARIANT=gpu-nvidia - - NVIDIA_VISIBLE_DEVICES=all - - CUDA_VISIBLE_DEVICES=all - networks: - - quantum-net - restart: unless-stopped - # NVIDIA GPU resource configuration - deploy: - resources: - reservations: - devices: - - driver: nvidia - count: all - capabilities: [gpu] - limits: - memory: 8G - runtime: nvidia +services: build: + + # ============================================================================= context: .. + + # CPU-Only Service dockerfile: docker/Dockerfile.cpu + + # ============================================================================= image: quantum101:cpu + + qc101-cpu: container_name: qc101-cpu + + build: volumes: + + context: .. - ../examples:/home/qc101/quantum-computing-101/examples + + dockerfile: docker/Dockerfile - ../outputs:/home/qc101/quantum-computing-101/outputs + + args: - ../modules:/home/qc101/quantum-computing-101/modules:ro + + VARIANT: cpu working_dir: /home/qc101/quantum-computing-101/examples + + target: runtime environment: + + image: quantum-computing-101:cpu - PYTHONPATH=/home/qc101/quantum-computing-101 + + container_name: qc101-cpu - MPLBACKEND=Agg + + hostname: qc101-cpu - QC101_VARIANT=cpu + + environment: networks: + + - QC101_VARIANT=cpu - quantum-net + + volumes: restart: unless-stopped + + - ../examples:/home/qc101/quantum-computing-101/examples # CPU resource limits for fair sharing + + - ../outputs:/home/qc101/quantum-computing-101/outputs deploy: + + - qc101-cache:/home/qc101/.cache resources: + + ports: limits: + + - "8888:8888" # Jupyter Lab cpus: '4.0' + + - "6006:6006" # TensorBoard memory: 4G + + networks: reservations: + + - qc101-network memory: 1G - # AMD ROCm GPU variant for AMD GPU acceleration - quantum101-gpu-amd: - build: - context: .. - dockerfile: docker/Dockerfile.gpu-amd - image: quantum101:gpu-amd - container_name: qc101-gpu-amd - volumes: - - ../examples:/home/qc101/quantum-computing-101/examples - - ../outputs:/home/qc101/quantum-computing-101/outputs - - ../modules:/home/qc101/quantum-computing-101/modules:ro - working_dir: /home/qc101/quantum-computing-101/examples - environment: - - PYTHONPATH=/home/qc101/quantum-computing-101 - - MPLBACKEND=Agg - - QC101_VARIANT=gpu-amd - - ROCm_HOME=/opt/rocm - - HIP_VISIBLE_DEVICES=all - networks: - - quantum-net restart: unless-stopped - devices: - - /dev/kfd:/dev/kfd - - /dev/dri:/dev/dri - group_add: - - video - deploy: - resources: - limits: - memory: 8G - # Jupyter development environment (CPU) - jupyter-cpu: + stdin_open: true # NVIDIA CUDA GPU variant for maximum acceleration + + tty: true quantum101-gpu-nvidia: + build: - context: .. - dockerfile: docker/Dockerfile.cpu - image: quantum101:cpu - container_name: qc101-jupyter-cpu - ports: - - "8888:8888" - volumes: - - ../examples:/home/qc101/quantum-computing-101/examples - - ../outputs:/home/qc101/quantum-computing-101/outputs + + # ============================================================================= context: .. + + # NVIDIA GPU Service dockerfile: docker/Dockerfile.gpu-nvidia + + # ============================================================================= image: quantum101:gpu-nvidia + + qc101-nvidia: container_name: qc101-gpu-nvidia + + build: volumes: + + context: .. - ../examples:/home/qc101/quantum-computing-101/examples + + dockerfile: docker/Dockerfile - ../outputs:/home/qc101/quantum-computing-101/outputs + + args: - ../modules:/home/qc101/quantum-computing-101/modules:ro + + VARIANT: nvidia working_dir: /home/qc101/quantum-computing-101/examples + + PYTORCH_VERSION: "2.8.0" environment: + + CUDA_VERSION: "12.9" - PYTHONPATH=/home/qc101/quantum-computing-101 + + CUDNN_VERSION: "9" - MPLBACKEND=Agg + + target: runtime - QC101_VARIANT=gpu-nvidia + + image: quantum-computing-101:nvidia-gpu - NVIDIA_VISIBLE_DEVICES=all + + container_name: qc101-nvidia - CUDA_VISIBLE_DEVICES=all + + hostname: qc101-nvidia networks: + + environment: - quantum-net + + - QC101_VARIANT=gpu-nvidia restart: unless-stopped + + - NVIDIA_VISIBLE_DEVICES=all # NVIDIA GPU resource configuration + + - NVIDIA_DRIVER_CAPABILITIES=compute,utility deploy: + + volumes: resources: + + - ../examples:/home/qc101/quantum-computing-101/examples reservations: + + - ../outputs:/home/qc101/quantum-computing-101/outputs devices: + + - qc101-cache-nvidia:/home/qc101/.cache - driver: nvidia + + - /tmp/.X11-unix:/tmp/.X11-unix:rw count: all + + ports: capabilities: [gpu] + + - "8889:8888" # Jupyter Lab (different port to avoid conflict) limits: + + - "6007:6006" # TensorBoard memory: 8G + + networks: runtime: nvidia + + - qc101-network + + deploy: # AMD ROCm GPU variant for AMD GPU acceleration + + resources: quantum101-gpu-amd: + + reservations: build: + + devices: context: .. + + - driver: nvidia dockerfile: docker/Dockerfile.gpu-amd + + count: all image: quantum101:gpu-amd + + capabilities: [gpu] container_name: qc101-gpu-amd + + restart: unless-stopped volumes: + + stdin_open: true - ../examples:/home/qc101/quantum-computing-101/examples + + tty: true - ../outputs:/home/qc101/quantum-computing-101/outputs + - ../modules:/home/qc101/quantum-computing-101/modules:ro - - jupyter-cpu-workspace:/home/qc101/workspace - working_dir: /home/qc101/quantum-computing-101/examples - environment: - - PYTHONPATH=/home/qc101/quantum-computing-101 + + # ============================================================================= working_dir: /home/qc101/quantum-computing-101/examples + + # AMD GPU Service (ROCm) environment: + + # ============================================================================= - PYTHONPATH=/home/qc101/quantum-computing-101 + + qc101-amd: - MPLBACKEND=Agg + + build: - QC101_VARIANT=gpu-amd + + context: .. - ROCm_HOME=/opt/rocm + + dockerfile: docker/Dockerfile - HIP_VISIBLE_DEVICES=all + + args: networks: + + VARIANT: amd - quantum-net + + target: runtime restart: unless-stopped + + image: quantum-computing-101:amd-gpu devices: + + container_name: qc101-amd - /dev/kfd:/dev/kfd + + hostname: qc101-amd - /dev/dri:/dev/dri + + environment: group_add: + + - QC101_VARIANT=gpu-amd - video + + - ROCM_VISIBLE_DEVICES=all deploy: + + - HIP_VISIBLE_DEVICES=all resources: + + volumes: limits: + + - ../examples:/home/qc101/quantum-computing-101/examples memory: 8G + + - ../outputs:/home/ysha/aicomputing101/quantum-computing-101/outputs + + - qc101-cache-amd:/home/qc101/.cache # Jupyter development environment (CPU) + + - /dev/kfd:/dev/kfd jupyter-cpu: + + - /dev/dri:/dev/dri build: + + ports: context: .. + + - "8890:8888" # Jupyter Lab (different port) dockerfile: docker/Dockerfile.cpu + + - "6008:6006" # TensorBoard image: quantum101:cpu + + networks: container_name: qc101-jupyter-cpu + + - qc101-network ports: + + devices: - "8888:8888" + + - /dev/kfd volumes: + + - /dev/dri - ../examples:/home/qc101/quantum-computing-101/examples + + group_add: - ../outputs:/home/qc101/quantum-computing-101/outputs + + - video - ../modules:/home/qc101/quantum-computing-101/modules:ro + + - render - jupyter-cpu-workspace:/home/qc101/workspace + + restart: unless-stopped working_dir: /home/qc101/quantum-computing-101/examples + + stdin_open: true environment: + + tty: true - PYTHONPATH=/home/qc101/quantum-computing-101 + - JUPYTER_ENABLE_LAB=yes - command: > - bash -c "pip install --quiet jupyter jupyterlab ipywidgets && - echo 'Starting Jupyter Lab on http://localhost:8888' && - jupyter lab --ip=0.0.0.0 --port=8888 --no-browser - --allow-root --NotebookApp.token='' --NotebookApp.password=''" - networks: - - quantum-net + +# ============================================================================= command: > + +# Networks bash -c "pip install --quiet jupyter jupyterlab ipywidgets && + +# ============================================================================= echo 'Starting Jupyter Lab on http://localhost:8888' && + +networks: jupyter lab --ip=0.0.0.0 --port=8888 --no-browser + + qc101-network: --allow-root --NotebookApp.token='' --NotebookApp.password=''" + + driver: bridge networks: + + name: qc101-network - quantum-net + restart: unless-stopped - # Jupyter development environment (NVIDIA GPU) - jupyter-gpu-nvidia: - build: - context: .. - dockerfile: docker/Dockerfile.gpu-nvidia - image: quantum101:gpu-nvidia - container_name: qc101-jupyter-gpu-nvidia - ports: - - "8889:8888" +# ============================================================================= + +# Volumes (for persistent cache) # Jupyter development environment (NVIDIA GPU) + +# ============================================================================= jupyter-gpu-nvidia: + +volumes: build: + + qc101-cache: context: .. + + name: qc101-cache-cpu dockerfile: docker/Dockerfile.gpu-nvidia + + qc101-cache-nvidia: image: quantum101:gpu-nvidia + + name: qc101-cache-nvidia container_name: qc101-jupyter-gpu-nvidia + + qc101-cache-amd: ports: + + name: qc101-cache-amd - "8889:8888" + volumes: - ../examples:/home/qc101/quantum-computing-101/examples - ../outputs:/home/qc101/quantum-computing-101/outputs diff --git a/docker/docker-compose.yml.old b/docker/docker-compose.yml.old new file mode 100644 index 0000000..5690e0b --- /dev/null +++ b/docker/docker-compose.yml.old @@ -0,0 +1,238 @@ +version: '3.8' + +services: + # CPU-only variant for lightweight usage and learning + quantum101-cpu: + build: + context: .. + dockerfile: docker/Dockerfile.cpu + image: quantum101:cpu + container_name: qc101-cpu + volumes: + - ../examples:/home/qc101/quantum-computing-101/examples + - ../outputs:/home/qc101/quantum-computing-101/outputs + - ../modules:/home/qc101/quantum-computing-101/modules:ro + working_dir: /home/qc101/quantum-computing-101/examples + environment: + - PYTHONPATH=/home/qc101/quantum-computing-101 + - MPLBACKEND=Agg + - QC101_VARIANT=cpu + networks: + - quantum-net + restart: unless-stopped + # CPU resource limits for fair sharing + deploy: + resources: + limits: + cpus: '4.0' + memory: 4G + reservations: + memory: 1G + + # NVIDIA CUDA GPU variant for maximum acceleration + quantum101-gpu-nvidia: + build: + context: .. + dockerfile: docker/Dockerfile.gpu-nvidia + image: quantum101:gpu-nvidia + container_name: qc101-gpu-nvidia + volumes: + - ../examples:/home/qc101/quantum-computing-101/examples + - ../outputs:/home/qc101/quantum-computing-101/outputs + - ../modules:/home/qc101/quantum-computing-101/modules:ro + working_dir: /home/qc101/quantum-computing-101/examples + environment: + - PYTHONPATH=/home/qc101/quantum-computing-101 + - MPLBACKEND=Agg + - QC101_VARIANT=gpu-nvidia + - NVIDIA_VISIBLE_DEVICES=all + - CUDA_VISIBLE_DEVICES=all + networks: + - quantum-net + restart: unless-stopped + # NVIDIA GPU resource configuration + deploy: + resources: + reservations: + devices: + - driver: nvidia + count: all + capabilities: [gpu] + limits: + memory: 8G + runtime: nvidia + + # AMD ROCm GPU variant for AMD GPU acceleration + quantum101-gpu-amd: + build: + context: .. + dockerfile: docker/Dockerfile.gpu-amd + image: quantum101:gpu-amd + container_name: qc101-gpu-amd + volumes: + - ../examples:/home/qc101/quantum-computing-101/examples + - ../outputs:/home/qc101/quantum-computing-101/outputs + - ../modules:/home/qc101/quantum-computing-101/modules:ro + working_dir: /home/qc101/quantum-computing-101/examples + environment: + - PYTHONPATH=/home/qc101/quantum-computing-101 + - MPLBACKEND=Agg + - QC101_VARIANT=gpu-amd + - ROCm_HOME=/opt/rocm + - HIP_VISIBLE_DEVICES=all + networks: + - quantum-net + restart: unless-stopped + devices: + - /dev/kfd:/dev/kfd + - /dev/dri:/dev/dri + group_add: + - video + deploy: + resources: + limits: + memory: 8G + + # Jupyter development environment (CPU) + jupyter-cpu: + build: + context: .. + dockerfile: docker/Dockerfile.cpu + image: quantum101:cpu + container_name: qc101-jupyter-cpu + ports: + - "8888:8888" + volumes: + - ../examples:/home/qc101/quantum-computing-101/examples + - ../outputs:/home/qc101/quantum-computing-101/outputs + - ../modules:/home/qc101/quantum-computing-101/modules:ro + - jupyter-cpu-workspace:/home/qc101/workspace + working_dir: /home/qc101/quantum-computing-101/examples + environment: + - PYTHONPATH=/home/qc101/quantum-computing-101 + - JUPYTER_ENABLE_LAB=yes + command: > + bash -c "pip install --quiet jupyter jupyterlab ipywidgets && + echo 'Starting Jupyter Lab on http://localhost:8888' && + jupyter lab --ip=0.0.0.0 --port=8888 --no-browser + --allow-root --NotebookApp.token='' --NotebookApp.password=''" + networks: + - quantum-net + restart: unless-stopped + + # Jupyter development environment (NVIDIA GPU) + jupyter-gpu-nvidia: + build: + context: .. + dockerfile: docker/Dockerfile.gpu-nvidia + image: quantum101:gpu-nvidia + container_name: qc101-jupyter-gpu-nvidia + ports: + - "8889:8888" + volumes: + - ../examples:/home/qc101/quantum-computing-101/examples + - ../outputs:/home/qc101/quantum-computing-101/outputs + - ../modules:/home/qc101/quantum-computing-101/modules:ro + - jupyter-gpu-nvidia-workspace:/home/qc101/workspace + working_dir: /home/qc101/quantum-computing-101/examples + environment: + - PYTHONPATH=/home/qc101/quantum-computing-101 + - JUPYTER_ENABLE_LAB=yes + - NVIDIA_VISIBLE_DEVICES=all + command: > + bash -c "pip install --quiet jupyter jupyterlab ipywidgets && + echo 'Starting GPU-accelerated Jupyter Lab on http://localhost:8889' && + echo 'CUDA Available:' $(python -c 'import torch; print(torch.cuda.is_available())') && + jupyter lab --ip=0.0.0.0 --port=8888 --no-browser + --allow-root --NotebookApp.token='' --NotebookApp.password=''" + networks: + - quantum-net + runtime: nvidia + deploy: + resources: + reservations: + devices: + - driver: nvidia + count: all + capabilities: [gpu] + restart: unless-stopped + + # Jupyter development environment (AMD ROCm GPU) + jupyter-gpu-amd: + build: + context: .. + dockerfile: docker/Dockerfile.gpu-amd + image: quantum101:gpu-amd + container_name: qc101-jupyter-gpu-amd + ports: + - "8890:8888" + volumes: + - ../examples:/home/qc101/quantum-computing-101/examples + - ../outputs:/home/qc101/quantum-computing-101/outputs + - ../modules:/home/qc101/quantum-computing-101/modules:ro + - jupyter-gpu-amd-workspace:/home/qc101/workspace + working_dir: /home/qc101/quantum-computing-101/examples + environment: + - PYTHONPATH=/home/qc101/quantum-computing-101 + - JUPYTER_ENABLE_LAB=yes + - ROCm_HOME=/opt/rocm + - HIP_VISIBLE_DEVICES=all + command: > + bash -c "pip install --quiet jupyter jupyterlab ipywidgets && + echo 'Starting ROCm-accelerated Jupyter Lab on http://localhost:8890' && + echo 'PyTorch ROCm Available:' $(python -c 'import torch; print(torch.cuda.is_available())') && + jupyter lab --ip=0.0.0.0 --port=8888 --no-browser + --allow-root --NotebookApp.token='' --NotebookApp.password=''" + networks: + - quantum-net + devices: + - /dev/kfd:/dev/kfd + - /dev/dri:/dev/dri + group_add: + - video + restart: unless-stopped + + # Development container with all tools (based on NVIDIA GPU) + quantum101-dev: + build: + context: .. + dockerfile: docker/Dockerfile.gpu-nvidia + image: quantum101:gpu-nvidia + container_name: qc101-dev + volumes: + - ..:/home/qc101/quantum-computing-101 + working_dir: /home/qc101/quantum-computing-101 + environment: + - PYTHONPATH=/home/qc101/quantum-computing-101 + networks: + - quantum-net + runtime: nvidia + deploy: + resources: + reservations: + devices: + - driver: nvidia + count: all + capabilities: [gpu] + command: /bin/bash + stdin_open: true + tty: true + +networks: + quantum-net: + driver: bridge + name: quantum-computing-network + +volumes: + quantum-outputs: + name: qc101-outputs + driver: local + jupyter-cpu-workspace: + name: qc101-jupyter-cpu-workspace + driver: local + jupyter-gpu-nvidia-workspace: + name: qc101-jupyter-gpu-nvidia-workspace + driver: local + jupyter-gpu-amd-workspace: + name: qc101-jupyter-gpu-amd-workspace + driver: local \ No newline at end of file diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh new file mode 100644 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 "$@" From a4177cf21093a2d98f5893d7f4e39e465b65f660 Mon Sep 17 00:00:00 2001 From: Stephen Shao Date: Tue, 30 Sep 2025 21:19:36 -0400 Subject: [PATCH 2/6] Updated script of build --- docker/build-unified.sh | 8 ++++---- docker/entrypoint.sh | 0 2 files changed, 4 insertions(+), 4 deletions(-) mode change 100644 => 100755 docker/entrypoint.sh diff --git a/docker/build-unified.sh b/docker/build-unified.sh index e183bad..be2e981 100755 --- a/docker/build-unified.sh +++ b/docker/build-unified.sh @@ -68,15 +68,15 @@ detect_gpu() { # Check for NVIDIA GPU if command -v nvidia-smi &> /dev/null && nvidia-smi &> /dev/null; then - local gpu_count=$(nvidia-smi --list-gpus | wc -l) - print_success "NVIDIA GPU detected (${gpu_count} GPU(s))" + 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" + print_success "AMD ROCm GPU detected" >&2 gpu_type="amd" else - print_info "No GPU detected, CPU-only mode available" + print_info "No GPU detected, CPU-only mode available" >&2 gpu_type="cpu" fi diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh old mode 100644 new mode 100755 From 7b7dc23d6a307bad25d5f00c26a39fbdc4ea32f5 Mon Sep 17 00:00:00 2001 From: Stephen Shao Date: Tue, 30 Sep 2025 21:35:23 -0400 Subject: [PATCH 3/6] cleanup --- docker/Dockerfile.base | 69 ---- docker/Dockerfile.cpu | 71 ---- docker/Dockerfile.gpu-amd | 164 --------- docker/Dockerfile.gpu-nvidia | 131 -------- docker/README-NEW.md | 284 ---------------- docker/README.md | 515 ++++++++++++----------------- docker/build.sh | 336 ------------------- docker/docker-compose.yml.old | 238 ------------- docker/requirements/cpu.txt | 24 +- docker/requirements/gpu-amd.txt | 31 +- docker/requirements/gpu-nvidia.txt | 32 +- docker/run.sh | 442 ------------------------- 12 files changed, 237 insertions(+), 2100 deletions(-) delete mode 100644 docker/Dockerfile.base delete mode 100644 docker/Dockerfile.cpu delete mode 100644 docker/Dockerfile.gpu-amd delete mode 100644 docker/Dockerfile.gpu-nvidia delete mode 100644 docker/README-NEW.md delete mode 100755 docker/build.sh delete mode 100644 docker/docker-compose.yml.old delete mode 100755 docker/run.sh 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 b615267..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-NEW.md b/docker/README-NEW.md deleted file mode 100644 index 299ab8f..0000000 --- a/docker/README-NEW.md +++ /dev/null @@ -1,284 +0,0 @@ -# Quantum Computing 101 - Docker Setup Guide - -## Overview - -This Docker setup provides a unified, flexible solution for running Quantum Computing 101 across different hardware configurations: - -- **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 - -### 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 -``` - -### 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 CPU variant -./build-unified.sh cpu - -# Build NVIDIA GPU variant -./build-unified.sh nvidia - -# Build AMD GPU variant -./build-unified.sh amd - -# Build all variants -./build-unified.sh all - -# Build without cache -./build-unified.sh nvidia --no-cache -``` - -### Using Docker Compose - -```bash -# 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 - -# View logs -docker-compose logs -f qc101-nvidia - -# Stop containers -docker-compose down -``` - -### Manual Docker Run - -```bash -# 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 -``` - -## Directory Structure - -``` -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 - -Start Jupyter Lab inside container: -```bash -jupyter lab --ip=0.0.0.0 --port=8888 --no-browser -``` - -## Advanced Configuration - -### Custom PyTorch/CUDA Versions - -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 . -``` - -### Multi-GPU Configuration - -```yaml -# docker-compose.yml -deploy: - resources: - reservations: - devices: - - driver: nvidia - device_ids: ['0', '1'] # Specific GPUs - capabilities: [gpu] -``` - -## Troubleshooting - -### NVIDIA GPU not detected - -```bash -# Check NVIDIA driver -nvidia-smi - -# 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 -``` - -### AMD GPU issues - -```bash -# Check ROCm installation -rocm-smi - -# Verify device permissions -ls -l /dev/kfd /dev/dri - -# 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 - -# Check disk space -df -h -``` - -## Migration Guide - -### From Old Structure to New - -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 - -- ✅ 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 - -## Performance Tips - -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 - -## Contributing - -When adding new dependencies: - -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 - -## License - -This Docker setup is part of the Quantum Computing 101 project. -See main project LICENSE for details. diff --git a/docker/README.md b/docker/README.md index 2f3bc13..299ab8f 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,385 +1,284 @@ -# 🐳 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. +## Overview -## 🚀 Quick Start +This Docker setup provides a unified, flexible solution for running Quantum Computing 101 across different hardware configurations: -### 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 +- **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 -### 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 +## Architecture + +### Unified Dockerfile Approach + +The new `Dockerfile` uses multi-stage builds with build arguments to create different variants from a single source: -# Interactive session -./run.sh -v cpu -i +``` +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 -```bash -# Build NVIDIA GPU container -cd docker -./build.sh gpu-nvidia +### Benefits -# Run GPU-accelerated ML example -./run.sh -v gpu-nvidia -e module6_machine_learning/01_quantum_neural_network.py +✅ **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 -# Interactive GPU session -./run.sh -v gpu-nvidia -i -``` +## Quick Start + +### Building Images -### AMD ROCm GPU Acceleration ```bash -# Build AMD ROCm container -cd docker -./build.sh gpu-amd +# Build CPU variant +./build-unified.sh cpu + +# Build NVIDIA GPU variant +./build-unified.sh nvidia + +# Build AMD GPU variant +./build-unified.sh amd -# Run with ROCm acceleration -./run.sh -v gpu-amd -e module6_machine_learning/01_quantum_neural_network.py +# Build all variants +./build-unified.sh all -# Interactive ROCm session -./run.sh -v gpu-amd -i +# Build without cache +./build-unified.sh nvidia --no-cache ``` -## 📦 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) +### Using Docker Compose + ```bash -# Start all services -docker-compose up -d +# Start CPU container +docker-compose up -d qc101-cpu -# Start specific variant -docker-compose up quantum101-gpu-nvidia +# Start NVIDIA GPU container +docker-compose up -d qc101-nvidia -# 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 +# Start AMD GPU container +docker-compose up -d qc101-amd -# Development container -docker-compose up quantum101-dev -``` +# View logs +docker-compose logs -f qc101-nvidia -### Build Script Options -```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 +# Stop containers +docker-compose down ``` -### Run Script Options +### Manual Docker Run + ```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 +# 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 ``` -## 🛠️ Requirements Architecture - -The new requirements system uses a modular approach for optimal Docker layer caching: +## Directory Structure ``` -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 +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 ``` -**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 - -## 🎓 Educational Benefits - -### 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 +## Requirements Files Structure -### 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 +### base.txt +Common dependencies for all variants: +- Qiskit core frameworks +- Scientific computing (NumPy, SciPy, Matplotlib) +- Machine learning (scikit-learn) +- Jupyter Lab -### 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 +### cpu.txt +CPU-optimized packages: +- PyTorch CPU version +- TensorFlow CPU version -## 🚨 Hardware Requirements & Setup +### gpu-nvidia.txt +NVIDIA GPU-optimized packages: +- CuPy (CUDA arrays) +- qiskit-aer-gpu (GPU-accelerated quantum simulation) +- PyTorch CUDA support +- CUDA tools and monitoring -### 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 +### gpu-amd.txt +AMD GPU-optimized packages: +- ROCm-specific tools +- qiskit-aer (with ROCm support) -# Test NVIDIA Docker -docker run --rm --gpus all nvidia/cuda:12.2-base-ubuntu22.04 nvidia-smi -``` +## Environment Variables -### AMD ROCm Setup -```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 +### Common +- `QC101_VARIANT`: cpu|gpu-nvidia|gpu-amd +- `PYTHONUNBUFFERED=1`: Real-time Python output +- `MPLBACKEND=Agg`: Non-interactive matplotlib backend -# Add user to render group -sudo usermod -a -G render,video $USER -newgrp render +### NVIDIA-Specific +- `NVIDIA_VISIBLE_DEVICES=all`: Expose all GPUs +- `NVIDIA_DRIVER_CAPABILITIES=compute,utility`: GPU capabilities +- `CUDA_VISIBLE_DEVICES=all`: CUDA device visibility -# Test ROCm access -ls -la /dev/kfd /dev/dri -``` +### AMD-Specific +- `ROCM_VISIBLE_DEVICES=all`: Expose all ROCm devices +- `HIP_VISIBLE_DEVICES=all`: HIP device visibility -### 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 | +## Jupyter Lab Access -## 🛡️ Security Features +Each variant runs Jupyter Lab on different ports to avoid conflicts: -- **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 +- CPU: http://localhost:8888 +- NVIDIA: http://localhost:8889 +- AMD: http://localhost:8890 -## 🐛 Troubleshooting Guide - -### Common Build Issues +Start Jupyter Lab inside container: ```bash -# Docker out of space -docker system prune -a -docker builder prune +jupyter lab --ip=0.0.0.0 --port=8888 --no-browser +``` -# Permission denied -sudo chown -R $USER:$USER outputs/ -sudo usermod -a -G docker $USER +## Advanced Configuration -# NVIDIA Docker not found -sudo systemctl restart docker -docker run --rm --gpus all nvidia/cuda:12.2-base-ubuntu22.04 nvidia-smi -``` +### Custom PyTorch/CUDA Versions -### 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 +Edit `build-unified.sh` or pass build args: -# AMD: Check device access -ls -la /dev/kfd /dev/dri -groups | grep -E 'render|video' +```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 . ``` -### Performance Issues -```bash -# Monitor container resources -docker stats +### Multi-GPU Configuration + +```yaml +# docker-compose.yml +deploy: + resources: + reservations: + devices: + - driver: nvidia + device_ids: ['0', '1'] # Specific GPUs + capabilities: [gpu] +``` -# Check GPU usage -nvidia-smi # NVIDIA -rocm-smi # AMD +## Troubleshooting -# Container hardware info -./run.sh -v gpu-nvidia --info -``` +### NVIDIA GPU not detected -### Port Conflicts ```bash -# Find running services -netstat -tlnp | grep :888 -lsof -i :8888 +# Check NVIDIA driver +nvidia-smi + +# Check Docker NVIDIA runtime +docker run --rm --gpus all nvidia/cuda:12.9.1-base nvidia-smi -# Use alternative ports -./run.sh -j # Will auto-detect and use alternative port +# 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 - -# Terminal 4: Interactive debugging -./run.sh -v cpu -i +# Add user to video/render groups +sudo usermod -a -G video,render $USER ``` -### Classroom Deployment -```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 -``` +### Build failures -### Research Scaling ```bash -# Multi-GPU research setup -docker-compose -f docker-compose.yml -f docker-compose.research.yml up -d +# Clean Docker cache +docker builder prune -a + +# Rebuild without cache +./build-unified.sh nvidia --no-cache -# 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 +# Check disk space +df -h ``` -## 📚 Additional Resources +## Migration Guide -### 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)** +### From Old Structure to New -### 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)** +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 -### 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)** +### Key Changes ---- +- ✅ 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 -## 🎯 Quick Reference Commands +## Performance Tips -### Essential Commands -```bash -# Build and run CPU variant -./build.sh cpu && ./run.sh -v cpu -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 -# Build and run NVIDIA GPU variant -./build.sh gpu-nvidia && ./run.sh -v gpu-nvidia -i +## Contributing -# Start Jupyter Lab (auto-detects available GPU) -./run.sh -j +When adding new dependencies: -# Run example with GPU acceleration -./run.sh -v gpu-nvidia -e module6_machine_learning/01_quantum_neural_network.py +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 -# List all available examples -./run.sh -l - -# 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.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/docker-compose.yml.old b/docker/docker-compose.yml.old deleted file mode 100644 index 5690e0b..0000000 --- a/docker/docker-compose.yml.old +++ /dev/null @@ -1,238 +0,0 @@ -version: '3.8' - -services: - # CPU-only variant for lightweight usage and learning - quantum101-cpu: - build: - context: .. - dockerfile: docker/Dockerfile.cpu - image: quantum101:cpu - container_name: qc101-cpu - volumes: - - ../examples:/home/qc101/quantum-computing-101/examples - - ../outputs:/home/qc101/quantum-computing-101/outputs - - ../modules:/home/qc101/quantum-computing-101/modules:ro - working_dir: /home/qc101/quantum-computing-101/examples - environment: - - PYTHONPATH=/home/qc101/quantum-computing-101 - - MPLBACKEND=Agg - - QC101_VARIANT=cpu - networks: - - quantum-net - restart: unless-stopped - # CPU resource limits for fair sharing - deploy: - resources: - limits: - cpus: '4.0' - memory: 4G - reservations: - memory: 1G - - # NVIDIA CUDA GPU variant for maximum acceleration - quantum101-gpu-nvidia: - build: - context: .. - dockerfile: docker/Dockerfile.gpu-nvidia - image: quantum101:gpu-nvidia - container_name: qc101-gpu-nvidia - volumes: - - ../examples:/home/qc101/quantum-computing-101/examples - - ../outputs:/home/qc101/quantum-computing-101/outputs - - ../modules:/home/qc101/quantum-computing-101/modules:ro - working_dir: /home/qc101/quantum-computing-101/examples - environment: - - PYTHONPATH=/home/qc101/quantum-computing-101 - - MPLBACKEND=Agg - - QC101_VARIANT=gpu-nvidia - - NVIDIA_VISIBLE_DEVICES=all - - CUDA_VISIBLE_DEVICES=all - networks: - - quantum-net - restart: unless-stopped - # NVIDIA GPU resource configuration - deploy: - resources: - reservations: - devices: - - driver: nvidia - count: all - capabilities: [gpu] - limits: - memory: 8G - runtime: nvidia - - # AMD ROCm GPU variant for AMD GPU acceleration - quantum101-gpu-amd: - build: - context: .. - dockerfile: docker/Dockerfile.gpu-amd - image: quantum101:gpu-amd - container_name: qc101-gpu-amd - volumes: - - ../examples:/home/qc101/quantum-computing-101/examples - - ../outputs:/home/qc101/quantum-computing-101/outputs - - ../modules:/home/qc101/quantum-computing-101/modules:ro - working_dir: /home/qc101/quantum-computing-101/examples - environment: - - PYTHONPATH=/home/qc101/quantum-computing-101 - - MPLBACKEND=Agg - - QC101_VARIANT=gpu-amd - - ROCm_HOME=/opt/rocm - - HIP_VISIBLE_DEVICES=all - networks: - - quantum-net - restart: unless-stopped - devices: - - /dev/kfd:/dev/kfd - - /dev/dri:/dev/dri - group_add: - - video - deploy: - resources: - limits: - memory: 8G - - # Jupyter development environment (CPU) - jupyter-cpu: - build: - context: .. - dockerfile: docker/Dockerfile.cpu - image: quantum101:cpu - container_name: qc101-jupyter-cpu - ports: - - "8888:8888" - volumes: - - ../examples:/home/qc101/quantum-computing-101/examples - - ../outputs:/home/qc101/quantum-computing-101/outputs - - ../modules:/home/qc101/quantum-computing-101/modules:ro - - jupyter-cpu-workspace:/home/qc101/workspace - working_dir: /home/qc101/quantum-computing-101/examples - environment: - - PYTHONPATH=/home/qc101/quantum-computing-101 - - JUPYTER_ENABLE_LAB=yes - command: > - bash -c "pip install --quiet jupyter jupyterlab ipywidgets && - echo 'Starting Jupyter Lab on http://localhost:8888' && - jupyter lab --ip=0.0.0.0 --port=8888 --no-browser - --allow-root --NotebookApp.token='' --NotebookApp.password=''" - networks: - - quantum-net - restart: unless-stopped - - # Jupyter development environment (NVIDIA GPU) - jupyter-gpu-nvidia: - build: - context: .. - dockerfile: docker/Dockerfile.gpu-nvidia - image: quantum101:gpu-nvidia - container_name: qc101-jupyter-gpu-nvidia - ports: - - "8889:8888" - volumes: - - ../examples:/home/qc101/quantum-computing-101/examples - - ../outputs:/home/qc101/quantum-computing-101/outputs - - ../modules:/home/qc101/quantum-computing-101/modules:ro - - jupyter-gpu-nvidia-workspace:/home/qc101/workspace - working_dir: /home/qc101/quantum-computing-101/examples - environment: - - PYTHONPATH=/home/qc101/quantum-computing-101 - - JUPYTER_ENABLE_LAB=yes - - NVIDIA_VISIBLE_DEVICES=all - command: > - bash -c "pip install --quiet jupyter jupyterlab ipywidgets && - echo 'Starting GPU-accelerated Jupyter Lab on http://localhost:8889' && - echo 'CUDA Available:' $(python -c 'import torch; print(torch.cuda.is_available())') && - jupyter lab --ip=0.0.0.0 --port=8888 --no-browser - --allow-root --NotebookApp.token='' --NotebookApp.password=''" - networks: - - quantum-net - runtime: nvidia - deploy: - resources: - reservations: - devices: - - driver: nvidia - count: all - capabilities: [gpu] - restart: unless-stopped - - # Jupyter development environment (AMD ROCm GPU) - jupyter-gpu-amd: - build: - context: .. - dockerfile: docker/Dockerfile.gpu-amd - image: quantum101:gpu-amd - container_name: qc101-jupyter-gpu-amd - ports: - - "8890:8888" - volumes: - - ../examples:/home/qc101/quantum-computing-101/examples - - ../outputs:/home/qc101/quantum-computing-101/outputs - - ../modules:/home/qc101/quantum-computing-101/modules:ro - - jupyter-gpu-amd-workspace:/home/qc101/workspace - working_dir: /home/qc101/quantum-computing-101/examples - environment: - - PYTHONPATH=/home/qc101/quantum-computing-101 - - JUPYTER_ENABLE_LAB=yes - - ROCm_HOME=/opt/rocm - - HIP_VISIBLE_DEVICES=all - command: > - bash -c "pip install --quiet jupyter jupyterlab ipywidgets && - echo 'Starting ROCm-accelerated Jupyter Lab on http://localhost:8890' && - echo 'PyTorch ROCm Available:' $(python -c 'import torch; print(torch.cuda.is_available())') && - jupyter lab --ip=0.0.0.0 --port=8888 --no-browser - --allow-root --NotebookApp.token='' --NotebookApp.password=''" - networks: - - quantum-net - devices: - - /dev/kfd:/dev/kfd - - /dev/dri:/dev/dri - group_add: - - video - restart: unless-stopped - - # Development container with all tools (based on NVIDIA GPU) - quantum101-dev: - build: - context: .. - dockerfile: docker/Dockerfile.gpu-nvidia - image: quantum101:gpu-nvidia - container_name: qc101-dev - volumes: - - ..:/home/qc101/quantum-computing-101 - working_dir: /home/qc101/quantum-computing-101 - environment: - - PYTHONPATH=/home/qc101/quantum-computing-101 - networks: - - quantum-net - runtime: nvidia - deploy: - resources: - reservations: - devices: - - driver: nvidia - count: all - capabilities: [gpu] - command: /bin/bash - stdin_open: true - tty: true - -networks: - quantum-net: - driver: bridge - name: quantum-computing-network - -volumes: - quantum-outputs: - name: qc101-outputs - driver: local - jupyter-cpu-workspace: - name: qc101-jupyter-cpu-workspace - driver: local - jupyter-gpu-nvidia-workspace: - name: qc101-jupyter-gpu-nvidia-workspace - driver: local - jupyter-gpu-amd-workspace: - name: qc101-jupyter-gpu-amd-workspace - driver: local \ No newline at end of file diff --git a/docker/requirements/cpu.txt b/docker/requirements/cpu.txt index 23e2051..d1fccf6 100644 --- a/docker/requirements/cpu.txt +++ b/docker/requirements/cpu.txt @@ -1,19 +1,17 @@ -# CPU-specific requirements for Quantum Computing 101 -# Optimized for CPU-only quantum simulations +# CPU-only requirements for Quantum Computing 101 +# Note: PyTorch CPU version is already included in the base image -# 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..249aaa2 100644 --- a/docker/requirements/gpu-amd.txt +++ b/docker/requirements/gpu-amd.txt @@ -1,35 +1,20 @@ # AMD ROCm GPU requirements for Quantum Computing 101 -# Optimized for AMD GPU acceleration with ROCm 6.x +# Note: PyTorch with ROCm is already included in the base image (rocm/pytorch:latest) -# 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..562a414 100644 --- a/docker/requirements/gpu-nvidia.txt +++ b/docker/requirements/gpu-nvidia.txt @@ -1,35 +1,25 @@ -# NVIDIA CUDA GPU requirements for Quantum Computing 101 -# Optimized for NVIDIA GPU acceleration +# NVIDIA GPU requirements for Quantum Computing 101 +# Note: PyTorch with CUDA is already included in the base image (pytorch/pytorch:2.8.0-cuda12.9-cudnn9-devel) -# Include base requirements +# 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 From 1b4aa9789091ae77bbaef294d872e7e25536a18a Mon Sep 17 00:00:00 2001 From: Stephen Shao Date: Tue, 30 Sep 2025 21:47:59 -0400 Subject: [PATCH 4/6] Fixed the setup --- setup.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) 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", From aa8ce9c872544244aa9fc7e1f80bbc6c4cd8b7f4 Mon Sep 17 00:00:00 2001 From: Stephen Shao Date: Tue, 30 Sep 2025 22:19:35 -0400 Subject: [PATCH 5/6] Updated docker compose --- docker/README.md | 256 ++++++++++++++++++++++++++ docker/docker-compose.yml | 371 ++++++++++++-------------------------- 2 files changed, 376 insertions(+), 251 deletions(-) diff --git a/docker/README.md b/docker/README.md index 299ab8f..31f3e41 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,5 +1,17 @@ # Quantum Computing 101 - Docker Setup Guide +## 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) + ## Overview This Docker setup provides a unified, flexible solution for running Quantum Computing 101 across different hardware configurations: @@ -99,6 +111,225 @@ docker run -it --rm \ quantum-computing-101:amd ``` +## Volume Mounting & Development Workflow + +### Current Setup + +The `docker-compose.yml` configures volume mounts for seamless host-container development: + +```yaml +volumes: + - ../examples:/home/qc101/quantum-computing-101/examples + - ../outputs:/home/qc101/quantum-computing-101/outputs + - ../modules:/home/qc101/quantum-computing-101/modules:ro +``` + +**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 +# 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! +``` + +#### 2. Interactive Development Workflow + +```bash +# 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 +``` + +#### 3. Jupyter Notebook with Volume Mounts + +```bash +# Start with Jupyter +docker compose up qc101-nvidia + +# Access Jupyter at http://localhost:8889 +# All notebooks saved in container → Synced to host examples/ +``` + +### 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__ +``` + +**Use when:** Developing library code, not just examples + +#### Option B: Selective File Mounting + +```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 +``` + +**Use when:** You want precise control over what's mounted + +#### Option C: Using .dockerignore + +Create `docker/.dockerignore`: + +``` +.git +__pycache__ +*.pyc +.pytest_cache +.venv +node_modules +*.log +``` + +Then mount entire project: +```yaml +volumes: + - ..:/home/qc101/quantum-computing-101 +``` + +### Docker Run Command with Volume Mounts + +If not using docker-compose: + +```bash +# 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 + +#### Linux/Mac (Native Docker) +- Volume mounts are fast (native filesystem) +- Use `consistency=cached` for better performance (macOS) + +#### 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 +``` + +- `: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 + +### Quick Reference Table + +| 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 | + +### Testing Your Volume Setup + +```bash +# Test host → container +echo "test from host" > ../examples/test.txt +docker exec qc101-nvidia cat /home/qc101/quantum-computing-101/examples/test.txt + +# 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 + +# Cleanup +rm ../examples/test.txt ../outputs/test.txt +``` + ## Directory Structure ``` @@ -245,6 +476,31 @@ docker builder prune -a df -h ``` +### Volume Mount Issues + +#### Permission Problems +```bash +# Fix ownership if needed +docker exec -it qc101-nvidia chown -R qc101:qc101 /home/qc101/quantum-computing-101 +``` + +#### Files Not Syncing +```bash +# Restart container to remount volumes +docker compose restart qc101-nvidia + +# Or recreate container +docker compose down +docker compose up qc101-nvidia +``` + +#### Check Mount Points +```bash +# Inside container, verify mounts +docker exec -it qc101-nvidia df -h +docker exec -it qc101-nvidia mount | grep qc101 +``` + ## Migration Guide ### From Old Structure to New diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index 512678c..5690e0b 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -1,265 +1,134 @@ -version: '3.8'version: '3.8' - - - -# Quantum Computing 101 - Docker Compose Configurationservices: - -# Supports CPU, NVIDIA GPU, and AMD GPU variants # CPU-only variant for lightweight usage and learning +version: '3.8' +services: + # CPU-only variant for lightweight usage and learning quantum101-cpu: - -services: build: - - # ============================================================================= context: .. - - # CPU-Only Service dockerfile: docker/Dockerfile.cpu - - # ============================================================================= image: quantum101:cpu - - qc101-cpu: container_name: qc101-cpu - - build: volumes: - - context: .. - ../examples:/home/qc101/quantum-computing-101/examples - - dockerfile: docker/Dockerfile - ../outputs:/home/qc101/quantum-computing-101/outputs - - args: - ../modules:/home/qc101/quantum-computing-101/modules:ro - - VARIANT: cpu working_dir: /home/qc101/quantum-computing-101/examples - - target: runtime environment: - - image: quantum-computing-101:cpu - PYTHONPATH=/home/qc101/quantum-computing-101 - - container_name: qc101-cpu - MPLBACKEND=Agg - - hostname: qc101-cpu - QC101_VARIANT=cpu - - environment: networks: - - - QC101_VARIANT=cpu - quantum-net - - volumes: restart: unless-stopped - - - ../examples:/home/qc101/quantum-computing-101/examples # CPU resource limits for fair sharing - - - ../outputs:/home/qc101/quantum-computing-101/outputs deploy: - - - qc101-cache:/home/qc101/.cache resources: - - ports: limits: - - - "8888:8888" # Jupyter Lab cpus: '4.0' - - - "6006:6006" # TensorBoard memory: 4G - - networks: reservations: - - - qc101-network memory: 1G - + build: + context: .. + dockerfile: docker/Dockerfile.cpu + image: quantum101:cpu + container_name: qc101-cpu + volumes: + - ../examples:/home/qc101/quantum-computing-101/examples + - ../outputs:/home/qc101/quantum-computing-101/outputs + - ../modules:/home/qc101/quantum-computing-101/modules:ro + working_dir: /home/qc101/quantum-computing-101/examples + environment: + - PYTHONPATH=/home/qc101/quantum-computing-101 + - MPLBACKEND=Agg + - QC101_VARIANT=cpu + networks: + - quantum-net restart: unless-stopped + # CPU resource limits for fair sharing + deploy: + resources: + limits: + cpus: '4.0' + memory: 4G + reservations: + memory: 1G - stdin_open: true # NVIDIA CUDA GPU variant for maximum acceleration - - tty: true quantum101-gpu-nvidia: - + # NVIDIA CUDA GPU variant for maximum acceleration + quantum101-gpu-nvidia: build: - - # ============================================================================= context: .. - - # NVIDIA GPU Service dockerfile: docker/Dockerfile.gpu-nvidia - - # ============================================================================= image: quantum101:gpu-nvidia - - qc101-nvidia: container_name: qc101-gpu-nvidia - - build: volumes: - - context: .. - ../examples:/home/qc101/quantum-computing-101/examples - - dockerfile: docker/Dockerfile - ../outputs:/home/qc101/quantum-computing-101/outputs - - args: - ../modules:/home/qc101/quantum-computing-101/modules:ro - - VARIANT: nvidia working_dir: /home/qc101/quantum-computing-101/examples - - PYTORCH_VERSION: "2.8.0" environment: - - CUDA_VERSION: "12.9" - PYTHONPATH=/home/qc101/quantum-computing-101 - - CUDNN_VERSION: "9" - MPLBACKEND=Agg - - target: runtime - QC101_VARIANT=gpu-nvidia - - image: quantum-computing-101:nvidia-gpu - NVIDIA_VISIBLE_DEVICES=all - - container_name: qc101-nvidia - CUDA_VISIBLE_DEVICES=all - - hostname: qc101-nvidia networks: - - environment: - quantum-net - - - QC101_VARIANT=gpu-nvidia restart: unless-stopped - - - NVIDIA_VISIBLE_DEVICES=all # NVIDIA GPU resource configuration - - - NVIDIA_DRIVER_CAPABILITIES=compute,utility deploy: - - volumes: resources: - - - ../examples:/home/qc101/quantum-computing-101/examples reservations: - - - ../outputs:/home/qc101/quantum-computing-101/outputs devices: - - - qc101-cache-nvidia:/home/qc101/.cache - driver: nvidia - - - /tmp/.X11-unix:/tmp/.X11-unix:rw count: all - - ports: capabilities: [gpu] - - - "8889:8888" # Jupyter Lab (different port to avoid conflict) limits: - - - "6007:6006" # TensorBoard memory: 8G - - networks: runtime: nvidia - - - qc101-network - - deploy: # AMD ROCm GPU variant for AMD GPU acceleration - - resources: quantum101-gpu-amd: - - reservations: build: - - devices: context: .. - - - driver: nvidia dockerfile: docker/Dockerfile.gpu-amd - - count: all image: quantum101:gpu-amd - - capabilities: [gpu] container_name: qc101-gpu-amd - - restart: unless-stopped volumes: - - stdin_open: true - ../examples:/home/qc101/quantum-computing-101/examples - - tty: true - ../outputs:/home/qc101/quantum-computing-101/outputs - + context: .. + dockerfile: docker/Dockerfile.gpu-nvidia + image: quantum101:gpu-nvidia + container_name: qc101-gpu-nvidia + volumes: + - ../examples:/home/qc101/quantum-computing-101/examples + - ../outputs:/home/qc101/quantum-computing-101/outputs - ../modules:/home/qc101/quantum-computing-101/modules:ro + working_dir: /home/qc101/quantum-computing-101/examples + environment: + - PYTHONPATH=/home/qc101/quantum-computing-101 + - MPLBACKEND=Agg + - QC101_VARIANT=gpu-nvidia + - NVIDIA_VISIBLE_DEVICES=all + - CUDA_VISIBLE_DEVICES=all + networks: + - quantum-net + restart: unless-stopped + # NVIDIA GPU resource configuration + deploy: + resources: + reservations: + devices: + - driver: nvidia + count: all + capabilities: [gpu] + limits: + memory: 8G + runtime: nvidia - # ============================================================================= working_dir: /home/qc101/quantum-computing-101/examples - - # AMD GPU Service (ROCm) environment: - - # ============================================================================= - PYTHONPATH=/home/qc101/quantum-computing-101 - - qc101-amd: - MPLBACKEND=Agg - - build: - QC101_VARIANT=gpu-amd - - context: .. - ROCm_HOME=/opt/rocm - - dockerfile: docker/Dockerfile - HIP_VISIBLE_DEVICES=all - - args: networks: - - VARIANT: amd - quantum-net - - target: runtime restart: unless-stopped - - image: quantum-computing-101:amd-gpu devices: - - container_name: qc101-amd - /dev/kfd:/dev/kfd - - hostname: qc101-amd - /dev/dri:/dev/dri - - environment: group_add: - - - QC101_VARIANT=gpu-amd - video - - - ROCM_VISIBLE_DEVICES=all deploy: - - - HIP_VISIBLE_DEVICES=all resources: - - volumes: limits: - - - ../examples:/home/qc101/quantum-computing-101/examples memory: 8G - - - ../outputs:/home/ysha/aicomputing101/quantum-computing-101/outputs - - - qc101-cache-amd:/home/qc101/.cache # Jupyter development environment (CPU) - - - /dev/kfd:/dev/kfd jupyter-cpu: - - - /dev/dri:/dev/dri build: - - ports: context: .. - - - "8890:8888" # Jupyter Lab (different port) dockerfile: docker/Dockerfile.cpu - - - "6008:6006" # TensorBoard image: quantum101:cpu - - networks: container_name: qc101-jupyter-cpu - - - qc101-network ports: - - devices: - "8888:8888" - - - /dev/kfd volumes: - - - /dev/dri - ../examples:/home/qc101/quantum-computing-101/examples - - group_add: - ../outputs:/home/qc101/quantum-computing-101/outputs - - - video - ../modules:/home/qc101/quantum-computing-101/modules:ro - - - render - jupyter-cpu-workspace:/home/qc101/workspace - - restart: unless-stopped working_dir: /home/qc101/quantum-computing-101/examples - - stdin_open: true environment: - - tty: true - PYTHONPATH=/home/qc101/quantum-computing-101 + # AMD ROCm GPU variant for AMD GPU acceleration + quantum101-gpu-amd: + build: + context: .. + dockerfile: docker/Dockerfile.gpu-amd + image: quantum101:gpu-amd + container_name: qc101-gpu-amd + volumes: + - ../examples:/home/qc101/quantum-computing-101/examples + - ../outputs:/home/qc101/quantum-computing-101/outputs + - ../modules:/home/qc101/quantum-computing-101/modules:ro + working_dir: /home/qc101/quantum-computing-101/examples + environment: + - PYTHONPATH=/home/qc101/quantum-computing-101 + - MPLBACKEND=Agg + - QC101_VARIANT=gpu-amd + - ROCm_HOME=/opt/rocm + - HIP_VISIBLE_DEVICES=all + networks: + - quantum-net + restart: unless-stopped + devices: + - /dev/kfd:/dev/kfd + - /dev/dri:/dev/dri + group_add: + - video + deploy: + resources: + limits: + memory: 8G + # Jupyter development environment (CPU) + jupyter-cpu: + build: + context: .. + dockerfile: docker/Dockerfile.cpu + image: quantum101:cpu + container_name: qc101-jupyter-cpu + ports: + - "8888:8888" + volumes: + - ../examples:/home/qc101/quantum-computing-101/examples + - ../outputs:/home/qc101/quantum-computing-101/outputs + - ../modules:/home/qc101/quantum-computing-101/modules:ro + - jupyter-cpu-workspace:/home/qc101/workspace + working_dir: /home/qc101/quantum-computing-101/examples + environment: + - PYTHONPATH=/home/qc101/quantum-computing-101 - JUPYTER_ENABLE_LAB=yes - -# ============================================================================= command: > - -# Networks bash -c "pip install --quiet jupyter jupyterlab ipywidgets && - -# ============================================================================= echo 'Starting Jupyter Lab on http://localhost:8888' && - -networks: jupyter lab --ip=0.0.0.0 --port=8888 --no-browser - - qc101-network: --allow-root --NotebookApp.token='' --NotebookApp.password=''" - - driver: bridge networks: - - name: qc101-network - quantum-net - + command: > + bash -c "pip install --quiet jupyter jupyterlab ipywidgets && + echo 'Starting Jupyter Lab on http://localhost:8888' && + jupyter lab --ip=0.0.0.0 --port=8888 --no-browser + --allow-root --NotebookApp.token='' --NotebookApp.password=''" + networks: + - quantum-net restart: unless-stopped -# ============================================================================= - -# Volumes (for persistent cache) # Jupyter development environment (NVIDIA GPU) - -# ============================================================================= jupyter-gpu-nvidia: - -volumes: build: - - qc101-cache: context: .. - - name: qc101-cache-cpu dockerfile: docker/Dockerfile.gpu-nvidia - - qc101-cache-nvidia: image: quantum101:gpu-nvidia - - name: qc101-cache-nvidia container_name: qc101-jupyter-gpu-nvidia - - qc101-cache-amd: ports: - - name: qc101-cache-amd - "8889:8888" - + # Jupyter development environment (NVIDIA GPU) + jupyter-gpu-nvidia: + build: + context: .. + dockerfile: docker/Dockerfile.gpu-nvidia + image: quantum101:gpu-nvidia + container_name: qc101-jupyter-gpu-nvidia + ports: + - "8889:8888" volumes: - ../examples:/home/qc101/quantum-computing-101/examples - ../outputs:/home/qc101/quantum-computing-101/outputs From 0c5927febd9a9d4d1e4ab288fcf467a4b6568a09 Mon Sep 17 00:00:00 2001 From: Stephen Shao Date: Tue, 30 Sep 2025 22:31:22 -0400 Subject: [PATCH 6/6] cleanup the requirements for docker and native installation --- docker/requirements/base.txt | 7 +++++-- docker/requirements/cpu.txt | 5 ++++- docker/requirements/gpu-amd.txt | 7 +++++-- docker/requirements/gpu-nvidia.txt | 8 ++++++-- examples/requirements-core.txt | 7 +++++-- examples/requirements-dev.txt | 7 ++++++- examples/requirements.txt | 13 +++++++++---- 7 files changed, 40 insertions(+), 14 deletions(-) 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 d1fccf6..e642459 100644 --- a/docker/requirements/cpu.txt +++ b/docker/requirements/cpu.txt @@ -1,5 +1,8 @@ -# CPU-only requirements for Quantum Computing 101 +# 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 quantum computing requirements -r base.txt diff --git a/docker/requirements/gpu-amd.txt b/docker/requirements/gpu-amd.txt index 249aaa2..29c7471 100644 --- a/docker/requirements/gpu-amd.txt +++ b/docker/requirements/gpu-amd.txt @@ -1,5 +1,8 @@ -# AMD ROCm GPU requirements for Quantum Computing 101 -# Note: PyTorch with ROCm is already included in the base image (rocm/pytorch:latest) +# 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 quantum computing requirements -r base.txt diff --git a/docker/requirements/gpu-nvidia.txt b/docker/requirements/gpu-nvidia.txt index 562a414..05b138b 100644 --- a/docker/requirements/gpu-nvidia.txt +++ b/docker/requirements/gpu-nvidia.txt @@ -1,5 +1,9 @@ -# NVIDIA GPU requirements for Quantum Computing 101 -# Note: PyTorch with CUDA is already included in the base image (pytorch/pytorch:2.8.0-cuda12.9-cudnn9-devel) +# 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 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