Skip to content

api.md

Latest commit

 

History

History
255 lines (192 loc) · 6.08 KB

api.md

File metadata and controls

255 lines (192 loc) · 6.08 KB

API Reference

This section provides detailed documentation for NetGraph's Python API.

📚 Quick Navigation:

Core Classes

Scenario

The main entry point for building and running network analyses.

from ngraph.scenario import Scenario

# Create from YAML
scenario = Scenario.from_yaml(yaml_content)

# Create programmatically
scenario = Scenario()
scenario.network = Network()
scenario.run()

Key Methods:

  • from_yaml(yaml_content) - Create scenario from YAML string
  • run() - Execute the scenario workflow

Network

Represents the network topology and provides analysis methods.

from ngraph.network import Network

network = Network()
# Access nodes, links, and analysis methods

Key Methods:

  • max_flow(source_path, sink_path, **kwargs) - Calculate maximum flow
  • add_node(name, **attrs) - Add network node
  • add_link(source, target, **params) - Add network link

NetworkExplorer

Provides network visualization and exploration capabilities.

from ngraph.explorer import NetworkExplorer

explorer = NetworkExplorer.explore_network(network)
explorer.print_tree(skip_leaves=True, detailed=False)

Flow Analysis

FlowPlacement

Enumeration of flow placement policies for traffic engineering.

from ngraph.lib.algorithms.base import FlowPlacement

# Available policies:
FlowPlacement.EQUAL_BALANCED    # ECMP - equal distribution
FlowPlacement.PROPORTIONAL      # UCMP - capacity proportional

Flow Calculation Methods

# Maximum flow analysis
max_flow = network.max_flow(
    source_path="datacenter1/servers",
    sink_path="datacenter2/servers",
    mode="combine",                    # or "full_mesh"
    shortest_path=True,               # Use shortest paths only
    flow_placement=FlowPlacement.EQUAL_BALANCED
)

Blueprint System

Blueprint Definition

Blueprints are defined in YAML and loaded through the scenario system:

from ngraph.blueprints import Blueprint

# Blueprint is a dataclass that holds blueprint configuration
# Blueprints are typically loaded from YAML, not created programmatically
blueprint = Blueprint(
    name="my_blueprint",
    groups={
        "servers": {"node_count": 4},
        "switches": {"node_count": 2}
    },
    adjacency=[
        {"source": "/servers", "target": "/switches", "pattern": "mesh"}
    ]
)

# Note: Blueprint objects are usually created internally when parsing YAML
# For programmatic creation, use the Network class directly

Traffic Demands

TrafficDemand

Define and manage traffic demands between network segments.

from ngraph.traffic_demand import TrafficDemand

demand = TrafficDemand(
    name="web_traffic",
    source_path="web_servers",
    sink_path="databases",
    volume=1000,
    mode="full_mesh"
)

Failure Modeling

FailurePolicy

Configure failure simulation parameters.

from ngraph.failure_policy import FailurePolicy

policy = FailurePolicy(
    enable_failures=True,
    max_concurrent_failures=2,
    failure_probability=0.01
)

Risk Groups

Model correlated component failures.

# Risk groups are typically defined in YAML
risk_groups = [
    {
        "name": "PowerSupplyA",
        "components": ["rack1/switch1", "rack1/servers"]
    }
]

Components and Hardware

Component Library

Define hardware specifications and attributes.

from ngraph.components import Component

router = Component(
    name="SpineRouter",
    component_type="router",
    attrs={
        "power_consumption": 500,
        "port_count": 64,
        "switching_capacity": 12800
    }
)

Workflow Automation

Available Workflow Steps

NetGraph provides workflow steps for automated analysis sequences.

# Available workflow steps:
# - BuildGraph: Builds a StrictMultiDiGraph from scenario.network
# - CapacityProbe: Probes capacity (max flow) between selected groups of nodes

# Example workflow configuration:
workflow = [
    {"step": "BuildGraph"},
    {"step": "CapacityProbe", "params": {"flow_placement": "PROPORTIONAL"}}
]

Utilities and Helpers

Graph Conversion Utilities

Utilities for converting between NetGraph and NetworkX graph formats.

from ngraph.lib.util import to_digraph, from_digraph, to_graph, from_graph
from ngraph.lib.graph import StrictMultiDiGraph

# Convert to NetworkX formats
graph = StrictMultiDiGraph()
nx_digraph = to_digraph(graph)  # Convert to NetworkX DiGraph
nx_graph = to_graph(graph)      # Convert to NetworkX Graph

# Convert back to NetGraph format
restored_graph = from_digraph(nx_digraph)
restored_graph = from_graph(nx_graph)

Graph Algorithms

Low-level graph analysis functions.

from ngraph.lib.graph import StrictMultiDiGraph
from ngraph.lib.algorithms.spf import spf, ksp
from ngraph.lib.algorithms.max_flow import calc_max_flow, run_sensitivity, saturated_edges

# Direct graph manipulation
graph = StrictMultiDiGraph()
graph.add_node("A")
graph.add_node("B")
graph.add_edge("A", "B", capacity=10, cost=1)

# Run shortest path algorithm
costs, pred = spf(graph, "A")

# Calculate maximum flow
max_flow = calc_max_flow(graph, "A", "B")

# Sensitivity analysis - identify bottleneck edges and test capacity changes
saturated = saturated_edges(graph, "A", "B")
sensitivity = run_sensitivity(graph, "A", "B", change_amount=1.0)

Error Handling

NetGraph uses standard Python exceptions for error conditions. Common error types include:

try:
    scenario = Scenario.from_yaml(invalid_yaml)
except ValueError as e:
    print(f"YAML validation failed: {e}")
except KeyError as e:
    print(f"Missing required field: {e}")
except Exception as e:
    print(f"General error: {e}")

For complete API documentation with method signatures, parameters, and return types, see the auto-generated API docs or use Python's help system:

help(Scenario)
help(Network.max_flow)