Chapter 36 — Teaching Notes

One-line purpose. Give students the ability to walk into a large, unfamiliar scientific Fortran code and be productive — by teaching its architecture (the five roles, the layered source tree), its build systems, and the navigation discipline (map + grep + tags, follow the data) — and to reorganize their own solver into a real package. This is the pivot from "learning the language" to "using it to build real things."

Key ideas to emphasize

  • The five roles are the whole framework. Driver / solver / physics / I/O / utility. Drill them until a student can classify any module on sight by asking "what job does this do for the program?" Everything else (layout, dependency direction, navigation) follows from the roles.
  • Navigate, don't read. The threshold idea of the chapter. Students instinctively try to read a big code; break that instinct explicitly. The mantra: hold the map, query the rest. The 0.05%/1.6% figures (Case Study 1, Exercise 36.23) are there to make it visceral.
  • Where state lives determines readability. Argument-passed state is local and knowable; module-variable global state has hidden inputs and outputs. example-02 and Case Study 1 are the same lesson twice — the "same call, different answer" moment is the one to land.
  • The source tree IS the dependency graph. Tie the directory layout straight back to Chapter 8's "depend downward" rule. Utilities at the bottom, driver at the top; compile order falls out of it.
  • Build configuration is a scientific artifact. Not plumbing — reproducibility. Same source, two builds, possibly two numbers. This sets up Chapter 37.

Misconceptions to preempt

  • "To understand a codebase you must read it." (No — you navigate its architecture and read <2%.)
  • "Bigger code = more Fortran to learn." (No — the students already know enough Fortran; the gap is architecture and tooling.)
  • "Module variables are just convenient globals." (They are globals with hidden inputs/outputs — the readability cost is the point, connect to Chapter 13's implicit-save trap.)
  • "fpm/CMake/Make are interchangeable." (Different tools for different scales; fpm for new Fortran, CMake for big multi-language, Make for inherited codes.)
  • "Real production codes are mysterious/special." (They are large but recognizably laid out — the honesty caveat: we make structural claims about WRF/CESM/Quantum ESPRESSO, never invented internals.)

A live demonstration (10 minutes) — the best part of the class

Clone a real open-source Fortran code live (WRF, CESM, or Quantum ESPRESSO — pick one and have it pre-cloned as backup; repos are large). Then, projected, run the navigation sequence on it cold: grep -rin "^\s*program " to find the entry point, grep -rin "^\s*module " | wc -l to count modules, then pick one physical quantity and grep for where it is assigned. Narrate that you have never read this code and are finding your way in real time. Students watching an instructor be productive in a million-line code they have never seen is worth more than any slide. (Fallback: run it on the packaged heat solver if network/repo size is a problem.)

Class-time budget (~50 min)

  • 8 min: the problem — a 100k-line code on day one; why reading it is hopeless (§36.1 opening).
  • 12 min: the source tree + the five roles, with the miniature example-01 (§36.1–§36.2).
  • 8 min: build systems tour — Make vs fpm, and "build configuration" as reproducibility (§36.3).
  • 12 min: navigation — the live demo above (§36.4).
  • 8 min: where state lives — example-02, the "same call, different answer" (§36.5), then point to the Project Checkpoint.
  • 2 min: launch the reorganization checkpoint as the take-home.

Prerequisites to review

  • Chapter 8 (modules, hierarchy, compile order, .mod, "Cannot open module file") — this chapter is Chapter 8 at scale; a 5-minute refresher pays off.
  • Chapter 13 (guarded allocate, validation, implicit save) — needed for §36.5 and Exercise 36.25.
  • Chapter 16 (fpm) — the build system used in the Checkpoint.
  • Chapter 24 (the stencil) — the physics the Checkpoint reuses unchanged.

Connections

  • Forward to Chapter 37: navigation and packaging set up testing, documentation, CI, reproducibility — the test/ directory created here is where the next chapter starts.
  • Forward to Chapter 38: the packaged, navigable solver is what the capstone presents "as a paper."
  • Back to Part IV (Ch. 17–18): reading large code and reading old code are the same skill in different keys; the "Modern vs Legacy" callout in §36.4 bridges them (COMMON as the F77 dependency graph).