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.2.0.tar.gz (742.8 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.2.0-cp313-cp313-win_amd64.whl (812.0 kB view details)

Uploaded CPython 3.13Windows x86-64

treemendous-1.2.0-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.2.0-cp313-cp313-macosx_12_0_universal2.whl (1.7 MB view details)

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

treemendous-1.2.0-cp312-cp312-win_amd64.whl (812.0 kB view details)

Uploaded CPython 3.12Windows x86-64

treemendous-1.2.0-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.2.0-cp312-cp312-macosx_12_0_universal2.whl (1.7 MB view details)

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

treemendous-1.2.0-cp311-cp311-win_amd64.whl (805.0 kB view details)

Uploaded CPython 3.11Windows x86-64

treemendous-1.2.0-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.2.0-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.2.0.tar.gz.

File metadata

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

File hashes

Hashes for treemendous-1.2.0.tar.gz
Algorithm Hash digest
SHA256 7ee78dd3daa88d70688f393be78c32238423372da0d26750c641d8d46f3bce95
MD5 285006079739c846e94c0656562a87f8
BLAKE2b-256 adc88f08f9b2fb93d3d609eeb6e77f3325471ffe374ea9732dc28299fc4eb3b2

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.2.0.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.2.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: treemendous-1.2.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 812.0 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.2.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 24cabedaf7ccb6afac91dfa0522018a73269c57b47af39b4a371447e314c36c5
MD5 2a9b6b2ed6d0e775f1243732b493e63b
BLAKE2b-256 eea59311ee59bcadd853ea9e331921045586cc85093e375d39b7f711b641eeac

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.2.0-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.2.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for treemendous-1.2.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 8aace178876e9ead9adf53d49bcdbb29c2f9bbbba9f838a91c9c9c0b7f57f40d
MD5 ef9789d37521a46437277845ee7e6e76
BLAKE2b-256 85c758a7413ca4da40691de90dd4912654d7a855ec04a37b65250a55bb748262

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.2.0-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.2.0-cp313-cp313-macosx_12_0_universal2.whl.

File metadata

File hashes

Hashes for treemendous-1.2.0-cp313-cp313-macosx_12_0_universal2.whl
Algorithm Hash digest
SHA256 e072c0a68a1c74b69dc066b15078534c602423d3dadb564913549dd247bc542a
MD5 2f51f9a88612dfc0e3b68df6d81a9410
BLAKE2b-256 4423a920b82f3d5fa8e24449635a2a6eafe2be473828b7844e09ed1bc7aead31

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.2.0-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.2.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: treemendous-1.2.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 812.0 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.2.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 9f0865fe9d6f36a5d6bf57b8425e2218559974b82ea32bd6f8cb916ce4841223
MD5 375c056510ddce972ddaa6fd1a1af4e7
BLAKE2b-256 1d6b5f197cfaca62f7f0133284206382f4e3147ac1954cae7163bfd3b8fbca96

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.2.0-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.2.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for treemendous-1.2.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ea281736db6aa06c78202bbd669c825dbcb3372fcce23a5db1e561d847253bed
MD5 601bd2f3bb3b6cf82e0513e63f73b5be
BLAKE2b-256 9b0188aa4109f2cf3621b4cd1226e74a3eb641ae7f219e69f2c348719df68469

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.2.0-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.2.0-cp312-cp312-macosx_12_0_universal2.whl.

File metadata

File hashes

Hashes for treemendous-1.2.0-cp312-cp312-macosx_12_0_universal2.whl
Algorithm Hash digest
SHA256 3a703df6755199e7eedc3f6bf330e5050d8e9347d3f6ca733a27619f9fcd4a2c
MD5 1a5349c15082fb8df6566ba4e81057db
BLAKE2b-256 4b65a57320f30749fda4c1246908e079314707c19c9cb163d1dd3d42da4d67a4

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.2.0-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.2.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: treemendous-1.2.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 805.0 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.2.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 a82fd5d34245a7fbc2a469cb3cca97a96e9060f65082acfeed34cd69deb705c6
MD5 fcaa7b2a9dfa2a749568c35f67dd726a
BLAKE2b-256 0b29b794954769fb8d6d8ef200dcf5978fd5da7c081bc84e73f3bf423ea9eb80

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.2.0-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.2.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for treemendous-1.2.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 eac3026cc3e15ee2e583705d9f3ea544a8604cd4843f2247c388837fa52ca1a4
MD5 9e1cc2a494a7b05b99a432d7b01d0345
BLAKE2b-256 1d18bdbbf7a481fac36c9a424893fba317ccab91028ed2fc683a15cb7dce8b38

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.2.0-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.2.0-cp311-cp311-macosx_12_0_universal2.whl.

File metadata

File hashes

Hashes for treemendous-1.2.0-cp311-cp311-macosx_12_0_universal2.whl
Algorithm Hash digest
SHA256 50e71e3e72654b70ee9f33dbb5c1d6f54217872699140e8eb71150acc75162f8
MD5 d751909ef33774fe995a7d409382b0cb
BLAKE2b-256 3a0e405e637410d520e91157e1fc84e2b2189f57189ef7cc3b98d35cf5a87cc3

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.2.0-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

This release

1.2.0 This release

10 files

1.1.1

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