digraphx 0.5__tar.gz → 0.6__tar.gz

{digraphx-0.5 → digraphx-0.6}/.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.6}/.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.5 → digraphx-0.6}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 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

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

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

{digraphx-0.5 → digraphx-0.6}/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.6}/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.6}/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.6/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.6/src/digraphx/_cycle_base.py

@@ -0,0 +1,180 @@
+"""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,
+    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 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,
+) -> 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).
+    """
+    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):
+        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)

digraphx-0.6/src/digraphx/_parametric_base.py

@@ -0,0 +1,101 @@
+"""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, []
+
+    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))
+
+    # 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

{digraphx-0.5 → digraphx-0.6}/src/digraphx/csr_digraph.py

@@ -91,6 +91,7 @@ class CSRDiGraph(Mapping):
     def add_edge(self, u: int, v: int, **attr) -> None:  # type: ignore
         """Add a directed edge ``u → v`` with optional attributes."""
         assert not self._frozen, "graph is frozen"
+        assert self._edges is not None
         self._edges[u].append((v, attr if attr else {}))
 
     def freeze(self) -> None:
@@ -100,6 +101,7 @@ class CSRDiGraph(Mapping):
         """
         if self._frozen:
             return
+        assert self._edges is not None
         indptr = array("i", [0])  # cumulative counts
         for node_edges in self._edges:
             indptr.append(indptr[-1] + len(node_edges))
@@ -123,6 +125,9 @@ class CSRDiGraph(Mapping):
     def __getitem__(self, u: int):
         if not self._frozen:
             self.freeze()
+        assert self._indptr is not None
+        assert self._indices is not None
+        assert self._data is not None
         start = self._indptr[u]
         end = self._indptr[u + 1]
         return _CSRNeighbors(self._indices, self._data, start, end)

{digraphx-0.5 → digraphx-0.6}/src/digraphx/mcf.py

@@ -106,33 +106,17 @@ def _build_residual(g, flow):
     for u, neighbors in g.items():
         if u not in residual:
             residual[u] = {}
-        for v, data in neighbors.items():
-            cap = data.get("capacity", float("inf"))
-            wgt = data.get("weight", 0)
-            f = flow.get(u, {}).get(v, 0)
-
-            if f < cap:
-                edge = {
-                    "cost": wgt,
-                    "capacity": cap - f,
-                    "orig": (u, v),
-                    "forward": True,
-                }
+        for v in neighbors:
+            fwd, bwd = _residual_edge(g, u, v, flow)
+            if fwd is not None:
                 # Keep the more negative cost when edges collide at same (u,v)
                 prev = residual[u].get(v)
-                if prev is None or edge["cost"] < prev["cost"]:
-                    residual[u][v] = edge
-
-            if f > 0:
-                edge = {
-                    "cost": -wgt,
-                    "capacity": f,
-                    "orig": (u, v),
-                    "forward": False,
-                }
+                if prev is None or fwd["cost"] < prev["cost"]:
+                    residual[u][v] = fwd
+            if bwd is not None:
                 prev = residual.setdefault(v, {}).get(u)
-                if prev is None or edge["cost"] < prev["cost"]:
-                    residual[v][u] = edge
+                if prev is None or bwd["cost"] < prev["cost"]:
+                    residual[v][u] = bwd
 
     return residual
 
@@ -297,8 +281,6 @@ def cycle_canceling_mcf(g, demands, sink=None):
                 if f > 0 and u != sink:
                     vf.used.add(u)
                     break  # one outgoing edge is enough to mark as used
-    if vf is not None:
-        print(f"Used init: {len(vf.used)}")
 
     all_nodes = None
 

{digraphx-0.5 → digraphx-0.6}/src/digraphx/min_parametric_q.py

@@ -43,14 +43,16 @@ from abc import abstractmethod
 from fractions import Fraction
 from typing import Callable, Generic, Mapping, MutableMapping, Tuple, TypeVar
 
-from .neg_cycle_q import Arc, Cycle, NegCycleFinderQ, Node
+from ._parametric_base import _run_loop
+from .neg_cycle_q import Arc, Cycle, Node
+from .parametric import ParametricAPI
 
 # Define type variables for domain (numeric types) and ratio (fraction or float)
 Domain = TypeVar("Domain", int, Fraction, float)  # Comparable Ring
 Ratio = TypeVar("Ratio", Fraction, float)
 
 
-class MinParametricAPI(Generic[Node, Arc, Ratio]):
+class MinParametricAPI(ParametricAPI[Node, Arc, Ratio]):
     @abstractmethod
     def distance(self, ratio: Ratio, edge: Arc) -> Ratio:
         """
@@ -117,7 +119,6 @@ class MinParametricSolver(Generic[Node, Arc, Ratio, Domain]):
             >>> digraph = {'a': {'b': {'cost': 5, 'time': 1}}}
             >>> omega = MinParametricAPI()  # Requires concrete implementation
         """
-        # self.ncf = NegCycleFinderQ(digraph)
         self.digraph = digraph
         self.omega: MinParametricAPI[Node, Arc, Ratio] = omega
 
@@ -149,46 +150,13 @@ class MinParametricSolver(Generic[Node, Arc, Ratio, Domain]):
                  - The minimum ratio found (ratio)
                  - The cycle that corresponds to this ratio (cycle)
         """
-        # Determine the numeric type used in distance calculations
-        DomainType = type(next(iter(dist.values())))
-
-        # Helper function to calculate edge weights based on current ratio
-        def get_weight(e: Arc) -> Domain:
-            return DomainType(self.omega.distance(ratio, e))
-
-        # Initialize tracking variables for minimum ratio and corresponding cycle
-        ratio_max = ratio
-        cycle_max = []
-        cycle = []
-        reverse: bool = True  # Flag to alternate search direction
-
-        # Initialize the negative cycle finder with our graph
-        ncf: NegCycleFinderQ[Node, Arc, Domain] = NegCycleFinderQ(self.digraph)
-
-        # Main optimization loop
-        while True:
-            # Search for cycles in either forward or reverse direction
-            if reverse:
-                cycles = ncf.howard_succ(dist, get_weight, update_ok)
-            else:
-                cycles = ncf.howard_pred(dist, get_weight, update_ok)
-
-            # Evaluate all found cycles
-            for c_i in cycles:
-                ratio_i = self.omega.zero_cancel(c_i)
-                if ratio_max < ratio_i:
-                    ratio_max = ratio_i
-                    cycle_max = c_i
-                    if pick_one_only:  # Early exit if we only need one improvement
-                        break
-
-            # Termination condition: no better ratio found
-            if ratio_max <= ratio:
-                break
-
-            # Update state for next iteration
-            cycle = cycle_max
-            ratio = ratio_max
-            reverse = not reverse  # Alternate search direction
-
-        return ratio, cycle
+        return _run_loop(
+            self.digraph,
+            self.omega,
+            dist,
+            ratio,
+            minimize=False,
+            update_ok=update_ok,
+            pick_one_only=pick_one_only,
+            alternate_direction=True,
+        )