.. _io-module:

==========
I/O Module
==========

Overview
========

.. admonition:: At a Glance
   :class: tip

   :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
----------------

.. code-block:: text

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

.. code-block:: text

   +------------------+     +------------------+     +------------------+
   | 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.

.. code-block:: python

   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.

.. code-block:: python

   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.

.. code-block:: python

   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:**

.. code-block:: python

   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:**

.. code-block:: bash

   # 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/

Related Documentation
=====================

- :ref:`core-module` - How core uses io for topology initialization
- :ref:`configs-module` - Configuration system that references network names
- :doc:`/developer/data/index` - Data directory structure and file formats