netgraph-core 0.3.2__cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

netgraph_core/__init__.py

@@ -0,0 +1,72 @@
+"""Runtime package surface for :mod:`netgraph_core`.
+
+All public symbols are re-exported from the compiled ``_netgraph_core`` module so
+downstream users import everything from a single place. Typing shims supplied in
+``_docs.py`` keep editors happy without affecting runtime behavior.
+"""
+
+# pyright: reportMissingImports=false
+
+from _netgraph_core import (
+    Algorithms,
+    Backend,
+    EdgeSelection,
+    EdgeTieBreak,
+    FlowGraph,
+    FlowIndex,
+    FlowPlacement,
+    FlowPolicy,
+    FlowPolicyConfig,
+    FlowState,
+    FlowSummary,
+    Graph,
+    MinCut,
+    PathAlg,
+    PredDAG,
+    StrictMultiDiGraph,
+    profiling_dump,
+    profiling_enabled,
+    profiling_reset,
+)
+
+from ._version import __version__
+
+# Provide richer type information for editors/type-checkers without affecting runtime.
+try:  # pragma: no cover - typing-only import
+    from typing import TYPE_CHECKING as _TYPE_CHECKING
+
+    if _TYPE_CHECKING:  # noqa: SIM108
+        from ._docs import (  # noqa: I001
+            EdgeSelection as EdgeSelection,
+            EdgeTieBreak as EdgeTieBreak,
+            FlowPlacement as FlowPlacement,
+            FlowSummary as FlowSummary,
+            MinCut as MinCut,
+            PredDAG as PredDAG,
+        )
+except ImportError:
+    # Safe fallback if _docs.py changes; runtime bindings above remain authoritative.
+    pass
+
+__all__ = [
+    "__version__",
+    "StrictMultiDiGraph",
+    "FlowGraph",
+    "Graph",
+    "EdgeSelection",
+    "EdgeTieBreak",
+    "PathAlg",
+    "FlowPlacement",
+    "FlowPolicy",
+    "FlowPolicyConfig",
+    "PredDAG",
+    "FlowIndex",
+    "FlowState",
+    "MinCut",
+    "FlowSummary",
+    "Backend",
+    "Algorithms",
+    "profiling_enabled",
+    "profiling_dump",
+    "profiling_reset",
+]

netgraph_core/_docs.py

