mihenk
A touchstone for discovered equations. Before you interpret the law that PySINDy found in your data, mihenk checks whether it could be an artifact: of noise amplified by numerical differentiation, of the particular states your data happened to visit, of a library that was too small, or of analysis choices.
Mihenk (Turkish mihenk taşı, Azerbaijani mehək daşı, Persian mahak محک) is the touchstone used to test whether gold is real.
Install · Testing · Roadmap · Publishing · Changelog · Experiments
pip install "mihenk[pysindy]"
The core needs only numpy, scipy and sympy, runs on a CPU, and works offline. It needs no account, API or GPU.
Why
A SINDy fit always returns an equation. Whether that equation is the law of your system is a separate question, and the fit's R² does not answer it. Here is SINDy on clean data from the Hopf normal form, observed on its limit cycle:
true law: x' = x - y - x^3 - x*y^2
SINDy returns: x' = -0.6667 y - 0.3333 x^2*y - 0.3333 y^3 (derivative R² = 1.000)
On the circle x² + y² = 1, both equations (and x' = -y) fit perfectly. mihenk finds this from the data and the equation alone:
ERROR EQUIFINALITY [tier 0: data + equation]
where: x'
A sparser equation fits your data exactly as well (1 term instead of 3): x' = -y. On the
observed states some candidate terms are combinations of others, so the data cannot choose
between these laws.
fix: Collect data that leaves the current set of states (other initial conditions,
transients, perturbations) so the alternatives make different predictions.
Following the fix works: with transients from six starting points, SINDy recovers the true law and mihenk reports no findings.
Quick start
import pysindy as ps
import mihenk
from mihenk import synth
# example data with a known law; use your own x (T, n) and t (T,) instead
b = synth.simulate("lorenz", noise=0.05, seed=0)
x, t = b.xs[0], b.ts[0]
model = ps.SINDy(optimizer=ps.STLSQ(threshold=0.1))
model.fit(x, t=t, feature_names=["x", "y", "z"])
report = mihenk.scan_pysindy(model, x, t)
print(report.render_text())
report.save("mihenk_report") # then open mihenk_report/report.html
From the command line:
mihenk synth lorenz --noise 0.05 -o lorenz.npz # or bring your own .npz / .csv
mihenk fit lorenz.npz -o model.json --threshold 0.1 # PySINDy, polynomial library
mihenk scan lorenz.npz --model model.json --out report # exit status 1 on errors
--model also takes a plain text file, including PySINDy's own model.print() output:
(x)' = -9.999 x + 9.999 y
(y)' = 27.992 x + -0.999 y + -1.000 x z
(z)' = -2.666 z + 1.000 x y
What mihenk checks
| Finding | Tier | The failure it names | How it is tested |
|---|---|---|---|
EQUIFINALITY |
0 | Another law fits the data exactly as well | Relations among candidate terms on the observed states (SVD); sparsest equally good subset; one-term swaps |
DERIVATIVE_ARTIFACT |
0 | A term or coefficient produced by differentiated noise | Refit the equation's own terms with a derivative-free integral form and compare signs and values |
WEAK_TERM |
0 | The data can't tell the equation with a term from without it | F statistic for dropping each term, in the integral form |
UNDERFIT |
0 | A left-out term explains much of what the equation misses | Add each library term, and each term up to two polynomial degrees beyond the library (odd functions such as sin θ skip a degree) |
ROLLOUT_TRAP |
0 | Fits derivatives but does not reproduce the system when simulated | Short rollouts from held-out states; escapes; full rollouts with a twin started a hair away: if the twins stay together, full-length R² must hold, otherwise long-run spread and mean must |
PHYSICS_VIOLATION |
0 | The equation breaks physics you declare: it gains energy where the system dissipates it, or fails to conserve a conserved quantity | Derivative-free rate of change of H in the data vs grad H . f along the data, and H along the equation's own simulations |
KINEMATIC_MISMATCH |
0 | A declared pair such as θ' = ω does not hold in the data or in the equation (a lagging, scaled or biased sensor) | Derivative-free fit of p' = gain * v(t + lag) + offset; checks the discovered p' against v; tests whether the lag predicts the extra terms; refits the other equations with v corrected |
UNSTABLE_STRUCTURE |
1 | Terms come and go when the data are resampled | Bootstrap (trajectories, or blocks of one trajectory), refit through PySINDy |
FORKING_PATHS |
1 | The law depends on defensible analysis choices | Refit under other derivative methods and sparsity thresholds |
MISSED_TERM, SPURIOUS_TERM, COEF_ERROR |
2 | (synthetic data only) The discovered law against the true one | Term-by-term comparison |
Declaring kinematic pairs
Some variables are derivatives of others by definition: position and velocity, angle and angular velocity. mihenk cannot infer that from data, so you declare it:
report = mihenk.scan_pysindy(model, x, t, kinematics={"theta": "omega"}) # theta' = omega
On the command line, use mihenk scan ... --kinematic theta=omega, or put
"kinematics" in the bundle's meta. Without a declaration the check is not
assessed, and mihenk suggests pairs whose discovered equations look
kinematic. On the experimental pendulum it reports that the velocity signal
runs 0.85 ms late, and that the lag accounts for 98% of the extra terms SINDy
put into θ'.
Declaring physics
If you know the system loses energy, or conserves some quantity, say so:
report = mihenk.scan_pysindy(model, x, t, properties={"dissipates": "0.5*omega**2 - 64*cos(theta)"})
report = mihenk.scan_pysindy(model, x, t, properties={"conserves": "0.5*x - log(x) + 0.5*y - log(y)"})
On the command line, use --dissipates "H" or --conserves "H". H is an
expression in the state variables.
- For
dissipates, H needs to be only roughly right. An error in its conservative part averages out over a swing. - For
conserves, H must be accurate.
This check does not see a velocity lag, which changes which terms carry the
damping but not the energy budget. KINEMATIC_MISMATCH covers that.
Tiers describe what evidence a check needs:
- Tier 0: only your data and the equation. mihenk never calls the discovery tool; it refits only the coefficients of term sets the equation already has.
- Tier 1: a refit callable, which you get automatically with a PySINDy model.
- Tier 2: ground truth, which only synthetic data has.
Every report lists which checks ran, which were clean, and which were not assessed and why. A check that did not run is not a clean result.
Every threshold is named and can be overridden: mihenk scan ... --set weak_term_f=5, or mihenk.scan(..., thresholds=mihenk.Thresholds(weak_term_f=5)).
Validation
mihenk validate runs 18 synthetic cases built to show each failure, plus cases that must come out clean. mihenk validate --seeds 20 repeats them over 20 random seeds (different initial conditions and noise):
case passed warned (clean) wrong law, flagged
lorenz_clean 20/20 0/20 1/1
lorenz_noise1 20/20 3/20 3/3
van_der_pol_clean 20/20 0/20 -
duffing_clean 20/20 0/20 1/1
linear_clean 20/20 0/20 -
lotka_volterra_many 20/20 0/20 -
stuart_landau_many 20/20 0/20 -
stuart_landau_on_cycle 20/20 - 20/20
lotka_volterra_one_orbit 20/20 0/20 -
lotka_volterra_one_orbit_noisy 20/20 - 6/6
duffing_small_library 20/20 - 20/20
lorenz_noise5_low_threshold 20/20 - 20/20
van_der_pol_noise10 20/20 - 20/20
pendulum_kinematics_clean 20/20 0/20 20/20
pendulum_velocity_lag 20/20 - 20/20
pendulum_velocity_gain 20/20 - 20/20
pendulum_velocity_offset 20/20 - 20/20
linear_wrong_sign 20/20 - -
360/360 case runs pass over seeds 0-19.
Over these runs:
- Every one of the 171 times SINDy returned a wrong law, mihenk flagged it. That includes 25 runs in cases meant to be clean. In 20 of those, SINDy added a small θ term next to sin θ in the clean pendulum.
- In the 8 non-pendulum cases built to come out clean, none of the 155 correct-law runs received an error. 3 received a warning. All three are single mild-noise Lorenz trajectories lying close to a quadric surface, where a constant term appears in some refits. (Up to 0.2 this README said "9 cases" and "175 runs", a counting error; the results were the same.)
KINEMATIC_MISMATCHnever fired on the clean pendulum (20 of 20) and caught the lag, gain and offset every time (60 of 60). Its separate, pre-registered calibration/test split is in experiments/kinematic_synthetic.- 0.3 was checked against 0.2.0 run by run, on these seeds and on fresh seeds 20–29 (540 runs):
- no flag was lost;
- no run where SINDy found the true law gained a flag;
- 46 runs with wrong laws gained one, mostly the new long-rollout drift warning.
Experimental data
mihenk was tested on the Brunton lab's experimental single pendulum, with the
predictions committed before any fit
(protocol,
results). The reference law is
omega' = 64.22 sin(theta) - 0.0672 omega. Of seven predictions, 5 held, 1
partly held and 1 failed. In brief:
-
Large swings, informed library. SINDy found sin θ = 63.82, and mihenk left that term alone. It warned about extra terms in θ' (which should be exactly ω). Following that up showed the lab's filtered velocity signal lags the angle by 0.7–1.4 ms. That lag also cancelled most of the damping, which is why SINDy missed it.
-
Small swings. sin θ ≈ π − θ, so mihenk reported
EQUIFINALITYerrors and a sparser equally good law, as predicted. -
What mihenk missed:
- an equation that injects energy;
- a long rollout that drifts (R² 0.73);
- that a cubic library lacks sin θ. The first missing term is degree 5,
beyond
UNDERFIT's one-degree search, and within the observed swings the cubic is a fine law anyway.
These lead the roadmap.
mihenk 0.2 adds the check this test asked for, KINEMATIC_MISMATCH. Declare
θ' = ω and it names the lag directly: 0.85 ms, accounting for 98% of the
extra θ' terms. Its own test is a pre-registered synthetic sweep
(experiments/kinematic_synthetic):
- no false alarms in 80 runs;
- a lag of the experiment's size caught as an error up to 0.5% noise;
- a 2% gain error and a velocity bias caught in every run.
At 1% position noise it misses half of the lags. That is a stated power limit.
mihenk 0.3 adds the checks for the other misses: declared physics, twin long
rollouts, a two-degree UNDERFIT and centred relations. They were tested on
a pre-registered synthetic sweep
(experiments/physics_synthetic),
where 8 of 10 predictions held as committed, and one failure was a regression that was then fixed. On the pendulum:
- Now flagged: the drifting rollouts.
- Now correct: the small-swing relation reads θ + sin θ ≈ π.
- A correction to our own write-up: the energy check shows SINDy's law is not a net energy injector. It loses energy at 74% of the data's rate.
- Still out of reach: the degree-5 term is below this recording's noise.
Limits (read these)
What comes next is in ROADMAP.md.
- Research prototype (alpha). Thresholds are calibrated on mihenk's own toy systems and were not changed after the first experimental test. Treat them as starting points.
- mihenk rules out named failures. It cannot prove that an equation is the law. No findings means that no tested failure explains the equation.
- ODE models only, without control inputs. PDEs and weak-form libraries (
WeakPDELibrary) are not supported yet. - The polynomial library is assumed when you pass a text equation. With a PySINDy model, mihenk uses its real library (polynomial and Fourier libraries are tested).
- mihenk checks only physics you can see in the data. It does not know that a free pendulum must lose energy unless a check for that exists (see the roadmap).
- The integral form uses overlapping windows, so F statistics are screening statistics, not exact tests.
- For chaotic systems a low full-length rollout R² is expected. mihenk compares long-run spread and mean instead.
Repository layout
mihenk/ the package (core checks; adapters/ for PySINDy)
tests/ the test suite (python -m pytest -q)
docs/ INSTALL, TESTING, PUBLISHING, ROADMAP
experiments/ pre-registered tests: protocol, data, scripts and results per experiment
CHANGELOG.md what changed in each release
Provenance
With pip install "mihenk[provenance]", mihenk scan ... --daftar records each scan (inputs, thresholds, environment, findings) with daftar, so daftar diff can show what changed between two scans.
Related work
- Brunton, Proctor & Kutz (2016), PNAS: SINDy.
- de Silva et al. (2020) and Kaptanoglu et al. (2022), JOSS: PySINDy.
- Reinbold, Gurevich & Grigoriev (2020/2021): integral (weak) formulations, and ensembles that flag missing or spurious terms.
- Hauger, Scholl & Kutyniok (2024): robust identifiability for symbolic recovery of differential equations.
License
Apache-2.0. Author: Aslan Satary Dizaji.
Metadata
Release files for mihenk 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mihenk-0.3.0.tar.gz | 66.1 kB | Without provenance | Details for mihenk-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mihenk-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for mihenk-0.3.0-py3-none-any.whl |
Total release size: 128.1 kB
Release files / mihenk-0.3.0.tar.gz
| Download URL | mihenk-0.3.0.tar.gz |
|---|---|
| Size | 66.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ea556b989d02bce715b915e5b5fad36e6a2a980d0be9ad68c70085fd3df505be
|
|
BLAKE2b-256 checksum How to use checksums |
42afdd2c8acd234677d30c4a1d805cd2a754d329568d367f3124207efcd87cc2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.5
|
Release files / mihenk-0.3.0-py3-none-any.whl
| Download URL | mihenk-0.3.0-py3-none-any.whl |
|---|---|
| Size | 62.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4de9c614731ffdd3b0671dae7580c8fda1f28487bf4fa73c976070e4a450e2e1
|
|
BLAKE2b-256 checksum How to use checksums |
f358449730563a85089549381c21218718af79d0f7682bff1bd16a01d615f372
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.5
|
Security for mihenk 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.