Skip to main content

The package and a project’s own texts

The texts of this workspace — models, parametrisations, superpositions, figures, derivations, expositions — are offered to other documents as a package. A document does not use “astra” at large. It declares what it imports, and exactly that is available to it.

The manifest

PACKAGE.yaml is written by famulus-astra package --write and never by hand. It lists every shared text:

schema: famulus-package/1
name: astra
address: fr:astra
notation: astra/1
version: 0.3.0
groups:
  solar:
    texts:
    - id: solar-eccentric-epicyclic
      kind: superposition
      title: Eccentric and epicyclic form of Ptolemy's solar model, superposed
      file: examples/solar/solar-eccentric-epicyclic.astra
      sha256: …
      needs: [solar-eccentric, solar-epicyclic]

A group is a folder under examples/ (solar, kepler, euler). needs are the texts a text names: the model of a parametrisation, the members of a superposition, the context and the values of a figure or a derivation. They are read from the parsed text, not from its wording. The hash is the SHA-256 of the source: an importing document can record against which state of a text it was written.

famulus-astra package --check says where the manifest and the texts differ, and the test suite fails when the manifest is behind. fr:astra names the package, fr:astra/<group> lists a group.

Importing it into a notebook

A Famulus notebook project declares its imports in famulus.yml:

imports:
  solar: fr:astra/solar                 # a group
  equant: fr:astra/kepler-equant        # one text, with the texts it rests on
  # astra: fr:astra@rel:0.3.0           # the whole package, pinned to a version

A text always comes with its closure over needs: importing a figure brings the derivation it draws, the superposition that derivation works in, the two models, and the parametrisations. What the declaration does in the notebook:

  • a segment {{< famulus fr:astra/<id> animation|svg|argument|exposition >}} shows an imported text; a text outside the imports is a gap that names the declaration which would import it;
  • the project’s famulus.lock records the hash of every imported text in use; when a text of the package changes, the segments that rest on it are stale until the author has looked and locked again;
  • cells ask the package through the steps astra:derive, astra:check and astra:positions and receive tables with counted values an oracle can be set against;
  • an instruction session lays exactly the imported texts before the engine that writes a project’s own text.

The notebook side is described in the Famulus Notebook documentation (project, references).

A project’s own texts

A project keeps texts of its own in a folder astra/ beside its notebooks. They may be of every kind: a figure of a shared derivation with a line of sight and a narration; a model of its own, superposed with a shared model, with a parametrisation that takes attested values over (use Ecc = solar-eccentric.ptolemy) and a figure. They join the workspace through --root <dir> (or FAMULUS_ASTRA_PATH):

famulus-astra --root ~/work/aequivalenz/astra check solar-mean-sun
famulus-astra --root ~/work/aequivalenz/astra svg solar-fig-mean-sun

A project’s text names shared texts by id. A shared text never names a project’s text, a project’s text never enters the manifest, and an id used on both sides is an error of that id. Every rule of the language holds for a project’s text as for a shared one: a model holds no values and needs its witness; a value needs its source or a stated gap.

Positions

famulus-astra positions solar-fig-1-2 Ecc.S "Epi.S'" --steps 6

lists where the named points of a figure stand at equally spaced states of one revolution — by default the bodies — and, for two points, their distance and its maximum. A model, a superposition or a derivation has no values; it is evaluated under a parametrisation named with --with. The table states what was computed with which values. It proves nothing: that two points coincide for every admissible value is what a derivation shows.