@@ -0,0 +1,604 @@
+"""Typing and docstrings for netgraph_core public API.
+
+This module is intentionally light; runtime implementations live in the
+compiled extension. The goal is to provide type hints and help text.
+
+TODO: replace this hand-written stub with generated `.pyi` (e.g. via
+pybind11-stubgen) to prevent drift from the runtime bindings.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:  # only for typing; runtime comes from extension
+    import numpy as np  # type: ignore[reportMissingImports]
+    # Use forward references (strings) below; avoid importing from the package
+    # to prevent circular imports during type checking.
+
+
+class EdgeTieBreak(Enum):
+    DETERMINISTIC = 1
+    PREFER_HIGHER_RESIDUAL = 2
+
+
+@dataclass
+class EdgeSelection:
+    multi_edge: bool = True
+    require_capacity: bool = False
+    tie_break: EdgeTieBreak = EdgeTieBreak.DETERMINISTIC
+
+
+class FlowPlacement(Enum):
+    """How to place flow across equal-cost predecessors during augmentation.
+
+    PROPORTIONAL (WCMP-like): Distributes flow proportionally to available capacity.
+        May be used iteratively (e.g., for max-flow).
+
+    EQUAL_BALANCED (ECMP): Single-pass admission on a fixed shortest-path DAG (Dijkstra).
+        Computes one global scale so no edge is oversubscribed under equal
+        per-edge splits, places once, and stops. Re-invoking on updated
+        residuals changes the next-hop set (progressive traffic-engineering behavior).
+        ECMP = Equal-Cost Multi-Path; WCMP = Weighted-Cost Multi-Path.
+    """
+
+    PROPORTIONAL = 1
+    EQUAL_BALANCED = 2
+
+
+class PredDAG:
+    """Compact predecessor DAG representation.
+
+    Arrays are int32; offsets has length N+1.
+    """
+
+    parent_offsets: np.ndarray
+    parents: np.ndarray
+    via_edges: np.ndarray
+
+    def resolve_to_paths(
+        self,
+        src: int,
+        dst: int,
+        *,
+        split_parallel_edges: bool = False,
+        max_paths: Optional[int] = None,
+    ) -> list[tuple[tuple[int, tuple[int, ...]], ...]]: ...
+
+
+class PathAlg(Enum):
+    SPF = 1
+
+
+class Backend:
+    """Backend for algorithm execution (typing stub only)."""
+
+    @staticmethod
+    def cpu() -> "Backend":
+        """Create a CPU backend."""
+        ...
+
+
+class Graph:
+    """Opaque graph handle provided by the runtime extension (typing stub only)."""
+
+    ...
+
+
+class FlowGraph:
+    """Flow graph for multi-commodity flow tracking.
+
+    Views return read-only NumPy arrays referencing internal C++ memory.
+    The FlowGraph must remain alive while views are in use.
+    """
+
+    def __init__(self, graph: "StrictMultiDiGraph") -> None: ...
+
+    def capacity_view(self) -> "np.ndarray":
+        """Return read-only float64 view of edge capacities."""
+        ...
+
+    def residual_view(self) -> "np.ndarray":
+        """Return read-only float64 view of residual capacities."""
+        ...
+
+    def edge_flow_view(self) -> "np.ndarray":
+        """Return read-only float64 view of placed flows."""
+        ...
+
+    @property
+    def graph(self) -> "StrictMultiDiGraph": ...
+
+    def place(
+        self,
+        index: "FlowIndex",
+        src: int,
+        dst: int,
+        dag: "PredDAG",
+        amount: float,
+        flow_placement: FlowPlacement = FlowPlacement.PROPORTIONAL,
+    ) -> float: ...
+
+    def remove(self, index: "FlowIndex") -> None: ...
+    def remove_by_class(self, cls: int) -> None: ...
+    def reset(self) -> None: ...
+    def get_flow_edges(self, index: "FlowIndex") -> list[tuple[int, float]]: ...
+    def get_flow_path(self, index: "FlowIndex") -> list[int]: ...
+
+
+class FlowState:
+    """Flow state tracker for a single-commodity flow problem.
+
+    Tracks per-edge residual capacity and flow placement for a graph.
+
+    **Lifetime & Memory Safety:**
+    - Views (capacity_view, residual_view, edge_flow_view) return read-only
+      NumPy arrays that directly reference internal C++ memory (zero-copy).
+    - The FlowState must remain alive while these views are in use.
+    - Arrays passed as 'residual' to __init__ or reset() are **copied** internally.
+    - Masks passed to compute_min_cut() are **copied** before releasing GIL (thread-safe).
+
+    **Array Requirements:**
+    - All arrays must be 1-D, C-contiguous, and have correct dtype (float64 for
+      residual, bool for masks).
+    - Mask lengths must match num_nodes/num_edges exactly or TypeError is raised.
+    """
+
+    def __init__(
+        self, graph: "StrictMultiDiGraph", residual: "Optional[np.ndarray]" = None
+    ) -> None:
+        """Initialize FlowState with a graph and optional residual capacities.
+
+        Args:
+            graph: The network graph (kept alive automatically)
+            residual: Optional 1-D float64 array of initial residual capacities.
+                     If not provided, uses graph capacities. **Array is copied.**
+
+        Raises:
+            TypeError: If residual has wrong dtype, ndim, or length.
+        """
+        ...
+
+    def reset(self, residual: "Optional[np.ndarray]" = None) -> None:
+        """Reset flow state to initial capacities.
+
+        Args:
+            residual: Optional 1-D float64 array. **Array is copied.**
+        """
+        ...
+
+    def capacity_view(self) -> "np.ndarray":
+        """Return read-only float64 view of edge capacities (zero-copy)."""
+        ...
+
+    def residual_view(self) -> "np.ndarray":
+        """Return read-only float64 view of residual capacities (zero-copy)."""
+        ...
+
+    def edge_flow_view(self) -> "np.ndarray":
+        """Return read-only float64 view of placed flows (zero-copy)."""
+        ...
+
+    def place_on_dag(
+        self,
+        src: int,
+        dst: int,
+        dag: "PredDAG",
+        requested_flow: float = float("inf"),
+        flow_placement: FlowPlacement = FlowPlacement.PROPORTIONAL,
+    ) -> float:
+        """Place flow along a predecessor DAG.
+
+        EqualBalanced is **single-pass ECMP admission** on the provided DAG:
+        we compute one global scale so no edge is oversubscribed under equal per-edge
+        splits, apply it once, and return. Re-invoking on updated residuals changes
+        the next-hop set (progressive behavior).
+
+        Returns:
+            Amount of flow actually placed (may be less than requested).
+        """
+        ...
+
+    def place_max_flow(
+        self,
+        src: int,
+        dst: int,
+        flow_placement: FlowPlacement = FlowPlacement.PROPORTIONAL,
+        shortest_path: bool = False,
+        require_capacity: bool = True,
+        *,
+        node_mask: "Optional[np.ndarray]" = None,
+        edge_mask: "Optional[np.ndarray]" = None,
+    ) -> float:
+        """Place maximum flow from src to dst.
+
+        Args:
+            require_capacity: Whether to require edges to have capacity.
+                - True (default): Routes adapt to residuals (SDN/TE, progressive fill).
+                - False: Routes based on costs only (IP/IGP, fixed routing).
+            node_mask: Optional 1-D bool array (True=allowed). Copied for thread safety.
+            edge_mask: Optional 1-D bool array (True=allowed). Copied for thread safety.
+
+        For *IP-style ECMP* max-flow, use: require_capacity=False, shortest_path=True,
+        flow_placement=EQUAL_BALANCED.
+
+        Caution: with require_capacity=True + EQUAL_BALANCED, this method iterates shortest-path +
+        placement (progressive fill), which differs from single-pass ECMP admission.
+
+        Returns:
+            Total flow placed.
+        """
+        ...
+
+    def compute_min_cut(
+        self,
+        src: int,
+        *,
+        node_mask: "Optional[np.ndarray]" = None,
+        edge_mask: "Optional[np.ndarray]" = None,
+    ) -> "MinCut":
+        """Compute minimum cut from source based on current residual.
+
+        Args:
+            src: Source node for reachability analysis
+            node_mask: Optional 1-D bool array of length num_nodes. **Copied for thread safety.**
+            edge_mask: Optional 1-D bool array of length num_edges. **Copied for thread safety.**
+
+        Returns:
+            MinCut object with edges in the cut set.
+
+        Raises:
+            TypeError: If masks have wrong dtype, ndim, or length.
+        """
+        ...
+
+
+class StrictMultiDiGraph:
+    """Opaque graph structure provided by the runtime extension (typing stub only)."""
+
+    ...
+
+
+class FlowIndex:
+    src: int
+    dst: int
+    flowClass: int
+    flowId: int
+
+
+class FlowPolicyConfig:
+    """Configuration for FlowPolicy behavior.
+
+    Key Parameters:
+        multipath: Controls whether individual flows split across multiple equal-cost paths.
+            - True (default): Hash-based ECMP - each flow uses a DAG with ALL equal-cost paths.
+              Flow volume is split across these paths according to flow_placement strategy.
+              This models router ECMP behavior where packets are hashed across next-hops.
+            - False: Tunnel-based ECMP - each flow uses a SINGLE path (one tunnel/LSP).
+              Multiple flows can share the same path. This models MPLS LSP semantics where
+              each LSP follows one specific path, and ECMP means balancing ACROSS LSPs.
+    """
+
+    path_alg: PathAlg
+    flow_placement: FlowPlacement
+    selection: EdgeSelection
+    require_capacity: bool
+    multipath: bool
+    min_flow_count: int
+    max_flow_count: Optional[int]
+    max_path_cost: Optional[int]
+    max_path_cost_factor: Optional[float]
+    shortest_path: bool
+    reoptimize_flows_on_each_placement: bool
+    max_no_progress_iterations: int
+    max_total_iterations: int
+    diminishing_returns_enabled: bool
+    diminishing_returns_window: int
+    diminishing_returns_epsilon_frac: float
+
+
+class FlowPolicy:
+    """Flow policy for demand placement.
+
+    When static_paths is empty the policy may refresh the DAG per round using
+    residual-aware shortest paths. This progressively prunes saturated next-hops
+    (traffic-engineering style) and differs from one-shot ECMP admission.
+
+    Args:
+        algorithms: Algorithms instance (kept alive by FlowPolicy)
+        graph: Graph handle (kept alive by FlowPolicy)
+        config: FlowPolicyConfig with all policy parameters
+        node_mask: Optional 1-D bool array (True=allowed). **Copied for thread safety.**
+        edge_mask: Optional 1-D bool array (True=allowed). **Copied for thread safety.**
+
+    Raises:
+        TypeError: If masks have wrong dtype, ndim, or length.
+    """
+
+    def __init__(
+        self,
+        algorithms: "Algorithms",
+        graph: "Graph",
+        config: "FlowPolicyConfig",
+        *,
+        node_mask: "Optional[np.ndarray]" = None,
+        edge_mask: "Optional[np.ndarray]" = None,
+    ) -> None: ...
+
+    def flow_count(self) -> int: ...
+    def placed_demand(self) -> float: ...
+    def place_demand(
+        self,
+        flow_graph: "FlowGraph",
+        src: int,
+        dst: int,
+        flowClass: int,
+        volume: float,
+        target_per_flow: Optional[float] = None,
+        min_flow: Optional[float] = None,
+    ) -> tuple[float, float]: ...
+
+    def rebalance_demand(
+        self,
+        flow_graph: "FlowGraph",
+        src: int,
+        dst: int,
+        flowClass: int,
+        target: float,
+    ) -> tuple[float, float]: ...
+
+    def remove_demand(self, flow_graph: "FlowGraph") -> None: ...
+
+    @property
+    def flows(self) -> dict[tuple[int, int, int, int], tuple[int, int, int, float]]: ...
+
+
+@dataclass(frozen=True)
+class Path:
+    nodes: np.ndarray
+    edges: np.ndarray
+    cost: float
+
+
+class MinCut:
+    edges: list[int]
+
+
+@dataclass(frozen=True)
+class FlowSummary:
+    total_flow: float
+    min_cut: MinCut
+    costs: "np.ndarray"  # int64[K]
+    flows: "np.ndarray"  # float64[K]
+    edge_flows: "np.ndarray"
+    residual_capacity: "np.ndarray"
+    reachable_nodes: "np.ndarray"
+
+
+class Algorithms:
+    """Core graph algorithms with thread-safe bindings.
+
+    **Thread Safety & Array Handling:**
+    - All input arrays (residual, node_mask, edge_mask) are **copied** before
+      releasing the GIL, ensuring thread safety even if Python code mutates
+      the arrays concurrently.
+    - All arrays must be 1-D, C-contiguous, with correct dtype.
+    - Mask lengths must match num_nodes/num_edges exactly or TypeError is raised.
+
+    **Lifetime Management:**
+    - Algorithms instances must be kept alive while Graph handles derived from
+      them are in use (automatic via Python reference counting in normal usage).
+    """
+
+    def __init__(self, backend: "Backend") -> None: ...
+
+    def build_graph(self, graph: "StrictMultiDiGraph") -> "Graph":
+        """Build a graph handle from StrictMultiDiGraph.
+
+        The graph object is kept alive automatically.
+        """
+        ...
+
+    def build_graph_from_arrays(
+        self,
+        num_nodes: int,
+        src: "np.ndarray",
+        dst: "np.ndarray",
+        capacity: "np.ndarray",
+        cost: "np.ndarray",
+        ext_edge_ids: "np.ndarray",
+    ) -> "Graph":
+        """Build graph directly from arrays (graph is owned by the handle)."""
+        ...
+
+    def spf(
+        self,
+        graph: "Graph",
+        src: int,
+        dst: Optional[int] = None,
+        *,
+        selection: Optional[EdgeSelection] = None,
+        residual: Optional["np.ndarray"] = None,
+        node_mask: Optional["np.ndarray"] = None,
+        edge_mask: Optional["np.ndarray"] = None,
+        multipath: bool = True,
+        dtype: str = "float64",
+    ) -> tuple["np.ndarray", "PredDAG"]:
+        """Shortest path first algorithm.
+
+        Args:
+            graph: Graph handle
+            src: Source node
+            dst: Optional destination (if None, compute from source to all)
+            selection: Edge selection policy
+            residual: Optional 1-D float64 array of residuals. **Copied for thread safety.**
+            node_mask: Optional 1-D bool mask (length num_nodes). **Copied for thread safety.**
+                       True = node allowed, False = node excluded.
+                       **If source node is masked (False), returns empty DAG with all distances at infinity.**
+            edge_mask: Optional 1-D bool mask (length num_edges). **Copied for thread safety.**
+                       True = edge allowed, False = edge excluded.
+            multipath: Whether to track multiple equal-cost paths
+            dtype: "float64" (inf for unreachable) or "int64" (max for unreachable)
+
+        Returns:
+            (distances, predecessor_dag)
+
+        Note:
+            When the source node is masked out (node_mask[src] == False), the algorithm
+            immediately returns an empty predecessor DAG with all distances set to infinity,
+            as no traversal can begin from an excluded source.
+
+        Raises:
+            TypeError: If arrays have wrong dtype, ndim, or length.
+            ValueError: If src/dst out of range.
+        """
+        ...
+
+    def ksp(
+        self,
+        graph: "Graph",
+        src: int,
+        dst: int,
+        *,
+        k: int,
+        max_cost_factor: Optional[float] = None,
+        unique: bool = True,
+        node_mask: Optional["np.ndarray"] = None,
+        edge_mask: Optional["np.ndarray"] = None,
+        dtype: str = "float64",
+    ) -> list[tuple["np.ndarray", "PredDAG"]]:
+        """K shortest paths algorithm.
+
+        Args:
+            k: Number of paths to find
+            max_cost_factor: Optional maximum cost factor relative to shortest
+            node_mask: Optional 1-D bool mask. **Copied for thread safety.**
+            edge_mask: Optional 1-D bool mask. **Copied for thread safety.**
+
+        Returns:
+            List of (distances, dag) tuples, up to k paths.
+
+        Note:
+            Tie-breaking is deterministic by edge ID. EdgeSelection policy is not used.
+        """
+        ...
+
+    def max_flow(
+        self,
+        graph: "Graph",
+        src: int,
+        dst: int,
+        *,
+        flow_placement: FlowPlacement = FlowPlacement.PROPORTIONAL,
+        shortest_path: bool = False,
+        require_capacity: bool = True,
+        with_edge_flows: bool = False,
+        with_reachable: bool = False,
+        with_residuals: bool = False,
+        node_mask: Optional["np.ndarray"] = None,
+        edge_mask: Optional["np.ndarray"] = None,
+    ) -> tuple[float, "FlowSummary"]:
+        """Maximum flow algorithm.
+
+        Behavior depends on require_capacity parameter:
+
+        - require_capacity=True (default): "True max-flow" - require edges to have capacity,
+          exclude saturated links (SDN/TE behavior). Uses all available paths.
+
+        - require_capacity=False: "IP ECMP" - routes based on costs only (IP/IGP behavior).
+          Routes computed once from topology, ignoring capacity. Models OSPF/IS-IS routing.
+
+        Common configurations:
+
+        1. True max-flow (SDN/TE):
+           require_capacity=True, shortest_path=False
+
+        2. IP ECMP max-flow:
+           require_capacity=False, shortest_path=True, flow_placement=EQUAL_BALANCED
+
+        3. IP WCMP max-flow:
+           require_capacity=False, shortest_path=True, flow_placement=PROPORTIONAL
+
+        Args:
+            require_capacity: Whether to require edges to have capacity.
+            shortest_path: Whether to restrict to lowest-cost tier only.
+            flow_placement: How to split flow across parallel edges (ECMP vs WCMP).
+            node_mask: Optional 1-D bool mask. **Copied for thread safety.**
+            edge_mask: Optional 1-D bool mask. **Copied for thread safety.**
+
+        Returns:
+            (total_flow, flow_summary)
+        """
+        ...
+
+    def batch_max_flow(
+        self,
+        graph: "Graph",
+        pairs: "np.ndarray",
+        *,
+        node_masks: Optional[list["np.ndarray"]] = None,
+        edge_masks: Optional[list["np.ndarray"]] = None,
+        flow_placement: FlowPlacement = FlowPlacement.PROPORTIONAL,
+        shortest_path: bool = False,
+        require_capacity: bool = True,
+        with_edge_flows: bool = False,
+        with_reachable: bool = False,
+        with_residuals: bool = False,
+    ) -> list[FlowSummary]:
+        """Batch maximum flow for multiple (src,dst) pairs.
+
+        Args:
+            pairs: int32 array of shape [B, 2] with (src, dst) pairs
+            node_masks: Optional list of B bool masks. **Each copied for thread safety.**
+            edge_masks: Optional list of B bool masks. **Each copied for thread safety.**
+            require_capacity: If True, exclude saturated edges (SDN/TE). If False, route by cost only (IP/IGP).
+
+        Returns:
+            List of FlowSummary objects, one per pair.
+        """
+        ...
+
+    def sensitivity_analysis(
+        self,
+        graph: "Graph",
+        src: int,
+        dst: int,
+        *,
+        flow_placement: FlowPlacement = FlowPlacement.PROPORTIONAL,
+        shortest_path: bool = False,
+        require_capacity: bool = True,
+        node_mask: Optional["np.ndarray"] = None,
+        edge_mask: Optional["np.ndarray"] = None,
+    ) -> list[tuple[int, float]]:
+        """Sensitivity analysis to identify critical edges that constrain flow.
+
+        Computes baseline flow, then tests removing each saturated edge to
+        measure how much the total flow would be reduced.
+
+        The `shortest_path` parameter controls the routing semantics:
+
+        - shortest_path=False (default): Full max-flow analysis (SDN/TE mode).
+          Identifies edges critical for achieving maximum possible flow.
+
+        - shortest_path=True: Shortest-path-only analysis (IP/IGP mode).
+          Identifies edges critical for flow under ECMP routing. Edges on
+          unused longer paths are not reported as critical.
+
+        Args:
+            graph: Graph handle
+            src: Source node
+            dst: Destination node
+            flow_placement: Flow placement strategy
+            shortest_path: If True, use single-pass shortest-path flow (IP/IGP).
+                          If False, use full iterative max-flow (SDN/TE).
+            require_capacity: If True, exclude saturated edges from routing.
+            node_mask: Optional 1-D bool mask. **Copied for thread safety.**
+            edge_mask: Optional 1-D bool mask. **Copied for thread safety.**
+
+        Returns:
+            List of (edge_id, flow_delta) tuples. Each edge_id is an edge
+            whose removal would reduce total flow by flow_delta.
+        """
+        ...

netgraph_core/_version.py

@@ -0,0 +1,5 @@
+"""netgraph_core version metadata."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.3.2"

