Metadata-Version: 2.4
Name: sitoolz
Version: 0.1.0
Summary: Lars Rocha's number-theory playground, every module in one package: rails, lanes, climbs, folds, rule 30's edge law, the square family, the XOR build system and the XOR difference triangle.
Author: Lars Rocha
License: MIT
Project-URL: Homepage, https://github.com/oppressionslayer/sitoolz
Keywords: primes,xor,number-theory,rule30,sieve,sierpinski
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Provides-Extra: fast
Requires-Dist: gmpy2; extra == "fast"
Requires-Dist: numba; extra == "fast"
Requires-Dist: scipy; extra == "fast"
Provides-Extra: sequence
Requires-Dist: sympy; extra == "sequence"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# sitoolz

**Make a 3,892-digit proven prime in one line. Make a 623-digit twin prime, both sides proven,
in the next. Build a 19,538-digit prime from M127 in nine rolls with the proof carried up. Hold
every prime to 268 million in 15 MB and prove anything to 72 quadrillion from it. Read rule 30's
edge off a table verified to 2⁴⁸.** Lars Rocha's number-theory playground, every module in one
package.

```
pip install sitoolz
```

```python
from sitoolz import twin_forge as tf
tf.proth(12919)                 # a 3,892-digit prime, proven: minutes here, 43 s in Rust with GMP
tf.hunt(2048, want_twins=1)[0]  # a 623-digit twin, both sides proven: under a minute
```

```python
from sitoolz import showcase, primebase as pb, twin_k2n256, numtools as nt, numtoolz as ntz, xortri

showcase.big_prime()                           # the 19,538-digit prime, built not found
pb.prove.build_up(2**31 - 1, 1024)             # roll M31 to 1024 bits, every rung proven, seconds
twin_k2n256.verify()                           # the 82-digit twin, both sides proven: 0.08 s
pb.is_prime(9_999_999_999_999_917)             # True, by elimination against the net
nt.verdict(1717)                               # ('composite', 'fold-wheel k=16: 17x101', 'free')
ntz.buildsystem(ntz.structured_index(128))     # the XOR Cayley table from its own row 0
xortri.square([2, 6, 8, 11, 12, 5, 4])[:, -1]  # [1, 8, 6, 12, 15, 2]
```

