v0.1.0

Author: networmix

CMakeLists.txt

@@ -13,8 +13,18 @@ if(NETGRAPH_CORE_BUILD_TESTS)
   )
   FetchContent_MakeAvailable(googletest)
   enable_testing()
-  add_executable(netgraph_core_tests tests/cpp/smoke_test.cpp tests/cpp/flow_policy_tests.cpp)
+  add_executable(netgraph_core_tests
+    tests/cpp/smoke_test.cpp
+    tests/cpp/flow_policy_tests.cpp
+    tests/cpp/strict_multidigraph_tests.cpp
+    tests/cpp/shortest_paths_tests.cpp
+    tests/cpp/flow_state_tests.cpp
+    tests/cpp/flow_graph_tests.cpp
+    tests/cpp/max_flow_tests.cpp
+    tests/cpp/k_shortest_paths_tests.cpp
+  )
   target_link_libraries(netgraph_core_tests PRIVATE netgraph_core GTest::gtest_main)
+  target_include_directories(netgraph_core_tests PRIVATE tests/cpp)
   if(NETGRAPH_CORE_COVERAGE AND (CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang"))
     target_compile_options(netgraph_core_tests PRIVATE -O0 -g --coverage)
     target_link_options(netgraph_core_tests PRIVATE --coverage)
@@ -34,7 +44,6 @@ if(APPLE)
   if(DEFINED ENV{MACOSX_DEPLOYMENT_TARGET})
     set(CMAKE_OSX_DEPLOYMENT_TARGET "$ENV{MACOSX_DEPLOYMENT_TARGET}" CACHE STRING "" FORCE)
   elseif(NOT DEFINED CMAKE_OSX_DEPLOYMENT_TARGET)
-    # Default matches Homebrew Python's target in this workspace
     set(CMAKE_OSX_DEPLOYMENT_TARGET "15.0" CACHE STRING "" FORCE)
   endif()
   if(NOT DEFINED CMAKE_OSX_ARCHITECTURES)

Makefile

@@ -14,7 +14,7 @@ PYTEST = $(PYTHON) -m pytest
 RUFF = $(PYTHON) -m ruff
 PRECOMMIT = $(PYTHON) -m pre_commit
 
-# Prefer Apple Command Line Tools compilers to avoid Homebrew libc++ ABI mismatches
+# Detect Apple Command Line Tools compilers (prefer system toolchain on macOS)
 APPLE_CLANG := $(shell xcrun --find clang 2>/dev/null)
 APPLE_CLANGXX := $(shell xcrun --find clang++ 2>/dev/null)
 DEFAULT_MACOSX := 15.0

README.md

@@ -1,14 +1,56 @@
-NetGraph-Core
+# NetGraph-Core
 
-C++ core with Python bindings.
+C++ implementation of graph algorithms for network flow analysis and traffic engineering with Python bindings.
 
-- Native C++ kernels for shortest paths, k-shortest paths, and max-flow
-- Deterministic, thread-parallel, batch execution with GIL released
-- Python API with a stable, well-documented surface
+## Features
 
-Development
+- **Algorithms:** Shortest paths (Dijkstra), K-shortest paths (Yen), max-flow (successive shortest paths)
+- **Graph representation:** Immutable directed multigraph with CSR adjacency
+- **Flow placement:** Tunable policies (proportional to capacity, equal-balanced across paths)
+- **Python bindings:** NumPy integration, GIL released during computation
+- **Deterministic:** Reproducible edge ordering by (cost, src, dst)
 
-- Setup: `make dev` (creates venv, installs dev deps, sets up pre-commit)
-- Local checks: `make check` (auto-fix with pre-commit, run C++/Python tests, then lint)
-- CI checks: `make check-ci` (strict, non-mutating: lint → C++ tests → Python tests)
-- Coverage: `make cov` (prints unified summary and writes XML + single-page HTML under build/coverage/)
+## Installation
+
+```bash
+pip install netgraph-core
+```
+
+Or from source:
+
+```bash
+pip install -e .
+```
+
+## Repository Structure
+
+```
+src/                    # C++ implementation
+include/netgraph/core/  # Public C++ headers
+bindings/python/        # pybind11 bindings
+python/netgraph_core/   # Python package
+tests/cpp/              # C++ tests (googletest)
+tests/py/               # Python tests (pytest)
+```
+
+## Development
+
+```bash
+make dev        # Setup: venv, dependencies, pre-commit hooks
+make check      # Run all tests and linting (auto-fix formatting)
+make check-ci   # Strict checks without auto-fix (for CI)
+make cpp-test   # C++ tests only
+make py-test    # Python tests only
+make cov        # Coverage report (C++ + Python)
+```
+
+## Requirements
+
+- **C++:** C++20 compiler (GCC 10+, Clang 12+, MSVC 2019+)
+- **Python:** 3.9+
+- **Build:** CMake 3.15+, scikit-build-core
+- **Dependencies:** pybind11, NumPy
+
+## License
+
+AGPL-3.0-or-later

bindings/python/module.cpp

@@ -74,83 +74,58 @@ PYBIND11_MODULE(_netgraph_core, m) {
           [](std::int32_t num_nodes,
              py::array src, py::array dst,
              py::array capacity, py::array cost,
-             bool add_reverse) {
+             py::object ext_edge_ids_obj) {
             // public API: src/dst are int32; pass through as int32 to core
             auto src_s = as_span<std::int32_t>(src, "src");
             auto dst_s = as_span<std::int32_t>(dst, "dst");
             if (src_s.size() != dst_s.size()) throw py::type_error("src and dst must have the same length");
             auto cap_s = as_span<double>(capacity, "capacity");
             // Cost dtype must be int64 to match internal Cost type
             auto cost_s = as_span<std::int64_t>(cost, "cost");
+            // Optional ext_edge_ids
+            std::span<const std::int64_t> ext_s;
+            if (!ext_edge_ids_obj.is_none()) {
+              py::array ext_arr = ext_edge_ids_obj.cast<py::array>();
+              ext_s = as_span<std::int64_t>(ext_arr, "ext_edge_ids");
+            }
             return StrictMultiDiGraph::from_arrays(num_nodes,
                                                   src_s,
                                                   dst_s,
-                                                  cap_s, cost_s, add_reverse);
+                                                  cap_s, cost_s, ext_s);
           },
           py::arg("num_nodes"), py::arg("src"), py::arg("dst"), py::arg("capacity"), py::arg("cost"),
-          py::kw_only(), py::arg("add_reverse") = false)
+          py::kw_only(), py::arg("ext_edge_ids") = py::none())
       .def("num_nodes", &StrictMultiDiGraph::num_nodes)
       .def("num_edges", &StrictMultiDiGraph::num_edges)
