integer-atlas-algos 0.1.0__py3-none-any.whl

integer_atlas_algos/__init__.py

@@ -0,0 +1,3 @@
+"""Integer Atlas — stateless property methods and shard executor."""
+
+__version__ = "0.1.0"

integer_atlas_algos/_lib/blake3_py.py

@@ -0,0 +1,172 @@
+"""Pure-Python BLAKE3 (hash mode), following the official reference design.
+
+This is the dependency-free fallback used when the fast `blake3` package is not
+installed, so a shard's blake3 hash is always populated. It is correct but slow;
+the executor prefers the native library when available. Validated against the
+official BLAKE3 test vectors (see tests/test_blake3.py).
+"""
+
+IV = [0x6A09E667, 0xBB67AE85, 0x3C6EF372, 0xA54FF53A,
+      0x510E527F, 0x9B05688C, 0x1F83D9AB, 0x5BE0CD19]
+
+MSG_PERMUTATION = [2, 6, 3, 10, 7, 0, 4, 13, 1, 11, 12, 5, 9, 14, 15, 8]
+
+CHUNK_START = 1 << 0
+CHUNK_END = 1 << 1
+PARENT = 1 << 2
+ROOT = 1 << 3
+
+BLOCK_LEN = 64
+CHUNK_LEN = 1024
+MASK = 0xFFFFFFFF
+
+
+def _rotr(x, n):
+    return ((x >> n) | (x << (32 - n))) & MASK
+
+
+def _g(s, a, b, c, d, mx, my):
+    s[a] = (s[a] + s[b] + mx) & MASK
+    s[d] = _rotr(s[d] ^ s[a], 16)
+    s[c] = (s[c] + s[d]) & MASK
+    s[b] = _rotr(s[b] ^ s[c], 12)
+    s[a] = (s[a] + s[b] + my) & MASK
+    s[d] = _rotr(s[d] ^ s[a], 8)
+    s[c] = (s[c] + s[d]) & MASK
+    s[b] = _rotr(s[b] ^ s[c], 7)
+
+
+def _round(s, m):
+    _g(s, 0, 4, 8, 12, m[0], m[1])
+    _g(s, 1, 5, 9, 13, m[2], m[3])
+    _g(s, 2, 6, 10, 14, m[4], m[5])
+    _g(s, 3, 7, 11, 15, m[6], m[7])
+    _g(s, 0, 5, 10, 15, m[8], m[9])
+    _g(s, 1, 6, 11, 12, m[10], m[11])
+    _g(s, 2, 7, 8, 13, m[12], m[13])
+    _g(s, 3, 4, 9, 14, m[14], m[15])
+
+
+def _compress(cv, block_words, counter, block_len, flags):
+    s = [
+        cv[0], cv[1], cv[2], cv[3], cv[4], cv[5], cv[6], cv[7],
+        IV[0], IV[1], IV[2], IV[3],
+        counter & MASK, (counter >> 32) & MASK, block_len, flags,
+    ]
+    m = list(block_words)
+    for r in range(7):
+        _round(s, m)
+        if r < 6:
+            m = [m[MSG_PERMUTATION[i]] for i in range(16)]
+    for i in range(8):
+        s[i] ^= s[i + 8]
+        s[i + 8] ^= cv[i]
+    return s
+
+
+def _words(block64):
+    return [int.from_bytes(block64[i:i + 4], "little") for i in range(0, 64, 4)]
+
+
+class _Output:
+    __slots__ = ("cv", "block_words", "counter", "block_len", "flags")
+
+    def __init__(self, cv, block_words, counter, block_len, flags):
+        self.cv = cv
+        self.block_words = block_words
+        self.counter = counter
+        self.block_len = block_len
+        self.flags = flags
+
+    def chaining_value(self):
+        return _compress(self.cv, self.block_words, self.counter,
+                         self.block_len, self.flags)[:8]
+
+    def root_bytes(self, length):
+        out = bytearray()
+        counter = 0
+        while length > 0:
+            words = _compress(self.cv, self.block_words, counter,
+                              self.block_len, self.flags | ROOT)
+            block = b"".join(w.to_bytes(4, "little") for w in words)
+            take = min(len(block), length)
+            out += block[:take]
+            length -= take
+            counter += 1
+        return bytes(out)
+
+
+class _ChunkState:
+    def __init__(self, counter):
+        self.cv = list(IV)
+        self.counter = counter
+        self.block = bytearray(BLOCK_LEN)
+        self.block_len = 0
+        self.blocks_compressed = 0
+
+    def length(self):
+        return BLOCK_LEN * self.blocks_compressed + self.block_len
+
+    def _start_flag(self):
+        return CHUNK_START if self.blocks_compressed == 0 else 0
+
+    def update(self, mv):
+        pos, n = 0, len(mv)
+        while pos < n:
+            if self.block_len == BLOCK_LEN:
+                self.cv = _compress(self.cv, _words(self.block), self.counter,
+                                    BLOCK_LEN, self._start_flag())[:8]
+                self.blocks_compressed += 1
+                self.block_len = 0
+            take = min(BLOCK_LEN - self.block_len, n - pos)
+            self.block[self.block_len:self.block_len + take] = mv[pos:pos + take]
+            self.block_len += take
+            pos += take
+
+    def output(self):
+        padded = bytes(self.block[:self.block_len]) + b"\x00" * (BLOCK_LEN - self.block_len)
+        flags = self._start_flag() | CHUNK_END
+        return _Output(self.cv, _words(padded), self.counter, self.block_len, flags)
+
+
+def _parent_output(left_cv, right_cv):
+    return _Output(list(IV), left_cv + right_cv, 0, BLOCK_LEN, PARENT)
+
+
+class Blake3:
+    def __init__(self):
+        self._chunk = _ChunkState(0)
+        self._stack = []
+
+    def _add_chunk_cv(self, new_cv, total_chunks):
+        while total_chunks & 1 == 0:
+            new_cv = _parent_output(self._stack.pop(), new_cv).chaining_value()
+            total_chunks >>= 1
+        self._stack.append(new_cv)
+
+    def update(self, data):
+        mv = memoryview(data)
+        pos, n = 0, len(mv)
+        while pos < n:
+            if self._chunk.length() == CHUNK_LEN:
+                cv = self._chunk.output().chaining_value()
+                total = self._chunk.counter + 1
+                self._add_chunk_cv(cv, total)
+                self._chunk = _ChunkState(total)
+            take = min(CHUNK_LEN - self._chunk.length(), n - pos)
+            self._chunk.update(mv[pos:pos + take])
+            pos += take
+        return self
+
+    def digest(self, length=32):
+        output = self._chunk.output()
+        for cv in reversed(self._stack):
+            output = _parent_output(cv, output.chaining_value())
+        return output.root_bytes(length)
+
+    def hexdigest(self, length=32):
+        return self.digest(length).hex()
+
+
+def blake3_hexdigest(data, length=32):
+    return Blake3().update(data).hexdigest(length)

