iheap 0.1.0__tar.gz

iheap-0.1.0/Cargo.lock

@@ -0,0 +1,137 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 3
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "iheap-core"
+version = "0.1.0"
+
+[[package]]
+name = "iheap-py"
+version = "0.1.0"
+dependencies = [
+ "iheap-core",
+ "pyo3",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.191"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "229ca13b8a15bb0d1487b81ab975bfcd97513416499a8312011b6036e42e0de4"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "70130e2b6dd1ee589a8788026a429561ca5c40fa7a2fa7914c2282eddae24700"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e7ff73c555c286d212d4ce7e5fbda845a973c4f61bd5f160f5f2c3c2a04d1c4"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c46d2e5862c7bb8207e3b639f713dda3c499933444784154c11d013c5a691b60"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38b89f066f2ae72a2aef52d1537ca2fcd104440ebfadee06e97aa90738a25b9b"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"

iheap-0.1.0/Cargo.toml

@@ -0,0 +1,15 @@
+[workspace]
+resolver = "2"
+members = ["crates/iheap-core", "crates/iheap-py"]
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+repository = "https://github.com/nvbkdw/iheap"
+rust-version = "1.88"  # std::hint::select_unpredictable
+
+[profile.release]
+lto = "fat"
+codegen-units = 1
+panic = "abort"

iheap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Huang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

iheap-0.1.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: iheap
+Version: 0.1.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+License-File: LICENSE
+Summary: Fast indexed priority queue (pqdict-style) with a Rust core
+Keywords: priority queue,heap,indexed heap,pqdict,dijkstra
+Author-email: Ryan Huang <ryan.huang@noetik.ai>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://nvbkdw.github.io/iheap/
+Project-URL: Issues, https://github.com/nvbkdw/iheap/issues
+Project-URL: Repository, https://github.com/nvbkdw/iheap
+
+# iheap
+
+A fast **indexed priority queue** for Python with a Rust core. It's a drop-in
+style replacement for [`pqdict`](https://github.com/nvictus/pqdict), and is
+**3–20× faster**.
+
+```python
+from iheap import PQDict
+
+pq = PQDict({"a": 3, "b": 1, "c": 2})   # key -> priority, min on top
+pq["d"] = 0                             # insert
+pq["a"] = -1                            # update priority in O(log n)
+del pq["c"]                             # delete any key in O(log n)
+pq.top()                                # 'a'
+list(pq.popitems())                     # [('a', -1), ('d', 0), ('b', 1)]
+```
+
+```
+pip install iheap
+```
+
+📖 **Documentation:** <https://nvbkdw.github.io/iheap/>. It covers a
+getting-started guide, the API reference, the benchmark and development notes.
+
+Prebuilt `abi3` wheels cover CPython ≥ 3.10 on Linux (glibc and musl, x86_64
+and aarch64), macOS (x86_64 and arm64) and Windows (x64).
+
+## Design
+
+Only priorities (as `f64`) and integer handles cross into Rust. Keys and
+values (the payload) never leave Python.
+
+```
+           Python (iheap.PQDict)                     Rust (iheap-core)
+  ┌───────────────────────────────────┐   ┌─────────────────────────────────────┐
+  │ _handles: dict[key -> handle]     │   │ 8-ary tournament tree               │
+  │ _keys:    list[handle -> key]     │──▶│   leaves[h]  = priority of handle h │
+  │ _values:  list[handle -> value]   │   │   node       = winner of 8 children │
+  └───────────────────────────────────┘   └─────────────────────────────────────┘
+                    only f64 priorities and u32 handles cross ▲
+```
+
+* **Handles, not keys.** The Rust core gives out dense `u32` handles and
+  recycles them, so Python keeps its key/value data in plain lists indexed by
+  handle. Rust never holds a Python object and never calls back into Python.
+* **An 8-ary tournament (winner) tree, not a binary heap.** Leaf `h` holds the
+  priority of handle `h`, so no position map is needed. Each internal node
+  stores the winner of 8 children. A sibling group is one 64- or 128-byte
+  cache-line block.
+* **The path is known in advance.** Every operation writes one leaf and
+  replays the path to the root, and the node above leaf `h` on each level is
+  `h >> 3·level`. In a heap's sift-down, each load must wait for the previous
+  comparison. Here, the winner among the *other* siblings on each level
+  doesn't depend on the value being replayed, so the CPU computes all levels
+  in parallel. The serial work per level is a single compare-and-select. On
+  aarch64, the 8-way reductions use NEON.
+* **Early exit.** Updates stop once a node's winner is unchanged, so insert,
+  decrease-key and changes to non-winning entries usually take one or two
+  comparisons.
+* **Order-preserving `u64` keys.** Priorities are stored as integers with the
+  same ordering. This gives integer compares and a total order: `-0.0` sorts
+  before `+0.0`, and both round-trip exactly. A vacant-leaf sentinel can never
+  collide with a real priority, because it corresponds to NaN, which is
+  rejected. A max-queue complements the keys.
+* **Growth only appends.** Bulk loads (`push_many`, `PQDict(data)`) rebuild
+  the tree in `O(n)`, and building a `PQDict` takes one native call.
+* **Clean layering.** `crates/iheap-core` is pure Rust with no PyO3 dependency
+  and has its own tests. `crates/iheap-py` is a thin PyO3 binding.
+  `python/iheap/_pqdict.py` implements the mapping API.
+
+## API
+
+### `PQDict(data=None, *, key=None, reverse=False)`
+
+A `MutableMapping` whose items are ordered by priority. The priority is
+`key(value)` if a `key` function is given, otherwise the value itself.
+`reverse=True` makes it a max-queue. Ties are popped in unspecified order.
+
+`PQDict` supports **every `dict` operation**: `pq[k]`, `pq[k] = v`,
+`del pq[k]`, `k in pq`, `len`, `iter`, `reversed`, `get`, `setdefault`,
+`pop(k[, default])`, `update`, `|`, `|=`, `keys`/`values`/`items` views,
+`clear`, `copy`, `fromkeys`, equality with any mapping, and pickling. As with
+`dict`, iteration follows **insertion order**. The one intended difference is
+`popitem()`, which removes the **top-priority** item instead of the last one
+inserted.
+
+| Method | Description |
+|---|---|
+| `pq[k] = v`, `del pq[k]`, `pq[k]`, `k in pq`, `len(pq)` | mapping protocol; inserts, updates and deletes are `O(log n)` |
+| `top(default)`, `topvalue(default)`, `topitem()` | look at the top item |
+| `pop()`, `popvalue(default)`, `popitem()` | remove the top item (`pop(key[, default])` keeps dict semantics) |
+| `additem(k, v)` / `updateitem(k, v)` | strict insert / strict update |
+| `pushpopitem(k, v)` | push then pop, done as a single tree replay |
+| `replace_key(k, new_k)`, `swap_priority(k1, k2)` | change keys in place (no heap work) |
+| `popkeys()`, `popvalues()`, `popitems()` | destructive iteration in priority order |
+| `heapify(key=None)` | re-prioritize after a value was mutated in place |
+| `update(mapping)` | bulk insert/update with one native call (atomic) |
+| `copy()`, pickling, `fromkeys()` | |
+
+Module functions: `minpq(**kw)`, `maxpq(**kw)`, `nsmallest(n, mapping, key=None)`,
+`nlargest(n, mapping, key=None)`.
+
+Differences from `pqdict`: priorities must be real numbers, and the custom
+comparator `precedes=` is replaced by `reverse=`.
+
+### `IndexedHeap(*, reverse=False, capacity=0)`
+
+The raw native heap, for when you want to manage your own key ↔ handle mapping:
+
+```python
+from iheap import IndexedHeap
+
+heap = IndexedHeap()
+h = heap.push(3.5)               # -> handle (int)
+heap.update(h, 1.0)              # -> old priority
+heap.remove(h)                   # -> priority
+handles = heap.push_many([5, 2, 8])
+heap.peek()                      # (handle, priority) or None
+heap.pop()                       # (handle, priority); IndexError if empty
+heap.pop_many(2)
+heap.push_pop(4.0)               # fused push+pop; reuses the popped handle
+```
+
+Handles stay valid until their entry is popped or removed, are always below
+`heap.handle_bound`, and are reused afterwards.
+
+## Benchmark
+
+`benchmarks/bench.py` runs a standard set of indexed-priority-queue
+operations. Each phase starts from fresh state, uses random `float`
+priorities and `str` keys, and reports the best of 5 runs:
+
+* **insert**: `n` single inserts into an empty queue
+* **build**: construct from `n` items in one call
+* **update**: `n` priority changes on random existing keys
+* **delete**: `n/2` deletions of random keys
+* **pop**: pop everything in priority order
+
+Implementations compared:
+
+* `iheap.PQDict`: this library's mapping API
+* `iheap.IndexedHeap`: the raw handle API, with the caller keeping a key → handle `dict`
+* [`pqdict`](https://pypi.org/project/pqdict/) 1.4: the pure-Python reference
+* `heapq (lazy)`: the stdlib "mark removed, skip on pop" recipe from the
+  Python docs. Its update and delete are cheap because they defer the work
+  to pop.
+
+Results on Apple M4 Max, CPython 3.13.7, iheap 0.1.0. Each cell is **ns per
+operation, lower is better**, with the speed-up over `pqdict` in parentheses.
+
+**n = 10,000**
+
+| implementation | insert | build | update | delete | pop |
+|---|---:|---:|---:|---:|---:|
+| iheap.PQDict | 155 (3.4x) | 48 (11.6x) | 122 (7.1x) | 134 (5.6x) | 139 (16.7x) |
+| iheap.IndexedHeap | 56 (9.4x) | 38 (14.4x) | 55 (15.6x) | 70 (10.8x) | 87 (26.6x) |
+| pqdict | 527 | 552 | 867 | 759 | 2,322 |
+| heapq (lazy) | 185 (2.9x) | 114 (4.9x) | 234 (3.7x) | 76 (9.9x) | 425 (5.5x) |
+
+**n = 100,000**
+
+| implementation | insert | build | update | delete | pop |
+|---|---:|---:|---:|---:|---:|
+| iheap.PQDict | 178 (3.4x) | 61 (11.1x) | 264 (6.0x) | 317 (4.5x) | 293 (14.9x) |
+| iheap.IndexedHeap | 75 (8.0x) | 53 (12.6x) | 118 (13.5x) | 149 (9.5x) | 184 (23.8x) |
+| pqdict | 603 | 674 | 1,593 | 1,415 | 4,376 |
+| heapq (lazy) | 237 (2.5x) | 147 (4.6x) | 487 (3.3x) | 283 (5.0x) | 970 (4.5x) |
+
+**n = 1,000,000**
+
+| implementation | insert | build | update | delete | pop |
+|---|---:|---:|---:|---:|---:|
+| iheap.PQDict | 260 (3.0x) | 110 (8.6x) | 660 (4.1x) | 760 (3.3x) | 754 (11.9x) |
+| iheap.IndexedHeap | 151 (5.1x) | 87 (10.9x) | 459 (5.9x) | 491 (5.1x) | 614 (14.6x) |
+| pqdict | 769 | 950 | 2,688 | 2,512 | 8,977 |
+| heapq (lazy) | 360 (2.1x) | 245 (3.9x) | 860 (3.1x) | 552 (4.6x) | 2,473 (3.6x) |
+
+### The Rust core alone
+
+`cargo run --release --example bench -p iheap-core` measures the core with
+Python out of the picture. The table compares the current tournament tree
+with the 4-ary binary heap used at first, in ns per operation:
+
+| n | insert | build | update | delete | pop |
+|---:|---:|---:|---:|---:|---:|
+| 10k | 3.0 → 3.0 (1.0×) | 3.5 → 2.2 (1.6×) | 3.2 → 2.0 (1.6×) | 3.9 → 2.5 (1.6×) | 25.2 → 17.1 (1.5×) |
+| 100k | 5.3 → 4.3 (1.2×) | 4.1 → 2.1 (2.0×) | 10.5 → 3.5 (3.0×) | 5.9 → 3.1 (1.9×) | 37.5 → 20.3 (1.8×) |
+| 1M | 8.0 → 4.9 (1.6×) | 4.7 → 2.6 (1.8×) | 18.2 → 5.6 (3.2×) | 14.1 → 5.4 (2.6×) | 64.0 → 29.6 (2.2×) |
+
+From n = 100k up, the core is **2.1× faster** (geometric mean over the five
+operations). In the Python benchmark above, the core accounts for only 5–20%
+of the time; the rest is the interpreter itself (method dispatch, `dict`
+lookups on string keys, object allocation). End to end, the new core makes
+`IndexedHeap` 1.1–1.4× faster and `PQDict` up to 1.3× faster. The
+[benchmark docs](https://nvbkdw.github.io/iheap/benchmark/) include the full
+optimization log, with every experiment that was kept or rejected.
+
+Reproduce with:
+
+```
+uv venv && uv pip install maturin pqdict
+maturin develop --release
+python benchmarks/bench.py --n 10000 100000 1000000 --markdown
+```
+
+## Development
+
+```
+cargo test -p iheap-core                  # Rust core tests (incl. randomized model test)
+maturin develop --release && pytest       # Python tests (incl. differential test vs pqdict)
+```
+
+Releasing: bump `version` in the root `Cargo.toml`, then push a `vX.Y.Z` tag.
+CI builds the wheels and sdist and publishes them to PyPI through Trusted
+Publishing.
+
+## License
+
+MIT
+

iheap-0.1.0/README.md

@@ -0,0 +1,219 @@
+# iheap
+
+A fast **indexed priority queue** for Python with a Rust core. It's a drop-in
+style replacement for [`pqdict`](https://github.com/nvictus/pqdict), and is
+**3–20× faster**.
+
+```python
+from iheap import PQDict
+
+pq = PQDict({"a": 3, "b": 1, "c": 2})   # key -> priority, min on top
+pq["d"] = 0                             # insert
+pq["a"] = -1                            # update priority in O(log n)
+del pq["c"]                             # delete any key in O(log n)
+pq.top()                                # 'a'
+list(pq.popitems())                     # [('a', -1), ('d', 0), ('b', 1)]
+```
+
+```
+pip install iheap
+```
+
+📖 **Documentation:** <https://nvbkdw.github.io/iheap/>. It covers a
+getting-started guide, the API reference, the benchmark and development notes.
+
+Prebuilt `abi3` wheels cover CPython ≥ 3.10 on Linux (glibc and musl, x86_64
+and aarch64), macOS (x86_64 and arm64) and Windows (x64).
+
+## Design
+
+Only priorities (as `f64`) and integer handles cross into Rust. Keys and
+values (the payload) never leave Python.
+
+```
+           Python (iheap.PQDict)                     Rust (iheap-core)
+  ┌───────────────────────────────────┐   ┌─────────────────────────────────────┐
+  │ _handles: dict[key -> handle]     │   │ 8-ary tournament tree               │
+  │ _keys:    list[handle -> key]     │──▶│   leaves[h]  = priority of handle h │
+  │ _values:  list[handle -> value]   │   │   node       = winner of 8 children │
+  └───────────────────────────────────┘   └─────────────────────────────────────┘
+                    only f64 priorities and u32 handles cross ▲
+```
+
+* **Handles, not keys.** The Rust core gives out dense `u32` handles and
+  recycles them, so Python keeps its key/value data in plain lists indexed by
+  handle. Rust never holds a Python object and never calls back into Python.
+* **An 8-ary tournament (winner) tree, not a binary heap.** Leaf `h` holds the
+  priority of handle `h`, so no position map is needed. Each internal node
+  stores the winner of 8 children. A sibling group is one 64- or 128-byte
+  cache-line block.
+* **The path is known in advance.** Every operation writes one leaf and
+  replays the path to the root, and the node above leaf `h` on each level is
+  `h >> 3·level`. In a heap's sift-down, each load must wait for the previous
+  comparison. Here, the winner among the *other* siblings on each level
+  doesn't depend on the value being replayed, so the CPU computes all levels
+  in parallel. The serial work per level is a single compare-and-select. On
+  aarch64, the 8-way reductions use NEON.
+* **Early exit.** Updates stop once a node's winner is unchanged, so insert,
+  decrease-key and changes to non-winning entries usually take one or two
+  comparisons.
+* **Order-preserving `u64` keys.** Priorities are stored as integers with the
+  same ordering. This gives integer compares and a total order: `-0.0` sorts
+  before `+0.0`, and both round-trip exactly. A vacant-leaf sentinel can never
+  collide with a real priority, because it corresponds to NaN, which is
+  rejected. A max-queue complements the keys.
+* **Growth only appends.** Bulk loads (`push_many`, `PQDict(data)`) rebuild
+  the tree in `O(n)`, and building a `PQDict` takes one native call.
+* **Clean layering.** `crates/iheap-core` is pure Rust with no PyO3 dependency
+  and has its own tests. `crates/iheap-py` is a thin PyO3 binding.
+  `python/iheap/_pqdict.py` implements the mapping API.
+
+## API
+
+### `PQDict(data=None, *, key=None, reverse=False)`
+
+A `MutableMapping` whose items are ordered by priority. The priority is
+`key(value)` if a `key` function is given, otherwise the value itself.
+`reverse=True` makes it a max-queue. Ties are popped in unspecified order.
+
+`PQDict` supports **every `dict` operation**: `pq[k]`, `pq[k] = v`,
+`del pq[k]`, `k in pq`, `len`, `iter`, `reversed`, `get`, `setdefault`,
+`pop(k[, default])`, `update`, `|`, `|=`, `keys`/`values`/`items` views,
+`clear`, `copy`, `fromkeys`, equality with any mapping, and pickling. As with
+`dict`, iteration follows **insertion order**. The one intended difference is
+`popitem()`, which removes the **top-priority** item instead of the last one
+inserted.
+
+| Method | Description |
+|---|---|
+| `pq[k] = v`, `del pq[k]`, `pq[k]`, `k in pq`, `len(pq)` | mapping protocol; inserts, updates and deletes are `O(log n)` |
+| `top(default)`, `topvalue(default)`, `topitem()` | look at the top item |
+| `pop()`, `popvalue(default)`, `popitem()` | remove the top item (`pop(key[, default])` keeps dict semantics) |
+| `additem(k, v)` / `updateitem(k, v)` | strict insert / strict update |
+| `pushpopitem(k, v)` | push then pop, done as a single tree replay |
+| `replace_key(k, new_k)`, `swap_priority(k1, k2)` | change keys in place (no heap work) |
+| `popkeys()`, `popvalues()`, `popitems()` | destructive iteration in priority order |
+| `heapify(key=None)` | re-prioritize after a value was mutated in place |
+| `update(mapping)` | bulk insert/update with one native call (atomic) |
+| `copy()`, pickling, `fromkeys()` | |
+
+Module functions: `minpq(**kw)`, `maxpq(**kw)`, `nsmallest(n, mapping, key=None)`,
+`nlargest(n, mapping, key=None)`.
+
+Differences from `pqdict`: priorities must be real numbers, and the custom
+comparator `precedes=` is replaced by `reverse=`.
+
+### `IndexedHeap(*, reverse=False, capacity=0)`
+
+The raw native heap, for when you want to manage your own key ↔ handle mapping:
+
+```python
+from iheap import IndexedHeap
+
+heap = IndexedHeap()
+h = heap.push(3.5)               # -> handle (int)
+heap.update(h, 1.0)              # -> old priority
+heap.remove(h)                   # -> priority
+handles = heap.push_many([5, 2, 8])
+heap.peek()                      # (handle, priority) or None
+heap.pop()                       # (handle, priority); IndexError if empty
+heap.pop_many(2)
+heap.push_pop(4.0)               # fused push+pop; reuses the popped handle
+```
+
+Handles stay valid until their entry is popped or removed, are always below
+`heap.handle_bound`, and are reused afterwards.
+
+## Benchmark
+
+`benchmarks/bench.py` runs a standard set of indexed-priority-queue
+operations. Each phase starts from fresh state, uses random `float`
+priorities and `str` keys, and reports the best of 5 runs:
+
+* **insert**: `n` single inserts into an empty queue
+* **build**: construct from `n` items in one call
+* **update**: `n` priority changes on random existing keys
+* **delete**: `n/2` deletions of random keys
+* **pop**: pop everything in priority order
+
+Implementations compared:
+
+* `iheap.PQDict`: this library's mapping API
+* `iheap.IndexedHeap`: the raw handle API, with the caller keeping a key → handle `dict`
+* [`pqdict`](https://pypi.org/project/pqdict/) 1.4: the pure-Python reference
+* `heapq (lazy)`: the stdlib "mark removed, skip on pop" recipe from the
+  Python docs. Its update and delete are cheap because they defer the work
+  to pop.
+
+Results on Apple M4 Max, CPython 3.13.7, iheap 0.1.0. Each cell is **ns per
+operation, lower is better**, with the speed-up over `pqdict` in parentheses.
+
+**n = 10,000**
+
+| implementation | insert | build | update | delete | pop |
+|---|---:|---:|---:|---:|---:|
+| iheap.PQDict | 155 (3.4x) | 48 (11.6x) | 122 (7.1x) | 134 (5.6x) | 139 (16.7x) |
+| iheap.IndexedHeap | 56 (9.4x) | 38 (14.4x) | 55 (15.6x) | 70 (10.8x) | 87 (26.6x) |
+| pqdict | 527 | 552 | 867 | 759 | 2,322 |
+| heapq (lazy) | 185 (2.9x) | 114 (4.9x) | 234 (3.7x) | 76 (9.9x) | 425 (5.5x) |
+
+**n = 100,000**
+
+| implementation | insert | build | update | delete | pop |
+|---|---:|---:|---:|---:|---:|
+| iheap.PQDict | 178 (3.4x) | 61 (11.1x) | 264 (6.0x) | 317 (4.5x) | 293 (14.9x) |
+| iheap.IndexedHeap | 75 (8.0x) | 53 (12.6x) | 118 (13.5x) | 149 (9.5x) | 184 (23.8x) |
+| pqdict | 603 | 674 | 1,593 | 1,415 | 4,376 |
+| heapq (lazy) | 237 (2.5x) | 147 (4.6x) | 487 (3.3x) | 283 (5.0x) | 970 (4.5x) |
+
+**n = 1,000,000**
+
+| implementation | insert | build | update | delete | pop |
+|---|---:|---:|---:|---:|---:|
+| iheap.PQDict | 260 (3.0x) | 110 (8.6x) | 660 (4.1x) | 760 (3.3x) | 754 (11.9x) |
+| iheap.IndexedHeap | 151 (5.1x) | 87 (10.9x) | 459 (5.9x) | 491 (5.1x) | 614 (14.6x) |
+| pqdict | 769 | 950 | 2,688 | 2,512 | 8,977 |
+| heapq (lazy) | 360 (2.1x) | 245 (3.9x) | 860 (3.1x) | 552 (4.6x) | 2,473 (3.6x) |
+
+### The Rust core alone
+
+`cargo run --release --example bench -p iheap-core` measures the core with
+Python out of the picture. The table compares the current tournament tree
+with the 4-ary binary heap used at first, in ns per operation:
+
+| n | insert | build | update | delete | pop |
+|---:|---:|---:|---:|---:|---:|
+| 10k | 3.0 → 3.0 (1.0×) | 3.5 → 2.2 (1.6×) | 3.2 → 2.0 (1.6×) | 3.9 → 2.5 (1.6×) | 25.2 → 17.1 (1.5×) |
+| 100k | 5.3 → 4.3 (1.2×) | 4.1 → 2.1 (2.0×) | 10.5 → 3.5 (3.0×) | 5.9 → 3.1 (1.9×) | 37.5 → 20.3 (1.8×) |
+| 1M | 8.0 → 4.9 (1.6×) | 4.7 → 2.6 (1.8×) | 18.2 → 5.6 (3.2×) | 14.1 → 5.4 (2.6×) | 64.0 → 29.6 (2.2×) |
+
+From n = 100k up, the core is **2.1× faster** (geometric mean over the five
+operations). In the Python benchmark above, the core accounts for only 5–20%
+of the time; the rest is the interpreter itself (method dispatch, `dict`
+lookups on string keys, object allocation). End to end, the new core makes
+`IndexedHeap` 1.1–1.4× faster and `PQDict` up to 1.3× faster. The
+[benchmark docs](https://nvbkdw.github.io/iheap/benchmark/) include the full
+optimization log, with every experiment that was kept or rejected.
+
+Reproduce with:
+
+```
+uv venv && uv pip install maturin pqdict
+maturin develop --release
+python benchmarks/bench.py --n 10000 100000 1000000 --markdown
+```
+
+## Development
+
+```
+cargo test -p iheap-core                  # Rust core tests (incl. randomized model test)
+maturin develop --release && pytest       # Python tests (incl. differential test vs pqdict)
+```
+
+Releasing: bump `version` in the root `Cargo.toml`, then push a `vX.Y.Z` tag.
+CI builds the wheels and sdist and publishes them to PyPI through Trusted
+Publishing.
+
+## License
+
+MIT

iheap-0.1.0/crates/iheap-core/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "iheap-core"
+description = "Indexed d-ary priority queue over f64 priorities with stable handles"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]