The Principia Machina/Tutorial

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 UUID Workspace Container (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 Principia Machina Specification (TPS) governs. Field-by-field reference: Public Recorder inputs.

Draft and certify: this tutorial covers the first two stages. (diagram page.)

Purpose

Walk one UWC from nothing to its declaration, so that every input and every check is met once, in order, on a real example.

Explains: TPS 0.3.0 (declared final on 2026-09-28 at revision 6; it follows TPS 0.1.1, declared final on 2026-09-26), whose sections 2.2 to 2.5 carry the zone schemas with the optional declared form, the ROLE field, the D variable and the structure check (records D92.1, D98.1, D99.1, D100.1, D103.1-D105.1, D106.1-D108.1, D132.1, D176.1, D177.1, D179.1 and D186.1); TPC-PY 0.1.0 (declared on 2026-09-28, tree digest a00161c1b321fd66abc591209007d46a7fa6290097835060e50f381426259043, conformed TPS 0.3.0; tpc_zone 0.5.0, tpc_units 0.1.1, tpc_tests 0.2.0, tpc_form 0.2.0, tpc_eom 0.1.0; schema 0.5.0) with check_draft 0.5.0. Where this page and the specification differ, the specification governs.

A kernel assumes nothing it does not state

Read this before you write anything. The Full Kernel (TFK) is a closed world: the only physics in a UWC is what its Prime Kernel declares - its degrees of freedom (DOF), constants, laws, assumptions, constraints and boundaries. Nothing is supplied from outside.

• No gravity, unless a law or a constant of the kernel declares it.
• No electric or magnetic force, unless declared.
• No friction and no air resistance, unless declared.
• No equation of motion except those the laws state. The kernel does not contain Newton's laws in general, or any other general law; it contains the equations you write, and nothing a reader would "normally assume" beside them.

Why: a result stands only while it derives from the TFK plus the assumptions it declares (TPS 4.4, SR2 and SR3). A derivation that uses a force stated neither in the kernel nor in the assumptions the result declares uses something the UWC does not contain; and an assumption brought in by a result is that result's, counted against it, never the kernel's. No check reports what you left out: completeness is judged only against what you declared (TPS 2.2), so a force you forgot is not an error message, it is simply absent from every result.

The rule is stated in TPS 2.2.19, the closed-world clause; this page explains it.

Environment modules are selected (D178.1) and not yet built. The new-container form will ask one question: which of the modules the declaring authority has declared act on the system, gravity at the standard strength and air resistance at sea level among the first selected. Nothing is pre-selected, and the last answer is "None of these: only the laws I write act". A chosen module adds ordinary entries and terms to the kernel, each shown before it enters; nothing is switched on by default, so the closed world above still holds (Inputs: environment modules). Until TPX offers modules on the form, every force is declared by hand; tutorial step 6 shows it for gravity.

What runs today, and what does not

Every step runs today. Steps 1 to 6 - write the draft, check it, fix what it refuses, and read its digests - run on your own machine with TPC-PY (The Principia Calculator in Python), or on this wiki at Special:TpmCheck, where TPX, the extension that takes the draft, runs the same checks with TPC-PHP, the calculator of record, and stores nothing. Steps 7 and 8 run on the wiki since 2026-10-04: the new-container form, Special:TpmNewUwc, runs the same checks and saves a passing draft with its candidate certificate, and the declaring authority declares it at Special:TpmDeclare; the first declaration created the DECLARATIONS page. This tutorial's spring is declared: it is the UWC SPR, and its register is at Special:TpmRegister/SPR. Steps 1 to 6 did not change for that: TPX runs the same checks, from the same calculator's residence of record. The checker is optional for an author: a draft can go straight to the form, and TPC-PY only lets you see TPX's answer first (record D101.1; the calculator).

The steps

1. Before you start
2. Write the Prime Kernel
3. Write the Translation Manifold
4. Write the Measure Set
5. Check the draft
6. Fix refusals
7. Inspect, submit and declare
8. After the declaration

Who does what

• You, the author - here also the initiator, who becomes the UWC's H-OWN - write the three zones and check them.
• The declaring authority (H-DECL) inspects what no machine checks yet and declares the UWC.
• The operator (H-OP) runs the wiki.
• TPX computes every digest, obtains the universally unique identifier (UUID), allocates the prefix and writes the pages.

See Roles.

The example

A mass m on a spring of stiffness k_s, moving along the spring's axis. Its equations of motion (EOM) are written out in full, as laws of the kernel:

EOM_X   m dv/dt = -k_s x     along the axis, the spring's force is the only force
KIN     dx/dt = v            v is the rate of change of the displacement x
EOM_Z   m d2z/dt2 = 0        across the axis, no force acts at all

The kernel also declares the time t, the variable every derivative is taken with respect to, and a coordinate z across the axis, which a constraint holds at 0 so that only motion on the axis is described. The spring law is asserted only for displacements smaller than x_max. Two assumptions state what the laws leave open: the stiffness and the mass are positive. It is deliberately small: four declared DOF, three laws, two assumptions, one constraint, one boundary. Its four digests are fixed, so you can check your copy against them at step 5.

What is not in it. The kernel declares no gravity, no friction, no air resistance and no electric or magnetic force, so in this UWC there are none. Read as physics, it is a closed one-dimensional oscillator: a mass, a spring, and nothing else. It is also the usual idealization of a glider on a level, frictionless air track, where the glider's weight and the track's support cancel - but the kernel does not say that, and no result in the UWC may use it unless that result declares it as its own assumption. If you want the weight and the support in your UWC, declare both; step 6 shows what the checker says when only the weight is declared, and the fix.

Non-goals

The tutorial does not teach physics or how to choose a good kernel. Its numbers are illustrative. It does not cover running work in a UWC once it exists; the operator's guide does.

Worked example

The whole tutorial is the worked example. The finished draft is on step 5.

Governing sections: TPS 5.5, 5.6, 2.1, 2.2 and 4.4.

---

Next: 1 Before you start.