The import name and the distribution are both `sitoolz`. The parts with real compute, the
net, the ladder, the forge, the lanes, the edge law and the triangle, are also a Rust crate,
[`rusttoolz`](https://github.com/oppressionslayer/rusttoolz), held to the same numbers: with GMP it
rolls M127 to 4,096 bits in two seconds, proves a 3,892-digit prime in 43, and finds 22 proven
twins of 102 digits in a fifth of one.

## The builds

**[Built, not found](docs/BUILT_NOT_FOUND.md).** Start from a prime you can prove, form
`N = 2·R·q + 1`, and one Pocklington witness proves `N`. Roll nine times from M127 and you hold a
64,903-bit prime whose certificate is the way it came up. The number ships with the package.

**[The twin forge](docs/TWIN_FORGE.md).** `k·2ⁿ ± 1` makes both members of a twin provable,
because `k·2ⁿ` is factored the moment you write it. The forge sieves, screens and proves in
parallel: an 82-digit pair proven both ways, 623-digit and 1,240-digit pairs with the `+1` side
proven, 187 proven Proth primes, and the hunt records to read.

**[The prime net](docs/PRIME_NET.md).** `primebase` keeps every prime to 268,499,993 as half-gaps
and answers from it: the n-th prime, every prime in a window past a trillion, a proof for any
number to 72 quadrillion, its factors, exact counts, and the ladder down to a prime's seed.

**[Rails, lanes, gates and folds](docs/RAILS_AND_LANES.md).** The primes as structure you can
walk. Free lanes settle 88% of every range with no test; the chain-walks and the fold-wheel
factor what slips through; the base-prime bootstrap squares its own reach.

## Make your own

**A twin prime, both sides proven.** `k·2ⁿ ± 1`: the sieve drops most `k`, a Fermat screen drops
most of the rest, Pocklington proves the `+1` side and Lucas the `−1` side. `hunt` runs on every
core and returns every twin its batch found; `want_twins=1` stops after the first batch that has
one.

```python
from sitoolz import twin_forge as tf
found = tf.hunt(320, want_twins=1)     # k·2^320 ± 1: about 100 digits
twin = found[0]
twin["k"], twin["digits"], twin["upper_proven_pocklington"], twin["lower_proven_lucas"]
# (41562, 101, True, True)
```

| `n` | digits | this desktop, Python with gmpy2 | Rust, `--features gmp` |
|---|---|---|---|
| 320 | 101 | 81 twins in 4.5 s | 22 twins in 0.18 s |
| 1024 | 313 | the first in 17 s | the first in 3 s |
| 2048 | 623 | the first in 49 s | the first in 13 s |

`twin_k2n256.verify()` replays the shipped 82-digit pair with its witnesses in a tenth of a second.

**Proven primes by the thousand.** The same twin hunt proves every `+1` prime it meets on the way:
at `n = 320` that is 222 proven primes of about 100 digits in a fifth of a second, over a thousand
proven primes a second, each with its Pocklington certificate. If you want a single proven prime
rather than a twin, `k·2ⁿ + 1` is the cheap road: `N − 1` is factored the moment it is written, so one witness per small prime proves it.
No chain. `proth(12919)` is a 3,892-digit proven prime in under three minutes here, 43 s in Rust
with GMP; both land on `k = 366`, because the search is by `k` in order.

```python
p = tf.proth(12919)        # {"k": 366, "n": 12919, "digits": 3892, "N": ..., "factors": [2, 3, 61]}
```

**A proven prime of any size.** Start from a prime you can prove, M127 by Lucas–Lehmer, and roll:
`N = 2·R·q + 1` with `R` just under `q/2`, so the bits double each rung and one Pocklington witness
proves every rung. The certificate is the chain itself.

```python
from sitoolz.primebase import prove
steps = prove.build_up(2**127 - 1, 4096)   # 18 rungs to 4,096 bits: 43 s here, 2 s in Rust with GMP
prove.verify_certificate(steps)            # True: every rung re-proved from the one below
text = prove.to_json(steps)                # [[seed, null, null], [N, q, a], ...]
prove.verify_certificate(prove.from_json(text))   # the same chain, read back; rusttoolz reads it too
```

`showcase.big_prime()` is where that road ends: 19,538 digits, nine rolls, proven at every rung.

The whole gallery, rule 30's edge law included, is in [docs/README.md](docs/README.md).

## The store

The same `primes.jsonl` rusttoolz writes, read and written from Python: a Mersenne exponent with
its verdict, a rung with its bits, witness and `q`, a Proth or twin from the forge. The 52 known
Mersenne primes go in as facts and `verify_certificate` accepts a seed on any of them without a
Lucas–Lehmer; a ladder resumes from its top stored rung; a chain from Rust or the browser is
checked against the store before it is kept.

```
python -m sitoolz.primebase.store 127 1024      # every known Mersenne to p = 127, each rolled to 1,024 bits,
                                                # the p and every q printed, every rung stored
```

```python
from sitoolz.primebase import store
st = store.Store()                       # primes.jsonl, or RUSTTOOLZ_STORE
store.rollball_mersennes(521, 2048, st)
st.ladder("M127")                        # the chain back; prove.verify_certificate replays it
```

## Credit

The ideas are Lars Rocha's, the XOR triangle's closed form among them, solved years before this
package existed. Claude assisted with packaging and the tests; that does not imply ownership.

## The modules

Every module loads on first use, so `import sitoolz` is cheap. The session aliases carry over:
`from sitoolz import numtools as nt, numtoolz as ntz, numtoolsd as ntd, numtoolsm as ntm`.

| group | modules |
|---|---|
| the builds | `showcase` (the numbers), `twin_k2n256` (the proven twin), `twin_forge`, `primebase` (`prove`, `rollball`, `certify`, `counting`, `query`, `neighborhood`) |
| the main library | `numtools` (163 functions: `creator`, `climb`, `rail_walk`, `verdict`, `dashboard`, `roll_prime`, `fold_wheel`, the frames), `numtoolz` (the build system, `structured_index`, the sieves, the Mersenne facts), `numtoolsd` (XOR and Diophantine), `numtoolsm` (perfect machines) |
| rule 30 | `ntfun`, `ntfunextended`, `ntmc`, `ntcomb`, `ntprobe`, `centerrandom`, `fast30`, `edgelaw`, `edgelaw_deep`, `edgeframe`, `edgeproof`, `edgerandom`, `edgereach`, `oeis_crosscheck` |
| drivers and triangular XOR systems | `tri_xor`, `tri_frame`, `txs`, `driver_lab`, `parity_lab`, `dfkit`, `anchors`, `backwalk` |
| the square family | `ntpar`, `ntpar_joint`, `squarewalk`, `square_frame`, `square_rng`, `square_store`, `squareverse`, `antispoof`, `randbattery`, `roguelike`, `shopworld` |
| primes | `qnr2`, `gap_forge`, `prime_check` |
| the city and the car | `city` (the addressed city: streets, lots, cards), `motion` (the one tick law of speed, and the whole flat-ground step), `contact` (first contact along a segment, exact fractions; two moving cars as one sweep), `district` (district drive: the three composed, with checkpoints, XOR-edge replay and branches), `convoy` (the braking reserve between two cars), `zipper` (two queues through one gate); all held to the files the Spindexin site and the Rust engine share |
| the triangle | `xortri` |
| the sequence project | `sequence`: `regen`, `twotables`, `xorsquares`, `rulefinder`, `frame`, `better` (needs sympy) |

`numpy` and `pandas` are required. `gmpy2`, `numba` and `scipy` are used when present
(`pip install "sitoolz[fast]"`) and never required.

## The city, the car and the wall

`sitoolz.city` is Lars's addressed city: a district number lays its streets and raises 64
buildings from their source primes, every building a packed lot card that opens back to its
address. `sitoolz.motion` is the one tick law the site and the engine drive by: accelerate, drag
the new speed, clamp, with the settling speed `throttle·accel·(1/drag − dt)` and the closed form
for a straight run. `sitoolz.contact` is first contact: where a footprint first enters a solid
along a segment, as an exact fraction. `sitoolz.district` composes the three: a district in
metres, the car's clearance square, the stop with a micrometre of skin, a checkpoint every 32
ticks with the block between kept as one packed word of five-bit lanes holding the XOR triangle's
left edge (any command read in at most five shift/XORs), `seek` back to any tick through the
commands it reads, the sweep tested only against the lots the street layout puts under the car,
and branches that share a prefix. `sitoolz.convoy` is the braking reserve between two cars on
one lane: the closure, the tail, the required and fitted gap, and first contact. `sitoolz.zipper`
admits two queues of packed car cards through one gate with exact exit gaps. All six are the same law in JavaScript
on the site, in Rust in the engine and in `rusttoolz`, and the tests hold them to one set of
reference files: the studio's six portable drives replay at zero difference.

## The build system

`xor_prefix(index)` is the prefix-XOR of an index with a leading zero, the anchor row `a`.
`buildsystem(index)` is the table `T[i, j] = a_i ^ a_j`: symmetric, zero on the diagonal, and
the whole of it rebuilds from its own row 0, so the storage is the index alone, itself a
formula (`structured_index`). `recover_index` reads the index back from the row or the table.

## The XOR difference triangle

Start from a row of integers, XOR each neighbour pair, and repeat down to one number:

```
[2, 6, 8, 11, 12, 5, 4]
   [4, 14, 3, 7, 9, 1]
     [10, 13, 4, 14, 8]
       [7, 9, 10, 6]
        [14, 3, 12]
         [13, 15]
           [2]
```

That is Pascal's triangle with XOR for addition, and since a binomial coefficient is odd
exactly when the lower index is a submask of the upper, row `k` has a closed form:

```
row_k[j] = XOR of arr[j + m]  over every m with  m & k == m
```

which is the gasket, `(a & b) == 0`, read as arithmetic. `xortri.row_at(arr, k)` gives any row
straight from the input in `popcount(k)` shift-XORs, the apex is the XOR of the inputs at the
submask positions of `n − 1`, and either edge rebuilds the whole triangle (`from_left_edge`,
`from_right_edge`). `square` is the session's `holder`, and `right_edge` its last column.

## Check

```
pip install -e ".[test]"
pytest -q tests          # every module imports, the doctests, the proofs replay, the docs stay clean
```

## Changes

**0.1.0** (2026-11-01) — the city, motion and contact laws shared with the engine; first packaging of the session modules, primebase and the sequence
project, with the showcase numbers and the docs gallery.
