Add Module 001: GPU Fundamentals (#1)

Initial curriculum module with lecture notes, quiz, and four hands-on
exercises (CPU-GPU comparison, peak throughput, occupancy calculator,
roofline analysis). Each exercise ships with starter.py and check.py.

Adds .gitignore for Python build artifacts and exercise outputs.

Co-authored-by: curriculum-night-runner <noreply@anthropic.com>

Author: JoshuaAFerguson

.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Editor
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Build / coverage
+build/
+dist/
+.coverage
+htmlcov/
+coverage.xml
+
+# Exercise outputs
+roofline.png

README.md

@@ -592,6 +592,11 @@ This curriculum was developed with input from:
 
 **Ready to become an AI/ML Performance Engineering expert?**
 
-Start with [Module 1: GPU Fundamentals →](lessons/01-gpu-fundamentals/README.md)
-
-or jump into [Project 1: Model Compression →](projects/project-01-model-optimization/README.md)
+Start with [Module 1: GPU Fundamentals →](modules/mod-001-gpu-fundamentals/README.md)
+*(Module 1 ships with 6 learning objectives, lecture notes, four
+autograded CPU-only exercises, and a 12-question quiz. Modules 2+
+are scheduled.)*
+
+> The longer-form curriculum spec (8 modules + 3 projects) lives in
+> [`CURRICULUM.md`](CURRICULUM.md). Modules will be promoted from
+> spec to implementation incrementally.

modules/mod-001-gpu-fundamentals/README.md

@@ -0,0 +1,85 @@
+# Module 1 — GPU Fundamentals
+
+> **Track:** AI/ML Performance Engineer
+> **Time budget:** ~20 hours (2 weeks part-time)
+> **Module status:** first build, 2026-05-22
+
+This is the first module in the Performance Engineering track. It sets the
+mental model you will reuse for the rest of the curriculum: what a GPU
+actually is, why it is fast on some workloads and slow on others, and how to
+reason about that quantitatively *before* you write a single line of CUDA.
+
+The lecture is intentionally light on CUDA code. You cannot meaningfully
+optimize what you do not understand at the architecture level, and almost
+all real-world performance work is decided in the math (arithmetic
+intensity, memory bandwidth, occupancy) — not in the kernel syntax. The
+CUDA programming syntax is the focus of [Module 2](../mod-002-cuda-programming/README.md).
+For this module, your job is to think like a hardware engineer.
+
+## Learning objectives
+
+By the end of this module, you will be able to:
+
+1. **Explain** the SIMT execution model and how a warp differs from a thread
+   in CPU-style multi-threading.
+2. **Calculate** the theoretical peak FP32, TF32, and FP16 throughput of a
+   given NVIDIA GPU from its published spec sheet.
+3. **Calculate** theoretical peak memory bandwidth from a memory clock,
+   memory bus width, and memory type (GDDR / HBM).
+4. **Identify** whether a workload is compute-bound or memory-bound using
+   arithmetic intensity and the roofline model.
+5. **Estimate** kernel occupancy from a launch configuration (block size,
+   registers per thread, shared memory per block) and explain which of those
+   three resources is the limiting one.
+6. **Distinguish** the levels of the GPU memory hierarchy (registers,
+   shared / L1, L2, global / HBM) and predict which level a memory access
+   will hit given a kernel's access pattern.
+
+These are measurable; every exercise targets one or more of them.
+
+## Prerequisites
+
+You should be comfortable with:
+
+- Python (numpy in particular)
+- Basic linear algebra (matrix multiply, what FLOPS means)
+- Reading a hardware spec sheet without panicking
+
+You do **not** need to have written CUDA before. You also do not need to
+have an NVIDIA GPU available *to do this module* — all four exercises run
+on CPU. (A GPU is required from Module 2 onward.)
+
+## Module structure
+
+| File | What's in it |
+|---|---|
+| [`lecture-notes.md`](lecture-notes.md) | The actual material. Six lessons covering CPU vs GPU, NVIDIA architecture, memory hierarchy, threads / blocks / grids, warp execution, and performance metrics. |
+| [`exercises/exercise-01-cpu-gpu-comparison`](exercises/exercise-01-cpu-gpu-comparison/) | Use the SIMT model to predict which of three workloads accelerates on a GPU and by roughly how much. CPU-only. |
+| [`exercises/exercise-02-peak-throughput`](exercises/exercise-02-peak-throughput/) | Given spec-sheet values, compute peak FP32 / TF32 / HBM bandwidth for A100, H100, RTX 4090. CPU-only. |
+| [`exercises/exercise-03-occupancy-calculator`](exercises/exercise-03-occupancy-calculator/) | Reimplement NVIDIA's occupancy calculation from scratch. CPU-only. |
+| [`exercises/exercise-04-roofline-analysis`](exercises/exercise-04-roofline-analysis/) | Plot a roofline for an A100 and place six kernels on it. CPU-only. |
+| [`quiz.md`](quiz.md) / [`quiz-answers.md`](quiz-answers.md) | 12-question check on the learning objectives. |
+| [`resources.md`](resources.md) | Primary sources — NVIDIA architecture whitepapers, the CUDA C Programming Guide, Volkov's thesis, the roofline paper. |
+
+## How to work through this module
+
+1. Read `lecture-notes.md` straight through once. It is short on purpose.
+2. Do the four exercises in order. Each one has a `starter.py` you edit
+   and a `check.py` that grades your answer. `python check.py` should
+   print `PASS` when you are done.
+3. Take the quiz **without** scrolling to the answer key. If you miss
+   more than two questions, reread the relevant lesson before moving on
+   to Module 2.
+
+## Assessment criteria for this module
+
+You are ready to move on when you can, on a blank page:
+
+- Write the SIMT execution model in three sentences without using the word
+  "thread" the way a CPU programmer would use it.
+- Compute peak FP32 throughput of any NVIDIA GPU from CUDA-core count and
+  boost clock.
+- Sketch a roofline and place a kernel on it given its arithmetic
+  intensity and achieved GFLOP/s.
+
+Module 2 picks up from these primitives and starts writing kernels.

modules/mod-001-gpu-fundamentals/exercises/exercise-01-cpu-gpu-comparison/README.md

@@ -0,0 +1,73 @@
+# Exercise 1 — When does the GPU actually help?
+
+> **Targets learning objectives:** 1, 4
+> **Time:** ~45 min
+> **Requires:** Python 3.10+, numpy. No GPU needed.
+
+## What you'll do
+
+You will be given three concrete workloads. For each, you predict —
+*without writing CUDA* — whether a modern data-center GPU will outperform
+a modern server CPU, and by approximately how much. You will defend each
+answer with a one-paragraph argument grounded in the SIMT execution
+model.
+
+The point of this exercise is to make you justify GPU-vs-CPU decisions
+the way they get justified in real engineering reviews: with arithmetic
+intensity, memory bandwidth, and parallelism analysis — not with vibes.
+
+## The workloads
+
+1. **`dense_matmul`** — Multiply two FP32 matrices of shape (8192, 8192).
+   The output is FP32. Inputs and outputs all live in device memory
+   already (no host-device transfer cost in your analysis).
+
+2. **`json_parse`** — Parse a single 1-GB JSON file containing a deeply
+   nested object hierarchy. Output is a Python dict.
+
+3. **`elementwise_relu`** — Apply `y = max(0, x)` to a single FP32
+   tensor of shape (1024, 1024). Input and output already live on the
+   appropriate device (CPU memory for the CPU case, device memory for
+   the GPU case).
+
+## What to submit
+
+Edit `starter.py`. For each workload, fill in:
+
+- `gpu_helps: bool` — Will the GPU outperform a comparable CPU?
+- `expected_speedup_bucket: str` — One of `"<1x"`, `"1-2x"`,
+  `"2-10x"`, `"10-100x"`, `">100x"`.
+- `reasoning: str` — One paragraph (3–6 sentences). At minimum,
+  identify (a) is this compute-bound or memory-bound, (b) how much
+  parallelism is available, (c) what kills it on the GPU if anything.
+
+Then run:
+
+```bash
+python check.py
+```
+
+The check looks at your bucketed answer (it does **not** grade the
+prose — that is what the solutions repo's worked answer is for) and
+prints `PASS` when all three are right.
+
+## Hints
+
+- For `dense_matmul`: how many independent multiply-accumulates are in
+  the output? How many bytes of HBM are read? Compute the arithmetic
+  intensity and place it relative to an A100's ridge point (~9.75
+  FLOP/byte for FP32).
+- For `json_parse`: how much arithmetic per byte of input? How many
+  truly independent sub-tasks are there? Is the workload going to live
+  on the GPU's arithmetic units or on its control-flow logic?
+- For `elementwise_relu`: arithmetic intensity is ~0.125 FLOP/byte
+  (one compare, one select per FP32). The interesting question is
+  *kernel launch overhead vs total work*. How many bytes does the
+  GPU move for a (1024, 1024) FP32 tensor? At HBM bandwidth, how long
+  does that take? Compare to a 5–20 µs kernel launch.
+
+## What "right" looks like
+
+This is a reasoning exercise; the buckets are coarse on purpose. There
+is one defensible answer per workload at this granularity, and the
+solutions repo's `SOLUTION.md` walks through the derivation in full.

modules/mod-001-gpu-fundamentals/exercises/exercise-01-cpu-gpu-comparison/check.py

@@ -0,0 +1,95 @@
+"""Autograder for Exercise 1. Run: python check.py
+
+Grades only the bucketed answer (gpu_helps + expected_speedup_bucket).
+The reasoning prose is graded by the human reader against the
+solutions repo's worked answer.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Make sibling starter.py importable regardless of CWD.
+sys.path.insert(0, str(Path(__file__).parent))
+
+try:
+    import starter  # type: ignore[import-not-found]
+except ImportError as e:
+    print(f"FAIL: could not import starter.py ({e})")
+    sys.exit(1)
+
+
+EXPECTED = {
+    # Dense GEMM at 8192^3 has AI ~ 341 FLOP/byte, far above the A100
+    # ridge point (~9.75). It is the canonical compute-bound GPU win.
+    # Practical speedups for FP32 dense GEMM on cuBLAS vs MKL on a
+    # modern server CPU land at >100x (8192^3 is ~1.1 TFLOP of work;
+    # a 19.5 TFLOPS A100 does it in ~60 ms, vs several seconds on
+    # most server CPUs).
+    "dense_matmul": {"gpu_helps": True, "bucket": ">100x"},
+    # JSON parsing is irregular control flow, tiny arithmetic per byte,
+    # serial dependency from one nested element to the next. The GPU
+    # has no path to win.
+    "json_parse": {"gpu_helps": False, "bucket": "<1x"},
+    # 4 MB tensor at ~2 TB/s HBM is ~2 microseconds of memory work.
+    # Kernel launch alone is 5-20 us. The CPU does this in <1 ms with
+    # warm caches and no kernel-launch tax; the GPU is bottlenecked by
+    # launch overhead at this size. Most realistic: 1-2x (GPU might
+    # barely win or barely lose). Either way, not a meaningful
+    # speedup; the bucketed answer is 1-2x.
+    "elementwise_relu": {"gpu_helps": True, "bucket": "1-2x"},
+}
+
+VALID_BUCKETS = {"<1x", "1-2x", "2-10x", "10-100x", ">100x"}
+
+
+def grade() -> int:
+    answers = getattr(starter, "ANSWERS", None)
+    if not isinstance(answers, dict):
+        print("FAIL: ANSWERS dict missing from starter.py")
+        return 1
+
+    failures: list[str] = []
+    for name, expected in EXPECTED.items():
+        a = answers.get(name)
+        if not isinstance(a, dict):
+            failures.append(f"  {name}: entry missing or not a dict")
+            continue
+        gh = a.get("gpu_helps")
+        bk = a.get("expected_speedup_bucket")
+        if gh is ... or bk is ... or gh is None or bk is None:
+            failures.append(f"  {name}: not filled in (still ... )")
+            continue
+        if not isinstance(gh, bool):
+            failures.append(f"  {name}: gpu_helps must be bool, got {type(gh).__name__}")
+            continue
+        if bk not in VALID_BUCKETS:
+            failures.append(
+                f"  {name}: expected_speedup_bucket must be one of {sorted(VALID_BUCKETS)}, got {bk!r}"
+            )
+            continue
+        if gh != expected["gpu_helps"]:
+            failures.append(
+                f"  {name}: gpu_helps={gh} but expected {expected['gpu_helps']}"
+            )
+            continue
+        if bk != expected["bucket"]:
+            failures.append(
+                f"  {name}: expected_speedup_bucket={bk!r} but expected {expected['bucket']!r}"
+            )
+            continue
+
+    if failures:
+        print("FAIL:")
+        for f in failures:
+            print(f)
+        return 1
+
+    print("PASS — all three workloads bucketed correctly.")
+    print("(Reasoning prose is not autograded; compare against the solutions repo.)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(grade())

modules/mod-001-gpu-fundamentals/exercises/exercise-01-cpu-gpu-comparison/starter.py

@@ -0,0 +1,43 @@
+"""Exercise 1 starter — fill in your answers for the three workloads.
+
+Each entry of `ANSWERS` is a dict with three keys:
+
+    gpu_helps: bool
+        True if you expect a modern data-center GPU (A100/H100 class) to
+        outperform a comparable modern server CPU on this workload.
+
+    expected_speedup_bucket: str
+        One of: "<1x", "1-2x", "2-10x", "10-100x", ">100x".
+        ">100x" means the GPU is more than 100 times faster.
+        "<1x" means the CPU is faster.
+
+    reasoning: str
+        3-6 sentences of justification. The autograder does not grade
+        the prose; the solutions repo has the worked answer.
+
+Replace each `...` with your answer. Then run:
+
+    python check.py
+"""
+
+ANSWERS = {
+    "dense_matmul": {
+        # Multiply two FP32 (8192, 8192) matrices, all data already on device.
+        "gpu_helps": ...,
+        "expected_speedup_bucket": ...,
+        "reasoning": ...,
+    },
+    "json_parse": {
+        # Parse a 1 GB deeply-nested JSON file.
+        "gpu_helps": ...,
+        "expected_speedup_bucket": ...,
+        "reasoning": ...,
+    },
+    "elementwise_relu": {
+        # y = max(0, x) on a single FP32 (1024, 1024) tensor,
+        # data already on the appropriate device.
+        "gpu_helps": ...,
+        "expected_speedup_bucket": ...,
+        "reasoning": ...,
+    },
+}