Cosmic Playground
  • Predict
  • Play
  • Explain

Instructor notes: Kepler’s Laws: Patterns of Planetary Motion

Public notes (v0.2 policy). Not linked from primary navigation.

Exhibit: /cosmic-playground/exhibits/keplers-laws/

Overview

Navigation

This guide is instructor-facing Student demo: /play/keplers-laws/
Main code: apps/demos/src/demos/keplers-laws/main.ts
UI markup: apps/demos/src/demos/keplers-laws/index.html
Model code (tested): packages/physics/src/keplersLawsModel.ts + packages/physics/src/twoBodyAnalytic.ts

Where to go next

  • Model + math + assumptions: model.md
  • In-class activities (MW quick + Friday lab + station version): activities.md
  • Assessment bank (clickers + short answer + exit ticket): assessment.md
  • Future enhancements (planning backlog): backlog.md

Why this demo exists

Why This Matters Kepler’s laws are one of the cleanest examples of “pattern → mechanism” in physics. Students can see the patterns (ellipses, equal areas, period–distance scaling), then flip to Newton mode and watch how a single inverse‑square force implies those patterns.

Learning goals (ASTR 201)

Students should be able to:

  • Interpret the orbit shape parameters (semi-major axis $a$ and eccentricity $e$) and connect them to perihelion/aphelion distances.
  • Explain (in words) Kepler’s 2nd law as a statement about swept area per unit time and connect it to “faster near perihelion.”
  • Use Kepler’s 3rd law ($P^2 \propto a^3$ for fixed central mass) to predict how orbital period changes with $a$.
  • In Newton mode, predict how period changes with central mass $M$ and verify using readouts.
  • Use units consistently (AU, yr, $M_{\odot}$; and speed in km/s in the readout/export).

10–15 minute live-teach script (projector)

  1. Start with Earth-like parameters. Ask: “What’s the ‘shape story’ here?” Turn on foci + apsides and point out “Sun at a focus.”

  2. Turn on equal-area slices. Ask: “Where should the planet move fastest?” Use the time slider (or Animate) to compare speed near perihelion vs aphelion.

  3. Increase eccentricity $e$. Ask: “What changed: only the shape, or also the timing?” Connect to the equal-area slices: same area per equal time, different arc length.

  4. Increase semi-major axis $a$ by a factor of ~2 and ask for a prediction: “What happens to $P$?” Reveal the period readout and connect to the $a^{3/2}$ scaling.

  5. Switch on Newton mode and vary the central mass $M$ (in $M_{\odot}$). Ask: “If the star is more massive, what happens to the period?” Use the period readout to support the sign of the effect.

Suggested connections to other demos

  • Seasons: “geometry of an orbit” and “what changes over a year” are different ideas; Kepler’s 2nd law is a useful contrast to the simplified seasons model.
  • Angular size: both are ratio stories; here the key ratios are $r/a$ and $v$ vs $r$.
  • Binary orbits (ASTR 201 extension): this demo is the single-body foundation; binaries add center-of-mass motion and two-body geometry.

Activities

Navigation

Links Student demo: /play/keplers-laws/
Main guide: index.md
Model deep dive: model.md

MW Quick Exploration (3–5 min, pairs)

TPS: Where is the planet fastest? Think (30 s): “At which point in an elliptical orbit is the planet moving fastest: perihelion or aphelion?”

Pair (60 s): Give a physical reason (not just “because the demo says so”).

Share (1–2 min): Use the demo:

  1. Turn on Apsides.
  2. Increase eccentricity (try a high‑$e$ preset).
  3. Use the time slider (or Animate) to compare speed near perihelion vs aphelion.

Debrief script: “Kepler 2 is really a timing law: equal areas in equal times. That forces higher speed at smaller $r$.”

MW Short Investigation (8–12 min, pairs/triads)

Investigation: Period scaling with semi-major axis Task: Use two different $a$ values (e.g., $a=1$ AU and $a=4$ AU) at the same star mass.

Prompt: “If $a$ increases by a factor of 4, by what factor should $P$ increase?”

Expected: $P \propto a^{3/2}$, so $P$ should increase by $4^{3/2}=8$.

Demo setup: Keep $M=1$ (default), change $a$, and read the period.

Friday Astro Lab (20–30+ min, groups of 3–4)

Astro Lab: Kepler’s laws → Newton’s law Deliverable: A short lab write-up (table + claim + reasoning).

Part A (Kepler): Choose an eccentric orbit (e.g., $e\sim0.6$). Turn on Equal areas and record:

  • A screenshot near perihelion (wedge shape + readouts)
  • A screenshot near aphelion (wedge shape + readouts)

Prompt: “How can the wedge area stay the same while the wedge shape changes?”

Part B (Newton): Switch to Newton Mode and enable the velocity vector overlay. Record at the same two points:

  • direction of the velocity vector (tangent to the path)

Claim prompt: “Newton’s inverse-square gravity produces Kepler’s laws because…”

ASTR 201 extension: Use vis-viva to predict the ratio $v_{\text{peri}}/v_{\text{aph}}$ from $r_{\min}$ and $r_{\max}$, then compare to the demo’s readouts.

