mathy/mathstream

Mathstream Library

mathstream offers streamed, string-based arithmetic for very large integers that you may not want to load entirely into memory. Instead of parsing numbers into Python int values, you work with digit files on disk via StreamNumber and call math operations that operate chunk-by-chunk.

Quick Start

python -m venv venv
source venv/bin/activate
pip install -e .

Create digit files anywhere you like (the examples below use instance/log), then construct StreamNumber objects, and call the helpers:

from mathstream import StreamNumber, add, sub, mul, div, pow

a = StreamNumber("instance/log/huge.txt")
b = StreamNumber("instance/log/tiny.txt")
e = StreamNumber("instance/log/exponent.txt")

print("sum =", "".join(add(a, b).stream()))
print("difference =", "".join(sub(a, b).stream()))
print("product =", "".join(mul(a, b).stream()))
print("quotient =", "".join(div(a, b).stream()))
print("power =", "".join(pow(a, e).stream()))

Each arithmetic call writes its result back into instance/log (configurable via mathstream.number.LOG_DIR) so you can stream the digits later or reuse them in further operations.

Core Concepts

• StreamNumber(path) – Wraps a digit text file. The file may include an optional leading sign (+ or -). Whitespace is ignored; digits must otherwise be contiguous.
• .stream(chunk_size) – Yields strings of digits with the provided chunk size. Operations in mathstream.engine consume these streams to avoid loading the entire number at once.
• Automatic staging – Outputs are stored under LOG_DIR with hashes based on input file paths, letting you compose operations without manual bookkeeping.
• Sign-aware – Addition, subtraction, multiplication, division (// behavior), and exponentiation (non-negative exponents) all respect operand sign. Division follows Python’s floor division rules.
• Utilities – clear_logs() wipes prior staged results so you can start fresh.

Example Script

test.py in the repository root demonstrates a minimal workflow:

1. Writes sample operands to tests/*.txt.
2. Calls every arithmetic primitive.
3. Asserts that the streamed outputs match known values (helpful for quick regression checks).

Run it via:

python test.py

Extending

• To hook into other storage backends, implement your own StreamNumber variant with the same .stream() interface.
• Need modulo or gcd? Compose the existing primitives (e.g., repeated subtraction or using div + remainder tracking inside _divide_abs) or add new helpers following the same streamed pattern.
• For more control over output locations, override LOG_DIR before using the operations:

from mathstream import engine
from pathlib import Path

engine.LOG_DIR = Path("/tmp/my_mathstage")
engine.clear_logs()

With these building blocks, you can manipulate arbitrarily large integers while keeping memory usage constant. Happy streaming!