README.md

---
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

[![Open in Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Open%20in-Spaces-blue)](https://huggingface.co/spaces/nickh007/physics-lint) ![Runs in browser](https://img.shields.io/badge/runs-in%20your%20browser-8A2BE2) ![Licence](https://img.shields.io/badge/licence-Apache--2.0-green) ![Tests](https://img.shields.io/badge/tests-35%20passing-brightgreen) ![Upload](https://img.shields.io/badge/data%20leaves%20your%20browser-never-brightgreen)

📖 **[Documentation site](https://nickharris808.github.io/physics-lint/)** — 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**](https://huggingface.co/spaces/nickh007/physics-lint)
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:

```bash
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:

```bash
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](https://chipletos.com).

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

## Related

- [`sparam-lint`](https://github.com/nickharris808/sparam-lint) — the CLI behind tab 1
- [`maxwell-lint`](https://github.com/nickharris808/maxwell-lint) — the ceiling test behind tab 2
- [`screening-ceiling`](https://huggingface.co/datasets/nickh007/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`](https://github.com/nickharris808/sparam-lint) | Is an S-parameter model physically possible? Five laws + a negative control. |
| [`maxwell-lint`](https://github.com/nickharris808/maxwell-lint) | Does a coupling extractor predict impossible physics? Screening ceiling k ≤ 1. |
| [`abstain-bench`](https://github.com/nickharris808/abstain-bench) | Does a model know when to shut up? Abstention recall, never pooled with accuracy. |
| [`sparam-conformance`](https://huggingface.co/datasets/nickh007/sparam-conformance) | 11 labelled networks with verified ground truth. Grades the graders. |
| [`screening-ceiling`](https://huggingface.co/datasets/nickh007/screening-ceiling) | A certified impossibility result + 27 counterexamples. Zero-dependency verifier. |
| [`physics-lint-action`](https://github.com/nickharris808/physics-lint-action) | The same checks, in your CI. |
| [`physics-lint-mcp`](https://github.com/nickharris808/physics-lint-mcp) | A physics oracle your AI agent can call. |
| [**Try it in your browser**](https://huggingface.co/spaces/nickh007/physics-lint) ← 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](https://chipletos.com)**.

## 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`](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`](CITATION.cff) is machine-readable; GitHub renders a “Cite this repository” button from it.