Release v0.2.2: Fix EqualBalanced flow placement

Author: networmix

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.2] - 2025-12-05
+
+### Fixed
+
+- **Flow Placement**: EqualBalanced placement now correctly returns 0 when the shortest path has no capacity with `require_capacity=False`. Previously, flow could be incorrectly reported on partial paths that didn't reach the destination.
+
 ## [0.2.1] - 2025-12-01
 
 ### Fixed

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "netgraph-core"
-version = "0.2.1"
+version = "0.2.2"
 description = "C++ implementation of graph algorithms for network flow analysis and traffic engineering with Python bindings"
 readme = "README.md"
 requires-python = ">=3.9"

python/netgraph_core/_version.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"

src/flow_state.cpp

@@ -341,6 +341,14 @@ Flow FlowState::place_on_dag(NodeId src, NodeId dst, const PredDAG& dag,
       }
     }
 
+    // Early exit if destination is not reachable with capacity.
+    // With require_capacity=false, SPF includes zero-capacity edges in the DAG,
+    // but those edges are filtered out during group building. If no path with
+    // capacity reaches the destination, return 0.
+    if (inflow[static_cast<std::size_t>(dst)] < kEpsilon) {
+      return static_cast<Flow>(0.0);
+    }
+
     // Single-pass ECMP admission: scale the unit assignment by the smallest
     // per-group headroom so that no edge is oversubscribed under *fixed equal
     // per-edge splits*. Any further injection with the same splits would violate

tests/cpp/flow_state_tests.cpp

@@ -377,3 +377,58 @@ TEST(FlowState, EqualBalanced_DownstreamSplitEqualization) {
   EXPECT_NEAR(ef[3], 5.0, 1e-9); // 2->4
   EXPECT_NEAR(ef[4], 5.0, 1e-9); // 3->4
 }
+
+TEST(FlowState, EqualBalanced_ZeroCapacityOnShortestPath_ReturnsZero) {
+  // With require_capacity=false (true IP/IGP semantics), routing is cost-only.
+  // If the shortest path has a zero-capacity edge, no flow can be placed.
+  // Graph: 0->1 (cap 0, cost 1) -> 2 (cap 10, cost 1)  [shortest path, but no capacity]
+  //        0->3 (cap 100, cost 2) -> 2 (cap 100, cost 2)  [longer path with capacity]
+  std::int32_t src[4]  = {0, 1, 0, 3};
+  std::int32_t dst[4]  = {1, 2, 3, 2};
+  double       cap[4]  = {0.0, 10.0, 100.0, 100.0};  // 0->1 has zero capacity!
+  std::int64_t cost[4] = {1,   1,    2,     2};
+  auto g = StrictMultiDiGraph::from_arrays(4,
+    std::span(src, 4), std::span(dst, 4),
+    std::span(cap, 4), std::span(cost, 4));
+  FlowState fs(g);
+
+  // Build DAG with require_capacity=false (cost-only routing, ignores capacity).
+  // This simulates true IP/IGP behavior where routes are based purely on cost.
+  EdgeSelection sel; sel.multi_edge = true; sel.require_capacity = false; sel.tie_break = EdgeTieBreak::Deterministic;
+  auto [dist, dag] = shortest_paths(g, 0, 2, /*multipath=*/true, sel, {}, {}, {});
+
+  // Verify SPF found a path (the zero-capacity one is included in the DAG).
+  // The shortest path 0->1->2 has cost 2, while 0->3->2 has cost 4.
+  EXPECT_LT(dist[2], std::numeric_limits<Cost>::max());
+
+  // Attempt EqualBalanced placement. Since the shortest path has no capacity,
+  // and we're in single-tier mode (simulated by only having one DAG),
+  // placement should return 0.
+  Flow placed = fs.place_on_dag(0, 2, dag, std::numeric_limits<double>::infinity(), FlowPlacement::EqualBalanced);
+  EXPECT_NEAR(placed, 0.0, 1e-9) << "EqualBalanced should return 0 when shortest path has no capacity";
+
+  // Verify no edge flows were placed
+  auto ef = fs.edge_flow_view();
+  for (std::size_t i = 0; i < static_cast<std::size_t>(g.num_edges()); ++i) {
+    EXPECT_NEAR(ef[i], 0.0, 1e-9) << "Edge " << i << " should have no flow";
+  }
+}
+
+TEST(FlowState, Proportional_ZeroCapacityOnShortestPath_ReturnsZero) {
+  // With require_capacity=false, if the shortest path has a zero-capacity edge,
+  // no flow can be placed. Both placements behave consistently.
+  std::int32_t src[4]  = {0, 1, 0, 3};
+  std::int32_t dst[4]  = {1, 2, 3, 2};
+  double       cap[4]  = {0.0, 10.0, 100.0, 100.0};
+  std::int64_t cost[4] = {1,   1,    2,     2};
+  auto g = StrictMultiDiGraph::from_arrays(4,
+    std::span(src, 4), std::span(dst, 4),
+    std::span(cap, 4), std::span(cost, 4));
+  FlowState fs(g);
+
+  EdgeSelection sel; sel.multi_edge = true; sel.require_capacity = false; sel.tie_break = EdgeTieBreak::Deterministic;
+  auto [dist, dag] = shortest_paths(g, 0, 2, /*multipath=*/true, sel, {}, {}, {});
+
+  Flow placed = fs.place_on_dag(0, 2, dag, std::numeric_limits<double>::infinity(), FlowPlacement::Proportional);
+  EXPECT_NEAR(placed, 0.0, 1e-9) << "Proportional should return 0 when shortest path has no capacity";
+}

