Merge pull request #8 from AIComputing101/dev/docker

multi-GPU containerization support

Author: coketaste

.dockerignore

@@ -0,0 +1,134 @@
+# Docker ignore file for Quantum Computing 101
+# Optimize build context and reduce image size
+
+# Version control
+.git
+.gitignore
+.github/
+.gitmodules
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+.env
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# Jupyter Notebook
+.ipynb_checkpoints
+*.ipynb
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# Documentation
+docs/
+*.md
+!README.md
+!CLAUDE.md
+
+# Output directories
+outputs/
+results/
+plots/
+figures/
+logs/
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+*.log
+
+# Package managers
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Large data files (if any)
+*.hdf5
+*.h5
+*.npz
+*.pkl
+*.pickle
+
+# Compiled files
+*.o
+*.so
+*.dylib
+*.dll
+
+# Docker related (avoid recursive copying)
+Dockerfile*
+docker-compose*.yml
+.dockerignore
+
+# CI/CD
+.github/
+.gitlab-ci.yml
+.travis.yml
+.circleci/
+
+# Local development
+local/
+scratch/
+sandbox/
+
+# Cloud credentials (should never be in repo anyway)
+*.json
+*.pem
+*.key
+!examples/requirements*.txt

BEGINNERS_GUIDE.md

@@ -101,17 +101,39 @@ Welcome to your quantum computing journey! This guide will help you navigate the
 
 ## 🛠️ Setup Instructions
 
-### Quick Start (5 minutes):
+### 🐳 **Option 1: Docker (Recommended - Zero Setup!)**
+```bash
+# Clone this repository first
+git clone https://github.com/AIComputing101/quantum-computing-101.git
+cd quantum-computing-101
+
+# Build and run with Docker (handles all dependencies automatically)
+cd docker
+./build.sh cpu                    # Build lightweight CPU container (1.2GB)
+./run.sh -v cpu -i               # Start interactive session
+
+# Or run specific examples directly
+./run.sh -v cpu -e module1_fundamentals/01_classical_vs_quantum_bits.py
+
+# Start Jupyter Lab for experimentation
+./run.sh -v cpu -j               # Access at http://localhost:8888
+```
+
+**🌟 Docker Benefits:**
+- **Zero Setup**: No Python installation or dependency management required
+- **Consistent Environment**: Same setup across Windows, Mac, Linux
+- **GPU Ready**: Easy GPU acceleration when you're ready for advanced examples
+- **Latest Software**: Pre-configured with optimized quantum computing stack
+
+### 💻 **Option 2: Native Installation (Traditional)**
 ```bash
 # Install Python 3.11+ if not already installed (3.12+ recommended)
 # Clone this repository first
 git clone https://github.com/AIComputing101/quantum-computing-101.git
 cd quantum-computing-101
 
-# Install required packages
+# Install required packages (Updated v2.0)
 pip install -r examples/requirements-core.txt
-# OR install individual packages:
-pip install qiskit>=0.45.0 qiskit-aer>=0.13.0 matplotlib>=3.7.0 numpy>=1.24.0 pylatexenc>=2.10
 
 # Test your setup
 python examples/module1_fundamentals/01_classical_vs_quantum_bits.py
@@ -120,6 +142,28 @@ python examples/module1_fundamentals/01_classical_vs_quantum_bits.py
 python verify_examples.py --quick
 ```
 
+### 🚀 **Option 3: GPU Acceleration (Advanced)**
+```bash
+# NVIDIA GPU setup (CUDA 12.6 with latest H100/A100 support)
+cd docker
+./build.sh gpu-nvidia            # Build NVIDIA GPU container (3.5GB)
+./run.sh -v gpu-nvidia -e module6_machine_learning/01_quantum_neural_network.py
+
+# AMD ROCm setup (ROCm 6.x with MI300A/MI300X support)
+./build.sh gpu-amd               # Build AMD ROCm container (3.2GB)
+./run.sh -v gpu-amd -i
+
+# GPU Jupyter Lab with acceleration
+./run.sh -v gpu-nvidia -j        # NVIDIA accelerated Jupyter
+./run.sh -v gpu-amd -j           # AMD ROCm accelerated Jupyter
+```
+
+**🏎️ GPU Performance Benefits:**
+- **5-8x Speedup**: Large quantum simulations and ML workloads
+- **Latest Hardware**: Supports newest NVIDIA H100/A100 and AMD MI300 series
+- **Automatic Detection**: Build scripts detect your GPU hardware
+- **Optimized Libraries**: Pre-built Qiskit-Aer GPU backends for quantum acceleration
+
 ### Recommended Development Environment:
 - **Python 3.11+** (required, 3.12+ recommended for best performance)
 - **Jupyter Notebook** (optional but helpful for experimentation)

