streamlined implementation

Author: networmix

CMakeLists.txt

@@ -1,5 +1,7 @@
 cmake_minimum_required(VERSION 3.23)
 project(netgraph_core LANGUAGES CXX)
+# Silence pybind11 FindPython compatibility warning by selecting the modern mode
+set(PYBIND11_FINDPYTHON NEW CACHE STRING "Use modern FindPython in pybind11")
 # Optional C++ tests
 option(NETGRAPH_CORE_BUILD_TESTS "Build C++ unit tests" OFF)
 if(NETGRAPH_CORE_BUILD_TESTS)
@@ -57,6 +59,7 @@ if(NOT pybind11_FOUND)
   FetchContent_MakeAvailable(pybind11)
 endif()
 
+
 add_library(netgraph_core STATIC
   src/strict_multidigraph.cpp
   src/shortest_paths.cpp

Makefile

@@ -6,7 +6,8 @@
 
 VENV_BIN := $(PWD)/venv/bin
 # Use dynamic (recursive) assignment so a newly created venv is picked up
-PYTHON = $(if $(wildcard $(VENV_BIN)/python),$(VENV_BIN)/python,python3)
+PY_FIND := $(shell command -v python3.13 2>/dev/null || command -v python3 2>/dev/null)
+PYTHON = $(if $(wildcard $(VENV_BIN)/python),$(VENV_BIN)/python,$(PY_FIND))
 PIP = $(PYTHON) -m pip
 PYTEST = $(PYTHON) -m pytest
 RUFF = $(PYTHON) -m ruff
@@ -46,7 +47,7 @@ dev:
 	@echo "🚀 Setting up development environment..."
 	@if [ ! -x "$(VENV_BIN)/python" ]; then \
 		echo "🐍 Creating virtual environment in ./venv ..."; \
-		python3 -m venv venv; \
+		$(PY_FIND) -m venv venv; \
 		$(VENV_BIN)/python -m pip install -U pip wheel; \
 	fi
 	@echo "📦 Installing dev dependencies..."
@@ -57,7 +58,7 @@ dev:
 
 venv:
 	@echo "🐍 Creating virtual environment in ./venv ..."
-	@python3 -m venv venv
+	@$(PY_FIND) -m venv venv
 	@$(VENV_BIN)/python -m pip install -U pip wheel
 	@echo "✅ venv ready. Activate with: source venv/bin/activate"
 

bindings/python/module.cpp

@@ -0,0 +1,51 @@
+/* Algorithms façade that forwards to a selected Backend implementation. */
+#pragma once
+
+#include <memory>
+
+#include "netgraph/core/backend.hpp"
+#include "netgraph/core/options.hpp"
+
+namespace netgraph::core {
+
+class Algorithms {
+public:
+  explicit Algorithms(BackendPtr backend) : backend_(std::move(backend)) {}
+
+  [[nodiscard]] GraphHandle build_graph(const StrictMultiDiGraph& g) const {
+    return backend_->build_graph(g);
+  }
+
+  [[nodiscard]] GraphHandle build_graph(std::shared_ptr<const StrictMultiDiGraph> g) const {
+    return backend_->build_graph(std::move(g));
+  }
+
+  [[nodiscard]] std::pair<std::vector<Cost>, PredDAG>
+  spf(const GraphHandle& gh, NodeId src, const SpfOptions& opts) const {
+    return backend_->spf(gh, src, opts);
+  }
+
+  [[nodiscard]] std::vector<std::pair<std::vector<Cost>, PredDAG>>
+  ksp(const GraphHandle& gh, NodeId src, NodeId dst, const KspOptions& opts) const {
+    return backend_->ksp(gh, src, dst, opts);
+  }
+
+  [[nodiscard]] std::pair<Flow, FlowSummary>
+  max_flow(const GraphHandle& gh, NodeId src, NodeId dst, const MaxFlowOptions& opts) const {
+    return backend_->max_flow(gh, src, dst, opts);
+  }
+
+  [[nodiscard]] std::vector<FlowSummary>
+  batch_max_flow(const GraphHandle& gh,
+                 const std::vector<std::pair<NodeId,NodeId>>& pairs,
+                 const MaxFlowOptions& opts,
+                 const std::vector<std::span<const bool>>& node_masks = {},
+                 const std::vector<std::span<const bool>>& edge_masks = {}) const {
+    return backend_->batch_max_flow(gh, pairs, opts, node_masks, edge_masks);
+  }
+
+private:
+  BackendPtr backend_;
+};
+
+} // namespace netgraph::core

include/netgraph/core/algorithms.hpp

@@ -1,9 +1,8 @@
 /*
-  ExecutionBackend interface — abstracts SP/MaxFlow/KSP implementations.
+  Backend interface — abstracts SPF/MaxFlow/KSP implementations.
 
   The default CPU backend delegates to in-process algorithm implementations.
-  Interfaces mirror the public helpers in headers (e.g., see max_flow.hpp)
-  including optional toggles for collecting additional outputs.
+  All execution flows through this interface via an explicit Algorithms façade.
 */
 #pragma once
 
@@ -13,39 +12,50 @@
 #include <vector>
 #include <span>
 
-#include "netgraph/core/max_flow.hpp"
-#include "netgraph/core/shortest_paths.hpp"
 #include "netgraph/core/strict_multidigraph.hpp"
+#include "netgraph/core/shortest_paths.hpp"
+#include "netgraph/core/max_flow.hpp"
+#include "netgraph/core/options.hpp"
 
 namespace netgraph::core {
 
-class ExecutionBackend {
+// Opaque handle to a backend-owned graph. Uses shared ownership to provide
+// safe lifetime management across API boundaries.
+struct GraphHandle {
+  std::shared_ptr<const StrictMultiDiGraph> graph {};
+};
+
+class Backend {
 public:
-  virtual ~ExecutionBackend() noexcept = default;
-  [[nodiscard]] virtual std::pair<std::vector<Cost>, PredDAG> shortest_paths(
-      const StrictMultiDiGraph& g, NodeId src, std::optional<NodeId> dst,
-      const EdgeSelection& selection,
-      std::span<const Cap> residual = {},
-      const bool* node_mask = nullptr,
-      const bool* edge_mask = nullptr) = 0;
-
-  [[nodiscard]] virtual std::pair<Flow, FlowSummary> calc_max_flow(
-      const StrictMultiDiGraph& g, NodeId src, NodeId dst,
-      FlowPlacement placement, bool shortest_path,
-      bool with_edge_flows,
-      bool with_reachable,
-      bool with_residuals,
-      const bool* node_mask = nullptr,
-      const bool* edge_mask = nullptr) = 0;
-
-  [[nodiscard]] virtual std::vector<std::pair<std::vector<Cost>, PredDAG>> k_shortest_paths(
-      const StrictMultiDiGraph& g, NodeId src, NodeId dst,
-      int k, std::optional<double> max_cost_factor,
-      bool unique,
-      const bool* node_mask = nullptr,
-      const bool* edge_mask = nullptr) = 0;
+  virtual ~Backend() noexcept = default;
+
+  // Prepare a backend-specific graph handle from an existing graph reference.
+  // CPU backend creates a non-owning shared_ptr with a no-op deleter.
+  [[nodiscard]] virtual GraphHandle build_graph(const StrictMultiDiGraph& g) = 0;
+
+  // Prepare a backend-specific graph handle that takes shared ownership of the
+  // provided graph instance.
+  [[nodiscard]] virtual GraphHandle build_graph(std::shared_ptr<const StrictMultiDiGraph> g) = 0;
+
+  [[nodiscard]] virtual std::pair<std::vector<Cost>, PredDAG> spf(
+      const GraphHandle& gh, NodeId src, const SpfOptions& opts) = 0;
+
+  [[nodiscard]] virtual std::pair<Flow, FlowSummary> max_flow(
+      const GraphHandle& gh, NodeId src, NodeId dst, const MaxFlowOptions& opts) = 0;
+
+  [[nodiscard]] virtual std::vector<std::pair<std::vector<Cost>, PredDAG>> ksp(
+      const GraphHandle& gh, NodeId src, NodeId dst, const KspOptions& opts) = 0;
+
+  [[nodiscard]] virtual std::vector<FlowSummary> batch_max_flow(
+      const GraphHandle& gh,
+      const std::vector<std::pair<NodeId,NodeId>>& pairs,
+      const MaxFlowOptions& opts,
+      const std::vector<std::span<const bool>>& node_masks = {},
+      const std::vector<std::span<const bool>>& edge_masks = {}) = 0;
 };
 
-[[nodiscard]] std::unique_ptr<ExecutionBackend> make_cpu_backend();
+using BackendPtr = std::shared_ptr<Backend>;
+
+[[nodiscard]] BackendPtr make_cpu_backend();
 
 } // namespace netgraph::core

include/netgraph/core/backend.hpp

@@ -5,6 +5,7 @@
 #pragma once
 
 #include <cstdint>
+#include <limits>
 #include <optional>
 #include <unordered_map>
 #include <utility>
@@ -13,18 +14,64 @@
 
 #include "netgraph/core/flow.hpp"
 #include "netgraph/core/flow_graph.hpp"
-#include "netgraph/core/shortest_paths.hpp"
+#include "netgraph/core/algorithms.hpp"
+#include "netgraph/core/options.hpp"
 #include "netgraph/core/types.hpp"
 
 namespace netgraph::core {
 
 enum class PathAlg : std::int32_t { SPF = 1 };
 
+// Execution context bundles algorithms and graph handle for clear dependency injection
+struct ExecutionContext {
+  Algorithms* algorithms;
+  GraphHandle graph;
+
+  // Constructor with validation
+  ExecutionContext(Algorithms& algs, const GraphHandle& gh) noexcept
+      : algorithms(&algs), graph(gh) {}
+};
+
+// Configuration for FlowPolicy behavior. Mirrors the long-form constructor
+// parameters in a grouped, maintainable struct.
+struct FlowPolicyConfig {
+  PathAlg path_alg { PathAlg::SPF };
+  FlowPlacement flow_placement { FlowPlacement::Proportional };
+  EdgeSelection selection { EdgeSelection{} };
+  int min_flow_count { 1 };
+  std::optional<int> max_flow_count { std::nullopt };
+  std::optional<Cost> max_path_cost { std::nullopt };
+  std::optional<double> max_path_cost_factor { std::nullopt };
+  bool shortest_path { false };
+  bool reoptimize_flows_on_each_placement { false };
+  int max_no_progress_iterations { 100 };
+  int max_total_iterations { 10000 };
+  bool diminishing_returns_enabled { true };
+  int diminishing_returns_window { 8 };
+  double diminishing_returns_epsilon_frac { 1e-3 };
+};
+
 // FlowPolicy orchestrates flow creation, placement, reopt, and removal for a
 // single demand (src,dst,flowClass) on a shared FlowGraph.
 class FlowPolicy {
 public:
-  FlowPolicy(PathAlg path_alg,
+  // New config-based constructor
+  FlowPolicy(const ExecutionContext& ctx, const FlowPolicyConfig& cfg)
+    : ctx_(ctx),
+      path_alg_(cfg.path_alg), flow_placement_(cfg.flow_placement), selection_(cfg.selection),
+      shortest_path_(cfg.shortest_path),
+      min_flow_count_(cfg.min_flow_count), max_flow_count_(cfg.max_flow_count), max_path_cost_(cfg.max_path_cost),
+      max_path_cost_factor_(cfg.max_path_cost_factor), reoptimize_flows_on_each_placement_(cfg.reoptimize_flows_on_each_placement),
+      max_no_progress_iterations_(cfg.max_no_progress_iterations), max_total_iterations_(cfg.max_total_iterations),
+      diminishing_returns_enabled_(cfg.diminishing_returns_enabled), diminishing_returns_window_(cfg.diminishing_returns_window),
+      diminishing_returns_epsilon_frac_(cfg.diminishing_returns_epsilon_frac) {
+    if (flow_placement_ == FlowPlacement::EqualBalanced && !max_flow_count_.has_value()) {
+      throw std::invalid_argument("max_flow_count must be set for EQUAL_BALANCED placement.");
+    }
+  }
+
+  FlowPolicy(const ExecutionContext& ctx,
+             PathAlg path_alg,
              FlowPlacement flow_placement,
              EdgeSelection selection,
              int min_flow_count = 1,
@@ -38,7 +85,8 @@ class FlowPolicy {
              bool diminishing_returns_enabled = true,
              int diminishing_returns_window = 8,
              double diminishing_returns_epsilon_frac = 1e-3)
-    : path_alg_(path_alg), flow_placement_(flow_placement), selection_(selection),
+    : ctx_(ctx),
+      path_alg_(path_alg), flow_placement_(flow_placement), selection_(selection),
       shortest_path_(shortest_path),
       min_flow_count_(min_flow_count), max_flow_count_(max_flow_count), max_path_cost_(max_path_cost),
       max_path_cost_factor_(max_path_cost_factor), reoptimize_flows_on_each_placement_(reoptimize_flows_on_each_placement),
@@ -87,6 +135,7 @@ class FlowPolicy {
   [[nodiscard]] FlowRecord* reoptimize_flow(FlowGraph& fg, const FlowIndex& idx, double headroom);
 
   // Config
+  ExecutionContext ctx_;
   PathAlg path_alg_ { PathAlg::SPF };
   FlowPlacement flow_placement_ { FlowPlacement::Proportional };
   EdgeSelection selection_ { EdgeSelection{} };
@@ -104,14 +153,9 @@ class FlowPolicy {
 
   // State
   std::unordered_map<FlowIndex, FlowRecord, FlowIndexHash> flows_;
-  Cost best_path_cost_ { 0 };
+  Cost best_path_cost_ { std::numeric_limits<Cost>::max() };
   std::int64_t next_flow_id_ { 0 };
 
-  // When selection_.multipath == false, freeze exactly one edge per neighbor
-  // pair (u,v) across all flows: subsequent path searches may only reuse the
-  // same chosen EdgeId for that (u,v). Key is (static_cast<uint64_t>(u)<<32)|v.
-  std::unordered_map<std::uint64_t, EdgeId> locked_uv_edge_;
-
   // Static paths (optional)
   std::vector<std::tuple<NodeId, NodeId, PredDAG, Cost>> static_paths_;
 };

include/netgraph/core/flow_policy.hpp

@@ -0,0 +1,38 @@
+/* Option structs for algorithm invocations to keep interfaces concise. */
+#pragma once
+
+#include <optional>
+#include <span>
+
+#include "netgraph/core/types.hpp"
+
+namespace netgraph::core {
+
+struct SpfOptions {
+  bool multipath { true };
+  EdgeSelection selection {};
+  std::optional<NodeId> dst {};
+  std::span<const Cap> residual {};
+  std::span<const bool> node_mask {};
+  std::span<const bool> edge_mask {};
+};
+
+struct KspOptions {
+  int k { 1 };
+  std::optional<double> max_cost_factor {};
+  bool unique { true };
+  std::span<const bool> node_mask {};
+  std::span<const bool> edge_mask {};
+};
+
+struct MaxFlowOptions {
+  FlowPlacement placement { FlowPlacement::Proportional };
+  bool shortest_path { false };
+  bool with_edge_flows { false };
+  bool with_reachable { false };
+  bool with_residuals { false };
+  std::span<const bool> node_mask {};
+  std::span<const bool> edge_mask {};
+};
+
+} // namespace netgraph::core

include/netgraph/core/options.hpp

@@ -29,6 +29,7 @@ struct PredDAG {
 [[nodiscard]] std::pair<std::vector<Cost>, PredDAG>
 shortest_paths(const StrictMultiDiGraph& g, NodeId src,
                std::optional<NodeId> dst,
+               bool multipath,
                const EdgeSelection& selection,
                std::span<const Cap> residual = {},
                const bool* node_mask = nullptr,

include/netgraph/core/shortest_paths.hpp

@@ -2,6 +2,7 @@
 #pragma once
 
 #include <cstdint>
+#include <functional>
 
 namespace netgraph::core {
 
@@ -26,11 +27,15 @@ struct FlowIndex {
 
 struct FlowIndexHash {
   std::size_t operator()(const FlowIndex& k) const noexcept {
-    // simple mix
-    std::size_t h = static_cast<std::size_t>(static_cast<std::uint64_t>(k.src) * 1469598103934665603ULL);
-    h ^= static_cast<std::size_t>(static_cast<std::uint32_t>(k.dst)) + 0x9e3779b97f4a7c15ULL + (h<<6) + (h>>2);
-    h ^= static_cast<std::size_t>(static_cast<std::uint32_t>(k.flowClass)) + 0x9e3779b97f4a7c15ULL + (h<<6) + (h>>2);
-    h ^= static_cast<std::size_t>(static_cast<std::uint64_t>(k.flowId)) + 0x9e3779b97f4a7c15ULL + (h<<6) + (h>>2);
+    std::size_t h = 0;
+    auto combine = [&h](std::size_t v) {
+      // Standard hash combine (boost-like)
+      h ^= v + 0x9e3779b97f4a7c15ULL + (h << 6) + (h >> 2);
+    };
+    combine(std::hash<NodeId>{}(k.src));
+    combine(std::hash<NodeId>{}(k.dst));
+    combine(std::hash<std::int32_t>{}(k.flowClass));
+    combine(std::hash<std::int64_t>{}(k.flowId));
     return h;
   }
 };
@@ -43,7 +48,9 @@ enum class FlowPlacement {
 enum class EdgeTieBreak { Deterministic = 1, PreferHigherResidual = 2 };
 
 struct EdgeSelection {
-  bool multipath { true };
+  // When true, keep all equal-cost parallel edges per (u,v) adjacency.
+  // When false, pick a single edge per (u,v) according to tie_break.
+  bool multi_edge { true };
   bool require_capacity { false };
   EdgeTieBreak tie_break { EdgeTieBreak::Deterministic };
 };