dtree-encoding 1.6.0__tar.gz → 1.8.0__tar.gz

{dtree_encoding-1.6.0 → dtree_encoding-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dtree-encoding
-Version: 1.6.0
+Version: 1.8.0
 Summary: DTree: incremental encoding of the topology of directed trees by two projections (Q1, Q2): O(1) reachability, and/or queries on the topology of the tree, dynamic (incremental) updates
 Author-email: Enis Olgac <enis@digraphs.info>
 License: MIT
@@ -59,7 +59,9 @@ t = DTree.from_file("Test.csx")   # e.g. examples/Test.csx from the repository
 | C# (docs) | Python |
 |---|---|
 | `DTree(id)` | `DTree(tree_id="P1")` |
-| `Insert(parent, child)` | `insert(parent, child)` |
+| `Insert(parent, child)` | `insert(parent, child)` (last child) |
+| `InsertAfter`, `InsertBefore` | `insert_after(sibling, child)`, `insert_before(sibling, child)` |
+| `AddLine` | `add_line(line)` (`p: c`, `s > c`, `s < c`; also in `from_file`) |
 | `Contains(node)` | `contains(node)` / `node in t` |
 | `GetParent(node)` | `get_parent(node)` (`None` for the root) |
 | `CutNPaste(u, p)` | `cut_n_paste(subtree_root, new_parent)` |
@@ -75,9 +77,12 @@ t = DTree.from_file("Test.csx")   # e.g. examples/Test.csx from the repository
 | `PathToRoot`, `RootToPath` | `path_to_root`, `root_to_path` (plus `path(u, v)`) |
 | `GetNode`, `TryGetNode`, `DNode` | `get_node`, `try_get_node`, `DNode` (node handles; `insert` returns one) |
 | `SubtreeLast` | `subtree_last` (last node of a subtree in Q1) |
+| `NextInQ1` | `next_in_q1` (next node in Q1, the display order; `None` at the end) |
 | `VMin`, `VMax`, `UMin`, `UMax` (of nodes) | `vmin`, `vmax`, `umin`, `umax` |
 | `ReachesAll`, `MayReachSome`, `ReachesSome` | `reaches_all`, `may_reach_some`, `reaches_some` |
 | `ReachedByAll`, `MayBeReachedBySome`, `ReachedBySome` | `reached_by_all`, `may_be_reached_by_some`, `reached_by_some` |
+| `Add`, `Discard`, `Contains` (of a constructed node) | `add`, `discard`, `node in s` |
+| `UMin.Covering` | `covering` (topmost member that reaches a node; `None` if none) |
 
 ## Semantics
 
@@ -88,7 +93,7 @@ t = DTree.from_file("Test.csx")   # e.g. examples/Test.csx from the repository
 - `delete(v)` re-attaches v's children to v's parent, in v's place among its siblings.
 - `delete_subtree(v)` removes v with all its descendants and returns them in Q1 order.
 - `cut_n_paste(u, p)` moves the subtree rooted at u under p as p's last child; p must not lie inside u's subtree.
-- And/or queries on the topology: the constructed nodes `vmin(S)`, `vmax(S)` (S as target) and `umin(S)`, `umax(S)` (S as source) take the minimum or maximum of each index over S, separately in Q1 and Q2. `reaches_all` and `reached_by_all` are exact O(1) tests; `may_reach_some` and `may_be_reached_by_some` are only filters, and `reaches_some` and `reached_by_some` are exact in O(log k). A constructed node stays valid under insertions and is recomputed automatically after `delete`, `delete_subtree` or `cut_n_paste`. See [and/or queries on the topology](https://github.com/EnisOlgac/DTree/blob/main/docs/and-or-queries.md).
+- And/or queries on the topology: the constructed nodes `vmin(S)`, `vmax(S)` (S as target) and `umin(S)`, `umax(S)` (S as source) take the minimum or maximum of each index over S, separately in Q1 and Q2. `reaches_all` and `reached_by_all` are exact O(1) tests; `may_reach_some` and `may_be_reached_by_some` are only filters, and `reaches_some` and `reached_by_some` are exact in O(log k). Members are added with `add` and removed with `discard`. A constructed node stays valid under insertions and is recomputed automatically after `delete`, `delete_subtree` or `cut_n_paste`. See [and/or queries on the topology](https://github.com/EnisOlgac/DTree/blob/main/docs/and-or-queries.md).
 - Projection positions are fractions: a new node gets the mediant (a+c)/(b+d) of its neighbors, so normally no other node moves. Only rare alternating insertion patterns trigger a local renumbering. Tree depth and width are unbounded. `t.Q1.index(v)` returns a position as a `Fraction`.
 
 ## Tests
@@ -101,14 +106,21 @@ Every operation is checked against a brute-force parent/children model on random
 
 ## Benchmarks
 
+The benchmarks come with the package, so you can measure on your own machine:
+
 ```
-python benchmarks/bench.py            # trees of 10,000 and 100,000 nodes
-python benchmarks/bench.py --quick    # a few seconds
-python benchmarks/bench.py --dynamic  # only insertions and queries alternating
-python benchmarks/bench.py 1000000    # custom sizes
+python -m dtree.bench            # trees of 10,000 and 100,000 nodes
+python -m dtree.bench --quick    # a few seconds
+python -m dtree.bench --dynamic  # only the dynamic updates and the tree view
+python -m dtree.bench --note "idle machine"   # remark for the report
+python -m dtree.bench 1000000    # custom sizes
 ```
 
-The script prints Markdown tables: build time and renumbering counts per tree shape (random, chain, star at the root, star at an inner node, alternating worst case), list growth at either end, and timings for `can_reach`, `depth`, `delete`, `cut_n_paste` and `delete_subtree`, and comparisons with a classical parent walk: reachability by tree depth, and/or queries with constructed nodes, and dynamic updates (insertions and queries alternating). Each `DList` keeps the counters `renumber_count` and `renumber_moved`, so the same figures are available in your own code via `t.Q1` and `t.Q2`.
+In a clone of the repository, `python python/benchmarks/bench.py` runs the same code from the sources.
+
+The script prints Markdown tables: build time and renumbering counts per tree shape (random, chain, star at the root, star at an inner node, alternating worst case), list growth at either end, and timings for `can_reach`, `depth`, `delete`, `cut_n_paste` and `delete_subtree`, and comparisons with a classical parent walk: reachability by tree depth, and/or queries with constructed nodes, dynamic updates (insertions with 1 or 10 queries each, and static pre/post numbers at depths 100 and 1,000), and a tree view with expand/collapse. Each dynamic measurement is the best of three runs. Each `DList` keeps the counters `renumber_count` and `renumber_moved`, so the same figures are available in your own code via `t.Q1` and `t.Q2`.
+
+Every run also writes its tables as a Markdown report to `benchmarks/python/`—in the current directory, or at the repository root when run inside a clone— named after date and time (for example `2026-10-17_14-18.md`), with a header giving the DTree and Python versions, the operating system and the processor; `--no-save` skips it. The C# benchmarks (`dotnet run --project csharp/DTree.Tests -c Release -- bench`) write theirs to `benchmarks/csharp/`.
 
 ## Provenance
 

{dtree_encoding-1.6.0 → dtree_encoding-1.8.0}/README.md

@@ -36,7 +36,9 @@ t = DTree.from_file("Test.csx")   # e.g. examples/Test.csx from the repository
 | C# (docs) | Python |
 |---|---|
 | `DTree(id)` | `DTree(tree_id="P1")` |
-| `Insert(parent, child)` | `insert(parent, child)` |
+| `Insert(parent, child)` | `insert(parent, child)` (last child) |
+| `InsertAfter`, `InsertBefore` | `insert_after(sibling, child)`, `insert_before(sibling, child)` |
+| `AddLine` | `add_line(line)` (`p: c`, `s > c`, `s < c`; also in `from_file`) |
 | `Contains(node)` | `contains(node)` / `node in t` |
 | `GetParent(node)` | `get_parent(node)` (`None` for the root) |
 | `CutNPaste(u, p)` | `cut_n_paste(subtree_root, new_parent)` |
@@ -52,9 +54,12 @@ t = DTree.from_file("Test.csx")   # e.g. examples/Test.csx from the repository
 | `PathToRoot`, `RootToPath` | `path_to_root`, `root_to_path` (plus `path(u, v)`) |
 | `GetNode`, `TryGetNode`, `DNode` | `get_node`, `try_get_node`, `DNode` (node handles; `insert` returns one) |
 | `SubtreeLast` | `subtree_last` (last node of a subtree in Q1) |
+| `NextInQ1` | `next_in_q1` (next node in Q1, the display order; `None` at the end) |
 | `VMin`, `VMax`, `UMin`, `UMax` (of nodes) | `vmin`, `vmax`, `umin`, `umax` |
 | `ReachesAll`, `MayReachSome`, `ReachesSome` | `reaches_all`, `may_reach_some`, `reaches_some` |
 | `ReachedByAll`, `MayBeReachedBySome`, `ReachedBySome` | `reached_by_all`, `may_be_reached_by_some`, `reached_by_some` |
+| `Add`, `Discard`, `Contains` (of a constructed node) | `add`, `discard`, `node in s` |
+| `UMin.Covering` | `covering` (topmost member that reaches a node; `None` if none) |
 
 ## Semantics
 
@@ -65,7 +70,7 @@ t = DTree.from_file("Test.csx")   # e.g. examples/Test.csx from the repository
 - `delete(v)` re-attaches v's children to v's parent, in v's place among its siblings.
 - `delete_subtree(v)` removes v with all its descendants and returns them in Q1 order.
 - `cut_n_paste(u, p)` moves the subtree rooted at u under p as p's last child; p must not lie inside u's subtree.
-- And/or queries on the topology: the constructed nodes `vmin(S)`, `vmax(S)` (S as target) and `umin(S)`, `umax(S)` (S as source) take the minimum or maximum of each index over S, separately in Q1 and Q2. `reaches_all` and `reached_by_all` are exact O(1) tests; `may_reach_some` and `may_be_reached_by_some` are only filters, and `reaches_some` and `reached_by_some` are exact in O(log k). A constructed node stays valid under insertions and is recomputed automatically after `delete`, `delete_subtree` or `cut_n_paste`. See [and/or queries on the topology](https://github.com/EnisOlgac/DTree/blob/main/docs/and-or-queries.md).
+- And/or queries on the topology: the constructed nodes `vmin(S)`, `vmax(S)` (S as target) and `umin(S)`, `umax(S)` (S as source) take the minimum or maximum of each index over S, separately in Q1 and Q2. `reaches_all` and `reached_by_all` are exact O(1) tests; `may_reach_some` and `may_be_reached_by_some` are only filters, and `reaches_some` and `reached_by_some` are exact in O(log k). Members are added with `add` and removed with `discard`. A constructed node stays valid under insertions and is recomputed automatically after `delete`, `delete_subtree` or `cut_n_paste`. See [and/or queries on the topology](https://github.com/EnisOlgac/DTree/blob/main/docs/and-or-queries.md).
 - Projection positions are fractions: a new node gets the mediant (a+c)/(b+d) of its neighbors, so normally no other node moves. Only rare alternating insertion patterns trigger a local renumbering. Tree depth and width are unbounded. `t.Q1.index(v)` returns a position as a `Fraction`.
 
 ## Tests
@@ -78,14 +83,21 @@ Every operation is checked against a brute-force parent/children model on random
 
 ## Benchmarks
 
+The benchmarks come with the package, so you can measure on your own machine:
+
 ```
-python benchmarks/bench.py            # trees of 10,000 and 100,000 nodes
-python benchmarks/bench.py --quick    # a few seconds
-python benchmarks/bench.py --dynamic  # only insertions and queries alternating
-python benchmarks/bench.py 1000000    # custom sizes
+python -m dtree.bench            # trees of 10,000 and 100,000 nodes
+python -m dtree.bench --quick    # a few seconds
+python -m dtree.bench --dynamic  # only the dynamic updates and the tree view
+python -m dtree.bench --note "idle machine"   # remark for the report
+python -m dtree.bench 1000000    # custom sizes
 ```
 
-The script prints Markdown tables: build time and renumbering counts per tree shape (random, chain, star at the root, star at an inner node, alternating worst case), list growth at either end, and timings for `can_reach`, `depth`, `delete`, `cut_n_paste` and `delete_subtree`, and comparisons with a classical parent walk: reachability by tree depth, and/or queries with constructed nodes, and dynamic updates (insertions and queries alternating). Each `DList` keeps the counters `renumber_count` and `renumber_moved`, so the same figures are available in your own code via `t.Q1` and `t.Q2`.
+In a clone of the repository, `python python/benchmarks/bench.py` runs the same code from the sources.
+
+The script prints Markdown tables: build time and renumbering counts per tree shape (random, chain, star at the root, star at an inner node, alternating worst case), list growth at either end, and timings for `can_reach`, `depth`, `delete`, `cut_n_paste` and `delete_subtree`, and comparisons with a classical parent walk: reachability by tree depth, and/or queries with constructed nodes, dynamic updates (insertions with 1 or 10 queries each, and static pre/post numbers at depths 100 and 1,000), and a tree view with expand/collapse. Each dynamic measurement is the best of three runs. Each `DList` keeps the counters `renumber_count` and `renumber_moved`, so the same figures are available in your own code via `t.Q1` and `t.Q2`.
+
+Every run also writes its tables as a Markdown report to `benchmarks/python/`—in the current directory, or at the repository root when run inside a clone— named after date and time (for example `2026-10-17_14-18.md`), with a header giving the DTree and Python versions, the operating system and the processor; `--no-save` skips it. The C# benchmarks (`dotnet run --project csharp/DTree.Tests -c Release -- bench`) write theirs to `benchmarks/csharp/`.
 
 ## Provenance
 

{dtree_encoding-1.6.0 → dtree_encoding-1.8.0}/dtree/__init__.py

@@ -3,4 +3,4 @@
 from .dtree import SINK, SOURCE, DList, DNode, DTree, UMax, UMin, VMax, VMin
 
 __all__ = ["DTree", "DNode", "DList", "VMin", "VMax", "UMin", "UMax", "SOURCE", "SINK"]
-__version__ = "1.6.0"
+__version__ = "1.8.0"

dtree_encoding-1.8.0/dtree/bench.py

@@ -0,0 +1,580 @@
+"""Performance benchmarks for DTree.
+
+Usage, after ``pip install dtree-encoding`` (or from the repository's python/ folder,
+where ``python benchmarks/bench.py`` does the same):
+
+    python -m dtree.bench                 # sizes 10,000 and 100,000
+    python -m dtree.bench 1000 1000000    # custom sizes
+    python -m dtree.bench --quick         # small sizes, a few seconds
+    python -m dtree.bench --dynamic       # only the dynamic updates and the tree view
+    python -m dtree.bench --note "idle machine after restart"   # remark for the report
+    python -m dtree.bench --no-save       # do not write a report
+
+Every run also writes its tables as a Markdown report, named after date and time
+(e.g. 2026-10-17_14-18.md), with a header giving the DTree and Python versions, the
+operating system and the processor: to benchmarks/python/ at the repository root when
+run from a clone, otherwise to benchmarks/python/ in the current directory.
+
+For each tree shape it reports the build time and how often positions in Q1
+and Q2 had to be renumbered, then times the queries and structural changes.
+Finally it compares reachability with the parent walk of classical doubly linked
+trees, for single pairs and for and/or queries (VMin, VMax, UMin, UMax), over increasing depth,
+and under dynamic updates, with insertions and queries alternating (including static
+pre/post numbers recomputed after each insertion), and in a use case: a tree view whose
+nodes are inserted, collapsed and expanded while rows are shown.
+Timings depend on the machine; the renumbering counts do not.
+"""
+
+import argparse
+import datetime
+import io
+import os
+import platform
+import random
+import sys
+import time
+
+import dtree
+from dtree import SINK, SOURCE, DList, DTree
+
+
+def _base_dir():
+    """The repository root when run from a clone, otherwise the current directory."""
+    root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    if os.path.isdir(os.path.join(root, "csharp")) and os.path.isdir(os.path.join(root, "python")):
+        return root
+    return os.getcwd()
+
+
+REPO = _base_dir()
+REPORTS = os.path.join(REPO, "benchmarks", "python")
+
+
+class _Tee(io.TextIOBase):
+    """Writes to the console and keeps a copy for the report."""
+
+    def __init__(self, console):
+        self.console, self.copy = console, io.StringIO()
+
+    def write(self, text):
+        self.console.write(text)
+        self.console.flush()
+        self.copy.write(text)
+        return len(text)
+
+    def flush(self):
+        self.console.flush()
+
+
+def _processor():
+    name = platform.processor() or platform.machine()
+    try:  # Linux: the model name is more telling than the architecture
+        with open("/proc/cpuinfo", encoding="utf-8") as fh:
+            for line in fh:
+                if line.startswith("model name"):
+                    return line.split(":", 1)[1].strip()
+    except OSError:
+        pass
+    return name
+
+
+def write_report(body, started, args_text, note):
+    os.makedirs(REPORTS, exist_ok=True)
+    path = os.path.join(REPORTS, started.strftime("%Y-%m-%d_%H-%M") + ".md")
+    head = [
+        f"# DTree benchmarks, Python—{started.strftime('%Y-%m-%d %H:%M')}",
+        "",
+        f"- DTree {dtree.__version__}, Python {sys.version.split()[0]} ({platform.python_implementation()})",
+        f"- {platform.system()} {platform.release()} ({platform.platform()})",
+        f"- Processor: {_processor()}, {os.cpu_count()} logical cores",
+        f"- Command: `python -m dtree.bench{(' ' + args_text) if args_text else ''}`",
+    ]
+    if note:
+        head.append(f"- Note: {note}")
+    lines = body.splitlines()
+    if lines and lines[0].startswith("DTree benchmarks"):
+        lines = lines[1:]             # the console title is replaced by the header above
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write("\n".join(head) + "\n" + "\n".join(lines).rstrip() + "\n")
+    return path
+
+SHAPES = {
+    # name: function(i, names, rnd) -> parent of the new node n{i}
+    "random": lambda i, names, rnd: rnd.choice(names),
+    "chain": lambda i, names, rnd: names[-1],
+    "star (root)": lambda i, names, rnd: "n0",
+    "star (inner node)": lambda i, names, rnd: "n1",
+    # worst case for rational positions: always the newer half-gap, alternating sides
+    "alternating": lambda i, names, rnd: f"n{2 * ((i - 1) // 2)}",
+    # a chain of 3,000, then new leaves under the spine nodes from the top down, repeatedly:
+    # finding the end of a subtree by walking down the last children would be O(depth) here
+    "top-down comb": lambda i, names, rnd: names[-1] if i < 3000 else f"n{(i - 3000) % 3000}",
+}
+
+
+def build(shape, n, seed=1):
+    rnd = random.Random(seed)
+    t, names = DTree("B"), ["n0"]
+    pick = SHAPES[shape]
+    start = time.perf_counter()
+    for i in range(1, n):
+        if shape == "star (inner node)" and i <= 2:
+            parent = "n0"  # n1 and n2 under the root, so n1 has a right neighbor
+        else:
+            parent = pick(i, names, rnd)
+        t.insert(parent, f"n{i}")
+        names.append(f"n{i}")
+    return t, names, time.perf_counter() - start
+
+
+def stats(q):
+    return q.renumber_count, q.renumber_moved
+
+
+def row(*cells):
+    print("| " + " | ".join(str(c) for c in cells) + " |")
+
+
+def bench_build(sizes):
+    print("\n### Building trees\n")
+    row("shape", "nodes", "time [s]", "renumberings Q1 / Q2", "positions moved per insertion")
+    row("---", "---:", "---:", "---:", "---:")
+    for shape in SHAPES:
+        for n in sizes:
+            t, _, dt = build(shape, n)
+            c1, m1 = stats(t.Q1)
+            c2, m2 = stats(t.Q2)
+            row(shape, f"{n:,}", f"{dt:.2f}", f"{c1:,} / {c2:,}", f"{(m1 + m2) / (2 * n):.2f}")
+
+
+def bench_lists(sizes):
+    print("\n### Growing a single list (DList)\n")
+    row("pattern", "nodes", "time [s]", "renumberings")
+    row("---", "---:", "---:", "---:")
+    for pattern in ("append", "prepend", "alternate"):
+        for n in sizes:
+            q = DList("Q")
+            start = time.perf_counter()
+            for i in range(n):
+                right = pattern == "append" or (pattern == "alternate" and i % 2)
+                if right:
+                    q.insert_before(f"v{i}", SINK)
+                else:
+                    q.insert_after(f"v{i}", SOURCE)
+            row(pattern, f"{n:,}", f"{time.perf_counter() - start:.2f}", f"{q.renumber_count:,}")
+
+
+def bench_operations(n, queries=1_000_000):
+    print(f"\n### Queries and changes on a random tree of {n:,} nodes\n")
+    row("operation", "count", "time [s]", "per operation [µs]")
+    row("---", "---:", "---:", "---:")
+    rnd = random.Random(2)
+
+    def timed(name, count, fn):
+        start = time.perf_counter()
+        fn()
+        dt = time.perf_counter() - start
+        row(name, f"{count:,}", f"{dt:.2f}", f"{dt / count * 1e6:.1f}")
+
+    t, names, _ = build("random", n)
+    pairs = [(rnd.choice(names), rnd.choice(names)) for _ in range(queries)]
+    timed("can_reach (names)", queries, lambda: sum(t.can_reach(u, v) for u, v in pairs))
+    handles = [(t.get_node(u), t.get_node(v)) for u, v in pairs]
+    timed("can_reach (handles)", queries, lambda: sum(t.can_reach(u, v) for u, v in handles))
+    timed("depth", len(names), lambda: sum(t.depth(v) for v in names))
+
+    k = max(1, n // 10)
+    t, names, _ = build("random", n)
+    victims = rnd.sample(names[1:], k)
+    timed("delete", k, lambda: [t.delete(v) for v in victims])
+
+    t, names, _ = build("random", n)
+    moves = []
+    while len(moves) < max(1, n // 100):
+        u, p = rnd.choice(names[1:]), rnd.choice(names)
+        moves.append((u, p))
+
+    def do_moves():
+        for u, p in moves:
+            if t.contains(u) and t.contains(p) and u != p and not t.can_reach(u, p):
+                t.cut_n_paste(u, p)
+
+    timed("cut_n_paste", len(moves), do_moves)
+
+    t, names, _ = build("random", n)
+    leaves = [v for v in names if t.is_leaf(v)][: max(1, n // 10)]
+    parents = list({t.get_parent(v) for v in leaves if t.get_parent(v)})
+    timed("delete_subtree", len(parents), lambda: [t.delete_subtree(v) for v in parents if t.contains(v) and not t.is_root(v)])
+
+
+def build_with_depth(n, depth, seed=1):
+    """A spine (chain) of `depth` nodes; all other nodes hang at random under spine nodes."""
+    rnd = random.Random(seed)
+    t, names = DTree("D"), ["n0"]
+    for i in range(1, n):
+        if i < depth:
+            parent = names[-1]                       # extend the spine
+        else:
+            parent = names[rnd.randrange(min(depth, len(names)))]
+        t.insert(parent, f"n{i}")
+        names.append(f"n{i}")
+    return t, names
+
+
+def parent_walk(parent, u, v):
+    """What classical doubly linked trees do: climb from v towards the root, looking for u."""
+    w = parent.get(v)
+    while w is not None:
+        if w == u:
+            return True
+        w = parent.get(w)
+    return False
+
+
+def ancestors_in(parent, v, members):
+    """Climb once from v towards the root and count the ancestors of v that lie in members."""
+    hits, w = 0, parent.get(v)
+    while w is not None:
+        if w in members:
+            hits += 1
+        w = parent.get(w)
+    return hits
+
+
+def bench_depth(n, depths, queries):
+    print(f"\n### Reachability by depth: DTree vs parent walk ({n:,} nodes, {queries:,} random pairs)\n")
+    row("depth", "DTree [µs]", "parent walk [µs]", "factor")
+    row("---:", "---:", "---:", "---:")
+    for depth in depths:
+        t, names = build_with_depth(n, depth)
+        parent = t._parent
+        rnd = random.Random(2)
+        pairs = [(rnd.choice(names), rnd.choice(names)) for _ in range(queries)]
+        start = time.perf_counter()
+        a = [t.can_reach(u, v) for u, v in pairs]
+        d = time.perf_counter() - start
+        start = time.perf_counter()
+        b = [parent_walk(parent, u, v) for u, v in pairs]
+        w = time.perf_counter() - start
+        assert a == b
+        row(f"{depth:,}", f"{d / queries * 1e6:.2f}", f"{w / queries * 1e6:.2f}", factor(w, d))
+
+
+def bench_sets(n, depths, k, queries):
+    print(f"\n### And/or queries: constructed nodes vs parent walk ({n:,} nodes, set of {k:,} nodes, {queries:,} query nodes)\n")
+    row("depth", "question", "DTree [µs]", "parent walk [µs]", "factor")
+    row("---:", "---", "---:", "---:", "---:")
+    for depth in depths:
+        t, names = build_with_depth(n, depth)
+        parent = t._parent
+        rnd = random.Random(4)
+        S = rnd.sample(names, k)
+        U = [rnd.choice(names) for _ in range(queries)]
+        start = time.perf_counter()
+        vmin, vmax, umin, umax = t.vmin(S), t.vmax(S), t.umin(S), t.umax(S)
+        build = time.perf_counter() - start
+        members = set(S)
+        # "reaches": climb from every member looking for u. "reached by": climb once from u,
+        # looking each ancestor up in a hash set of the members (the best a parent walk can do).
+        for name, v_q, walk_q in (
+            ("reaches all", vmin.reaches_all, lambda u: all(parent_walk(parent, u, v) for v in S)),
+            ("reaches some", vmax.reaches_some, lambda u: any(parent_walk(parent, u, v) for v in S)),
+            ("reached by all", umax.reached_by_all, lambda u: ancestors_in(parent, u, members) == len(members)),
+            ("reached by some", umin.reached_by_some, lambda u: ancestors_in(parent, u, members) > 0),
+        ):
+            start = time.perf_counter()
+            a = [v_q(u) for u in U]
+            d = time.perf_counter() - start
+            start = time.perf_counter()
+            b = [walk_q(u) for u in U]
+            w = time.perf_counter() - start
+            assert a == b, name
+            row(f"{depth:,}", name, f"{d / queries * 1e6:.2f}", f"{w / queries * 1e6:.1f}", factor(w, d))
+    print(f"\n(Building VMin, VMax, UMin and UMax for {k:,} nodes: {build * 1e3:.1f} ms, once per set.)")
+
+
+def factor(slow, fast):
+    return f"{slow / fast:.1f}×" if slow < 10 * fast else f"{slow / fast:,.0f}×"
+
+
+def dynamic_workload(n, depth, queries_per_insert, seed=5):
+    """The same sequence for every contender: insertions (a spine of `depth` nodes, the
+    others attached at random to spine nodes) with random queries among the nodes present."""
+    rnd = random.Random(seed)
+    steps = []
+    for i in range(1, n):
+        parent = i - 1 if i < depth else rnd.randrange(min(depth, i))
+        qs = [(rnd.randrange(i + 1), rnd.randrange(i + 1)) for _ in range(queries_per_insert)]
+        steps.append((parent, i, qs))
+    return steps
+
+
+def run_dtree(steps):
+    """DTree with node handles (insert returns the new node's handle)."""
+    t, answers = DTree("D"), []
+    nodes = [None] * (len(steps) + 1)
+    for p, c, qs in steps:
+        if c == 1:
+            nodes[1] = t.insert("n0", "n1")
+            nodes[0] = t.get_node("n0")
+        else:
+            nodes[c] = t.insert(nodes[p], f"n{c}")
+        for u, v in qs:
+            answers.append(t.can_reach(nodes[u], nodes[v]))
+    return answers
+
+
+def run_parent_walk(steps):
+    parent, answers = {}, []
+    for p, c, qs in steps:
+        parent[c] = p
+        for u, v in qs:
+            answers.append(parent_walk(parent, u, v))
+    return answers
+
+
+def run_static_numbers(steps):
+    """Pre- and post-order numbers from a traversal, recomputed before a query whenever the
+    tree has changed: O(1) queries, but every insertion invalidates all numbers."""
+    children, answers = {}, []
+    pre = post = None
+    for p, c, qs in steps:
+        children.setdefault(p, []).append(c)
+        pre = None                                     # the insertion invalidates the numbers
+        for u, v in qs:
+            if pre is None:
+                pre, post, clock = {}, {}, 0
+                stack = [(0, False)]
+                while stack:
+                    x, done = stack.pop()
+                    if done:
+                        post[x] = clock
+                        clock += 1
+                        continue
+                    pre[x] = clock
+                    clock += 1
+                    stack.append((x, True))
+                    stack.extend((k, False) for k in reversed(children.get(x, ())))
+            answers.append(pre[u] < pre[v] and post[v] < post[u])
+    return answers
+
+
+def timed(run, steps):
+    start = time.perf_counter()
+    answers = run(steps)
+    return time.perf_counter() - start, answers
+
+
+def best(run, steps):
+    """Best of three runs, or a single run if it takes over two seconds (noise is small then)."""
+    sec, answers = timed(run, steps)
+    if sec < 2:
+        for _ in range(2):
+            sec = min(sec, timed(run, steps)[0])
+    return sec, answers
+
+
+def bench_dynamic(n, depths, static_sizes, static_depths=(100, 1_000)):
+    timed(run_dtree, dynamic_workload(1_000, 10, 1))                 # warm-up
+    timed(run_parent_walk, dynamic_workload(1_000, 10, 1))
+    print(f"\n### Dynamic updates: insertions and queries alternating ({n:,} nodes)\n")
+    print("A step is one insertion followed by 1 or 10 queries between random nodes present at "
+          "that moment; µs per step, best of three runs.\n")
+    row("depth", "DTree, 1 query", "parent walk, 1 query", "factor",
+        "DTree, 10 queries", "parent walk, 10 queries", "factor")
+    row("---:", "---:", "---:", "---:", "---:", "---:", "---:")
+    for depth in depths:
+        cells = [f"{depth:,}"]
+        for q in (1, 10):
+            steps = dynamic_workload(n, depth, q)
+            d, a = best(run_dtree, steps)
+            w, b = best(run_parent_walk, steps)
+            assert a == b
+            cells += [f"{d / len(steps) * 1e6:.2f}", f"{w / len(steps) * 1e6:.2f}", factor(w, d)]
+        row(*cells)
+    print("\n### Dynamic updates with static pre/post numbers, recomputed after each insertion "
+          "(1 query per insertion)\n")
+    print("The tree keeps the given depth as it grows: more nodes make it wider, not deeper. "
+          "Total time in ms.\n")
+    row("depth", "nodes", "DTree [ms]", "parent walk [ms]", "static numbers [ms]")
+    row("---:", "---:", "---:", "---:", "---:")
+    for depth in static_depths:
+        for m in static_sizes:
+            steps = dynamic_workload(m, depth, 1)
+            d, a = best(run_dtree, steps)
+            w, b = best(run_parent_walk, steps)
+            r, c = timed(run_static_numbers, steps)
+            assert a == b == c
+            row(f"{depth:,}", f"{m:,}", f"{d * 1e3:,.1f}", f"{w * 1e3:,.1f}", f"{r * 1e3:,.0f}")
+
+
+# -- use case: a tree view with expand/collapse --------------------------------------------
+
+def tree_view_workload(n, depth, steps, seed=6):
+    """Changes to a tree built by build_with_depth(n, depth): each step either inserts a leaf
+    under a random spine node or toggles (collapses or expands) a random spine node, and then
+    names a random node v whose row is to be shown."""
+    rnd = random.Random(seed)
+    ops, size = [], n
+    for _ in range(steps):
+        if rnd.random() < 0.5:
+            op = ("insert", f"n{rnd.randrange(depth)}", f"n{size}")
+            size += 1
+        else:
+            op = ("toggle", f"n{rnd.randrange(depth)}", None)
+        ops.append(op + (f"n{rnd.randrange(size)}",))
+    return ops
+
+
+def tree_view_dtree(t, ops, rows):
+    """DTree: the collapsed nodes are one UMin. The visible row that contains v is
+    collapsed.covering(v) (v itself if None); the rows below it follow Q1, jumping over the
+    subtree of every collapsed node with subtree_last."""
+    collapsed, out = t.umin(), []
+    nxt, last = t.next_in_q1, t.subtree_last
+    for kind, a, b, v in ops:
+        if kind == "insert":
+            t.insert(a, b)
+        elif a in collapsed:
+            collapsed.discard(a)
+        else:
+            collapsed.add(a)
+        x = collapsed.covering(v) or v
+        shown = [x]
+        while len(shown) < rows:
+            if x in collapsed:
+                x = last(x)
+            x = nxt(x)
+            if x is None:
+                break
+            shown.append(x)
+        out.append(shown)
+    return out
+
+
+def tree_view_walk(tree, ops, rows):
+    """Classical tree model: parent link, child list and next-sibling link per node, and a set of
+    collapsed nodes. The visible row that contains v is its topmost collapsed ancestor (one climb
+    to the root); the next row is the first child of an expanded node, otherwise the next sibling
+    of the node or of its nearest ancestor that has one."""
+    parent, kids, nsib = tree
+    collapsed, out = set(), []
+    for kind, a, b, v in ops:
+        if kind == "insert":
+            parent[b] = a
+            ks = kids.setdefault(a, [])
+            if ks:
+                nsib[ks[-1]] = b
+            ks.append(b)
+        elif a in collapsed:
+            collapsed.discard(a)
+        else:
+            collapsed.add(a)
+        top, w = None, parent[v]
+        while w is not None:
+            if w in collapsed:
+                top = w
+            w = parent[w]
+        x = top or v
+        shown = [x]
+        while len(shown) < rows:
+            ks = kids.get(x)
+            if ks and x not in collapsed:
+                x = ks[0]
+            else:
+                while x is not None and x not in nsib:
+                    x = parent[x]
+                if x is None:
+                    break
+                x = nsib[x]
+            shown.append(x)
+        out.append(shown)
+    return out
+
+
+def classical_copy(t):
+    parent, kids, nsib = {}, {}, {}
+    for v in t.q1:
+        parent[v] = t.get_parent(v)
+        ks = t.children(v)
+        if ks:
+            kids[v] = ks
+            nsib.update(zip(ks, ks[1:]))
+    return parent, kids, nsib
+
+
+def bench_tree_view(n, depths, steps, rows=20):
+    print(f"\n### Use case: tree view with expand/collapse ({n:,} nodes, {steps:,} steps)\n")
+    print("Each step changes the tree (inserts a leaf or collapses/expands a node, half and half), "
+          f"then shows a random node: it finds the visible row that contains it and lists the {rows} "
+          "visible rows from there. µs per step, best of three runs.\n")
+    row("depth", "DTree [µs per step]", "parent walk [µs per step]", "factor")
+    row("---:", "---:", "---:", "---:")
+    for depth in depths:
+        ops = tree_view_workload(n, depth, steps)
+        t, _ = build_with_depth(n, depth)
+        base = classical_copy(t)
+        d = w = float("inf")
+        for _ in range(3):
+            t, _ = build_with_depth(n, depth)
+            sec, a = timed(lambda o: tree_view_dtree(t, o, rows), ops)
+            d = min(d, sec)
+            tree = ({**base[0]}, {k: list(v) for k, v in base[1].items()}, {**base[2]})
+            sec, b = timed(lambda o: tree_view_walk(tree, o, rows), ops)
+            w = min(w, sec)
+            assert a == b
+        row(f"{depth:,}", f"{d / steps * 1e6:.1f}", f"{w / steps * 1e6:.1f}", factor(w, d))
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("sizes", nargs="*", type=int, help="tree sizes (default: 10000 100000)")
+    ap.add_argument("--quick", action="store_true", help="small sizes for a fast check")
+    ap.add_argument("--dynamic", action="store_true", help="only the dynamic updates and the tree view")
+    ap.add_argument("--note", default="", help="remark written into the report (e.g. machine state)")
+    ap.add_argument("--no-save", action="store_true", help="do not write a Markdown report")
+    args = ap.parse_args()
+    started = datetime.datetime.now()
+    tee = None
+    if not args.no_save:
+        tee = _Tee(sys.stdout)
+        sys.stdout = tee
+    try:
+        run(args)
+    finally:
+        if tee is not None:
+            sys.stdout = tee.console
+            shown = " ".join(f'"{a}"' if " " in a else a for a in sys.argv[1:])
+            path = write_report(tee.copy.getvalue(), started, shown, args.note)
+            print(f"\nReport written to {os.path.relpath(path, REPO)}")
+
+
+def run(args):
+    if args.dynamic:
+        print(f"DTree benchmarks, Python {sys.version.split()[0]}")
+        if args.quick:
+            bench_dynamic(5_000, [10, 100, 1_000], [500, 1_000, 2_000])
+            bench_tree_view(5_000, [10, 100, 1_000], 1_000)
+        else:
+            bench_dynamic(20_000, [10, 100, 1_000, 10_000], [1_000, 2_000, 5_000])
+            bench_tree_view(20_000, [10, 100, 1_000, 10_000], 5_000)
+        return
+    sizes = [1_000, 10_000] if args.quick else (args.sizes or [10_000, 100_000])
+    print(f"DTree benchmarks, Python {sys.version.split()[0]}")
+    bench_build(sizes)
+    bench_lists(sizes)
+    bench_operations(max(sizes), queries=100_000 if args.quick else 1_000_000)
+    if args.quick:
+        bench_depth(10_000, [10, 100, 1_000, 10_000], 20_000)
+        bench_sets(10_000, [10, 100, 1_000], 100, 200)
+        bench_dynamic(5_000, [10, 100, 1_000], [500, 1_000, 2_000])
+        bench_tree_view(5_000, [10, 100, 1_000], 1_000)
+    else:
+        bench_depth(100_000, [10, 100, 1_000, 10_000, 100_000], 20_000)
+        bench_sets(100_000, [10, 100, 1_000, 10_000], 1_000, 200)
+        bench_dynamic(20_000, [10, 100, 1_000, 10_000], [1_000, 2_000, 5_000])
+        bench_tree_view(20_000, [10, 100, 1_000, 10_000], 5_000)
+
+
+if __name__ == "__main__":
+    main()

{dtree_encoding-1.6.0 → dtree_encoding-1.8.0}/dtree/dtree.py

@@ -351,7 +351,12 @@ class DTree:
     # -- construction ------------------------------------------------------
     @classmethod
     def from_file(cls, path: str, tree_id: Optional[str] = None) -> "DTree":
-        """Read the ``parent: child1; child2`` format used by the .csx examples."""
+        """Read the format used by the .csx examples.
+
+        ``parent: child1; child2`` adds children as last children of ``parent``;
+        ``sibling > child1; child2`` inserts them as siblings directly after ``sibling``
+        (in that order), ``sibling < child1; child2`` directly before it.
+        """
         import os
 
         tree = cls(tree_id or os.path.splitext(os.path.basename(path))[0])
@@ -362,12 +367,27 @@ class DTree:
                     continue
                 if line.startswith("@@"):
                     break
-                parent, _, rest = line.partition(":")
-                for child in (c.strip() for c in rest.split(";")):
-                    if child:
-                        tree.insert(parent.strip(), child)
+                tree.add_line(line)
         return tree
 
+    def add_line(self, line: str) -> List[DNode]:
+        """Apply one line of the description format (see from_file); returns the new handles."""
+        at = min((i for i in (line.find(":"), line.find(">"), line.find("<")) if i >= 0), default=-1)
+        if at < 0:
+            raise ValueError(f"no ':', '>' or '<' in {line!r}")
+        op, anchor = line[at], line[:at].strip()
+        children = [c.strip() for c in line[at + 1:].split(";") if c.strip()]
+        added = []
+        for child in children:
+            if op == ":":
+                added.append(self.insert(anchor, child))
+            elif op == ">":
+                added.append(self.insert_after(anchor, child))
+                anchor = child                       # the next one goes after this one
+            else:
+                added.append(self.insert_before(anchor, child))
+        return added
+
     def insert(self, parent, child: str) -> DNode:
         """Add the edge parent -> child and return the handle of ``child``.
 
@@ -387,6 +407,56 @@ class DTree:
         self.edge_log.append(f"({p.name}, {child})")
         return n
 
+    def insert_after(self, sibling, child: str) -> DNode:
+        """Insert ``child`` as a sibling directly after ``sibling`` (same parent) and return its
+        handle. In Q1 it goes after the end of the sibling's subtree, in Q2 directly before the
+        sibling; no other node moves. The root has no siblings."""
+        s = self._sibling(sibling, child)
+        p = s.up
+        i = p.kids.index(s)
+        w = self._subtree_last_node(s)
+        n = self._link_node(child, p, i + 1, w.c1, s.c2.prev)
+        if i + 1 == len(p.kids) - 1:
+            p.last = n                                  # n is now the last node of p's subtree
+        self.edge_log.append(f"({s.name} > {child})")
+        return n
+
+    def insert_before(self, sibling, child: str) -> DNode:
+        """Insert ``child`` as a sibling directly before ``sibling`` (same parent) and return its
+        handle. In Q1 it goes directly before the sibling, in Q2 after the end of the sibling's
+        subtree there (directly before the previous sibling; for a first child, after the end
+        of the parent's subtree in Q2, found by following first children); no other node moves."""
+        s = self._sibling(sibling, child)
+        p = s.up
+        i = p.kids.index(s)
+        q2_after = p.kids[i - 1].c2.prev if i > 0 else self._subtree_first_last_q2(s).c2
+        n = self._link_node(child, p, i, s.c1.prev, q2_after)
+        self.edge_log.append(f"({s.name} < {child})")
+        return n
+
+    def _sibling(self, sibling, child: str) -> DNode:
+        if child in (SOURCE, SINK):
+            raise ValueError("SOURCE/SINK markers cannot be tree nodes")
+        s = self._node(sibling)
+        if s.up is None:
+            raise ValueError("the root has no siblings")
+        if child in self._nodes:
+            raise ValueError(f"child {child!r} is already in the tree")
+        return s
+
+    def _link_node(self, name: str, p: DNode, index: int, q1_after, q2_after) -> DNode:
+        """Create a child of p at position ``index`` among p's children, linked after the given cells."""
+        n = DNode(name, self)
+        c1, c2 = self._q1._new(name), self._q2._new(name)
+        self._q2._link_after(c2, q2_after)
+        self._q1._link_after(c1, q1_after)
+        n.up = p
+        p.kids.insert(index, n)
+        c1.node = c2.node = n
+        n.c1, n.c2 = c1, c2
+        self._nodes[name] = n
+        return n
+
     def _new_node(self, name: str, p: Optional[DNode]) -> DNode:
         n = DNode(name, self)
         q1, q2 = self._q1, self._q2
@@ -466,6 +536,12 @@ class DTree:
             w = w.kids[0]
         return w
 
+    def next_in_q1(self, node) -> Optional[str]:
+        """The node after ``node`` in Q1, as a name, or None after the last node. Q1 is the
+        display order of a tree view (parents before children, siblings in insertion order)."""
+        c = self._node(node).c1.next
+        return c.node.name if c is not None and c.node is not None else None
+
     def subtree_last(self, node):
         """Last node of the subtree of ``node`` in Q1, as a name (the subtree is the block from
         ``node`` to it). Usually O(1) when asked again for the same node."""
@@ -785,7 +861,8 @@ class _VNode:
     the minimal (or maximal) index there; the two may be different nodes, so the constructed
     node usually corresponds to no real node. Insertions and renumbering keep the order of
     existing nodes, so it stays valid while the tree grows. After a deletion or a cut_n_paste it is
-    recomputed from the remaining members on its next use.
+    recomputed from the remaining members on its next use. Members are added with ``add`` and
+    removed with ``discard``.
     """
 
     _lowest = True  # VMin keeps the leftmost member, VMax the rightmost
@@ -829,9 +906,49 @@ class _VNode:
         self._added(node)
         return self
 
+    def discard(self, node) -> "_VNode":
+        """Remove a node (name or handle) from the set; no error if it is not a member.
+
+        O(log k) to find it plus the list removal; if it held an index (the minimal or
+        maximal position in Q1 or Q2), the index nodes are recomputed in O(k). Returns the
+        constructed node itself. Typical use: expanding a node in a tree view, after it was
+        added to the set of collapsed nodes.
+        """
+        node = self._t._name(node)
+        self._check()
+        if node not in self._seen:
+            return self
+        self._seen.discard(node)
+        q1, m = self._t._q1, self._members
+        lo, hi = 0, len(m)                  # members are sorted by Q1 order
+        while lo < hi:
+            mid = (lo + hi) // 2
+            if q1.precedes(m[mid], node):
+                lo = mid + 1
+            else:
+                hi = mid
+        del m[lo]
+        if node == self._c1 or node == self._c2:
+            t = self._t
+            self._c1 = self._c2 = None
+            for v in self._members:
+                if self._better(t._q1, v, self._c1):
+                    self._c1 = v
+                if self._better(t._q2, v, self._c2):
+                    self._c2 = v
+        self._discarded(node)
+        return self
+
+    def __contains__(self, node) -> bool:
+        self._check()
+        return self._t._name(node) in self._seen
+
     def _added(self, node: str) -> None:
         """Hook for subclasses that keep more than the index nodes."""
 
+    def _discarded(self, node: str) -> None:
+        """Hook for subclasses that keep more than the index nodes."""
+
     def _rebuilt(self) -> None:
         """Hook for subclasses that keep more than the index nodes."""
 
@@ -989,6 +1106,10 @@ class UMin(_VNode):
             del m[i]                     # node is above them: they are no longer topmost
         m.insert(i, node)
 
+    def _discarded(self, node: str) -> None:
+        if node in self._tops:           # members it covered may become topmost
+            self._rebuilt()
+
     def _rebuilt(self) -> None:
         self._tops = []
         t = self._t
@@ -1011,3 +1132,18 @@ class UMin(_VNode):
         if not self.may_be_reached_by_some(v):
             return False
         return self._covered(v)
+
+    def covering(self, v) -> Optional[str]:
+        """The topmost member of the set that reaches v, or None if no member does (O(log k)).
+
+        With the collapsed nodes of a tree view as a UMin, this is the visible row that
+        contains v: None means v itself is visible.
+        """
+        v = self._t._name(v)
+        self._check()
+        if not self._t.contains(v):
+            return None
+        i = self._last_top_before(v)
+        if i > 0 and self._t.can_reach(self._tops[i - 1], v):
+            return self._tops[i - 1]
+        return None

{dtree_encoding-1.6.0 → dtree_encoding-1.8.0}/dtree_encoding.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dtree-encoding
-Version: 1.6.0
+Version: 1.8.0
 Summary: DTree: incremental encoding of the topology of directed trees by two projections (Q1, Q2): O(1) reachability, and/or queries on the topology of the tree, dynamic (incremental) updates
 Author-email: Enis Olgac <enis@digraphs.info>
 License: MIT
@@ -59,7 +59,9 @@ t = DTree.from_file("Test.csx")   # e.g. examples/Test.csx from the repository
 | C# (docs) | Python |
 |---|---|
 | `DTree(id)` | `DTree(tree_id="P1")` |
-| `Insert(parent, child)` | `insert(parent, child)` |
+| `Insert(parent, child)` | `insert(parent, child)` (last child) |
+| `InsertAfter`, `InsertBefore` | `insert_after(sibling, child)`, `insert_before(sibling, child)` |
+| `AddLine` | `add_line(line)` (`p: c`, `s > c`, `s < c`; also in `from_file`) |
 | `Contains(node)` | `contains(node)` / `node in t` |
 | `GetParent(node)` | `get_parent(node)` (`None` for the root) |
 | `CutNPaste(u, p)` | `cut_n_paste(subtree_root, new_parent)` |
@@ -75,9 +77,12 @@ t = DTree.from_file("Test.csx")   # e.g. examples/Test.csx from the repository
 | `PathToRoot`, `RootToPath` | `path_to_root`, `root_to_path` (plus `path(u, v)`) |
 | `GetNode`, `TryGetNode`, `DNode` | `get_node`, `try_get_node`, `DNode` (node handles; `insert` returns one) |
 | `SubtreeLast` | `subtree_last` (last node of a subtree in Q1) |
+| `NextInQ1` | `next_in_q1` (next node in Q1, the display order; `None` at the end) |
 | `VMin`, `VMax`, `UMin`, `UMax` (of nodes) | `vmin`, `vmax`, `umin`, `umax` |
 | `ReachesAll`, `MayReachSome`, `ReachesSome` | `reaches_all`, `may_reach_some`, `reaches_some` |
 | `ReachedByAll`, `MayBeReachedBySome`, `ReachedBySome` | `reached_by_all`, `may_be_reached_by_some`, `reached_by_some` |
+| `Add`, `Discard`, `Contains` (of a constructed node) | `add`, `discard`, `node in s` |
+| `UMin.Covering` | `covering` (topmost member that reaches a node; `None` if none) |
 
 ## Semantics
 
@@ -88,7 +93,7 @@ t = DTree.from_file("Test.csx")   # e.g. examples/Test.csx from the repository
 - `delete(v)` re-attaches v's children to v's parent, in v's place among its siblings.
 - `delete_subtree(v)` removes v with all its descendants and returns them in Q1 order.
 - `cut_n_paste(u, p)` moves the subtree rooted at u under p as p's last child; p must not lie inside u's subtree.
-- And/or queries on the topology: the constructed nodes `vmin(S)`, `vmax(S)` (S as target) and `umin(S)`, `umax(S)` (S as source) take the minimum or maximum of each index over S, separately in Q1 and Q2. `reaches_all` and `reached_by_all` are exact O(1) tests; `may_reach_some` and `may_be_reached_by_some` are only filters, and `reaches_some` and `reached_by_some` are exact in O(log k). A constructed node stays valid under insertions and is recomputed automatically after `delete`, `delete_subtree` or `cut_n_paste`. See [and/or queries on the topology](https://github.com/EnisOlgac/DTree/blob/main/docs/and-or-queries.md).
+- And/or queries on the topology: the constructed nodes `vmin(S)`, `vmax(S)` (S as target) and `umin(S)`, `umax(S)` (S as source) take the minimum or maximum of each index over S, separately in Q1 and Q2. `reaches_all` and `reached_by_all` are exact O(1) tests; `may_reach_some` and `may_be_reached_by_some` are only filters, and `reaches_some` and `reached_by_some` are exact in O(log k). Members are added with `add` and removed with `discard`. A constructed node stays valid under insertions and is recomputed automatically after `delete`, `delete_subtree` or `cut_n_paste`. See [and/or queries on the topology](https://github.com/EnisOlgac/DTree/blob/main/docs/and-or-queries.md).
 - Projection positions are fractions: a new node gets the mediant (a+c)/(b+d) of its neighbors, so normally no other node moves. Only rare alternating insertion patterns trigger a local renumbering. Tree depth and width are unbounded. `t.Q1.index(v)` returns a position as a `Fraction`.
 
 ## Tests
@@ -101,14 +106,21 @@ Every operation is checked against a brute-force parent/children model on random
 
 ## Benchmarks
 
+The benchmarks come with the package, so you can measure on your own machine:
+
 ```
-python benchmarks/bench.py            # trees of 10,000 and 100,000 nodes
-python benchmarks/bench.py --quick    # a few seconds
-python benchmarks/bench.py --dynamic  # only insertions and queries alternating
-python benchmarks/bench.py 1000000    # custom sizes
+python -m dtree.bench            # trees of 10,000 and 100,000 nodes
+python -m dtree.bench --quick    # a few seconds
+python -m dtree.bench --dynamic  # only the dynamic updates and the tree view
+python -m dtree.bench --note "idle machine"   # remark for the report
+python -m dtree.bench 1000000    # custom sizes
 ```
 
-The script prints Markdown tables: build time and renumbering counts per tree shape (random, chain, star at the root, star at an inner node, alternating worst case), list growth at either end, and timings for `can_reach`, `depth`, `delete`, `cut_n_paste` and `delete_subtree`, and comparisons with a classical parent walk: reachability by tree depth, and/or queries with constructed nodes, and dynamic updates (insertions and queries alternating). Each `DList` keeps the counters `renumber_count` and `renumber_moved`, so the same figures are available in your own code via `t.Q1` and `t.Q2`.
+In a clone of the repository, `python python/benchmarks/bench.py` runs the same code from the sources.
+
+The script prints Markdown tables: build time and renumbering counts per tree shape (random, chain, star at the root, star at an inner node, alternating worst case), list growth at either end, and timings for `can_reach`, `depth`, `delete`, `cut_n_paste` and `delete_subtree`, and comparisons with a classical parent walk: reachability by tree depth, and/or queries with constructed nodes, dynamic updates (insertions with 1 or 10 queries each, and static pre/post numbers at depths 100 and 1,000), and a tree view with expand/collapse. Each dynamic measurement is the best of three runs. Each `DList` keeps the counters `renumber_count` and `renumber_moved`, so the same figures are available in your own code via `t.Q1` and `t.Q2`.
+
+Every run also writes its tables as a Markdown report to `benchmarks/python/`—in the current directory, or at the repository root when run inside a clone— named after date and time (for example `2026-10-17_14-18.md`), with a header giving the DTree and Python versions, the operating system and the processor; `--no-save` skips it. The C# benchmarks (`dotnet run --project csharp/DTree.Tests -c Release -- bench`) write theirs to `benchmarks/csharp/`.
 
 ## Provenance
 

{dtree_encoding-1.6.0 → dtree_encoding-1.8.0}/dtree_encoding.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 README.md
 pyproject.toml
 dtree/__init__.py
+dtree/bench.py
 dtree/dtree.py
 dtree_encoding.egg-info/PKG-INFO
 dtree_encoding.egg-info/SOURCES.txt

{dtree_encoding-1.6.0 → dtree_encoding-1.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dtree-encoding"
-version = "1.6.0"
+version = "1.8.0"
 description = "DTree: incremental encoding of the topology of directed trees by two projections (Q1, Q2): O(1) reachability, and/or queries on the topology of the tree, dynamic (incremental) updates"
 readme = "README.md"
 requires-python = ">=3.8"

{dtree_encoding-1.6.0 → dtree_encoding-1.8.0}/tests/test_dtree.py

@@ -68,6 +68,18 @@ class Reference:
         for n in gone:
             del self.parent[n]
 
+    def insert_after(self, s, v):
+        p = self.parent[s]
+        sib = self.children[p]
+        sib.insert(sib.index(s) + 1, v)
+        self.parent[v] = p
+
+    def insert_before(self, s, v):
+        p = self.parent[s]
+        sib = self.children[p]
+        sib.insert(sib.index(s), v)
+        self.parent[v] = p
+
     def move(self, u, p):
         old = self.parent[u]
         self.children[old].remove(u)
@@ -332,6 +344,58 @@ class TestVNodes(unittest.TestCase):
                 self.check_vnodes(t, live, **v_s)
                 self.assertEqual(sorted(v_s["umin"].members), sorted(live))
 
+    def test_discard(self):
+        # random adds and discards, with inserts, deletes and moves in between
+        for seed in range(15):
+            t, ref, rnd = random_tree(60, seed)
+            v_s = dict(vmin=t.vmin(), vmax=t.vmax(), umin=t.umin(), umax=t.umax())
+            S, k = set(), 60
+            for step in range(120):
+                nodes = t.nodes
+                r = rnd.random()
+                if r < 0.35:
+                    v = rnd.choice(nodes)
+                    for x in v_s.values():
+                        x.add(v if rnd.random() < 0.5 else t.get_node(v))
+                    S.add(v)
+                elif r < 0.65 and S:
+                    v = rnd.choice(sorted(S))
+                    for x in v_s.values():
+                        x.discard(v)
+                    S.discard(v)
+                elif r < 0.8:
+                    t.insert(rnd.choice(nodes), f"x{k}")
+                    k += 1
+                elif r < 0.9 and len(nodes) > 10:
+                    v = rnd.choice(nodes[1:])
+                    t.delete(v)
+                    S.discard(v)
+                elif len(nodes) > 10:
+                    u = rnd.choice(nodes[1:])
+                    banned = set(t.subtree(u))
+                    t.cut_n_paste(u, rnd.choice([w for w in nodes if w not in banned]))
+                live = sorted(S)
+                self.check_vnodes(t, live, **v_s)
+                self.assertEqual(sorted(v_s["umin"].members), live)
+                for v in live[:3]:
+                    self.assertIn(v, v_s["vmax"])
+                for v in t.nodes:                        # topmost member that reaches v
+                    above = [a for a in t.path_to_root(v)[1:] if a in S]
+                    self.assertEqual(v_s["umin"].covering(v), above[-1] if above else None)
+        # discarding a non-member is a no-op
+        t = DTree()
+        t.insert("a", "b")
+        u = t.umin(["b"])
+        u.discard("a").discard("nobody")
+        self.assertEqual(u.members, ["b"])
+
+    def test_next_in_q1(self):
+        t, ref, rnd = random_tree(80, 7)
+        q1 = t.q1
+        for a, b in zip(q1, q1[1:] + [None]):
+            self.assertEqual(t.next_in_q1(a), b)
+            self.assertEqual(t.next_in_q1(t.get_node(a)), b)
+
     def test_incremental_add(self):
         t, ref, rnd = random_tree(100, 3)
         v_s = dict(vmin=t.vmin(), vmax=t.vmax(), umin=t.umin(), umax=t.umax())
@@ -507,6 +571,136 @@ class TestAgainstReference(unittest.TestCase):
                 check(self, t, ref)
 
 
+class TestSiblingInsert(unittest.TestCase):
+    def test_example(self):
+        t = DTree()
+        t.insert("A", "B")
+        t.insert("A", "D")
+        t.insert("B", "C")
+        t.insert_after("B", "X")       # A: B, X, D
+        t.insert_before("B", "W")      # A: W, B, X, D
+        t.insert_before("C", "C0")     # B: C0, C
+        self.assertEqual(t.children("A"), ["W", "B", "X", "D"])
+        self.assertEqual(t.children("B"), ["C0", "C"])
+        self.assertEqual(t.q1, ["A", "W", "B", "C0", "C", "X", "D"])
+        self.assertEqual(t.q2, ["A", "D", "X", "B", "C", "C0", "W"])
+        self.assertTrue(t.can_reach("A", "X") and not t.can_reach("B", "X"))
+        self.assertEqual(t.subtree_last("A"), "D")
+
+    def test_rules(self):
+        t = DTree()
+        t.insert("A", "B")
+        with self.assertRaises(ValueError):
+            t.insert_after("A", "Z")           # the root has no siblings
+        with self.assertRaises(ValueError):
+            t.insert_before("A", "Z")
+        with self.assertRaises(ValueError):
+            t.insert_after("B", "A")           # already in the tree
+        with self.assertRaises(KeyError):
+            t.insert_after("nobody", "Z")
+        n = t.insert_after(t.get_node("B"), "C")   # handles work too
+        self.assertIsInstance(n, DNode)
+        self.assertEqual(t.children("A"), ["B", "C"])
+
+    def test_example_file(self):
+        t = DTree.from_file(os.path.join(EXAMPLES, "siblings.csx"))
+        self.assertEqual(t.children("01"), ["02", "04", "06", "05"])
+        self.assertEqual(t.q1, ["01", "02", "03a", "03", "04", "06", "05"])
+        self.assertEqual(t.q2, ["01", "05", "06", "04", "02", "03", "03a"])
+
+    def test_description_lines(self):
+        t = DTree()
+        t.add_line("A: B; D")
+        t.add_line("B > X; Y")         # X after B, Y after X
+        t.add_line("D < W1; W2")       # W1 before D, W2 before D
+        t.add_line("B: C")
+        self.assertEqual(t.children("A"), ["B", "X", "Y", "W1", "W2", "D"])
+        self.assertEqual(t.children("B"), ["C"])
+
+    def test_random_mix(self):
+        # all three kinds of insertion, mixed with deletes and moves, against the reference
+        import dtree.dtree as impl
+        for budget in (impl._BUDGET, 0):
+            saved, impl._BUDGET = impl._BUDGET, budget
+            try:
+                for seed in range(12):
+                    t, ref, rnd = random_tree(20, seed)
+                    k = 0
+                    for _ in range(100):
+                        nodes = ref.nodes()
+                        inner = [n for n in nodes if n != ref.root]
+                        r = rnd.random()
+                        name = f"x{k}"
+                        if r < 0.25:
+                            p = rnd.choice(nodes)
+                            t.insert(p, name)
+                            ref.insert(p, name)
+                            k += 1
+                        elif r < 0.5 and inner:
+                            s = rnd.choice(inner)
+                            t.insert_after(s, name)
+                            ref.insert_after(s, name)
+                            k += 1
+                        elif r < 0.75 and inner:
+                            s = rnd.choice(inner)
+                            t.insert_before(s, name)
+                            ref.insert_before(s, name)
+                            k += 1
+                        elif r < 0.85 and len(inner) > 10:
+                            v = rnd.choice(inner)
+                            t.delete(v)
+                            ref.delete(v)
+                        elif len(inner) > 10:
+                            u = rnd.choice(inner)
+                            banned = set(t.subtree(u))
+                            p = rnd.choice([n for n in nodes if n not in banned])
+                            t.cut_n_paste(u, p)
+                            ref.move(u, p)
+                        check(self, t, ref)
+                        for v in rnd.sample(ref.nodes(), 3):
+                            sub_v = [w for w in ref.nodes() if w == v or v == ref.root or v in ref_ancestors(ref.parent, w)]
+                            self.assertEqual(t.subtree_last(v), [w for w in t.q1 if w in sub_v][-1])
+            finally:
+                impl._BUDGET = saved
+
+    def test_same_gap_many_times(self):
+        # repeated insertion into the same gap from both sides: positions stay strictly increasing
+        t, ref = DTree(), Reference()
+        t.insert("r", "a")
+        ref.insert("r", "a")
+        t.insert("r", "b")
+        ref.insert("r", "b")
+        left, right = "a", "b"
+        for i in range(400):
+            if i % 2:
+                t.insert_after(left, f"l{i}")
+                ref.insert_after(left, f"l{i}")
+                left = f"l{i}"
+            else:
+                t.insert_before(right, f"r{i}")
+                ref.insert_before(right, f"r{i}")
+                right = f"r{i}"
+        check(self, t, ref)
+
+    def test_constructed_nodes_stay_valid(self):
+        t, ref, rnd = random_tree(60, 3)
+        S = rnd.sample(ref.nodes(), 6)
+        um, vm = t.umin(S), t.vmax(S)
+        for i in range(60):
+            s = rnd.choice([n for n in ref.nodes() if n != ref.root])
+            if i % 2:
+                t.insert_after(s, f"y{i}")
+                ref.insert_after(s, f"y{i}")
+            else:
+                t.insert_before(s, f"y{i}")
+                ref.insert_before(s, f"y{i}")
+        for v in ref.nodes():
+            anc = set(ref_ancestors(ref.parent, v)[1:]) | ({ref.root} if v != ref.root else set())
+            self.assertEqual(um.reached_by_some(v), any(m in anc for m in S), v)
+            below = {w for w in ref.nodes() if w != v and (v == ref.root or v in ref_ancestors(ref.parent, w))}
+            self.assertEqual(vm.reaches_some(v), any(m in below for m in S), v)
+
+
 class TestNoSizeLimit(unittest.TestCase):
     def test_deep_chain(self):
         t = DTree()