Project 1 Planning + Build Checklist

Specs first — evidence always

Author

Dr. Anna Rosen

Published

February 2, 2026

This worksheet is a guide for all of Project 1. You are not required to complete every section today.

The goal is to help you implement a published model as verified code without wandering: specs \(\to\) plan \(\to\) validate \(\to\) tests \(\to\) figures.

Bring this sheet at the end of class for a quick checkoff.

Group info

Names:

Section / group # (if applicable):

Roles (circle): Spec navigator / Scribe / Skeptic / Timekeeper

1) What you are building (in 4 sentences)

Write a short description of what this repo does. This becomes the first draft of your README.md overview.

2) Specs (paper \(\to\) code map)

A spec is the authoritative description of what your code must do. If you can’t point to a line in a spec, you’re guessing.

Spec snapshot (quick)

  • Mass range:
  • Metallicity range:
  • Log base used in the paper ($\log_{10}$ or $\ln$):

Where do the model pieces live?

Write pointers, not full transcription.

  • Luminosity: equation # and table #:
  • Radius: equation # and table #:
  • Any piecewise mass regimes you notice (boundary values):

Column 1 mindset (solar \(Z\))

In one sentence, what does “column 1 for solar \(Z\)” mean for your first implementation pass?

3) Repo plan (single source of truth)

Write a 1-line responsibility for each file you will have in your repo.

  • run.py:
  • constants.py:
  • zams.py:
  • star.py:
  • stellar_population.py:
  • astro_plot.py:
  • tests/:

4) Star contract (plain language first)

For the Star class: write “input rules”, “attribute promises”, and “what could go wrong”.

Star(mass, Z=0.02)

Input rules (types, units, valid ranges):

Attribute promises (what attributes exist, with units):

What could go wrong (at least 3):

List the derived quantities you will compute (check units):

  • \(T_\mathrm{eff}\) (K):
  • \(t_\mathrm{MS}\) (Gyr):
  • \(t_\mathrm{KH}\) (Myr):

5) Pseudocode for Star.__init__ (solar \(Z\) first)

Write pseudocode for a clean first implementation. Keep it high level.

6) zams.py plan (solar \(Z\) first, then full \(Z\))

You do not need to finish the full transcription today. You do need a plan that prevents a tangled implementation.

Pass 2: full metallicity dependence (later)

Write one sentence describing how you will upgrade from column 1 to full \(Z\) dependence (what changes, what stays invariant).

7) Validation plan (python run.py validate)

Write three checks you will implement before making any plots.

  1. Anchor check (example: 1 \(M_\odot\)): expected value and tolerance:

  2. Trend check (example: \(L\) increases with \(M\) over the valid range):

  3. One more check (example: low \(Z\) has higher \(L\) at fixed \(M\)):

8) Test plan (python run.py test)

List tests you will write (name + what it verifies). You can add more later.

  1. test_... verifies:
  2. test_... verifies:
  3. test_... verifies:
  4. test_... verifies:
  5. test_... verifies:
  6. test_... verifies:

(By the end of the project you need at least 8 tests.)

9) Write a trace (debug your understanding)

Pick one input (example: \(M = 1.0\), \(Z = 0.02\)). Write down intermediate values in a way that would let you catch a log-base, unit, or transcription error.

Good Star trace steps:

  • Start with \(M\), \(Z\)
  • Compute \(L\) and \(R\) (solar units)
  • Compute \(T_\mathrm{eff}\) (K)
  • Compute \(t_\mathrm{MS}\) (Gyr)
  • Compute \(t_\mathrm{KH}\) (Myr)

If you can’t trace it, you can’t validate it.

10) Figures plan (so plotting doesn’t become a last-minute crisis)

List the required figures you need and which function/module produces them. Keep it short.

  • Figure 1:
  • Figure 2:
  • Figure 3:
  • Figure 4:

For each figure, write one “what would look obviously wrong?” sentence.

11) README + provenance (reproducibility is graded)

Draft the 5–15 lines you will eventually put in your README.md provenance section:

  • Which equation numbers did you implement?
  • Which tables did you transcribe coefficients from?
  • What interpretation choices did you make (log base, units/normalization, piecewise regimes)?
  • What is one validation check that convinced you your extraction was correct?

12) Constants (no mystery numbers)

Where will you document your constants table (README.md or CONSTANTS.md)?

List the constants you know you’ll need for Star derived quantities:

  • MSUN:
  • RSUN:
  • LSUN:
  • TSUN:
  • G:
  • SIGMA_SB:
  • YEAR / MYR / GYR:

For one constant, write the source you plan to cite:

Instructor checkoff (end of class)

Checkboxes:

  • Star contract exists (inputs/units + failure modes)
  • Star pseudocode exists (includes \(T_\mathrm{eff}\), \(t_\mathrm{MS}\), \(t_\mathrm{KH}\))
  • zams.py plan exists (equation/table pointers + single source of truth for coefficients)
  • (Optional today) 3 validation checks are written (anchor + trend + one more)
  • (Optional today) 2 “first tests” are named and described

Instructor initials: