Principia: turning a local dataset into an inspectable scientific Rule

What Principia is for, and who it is not for

Bring a research goal and a local dataset. That is the opening instruction in the README, and it defines the audience precisely: someone who already has measurements and wants to know whether a compact, interpretable relationship explains them. Principia is not a search engine for papers and it is not a hypothesis generator that works from text alone. The workspace connects literature Principles, which supply scientific context, to executable analysis run over your own files.

The output is deliberately constrained. The README describes the result as a scientific object you can examine, and warns that a strong fit alone does not establish a mechanism. Known identities, empirical relationships and tentative interpretations each keep their own evidential scope. A dataset may produce observations without any Rule that passes the available checks. That last sentence is the honest part of the pitch, and it is the reason the tool suits a group that wants a record of what failed as much as what worked.

Anyone looking for a system that outputs a finished claim should look elsewhere. The five demo projects span atomic sensing, seismology, particle physics, thin-film metrology and human movement, and the README frames them as illustrations of different kinds of useful scientific output rather than evidence that every recovered relationship is a new law of nature.

How a dataset becomes a Rule: the four stages

The README lays out four stages, and each one produces something you can open.

Inventory and understand reads supported files, profiles measurements, and connects variables to the research goal and the scientific context. What you can inspect at this point is the source inventory, the formats, the units, the coverage and the interpretation. Units matter here: the Rydberg demo reports field amplitude in V/m and the earthquake demo works on a retained `ml` catalog subset, so a unit mismatch between your files and your goal surfaces early rather than at fit time.

Generate and evaluate proposes candidate expressions, fits them on development data, and uses validation evidence to compare alternatives. The inspectable artifacts are the executable expressions, the fitted parameters, the baselines and the candidate tests. In the Rydberg project the fitted form is a square-root RF-power relationship, and the saved record carries the optical and ion readout errors against a development-mean baseline.

Challenge applies recorded held-out checks and evidence gates before promoting a relationship. Split definitions, errors, controls, failure reasons and limits of applicability all stay visible. This is where the seismology demo records its 18 development, 6 validation and 7 test days, and where its test normalized RMSE of 0.1267 sits next to the frozen linear baseline of 0.6584.

Synthesize and explore presents supported Rules alongside observations and relevant Principles in a saved study map. You get typeset equations, a plain-language interpretation, linked evidence and the underlying numerical records. A study map is the navigational object: from a promising relationship you move to the records that support it.

Installing Principia v1.4.2 and running a first discovery

The README points to the `Principia-v1.4.2/` directory as the source release, and the repository layout shows that directory at the top level next to `ASD-benchmarks/`, `global-cloud/`, `scenario/`, `assets/` and `LICENSE`. The README does not spell out a package manager, a container image, a port or a startup command, so the reliable first step is to clone the repository and enter the release directory rather than to guess an installer.

git clone https://github.com/pzqpzq/Principia.git
cd Principia/Principia-v1.4.2

After that, look at what the release directory contains before running anything. The README links its licence badge to `./Principia-v1.4.2/core-v1.4.2/LICENSE`, which tells you the application code sits under `core-v1.4.2` inside the release folder.

cd Principia-v1.4.2
ls

The first real use does not require your own data or a model key. The five demo projects ship with saved maps, results, equations and packaged evidence, and the README states they open locally without the original datasets or an API key. Open one of those first. Work through the Rydberg project end to end: read the study map, open the extracted Rule, and follow the links down to the numerical records. That sequence tells you whether the evidence format is useful to you before you spend time on data preparation.

When you are ready to connect your own data, the README describes the flow as bringing a research goal and a local dataset, with configurable reasoning and vision models. Data and workspace state are kept separate, so repeated discovery does not require copying the source dataset into each project. The README does not document the model configuration keys or the accepted file formats, so those are the first things to look for in the release directory itself.

The demo projects show the ceiling and the floor

Read the five demos as a spread rather than a scoreboard, because they are not measuring the same thing.

The ATLAS transverse momentum project recovers a parameter-free vector identity, `p_T = sqrt(p_x^2 + p_y^2)`, with a corresponding direction check across 78,227 events in two held-out period files and a 99th-percentile relative magnitude error of about 1.17e-7. That is a representation consistency check. It confirms the pipeline handles known geometry correctly. It is not a discovery.

The Rydberg calibration is closer to the intended use. Field amplitude follows a square-root RF-power form, `E_r(P) = b_r + kappa_r * sqrt(P)`, with held-out RMSE of 0.0825 and 0.0923 V/m across optical and ion readouts, more than 92% below their development-mean baselines. The stated scope is narrow and worth reading twice: only two held-out power settings per readout, and both readouts share the same RF chain. A calibration curve with two held-out points is a thin validation set.

