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.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

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.

PENDING D176-D18x: the TPS section that states this closed-world rule, if one is added; this paragraph will then name it instead of explaining it from SR2 and SR3.

PENDING D176-D18x: environment presets or modules (for example gravity at the default Earth-surface strength, or air resistance at sea level) - whether they exist, how a kernel turns one on, and what each one adds to the kernel. Until that is decided, every force is declared by hand; tutorial step 6 shows it for gravity.

What runs today, and what does not

You can do steps 1 to 6 today, on your own machine: write the draft, check it with TPC-PY (The Principia Calculator in Python), fix what it refuses, and read its digests. Steps 7 and 8 describe the specified flow on the wiki. TPX, the extension that will take the draft, and the new-container form it provides, are not built yet (implementation sequence step 3), and the DECLARATIONS page is created only at TPX's first landing. So no UWC can be declared yet. When TPX is built, steps 7 and 8 become runnable without changing steps 1 to 6: TPX runs the same checks, from the same calculator's residence of record. From then on 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, because every derivative is taken with respect to it, 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.