digraphx 0.6__tar.gz → 0.7__tar.gz

{digraphx-0.6 → digraphx-0.7}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## Version 0.7 (2026-10-09)
+
+### Features
+- **Optional `max_iter` cap for Howard's method**: `howard` / `howard_pred` / `howard_succ` accept an optional `max_iter` (default `None` = unbounded); a set cap raises `RuntimeError` instead of looping forever on degenerate graphs. (#8669cdd)
+
+### Performance
+- **Fast-path `TinyDiGraph.add_edge`**: Lazy-slot resolution avoids unnecessary work on edge insertion. (#a7ed9c3)
+- **Pre-weighted edge list reuse**: Howard relaxation reuses the pre-weighted edge list instead of recomputing it. (#da93374)
+
+### Bug Fixes
+- **`cheat_adjlist_outer_dict` doctest**: Aligned the doctest with the lazy-sentinel behavior. (#20e7c11)
+
+### Testing & Code Quality
+- **Runtime benchmarks**: Added benchmarks for the core graph algorithms. (#0c7329a)
+- **Neg-cycle tests**: Added tests covering the `max_iter` cap. (#8669cdd)
+
+### Documentation
+- **Tunable parameter reference**: Added `tunable_parameter.md`. (#9e0639b)
+
 ## Version 0.6 (2026-09-04)
 
 ### Features

{digraphx-0.6/src/digraphx.egg-info → digraphx-0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digraphx
-Version: 0.6
+Version: 0.7
 Summary: Network Optimization Python Code
 Home-page: https://github.com/luk036/digraphx
 Author: Wai-Shing Luk

digraphx-0.7/benchmarks/test_benchmarks.py

@@ -0,0 +1,131 @@
+"""Runtime benchmarks for digraphx core algorithms.
+
+Run explicitly (they are outside the default ``testpaths`` so ``pytest`` alone
+skips them):
+
+    pytest benchmarks/ --benchmark-only
+
+Uses fixed seeds so numbers are comparable across runs and across machines.
+"""
+
+import random
+from fractions import Fraction
+
+import networkx as nx
+import pytest
+
+from digraphx.min_cycle_ratio import MinCycleRatioSolver, set_default
+from digraphx.neg_cycle import NegCycleFinder
+from digraphx.tiny_digraph import DiGraphAdapter, TinyDiGraph
+
+SEED = 1234
+SIZES = [200, 1000]
+MCR_SIZES = [50, 100]
+
+
+def weighted_graph(n: int, deg: int, seed: int = SEED) -> dict:
+    rng = random.Random(seed)
+    g: dict = {i: {} for i in range(n)}
+    for i in range(n):
+        for _ in range(deg):
+            j = rng.randrange(n)
+            if j != i:
+                g[i][j] = rng.randint(1, 9)
+    for i in range(n - 1):
+        g[i][i + 1] = 1
+    g[n - 1][0] = -n
+    return g
+
+
+def ratio_graph(n: int, deg: int, seed: int = SEED) -> DiGraphAdapter:
+    rng = random.Random(seed)
+    g = DiGraphAdapter()
+    g.add_nodes_from(range(n))
+    for i in range(n):
+        for _ in range(deg):
+            j = rng.randrange(n)
+            if j != i:
+                g.add_edge(i, j, cost=rng.randint(-5, 9), time=rng.randint(1, 5))
+    return g
+
+
+@pytest.mark.parametrize("n", SIZES)
+def test_bench_tiny_build(benchmark, n: int) -> None:
+    deg = 5
+
+    def build() -> TinyDiGraph:
+        g = TinyDiGraph()
+        g.init_nodes(n)
+        for i in range(n):
+            for j in range(1, deg + 1):
+                g.add_edge(i, (i + j) % n, weight=1)
+        return g
+
+    benchmark(build)
+
+
+@pytest.mark.parametrize("n", SIZES)
+def test_bench_adapter_build(benchmark, n: int) -> None:
+    deg = 5
+
+    def build() -> DiGraphAdapter:
+        g = DiGraphAdapter()
+        g.add_nodes_from(range(n))
+        for i in range(n):
+            for j in range(1, deg + 1):
+                g.add_edge(i, (i + j) % n, weight=1)
+        return g
+
+    benchmark(build)
+
+
+@pytest.mark.parametrize("n", SIZES)
+def test_bench_howard_negative_cycle(benchmark, n: int) -> None:
+    g = weighted_graph(n, 6)
+    finder = NegCycleFinder(g)
+
+    def run() -> None:
+        dist = {v: 0 for v in g}
+        list(finder.howard(dist, lambda e: e))
+
+    benchmark(run)
+
+
+@pytest.mark.parametrize("n", SIZES)
+def test_bench_networkx_negative_edge_cycle(benchmark, n: int) -> None:
+    g = weighted_graph(n, 6)
+    h = nx.DiGraph()
+    for u, nb in g.items():
+        h.add_node(u)
+        for v, w in nb.items():
+            h.add_edge(u, v, weight=w)
+
+    benchmark(lambda: nx.negative_edge_cycle(h, weight="weight"))
+
+
+@pytest.mark.parametrize("n", MCR_SIZES)
+def test_bench_mcr_fraction(benchmark, n: int) -> None:
+    g = ratio_graph(n, 5)
+    set_default(g, "cost", 0)
+    set_default(g, "time", 1)
+    solver = MinCycleRatioSolver(g)
+
+    def run():
+        dist = {v: Fraction(0) for v in g}
+        return solver.run(dist, Fraction(10))
+
+    benchmark(run)
+
+
+@pytest.mark.parametrize("n", MCR_SIZES)
+def test_bench_mcr_float(benchmark, n: int) -> None:
+    g = ratio_graph(n, 5)
+    set_default(g, "cost", 0)
+    set_default(g, "time", 1)
+    solver = MinCycleRatioSolver(g)
+
+    def run():
+        dist = {v: 0.0 for v in g}
+        return solver.run(dist, 10.0)
+
+    benchmark(run)

{digraphx-0.6 → digraphx-0.7}/src/digraphx/_cycle_base.py

@@ -17,6 +17,7 @@ from typing import (
     List,
     Mapping,
     MutableMapping,
+    Optional,
     Tuple,
     TypeVar,
 )
@@ -110,6 +111,57 @@ def relax_succ(
     return changed
 
 
+def prepare_edges(
+    digraph: Mapping[Node, Mapping[Node, Arc]],
+    get_weight: Callable[[Arc], Domain],
+) -> List[Tuple[Node, Node, Arc, Domain]]:
+    """Flatten the graph into ``(u, v, edge, weight)`` tuples.
+
+    ``get_weight`` is evaluated exactly once per edge.  Callers that keep the
+    ratio (and hence every edge weight) fixed for the whole search can reuse the
+    result across many relaxation passes instead of recomputing it each time.
+    """
+    return [
+        (utx, vtx, edge, get_weight(edge))
+        for utx, neighbors in digraph.items()
+        for vtx, edge in neighbors.items()
+    ]
+
+
+def relax_pred_flat(
+    edges: List[Tuple[Node, Node, Arc, Domain]],
+    dist: MutableMapping[Node, Domain],
+    update_ok: Callable[[Domain, Domain], bool],
+    pred: PointTo,
+) -> bool:
+    """Predecessor relaxation over a pre-flattened, pre-weighted edge list."""
+    changed = False
+    for utx, vtx, edge, weight in edges:
+        distance = dist[utx] + weight
+        if dist[vtx] > distance and update_ok(dist[vtx], distance):
+            dist[vtx] = distance
+            pred[vtx] = (utx, edge)
+            changed = True
+    return changed
+
+
+def relax_succ_flat(
+    edges: List[Tuple[Node, Node, Arc, Domain]],
+    dist: MutableMapping[Node, Domain],
+    update_ok: Callable[[Domain, Domain], bool],
+    succ: PointTo,
+) -> bool:
+    """Successor relaxation over a pre-flattened, pre-weighted edge list."""
+    changed = False
+    for utx, vtx, edge, weight in edges:
+        distance = dist[vtx] - weight
+        if dist[utx] < distance and update_ok(dist[utx], distance):
+            dist[utx] = distance
+            succ[utx] = (vtx, edge)
+            changed = True
+    return changed
+
+
 def cycle_list(point_to: PointTo, handle: Node) -> Cycle:
     """Reconstruct the cycle starting from ``handle`` in the point-to map.
 
@@ -157,6 +209,7 @@ def howard_search(
     point_to: PointTo,
     direction: str,
     verify: bool = True,
+    max_iter: Optional[int] = None,
 ) -> Generator[Cycle, None, None]:
     """Template Method: Howard's policy-iteration skeleton.
 
@@ -167,14 +220,34 @@ def howard_search(
     (``"pred"`` for predecessor relaxation, ``"succ"`` for successor).  When
     ``verify`` is ``True``, each candidate cycle is asserted to be negative
     before being yielded (matching the predecessor variants).
+
+    ``max_iter`` optionally caps the number of relaxation rounds.  ``None``
+    (default) means unbounded; when set and exceeded without finding a negative
+    cycle, ``RuntimeError`` is raised rather than looping forever.
     """
     point_to.clear()
     found = False
-    relax = relax_pred if direction == "pred" else relax_succ
-    while not found and relax(digraph, dist, get_weight, update_ok, point_to):
+    num_iter = 0
+    edges = prepare_edges(digraph, get_weight)
+    if direction == "pred":
+
+        def relax() -> bool:
+            return relax_pred_flat(edges, dist, update_ok, point_to)
+
+    else:
+
+        def relax() -> bool:
+            return relax_succ_flat(edges, dist, update_ok, point_to)
+
+    while not found and relax():
+        num_iter += 1
         for vtx in find_cycle(digraph, point_to):
             if verify:
                 # Safety check - verify the cycle is indeed negative
                 assert is_negative(point_to, vtx, dist, get_weight)
             found = True
             yield cycle_list(point_to, vtx)
+        if not found and max_iter is not None and num_iter >= max_iter:
+            raise RuntimeError(
+                f"howard_search did not converge within max_iter={max_iter}"
+            )

{digraphx-0.6 → digraphx-0.7}/src/digraphx/_parametric_base.py

@@ -50,11 +50,8 @@ def _run_loop(
     if not dist:  # empty graph case - return early with no cycle found
         return ratio, []
 
-    DomainType = type(next(iter(dist.values())))
-
-    # Define a weight function that calculates distance based on current ratio
     def get_weight(e: Arc) -> Domain:
-        return DomainType(omega.distance(ratio, e))
+        return omega.distance(ratio, e)
 
     # Initialize min/max ratio and cycle
     ratio_best = ratio

{digraphx-0.6 → digraphx-0.7}/src/digraphx/neg_cycle.py

@@ -46,6 +46,7 @@ from typing import (
     Generic,
     Mapping,
     MutableMapping,
+    Optional,
     Tuple,
     Union,
 )
@@ -241,12 +242,16 @@ class NegCycleFinder(Generic[Node, Arc, Domain]):
         self,
         dist: MutableMapping[Node, Domain],
         get_weight: Callable[[Arc], Domain],
+        max_iter: Optional[int] = None,
     ) -> Generator[Cycle, None, None]:
         """Main algorithm to find negative cycles using Howard's method.
 
         Args:
             dist: Initial distance estimates (often initialized to zero)
             get_weight: Function to get edge weights
+            max_iter: Optional cap on relaxation rounds; ``None`` (default) is
+                unbounded. Exceeding the cap without a negative cycle raises
+                ``RuntimeError``.
 
         Yields:
             Generator[Cycle, None, None]: Each found negative cycle as a list of edges
@@ -274,5 +279,11 @@ class NegCycleFinder(Generic[Node, Arc, Domain]):
             False
         """
         yield from _howard_search(
-            self.digraph, dist, get_weight, _always_true, self.pred, "pred"
+            self.digraph,
+            dist,
+            get_weight,
+            _always_true,
+            self.pred,
+            "pred",
+            max_iter=max_iter,
         )

{digraphx-0.6 → digraphx-0.7}/src/digraphx/neg_cycle_q.py

@@ -44,6 +44,7 @@ from typing import (
     Generic,
     Mapping,
     MutableMapping,
+    Optional,
     Tuple,
     Union,
 )
@@ -202,6 +203,7 @@ class NegCycleFinderQ(Generic[Node, Arc, Domain]):
         dist: MutableMapping[Node, Domain],
         get_weight: Callable[[Arc], Domain],
         update_ok: Callable[[Domain, Domain], bool],
+        max_iter: Optional[int] = None,
     ) -> Generator[Cycle, None, None]:
         """Find negative cycles using predecessor-based Howard's algorithm.
 
@@ -209,6 +211,9 @@ class NegCycleFinderQ(Generic[Node, Arc, Domain]):
             dist: Initial distance estimates (often zero-initialized)
             get_weight: Function to get weight of an edge
             update_ok: Function to determine if distance updates are allowed
+            max_iter: Optional cap on relaxation rounds; ``None`` (default) is
+                unbounded. Exceeding the cap without a negative cycle raises
+                ``RuntimeError``.
 
         Yields:
             Generator[Cycle, None, None]: Each negative cycle found as a list of edges
@@ -237,7 +242,13 @@ class NegCycleFinderQ(Generic[Node, Arc, Domain]):
             False
         """
         yield from _howard_search(
-            self.digraph, dist, get_weight, update_ok, self.pred, "pred"
+            self.digraph,
+            dist,
+            get_weight,
+            update_ok,
+            self.pred,
+            "pred",
+            max_iter=max_iter,
         )
 
     def howard_succ(
@@ -245,6 +256,7 @@ class NegCycleFinderQ(Generic[Node, Arc, Domain]):
         dist: MutableMapping[Node, Domain],
         get_weight: Callable[[Arc], Domain],
         update_ok: Callable[[Domain, Domain], bool],
+        max_iter: Optional[int] = None,
     ) -> Generator[Cycle, None, None]:
         """Find negative cycles using successor-based Howard's algorithm.
 
@@ -252,9 +264,9 @@ class NegCycleFinderQ(Generic[Node, Arc, Domain]):
             dist: Initial distance estimates (often zero-initialized)
             get_weight: Function to get weight of an edge
             update_ok: Function to determine if distance updates are allowed
-
-        Yields:
-            Generator[Cycle, None, None]: Each negative cycle found as a list of edges
+            max_iter: Optional cap on relaxation rounds; ``None`` (default) is
+                unbounded. Exceeding the cap without a negative cycle raises
+                ``RuntimeError``.
 
         Note:
             Similar to howard_pred but uses successor updates instead of predecessor
@@ -278,7 +290,14 @@ class NegCycleFinderQ(Generic[Node, Arc, Domain]):
             False
         """
         yield from _howard_search(
-            self.digraph, dist, get_weight, update_ok, self.succ, "succ", verify=False
+            self.digraph,
+            dist,
+            get_weight,
+            update_ok,
+            self.succ,
+            "succ",
+            verify=False,
+            max_iter=max_iter,
         )
 
     def cycle_list(self, handle: Node, point_to: Dict[Node, Tuple[Node, Arc]]) -> Cycle:

{digraphx-0.6 → digraphx-0.7}/src/digraphx/tiny_digraph.py

@@ -158,7 +158,9 @@ class TinyDiGraph(DiGraphAdapter):
             >>> adj_list = graph.cheat_adjlist_outer_dict()
             >>> list(adj_list.keys())
             [0, 1]
-            >>> adj_list[0] is _UNINIT
+            >>> adj_list[0]
+            {}
+            >>> adj_list.lst[0] is _UNINIT
             True
         """
         return _LazyMapAdapter([_UNINIT] * self.num_nodes)
@@ -238,18 +240,44 @@ class TinyDiGraph(DiGraphAdapter):
         return self._succ.lst[n] is _UNINIT
 
     def add_edge(self, u_of_edge, v_of_edge, **attr):  # type: ignore
+        """Add the edge ``u_of_edge -> v_of_edge`` with optional attributes.
+
+        Resolves the lazy adjacency slots with direct list access instead of
+        routing through ``nx.DiGraph.add_edge``, which performs several
+        Python-level ``_LazyMapAdapter`` lookups per edge.
+        """
         u, v = u_of_edge, v_of_edge
-        self._ensure_adj(u)
-        self._ensure_adj(v)
-        super().add_edge(u, v, **attr)
+        succ = self._succ.lst
+        pred = self._pred.lst
+        if succ[u] is _UNINIT:
+            succ[u] = {}
+            pred[u] = {}
+        if succ[v] is _UNINIT:
+            succ[v] = {}
+            pred[v] = {}
+        neighbors = succ[u]
+        datadict = neighbors.get(v)
+        if datadict is None:
+            datadict = {}
+            neighbors[v] = datadict
+        if attr:
+            datadict.update(attr)
+        pred[v][u] = datadict
+        nx._clear_cache(self)
 
     def add_edges_from(self, ebunch_to_add, **attr):  # type: ignore
         for e in ebunch_to_add:
             ne = len(e)
             if ne == 3:
                 u, v, dd = e
-                d = {**attr, **dd}
-                self.add_edge(u, v, **d)
+                if attr and dd:
+                    self.add_edge(u, v, **{**attr, **dd})
+                elif attr:
+                    self.add_edge(u, v, **attr)
+                elif dd:
+                    self.add_edge(u, v, **dd)
+                else:
+                    self.add_edge(u, v)
             elif ne == 2:
                 u, v = e
                 if attr:

{digraphx-0.6 → digraphx-0.7/src/digraphx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digraphx
-Version: 0.6
+Version: 0.7
 Summary: Network Optimization Python Code
 Home-page: https://github.com/luk036/digraphx
 Author: Wai-Shing Luk

{digraphx-0.6 → digraphx-0.7}/src/digraphx.egg-info/SOURCES.txt

@@ -19,11 +19,13 @@ requirements.txt
 setup.cfg
 setup.py
 tox.ini
+tunable_parameter.md
 .github/workflows/jekyll-gh-pages.yml
 .github/workflows/multi-platforms.yml
 .github/workflows/python-app.yml
 .github/workflows/python-publish.yml
 .vscode/settings.json
+benchmarks/test_benchmarks.py
 docs/Makefile
 docs/authors.md
 docs/changelog.md

{digraphx-0.6 → digraphx-0.7}/src/digraphx.egg-info/scm_file_list.json

@@ -17,6 +17,7 @@
     "GEMINI.md",
     "LICENSE.txt",
     "README.md",
+    "benchmarks/test_benchmarks.py",
     "coverage.json",
     "docs/Makefile",
     "docs/_static/.gitignore",
@@ -86,6 +87,7 @@
     "tests/test_timing_example_howard.py",
     "tests/test_tiny_digraph.py",
     "tests/test_tiny_digraph_property.py",
-    "tox.ini"
+    "tox.ini",
+    "tunable_parameter.md"
   ]
 }

digraphx-0.7/src/digraphx.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.7",
+  "distance": 0,
+  "node": "g0368caf1c0b8dde863eec2db7af4d8bb2bd55ecb",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-09"
+}

{digraphx-0.6 → digraphx-0.7}/tests/test_neg_cycle.py

@@ -3,6 +3,7 @@ from __future__ import print_function
 
 from typing import Any, Callable, Dict, Union
 
+import pytest
 from mywheel.map_adapter import MapAdapter
 
 from digraphx.neg_cycle import NegCycleFinder
@@ -112,3 +113,31 @@ def test_neg_cycle_is_negative_edge_case() -> None:
 
     # This should return False as the triangle inequality is not violated
     assert not finder.is_negative(0, dist, lambda edge: edge.get("weight", 1))
+
+
+def test_howard_max_iter_default_unbounded() -> None:
+    digraph: DiGraphAdapter = DiGraphAdapter()
+    digraph.add_edge(0, 1, weight=1)
+    dist: Dict[int, int] = {0: 0, 1: 5}
+    finder: NegCycleFinder[Any, Any, Any] = NegCycleFinder(digraph)
+    assert list(finder.howard(dist, lambda edge: edge.get("weight", 1))) == []
+
+
+def test_howard_max_iter_finds_cycle() -> None:
+    digraph: DiGraphAdapter = DiGraphAdapter()
+    digraph.add_edge(0, 1, weight=1)
+    digraph.add_edge(1, 0, weight=-3)
+    dist: Dict[int, int] = {0: 0, 1: 0}
+    finder: NegCycleFinder[Any, Any, Any] = NegCycleFinder(digraph)
+    cycles = list(finder.howard(dist, lambda edge: edge.get("weight", 1), max_iter=100))
+    assert len(cycles) >= 1
+
+
+def test_howard_max_iter_raises_when_exceeded() -> None:
+    digraph: DiGraphAdapter = DiGraphAdapter()
+    digraph.add_edge(0, 1, weight=1)
+    dist: Dict[int, int] = {0: 0, 1: 5}
+    finder: NegCycleFinder[Any, Any, Any] = NegCycleFinder(digraph)
+    with pytest.raises(RuntimeError):
+        for _ in finder.howard(dist, lambda edge: edge.get("weight", 1), max_iter=1):
+            pass

digraphx-0.7/tunable_parameter.md

@@ -0,0 +1,153 @@
+# Tunable Parameters in `digraphx`
+
+A complete reference of every user-tunable parameter of the algorithms in this
+project, together with its default value and source location.
+
+## Key finding
+
+`digraphx` has **no `Options` / config dataclass**. There are zero `@dataclass`
+or `NamedTuple` definitions in the package. Every tunable is a plain
+function/method parameter or an injected callback. The dominant policy knob is
+the `update_ok` predicate that gates Bellman-Ford relaxation.
+
+This report separates the categories explicitly so it is clear what a caller
+can actually adjust.
+
+---
+
+## 1. Negative-cycle finders
+
+Files: `src/digraphx/neg_cycle.py`, `src/digraphx/neg_cycle_q.py`,
+internal `src/digraphx/_cycle_base.py`.
+
+| API | Parameters | Default |
+| --- | --- | --- |
+| `NegCycleFinder(digraph)` | `digraph` | required |
+| `NegCycleFinder.howard(dist, get_weight, max_iter=None)` | `max_iter: int \| None` | `None` (unbounded) |
+| `NegCycleFinderQ(digraph)` | `digraph` | required |
+| `NegCycleFinderQ.relax_pred(dist, get_weight, update_ok)` | `update_ok` (predicate) | required |
+| `NegCycleFinderQ.relax_succ(dist, get_weight, update_ok)` | `update_ok` | required |
+| `NegCycleFinderQ.howard_pred(dist, get_weight, update_ok, max_iter=None)` | `update_ok`; `max_iter` | required; `None` |
+| `NegCycleFinderQ.howard_succ(dist, get_weight, update_ok, max_iter=None)` | `update_ok`; `max_iter` | required; `None` |
+| `howard_search(..., direction, verify=True, max_iter=None)` (internal) | `verify: bool`; `max_iter` | `True`; `None` |
+
+Notes:
+
+- `update_ok(old, new) -> bool` is the relaxation-gate callback. When
+  `NegCycleFinder` omits it, the gate is `_always_true`
+  (`src/digraphx/_cycle_base.py:36-38`).
+- `NegCycleFinderQ.howard_succ` hard-wires `verify=False`; `howard_pred` uses
+  `verify=True` (`src/digraphx/neg_cycle_q.py:281` and `:239-241`).
+
+---
+
+## 2. Parametric solvers
+
+Files: `src/digraphx/parametric.py`, `src/digraphx/min_parametric_q.py`,
+internal `src/digraphx/_parametric_base.py`.
+
+| API | Parameters | Default |
+| --- | --- | --- |
+| `MaxParametricSolver(digraph, omega)` | `omega` (strategy) | required |
+| `MaxParametricSolver.run(dist, ratio)` | — | no tunables (internally `minimize=True`) |
+| `MinParametricSolver(digraph, omega)` | `omega` | required |
+| `MinParametricSolver.run(dist, ratio, update_ok, pick_one_only=False)` | `update_ok`; `pick_one_only: bool` | required; `False` |
+| `_run_loop(..., *, minimize, update_ok=..., pick_one_only=False, alternate_direction=False)` (internal) | `update_ok`, `pick_one_only`, `alternate_direction` | `lambda old, new: True`; `False`; `False` |
+
+- `MinParametricSolver.run` is the public surface
+  (`src/digraphx/min_parametric_q.py:125-131`).
+- `alternate_direction=True` is fixed internally for the constrained solver.
+
+---
+
+## 3. Minimum cycle ratio
+
+File: `src/digraphx/min_cycle_ratio.py`.
+
+| API | Parameters | Default |
+| --- | --- | --- |
+| `MinCycleRatioSolver(digraph)` | `digraph` | required |
+| `MinCycleRatioSolver.run(dist, ratio0)` | `ratio0` (initial ratio) | required |
+| `CycleRatioAPI(digraph, result_type)` | `result_type` (`Fraction` or `float`) | required (selects numeric precision) |
+| `set_default(digraph, weight, value)` | `weight: str`, `value` | required |
+
+---
+
+## 4. Min-cost flow (cycle-canceling)
+
+File: `src/digraphx/mcf.py`.
+
+| API | Parameters | Default |
+| --- | --- | --- |
+| `cycle_canceling_mcf(g, demands, sink=None)` | `sink` | `None` |
+| `VertexFilter(sink)` | `sink` | required |
+
+- When `sink` is provided, the vertex-disjoint constraint is enabled; when
+  `None`, no constraint is enforced.
+- Edge-data defaults consumed internally: `capacity` defaults to `inf`,
+  `weight` defaults to `0`; the bottleneck is truncated via `int(...)`
+  (`src/digraphx/mcf.py:61-62`, `:239`, `:304`).
+
+---
+
+## 5. Graph containers
+
+Files: `src/digraphx/tiny_digraph.py`, `src/digraphx/csr_digraph.py`.
+
+| API | Parameters | Default |
+| --- | --- | --- |
+| `TinyDiGraph.init_nodes(num_nodes)` | `num_nodes: int` | required |
+| `TinyDiGraph.add_edge(u, v, **attr)` | free-form attributes | — |
+| `CSRDiGraph.init_nodes(num_nodes)` | `num_nodes: int` | required |
+| `CSRDiGraph.add_edge(u, v, **attr)` | free-form attributes | — |
+| `CSRDiGraph.freeze()` | — | — |
+| `DiGraphAdapter.get_edge_data(u, v, default=None)` | `default` | `None` |
+
+---
+
+## 6. Repository utilities (experiments, not core library)
+
+File: `experimental/spare_tsv.py`.
+
+| Function | Parameters | Default |
+| --- | --- | --- |
+| `formGraph(T, pos, mu, eta, seed=None)` | `seed` | `None` |
+| `vdc(n, base=2)` | `base` | `2` |
+| `vdcorput(n, base=2)` | `base` | `2` |
+| `vdcorput_iter(n, base=2)` | `base` | `2` |
+| `showPaths(gra, pos, N, edgeProbs=1.0, path=None, visibleNodes=None, guards=None)` | `edgeProbs`, `path`, `visibleNodes`, `guards` | `1.0`, `None`, `None`, `None` |
+| `setup_network_flow(gra, pos, primal_count, capacity)` | `capacity` | required |
+| `solve_network_flow(gra, sink_node)` | `sink_node` | required |
+
+---
+
+## 7. Fixed values in tests and benchmarks (not library defaults)
+
+| Source | Constant | Value |
+| --- | --- | --- |
+| `benchmarks/test_benchmarks.py:21-23` | `SEED`, `SIZES`, `MCR_SIZES` | `1234`, `[200, 1000]`, `[50, 100]` |
+| `benchmarks/test_benchmarks.py:53-61` | node degree | `5` / `6` |
+| `tests/test_*howard*.py:14,64,107` | test-local Howard helper `max_iter` | `2000` |
+| `experiments/experi.py:13-23` and `experi-descent*.py` | `N`, `M`, `r`, `mu`, `eta`, `seed`, `xbase`, `ybase` | `155`, `40`, `4`, `0.12`, `1.6`, `5`, `2`, `3` |
+| `docs/examples/plot_*.py` | `seed` | `42` |
+
+---
+
+## Summary of genuine tunables
+
+| Tunable | Default | Location |
+| --- | --- | --- |
+| `update_ok` predicate (relaxation gate) | `lambda old, new: True` | `src/digraphx/_cycle_base.py:37`, `src/digraphx/_parametric_base.py:37` |
+| `howard`/`howard_pred`/`howard_succ` `max_iter` | `None` (unbounded; raises `RuntimeError` if set and exceeded) | `src/digraphx/neg_cycle.py`, `src/digraphx/neg_cycle_q.py` |
+| `MinParametricSolver.run(..., pick_one_only)` | `False` | `src/digraphx/min_parametric_q.py:130` |
+| `cycle_canceling_mcf(..., sink)` | `None` | `src/digraphx/mcf.py:254` |
+| `CycleRatioAPI(..., result_type)` | required (`Fraction` / `float`) | `src/digraphx/min_cycle_ratio.py:113` |
+| `howard_search(..., verify)` (internal) | `True` | `src/digraphx/_cycle_base.py:210` |
+| `_run_loop(..., alternate_direction)` (internal) | `False` | `src/digraphx/_parametric_base.py:39` |
+| `formGraph(..., seed)` | `None` | `experimental/spare_tsv.py:34` |
+| `vdc` / `vdcorput` / `vdcorput_iter(..., base)` | `2` | `experimental/spare_tsv.py:10,20,25` |
+| `showPaths` overlay options | `edgeProbs=1.0`, `path=None`, `visibleNodes=None`, `guards=None` | `experimental/spare_tsv.py:54` |
+
+Everything else is problem data (graph, distances, ratio, demands) or a
+hardcoded constant (`capacity=inf`, `weight=0`, integer bottleneck,
+`verify=False` on `howard_succ`).

digraphx-0.6/src/digraphx.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.6",
-  "distance": 0,
-  "node": "g0ed3c93296539f391931daa4c1b99888a64a389f",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-09-04"
-}