fixing ubuntu build, updated docs

Author: networmix

.github/workflows/release.yml

@@ -34,6 +34,7 @@ jobs:
           # macOS: Build Universal2 wheels on Intel runner (macos-13)
           CIBW_ARCHS_MACOS: "universal2"
           CIBW_TEST_COMMAND: "python -c \"import netgraph_core; print(netgraph_core.__version__)\""
+          CIBW_BEFORE_ALL_LINUX: "yum install -y libatomic || apt-get update && apt-get install -y libatomic1 || apk add libatomic"
 
       - uses: actions/upload-artifact@v4
         with:

CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+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.1.0] - 2025-11-23
+
+### Added
+
+- **Core Library**: Initial release of C++ implementation for graph algorithms and flow tracking.
+- **Graph Structures**:
+  - `StrictMultiDiGraph`: Immutable directed multigraph using CSR (Compressed Sparse Row) adjacency.
+  - `FlowGraph`: Manages flow state, per-flow edge allocations, and residual capacities.
+- **Algorithms**:
+  - Shortest paths (Dijkstra variant returning a DAG for ECMP; supports node/edge masking and residual-aware tie-breaking).
+  - K-Shortest paths (Yen's algorithm).
+  - Max-flow (Successive Shortest Path with ECMP/WCMP placement; supports capacity-aware (TE) and cost-only (IP) routing modes).
+  - Sensitivity analysis (identifies bottlenecks).
+- **Flow Policy**:
+  - **Modeling**: Unified configuration for IP routing (cost-based ECMP) and Traffic Engineering (capacity-aware TE).
+  - **Placement**: `Proportional` (WCMP) and `EqualBalanced` (ECMP) strategies.
+  - **Lifecycle**: Manages demand placement, static/dynamic path selection, and re-optimization.
+  - **Constraints**: Enforces limits on path cost, stretch factor, and flow counts.
+- **Python Bindings**:
+  - Python 3.9+ support via pybind11.
+  - NumPy integration using zero-copy views where applicable.
+  - Releases GIL during long-running graph algorithms.
+- **Testing**:
+  - Python and C++ test suites.

README.md

@@ -1,14 +1,56 @@
 # NetGraph-Core
 
-C++ implementation of graph algorithms for network flow analysis and traffic engineering with Python bindings.
+C++ graph engine for network flow analysis, traffic engineering simulation, and capacity planning.
 
-## Features
+## Overview
 
-- **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)
+NetGraph-Core provides a specialized graph implementation for networking problems. Key design priorities:
+
+- **Determinism**: Guaranteed reproducible edge ordering by (cost, src, dst).
+- **Flow Modeling**: Native support for multi-commodity flow state, residual tracking, and ECMP/WCMP placement.
+- **Performance**: Immutable CSR (Compressed Sparse Row) adjacency and zero-copy NumPy views.
+
+## Core Features
+
+### 1. Graph Representations
+
+- **`StrictMultiDiGraph`**: Immutable directed multigraph using CSR adjacency. Supports parallel edges (multi-graph), essential for network topologies.
+- **`FlowGraph`**: Topology overlay managing mutable flow state, per-flow edge allocations, and residual capacities.
+
+### 2. Network Algorithms
+
+- **Shortest Paths (SPF)**:
+  - Modified Dijkstra returns a **Predecessor DAG** to capture all equal-cost paths.
+  - Supports **ECMP** (Equal-Cost Multi-Path) routing.
+  - Features **node/edge masking** and **residual-aware tie-breaking**.
+
+- **K-Shortest Paths (KSP)**:
+  - Yen's algorithm returning DAG-wrapped paths.
+  - Configurable constraints on cost factors (e.g., paths within 1.5x of optimal).
+
+- **Max-Flow**:
+  - **Algorithm**: Iterative augmentation using Successive Shortest Path on residual graphs, pushing flow across full ECMP/WCMP DAGs at each step.
+  - **Traffic Engineering (TE) Mode**: Routing adapts to residual capacity (progressive fill).
+  - **IP Routing Mode**: Cost-only routing (ECMP/WCMP) ignoring capacity constraints.
+
+- **Analysis**:
+  - **Sensitivity Analysis**: Identifies bottleneck edges where capacity relaxation increases total flow.
+  - **Min-Cut**: Computes minimum cuts on residual graphs.
+
+### 3. Flow Policy Engine
+
+Unified configuration object (`FlowPolicy`) that models diverse routing behaviors:
+
+- **Modeling**: Unified configuration for **IP Routing** (static costs) and **Traffic Engineering** (dynamic residuals).
+- **Placement Strategies**:
+  - `EqualBalanced`: **ECMP** (equal splitting) - equal distribution across next-hops and parallel edges.
+  - `Proportional`: **WCMP** (weighted splitting) - distribution proportional to residual capacity.
+- **Lifecycle Management**: Handles demand placement, re-optimization of existing flows, and constraints (path cost, stretch factor, flow counts).
+
+### 4. Python Integration
+
+- **Zero-Copy**: Exposes C++ internal buffers to Python as read-only NumPy arrays (float64/int64).
+- **Concurrency**: Releases the Python GIL during graph algorithms to enable threading.
 
 ## Installation
 

