Verifies that physics simulations solve equations at the claimed order of accuracy using numerical convergence and conservation checks.
Also known as rcgiri-physics/physverify
- Stars
- 6
- Tools
- 2
- Downloads, 30 days
- 1,283
- Latest version
- 0.8.0
- Last commit
- Nov 15, 2026
- License
- MIT
What is physverify MCP?
physverify verifies that physics simulations solve equations at the claimed order of accuracy using numerical convergence and conservation checks. It exposes 2 tools, such as run_checks, confirm_claim.
Summary generated from the project's README
About physverify MCP server
Verifying that physics simulations solve equations at the correct order of accuracy is the primary function of physverify. This tool is designed for the computational physics community to ensure that numerical solutions for ODEs and PDEs meet their mathematical claims through convergence and conservation checks. It operates locally using Python and requires only NumPy to function.
Developers can use the scan command to perform a static analysis of their code, which flags issues like mismatched grid spacings, incorrect Runge-Kutta orders, or unit table dimension errors without executing the program. For active verification, the init and run commands allow users to create a specification and test a solver against an independent description of the physics. The server also provides specialized tools like check_tableau for analyzing Runge-Kutta coefficients and check_order for evaluating error against step sizes. While it works best for ODEs, it currently supports 1D PDEs and can be integrated into CI pipelines to catch defects during development.
What you can do with it
- 1Perform static code analysisScan a directory to find Runge-Kutta methods that do not match their stated order or identify near-miss physical constants.
- 2Verify an ODE solverInitialize a verification specification for a specific solver and run it against independent physics equations.
- 3Validate Runge-Kutta coefficientsCheck the order, stage order, and stability of a Runge-Kutta table using only its coefficients.
Written from the project's README. Every use case is checked against a quote from it.
How to install physverify MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall physverify MCP in Claude Code
$ claude mcp add physverify -- uvx physverify mcpInstall physverify MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"physverify": {
"command": "uvx",
"args": [
"physverify",
"mcp"
]
}
}
}Install physverify MCP in VS Code
.vscode/mcp.json
{
"servers": {
"physverify": {
"type": "stdio",
"command": "uvx",
"args": [
"physverify",
"mcp"
]
}
}
}Install physverify MCP in VS Code CLI
$ code --add-mcp '{"name":"physverify","type":"stdio","command":"uvx","args":["physverify","mcp"]}'Install physverify MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"physverify": {
"command": "uvx",
"args": [
"physverify",
"mcp"
]
}
}
}Install physverify MCP in Codex
$ codex mcp add physverify -- uvx physverify mcpInstall physverify MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.physverify] command = "uvx" args = ["physverify", "mcp"]
Install physverify MCP in Gemini CLI
$ gemini mcp add -s user physverify uvx -- physverify mcpInstall physverify MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"physverify": {
"command": "uvx",
"args": [
"physverify",
"mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for physverify 0.8.0 in an isolated container with no network and no keys. It answered and listed 2 tools.
physverify MCP tools 2
Read from the server with tools/listrun_checksRun physverify verification checks (manufactured solutions, order of convergence, invariants, limits, exactness) on physics simulation code. Takes spec files that define checks(); with no specs given, finds verify_*.py files under `project`. Returns a JSON report: per check family, label, status (PASS, EXACT, FAIL, INCONCLUSIVE, ERROR, SKIP), message, observed and expected order, step sizes and errors.
confirm_claimJudge one suspected defect with physverify confirm. Takes a claim file that defines CLAIM, control() and checks() with a reference written from the physics (docs/confirm.md), runs it in a fresh process and returns the verdict: confirmed, rejected or not decidable, with the reason and each check's status and message. Appends the result to a ledger file. Runs the code, so it needs trusted=true or the sandbox (PHYSVERIFY_REPO set).
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablercgiri-physics/physverify is public and reachablegithub.com/rcgiri-physics/physverify ↗Pass
- Package names this repository as its sourcephysverify names rcgiri-physics/physverify as sourcepypi.org/project/physverify/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for physverifypypi.org/project/physverify/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/rcgiri-physics/physverify ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from physverifyPass
- No critical advisory in the package or its dependencies2 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubphysverify
Checks that a simulation solves the equations it claims, at the order of accuracy it claims, not just that it runs.
physverify is actively evolving (v0.7.0), welcoming contributions and test cases from the computational physics community. Status: under active development and maintenance, tested on a growing corpus of public physics codes; releases come at milestones. Scope: numerical solutions of ODEs and PDEs (time integration, convergence, conservation), plus a few Monte Carlo checks. It needs only NumPy.
pip install physverify
physverify demo
The demo checks a correct solver (all checks pass), then the same solver with the damping 10% too large (all fail):
New to this? Start here walks through installation and a first check in about ten minutes, with a prompt to paste if you use an AI coding assistant.
Use it on your own code
- Any project, no set-up:
physverify scan PATHreads the code (it runs nothing) and flags Runge-Kutta methods that do not have their stated order (written as tables, as class attributes or as stages in code), grid spacings that do not match their grid, near-miss physical constants, undefined names and files that do not parse, NumPy/SciPy/Python features that have been removed, typo-like literals (1e0 - 5), unit tables with the wrong dimension, and inverse function pairs worth a round-trip test.scan --run(in the sandbox) adds probes that run the code. A clean scan says only that these patterns were not found; it is a quick first pass, not a bug finder. - An ODE solver:
physverify init verify_solver.py --solver mysolver --order 4writes a spec; fill in the equations (from the physics, not from your code) and runphysverify run verify_solver.py. - A Runge-Kutta table:
check_tableau(A, b, c, claimed=3)fromphysverify.butcherchecks its order, stage order and stability from the coefficients alone. - Suspected bugs from a review (yours or an AI's): turn each claim into a run against an independent reference and get a verdict; see Checking an AI code review.
- Errors you already have:
check_order(hs, errors, expected=2)gives PASS, FAIL or INCONCLUSIVE with a reason.
Run it in CI
A failed check fails the job, like a broken unit test (CI guide: options, pre-commit, pytest):
- uses: rcgiri-physics/physverify@v0.7.0
with:
specs: tests/verify_*.py
Getting started · Recipes · What a PASS means · Troubleshooting · API
Does it catch bugs?
Of 37 bugs seeded into five small solvers, it flagged 35 (plain "compare with one answer" tests: 27), with no false alarms. The bugs and checks were written by the same person, so this shows the tool works as designed, not how it does on other people's code. On public physics repositories, 74 defects were reported to authors; 14 of them were found by a physverify check as such, 11 by simply running the code, and the rest by the per-repository test scripts or by reading the code. physverify scan alone, with no script, now finds 18 of the 74, up from 2 in its first version, and found 7 new defects in the same repositories (which found what). In a pilot on 20 of the tested repositories (2026-11-08), an AI reviewer with a short prompt found 8 of 10 known defects where scan found 1, but raised alarms on 6 or 7 of 10 repositories tested clean, none of them a physics defect; checks run against the physics told the true claims from the false ones (Checking an AI code review). The counts describe that sample only and are not a bug rate. Details: results, and results/README.md to regenerate every table.
Limits
Works best for ODEs; PDEs only in 1D so far. Your code needs a way to add a source term, or a small wrapper that can itself be wrong. A PASS means these checks found nothing wrong; it does not prove the simulation correct, and it is only as independent as the reference you wrote: see What a PASS means.
Contributing, citing, licence
Help is welcome: a trial report on your own solver, seeded bugs written by someone other than the author, adapters, documentation. See CONTRIBUTING.md, the code of conduct, SUPPORT.md for help, SECURITY.md on running untrusted code, and AGENTS.md for AI assistants. To cite, use doi:10.5281/zenodo.23534512 or CITATION.cff. Changes: CHANGELOG.md; plans: ROADMAP.md. The methods are standard and other tools do parts of this, some better (NodePy for Runge-Kutta analysis); see related work and credits. MIT licence, copyright (c) 2026 Ram Chandra Giri.
physverify MCP questions
How do I add physverify MCP to Claude Code?
Run claude mcp add physverify -- uvx physverify mcp in your terminal. Add --scope user to make it available in every project.
How do I add physverify MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does physverify MCP provide?
It exposes 2 tools, including run_checks, confirm_claim.
What does physverify check?
It checks that a simulation solves the equations it claims at the correct order of accuracy, covering numerical solutions of ODEs and PDEs including time integration, convergence, and conservation.
Can I use it to scan my existing code?
Yes, the scan command reads your code without running it to flag issues like incorrect Runge-Kutta orders, mismatched grid spacings, or near-miss physical constants.
Does a PASS mean my simulation is perfect?
No, a PASS only means the specific checks performed found no errors; it does not prove the simulation is entirely correct.
What are the limitations of the tool?
It works best for ODEs, and PDE support is currently limited to 1D. Your code must also allow for adding a source term or include a small wrapper.