This commit is contained in:
commit
568474d52f
1591 files changed
+528213
No files matched your search
@@ -0,0 +1,99 @@
|
||||
# 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](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](#checking-it)).
|
||||
- **Report a problem:** [SECURITY.md](SECURITY.md) says where to send a report and what counts as a security problem; [CONTRIBUTING.md](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 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 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](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](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](https://pixi.sh), which brings the pinned Mojo, Node and Python:
|
||||
|
||||
```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)
|
||||
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](AGENTS.md) before adding or changing a routine.
|
||||
|
||||
## License
|
||||
|
||||
Copyright 2026 Scientific Computing Studio, LLC, under the Apache License 2.0 ([LICENSE.md](LICENSE.md)); [NOTICE.md](NOTICE.md) has the notices and a disclaimer of affiliation with Modular, and [THIRD_PARTY.md](THIRD_PARTY.md) lists what is not ours and its licenses.
|
||||
Reference in new issue
Block a user