NetGraph

Network modeling and analysis framework: Python front end, C++ graph algorithms.

What It Does

NetGraph models network topologies, traffic demands and failure scenarios, and analyzes capacity and resilience. Networks are defined in Python or in YAML; max-flow and failure simulations export reproducible JSON.

Install

pip install ngraph

Python API

from ngraph import (
    CapacityQuery, Link, Network, Node, Scenario, Selector, UnitsSettings,
    capacity, prepare,
)

# Three nodes in a line, joined by links of capacity 10
network = Network()
for name in ("A", "B", "C"):
    network.add_node(Node(name))
network.add_link(Link("A", "B", capacity=10))
network.add_link(Link("B", "C", capacity=10))

# Prepare the graph once, with a bandwidth unit q of 1.
prepared = prepare(Scenario(network, units=UnitsSettings(resolution=1)))
result = capacity(prepared, CapacityQuery(Selector("^A$"), Selector("^C$")))
row = result.cases[0].states["converged"].rows[0]
print(row.result.delivered)

10

It prints 10: native bandwidth results are whole units of one bandwidth unit q, and UnitsSettings(resolution=1) sets q to 1 (Units and the resolution q). A CapacityQuery without a model asks for the most that optimized traffic engineering carries from the sources to the targets (TE_MAXFLOW_UNLIM); cases[0] is the case without failures, states["converged"] its one state and rows[0] the A-to-C answer (Failures: patterns, cases and states). For capacities this small, q = 1 misses the default precision target although nothing is rounded, and prepared.units_report.target_met is false (Precision and the choice of q).

Scenario DSL

For reproducible analysis workflows, define topology, demands, and failure policies in YAML (this is scenarios/readme_example.yml):

# Two Clos sites built from one blueprint and joined spine to spine. The workflow finds
# the largest tested feasible demand multiplier (alpha), then places the demands at that
# alpha under 100 draws of one random link failure.
seed: 42

# A reusable topology template
blueprints:
  Clos_Fabric:
    nodes:
      spine: {count: 2, template: "spine{n}"}
      leaf: {count: 4, template: "leaf{n}"}
    links:
      - {source: /leaf, target: /spine, pattern: mesh, capacity: 100}

# Two instances of the template, linked spine to spine
network:
  nodes:
    site1: {blueprint: Clos_Fabric}
    site2: {blueprint: Clos_Fabric}
  links:
    - {source: site1/spine, target: site2/spine, pattern: one_to_one, capacity: 50}

# One random link fails per draw
failures:
  random_link:
    modes:
      - weight: 1
        rules:
          - {scope: link, mode: choice, count: 1}

# Traffic from the leaves of site1 to the leaves of site2
demands:
  global_traffic:
    - {source: ^site1/leaf/, target: ^site2/leaf/, volume: 100, preset: SHORTEST_PATHS_ECMP}

workflow:
  - type: MaximumSupportedDemand
    name: max_demand
    demand_set: global_traffic
  - type: TrafficMatrixPlacement
    name: placement_at_max
    demand_set: global_traffic
    alpha_from_step: max_demand  # its largest tested feasible alpha
    failure_policy: random_link
    iterations: 100

ngraph run scenarios/readme_example.yml --output results/
jq '.steps[] | select(.name == "max_demand") | .result.alpha_feasible.value' results/readme_example.results.json

A preset chooses routing and admission; SHORTEST_PATHS_ECMP splits whole units equally among equal-cost next hops at each router (Routing models and admission). How NetGraph computes explains the presets such as SHORTEST_PATHS_ECMP, maximum supported demand and the numbers in the results; run(prepare(scenario)) returns the same results in Python.

Capabilities

• Declarative scenarios: schema-validated YAML and reusable blueprints
• Failure analysis: weighted failure modes, risk groups, and analysis-time exclusions that leave the base topology untouched
• Routing models: cost-only IP routing and capacity-aware traffic engineering
• Traffic placement: ECMP and WCMP splits, maximum flow and demand placement
• Reproducible results: seeded randomness and stable link ids
• C++ algorithms with the GIL released, via NetGraph-Core

Documentation

• Tutorial - Running a scenario from the CLI and from Python
• How NetGraph computes - How a scenario becomes numbers
• Examples - From a four-node network to the bundled scenarios
• Scenario YAML - Every scenario key
• Python API - The library by task

License

MIT License

Requirements

• Python 3.11+
• NetGraph-Core (installed automatically)