A showcase for rakupp --target=js

An orbit is six numbers

Two for the ellipse — how big, how squashed. Three angles to hang that ellipse in space. One to say where the body was at a known moment. That is the entire state of a planet, for ever, and everything below is what you can do with it.

Every number on this page is computed in your browser by Raku code. The engine is lib/Orbit.rakumod; the same file runs a command-line program in a terminal and this book in a browser, because rakupp --target=js turns it into JavaScript. Move a slider and Raku runs.

ElementWhat it sets
asemi-major axis — the size, and by Kepler's third law the period too
eeccentricity — 0 is a circle, 0.9 is a comet, 1 is a parabola and never comes back
iinclination — how far the orbital plane is tipped from the ecliptic
Ωlongitude of the ascending node — where it crosses the ecliptic going north
ωargument of perihelion — where the closest point sits within the orbit
Mmean anomaly — where the body would be if it moved at a constant rate

Six sliders, one orbitengine: orbit-path, kepler, vis-viva

distance now
–
au from the Sun
speed now
–
km/s, from vis-viva
period
–
perihelion
–
aphelion
–
true anomaly
–

Raise the tilt slider to see the orbit edge-on, and the inclination stops being a number and becomes a thing. Push e past 0.8 and watch the speed readouts separate: a body on a long ellipse spends almost all its time crawling near aphelion and crosses perihelion in a hurry. That is Kepler's second law, and it is why a Mars window is a window.

Chapter 2

The equation nobody can solve

Knowing the orbit is not knowing the position. Getting from "where it would be if it moved evenly" to "where it actually is" needs one equation, and that equation has no closed-form solution. Kepler said so himself in 1609, and four centuries have agreed.

M = E − e sin E M mean anomaly the angle a uniformly-moving body would have swept E eccentric anomaly an angle measured at the CENTRE of the ellipse ν true anomaly the angle actually seen from the Sun, at the focus

You know M, because it grows linearly with time. You want E, because from E the position falls out immediately. And E is not an elementary function of M — no arrangement of roots and logs and trigonometry will give it to you.

So we guess and correct. Newton's method: at a guess E, the error is f(E) = E − e sin E − M, the slope is 1 − e cos E, and the next guess is the current one minus their ratio. Started at M it converges quadratically: each step roughly doubles the number of correct digits, so five or six steps exhaust a double-precision float even for a comet.

Newton–Raphson, one step at a timeengine: kepler

E
–
eccentric anomaly
ν
–
true anomaly
steps
–
to machine precision
residual
–
|E − e sin E − M|

Each bar is one iteration and the scale is logarithmic, so the error dropping 1e−1, 1e−3, 1e−7, 1e−15 is a straight staircase getting steeper. That accelerating collapse is quadratic convergence. Push e toward 0.95 and it takes a step or two longer, which is why comet people use a better starting guess.

And the three anomalies across a whole orbit. At e = 0 they are the same line. Raise e and ν runs far ahead of M near perihelion and lags behind it near aphelion — the body really is racing and dawdling, and the gap between those curves is the equation of the centre.

Chapter 3

The whole system, any date

Eight planets, six numbers each, and one date. The elements themselves drift — the ellipses slowly turn and tilt — so each is a value at the year 2000 plus a rate per century.

That linear model is Standish's, published by JPL for exactly this purpose, and it is good to a fraction of an arcminute from 1800 to 2050. Beyond that it decays gracefully rather than failing: the planets stay in roughly the right places for a few centuries either side, which is enough to watch the pattern.

An orreryengine: system

Scrub the date. The inner planets bolt round while Neptune barely stirs — that is Kepler's third law made visible: period goes as a3/2, so Neptune's year is 165 of ours. Switch to the outer planets and raise the tilt to see how far Pluto‑like inclinations would stand out; the eight major planets are all within a couple of degrees of the same plane, which is a fact about how the solar system formed.

Chapter 4

Seen from here

Everything so far has been heliocentric. From the Earth, which is itself moving, the same motion looks stranger: planets loop backwards, brighten and fade, and come close on a rhythm of their own.

