I/O Module

Overview

At a Glance

Purpose:

Data input/output for network topology loading and simulation data export

Location:

fusion/io/

Key Files:

structure.py, generate.py, exporter.py

Depends On:

fusion.utils

Used By:

fusion.core, fusion.cli

The io module handles all data input and output operations for the FUSION simulator. It provides utilities for loading network topologies from files, generating physical topology configurations, and exporting simulation results in multiple formats.

Why this module matters:

  • Provides the foundation for network initialization (topology loading)

  • Generates physical layer parameters (fiber properties, modulation formats)

  • Enables flexible data export for analysis (JSON, CSV)

  • Abstracts file operations from simulation logic

When you work here:

  • Adding support for new network topology formats

  • Modifying physical layer default parameters

  • Adding new export formats for simulation results

  • Changing how network files are discovered and loaded

Key Concepts

Network Topology Files

Tab-separated text files defining network links with format: source<TAB>destination<TAB>length. Located in data/raw/.

Physical Topology (PT)

A dictionary containing fiber properties (attenuation, dispersion, non-linearity) and per-link spectrum information. Generated by create_pt().

Bandwidth Info

Mapping of modulation formats to their bandwidth and reach characteristics. Generated by create_bw_info() from JSON configuration files.

Core Nodes

Designated high-capacity nodes in backbone networks. Currently supported for USbackbone60 and Spainbackbone30 topologies.

Architecture

Module Structure

fusion/io/
|-- __init__.py       # Public API exports
|-- structure.py      # Network topology loading and parsing
|-- generate.py       # Physical topology and bandwidth generation
|-- exporter.py       # Multi-format data export with registry pattern
|-- README.md         # Module documentation
|-- TODO.md           # Development roadmap
`-- tests/            # Unit tests
    |-- test_structure.py
    |-- test_generate.py
    `-- test_exporter.py

Data Flow

+------------------+     +------------------+     +------------------+
| Topology Files   |     | Modulation JSON  |     | Simulation       |
| (data/raw/*.txt) |     | (data/json_input)|     | Results          |
+--------+---------+     +--------+---------+     +--------+---------+
         |                        |                        |
         v                        v                        v
+------------------+     +------------------+     +------------------+
| create_network() |     | create_bw_info() |     | SimulationData   |
| structure.py     |     | generate.py      |     | Exporter         |
+--------+---------+     +--------+---------+     +--------+---------+
         |                        |                        |
         v                        v                        v
+------------------+     +------------------+     +------------------+
| network_dict     |     | bandwidth_info   |     | JSON/CSV files   |
| core_nodes_list  |     | physical_topology|     | (output/)        |
+------------------+     +------------------+     +------------------+

Components

structure.py

Purpose:

Load and parse network topology files

Key Functions:

create_network(), assign_link_lengths(), assign_core_nodes()

Loads network topologies from text files and constructs the network dictionary used by the simulation engine.

from fusion.io import create_network

# Load NSFNet topology
network_dict, core_nodes = create_network("NSFNet")

# Load with custom path
network_dict, core_nodes = create_network(
    "USbackbone60",
    base_fp="/custom/path",
    const_weight=False,
    is_only_core_node=False
)

Supported networks:

  • NSFNet, USNet, Pan-European, geant

  • USbackbone60, Spainbackbone30

  • toy_network, metro_net, dt_network

generate.py

Purpose:

Generate physical topology and bandwidth configuration

Key Functions:

create_pt(), create_bw_info()

Creates the physical layer parameters needed for signal quality calculations and spectrum assignment.

from fusion.io import create_pt, create_bw_info

# Generate physical topology for 7-core fiber
physical_topology = create_pt(
    cores_per_link=7,
    network_spectrum_dict=network_dict
)

# Load bandwidth/modulation info
bandwidth_info = create_bw_info()

exporter.py

Purpose:

Export simulation data in multiple formats

Key Classes:

SimulationDataExporter, ExporterRegistry, BaseExporter

Uses the registry pattern to support extensible export formats. Currently supports JSON and CSV output.

from fusion.io import SimulationDataExporter

exporter = SimulationDataExporter()
exporter.export_results(results_data, "output/results.json")
exporter.export_metrics(metrics_data, "output/metrics.csv", format="csv")

Adding a custom exporter:

from fusion.io import ExporterRegistry
from fusion.io.exporter import BaseExporter

class XMLExporter(BaseExporter):
    def export(self, data, output_path):
        # Custom XML export logic
        pass

registry = ExporterRegistry()
registry.register_exporter("xml", XMLExporter())

Dependencies

This Module Depends On

  • fusion.utils.os - Project root finding for path resolution

  • Standard Library: json, csv, pathlib, typing, abc

Modules That Depend On This

  • fusion.core.simulation - Uses create_network() for topology initialization

  • fusion.core.properties - Uses create_pt() for physical topology

  • fusion.cli - May use exporters for result output

  • fusion.configs - References network names from this module

Development Guide

Common Tasks

Adding a new network topology

  1. Add the topology file to data/raw/ in tab-separated format

  2. Add an entry to the network_files dictionary in structure.py:86

  3. If the network has core nodes, add handling in the create_network() function

  4. Add a test case in test_structure.py

Note

The current network name-to-file mapping is inconsistent (e.g., “USNet” maps to “us_network.txt”). This is tracked in TODO.md for cleanup in v6.0/v6.1.

Adding a new export format

  1. Create a class inheriting from BaseExporter (import from fusion.io.exporter)

  2. Implement the export(data, output_path) method

  3. Register with ExporterRegistry

  4. Add tests in test_exporter.py

Modifying physical topology defaults

Edit the fiber_props_dict in generate.py:create_pt() to change default fiber parameters (attenuation, dispersion, non-linearity, etc.).

Testing

Test Location:

fusion/io/tests/

Run Tests:

pytest fusion/io/tests/ -v

Coverage Target:

80%+

Test files:

  • test_structure.py - Network loading, link assignment, core nodes

  • test_generate.py - Physical topology and bandwidth generation

  • test_exporter.py - JSON/CSV export, registry pattern

Running specific tests:

# Run all io tests
pytest fusion/io/tests/ -v

# Run structure tests only
pytest fusion/io/tests/test_structure.py -v

# Run with coverage
pytest --cov=fusion.io fusion/io/tests/