# sitoolz

### a toolkit for working with a superintelligence

**Lars Rocha's laws, as a library.** Terrain, settlements, weather, indexed randomness, primes and
puzzles from arithmetic, written twice, in Python and in JavaScript, and checked against one
fixture so that every number one twin produces, the other produces. Something for everyone to
use, and something an AI can use well: the docs are written for both readers.

```python
import sitoolz as si
si.rulerland.height_at(2600123, 0)          # the Ruler Hills at column 2,600,123
si.rulerland.cone_column(1791)              # rule 30's edge at generation 1791, as stone and lace
si.rulerland.warp_code("rulerhills", 2600123, -77)
si.verify()                                 # every claim in every engine, checked
```

```js
const si = require("sitoolz");                       // or SIToolz in a page
si.rulerland.heightAt(2600123, 0);                   // the same number
si.rulerland.coneColumn(1791).join("");              // the same bits
```

`START_HERE.md` takes a fresh checkout to a walkable world in twenty minutes; `python3 tools/everything.py` runs every check and prints one table.

## Rebuilt from the twins (2026-10-03)

The drive holding `~/mywork` was lost. Everything that defines the laws survived in the site's deploy (the JavaScript twins, the
fixtures, the cards, the experiments, these docs), and the Python was ported back from them the same day, each engine checked
against its fixture before the next: `python3 tools/everything.py --quick` prints the table (48 engines, 276,692 checks). The
rules of that port, and the JavaScript-to-Python traps it met, are in `PORTING.md`; the knobs each old fixture was written with
are recorded in its test. `tools/audit.py` is the constitution as a linter. What is still missing is listed in `CHANGELOG.md`.

## The constitution

Three rules, and everything in the repository follows from them.

1. **One law, one card.** Every law has a card in `cards/`: the arithmetic in a sentence, the
   signatures in both languages, what it produces, a picture, the fixture that proves the twins
   agree, and the credit. The cards are the documentation, the test list and the gallery at once.
2. **Two twins, one fixture.** Every function exists in `sitoolz/` (Python) and `js/`
   (JavaScript) under the same name. `tests/write_fixture.py` writes `fixtures/` from the Python
   and `tests/twins.test.cjs` checks the JavaScript against it. A law is not in until both pass.
3. **Credit travels with the code.** Every module names its author in its docstring, every card
   carries its provenance, and `CREDITS.md` and `CITATION.cff` say how to cite. Keep those lines
   when you copy anything.

## Engines

| engine | modules | state |
|---|---|---|
| terrain | `rulerland`, `rangeblends`, `prefixlaw`, `edgelaw` | in: 16 landscapes, rivers, the light cone, prizes and warp addresses; the Wander client renders them |
| settlements | `citylaw` | in: sites, census and the biggest of a region without looking; plans, streets, medians, lamps, estates and lifted districts |
| indexed randomness | `indexrng`, `qrand`, `gamerng` | next |
| the annex | every other pytoolz library, as `sitoolz.<name>`, on demand | in (`cards/ANNEX.md`); no twins or cards yet |
| primes | `primebase`, the Pocklington walk | next |
| puzzles, cards, weather | `larsdoku`, `wsrf`, `tri_xor`, `txs` | later |

## Run the checks

```
python3 tests/write_fixture.py         # only when a law changes
python3 tests/write_city_fixture.py
python3 tests/test_sitoolz.py
node tests/twins.test.cjs && node tests/twins-city.test.cjs
```

The showcase next door (`../sitoolz-showcase`) draws every law twice, in both languages, and
checks the pictures agree pixel for pixel: progress you can look at.

## Credits and licence

The ideas are Lars Rocha's: `CREDITS.md`, `CITATION.cff`. The licence is being chosen:
`LICENSING.md` lays out the choice, and until it is made nothing here is licensed for use.

## Wander, rebuilt from the kit

`sitoolz.wander` and `js/wander.js` are Wander's laws without its client: the 82 worlds, their chunks, the people and works
on them, the lanterns and their facts. The guide "How Wander is built" (`../sitoolz-showcase/demo/how-wander-is-built/`)
takes the seven layers one at a time, from one integer to a walkable world, each with the law it stands on and the twenty
lines that make it.

## meshz: level of detail on the ruler

`sitoolz.meshz` and `js/meshz.js` decide which points of the ground a renderer draws, with one number-theory rule: a point's level is
its Gaussian rank, `v2(x² + z²)` (half of it is the ruler's quadtree level, `min(v2 x, v2 z)`), and a point of level `g` is kept within
`K · 2^(g/2)` of the camera. So the mesh thins in rings that double outward, and because the ruler nests the levels (every coarse point
is also a fine one), tiles of any step meet with no crack: no skirts, no seam patching. That is a claim the fixture checks, not a hope:
every shared edge of fifteen blocks of 64 tiles is met by exactly two triangles on both twins, and the two blocks whose `K` is too small
crack, the same on both. In Wander, `terrain=mesh` draws a range with about five and a half times fewer triangles than detail ultra.
What it does not do yet: sheer walls in the middle distance show a comb of teeth, and the error term that fixes them is the next step.
`examples/wander-lite/` draws one world this way in a single page with no build step (serve the repository's parent and open it).

## The GPU

`pip install sitoolz[gpu]` adds `sitoolz.gpu`, Lars's Taichi kernels from RangeBlends3D: the same hash, noise and ridge, every landscape law of `terrain.WORLDS` with the rivers and the finish (`gpu.window`, checked cell for cell against `terrain.window` by `gpu.check_world`), a relief shader for whole regions (the showcase's atlas), flow2z's step bit for bit (`gpu.flow_step`) and the drone's shot as a ray-marching kernel (`gpu.fly`); a region in a fraction of a second where the Python takes minutes. Everything else in the kit runs without it.

## Levelling up: laws that had no home

Section 18 of the roadmap took the rest of the work (the Celestials, the prime and sequence libraries, the notes) and
gave its laws engines and worlds: the Prime Rails (`primerails`), the Fold Marches and the Square Vault (`folds`), the
Vortex Sea and cascade weather (`cascade`, exact integer fluids), the Hamlet place code (`hamlet`), the zones and three
unblackboxing experiments (`zones`, `experiments/`), and saves with prophecy (`saves`). Any engine can add a world to the
terrain table with `terrain.register`, and Wander walks the new ones.