Skip to content

README.md

Latest commit

 

History

History
150 lines (107 loc) · 7.24 KB

README.md

File metadata and controls

150 lines (107 loc) · 7.24 KB
Raw

Metro Inflow Optimization

This repository contains the code for optimizing passenger inflow into urban rail transit networks to prevent overcrowding: a rolling-horizon linear program that coordinates station-level inflow restrictions network-wide, plus a minute-level discrete-time simulation that evaluates the resulting policies against physical arc capacities. It supports multiple regions through a TOML-based configuration system.

Accompanying Paper

This code accompanies the manuscript

Tobias Vlćek, Usama Dkaidik, Knut Haase, Matthes Koch, Anneke Weygandt, Lena Pagels, and Jan Pape: "Network-Wide FIFO Inflow Control for Oversaturated Urban Rail Transit: A Cumulative-Count Optimization Framework", under review at Transportation Research Part C.

The curated result files behind the paper's tables are in results_paper/, and the paper's figures are in visuals/.

Supported Regions

Region Interval Data Period Data Availability
Doha Metro 15 min Nov 27-30, 2022 Not included (confidential)
Shanghai Metro 10 min May-Aug 2017 Publicly available

Note: Doha Metro data cannot be provided due to confidentiality agreements. The framework supports Doha but users must supply their own data. The Shanghai case study is fully reproducible from public data (see below).

Quick Start

Prerequisites

  • Julia (tested with 1.12)
  • All required packages, including the open-source LP solver HiGHS, are pinned in metroflow/Manifest.toml. Instantiate the environment once:
julia --project=metroflow -e 'using Pkg; Pkg.instantiate()'

Running the Framework

# Doha (default config)
julia metro_framework_parallel.jl 15 '2022-11-29T05:00:00' '2022-11-30T04:59:00'

# Shanghai
julia metro_framework_parallel.jl --config config/shanghai.toml 60 '2017-05-15T05:00:00' '2017-05-16T04:59:00'

# Baseline without optimization (uncoordinated inflow)
julia metro_framework_parallel.jl --unbound --config config/shanghai.toml 60 '2017-05-15T05:00:00' '2017-05-16T04:59:00'

Positional arguments: period length in minutes (must be divisible by the data interval), horizon start, horizon end. Each run sweeps the parameter grid defined in the config file (safety factor, entry bounds, demand scaling, shift-scenario count).

For full parameter sweeps over several days, the tmux-based batch scripts run_parallel_metro.sh and run_sequential_metro.sh iterate the framework over all dates and period lengths in a config file.

Directory Structure

├── config/                      # Region configuration files
│   ├── doha.toml                #   Doha parameter grid (paper case study 1)
│   └── shanghai.toml            #   Shanghai parameter grid (paper case study 2)
├── data_public/
│   └── Shanghai/                # Shanghai Metro data and preprocessing
│       ├── README.md            #   Detailed preprocessing docs
│       ├── stationInfo.csv      #   Station data (included, with fixes)
│       ├── station_lines_2017.csv
│       ├── stations_shanghai.csv    # Generated
│       ├── metroarcs_shanghai.csv   # Generated
│       └── OD_*.csv                 # Generated (not tracked)
├── functions/                   # Core Julia modules
│   ├── config.jl                #   Configuration loading
│   ├── metro_functions.jl       #   Data loading and path precomputation
│   ├── metro_model.jl           #   LP formulations (base and multi-shift)
│   ├── metro_heuristic.jl       #   Rolling-horizon loop and FIFO queue depletion
│   ├── metro_simulation.jl      #   Minute-level evaluation simulation
│   └── metro_visuals.jl         #   Plotting utilities
├── metroflow/                   # Julia project environment (pinned versions)
├── results_paper/               # Curated logfiles behind the paper's tables
├── visuals/                     # Figures used in the paper
├── metro_framework_parallel.jl  # Main entry point
├── metro_data_summary.jl        # Generates the figures in visuals/
├── run_parallel_metro.sh        # Batch runner (parallel tmux sessions)
└── run_sequential_metro.sh      # Batch runner (sequential, low memory)

Reproducing the Paper Results

  • Shanghai (Case Study 2): fully reproducible. Download the public OD dataset, run the preprocessing pipeline below, then run the framework with config/shanghai.toml for May 15-17, 2017. The configuration reproduces the published setup (period length 60 min, shift-scenario count 4, safety factor 1.0, demand scalings 1.0/1.2/1.4). Baselines use --unbound.
  • Doha (Case Study 1): the demand data is confidential, so runs cannot be repeated externally. The complete run logs behind the paper's tables (all period lengths, safety factors, and entry bounds) are archived in results_paper/.
  • results_paper/logfile_{region}_{date}_{period}.csv files contain one row per parameter combination with the simulation metrics reported in the paper (capacity violations, utilization, queue lengths, share of transported passengers, computation times); _unbound files hold the uncoordinated baselines.
  • metro_data_summary.jl regenerates the arc-utilization, queue, and demand figures from raw run output.

Shanghai Data Setup

The Shanghai data requires preprocessing. Station data files are included with corrections; OD flow files must be downloaded separately.

1. Download OD Data

Download from the original dataset:

  • metroData_ODFlow.csv (11 GB)
  • metroData_InOutFlow.csv (217 MB)

Place in data_public/Shanghai/.

2. Build Network

cd data_public/Shanghai
julia --project=../../metroflow build_metroarcs.jl

This generates:

  • stations_shanghai.csv - Expanded network nodes
  • metroarcs_shanghai.csv - Network arcs with capacities

3. Visualize Network (optional)

julia --project=../../metroflow plot_network.jl

Opens an interactive HTML plot for data verification.

4. Transform OD Data

julia --project=../../metroflow transform_od.jl 2017-05-15 2017-05-21

See data_public/Shanghai/README.md for detailed documentation.

Configuration Parameters

Edit config files in config/. The main parameters map to the paper's notation:

Parameter Paper symbol Description
safety_factors α Safety factor scaling arc and station capacities
max_enter c_o^max Maximum station entries per minute
min_enter c_o^min Minimum station entries per minute
past_periods s̄ Number of additional shift scenarios for past-cohort od compositions
minutes_in_period m Optimization period length (must be a multiple of the data interval)
scaling_factors - Demand scaling factors (e.g. 1.2 = +20% demand)

Output

Each run writes:

  • logfile_{region}_*.csv - Aggregated summary per parameter combination (repository root, copied to results/)
  • results/queues/sim_queues_{region}_*.csv - Simulated queue data
  • results/arcs/sim_arcs_{region}_*.csv - Simulated arc utilization

License

This project is licensed under the MIT License.