digraphx 0.3__tar.gz → 0.5__tar.gz

{digraphx-0.3 → digraphx-0.5}/.github/workflows/ci.bak

@@ -8,7 +8,7 @@ on:
   push:
     # Avoid using all the resources/limits available by checking only
     # relevant branches and tags. Other branches can be checked via PRs.
-    branches: [main]
+    branches: [ main, dev ]
     tags: ['v[0-9]*', '[0-9]+.[0-9]+*']  # Match tags that resemble a version
   pull_request:  # Run in every PR
   workflow_dispatch:  # Allow manually triggering the workflow
@@ -60,8 +60,8 @@ jobs:
     strategy:
       matrix:
         python:
-        - "3.9"  # oldest Python supported by PSF
-        - "3.11"  # newest Python that is stable
+        - "3.10"  # oldest Python supported by PSF
+        - "3.13"  # newest Python that is stable
         platform:
         - ubuntu-latest
         - macos-latest

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

@@ -8,7 +8,7 @@ jobs:
     strategy:
       matrix:
         os: ["ubuntu-latest", "windows-latest"]
-        version: ["3.9", "3.11"]
+        version: ["3.10", "3.13"]
     steps:
       - uses: actions/checkout@v3
       - uses: conda-incubator/setup-miniconda@v3
@@ -34,6 +34,5 @@ jobs:
           conda install pip
           conda install setuptools wheel setuptools_scm
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-          pip install git+https://github.com/luk036/mywheel.git
           pip install -e .
           pytest

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

@@ -5,9 +5,9 @@ name: Python application
 
 on:
   push:
-    branches: [main]
+    branches: [ main, dev ]
   pull_request:
-    branches: [main]
+    branches: [ main, dev ]
 
 jobs:
   build:
@@ -15,16 +15,15 @@ jobs:
 
     steps:
       - uses: actions/checkout@v2
-      - name: Set up Python 3.9
+      - name: Set up Python 3.10
         uses: actions/setup-python@v2
         with:
-          python-version: 3.9
+          python-version: "3.10"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install flake8 pytest
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-          pip install git+https://github.com/luk036/mywheel.git
           python setup.py develop
       # - name: Lint with flake8
       #   run: |

{digraphx-0.3 → digraphx-0.5}/.gitignore

@@ -176,3 +176,7 @@ MANIFEST
 
 # my stuffs
 .hypothesis
+
+# Cache dirs
+.ruff_cache/
+.benchmarks/

digraphx-0.5/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 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.3/src/digraphx.egg-info → digraphx-0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digraphx
-Version: 0.3
+Version: 0.5
 Summary: Network Optimization Python Code
 Home-page: https://github.com/luk036/digraphx
 Author: Wai-Shing Luk
@@ -12,7 +12,8 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 License-File: LICENSE.txt
-Requires-Dist: importlib-metadata; python_version < "3.9"
+Requires-Dist: importlib-metadata; python_version < "3.10"
+Requires-Dist: mywheel>=0.3
 Requires-Dist: networkx
 Provides-Extra: testing
 Requires-Dist: setuptools; extra == "testing"

{digraphx-0.3 → digraphx-0.5}/docs/conf.py

