Slice 2: GPU infrastructure — Dockerfile, deps, --gpu/--device flags, memory check

[joeljose]

Context

Parent: #11 | PRD: #10 | Design: docs/design/gpu-acceleration.md Sections D, E, F

Goal

Set up all GPU infrastructure so later slices can focus on the pipeline logic. After this slice, --gpu is accepted but prints "GPU pipeline not yet implemented" and exits. The Docker image builds and imports work.

Acceptance Criteria

• Dockerfile.gpu based on pytorch/pytorch:2.1.2-cuda12.1-cudnn8-runtime with numpy<2, pytorch_wavelets from git
• docker-build-gpu.sh reads VERSION, tags as motion-mag-dtcwt-gpu:{version} and :latest
• requirements-gpu.txt with scipy, numpy<2, opencv-python-headless, PyWavelets
• --gpu flag added to CLI (import-guarded: torch/pytorch_wavelets only imported when --gpu used)
• --device flag (default: 0) for GPU selection
• Clear error messages when --gpu used but torch or pytorch_wavelets not installed
• Clear error message when --gpu used but no CUDA GPU available
• Pre-flight memory estimation function: estimate_memory(num_frames, height, width, nlevels, gpu=False) returns (cpu_ram_bytes, vram_bytes)
• Memory check runs before processing, warns if estimated usage > 70% of available
• GPU name and VRAM printed at startup when --gpu used
• test.sh updated with gpu mode (builds GPU image, runs lint + tests)
• CI .github/workflows/ci.yml updated with GPU job (lint only, no GPU on runners)

Blocked by

Nothing — can be done in parallel with Slice 1.

Files likely involved

• motion_mag.py — CLI flags, import guards, memory estimation, GPU detection
• Dockerfile.gpu — new file
• docker-build-gpu.sh — new file
• requirements-gpu.txt — new file
• test.sh — add gpu mode
• .github/workflows/ci.yml — add GPU lint job

Testing approach

• docker-build-gpu.sh succeeds
• docker run --gpus device=0 ... --gpu --help works
• docker run ... --gpu -i face.mp4 prints "not yet implemented"
• docker run ... --gpu without GPU prints CUDA error
• Memory estimation unit tests

[joeljose]

Completed in PR #18, released in v2.0.0