-      // external link ids removed; EdgeId is the canonical id
-      .def("capacity_view", [](py::object self_obj, const StrictMultiDiGraph& g){
+      .def("capacity_view", [](const StrictMultiDiGraph& g){
         auto s = g.capacity_view();
-        py::array out(
-            py::buffer_info(
-                const_cast<double*>(s.data()),
-                sizeof(double),
-                py::format_descriptor<double>::format(),
-                1,
-                { s.size() },
-                { sizeof(double) }
-            ),
-            self_obj
-        );
-        return out;
+        py::array_t<double> arr(s.size());
+        std::memcpy(arr.mutable_data(), s.data(), s.size()*sizeof(double));
+        return arr;
       })
-      .def("edge_src_view", [](py::object self_obj, const StrictMultiDiGraph& g){
+      .def("edge_src_view", [](const StrictMultiDiGraph& g){
         auto s = g.edge_src_view();
-        py::array out(
-            py::buffer_info(
-                const_cast<std::int32_t*>(s.data()),
-                sizeof(std::int32_t),
-                py::format_descriptor<std::int32_t>::format(),
-                1,
-                { s.size() },
-                { sizeof(std::int32_t) }
-            ),
-            self_obj
-        );
-        return out;
+        py::array_t<std::int32_t> arr(s.size());
+        std::memcpy(arr.mutable_data(), s.data(), s.size()*sizeof(std::int32_t));
+        return arr;
       })
-      .def("edge_dst_view", [](py::object self_obj, const StrictMultiDiGraph& g){
+      .def("edge_dst_view", [](const StrictMultiDiGraph& g){
         auto s = g.edge_dst_view();
-        py::array out(
-            py::buffer_info(
-                const_cast<std::int32_t*>(s.data()),
-                sizeof(std::int32_t),
-                py::format_descriptor<std::int32_t>::format(),
-                1,
-                { s.size() },
-                { sizeof(std::int32_t) }
-            ),
-            self_obj
-        );
-        return out;
+        py::array_t<std::int32_t> arr(s.size());
+        std::memcpy(arr.mutable_data(), s.data(), s.size()*sizeof(std::int32_t));
+        return arr;
       })
-      .def("cost_view", [](py::object self_obj, const StrictMultiDiGraph& g){
+      .def("ext_edge_ids_view", [](const StrictMultiDiGraph& g){
+        auto s = g.ext_edge_ids_view();
+        py::array_t<std::int64_t> arr(s.size());
+        std::memcpy(arr.mutable_data(), s.data(), s.size()*sizeof(std::int64_t));
+        return arr;
+      })
+      .def("cost_view", [](const StrictMultiDiGraph& g){
         auto s = g.cost_view();
-        py::array out(
-            py::buffer_info(
-                const_cast<Cost*>(s.data()),
-                sizeof(Cost),
-                py::format_descriptor<Cost>::format(),
-                1,
-                { s.size() },
-                { sizeof(Cost) }
-            ),
-            self_obj
-        );
-        return out;
+        py::array_t<std::int64_t> arr(s.size());
+        std::memcpy(arr.mutable_data(), s.data(), s.size()*sizeof(std::int64_t));
+        return arr;
       })
       .def("row_offsets_view", [](const StrictMultiDiGraph& g){
         auto s = g.row_offsets_view();
@@ -183,8 +158,6 @@ PYBIND11_MODULE(_netgraph_core, m) {
         return arr;
       });
 
-  // PredDAG properties already defined earlier at L200; avoid duplicate class registration
-
   // Backend and Algorithms
 
   // Opaque wrapper types
@@ -208,21 +181,26 @@ PYBIND11_MODULE(_netgraph_core, m) {
                                           std::int32_t num_nodes,
                                           py::array src, py::array dst,
                                           py::array capacity, py::array cost,
-                                          bool add_reverse){
+                                          py::object ext_edge_ids_obj){
         // Build graph by value, then move-assign into a shared_ptr to own it
+        std::span<const std::int64_t> ext_s;
+        if (!ext_edge_ids_obj.is_none()) {
+          py::array ext_arr = ext_edge_ids_obj.cast<py::array>();
+          ext_s = as_span<std::int64_t>(ext_arr, "ext_edge_ids");
+        }
         StrictMultiDiGraph gv = StrictMultiDiGraph::from_arrays(
             num_nodes,
             as_span<std::int32_t>(src, "src"),
             as_span<std::int32_t>(dst, "dst"),
             as_span<double>(capacity, "capacity"),
             as_span<std::int64_t>(cost, "cost"),
-            add_reverse);
+            ext_s);
         auto sp = std::make_shared<StrictMultiDiGraph>();
         *sp = std::move(gv);
         auto gh = algs.build_graph(std::static_pointer_cast<const StrictMultiDiGraph>(sp));
         // No need to keep a Python-side owner; GraphHandle holds shared ownership
         return PyGraph{ gh, py::none(), sp->num_nodes(), sp->num_edges() };
-      }, py::arg("num_nodes"), py::arg("src"), py::arg("dst"), py::arg("capacity"), py::arg("cost"), py::kw_only(), py::arg("add_reverse") = false)
+      }, py::arg("num_nodes"), py::arg("src"), py::arg("dst"), py::arg("capacity"), py::arg("cost"), py::kw_only(), py::arg("ext_edge_ids") = py::none())
       .def("spf", [](const Algorithms& algs, const PyGraph& pg, std::int32_t src,
                        py::object dst, py::object selection_obj, py::object residual_obj,
                        py::object node_mask, py::object edge_mask, bool multipath){
@@ -348,7 +326,6 @@ PYBIND11_MODULE(_netgraph_core, m) {
         py::gil_scoped_release rel; auto out = algs.batch_max_flow(pg.handle, pp, o, node_spans, edge_spans); py::gil_scoped_acquire acq; return out;
       }, py::arg("graph"), py::arg("pairs"), py::kw_only(), py::arg("node_masks") = py::none(), py::arg("edge_masks") = py::none(), py::arg("flow_placement") = FlowPlacement::Proportional, py::arg("shortest_path") = false, py::arg("with_edge_flows") = false, py::arg("with_reachable") = false, py::arg("with_residuals") = false);
 
-  // resolve_to_paths now exposed as a PredDAG instance method
   py::class_<PredDAG>(m, "PredDAG")
       .def_property_readonly("parent_offsets", [](const PredDAG& d){
         py::array_t<std::int32_t> arr(d.parent_offsets.size());
@@ -390,7 +367,7 @@ PYBIND11_MODULE(_netgraph_core, m) {
         }
         return arr;
       });
-  // CostBucket/CostDistribution removed in favor of parallel arrays on FlowSummary
+
   py::class_<FlowSummary>(m, "FlowSummary")
       .def_readonly("total_flow", &FlowSummary::total_flow)
       .def_readonly("min_cut", &FlowSummary::min_cut)
@@ -422,9 +399,6 @@ PYBIND11_MODULE(_netgraph_core, m) {
         return arr;
       });
 
-  // spf_residual removed; unified spf accepts optional residual and EdgeSelection
-
-
   // FlowState bindings
   py::class_<FlowState>(m, "FlowState")
       .def(py::init<const StrictMultiDiGraph&>())

include/netgraph/core/backend.hpp

@@ -2,7 +2,12 @@
   Backend interface — abstracts SPF/MaxFlow/KSP implementations.
 
   The default CPU backend delegates to in-process algorithm implementations.
-  All execution flows through this interface via an explicit Algorithms façade.
+  All execution flows through this interface via an Algorithms façade.
+
+  For Python developers:
+  - std::shared_ptr<T>: reference-counted pointer (like Python object references)
+  - virtual: method can be overridden in subclasses (like Python's inheritance)
+  - = 0: pure virtual (must be implemented by subclass, like @abstractmethod)
 */
 #pragma once
 
@@ -19,8 +24,8 @@
 
 namespace netgraph::core {
 
-// Opaque handle to a backend-owned graph. Uses shared ownership to provide
-// safe lifetime management across API boundaries.
+// GraphHandle: opaque handle to a backend-owned graph.
+// Uses shared_ptr for automatic lifetime management (like Python's reference counting).
 struct GraphHandle {
   std::shared_ptr<const StrictMultiDiGraph> graph {};
 };

include/netgraph/core/flow_policy.hpp

@@ -50,7 +50,7 @@ struct FlowPolicyConfig {
 // FlowPolicy manages flow creation, placement, reoptimization for a single demand
 class FlowPolicy {
 public:
-  // New config-based constructor
+  // Constructor accepting configuration struct
   FlowPolicy(const ExecutionContext& ctx, const FlowPolicyConfig& cfg)
     : ctx_(ctx),
       path_alg_(cfg.path_alg), flow_placement_(cfg.flow_placement), selection_(cfg.selection),

include/netgraph/core/flow_state.hpp

@@ -18,9 +18,9 @@
 namespace netgraph::core {
 
 // FlowState maintains per-edge residual capacity and per-edge placed flow for a
-// given immutable StrictMultiDiGraph. It provides efficient placement on a
-// provided predecessor DAG (PredDAG) using either proportional or equal-balanced
-// strategies, updating internal residuals deterministically.
+// given immutable StrictMultiDiGraph. It places flow on a predecessor DAG (PredDAG)
+// using either proportional or equal-balanced strategies, updating internal
+// residuals deterministically.
 class FlowState {
 public:
   explicit FlowState(const StrictMultiDiGraph& g);

include/netgraph/core/shortest_paths.hpp

@@ -1,4 +1,10 @@
-/* Shortest paths (Dijkstra) with multipath predecessor DAG support. */
+/* Shortest paths (Dijkstra) with multipath predecessor DAG support.
+ *
+ * For Python developers:
+ * - std::pair<A, B>: tuple of two elements (like tuple[A, B])
+ * - std::optional<T>: nullable value (like T | None)
+ * - std::nullopt: None equivalent for std::optional
+ */
 #pragma once
 
 #include <optional>
@@ -11,21 +17,31 @@
 
 namespace netgraph::core {
 
-// Predecessor DAG: compact representation of all equal-cost predecessors.
-// For each node v, entries are stored in [parent_offsets[v], parent_offsets[v+1])
-// as pairs (parents[i], via_edges[i]) where via_edges[i] is the compacted EdgeId
-// used to reach v from parents[i]. Multiple parallel edges are represented by
-// multiple entries with the same parent. Offsets has length N+1.
+// PredDAG (Predecessor Directed Acyclic Graph): compact representation of all equal-cost
+// shortest paths from a source node. Similar to a defaultdict(list) in Python, but stored
+// in CSR format for efficiency.
+//
+// For each node v, predecessors are stored in parents[parent_offsets[v]:parent_offsets[v+1]]
+// with corresponding EdgeIds in via_edges[parent_offsets[v]:parent_offsets[v+1]].
+// Multiple parallel edges are represented by multiple entries with the same parent.
+// parent_offsets has length N+1 (like CSR row pointers).
 struct PredDAG {
-  std::vector<std::int32_t> parent_offsets;
-  std::vector<NodeId> parents;
-  std::vector<EdgeId> via_edges;
+  std::vector<std::int32_t> parent_offsets;  // Length N+1 (CSR row pointers)
+  std::vector<NodeId> parents;                // Predecessor node IDs
+  std::vector<EdgeId> via_edges;              // EdgeId used to reach node from predecessor
 };
 
-// Optional node/edge masks:
-// - node_mask[v] == true means node v is allowed; false excludes it from search.
-// - edge_mask[e] == true means edge e is allowed; false excludes it from search.
-// Empty mask spans are ignored.
+// Compute shortest paths from src using Dijkstra's algorithm.
+// Returns (distances, predecessor_dag) where distances[v] is the shortest cost to reach v
+// (or inf if unreachable), and predecessor_dag encodes all equal-cost paths.
+//
+// Parameters:
+// - dst: if provided, algorithm may exit early once destination is reached
+// - multipath: if true, keep all equal-cost predecessors; if false, keep only one per node
+// - selection: edge selection policy (multi-edge, capacity filtering, tie-breaking)
+// - residual: if provided, use these capacities instead of graph's original capacities
+// - node_mask: if provided, node_mask[v]==true means node v is allowed (false excludes it)
+// - edge_mask: if provided, edge_mask[e]==true means edge e is allowed (false excludes it)
 [[nodiscard]] std::pair<std::vector<Cost>, PredDAG>
 shortest_paths(const StrictMultiDiGraph& g, NodeId src,
                std::optional<NodeId> dst,