added ksp

Author: networmix

bindings/python/module.cpp

@@ -31,7 +31,11 @@ PYBIND11_MODULE(_netgraph_core, m) {
   py::enum_<EdgeSelect>(m, "EdgeSelect")
       .value("ALL_MIN_COST", EdgeSelect::AllMinCost)
       .value("SINGLE_MIN_COST", EdgeSelect::SingleMinCost)
-      .value("ALL_MIN_COST_WITH_CAP_REMAINING", EdgeSelect::AllMinCostWithCapRemaining);
+      .value("ALL_MIN_COST_WITH_CAP_REMAINING", EdgeSelect::AllMinCostWithCapRemaining)
+      .value("ALL_ANY_COST_WITH_CAP_REMAINING", EdgeSelect::AllAnyCostWithCapRemaining)
+      .value("SINGLE_MIN_COST_WITH_CAP_REMAINING", EdgeSelect::SingleMinCostWithCapRemaining)
+      .value("SINGLE_MIN_COST_WITH_CAP_REMAINING_LOAD_FACTORED", EdgeSelect::SingleMinCostWithCapRemainingLoadFactored)
+      .value("USER_DEFINED", EdgeSelect::UserDefined);
 
   py::enum_<FlowPlacement>(m, "FlowPlacement")
       .value("PROPORTIONAL", FlowPlacement::Proportional)
@@ -176,19 +180,6 @@ PYBIND11_MODULE(_netgraph_core, m) {
           return py::make_tuple(std::move(dist_arr), res.second);
         }, py::arg("g"), py::arg("src"), py::arg("dst") = py::none(), py::kw_only(), py::arg("edge_select") = EdgeSelect::AllMinCost, py::arg("multipath") = true, py::arg("node_mask") = py::none(), py::arg("edge_mask") = py::none(), py::arg("eps") = 1e-10);
 
-  py::class_<Path>(m, "Path")
-      .def_property_readonly("nodes", [](const Path& p){
-        py::array_t<std::int32_t> arr(p.nodes.size());
-        std::memcpy(arr.mutable_data(), p.nodes.data(), p.nodes.size()*sizeof(std::int32_t));
-        return arr;
-      })
-      .def_property_readonly("edges", [](const Path& p){
-        py::array_t<std::int32_t> arr(p.edges.size());
-        std::memcpy(arr.mutable_data(), p.edges.data(), p.edges.size()*sizeof(std::int32_t));
-        return arr;
-      })
-      .def_readonly("cost", &Path::cost);
-
   m.def("ksp",
         [](const StrictMultiDiGraph& g, std::int32_t src, std::int32_t dst,
            int k, py::object max_cost_factor, bool unique, py::object node_mask, py::object edge_mask, double eps) {
@@ -209,9 +200,17 @@ PYBIND11_MODULE(_netgraph_core, m) {
             if (static_cast<std::size_t>(buf.shape[0]) != static_cast<std::size_t>(g.num_edges())) throw py::type_error("edge_mask length must equal num_edges");
           }
           py::gil_scoped_release release;
-          auto paths = k_shortest_paths(g, src, dst, k, mcf, unique, eps);
+          auto items = k_shortest_paths(g, src, dst, k, mcf, unique, eps);
           py::gil_scoped_acquire acquire;
-          return paths;
+          // Convert to list of (dist ndarray, PredDAG)
+          py::list out;
+          for (auto& pr : items) {
+            auto& dist = pr.first;
+            py::array_t<double> dist_arr(dist.size());
+            std::memcpy(dist_arr.mutable_data(), dist.data(), dist.size()*sizeof(double));
+            out.append(py::make_tuple(std::move(dist_arr), pr.second));
+          }
+          return out;
         }, py::arg("g"), py::arg("src"), py::arg("dst"), py::kw_only(), py::arg("k"), py::arg("max_cost_factor") = py::none(), py::arg("unique") = true, py::arg("node_mask") = py::none(), py::arg("edge_mask") = py::none(), py::arg("eps") = 1e-10);
 
   py::class_<MinCut>(m, "MinCut")