integer_atlas_algos/_lib/factorization.py

@@ -0,0 +1,87 @@
+"""Factorization backed by a precomputed base-primes table.
+
+To factor any n up to BOUND**2 you only need primes up to BOUND. With
+BOUND = 31623 (>= sqrt(1e9)) this covers the whole 0..1e9 range using ~3401
+primes. The table is a deterministic, regenerable resource cached in
+algos/precomputed/ — not state about any shard or pack. For n beyond BOUND**2
+factorization stays correct by continuing trial division past the table.
+"""
+import os
+
+_PRECOMP_DIR = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "precomputed")
+DEFAULT_BOUND = 31623  # ceil(sqrt(1e9)); factors any n <= 1e9
+
+_primes_cache: dict[int, list[int]] = {}
+
+
+def _sieve(bound: int) -> list[int]:
+    flags = bytearray([1]) * (bound + 1)
+    flags[0] = flags[1] = 0
+    i = 2
+    while i * i <= bound:
+        if flags[i]:
+            flags[i * i::i] = bytearray(len(flags[i * i::i]))
+        i += 1
+    return [i for i in range(2, bound + 1) if flags[i]]
+
+
+def small_primes(bound: int = DEFAULT_BOUND) -> list[int]:
+    """Primes <= bound, cached in memory and persisted under precomputed/."""
+    cached = _primes_cache.get(bound)
+    if cached is not None:
+        return cached
+    path = os.path.join(_PRECOMP_DIR, f"primes_le_{bound}.txt")
+    if os.path.exists(path):
+        with open(path) as f:
+            primes = [int(x) for x in f.read().split()]
+    else:
+        primes = _sieve(bound)
+        try:
+            os.makedirs(_PRECOMP_DIR, exist_ok=True)
+            tmp = path + ".tmp"
+            with open(tmp, "w") as f:
+                f.write("\n".join(map(str, primes)))
+            os.replace(tmp, path)
+        except OSError:
+            pass  # read-only filesystem: fall back to in-memory only
+    _primes_cache[bound] = primes
+    return primes
+
+
+def factorize(m: int) -> dict[int, int]:
+    """prime -> exponent for abs(m); empty dict for 0 and 1."""
+    m = abs(int(m))
+    f: dict[int, int] = {}
+    if m < 2:
+        return f
+    primes = small_primes()
+    broke = False
+    for p in primes:
+        if p * p > m:
+            broke = True
+            break
+        if m % p == 0:
+            c = 0
+            while m % p == 0:
+                m //= p
+                c += 1
+            f[p] = c
+    if m > 1:
+        if broke or m <= primes[-1] * primes[-1]:
+            # remaining cofactor is prime (it has no factor <= sqrt(m))
+            f[m] = f.get(m, 0) + 1
+        else:
+            # n exceeded the table's reach: keep trial-dividing past the bound
+            d = primes[-1] + 2
+            while d * d <= m:
+                if m % d == 0:
+                    c = 0
+                    while m % d == 0:
+                        m //= d
+                        c += 1
+                    f[d] = c
+                d += 2
+            if m > 1:
+                f[m] = f.get(m, 0) + 1
+    return f

