Start pplus-library: 16 verified routines in six modules

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
This commit is contained in:
alexmandClaude committed 2026-10-05 11:58:22 +00:00
commit df12b2a008
103 files changed
+3025

No files matched your search

+54
View File
@@ -0,0 +1,54 @@
# pplus-library
Verified routines for Programming+, written once in pseudo and checked at every level: the cases run, the prover proves the contracts, the fuzzer finds no failure, the generated Mojo prints the same, every reference implementation (Python, C, Mojo, at more than one level of care or optimization) agrees with the pseudo on the cases, and, where it says something, a Dafny proof verifies the method over exact numbers.
A program uses a routine by name, and a run steps over it unless asked to step in:
```
USE md
DECLARE R : FLOAT <- 1.5
OUTPUT LennardJones(R, 0.238, 3.4), " ", MinimumImage(2.3, 1.0)
```
`USE md` brings in every routine of the module; `USE md.MinimumImage` brings in one. The prover uses each routine's REQUIRE and ENSURE lines at the call, so a program built from library routines is checked against what they promise, without proving them again.
This repository is content. Its checks are pplus-core's tasks, and pplus-core pins it as the submodule `library/`. pplus-web gets it through core.
## What is here
```
modules/<module>/module.json the module's name, title and summary
modules/<module>/<routine>/routine.pseudo the routine: one FUNCTION or PROCEDURE, its contracts, USE lines for what it calls
modules/<module>/<routine>/routine.json name, summary, tags, sources, cases, references, proof
modules/<module>/<routine>/ref/<lang>/<level>.<ext> reference implementations
modules/<module>/<routine>/proof/<name>.dfy a Dafny proof, where one says something
modules/<module>/<routine>/golden/ stored answers of real tools (written by tools only)
status.json, STATUS.md what every check found (written by pixi run library-check)
```
| Module | What it holds |
|---|---|
| `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, within 1.5e-7) |
[STATUS.md](STATUS.md) is the current state of every check.
## Checking it
From a pplus-core checkout (the library is its submodule `library/`):
```bash
pixi run library-check # every check of every routine; writes status.json, STATUS.md and the Dafny goldens
pixi run library-emit # regenerate core's registry (src/library/generated.ts) from this checkout
pixi run library-verify-mojo # ask the pinned Mojo compiler about every Mojo reference (network)
```
## Levels
A reference's level says how it differs from the plainest translation of the pseudo: `plain` follows the pseudo step for step; other levels change the order of operations (`unrolled`, `fsum`), the method (`statistics`, `libm`, `two-rows`), or the arithmetic (`powers` against `multiply`). Each level is held to the pseudo's results exactly, or within a tolerance its `routine.json` states, and its note says why the tolerance is needed. C references run at `-O0` and `-O2`, so a level of optimization that changes an answer shows up.
Read [AGENTS.md](AGENTS.md) before adding or changing a routine.