Update course index, dependencies, and Lecture 3 test paths

.gitignore

@@ -18,3 +18,8 @@ esm2_diffusion_outputs/
 # Local secrets must never be committed.
 .env
 .env.*
+
+# Lecture 2 downloads and newly generated results.
+data/
+flow_matching_outputs/
+!lecture_2/flow_unet_mnist.pt

README.md

@@ -10,6 +10,8 @@ tags:
   - esm2
   - protein-generation
   - guidance
+  - mnist
+  - image-generation
 ---
 
 # CIS 6270 Course Code
@@ -26,19 +28,22 @@ and implementation notes; additional directories will accompany later lectures.
 
 ## Lecture index
 
-| Lectures | Topics | Code and documentation |
+| Lecture | Topics | Code and documentation |
 | --- | --- | --- |
-| 2 and 3 | Continuous generative models, flow matching, diffusion, and guidance | [Guide](lectures_02_03/README.md) · [Flow matching](lectures_02_03/esm2_flow_guidance.py) · [Diffusion](lectures_02_03/esm2_diffusion_guidance.py) |
+| 2 | Unconditional MNIST image generation with flow matching and a simple U-Net | [Guide](lecture_2/README.md) · [Script](lecture_2/flow_matching_unet_lecture.py) · [Saved checkpoint](https://huggingface.co/ChatterjeeLab/CIS6270/resolve/main/lecture_2/flow_unet_mnist.pt?download=true) |
+| 3 | Flow matching, diffusion, and guidance for ESM-2 residue embeddings | [Guide](lecture_3/README.md) · [Flow matching](lecture_3/esm2_flow_guidance.py) · [Diffusion](lecture_3/esm2_diffusion_guidance.py) |
 
 ## Installation
 
 Use Python 3.11, or another compatible Python version at least 3.10, in a new
-virtual environment. The current examples were tested with PyTorch 2.9.1 and
-Transformers 4.57.6, as specified in `requirements.txt`.
+virtual environment. The shared `requirements.txt` pins PyTorch 2.9.1,
+TorchVision 0.24.1, and Transformers 4.57.6. Lecture 2 uses PyTorch and
+TorchVision; Lecture 3 also uses Transformers.
 
 ```bash
 git clone https://huggingface.co/ChatterjeeLab/CIS6270
 cd CIS6270
+git lfs pull
 
 python3 -m venv .venv
 source .venv/bin/activate
@@ -49,13 +54,41 @@ python -m pip install -r requirements.txt
 On Windows PowerShell, create the environment with `python -m venv .venv`
 and activate it with `.venv\Scripts\Activate.ps1`.
 
-## Run the Lectures 2 and 3 examples
+The saved checkpoint uses Git LFS. If Git LFS is unavailable, download
+[flow_unet_mnist.pt](https://huggingface.co/ChatterjeeLab/CIS6270/resolve/main/lecture_2/flow_unet_mnist.pt?download=true)
+directly and place it in `lecture_2/`. Training from scratch does not require
+the saved checkpoint.
+
+## Lecture 2: MNIST flow matching
+
+Lecture 2 contains one self-contained, commented script. It downloads MNIST,
+loads batches of normalized images, defines a small U-Net velocity network,
+trains it with conditional flow matching, and generates images from Gaussian
+noise using Euler integration.
 
 From the repository root:
 
 ```bash
-python lectures_02_03/esm2_flow_guidance.py --epochs 200 --samples 8
-python lectures_02_03/esm2_diffusion_guidance.py --epochs 200 --samples 8
+python lecture_2/flow_matching_unet_lecture.py
+```
+
+The default run trains for 20 epochs and writes `samples.png`, `trajectory.png`,
+and a new `flow_unet_mnist.pt` to `flow_matching_outputs/`. The script selects
+CUDA, Apple MPS, or CPU according to availability. Its numbered `# %%` sections
+match the lecture walkthrough.
+
+The bundled [checkpoint](lecture_2/flow_unet_mnist.pt) has **5 completed epochs**
+on all 60,000 MNIST training images. The [Lecture 2 guide](lecture_2/README.md)
+includes a short example for loading it and generating images without training,
+along with selected generated digits and their noise-to-image trajectories.
+
+## Lecture 3: Flow and diffusion guidance
+
+From the repository root:
+
+```bash
+python lecture_3/esm2_flow_guidance.py --epochs 200 --samples 8
+python lecture_3/esm2_diffusion_guidance.py --epochs 200 --samples 8
 ```
 
 Both scripts train on ESM-2 residue embeddings and compare classifier-free
@@ -65,26 +98,18 @@ constrained decoder to compare the flow and diffusion implementations.
 
 The first run downloads the public ESM-2 checkpoint. Each script then writes
 generated sequences and model parameters to its own output directory.
-The [lecture guide](lectures_02_03/README.md) describes the data format, training
+The [lecture guide](lecture_3/README.md) describes the data format, training
 and sampling settings, property calculations, normalization, and residue-count
 constraint, with commands for using a custom dataset.
 
 ## Repository organization
 
-```text
-CIS6270/
-├── README.md
-├── requirements.txt
-├── LICENSE
-├── lectures_02_03/
-│   ├── README.md
-│   ├── esm2_flow_guidance.py
-│   ├── esm2_diffusion_guidance.py
-│   ├── esm2_example.csv
-│   └── GUIDANCE_NOTES.md
-└── tests/
-    └── test_examples.py
-```
+| Location | Contents |
+| --- | --- |
+| Repository root | Course index, installation requirements, and license |
+| [`lecture_2/`](https://huggingface.co/ChatterjeeLab/CIS6270/tree/main/lecture_2) | One MNIST flow-matching script, guide, trained checkpoint, and selected example images |
+| [`lecture_3/`](https://huggingface.co/ChatterjeeLab/CIS6270/tree/main/lecture_3) | ESM-2 flow and diffusion guidance scripts, sequence data, guide, and mathematical notes |
+| [`tests/`](https://huggingface.co/ChatterjeeLab/CIS6270/tree/main/tests) | Offline checks for the Lecture 3 examples |
 
 Installation instructions and the lecture index are maintained at the
 repository root. Lecture-specific commands, mathematical explanations, and
@@ -96,12 +121,13 @@ references accompany the corresponding code.
 python -m unittest discover -s tests -v
 ```
 
-The current unit tests cover property annotations, scalarization weights, reward
+The Lecture 3 unit tests cover property annotations, scalarization weights, reward
 gradients, DDPM schedule indexing, and constrained decoding.
 
 ## License
 
 The repository code is distributed under the
 [MIT License](https://huggingface.co/ChatterjeeLab/CIS6270/blob/main/LICENSE).
-Pretrained model weights are downloaded from their original repositories
-under the corresponding distribution terms.
+The Lecture 2 U-Net checkpoint is included under the same license. The Lecture 3
+ESM-2 weights are downloaded from their original repository under the
+corresponding distribution terms.

requirements.txt

@@ -1,3 +1,4 @@
 # Tested teaching environment: Python 3.11.
 torch==2.9.1
+torchvision==0.24.1
 transformers==4.57.6

tests/test_examples.py

@@ -1,4 +1,4 @@
-"""Offline unit checks for the Lectures 2 and 3 examples."""
+"""Offline unit checks for the Lecture 3 examples."""
 import csv
 import itertools
 from pathlib import Path
@@ -9,7 +9,7 @@ import unittest
 import torch
 
 ROOT = Path(__file__).resolve().parents[1]
-sys.path.insert(0, str(ROOT / "lectures_02_03"))
+sys.path.insert(0, str(ROOT / "lecture_3"))
 import esm2_flow_guidance as flow
 import esm2_diffusion_guidance as diffusion
 
@@ -20,7 +20,7 @@ class GuidanceTests(unittest.TestCase):
         torch.set_num_threads(2)
 
     def test_example_annotations(self):
-        with (ROOT / "lectures_02_03" / "esm2_example.csv").open(newline="") as handle:
+        with (ROOT / "lecture_3" / "esm2_example.csv").open(newline="") as handle:
             rows = list(csv.DictReader(handle))
         self.assertEqual(len(rows), 64)
         self.assertEqual({len(row["sequence"]) for row in rows}, {24})