digraphx 0.5__tar.gz → 0.7__tar.gz

{digraphx-0.5 → digraphx-0.7}/.github/workflows/multi-platforms.yml

@@ -10,7 +10,7 @@ jobs:
         os: ["ubuntu-latest", "windows-latest"]
         version: ["3.10", "3.13"]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: conda-incubator/setup-miniconda@v3
         with:
           activate-environment: test

{digraphx-0.5 → digraphx-0.7}/.github/workflows/python-app.yml

@@ -14,9 +14,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Set up Python 3.10
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: "3.10"
       - name: Install dependencies
@@ -37,7 +37,7 @@ jobs:
       - name: Codecov
         # You may pin to the exact commit or the version.
         # uses: codecov/codecov-action@29386c70ef20e286228c72b668a06fd0e8399192
-        uses: codecov/codecov-action@v1.5.2
+        uses: codecov/codecov-action@v4
         with:
           # Repository upload token - get it from codecov.io. Required only for private repositories
           token: ${{ secrets.CODECOV_TOKEN }}

digraphx-0.7/CHANGELOG.md

@@ -0,0 +1,70 @@
+# 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
+- **Shared cycle/parametric bases**: Extracted `_cycle_base.py` (`find_cycle`, `relax_pred`, `relax_succ`, `cycle_list`, `is_negative`, `howard_search`) and `_parametric_base.py` (`_run_loop`) shared by the max/min parametric solvers. `NegCycleFinder`/`NegCycleFinderQ` now delegate to the shared skeleton, `MinParametricAPI` subclasses `ParametricAPI` (was a duplicate interface), and `mcf.py` reuses `_residual_edge`. Public API unchanged. (#1c60bde)
+- **Public re-exports in `__init__.py`**: Fixes README quick-start imports such as `NegCycleFinder`, `TinyDiGraph`, `MinCycleRatioSolver`. (#1c60bde)
+
+### Bug Fixes
+- **mypy type errors**: Resolved None guards, test generics and networkx config issues. (#13dc943)
+- **RTD doc build**: Added matplotlib and numpy to `docs/requirements.txt`. (#1f49779)
+
+### Testing & Code Quality
+- **Coverage raised 85%→99%**: Added coverage extras for MCF solver, TinyDiGraph and solvers. (#2cabc4e)
+- **Style pass**: Reformatted list comprehensions and type annotations. (#2973013)
+
+### Code Cleanup
+- **Removed AI slop**: Stripped boilerplate from docstrings and comments. (#be4456a)
+- **Import tidy-up**: Dropped unused `NegCycleFinderQ` import in `min_parametric_q`, split multi-name `_cycle_base` imports, stripped stray blank lines in `tiny_digraph`. (#5e37f7c)
+
+### Build & CI
+- **Removed stale `.bak` workflow**: Deleted `ci.bak`. (#5f50fe3)
+- **Updated GitHub Actions**: checkout→v4, setup-python→v5, codecov-action→v4 to fix Codecov tokenless upload failure and Node 20 deprecation. (#5334192)
+
+## Version 0.5 (2026-07-16)
+
+### Features
+- **MCF solver**: Added min-cost flow cycle-cancellation solver (`mcf.py`) and `NegCycleFinderQ` with `VertexFilter` for vertex-disjoint MCF constraint. (#582b1eb, #e6e248f)
+- **CSRDiGraph**: Memory-efficient CSR-backed directed graph with `_CSRNeighbors` Mapping view — compact integer arrays instead of dicts. (#12465a3)
+- **Bellman-Ford cycle detection**: Replaced Howard's algorithm with Bellman-Ford for negative cycle detection; fixed parallel edge bug. (#04da700)
+- **spareTSV integration**: Added spare TSV network flow utilities and unified variable naming to `utx`/`vtx` (C++ convention). (#762008a)
+- **Moved spare_tsv to experimental/**: Relocated matplotlib-dependent spare_tsv module out of main package to avoid CI failures when matplotlib is not installed. (#7367e6c)
+
+### Performance
+- **Lazy TinyDiGraph/CSRDiGraph**: Avoid pre-allocating 2N dicts per `init_nodes()` call (~464 MB saved for 1M nodes). (#12465a3)
+- **Incremental residual updates**: Update only edges affected by cycle cancellation instead of rebuilding full residual each iteration. (#12465a3)
+
+### Documentation
+- **plot_directive and svgbob**: Enabled matplotlib plot_directive for auto-generated figures. Added TinyDiGraph and cycle detection example plots. Added svgbob diagram to TinyDiGraph class docstring. (#b64d424)
+
+### Testing & Code Quality
+- **Coverage raised 70%→95%**: Added extensive test coverage including MCF solver, CSRDiGraph, edge cases, and extra min-cycle-ratio tests. (#80da2a2, #9030d8a)
+
+### Code Cleanup
+- **Removed PyScaffold boilerplate**: Deleted `skeleton.py` and `test_skeleton.py`. (#9bdbdb1)
+- **Dropped Python < 3.9 compat**: Removed `importlib-metadata` conditional dependency. (#9bdbdb1)
+- **Config cleanup**: Removed dead entry points, unused mypy ignores, stale `IFLOW.md` and duplicate `LICENSE`. (#9bdbdb1)
+
+### Build & CI
+- **CI repair**: Fixed broken entry_points and remaining skeleton imports. (#91fd90e)
+- **flake8 cleanup**: Removed unused imports and fixed formatting warnings. (#91d7141)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digraphx
-Version: 0.5
+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.5 → digraphx-0.7}/docs/requirements.txt

@@ -6,3 +6,4 @@ git+https://github.com/luk036/mywheel.git
 myst-parser[linkify]
 sphinx>=3.2.1
 sphinxcontrib-svgbob
+matplotlib

{digraphx-0.5 → digraphx-0.7}/experimental/spare_tsv.py

@@ -97,9 +97,7 @@ def showPaths(gra, pos, N, edgeProbs=1.0, path=None, visibleNodes=None, guards=N
     # only display edges between non-dummy nodes
     edge_list = list(gra.edges())
     visibleEdges = [
-        e
-        for e in edge_list
-        if e[0] in visibleNodes and e[1] in visibleNodes
+        e for e in edge_list if e[0] in visibleNodes and e[1] in visibleNodes
     ]
 
     if isinstance(edgeProbs, float):

{digraphx-0.5 → digraphx-0.7}/mypy.ini

@@ -1,15 +1,13 @@
 [mypy]
 python_version = 3.12
 warn_unused_configs = True
+disable_error_code = import-untyped
 
 [mypy-setuptools.*]
 ignore_missing_imports = True
 
+[mypy-matplotlib.*]
 ignore_missing_imports = True
 
-ignore_missing_imports = True
-
-ignore_missing_imports = True
-
-[mypy-matplotlib.*]
+[mypy-networkx.*]
 ignore_missing_imports = True

digraphx-0.7/src/digraphx/__init__.py

@@ -0,0 +1,36 @@
+import sys
+
+if sys.version_info[:2] >= (3, 8):
+    from importlib.metadata import PackageNotFoundError, version  # pragma: no cover
+else:
+    from importlib_metadata import PackageNotFoundError, version  # pragma: no cover
+
+try:
+    dist_name = __name__
+    __version__ = version(dist_name)
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
+finally:
+    del version, PackageNotFoundError
+
+# Public API re-exports (matching the README quick-start examples)
+from .csr_digraph import CSRDiGraph  # noqa: E402
+from .mcf import cycle_canceling_mcf  # noqa: E402
+from .min_cycle_ratio import MinCycleRatioSolver  # noqa: E402
+from .min_parametric_q import MinParametricSolver  # noqa: E402
+from .neg_cycle import NegCycleFinder  # noqa: E402
+from .neg_cycle_q import NegCycleFinderQ  # noqa: E402
+from .parametric import MaxParametricSolver  # noqa: E402
+from .tiny_digraph import DiGraphAdapter, TinyDiGraph  # noqa: E402
+
+__all__ = [
+    "CSRDiGraph",
+    "DiGraphAdapter",
+    "MaxParametricSolver",
+    "MinCycleRatioSolver",
+    "MinParametricSolver",
+    "NegCycleFinder",
+    "NegCycleFinderQ",
+    "TinyDiGraph",
+    "cycle_canceling_mcf",
+]

digraphx-0.7/src/digraphx/_cycle_base.py

@@ -0,0 +1,253 @@
+"""Shared implementation cores for the negative-cycle finders.
+
+This module centralises the graph-traversal helpers and the Howard
+policy-iteration skeleton (Template Method) used by :class:`NegCycleFinder`
+(neg_cycle.py) and :class:`NegCycleFinderQ` (neg_cycle_q.py).  The relaxation
+direction and the optional negativity check are injected as strategies.
+
+It is an implementation detail of the package; the public API lives in
+``neg_cycle`` / ``neg_cycle_q`` and is unchanged.
+"""
+
+from fractions import Fraction
+from typing import (
+    Callable,
+    Dict,
+    Generator,
+    List,
+    Mapping,
+    MutableMapping,
+    Optional,
+    Tuple,
+    TypeVar,
+)
+
+# Type variables for generic graph components
+Node = TypeVar("Node")  # Hashable node type (must implement __hash__)
+Arc = TypeVar("Arc")  # Hashable edge type (must implement __hash__)
+Domain = TypeVar(
+    "Domain", int, Fraction, float
+)  # Numeric type for weights (must support comparison and arithmetic)
+Cycle = List[Arc]  # Alias for a list of edges forming a cycle
+
+# A point-to map: node -> (predecessor/successor node, connecting edge)
+PointTo = Dict[Node, Tuple[Node, Arc]]
+
+
+def _always_true(old: Domain, new: Domain) -> bool:
+    """Default `update_ok` gate: allow every distance update."""
+    return True
+
+
+def find_cycle(
+    digraph: Mapping[Node, Mapping[Node, Arc]], point_to: PointTo
+) -> Generator[Node, None, None]:
+    """Yield each node that starts a cycle in the given point-to map.
+
+    Uses a coloring algorithm (white/gray/black) to detect cycles: white nodes
+    are unvisited, gray nodes are being visited in the current DFS path, and
+    black nodes are fully visited.  A cycle is found when a node in the current
+    path is reached again.
+    """
+    visited: Dict[Node, Node] = {}  # Maps nodes to their DFS root
+    for vtx in filter(lambda vtx: vtx not in visited, digraph):
+        utx = vtx
+        while True:
+            visited[utx] = vtx  # Mark as visited with current DFS root
+            if utx not in point_to:
+                break  # Reached a leaf node
+            utx, _ = point_to[utx]  # Move to predecessor/successor
+            if utx in visited:
+                if visited[utx] == vtx:  # Found cycle back to current root
+                    yield utx
+                break  # Cycle or different DFS tree
+
+
+def relax_pred(
+    digraph: Mapping[Node, Mapping[Node, Arc]],
+    dist: MutableMapping[Node, Domain],
+    get_weight: Callable[[Arc], Domain],
+    update_ok: Callable[[Domain, Domain], bool],
+    pred: PointTo,
+) -> bool:
+    """Perform one predecessor relaxation pass (Bellman-Ford style).
+
+    Updates ``dist[v]`` and the predecessor map when the triangle inequality
+    ``dist[v] > dist[u] + weight(u, v)`` holds AND ``update_ok`` permits it.
+    Returns ``True`` if any distance was updated.
+    """
+    changed = False
+    for utx, neighbors in digraph.items():
+        for vtx, edge in neighbors.items():
+            distance = dist[utx] + get_weight(edge)
+            if dist[vtx] > distance and update_ok(dist[vtx], distance):
+                dist[vtx] = distance
+                pred[vtx] = (utx, edge)  # Update predecessor
+                changed = True
+    return changed
+
+
+def relax_succ(
+    digraph: Mapping[Node, Mapping[Node, Arc]],
+    dist: MutableMapping[Node, Domain],
+    get_weight: Callable[[Arc], Domain],
+    update_ok: Callable[[Domain, Domain], bool],
+    succ: PointTo,
+) -> bool:
+    """Perform one successor relaxation pass (reverse Bellman-Ford style).
+
+    Updates ``dist[u]`` and the successor map when the triangle inequality
+    ``dist[u] < dist[v] - weight(u, v)`` holds AND ``update_ok`` permits it.
+    Returns ``True`` if any distance was updated.
+    """
+    changed = False
+    for utx, neighbors in digraph.items():
+        for vtx, edge in neighbors.items():
+            distance = dist[vtx] - get_weight(edge)
+            if dist[utx] < distance and update_ok(dist[utx], distance):
+                dist[utx] = distance
+                succ[utx] = (vtx, edge)  # Update successor
+                changed = True
+    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.
+
+    Follows predecessor/successor links until returning to the starting node.
+    """
+    vtx = handle
+    cycle = list()
+    while True:
+        utx, edge = point_to[vtx]  # Get next node and connecting edge
+        cycle.append(edge)  # Add edge to cycle
+        vtx = utx  # Move to next node
+        if vtx == handle:  # Completed the cycle
+            break
+    return cycle
+
+
+def is_negative(
+    point_to: PointTo,
+    handle: Node,
+    dist: MutableMapping[Node, Domain],
+    get_weight: Callable[[Arc], Domain],
+) -> bool:
+    """Return ``True`` if the cycle starting at ``handle`` is negative.
+
+    A cycle is negative if at least one edge (u, v) on it violates the
+    triangle inequality ``dist[v] > dist[u] + weight(u, v)``.
+    """
+    vtx = handle
+    # C-style do-while loop
+    while True:
+        utx, edge = point_to[vtx]
+        if dist[vtx] > dist[utx] + get_weight(edge):  # Found negative cycle
+            return True
+        vtx = utx
+        if vtx == handle:  # Completed full cycle
+            break
+    return False
+
+
+def howard_search(
+    digraph: Mapping[Node, Mapping[Node, Arc]],
+    dist: MutableMapping[Node, Domain],
+    get_weight: Callable[[Arc], Domain],
+    update_ok: Callable[[Domain, Domain], bool],
+    point_to: PointTo,
+    direction: str,
+    verify: bool = True,
+    max_iter: Optional[int] = None,
+) -> Generator[Cycle, None, None]:
+    """Template Method: Howard's policy-iteration skeleton.
+
+    Repeatedly relaxes the distance estimates until no improvement is made or a
+    cycle is found, then yields each detected cycle as a list of edge weights.
+
+    The relaxation pass and the point-to map are selected by ``direction``
+    (``"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
+    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.7/src/digraphx/_parametric_base.py

@@ -0,0 +1,98 @@
+"""Shared implementation core for the parametric solvers.
+
+This module centralises the parametric-search loop (Template Method) shared by
+:class:`MaxParametricSolver` (parametric.py) and :class:`MinParametricSolver`
+(min_parametric_q.py).  The ratio-comparison direction and the cycle-search
+direction alternation are injected as strategies.
+
+It is an implementation detail of the package; the public API lives in
+``parametric`` / ``min_parametric_q`` and is unchanged.
+"""
+
+from typing import Callable, Generic, Mapping, MutableMapping, Tuple, TypeVar
+
+from .neg_cycle import Arc, Cycle, Domain, NegCycleFinder, Node
+from .neg_cycle_q import NegCycleFinderQ
+
+Ratio = TypeVar("Ratio", int, float)  # Comparable Ring
+
+
+class _API(Generic[Node, Arc, Ratio]):
+    """Protocol-ish base for the parametric API strategies."""
+
+    def distance(self, ratio: Ratio, edge: Arc) -> Ratio:
+        raise NotImplementedError
+
+    def zero_cancel(self, cycle: Cycle) -> Ratio:
+        raise NotImplementedError
+
+
+def _run_loop(
+    digraph: Mapping[Node, Mapping[Node, Arc]],
+    omega: _API,
+    dist: MutableMapping[Node, Domain],
+    ratio: Ratio,
+    *,
+    minimize: bool,
+    update_ok: Callable[[Domain, Domain], bool] = lambda old, new: True,
+    pick_one_only: bool = False,
+    alternate_direction: bool = False,
+) -> Tuple[Ratio, Cycle]:
+    """Template Method: the parametric-search loop.
+
+    Repeatedly finds negative cycles at the current ratio and updates the ratio
+    until no improving cycle exists.  ``minimize`` selects the comparison
+    direction; ``alternate_direction`` (with ``update_ok``) enables the
+    predecessor/successor alternation used by the constrained solver.
+
+    Returns ``(final_ratio, critical_cycle)``.
+    """
+    if not dist:  # empty graph case - return early with no cycle found
+        return ratio, []
+
+    def get_weight(e: Arc) -> Domain:
+        return omega.distance(ratio, e)
+
+    # Initialize min/max ratio and cycle
+    ratio_best = ratio
+    cycle_best = []
+    cycle = []
+    reverse: bool = True  # Flag to alternate search direction
+
+    if alternate_direction:
+        ncf: NegCycleFinderQ[Node, Arc, Domain] = NegCycleFinderQ(digraph)
+    else:
+        ncf = NegCycleFinder(digraph)
+
+    # Main algorithm loop
+    while True:
+        if alternate_direction:
+            # Search for cycles in either forward or reverse direction
+            cycles = (
+                ncf.howard_succ(dist, get_weight, update_ok)
+                if reverse
+                else ncf.howard_pred(dist, get_weight, update_ok)
+            )
+        else:
+            cycles = ncf.howard(dist, get_weight)
+
+        # Evaluate all found cycles
+        for c_i in cycles:
+            ratio_i = omega.zero_cancel(c_i)
+            if (ratio_best > ratio_i) if minimize else (ratio_best < ratio_i):
+                ratio_best = ratio_i
+                cycle_best = c_i
+                if pick_one_only:  # Early exit if we only need one improvement
+                    break
+
+        # Termination condition: no better ratio found
+        if (ratio_best >= ratio) if minimize else (ratio_best <= ratio):
+            break
+
+        # Update state for next iteration
+        cycle = cycle_best
+        ratio = ratio_best
+        if alternate_direction:
+            reverse = not reverse  # Alternate search direction
+
+    return ratio, cycle