Design notes

Why a language

Swerdlow’s page 20 explains a figure in prose: “the result of the two motions is that S moves uniformly in the eccentric about E and the direction OS from the earth to the sun, the diagonal of the parallelogram, is the same in both models”. The figure carries the points, the prose carries the relations, the parameters are elsewhere on page 22, and the motion that makes the figure a model — κ̄ growing uniformly with time — is in the reader’s head. A representational language writes these down, each as what it is: the construction as a model, the numbers as a parametrisation with sources, the relation between two models as a derivation in their superposition. From those texts the figure, the animation, the sheets and the check of every step are derived, not drawn by hand.

What was learned from the geometry packages

• GCLC (Janičić) treats a construction as a procedure, not a picture: point, circle k O A, intersec, towards, rotate; free and constructed points are distinct; prove {…} checks a statement over the construction; animation_frames parametrises. astra/1 keeps the procedure view — every object is defined before it is used, so the construction is a directed acyclic graph by construction. GCLC’s prover takes a conjecture and returns a proof; an astra derivation takes the steps a text gives and asks of each whether it is true and whether the rule it names licenses it. It drops coordinates: only the observer has a position.
• Eukleides (Obrecht) makes the syntax resemble geometric notation and avoids Cartesian coordinates; values are typed (point, vector, line, circle, conic); interactive variables are bounded. astra/1 is typed with units (an angle is not a length, a rate is an angle per time) and coordinate-free.
• GeoGebra, JSXGraph’s JessieCode, CindyScript drive a dependency graph from sliders and treat labels as handles on objects. In astra/1 the driving variable is the model’s kinematic variable; every object has an ASCII identifier that is also its reference address, and a display symbol for the figure.
• Dennis Duke’s animations of the Almagest models compute every position in closed form from one time variable with named rates and lengths, and show the equivalence of two models by a slider between them. In astra/1 that slider is the fade between the members of a superposition; what Duke shows, a derivation states with its hypotheses.
• Brandon Rhodes’ SVGs keep parameter fitting apart from drawing and state their scale conventions. In astra/1 values stand in parametrisations with a source or an explicit gap each, and a figure text states orientation, framing and drawing values.

None of these was taken over: astra/1 is a language for historical astronomical models, so an observer, a body, a kinematic variable, a source for every number and a rule for every step are part of what makes a text complete.

The universal frame

What all historical models share, and what the checks test for: one observer; bodies carried by constructed points; kinematic variables; a construction from circles and lines (and the ellipse); observables that are directions from the observer. Ptolemy’s eccentric and epicycle, the equant (seen_from), the Maragha couples, the Copernican transposition to a heliocentric frame, Tycho’s arrangement and Kepler’s ellipse (true_anomaly, ellipse) are expressible. What differs between two of them is visible in the diff of their models; what they share in spite of it is the conclusion of a derivation in their superposition.

For an AI reader

The texts are small, typed and separate, so a language model can read them as reliably as code: every name resolves, a model has no accidental numbers in it, every number has a page and an owner, every step of an argument names its rule and carries its status, and the sheets restate all of it as tables. An explanation of the difference between two models would quote the diff of their geometries and the derivation of what they share, not a recollection.

Decisions

• Model, parametrisation, state are three things (10 Nov 2026, owner). A model has no values. Values are a text of their own, with an owner and sources. A state is an argument. Different things are true of each.
• Three roles. attributed (whose model), witness (the text analysed), author (who wrote the astra text). An exposition is not an authorship.
• A diagram of two models is a superposition. Equivalence is a relation derived under hypotheses, never drawn in.
• Derivation is an operation after construction. Givens, auxiliary constructions, steps with premises and rules, a conclusion; four checks. The rules are a table with Heath’s wording and pages.
• Coordinate-free. The observer is the origin; everything else is relational.
• Gaps are explicit. A value without a source needs gap "…"; a partial parametrisation is reported as partial; a step whose rule does not match is “true, not justified”. No check passes by default.
• Two evaluators, one op-set, shared vectors. Python for stills and checks, JS for animation.
• Drawn as printed, marked as drawn. Drawing values stand in the figure text and never in a parametrisation.
• Tokens, not colours. The famulus palette comes from famulus-visualization’s token source.
• Reference objects. Every text and every part of it, down to a step of a derivation, has an address.

Open

• A derivation covers its degenerate states only when it argues them separately, by cases. The checks report uncovered states and whether the cases cover every configuration; they do not propose the distinction.
• Hypotheses have to fix a parameter; inequalities and incidence hypotheses are not supported.
• “Read off the construction” and “calculation” are tested numerically, not replayed symbolically.
• Tabulated motions; latitude (the frame is planar); models beyond the solar model wait for their source pages on this machine.