Routines written once in pseudo and checked at every level, so programs can use them by name instead of rewriting and re-verifying them: - stats: Mean, Variance (two-pass) - numerics: KahanSum, LinearInterp, Trapezoid - align: LinearGapPenalty, AffineGapPenalty, MatchScore, NeedlemanWunschScore - md: LennardJones, LennardJonesForce, MinimumImage, PairDistance - seq: GCContent, HammingDistance - special: ErfApprox (Abramowitz and Stegun 7.1.26) Each has contracts, cases, reference implementations in Python, Mojo and (for the numerical ones) C at more than one level, and nine have a Dafny proof over exact numbers. status.json and STATUS.md are written by pplus-core's library-check: every check passes or is open/unverified as listed there. The Mojo references still need the pinned compiler's answers (library-verify-mojo, network). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
31 lines
3.1 KiB
Markdown
31 lines
3.1 KiB
Markdown
# AGENTS.md
|
|
|
|
Rules for adding or changing a routine of pplus-library. The checks are pplus-core's tasks: run them from a core checkout, where this repository is `library/`.
|
|
|
|
## The gate
|
|
|
|
```bash
|
|
pixi run library-check # in pplus-core: no check may fail
|
|
pixi run library-emit # then core's registry, committed in core
|
|
```
|
|
|
|
**A change is finished when `library-check` reports no failing check and `STATUS.md` shows what you expect.** A check may be `open` (the prover could not finish an obligation), `skipped` (a tool is missing, or core's Mojo interpreter declines a construct) or `unverified` (no stored compiler answer for this exact text yet); none of those is a failure, and each is listed in your summary.
|
|
|
|
## Hard rules
|
|
|
|
1. **One routine per file.** `routine.pseudo` holds USE lines and one FUNCTION or PROCEDURE, named as `routine.json` names it, and nothing else. A helper is a routine of its own, brought in with USE. That way every function in the library is checked on its own and appears once in generated Mojo.
|
|
2. **The pseudo is the specification.** The cases' results come from running the pseudo; every reference implementation is held to them. Never change a case's expected value by hand: `status.json` records it from the run.
|
|
3. **Do not edit generated files.** `status.json`, `STATUS.md` and everything under `golden/` are written by tools. A Mojo answer comes only from `pixi run library-verify-mojo`; a Dafny verdict only from `library-check` with the pinned Dafny.
|
|
4. **Contracts the prover can hold.** REQUIRE everything the routine needs. Write an ENSURE when the prover proves it (whole numbers, comparisons, lengths); a claim about the value of FLOAT arithmetic belongs in the Dafny proof over exact numbers, because rounding is opaque to the prover. An obligation left open is explained in the routine's comment (see `special.ErfApprox`).
|
|
5. **Every tolerance is explained.** A reference held to the pseudo within `rel` or `abs` says in its note why the answers differ (a different order of additions, a different method, an approximation's stated bound).
|
|
6. **Cite the method.** `sources` names where it comes from: a paper with its DOI, a textbook and section, a manual page.
|
|
7. **No new dependencies.** Python references use the standard library; C references use the C standard library and `-lm`; Mojo references use the standard library of the pinned Mojo.
|
|
8. **US English**, plain sentences, in comments, notes and summaries.
|
|
|
|
## Adding a routine
|
|
|
|
1. Make `modules/<module>/<kebab-name>/` with `routine.json` (name, summary, tags, sources, cases) and `routine.pseudo`.
|
|
2. Add references under `ref/<lang>/<level>.<ext>`: the function only, named in snake case after the routine (`LennardJones` is `lennard_jones`). A list parameter is a list in Python and Mojo, and an array and its length in C. Add each to `routine.json` with its note and any tolerance.
|
|
3. Add a Dafny proof under `proof/` when there is something worth proving over exact numbers, and name it in `routine.json`.
|
|
4. Run `pixi run library-check` and `pixi run library-emit` in core; commit this repository, then core with the new pointer and registry.
|