Station version (for a rotation lab)

Station card: Kepler’s Laws (6–8 minutes) Controls: $a$, $e$, time (mean anomaly $M$, deg) (and in Newton mode: central mass $M$, $M_{\odot}$)
Overlays: foci, apsides, equal areas, vectors

Your station artifact (fill in):

  1. Observation: where is the planet fastest (perihelion or aphelion)?
  2. Kepler law: explain using “equal areas in equal times.”
  3. Geometry: identify perihelion and aphelion in the orbit.
  4. Scaling: if $a$ doubles (same $M$), what happens to $P$ (longer/shorter, and why)?
  5. Connection sentence: “This connects to another course idea because…”

Word bank + sanity checks Word bank:

  • Semi-major axis $a$ (AU): the orbit’s size scale.
  • Eccentricity $e$ (unitless): orbit shape (0 = circle; larger = more stretched).
  • Perihelion / aphelion: closest / farthest point from the star.
  • Kepler 2: equal areas in equal times (a timing law → speed changes).
  • Kepler 3: bigger orbits have longer periods (for the same central mass).

Key relationship (period scaling):

$$P \propto a^{3/2}$$

Sanity checks:

  • If $e=0$, speed should be constant around the orbit.
  • For an ellipse, the planet should move fastest at perihelion.
  • Increasing $a$ should increase the period $P$.

Assessment

Navigation

How to use this bank Each item includes a demo setup so you can reproduce the scenario live, plus distractors tied to common misconceptions.

Clicker questions

Clicker 1: Fastest at perihelion or aphelion? Prompt: In an elliptical orbit around a star, the planet’s speed is greatest at…

A. Perihelion
B. Aphelion
C. It’s the same everywhere
D. It depends only on the star’s mass, not position

Correct: A.

Reasoning: Kepler’s 2nd law (equal areas in equal times) forces higher speed at smaller $r$.

Demo setup: Use a high‑$e$ orbit, then use the time slider (or Animate) to compare the speed readout near perihelion vs aphelion.

Clicker 2: Kepler 3 scaling Prompt: If you increase the semi-major axis by a factor of 4 (same star mass), the period increases by a factor of…

A. 2
B. 4
C. 8
D. 16

Correct: C.

Reasoning: $P \propto a^{3/2}$, so $P$ scales as $4^{3/2}=8$.

Demo setup: Set $M=1$, compare $P$ at $a=1$ and $a=4$.

Clicker 3: Velocity vector direction Prompt: When the velocity vector overlay is enabled, the velocity vector points…

A. Toward the star
B. Away from the star
C. Tangent to the orbit (direction of motion)
D. In a fixed direction regardless of position

Correct: C.

Demo setup: Enable “Show velocity vector”, then move time around the orbit and note the vector is tangent to the path.

Short answer

Short answer 1: The ‘two pictures’ explanation Prompt (3–5 sentences): Explain how Newton’s inverse-square gravity connects to Kepler’s laws. Your answer must mention both (i) a force pointing toward the star and (ii) a change in orbital speed with distance.

Answer key (core idea): Gravity provides a central force toward the star, which implies conservation of angular momentum and a constant areal sweep rate (Kepler 2). That forces the planet to move faster when it is closer (perihelion) and slower when it is farther (aphelion). The same gravitational law also yields the period–distance scaling (Kepler 3).

Short answer 2: Units discipline Prompt: The demo reports orbital distance in AU and speed in km/s. Explain (in 1–2 sentences) what it would mean to “change units” without changing the physics.

Expected: Units are a measurement/labeling convention; the underlying relationship is unchanged and the numbers transform by fixed conversion factors.

Exit ticket (1 minute)

Exit ticket: One-sentence Kepler 2 Prompt: In one sentence, state Kepler’s 2nd law in your own words.

Expected: A line from the star to the planet sweeps out equal areas in equal times.

Model notes (deeper)

Navigation

Links Student demo: /play/keplers-laws/
Model code (tested): packages/physics/src/keplersLawsModel.ts + packages/physics/src/twoBodyAnalytic.ts
UI/visualization code: apps/demos/src/demos/keplers-laws/main.ts

What the demo is modeling (big picture)

This demo is a planar, two-body Keplerian-orbit model (planet mass negligible; no perturbations). It is designed to make these ideas concrete:

  • Orbit geometry (Kepler 1): ellipses with a focus at the star
  • Orbit timing (Kepler 2): equal areas in equal times → faster near perihelion
  • Period scaling (Kepler 3): $P^2 \propto a^3$ for fixed central mass
  • Newton’s mechanism: inverse-square gravity explains the Kepler patterns

