Skip to main content

Tree-Mendous

PyPI Python CI License

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

Need Interface Status Important boundary
Add, discard, query, allocate, snapshot, or attach payloads RangeSet via treemendous.create_range_set Stable The canonical general-purpose API
Apply ordered geometry mutations as one native transaction treemendous.exact_batch Stable, specialized No payloads, allocation, or generic query API
Use a concrete scheduler, allocator, catalog, partitioner, or lease pool treemendous.applications Stable application namespace 50 process-local engines with scenario-specific contracts
Index identity-preserving 2D–4D boxes treemendous.multidimensional Experimental Process-local; not exported from the package root

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:

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.

Backend ID Runtime Width Maturity Notes
py_boundary Python/CPU 64-bit Stable Core geometry
py_avl_earliest Python/CPU 64-bit Stable Core geometry
py_summary Python/CPU 64-bit Stable Best-fit + analytics
py_treap Python/CPU 64-bit Stable Random interval sampling
py_boundary_summary Python/CPU 64-bit Stable Best-fit + analytics
cpp_boundary C++/CPU 64-bit Stable when built Core geometry
cpp_treap C++/CPU 32-bit Experimental Not selectable
cpp_boundary_summary C++/CPU 32-bit Experimental Not selectable
cpp_boundary_summary_optimized C++/CPU 32-bit Experimental Not selectable
gpu_boundary_summary CUDA/GPU 32-bit Experimental Not selectable
metal_boundary_summary Metal/GPU 32-bit Experimental Not selectable

See the backend catalog for discovery and qualification details.

Documentation

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

treemendous-1.1.1.tar.gz (614.1 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

treemendous-1.1.1-cp313-cp313-win_amd64.whl (808.6 kB view details)

Uploaded CPython 3.13Windows x86-64

treemendous-1.1.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.0 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

treemendous-1.1.1-cp313-cp313-macosx_12_0_universal2.whl (1.7 MB view details)

Uploaded CPython 3.13macOS 12.0+ universal2 (ARM64, x86-64)

treemendous-1.1.1-cp312-cp312-win_amd64.whl (808.5 kB view details)

Uploaded CPython 3.12Windows x86-64

treemendous-1.1.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.0 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

treemendous-1.1.1-cp312-cp312-macosx_12_0_universal2.whl (1.7 MB view details)

Uploaded CPython 3.12macOS 12.0+ universal2 (ARM64, x86-64)

treemendous-1.1.1-cp311-cp311-win_amd64.whl (801.6 kB view details)

Uploaded CPython 3.11Windows x86-64

treemendous-1.1.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.0 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

treemendous-1.1.1-cp311-cp311-macosx_12_0_universal2.whl (1.7 MB view details)

Uploaded CPython 3.11macOS 12.0+ universal2 (ARM64, x86-64)

File details

Details for the file treemendous-1.1.1.tar.gz.

File metadata

  • Download URL: treemendous-1.1.1.tar.gz
  • Upload date:
  • Size: 614.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for treemendous-1.1.1.tar.gz
Algorithm Hash digest
SHA256 00b184132f823ff644984b4ed42dc6b0d38e9b96a416b5a7ce4aecfe278cb8dd
MD5 f2325f35da81ad94a15e9ab3b171d4f7
BLAKE2b-256 b18313b10cddea31eaeefa5aa672ebfdf8d74daf7f64b59cfaa283516157aa04

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.1.tar.gz:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.1-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: treemendous-1.1.1-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 808.6 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for treemendous-1.1.1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 6b68d09a236bc232402f151a289785c7dcba5b621949bfdce049e66529dde4e0
MD5 4384125d0385957e365b231e79dc6c8e
BLAKE2b-256 9a3e72671be44c98bbf98340135301fdcf19b52cb1a274168597f52f6ede223f

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.1-cp313-cp313-win_amd64.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for treemendous-1.1.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 8e619c1384731fdde185e8ef98da3ba0c1491e25c311464c52d4596fdadda0a4
MD5 6e356affc620b80abf0a277a8a2f50a7
BLAKE2b-256 48b60f10399f0d7d9878b9e63f85d1811dbcfbf328bf5b0d40e85cb9e3951412

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.1-cp313-cp313-macosx_12_0_universal2.whl.

File metadata

File hashes

Hashes for treemendous-1.1.1-cp313-cp313-macosx_12_0_universal2.whl
Algorithm Hash digest
SHA256 1b1d43586f6332b3c4f8a18333cda0d62b213d70ac13d713f7992413831d561f
MD5 e79fad616bd0c8504aec00d4d1408803
BLAKE2b-256 7f692c041adf9388be3ee2813fc9e649c0b1a2f72dfbf8c27e0ff91b3bca3e82

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.1-cp313-cp313-macosx_12_0_universal2.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.1-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: treemendous-1.1.1-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 808.5 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for treemendous-1.1.1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 888bb577b3775d0201916bd8df647ccdebbf568392dc60c1719c75ea7907976a
MD5 ed5f2ee677294fe5172a402924664193
BLAKE2b-256 aa4c29cb29277674ae573aaa687172405aba47692d5f7ee7543bc4d9eea7d291

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.1-cp312-cp312-win_amd64.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for treemendous-1.1.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 8459e440355f9f14d9c02f55197806eec8906cd28197a442d1fc1ec75cc3e443
MD5 c95cb3e499cc61daa7f11d1d28970865
BLAKE2b-256 856550ae7f62c8b79567c89536a525afb820737bee32d60b08e0e335e24bb5bb

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.1-cp312-cp312-macosx_12_0_universal2.whl.

File metadata

File hashes

Hashes for treemendous-1.1.1-cp312-cp312-macosx_12_0_universal2.whl
Algorithm Hash digest
SHA256 a008d77490405da7198e865beee5b4a144200367f8639238e5a7ef5f718fc9b2
MD5 0d52c04f904c7f26e6d08e81d3153cab
BLAKE2b-256 62f358ae0eabaf117a4d9fab4419f5f8f7024aaa93a1ca8156d743b71082980a

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.1-cp312-cp312-macosx_12_0_universal2.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.1-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: treemendous-1.1.1-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 801.6 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for treemendous-1.1.1-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 e5c98ed77f096a6563d70ae2017835fb16dce2f9788d3a7b82d7935ab74c30e9
MD5 e0b76b5314a776e3dec0acfeaa5e315e
BLAKE2b-256 81f982443cb63fa0e1091934b3efea9c88d191e51e3efe8c081113962c7c0c28

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.1-cp311-cp311-win_amd64.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for treemendous-1.1.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 8fec5829bc3e00a231384128c2e786d851f591ac2c0083f9785ed87044c55d4a
MD5 132f6af47e0ee05abda6f9a00b7f1413
BLAKE2b-256 6e4eb804d0a2399b224dd508b6e203324985fce7d5bd8b0e987688b375f28fef

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.1-cp311-cp311-macosx_12_0_universal2.whl.

File metadata

File hashes

Hashes for treemendous-1.1.1-cp311-cp311-macosx_12_0_universal2.whl
Algorithm Hash digest
SHA256 f4a7220648a1706164ee04257fb06f553d5a4d471d5a54463c3605527df27e6e
MD5 d968da0b5fcfd0bd82d1d35baaa35c8d
BLAKE2b-256 6276be7079f120923f3de25a15e3adae3b407c54fa773dd0bdb0d00f2c7073b6

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.1-cp311-cp311-macosx_12_0_universal2.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.2.0

10 files

This release

1.1.1 This release

10 files

1.1.0

10 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page