Files
pplus-library/README.md
T
alexmandClaude df12b2a008 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
2026-10-05 11:58:22 +00:00

3.2 KiB

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 is the current state of every check.

Checking it

From a pplus-core checkout (the library is its submodule library/):

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 before adding or changing a routine.