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 linear spring, moving only along x - 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 two decisions that come before any physics.

Explains: TPS 0.1.0, revision 4 (declared final 2026-09-22); the zone schemas the declaring authority selected on 2026-09-22 (records D92.1, D98.1, D99.1, D100.1, and for units D103.1, D104.1, D105.1; schema 0.3.0), whose text enters TPS at revision 5, and the kernel tests and isomorphism checks selected the same day (D106.1, D107.1, D108.1; tpm_kernel_tests 0.2.0), whose text follows at the next TPS revision; TPC-PY as built 2026-09-22 (tpc_zone 0.3.0, tpc_units 0.1.0, tpc_tests 0.1.0; no TPC-PY version is declared yet) with check_draft 0.3.0. Where this page and the specification differ, the specification governs.

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), 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. 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.8 or later (run on 3.8 and 3.10 to 3.13 for this tutorial) on Linux, macOS or Windows, and a text editor that saves UTF-8. The checker uses Python's standard library only; nothing to install.

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. Keep them together:

tpc/
  check_draft.py
  tpc_zone.py  tpc_units.py  tpc_tests.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.3.0, tpc_units 0.1.0, tpc_tests 0.1.0; schema 0.3.0). TPX decides at the gate., and the digest lines should match those on step 5. If they do, your set-up is right.

Two decisions first

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 and the access list.

The scope

Decide exactly which system the kernel describes and where it stops. A restriction ("motion along x only") is written into the kernel as a constraint, not left to the reader. The example restricts itself this way at step 2.

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, and fixes the scope: one mass, one linear spring, motion along x only, small displacements.

Governing sections: TPS 2.1, 5.5 and 5.16.

---

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