integer_atlas_algos/_lib/multiplicative.py

@@ -0,0 +1,9 @@
+"""Shared multiplicative-function helpers derived from a factorization."""
+
+
+def sigma(factorization):
+    """Sum of divisors from prime -> exponent (1 for the empty factorization)."""
+    s = 1
+    for p, e in factorization.items():
+        s *= (p ** (e + 1) - 1) // (p - 1)
+    return s

integer_atlas_algos/context.py

@@ -0,0 +1,28 @@
+"""Per-n memoized context passed to every method.
+
+Shared, expensive intermediates (factorization, etc.) are computed once per n
+and reused across methods that declare them via `requires`. Cheap methods just
+read ctx.n / ctx.abs_n and ignore the rest.
+"""
+from functools import cached_property
+
+from integer_atlas_algos._lib.factorization import factorize
+
+
+class Context:
+    def __init__(self, n: int):
+        self.n = n
+        self.abs_n = abs(n)
+
+    @cached_property
+    def factorization(self) -> dict[int, int]:
+        """prime -> exponent for abs(n); empty for 0 and 1."""
+        return factorize(self.abs_n)
+
+    @cached_property
+    def divisors(self) -> list[int]:
+        """Sorted positive divisors of abs(n) (for abs(n) >= 1)."""
+        divs = [1]
+        for p, e in self.factorization.items():
+            divs = [d * p ** k for d in divs for k in range(e + 1)]
+        return sorted(divs)

integer_atlas_algos/executor/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from integer_atlas_algos.executor.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

integer_atlas_algos/executor/atomicio.py

