The Principia Machina/Tools/General reader

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)

For anyone curious. What a physics tool is for, one small example taken from a law all the way to numbers, which tool answers which question, and what the Principia Machina does with a tool's answer. You do not need to follow any equation to read this page. Operators have their own guide, and AI agents their own page. All three start from the front page.

1 Three jobs between an idea and a number

A physical theory starts as an idea and has to end as a number someone can measure. Between the two lie three jobs. People did all three by hand for centuries: Kepler found his laws in Tycho Brahe's tables of planet positions; Lagrange and Hamilton showed how to derive the equations of motion from a single quantity, the action (Hamilton's principle); and astronomers solved those equations, line by line, to predict where a planet would be.

The tools on these pages are computer programs for the same three jobs.

• Find: look at data and find the rule behind it.
• Derive: start from a rule and work out the equations it implies.
• Solve: start from the equations and work out the numbers.

The dashed arrow matters. A prediction is compared with a measurement only after the work is done, never while it is being done. Section 6 explains why.

2 One example, all the way through: a pendulum

A weight on a string, swinging. Here is the whole road from rule to number, once, so the rest of the page has something to hang on.

The rule. The action of a pendulum is built from two energies: the energy of motion and the energy of height. Written out, with m the mass, ℓ the string's length, g gravity and θ the angle from straight down:

$L=\frac{1}{2}m{\ell }^2{\dot{\theta }}^2+mg\ell \cos \theta$

Derived. Hamilton's principle turns that one line into the equation of motion. A symbolic tool such as Cadabra2 or ModelingToolkit.jl does this step the way a physicist does it on paper:

$\ddot{\theta }=-\frac{g}{\ell }\sin \theta$

Notice that the mass has dropped out. The tool did not decide that; the mathematics did.

Solved. For small swings the equation has a famous answer: the time for one full swing is

$T\approx 2\pi \sqrt{\ell /g}$

For a string 1 m long (about 3.3 ft) and g = 9.81 m/s², that is 2.006 seconds. For bigger swings there is no such short formula, and a solver steps the equation forward in time instead. It gives 2.038 s for a swing of 0.5 radian (about 29°) and 2.139 s for 1 radian (about 57°). The short formula is 1.6 per cent too fast at 29° and 6 per cent too fast at 57°.

Found, the other way round. Hand a tool such as PySR a long table of measured angles and times, and it can search for the equation that reproduces the table, and find $\ddot{\theta }=-(g/\ell )\sin \theta$ without being told it.

3 Solving a field: four ways to cut up space

A pendulum has one moving part. A field, such as the electromagnetic field in a cavity or a wave crossing a room, has a value at every point of space. A computer cannot hold infinitely many points, so each solver cuts space up in its own way. That choice is most of what separates the field solvers on these pages.

• A regular grid (Devito): space as graph paper. Each point looks at its neighbours to estimate how fast the field changes. Fast and simple; best for waves in simple boxes.
• A mesh of small shapes (FEniCS): space tiled with triangles or tetrahedra that follow curved walls. The action is added up shape by shape.
• Cells that trade with their neighbours (FiPy, Clawpack): space as boxes, and whatever leaves one box enters the next, so nothing is created or lost by rounding. Clawpack also follows sharp fronts, such as shocks.
• No grid at all (DeepXDE): a neural network is bent until the field it describes obeys the equations everywhere at once.

Three more solvers work in worlds of their own: the Einstein Toolkit solves the equations of general relativity, where space and time themselves move; QuTiP solves quantum systems that leak into their surroundings; and Modelica solves machines made of connected parts, such as linkages and circuits, where there is no field at all.

4 Which tool for which question

Start from the question you are asking, not from the tool.

The survey gives each tool a score out of ten for four kinds of work: actions, fields, relativity, and quantum systems or data. The scores are the survey's own judgments, not measurements; the front page charts all forty-eight of them.

The survey's own plain-language primer sorts the same tools into four families and gives each a picture to remember it by: the prospectors, the approximators, the wave engines and the architects.

5 What the Principia Machina does with a tool's answer

The Principia Machina is a way of doing research with AI so that anyone can check the result afterwards. A tool's answer is never taken on the tool's word. It goes through the same steps as every other finding.

1. It is written down as a numbered entry in the register of a research container, with its steps and its starting assumptions spelled out, and the conditions it was worked under (for the pendulum: the string length, the starting angle).
2. A machine checks its form, not its physics: that every field is filled in, that the units agree, that the fingerprints of the text match. The server, TPX, never runs the physics tool.
3. Another AI redoes it from the same starting point, without being shown the first answer. If both agree, the finding gains support; if not, the disagreement is logged in public.
4. Only then is it compared with the world: a measured value from outside is set beside it, and the difference is written down. Agreement is never claimed in words; the numbers speak.

6 Why the answer is not shown the target

If you know the answer you want, it is easy to steer a calculation towards it without meaning to: a slightly different mesh here, a different starting guess there. So the Principia Machina keeps the measured value out of sight until the derivation is finished. It calls this benchmark quarantine. A tool that was fitted to a set of data cannot then be tested against that same data: that would be grading a student with the answer key it studied from.

7 What a tool cannot do here

Each research container rests on a kernel: the laws and assumptions everyone agreed to hold fixed for that piece of research (the walk through, page 2). A tool cannot change it. If a tool finds a better law in the data, that law does not slip into the old container. It becomes the starting point of a new one, with a new name, checked from the beginning and declared by a named person. The old container and everything in it stay exactly as they were.

A tool also cannot vouch for itself. A program can have bugs, and two runs of the same program share them. That is why the redo in step 3 is done by a different AI, and why the comparison in step 4 uses a measurement from outside.

9 The twelve tools in one table

Tool	Its job	In one line
PySR	find	Searches millions of formulas for the simplest one that fits the data.
AI Feynman	find	Looks for symmetries and checks units first, then searches for the formula.
Cadabra2	derive	Does field-theory algebra with indices and tensors, as a physicist would on paper.
ModelingToolkit.jl	derive and solve	Turns an action for a system of parts into equations, simplifies them, and solves them.
FEniCS	solve	Solves fields on meshes that follow curved shapes, adding up the action piece by piece.
Devito	solve	Writes fast code for waves on regular grids, from equations written in ordinary notation.
DeepXDE	solve	Bends a neural network until it obeys the equations everywhere; no grid needed.
FiPy	solve	Moves quantities between cells so that nothing is created or lost.
Clawpack	solve	Follows sharp fronts and shocks without smearing them out.
Einstein Toolkit	solve	Evolves space and time themselves, as general relativity describes them.
QuTiP	solve	Follows quantum systems that exchange energy with their surroundings.
Modelica	solve	Solves machines and circuits built from connected parts.

Where to go next

• Hamilton's principle – the rule behind the derive arrow, with a plain-language counterpart for every page that carries equations.
• The walk through – the Principia Machina itself, from the beginning.
• The operator's guide to the tools – the same ground, with the rules.
• Back to the front page and the full survey.