pplus-library

The ground truth of Programming+: everything the engines in pplus-core are held to, and nothing they run. It holds three kinds of material:

  • Verified routines (modules/), written once in pseudo and used by name with USE.
  • The Mojo corpus (mojo/): the pinned Mojo version, material harvested from Modular's repositories at pinned commits, our own probes, exercise programs and stress programs, and godbolt's stored answer for every one of them.
  • Pseudo programs (pseudo/): regression programs with the output they must print, and the prover's soundness regressions.

The tools that check and regenerate all of it live in pplus-core, which pins this repository as the submodule library/. pplus-web gets it through core.

Verified routines

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.

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)

mojo/pin.json                               the Mojo version, the godbolt compiler, each source repository and its ref (you edit this)
mojo/mojo.lock.json                         what each ref resolved to: commit, zip sha256 (written by mojo-fetch, mojo-harvest)
mojo/corpus/                                processed material from Modular's repositories, each item with its provenance (mojo-harvest)
mojo/probes/                                one question about the pinned compiler per program (new-probe)
mojo/local/                                 the Mojo of each catalog exercise, shipped in the app (new-exercise)
mojo/stress/                                realistic programs that test core's Mojo interpreter, not shipped (new-stress)
mojo/golden/                                godbolt's answer for each exact source, and STATUS.md, every item's verdict (mojo-verify, mojo-status)
syntax/mojo.xml                             the pinned Mojo's words as a KDE syntax for Pandoc listings (mojo-emit)

pseudo/programs/<nn>-<name>.pseudo          regression programs; their `// EXPECT:` lines are the output each must print
pseudo/prover/<name>.pseudo                 prover soundness regressions: `// MUST-NOT-PROVE: <kind>@<line>` or `// RUN-STOPS: <kind>@<line>`
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)
pixi run mojo-status            # judge every Mojo corpus item from the stored answers, offline; writes mojo/golden/STATUS.md
pixi run mojo-verify            # ask godbolt about every Mojo program with no stored answer yet (network)
pixi run mojo-emit              # regenerate core's src/mojo/generated/ and this repository's syntax/mojo.xml, offline
npm test                        # core's tests, which run every program under pseudo/ and every Mojo program here

pplus-core's docs/mojo-corpus.md describes the Mojo corpus pipeline and how to move to a new Mojo version.

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.

S
Description
No description provided
Readme
3.6 MiB
0 Stars 1 Watchers 0 Forks
Languages
Mojo 90.5%
Dafny 6.1%
Python 2.8%
C 0.6%