CHANGELOG.md

@@ -7,17 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0] - 2025-09-10
+
 ### Added
-- Initial open source release preparation
-- Comprehensive GitHub workflows for CI/CD
-- Security policy and vulnerability reporting process
-- Issue and pull request templates
-- Code of conduct for community guidelines
+- **Docker GPU Acceleration v2.0**: Latest GPU support with cutting-edge hardware compatibility
+  - **NVIDIA CUDA 12.6**: Updated from CUDA 12.2 for latest H100/A100 support
+  - **AMD ROCm 6.x**: Updated from ROCm 5.x with AMD MI300A/MI300X series support
+  - **Qiskit-Aer GPU Optimization**: Proper GPU backend installation for quantum acceleration
+    - NVIDIA: qiskit-aer-gpu package for CUDA acceleration
+    - AMD: Custom Qiskit-Aer build from source with ROCm gfx942 (MI300) support
+  - **Package Conflict Resolution**: Fixed qiskit-aer CPU/GPU variant conflicts
+  - **Performance Optimization**: Enhanced GPU detection and graceful fallbacks
+- **Docker Containerization**: Complete multi-GPU containerization support
+  - CPU-only lightweight container (1.2GB) for learning and basic examples
+  - NVIDIA CUDA GPU container (3.5GB) with 5-8x acceleration for large simulations
+  - AMD ROCm GPU container (3.2GB) with MI300 series support
+  - Multi-stage builds for optimal image sizes
+  - Smart build scripts with automatic GPU hardware detection
+  - Comprehensive run scripts with Jupyter Lab support
+  - Docker Compose orchestration for multi-service deployments
+- **Enhanced Requirements Management**: Modular requirements system for better dependency management
+  - Separated core, full, and GPU-specific requirements
+  - Updated to latest package versions (Qiskit 1.0+, PyTorch 2.2+, Python 3.11+)
+  - Added missing dependencies (yfinance, cryptography, boto3, qiskit-algorithms)
+  - Optimized Docker layer caching with modular requirements structure
+- **Updated Python Support**: Minimum Python version increased to 3.11, with 3.12+ support
+- **Performance Improvements**: Updated scientific computing stack for better performance
+- **Cloud Integration**: Enhanced AWS Braket and IBM Quantum cloud support
 
 ## [1.0.0] - 2025-09-04
 
 ### Added
-- **Complete curriculum implementation**: All 40 examples across 8 modules
+- **Complete curriculum implementation**: All 45 examples across 8 modules
 - **Module 1 - Fundamentals**: 5 examples covering basic quantum concepts (1,703 LOC)
   - Classical vs quantum bits comparison
   - Quantum gates and circuits
@@ -78,11 +99,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Production quality**: Professional code standards throughout
 
 ### Technical
-- **Total codebase**: 24,547 lines of production-grade Python code
-- **Dependencies**: Qiskit 2.x, NumPy, SciPy, Matplotlib, and more
-- **Python compatibility**: Python 3.8+
+- **Total codebase**: 24,547+ lines of production-grade Python code
+- **Dependencies**: Qiskit 1.0+, NumPy, SciPy, Matplotlib, and more
+- **Python compatibility**: Python 3.11+ (updated from 3.8+)
 - **Framework support**: Primary Qiskit with extension points for other frameworks
 - **Testing**: Comprehensive validation of all examples
+- **Container Support**: Docker-first approach with multi-GPU support
 
 ## [0.9.0] - 2025-08-15
 
@@ -107,11 +129,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Dependency and framework evaluation
 
 ### Implementation Phase (2025-08-15 to 2025-09-04)
-- Systematic implementation of all 40 examples
+- Systematic implementation of all 45 examples
 - Quality assurance and testing
 - Documentation completion
 - Code review and optimization
 
+### Docker Containerization Phase (2025-09-10)
+- Complete Docker containerization with multi-GPU support
+- Requirements system refactoring and dependency updates
+- Performance optimizations and Python 3.11+ migration
+- Enhanced cloud platform integration
+
 ### Open Source Preparation (2025-09-04)
 - Community guidelines and contribution framework
 - Security policy and vulnerability reporting