From 7fa3906a9badcb82a4462cfe7d5c0f7d36c06325 Mon Sep 17 00:00:00 2001 From: Hussein Mahfouz <45176416+Hussein-Mahfouz@users.noreply.github.com> Date: Thu, 19 Mar 2026 19:51:56 +0000 Subject: [PATCH 1/4] docs: update readme --- README.md | 53 ++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 40 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 26a6c57..141ee79 100644 --- a/README.md +++ b/README.md @@ -3,24 +3,51 @@ ![PyPI version](https://img.shields.io/pypi/v/transit_opt.svg) [![Documentation Status](https://readthedocs.org/projects/transit_opt/badge/?version=latest)](https://transit_opt.readthedocs.io/en/latest/?version=latest) -This repo is meant to host code for the joint design of public transport schedules and DRT fleet sizes. -- For an overview of the research area, check [Planning, operation, and control of bus transport systems: A literature review](https://www.sciencedirect.com/science/article/abs/pii/S0191261515000454) -- The specific focus of this research is frequency setting problem. -- We aim to add DRT fleet sizing to the frequency setting problem. A relevant paper that describes the research area is [Joint design of multimodal transit networks and shared autonomous mobility fleets](https://www.sciencedirect.com/science/article/pii/S235214651930016X) +This repository provides a framework for the joint optimization of public transport schedules and Demand Responsive Transit (DRT) fleet sizes. -> [!WARNING] -> This is a WIP research project. You can find a rough overview of functionality in the notebooks folder, but the codebase will change in the next few weeks +For an overview of the research area, see [Planning, operation, and control of bus transport systems: A literature review](https://www.sciencedirect.com/science/article/abs/pii/S0191261515000454). The specific focus of this implementation is the frequency setting problem, extending it to multimodal networks (PT continuous frequency setting + DRT discrete fleet sizing). A relevant foundational paper is [Joint design of multimodal transit networks and shared autonomous mobility fleets](https://www.sciencedirect.com/science/article/pii/S235214651930016X). ## Features -- [ ] Read GTFS and convert to matrix for optimisation -- [ ] Headway optimisation of existing bus network - - [ ] Different objective functions - - [ ] Configurable constraints - - [ ] Algorithms: PSO -- [ ] Adding DRT fleet sizing to problem -- [ ] Writing output back to GTFS +- Parse and extract operational data directly from raw GTFS feeds. +- Headway optimization of existing transit networks using metaheuristics (PSO via PyMOO). +- Joint optimization of Fixed-Route PT headways and DRT fleet sizing. +- Pluggable framework for customized objective functions (e.g., waiting time, service coverage) and configurable constraints (e.g., fleet limits). +- Automated reconstruction of optimized solutions back into valid GTFS outputs for downstream simulation (e.g., MATSim). +## Installation + +This project uses `uv` for dependency management. To set up the virtual environment: + +```bash +uv venv --python 3.12 .transit_opt_uv +source .transit_opt_uv/bin/activate +uv pip install -e . +uv pip install -r requirements.txt +``` + +## Usage + +The core functional pipeline runs via the CLI using a YAML configuration file. The configuration defines the input GTFS, the allowable headway parameters, optimization constraints, evaluation intervals, and output directories. + +To run the optimization pipeline: + +```bash +python scripts/run.py --config configs/config_template.yaml +``` + +If you are running iterative setups (such as starting an optimization run with seeded samples from a previous run), you can specify the target iteration index: + +```bash +python scripts/run.py --config configs/iteration_01/your_config.yaml --iteration 1 +``` + +### Notebooks + +You can find conceptual walk-throughs, data visualisations, and implementation examples in the `notebooks/` directory. + +> [!WARNING] +> While notebooks are a helpful starting point to understand the framework's mechanics, some may be outdated compared to the active `scripts/run.py` pipeline. ## Credits From 3cb3ef20ce166581ce77d35f978bcbeab16da47e Mon Sep 17 00:00:00 2001 From: Hussein Mahfouz <45176416+Hussein-Mahfouz@users.noreply.github.com> Date: Thu, 19 Mar 2026 19:53:37 +0000 Subject: [PATCH 2/4] docs: update configs readme --- configs/README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 configs/README.md diff --git a/configs/README.md b/configs/README.md new file mode 100644 index 0000000..1476c8e --- /dev/null +++ b/configs/README.md @@ -0,0 +1,23 @@ +# Config notes + +- `config_template.yaml` is the starting point for any one wanting to run the optimisaion pipeline. + +I use multiple configs to run different scenarios. I have created a naming convention for these configs. + + +### Components + +| Element | Description | Example Values | Example Meaning | +|----------|--------------|----------------|-----------------| +| **objective** | The optimisation objective being evaluated | `wt` = WaitingTimeObjective
`sc` = StopCoverageObjective | `wt` → objective minimises user waiting time | +| **time_aggregation** | How values are aggregated across time intervals | `av` = average
`pk` = peak
`sm` = sum
`int` = intervals | `av` → uses average values across intervals | +| **metric** | The performance measure used in the objective | `tot` = total
`var` = variance | `tot` → total waiting time or total vehicles | + +### Examples + +| Config file | Expanded meaning | +|--------------|------------------| +| `wt_av_tot.yaml` | WaitingTimeObjective, time aggregation = *average*, metric = *total* | +| `wt_pk_var.yaml` | WaitingTimeObjective, time aggregation = *peak*, metric = *variance* | +| `sc_av_var.yaml` | StopCoverageObjective, time aggregation = *average*, metric = *variance* | +| `sc_int_var.yaml` | StopCoverageObjective, time aggregation = *intervals*, metric = *variance* | From 318fe7a959a97e0fc89e2d3a111371a46bfb1358 Mon Sep 17 00:00:00 2001 From: Hussein Mahfouz <45176416+Hussein-Mahfouz@users.noreply.github.com> Date: Thu, 19 Mar 2026 19:55:25 +0000 Subject: [PATCH 3/4] docs: update configs readme --- configs/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/configs/README.md b/configs/README.md index 1476c8e..da06eee 100644 --- a/configs/README.md +++ b/configs/README.md @@ -1,6 +1,6 @@ # Config notes -- `config_template.yaml` is the starting point for any one wanting to run the optimisaion pipeline. +- `config_template.yaml` is the starting point for anyone wanting to run the optimization pipeline. I use multiple configs to run different scenarios. I have created a naming convention for these configs. @@ -11,7 +11,7 @@ I use multiple configs to run different scenarios. I have created a naming conve |----------|--------------|----------------|-----------------| | **objective** | The optimisation objective being evaluated | `wt` = WaitingTimeObjective
`sc` = StopCoverageObjective | `wt` → objective minimises user waiting time | | **time_aggregation** | How values are aggregated across time intervals | `av` = average
`pk` = peak
`sm` = sum
`int` = intervals | `av` → uses average values across intervals | -| **metric** | The performance measure used in the objective | `tot` = total
`var` = variance | `tot` → total waiting time or total vehicles | +| **metric** | The performance measure used in the objective | `tot` = total
`var` = variance
`atk` = atkinson | `tot` → total waiting time or total vehicles
`atk` → evaluates inequality via Atkinson Index | ### Examples @@ -21,3 +21,4 @@ I use multiple configs to run different scenarios. I have created a naming conve | `wt_pk_var.yaml` | WaitingTimeObjective, time aggregation = *peak*, metric = *variance* | | `sc_av_var.yaml` | StopCoverageObjective, time aggregation = *average*, metric = *variance* | | `sc_int_var.yaml` | StopCoverageObjective, time aggregation = *intervals*, metric = *variance* | +| `wt_av_atk.yaml` | WaitingTimeObjective, time aggregation = *average*, metric = *atkinson* | From 55f49a51cd4d16973d716ecaddc1720b3353cfef Mon Sep 17 00:00:00 2001 From: Hussein Mahfouz <45176416+Hussein-Mahfouz@users.noreply.github.com> Date: Fri, 20 Mar 2026 10:16:12 +0000 Subject: [PATCH 4/4] Refactor features section in README.md --- README.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 141ee79..b7c65b3 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,18 @@ This repository provides a framework for the joint optimization of public transport schedules and Demand Responsive Transit (DRT) fleet sizes. -For an overview of the research area, see [Planning, operation, and control of bus transport systems: A literature review](https://www.sciencedirect.com/science/article/abs/pii/S0191261515000454). The specific focus of this implementation is the frequency setting problem, extending it to multimodal networks (PT continuous frequency setting + DRT discrete fleet sizing). A relevant foundational paper is [Joint design of multimodal transit networks and shared autonomous mobility fleets](https://www.sciencedirect.com/science/article/pii/S235214651930016X). +For an overview of the research area, see [Planning, operation, and control of bus transport systems: A literature review](https://www.sciencedirect.com/science/article/abs/pii/S0191261515000454). The specific focus of this implementation is the frequency setting problem, extending it to multimodal networks (PT frequency setting + DRT discrete fleet sizing). A relevant foundational paper is [Joint design of multimodal transit networks and shared autonomous mobility fleets](https://www.sciencedirect.com/science/article/pii/S235214651930016X). ## Features -- Parse and extract operational data directly from raw GTFS feeds. -- Headway optimization of existing transit networks using metaheuristics (PSO via PyMOO). -- Joint optimization of Fixed-Route PT headways and DRT fleet sizing. -- Pluggable framework for customized objective functions (e.g., waiting time, service coverage) and configurable constraints (e.g., fleet limits). -- Automated reconstruction of optimized solutions back into valid GTFS outputs for downstream simulation (e.g., MATSim). +- Encoding + - Parse and extract operational data directly from raw GTFS feeds. +- Optimisation + - Headway optimization of existing transit networks using metaheuristics (PSO via PyMOO). + - Joint optimization of Fixed-Route PT headways and DRT fleet sizing. + - Pluggable framework for customized objective functions (e.g., waiting time, service coverage) and configurable constraints (e.g., fleet limits). +- Decoding + - Automated reconstruction of optimized solutions back into valid GTFS outputs for downstream simulation (e.g., MATSim). ## Installation