@@ -83,6 +83,20 @@ extensions = [
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
     "sphinxcontrib.svgbob",
+    "matplotlib.sphinxext.plot_directive",
+]
+
+# -- matplotlib.sphinxext.plot_directive configuration -----------------------
+plot_html_show_source_link = True
+plot_html_show_formats = False
+plot_include_source = True
+plot_working_directory = os.path.join(__location__, "examples")
+plot_pre_code = [
+    "import matplotlib.pyplot as plt",
+    "import networkx as nx",
+    "import numpy as np",
+    "from digraphx.tiny_digraph import TinyDiGraph",
+    "plt.rcParams['figure.dpi'] = 100",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

digraphx-0.5/docs/examples/plot_cycle_detection.py

@@ -0,0 +1,32 @@
+"""
+Negative Cycle Detection
+========================
+
+Demonstrates negative cycle detection in a weighted directed graph.
+"""
+import matplotlib.pyplot as plt
+import networkx as nx
+
+g = nx.DiGraph()
+g.add_edge(1, 2, w=2)
+g.add_edge(2, 3, w=-3)
+g.add_edge(3, 1, w=1)
+g.add_edge(2, 4, w=1)
+g.add_edge(4, 5, w=-1)
+g.add_edge(5, 2, w=2)
+
+plt.figure(figsize=(7, 5))
+pos = nx.spring_layout(g, seed=42)
+nx.draw(
+    g,
+    pos,
+    with_labels=True,
+    node_color="lightcoral",
+    node_size=600,
+    arrowsize=20,
+    font_weight="bold",
+)
+edge_labels = {(u, v): f"w={d['w']}" for u, v, d in g.edges(data=True)}
+nx.draw_networkx_edge_labels(g, pos, edge_labels=edge_labels)
+plt.title("Directed Graph with Potential Negative Cycles")
+plt.grid(True, alpha=0.3)

digraphx-0.5/docs/examples/plot_tiny_digraph.py

@@ -0,0 +1,33 @@
+"""
+TinyDiGraph visualization
+=========================
+
+Example of creating and visualizing a directed graph using TinyDiGraph.
+"""
+import matplotlib.pyplot as plt
+import networkx as nx
+
+from digraphx.tiny_digraph import TinyDiGraph
+
+g = TinyDiGraph()
+g.init_nodes(5)
+g.add_edge(0, 1)
+g.add_edge(1, 2)
+g.add_edge(2, 3)
+g.add_edge(3, 0)
+g.add_edge(0, 4)
+g.add_edge(4, 2)
+
+plt.figure(figsize=(6, 5))
+pos = nx.spring_layout(g, seed=42)
+nx.draw(
+    g,
+    pos,
+    with_labels=True,
+    node_color="lightblue",
+    node_size=500,
+    arrowsize=20,
+    font_weight="bold",
+)
+plt.title("TinyDiGraph with 5 nodes and 6 edges")
+plt.grid(True, alpha=0.3)

digraphx-0.5/docs/figures_demo.md

@@ -0,0 +1,25 @@
+# Figures Demo
+
+Auto-generated figures demonstrating digraphx functionality.
+
+## TinyDiGraph Example
+
+```{plot} examples/plot_tiny_digraph.py
+```
+
+## Cycle Detection Example
+
+```{plot} examples/plot_cycle_detection.py
+```
+
+### Inline Plot Example
+
+```{plot}
+import matplotlib.pyplot as plt
+import numpy as np
+
+x = np.linspace(0, 2 * np.pi, 100)
+plt.plot(x, np.sin(x))
+plt.title("Simple Sine Wave")
+plt.grid(True, alpha=0.3)
+```

{digraphx-0.3 → digraphx-0.5}/docs/index.md

@@ -22,6 +22,7 @@ Contributions & Help <contributing>
 License <license>
 Authors <authors>
 Changelog <changelog>
+Figures Demo <figures_demo>
 Module Reference <api/modules>
 ```
 

digraphx-0.5/experimental/__init__.py

@@ -0,0 +1,5 @@
+"""Experimental / plotting utilities for digraphx.
+
+This module contains experimental code including the spare TSV
+network flow visualization utilities (requires matplotlib).
+"""

digraphx-0.5/experimental/spare_tsv.py

@@ -0,0 +1,190 @@
+"""Spare TSV network optimization utilities."""
+
+import math
+
+import matplotlib.pyplot as plt
+import networkx as nx
+import numpy as np
+
+
+def vdc(n, base=2):
+    """Van der Corput sequence."""
+    vdc, denom = 0.0, 1.0
+    while n:
+        denom *= base
+        n, remainder = divmod(n, base)
+        vdc += remainder / denom
+    return vdc
+
+
+def vdcorput(n, base=2):
+    """Generate n Van der Corput vectors as a list."""
+    return [vdc(i, base) for i in range(n)]
+
+
+def vdcorput_iter(n, base=2):
+    """Generate n Van der Corput vectors lazily (generator).
+
+    Yields values one at a time instead of allocating a full list.
+    """
+    for i in range(n):
+        yield vdc(i, base)
+
+
+def formGraph(T, pos, mu, eta, seed=None):
+    """Form N by N grid of nodes, perturb by mu and connect nodes within eta.
+
+    mu and eta are relative to 1/(N-1).
+    """
+    if seed is not None:
+        np.random.seed(seed)
+
+    N = int(np.sqrt(T))
+    mu = mu / (N - 1)
+    eta = eta / (N - 1)
+
+    pos = dict(enumerate(pos))
+    n = len(pos)
+
+    gra = nx.random_geometric_graph(n, eta, pos=pos)
+    gra = nx.DiGraph(gra)
+    return gra
+
+
+def showPaths(gra, pos, N, edgeProbs=1.0, path=None, visibleNodes=None, guards=None):
+    """Draw directed graph with optional path overlay.
+
+    Parameters
+    ----------
+    gra : nx.DiGraph
+        Directed graph.
+    pos : dict
+        Node positions {node: (x, y)}.
+    N : int
+        Number of primal nodes (drawn cyan).
+    edgeProbs : float or list
+        Edge probability/weights for coloring.
+    path : list of edges
+        Edges to highlight in blue.
+    visibleNodes : list
+        Nodes to draw (default: all).
+    guards : list
+        Nodes to highlight with black dots.
+    """
+    fig = plt.figure(figsize=(8, 6))
+    ax = fig.add_subplot(111, aspect="equal")
+
+    n = gra.number_of_nodes()
+    if visibleNodes is None:
+        visibleNodes = gra.nodes()
+    primalNodes = range(0, N)
+    spareNodes = range(N, n)
+
+    nx.draw_networkx_nodes(
+        gra, pos, nodelist=primalNodes, node_color="c", node_size=50, ax=ax
+    )
+    nx.draw_networkx_nodes(
+        gra, pos, nodelist=spareNodes, node_color="r", node_size=50, ax=ax
+    )
+
+    if guards is not None:
+        nx.draw_networkx_nodes(
+            gra, pos, nodelist=guards, node_color=".0", node_size=100, ax=ax
+        )
+
+    alpha = 1.0 if path is None else 0.15
+
+    # 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
+    ]
+
+    if isinstance(edgeProbs, float):
+        edgeProbs = [edgeProbs] * gra.number_of_edges()
+    p = [edgeProbs[i] for i, e in enumerate(edge_list) if e in visibleEdges]
+
+    nx.draw_networkx_edges(
+        gra,
+        pos,
+        edge_color=p,
+        width=1,
+        edge_cmap=plt.cm.RdYlGn,
+        arrows=False,
+        edgelist=visibleEdges,
+        edge_vmin=0.0,
+        edge_vmax=1.0,
+        ax=ax,
+        alpha=alpha,
+    )
+
+    if path is not None:
+        nx.draw_networkx_edges(
+            gra,
+            pos,
+            edge_color="b",
+            width=1,
+            edge_cmap=plt.cm.RdYlGn,
+            edgelist=path,
+            arrows=True,
+            edge_vmin=0.0,
+            edge_vmax=1.0,
+        )
+
+    ax.axis([-0.05, 1.05, -0.05, 1.05])
+    ax.axis("off")
+
+    return fig, ax
+
+
+def setup_network_flow(gra, pos, primal_count, capacity):
+    """Configure graph for spare TSV network flow.
+
+    Sets edge weights (Euclidean distance * 100), assigns demand=-1 to
+    primal nodes and demand=0 to spare nodes, then adds a sink node
+    connected to all spare nodes.
+
+    Returns the sink node index.
+    """
+    total = gra.number_of_nodes()
+    for u, v in gra.edges():
+        dx = pos[u][0] - pos[v][0]
+        dy = pos[u][1] - pos[v][1]
+        gra[u][v]["weight"] = int(math.sqrt(dx * dx + dy * dy) * 100)
+        gra[u][v]["capacity"] = capacity
+
+    for i in range(primal_count):
+        gra.nodes[i]["demand"] = -1
+    for i in range(primal_count, total):
+        gra.nodes[i]["demand"] = 0
+
+    sink = total
+    gra.add_node(sink, demand=primal_count)
+    for i in range(primal_count, total):
+        gra.add_edge(i, sink, capacity=capacity)
+
+    return sink
+
+
+def solve_network_flow(gra, sink_node):
+    """Solve network flow and return path edges.
+
+    Returns (flow_cost, path_list) where path_list contains edges
+    with positive flow (excluding edges to the sink).
+
+    Returns None if the problem is infeasible.
+    """
+    try:
+        flow_cost, flow_dict = nx.network_simplex(gra)
+    except nx.NetworkXUnfeasible:
+        return None
+
+    path_list = [
+        (u, v)
+        for u in flow_dict
+        for v in flow_dict[u]
+        if flow_dict[u][v] > 0 and v != sink_node
+    ]
+    return flow_cost, path_list

digraphx-0.5/experimental/test_spare_tsv.py

@@ -0,0 +1,170 @@
+"""Tests for spareTSV (experimental)."""
+
+import networkx as nx
+import pytest
+
+from experimental.spare_tsv import (
+    formGraph,
+    setup_network_flow,
+    showPaths,
+    solve_network_flow,
+    vdc,
+    vdcorput,
+    vdcorput_iter,
+)
+
+
+def _vdc(n, base=2):
+    v, denom = 0.0, 1.0
+    while n:
+        denom *= base
+        n, remainder = divmod(n, base)
+        v += remainder / denom
+    return v
+
+
+@pytest.fixture
+def sample_positions():
+    """Van der Corput positions (T=12, bases 2/3)."""
+    T = 12
+    xbase, ybase = 2, 3
+    x = [_vdc(i, xbase) for i in range(T)]
+    y = [_vdc(i, ybase) for i in range(T)]
+    return list(zip(x, y))
+
+
+@pytest.fixture
+def small_graph(sample_positions):
+    """Small geometric graph for spareTSV tests."""
+    return formGraph(12, sample_positions, 0.12, 1.6, seed=5)
+
+
+def test_vdc():
+    result = vdc(1, base=2)
+    assert result == 0.5
+
+
+def test_vdc_sequence_base_2():
+    vals = [vdc(i, base=2) for i in range(4)]
+    assert vals == [0.0, 0.5, 0.25, 0.75]
+
+
+def test_vdc_sequence_base_3():
+    vals = [vdc(i, base=3) for i in range(3)]
+    assert vals == [0.0, 1 / 3, 2 / 3]
+
+
+def test_vdcorput():
+    result = vdcorput(5, base=2)
+    assert len(result) == 5
+    assert all(0 <= x < 1 for x in result)
+
+
+def test_vdcorput_iter():
+    result = list(vdcorput_iter(5, base=2))
+    assert len(result) == 5
+    assert result == vdcorput(5, base=2)
+
+
+def test_formGraph(sample_positions):
+    gra = formGraph(12, sample_positions, 0.12, 1.6, seed=5)
+    assert gra.number_of_nodes() == 12
+    assert gra.is_directed()
+
+
+def test_formGraph_reproducible(sample_positions):
+    g1 = formGraph(12, sample_positions, 0.12, 1.6, seed=42)
+    g2 = formGraph(12, sample_positions, 0.12, 1.6, seed=42)
+    assert g1.number_of_edges() == g2.number_of_edges()
+
+
+def test_formGraph_no_seed(sample_positions):
+    gra = formGraph(12, sample_positions, 0.12, 1.6)
+    assert gra.number_of_nodes() == 12
+    assert gra.is_directed()
+
+
+def test_showPaths(small_graph, sample_positions):
+    N = 9
+    pos = dict(enumerate(sample_positions))
+    fig, ax = showPaths(small_graph, pos, N)
+    assert fig is not None
+    assert ax is not None
+
+
+def test_showPaths_with_options(small_graph, sample_positions):
+    N = 9
+    pos = dict(enumerate(sample_positions))
+    edges = list(small_graph.edges())[:3]
+    edge_probs = [0.5] * small_graph.number_of_edges()
+    vis = list(range(9))
+    fig, ax = showPaths(
+        small_graph,
+        pos,
+        N,
+        edgeProbs=edge_probs,
+        path=edges,
+        visibleNodes=vis,
+        guards=[0, 1],
+    )
+    assert fig is not None
+    assert ax is not None
+
+
+def test_setup_network_flow(small_graph, sample_positions):
+    gra = small_graph.copy()
+    total = gra.number_of_nodes()
+    sink = setup_network_flow(gra, sample_positions, primal_count=9, capacity=4)
+
+    assert sink == total
+    assert gra.number_of_nodes() == total + 1
+    assert gra.has_node(sink)
+    assert gra.nodes[0]["demand"] == -1
+    assert gra.nodes[9]["demand"] == 0
+    assert gra.nodes[sink]["demand"] == 9
+
+
+def test_setup_network_flow_edge_attrs(small_graph, sample_positions):
+    gra = small_graph.copy()
+    setup_network_flow(gra, sample_positions, primal_count=9, capacity=4)
+
+    u, v = next(iter(gra.edges()))
+    assert "weight" in gra[u][v]
+    assert "capacity" in gra[u][v]
+    assert gra[u][v]["capacity"] == 4
+    assert isinstance(gra[u][v]["weight"], int)
+
+
+def test_solve_network_flow(small_graph, sample_positions):
+    gra = small_graph.copy()
+    sink = setup_network_flow(gra, sample_positions, primal_count=9, capacity=4)
+    result = solve_network_flow(gra, sink)
+
+    assert result is not None
+    flow_cost, path_list = result
+    assert isinstance(path_list, list)
+    assert flow_cost >= 0
+
+
+def test_solve_network_flow_path_excludes_sink(small_graph, sample_positions):
+    gra = small_graph.copy()
+    sink = setup_network_flow(gra, sample_positions, primal_count=9, capacity=4)
+    result = solve_network_flow(gra, sink)
+
+    assert result is not None
+    _, path_list = result
+    for u, v in path_list:
+        assert v != sink
+
+
+def test_solve_network_flow_infeasible():
+    gra = nx.DiGraph()
+    gra.add_node(0, demand=-1)
+    gra.add_node(1, demand=0)
+    gra.add_edge(0, 1, weight=1, capacity=0)
+    sink = 2
+    gra.add_node(sink, demand=1)
+    gra.add_edge(1, sink, capacity=0)
+
+    result = solve_network_flow(gra, sink)
+    assert result is None

digraphx-0.5/experiments/experi-descent-new.py

@@ -0,0 +1,79 @@
+# Experiment: spare TSV network flow optimization using cycle-cancellation descent
+
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt  # noqa: E402
+
+from digraphx.mcf import cycle_canceling_mcf  # noqa: E402
+from experimental.spare_tsv import (  # noqa: E402
+    formGraph,
+    setup_network_flow,
+    showPaths,
+    vdcorput,
+)
+
+
+def nx_to_dict_graph(gra, sink):
+    """Convert networkx graph to dict-of-dicts for cycle_canceling_mcf.
+
+    Extracts weight/capacity from edge data and demand from node data.
+    Excludes the sink node (added separately by setup logic).
+    """
+    g = {}
+    demands = {}
+    for u in gra.nodes():
+        d = gra.nodes[u].get("demand", 0)
+        if d != 0 or u == sink:
+            demands[u] = d
+    for u, v, data in gra.edges(data=True):
+        if u not in g:
+            g[u] = {}
+        g[u][v] = {
+            "weight": data.get("weight", 0),
+            "capacity": data.get("capacity", 1),
+        }
+    return g, demands
+
+
+N = 155
+M = 40
+r = 4
+
+T = N + M
+xbase = 2
+ybase = 3
+x = [i for i in vdcorput(T, xbase)]
+y = [i for i in vdcorput(T, ybase)]
+pos = list(zip(x, y))
+gra = formGraph(T, pos, 0.12, 1.6, seed=5)
+pos2 = dict(enumerate(pos))
+fig, ax = showPaths(gra, pos2, N)
+fig.savefig("spareTSV-initial.svg")
+plt.close(fig)
+
+# Set up the network flow graph (weights, capacities, demands, sink)
+sink = setup_network_flow(gra, pos, primal_count=N, capacity=r)
+
+# Convert to dict-of-dicts format and solve via cycle-cancellation descent
+g, demands = nx_to_dict_graph(gra, sink)
+result = cycle_canceling_mcf(g, demands, sink=sink)
+
+if result is None:
+    print("Solution Infeasible!")
+else:
+    flow_cost, flow_dict = result
+    print(f"Flow cost: {flow_cost}")
+
+    # Extract path edges with positive flow, excluding sink
+    pathlist = [
+        (u, v)
+        for u in flow_dict
+        for v, f in flow_dict[u].items()
+        if f > 0 and v != sink
+    ]
+
+    gra.remove_node(sink)
+    fig, ax = showPaths(gra, pos2, N, path=pathlist)
+    fig.savefig("spareTSV-solution.svg")
+    plt.close(fig)