netgraph_core-0.3.2.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.2
+Name: netgraph-core
+Version: 0.3.2
+Summary: C++ implementation of graph algorithms for network flow analysis and traffic engineering with Python bindings
+Author: Project Contributors
+License: AGPL-3.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: C++
+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
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-benchmark; extra == "dev"
+Requires-Dist: gcovr>=7; extra == "dev"
+Requires-Dist: ruff==0.11.13; extra == "dev"
+Requires-Dist: pyright==1.1.401; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: cmake>=3.23; extra == "dev"
+Requires-Dist: ninja; extra == "dev"
+Description-Content-Type: text/markdown
+
+# NetGraph-Core
+
+C++ graph engine for network flow analysis, traffic engineering simulation, and capacity planning.
+
+## Overview
+
+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. 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
+
+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
+
+```bash
+pip install netgraph-core
+```
+
+Or from source:
+
+```bash
+pip install -e .
+```
+
+### Build Optimizations
+
+Default builds include LTO and loop unrolling. For local development:
+
+```bash
+make install-native   # CPU-specific optimizations (not portable)
+```
+
+## 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 test       # Python tests with coverage
+make cpp-test   # C++ tests only
+make cov        # Combined coverage report (C++ + Python)
+```
+
+## Requirements
+
+- **C++:** C++20 compiler (GCC 10+, Clang 12+, MSVC 2019+)
+- **Python:** 3.11+
+- **Build:** CMake 3.15+, scikit-build-core
+- **Dependencies:** pybind11, NumPy
+
+## License
+
+AGPL-3.0-or-later

netgraph_core-0.3.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+_netgraph_core.cpython-312-x86_64-linux-gnu.so,sha256=imS3CpY193RGEPjhyuPKrEwB3Gs74A-0lel1tYcTZhg,869120
+netgraph_core-0.3.2.dist-info/RECORD,,
+netgraph_core-0.3.2.dist-info/WHEEL,sha256=mHU8IgtXlS9dt0QiyHytIewnnNX1NrwZMGogjhxiHgs,156
+netgraph_core-0.3.2.dist-info/METADATA,sha256=Ic6cJqGuzefLnGuAYnbpEdsvBO4A2MwcD7Sm97kxPpg,5536
+netgraph_core-0.3.2.dist-info/licenses/LICENSE,sha256=lKbJTfEk6X57dZfORMJJrYPQGNQk8ypxQnlh14A48lc,7070
+netgraph_core/__init__.py,sha256=Crlj39aIZV0STiL3_w6S2FH4x13Tj906gb2x6Zjg0jY,1740
+netgraph_core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+netgraph_core/_docs.py,sha256=qOflLG0zDQ2un0zxQ9q6CdqXbaDSs8CDdWFuN91cgs0,20367
+netgraph_core/_version.py,sha256=uHeg5yAzQiHBeFhKJ-6zwAQdxbT4eJQEsRLbWYMwd8g,88

netgraph_core-0.3.2.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: scikit-build-core 0.11.6
+Root-Is-Purelib: false
+Tag: cp312-cp312-manylinux_2_17_x86_64
+Tag: cp312-cp312-manylinux2014_x86_64
+

netgraph_core-0.3.2.dist-info/licenses/LICENSE

@@ -0,0 +1,148 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+Preamble
+
+The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+The precise terms and conditions for copying, distribution and
+modification follow.
+
+TERMS AND CONDITIONS
+
+0. Definitions.
+
+"This License" refers to version 3 of the GNU Affero General Public License.
+
+"Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+"The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+1. Source Code.
+
+The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+... (AGPLv3 full text continues; include the entire standard text without modification) ...
+
+How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.