8.6 KiB
pplus-library
Programming+ takes a procedure from an idea to Mojo to the machine. pplus-library is its ground truth: the routines a program can use by name, the Mojo programs and stored compiler answers the engines are held to, and the regression programs they must run as written. The engines and the tools that check all of this live in pplus-core, which pins this repository as its submodule library/; pplus-web, the site, gets it through core.
- Who it is for: anyone adding a routine to Programming+, a question about the Mojo compiler, or a program the engines must handle, and anyone who wants to see what the engines are tested against.
- Status: in development, with no tagged release; pplus-core pins it by commit (CHANGELOG.md). Nothing here runs on its own.
- Try it and run its checks: from a pplus-core checkout,
pixi run library-check(Checking it). - Report a problem: SECURITY.md says where to send a report and what counts as a security problem; CONTRIBUTING.md says what makes a good bug report.
Programming+ works in five notations:
- lingo: steps in plain English that a reader can run.
- matho: equations written in LaTeX.
- pseudo: pseudocode precise enough to run, prove and translate; every translation goes through it.
- speco: a specification to prove against: what a routine requires and ensures, and what each loop keeps.
- Mojo: Modular's programming language, pinned to version 1.2.0. Programming+ writes Mojo from pseudo, steps through it, and asks the real compiler about it.
This repository holds three kinds of material:
- Verified routines (
modules/), written once in pseudo and used by name withUSE. - 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 program we wrote and every harvested program that runs (the compiler's own diagnostic tests are asked only on request, and most have no stored answer). - Pseudo programs (
pseudo/): regression programs with what each must print, stop with or be refused for, and the prover's soundness regressions.
Verified routines
Each routine is written once in pseudo, and pixi run library-check checks it in every way a tool here can. The cases run. The prover proves every obligation, or the check is recorded open and the routine's comment says which obligation and why. The fuzzer finds no failure in the inputs it generates (STATUS.md gives the count for each routine). The Mojo generated from the pseudo prints the same results, or results within 1e-9 relative where the compiler's std.math rounds differently. Every reference implementation agrees with the pseudo on the cases: Python and Mojo for every routine, C for a few, and a second level of care or optimization for some. Where one says something, a Dafny transcription of the method verifies over exact numbers.
A program uses a routine by name. A run steps over it; to step through a routine itself, open it from the site's library page, which opens it in the Bridge.
USE md
DECLARE R : FLOAT <- 1.5
OUTPUT LennardJones(R, 0.238, 3.4), " ", MinimumImage(2.3, 1.0)
prints 17380.997888282014 0.2999999999999998 (pixi run cli run <file> in pplus-core).
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/ programs that test core's Mojo interpreter, not shipped (new-stress): mostly realistic programs, and a few that the compiler must reject, for the checker
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, or a `// STOPS:` or `// ERRORS:` line says how its run must stop or how many errors the checker must report
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, stated error below 1.5e-7) |
STATUS.md is the current state of every check.
Checking it
From a pplus-core checkout (git clone --recurse-submodules; the library is its submodule library/), with pixi, which brings the pinned Mojo, Node and Python:
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: every program under pseudo/, and core's Mojo checker and interpreter held to godbolt's stored answers for the probes, exercise, stress, manual and Mojo Quest programs
The Dafny proofs run only after pixi run dafny-fetch (once); without it their stored verdicts are compared. 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 computes what the pseudo computes with the language's plain operations (for PairDistance it takes one three-way hypot, or a square root of the sum of squares, where the pseudo nests HYPOT, so it carries a tolerance); 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 difference between those two levels shows up; flags that allow reordering, such as -ffast-math, are not tried.
Read AGENTS.md before adding or changing a routine.
License
Copyright 2026 Scientific Computing Studio, LLC, under the Apache License 2.0 (LICENSE.md); NOTICE.md has the notices and a disclaimer of affiliation with Modular, and THIRD_PARTY.md lists what is not ours and its licenses.