Getting Started

This page will help you get started with Topolib by showing a basic workflow and example.

Quick Example:

from topolib.elements.node import Node
from topolib.topology.topology import Topology

# Create nodes
n1 = Node(1, 'A', 10.0, 20.0)
n2 = Node(2, 'B', 11.0, 21.0)

# Build topology
topo = Topology(nodes=[n1, n2])
# Add links, compute metrics, visualize, etc.

Typical workflow:

Define nodes and links
Create a Topology object
Analyze metrics (degree, link stats, etc.)
Visualize the topology (see MapView)

Detailed Examples

Below are practical examples showing how to use Topolib for exporting and visualizing topologies in different formats. Examples use either simple fictitious nodes or real topologies from the assets folder. Each example is explained step by step.

Available example scripts:

export_csv_json.py: Export a simple topology to CSV and JSON
export_flexnetsim.py: Export a topology and k-shortest paths for FlexNetSim
show_topology_in_map.py: Show a topology from assets on a map
show_default_topology_in_map.py: List available topologies and show one on a map
show_node_ids.py: Display node IDs on topology maps (Issue #15)
export_topology_png.py: Export a default topology as PNG (graph and map)
export_paper_format.py: Export topology in clean paper format with white background
adjacency_matrices.py: Work with binary and weighted adjacency matrices
traffic_matrices.py: Generate traffic demand matrices using three different models
multiperiod_traffic_matrices.py: Generate multi-period traffic matrices with growth

Exporting to CSV and JSON

This example demonstrates how to create a simple topology and export it to CSV and JSON files.

Import required classes:

from topolib.topology.topology import Topology
from topolib.elements.node import Node
from topolib.elements.link import Link

Create nodes: Each node is defined with an id, name, latitude, and longitude.

nodes = [
    Node(1, "A", 0.0, 0.0),
    Node(2, "B", 1.0, 1.0),
    Node(3, "C", 2.0, 2.0)
]

Create links: Each link connects to two nodes and has an id and length.

links = [
    Link(1, nodes[0], nodes[1], 10.0),
    Link(2, nodes[1], nodes[2], 20.0),
    Link(3, nodes[2], nodes[0], 15.0)
]

Build the topology:
```
topology = Topology(nodes, links)
```

Export to CSV and JSON: The following methods generate output files with the topology data.

topology.export_to_csv("example_topology.csv")
topology.export_to_json("example_topology.json")

The resulting files can be opened with spreadsheet or text editors for inspection.

—

Exporting to FlexNetSim formats

This example shows how to export the topology and k-shortest paths in FlexNetSim format, which is used for optical network simulation.

Create nodes and links: (same as above)
Build the topology: (same as above)
Export to FlexNetSim topology:
```
topology.export_to_flexnetsim_json("example_flexnetsim_topology.json", slots=320)
```
This creates a JSON file compatible with FlexNetSim, specifying the number of slots per link.
Export k-shortest paths:
```
topology.export_to_flexnetsim_ksp_json("example_flexnetsim_ksp.json", k=3)
```
This generates a JSON file with the k-shortest paths between all node pairs, using link length as weight.

FlexNetSim project: https://gitlab.com/DaniloBorquez/flex-net-sim

—

Showing topology on a map

This example demonstrates how to visualize a topology using the MapView class.

Create nodes and links: (same as above)
Build the topology: (same as above)

Create a MapView and display the map:

from topolib.visualization.mapview import MapView
mapview = MapView(topology)
mapview.show_map()

This will open an interactive HTML map in your default web browser, displaying the network topology with clickable nodes on a geographic map background. You can also export the map to HTML or PNG formats using export_html() or export_map_png() methods.

For academic papers or presentations, use the paper_format=True parameter in export_map_png() to generate clean images with white background and no map tiles:

mapview.export_map_png("topology_paper.png", paper_format=True)

—

Loading and Visualizing a Default Topology

This example demonstrates how to list available topologies, load a default topology from the assets folder, and display it on a map using MapView.

Import required classes:

from topolib.topology import Topology
from topolib.visualization import MapView

List available topologies: Use the class method to see all built-in topologies and their metadata.

available = Topology.list_available_topologies()
print("Available topologies:")
for entry in available:
    print(f"- {entry['name']} (nodes: {entry['nodes']}, links: {entry['links']})")

Load the default topology: Use the static method to load a built-in topology by name (e.g., “Germany-14nodes”).
```
topo = Topology.load_default_topology("Germany-14nodes")
```
Visualize the topology on a map: Create a MapView and display the topology on an OpenStreetMap background.
```
map_view = MapView(topo)
map_view.show_map()
```

—

Displaying Node IDs on Maps

This example demonstrates how to display node IDs directly on topology maps for easy identification and analysis (Issue #15).

Import required classes:

from topolib.topology import Topology
from topolib.visualization import MapView

Load a topology:

topo = Topology.load_default_topology("Germany-14nodes")

Create MapView and export with node IDs: Use the show_node_ids=True parameter to display node IDs as centered text within larger blue circles.

mapview = MapView(topo)

# Export HTML maps for comparison
mapview.export_html("topology_without_ids.html", show_node_ids=False)
mapview.export_html("topology_with_ids.html", show_node_ids=True)

# Export PNG with node IDs
mapview.export_map_png(
    "topology_with_ids.png",
    width=1920,
    height=1080,
    wait_time=5.0,  # Important: use 5s or higher for proper rendering
    show_node_ids=True
)

# Export paper format PNG with node IDs
mapview.export_map_png(
    "topology_paper_with_ids.png",
    width=1920,
    height=1080,
    wait_time=5.0,
    paper_format=True,
    show_node_ids=True
)

Warning

When exporting PNG files with show_node_ids=True, use wait_time=5.0 seconds or higher to ensure proper rendering. Insufficient wait time may result in blank or incomplete images.

Node ID Display Features:

Node IDs appear as white text centered in larger blue circles (radius 12px)
Compatible with all visualization modes: show_map(), export_html(), and export_map_png()
Works with both regular and paper format exports
Very useful for network analysis, metrics calculation, and academic presentations

—

Generating Traffic Demand Matrices

This example demonstrates how to generate traffic demand matrices between network nodes using three different models. Traffic matrices are essential for network planning, capacity analysis, and simulation.

Import required classes:

import numpy as np
from topolib.topology import Topology
from topolib.analysis import TrafficMatrix

Load a topology: Load a default topology or create your own with nodes that have population, datacenter (dc), and IXP attributes.
```
topology = Topology.load_default_topology("Germany-14nodes")
```

Generate traffic matrix using the Gravitational Model: This model generates traffic proportional to node populations: T(i,j) = K × Pop_i × Pop_j

matrix_grav = TrafficMatrix.gravitational(topology, rate=0.015)
# matrix_grav is a NumPy array of shape (n_nodes, n_nodes)
# matrix_grav[i, j] = traffic from node i to node j in Gbps

Generate traffic matrix using the MPT Model (Multi-Period Traffic): This model considers datacenter and IXP resources along with node connectivity.
```
matrix_dc = TrafficMatrix.mpt(topology)
```

Generate traffic matrix using the RAM Model (Region Aggregation Model): This model distributes traffic probabilistically based on weighted resources.

matrix_dist = TrafficMatrix.ram(
    topology,
    w_pop=0.015,   # Gbps per capita
    w_dc=400.0,    # Gbps per datacenter
    w_ixp=2857.0   # Gbps per IXP
)

Analyze the results: All methods return NumPy arrays, allowing efficient mathematical operations.

print(f"Matrix shape: {matrix_grav.shape}")
print(f"Total traffic: {np.sum(matrix_grav):.2f} Gbps")
print(f"Max traffic flow: {np.max(matrix_grav):.2f} Gbps")

Export to CSV: Export any traffic matrix to CSV format for further analysis.
```
TrafficMatrix.to_csv(matrix_grav, topology, "traffic_matrix.csv")
```

Export to JSON: Export traffic matrices to JSON format as a list of traffic demands.

TrafficMatrix.to_json(
    matrix_grav,
    topology,
    "traffic_matrix.json"
)

The JSON output is a list of demands with node names:

[
    {"src": "Node_A", "dst": "Node_B", "required": 10.5},
    {"src": "Node_A", "dst": "Node_C", "required": 15.2},
    ...
]

Only non-zero traffic values are included to minimize file size.

Traffic Matrix Models:

Gravitational Model: Best for networks where traffic is primarily driven by population distribution
DC/IXP Model: Suitable for networks with significant datacenter and internet exchange point infrastructure
Distribution Probability Model: Most flexible, combines multiple factors with configurable weights

All matrices have zeros on the diagonal (no self-traffic) and represent unidirectional traffic flows in Gbps.

—

Each example script can be found in the examples/ folder. You can run them directly with Python to generate output files or visualizations.