The Principia Machina/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 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.

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

Purpose

Write the first zone, the Prime Kernel, with its equations of motion stated in full, and check it.

Explains: TPS revision 6 (proposed as TPS 0.3.0 until the declaring authority declares it; 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 as built at increment 10 (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; no TPC-PY version is declared yet) with check_draft 0.5.0. Where this page and the specification differ, the specification governs.

Remember the rule of the first page: the kernel is a closed world. Everything the UWC's physics contains is written on this page, or it is not there.

Step 2.1: time and the degrees of freedom (DOF)

List what the kernel leaves free for its laws to relate, each with a name and a dimension. Write every exponent, even 1.

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

• t is the time, the independent variable. It is declared here because every derivative in the laws is taken with respect to it, and the declared form (step 2.3) needs its variable among the law's names, and that variable must be a DOF (TPS 2.2.13). The schema has no separate kind for an independent variable, so t is listed under DOF.
• x and v are the state of the motion along the spring's axis: the displacement and the velocity.
• z is the displacement across the axis. Step 2.5 holds it at 0.

In TPM a DOF is any variable the kernel leaves free for its laws to relate. It is not the mechanical count of degrees of freedom, which for this system is one - x - once z is held at 0.

The time t stays a DOF. It is the variable the derivatives are taken with respect to, called the D variable. The D variable may be any DOF that no constraint fixes or removes, of any dimension: a kernel written in a scaled, dimensionless time works the same way (TPS 2.2.13). This kernel uses one D variable, which is the default. A kernel whose laws take derivatives in more than one variable - heat spreading along a rod, in position and in time - adds "PARAMETERS": {"D_VARIABLES": "SEVERAL"} to its TPK; the structure check then cannot analyse it (Inputs: the Prime Kernel).

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 - here, the equations of motion

A law is taken as given. In a kernel that describes motion, the laws that matter most are the equations of motion: together they say how every DOF except t changes with t. The example writes them out in full:

"LAW": [
  {
    "NAME": "EOM_X",
    "STATEMENT": "m dv/dt = -k_s x",
    "REFS": ["m", "v", "k_s", "x", "t"],
    "ROLE": "EOM(v)",
    "EQUATION": "m * D(v, t) = -k_s * x"
  },
  {
    "NAME": "KIN",
    "STATEMENT": "dx/dt = v",
    "REFS": ["x", "v", "t"],
    "ROLE": "EOM(x)",
    "EQUATION": "D(x, t) = v"
  },
  {
    "NAME": "EOM_Z",
    "STATEMENT": "m d2z/dt2 = 0",
    "REFS": ["m", "z", "t"],
    "ROLE": "CONSTRAINT",
    "EQUATION": "m * D(z, t, 2) = 0"
  }
]

EOM_X

The equation of motion along the axis, with "ROLE": "EOM(v)": the mass times the rate of change of its velocity equals the spring's force, -k_s x. You may read it as Newton's second law with Hooke's force as the only force. But the kernel contains this equation, not Newton's laws: no other force acts along x, because no other force is declared, and nothing can be derived in the UWC from a general law the kernel does not state.

KIN

The kinematic equation, with "ROLE": "EOM(x)": v is the rate of change of x. With EOM_X it gives the equations of motion along the axis in first-order form, the state being x and v. (You could instead declare x alone and write m d2x/dt2 = -k_s x; the example keeps v because step 3 ties it to a measured velocity.)

EOM_Z

The motion across the axis. Its ROLE is "CONSTRAINT", since C_NOZ (step 2.5) fixes z. The right side is 0 because no force across the axis is declared - no gravity, no support, no friction. Left alone, the mass would coast in z at constant speed; step 2.5 holds it at z = 0.

Each law has a STATEMENT, your prose in your own notation, and REFS, the DOF and constants it uses. The checker cannot read your prose; REFS is how it knows what a law is about.

Each law here also carries an EQUATION: the same statement in the declared form, a small closed grammar in which D(v, t) is the derivative of v with respect to t and D(z, t, 2) the second derivative of z (TPS 2.2 gives the grammar). With it the checker can test more: that both sides of each law have one dimension (T4), that the names in the equation are exactly the law's REFS, and, where every name in a law has a value, that the law is not false (T3, at the final pass). The form is optional (record D132.1): a law without one still passes, and those checks go to the declaring authority by inspection. See step 2.8.

Each law also carries a ROLE, which says what the law is for. KIN has "ROLE": "EOM(x)", because it is the equation of motion of x; EOM_X has "ROLE": "EOM(v)", the equation of motion of v; EOM_Z has "ROLE": "CONSTRAINT", because it restates the motion of z, which the constraint of step 2.5 fixes (TPS 2.2.6). The laws above show each one.

With the forms and the roles, a check now asks the question this step began with. At the final pass the structure check reads every law that has an EQUATION and reports, for each DOF except t, which law gives it: the EOM map. If a DOF has no law, or two, it says so; it refuses nothing. It runs because the Measure Set's switch STRUCTURE_CHECK is ON unless you turn it off (step 4). Delete EOM_X from this kernel and the check names the DOF left without a law: a named gap, which would open the first task EOM-0 in the UWC and give it the label Structure not Validated at Inception. Step 5 shows the map.

Step 2.4: the assumptions

One proposition per entry. An assumption states what the kernel takes as given that its laws do not already say. The laws above hold for any values of m and k_s; the assumptions add that both are positive:

"ASSUMPTION": [
  {
    "NAME": "A_kpos",
    "PROPOSITION": "k_s is positive",
    "REFS": ["k_s"]
  },
  {
    "NAME": "A_mpos",
    "PROPOSITION": "m is positive",
    "REFS": ["m"]
  }
]

This is not pedantry. With k_s negative, EOM_X describes a mass pushed away from x = 0, not an oscillation; with m zero, EOM_X says nothing about v at all. In a closed world "obviously positive" is not assumed unless it is stated.

The checker refuses an assumption visibly joined into two claims (T2's syntactic part, TPS 2.2): "k_s is positive and m is positive" would be refused, and should be the two entries above. An assumption of the kernel is part of the TFK; it does not add to any result's count of assumptions, which counts the register's own assumption records (TPS 4.4, SR4).

Step 2.5: the constraints

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

"CONSTRAINT": [
  {
    "NAME": "C_NOZ",
    "TARGET": "z",
    "ACTION": "FIX",
    "VALUE": "0",
    "UNIT": "m",
    "STATEMENT": "only motion on the spring axis is described: z = 0"
  }
]

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

What C_NOZ means here: EOM_Z says nothing acts across the axis, so a mass that starts on the axis, and is not moving across it, stays on it. C_NOZ restricts the kernel to those motions. It is not a rail and it models no force: nothing in this kernel pushes the mass back to the axis. If your system has a guide or a track that does push, that push is physics and must be declared as a force; step 6 shows what happens when it is not.

Step 2.6: the boundaries

A boundary says where the kernel is asserted to hold, as a PREDICATE over DOF and constants. In this tutorial the predicate is true inside that region: the spring law is asserted for displacements smaller than x_max.

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

The CONDITION is the predicate in the declared form. With it the checker tests that the predicate is decided for every value of x (T6).

The predicate says where the kernel is asserted, as here: the spring law is claimed only while |x| < x_max (TPS 2.2.6).

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
     T4 PASS
     T6 PASS
TrM  MISSING (not checked)
TMS  MISSING (not checked)
FINAL not run: a zone is missing

Advisory result (TPC-PY: 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). TPX decides at the gate.

The kernel passes T1 - which now includes parsing each EQUATION and CONDITION, checking its names against REFS, reading each ROLE and checking the D variable - and then the kernel tests that run as it is entered: T2, which looks for an assumption joined into two claims; T5, which checks that every DOF is used by a law and every constraint acts on a DOF a law uses; and, because the laws and the boundary carry declared forms, T4 (each EQUATION has one dimension on both sides) and T6 (the CONDITION is decided for every x). 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.

Step 2.8: the forms are optional

The same kernel with every EQUATION and CONDITION removed (examples/spring_step2_noform_tpk.json) also passes:

TPK  PASS
     T2 PASS
     T5 PASS
     T4 NO FORM (by inspection)
     T6 NO FORM (by inspection)
     inspection BOUNDARY:B_small: no CONDITION; T6 totality by inspection
     inspection LAW:EOM_X: no EQUATION; T4 and T3 over this law by inspection
     inspection LAW:EOM_Z: no EQUATION; T4 and T3 over this law by inspection
     inspection LAW:KIN: no EQUATION; T4 and T3 over this law by inspection
TrM  MISSING (not checked)
TMS  MISSING (not checked)
FINAL not run: a zone is missing

Advisory result (TPC-PY: 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). TPX decides at the gate.

T4 and T6 report NO FORM, and each law and boundary without a form is listed as an inspection the declaring authority owes before declaring (TPS 2.2). Nothing is forced on you; what you do not declare in the form, a person checks by eye. The equations of motion are explicit either way: in the STATEMENT, or in the STATEMENT and the EQUATION. The forms matter again at the final pass: the structure check reads only laws with an EQUATION, so the finished draft without its forms (examples/spring_noform_draft.json) gets the label Structure not Validated at Inception: PROSE, NO FORM.

Tips

• Names are unique across the whole kernel, not per kind: a law and a constant cannot share a name.
• Keep the prose, the REFS and the EQUATION in step. With an EQUATION the checker compares its names with REFS; that the prose says what the EQUATION says is still read by the declaring authority at step 7.
• Do not constrain t. A kernel whose time is fixed describes no motion, and T1 refuses it: a derivative's variable must be a DOF no constraint fixes or removes (TPS 2.2.13).
• Status fields such as STATE have no place here; they belong to register records.

Non-goals

Passing these checks means the kernel is well-formed, its assumptions are not visibly joined, no DOF or constraint is idle, and, where a form is declared, each law balances dimensionally and each boundary is decided everywhere. It does not mean the laws are right, complete or consistent beyond the bounded test T3 makes at the final pass (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, 2.1 and 4.4.

---

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