@@ -0,0 +1,91 @@
+"""Crash-safe file primitives.
+
+Every durable write goes to a temp file in the same directory, is fsync'd, then
+atomically renamed into place (os.replace). The containing directory is fsync'd
+so the rename itself survives a crash. A partial temp file is never visible under
+the real name, so a reader either sees the previous version or the new one.
+"""
+import json
+import os
+import tempfile
+
+
+def _fsync_file(path):
+    fd = os.open(path, os.O_RDONLY)
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def _fsync_dir(d):
+    try:
+        fd = os.open(d, os.O_RDONLY)
+        try:
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+    except OSError:
+        # Some platforms disallow fsync on a directory; the rename is still atomic.
+        pass
+
+
+def _safe_unlink(path):
+    try:
+        os.unlink(path)
+    except FileNotFoundError:
+        pass
+
+
+def atomic_write_bytes(path, data: bytes):
+    d = os.path.dirname(os.path.abspath(path))
+    fd, tmp = tempfile.mkstemp(dir=d, prefix=".tmp-", suffix=".part")
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, path)
+        _fsync_dir(d)
+    except BaseException:
+        _safe_unlink(tmp)
+        raise
+
+
+def atomic_write_text(path, text: str):
+    atomic_write_bytes(path, text.encode("utf-8"))
+
+
+def atomic_write_json(path, obj):
+    atomic_write_text(path, json.dumps(obj, indent=2, sort_keys=True))
+
+
+def atomic_produce(path, writer):
+    """Atomically create `path` via writer(tmp_path), which writes the whole file.
+
+    Used for backends (e.g. Parquet) that write their own file format.
+    """
+    d = os.path.dirname(os.path.abspath(path))
+    fd, tmp = tempfile.mkstemp(dir=d, prefix=".tmp-", suffix=".part")
+    os.close(fd)
+    try:
+        writer(tmp)
+        _fsync_file(tmp)
+        os.replace(tmp, path)
+        _fsync_dir(d)
+    except BaseException:
+        _safe_unlink(tmp)
+        raise
+
+
+def read_json(path):
+    with open(path) as f:
+        return json.load(f)
+
+
+def cleanup_tmp(directory):
+    if not os.path.isdir(directory):
+        return
+    for name in os.listdir(directory):
+        if name.startswith(".tmp-"):
+            _safe_unlink(os.path.join(directory, name))

integer_atlas_algos/executor/backends/__init__.py

@@ -0,0 +1,24 @@
+"""Pluggable shard file backends.
+
+The resume/checkpoint/atomic machinery in compute.py is format-agnostic; a
+backend only knows how to write/read/count one file. `csv` is stdlib and always
+available (handy for dev and tests); `parquet` is the real shard format and
+needs pyarrow.
+"""
+
+
+def get_backend(name):
+    if name == "csv":
+        from . import csv_backend
+        return csv_backend
+    if name == "parquet":
+        try:
+            import pyarrow  # noqa: F401
+        except ImportError as e:
+            raise RuntimeError(
+                "parquet format requires pyarrow (pip install pyarrow). "
+                "For a dependency-free run use --format csv."
+            ) from e
+        from . import parquet_backend
+        return parquet_backend
+    raise ValueError(f"unknown format: {name}")

integer_atlas_algos/executor/backends/csv_backend.py

