This file is for an AI assistant (Claude Code, Codex, Cursor, Copilot and others) that is asked either to check a project with physverify or to change physverify itself. People are welcome to read it too.
- Install into a virtual environment:
python -m venv .pv && . .pv/bin/activate && pip install physverify(on Windows.pv\Scripts\Activate.ps1). - Start with
physverify scan PATH(physverify 0.5.0 or newer). It reads the source and runs nothing, so it is safe on untrusted code. Exit code 1 means at least one WARN. physverify run,physverify smoke, the hook and the MCP server run the code. Use them only on code the user trusts, or inside the container insandbox/(seesandbox/README.md).- Write the reference in a spec from the physics: the README, the paper, a textbook. Never derive it from the solver under test, or a bug in the solver is copied into the reference and the check passes. Say where each equation came from.
- When a check fails, suspect the spec first: units, sign conventions, time origin, the step counts, CODATA edition.
docs/troubleshooting.mdanddocs/pitfalls.mdlist the mistakes that were made most often. In the corpus study, adapters written with an AI assistant were wrong about 28 times before they were right. - Report what was tested and what was not. A PASS is a bounded claim (
docs/assumptions.md). - Do not post issues, comments or pull requests on other people's projects without the user's explicit approval of the exact text.
Useful entry points: physverify init (a starter spec), physverify references (exact solutions), docs/recipes.md, examples/verify_damped_oscillator.py.
- Install with
pip install -e ".[dev]"and runpython -m pytest -qbefore and after a change. Slow tests are markedslow. tests/test_seeded_bugs.pyandtests/test_figures.pycompare with committed files inresults/; if a change alters them on purpose, runpython scripts/reproduce_all.pyand commit the new files.tests/test_docs_examples.pyre-runsdocs/examples/and compares withdocs/examples/output/.- The installed package (
src/physverify/) holds only the checks and uses only NumPy at import time; the benchmark lives inbenchmark/pvbench/and is not installed. - Keep the scope in
ROADMAP.md: deepen ODE/PDE time integration, convergence and conservation before adding new families. Statistical checks need a measured false-alarm rate. - Every message a check prints should say what was tested, in plain words. Match the style of the surrounding code: short docstrings that say where a rule came from.
- Never state a general bug rate for physics code from the corpus results; give counts within the stated sample only.
- Plain commit messages; follow
CONTRIBUTING.md.