Getting Started
===============

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

Quick Example:
--------------

.. code-block:: python

   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:
-----------------
1. Define nodes and links
2. Create a Topology object
3. Analyze metrics (degree, link stats, etc.)
4. 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

.. _example_csv_json:

Exporting to CSV and JSON
~~~~~~~~~~~~~~~~~~~~~~~~~

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

1. **Import required classes:**

   .. code-block:: python

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

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

   .. code-block:: python

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

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

   .. code-block:: python

      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)
      ]

4. **Build the topology:**

   .. code-block:: python

      topology = Topology(nodes, links)

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

   .. code-block:: python

      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.

---

.. _example_flexnetsim:

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.

1. **Create nodes and links:** (same as above)
2. **Build the topology:** (same as above)
3. **Export to FlexNetSim topology:**

   .. code-block:: python

      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.

4. **Export k-shortest paths:**

   .. code-block:: python

      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

---

.. _example_mapview:

Showing topology on a map
~~~~~~~~~~~~~~~~~~~~~~~~~

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

1. **Create nodes and links:** (same as above)
2. **Build the topology:** (same as above)
3. **Create a MapView and display the map:**

   .. code-block:: python

      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:

   .. code-block:: python

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

---

.. _example_default_topology_map:

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.

1. **Import required classes:**

   .. code-block:: python

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

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

   .. code-block:: python

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

3. **Load the default topology:**
   Use the static method to load a built-in topology by name (e.g., "Germany-14nodes").

   .. code-block:: python

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

4. **Visualize the topology on a map:**
   Create a MapView and display the topology on an OpenStreetMap background.

   .. code-block:: python

      map_view = MapView(topo)
      map_view.show_map()

---

.. _example_node_ids:

Displaying Node IDs on Maps
~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

1. **Import required classes:**

   .. code-block:: python

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

2. **Load a topology:**

   .. code-block:: python

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

3. **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.

   .. code-block:: python

      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

---

.. _example_traffic_matrices:

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.

1. **Import required classes:**

   .. code-block:: python

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

2. **Load a topology:**
   Load a default topology or create your own with nodes that have population, datacenter (dc), and IXP attributes.

   .. code-block:: python

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

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

   .. code-block:: python

      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

4. **Generate traffic matrix using the MPT Model (Multi-Period Traffic):**
   This model considers datacenter and IXP resources along with node connectivity.

   .. code-block:: python

      matrix_dc = TrafficMatrix.mpt(topology)

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

   .. code-block:: python

      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
      )

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

   .. code-block:: python

      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")

7. **Export to CSV:**
   Export any traffic matrix to CSV format for further analysis.

   .. code-block:: python

      TrafficMatrix.to_csv(matrix_grav, topology, "traffic_matrix.csv")

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

   .. code-block:: python

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

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

   .. code-block:: json

      [
          {"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.