tests/py/test_edge_cases.py

@@ -80,3 +80,97 @@ def test_ksp_distance_dtype_int64_exact(algs):
         dist_i64 = np.asarray(dist_i64)
         assert dist_i64.dtype == np.int64
         assert int(dist_i64[2]) == int(big + big)
+
+
+def test_max_flow_zero_capacity_on_shortest_path_equal_balanced(algs, to_handle):
+    """EqualBalanced with require_capacity=False returns 0 when shortest path has no capacity.
+
+    With require_capacity=False (true IP/IGP semantics), routing is cost-only.
+    If the shortest path has a zero-capacity edge, no flow can be placed.
+
+    Topology:
+        Shortest path: 0->1->2 (cost 2, but 0->1 has cap=0)
+        Longer path:   0->3->2 (cost 4, cap=100)
+    """
+    src = np.array([0, 1, 0, 3], dtype=np.int32)
+    dst = np.array([1, 2, 3, 2], dtype=np.int32)
+    cap = np.array(
+        [0.0, 10.0, 100.0, 100.0], dtype=np.float64
+    )  # 0->1 has zero capacity
+    cost = np.array([1, 1, 2, 2], dtype=np.int64)
+    g = ngc.StrictMultiDiGraph.from_arrays(4, src, dst, cap, cost)
+
+    # Test with EqualBalanced + require_capacity=False + shortest_path=True
+    total, summary = algs.max_flow(
+        to_handle(g),
+        0,
+        2,
+        flow_placement=ngc.FlowPlacement.EQUAL_BALANCED,
+        shortest_path=True,
+        require_capacity=False,
+        with_edge_flows=True,
+    )
+
+    # Should return 0 because the shortest path (cost 2) has no capacity
+    assert np.isclose(total, 0.0), (
+        f"Expected 0 flow when shortest path has zero capacity, got {total}"
+    )
+
+    # Verify no edge flows were placed
+    edge_flows = np.asarray(summary.edge_flows)
+    assert np.allclose(edge_flows, 0.0), f"Expected no edge flows, got {edge_flows}"
+
+
+def test_max_flow_zero_capacity_on_shortest_path_proportional(algs, to_handle):
+    """Proportional with require_capacity=False returns 0 when shortest path has no capacity.
+
+    With require_capacity=False, if the shortest path has a zero-capacity edge,
+    no flow can be placed. Both placements behave consistently.
+    """
+    src = np.array([0, 1, 0, 3], dtype=np.int32)
+    dst = np.array([1, 2, 3, 2], dtype=np.int32)
+    cap = np.array([0.0, 10.0, 100.0, 100.0], dtype=np.float64)
+    cost = np.array([1, 1, 2, 2], dtype=np.int64)
+    g = ngc.StrictMultiDiGraph.from_arrays(4, src, dst, cap, cost)
+
+    total, summary = algs.max_flow(
+        to_handle(g),
+        0,
+        2,
+        flow_placement=ngc.FlowPlacement.PROPORTIONAL,
+        shortest_path=True,
+        require_capacity=False,
+        with_edge_flows=True,
+    )
+
+    assert np.isclose(total, 0.0), (
+        f"Expected 0 flow when shortest path has zero capacity, got {total}"
+    )
+
+
+def test_max_flow_require_capacity_true_finds_alternative(algs, to_handle):
+    """With require_capacity=True, max_flow should find an alternative path with capacity.
+
+    This is the contrast test: when require_capacity=True, the algorithm should
+    skip the zero-capacity edge and find the longer path that has capacity.
+    """
+    src = np.array([0, 1, 0, 3], dtype=np.int32)
+    dst = np.array([1, 2, 3, 2], dtype=np.int32)
+    cap = np.array([0.0, 10.0, 100.0, 100.0], dtype=np.float64)
+    cost = np.array([1, 1, 2, 2], dtype=np.int64)
+    g = ngc.StrictMultiDiGraph.from_arrays(4, src, dst, cap, cost)
+
+    total, summary = algs.max_flow(
+        to_handle(g),
+        0,
+        2,
+        flow_placement=ngc.FlowPlacement.EQUAL_BALANCED,
+        shortest_path=True,
+        require_capacity=True,  # This should skip zero-capacity edges
+        with_edge_flows=True,
+    )
+
+    # Should find the longer path 0->3->2 and place 100 flow
+    assert np.isclose(total, 100.0), (
+        f"Expected 100 flow via alternative path, got {total}"
+    )