View source for The Principia Machina/Tutorial/1 Before you start

{{TPM map}}
{{DISPLAYTITLE:Tutorial 1: Before you start}}
''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: [[The Principia Machina/Inputs|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.
([[The Principia Machina/TPS/2.1 The Full Kernel and immutability|TPS 2.1]] and [[The Principia Machina/TPS/1.3 System of record and containers|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 <code>check_draft.py</code>. 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 Principia Machina/Walk/The calculator and its copy|the calculator and its copy]]). It is published on this wiki as source pages once the declaring authority declares its version ([[The Principia Machina/TPS/5.11 The index of record|TPS 5.11]]); that publication has not happened yet, so for now ask the operator for the files. Keep them together:
<pre>
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
</pre>

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 <code>tpc</code> folder:
<pre>
python3 check_draft.py examples/spring_draft.json      (Linux, macOS)
py check_draft.py examples\spring_draft.json          (Windows)
</pre>

The last line should read <code>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.</code>, and the digest lines should match those on [[The Principia Machina/Tutorial/5 Check the draft|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 Principia Machina/Inputs/New container form|the new-container form]] and [[The Principia Machina/Inputs/Access list|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:
<pre>
{
  "TPK": { ... },
  "TrM": { ... },
  "TMS": { ... }
}
</pre>

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 ([[The Principia Machina/TPS/5.5 The new-container flow|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: [[The Principia Machina/TPS/2.1 The Full Kernel and immutability|TPS 2.1]], [[The Principia Machina/TPS/5.5 The new-container flow|5.5]] and [[The Principia Machina/TPS/5.16 UWC access policy|5.16]].

----
Previous: [[The Principia Machina/Tutorial|Tutorial: create a new UWC]]. Next: [[The Principia Machina/Tutorial/2 Write the Prime Kernel|2 Write the Prime Kernel]].

[[Category:The Principia Machina]]