include/netgraph/core/flow_graph.hpp

@@ -1,4 +1,4 @@
-/* FlowGraph manages per-flow edge deltas over FlowState. */
+/* FlowGraph manages per-flow edge allocations over FlowState. */
 #pragma once
 
 #include <cstdint>
@@ -14,7 +14,7 @@
 
 namespace netgraph::core {
 
-// FlowGraph manages per-flow edge deltas over a StrictMultiDiGraph.
+// FlowGraph manages per-flow edge allocations over a StrictMultiDiGraph.
 // Composes FlowState for residual/aggregate edge flow management.
 class FlowGraph {
 public:
@@ -29,12 +29,12 @@ class FlowGraph {
   // Access underlying graph (const)
   [[nodiscard]] const StrictMultiDiGraph& graph() const noexcept { return *g_; }
 
-// Apply placement and record per-edge deltas for this flow. Returns placed amount.
+// Apply placement and record per-edge allocations for this flow. Returns placed amount.
   [[nodiscard]] Flow place(const FlowIndex& idx, NodeId src, NodeId dst,
              const PredDAG& dag, Flow amount,
              FlowPlacement placement);
 
-  // Remove a specific flow, reverting its edge deltas from the ledger.
+  // Remove a specific flow, reverting its edge allocations from the ledger.
   void remove(const FlowIndex& idx);
 
   // Remove all flows belonging to a given flowClass.
@@ -55,9 +55,6 @@ class FlowGraph {
   FlowState fs_;
   // Per-flow ledger: stores only edges with non-zero flow
   std::unordered_map<FlowIndex, std::vector<std::pair<EdgeId, Flow>>, FlowIndexHash> ledger_;
-  // Cached EdgeId -> (src,dst) maps for faster path reconstruction
-  std::vector<NodeId> src_of_;
-  std::vector<NodeId> dst_of_;
 };
 
 } // namespace netgraph::core

include/netgraph/core/flow_state.hpp

@@ -55,7 +55,7 @@ class FlowState {
                     const PredDAG& dag,
                     Flow requested_flow,
                     FlowPlacement placement,
-                    // Optional trace collector to record per-edge deltas applied by this call
+                    // Optional trace collector to record per-edge allocations applied by this call
                     std::vector<std::pair<EdgeId, Flow>>* trace = nullptr);
 
   // Convenience: run repeated placements until exhaustion (or single tier when
@@ -76,16 +76,17 @@ class FlowState {
                       std::span<const bool> node_mask = {},
                       std::span<const bool> edge_mask = {});
 
-  // Compute min-cut with respect to current residual state, starting reachability
-  // from source s on the residual graph (forward arcs: residual>MIN; reverse arcs:
-  // positive flow). Honors optional masks.
+  // Compute min-cut (edges crossing from reachable set S to unreachable set T)
+  // based on reachability in the current residual graph.
+  // Reachability starts from source s; forward arcs allowed if residual > kMinCap,
+  // reverse arcs allowed if flow > kMinFlow.
   [[nodiscard]] MinCut compute_min_cut(NodeId src,
                          std::span<const bool> node_mask = {},
                          std::span<const bool> edge_mask = {}) const;
 
-  // Apply or revert a set of edge flow deltas directly.
+  // Apply or revert a set of edge flow allocations directly.
   // When add==true, treats each (eid, flow) as additional placed flow on the edge.
-  // When add==false, removes placed flow (reverts deltas), clamping to [0, capacity].
+  // When add==false, removes placed flow (reverts allocations), clamping to [0, capacity].
   void apply_deltas(std::span<const std::pair<EdgeId, Flow>> deltas, bool add) noexcept;
 
 private:

pyproject.toml

@@ -1,11 +1,5 @@
 [build-system]
-requires = [
-    "scikit-build-core>=0.10",
-    "pybind11>=3",
-    "numpy>=1.22",
-    "cmake>=3.23",
-    "ninja",
-]
+requires = ["scikit-build-core>=0.10", "pybind11>=3", "numpy>=1.22"]
 build-backend = "scikit_build_core.build"
 
 [project]
@@ -36,12 +30,6 @@ classifiers = [
 ]
 dependencies = ["numpy>=1.22"]
 
-[tool.setuptools]
-packages = []
-
-[tool.setuptools.package-data]
-"netgraph_core" = ["py.typed"]
-
 [project.optional-dependencies]
 dev = [
     "pytest>=8",
@@ -61,8 +49,7 @@ Homepage = "https://github.com/networmix/NetGraph-Core"
 [tool.scikit-build]
 wheel.expand-macos-universal-tags = true
 build-dir = "build/{wheel_tag}"
-cmake.minimum-version = "3.23"
-
+cmake.version = ">=3.23"
 # Include Python sources from the "python/" directory
 wheel.packages = ["python/netgraph_core"]
 
@@ -71,9 +58,7 @@ wheel.packages = ["python/netgraph_core"]
 
 [tool.pytest.ini_options]
 addopts = "-q"
-markers = [
-    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
-]
+markers = ["slow: marks tests as slow (deselect with '-m \"not slow\"')"]
 
 [tool.ruff]
 line-length = 88

src/flow_graph.cpp

@@ -1,7 +1,7 @@
 /*
   FlowGraph — authoritative flow ledger layered over FlowState.
 
-  Tracks per-flow edge deltas to support exact removal and path inspection,
+  Tracks per-flow edge allocations to support exact removal and path inspection,
   while delegating residual and aggregate flow management to FlowState.
 */
 #include "netgraph/core/flow_graph.hpp"
@@ -13,11 +13,6 @@ namespace netgraph::core {
 
 FlowGraph::FlowGraph(const StrictMultiDiGraph& g)
   : g_(&g), fs_(g) {
-  // Precompute EdgeId -> (src,dst) directly from edge views
-  auto sv = g_->edge_src_view();
-  auto dv = g_->edge_dst_view();
-  src_of_.assign(sv.begin(), sv.end());
-  dst_of_.assign(dv.begin(), dv.end());
 }
 
 Flow FlowGraph::place(const FlowIndex& idx, NodeId src, NodeId dst,
@@ -31,7 +26,7 @@ Flow FlowGraph::place(const FlowIndex& idx, NodeId src, NodeId dst,
   auto& bucket = ledger_[idx];
 
   // Delegate placement to FlowState, which returns the actual placed flow and
-  // populates bucket with per-edge deltas (EdgeId, Flow) pairs.
+  // populates bucket with per-edge allocations (EdgeId, Flow) pairs.
   Flow placed = fs_.place_on_dag(src, dst, dag, amount, placement, &bucket);
 
   // Coalesce and filter: merge duplicate EdgeIds. Keep any positive totals
@@ -63,7 +58,7 @@ void FlowGraph::remove(const FlowIndex& idx) {
   auto it = ledger_.find(idx);
   if (it == ledger_.end()) return;  // flow not found
   const auto& deltas = it->second;
-  // Revert this flow's deltas from the FlowState by subtracting them.
+  // Revert this flow's allocations from the FlowState by subtracting them.
   if (!deltas.empty()) {
     fs_.apply_deltas(deltas, /*add=*/false);  // false = subtract
   }
@@ -93,16 +88,16 @@ std::vector<EdgeId> FlowGraph::get_flow_path(const FlowIndex& idx) const {
   if (it == ledger_.end()) return {};
   const auto& deltas = it->second;
 
-  // Reconstruct a simple path from the flow's edge deltas.
+  // Reconstruct a simple path from the flow's edge allocations.
   // This only succeeds if the flow forms a single path (not a DAG).
 
   // Step 1: Build adjacency map from edges with positive flow.
   std::unordered_map<NodeId, std::vector<std::pair<NodeId, EdgeId>>> adj;
-  // Build adjacency list from deltas using cached src/dst.
+  // Build adjacency list from allocations using cached src/dst.
   for (auto const& pr : deltas) {
     if (pr.second < kMinFlow) continue;
     auto eid = static_cast<std::size_t>(pr.first);
-    NodeId u = src_of_[eid]; NodeId v = dst_of_[eid];
+    NodeId u = g_->edge_src_view()[eid]; NodeId v = g_->edge_dst_view()[eid];
     adj[u].emplace_back(v, pr.first);
   }
 

src/max_flow.cpp

@@ -4,6 +4,9 @@
   Uses FlowState to track residuals and place flow along SPF predecessor DAGs.
   Accumulates total flow, optional per-edge flows, cost distribution, and
   derives a min-cut from the final residual graph.
+
+  Algorithm: Iterative augmentation using Successive Shortest Path on residual graphs,
+  pushing flow across full ECMP/WCMP DAGs at each step.
 */
 #include "netgraph/core/max_flow.hpp"
 #include "netgraph/core/shortest_paths.hpp"
@@ -104,8 +107,8 @@ calc_max_flow(const StrictMultiDiGraph& g, NodeId src, NodeId dst,
     summary.flows.reserve(cost_dist.size());
     for (auto const& pr : cost_dist) { summary.costs.push_back(pr.first); summary.flows.push_back(pr.second); }
   }
-  // Min-cut extraction (proportional/equal-balanced): compute reachability in final residual graph
-  // Residual graph has forward residual = residual[e], reverse residual = flow[e] (capacity - residual)
+  // Min-Cut: Set of edges crossing from the reachable set (S) to the unreachable set (T).
+  // Computed by finding all nodes reachable from src in the residual graph.
   if (total >= kMinFlow) {
     auto mc = fs.compute_min_cut(src, node_mask, edge_mask);
     summary.min_cut = mc;