How aubinx/fret-sncf works
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.