Subtract the Earth's position from the planet's and you get the vector we actually see along. Its length is the distance — which for Mars swings between 0.37 and 2.67 astronomical units, a factor of seven, and is why some Mars oppositions are famous and others are not.

1/S = |1/T₁ − 1/T₂| the synodic period: how long between alignments Earth–Mars 779.9 days Earth–Jupiter 398.9 days Earth–Venus 583.9 days Earth–Saturn 378.1 days

Distance from the Earth, and the events on itengine: geocentric, oppositions

The dots are oppositions — or, for Mercury and Venus, conjunctions. Mars is the interesting one: its opposition distance itself cycles, over about fifteen years, because Mars's orbit is eccentric enough that it matters where in its year the meeting happens. The 2003 and 2018 oppositions were the close ones; 2027 is not.

Chapter 5

Getting there

Leaving Earth for Mars is not a matter of pointing at Mars. You are already moving at 30 km/s; so is Mars, more slowly, somewhere else. The cheapest thing to do is fall into a new ellipse that touches both orbits, and arrange to arrive where Mars will be.

That is a Hohmann transfer: two burns, one at each end. Raise your speed at Earth's distance until your new orbit reaches Mars's distance at its far side; coast for half an ellipse; then raise it again on arrival to stop falling back. It is provably the cheapest two-burn transfer between circular orbits.

v = √( GM (2/r − 1/a) ) the vis-viva equation: energy, rearranged

Two burns and a waitengine: hohmann, synodic

first burn
–
km/s, leaving
second burn
–
km/s, arriving
total Δv
–
km/s
time of flight
–
launch window
–
days between chances
target must lead by
–
at the moment you leave

Slide the destination outwards. The Δv climbs and then flattens — going to Neptune costs barely more than going to Jupiter, because most of the price is escaping the Sun's grip near the Earth, and past a point you are paying for patience instead of fuel. The time of flight does not flatten at all: Neptune is a thirty-year coast.

Chapter 6

What this does not do

Every model is a claim about what can be ignored. This one ignores that the planets pull on each other, that orbits are not coplanar, and that you rarely get to leave on the perfect day.

The planets are treated as independent. Each one follows its own ellipse around the Sun as though the others did not exist, with the slow drift of the elements standing in for their combined effect. That is why the outer-planet periods here differ from the published ones by up to 0.06%: Jupiter and Saturn pull on each other hard enough to matter, and a linear element fit cannot express it. A model that does is a numerical integration of all eight bodies at once, and it costs a great deal more than 271 lines.

Transfers assume circular, coplanar orbits. Real trajectory design solves Lambert's problem — given a departure point, an arrival point and a flight time, find the orbit connecting them — for every pair of dates in a window, and plots the resulting Δv as contours. The result is a porkchop plot, and its shape is why a Mars launch window is about three weeks wide rather than a single instant. Mars's 1.85° inclination alone adds a few hundred m/s that the numbers in chapter 5 do not charge you for.

And the answer is only as good as its check. orbits.raku --check runs 42 of them against reference/known.tsv: the eight sidereal periods, four synodic periods, ten opposition dates from the almanacs, the textbook Hohmann figures for Earth to Mars, escape and low-orbit speeds, Kepler's equation solved to better than 1e−11 at seven eccentricities, and each planet's radius agreeing with its own coordinates. The opposition dates are the sharpest of those, because being a day out is visible:

Mars 2020-10-13 2022-12-08 2025-01-16 2027-02-19 Jupiter 2022-09-26 2023-11-03 2024-12-07 Saturn 2022-08-14 2023-08-27 2025-09-21

All ten land on the almanac date. That does not make the model true — it makes it accurate enough for what it claims, which is the most any model gets.

The engine is showcase/orbits/lib/Orbit.rakumod in the rakupp repository. orbits.raku is the terminal version of this book, with an orrery drawn in characters; tools/build.raku bundles the engine with web/api.raku, transpiles it with rakupp --target=js --standalone, and inlines the result here. The page you are reading is one file with no dependencies.