From 7ddc62859703a65f68710ca9455af23df7a1c834 Mon Sep 17 00:00:00 2001 From: Alex Maldonado Date: Mon, 5 Oct 2026 12:06:41 +0000 Subject: [PATCH] Add USE and pin pplus-library: routines verified once, used by name Routines that many programs need (a mean, a gap penalty, the Lennard-Jones potential, the minimum image convention) were rewritten and re-verified each time, and there was no way to open one and see exactly what it does. They now live in pplus-library, pinned here as the submodule library/, and a program brings them in with USE. - USE module / USE module.Routine (pseudo-study resolveUses): each routine is studied once in its own file (its own USE lines resolved the same way, cycles refused) and handed to the checker as a library routine; unknown-library, unknown-routine, library-clash, use-place. - A run steps over a library routine (one step at the call, one at the return, none of its lines); a broken contract is reported at the call, naming the routine. The prover uses its REQUIRE and ENSURE at the call and does not prove it again; it is not a unit of the program. - pseudo-to-mojo writes each library routine the program calls once, dependencies first, labeled as coming from the library. - src/library: the registry USE reads, generated from library/ (scripts/library.mjs emit), so the site needs no files at run time. - scripts/library.mjs check: every routine at every level: structure, cases, prover, fuzzer, generated Mojo, each reference implementation (CPython; cc at -O0 and -O2; core's Mojo interpreter; the pinned compiler's stored answer) held to the pseudo's results, and the Dafny proof with the pinned Dafny. Writes library/status.json and STATUS.md. scripts/library_godbolt.py stores the compiler's answers (network). - pixi tasks library-check, library-emit, library-verify-mojo, library-harness; CI checks out the submodule and runs library-check. - Tests: tests/library.test.mjs, corpus 53-library; docs/library.md and a library section in trust.md. Gate: 332 pass; library-check: no failing check (16 routines; the Mojo references are unverified until library-verify-mojo runs on the network). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ --- .gitea/workflows/test.yml | 6 + .gitmodules | 4 + AGENTS.md | 3 +- README.md | 11 +- docs/library.md | 43 + docs/sync-coverage.md | 12 +- docs/trust.md | 14 + library | 1 + pixi.toml | 8 +- scripts/library.mjs | 460 +++++++++ scripts/library_godbolt.py | 58 ++ src/engines/pseudo/check.js | 5 +- src/engines/pseudo/interp.js | 8 +- src/library/generated.ts | 1703 ++++++++++++++++++++++++++++++++ src/library/registry.ts | 40 + src/library/types.ts | 70 ++ src/services/pseudo-study.ts | 71 +- src/services/pseudo.ts | 2 +- src/sync/pseudo-to-mojo.ts | 58 +- tests/corpus/53-library.pseudo | 12 + tests/library.test.mjs | 85 ++ 21 files changed, 2654 insertions(+), 20 deletions(-) create mode 100644 .gitmodules create mode 100644 docs/library.md create mode 160000 library create mode 100644 scripts/library.mjs create mode 100644 scripts/library_godbolt.py create mode 100644 src/library/generated.ts create mode 100644 src/library/registry.ts create mode 100644 src/library/types.ts create mode 100644 tests/corpus/53-library.pseudo create mode 100644 tests/library.test.mjs diff --git a/.gitea/workflows/test.yml b/.gitea/workflows/test.yml index 7e5827c..006ba11 100644 --- a/.gitea/workflows/test.yml +++ b/.gitea/workflows/test.yml @@ -11,7 +11,10 @@ jobs: test: runs-on: quarto-deploy steps: + # library/ is pplus-library, a submodule; tests/library.test.mjs needs it checked out - uses: actions/checkout@v4 + with: + submodules: recursive - name: Toolchain on the host run: | node --version @@ -23,3 +26,6 @@ jobs: run: | if command -v python3 >/dev/null; then python3 scripts/mojo/corpus.py status --strict else echo "python3 missing: corpus status skipped"; fi + # every library routine at every level the host has tools for (python3, cc); nothing may fail + - name: Library routines pass + run: node scripts/library.mjs check diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..c7d87d8 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,4 @@ +[submodule "library"] + path = library + url = ../pplus-library.git + branch = main diff --git a/AGENTS.md b/AGENTS.md index ae27d0b..686540e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ The full suite takes about two minutes. While iterating, build and run one file: ## Hard rules 1. **Core has no DOM.** What a program means is decided without a browser. A library module never touches `document`, `window`, `localStorage` or `navigator`, never imports one of the course's page widgets, and never imports from outside `src/`; `tests/boundary.test.mjs` holds it to that. The widgets (listed in that test) live beside the engines only so the course and pplus-web take them from one place. -2. **Do not edit generated files by hand.** `src/mojo/generated/*` and `syntax/mojo.xml` come from the corpus pipeline (`pixi run mojo-emit`, `mojo-status`, `play`). `mojo/corpus/` comes from `mojo-harvest`. `mojo/golden/` holds godbolt's answers and comes only from `mojo-verify`. +2. **Do not edit generated files by hand.** `src/mojo/generated/*` and `syntax/mojo.xml` come from the corpus pipeline (`pixi run mojo-emit`, `mojo-status`, `play`). `src/library/generated.ts` comes from `library/` (`pixi run library-emit`), and the library's `status.json`, `STATUS.md` and `golden/` from `pixi run library-check` and `library-verify-mojo`. `mojo/corpus/` comes from `mojo-harvest`. `mojo/golden/` holds godbolt's answers and comes only from `mojo-verify`. 3. **Do not edit a `.mojo` file's text unless the task needs it.** A stored godbolt answer is keyed by the whole source, header comments included, so any edit (even to a comment) makes the program unverified until it is asked again on the network. If you add or change one, say in your summary that it needs `pixi run mojo-verify-item '/'`. 4. **Never claim Mojo compiles, runs, or prints something without the real compiler's answer.** Mojo is pinned to 1.1.0. The checker may never report an error on a program the compiler accepts, and the interpreter must print exactly what godbolt printed or decline; `tests/mojo-check.test.mjs` and `tests/mojo-run.test.mjs` hold them to that. Every Mojo construct you write into core must pass `checkMojo`, and every standard-library name must exist in `src/mojo/generated/stdlib.ts` or `types.ts`. 5. **Never let the prover call something proved that a run breaks.** "Proved" must be a proof. A change to `src/engines/pseudo/logic.ts`, `solver.ts` or `vcgen.ts` keeps `tests/prover-soundness.test.mjs` and `tests/engine-solver.test.mjs` green, and a fact the prover assumes must hold for every value a run can produce, or be guarded by an obligation. When you find a soundness bug, add the program that shows it to `tests/prover/` with a `// MUST-NOT-PROVE:` (or `// RUN-STOPS:`) header first, see the test fail, then fix the rule ([docs/engines.md](docs/engines.md#soundness)). @@ -49,6 +49,7 @@ The full suite takes about two minutes. While iterating, build and run one file: | Realistic Mojo for the interpreter | `pixi run new-stress ""`, with the output you predict in `# expect-stdout:` lines | | A pseudo regression program | a file in `tests/corpus/` whose `// EXPECT:` lines are the output it must print | | A prover soundness regression | a file in `tests/prover/` whose `// MUST-NOT-PROVE: @` names an obligation a run breaks, or `// RUN-STOPS: @` where a run must stop | +| A verified routine others can USE | in pplus-library (`library/`), under its AGENTS.md; then `pixi run library-check` and `library-emit` here ([docs/library.md](docs/library.md)) | | A command | a task in `pixi.toml` and a row in the README's Commands table | | A language | a `LanguageService` (`src/common/types.ts`) in `src/services/`, registered in `src/services/index.ts` | diff --git a/README.md b/README.md index 2ed0308..a184449 100644 --- a/README.md +++ b/README.md @@ -7,13 +7,14 @@ pplus-core is the part of Programming+ that has to be right: the languages, the - **Verification:** the prover (`src/engines/pseudo/logic.ts`, `solver.ts`, `vcgen.ts`), sound and held to it by tests; the fuzzer (`src/common/fuzz.ts`); and a pinned Dafny (`scripts/dafny.py`). - **Stored answers:** the Mojo corpus (`mojo/`): material harvested from Modular's repositories at pinned commits, our own probes and programs, and godbolt's answers for every one of them (`mojo/golden/`). - **A workspace:** `src/common/workspace.ts` is one piece of work and everything its sources mean. pplus-web's session extends it. +- **A library:** pplus-library, the submodule `library/`: verified routines (statistics, numerics, alignment, molecular simulation, sequences) that a program brings in with `USE`, each checked at every level ([docs/library.md](docs/library.md)). - **A command line:** `pixi run cli check|run|prove|fuzz|translate `. Everything it says about Mojo is pinned to **Mojo 1.1.0** and checked against the real compiler on [Compiler Explorer](https://godbolt.org). ## Quick start -With [pixi](https://pixi.sh) (it brings the pinned Mojo, Node and Python): +Clone with the library submodule (`git clone --recurse-submodules`, or `git submodule update --init` in an existing clone). With [pixi](https://pixi.sh) (it brings the pinned Mojo, Node and Python): ```bash pixi run test # build, then every test @@ -46,6 +47,11 @@ Every command is a pixi task (`pixi task list` shows them with their description | **Dafny, pinned** ([scripts/dafny.py](scripts/dafny.py)) | | | `dafny-fetch` | Download the pinned Dafny into `.tools/`, checked by SHA-256 (network, once) | | `dafny` | Run the pinned Dafny with the arguments given, e.g. `pixi run dafny verify file.dfy` | +| **The library** ([docs/library.md](docs/library.md)) | | +| `library-check` | Check every library routine at every level; writes `library/status.json` and `STATUS.md` | +| `library-emit` | Regenerate `src/library/generated.ts`, the registry `USE` reads, from `library/` | +| `library-verify-mojo` | Ask the pinned Mojo compiler about every Mojo reference of the library (network) | +| `library-harness ` | Print the program a reference implementation is run as | | **Write content** | | | `new-exercise ` | Start an exercise whose Mojo lives in `mojo/local/.mojo` ([docs/exercises.md](docs/exercises.md)) | | `new-probe ` | Start `mojo/probes/.mojo`: one question about the compiler ([docs/mojo-corpus.md](docs/mojo-corpus.md)) | @@ -79,6 +85,7 @@ AGENTS.md rules for changing core (read first) src/ common/ the workspace, the problem catalog, the fuzzer, the run view's data, the language reference, the machine presets, the shared types + library/ the registry USE reads (generated from library/), and its types engines/pseudo/ the pseudo language and the prover (logic, solver, vcgen in TypeScript), and the course's page widgets for it (excluded from the build; see docs/engines.md) engines/asm86/ the x86-64 model machine, and the course's widgets that draw it (views, hwviews) @@ -89,6 +96,7 @@ src/ exercises/ one file per catalog problem curriculum/ a lesson corpus kept as an interpreter fixture syntax/mojo.xml the Mojo words as a KDE syntax for Pandoc (generated; pplus-web copies it) +library/ pplus-library, a git submodule: verified routines that programs bring in with USE tests/ node --test against dist/; corpus/ (pseudo programs), prover/ (soundness regressions) mojo/ the Mojo corpus: the pin and lock, harvested material, our programs, godbolt's answers scripts/ the tasks above; scripts/mojo/ is the corpus pipeline; dafny.py the Dafny pin; cli.mjs @@ -103,6 +111,7 @@ docs/ the documents below | [docs/engines.md](docs/engines.md) | The engines, the prover and its soundness, and how the course takes them | | [docs/trust.md](docs/trust.md) | Every verdict core produces: which tool earns it, what it means, and what it does not mean | | [docs/mojo-corpus.md](docs/mojo-corpus.md) | Writing Mojo of our own and moving to a new Mojo version | +| [docs/library.md](docs/library.md) | The library: USE, what each check of a routine means, and changing it | | [docs/exercises.md](docs/exercises.md) | Adding a catalog problem | | [docs/sync-coverage.md](docs/sync-coverage.md) | What each translator can say, written by the tests | | [docs/asm-coverage.md](docs/asm-coverage.md) | Which instructions compiled Mojo uses, against what the machine models | diff --git a/docs/library.md b/docs/library.md new file mode 100644 index 0000000..10fc5ea --- /dev/null +++ b/docs/library.md @@ -0,0 +1,43 @@ +# The library + +pplus-library (the submodule `library/`) holds routines written once in pseudo and checked at every level, so a program can use them by name instead of rewriting and re-verifying them, and a learner can open any of them to see exactly what it does. Core reads it through a generated registry (`src/library/generated.ts`, `pixi run library-emit`), so the site needs no files at run time. + +## Using a routine + +``` +USE md // every routine of the module +USE align.MatchScore // one routine +``` + +USE lines go at the top of a program. From then on a routine is called like the program's own: + +- **The checker** types each call against the routine's parameters. A program may not define a routine of the same name (`library-clash`); an unknown module or routine is an error at the USE line, with the names that exist (`unknown-library`, `unknown-routine`). +- **A run** steps over a routine: one step where it is called, one where it hands back, and none of its own lines (they belong to another file). Its contracts are still checked; a broken REQUIRE is reported at the call, naming the routine. To step through a routine, open it in the library. +- **The prover** uses the routine's REQUIRE as an obligation at each call and its ENSURE as a fact afterwards, the way it treats the program's own routines. It does not prove the routine again: the library did. +- **The Mojo translator** writes each routine the program uses once, before the program's own code, dependencies first, labeled as coming from the library. + +A routine file (`routine.pseudo`) holds USE lines and exactly one FUNCTION or PROCEDURE. A routine that calls another brings it in with USE, so every function in the library is checked on its own. + +## What "verified" means for a routine + +`pixi run library-check` runs every check and records what it found in `library/status.json` and `library/STATUS.md`: + +| Check | Passes when | Recorded as | +|---|---|---| +| structure | `routine.pseudo` defines exactly the routine `routine.json` names, and nothing else | pass, fail | +| pseudo | every case runs; its result is recorded and is what the references are held to | pass, fail | +| prover | every obligation of the routine is proved | pass; open (some not proved, none broken); fail (one broken) | +| fuzz | 300 generated inputs break no contract and stop no run | pass, fail, skipped | +| mojo | the Mojo generated from the pseudo checks, runs in core's interpreter and prints what the pseudo prints | pass, fail, skipped (a construct the interpreter declines) | +| a reference, per runner | `cpython`, `cc -O0`, `cc -O2`, core's Mojo `interpreter`, or the pinned compiler on `godbolt` prints the pseudo's results on every case, exactly or within the tolerance `routine.json` states | pass, fail, skipped (the tool is missing), unverified (no stored compiler answer for this exact program) | +| proof | the pinned Dafny verifies the proof file, or its stored verdict matches this exact text | pass, fail, unverified | + +A reference implementation is the function alone; the tool writes the program it runs as (the function plus a main that prints each case), and `pixi run library-harness ` prints it. A Mojo reference's answer from the compiler is stored in the routine's `golden/mojo-.json`, keyed by the SHA-256 of that program, by `pixi run library-verify-mojo` (network). A Dafny verdict is stored in `golden/dafny.json`, keyed by the proof's text and the Dafny version. + +What each check does not say is in [trust.md](trust.md#library-routines). + +## Changing the library + +1. Change pplus-library under its [AGENTS.md](../library/AGENTS.md): one routine per file, cases, references with their notes and tolerances, a Dafny proof where one says something. +2. In core: `pixi run library-check` (no check may fail), then `pixi run library-emit`. +3. Commit pplus-library; commit core with the new `library` pointer and the regenerated registry. `tests/library.test.mjs` fails while the registry is out of date with the checkout. diff --git a/docs/sync-coverage.md b/docs/sync-coverage.md index 543a753..3c07ec8 100644 --- a/docs/sync-coverage.md +++ b/docs/sync-coverage.md @@ -2,13 +2,13 @@ -Each translator in `src/sync/` is run over every exercise with pseudo (17), every program in `tests/corpus/` (52), and 17 one-construct fixtures (`tests/helpers/sync-programs.mjs`). 3 of the 86 have pseudo that does not read, by design (they teach the notation's error messages), and are left out below. That leaves **83 programs**. +Each translator in `src/sync/` is run over every exercise with pseudo (17), every program in `tests/corpus/` (53), and 17 one-construct fixtures (`tests/helpers/sync-programs.mjs`). 3 of the 87 have pseudo that does not read, by design (they teach the notation's error messages), and are left out below. That leaves **84 programs**. | From pseudo to | Says it completely | Says it with a gap or a checker error | Cannot say it | | --- | ---: | ---: | ---: | -| Mojo | 80 | 3 | 0 | -| lingo | 31 | 0 | 52 | -| matho | 3 | 0 | 80 | +| Mojo | 81 | 3 | 0 | +| lingo | 31 | 0 | 53 | +| matho | 3 | 0 | 81 | Mojo is a program-for-program translation that always produces something: a line with no faithful spelling becomes a visible `raise Error("not translated: pseudo line N")` and a warning. Lingo and matho must read back as the same program, so what they cannot say exactly they refuse, with the construct and its line, and the pane keeps its last good text. @@ -32,7 +32,7 @@ English is read by `readSteps`, whose grammar has no sentence for these. | What it has no form for | Programs | Which | | --- | ---: | --- | -| steps outside a routine (every English step belongs to a routine) | 50 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 46 more | +| steps outside a routine (every English step belongs to a routine) | 51 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 47 more | | a fixed-length ARRAY | 4 | ex:edit-distance, 05-primes-sieve.pseudo, 11-matrix-multiply.pseudo, 15-game-of-life.pseudo | | a BYREF parameter | 3 | 06-fibonacci-memo.pseudo, 10-insertion-sort.pseudo, 26-swap-byref.pseudo | | a HASHMAP whose values are not counts | 3 | ex:translate-codons, 13-stack-brackets.pseudo, 39-constants-codons.pseudo | @@ -64,7 +64,7 @@ An equation lowers to one `FUNCTION` that returns a value; a program with output | What it has no form for | Programs | Which | | --- | ---: | --- | -| steps outside a function (an equation is a function) | 46 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 42 more | +| steps outside a function (an equation is a function) | 47 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 43 more | | a function that answers LIST (equations answer numbers) | 5 | ex:match, ex:match-proved, ex:match-off-by-one, ex:match-reset, and 1 more | | a function that answers STRING (equations answer numbers) | 5 | ex:revcomp, fixture:string-build, fixture:slice, fixture:case, and 1 more | | a function that answers BOOL (equations answer numbers) | 3 | ex:binary-search, fixture:early-return, fixture:forall | diff --git a/docs/trust.md b/docs/trust.md index e9f7214..712d5f4 100644 --- a/docs/trust.md +++ b/docs/trust.md @@ -55,3 +55,17 @@ The Prove tab reports every obligation in three statuses (`src/engines/pseudo/vc |---|---|---|---| | Registers, caches, pipeline and counters in the Hardware area | The model machine (`src/engines/asm86/`), on the preset machine named in Setup | What that model does with these instructions | A measurement of a real processor. Cycle counts are a teaching model; compare a run with itself across edits | | "stopped: … standard library, not on the model machine" | A call into a function the model does not have | The real program would enter the library here | That the library call does anything in particular | + +## Library routines + +A routine of pplus-library (`USE md`) carries the record of `pixi run library-check` ([library.md](library.md)). + +| Shown | Earned by | Means | Does not mean | +|---|---|---|---| +| **Cases pass** | Running the pseudo on the cases in `routine.json` | The routine gives those results; they are what every reference is held to | That the results are right for other inputs | +| **Prover: pass** | Every obligation of the routine proved, as for any pseudo | Its contracts hold for every input that meets its REQUIRE, in the notation's number model | Anything about the value of FLOAT arithmetic beyond what the contracts say | +| **Prover: open** | Some obligation not proved, none broken | The routine's comment says which and why (usually FLOAT rounding, which is opaque to the prover) | That it is wrong | +| **A reference agrees** | Python, C at -O0 and -O2, core's Mojo interpreter, or the pinned compiler, run on the cases | That implementation, at that level, prints the pseudo's results exactly, or within the stated tolerance | That it agrees on other inputs, or at other optimization flags | +| **Mojo: unverified** | No stored answer from the pinned compiler for that exact program | Not yet asked (`pixi run library-verify-mojo`) | That it fails | +| **Proof: pass** | The pinned Dafny verified the proof file (or its stored verdict for this exact text) | The method is correct over exact numbers, as the proof states it | That the FLOAT version computes the same digits: rounding is outside the proof | + diff --git a/library b/library new file mode 160000 index 0000000..df12b2a --- /dev/null +++ b/library @@ -0,0 +1 @@ +Subproject commit df12b2a0082c251e25d12fc0f3df01bf4e101761 diff --git a/pixi.toml b/pixi.toml index 8c13b28..125d8e3 100644 --- a/pixi.toml +++ b/pixi.toml @@ -34,6 +34,12 @@ engines-export = { cmd = "node scripts/engines-export.mjs {{ static }}", args = dafny-fetch = { cmd = "python scripts/dafny.py fetch", description = "Download the pinned Dafny into .tools/, checked by SHA-256 (network, once)" } dafny = { cmd = "python scripts/dafny.py", description = "Run the pinned Dafny with the arguments given, e.g. pixi run dafny verify file.dfy (fetches it first if missing)" } +# --- the library (library/, the pplus-library submodule; docs/library.md) --- +library-check = { cmd = "node scripts/library.mjs check", depends-on = ["build"], description = "Check every library routine at every level (cases, prover, fuzzer, generated Mojo, every reference, the Dafny proof); writes library/status.json and STATUS.md" } +library-emit = { cmd = "node scripts/library.mjs emit", depends-on = ["build"], description = "Regenerate src/library/generated.ts, the registry USE reads, from library/" } +library-verify-mojo = { cmd = "node scripts/library.mjs mojo-sources | python scripts/library_godbolt.py", depends-on = ["build"], description = "Ask the pinned Mojo compiler about every Mojo reference of the library and store the answers (network)" } +library-harness = { cmd = "node scripts/library.mjs harness {{ id }} {{ lang }} {{ level }}", args = ["id", "lang", "level"], depends-on = ["build"], description = "Print the program a reference implementation is run as, e.g. pixi run library-harness md.LennardJones c multiply" } + # --- write content --------------------------------------------------------- new-exercise = { cmd = "node scripts/new-exercise.mjs {{ id }}", args = ["id"], description = "Start an exercise: mojo/local/.mojo and src/exercises/.ts, registered in index.ts" } new-probe = { cmd = "node scripts/mojo/new-program.mjs probe {{ name }} \"{{ question }}\"", args = ["name", "question"], description = "Start mojo/probes/.mojo: one question about the pinned compiler" } @@ -59,5 +65,5 @@ mojo-probes-local = { cmd = "for f in mojo/probes/*.mojo; do echo \"== $f\"; moj mojo-update = { depends-on = ["mojo-harvest", "mojo-verify", "mojo-status", "test"], description = "After editing mojo/pin.json: harvest, verify, status, test" } # --- ship ------------------------------------------------------------------ -ci = { depends-on = ["test", "mojo-status-strict"], description = "What CI runs: every test, and no program of ours failing" } +ci = { depends-on = ["test", "mojo-status-strict"], description = "What CI runs: every test (the library's registry up to date among them), and no program of ours failing" } package = { cmd = "python scripts/package.py", description = "Zip the files git tracks (and new ones it does not ignore) into package/ for sharing" } diff --git a/scripts/library.mjs b/scripts/library.mjs new file mode 100644 index 0000000..ca732c9 --- /dev/null +++ b/scripts/library.mjs @@ -0,0 +1,460 @@ +#!/usr/bin/env node +/** + * The library's tools: check every routine of pplus-library (the submodule library/) at every level, record + * what was found in the library, and generate core's registry from it. + * + * node scripts/library.mjs check [--dir library] [--only stats.Mean] every check; writes status.json, STATUS.md, goldens + * node scripts/library.mjs emit [--check] library/ -> src/library/generated.ts + * node scripts/library.mjs harness print the program a reference is run as + * node scripts/library.mjs mojo-sources [--out dir] write each Mojo reference's harness, for godbolt + * + * The checks of one routine: + * structure routine.pseudo defines exactly the routine routine.json names, and nothing else (USE lines aside) + * pseudo every case runs; its result is recorded and becomes what the references are held to + * prover every obligation of the routine: pass when all are proved, open when some are not, fail when broken + * fuzz the fuzzer finds no input that breaks a contract or stops the run + * mojo the Mojo generated from the pseudo checks, runs in core's interpreter and prints what the pseudo prints + * and for each reference implementation, per way of running it: + * cpython python3 runs it on every case cc -O0, cc -O2 cc compiles and runs it on every case + * interpreter core's Mojo interpreter runs it godbolt the stored answer of the pinned compiler + * and the proof, if there is one: the pinned Dafny verifies it (or its stored verdict for this exact text). + * + * Needs a build (dist/). Python and a C compiler are used when they are on the PATH; without them those checks + * are recorded as skipped, never as passed. + */ +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import crypto from 'node:crypto'; +import { execFileSync, spawnSync } from 'node:child_process'; +import { fileURLToPath } from 'node:url'; + +const CORE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); +const args = process.argv.slice(2); +const cmd = args[0]; +const opt = (name, dflt = null) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : dflt; }; +const flag = (name) => args.includes(`--${name}`); +const LIB = path.resolve(opt('dir', path.join(CORE, 'library'))); +const GENERATED = path.join(CORE, 'src', 'library', 'generated.ts'); + +const sha256 = (s) => crypto.createHash('sha256').update(s).digest('hex'); +const readJson = (p) => JSON.parse(fs.readFileSync(p, 'utf8')); +const writeIfChanged = (p, text) => { if (!fs.existsSync(p) || fs.readFileSync(p, 'utf8') !== text) { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, text); return true; } return false; }; + +/* ------------------------------------------------------------------ */ +/* Reading the library */ +/* ------------------------------------------------------------------ */ + +/** Every module and routine on disk, with its sources, and the status last recorded for it. */ +export function load(dir = LIB) { + if (!fs.existsSync(path.join(dir, 'modules'))) throw new Error(`no library at ${dir}: check out the submodule (git submodule update --init) or pass --dir`); + const status = fs.existsSync(path.join(dir, 'status.json')) ? readJson(path.join(dir, 'status.json')).routines || {} : {}; + const modules = []; + for (const m of fs.readdirSync(path.join(dir, 'modules')).sort()) { + const mdir = path.join(dir, 'modules', m); + if (!fs.existsSync(path.join(mdir, 'module.json'))) continue; + const meta = readJson(path.join(mdir, 'module.json')); + const routines = []; + for (const r of fs.readdirSync(mdir).sort()) { + const rdir = path.join(mdir, r); + if (!fs.existsSync(path.join(rdir, 'routine.json'))) continue; + const rm = readJson(path.join(rdir, 'routine.json')); + const id = `${meta.name}.${rm.name}`; + const st = status[id] || {}; + routines.push({ + id, module: meta.name, name: rm.name, dir: path.relative(dir, rdir).split(path.sep).join('/'), + summary: rm.summary || '', tags: rm.tags || [], sources: rm.sources || [], + source: fs.readFileSync(path.join(rdir, 'routine.pseudo'), 'utf8'), + cases: (rm.cases || []).map((c, i) => ({ ...c, ...(st.cases?.[i]?.call === c.call ? { result: st.cases[i].result } : {}) })), + references: (rm.references || []).map((ref) => ({ + lang: ref.lang, level: ref.level, file: ref.file, note: ref.note || '', + ...(ref.rel !== undefined ? { rel: ref.rel } : {}), ...(ref.abs !== undefined ? { abs: ref.abs } : {}), + source: fs.readFileSync(path.join(rdir, ref.file), 'utf8'), + checks: st.references?.[`${ref.lang}/${ref.level}`] || {}, + })), + ...(rm.proof ? { proof: { lang: rm.proof.lang, file: rm.proof.file, note: rm.proof.note || '', source: fs.readFileSync(path.join(rdir, rm.proof.file), 'utf8'), check: st.proof || { status: 'unverified', detail: 'not checked yet' } } } : {}), + checks: st.checks || {}, + }); + } + modules.push({ name: meta.name, title: meta.title, summary: meta.summary, routines }); + } + return modules; +} + +/* ------------------------------------------------------------------ */ +/* Values in other languages */ +/* ------------------------------------------------------------------ */ + +const floatText = (v) => { const s = String(v); return /[.e]/.test(s) || !Number.isFinite(v) ? s : `${s}.0`; }; +const items = (v) => (Array.isArray(v) ? v : v?.data ? v.data : []); + +function pyLiteral(v, t) { + switch (t?.k) { + case 'FLOAT': return floatText(v).replace('e+', 'e'); + case 'INTEGER': return String(v); + case 'BOOL': return v ? 'True' : 'False'; + case 'CHAR': case 'STRING': return JSON.stringify(v); + case 'LIST': case 'ARRAY': return `[${items(v).map((x) => pyLiteral(x, t.of)).join(', ')}]`; + default: throw new Error(`no Python literal for ${t?.k}`); + } +} + +function mojoType(t) { + switch (t?.k) { + case 'FLOAT': return t.bits === 32 ? 'Float32' : 'Float64'; + case 'INTEGER': return t.bits ? `${t.signed ? 'Int' : 'UInt'}${t.bits}` : 'Int'; + case 'BOOL': return 'Bool'; + case 'CHAR': case 'STRING': return 'String'; + case 'LIST': case 'ARRAY': return `List[${mojoType(t.of)}]`; + default: throw new Error(`no Mojo type for ${t?.k}`); + } +} + +function mojoLiteral(v, t) { + switch (t?.k) { + case 'FLOAT': return floatText(v).replace('e+', 'e'); + case 'INTEGER': return String(v); + case 'BOOL': return v ? 'True' : 'False'; + case 'CHAR': case 'STRING': return JSON.stringify(v); + case 'LIST': case 'ARRAY': return `${mojoType(t)}(${items(v).map((x) => mojoLiteral(x, t.of)).join(', ')})`; + default: throw new Error(`no Mojo literal for ${t?.k}`); + } +} + +/** A C argument list for one call, with the declarations it needs first: a list becomes (array, length). */ +function cArgs(vals, params, tag) { + const decls = []; const out = []; + vals.forEach((v, i) => { + const t = params[i].type; + switch (t?.k) { + case 'FLOAT': out.push(floatText(v)); break; + case 'INTEGER': out.push(`${v}L`); break; + case 'BOOL': out.push(v ? '1' : '0'); break; + case 'CHAR': out.push(`'${v.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`); break; + case 'STRING': out.push(JSON.stringify(v)); break; + case 'LIST': case 'ARRAY': { + const xs = items(v); + if (t.of?.k !== 'FLOAT' && t.of?.k !== 'INTEGER') throw new Error('C lists hold numbers only'); + const ct = t.of.k === 'FLOAT' ? 'double' : 'long'; + const name = `a${tag}_${i}`; + decls.push(`${ct} ${name}[${Math.max(1, xs.length)}] = {${xs.length ? xs.map((x) => (t.of.k === 'FLOAT' ? floatText(x) : `${x}L`)).join(', ') : '0'}};`); + out.push(name, `${xs.length}L`); + break; + } + default: throw new Error(`no C argument for ${t?.k}`); + } + }); + return { decls, args: out }; +} + +/* ------------------------------------------------------------------ */ +/* The checks */ +/* ------------------------------------------------------------------ */ + +const ok = (detail) => ({ status: 'pass', detail }); +const bad = (detail) => ({ status: 'fail', detail }); +const skip = (detail) => ({ status: 'skipped', detail }); +const open = (detail) => ({ status: 'open', detail }); +const unverified = (detail) => ({ status: 'unverified', detail }); + +function have(cmdName) { return spawnSync(cmdName, ['--version'], { encoding: 'utf8' }).status === 0; } + +/** Does a printed value agree with the pseudo's, within the reference's tolerance? */ +function agrees(printed, want, t, rel = 0, abs = 0) { + const s = String(printed).trim(); + if (t?.k === 'FLOAT' || t?.k === 'INTEGER') { + const got = Number(s.replace(/^inf$/i, 'Infinity').replace(/^-inf$/i, '-Infinity').replace(/^nan$/i, 'NaN')); + if (Number.isNaN(got) && Number.isNaN(want)) return true; + if (Number.isNaN(got)) return false; + if (got === want) return true; + return Math.abs(got - want) <= Math.max(rel * Math.max(Math.abs(got), Math.abs(want)), abs); + } + if (t?.k === 'BOOL') return ['true', '1'].includes(s.toLowerCase()) === Boolean(want); + return s === String(want); +} + +function compareLines(stdout, wants, t, rel, abs) { + const got = stdout.replace(/\n$/, '').split('\n'); + if (got.length !== wants.length) return `printed ${got.length} line(s) for ${wants.length} case(s)`; + for (let i = 0; i < wants.length; i++) if (!agrees(got[i], wants[i].value, t, rel, abs)) return `case ${i + 1} (${wants[i].call}) printed ${got[i]}, and the pseudo gives ${wants[i].text}`; + return null; +} + +/** The program a reference implementation is run as: its source, plus a main that prints each case. */ +function harness(lang, ref, fname, sub, calls) { + const params = sub.params; + if (lang === 'python') { + return `import importlib.util\nspec = importlib.util.spec_from_file_location("ref", __REF__)\nref = importlib.util.module_from_spec(spec)\nspec.loader.exec_module(ref)\n${calls.map((c) => `print(repr(ref.${fname}(${c.args.map((v, i) => pyLiteral(v, params[i].type)).join(', ')})))`).join('\n')}\n`; + } + if (lang === 'mojo') { + return `${ref.source.replace(/\s+$/, '')}\n\n\ndef main() raises:\n${calls.map((c) => ` print(${fname}(${c.args.map((v, i) => mojoLiteral(v, params[i].type)).join(', ')}))`).join('\n')}\n`; + } + if (lang === 'c') { + const fmt = sub.returns?.k === 'FLOAT' ? '%.17g' : '%ld'; + const body = calls.map((c, k) => { const a = cArgs(c.args, params, k); return ` { ${a.decls.join(' ')} printf("${fmt}\\n", ${fname}(${a.args.join(', ')})); }`; }).join('\n'); + return `#include \n\n${ref.source.replace(/\s+$/, '')}\n\nint main(void) {\n${body}\n return 0;\n}\n`; + } + throw new Error(`no harness for ${lang}`); +} + +export async function checkLibrary(dir = LIB, only = null) { + const { setLibrary } = await import(path.join(CORE, 'dist/library/registry.js')); + const svc = await import(path.join(CORE, 'dist/services/pseudo.js')); + const { parseExpression } = await import(path.join(CORE, 'dist/engines/pseudo/parse.js')); + const { evaluateConstant } = await import(path.join(CORE, 'dist/engines/pseudo/interp.js')); + const { formatValue } = await import(path.join(CORE, 'dist/engines/pseudo/lang.js')); + const { pseudoToMojo, snake } = await import(path.join(CORE, 'dist/sync/pseudo-to-mojo.js')); + const { checkMojo } = await import(path.join(CORE, 'dist/mojo/check.js')); + const { runMojo } = await import(path.join(CORE, 'dist/mojo/interp.js')); + const { sameOutput } = await import(path.join(CORE, 'dist/sync/compare.js')); + + const modules = load(dir); + setLibrary(modules); + const pin = readJson(path.join(CORE, 'mojo', 'pin.json')); + const dafny = (() => { try { const p = execFileSync('python3', [path.join(CORE, 'scripts', 'dafny.py'), 'path'], { encoding: 'utf8' }).trim(); return fs.existsSync(p) ? p : null; } catch { return null; } })(); + const dafnyVersion = (() => { try { return readJson(path.join(CORE, 'scripts', 'dafny.json')).version; } catch { return null; } })() || (() => { const m = /VERSION = "([^"]+)"/.exec(fs.readFileSync(path.join(CORE, 'scripts', 'dafny.py'), 'utf8')); return m ? m[1] : 'unknown'; })(); + const python = have('python3'); + const cc = have('cc'); + const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pplus-library-')); + const out = {}; + for (const m of modules) { + for (const r of m.routines) { + if (only && r.id !== only) { continue; } + const rdir = path.join(dir, r.dir); + const rec = { checks: {}, cases: [], references: {}, proof: undefined }; + out[r.id] = rec; + const st = svc.studyOf(r.source); + const program = st.program?.program; + // structure + const subs = program ? [...program.subs.values()] : []; + if (!st.ok) { rec.checks.structure = bad(`the pseudo does not check: ${st.diagnostics.filter((d) => d.severity === 'error').map((d) => `line ${d.line}: ${d.message}`).join('; ')}`); continue; } + if (subs.length !== 1 || subs[0].name.toUpperCase() !== r.name.toUpperCase()) { rec.checks.structure = bad(`routine.pseudo defines ${subs.map((s) => s.name).join(', ') || 'nothing'}; it must define exactly ${r.name} (helpers are routines of their own, brought in with USE)`); continue; } + if (program.main.body.length) { rec.checks.structure = bad(`routine.pseudo has lines outside ${r.name} (line ${program.main.body[0].line}); a routine file holds USE lines and the routine only`); continue; } + const sub = subs[0]; + rec.checks.structure = ok(`defines ${sub.kind === 'Function' ? 'FUNCTION' : 'PROCEDURE'} ${sub.name}${program.libs?.size ? `, using ${[...program.libs.values()].map((x) => x.lib.id).join(', ')}` : ''}`); + // pseudo: every case + const calls = []; + let caseFail = null; + for (const c of r.cases) { + const p = parseExpression(c.call); + let entry = { call: c.call }; + try { + if (p.diags.some((d) => d.severity === 'error') || p.expr.kind !== 'CallExpr' || p.expr.name.toUpperCase() !== r.name.toUpperCase()) throw new Error(`"${c.call}" is not a call of ${r.name}`); + const vals = p.expr.args.map((a) => evaluateConstant(program, a)); + const tr = svc.runPseudo(st, { call: c.call, maxSteps: 2000000 }); + if (tr.error) throw new Error(`${c.call} stops: ${tr.error.message}`); + const result = tr.raw.result; + entry = { call: c.call, result: formatValue(result, sub.returns, { max: 1000 }) }; + calls.push({ call: c.call, args: vals, value: result, text: entry.result }); + } catch (e) { caseFail = caseFail || e.message; } + rec.cases.push(entry); + } + rec.checks.pseudo = caseFail ? bad(caseFail) : ok(`${calls.length} case(s) run`); + // prover + const pr = svc.provePseudo(st); + const obs = pr.units.flatMap((u) => u.obligations); + const broken = obs.filter((o) => o.status === 'broken'); + const notProved = obs.filter((o) => o.status !== 'proved'); + rec.checks.prover = broken.length ? bad(`${broken.length} obligation(s) broken: ${broken.map((o) => `${o.kind}@${o.line} (${o.label})`).join('; ')}`) + : notProved.length ? open(`${obs.length - notProved.length} of ${obs.length} obligation(s) proved; open: ${notProved.map((o) => `${o.kind}@${o.line} (${o.label})`).join('; ')}`) + : ok(`all ${obs.length} obligation(s) proved`); + // fuzz + const props = svc.propertiesPseudo(st, r.name)[0]; + rec.checks.fuzz = !props ? skip('no routine to fuzz') : props.problem ? skip(`the fuzzer cannot generate inputs: ${props.problem}`) + : props.failures.length ? bad(`${props.failures.length} failing input(s), first: ${props.failures[0].call}: ${props.failures[0].message}`) + : ok(`no failure in ${props.checked} generated input(s)`); + // the Mojo generated from the pseudo, on every case + if (calls.length) { + const prog = `USE ${r.module}.${r.name}\n${calls.map((c) => `OUTPUT ${c.call}`).join('\n')}\n`; + const want = svc.runPseudo(svc.studyOf(prog), {}).output.join('\n'); + const mj = pseudoToMojo(prog); + if ('unsupported' in mj) rec.checks.mojo = bad(`the translator refused: ${mj.unsupported.map((d) => d.message).join('; ')}`); + else { + const gaps = mj.notes.filter((n) => n.id === 'translate-gap'); + const ck = checkMojo(mj.source); + const errs = ck.diagnostics.filter((d) => d.severity === 'error'); + if (gaps.length) rec.checks.mojo = skip(`the translator has no Mojo for: ${gaps.map((g) => g.message.replace(/^.*?\(|\)\..*$/g, '')).join('; ')}`); + else if (errs.length) rec.checks.mojo = bad(`the generated Mojo has checker errors: ${errs.map((d) => `L${d.line} ${d.message}`).join(' | ')}`); + else { + const run = runMojo(ck.module, mj.source, { maxSteps: 4000000 }); + rec.checks.mojo = run.refused ? skip(`core's Mojo interpreter declines ${run.refused}; the compiler's answer is needed`) + : run.exitCode !== 0 ? bad(`the generated Mojo stopped (exit ${run.exitCode})`) + : sameOutput(want, run.stdout) ? ok('the generated Mojo prints what the pseudo prints on every case, in core\'s interpreter') : bad(`the generated Mojo printed ${JSON.stringify(run.stdout.slice(0, 120))}; the pseudo printed ${JSON.stringify(want.slice(0, 120))}`); + } + } + } + // references + const fname = snake(r.name); + for (const ref of r.references) { + const checks = {}; + rec.references[`${ref.lang}/${ref.level}`] = checks; + if (!calls.length) { checks.cases = skip('no case ran in pseudo, so there is nothing to hold it to'); continue; } + const rel = ref.rel ?? 0; const abs = ref.abs ?? 0; + const tol = rel || abs ? ` (within rel ${rel}, abs ${abs})` : ' (exactly)'; + try { + if (ref.lang === 'python') { + if (!python) { checks.cpython = skip('python3 is not on the PATH'); continue; } + const h = harness('python', ref, fname, sub, calls).replace('__REF__', JSON.stringify(path.join(rdir, ref.file))); + const p = spawnSync('python3', ['-c', h], { encoding: 'utf8', timeout: 60000 }); + if (p.status !== 0) { checks.cpython = bad(`python3 stopped: ${(p.stderr || '').trim().split('\n').pop()}`); continue; } + const diff = compareLines(p.stdout, calls, sub.returns, rel, abs); + checks.cpython = diff ? bad(diff) : ok(`agrees with the pseudo on ${calls.length} case(s)${tol}`); + } else if (ref.lang === 'c') { + if (!cc) { checks['cc -O0'] = skip('no C compiler (cc) on the PATH'); continue; } + const src = harness('c', ref, fname, sub, calls); + const file = path.join(tmp, `${fname}-${ref.level}.c`); + fs.writeFileSync(file, src); + for (const level of ['-O0', '-O2']) { + const bin = path.join(tmp, `${fname}-${ref.level}${level}`); + const c = spawnSync('cc', ['-std=c11', level, '-o', bin, file, '-lm'], { encoding: 'utf8' }); + if (c.status !== 0) { checks[`cc ${level}`] = bad(`cc ${level} failed: ${(c.stderr || '').trim().split('\n')[0]}`); continue; } + const p = spawnSync(bin, [], { encoding: 'utf8', timeout: 60000 }); + const diff = p.status !== 0 ? `exited ${p.status}` : compareLines(p.stdout, calls, sub.returns, rel, abs); + checks[`cc ${level}`] = diff ? bad(diff) : ok(`agrees with the pseudo on ${calls.length} case(s)${tol}`); + } + } else if (ref.lang === 'mojo') { + const src = harness('mojo', ref, fname, sub, calls); + const ck = checkMojo(src); + const errs = ck.diagnostics.filter((d) => d.severity === 'error'); + if (errs.length) checks.interpreter = bad(`core's Mojo checker reports: ${errs.map((d) => `L${d.line} ${d.message}`).join(' | ')}`); + else { + const run = runMojo(ck.module, src, { maxSteps: 4000000 }); + const diff = run.refused ? null : run.exitCode !== 0 ? `stopped (exit ${run.exitCode})` : compareLines(run.stdout, calls, sub.returns, rel, abs); + checks.interpreter = run.refused ? skip(`core's Mojo interpreter declines ${run.refused}`) : diff ? bad(diff) : ok(`agrees with the pseudo on ${calls.length} case(s) in core's interpreter${tol}`); + } + // the compiler's stored answer for this exact program + const gfile = path.join(rdir, 'golden', `mojo-${ref.level}.json`); + const g = fs.existsSync(gfile) ? readJson(gfile) : null; + if (!g || g.source_sha256 !== sha256(src) || g.compiler !== pin.godbolt.compiler) checks.godbolt = unverified(`no stored answer from ${pin.godbolt.compiler} for this program: pixi run library-verify-mojo`); + else if (!g.result?.compiled) checks.godbolt = bad(`${pin.godbolt.compiler} did not compile it: ${(g.result?.buildStderr || '').split('\n')[0]}`); + else { + const diff = g.result.exitCode !== 0 ? `exited ${g.result.exitCode}` : compareLines(g.result.stdout, calls, sub.returns, rel, abs); + checks.godbolt = diff ? bad(diff) : ok(`${pin.godbolt.compiler} agrees with the pseudo on ${calls.length} case(s)${tol}`); + } + } else checks.cases = skip(`no runner for ${ref.lang} yet`); + } catch (e) { + checks.harness = bad(`could not build the harness: ${e.message}`); + } + } + // proof + if (r.proof) { + const gfile = path.join(rdir, 'golden', 'dafny.json'); + const src = r.proof.source; + const flags = ['verify', '--resource-limit', '20000000']; + if (dafny) { + const p = spawnSync(dafny, [...flags, path.join(rdir, r.proof.file)], { encoding: 'utf8', timeout: 600000 }); + const summary = /Dafny program verifier finished with (.*)/.exec(p.stdout || '')?.[1] || (p.stdout || p.stderr || '').trim().split('\n').pop(); + const pass = p.status === 0 && / 0 errors/.test(summary); + rec.proof = pass ? ok(`Dafny ${dafnyVersion}: ${summary}`) : bad(`Dafny ${dafnyVersion}: ${summary}`); + writeIfChanged(gfile, `${JSON.stringify({ tool: 'dafny', version: dafnyVersion, flags, source_sha256: sha256(src), verdict: pass ? 'verified' : 'failed', summary }, null, 2)}\n`); + } else { + const g = fs.existsSync(gfile) ? readJson(gfile) : null; + rec.proof = g && g.source_sha256 === sha256(src) ? (g.verdict === 'verified' ? ok(`Dafny ${g.version} (stored answer): ${g.summary}`) : bad(`Dafny ${g.version} (stored answer): ${g.summary}`)) + : unverified('the pinned Dafny is not fetched (pixi run dafny-fetch) and there is no stored verdict for this text'); + } + } + } + } + fs.rmSync(tmp, { recursive: true, force: true }); + return { modules, results: out }; +} + +const ORDER = ['structure', 'pseudo', 'prover', 'fuzz', 'mojo']; + +function statusMarkdown(modules, results) { + const mark = (c) => (!c ? '·' : { pass: 'pass', fail: '**fail**', open: 'open', skipped: 'skipped', unverified: 'unverified' }[c.status] || c.status); + const lines = ['# Library status', '', '', '', + 'Each routine, at each level. *pass*: checked and agrees; *open*: the prover could not finish every obligation (nothing is wrong, nothing is proved); *skipped*: the tool is not available here, or it declines the construct; *unverified*: no stored answer for this exact text yet.', '']; + for (const m of modules) { + lines.push(`## ${m.title} (\`${m.name}\`)`, '', '| Routine | Cases | Prover | Fuzz | Generated Mojo | References | Proof |', '| --- | --- | --- | --- | --- | --- | --- |'); + for (const r of m.routines) { + const res = results[r.id]; + if (!res) continue; + const refs = Object.entries(res.references).map(([k, checks]) => `${k}: ${Object.entries(checks).map(([how, c]) => `${how} ${mark(c)}`).join(', ')}`).join('
'); + lines.push(`| \`${r.id}\` | ${mark(res.checks.pseudo)} | ${mark(res.checks.prover)} | ${mark(res.checks.fuzz)} | ${mark(res.checks.mojo)} | ${refs || '·'} | ${res.proof ? `dafny ${mark(res.proof)}` : '·'} |`); + } + lines.push(''); + } + lines.push('## Details', ''); + for (const m of modules) for (const r of m.routines) { + const res = results[r.id]; + if (!res) continue; + lines.push(`### ${r.id}`, ''); + for (const k of ORDER) if (res.checks[k]) lines.push(`- ${k}: ${res.checks[k].status}. ${res.checks[k].detail}`); + for (const [k, checks] of Object.entries(res.references)) for (const [how, c] of Object.entries(checks)) lines.push(`- ${k}, ${how}: ${c.status}. ${c.detail}`); + if (res.proof) lines.push(`- proof: ${res.proof.status}. ${res.proof.detail}`); + lines.push(''); + } + return lines.join('\n'); +} + +/* ------------------------------------------------------------------ */ +/* Emitting core's registry */ +/* ------------------------------------------------------------------ */ + +function emitText(dir = LIB) { + const modules = load(dir); + let commit = ''; + try { commit = execFileSync('git', ['-C', dir, 'rev-parse', '--short=12', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { /* not a checkout */ } + return `// Generated by scripts/library.mjs emit from library/ (pplus-library). Do not edit; run pixi run library-emit.\nimport type { LibraryModule } from './types.js';\n\nexport const LIBRARY_COMMIT = ${JSON.stringify(commit)};\nexport const LIBRARY_MODULES: LibraryModule[] = ${JSON.stringify(modules, null, 2)};\n`; +} + +/* ------------------------------------------------------------------ */ +/* Command line */ +/* ------------------------------------------------------------------ */ + +if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { + if (cmd === 'check') { + const only = opt('only'); + const { modules, results } = await checkLibrary(LIB, only); + const prior = fs.existsSync(path.join(LIB, 'status.json')) ? readJson(path.join(LIB, 'status.json')).routines || {} : {}; + const merged = only ? { ...prior, ...results } : results; + const sorted = Object.fromEntries(Object.keys(merged).sort().map((k) => [k, merged[k]])); + writeIfChanged(path.join(LIB, 'status.json'), `${JSON.stringify({ comment: 'Written by pixi run library-check in pplus-core. Do not edit.', routines: sorted }, null, 2)}\n`); + writeIfChanged(path.join(LIB, 'STATUS.md'), `${statusMarkdown(modules, sorted)}\n`); + let failed = 0; + for (const [id, res] of Object.entries(results)) { + const all = [...Object.entries(res.checks), ...Object.entries(res.references).flatMap(([k, c]) => Object.entries(c).map(([h, v]) => [`${k} ${h}`, v])), ...(res.proof ? [['proof', res.proof]] : [])]; + for (const [k, c] of all) if (c.status === 'fail') { failed++; console.log(`FAIL ${id} ${k}: ${c.detail}`); } + console.log(`${id}: ${all.map(([k, c]) => `${k}=${c.status}`).join(' ')}`); + } + console.log(failed ? `${failed} failing check(s)` : 'no failing check'); + process.exit(failed ? 1 : 0); + } else if (cmd === 'emit') { + const text = emitText(LIB); + if (flag('check')) { + const cur = fs.existsSync(GENERATED) ? fs.readFileSync(GENERATED, 'utf8') : ''; + if (cur !== text) { console.error('src/library/generated.ts is out of date with library/: run pixi run library-emit'); process.exit(1); } + console.log('src/library/generated.ts is up to date'); + } else console.log(writeIfChanged(GENERATED, text) ? 'wrote src/library/generated.ts' : 'src/library/generated.ts unchanged'); + } else if (cmd === 'harness' || cmd === 'mojo-sources') { + const svc = await import(path.join(CORE, 'dist/services/pseudo.js')); + const { setLibrary } = await import(path.join(CORE, 'dist/library/registry.js')); + const { parseExpression } = await import(path.join(CORE, 'dist/engines/pseudo/parse.js')); + const { evaluateConstant } = await import(path.join(CORE, 'dist/engines/pseudo/interp.js')); + const { snake } = await import(path.join(CORE, 'dist/sync/pseudo-to-mojo.js')); + const modules = load(LIB); + setLibrary(modules); + const programs = []; + for (const m of modules) for (const r of m.routines) { + const st = svc.studyOf(r.source); + if (!st.ok) continue; + const sub = [...st.program.program.subs.values()][0]; + const calls = r.cases.map((c) => ({ args: parseExpression(c.call).expr.args.map((a) => evaluateConstant(st.program.program, a)) })); + for (const ref of r.references) programs.push({ id: r.id, ref, dir: path.join(LIB, r.dir), make: () => harness(ref.lang, ref, snake(r.name), sub, calls) }); + } + if (cmd === 'harness') { + const [id, lang, level] = args.slice(1); + const p = programs.find((x) => x.id === id && x.ref.lang === lang && x.ref.level === level); + if (!p) { console.error(`no reference ${lang}/${level} for ${id}`); process.exit(2); } + process.stdout.write(p.make()); + } else { + // one JSON line per Mojo reference: what scripts/library_godbolt.py sends, and where its answer goes + const list = programs.filter((p) => p.ref.lang === 'mojo').map((p) => ({ id: `${p.id} mojo/${p.ref.level}`, source: p.make(), golden: path.join(p.dir, 'golden', `mojo-${p.ref.level}.json`) })); + process.stdout.write(`${JSON.stringify(list, null, 2)}\n`); + } + } else { + console.error('usage: node scripts/library.mjs check [--only id] | emit [--check] | harness | mojo-sources'); + process.exit(2); + } +} diff --git a/scripts/library_godbolt.py b/scripts/library_godbolt.py new file mode 100644 index 0000000..f94db4e --- /dev/null +++ b/scripts/library_godbolt.py @@ -0,0 +1,58 @@ +#!/usr/bin/env python3 +"""Ask the pinned Mojo compiler (on Compiler Explorer) about every Mojo reference implementation of the library, +and store each answer beside the routine, in golden/mojo-.json. Network; standard library only. + + node scripts/library.mjs mojo-sources | python3 scripts/library_godbolt.py [--force] [--dry-run] + +Each program is the reference's source with a main that prints every case (scripts/library.mjs builds it). An +answer is keyed by the SHA-256 of that exact program and the compiler id, so editing a reference or a case makes +it unverified until it is asked again; an answer already stored for the same program is not asked again unless +--force. pixi run library-check then compares the stored output with the pseudo's results. +""" +from __future__ import annotations + +import hashlib +import json +import sys +from datetime import date +from pathlib import Path + +CORE = Path(__file__).resolve().parent.parent +sys.path.insert(0, str(CORE / "scripts" / "mojo")) +from mojocorpus import godbolt # noqa: E402 + + +def main(argv: list[str]) -> int: + force = "--force" in argv + dry = "--dry-run" in argv + pin = json.loads((CORE / "mojo" / "pin.json").read_text()) + base, compiler = pin["godbolt"]["base"], pin["godbolt"]["compiler"] + timeout = int(pin["godbolt"].get("timeoutSeconds", 90)) + items = json.load(sys.stdin) + asked = 0 + for it in items: + src = it["source"] + sha = hashlib.sha256(src.encode("utf-8")).hexdigest() + out = Path(it["golden"]) + if out.exists() and not force: + old = json.loads(out.read_text()) + if old.get("source_sha256") == sha and old.get("compiler") == compiler: + print(f"[library] {it['id']}: stored answer is current") + continue + if dry: + print(f"[library] {it['id']}: would ask {base} ({compiler}), {len(src)} bytes") + continue + data = godbolt.post(base, compiler, godbolt.request_body(src, "run"), timeout=timeout) + result = godbolt.normalise("run", data) + out.parent.mkdir(parents=True, exist_ok=True) + out.write_text(json.dumps({"tool": "godbolt", "compiler": compiler, "mojoVersion": pin["mojo"]["version"], + "source_sha256": sha, "asked": date.today().isoformat(), "result": result}, + indent=2, ensure_ascii=False) + "\n") + asked += 1 + print(f"[library] {it['id']}: compiled={result['compiled']} exit={result['exitCode']}") + print(f"[library] asked {asked} program(s)") + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/src/engines/pseudo/check.js b/src/engines/pseudo/check.js index b026bda..724ebb6 100644 --- a/src/engines/pseudo/check.js +++ b/src/engines/pseudo/check.js @@ -177,7 +177,10 @@ class Checker { if (s.name.startsWith('<')) this.subs.set(`${up(s.name)}#${s.line}`, { name: s.name, kind: s.kind, node: s, params: [], returns: null, requires: [], ensures: [], decreases: null }); else if (this.subs.has(up(s.name))) this.error('duplicate', s, `${s.name} is already defined on line ${this.subs.get(up(s.name)).node.line}.`); else if ((BUILTINS[up(s.name)] && !SOFT_BUILTINS.has(up(s.name))) || SIZED[up(s.name)]) this.error('builtin-name', s, `${up(s.name)} is a built-in, so a ${s.kind.toUpperCase()} cannot take its name.`); - else if (this.libs.has(up(s.name))) this.error('library-clash', s, `${s.name} also comes from the library (USE ${this.libOrigin.get(up(s.name))?.module} on line ${this.libOrigin.get(up(s.name))?.line}). Rename this one, or bring in only the routines you need: USE ${this.libOrigin.get(up(s.name))?.module}..`, { guide: 'libraries' }); + else if (this.libs.has(up(s.name))) { + this.error('library-clash', s, `${s.name} also comes from the library (USE ${this.libOrigin.get(up(s.name))?.module} on line ${this.libOrigin.get(up(s.name))?.line}). Rename this one, or bring in only the routines you need: USE ${this.libOrigin.get(up(s.name))?.module}..`, { guide: 'libraries' }); + this.subs.set(up(s.name), { name: s.name, kind: s.kind, node: s, params: [], returns: null, requires: [], ensures: [], decreases: null }); + } else this.subs.set(up(s.name), { name: s.name, kind: s.kind, node: s, params: [], returns: null, requires: [], ensures: [], decreases: null }); } } diff --git a/src/engines/pseudo/interp.js b/src/engines/pseudo/interp.js index d6ffbf7..2be60f2 100644 --- a/src/engines/pseudo/interp.js +++ b/src/engines/pseudo/interp.js @@ -289,7 +289,7 @@ class Interpreter { runCall(name, args) { this.start(); - const sub = this.program.subs.get(up(name)); + const sub = this.program.subs.get(up(name)) || this.program.libs?.get(up(name)); if (!sub) throw new PseudoError('value', `No FUNCTION or PROCEDURE is called ${name}.`, null); if (args.length !== sub.params.length) throw new PseudoError('value', `${sub.name} takes ${plural(sub.params.length, 'value')}, and ${args.length} ${args.length === 1 ? 'was' : 'were'} given.`, sub.node); sub.params.forEach((p, i) => { @@ -1221,8 +1221,8 @@ class Interpreter { if (old && n.kind === 'Name' && old.has(up(n.name))) return old.get(up(n.name)); return this.evaluate(n); } - if (e.sub || this.program.subs.get(up(e.name))) { - const sub = e.sub || this.program.subs.get(up(e.name)); + if (e.sub || this.program.subs.get(up(e.name)) || this.program.libs?.get(up(e.name))) { + const sub = e.sub || this.program.subs.get(up(e.name)) || this.program.libs.get(up(e.name)); const slots = this.argSlots(sub, e.args); return this.invoke(sub, slots, e, false); } @@ -1536,7 +1536,7 @@ export function run(program, options = {}) { throw e; } } - const sub = options.call ? program.subs.get(up(options.call.name)) : null; + const sub = options.call ? (program.subs.get(up(options.call.name)) || program.libs?.get(up(options.call.name))) : null; return { program, steps: it.steps, diff --git a/src/library/generated.ts b/src/library/generated.ts new file mode 100644 index 0000000..b360bb2 --- /dev/null +++ b/src/library/generated.ts @@ -0,0 +1,1703 @@ +// Generated by scripts/library.mjs emit from library/ (pplus-library). Do not edit; run pixi run library-emit. +import type { LibraryModule } from './types.js'; + +export const LIBRARY_COMMIT = "df12b2a0082c"; +export const LIBRARY_MODULES: LibraryModule[] = [ + { + "name": "align", + "title": "Sequence alignment", + "summary": "Scores for aligning two sequences: gap models, letter scores, and global alignment by dynamic programming.", + "routines": [ + { + "id": "align.AffineGapPenalty", + "module": "align", + "name": "AffineGapPenalty", + "dir": "modules/align/affine-gap", + "summary": "The score of a gap of Length positions when opening a gap scores Open and each further position scores Extend.", + "tags": [ + "alignment", + "gap model" + ], + "sources": [ + { + "title": "Gotoh, An improved algorithm for matching biological sequences, J. Mol. Biol. 162 (1982)", + "url": "https://doi.org/10.1016/0022-2836(82)90398-9" + } + ], + "source": "// AffineGapPenalty: the score of a gap of Length positions under an affine\n// gap model (Gotoh, 1982): Open for the first position and Extend for each\n// one after it, so one long gap costs less than many short ones. With\n// Open == Extend it is the linear model.\nFUNCTION AffineGapPenalty(Length : INTEGER, Open : INTEGER, Extend : INTEGER) RETURNS INTEGER\n REQUIRE Length >= 1\n ENSURE RESULT == Open + (Length - 1) * Extend\n RETURN Open + (Length - 1) * Extend\nENDFUNCTION\n", + "cases": [ + { + "call": "AffineGapPenalty(1, -10, -1)", + "result": "-10" + }, + { + "call": "AffineGapPenalty(5, -10, -1)", + "result": "-14" + }, + { + "call": "AffineGapPenalty(3, -2, -2)", + "result": "-6" + } + ], + "references": [ + { + "lang": "python", + "level": "plain", + "file": "ref/python/plain.py", + "note": "The same formula.", + "source": "def affine_gap_penalty(length, open_, extend):\n return open_ + (length - 1) * extend\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) (exactly)" + } + } + }, + { + "lang": "mojo", + "level": "plain", + "file": "ref/mojo/plain.mojo", + "note": "The same formula in Mojo.", + "source": "def affine_gap_penalty(length: Int, open_: Int, extend: Int) -> Int:\n return open_ + (length - 1) * extend\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) in core's interpreter (exactly)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "proof": { + "lang": "dafny", + "file": "proof/affine_gap.dfy", + "note": "The formula equals the score built position by position, and with Open == Extend it equals the linear model.", + "source": "method AffineGapPenalty(length: int, open: int, extend: int) returns (result: int)\n requires length >= 1\n ensures result == open + (length - 1) * extend\n{\n result := open + (length - 1) * extend;\n}\n\n// Position by position: the first position opens the gap, every later one extends it.\nmethod AffineByPositions(length: int, open: int, extend: int) returns (score: int)\n requires length >= 1\n ensures score == open + (length - 1) * extend\n{\n score := open;\n var i := 1;\n while i < length\n invariant 1 <= i <= length\n invariant score == open + (i - 1) * extend\n {\n score := score + extend;\n i := i + 1;\n }\n}\n\n// With the same score for opening and extending, the affine model is the linear one.\nlemma AffineIsLinearWhenEqual(length: int, gap: int)\n requires length >= 1\n ensures gap + (length - 1) * gap == length * gap\n{\n}\n", + "check": { + "status": "pass", + "detail": "Dafny 4.11.0: 3 verified, 0 errors" + } + }, + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION AffineGapPenalty" + }, + "pseudo": { + "status": "pass", + "detail": "3 case(s) run" + }, + "prover": { + "status": "pass", + "detail": "all 1 obligation(s) proved" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 201 generated input(s)" + }, + "mojo": { + "status": "pass", + "detail": "the generated Mojo prints what the pseudo prints on every case, in core's interpreter" + } + } + }, + { + "id": "align.LinearGapPenalty", + "module": "align", + "name": "LinearGapPenalty", + "dir": "modules/align/linear-gap", + "summary": "The score of a gap of Length positions when every position of a gap scores Gap.", + "tags": [ + "alignment", + "gap model" + ], + "sources": [ + { + "title": "Durbin, Eddy, Krogh and Mitchison, Biological Sequence Analysis, section 2.2" + } + ], + "source": "// LinearGapPenalty: the score of a gap of Length positions under a linear gap\n// model, where every position of a gap scores Gap (usually negative).\nFUNCTION LinearGapPenalty(Length : INTEGER, Gap : INTEGER) RETURNS INTEGER\n REQUIRE Length >= 0\n ENSURE RESULT == Length * Gap\n RETURN Length * Gap\nENDFUNCTION\n", + "cases": [ + { + "call": "LinearGapPenalty(3, -2)", + "result": "-6" + }, + { + "call": "LinearGapPenalty(0, -2)", + "result": "0" + }, + { + "call": "LinearGapPenalty(10, -1)", + "result": "-10" + } + ], + "references": [ + { + "lang": "python", + "level": "plain", + "file": "ref/python/plain.py", + "note": "The same product.", + "source": "def linear_gap_penalty(length, gap):\n return length * gap\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) (exactly)" + } + } + }, + { + "lang": "mojo", + "level": "plain", + "file": "ref/mojo/plain.mojo", + "note": "The same product in Mojo.", + "source": "def linear_gap_penalty(length: Int, gap: Int) -> Int:\n return length * gap\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) in core's interpreter (exactly)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "proof": { + "lang": "dafny", + "file": "proof/linear_gap.dfy", + "note": "The product equals the score built position by position: each of the Length positions adds Gap.", + "source": "// A gap of `length` positions under a linear model: each position scores `gap`.\nmethod LinearGapPenalty(length: int, gap: int) returns (result: int)\n requires length >= 0\n ensures result == length * gap\n{\n result := length * gap;\n}\n\n// The same score, built one position at a time: the product is the model, not a shortcut.\nmethod LinearGapByPositions(length: int, gap: int) returns (score: int)\n requires length >= 0\n ensures score == length * gap\n{\n score := 0;\n var i := 0;\n while i < length\n invariant 0 <= i <= length\n invariant score == i * gap\n {\n score := score + gap;\n i := i + 1;\n }\n}\n", + "check": { + "status": "pass", + "detail": "Dafny 4.11.0: 2 verified, 0 errors" + } + }, + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION LinearGapPenalty" + }, + "pseudo": { + "status": "pass", + "detail": "3 case(s) run" + }, + "prover": { + "status": "pass", + "detail": "all 1 obligation(s) proved" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 123 generated input(s)" + }, + "mojo": { + "status": "pass", + "detail": "the generated Mojo prints what the pseudo prints on every case, in core's interpreter" + } + } + }, + { + "id": "align.MatchScore", + "module": "align", + "name": "MatchScore", + "dir": "modules/align/match-score", + "summary": "The score of aligning letter A with letter B: Match when they are the same, Mismatch otherwise.", + "tags": [ + "alignment", + "scoring" + ], + "sources": [ + { + "title": "Durbin, Eddy, Krogh and Mitchison, Biological Sequence Analysis, section 2.2" + } + ], + "source": "// MatchScore: the score of aligning letter A with letter B: Match when they\n// are the same letter, Mismatch otherwise. The simplest substitution score;\n// a substitution matrix such as BLOSUM62 replaces it for proteins.\nFUNCTION MatchScore(A : CHAR, B : CHAR, Match : INTEGER, Mismatch : INTEGER) RETURNS INTEGER\n ENSURE (A == B AND RESULT == Match) OR (A != B AND RESULT == Mismatch)\n IF A == B THEN\n RETURN Match\n ENDIF\n RETURN Mismatch\nENDFUNCTION\n", + "cases": [ + { + "call": "MatchScore('A', 'A', 1, -1)", + "result": "1" + }, + { + "call": "MatchScore('A', 'G', 1, -1)", + "result": "-1" + }, + { + "call": "MatchScore('T', 'T', 5, -4)", + "result": "5" + } + ], + "references": [ + { + "lang": "python", + "level": "plain", + "file": "ref/python/plain.py", + "note": "The same test.", + "source": "def match_score(a, b, match, mismatch):\n return match if a == b else mismatch\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) (exactly)" + } + } + }, + { + "lang": "mojo", + "level": "plain", + "file": "ref/mojo/plain.mojo", + "note": "The same test in Mojo; a letter is a String of one character.", + "source": "def match_score(a: String, b: String, match_: Int, mismatch: Int) -> Int:\n if a == b:\n return match_\n return mismatch\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) in core's interpreter (exactly)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "proof": { + "lang": "dafny", + "file": "proof/match_score.dfy", + "note": "The score is Match exactly when the letters agree.", + "source": "method MatchScore(a: char, b: char, match_: int, mismatch: int) returns (r: int)\n ensures (a == b && r == match_) || (a != b && r == mismatch)\n{\n if a == b { r := match_; } else { r := mismatch; }\n}\n", + "check": { + "status": "pass", + "detail": "Dafny 4.11.0: 1 verified, 0 errors" + } + }, + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION MatchScore" + }, + "pseudo": { + "status": "pass", + "detail": "3 case(s) run" + }, + "prover": { + "status": "pass", + "detail": "all 2 obligation(s) proved" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 285 generated input(s)" + }, + "mojo": { + "status": "pass", + "detail": "the generated Mojo prints what the pseudo prints on every case, in core's interpreter" + } + } + }, + { + "id": "align.NeedlemanWunschScore", + "module": "align", + "name": "NeedlemanWunschScore", + "dir": "modules/align/needleman-wunsch-score", + "summary": "The best score of a global alignment of two sequences with a linear gap model, by dynamic programming.", + "tags": [ + "alignment", + "dynamic programming" + ], + "sources": [ + { + "title": "Needleman and Wunsch, A general method applicable to the search for similarities in the amino acid sequence of two proteins, J. Mol. Biol. 48 (1970)", + "url": "https://doi.org/10.1016/0022-2836(70)90057-4" + } + ], + "source": "// NeedlemanWunschScore: the best score of a global alignment of S and T\n// (Needleman and Wunsch, 1970) with a linear gap model, by dynamic\n// programming. D[I, J] is the best score of aligning the first I letters of\n// S with the first J letters of T; each cell takes the best of three moves:\n// align S[I - 1] with T[J - 1], or put a gap in one sequence or the other.\nUSE align.MatchScore\nUSE align.LinearGapPenalty\nFUNCTION NeedlemanWunschScore(S : STRING, T : STRING, Match : INTEGER, Mismatch : INTEGER, Gap : INTEGER) RETURNS INTEGER\n DECLARE N : INTEGER <- LENGTH(S)\n DECLARE M : INTEGER <- LENGTH(T)\n DECLARE D : ARRAY[N + 1, M + 1] OF INTEGER\n FOR I <- 0 TO N + 1\n D[I, 0] <- LinearGapPenalty(I, Gap)\n NEXT I\n FOR J <- 1 TO M + 1\n D[0, J] <- LinearGapPenalty(J, Gap)\n NEXT J\n FOR I <- 1 TO N + 1\n FOR J <- 1 TO M + 1\n DECLARE Diagonal : INTEGER <- D[I - 1, J - 1] + MatchScore(S[I - 1], T[J - 1], Match, Mismatch)\n DECLARE Down : INTEGER <- D[I - 1, J] + Gap\n DECLARE Across : INTEGER <- D[I, J - 1] + Gap\n D[I, J] <- MAX(Diagonal, Down, Across)\n NEXT J\n NEXT I\n RETURN D[N, M]\nENDFUNCTION\n", + "cases": [ + { + "call": "NeedlemanWunschScore(\"GATTACA\", \"GCATGCU\", 1, -1, -1)", + "result": "0" + }, + { + "call": "NeedlemanWunschScore(\"ACGT\", \"ACGT\", 1, -1, -2)", + "result": "4" + }, + { + "call": "NeedlemanWunschScore(\"\", \"ACG\", 1, -1, -2)", + "result": "-6" + }, + { + "call": "NeedlemanWunschScore(\"AAAA\", \"TTTT\", 2, -3, -1)", + "result": "-8" + } + ], + "references": [ + { + "lang": "python", + "level": "plain", + "file": "ref/python/plain.py", + "note": "The same table, filled row by row.", + "source": "def needleman_wunsch_score(s, t, match, mismatch, gap):\n n, m = len(s), len(t)\n d = [[0] * (m + 1) for _ in range(n + 1)]\n for i in range(n + 1):\n d[i][0] = i * gap\n for j in range(1, m + 1):\n d[0][j] = j * gap\n for i in range(1, n + 1):\n for j in range(1, m + 1):\n diagonal = d[i - 1][j - 1] + (match if s[i - 1] == t[j - 1] else mismatch)\n d[i][j] = max(diagonal, d[i - 1][j] + gap, d[i][j - 1] + gap)\n return d[n][m]\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 4 case(s) (exactly)" + } + } + }, + { + "lang": "python", + "level": "two-rows", + "file": "ref/python/two-rows.py", + "note": "Only the previous row is kept: memory grows with the length of T alone, the first step toward Hirschberg's linear-space alignment.", + "source": "def needleman_wunsch_score(s, t, match, mismatch, gap):\n m = len(t)\n prev = [j * gap for j in range(m + 1)]\n for i in range(1, len(s) + 1):\n cur = [i * gap] + [0] * m\n for j in range(1, m + 1):\n diagonal = prev[j - 1] + (match if s[i - 1] == t[j - 1] else mismatch)\n cur[j] = max(diagonal, prev[j] + gap, cur[j - 1] + gap)\n prev = cur\n return prev[m]\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 4 case(s) (exactly)" + } + } + }, + { + "lang": "mojo", + "level": "plain", + "file": "ref/mojo/plain.mojo", + "note": "The same table in Mojo, as a list of rows.", + "source": "def needleman_wunsch_score(s: String, t: String, match_: Int, mismatch: Int, gap: Int) -> Int:\n var n = s.count_codepoints()\n var m = t.count_codepoints()\n var d = List[List[Int]]()\n for i in range(n + 1):\n var row = List[Int]()\n for j in range(m + 1):\n row.append(0)\n d.append(row^)\n for i in range(n + 1):\n d[i][0] = i * gap\n for j in range(1, m + 1):\n d[0][j] = j * gap\n for i in range(1, n + 1):\n for j in range(1, m + 1):\n var score = mismatch\n if String(s[codepoint=i - 1]) == String(t[codepoint=j - 1]):\n score = match_\n var best = d[i - 1][j - 1] + score\n if d[i - 1][j] + gap > best:\n best = d[i - 1][j] + gap\n if d[i][j - 1] + gap > best:\n best = d[i][j - 1] + gap\n d[i][j] = best\n return d[n][m]\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 4 case(s) in core's interpreter (exactly)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION NeedlemanWunschScore, using align.MatchScore, align.LinearGapPenalty" + }, + "pseudo": { + "status": "pass", + "detail": "4 case(s) run" + }, + "prover": { + "status": "pass", + "detail": "all 11 obligation(s) proved" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 300 generated input(s)" + }, + "mojo": { + "status": "pass", + "detail": "the generated Mojo prints what the pseudo prints on every case, in core's interpreter" + } + } + } + ] + }, + { + "name": "md", + "title": "Molecular simulation", + "summary": "Pair potentials, forces and periodic boxes, the inner loop of molecular dynamics.", + "routines": [ + { + "id": "md.LennardJones", + "module": "md", + "name": "LennardJones", + "dir": "modules/md/lennard-jones", + "summary": "The Lennard-Jones pair potential at distance R, with well depth Epsilon and zero-crossing distance Sigma.", + "tags": [ + "molecular dynamics", + "pair potential" + ], + "sources": [ + { + "title": "Jones, On the determination of molecular fields II, Proc. R. Soc. A 106 (1924)", + "url": "https://doi.org/10.1098/rspa.1924.0082" + }, + { + "title": "Allen and Tildesley, Computer Simulation of Liquids, section 1.4" + } + ], + "source": "// LennardJones: the Lennard-Jones pair potential at distance R,\n// V(R) = 4 Epsilon ((Sigma / R)^12 - (Sigma / R)^6). Epsilon is the depth of\n// the well, reached at R = 2^(1/6) Sigma, and V is 0 at R = Sigma. The powers\n// are built by multiplication from (Sigma / R)^2, as simulation codes do,\n// which is faster than ^ and rounds a little differently.\nFUNCTION LennardJones(R : FLOAT, Epsilon : FLOAT, Sigma : FLOAT) RETURNS FLOAT\n REQUIRE R > 0.0\n DECLARE S2 : FLOAT <- (Sigma / R) * (Sigma / R)\n DECLARE S6 : FLOAT <- S2 * S2 * S2\n RETURN 4.0 * Epsilon * (S6 * S6 - S6)\nENDFUNCTION\n", + "cases": [ + { + "call": "LennardJones(1.0, 1.0, 1.0)", + "result": "0.0" + }, + { + "call": "LennardJones(1.122462048309373, 1.0, 1.0)", + "result": "-1.0" + }, + { + "call": "LennardJones(2.5, 0.238, 3.4)", + "result": "32.09189752256677" + }, + { + "call": "LennardJones(0.9, 1.0, 1.0)", + "result": "6.6361189532529234" + } + ], + "references": [ + { + "lang": "python", + "level": "multiply", + "file": "ref/python/multiply.py", + "note": "The same multiplications.", + "source": "def lennard_jones(r, epsilon, sigma):\n s2 = (sigma / r) * (sigma / r)\n s6 = s2 * s2 * s2\n return 4.0 * epsilon * (s6 * s6 - s6)\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 4 case(s) (exactly)" + } + } + }, + { + "lang": "python", + "level": "powers", + "file": "ref/python/powers.py", + "note": "The textbook formula with ** 12 and ** 6: the same function, rounded differently, held to agree to 12 digits.", + "rel": 1e-12, + "source": "def lennard_jones(r, epsilon, sigma):\n return 4.0 * epsilon * ((sigma / r) ** 12 - (sigma / r) ** 6)\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 4 case(s) (within rel 1e-12, abs 0)" + } + } + }, + { + "lang": "c", + "level": "multiply", + "file": "ref/c/multiply.c", + "note": "The same multiplications in C.", + "source": "double lennard_jones(double r, double epsilon, double sigma) {\n double s2 = (sigma / r) * (sigma / r);\n double s6 = s2 * s2 * s2;\n return 4.0 * epsilon * (s6 * s6 - s6);\n}\n", + "checks": { + "cc -O0": { + "status": "pass", + "detail": "agrees with the pseudo on 4 case(s) (exactly)" + }, + "cc -O2": { + "status": "pass", + "detail": "agrees with the pseudo on 4 case(s) (exactly)" + } + } + }, + { + "lang": "mojo", + "level": "multiply", + "file": "ref/mojo/multiply.mojo", + "note": "The same multiplications in Mojo.", + "source": "def lennard_jones(r: Float64, epsilon: Float64, sigma: Float64) -> Float64:\n var s2 = (sigma / r) * (sigma / r)\n var s6 = s2 * s2 * s2\n return 4.0 * epsilon * (s6 * s6 - s6)\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 4 case(s) in core's interpreter (exactly)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "proof": { + "lang": "dafny", + "file": "proof/lennard_jones.dfy", + "note": "Over real numbers the multiplications compute the textbook formula exactly, and V(Sigma) = 0.", + "source": "function Pow(x: real, n: nat): real\n{\n if n == 0 then 1.0 else x * Pow(x, n - 1)\n}\n\nfunction LJ(r: real, epsilon: real, sigma: real): real\n requires r > 0.0\n{\n 4.0 * epsilon * (Pow(sigma / r, 12) - Pow(sigma / r, 6))\n}\n\nlemma PowAdd(x: real, a: nat, b: nat)\n ensures Pow(x, a + b) == Pow(x, a) * Pow(x, b)\n{\n if a > 0 {\n PowAdd(x, a - 1, b);\n assert Pow(x, a + b) == x * Pow(x, a - 1 + b);\n }\n}\n\nlemma Pow2(x: real)\n ensures Pow(x, 2) == x * x\n{\n assert Pow(x, 1) == x;\n}\n\nlemma Pow6(s: real)\n ensures Pow(s, 6) == (s * s) * (s * s) * (s * s)\n{\n Pow2(s);\n PowAdd(s, 2, 2);\n PowAdd(s, 4, 2);\n}\n\nlemma Pow12(s: real)\n ensures Pow(s, 12) == Pow(s, 6) * Pow(s, 6)\n{\n PowAdd(s, 6, 6);\n}\n\nmethod LennardJones(r: real, epsilon: real, sigma: real) returns (v: real)\n requires r > 0.0\n ensures v == LJ(r, epsilon, sigma)\n{\n var s := sigma / r;\n var s2 := s * s;\n var s6 := s2 * s2 * s2;\n Pow6(s);\n Pow12(s);\n v := 4.0 * epsilon * (s6 * s6 - s6);\n}\n\n// The potential crosses zero at R = Sigma.\nlemma ZeroAtSigma(epsilon: real, sigma: real)\n requires sigma > 0.0\n ensures LJ(sigma, epsilon, sigma) == 0.0\n{\n assert sigma / sigma == 1.0;\n}\n", + "check": { + "status": "pass", + "detail": "Dafny 4.11.0: 14 verified, 0 errors" + } + }, + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION LennardJones" + }, + "pseudo": { + "status": "pass", + "detail": "4 case(s) run" + }, + "prover": { + "status": "pass", + "detail": "all 2 obligation(s) proved" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 252 generated input(s)" + }, + "mojo": { + "status": "pass", + "detail": "the generated Mojo prints what the pseudo prints on every case, in core's interpreter" + } + } + }, + { + "id": "md.LennardJonesForce", + "module": "md", + "name": "LennardJonesForce", + "dir": "modules/md/lennard-jones-force", + "summary": "The force between two particles at distance R under the Lennard-Jones potential: positive pushes them apart.", + "tags": [ + "molecular dynamics", + "force" + ], + "sources": [ + { + "title": "Allen and Tildesley, Computer Simulation of Liquids, section 1.4" + } + ], + "source": "// LennardJonesForce: the force between two particles at distance R under\n// the Lennard-Jones potential, F(R) = -dV/dR\n// = 24 Epsilon / R (2 (Sigma / R)^12 - (Sigma / R)^6).\n// Positive pushes the particles apart; it is 0 at the bottom of the well.\nFUNCTION LennardJonesForce(R : FLOAT, Epsilon : FLOAT, Sigma : FLOAT) RETURNS FLOAT\n REQUIRE R > 0.0\n DECLARE S2 : FLOAT <- (Sigma / R) * (Sigma / R)\n DECLARE S6 : FLOAT <- S2 * S2 * S2\n RETURN 24.0 * Epsilon * (2.0 * S6 * S6 - S6) / R\nENDFUNCTION\n", + "cases": [ + { + "call": "LennardJonesForce(1.0, 1.0, 1.0)", + "result": "24.0" + }, + { + "call": "LennardJonesForce(1.122462048309373, 1.0, 1.0)", + "result": "-2.3738310467722616e-15" + }, + { + "call": "LennardJonesForce(2.5, 0.238, 3.4)", + "result": "168.49822326347663" + } + ], + "references": [ + { + "lang": "python", + "level": "multiply", + "file": "ref/python/multiply.py", + "note": "The same multiplications.", + "source": "def lennard_jones_force(r, epsilon, sigma):\n s2 = (sigma / r) * (sigma / r)\n s6 = s2 * s2 * s2\n return 24.0 * epsilon * (2.0 * s6 * s6 - s6) / r\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) (exactly)" + } + } + }, + { + "lang": "mojo", + "level": "multiply", + "file": "ref/mojo/multiply.mojo", + "note": "The same multiplications in Mojo.", + "source": "def lennard_jones_force(r: Float64, epsilon: Float64, sigma: Float64) -> Float64:\n var s2 = (sigma / r) * (sigma / r)\n var s6 = s2 * s2 * s2\n return 24.0 * epsilon * (2.0 * s6 * s6 - s6) / r\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) in core's interpreter (exactly)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION LennardJonesForce" + }, + "pseudo": { + "status": "pass", + "detail": "3 case(s) run" + }, + "prover": { + "status": "pass", + "detail": "all 3 obligation(s) proved" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 252 generated input(s)" + }, + "mojo": { + "status": "pass", + "detail": "the generated Mojo prints what the pseudo prints on every case, in core's interpreter" + } + } + }, + { + "id": "md.MinimumImage", + "module": "md", + "name": "MinimumImage", + "dir": "modules/md/minimum-image", + "summary": "A displacement brought to its nearest periodic image in a box of length Box: the minimum image convention.", + "tags": [ + "molecular dynamics", + "periodic boundary conditions" + ], + "sources": [ + { + "title": "Allen and Tildesley, Computer Simulation of Liquids, section 1.5.2" + } + ], + "source": "// MinimumImage: the displacement Dx brought to its nearest periodic image in\n// a box of length Box, the minimum image convention: Dx minus the whole\n// number of box lengths that brings it into [-Box / 2, Box / 2). FLOOR of\n// Dx / Box + 0.5 rounds halves upward, so exactly half a box maps to -Box / 2.\nFUNCTION MinimumImage(Dx : FLOAT, Box : FLOAT) RETURNS FLOAT\n REQUIRE Box > 0.0\n RETURN Dx - Box * FLOOR(Dx / Box + 0.5)\nENDFUNCTION\n", + "cases": [ + { + "call": "MinimumImage(0.75, 1.0)", + "result": "-0.25" + }, + { + "call": "MinimumImage(-0.75, 1.0)", + "result": "0.25" + }, + { + "call": "MinimumImage(2.3, 1.0)", + "result": "0.2999999999999998" + }, + { + "call": "MinimumImage(0.5, 1.0)", + "result": "-0.5" + }, + { + "call": "MinimumImage(-12.0, 10.0)", + "result": "-2.0" + } + ], + "references": [ + { + "lang": "python", + "level": "plain", + "file": "ref/python/plain.py", + "note": "The same formula with math.floor.", + "source": "import math\n\n\ndef minimum_image(dx, box):\n return dx - box * math.floor(dx / box + 0.5)\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 5 case(s) (exactly)" + } + } + }, + { + "lang": "c", + "level": "plain", + "file": "ref/c/plain.c", + "note": "The same formula with floor from math.h.", + "source": "#include \n\ndouble minimum_image(double dx, double box) {\n return dx - box * floor(dx / box + 0.5);\n}\n", + "checks": { + "cc -O0": { + "status": "pass", + "detail": "agrees with the pseudo on 5 case(s) (exactly)" + }, + "cc -O2": { + "status": "pass", + "detail": "agrees with the pseudo on 5 case(s) (exactly)" + } + } + }, + { + "lang": "mojo", + "level": "plain", + "file": "ref/mojo/plain.mojo", + "note": "The same formula in Mojo, with floor from std.math.", + "source": "from std.math import floor\n\n\ndef minimum_image(dx: Float64, box: Float64) -> Float64:\n return dx - box * floor(dx / box + 0.5)\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 5 case(s) in core's interpreter (exactly)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "proof": { + "lang": "dafny", + "file": "proof/minimum_image.dfy", + "note": "Over real numbers the result lies in [-Box / 2, Box / 2) and differs from Dx by a whole number of box lengths.", + "source": "// MinimumImage, over real numbers: the image lies in [-box / 2, box / 2) and is a whole number of box lengths from dx.\nlemma ScaledBounds(g: real, box: real)\n requires box > 0.0\n requires -0.5 <= g < 0.5\n ensures -box / 2.0 <= g * box < box / 2.0\n{\n assert (g + 0.5) * box >= 0.0;\n assert (0.5 - g) * box > 0.0;\n}\n\nmethod MinimumImage(dx: real, box: real) returns (r: real, k: int)\n requires box > 0.0\n ensures r == dx - box * (k as real)\n ensures -box / 2.0 <= r < box / 2.0\n{\n var q := dx / box + 0.5;\n k := q.Floor;\n assert (k as real) <= q < (k as real) + 1.0;\n var g := q - (k as real) - 0.5;\n assert -0.5 <= g < 0.5;\n assert dx == (q - 0.5) * box;\n r := dx - box * (k as real);\n assert r == g * box;\n ScaledBounds(g, box);\n}\n", + "check": { + "status": "pass", + "detail": "Dafny 4.11.0: 4 verified, 0 errors" + } + }, + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION MinimumImage" + }, + "pseudo": { + "status": "pass", + "detail": "5 case(s) run" + }, + "prover": { + "status": "pass", + "detail": "all 1 obligation(s) proved" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 241 generated input(s)" + }, + "mojo": { + "status": "pass", + "detail": "the generated Mojo prints what the pseudo prints on every case, in core's interpreter" + } + } + }, + { + "id": "md.PairDistance", + "module": "md", + "name": "PairDistance", + "dir": "modules/md/pair-distance", + "summary": "The distance between two points in a cubic periodic box, each coordinate difference taken by the minimum image convention.", + "tags": [ + "molecular dynamics", + "periodic boundary conditions" + ], + "sources": [ + { + "title": "Allen and Tildesley, Computer Simulation of Liquids, section 1.5.2" + } + ], + "source": "// PairDistance: the distance between two points in a cubic periodic box of\n// side Box, each coordinate difference taken by the minimum image\n// convention. HYPOT adds the squares without overflowing on the way.\nUSE md.MinimumImage\nFUNCTION PairDistance(A : LIST OF FLOAT, B : LIST OF FLOAT, Box : FLOAT) RETURNS FLOAT\n REQUIRE LENGTH(A) == 3 AND LENGTH(B) == 3 AND Box > 0.0\n DECLARE Dx : FLOAT <- MinimumImage(A[0] - B[0], Box)\n DECLARE Dy : FLOAT <- MinimumImage(A[1] - B[1], Box)\n DECLARE Dz : FLOAT <- MinimumImage(A[2] - B[2], Box)\n RETURN HYPOT(HYPOT(Dx, Dy), Dz)\nENDFUNCTION\n", + "cases": [ + { + "call": "PairDistance([0.1, 0.1, 0.1], [0.9, 0.9, 0.9], 1.0)", + "result": "0.34641016151377535" + }, + { + "call": "PairDistance([0.0, 0.0, 0.0], [3.0, 4.0, 0.0], 20.0)", + "result": "5.0" + }, + { + "call": "PairDistance([1.0, 2.0, 3.0], [1.0, 2.0, 3.0], 5.0)", + "result": "0.0" + } + ], + "references": [ + { + "lang": "python", + "level": "plain", + "file": "ref/python/plain.py", + "note": "The same steps, with math.hypot of all three differences at once.", + "rel": 1e-15, + "source": "import math\n\n\ndef pair_distance(a, b, box):\n d = [x - y for x, y in zip(a, b)]\n d = [v - box * math.floor(v / box + 0.5) for v in d]\n return math.hypot(*d)\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) (within rel 1e-15, abs 0)" + } + } + }, + { + "lang": "mojo", + "level": "plain", + "file": "ref/mojo/plain.mojo", + "note": "The same steps in Mojo, with the square root of the sum of squares.", + "rel": 1e-15, + "source": "from std.math import floor, sqrt\n\n\ndef pair_distance(a: List[Float64], b: List[Float64], box: Float64) -> Float64:\n var total: Float64 = 0.0\n for i in range(3):\n var d = a[i] - b[i]\n d = d - box * floor(d / box + 0.5)\n total = total + d * d\n return sqrt(total)\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) in core's interpreter (within rel 1e-15, abs 0)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION PairDistance, using md.MinimumImage" + }, + "pseudo": { + "status": "pass", + "detail": "3 case(s) run" + }, + "prover": { + "status": "pass", + "detail": "all 9 obligation(s) proved" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 4 generated input(s)" + }, + "mojo": { + "status": "skipped", + "detail": "core's Mojo interpreter declines hypot(...) as written here; the compiler's answer is needed" + } + } + } + ] + }, + { + "name": "numerics", + "title": "Numerics", + "summary": "Summing, interpolating and integrating with FLOAT values, and what rounding does to each.", + "routines": [ + { + "id": "numerics.KahanSum", + "module": "numerics", + "name": "KahanSum", + "dir": "modules/numerics/kahan-sum", + "summary": "The sum of a list of FLOAT values by compensated summation, whose error does not grow with the length of the list.", + "tags": [ + "summation", + "rounding", + "precision" + ], + "sources": [ + { + "title": "Kahan, Further remarks on reducing truncation errors, CACM 8(1), 1965", + "url": "https://doi.org/10.1145/363707.363723" + }, + { + "title": "Higham, Accuracy and Stability of Numerical Algorithms, section 4.3" + } + ], + "source": "// KahanSum: the sum of a list of FLOAT values by compensated summation\n// (Kahan, 1965). C holds the low-order part the last addition lost, and the\n// next addition puts it back, so the error does not grow with the length of\n// the list. In exact arithmetic C is always 0 and this is the plain sum: the\n// compensation exists only because of rounding. A compiler allowed to\n// reorder FLOAT arithmetic (-ffast-math) can simplify C away.\nFUNCTION KahanSum(X : LIST OF FLOAT) RETURNS FLOAT\n DECLARE Total : FLOAT <- 0.0\n DECLARE C : FLOAT <- 0.0\n FOR I <- 0 TO LENGTH(X)\n DECLARE Y : FLOAT <- X[I] - C\n DECLARE T : FLOAT <- Total + Y\n C <- (T - Total) - Y\n Total <- T\n NEXT I\n RETURN Total\nENDFUNCTION\n", + "cases": [ + { + "call": "KahanSum([1.0, 2.0, 3.0])", + "result": "6.0" + }, + { + "call": "KahanSum([1.0, 1.0e-16, 1.0e-16, 1.0e-16, 1.0e-16, 1.0e-16, 1.0e-16, 1.0e-16, 1.0e-16, 1.0e-16, 1.0e-16])", + "result": "1.000000000000001" + }, + { + "call": "KahanSum([0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1])", + "result": "1.0" + }, + { + "call": "KahanSum([])", + "result": "0.0" + } + ], + "references": [ + { + "lang": "python", + "level": "plain", + "file": "ref/python/plain.py", + "note": "The same compensated loop.", + "source": "def kahan_sum(x):\n total = 0.0\n c = 0.0\n for v in x:\n y = v - c\n t = total + y\n c = (t - total) - y\n total = t\n return total\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 4 case(s) (exactly)" + } + } + }, + { + "lang": "c", + "level": "plain", + "file": "ref/c/plain.c", + "note": "The same loop in C. It survives -O2; it would not survive -ffast-math, which lets the compiler treat (t - total) - y as 0.", + "source": "double kahan_sum(const double *x, long n) {\n double total = 0.0, c = 0.0;\n for (long i = 0; i < n; i++) {\n double y = x[i] - c;\n double t = total + y;\n c = (t - total) - y;\n total = t;\n }\n return total;\n}\n", + "checks": { + "cc -O0": { + "status": "pass", + "detail": "agrees with the pseudo on 4 case(s) (exactly)" + }, + "cc -O2": { + "status": "pass", + "detail": "agrees with the pseudo on 4 case(s) (exactly)" + } + } + }, + { + "lang": "mojo", + "level": "plain", + "file": "ref/mojo/plain.mojo", + "note": "The same loop in Mojo.", + "source": "def kahan_sum(x: List[Float64]) -> Float64:\n var total: Float64 = 0.0\n var c: Float64 = 0.0\n for i in range(len(x)):\n var y = x[i] - c\n var t = total + y\n c = (t - total) - y\n total = t\n return total\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 4 case(s) in core's interpreter (exactly)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "proof": { + "lang": "dafny", + "file": "proof/kahan_sum.dfy", + "note": "Over real numbers the compensation C stays 0 and the result is exactly the sum: what Kahan summation corrects is rounding, and nothing else.", + "source": "function Sum(x: seq): real\n{\n if |x| == 0 then 0.0 else Sum(x[..|x| - 1]) + x[|x| - 1]\n}\n\n// In exact arithmetic Kahan summation is the plain sum, and its compensation is always 0.\nmethod KahanSum(x: seq) returns (total: real)\n ensures total == Sum(x)\n{\n total := 0.0;\n var c := 0.0;\n var i := 0;\n while i < |x|\n invariant 0 <= i <= |x|\n invariant total == Sum(x[..i])\n invariant c == 0.0\n {\n assert x[..i + 1][..i] == x[..i];\n var y := x[i] - c;\n var t := total + y;\n c := (t - total) - y;\n total := t;\n i := i + 1;\n }\n assert x[..|x|] == x;\n}\n", + "check": { + "status": "pass", + "detail": "Dafny 4.11.0: 2 verified, 0 errors" + } + }, + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION KahanSum" + }, + "pseudo": { + "status": "pass", + "detail": "4 case(s) run" + }, + "prover": { + "status": "pass", + "detail": "all 1 obligation(s) proved" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 263 generated input(s)" + }, + "mojo": { + "status": "pass", + "detail": "the generated Mojo prints what the pseudo prints on every case, in core's interpreter" + } + } + }, + { + "id": "numerics.LinearInterp", + "module": "numerics", + "name": "LinearInterp", + "dir": "modules/numerics/linear-interp", + "summary": "The value at X on the straight line through (X0, Y0) and (X1, Y1).", + "tags": [ + "interpolation" + ], + "sources": [ + { + "title": "Any numerical methods text: linear interpolation" + } + ], + "source": "// LinearInterp: the value at X on the straight line through (X0, Y0) and\n// (X1, Y1). X may lie outside [X0, X1]: that is extrapolation, and the line\n// carries on. The REQUIRE names the difference the division divides by.\nFUNCTION LinearInterp(X0 : FLOAT, Y0 : FLOAT, X1 : FLOAT, Y1 : FLOAT, X : FLOAT) RETURNS FLOAT\n REQUIRE X1 - X0 != 0.0\n RETURN Y0 + (Y1 - Y0) * (X - X0) / (X1 - X0)\nENDFUNCTION\n", + "cases": [ + { + "call": "LinearInterp(0.0, 0.0, 10.0, 5.0, 4.0)", + "result": "2.0" + }, + { + "call": "LinearInterp(1.0, 2.0, 3.0, 2.0, 2.5)", + "result": "2.0" + }, + { + "call": "LinearInterp(0.0, 1.0, 1.0, 3.0, 2.0)", + "result": "5.0" + } + ], + "references": [ + { + "lang": "python", + "level": "plain", + "file": "ref/python/plain.py", + "note": "The same formula.", + "source": "def linear_interp(x0, y0, x1, y1, x):\n return y0 + (y1 - y0) * (x - x0) / (x1 - x0)\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) (exactly)" + } + } + }, + { + "lang": "mojo", + "level": "plain", + "file": "ref/mojo/plain.mojo", + "note": "The same formula in Mojo.", + "source": "def linear_interp(x0: Float64, y0: Float64, x1: Float64, y1: Float64, x: Float64) -> Float64:\n return y0 + (y1 - y0) * (x - x0) / (x1 - x0)\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) in core's interpreter (exactly)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION LinearInterp" + }, + "pseudo": { + "status": "pass", + "detail": "3 case(s) run" + }, + "prover": { + "status": "pass", + "detail": "all 1 obligation(s) proved" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 300 generated input(s)" + }, + "mojo": { + "status": "pass", + "detail": "the generated Mojo prints what the pseudo prints on every case, in core's interpreter" + } + } + }, + { + "id": "numerics.Trapezoid", + "module": "numerics", + "name": "Trapezoid", + "dir": "modules/numerics/trapezoid", + "summary": "The integral of samples Y taken H apart, by the trapezoidal rule.", + "tags": [ + "integration", + "quadrature" + ], + "sources": [ + { + "title": "Any numerical methods text: the composite trapezoidal rule" + } + ], + "source": "// Trapezoid: the integral of samples Y taken H apart, by the composite\n// trapezoidal rule: the ends count half, every inside sample counts whole.\n// The error shrinks with H^2 for a smooth function.\nFUNCTION Trapezoid(Y : LIST OF FLOAT, H : FLOAT) RETURNS FLOAT\n REQUIRE LENGTH(Y) >= 2\n DECLARE Total : FLOAT <- (Y[0] + Y[LENGTH(Y) - 1]) / 2.0\n FOR I <- 1 TO LENGTH(Y) - 1\n Total <- Total + Y[I]\n NEXT I\n RETURN Total * H\nENDFUNCTION\n", + "cases": [ + { + "call": "Trapezoid([0.0, 1.0, 4.0, 9.0, 16.0], 1.0)", + "result": "22.0" + }, + { + "call": "Trapezoid([1.0, 1.0], 0.5)", + "result": "0.5" + }, + { + "call": "Trapezoid([0.0, 0.25, 1.0], 0.5)", + "result": "0.375" + } + ], + "references": [ + { + "lang": "python", + "level": "plain", + "file": "ref/python/plain.py", + "note": "The same sums.", + "source": "def trapezoid(y, h):\n total = (y[0] + y[len(y) - 1]) / 2.0\n for i in range(1, len(y) - 1):\n total += y[i]\n return total * h\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) (exactly)" + } + } + }, + { + "lang": "mojo", + "level": "plain", + "file": "ref/mojo/plain.mojo", + "note": "The same sums in Mojo.", + "source": "def trapezoid(y: List[Float64], h: Float64) -> Float64:\n var total: Float64 = (y[0] + y[len(y) - 1]) / 2.0\n for i in range(1, len(y) - 1):\n total = total + y[i]\n return total * h\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) in core's interpreter (exactly)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION Trapezoid" + }, + "pseudo": { + "status": "pass", + "detail": "3 case(s) run" + }, + "prover": { + "status": "pass", + "detail": "all 4 obligation(s) proved" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 227 generated input(s)" + }, + "mojo": { + "status": "pass", + "detail": "the generated Mojo prints what the pseudo prints on every case, in core's interpreter" + } + } + } + ] + }, + { + "name": "seq", + "title": "Sequences", + "summary": "Counting and comparing the letters of biological sequences.", + "routines": [ + { + "id": "seq.GCContent", + "module": "seq", + "name": "GCContent", + "dir": "modules/seq/gc-content", + "summary": "The fraction of the letters of a sequence that are G or C.", + "tags": [ + "sequences", + "counting" + ], + "sources": [ + { + "title": "Any molecular biology text: GC content" + } + ], + "source": "// GCContent: the fraction of the letters of S that are G or C. Other letters\n// (N for an unknown base, lowercase) count in the length and not in the count.\nFUNCTION GCContent(S : STRING) RETURNS FLOAT\n REQUIRE LENGTH(S) > 0\n DECLARE Count : INTEGER <- 0\n FOR I <- 0 TO LENGTH(S)\n IF S[I] == 'G' OR S[I] == 'C' THEN\n Count <- Count + 1\n ENDIF\n NEXT I\n RETURN Count / LENGTH(S)\nENDFUNCTION\n", + "cases": [ + { + "call": "GCContent(\"GATTACA\")", + "result": "0.2857142857142857" + }, + { + "call": "GCContent(\"GGCC\")", + "result": "1.0" + }, + { + "call": "GCContent(\"ATAT\")", + "result": "0.0" + } + ], + "references": [ + { + "lang": "python", + "level": "plain", + "file": "ref/python/plain.py", + "note": "The same count.", + "source": "def gc_content(s):\n count = 0\n for c in s:\n if c == \"G\" or c == \"C\":\n count += 1\n return count / len(s)\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) (exactly)" + } + } + }, + { + "lang": "mojo", + "level": "plain", + "file": "ref/mojo/plain.mojo", + "note": "The same count in Mojo.", + "source": "def gc_content(s: String) -> Float64:\n var count = 0\n for i in range(s.count_codepoints()):\n var c = String(s[codepoint=i])\n if c == \"G\" or c == \"C\":\n count = count + 1\n return Float64(count) / Float64(s.count_codepoints())\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) in core's interpreter (exactly)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "proof": { + "lang": "dafny", + "file": "proof/gc_content.dfy", + "note": "The count never exceeds the length, so the fraction lies in [0, 1].", + "source": "function GC(s: string, n: nat): nat\n requires n <= |s|\n{\n if n == 0 then 0 else GC(s, n - 1) + (if s[n - 1] == 'G' || s[n - 1] == 'C' then 1 else 0)\n}\n\nlemma GCAtMost(s: string, n: nat)\n requires n <= |s|\n ensures GC(s, n) <= n\n{\n if n > 0 { GCAtMost(s, n - 1); }\n}\n\nmethod GCContent(s: string) returns (f: real)\n requires |s| > 0\n ensures f == (GC(s, |s|) as real) / (|s| as real)\n ensures 0.0 <= f <= 1.0\n{\n var count := 0;\n var i := 0;\n while i < |s|\n invariant 0 <= i <= |s|\n invariant count == GC(s, i)\n {\n if s[i] == 'G' || s[i] == 'C' { count := count + 1; }\n i := i + 1;\n }\n GCAtMost(s, |s|);\n f := (count as real) / (|s| as real);\n}\n", + "check": { + "status": "pass", + "detail": "Dafny 4.11.0: 5 verified, 0 errors" + } + }, + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION GCContent" + }, + "pseudo": { + "status": "pass", + "detail": "3 case(s) run" + }, + "prover": { + "status": "pass", + "detail": "all 3 obligation(s) proved" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 469 generated input(s)" + }, + "mojo": { + "status": "pass", + "detail": "the generated Mojo prints what the pseudo prints on every case, in core's interpreter" + } + } + }, + { + "id": "seq.HammingDistance", + "module": "seq", + "name": "HammingDistance", + "dir": "modules/seq/hamming-distance", + "summary": "How many positions of two sequences of the same length hold different letters.", + "tags": [ + "sequences", + "distance" + ], + "sources": [ + { + "title": "Hamming, Error detecting and error correcting codes, Bell System Technical Journal 29 (1950)" + } + ], + "source": "// HammingDistance: how many positions of two sequences of the same length\n// hold different letters. The INVARIANT is what makes the ENSURE provable:\n// after I positions, at most I mismatches can have been counted.\nFUNCTION HammingDistance(S : STRING, T : STRING) RETURNS INTEGER\n REQUIRE LENGTH(S) == LENGTH(T)\n ENSURE 0 <= RESULT AND RESULT <= LENGTH(S)\n DECLARE Count : INTEGER <- 0\n FOR I <- 0 TO LENGTH(S)\n INVARIANT 0 <= Count AND Count <= I\n IF S[I] != T[I] THEN\n Count <- Count + 1\n ENDIF\n NEXT I\n RETURN Count\nENDFUNCTION\n", + "cases": [ + { + "call": "HammingDistance(\"GATTACA\", \"GACTATA\")", + "result": "2" + }, + { + "call": "HammingDistance(\"\", \"\")", + "result": "0" + }, + { + "call": "HammingDistance(\"AAAA\", \"TTTT\")", + "result": "4" + } + ], + "references": [ + { + "lang": "python", + "level": "plain", + "file": "ref/python/plain.py", + "note": "The same count.", + "source": "def hamming_distance(s, t):\n return sum(1 for a, b in zip(s, t) if a != b)\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) (exactly)" + } + } + }, + { + "lang": "mojo", + "level": "plain", + "file": "ref/mojo/plain.mojo", + "note": "The same count in Mojo.", + "source": "def hamming_distance(s: String, t: String) -> Int:\n var count = 0\n for i in range(s.count_codepoints()):\n if String(s[codepoint=i]) != String(t[codepoint=i]):\n count = count + 1\n return count\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) in core's interpreter (exactly)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "proof": { + "lang": "dafny", + "file": "proof/hamming_distance.dfy", + "note": "The loop computes the number of mismatched positions, which lies in [0, |S|].", + "source": "function Mismatches(s: string, t: string, n: nat): nat\n requires n <= |s| && n <= |t|\n{\n if n == 0 then 0 else Mismatches(s, t, n - 1) + (if s[n - 1] != t[n - 1] then 1 else 0)\n}\n\nlemma MismatchesAtMost(s: string, t: string, n: nat)\n requires n <= |s| && n <= |t|\n ensures Mismatches(s, t, n) <= n\n{\n if n > 0 { MismatchesAtMost(s, t, n - 1); }\n}\n\nmethod HammingDistance(s: string, t: string) returns (count: int)\n requires |s| == |t|\n ensures count == Mismatches(s, t, |s|)\n ensures 0 <= count <= |s|\n{\n count := 0;\n var i := 0;\n while i < |s|\n invariant 0 <= i <= |s|\n invariant count == Mismatches(s, t, i)\n {\n if s[i] != t[i] { count := count + 1; }\n i := i + 1;\n }\n MismatchesAtMost(s, t, |s|);\n}\n", + "check": { + "status": "pass", + "detail": "Dafny 4.11.0: 5 verified, 0 errors" + } + }, + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION HammingDistance" + }, + "pseudo": { + "status": "pass", + "detail": "3 case(s) run" + }, + "prover": { + "status": "pass", + "detail": "all 5 obligation(s) proved" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 291 generated input(s)" + }, + "mojo": { + "status": "pass", + "detail": "the generated Mojo prints what the pseudo prints on every case, in core's interpreter" + } + } + } + ] + }, + { + "name": "special", + "title": "Special functions", + "summary": "Functions with no exact built-in, as approximations with a stated error bound.", + "routines": [ + { + "id": "special.ErfApprox", + "module": "special", + "name": "ErfApprox", + "dir": "modules/special/erf-approx", + "summary": "The error function by Abramowitz and Stegun's formula 7.1.26, within 1.5e-7 of the exact value everywhere.", + "tags": [ + "special functions", + "approximation", + "statistics" + ], + "sources": [ + { + "title": "Abramowitz and Stegun, Handbook of Mathematical Functions, formula 7.1.26" + } + ], + "source": "// ErfApprox: the error function by Abramowitz and Stegun's formula 7.1.26,\n// with an absolute error below 1.5e-7 for every X. It is an approximation\n// with a stated bound, not the correctly rounded erf: the libm reference\n// holds it to that bound. ERF(X) for X < 0 is -ERF(-X), so the sign is set\n// aside first.\nFUNCTION ErfApprox(X : FLOAT) RETURNS FLOAT\n DECLARE Sign : FLOAT <- 1.0\n IF X < 0.0 THEN\n Sign <- -1.0\n ENDIF\n DECLARE A : FLOAT <- ABS(X)\n DECLARE T : FLOAT <- 1.0 / (1.0 + 0.3275911 * A)\n DECLARE Poly : FLOAT <- ((((1.061405429 * T - 1.453152027) * T + 1.421413741) * T - 0.284496736) * T + 0.254829592) * T\n RETURN Sign * (1.0 - Poly * EXP(-A * A))\nENDFUNCTION\n", + "cases": [ + { + "call": "ErfApprox(0.0)", + "result": "9.999999717180685e-10" + }, + { + "call": "ErfApprox(0.5)", + "result": "0.5205000163047472" + }, + { + "call": "ErfApprox(-1.0)", + "result": "-0.8427006897475899" + }, + { + "call": "ErfApprox(2.0)", + "result": "0.9953221395812188" + }, + { + "call": "ErfApprox(3.5)", + "result": "0.999999255782864" + } + ], + "references": [ + { + "lang": "python", + "level": "plain", + "file": "ref/python/plain.py", + "note": "The same formula.", + "source": "import math\n\n\ndef erf_approx(x):\n sign = -1.0 if x < 0.0 else 1.0\n a = abs(x)\n t = 1.0 / (1.0 + 0.3275911 * a)\n poly = ((((1.061405429 * t - 1.453152027) * t + 1.421413741) * t - 0.284496736) * t + 0.254829592) * t\n return sign * (1.0 - poly * math.exp(-a * a))\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 5 case(s) (exactly)" + } + } + }, + { + "lang": "python", + "level": "libm", + "file": "ref/python/libm.py", + "note": "math.erf, the C library's correctly rounded erf: the approximation must stay within its stated 1.5e-7 of it.", + "abs": 1.5e-7, + "source": "import math\n\n\ndef erf_approx(x):\n return math.erf(x)\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 5 case(s) (within rel 0, abs 1.5e-7)" + } + } + }, + { + "lang": "mojo", + "level": "plain", + "file": "ref/mojo/plain.mojo", + "note": "The same formula in Mojo.", + "source": "from std.math import exp\n\n\ndef erf_approx(x: Float64) -> Float64:\n var sign: Float64 = 1.0\n if x < 0.0:\n sign = -1.0\n var a = abs(x)\n var t = 1.0 / (1.0 + 0.3275911 * a)\n var poly = ((((1.061405429 * t - 1.453152027) * t + 1.421413741) * t - 0.284496736) * t + 0.254829592) * t\n return sign * (1.0 - poly * exp(-a * a))\n", + "checks": { + "interpreter": { + "status": "skipped", + "detail": "core's Mojo interpreter declines exp(...) as written here" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION ErfApprox" + }, + "pseudo": { + "status": "pass", + "detail": "5 case(s) run" + }, + "prover": { + "status": "open", + "detail": "0 of 1 obligation(s) proved; open: divide@12 (1.0 + 0.3275911 * A is not 0)" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 269 generated input(s)" + }, + "mojo": { + "status": "skipped", + "detail": "core's Mojo interpreter declines exp(...) as written here; the compiler's answer is needed" + } + } + } + ] + }, + { + "name": "stats", + "title": "Statistics", + "summary": "Summaries of a list of measurements: where it sits and how far it spreads.", + "routines": [ + { + "id": "stats.Mean", + "module": "stats", + "name": "Mean", + "dir": "modules/stats/mean", + "summary": "The arithmetic mean of a list of numbers.", + "tags": [ + "statistics", + "summation" + ], + "sources": [ + { + "title": "Any statistics text: the sample mean, the sum divided by the count" + } + ], + "source": "// Mean: the arithmetic mean of a list of numbers.\n// The running total is a FLOAT, rounded at every addition, so the mean of\n// [0.1, 0.1, 0.1] comes out a little above 0.1. For long lists of values of\n// very different sizes, sum with numerics.KahanSum instead.\nFUNCTION Mean(X : LIST OF FLOAT) RETURNS FLOAT\n REQUIRE LENGTH(X) > 0\n DECLARE Total : FLOAT <- 0.0\n FOR I <- 0 TO LENGTH(X)\n Total <- Total + X[I]\n NEXT I\n RETURN Total / LENGTH(X)\nENDFUNCTION\n", + "cases": [ + { + "call": "Mean([1.0, 2.0, 3.0, 4.0])", + "result": "2.5" + }, + { + "call": "Mean([0.1, 0.1, 0.1])", + "result": "0.10000000000000002" + }, + { + "call": "Mean([-5.0, 5.0])", + "result": "0.0" + }, + { + "call": "Mean([1.0e300, 1.0e300])", + "result": "1.0e300" + }, + { + "call": "Mean([2.5])", + "result": "2.5" + } + ], + "references": [ + { + "lang": "python", + "level": "plain", + "file": "ref/python/plain.py", + "note": "The same loop: one running total, added to in order.", + "source": "def mean(x):\n total = 0.0\n for v in x:\n total += v\n return total / len(x)\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 5 case(s) (exactly)" + } + } + }, + { + "lang": "python", + "level": "fsum", + "file": "ref/python/fsum.py", + "note": "math.fsum rounds the sum once, exactly; the plain loop rounds at every step, so the two can differ in the last digit.", + "rel": 1e-15, + "source": "import math\n\n\ndef mean(x):\n return math.fsum(x) / len(x)\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 5 case(s) (within rel 1e-15, abs 0)" + } + } + }, + { + "lang": "c", + "level": "plain", + "file": "ref/c/plain.c", + "note": "The same loop in C. Without -ffast-math the compiler keeps the additions in order at every optimization level.", + "source": "double mean(const double *x, long n) {\n double total = 0.0;\n for (long i = 0; i < n; i++) total += x[i];\n return total / (double)n;\n}\n", + "checks": { + "cc -O0": { + "status": "pass", + "detail": "agrees with the pseudo on 5 case(s) (exactly)" + }, + "cc -O2": { + "status": "pass", + "detail": "agrees with the pseudo on 5 case(s) (exactly)" + } + } + }, + { + "lang": "mojo", + "level": "plain", + "file": "ref/mojo/plain.mojo", + "note": "The same loop in Mojo.", + "source": "def mean(x: List[Float64]) -> Float64:\n var total: Float64 = 0.0\n for i in range(len(x)):\n total = total + x[i]\n return total / Float64(len(x))\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 5 case(s) in core's interpreter (exactly)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + }, + { + "lang": "mojo", + "level": "unrolled", + "file": "ref/mojo/unrolled.mojo", + "note": "Four running totals, as a vectorizing compiler keeps them: faster on long lists, and the additions happen in a different order, so the last digit can differ.", + "rel": 1e-15, + "source": "def mean(x: List[Float64]) -> Float64:\n var s0: Float64 = 0.0\n var s1: Float64 = 0.0\n var s2: Float64 = 0.0\n var s3: Float64 = 0.0\n var n = len(x)\n var i = 0\n while i + 4 <= n:\n s0 = s0 + x[i]\n s1 = s1 + x[i + 1]\n s2 = s2 + x[i + 2]\n s3 = s3 + x[i + 3]\n i = i + 4\n while i < n:\n s0 = s0 + x[i]\n i = i + 1\n return ((s0 + s1) + (s2 + s3)) / Float64(n)\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 5 case(s) in core's interpreter (within rel 1e-15, abs 0)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "proof": { + "lang": "dafny", + "file": "proof/mean.dfy", + "note": "Over real numbers: the loop computes Sum(X) / |X|, and the mean lies between the smallest and largest value (rounding can push the FLOAT result just outside, as Mean([0.1, 0.1, 0.1]) shows).", + "source": "// Mean, over real numbers. The FLOAT version rounds; this one does not.\nfunction Sum(x: seq): real\n{\n if |x| == 0 then 0.0 else Sum(x[..|x| - 1]) + x[|x| - 1]\n}\n\nmethod Mean(x: seq) returns (m: real)\n requires |x| > 0\n ensures m == Sum(x) / (|x| as real)\n{\n var total := 0.0;\n var i := 0;\n while i < |x|\n invariant 0 <= i <= |x|\n invariant total == Sum(x[..i])\n {\n assert x[..i + 1][..i] == x[..i];\n total := total + x[i];\n i := i + 1;\n }\n assert x[..|x|] == x;\n m := total / (|x| as real);\n}\n\n// Every value at most hi: the sum is at most |x| * hi.\nlemma SumAtMost(x: seq, hi: real)\n requires forall i :: 0 <= i < |x| ==> x[i] <= hi\n ensures Sum(x) <= (|x| as real) * hi\n{\n if |x| > 0 { SumAtMost(x[..|x| - 1], hi); }\n}\n\n// Every value at least lo: the sum is at least |x| * lo.\nlemma SumAtLeast(x: seq, lo: real)\n requires forall i :: 0 <= i < |x| ==> lo <= x[i]\n ensures (|x| as real) * lo <= Sum(x)\n{\n if |x| > 0 { SumAtLeast(x[..|x| - 1], lo); }\n}\n\n// In exact arithmetic the mean lies between any lower and upper bound of the values.\nlemma MeanBetween(x: seq, lo: real, hi: real)\n requires |x| > 0\n requires forall i :: 0 <= i < |x| ==> lo <= x[i] <= hi\n ensures lo <= Sum(x) / (|x| as real) <= hi\n{\n SumAtMost(x, hi);\n SumAtLeast(x, lo);\n}\n", + "check": { + "status": "pass", + "detail": "Dafny 4.11.0: 9 verified, 0 errors" + } + }, + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION Mean" + }, + "pseudo": { + "status": "pass", + "detail": "5 case(s) run" + }, + "prover": { + "status": "pass", + "detail": "all 2 obligation(s) proved" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 262 generated input(s)" + }, + "mojo": { + "status": "pass", + "detail": "the generated Mojo prints what the pseudo prints on every case, in core's interpreter" + } + } + }, + { + "id": "stats.Variance", + "module": "stats", + "name": "Variance", + "dir": "modules/stats/variance", + "summary": "The sample variance of a list of numbers (dividing by N - 1), computed in two passes.", + "tags": [ + "statistics", + "cancellation" + ], + "sources": [ + { + "title": "Chan, Golub and LeVeque, Algorithms for computing the sample variance (1983)", + "url": "https://doi.org/10.1080/00031305.1983.10483115" + } + ], + "source": "// Variance: the sample variance (dividing by N - 1), in two passes: the mean\n// first, then the squared distances from it. The one-pass formula\n// (SUM X^2 - N * MEAN^2) / (N - 1) subtracts two nearly equal large numbers\n// and loses every digit when the values sit far from 0, as the third case shows.\nUSE stats.Mean\nFUNCTION Variance(X : LIST OF FLOAT) RETURNS FLOAT\n REQUIRE LENGTH(X) >= 2\n DECLARE M : FLOAT <- Mean(X)\n DECLARE Total : FLOAT <- 0.0\n FOR I <- 0 TO LENGTH(X)\n Total <- Total + (X[I] - M) * (X[I] - M)\n NEXT I\n RETURN Total / (LENGTH(X) - 1)\nENDFUNCTION\n", + "cases": [ + { + "call": "Variance([2.0, 4.0, 4.0, 4.0, 5.0, 5.0, 7.0, 9.0])", + "result": "4.571428571428571" + }, + { + "call": "Variance([1.0, 2.0])", + "result": "0.5" + }, + { + "call": "Variance([1.0e9 + 4.0, 1.0e9 + 7.0, 1.0e9 + 13.0, 1.0e9 + 16.0])", + "result": "30.0" + } + ], + "references": [ + { + "lang": "python", + "level": "plain", + "file": "ref/python/plain.py", + "note": "The same two passes.", + "source": "def variance(x):\n m = 0.0\n for v in x:\n m += v\n m /= len(x)\n total = 0.0\n for v in x:\n total += (v - m) * (v - m)\n return total / (len(x) - 1)\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) (exactly)" + } + } + }, + { + "lang": "python", + "level": "statistics", + "file": "ref/python/statistics.py", + "note": "The standard library's statistics.variance, which works with exact fractions inside: a different method, held to agree to 12 digits.", + "rel": 1e-12, + "source": "import statistics\n\n\ndef variance(x):\n return statistics.variance(x)\n", + "checks": { + "cpython": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) (within rel 1e-12, abs 0)" + } + } + }, + { + "lang": "mojo", + "level": "plain", + "file": "ref/mojo/plain.mojo", + "note": "The same two passes in Mojo.", + "source": "def variance(x: List[Float64]) -> Float64:\n var m: Float64 = 0.0\n for i in range(len(x)):\n m = m + x[i]\n m = m / Float64(len(x))\n var total: Float64 = 0.0\n for i in range(len(x)):\n total = total + (x[i] - m) * (x[i] - m)\n return total / Float64(len(x) - 1)\n", + "checks": { + "interpreter": { + "status": "pass", + "detail": "agrees with the pseudo on 3 case(s) in core's interpreter (exactly)" + }, + "godbolt": { + "status": "unverified", + "detail": "no stored answer from mojo_1_1_0 for this program: pixi run library-verify-mojo" + } + } + } + ], + "checks": { + "structure": { + "status": "pass", + "detail": "defines FUNCTION Variance, using stats.Mean" + }, + "pseudo": { + "status": "pass", + "detail": "3 case(s) run" + }, + "prover": { + "status": "pass", + "detail": "all 4 obligation(s) proved" + }, + "fuzz": { + "status": "pass", + "detail": "no failure in 221 generated input(s)" + }, + "mojo": { + "status": "pass", + "detail": "the generated Mojo prints what the pseudo prints on every case, in core's interpreter" + } + } + } + ] + } +]; diff --git a/src/library/registry.ts b/src/library/registry.ts new file mode 100644 index 0000000..b5f8c1a --- /dev/null +++ b/src/library/registry.ts @@ -0,0 +1,40 @@ +/** + * The library as core sees it: modules of verified routines that a program brings in with USE. + * + * The data comes from the generated module (scripts/library.mjs emit, from the library/ submodule), so the + * site needs no files at run time. The library's own tools read the routines from disk instead and install + * them here with setLibrary() before checking them. + */ +import { LIBRARY_MODULES } from './generated.js'; +import type { LibraryModule, LibraryRoutine } from './types.js'; + +export type { LibraryModule, LibraryRoutine } from './types.js'; + +let modules: LibraryModule[] = LIBRARY_MODULES; +let byModule = index(modules); + +function index(mods: LibraryModule[]): Map { + return new Map(mods.map((m) => [m.name.toUpperCase(), m])); +} + +/** Replace the library (the library's own tools, and tests). Returns the one it replaced. */ +export function setLibrary(mods: LibraryModule[]): LibraryModule[] { + const old = modules; + modules = mods; + byModule = index(mods); + generation++; + return old; +} + +/** Bumped by setLibrary, so a cache of studied routines knows to start again. */ +export let generation = 0; + +export function libraryModules(): LibraryModule[] { return modules; } + +export function libraryModule(name: string): LibraryModule | undefined { return byModule.get(String(name).toUpperCase()); } + +/** A routine by its id (stats.Mean), or by module and name. Names ignore case, as in pseudo. */ +export function libraryRoutine(module: string, name?: string): LibraryRoutine | undefined { + if (name === undefined) { const i = module.indexOf('.'); if (i < 0) return undefined; name = module.slice(i + 1); module = module.slice(0, i); } + return libraryModule(module)?.routines.find((r) => r.name.toUpperCase() === String(name).toUpperCase()); +} diff --git a/src/library/types.ts b/src/library/types.ts new file mode 100644 index 0000000..b858fc1 --- /dev/null +++ b/src/library/types.ts @@ -0,0 +1,70 @@ +/** + * The shapes of the library (pplus-library, the submodule library/): modules of verified pseudo routines, each + * with its cases, its reference implementations in other languages, an optional proof, and the status of every + * check, as `pixi run library-check` last recorded it. + */ + +/** One check of one routine: what it found, and when the stored answer was made. */ +export interface LibraryCheck { + /** + * 'pass'; 'fail'; 'open' (the prover could not finish every obligation: nothing is wrong, nothing is proved); + * 'unverified' (no stored answer for this exact text); 'skipped' (the tool is not available, or declines). + */ + status: 'pass' | 'fail' | 'open' | 'unverified' | 'skipped'; + /** One line: what was checked and what it found. */ + detail: string; +} + +export interface LibraryReference { + /** 'python', 'mojo', 'c', ... */ + lang: string; + /** 'plain', 'unrolled', 'fsum', ...: one implementation of the routine, at one level of care or optimization. */ + level: string; + /** The file, relative to the routine's folder. */ + file: string; + /** What this level does differently, in a sentence, and why it needs a tolerance if it has one. */ + note: string; + /** The tolerance this level is held to against the pseudo, relative and absolute; exact when absent. */ + rel?: number; + abs?: number; + source: string; + /** Per way of running it: 'interpreter' (core's Mojo interpreter), 'godbolt', 'cpython', 'cc -O0', 'cc -O2'. */ + checks: Record; +} + +export interface LibraryCase { + /** A call in pseudo, such as Mean([1.0, 2.0, 3.0]). */ + call: string; + /** What the pseudo returns, written as pseudo writes values; filled in by library-check from a run. */ + result?: string; + /** The tolerance a reference implementation is held to, relative and absolute; 0 for exact. */ + rel?: number; + abs?: number; +} + +export interface LibraryRoutine { + /** module.Name, as USE writes it: stats.Mean. */ + id: string; + module: string; + name: string; + /** The routine's folder in pplus-library, such as modules/stats/mean. */ + dir: string; + summary: string; + tags: string[]; + /** Where the method comes from: a paper, a textbook section, a manual page. */ + sources: Array<{ title: string; url?: string }>; + /** The routine file, routine.pseudo: one FUNCTION or PROCEDURE with its contracts, and USE lines for what it calls. */ + source: string; + cases: LibraryCase[]; + references: LibraryReference[]; + proof?: { lang: string; file: string; note: string; source: string; check: LibraryCheck }; + /** pseudo (cases run), prover, fuzz, mojo (the generated Mojo), each a LibraryCheck. */ + checks: Record; +} + +export interface LibraryModule { + name: string; + title: string; + summary: string; + routines: LibraryRoutine[]; +} diff --git a/src/services/pseudo-study.ts b/src/services/pseudo-study.ts index 9f58d50..d8bb88c 100644 --- a/src/services/pseudo-study.ts +++ b/src/services/pseudo-study.ts @@ -22,6 +22,8 @@ import { parse, parseExpression } from '../engines/pseudo/parse.js'; import { check } from '../engines/pseudo/check.js'; import { analyze } from '../engines/pseudo/analyze.js'; import { coach } from '../engines/pseudo/coach.js'; +import { libraryModule, libraryModules, generation as libraryGeneration } from '../library/registry.js'; +import type { LibraryRoutine } from '../library/registry.js'; const RANK: Record = { error: 0, warning: 1, note: 2 }; @@ -118,7 +120,66 @@ const diag = (severity: string, code: string, line: number, col: number, message * `source` is the source as written; `parsed` is the engine's parse of the blanked source, with the assignments * put in. */ -export function studyPseudo(source: string, options: { coach?: boolean; strict?: boolean } = {}): any { +/** Studied library routines, by generation, id and source, so a routine is checked once however many programs use it. */ +const routineCache = new Map(); + +/** A library routine, studied as a program of its own (its own USE lines resolved the same way). */ +function studyRoutine(r: LibraryRoutine, stack: string[]): any { + const key = `${libraryGeneration}\u0000${r.id}\u0000${r.source}`; + let st = routineCache.get(key); + if (!st) { + st = studyPseudo(r.source, { coach: false, libraryStack: [...stack, r.id] }); + routineCache.set(key, st); + } + return st; +} + +/** + * The routines a program's USE lines bring in: UPPER name -> the checked routine (its own program's FUNCTION or + * PROCEDURE, marked with `lib`), where each came from, and what could not be found. + */ +export function resolveUses(body: any[], stack: string[] = []): { libs: Map; origin: Map; diags: any[] } { + const libs = new Map(); + const origin = new Map(); + const diags: any[] = []; + for (const u of body) { + if (u?.kind !== 'Use' || u.ieee) continue; + const m = libraryModule(u.module); + if (!m) { + const names = libraryModules().map((x) => x.name); + diags.push(diag('error', 'unknown-library', u.line, u.moduleCol ?? u.col, `No module of the library is called ${u.module}.${names.length ? ` The modules are ${names.join(', ')}.` : ' The library has no modules in this build.'}`, { guide: 'libraries' })); + continue; + } + let routines = m.routines; + if (u.routine) { + const r = m.routines.find((x) => x.name.toUpperCase() === String(u.routine).toUpperCase()); + if (!r) { diags.push(diag('error', 'unknown-routine', u.line, u.routineCol ?? u.col, `The module ${m.name} has no routine called ${u.routine}. Its routines are ${m.routines.map((x) => x.name).join(', ')}.`, { guide: 'libraries' })); continue; } + routines = [r]; + } + for (const r of routines) { + if (stack.includes(r.id)) { diags.push(diag('error', 'library-cycle', u.line, u.col, `${r.id} is already being brought in by ${stack[stack.length - 1]}, so the routines would use each other in a circle.`, { guide: 'libraries' })); continue; } + const st = studyRoutine(r, stack); + const sub = st.ok ? st.program.subs.get(r.name.toUpperCase()) : null; + if (!sub) { + const why = st.errors?.[0] ? `line ${st.errors[0].line}: ${st.errors[0].message}` : `it defines no routine called ${r.name}`; + diags.push(diag('error', 'library-broken', u.line, u.col, `The library routine ${r.id} does not check (${why}). That is a fault in the library, not in this program.`, { guide: 'libraries' })); + continue; + } + sub.lib = { module: m.name, id: r.id, program: st.program, source: r.source }; + const k = r.name.toUpperCase(); + const prior = origin.get(k); + if (prior && prior.module.toUpperCase() !== m.name.toUpperCase()) { + diags.push(diag('error', 'library-clash', u.line, u.col, `${r.name} comes from both ${prior.module} (line ${prior.line}) and ${m.name}. Bring in only the one you mean: USE ${m.name}..`, { guide: 'libraries' })); + continue; + } + libs.set(k, sub); + origin.set(k, { module: m.name, line: u.line }); + } + } + return { libs, origin, diags }; +} + +export function studyPseudo(source: string, options: { coach?: boolean; strict?: boolean; libraryStack?: string[] } = {}): any { const original = String(source ?? ''); const { source: blanked, inits } = splitDeclareInits(original); const parsed: any = parse(blanked); @@ -149,8 +210,12 @@ export function studyPseudo(source: string, options: { coach?: boolean; strict?: } if (extra.length) parsed.diags = [...parsed.diags, ...extra].sort((a: any, b: any) => a.line - b.line || a.col - b.col); - // from here on, exactly what study() does (src/engines/pseudo/study.js) - const { program, diags } = check(parsed); + // the routines USE brings in, checked in their own files first + const uses = resolveUses(parsed.ast.body, options.libraryStack || []); + if (uses.diags.length) parsed.diags = [...parsed.diags, ...uses.diags].sort((a: any, b: any) => a.line - b.line || a.col - b.col); + + // from here on, what study() does (src/engines/pseudo/study.js), with the library's routines in scope + const { program, diags } = check(parsed, { libs: uses.libs, libOrigin: uses.origin }); const errors = diags.filter((d: any) => d.severity === 'error'); let analysis = null; let coached: any[] = []; diff --git a/src/services/pseudo.ts b/src/services/pseudo.ts index 3231725..fe2c8df 100644 --- a/src/services/pseudo.ts +++ b/src/services/pseudo.ts @@ -47,7 +47,7 @@ export function studyOf(source: string): Parsed { function resolveCall(program: any, call: string) { const p = parseExpression(call); if (p.diags.some((d: any) => d.severity === 'error') || p.expr.kind !== 'CallExpr') throw new Error(`"${call}" is not a call. Write the subroutine's name and its arguments, as in COUNT_BASE('A', "GATTACA").`); - const sub = program.subs.get(p.expr.name.toUpperCase()); + const sub = program.subs.get(p.expr.name.toUpperCase()) || program.libs?.get(p.expr.name.toUpperCase()); if (!sub) throw new Error(`The program has no FUNCTION or PROCEDURE called ${p.expr.name}.`); if (p.expr.args.length !== sub.params.length) throw new Error(`${sub.name} takes ${sub.params.length} value(s), and the call gives ${p.expr.args.length}.`); const args = p.expr.args.map((a: any, i: number) => { diff --git a/src/sync/pseudo-to-mojo.ts b/src/sync/pseudo-to-mojo.ts index fb1d5d8..85a63d5 100644 --- a/src/sync/pseudo-to-mojo.ts +++ b/src/sync/pseudo-to-mojo.ts @@ -39,6 +39,10 @@ export { GENERATED_HEADER }; export interface MojoOptions { /** The call to run, such as COUNT_BASE('A', "GATTACA"); becomes the body of `main` when the pseudo has no lines of its own. */ call?: string | null; + /** Internal: write the definitions only, no imports and no main (a library routine). */ + defsOnly?: boolean; + /** Internal: the library routines' Mojo, written before the program's own definitions. */ + libraryBlocks?: Array<{ id: string; lines: string[]; imports: string[] }>; } export interface MojoResult { source: string; map: LineMap; notes: Diagnostic[] } @@ -183,7 +187,7 @@ class Gen { constructor(private program: any, private source: string, private raising: Set, private opts: MojoOptions) { for (const c of program.comments || []) this.commentsByLine.set(c.line, c); this.srcLines = source.split('\n'); - for (const sub of program.subs.values()) { + for (const sub of [...program.subs.values(), ...(program.libs?.values() ?? [])]) { const changed = this.changedIn(sub.node.body); const assigned = this.assignedIn(sub.node.body); this.varParams.set(key(sub.name), sub.params.map((p: any) => p.mode !== 'BYREF' && ((changed.has(up(p.name)) && isCollection(p.type)) || assigned.has(up(p.name))))); @@ -344,7 +348,15 @@ class Gen { this.emit(0, '', null); this.emit(0, '', null); } + for (const b of this.opts.libraryBlocks || []) { + this.emit(0, `# From the Programming+ library: ${b.id} (verified in pplus-library; generated from its pseudo)`, null); + for (const l of b.lines) this.emit(0, l, null); + for (const n of b.imports) this.imports.add(n); + this.emit(0, '', null); + this.emit(0, '', null); + } for (const sub of p.subs.values()) { this.subroutine(sub); this.emit(0, '', null); this.emit(0, '', null); } + if (this.opts.defsOnly) return this.assemble(); this.mainFunction(); this.leadingComments(Infinity, 0); return this.assemble(); @@ -997,10 +1009,24 @@ export function pseudoToMojo(pseudo: string, opts: MojoOptions = {}): MojoResult return { unsupported: errors.length ? errors : [{ lang: 'pseudo', severity: 'error', id: 'translate-no-program', line: 1, message: 'The pseudo does not read yet, so there is nothing to translate.' }] }; } const program = st.program; + // the library routines the program uses, each once, the ones they use first + const libs = libraryOrder(program); + const libRaising = new Set(); + const libraryBlocks: Array<{ id: string; lines: string[]; imports: string[] }> = []; + for (const lib of libs) { + const raising = inferRaising(lib.program, libRaising); + const gen = new Gen(lib.program, lib.source, raising, { defsOnly: true }); + gen.run(); + for (const sub of lib.program.subs.values()) if (raising.has(up(sub.name))) libRaising.add(up(sub.name)); + const lines = gen.out.map((l) => l.text); + while (lines.length && !lines[lines.length - 1].trim()) lines.pop(); + libraryBlocks.push({ id: lib.id, lines, imports: [...gen.imports] }); + } + opts = { ...opts, libraryBlocks }; const callText = (opts.call || '').trim(); const callName = callText ? /^\s*([A-Za-z_][A-Za-z0-9_]*)/.exec(callText)?.[1] : null; // Inference, then translation; a line that could not be translated becomes a raise, so its routine raises too, and the pass is run again. - const extra = new Set(); + const extra = new Set(libRaising); for (let pass = 0; ; pass++) { const raising = inferRaising(program, extra); if (bodyRaises(program.main.body, raising)) raising.add('MAIN'); @@ -1014,6 +1040,34 @@ export function pseudoToMojo(pseudo: string, opts: MojoOptions = {}): MojoResult } } +/** The names of every routine a program calls, anywhere in it. */ +function calledNames(program: any): Set { + const out = new Set(); + const seen = new Set(); + const visit = (x: any): void => { + if (!x || typeof x !== 'object' || seen.has(x)) return; + seen.add(x); + if (Array.isArray(x)) { for (const y of x) visit(y); return; } + if ((x.kind === 'CallExpr' || x.kind === 'Call') && x.name) out.add(up(x.name)); + for (const [k, v] of Object.entries(x)) if (k !== 'sub' && k !== 'sym' && k !== 'type' && k !== 'resolved' && v && typeof v === 'object') visit(v); + }; + visit(program.main?.body); + for (const s of program.subs.values()) { visit(s.node.body); visit(s.requires); visit(s.ensures); } + return out; +} + +/** Every library routine a program calls, directly or through another routine, dependencies first, each once. */ +function libraryOrder(program: any, out: Map = new Map()): any[] { + const called = calledNames(program); + for (const sub of program.libs?.values() ?? []) { + if (!called.has(up(sub.name))) continue; + if (out.has(sub.lib.id)) continue; + libraryOrder(sub.lib.program, out); + out.set(sub.lib.id, sub.lib); + } + return [...out.values()]; +} + /** The set of names a generated source may use from the standard library, for the grounding test. */ export function stdlibNamesUsed(): string[] { return Object.keys(USED_STDLIB); } export const STD_INDEX = MOJO_STD_EXPORTS; diff --git a/tests/corpus/53-library.pseudo b/tests/corpus/53-library.pseudo new file mode 100644 index 0000000..b521118 --- /dev/null +++ b/tests/corpus/53-library.pseudo @@ -0,0 +1,12 @@ +// Routines from the library, called like the program's own: a run steps over each one, and the +// prover uses each one's REQUIRE and ENSURE at the call. +// EXPECT: 5.0 4.571428571428571 +// EXPECT: 0.0 -0.0615234375 +// EXPECT: 0 +USE stats +USE md.LennardJones +USE align.NeedlemanWunschScore +DECLARE Samples : LIST OF FLOAT <- [2.0, 4.0, 4.0, 4.0, 5.0, 5.0, 7.0, 9.0] +OUTPUT Mean(Samples), " ", Variance(Samples) +OUTPUT LennardJones(1.0, 1.0, 1.0), " ", LennardJones(2.0, 1.0, 1.0) +OUTPUT NeedlemanWunschScore("GATTACA", "GCATGCU", 1, -1, -1) diff --git a/tests/library.test.mjs b/tests/library.test.mjs new file mode 100644 index 0000000..23c6af4 --- /dev/null +++ b/tests/library.test.mjs @@ -0,0 +1,85 @@ +// The library (library/, pplus-library): the registry core builds from it is current, every routine checks and +// runs as its record says, and USE behaves as docs/library.md describes: names resolve, runs step over the +// routines, the prover uses their contracts, and the Mojo translator writes each routine once. +import test from 'node:test'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import { spawnSync } from 'node:child_process'; +import { libraryModules, libraryRoutine } from '../dist/library/registry.js'; +import { studyOf, runPseudo, provePseudo } from '../dist/services/pseudo.js'; +import { pseudoToMojo } from '../dist/sync/pseudo-to-mojo.js'; +import { checkMojo } from '../dist/mojo/check.js'; +import { runMojo } from '../dist/mojo/interp.js'; + +test('the registry is generated from the library checkout and is up to date', () => { + assert.ok(fs.existsSync('library/modules'), 'library/ is not checked out: git submodule update --init'); + const r = spawnSync(process.execPath, ['scripts/library.mjs', 'emit', '--check'], { encoding: 'utf8' }); + assert.equal(r.status, 0, r.stderr || r.stdout); +}); + +test('every routine: one routine per file, its cases run, and its record is current and has no failing check', () => { + const mods = libraryModules(); + assert.ok(mods.length >= 6, `only ${mods.length} modules`); + let routines = 0; + for (const m of mods) { + for (const r of m.routines) { + routines++; + const st = studyOf(r.source); + assert.ok(st.ok, `${r.id}: ${st.diagnostics.filter((d) => d.severity === 'error').map((d) => d.message).join('; ')}`); + const subs = [...st.program.program.subs.values()]; + assert.deepEqual(subs.map((s) => s.name), [r.name], `${r.id} defines ${subs.map((s) => s.name)}`); + assert.ok(r.cases.length >= 2, `${r.id} has fewer than two cases`); + for (const c of r.cases) { + const tr = runPseudo(st, { call: c.call, maxSteps: 2000000 }); + assert.equal(tr.error, null, `${r.id}: ${c.call}: ${tr.error?.message}`); + assert.ok(c.result !== undefined, `${r.id}: ${c.call} has no recorded result: run pixi run library-check`); + } + const all = [...Object.entries(r.checks), ...r.references.flatMap((x) => Object.entries(x.checks).map(([k, v]) => [`${x.lang}/${x.level} ${k}`, v])), ...(r.proof ? [['proof', r.proof.check]] : [])]; + for (const [k, c] of all) assert.notEqual(c.status, 'fail', `${r.id} ${k}: ${c.detail}`); + for (const k of ['structure', 'pseudo', 'prover', 'fuzz']) assert.ok(r.checks[k], `${r.id} has no ${k} check recorded: run pixi run library-check`); + } + } + assert.ok(routines >= 16, `only ${routines} routines`); +}); + +test('USE: a module or one routine; unknown names are errors at the USE line', () => { + assert.ok(libraryRoutine('md.LennardJones')); + assert.ok(libraryRoutine('MD', 'lennardjones'), 'names ignore case'); + const ids = (src) => studyOf(src).diagnostics.filter((d) => d.severity === 'error').map((d) => `${d.id}@${d.line}`); + assert.deepEqual(ids('USE nosuchmodule\n'), ['unknown-library@1']); + assert.deepEqual(ids('USE md.NoSuchRoutine\n'), ['unknown-routine@1']); + assert.deepEqual(ids('USE md.MinimumImage\nFUNCTION MinimumImage(X : FLOAT) RETURNS FLOAT\n RETURN X\nENDFUNCTION\n'), ['library-clash@2']); + assert.deepEqual(ids('USE align.MatchScore\nOUTPUT LinearGapPenalty(2, -1)\n'), ['unknown-function@2'], 'USE of one routine brings in only that one'); + assert.deepEqual(ids('IF TRUE THEN\n USE md\nENDIF\n'), ['use-place@2']); +}); + +test('a run steps over a library routine, and a broken REQUIRE is reported at the call', () => { + const st = studyOf('USE md\nOUTPUT MinimumImage(2.3, 1.0)\nOUTPUT MinimumImage(1.0, 0.0)\n'); + const tr = runPseudo(st, {}); + assert.equal(tr.output[0], '0.2999999999999998'); + assert.ok(tr.steps.every((s) => s.line === null || s.line <= 3), 'a step carries a line of the library file'); + assert.ok(tr.steps.some((s) => s.kind === 'call' && /from the library \(md\.MinimumImage\)/.test(s.text))); + assert.equal(tr.error?.kind, 'require'); + assert.equal(tr.error.line, 3); + assert.match(tr.error.message, /In the library routine md\.MinimumImage/); +}); + +test('the prover uses a routine\'s REQUIRE at the call and its ENSURE afterwards, without proving it again', () => { + const r = provePseudo(studyOf('USE seq.HammingDistance\nFUNCTION F(S : STRING) RETURNS INTEGER\n ENSURE RESULT <= LENGTH(S)\n RETURN HammingDistance(S, S)\nENDFUNCTION\n')); + assert.deepEqual(r.units.map((u) => u.name), ['F'], 'library routines are not units of the program'); + const obs = r.units[0].obligations; + assert.equal(obs.find((o) => o.kind === 'require').status, 'proved'); + assert.equal(obs.find((o) => o.kind === 'ensure').status, 'proved', 'the ENSURE of HammingDistance is a fact after the call'); +}); + +test('the Mojo made from a program that uses the library holds each routine once, dependencies first, and agrees', () => { + const src = 'USE align\nOUTPUT NeedlemanWunschScore("GATTACA", "GCATGCU", 1, -1, -1), " ", MatchScore(\'A\', \'A\', 2, -1)\n'; + const mj = pseudoToMojo(src); + const defs = [...mj.source.matchAll(/^def (\w+)/gm)].map((m) => m[1]); + assert.deepEqual(defs, ['match_score', 'linear_gap_penalty', 'needleman_wunsch_score', 'main']); + assert.match(mj.source, /# From the Programming\+ library: align\.MatchScore/); + const ck = checkMojo(mj.source); + assert.deepEqual(ck.diagnostics.filter((d) => d.severity === 'error'), []); + const run = runMojo(ck.module, mj.source, { maxSteps: 4000000 }); + assert.equal(run.stdout.trim(), runPseudo(studyOf(src), {}).output.join('\n')); +});