netgraph-core 0.7.2__tar.gz → 0.9.0__tar.gz

{netgraph_core-0.7.2 → netgraph_core-0.9.0}/.github/workflows/release.yml

@@ -10,6 +10,25 @@ on:
   workflow_dispatch:
 
 jobs:
+  # A tag push publishes whatever version pyproject.toml declares, so a mistyped
+  # tag would ship the wrong version silently. Fail fast instead.
+  check_version:
+    name: Tag matches project version
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/checkout@v4
+      - name: Compare tag with pyproject version
+        run: |
+          python -c "
+          import tomllib, os, sys
+          version = tomllib.load(open('pyproject.toml','rb'))['project']['version']
+          tag = os.environ['GITHUB_REF_NAME'].removeprefix('v')
+          if tag != version:
+              sys.exit(f'tag {tag!r} != pyproject version {version!r}')
+          print(f'tag matches project version: {version}')
+          "
+
   build_wheels:
     name: Wheel (${{ matrix.os }}, ${{ matrix.cibw_archs }})
     runs-on: ${{ matrix.os }}
@@ -95,7 +114,7 @@ jobs:
 
   publish_pypi:
     name: Publish to PyPI
-    needs: [build_wheels, build_sdist, test_wheels_centos_stream_9]
+    needs: [check_version, build_wheels, build_sdist, test_wheels_centos_stream_9]
     runs-on: ubuntu-latest
     environment: pypi
     permissions:

{netgraph_core-0.7.2 → netgraph_core-0.9.0}/.gitignore

@@ -221,3 +221,6 @@ marimo/_static/
 marimo/_lsp/
 __marimo__/
 .pgo-profile/
+
+# Personal Superset lifecycle overrides
+.superset/config.local.json

netgraph_core-0.9.0/.superset/config.json

@@ -0,0 +1,4 @@
+{
+  "setup": ["bash .superset/workspace.sh setup"],
+  "run": ["bash .superset/workspace.sh check"]
+}

netgraph_core-0.9.0/.superset/workspace.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+mode=${1:-help}
+case "$mode" in
+    setup|check) ;;
+    *) echo 'Usage: bash .superset/workspace.sh {setup|check}'; exit 2 ;;
+esac
+if [[ "$mode" == setup && ! -x venv/bin/python ]]; then
+    make venv
+fi
+[[ -x venv/bin/python ]] || { echo 'Run bash .superset/workspace.sh setup first.' >&2; exit 1; }
+export VIRTUAL_ENV="$PWD/venv"
+export PATH="$VIRTUAL_ENV/bin:$PATH"
+unset PYTHONPATH PYTHONHOME
+export CMAKE_BUILD_PARALLEL_LEVEL="${CMAKE_BUILD_PARALLEL_LEVEL:-4}"
+if [[ "$(uname -s)" == Darwin ]]; then
+    export CC="$(xcrun --find clang)"
+    export CXX="$(xcrun --find clang++)"
+    export MACOSX_DEPLOYMENT_TARGET="${MACOSX_DEPLOYMENT_TARGET:-15.0}"
+fi
+if [[ "$mode" == setup ]]; then
+    python -m pip install -e '.[dev]'
+    python -m pip check
+    python -c 'import netgraph_core, _netgraph_core; print("Workspace environment ready")'
+else
+    make install
+    make check-ci
+fi

netgraph_core-0.9.0/AGENTS.md

@@ -0,0 +1,15 @@
+# Development
+
+- Setup: `bash .superset/workspace.sh setup`. Each worktree gets its own venv;
+  setup does not replace the Git hooks shared by worktrees.
+- Superset **Run**: `bash .superset/workspace.sh check` rebuilds the Python
+  extension, then runs lint, types, C++ and Python tests. Editable Python imports
+  alone do not rebuild changed C++.
+- For C++ changes, also run `make sanitize-test` (ASan/UBSan; errors must fail).
+- For downstream changes, run NetGraph's `dev/check_core_integration.sh` with
+  this worktree's absolute path. Test the chosen build, not the published wheel.
+
+Confirm defects with a reproducer. Max-flow tests need feasibility, conservation
+and optimality/cut checks with nonuniform costs, masks and cost-factor cases.
+Keep bindings and `_docs.py` consistent. Performance claims need correctness
+checks and A/B/A on one quiet machine. Local checks do not replace CI.

netgraph_core-0.9.0/CHANGELOG.md

