Tutorial 2: Write the Prime Kernel

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.

Step 2 writes the first zone. (diagram page.)

Purpose

Write the first zone, the Prime Kernel, and check it.

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.

Step 2.1: the degrees of freedom

List what the kernel leaves free, each with a name and a dimension. The example has position x, velocity v and height z. Write every exponent, even 1.

"DOF": [
    {"NAME": "x", "DIMENSION": "L1"},
    {"NAME": "v", "DIMENSION": "L1 T-1"},
    {"NAME": "z", "DIMENSION": "L1"}
  ]

Step 2.2: the constants

Each constant has a name and a dimension; a measured one also has a VALUE (a string), a UNIT with the constant's dimension (a length in m here) and, if you know it, an UNCERTAINTY in the same unit.

"CONSTANT": [
    {"NAME": "m", "DIMENSION": "M1"},
    {"NAME": "k_s", "DIMENSION": "M1 T-2"},
    {
      "NAME": "x_max",
      "DIMENSION": "L1",
      "VALUE": "0.05",
      "UNIT": "m",
      "UNCERTAINTY": "0.001"
    }
  ]

The mass and the stiffness carry no value: the kernel reasons about them symbolically. x_max has one, because the boundary uses it.

Step 2.3: the laws

Each law is a STATEMENT in your own notation, with REFS listing every DOF and constant it uses. The checker cannot read your notation; REFS is how it knows what the law is about.

"LAW": [
    {
      "NAME": "N2",
      "STATEMENT": "m dv/dt = -k_s x",
      "REFS": ["m", "v", "k_s", "x"]
    },
    {
      "NAME": "KIN",
      "STATEMENT": "dx/dt = v",
      "REFS": ["x", "v"]
    },
    {
      "NAME": "FREE_Z",
      "STATEMENT": "d2z/dt2 = 0",
      "REFS": ["z"]
    }
  ]

N2 is Newton's second law with Hooke's force; KIN says v is the rate of change of x; FREE_Z says nothing acts along z.

Step 2.4: the assumptions

One proposition per entry. Later every result will cite the assumptions it rests on, and the number cited is part of how results are ranked, so an assumption that bundles two claims would distort the ranking. The checker refuses an assumption visibly joined into two claims - by "and", "but", a semicolon, a second sentence or a list (T2). Text in brackets is not read for joins, so the bracketed note in A_lin passes.

"ASSUMPTION": [
    {
      "NAME": "A_lin",
      "PROPOSITION": "the restoring force is linear in x (Hooke régime)",
      "REFS": ["x"]
    }
  ]

Step 2.5: the constraints

A constraint removes or fixes one DOF. This is where the example restricts itself to motion along x:

"CONSTRAINT": [
    {
      "NAME": "C_NOZ",
      "TARGET": "z",
      "ACTION": "FIX",
      "VALUE": "0",
      "UNIT": "m",
      "STATEMENT": "motion confined to z = 0"
    }
  ]

FIX needs a VALUE and a UNIT with the DOF's dimension: z is a length, so m. REMOVE takes neither.

Step 2.6: the boundaries

A boundary says where the kernel is asserted to hold, as a predicate over DOF and constants.

"BOUNDARY": [
    {
      "NAME": "B_small",
      "PREDICATE": "|x| < x_max",
      "REFS": ["x", "x_max"]
    }
  ]

Step 2.7: check the kernel

Put the six kinds inside "TPK": { ... } in your file and run the checker (the file examples/spring_step2_tpk.json is this stage):

python3 check_draft.py my_draft.json        (Linux, macOS)
py check_draft.py my_draft.json             (Windows)

TPK  PASS
     T2 PASS
     T5 PASS
TrM  MISSING (not checked)
TMS  MISSING (not checked)
FINAL not run: a zone is missing

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.

The kernel passes T1 and then the two kernel tests that run as it is entered: T2, which looks for an assumption joined into two claims, and T5, which checks that every DOF is used by a law and every constraint acts on a DOF a law uses. The other two zones are reported MISSING, the final pass does not run, and the exit status is 1. That is expected at this stage: the draft passes only when all three zones are present.

Tips

Names are unique across the whole kernel, not per kind: a law and a constant cannot share a name.
Keep the prose and the REFS in step. A law that uses a name its REFS omits escapes every check that reads REFS; the declaring authority reads for it at step 7.
Status fields such as STATE have no place here; they belong to register records.

Non-goals

Passing T1, T2 and T5 means the kernel is well-formed, its assumptions are not visibly joined, and no DOF or constraint is idle. Whether the laws are consistent and dimensionally sound is checked at step 7 by inspection, until laws have a machine-readable form (record D108.1; TPS 2.2).

Worked example

The step is its own example. The field rules are on Inputs: the Prime Kernel.

Governing sections: TPS 2.2 and 2.1.

Previous: 1 Before you start. Next: 3 Write the Translation Manifold.