Skip to content

Commit c18f203

Browse files
committed
Complete the README package table and normalize benchmark notation
- The Packages table omitted `@metta-ts/grapher` (the hero feature) and `@metta-ts/das-gateway`; add both and re-align the table. - Normalize the benchmark speedup notation to the letter `x` throughout. The corpus table used the multiplication-sign glyph while the rest of the file and the release notes already use `x`. - Add `@metta-ts/edsl` to the "other packages" install list, where it was missing next to the niche grapher line. - Label the 1.1.5 comparison as the pre-optimization baseline, since stable is now 1.1.7.
1 parent 47941bc commit c18f203

1 file changed

Lines changed: 26 additions & 23 deletions

File tree

README.md

Lines changed: 26 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Other packages, add as needed:
1919

2020
```bash
2121
npm install @metta-ts/hyperon # a Python-hyperon-style class API
22+
npm install @metta-ts/edsl # a typed TypeScript eDSL for building MeTTa
2223
npm install @metta-ts/node # CLI + file import! + a parallel matcher
2324
npm install @metta-ts/browser # web entry + in-memory virtual file system
2425
npm install @metta-ts/py # optional Python interop: pythonia or Pyodide
@@ -284,16 +285,18 @@ node packages/node/dist/cli.js examples/factorial.metta
284285

285286
## Packages
286287

287-
| Package | What it is |
288-
| --------------------------------------------- | --------------------------------------------------------------------------------------------- |
289-
| [`@metta-ts/core`](packages/core) | The interpreter, parser, type system, and standard library. Zero platform dependencies. |
290-
| [`@metta-ts/hyperon`](packages/hyperon) | A TypeScript class API over the core, modeled on Python's `hyperon`. |
291-
| [`@metta-ts/edsl`](packages/edsl) | An ergonomic, typed eDSL: term builders, special-form combinators, and a tagged template. |
292-
| [`@metta-ts/node`](packages/node) | The `metta-ts` CLI, file `import!`, and a `SharedArrayBuffer` worker-thread parallel matcher. |
293-
| [`@metta-ts/browser`](packages/browser) | Browser entry point with an in-memory virtual file system for `import!`. |
294-
| [`@metta-ts/py`](packages/py) | Optional Python interop: PeTTa's `py-call` and Hyperon's `py-atom`, over pythonia or Pyodide. |
295-
| [`@metta-ts/prolog`](packages/prolog) | Optional Prolog interop: PeTTa-compatible predicate calls over SWI-Prolog or SWI-WASM. |
296-
| [`@metta-ts/das-client`](packages/das-client) | Optional client to SingularityNET's Distributed AtomSpace via a Connect gateway. |
288+
| Package | What it is |
289+
| ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
290+
| [`@metta-ts/core`](packages/core) | The interpreter, parser, type system, and standard library. Zero platform dependencies. |
291+
| [`@metta-ts/hyperon`](packages/hyperon) | A TypeScript class API over the core, modeled on Python's `hyperon`. |
292+
| [`@metta-ts/edsl`](packages/edsl) | An ergonomic, typed eDSL: term builders, special-form combinators, and a tagged template. |
293+
| [`@metta-ts/node`](packages/node) | The `metta-ts` CLI, file `import!`, and a `SharedArrayBuffer` worker-thread parallel matcher. |
294+
| [`@metta-ts/browser`](packages/browser) | Browser entry point with an in-memory virtual file system for `import!`. |
295+
| [`@metta-ts/py`](packages/py) | Optional Python interop: PeTTa's `py-call` and Hyperon's `py-atom`, over pythonia or Pyodide. |
296+
| [`@metta-ts/prolog`](packages/prolog) | Optional Prolog interop: PeTTa-compatible predicate calls over SWI-Prolog or SWI-WASM. |
297+
| [`@metta-ts/grapher`](packages/grapher) | MeTTaGrapher: a visual editor with browser and headless Node reduction-GIF rendering. |
298+
| [`@metta-ts/das-client`](packages/das-client) | Optional client to SingularityNET's Distributed AtomSpace via a Connect gateway. |
299+
| [`@metta-ts/das-gateway`](packages/das-gateway) | Optional transport-agnostic gateway bridging the browser to a Distributed AtomSpace. |
297300

298301
## Performance
299302

@@ -307,17 +310,17 @@ A representative slice (wall-clock, subprocess including startup; `speedup` = Pe
307310

308311
| Program | PeTTa | MeTTa TS | Speedup |
309312
| ------------------ | ------: | -------: | --------: |
310-
| `peano` | 1645 ms | 304 ms | **5.41×** |
311-
| `fib` | 486 ms | 98 ms | **4.99×** |
312-
| `fibadd` | 471 ms | 107 ms | **4.39×** |
313-
| `peanofast` | 571 ms | 134 ms | **4.25×** |
314-
| `tilepuzzle` | 1603 ms | 415 ms | **3.86×** |
315-
| `permutations` | 899 ms | 614 ms | 1.46× |
316-
| `he_minimalmetta` | 1843 ms | 1272 ms | 1.45× |
317-
| `matespacefast` | 4603 ms | 3701 ms | 1.24× |
318-
| `factorial` | 162 ms | 144 ms | 1.12× |
319-
| `hyperpose_primes` | 1165 ms | 1107 ms | 1.05× |
320-
| `nilbc` | 773 ms | 748 ms | 1.03× |
313+
| `peano` | 1645 ms | 304 ms | **5.41x** |
314+
| `fib` | 486 ms | 98 ms | **4.99x** |
315+
| `fibadd` | 471 ms | 107 ms | **4.39x** |
316+
| `peanofast` | 571 ms | 134 ms | **4.25x** |
317+
| `tilepuzzle` | 1603 ms | 415 ms | **3.86x** |
318+
| `permutations` | 899 ms | 614 ms | 1.46x |
319+
| `he_minimalmetta` | 1843 ms | 1272 ms | 1.45x |
320+
| `matespacefast` | 4603 ms | 3701 ms | 1.24x |
321+
| `factorial` | 162 ms | 144 ms | 1.12x |
322+
| `hyperpose_primes` | 1165 ms | 1107 ms | 1.05x |
323+
| `nilbc` | 773 ms | 748 ms | 1.03x |
321324

322325
The full per-program table is in [`RESULTS-corpus.md`](packages/node/bench/RESULTS-corpus.md).
323326

@@ -336,7 +339,7 @@ The MiB columns are the highest sampled process-tree RSS across the 15 runs on L
336339

337340
The benchmark validates both `jarr` proofs and all three `loowoz` proofs in exact order, all 234,256 cross-product results, all 196 distinct Fibonacci answers, the exact `TupleConcat` result, and the embedded matespace assertion. MeTTa TS uses the same default evaluator as the CLI. No benchmark, PeTTa, curry, or tabling mode is selected.
338341

339-
Against the untouched 1.1.5 build on the same machine, alternating exact-output comparisons improved `jarr` by 1.14x cold and 1.12x loaded. `loowoz` improved by 1.18x cold and 1.31x loaded. The `jarr` cold path also improved on Node 20, 22, and 24. Ineligible programs skip the new route and retain the old generated module shape.
342+
Against the pre-optimization 1.1.5 build on the same machine, alternating exact-output comparisons improved `jarr` by 1.14x cold and 1.12x loaded. `loowoz` improved by 1.18x cold and 1.31x loaded. The `jarr` cold path also improved on Node 20, 22, and 24. Ineligible programs skip the new route and retain the old generated module shape.
340343

341344
Automatic tabling does not memoize every recursive function. Admission requires transitive purity and a recursive strongly connected component that branches back into itself at least twice. Linear recursion such as factorial stays on the compiled path. Custom host operations and space, state, file, random, time, import, and output operations are excluded.
342345

@@ -364,7 +367,7 @@ Every one of these is verified against the 270-assertion Hyperon oracle and the
364367

365368
The last holdouts fell in order. `permutations` is a 28-relation conjunctive `(length (collapse (match &self (, …) …)))`: MeTTa TS folds the worst-case-optimal join and counts each solution rather than materialising the ~360k answer atoms, which brings the current corpus run to 614 ms, under PeTTa's 899 ms. `hyperpose_primes` races `(once (hyperpose …))` across Node worker threads. `nilbc` is a dependently-typed backward chainer: compiling its clauses to a collect-all search with the interpreter's own unification brings the current run to 748 ms, under PeTTa's 773 ms. `peano`, the final one, is an impure dedup-build loop: compiling its saturation step (a `case` over the space with add-if-absent branches) to membership probes on the exact-match index brings the current run to 304 ms, under PeTTa's 1645 ms. The remaining parity work (PLN/NARS library ports, PeTTa-only execution-model examples) is tracked in [`packages/node/bench/TODO-parity.md`](packages/node/bench/TODO-parity.md).
366369

367-
`matespace`/`matespace2` are **PeTTa-specific** and excluded from the faithful subset. Their expected counts, 1063919 and 1297533, are produced only by PeTTa's compilation to Prolog: native backtracking over a globally-persistent atomspace, with duplicate adds pruned by failure, which is not minimal-MeTTa semantics. Run through `hyperon-experimental` itself, `(collapse (mate-space-demo K))` is empty, and LeaTTa agrees. PeTTa, real Hyperon, and MeTTa TS each compute a different result for the same program, so no Hyperon-faithful engine reproduces PeTTa's number. The faithful rewrite of the same workload is `matespacefast`, which uses deterministic tuple recursion instead of a `case`-driven non-deterministic build. MeTTa TS runs it 1.24× faster than PeTTa in the latest corpus run, byte-identical.
370+
`matespace`/`matespace2` are **PeTTa-specific** and excluded from the faithful subset. Their expected counts, 1063919 and 1297533, are produced only by PeTTa's compilation to Prolog: native backtracking over a globally-persistent atomspace, with duplicate adds pruned by failure, which is not minimal-MeTTa semantics. Run through `hyperon-experimental` itself, `(collapse (mate-space-demo K))` is empty, and LeaTTa agrees. PeTTa, real Hyperon, and MeTTa TS each compute a different result for the same program, so no Hyperon-faithful engine reproduces PeTTa's number. The faithful rewrite of the same workload is `matespacefast`, which uses deterministic tuple recursion instead of a `case`-driven non-deterministic build. MeTTa TS runs it 1.24x faster than PeTTa in the latest corpus run, byte-identical.
368371

369372
## Provenance
370373

0 commit comments

Comments
 (0)