Famulus Astronomica

astra/1 — a language for historical astronomical models and the geometrical reasoning about them

A historical astronomical model is a geometrical construction with a kinematic variable: a few lengths and angles, one or two circles, a point that moves, and an observer who measures directions. Texts about such models do four different things at once: they describe a geometry, give it numbers, show it in one position, and reason about it. astra/1 writes each of the four as plain text of its own kind.

model	the pure geometry: symbols, construction, observables; no values	Model · values · state
parametrisation	values for a model’s parameters, each with its source; one model has many	Model · values · state
superposition	several models in one plane, their inputs identified	Superposition
derivation	geometrical reasoning: givens, auxiliary constructions, steps justified by named rules, a conclusion	Derivations
figure	a depiction: which values, which state, which labels	Outputs

The first texts describe Ptolemy’s solar model in its eccentric and its epicyclic form, as Noel Swerdlow sets it out in The Renaissance of Astronomy (2026), chapter 1. The model is Ptolemy’s; the text whose use of the model is analysed is Swerdlow’s; the astra texts are by Gerd Graßhoff. Every astra text says all three (attributed, witness, author).

Swerdlow’s Fig. 1.2 is a superposition: the eccentric and the epicyclic form of Ptolemy’s solar model in one plane. The upper slider runs the mean anomaly, the lower one fades between the two forms. That the two suns are one point is not drawn in: it is derived, under the hypotheses R′ = R and r = e (Derivations).

Sixty seconds

model solar-eccentric "Ptolemy's solar model, eccentric form"
attributed "Ptolemy"
witness fr:kepler-sec/Swerdlow2026/0049/p04 "the construction, p. 19"
author "Gerd Graßhoff"
frame geocentric
param R    : length "radius of the eccentric"         in (1, 1000)
param e    : length "eccentricity, the distance OE"   in (0, R / 2)
param lamA : angle  "longitude of the apogee"
variable kappa_bar : angle "mean anomaly about E, counted from the apogee"
O   = observer                        "earth"
E   = O + polar(e, lamA)              "centre of the eccentric"
ecc = circle(E, R)                    "the eccentric"
S   = E + polar(R, lamA + kappa_bar)  "sun"
body sun at S
observe lam = direction(O, S)         "true longitude"

No number stands in it. The numbers are a second text, and there can be several:

parametrisation solar-eccentric.ptolemy of solar-eccentric "Ptolemy's values"
attributed "Ptolemy"
R    = 60        source fr:kepler-sec/Swerdlow2026/0052/p05
e    = 2;30      source fr:kepler-sec/Swerdlow2026/0052/p05
lamA = 65;30°    source fr:kepler-sec/Swerdlow2026/0052/p05

A state is a value of the kinematic variable, kappa_bar = 41°. Model, values and state together give a configuration; a figure draws one, an animation runs through them.

Reasoning comes after the construction, as an operation of its own:

derivation solar-equivalence-equal-radii in solar-eccentric-epicyclic "…"
given h1: equal(Epi.R', Ecc.R)
given h2: equal(Epi.r, Ecc.e)
derive d2: parallel(line(Ecc.E, Ecc.S), line(O, Epi.C)) from d1 by Elements I.28
derive d6: parallel(line(O, Ecc.E), line(Epi.C, Ecc.S)) from d2, d5 by Elements I.33
…
conclude equivalent(Ecc, Epi, position) from d12

Each step is checked four ways: are its premises there, is it true, is it an instance of the rule it names, and does the conclusion rest on what is cited (Derivations).

What follows from the texts

a check per kind of text (Checking);
a specification sheet, a still figure (SVG, Typst) and a browser animation (Outputs, Runtime);
a reference address for every text and each of its parts, fr:astra/<text>/<object> (References);
a comparison of two models or two parametrisations (Comparison);
a deep reading of a source’s pages: every assertion quoted, formalised, recomputed (Deep reading).

Where things are

workspace	`~/ai-mac-studio/development/famulus-astronomica/`
CLI	`uv run --no-sync famulus-astra check \\| derive \\| sheet \\| svg \\| animate \\| typst \\| diff \\| render-check \\| gallery \\| fr \\| reading \\| docs`
language	`spec/astra-1.md` (normative), `spec/ops.yaml` (op-set), `spec/rules.yaml` (rules of derivation), vectors `spec/*-vectors.json`
texts	`examples/solar/*.astra`
runtime	`web/astra-runtime/astra-runtime.js` (dependency-free ES module)
outputs	`build/<id>/` — source, check, sheet, and for figures SVG, animation, bundle, Typst snippet
dossier	`~/ai-mac-studio/dossiers/famulus-astronomica.md`