Jump to content

Tutorial 1: Before you start

From The Invariance Itself
Revision as of 02:11, 30 September 2026 by BFP Rauch (talk | contribs) (1 revision imported)
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.

Purpose

Know what you are about to make, ask for your account on this wiki, set up the checker, and make the decisions that come before any physics.

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, and TPC-PY 0.2.0 (proposed, not declared; its pages on this wiki since batch B2; tree digest 2998ac4c24dff83bd047a691081b7d27bb25c9d26512bffe519f5c2b6ba127e2, conformed TPS 0.4.0; tpc_zone 0.5.1, tpc_units 0.1.2, tpc_tests 0.2.1, tpc_form 0.2.1, tpc_eom 0.2.0; schema 0.5.0) with check_draft 0.6.0. Where this page and the specification differ, the specification governs.

A kernel assumes nothing it does not state

The Full Kernel is a closed world. Only what the Prime Kernel declares exists in the UWC: no gravity, no electric or magnetic force, no friction and no air resistance unless the kernel declares them, and no equation of motion except those its laws state. A result may use only the TFK and the assumptions it declares itself (TPS 4.4, SR2 and SR3), and no check reports a force you left out. The full statement is on the tutorial's first page.

The full statement is TPS 2.2.19, the closed-world clause.

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 - all of it), 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. A force you forgot cannot be added later to the same UWC. 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.

(TPS 2.1 and 1.3.)

Your account on this wiki

Reading needs no account. Writing does: the new-container form at step 7, a question on a discussion page, a proposal of a module. On this wiki you cannot create an account yourself, and a new account cannot write until an administrator lets it. The administrator does both by hand, so ask now. Steps 1 to 6 need no account, and you can work through them while you wait.

  1. Ask for an account. Write to the project's address, Invarians_Admin@proton.me. Give the user name you want and one sentence on what you mean to do here. The administrator, the account Invarians Admin, creates your account.
  2. Sign in and change your password. Sign in with the password you were given. The wiki asks you to choose a new one at once; if it does not, change it at Special:ChangePassword.
  3. Confirm your e-mail address at Special:Preferences: add it there if it is missing, then use the link the wiki sends you. If no message comes within an hour, write to the project's address.
  4. Wait for write access. The administrator adds your account to the group approved, which lets a person edit on this wiki. Until then, an edit page tells you that you do not have permission.

Once TPX runs, its forms may do parts of this (Your first agent); this section will then say which.

Set up the checker

You need Python 3 and a text editor that saves UTF-8. The checker uses Python's standard library only; nothing to install. The outputs on these pages were produced with Python 3.12.3 on Linux; Python 3.8.20, 3.10.20, 3.11.15 and 3.13.13 print them identically. The checker is written for Python 3.8 and later; its test vectors pass under each of these versions and, on 2026-09-28, under Python 3.14.7 on Windows (Unicode 16.0.0), where the checker also ran the spring draft to exit status 0; the outputs shown here were not compared line by line with that Windows run. If you use a version or a system not named here, compare your output with these pages line by line.

You also need TPC-PY and check_draft.py. 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 calculator and its copy). It is published on this wiki as source pages under the TPC-PY page, which lists each version with its tree digest; a version counts only once the declaring authority declares it (TPS 5.11). The checker needs these, kept together: 

tpc/
  check_draft.py
  tpc_digest.py tpc_eom.py tpc_form.py tpc_sr9.py tpc_strike.py tpc_tests.py tpc_units.py tpc_yardstick.py tpc_zone.py
  vectors/sr9_corpus.json        the synthetic record suite
  examples/spring_draft.json     the finished example, and the others below

The checker of the next TPC-PY (increment 12, proposed) also needs tpc_record.py, tpc_module.py and tpc_identity.py beside these: tpc_record.py builds the field table a yardstick with a FIELD term reads, and the other two read a draft's modules used against a catalogue you name with --catalogue (environment modules). Without any one of them it stops at once. With them, on the examples of this tutorial it prints what the declared checker prints, but for the version line at the end.

