README.md

metadata

title: physics-lint
emoji: ⚡
colorFrom: indigo
colorTo: red
sdk: static
app_file: index.html
pinned: false
license: apache-2.0
short_description: Is your S-parameter model physically possible?
tags:
  - physics
  - electromagnetics
  - rf
  - signal-integrity
  - verification
  - eda

physics-lint

📖 Documentation site — the portfolio narrative, the concepts, a full walkthrough, and what all of this proves (and does not).

Is this model physically possible? Three checks, three tabs, no install.

Why this exists

Every RF and signal-integrity engineer has a folder of .s2p files from vendors, simulators and measurements. Some of them describe networks that cannot exist — they produce power from nothing, respond before they are excited, or present negative resistance. Those files go into simulators, and the simulators believe them.

The same problem shows up one level down, in the extractors that generate the models: a learned or approximate coupling extractor can predict anti-screening, where adding a grounded conductor between two others increases their coupling. No passive arrangement of conductors in a linear medium can do that, and no accuracy metric will tell you it happened.

This Space lets you check both in a browser, in about thirty seconds, against nothing but open-source code.

30-second quickstart

Nothing to install — open the Space and do these three things in order:

1. On the S-parameters tab, press run the negative control. Five networks built to violate one law each are all rejected, which is what makes the next step mean anything.
2. Pick active_gain from the examples dropdown. It fails passivity and energy conservation, and says why in plain language.
3. Pick ferrite_isolator. It fails reciprocity — and that one is correct behaviour, because the device's medium is non-reciprocal. Reading those two failures differently is the whole skill this Space is trying to teach.

Then upload one of your own .s1p–.s4p files. It is parsed in your browser; nothing is uploaded anywhere.

What is in it

1 · S-parameters. Upload a Touchstone file or pick an example, and see the five laws every passive linear network must obey — passivity, reciprocity, energy conservation, positive-real input impedance, non-negative group delay — each with the measured value that decided it.

Two examples worth clicking. active_gain is the passive line with 3× gain bolted onto the through path; it fails passivity and energy conservation and says so in plain language. ferrite_isolator is physically real hardware that legitimately fails reciprocity, because its medium is non-reciprocal — the check firing there is a true positive for the law and a false alarm for the device, and any honest tool has to let you tell those apart.

There is also a button marked run the negative control. A checker reporting 100% compliance is indistinguishable from one that has quietly stopped working, so the battery is run against networks built to violate each law and against one built to satisfy them all. Both directions are shown, because a law that stops rejecting violators has gone blind and a law that starts rejecting good networks has gone hysterical.

2 · Coupling extractors. Run four reference extractors against the screening ceiling k = |C_full|/|C_iso| ≤ 1 on a layout you configure:

Model	pairs k>1	max k	verdict
monopole_closure	0/56	0.7180	✅ admissible
born_second_order	40/56	1.7219	❌ impossible
mean_field	0/56	0.3153	✅ admissible
pairwise	0/56	1.0000	✅ admissible

born_second_order is a truncated perturbation series — the thing a competent engineer reaches for when a full solve is too slow. It is not a strawman, and it predicts impossible physics on most pairs. Meanwhile pairwise sits exactly on the ceiling: admissible and maximally wrong, since it assumes no screening at all.

3 · The certified bound. Four sliders over a four-parameter family of layouts, and a live evaluation against a machine-certified bound:

✅ inside the certified bound

  worst-pair k               0.865716299079
  certified bound            0.909090909091
  margin                    +0.043374610012
  pairwise over-predicts by  15.5113%

Interval branch-and-bound has certified that every layout in that family satisfies k ≤ 0.909090909091 — 237,490 certified leaves, zero failure regions, full volume coverage. The consequence is that a pairwise extractor over-predicts the worst coupling by at least 10% on every member of the family. Not on average. Always.

Move the sliders and try to find a counterexample. Sampling cannot prove the bound; it can only refute it, and that is exactly what a skeptical reader should be handed.

How it runs

The Space is static: index.html boots Gradio Lite, which runs CPython in your browser through WebAssembly and installs the two checkers from the wheels bundled beside it. Nothing is uploaded and no server executes your files.

To run the same app as a normal local server instead:

pip install -r requirements.txt
python app.py

Opens on http://127.0.0.1:7860.

The demo logic lives in demo_logic.py, which imports no UI framework, so the numbers shown in the browser are produced by exactly the code the test suite exercises:

python -m pytest tests/ -q     # 35 passed

Scope, honestly

Physical admissibility is not accuracy. A perfectly passive model of entirely the wrong structure passes every law here. These checks are necessary conditions, never sufficient ones — each tab says so on the page, not just in this file.

The certified bound is a theorem about a monopole-closure model, not about Maxwell. The closure-versus-solver gap is additive and disclosed and is never absorbed into the bound. Every number in this Space is computational; none is measured.

Reference coupling models are thin-wire forms in a homogeneous medium — enough to demonstrate the ceiling and sanity-check an extractor's sign and magnitude, not a substitute for a field solve.

Troubleshooting

The page sits on "Loading…" for a while on first visit — Gradio Lite is downloading a CPython build and the two wheels into your browser. It is a few tens of megabytes once, then cached. Nothing is being uploaded in the other direction.

It never finishes loading — the version of Gradio Lite is pinned in index.html for exactly this reason. Newer releases currently fail to resolve their own huggingface-hub dependency inside Pyodide, which shows up as a micropip error in the browser console rather than as anything on the page. If you fork this Space, keep the pin or verify the newer one boots.

Your file uploads but nothing appears — check the extension. The upload accepts .s1p through .s4p, and Touchstone encodes the port count there; a file named .txt cannot be parsed no matter what is inside it.

A model you believe is fine fails reciprocity — if it is a ferrite, isolator or circulator, that is correct. The medium is non-reciprocal, so S ≠ Sᵀ is the device working. ferrite_isolator in the examples dropdown is there to make that visible before you hit it on your own data.

The certified-bound tab never shows a violation however you move the sliders — that is the expected outcome; the bound is a theorem over the whole box. The sliders are there so a skeptical reader can try to refute it rather than take our word, and failing to find one is the honest result.

Running locally, python app.py prints nothing and appears to hang — it is stdout buffering, not the app. Use python -u app.py, or wait for the Running on local URL: http://127.0.0.1:7860 line to flush.

Privacy

Everything runs in the Space process. Uploaded files are parsed in memory and are not stored, logged or transmitted anywhere.

Where the closed core is

These tools grade a model. Producing one that is passive by construction — so it cannot fail these laws whatever its parameters — and accurate at speed in the many-body regime, with calibrated abstention and a fail-closed signoff certificate, is ChipletOS.

If this Space keeps failing your vendor models, that is the conversation to have.

Related

• sparam-lint — the CLI behind tab 1
• maxwell-lint — the ceiling test behind tab 2
• screening-ceiling — the certified regions and counterexamples behind tab 3, with a zero-dependency verifier

The rest of the toolkit

Eight artifacts that answer one question in different places: is this model physically possible? Each is a grader — it can tell you a model is wrong; none can tell you one is right.

sparam-lint	Is an S-parameter model physically possible? Five laws + a negative control.
maxwell-lint	Does a coupling extractor predict impossible physics? Screening ceiling k ≤ 1.
abstain-bench	Does a model know when to shut up? Abstention recall, never pooled with accuracy.
sparam-conformance	11 labelled networks with verified ground truth. Grades the graders.
screening-ceiling	A certified impossibility result + 27 counterexamples. Zero-dependency verifier.
physics-lint-action	The same checks, in your CI.
physics-lint-mcp	A physics oracle your AI agent can call.
Try it in your browser ← you are here	All three checks, no install, runs client-side.

These tools grade a model. Producing one that is passive by construction — so it cannot fail these laws whatever its parameters — and accurate at speed in the many-body regime, with calibrated abstention and a fail-closed signoff certificate, is the commercial core: ChipletOS.

Licence

Apache-2.0.

Contributing

One non-negotiable rule here: the numbers on the page must come from demo_logic.py, which imports no UI framework and is exercised by the test suite. CONTRIBUTING.md has the detail. Each sibling repository states its own, and they differ — that is deliberate, and it is why each is trustworthy on its own terms.

Citation

CITATION.cff is machine-readable; GitHub renders a “Cite this repository” button from it.