@@ -0,0 +1,233 @@
+# 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.9.0] - 2026-09-13
+
+### Added
+
+- **Shortest Paths**: `shortest_paths_to(dst, ...)` / `Algorithms.spf_to` runs Dijkstra over the in-adjacency and returns distances *to* one destination plus a forward-oriented `PredDAG` valid for placement from any node toward it (the union of the per-source shortest-path DAGs). `fanout_edges` adds edges regardless of cost, for an origin whose first hop is a traffic split rather than a routing decision, such as a pseudo source whose demand originates evenly at every attached real source; a fan-out edge must leave a node with no incoming DAG entry, which keeps the result acyclic.
+- **Flow Placement**: two equal-balanced modes for hop-by-hop ECMP with a load-blind forwarding table. `EQUAL_BALANCED_FIXED` takes the split set from the DAG edges with *capacity* rather than residual and keeps the single global admission scale, so a member filled since the DAG was computed drives the scale to 0 (lossless hash-ECMP admission; the existing `EQUAL_BALANCED` drops such members from the split, which is progressive/TE behaviour). `EQUAL_BALANCED_LOSSY` splits over the same set without a scale: each edge carries `min(share, residual)`, the excess is dropped, deficits propagate downstream, and the placed amount is what reaches the destination. `FlowGraph.place_with_drops` returns the dropped volume per edge; `FlowState::place_on_dag` gained an optional `drops` collector. On a 100/10 parallel pair offered 100 units, `EQUAL_BALANCED` and `EQUAL_BALANCED_FIXED` admit 20 and `EQUAL_BALANCED_LOSSY` delivers 60. `FlowPolicy` treats the new modes as equal-balanced except that the lossy mode skips the equalizing rebalance, so with pinned routes each LSP carries what fits and `placed` is the delivered total.
+
+### Changed
+
+- **Flow Policy**: a cost-only policy (`require_capacity=false`) no longer passes the residual to SPF when an equal-balanced per-flow target is set. A residual forces capacity-aware edge selection, so such policies silently routed around saturated edges instead of following costs; they now route on cost alone, and the per-flow target still bounds how much each flow requests.
+
+- **Flow Policy**: `get_path_bundle` now memoizes raw SPF results keyed by the exact inputs that can vary per call (src, dst, residual content, residual-awareness). EqualBalanced placement and rebalance rounds re-request bundles against residual state that repeats -- 94% of SPF calls in a measured place/rebalance cycle were exact input repeats, largely remove+place round-trips restoring identical bytes -- and those calls are now elided. Matching is exact (FlowGraph state stamp fast path, full residual `memcmp` content path), so all outputs are bit-identical; a corpus hash over max-flow, SPF, KSP and policy outputs is unchanged. Measured on place/rebalance churn: 31-70% faster; single EqualBalanced placement: 6-26% faster; Proportional mode skips the memo (it measured 0% repeat inputs) and is unaffected. `FlowGraph` gained an internal monotonic state stamp to support this; no public API change.
+
+## [0.8.0] - 2026-08-24
+
+### Added
+
+- **Flow Policy**: `set_static_paths(src, dst, paths)` pins a demand to explicit path bundles (MPLS-style routing), finishing a feature that was ported but never bound and whose port bound every flow to the first bundle. One flow per usable bundle, each bound to its own bundle in supply order; bundles are validated against the graph and pruned against the policy's masks, and a bundle with no surviving `src->dst` walk is down (no reroute). `EqualBalanced` spreads over the up bundles only. With static paths the policy neither grows its flow set nor reoptimizes; `max_path_cost`/`-factor`, `min_flow_count` and `reoptimize_flows_on_each_placement` are inert.
+- **Shortest Paths**: `PredDAG.from_edges(graph, edges)` builds a single-path `PredDAG` from a contiguous edge-id sequence (`make_path_dag` in C++) -- the missing constructor for operator-defined explicit paths. Extracting it also deduplicates the two identical path-to-DAG conversion blocks in `k_shortest_paths` (outputs unchanged).
+
+### Fixed
+
+- **Max-Flow**: `calc_max_flow` could return less than the true maximum, since the tier loop augments only along forward SPF DAGs and never cancels an earlier placement (the reported `min_cut` then contradicted `total_flow`). Added a residual completion phase with reverse arcs. **This is the default configuration** of `max_flow`/`batch_max_flow` (`Proportional` + `require_capacity=True` + `shortest_path=False`), so recorded expected values, regression baselines and stored results must be regenerated: `total_flow` increases where the previous value was suboptimal, and `min_cut`, `edge_flows`, `residual_capacity` and `reachable_nodes` change with it. `sensitivity_analysis`, which is built on `calc_max_flow`, is affected too.
+- **Shortest Paths**: Zero-cost edges produced a cyclic predecessor DAG, making `EqualBalanced` placement return 0 flow and `resolve_to_paths` hang. Equal-cost predecessors are now recorded only while a node is unsettled, and `resolve_to_paths` guards against cycles in caller-supplied DAGs. Side effect on graphs containing zero-cost edges: among nodes mutually reachable at equal distance the settle order now decides which alternatives are kept, so a `PredDAG` can hold fewer equal-cost predecessors than in 0.7.2 and ECMP fan-out narrows accordingly. Graphs with strictly positive costs are unaffected (verified bit-identical).
+- **K-Shortest Paths**: Spur enumeration materialized every equal-cost path, exponential in ECMP fan-out (a 67-node ECMP ladder needed ~4 s and ~3.5 GiB for `k=3`, and a 73-node one ~19 s; both are now instant in ~34 MB). Enumeration is now bounded by the number of candidates still acceptable; tie-breaking among equal-cost paths may differ, but path counts and costs are unchanged.
+- **Flow Policy**: `place_demand` silently routed a second `(src, dst)` pair over the first pair's paths, and neither `place_demand` nor `rebalance_demand` checked that the supplied `FlowGraph` wrapped the policy's own graph -- with equal edge counts that selected paths on one topology and placed flow on another. Both now raise `invalid_argument` (`ValueError` from Python); use one policy per demand, or call `remove_demand()` first to retarget it.
+- **Graph Construction**: `from_arrays` now rejects a total edge cost at or above 2^62, which overflows the int64 path arithmetic in SPF and silently corrupts results. The bound is on the sum of all edge costs -- a conservative upper bound on any path -- so it can reject a graph whose individual paths could not actually overflow.
+- **Flow State**: `compute_min_cut` and max-flow reachability derived placed flow from `capacity - residual`, overstating it for a `FlowState` built with a custom `residual_init`. Both now use `edge_flow`.
+- **K-Shortest Paths**: `k_shortest_paths` read `paths.back()` on an empty vector when `max_cost_factor < 1.0` put the cost ceiling below the shortest path, crashing for `k > 1` (the `k == 1` early return masked it). All `k` now return no paths for such a factor.
+- **Python Bindings**: `batch_max_flow` rejected a valid int32 `pairs` array on Windows, because the dtype check compared buffer format strings and NumPy spells int32 as `NPY_LONG` on LLP64 but `NPY_INT` on LP64. It now compares dtype equivalence, and rejects non-contiguous `pairs` rather than reading them as if packed.
+- **Build**: `NETGRAPH_CORE_SANITIZE` passed its flags as one quoted string, so sanitizer builds never compiled, and the test target was missing them entirely. `make sanitize-test` also no longer sets `detect_leaks=1` on macOS, where it aborts.
+- **Build**: Coverage builds now use `-fprofile-update=atomic` on GCC; the default non-atomic counters corrupt under the threads used by `batch_max_flow` and `sensitivity_analysis`.
+
+### Changed
+
+- **Max-Flow**: `FlowSummary.costs`/`flows` is now a cost-weighted breakdown of the total flow rather than a list of path costs. Entries added by the new completion phase are *marginal* costs -- the augmenting path's forward edge costs minus the cost of the flow it cancels -- so an entry need not correspond to any traversable `src->dst` path. Consumers that treat these as path costs (for example a cost-distribution report) should be reviewed.
+- **Flow Policy**: `max_path_cost` no longer implies a relative factor of 1.0. Previously `max_path_cost_factor` defaulted to 1.0 whenever either limit was set, so setting `max_path_cost` alone also rejected every path costing more than the best path found -- making the absolute limit unreachable. The two limits are now independent, and a policy with only `max_path_cost` set admits every path up to that cost. (Found while fixing undefined behavior in the same expression: with an unreachable destination, `best_path_cost_` is the `INT64_MAX` sentinel and multiplying it by the factor overflowed the cast back to `int64`.)
+- **Shortest Paths**: Replaced nested per-node predecessor vectors with flat intrusive lists, removing the allocation churn that dominated the hot path (~3-4x faster; output unchanged).
+- **Flow Placement**: `place_on_dag` now rebuilds its `(parent, child)` edge groups into a reused arena instead of nested per-node vectors, which was ~70% of its runtime (~2-2.4x faster; output unchanged).
+- **Max-Flow**: Parallelized `batch_max_flow` across source/destination pairs using `std::async`; workers claim pairs from a shared counter, so a batch whose costs are unevenly distributed still parallelizes. Thread count from `NGRAPH_CORE_BATCH_THREADS` env or hardware concurrency; set it to `1` when calling from your own worker pool to avoid oversubscription.
+- **BREAKING** **C++ API**: `FlowPolicy::set_static_paths` changed signature from `(std::vector<std::tuple<NodeId, NodeId, PredDAG, Cost>>)` to `(NodeId src, NodeId dst, std::vector<PredDAG> bundles)`, and its behavior changed: the previous implementation handed every flow the first matching bundle instead of one bundle per flow. It was never bound to Python, so only C++ callers are affected.
+- **Flow Policy**: `place_demand` computes one SPF when seeding initial flows instead of repeating an identical one per flow; seeding cost no longer scales with `min_flow_count`.
+- **Flow Policy**: The `EqualBalanced` rebalance recursion (`place_demand` -> `rebalance_demand` -> `place_demand`) is now an iterative loop with numerically identical results (returned leftover may differ by ~1 ulp from floating-point summation order); with many pinned bundles of heterogeneous capacity the recursion depth grew like `U * ln(imbalance/kMinFlow)`, a stack-overflow risk on worker threads.
+- **Python Bindings**: Three input errors now raise where they previously did not, or raise a different type -- adjust `except` clauses accordingly. `Algorithms.spf` raises `TypeError` (was `ValueError`) for a wrong `residual` length, matching every other length check; `batch_max_flow` raises `ValueError` for out-of-range node ids that previously produced a zero-flow summary absorbed silently into the batch; and `Algorithms.ksp` validates `dtype` up front, where an invalid value previously went unnoticed whenever the query returned no paths.
+- **Python Bindings**: A wrong-typed `graph`/`algorithms` argument now raises `TypeError` instead of an opaque `RuntimeError: Unable to cast ... to C++ type '?'`.
+- **Python Typing**: Corrected `_docs.py` (pybind11 enums and classes are not `enum.Enum`/`dataclass`, `MinCut.edges` is an `int32` array, removed a `Path` class that never existed, and added the constructors for `FlowIndex`, `FlowPolicyConfig` and the three enums) and widened the type-checking re-exports from 6 names to all 16, so `Algorithms`, `FlowPolicy`, `StrictMultiDiGraph` and friends are no longer `Unknown` to type checkers despite the shipped `py.typed`. A missing stub constructor is now worse than no stub, so a test asserts every stub constructor matches its binding.
+- **Tests**: Several assertions could never fail and now do: a self-loop assertion sat inside `except Exception: pass`, a thread-safety test ended in `assert True` while its workers called `pytest.fail()` from a thread where it cannot fail the test, and two tautologies (`assert size >= 0`) were replaced with the properties actually under test.
+- **Docs**: Corrected README/CONTRIBUTING (required CMake is 3.23 not 3.15, `make py-test` does not exist, `make test` does not collect coverage), the `sensitivity_analysis` description in README and `backend.hpp` (it measures flow *lost* on edge removal, not gain from relaxing capacity), the zero-copy and GIL claims, and header contracts for `from_arrays`, `PredDAG`, `FlowSummary.costs`, `calc_max_flow` and `FlowPolicy`.
+
+### Removed
+
+- **Dead code**: `.gcovr.cfg` (never read -- gcovr's default config name has no leading dot, and `make cov` passes every flag explicitly), the unreachable `FlowGraph` include and `expect_flow_conservation()` helper in the C++ test utilities, unused test helpers/fixtures, `_USE_MATH_DEFINES` (no `M_*` macro is used), and unused `<optional>`/`<stack>`/`<unordered_map>`/`<unordered_set>`/`<cmath>` includes across `src/` and `include/`.
+- **BREAKING** **Python Bindings**: `Algorithms.build_graph_from_arrays`. Nothing used it (no test, and not NetGraph), and the `Graph` handle it returned could not be passed to `FlowGraph` or `FlowPolicy`, so it only ever served the stateless algorithms while looking like a peer of `build_graph`. Build the graph with `StrictMultiDiGraph.from_arrays()` and pass it to `Algorithms.build_graph()`.
+- **BREAKING** **C++ API**: The `build_graph(std::shared_ptr<const StrictMultiDiGraph>)` overload on `Algorithms` and `Backend`, which existed solely to serve that binding. It was a pure virtual, so an out-of-tree `Backend` implementation must delete its now-dangling `override` to compile. Callers wanting the handle to own the graph construct it directly: `GraphHandle{my_shared_ptr}`.
+- **BREAKING** **Python Bindings**: The `Flow` class (bound from `FlowRecord`). It was reachable only as `_netgraph_core.Flow`, never exported from `netgraph_core`, and no binding constructed or returned one, so nothing could obtain an instance; the name also collided with the C++ alias `using Flow = double`.
+
+## [0.7.2] - 2026-03-26
+
+### Fixed
+
+- Added missing `<stdexcept>` include for MSVC compatibility
+
+## [0.7.1] - 2026-03-26
+
+### Added
+
+- Windows AMD64 wheel builds in release workflow
+- Windows test coverage in CI
+
+## [0.7.0] - 2026-03-26
+
+### Changed
+
+- Relicensed from BSD-3-Clause to MIT
+- Parallelized sensitivity analysis across candidate edges using `std::async`; thread count controlled by `NGRAPH_CORE_SENSITIVITY_THREADS` env or hardware concurrency
+- Thread-local profiling stats to remove global mutex from the hot `record()` path; public API unchanged
+
+## [0.6.0] - 2026-02-26
+
+### Changed
+
+- **License**: Relicensed from GPL-3.0-or-later to BSD-3-Clause.
+
+## [0.5.0] - 2026-02-18
+
+### Changed
+
+- **License**: Relicensed from AGPL-3.0 to GPL-3.0.
+
+## [0.4.1] - 2026-02-17
+
+### Added
+
+- **Build**: Add Linux ARM64 (aarch64) wheel builds using native GitHub ARM runners in the release workflow.
+
+## [0.4.0] - 2026-02-17
+
+### Added
+
+- **Python 3.14**: Add support for Python 3.14 in CI tests, wheel builds, and packaging.
+- **Free Threading**: Declare free-threading compatibility (`py::mod_gil_not_used`) for Python 3.13t/3.14t builds. Build and publish free-threaded (`cp314t`) wheels.
+
+### Changed
+
+- **CI**: Upgrade cibuildwheel from v2 to v3.3.1 for Python 3.14 wheel builds.
+
+### Fixed
+
+- **Python Bindings**: Fix object leak on Python 3.14 caused by pybind11 not clearing managed dicts during deallocation. Replace `dynamic_attr` + `_graph_ref` pattern with `py::keep_alive` for FlowState, FlowGraph, and FlowPolicy.
+
+## [0.3.6] - 2026-02-17
+
+### Fixed
+
+- **Python Bindings**: Fix build failure with pybind11 3.x typed tuples by adding explicit `-> py::tuple` return type on the `spf` lambda.
+
+### Changed
+
+- **CI**: Add CentOS Stream 9 build and test jobs.
+
+## [0.3.5] - 2026-02-08
+
+### Fixed
+
+- **K-Shortest Paths**: Fix off-by-one in Yen's prefix comparison and PredDAG CSR fill order. Paths visiting nodes out of numerical order (e.g., `[0,3,2]`) previously produced malformed predecessor DAGs.
+
+## [0.3.4] - 2026-02-02
+
+### Changed
+
+- **Build**: Simplified version handling.
+
+## [0.3.3] - 2026-02-02
+
+### Fixed
+
+- **License**: Replaced incomplete AGPLv3 LICENSE file with complete official text from GNU.
+
+## [0.3.2] - 2025-12-12
+
+### Fixed
+
+- **Profiling**: Fix ODR violation that caused empty stats when profiling was enabled. Moved `profiling_enabled()` and `ProfilingStats::instance()` definitions from inline header to `profiling.cpp` to ensure a single instance when static library is linked into the Python module.
+
+## [0.3.1] - 2025-12-08
+
+### Added
+
+- **Profiling**: Runtime profiling infrastructure for C++ hot paths (`shortest_paths_core`, `place_demand`, `place_on_dag`).
+  - Enable via `NGRAPH_CORE_PROFILE=1` environment variable.
+  - Python API: `profiling_enabled()`, `profiling_dump()`, `profiling_reset()`.
+  - Minimal overhead when disabled (single static bool check per instrumented scope).
+  - ~2% overhead when enabled.
+
+### Changed
+
+- **Build**: Default optimizations: LTO, loop unrolling, `-fno-math-errno`. Add `make install-native` for CPU-specific builds.
+
+## [0.3.0] - 2025-12-06
+
+### Changed
+
+- **BREAKING**: Minimum Python version raised to 3.11 (was 3.9)
+
+## [0.2.3] - 2025-12-06
+
+### Changed
+
+- **Python bindings**: `StrictMultiDiGraph.from_arrays` now requires `ext_edge_ids` so callers always supply stable external edge identifiers.
+- **FlowPolicy**: construction is now config-only (via `FlowPolicyConfig`), dropping the parameter-heavy constructor.
+
+### Fixed
+
+- **FlowGraph**: `get_flow_path` now filters only below-`kEpsilon` noise so paths are reconstructed even when per-edge allocations are smaller than `kMinFlow`.
+
+## [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
+
+- **Shortest Paths**: In single-path mode, ties between equal-cost paths are now broken by preferring higher bottleneck capacity. Improves flow placement when multiple equal-cost paths exist with different capacities.
+- **Flow Placement**: Use epsilon threshold in `place_on_dag()` to fix placement of very small flow fractions in large fanout networks.
+
+### Changed
+
+- **Build**: Use `uv` build frontend for wheel builds.
+- **Build**: Drop 32-bit Linux (i686) wheels.
+
+## [0.2.0] - 2025-11-25
+
+### Added
+
+- **Sensitivity Analysis**: Added `shortest_path` parameter to `sensitivity_analysis()`.
+  - `shortest_path=False` (default): Uses full max-flow; reports all saturated edges across all cost tiers.
+  - `shortest_path=True`: Uses single-tier shortest-path flow; reports only edges used under ECMP routing.
+- Python type stub documentation for `Algorithms.sensitivity_analysis()`.
+
+## [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.

netgraph_core-0.9.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

{netgraph_core-0.7.2 → netgraph_core-0.9.0}/CMakeLists.txt

@@ -27,7 +27,11 @@ add_executable(netgraph_core_tests
   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"))
+    # Atomic counters: see the NETGRAPH_CORE_COVERAGE block below.
     target_compile_options(netgraph_core_tests PRIVATE -O0 -g --coverage)
+    if(CMAKE_CXX_COMPILER_ID MATCHES "GNU")
+      target_compile_options(netgraph_core_tests PRIVATE -fprofile-update=atomic)
+    endif()
     target_link_options(netgraph_core_tests PRIVATE --coverage)
   endif()
   include(GoogleTest)
@@ -85,7 +89,6 @@ target_include_directories(netgraph_core PUBLIC
   $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
   $<INSTALL_INTERFACE:include>
 )
-target_compile_definitions(netgraph_core PRIVATE _USE_MATH_DEFINES)
 ## C++ standard is set globally above.
 target_compile_features(netgraph_core PUBLIC cxx_std_20)
 
@@ -206,8 +209,15 @@ endif()
 if(NETGRAPH_CORE_COVERAGE)
   message(STATUS "Enabling coverage instrumentation (disables optimizations)")
   if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+    # batch_max_flow and sensitivity_analysis run worker threads, and the default
+    # non-atomic profile counters corrupt under concurrent updates (gcov then
+    # emits impossible values such as "branch 4 taken -1").
+    set(COV_FLAGS -O0 -g --coverage)
+    if(CMAKE_CXX_COMPILER_ID MATCHES "GNU")
+      list(APPEND COV_FLAGS -fprofile-update=atomic)
+    endif()
     foreach(tgt netgraph_core _netgraph_core)
-      target_compile_options(${tgt} PRIVATE -O0 -g --coverage)
+      target_compile_options(${tgt} PRIVATE ${COV_FLAGS})
       target_link_options(${tgt} PRIVATE --coverage)
     endforeach()
   else()
@@ -218,8 +228,22 @@ endif()
 if(NETGRAPH_CORE_SANITIZE)
   message(STATUS "Enabling sanitizers (disables optimizations)")
   if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
-    set(SAN_FLAGS "-fsanitize=address,undefined -fno-omit-frame-pointer")
-    foreach(tgt netgraph_core _netgraph_core)
+    # Must be a CMake list: a single quoted string reaches the compiler as one
+    # argument and clang rejects "-fsanitize=address,undefined -fno-omit-frame-pointer".
+    #
+    # -fno-sanitize-recover=undefined makes UBSan findings FATAL. Without it UBSan
+    # prints a "runtime error:" diagnostic and lets the program continue, so the test
+    # still exits 0 and ctest reports success -- undefined behaviour would be detected
+    # and then silently ignored, which is indistinguishable from not checking at all.
+    set(SAN_FLAGS -fsanitize=address,undefined -fno-omit-frame-pointer
+                  -fno-sanitize-recover=undefined)
+    set(SAN_TARGETS netgraph_core _netgraph_core)
+    if(TARGET netgraph_core_tests)
+      # The test executable links the sanitized static library, so it must be
+      # built and linked with the same flags to pull in the sanitizer runtime.
+      list(APPEND SAN_TARGETS netgraph_core_tests)
+    endif()
+    foreach(tgt ${SAN_TARGETS})
       target_compile_options(${tgt} PRIVATE ${SAN_FLAGS})
       target_link_options(${tgt} PRIVATE ${SAN_FLAGS})
     endforeach()

{netgraph_core-0.7.2 → netgraph_core-0.9.0}/CONTRIBUTING.md

@@ -47,7 +47,7 @@ Run specific test suites:
 
 ```bash
 make cpp-test   # C++ tests (GoogleTest)
-make py-test    # Python tests (pytest)
+make test       # Python tests (pytest)
 ```
 
 ### Code Style
@@ -65,13 +65,19 @@ make format
 
 Releases are automated via GitHub Actions when a new tag is pushed.
 
-1. Bump version in `pyproject.toml`.
-2. Commit and push.
-3. Create and push a tag:
+1. Move the pending notes into a new `## [X.Y.Z] - YYYY-MM-DD` section in `CHANGELOG.md`,
+   dated the day you tag. Mark anything that breaks consumers as **BREAKING**.
+2. Bump `version` in `pyproject.toml` to the same `X.Y.Z`. CI does not cross-check the
+   tag against this value, so a mismatch publishes the wrong version silently.
+3. Commit and push.
+4. Create and push a matching tag:
 
    ```bash
-   git tag v0.1.0
-   git push origin v0.1.0
+   git tag v0.8.0
+   git push origin v0.8.0
    ```
 
-4. The CI pipeline will build wheels, sdist, and publish to PyPI.
+5. The CI pipeline builds wheels and the sdist, tests them, and publishes to PyPI via
+   Trusted Publishing. `make publish` / `make publish-test` upload whatever is in your
+   local `dist/` and are for Test PyPI or emergencies only -- real releases go through
+   the tag.

{netgraph_core-0.7.2 → netgraph_core-0.9.0}/Makefile

@@ -52,7 +52,7 @@ help:
 	@echo "  make check-ci      - Run non-mutating lint + tests (CI entrypoint)"
 	@echo "  make lint          - Run only linting (non-mutating: ruff + pyright)"
 	@echo "  make format        - Auto-format code with ruff"
-	@echo "  make test          - Run tests with coverage"
+	@echo "  make test          - Run Python tests (pytest)"
 	@echo "  make qt            - Run quick tests only (exclude slow/benchmark)"
 	@echo "  make cpp-test      - Build and run C++ tests"
 	@echo "  make cov           - Coverage summary + XML + single-page combined HTML"
@@ -244,21 +244,7 @@ hooks:
 	@$(PRECOMMIT) run --all-files || (echo "Some pre-commit hooks failed. Fix and re-run." && exit 1)
 
 cpp-test:
-	@echo "🧪 Building and running C++ tests..."
-	@BUILD_DIR="build/cpp-tests"; \
-		mkdir -p "$$BUILD_DIR"; \
-		GEN_ARGS=""; \
-		if command -v ninja >/dev/null 2>&1; then GEN_ARGS="-G Ninja"; fi; \
-		cmake -S . -B "$$BUILD_DIR" -DNETGRAPH_CORE_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Release $$GEN_ARGS; \
-		cmake --build "$$BUILD_DIR" --config Release -j; \
-		if command -v sysctl >/dev/null 2>&1; then \
-			NPROC=$$(sysctl -n hw.ncpu 2>/dev/null || echo 2); \
-		elif command -v nproc >/dev/null 2>&1; then \
-			NPROC=$$(nproc); \
-		else \
-			NPROC=2; \
-		fi; \
-		ctest --test-dir "$$BUILD_DIR" --output-on-failure -j "$$NPROC" --timeout 120
+	@PATH="$(VENV_BIN):$$PATH" bash dev/cpp-tests.sh release
 
 cov:
 	@echo "📦 Reinstalling with C++ coverage instrumentation..."
@@ -281,6 +267,7 @@ cov:
 		--object-directory build/cpp-tests-cov \
 		--filter 'include/netgraph' --filter 'src' --exclude 'tests' --exclude 'bindings/.*' --exclude '.*pybind11.*' --exclude '_deps/pybind11-src/.*' \
 		--gcov-ignore-errors=all \
+		--gcov-ignore-parse-errors=negative_hits.warn_once_per_file \
 		--xml-pretty -o build/coverage/coverage-cpp.xml
 	@echo ""
 	@echo "================ Python + C++ coverage (summary) ================"
@@ -289,14 +276,7 @@ cov:
 	@echo "✅ Coverage ready in build/coverage/: coverage-python.xml, coverage-cpp.xml, coverage-combined.html"
 
 sanitize-test:
-	@echo "🧪 Building and running C++ tests with sanitizers..."
-	@BUILD_DIR="build/cpp-sanitize"; \
-		mkdir -p "$$BUILD_DIR"; \
-		GEN_ARGS=""; \
-		if command -v ninja >/dev/null 2>&1; then GEN_ARGS="-G Ninja"; fi; \
-		cmake -S . -B "$$BUILD_DIR" -DNETGRAPH_CORE_BUILD_TESTS=ON -DNETGRAPH_CORE_SANITIZE=ON -DCMAKE_BUILD_TYPE=Debug $$GEN_ARGS; \
-		cmake --build "$$BUILD_DIR" --config Debug -j; \
-		ASAN_OPTIONS=detect_leaks=1 ctest --test-dir "$$BUILD_DIR" --output-on-failure || echo "⚠️  Some sanitizer tests failed"
+	@PATH="$(VENV_BIN):$$PATH" bash dev/cpp-tests.sh sanitize
 
 # Clean + reinstall in dev mode (respects CMAKE_ARGS and MACOSX_DEPLOYMENT_TARGET)
 # Uses active PYTHON (venv or PATH) to avoid environment mismatches

{netgraph_core-0.7.2 → netgraph_core-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netgraph-core
-Version: 0.7.2
+Version: 0.9.0
 Summary: C++ implementation of graph algorithms for network flow analysis and traffic engineering with Python bindings
 Author: Project Contributors
 License-Expression: MIT
@@ -20,7 +20,7 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Operating System :: OS Independent
 Project-URL: Homepage, https://github.com/networmix/NetGraph-Core
 Requires-Python: >=3.11
-Requires-Dist: numpy>=1.22
+Requires-Dist: numpy>=1.23.2
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -45,7 +45,7 @@ NetGraph-Core provides a specialized graph implementation for networking problem
 
 - **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.
+- **Performance**: Immutable CSR (Compressed Sparse Row) adjacency, and zero-copy NumPy views over mutable flow state.
 
 ## Core Features
 
@@ -65,13 +65,17 @@ NetGraph-Core provides a specialized graph implementation for networking problem
   - Yen's algorithm returning DAG-wrapped paths.
   - Configurable constraints on cost factors (e.g., paths within 1.5x of optimal).
 
+- **Explicit Paths**:
+  - `PredDAG.from_edges(graph, edges)` builds a path bundle from an operator-supplied
+    edge sequence, usable anywhere a `PredDAG` is accepted.
+
 - **Max-Flow**:
-  - **Algorithm**: Iterative augmentation using Successive Shortest Path on residual graphs, pushing flow across full ECMP/WCMP DAGs at each step.
+  - **Algorithm**: Iterative augmentation using Successive Shortest Path on residual graphs, pushing flow across full ECMP/WCMP DAGs at each step. For `Proportional` placement with `require_capacity=True`, a final residual completion phase augments with reverse arcs so the result is a true maximum flow; the other modes are placement models and may report less.
   - **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. Supports `shortest_path` mode to analyze only edges used under ECMP routing (IP/IGP networks) vs. full max-flow (SDN/TE networks).
+  - **Sensitivity Analysis**: Identifies critical edges by removing each saturated edge and measuring how much total flow is *lost*. Supports `shortest_path` mode to analyze only edges used under ECMP routing (IP/IGP networks) vs. full max-flow (SDN/TE networks).
   - **Min-Cut**: Computes minimum cuts on residual graphs.
 
 ### 3. Flow Policy Engine
@@ -83,11 +87,36 @@ Unified configuration object (`FlowPolicy`) that models diverse routing behavior
   - `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).
+- **Static (Pinned) Paths**: `FlowPolicy.set_static_paths()` pins a demand to explicit path bundles (MPLS-style). One flow per usable bundle; a bundle with no path surviving the failure masks is *down* and carries nothing, since a pinned path does not reroute.
 
 ### 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.
+- **Zero-Copy**: `FlowState` and `FlowGraph` `*_view()` methods expose C++ buffers as read-only NumPy arrays that track mutation in place. `StrictMultiDiGraph.*_view()` returns copies instead, so the graph's immutability cannot be violated.
+- **Concurrency**: Releases the Python GIL during the long-running algorithms (SPF, KSP, max-flow, placement) to enable threading. `PredDAG.resolve_to_paths` holds the GIL. `batch_max_flow` and `sensitivity_analysis` also use internal worker threads, sized by `NGRAPH_CORE_BATCH_THREADS` / `NGRAPH_CORE_SENSITIVITY_THREADS`.
+
+## Quick Start
+
+```python
+import numpy as np
+import netgraph_core as ngc
+
+# Two parallel paths from node 0 to node 3.
+graph = ngc.StrictMultiDiGraph.from_arrays(
+    num_nodes=4,
+    src=np.array([0, 1, 0, 2], dtype=np.int32),
+    dst=np.array([1, 3, 2, 3], dtype=np.int32),
+    capacity=np.array([10.0, 10.0, 5.0, 5.0], dtype=np.float64),
+    cost=np.array([1, 1, 1, 1], dtype=np.int64),
+    ext_edge_ids=np.arange(4, dtype=np.int64),  # your own stable edge ids
+)
+
+algs = ngc.Algorithms(ngc.Backend.cpu())
+handle = algs.build_graph(graph)
+
+total, summary = algs.max_flow(handle, 0, 3)
+print(total)                            # 15.0
+print(summary.min_cut.edges.tolist())   # [0, 1] -- bottleneck edge ids
+```
 
 ## Installation
 
@@ -126,16 +155,24 @@ tests/py/               # Python tests (pytest)
 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 test       # Python tests with coverage
+make test       # Python tests
 make cpp-test   # C++ tests only
 make cov        # Combined coverage report (C++ + Python)
 ```
 
+## Environment Variables
+
+| Variable | Effect |
+| --- | --- |
+| `NGRAPH_CORE_PROFILE=1` | Enable profiling of C++ hot paths (`profiling_dump()` / `profiling_reset()`). |
+| `NGRAPH_CORE_BATCH_THREADS` | Worker threads for `batch_max_flow` (default: hardware concurrency). Set to `1` when calling from your own worker pool. |
+| `NGRAPH_CORE_SENSITIVITY_THREADS` | Worker threads for `sensitivity_analysis` (default: hardware concurrency). |
+
 ## Requirements
 
 - **C++:** C++20 compiler (GCC 10+, Clang 12+, MSVC 2019+)
 - **Python:** 3.11+
-- **Build:** CMake 3.15+, scikit-build-core
+- **Build:** CMake 3.23+, scikit-build-core
 - **Dependencies:** pybind11, NumPy
 
 ## License