NetGraph

Scenario-driven network modeling and analysis framework combining Python's flexibility with high-performance C++ algorithms.

Overview

NetGraph enables declarative modeling of network topologies, traffic matrices, and failure scenarios. It delegates computationally intensive graph algorithms to NetGraph-Core while providing a rich Python API and CLI for orchestration.

Architecture

NetGraph employs a hybrid Python+C++ architecture:

• Python layer (NetGraph): Scenario DSL parsing, workflow orchestration, result aggregation, and high-level APIs.
• C++ layer (NetGraph-Core): Performance-critical graph algorithms (SPF, KSP, Max-Flow) executing in optimized C++ with the GIL released.

Key Features

1. Modeling & DSL

• Declarative Scenarios: Define topology, traffic, and workflows in validated YAML.
• Blueprints: Reusable topology templates (e.g., Clos fabrics, regions) with parameterized expansion.
• Strict Multigraph: Deterministic graph representation with stable edge IDs.

2. Failure Analysis

• Policy Engine: Weighted failure modes with multiple policy rules per mode.
• Non-Destructive: Runtime exclusions simulate failures without modifying the base topology.
• Risk Groups: Model shared fate (e.g., fiber cuts, power zones).

3. Traffic Engineering

• Routing Modes: Unified modeling of IP Routing (static costs, oblivious to congestion) and Traffic Engineering (dynamic residuals, congestion-aware).
• Flow Placement: Strategies for ECMP (Equal-Cost Multi-Path) and WCMP (Weighted Cost Multi-Path).
• Capacity Analysis: Compute max-flow envelopes and demand allocation with configurable placement policies.

4. Workflow & Integration

• Structured Results: Export analysis artifacts to JSON for downstream processing.
• CLI: Comprehensive command-line interface for validation and execution.
• Python API: Full programmatic access to all modeling and solving capabilities.

Installation

From PyPI

pip install ngraph

From Source

git clone https://github.com/networmix/NetGraph
cd NetGraph
make dev    # Install in editable mode with dev dependencies
make check  # Run full test suite

Quick Start

CLI Usage

# Validate and inspect a scenario
ngraph inspect scenarios/backbone_clos.yml --detail

# Run analysis workflow
ngraph run scenarios/backbone_clos.yml --results clos.results.json

Python API

from ngraph.scenario import Scenario
from ngraph.types.base import FlowPlacement
from ngraph.solver.maxflow import max_flow

# Load scenario
scenario = Scenario.from_yaml("""
network:
  nodes: {A: {}, B: {}, C: {}}
  links:
    - {source: A, target: B, link_params: {capacity: 10, cost: 1}}
    - {source: B, target: C, link_params: {capacity: 10, cost: 1}}
""")

# Compute max flow
flow = max_flow(scenario.network, "A", "C", shortest_path=True)
print(f"Max flow: {flow}")

Example Scenario

NetGraph scenarios define topology, configuration, and analysis steps in a unified YAML file. This example demonstrates blueprints for modular topology definition:

seed: 42

# Define reusable topology templates
blueprints:
  Clos_Fabric:
    groups:
      spine: {node_count: 2, name_template: "spine{node_num}"}
      leaf:  {node_count: 4, name_template: "leaf{node_num}"}
    adjacency:
    - source: /leaf
      target: /spine
      pattern: mesh
      link_params: {capacity: 100, cost: 1}
    - source: /spine
      target: /leaf
      pattern: mesh
      link_params: {capacity: 100, cost: 1}

# Instantiate network from templates
network:
  groups:
    site1: {use_blueprint: Clos_Fabric}
    site2: {use_blueprint: Clos_Fabric}
  adjacency:
  - source: {path: site1/spine}
    target: {path: site2/spine}
    pattern: one_to_one
    link_params: {capacity: 50, cost: 10}

# Define traffic matrix
traffic_matrix_set:
  global_traffic:
    - source_path: ^site1/leaf/
      sink_path: ^site2/leaf/
      demand: 100.0
      mode: combine
      flow_policy_config: SHORTEST_PATHS_ECMP

# Define analysis workflow
workflow:
- step_type: NetworkStats
  name: stats
- step_type: MaxFlow
  name: site_capacity
  source_path: ^site1/leaf/
  sink_path: ^site2/leaf/
  mode: combine
  shortest_path: false
- step_type: MaximumSupportedDemand
  name: max_demand
  matrix_name: global_traffic

Repository Structure

ngraph/             # Python package source
  dsl/              # Scenario parsing and blueprint expansion
  model/            # Network and flow domain models
  solver/           # Algorithms and Core wrappers
  workflow/         # Analysis steps and orchestration
scenarios/          # Example scenario definitions
tests/              # Pytest suite (unit and integration)
docs/               # Documentation source (MkDocs)
dev/                # Development tools and scripts

Development

make dev        # Setup environment
make check      # Run tests and linting
make lint       # Run linting only
make test       # Run tests only
make docs-serve # Preview documentation

Requirements

• Python: 3.9+
• NetGraph-Core: Compatible C++ backend version

Documentation

• Site: networmix.github.io/NetGraph
• Tutorial: Getting Started
• Reference: API | CLI | DSL

License

GNU Affero General Public License v3.0 or later