Single source of truth (testable model) The Kepler orbit math lives in @cosmic/physics and is unit tested in packages/physics/src/*.test.ts.

Coordinate convention (important!)

The demo uses true anomaly $\theta$ measured in the orbital plane with $\theta=0$ at perihelion. For visualization, we choose a coordinate convention where perihelion is drawn to the right of the star:

$$x = r\cos\theta,\qquad y = r\sin\theta$$

This is purely a drawing convention. The physics is in $r(\theta)$ and in how $\theta$ evolves with time.

Kepler 1: Orbit geometry (ellipse with the star at a focus)

The key geometric quantity is the orbital radius (distance from the star to the planet):

$$r(\theta) = \frac{a(1-e^2)}{1+e\cos\theta}$$

Let’s unpack each piece:

  • $r$ is the star–planet distance (AU in the demo).
  • $a$ is the semi-major axis (AU).
  • $e$ is eccentricity (dimensionless; $0$ = circle).
  • $\theta$ is true anomaly (radians in the math; the UI reports angles in degrees).

Geometry sanity checks

  • If $e=0$, then $r(\theta)=a$ (a circle).
  • Perihelion ($\theta=0$): $r_{\min}=a(1-e)$.
  • Aphelion ($\theta=\pi$): $r_{\max}=a(1+e)$.

In the code:

  • TwoBodyAnalytic.orbitalRadius({ a, e, thetaRad }) (with $a$ and $r$ in AU)
  • KeplersLawsModel.stateAtMeanAnomalyRad(...) returns $r$ and $(x,y)$ in AU.

Kepler 2: Timing (equal areas in equal times)

Kepler’s 2nd law is most cleanly stated as:

$$\frac{dA}{dt}=\text{constant}$$

where $A$ is the area swept out by the radius vector from star to planet.

In practice, the demo implements the correct “non-uniform motion” using the standard anomaly relationships. The animation advances mean anomaly uniformly in time, then solves Kepler’s equation to recover $\theta$.

Mean anomaly $M$ and Kepler’s equation

Mean anomaly is linear in time:

$$M(t)=\frac{2\pi}{P}t$$

Kepler’s equation relates mean anomaly $M$ to eccentric anomaly $E$:

$$M = E - e\sin E$$

The demo solves this equation numerically (Newton’s method) to get $E$, then converts to true anomaly $\theta$.

In the code (shared model):

  • TwoBodyAnalytic.trueToMeanAnomalyRad({ thetaRad, e })
  • TwoBodyAnalytic.meanToTrueAnomalyRad({ meanAnomalyRad, e })

Timing sanity checks

  • For $e=0$ (circle), $\theta$ increases uniformly with time (constant speed).
  • For $e>0$, the motion is faster near perihelion and slower near aphelion.

Kepler 3: Period scaling (AU, years, solar masses)

For a Keplerian orbit around a central mass $M$:

$$P = 2\pi\sqrt{\frac{a^3}{GM}}$$

In the “solar unit” system (with $a$ in AU, $P$ in years, and $M$ in solar masses), this becomes:

$$P^2 = \frac{a^3}{M}$$

The demo uses this solar-units form for the period readout.

Newton mode: varying the central mass $M$

Newton mode lets students vary $M$ (in $M_{\odot}$) and see how the same orbit size $a$ produces a different period.

Vis-viva (speed along a Kepler orbit)

$$v = \sqrt{GM\left(\frac{2}{r}-\frac{1}{a}\right)}$$

In this instrument, the model state is computed in AU/yr and the speed is displayed (and exported) in km/s via a fixed unit conversion.

Vectors (Newton mode)

The demo can draw a velocity vector that is tangent to the path. (It does not currently draw a force/acceleration vector.)

What’s simplified / not modeled

Intentional simplifications

  • Planar orbit (no inclination).
  • Two-body Keplerian dynamics (no perturbations, no GR precession).
  • “Time” is a teaching scale: the slider advances mean anomaly uniformly (a time proxy), not a calendar ephemeris.
  • Vectors (when shown) are scaled for visibility (not drawn to physical scale).

Backlog

Navigation

How to use this backlog This is a planning guide. Prefer changes that increase correctness and reduce cognitive friction before adding new features.

Note This backlog tracks the migrated Cosmic Playground runtime version of the demo (Feb 2026). Legacy implementation notes are intentionally omitted here to avoid confusion.

PriorityImpactEffortCategoryNotesCode entrypoint
P0HighMediumMigrationDONE (2026-02-02): Migrate demo into the standard instrument shell (triad), keep contract markers, and use base-path-safe links.apps/demos/src/demos/keplers-laws/index.html
P0HighMediumExportsDONE (2026-02-02): Add v1 results export + live-region status messaging.apps/demos/src/demos/keplers-laws/main.ts
P0HighMediumPhysicsDONE (2026-02-02): Implement a unit-tested Kepler orbit model (AU/yr/$M_{\odot}$ teaching units; no “G=1”).packages/physics/src/keplersLawsModel.ts
P1MediumMediumPedagogyAdd an optional “prediction checkpoint” mode (pause prompts + guiding questions) aligned to common misconceptions.apps/demos/src/demos/keplers-laws/main.ts
P1MediumMediumPhysicsAdd a force/acceleration vector overlay (radial) to connect more directly to Newton’s law.apps/demos/src/demos/keplers-laws/main.ts + packages/physics/src/keplersLawsModel.ts
P2LowLowUXAdd a small preset picker (Earth/Mars/Jupiter) in the controls panel (in addition to Station Mode row sets).apps/demos/src/demos/keplers-laws/main.ts