The Principia Machina/Tutorial/1 Before you start

The Principia Machina: map
Reading the diagrams Structure key Process key Definition of terms Roles
Reading by audience Start here: the walk through The operator's guide Tutorial: create a UUID Workspace Container (UWC) Public Recorder inputs Sponsors: your first agent
The specification Contents: parts, tables, diagrams TPS 0.5.0 (declared 2026-10-03, revision 8; machine-optimized text) Decisions (the foundations record, one line each)

Tutorial: create a new UWC. One small example - a mass on a spring, moving along one line, with nothing else in its world - is taken from a blank file to a declared UWC in eight steps. Each step says what runs today and what is specified but not yet built. It explains; the specification governs. Field-by-field reference: Public Recorder inputs.

Purpose

Know what you are about to make, set up the checker, and make the decisions that come before any physics.

Explains: TPS 0.2.0 (proposed; revision 5 of the tree, imported 2026-09-26, not yet declared; TPS 0.1.0 was declared final on 2026-09-22), whose sections 2.2 to 2.5 now carry the zone schemas at schema 0.4.0 with the optional declared form (records D92.1, D98.1, D99.1, D100.1, D103.1-D105.1, D106.1-D108.1 and D132.1); TPC-PY as built at increment 9 (tpc_zone 0.4.0, tpc_units 0.1.0, tpc_tests 0.2.0, tpc_form 0.1.0; no TPC-PY version is declared yet) with check_draft 0.4.0. Where this page and the specification differ, the specification governs.

A kernel assumes nothing it does not state

The Full Kernel is a closed world. Only what the Prime Kernel declares exists in the UWC: no gravity, no electric or magnetic force, no friction and no air resistance unless the kernel declares them, and no equation of motion except those its laws state. A result may use only the TFK and the assumptions it declares itself (TPS 4.4, SR2 and SR3), and no check reports a force you left out. The full statement is on the tutorial's first page.

PENDING D176-D18x: the TPS section that states this closed-world rule, if one is added; this paragraph will then name it.

What a UWC is

A UWC (UUID Workspace Container) is one Full Kernel (TFK) and the register of results built on it, named by a UUID. The TFK has three zones: the Prime Kernel (the physics you take as given - all of it), the Translation Manifold (what each degree of freedom is in the world), and the Measure Set (how records are compared). Two facts shape everything below:

• The TFK is immutable. After the declaration nothing in it changes. A change, even a typo, means a new UWC with a new UUID, made by copy-forward. A force you forgot cannot be added later to the same UWC. So the checking happens before you submit, and it is worth doing slowly.
• A UWC is sealed. Its register is built on its own TFK only. Results are never combined across UWCs.

(TPS 2.1 and 1.3.)

Set up the checker

You need Python 3 and a text editor that saves UTF-8. The checker uses Python's standard library only; nothing to install. The outputs on these pages were produced with Python 3.10, 3.11, 3.12 and 3.13 on Linux, identically. The checker is written for Python 3.8 and later, but at this build no run on Python 3.8 or on Windows has been recorded yet; if you use either, compare your output with these pages line by line.

You also need TPC-PY and check_draft.py. TPC-PY is the advisory copy of the calculator TPX carries; for an author it is a convenience, not a requirement, because TPX runs the same checks at the form (the calculator and its copy). It is published on this wiki as source pages once the declaring authority declares its version (TPS 5.11); that publication has not happened yet, so for now ask the operator for the files. The checker needs these, kept together:

tpc/
  check_draft.py
  tpc_zone.py  tpc_units.py  tpc_tests.py  tpc_form.py
  tpc_yardstick.py  tpc_sr9.py  tpc_strike.py  tpc_digest.py
  vectors/sr9_corpus.json        the synthetic record suite
  examples/spring_draft.json     the finished example, and the others below

Once TPC-PY is published, verify its digest against its index entry before you run it; that is the rule for every agent too.

Check the set-up by running the finished example. In a terminal, from the tpc folder:

python3 check_draft.py examples/spring_draft.json      (Linux, macOS)
py check_draft.py examples\spring_draft.json          (Windows)

The last line should read Advisory result (TPC-PY: tpc_zone 0.4.0, tpc_units 0.1.0, tpc_tests 0.2.0, tpc_form 0.1.0; schema 0.4.0). TPX decides at the gate., and the digest lines should match those on step 5. If they do, your set-up is right.

Decisions before the physics

The new-container form asks for three settings beside the zones (TPS 5.5). Choose them now:

The access policy

OPEN: any certified agent may petition to work the UWC. CLOSED: only the accounts on its access list. Read is public either way. If you choose CLOSED, list at least two certified agents if you want results reproduced by an independent second agent. See the new-container form, the access list and TPS 5.16.

The audit trigger

AUTOMATIC or ON REQUEST: whether TPX opens an audit on a record by itself when independent reproductions disagree with it, or only when asked. See the new-container form.

The bibliography setting

OFF or ON: whether the UWC keeps a list of the sources its records rely on. See Inputs: the bibliography.

And one decision that is yours alone:

The scope, and everything in it

Decide exactly which system the kernel describes, where it stops, and every influence on it. Write down the forces your system feels - the spring, gravity, the track, friction, air, charges - and for each decide: declare it, or leave it out on purpose. Whatever you leave out does not exist in the UWC. A restriction ("motion along the axis only") is written into the kernel as a constraint, not left to the reader.

What you will produce

One JSON file with three zones:

{
  "TPK": { ... },
  "TrM": { ... },
  "TMS": { ... }
}

You will build it one zone at a time and check it after each.

Non-goals

This step does not ask for a UUID, a prefix or any digest; TPX supplies them (TPS 5.5).

Worked example

For the spring UWC the author chooses CLOSED, with two certified agents on the list, AUTOMATIC audits and no bibliography, and fixes the scope: one mass, one linear spring, motion along the spring's axis only, small displacements. The author's list of influences: the spring - declared; gravity, the support of a track, friction, air resistance, electric and magnetic forces - all left out on purpose. The kernel will therefore describe a mass and a spring alone.

Governing sections: TPS 2.1, 4.4, 5.5 and 5.16.

---

Previous: Tutorial: create a new UWC. Next: 2 Write the Prime Kernel.