@@ -0,0 +1,67 @@
+"""Stdlib CSV backend. Deterministic output; types coerced via the schema."""
+import csv
+
+EXT = ".csv"
+COMPRESSION = "none"
+
+
+def _fmt(v, dtype):
+    if dtype == "bool":
+        return "true" if v else "false"
+    return str(v)
+
+
+def _parse(s, dtype):
+    if dtype == "bool":
+        return s == "true"
+    if dtype in ("double", "float64"):
+        return float(s)
+    if dtype == "string":
+        return s
+    return int(s)  # int*, uint*, and bigint (Python ints are unbounded)
+
+
+def write_table(path, schema, rows):
+    names = [n for n, _ in schema]
+    with open(path, "w", newline="") as f:
+        w = csv.writer(f)
+        w.writerow(names)
+        for r in rows:
+            w.writerow([_fmt(r[n], dt) for n, dt in schema])
+
+
+class Writer:
+    """Streaming writer: write parts one at a time without buffering the whole file."""
+
+    def __init__(self, path, schema):
+        self.schema = schema
+        self.f = open(path, "w", newline="")
+        self.w = csv.writer(self.f)
+        self.w.writerow([n for n, _ in schema])
+
+    def write_table(self, rows):
+        for r in rows:
+            self.w.writerow([_fmt(r[n], dt) for n, dt in self.schema])
+
+    def close(self):
+        self.f.close()
+
+
+def open_writer(path, schema):
+    return Writer(path, schema)
+
+
+def read_table(path, schema):
+    dtypes = dict(schema)
+    out = []
+    with open(path, newline="") as f:
+        rd = csv.reader(f)
+        header = next(rd)
+        for row in rd:
+            out.append({n: _parse(v, dtypes.get(n, "int64")) for n, v in zip(header, row)})
+    return out
+
+
+def count_rows(path):
+    with open(path) as f:
+        return max(0, sum(1 for _ in f) - 1)

integer_atlas_algos/executor/backends/parquet_backend.py

@@ -0,0 +1,87 @@
+"""Parquet backend (pyarrow). The real shard format.
+
+Exercised only when pyarrow is installed; the control flow it plugs into is
+covered by the CSV-backed tests.
+"""
+EXT = ".parquet"
+COMPRESSION = "zstd"
+
+
+def _arrow_types():
+    import pyarrow as pa
+    return {
+        "int8": pa.int8(), "int16": pa.int16(), "int32": pa.int32(), "int64": pa.int64(),
+        "uint8": pa.uint8(), "uint16": pa.uint16(), "uint32": pa.uint32(), "uint64": pa.uint64(),
+        "bool": pa.bool_(), "double": pa.float64(), "float64": pa.float64(),
+        # bigint values can exceed any fixed width, so store them as decimal strings.
+        "string": pa.string(), "bigint": pa.string(),
+    }
+
+
+def _rows_to_table(schema, rows):
+    import pyarrow as pa
+
+    t = _arrow_types()
+    cols = {n: [] for n, _ in schema}
+    for r in rows:
+        for n, dt in schema:
+            cols[n].append(str(r[n]) if dt == "bigint" else r[n])
+    arrays = [pa.array(cols[n], type=t[dt]) for n, dt in schema]
+    return pa.table(arrays, names=[n for n, _ in schema])
+
+
+def write_table(path, schema, rows):
+    import pyarrow.parquet as pq
+
+    pq.write_table(_rows_to_table(schema, rows), path, compression=COMPRESSION)
+
+
+class Writer:
+    """Streaming writer: each part becomes a row group; memory stays bounded."""
+
+    def __init__(self, path, schema):
+        import pyarrow.parquet as pq
+
+        self.schema = schema
+        self._pq = pq
+        self._writer = None
+        self._path = path
+
+    def write_table(self, rows):
+        table = _rows_to_table(self.schema, rows)
+        if self._writer is None:
+            self._writer = self._pq.ParquetWriter(self._path, table.schema,
+                                                  compression=COMPRESSION)
+        self._writer.write_table(table)
+
+    def close(self):
+        if self._writer is not None:
+            self._writer.close()
+
+
+def open_writer(path, schema):
+    return Writer(path, schema)
+
+
+def read_table(path, schema):
+    import pyarrow.parquet as pq
+
+    cols = pq.read_table(path).to_pydict()
+    dtypes = dict(schema)
+    n = len(next(iter(cols.values()))) if cols else 0
+    rows = []
+    for i in range(n):
+        row = {}
+        for k in cols:
+            v = cols[k][i]
+            if dtypes.get(k) == "bigint" and v is not None:
+                v = int(v)  # stored as decimal string; restore exact integer
+            row[k] = v
+        rows.append(row)
+    return rows
+
+
+def count_rows(path):
+    import pyarrow.parquet as pq
+
+    return pq.ParquetFile(path).metadata.num_rows