# aubinx/fret-sncf architecture

> Architecture diagram of the GitHub repository aubinx/fret-sncf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aubinx/fret-sncf
- Repository: https://github.com/aubinx/fret-sncf

## Overview

##### Project Overview
- The project aims to model the scheduling and operations of a rail yard (specifically the Woippy freight yard) using real-world data.
- The optimization is based on Gurobi models (with several refinement milestones “jalon”) and includes modules for data reading, transforming, and displaying results (via an agenda).
- It is primarily a Python-based full-stack optimization tool with clearly separated components for data ingestion, processing and optimization, visualization, and output generation.

##### Main Components
a. Data Sources & Instances:
- “Instances” directory holds several data files (both .pkl and .xlsx) representing various instance sizes (mini, simple, realistic).
- This forms the raw input data that the system processes.
b. Data Reading and Preprocessing:
- Files such as lecture_donnees.py and donnees_trains.py manage the extraction of data from the instance files into pandas dataframes.
- horaires.py converts integer time formats to standard date/time formats.
c. Modeling/Optimization Module:
- The optimization models are implemented in model.py, model_jalon2.py, and model_jalon3.py. They contain the Gurobi optimization formulations that solve the scheduling problem.
- Additionally, heuristic_dichotomy.py provides an alternative heuristic approach (dichotomic search) for handling larger instances.
d. Output Generation:
- output.py generates the final results in Excel format and writes out the solution files.
- Two additional folders (“Outputs” and “Modeles”) are to be created for saving these generated outputs and intermediate model files, respectively.
e. Visualization & Display Tools:
- The “display_tools” folder (present both in the root and within the Old-Version directory) includes several modules for visualizing results (e.g., displaying agendas, tracking occupation, computing statistics).
f. Utility Components:
- util.py and other helper functions provide common support functions that are used across the project.
g. Legacy/Old-Version Code:

##### Relationships and Workflow
- Data Flow: Show how raw data from the “Instances” is read and processed by the data ingestion modules (lecture_donnees.py, donnees_trains.py, horaires.py).
- Processing Flow: Once data is preprocessed, it is fed into one or several optimization models (Gurobi models in model.py, etc.) that produce scheduling decisions.
- Output Flow: The optimization results are passed on to output.py to create Excel-based schedules and also to display_tools modules for generating visual agendas.
- Control Flow: main.py serves as the orchestrator that ties these modules together for a complete run.
- Legacy Branch: Represent the “Old-Version” as an alternative or earlier implementation branch that influenced the current design.

##### Architectural Patterns, Technologies, and Libraries
- Pattern: The system demonstrates a layered architecture with input (data reading), business logic (optimization modeling), and output/visualization layers.
- Key Libraries: Python’s pandas for data handling, Gurobi for optimization, and visualization modules for agendas.
- Separation of Concerns: Each file or module clearly handles a separate functional area, following modular design principles.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Input Layer
    subgraph "Data Input Layer"
        Instances("Instances"):::inputLayer
        Lecture["lecture_donnees.py"]:::inputLayer
        DonneesTrains["donnees_trains.py"]:::inputLayer
        Horaires["horaires.py"]:::inputLayer
    end

    %% Processing & Optimization Layer
    subgraph "Processing & Optimization Layer"
        Model["model.py"]:::processingLayer
        ModelJalon2["model_jalon2.py"]:::processingLayer
        ModelJalon3["model_jalon3.py"]:::processingLayer
        Heuristic["heuristic_dichotomy.py"]:::processingLayer
        Util["util.py"]:::processingLayer
    end

    %% Output & Visualization Layer
    subgraph "Output & Visualization Layer"
        Output["output.py"]:::outputLayer
        Display["display_tools/"]:::outputLayer
    end

    %% Control Layer
    subgraph "Control Layer"
        Main["main.py"]:::controlLayer
    end

    %% Legacy / Old-Version Branch
    subgraph "Legacy / Old-Version"
        OldVersion["Old-Version/"]:::legacyLayer
        LegacyDisplay["Old-Version/display_tools/"]:::legacyLayer
        HeuristicOld["heuristic_day_by_day.py"]:::legacyLayer
    end

    %% Data Flow Connections
    Instances -->|"rawData"| Lecture
    Instances -->|"rawData"| DonneesTrains
    Instances -->|"rawData"| Horaires

    %% Processing Flow Connections
    Lecture -->|"processedData"| Model
    DonneesTrains -->|"processedData"| Model
    Horaires -->|"processedTime"| Model

    %% Optimization Models Feeding Output
    Model -->|"results"| Output
    ModelJalon2 -->|"results"| Output
    ModelJalon3 -->|"results"| Output
    Heuristic -->|"results"| Output

    %% Optimization Models Feeding Visualization
    Model -->|"results"| Display
    ModelJalon2 -->|"results"| Display
    ModelJalon3 -->|"results"| Display
    Heuristic -->|"results"| Display

    %% Utility Support Flow
    Util -.->|"support"| Lecture
    Util -.->|"support"| DonneesTrains
    Util -.->|"support"| Model
    Util -.->|"support"| Output

    %% Control Flow from Main
    Main -->|"orchestrates"| Lecture
    Main -->|"orchestrates"| DonneesTrains
    Main -->|"orchestrates"| Horaires
    Main -->|"orchestrates"| Model
    Main -->|"orchestrates"| Output
    Main -->|"orchestrates"| Display

    %% Legacy Connections
    OldVersion -->|"alternative"| Lecture
    OldVersion -->|"alternative"| HeuristicOld
    OldVersion -->|"alternative"| LegacyDisplay

    %% Styles
    classDef inputLayer fill:#fdd,stroke:#333,stroke-width:2px;
    classDef processingLayer fill:#dfd,stroke:#333,stroke-width:2px;
    classDef outputLayer fill:#ddf,stroke:#333,stroke-width:2px;
    classDef controlLayer fill:#ffd,stroke:#333,stroke-width:2px;
    classDef legacyLayer fill:#eee,stroke:#333,stroke-width:2px;

    %% Click Events
    click Instances "https://github.com/aubinx/fret-sncf/tree/main/Instances/"
    click Lecture "https://github.com/aubinx/fret-sncf/blob/main/lecture_donnees.py"
    click DonneesTrains "https://github.com/aubinx/fret-sncf/blob/main/donnees_trains.py"
    click Horaires "https://github.com/aubinx/fret-sncf/blob/main/horaires.py"
    click Model "https://github.com/aubinx/fret-sncf/blob/main/model.py"
    click ModelJalon2 "https://github.com/aubinx/fret-sncf/blob/main/model_jalon2.py"
    click ModelJalon3 "https://github.com/aubinx/fret-sncf/blob/main/model_jalon3.py"
    click Heuristic "https://github.com/aubinx/fret-sncf/blob/main/heuristic_dichotomy.py"
    click Util "https://github.com/aubinx/fret-sncf/blob/main/util.py"
    click Output "https://github.com/aubinx/fret-sncf/blob/main/output.py"
    click Display "https://github.com/aubinx/fret-sncf/tree/main/display_tools/"
    click Main "https://github.com/aubinx/fret-sncf/blob/main/main.py"
    click OldVersion "https://github.com/aubinx/fret-sncf/tree/main/Old-Version/"
    click LegacyDisplay "https://github.com/aubinx/fret-sncf/tree/main/Old-Version/display_tools/"
    click HeuristicOld "https://github.com/aubinx/fret-sncf/blob/main/heuristic_day_by_day.py"
```
