.. _gui-features:

=============
User Guide
=============

This guide walks through each feature of the FUSION GUI.

----

Simulation Runs
===============

The Runs section lets you create, monitor, and view simulation results.

Run List (Dashboard)
--------------------

The main dashboard shows all simulation runs with their status.

.. image:: /_static/images/gui/run-list-page.png
   :alt: Run list page showing simulation runs
   :width: 100%

**Status indicators:**

- **Pending** - Run is queued but not started
- **Running** - Simulation is in progress
- **Completed** - Simulation finished successfully
- **Failed** - Simulation encountered an error
- **Cancelled** - Run was manually cancelled

**Actions:**

- Click a run card to view details
- Click "New Run" to create a new simulation

Creating a New Run
------------------

.. image:: /_static/images/gui/new-run-page.png
   :alt: New run page with configuration form
   :width: 100%

**Steps:**

1. Click "New Run" from the dashboard
2. Enter a **Run ID** (unique identifier for this simulation)
3. Select a **Config Template** from the dropdown
4. (Optional) Modify the configuration in the editor
5. Click "Start Run"

The configuration editor shows the INI file contents. You can modify values
before starting the run.

Run Details
-----------

Click on any run to view its details.

**Logs Tab**

.. image:: /_static/images/gui/run-detail-logs.png
   :alt: Run detail page showing logs tab
   :width: 100%

- Real-time log streaming for running simulations
- Complete log history for finished runs
- Auto-scroll follows new log entries

**Artifacts Tab**

.. image:: /_static/images/gui/run-detail-artifacts.png
   :alt: Run detail page showing artifacts tab
   :width: 100%

- Browse output files generated by the simulation
- Download individual files
- View JSON results and statistics

----

Network Topology
================

Visualize network topologies used in simulations.

.. image:: /_static/images/gui/topology-page.png
   :alt: Network topology visualization
   :width: 100%

**Features:**

- Interactive node-link diagram
- Click nodes to see details (ID, degree, connected links)
- Zoom and pan controls
- Link utilization coloring (when viewing run results)

**Selecting a Topology:**

1. Use the dropdown to select from available topologies
2. The graph updates to show the selected network
3. Node positions are computed automatically using force-directed layout

**Understanding the Visualization:**

- **Nodes** represent network switches/routers
- **Links** represent fiber connections
- Node size may indicate degree (number of connections)
- Link color may indicate utilization (green=low, red=high)

----

Configuration Editor
====================

Edit simulation configurations with syntax highlighting.

.. image:: /_static/images/gui/config-editor.png
   :alt: Configuration editor with INI content
   :width: 100%

**Features:**

- INI syntax highlighting
- Load templates from the configs directory
- Real-time validation feedback
- Save configurations for later use

**Workflow:**

1. Select a template from the dropdown
2. The editor loads the template content
3. Modify values as needed (Erlang load, network, algorithms, etc.)
4. Use the configuration when creating a new run

**Common Configuration Sections:**

- ``[general_settings]`` - Core parameters (network, requests, Erlang)
- ``[routing_settings]`` - Routing algorithm options
- ``[rl_settings]`` - Reinforcement learning parameters
- ``[s1]``, ``[s2]``, ... - Per-process overrides

See :doc:`/developer/fusion/configs/tutorials` for detailed configuration help.

----

Codebase Explorer
=================

Browse the FUSION codebase structure and documentation.

Architecture View
-----------------

.. image:: /_static/images/gui/codebase-architecture.png
   :alt: Codebase explorer architecture view
   :width: 100%

The architecture view shows high-level module categories:

- **core** - Simulation engine and orchestrator
- **modules** - Algorithm implementations (routing, spectrum, RL, etc.)
- **configs** - Configuration system
- **cli** - Command-line interface

Click a module card to explore its contents.

Guided Tour
-----------

The guided tour introduces the codebase structure step-by-step:

1. Click "Start Tour" from the architecture view
2. Follow the prompts as they highlight different sections
3. Learn about each module's purpose and key files

Code View
---------

.. image:: /_static/images/gui/codebase-code.png
   :alt: Codebase explorer code view
   :width: 100%

- File tree on the left shows directory structure
- Code panel on the right displays file contents
- Syntax highlighting for Python, INI, and other formats
- Search within files using Ctrl+F / Cmd+F

----

Settings
========

Customize the GUI appearance and behavior.

.. image:: /_static/images/gui/settings-page.png
   :alt: Settings page with theme selection
   :width: 100%

**Available Settings:**

Theme Selection
   - **Light** - Default light theme
   - **Dark** - Dark theme for low-light environments
   - **System** - Follow your OS preference

Settings are persisted in your browser's local storage.

----

Keyboard Shortcuts
==================

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Shortcut
     - Action
   * - ``Ctrl+N`` / ``Cmd+N``
     - New run
   * - ``Ctrl+/`` / ``Cmd+/``
     - Toggle sidebar
   * - ``Escape``
     - Close modal/dialog

----

Browser Compatibility
=====================

The GUI is tested on:

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

JavaScript must be enabled for the GUI to function.