@@ -256,6 +255,49 @@ PYBIND11_MODULE(_netgraph_core, m) {
           return res;
         }, py::arg("g"), py::arg("src"), py::arg("dst"), py::kw_only(), py::arg("flow_placement") = FlowPlacement::Proportional, py::arg("shortest_path") = false, py::arg("eps") = 1e-10, py::arg("with_edge_flows") = false, py::arg("node_mask") = py::none(), py::arg("edge_mask") = py::none());
 
+  // Residual-aware SPF (exposes selection variants requiring capacity/flow)
+  m.def("spf_residual",
+        [](const StrictMultiDiGraph& g, std::int32_t src, py::object dst,
+           EdgeSelect policy, bool multipath, double eps,
+           py::array residual, py::object node_mask, py::object edge_mask) {
+          std::optional<std::int32_t> dst_opt;
+          if (!dst.is_none()) dst_opt = py::cast<std::int32_t>(dst);
+          // residual must be 1-D float64 of length num_edges
+          if (!(py::isinstance<py::array_t<double>>(residual))) {
+            throw py::type_error("residual must be a numpy float64 array");
+          }
+          if (!(residual.flags() & py::array::c_style)) {
+            throw py::type_error("residual must be C-contiguous (np.ascontiguousarray)");
+          }
+          auto rbuf = residual.request();
+          if (rbuf.ndim != 1 || static_cast<std::size_t>(rbuf.shape[0]) != static_cast<std::size_t>(g.num_edges())) {
+            throw py::type_error("residual length must equal num_edges");
+          }
+          std::vector<double> residual_vec(static_cast<std::size_t>(rbuf.shape[0]));
+          std::memcpy(residual_vec.data(), rbuf.ptr, residual_vec.size()*sizeof(double));
+          const bool* node_ptr = nullptr; const bool* edge_ptr = nullptr; py::array node_arr, edge_arr;
+          if (!node_mask.is_none()) {
+            node_arr = py::cast<py::array>(node_mask);
+            auto b = node_arr.request();
+            if (b.ndim != 1 || b.format != py::format_descriptor<bool>::format() || static_cast<std::size_t>(b.shape[0]) != static_cast<std::size_t>(g.num_nodes())) {
+              throw py::type_error("node_mask must be 1-D bool and length=num_nodes");
+            }
+            node_ptr = static_cast<const bool*>(b.ptr);
+          }
+          if (!edge_mask.is_none()) {
+            edge_arr = py::cast<py::array>(edge_mask);
+            auto b = edge_arr.request();
+            if (b.ndim != 1 || b.format != py::format_descriptor<bool>::format() || static_cast<std::size_t>(b.shape[0]) != static_cast<std::size_t>(g.num_edges())) {
+              throw py::type_error("edge_mask must be 1-D bool and length=num_edges");
+            }
+            edge_ptr = static_cast<const bool*>(b.ptr);
+          }
+          py::gil_scoped_release rel;
+          auto res = shortest_paths_with_residual(g, src, dst_opt, policy, multipath, eps, residual_vec, node_ptr, edge_ptr);
+          py::gil_scoped_acquire acq;
+          return res;
+        }, py::arg("g"), py::arg("src"), py::arg("dst") = py::none(), py::arg("edge_select") = EdgeSelect::AllMinCostWithCapRemaining, py::arg("multipath") = true, py::arg("eps") = 1e-12, py::arg("residual"), py::arg("node_mask") = py::none(), py::arg("edge_mask") = py::none());
+
   m.def("max_flow",
         [](const StrictMultiDiGraph& g, std::int32_t src, std::int32_t dst,
            FlowPlacement placement, bool shortest_path, double eps, bool with_edge_flows,

dev/run-checks.sh

@@ -108,6 +108,9 @@ echo ""
 
 # Run Python tests (with coverage if available)
 echo "🧪 Running Python tests..."
+# Ensure the extension is built for the active Python and importable
+echo "🔧 Installing project in editable mode for current Python..."
+"$PYTHON" -m pip install -e . >/dev/null
 if "$PYTHON" -c "import pytest_cov" >/dev/null 2>&1; then
     "$PYTHON" -m pytest --cov=netgraph_core --cov-report=term-missing
 else

include/netgraph/core/k_shortest_paths.hpp

@@ -4,17 +4,17 @@
 #include <vector>
 
 #include "netgraph/core/strict_multidigraph.hpp"
+#include "netgraph/core/shortest_paths.hpp"
 #include "netgraph/core/types.hpp"
 
 namespace netgraph::core {
 
-struct Path {
-  std::vector<NodeId> nodes;
-  std::vector<EdgeId> edges;
-  double cost {0.0};
-};
-
-std::vector<Path> k_shortest_paths(
+// Compute up to k shortest paths from s to t (Yen-like) and return
+// SPF-compatible outputs per path: (distances, predecessor DAG).
+// Distances are float64[N], PredDAG encodes one concrete path with single parent
+// per node along the path; other nodes have no parents and dist=inf.
+// Deterministic tie-breaking across equal-cost edges uses compacted edge order.
+std::vector<std::pair<std::vector<double>, PredDAG>> k_shortest_paths(
     const StrictMultiDiGraph& g, NodeId s, NodeId t,
     int k, std::optional<double> max_cost_factor,
     bool unique, double eps);

include/netgraph/core/shortest_paths.hpp

@@ -31,4 +31,16 @@ shortest_paths(const StrictMultiDiGraph& g, NodeId src,
                const bool* node_mask = nullptr,
                const bool* edge_mask = nullptr);
 
+// Residual-aware shortest paths: like shortest_paths but considers per-edge
+// residual capacities (residual[e] = remaining capacity). Some EdgeSelect
+// policies require residual/capacity/load (e.g., load-factored). When residual
+// is provided, edges with residual < MIN_CAP are excluded.
+std::pair<std::vector<double>, PredDAG>
+shortest_paths_with_residual(const StrictMultiDiGraph& g, NodeId src,
+                             std::optional<NodeId> dst,
+                             EdgeSelect policy, bool multipath, double eps,
+                             const std::vector<double>& residual,
+                             const bool* node_mask = nullptr,
+                             const bool* edge_mask = nullptr);
+
 } // namespace netgraph::core

include/netgraph/core/types.hpp

@@ -13,7 +13,11 @@ using Cap    = double;
 enum class EdgeSelect {
   AllMinCost = 1,
   SingleMinCost = 2,
-  AllMinCostWithCapRemaining = 3
+  AllMinCostWithCapRemaining = 3,
+  AllAnyCostWithCapRemaining = 4,
+  SingleMinCostWithCapRemaining = 5,
+  SingleMinCostWithCapRemainingLoadFactored = 6,
+  UserDefined = 99
 };
 
 enum class FlowPlacement {

pyproject.toml

@@ -14,15 +14,14 @@ version = "0.1.0"
 description = "Native C++ engine for NetGraph with Python bindings (CPU today, GPU-ready)"
 readme = "README.md"
 requires-python = ">=3.9"
-license = { file = "LICENSE" }
+license = "AGPL-3.0-or-later"
 authors = [{ name = "NetGraph Contributors" }]
 classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: C++",
     "Programming Language :: Python :: Implementation :: CPython",
     "Operating System :: OS Independent",
-    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
 ]
 dependencies = ["numpy>=1.22"]
 

python/netgraph_core/__init__.py

@@ -7,30 +7,48 @@
     FlowPlacement,
     FlowSummary,
     MinCut,
-    Path,
     PredDAG,
     StrictMultiDiGraph,
     batch_max_flow,
     calc_max_flow,
     ksp,
     max_flow,
     spf,
+    spf_residual,
 )
 
 from ._version import __version__
 
+# Provide richer type information for editors/type-checkers without affecting runtime.
+try:  # pragma: no cover - typing-only import
+    from typing import TYPE_CHECKING as _TYPE_CHECKING
+
+    if _TYPE_CHECKING:  # noqa: SIM108
+        from ._docs import (  # noqa: I001
+            CostBucket as CostBucket,
+            CostDistribution as CostDistribution,
+            EdgeSelect as EdgeSelect,
+            FlowPlacement as FlowPlacement,
+            FlowSummary as FlowSummary,
+            MinCut as MinCut,
+            PredDAG as PredDAG,
+        )
+except Exception:
+    # Safe fallback if _docs.py changes; runtime bindings above remain authoritative.
+    pass
+
 __all__ = [
     "__version__",
     "StrictMultiDiGraph",
     "spf",
     "ksp",
     "calc_max_flow",
     "max_flow",
+    "spf_residual",
     "batch_max_flow",
     "EdgeSelect",
     "FlowPlacement",
     "PredDAG",
-    "Path",
     "MinCut",
     "CostBucket",
     "CostDistribution",

python/netgraph_core/_docs.py

@@ -16,17 +16,33 @@
 
 
 class EdgeSelect(Enum):
+    """Edge selection policies for shortest-path traversal.
+
+    Mirrors netgraph.core.types.EdgeSelect (C++ enum).
+    """
+
     ALL_MIN_COST = 1
     SINGLE_MIN_COST = 2
     ALL_MIN_COST_WITH_CAP_REMAINING = 3
+    ALL_ANY_COST_WITH_CAP_REMAINING = 4
+    SINGLE_MIN_COST_WITH_CAP_REMAINING = 5
+    SINGLE_MIN_COST_WITH_CAP_REMAINING_LOAD_FACTORED = 6
+    USER_DEFINED = 99
 
 
 class FlowPlacement(Enum):
+    """How to place flow across equal-cost predecessors during augmentation."""
+
     PROPORTIONAL = 1
     EQUAL_BALANCED = 2
 
 
 class PredDAG:
+    """Compact predecessor DAG representation.
+
+    Arrays are int32; offsets has length N+1.
+    """
+
     parent_offsets: np.ndarray
     parents: np.ndarray
     via_edges: np.ndarray
@@ -57,6 +73,26 @@ def spf(
     ...
 
 
+def spf_residual(
+    g: "StrictMultiDiGraph",
+    src: int,
+    dst: Optional[int] = None,
+    *,
+    edge_select: EdgeSelect = EdgeSelect.ALL_MIN_COST_WITH_CAP_REMAINING,
+    multipath: bool = True,
+    eps: float = 1e-12,
+    residual: np.ndarray | list[float] = ...,
+    node_mask: Optional[np.ndarray] = None,
+    edge_mask: Optional[np.ndarray] = None,
+):
+    """Residual-aware shortest paths wrapper.
+
+    Uses per-edge residual capacities to filter/select edges.
+    Returns: (dist: float64[N], pred: PredDAG)
+    """
+    ...
+
+
 def ksp(
     g: "StrictMultiDiGraph",
     src: int,
@@ -83,3 +119,42 @@ def calc_max_flow(
     node_mask: Optional[np.ndarray] = None,
     edge_mask: Optional[np.ndarray] = None,
 ): ...
+
+
+@dataclass(frozen=True)
+class CostBucket:
+    cost: float
+    share: float
+
+
+@dataclass(frozen=True)
+class CostDistribution:
+    buckets: list[CostBucket]
+
+
+@dataclass(frozen=True)
+class MinCut:
+    edges: list[int]
+
+
+@dataclass(frozen=True)
+class FlowSummary:
+    total_flow: float
+    min_cut: MinCut
+    cost_distribution: CostDistribution
+    edge_flows: list[float]
+
+
+def batch_max_flow(
+    g: "StrictMultiDiGraph",
+    pairs: np.ndarray,
+    *,
+    flow_placement: FlowPlacement = FlowPlacement.PROPORTIONAL,
+    shortest_path: bool = False,
+    eps: float = 1e-10,
+    with_edge_flows: bool = False,
+    threads: Optional[int] = None,
+    seed: Optional[int] = None,
+    node_masks: Optional[list[np.ndarray]] = None,
+    edge_masks: Optional[list[np.ndarray]] = None,
+) -> list[FlowSummary]: ...