Tree-Mendous

Tree-Mendous provides exact half-open integer range sets: [start, end) includes start and excludes end. Choose the stable RangeSet interface for payloads, queries, and allocation; a specialized native API for atomic geometry batches; 50 process-local application engines; or explicitly experimental multidimensional indexes.

Choose an API

The task-oriented interface guide explains these boundaries in detail.

Install

Tree-Mendous supports CPython 3.11–3.13.

python -m pip install treemendous

RangeSet quickstart

This complete example reserves unavailable edges, atomically allocates the first two-unit slot, and checks the remaining capacity:

from treemendous import Span, create_range_set

ranges = create_range_set((0, 24), backend="py_boundary")
ranges.discard(Span(0, 9))
ranges.discard(Span(17, 24))

booking = ranges.allocate(2, not_before=9, not_after=17)
assert booking is not None
assert booking.span == Span(9, 11)
assert ranges.first_fit(2, not_before=11, not_after=17).span == Span(11, 13)
assert ranges.snapshot().total_free == 6

allocate returns None if no fit exists. Coordinates must be integers, lengths must be positive, and mutations must stay inside the managed domain. Payload behavior is selected with an explicit UniformPayloadPolicy, JoinPayloadPolicy, or OrderedPayloadPolicy; see the API guide.

Exact-batch quickstart

Use ExactBatchRangeSet when one ordered, geometry-only batch must either publish completely or leave the prior snapshot visible:

from treemendous import Span
from treemendous.exact_batch import (
    BatchMutation,
    ExactBatchRangeSet,
    MutationOpcode,
)

ranges = ExactBatchRangeSet((0, 64), initially_available=False)
results = ranges.mutate(
    [
        BatchMutation(MutationOpcode.ADD, 8, 20),
        BatchMutation(MutationOpcode.DISCARD_REQUIRE_COVERED, 10, 14),
    ]
)

assert [result.changed for result in results] == [
    (Span(8, 20),),
    (Span(10, 14),),
]
assert ranges.snapshot().intervals[0].span == Span(8, 10)

Rows execute in input order. Per-instance limits bound operations, live intervals, changed spans, packed-result bytes, and staging work. Exact batch is not a RangeSet backend and is not integrated into the 50 application engines. Read the exact-batch contract.

Performance

Performance depends on workload shape, state size, backend availability, platform, and which wrapper or materialization layers are timed. Current local Apple M5 Max/macOS 26.5.1/CPython 3.12.7 standard measurements put cpp_boundary at about 0.30M–0.91M timed public operations per second across six traces with 64–128 initial intervals. This is evidence for those traces, not a universal throughput claim. Large snapshots and sorted-vector exact batches can become copy-bound.

The performance guide reports operation-level measurements, hosted 1.1.0 exact-batch evidence, timing boundaries, and the optimization roadmap. The benchmark methodology explains correctness checks and durable artifacts.

Applications and reusable patterns

The 50 concrete engines cover partitioning, scheduling, overlap catalogs, allocation, and numeric leasing. Each has its own factory, state model, and exclusions; names describing distributed work do not imply transport, consensus, or durable storage. Start with the application index or the application-pattern guide.

Two additional executable patterns demonstrate APIs outside the 50-engine registry:

• atomic port-pool reconciliation uses exact batch for geometry only; it has no lease identity, TTL, or fencing;
• spatiotemporal geofences uses experimental, process-local BoxIndex3D.

The registered radio-spectrum engine is the existing generic BoxIndex integration: it wraps an experimental BoxIndex(2) inside its stable, application-specific reservation contract. The Morton catalog instead uses one-dimensional Morton candidate bands plus exact Cartesian filtering. The new BoxIndex3D pattern is outside the registry, and exact batch is not integrated into any of the 50 engines.

Backend maturity

Automatic selection considers only stable backends that are available, pass semantic probes, and satisfy requested capabilities. Selecting an unavailable or invalid backend raises a reasoned error.

See the backend catalog for discovery and qualification details.

Documentation

• Documentation index
• Getting started
• Choosing an interface
• Canonical API
• Performance
• Examples
• Release notes

Development

git clone https://github.com/josephjohncox/TreeMendous.git
cd TreeMendous
uv sync --all-extras
just check
just run-examples

Use just build for locally verified wheel and source artifacts. See Contributing and Releasing for the complete quality and publication contracts.

BSD-3-Clause license.