Update readme

README.md

@@ -3,24 +3,54 @@
 ![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 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
+- 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
+
+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
 

configs/README.md

@@ -0,0 +1,24 @@
+# Config notes
+
+- `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.
+
+
+### Components
+
+| Element | Description | Example Values | Example Meaning |
+|----------|--------------|----------------|-----------------|
+| **objective** | The optimisation objective being evaluated | `wt` = WaitingTimeObjective<br>`sc` = StopCoverageObjective | `wt` → objective minimises user waiting time |
+| **time_aggregation** | How values are aggregated across time intervals | `av` = average<br>`pk` = peak<br>`sm` = sum<br>`int` = intervals | `av` → uses average values across intervals |
+| **metric** | The performance measure used in the objective | `tot` = total<br>`var` = variance<br>`atk` = atkinson | `tot` → total waiting time or total vehicles<br>`atk` → evaluates inequality via Atkinson Index |
+
+### 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* |
+| `wt_av_atk.yaml` | WaitingTimeObjective, time aggregation = *average*, metric = *atkinson* |