Project 2 Planning + Build Checklist

Pipeline first — validate always

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

The goal is to help you build a working N-body pipeline without wandering: units \(\to\) data structures \(\to\) forces \(\to\) integrator \(\to\) diagnostics \(\to\) validate.

Bring this sheet to the Monday Feb 17 lab for a quick checkoff.

Group info

Names:

Section / group # (if applicable):

Roles (circle): Pipeline lead / Physics checker / 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) Units and constants (before anything else)

Getting units wrong is the #1 failure mode in N-body code. Commit to a unit system before writing a single line.

Your unit system

Fill in:

• Mass unit:
• Length unit:
• Time unit:

Compute \(G\) in your units

Show the calculation. If you use \(M_\odot\), AU, yr, you should get \(G = 4\pi^2\) AU\(^3\) \(M_\odot^{-1}\) yr\(^{-2}\).

\(G\) = ________

Why is \(G = 4\pi^2\) convenient?

In one sentence, explain what makes this choice natural for solar system dynamics:

Constants you will need

Constant	Symbol	Value (in your units)
Gravitational constant	G
Solar mass	M_SUN
Earth mass	M_EARTH
Jupiter mass	M_JUPITER
Earth orbital radius
Jupiter orbital radius

---

3) Data structure contract

Write the NumPy array shapes you will use. This is a contract — your entire codebase must be consistent.

Array	Shape	Row \(i\) represents	Column \(j\) represents
positions
velocities
accelerations
masses

---

4) Force calculation plan

The equation

Write the gravitational acceleration formula for particle \(i\) (from the project spec):

\[\vec{a}_i = \]

Three bugs to avoid

For each, write one sentence explaining the bug and how to prevent it:

1. Self-force bug (\(i = j\)):

2. Double-counting bug (in potential energy):

3. Sign error bug (force direction):

What is softening (\(\epsilon\))?

In one sentence, explain why we add \(\epsilon\) and what happens if it is too large or too small:

---

5) Hand trace: \(N = 2\) (Sun + Earth)

Compute by hand. If you can’t trace it, you can’t debug it.

Setup

• Sun at position \((0, 0, 0)\) AU, mass \(= 1\,M_\odot\)
• Earth at position \((1, 0, 0)\) AU, mass \(\approx 3 \times 10^{-6}\,M_\odot\)
• \(G = 4\pi^2\), \(\epsilon = 0\) for this trace

Acceleration of Earth

Direction vector (Sun \(-\) Earth): \(\vec{r}_\text{Sun} - \vec{r}_\text{Earth}\) = ________

Distance: \(|\vec{r}_{ij}|\) = ________

Acceleration magnitude: \(|\vec{a}_\text{Earth}| = G M_\odot / r^2\) = ________ AU/yr\(^2\)

Acceleration vector: \(\vec{a}_\text{Earth}\) = ________ (should point toward the Sun)

Circular orbit velocity

For a circular orbit: \(v_c = \sqrt{GM/r}\) = ________ AU/yr

So Earth starts at \((1, 0, 0)\) with velocity \((0,\; v_c,\; 0)\) = \((0,\) ____\(, 0)\) AU/yr.

Sanity check

Expected orbital period: \(T = 2\pi r / v_c\) = ________ yr

Does this match Earth’s actual period? ________

---

6) Euler integrator plan

The update rule

Euler’s method: \(\vec{y}_{n+1} = \vec{y}_n + \Delta t \cdot \vec{f}(t_n, \vec{y}_n)\)

For N-body, this means (write pseudocode):

1. Compute accelerations from current positions: a = ...
2. Update velocities: v_new = ...
3. Update positions: r_new = ...
4. Advance time: t = ...

Key design question

Will your integrator update positions and velocities simultaneously (using old values for both) or sequentially (using new velocities to update positions)?

Answer:

Why does this choice matter for Leapfrog later?

---

7) Energy diagnostics plan

The formulas

Fill in the energy formulas you will implement:

Kinetic energy: \(E_K\) = ________

Potential energy: \(W\) = ________ (Why \(i < j\), not \(i \neq j\)?)

Total energy: \(E_\text{tot}\) = ________

Virial ratio: \(Q\) = ________

Hand-compute \(E_\text{tot}\) for \(N = 2\) at \(t = 0\)

Using your Sun-Earth initial conditions from Section 5:

\(E_K\) = ________ (include both Sun and Earth contributions)

\(W\) = ________

\(E_\text{tot}\) = ________

Is the system bound (\(E_\text{tot} < 0\))? ________

---

8) \(N = 2\) test case: what to expect

Initial conditions table

Particle	\(x\) (AU)	\(y\) (AU)	\(z\) (AU)	\(v_x\) (AU/yr)	\(v_y\) (AU/yr)	\(v_z\) (AU/yr)	Mass (\(M_\odot\))
Sun
Earth

Simulation parameters

• \(\Delta t\) = ________ yr
• \(t_\text{end}\) = ________ yr (how many orbital periods?)
• \(\epsilon\) = ________ AU

What correct output looks like

Describe what you expect to see for Euler integration (2-3 sentences):

What obviously wrong output looks like

List three things that would indicate a bug:

---

9) Validation plan

Write three checks you will run before making any production plots.

1. Anchor check (e.g., orbital period matches 1 yr for \(N = 2\)):

2. Trend check (e.g., Euler energy grows monotonically):

3. Diagnostic check (e.g., \(E_\text{tot}(t=0)\) matches hand calculation from Section 7):

---

10) Repo structure

Write a 1-line responsibility for each file you plan to have:

• run.py or main.py:
• nbody.py or simulator.py:
• integrators.py:
• initial_conditions.py:
• diagnostics.py or energy.py:
• plotting.py:
• tests/:

---

11) Phases 2–4 roadmap (lightweight)

You do not need to plan these in detail yet. Write one sentence for each.

Phase 2: Upgrade the integrator

Which two integrators will you add?

How will they share the same interface as Euler? (one sentence):

Phase 3: Plummer sphere initial conditions

What is a Plummer sphere? (one sentence):

What does “virial equilibrium” mean for initial velocities? (one sentence):

Phase 4: Vectorize and scale up

What is the main loop you will replace with NumPy broadcasting? (one sentence):

---

12) Figures plan

List the required figures from the project spec. For each, note which module produces it.

Figure	Description	Module/function
Phase 2 key figure
\(N = 3\) verification
Plummer IC validation
Cluster energy diagnostics
Cluster evolution snapshots
Performance comparison

For each figure, write one “what would look obviously wrong?” note:

---

Instructor checkoff (Mon Feb 17)

Checkboxes:

• Units and constants defined (\(G = 4\pi^2\) in AU, \(M_\odot\), yr)
• Data structure contract exists (array shapes for positions, velocities, masses)
• Hand trace completed (acceleration, circular velocity, period = 1 yr)
• Euler pseudocode written (update rule for positions and velocities)
• Energy formulas written (\(E_K\), \(W\), \(E_\text{tot}\)) with \(E_\text{tot}\) hand-computed for \(N = 2\)
• \(N = 2\) initial conditions table filled in
• 3 validation checks planned (anchor + trend + diagnostic)
• Repo structure planned (file responsibilities)

(Optional today, required by Check-in 1 on Wed Feb 18):

• Euler integrator running on \(N = 2\) Sun-Earth
• At least one energy plot produced
• Git repo with \(\geq 3\) meaningful commits