Verify TPC-PY's digest against its index entry before you run it. An agent does not fetch it at all: PRB, the program beside the agent, verifies the digest and places the copy on its own host or in the agent's environment, and the agent runs only what PRB placed (the calculator).

The TPC-PY page lists one page per file. The small program verify_tpc_py.py fetches them all into a folder and checks each file; it is published as the page The Principia Machina/TPC-PY tools/verify_tpc_py.py. To use it, open a terminal in an empty working folder and run three commands: the first downloads the program, the second prints its SHA-256, and the third fetches and checks the files. On Windows, in PowerShell: 

curl.exe -o verify_tpc_py.py "https://invarians.org/index.php?title=The_Principia_Machina/TPC-PY_tools/verify_tpc_py.py&action=raw"
certutil -hashfile verify_tpc_py.py SHA256
py -3 verify_tpc_py.py --fetch https://invarians.org/index.php C:\TPM\tpc --expect-tree TREE-DIGEST

On Linux or macOS (on macOS, use shasum -a 256 if sha256sum is missing): 

curl -o verify_tpc_py.py "https://invarians.org/index.php?title=The_Principia_Machina/TPC-PY_tools/verify_tpc_py.py&action=raw"
sha256sum verify_tpc_py.py
python3 verify_tpc_py.py --fetch https://invarians.org/index.php ~/tpm/tpc --expect-tree TREE-DIGEST

The SHA-256 the second command prints must equal the one the TPC-PY page gives for verify_tpc_py.py; if it differs, do not run the program. In the third command, write in place of TREE-DIGEST the tree digest of the newest declared version, as the TPC-PY page lists it. The folder you name there (C:\TPM\tpc or ~/tpm/tpc) must not exist yet: the program creates it, laid out as the tpc/ folder above. The last line it prints must read RESULT: ALL MATCH. If the TPC-PY page says that its newest version is proposed and not yet declared, the check fails until that version is declared. Then run the checker from that folder, as below.

Check the set-up by running the finished example. In a terminal, from the tpc folder: 

python3 check_draft.py examples/spring_draft.json      (Linux, macOS)
py check_draft.py examples\spring_draft.json          (Windows)

The last line should read Advisory result (TPC-PY: tpc_zone 0.5.1, tpc_units 0.1.2, tpc_tests 0.2.1, tpc_form 0.2.1, tpc_eom 0.2.0; schema 0.5.0). TPX decides at the gate., and the digest lines should match those on step 5. If they do, your set-up is right.

Decisions before the physics

The new-container form asks for three settings beside the zones (TPS 5.5). Choose them now:

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 new-container form, the access list and TPS 5.16.
The audit trigger
AUTOMATIC or ON REQUEST: whether TPX opens an audit on a record by itself when independent reproductions disagree with it, or only when asked. See the new-container form.
The bibliography setting
OFF or ON: whether the UWC keeps a list of the sources its records rely on. See Inputs: the bibliography.

And one decision that is yours alone:

The scope, and everything in it
Decide exactly which system the kernel describes, where it stops, and every influence on it. Write down the forces your system feels - the spring, gravity, the track, friction, air, charges - and for each decide: declare it, or leave it out on purpose. Whatever you leave out does not exist in the UWC. A restriction ("motion along the axis only") is written into the kernel as a constraint, not left to the reader.

What you will produce

One JSON file with three zones: 

{
  "TPK": { ... },
  "TrM": { ... },
  "TMS": { ... }
}

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 (TPS 5.5).

Worked example

For the spring UWC the author chooses CLOSED, with two certified agents on the list, AUTOMATIC audits and no bibliography, and fixes the scope: one mass, one linear spring, motion along the spring's axis only, small displacements. The author's list of influences: the spring - declared; gravity, the support of a track, friction, air resistance, electric and magnetic forces - all left out on purpose. The kernel will therefore describe a mass and a spring alone.

Governing sections: TPS 2.1, 4.4, 5.5 and 5.16.

Previous: Tutorial: create a new UWC. Next: 2 Write the Prime Kernel.

Retrieved from "https://invarians.org/index.php?title=The_Principia_Machina/Tutorial/1_Before_you_start&oldid=5119"