The Hafnia wafer project shows the floor. A spatial relationship connects measured thin-film thickness with position on the wafer, with held-out normalized RMSE of 0.7471, which is 41.1% below a constant baseline. The README says this is a fit for the measured specimen and that transfer to another wafer remains untested. A 41% improvement over predicting a constant is real but modest, and the untested transfer is the part that decides whether it matters.

The walking dynamics project is the clearest statement of limits: contact moment is reconstructed from normal load and pressure-center displacement, and the README calls it an executable force-plate consistency relationship under the recorded coordinate convention, not evidence of a new biological mechanism.

Where Principia stops: forecasting, transfer and format coverage

The earthquake project is the sharpest limitation in the whole README. A one-parameter exponential describes conditional magnitude-exceedance fractions, `S(M) = exp[-beta(M - 2.5)]`, and the validation is unusually well described: 18 development, 6 validation and 7 test days, with test normalized RMSE of 0.1267 against 0.6584 for the frozen linear baseline. Then the scope line: restricted to the retained `ml` catalog subset, and it does not predict event times or locations.

That is not a caveat bolted on at the end. It is the boundary of the method. Principia finds relationships inside a dataset you already have. If your research question is forward-looking in time or space, the fitted Rule will not answer it, and the demo is honest enough to say so about its own strongest-looking result.

The second limitation is transfer. The hafnia fit is explicitly for the measured specimen, with transfer to another wafer untested. Nothing in the README claims a Rule extracted from one instrument, wafer or cohort carries to the next. The Rydberg scope note about a shared RF chain points at the same issue from the other direction: a shared chain can make two readouts look like independent confirmation when they are not.

The third limitation is coverage. The inventory stage reads supported files, and the README does not enumerate which formats are supported. If your data lives in a proprietary binary or a format the inventory stage cannot profile, the pipeline stops at stage one. Check that before planning around it.

How Principia differs from symbolic regression and from LLM agent frameworks

The obvious comparison is a symbolic regression library such as PySR or a genetic-programming search over expressions. Both fit candidate formulas to data and both return equations. The difference is what surrounds the fit. A symbolic regression run returns a Pareto front of expressions ranked by error and complexity, and the scientific context lives in your head. Principia attaches literature Principles to the goal, records the split definitions, keeps the baselines, and writes failure reasons into a study map alongside the surviving Rule. The README's framing, that unsuccessful candidates remain part of the study record, is the design decision that separates the two.

The second comparison is an LLM agent framework that drives a research loop. Those typically orchestrate tool calls and produce a narrative report. Principia produces a typed record: executable expressions, fitted parameters, calibration results, validation decisions and a stated scope, connected in a map. The trade-off is that Principia is narrower. It will not browse for new literature, design an experiment or write your paper. It reads supported files, fits, challenges and records.

There is also a cost difference that follows from the design. An agent framework spends tokens on orchestration. Principia spends them on candidate generation and evaluation, which is why the demo projects were analyzed with a named model and why the packaged evidence opens without one. The saved maps are static artifacts, not a live service.

Maintenance, licensing and what a fork would cost you

The repository is not archived. The last push was on 2026-09-15, two days before this writing, and the release list shows three builds on 2026-08-23: global-20260823-b57bea97a4cf, global-20260823-b0c8caa097b2 and global-20260823-3069b0d0b260. The release names carry commit-like suffixes rather than semantic versions, which suggests automated or date-driven publishing rather than a hand-curated changelog. The README itself refers to v1.4.2 and links to v1.4.1, so the documentation and the release tags use different naming schemes. Expect to reconcile those yourself.

Licensing is the part to read carefully, and this is not legal advice. The repository root carries an Apache-2.0 LICENSE, and the GitHub metadata for the project lists Apache-2.0. The README's badge, however, points at `./Principia-v1.4.2/core-v1.4.2/LICENSE` and labels it MIT licensed application. Two different licences across two different scopes is a normal arrangement, but it means the Apache-2.0 label on the repository does not by itself tell you the terms for the application code you would actually run and modify. Read both files before you build on either.

Upgrade cost is low if you treat the demo maps as your regression test. They open without datasets or an API key, so after pulling a new release you can reopen a saved project and check that the study map, the equations and the evidence links still render. That is a concrete check, and it is available to you today because the packaged evidence is self-contained. The part that will cost you time is the model configuration surface, which the README describes as configurable for reasoning and vision models but does not document key by key.

Editorial conclusion

Principia fits researchers who already own a dataset and want the fitted expression, the held-out checks and the failure reasons kept in one inspectable record. It is the wrong tool if you want event forecasts: the earthquake demo states plainly that it does not predict event times or locations, and the hafnia fit is for the measured specimen only. Before adopting it, verify three things in the repository: how the application is launched from the Principia-v1.4.2/ directory, which file formats the inventory stage accepts, and whether the Apache-2.0 root LICENSE actually covers the MIT-labelled application code. The demo maps are the cheapest way to see whether the evidence record matches how your group works.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. pzqpzq/Principia on GitHub
4. README
5. Releases