{"id":50487084,"url":"https://github.com/poudel-bibek/decor","last_synced_at":"2026-06-01T23:03:40.493Z","repository":{"id":252556947,"uuid":"792058715","full_name":"poudel-bibek/DeCoR","owner":"poudel-bibek","description":"Design and Control Co-Optimization for Urban Streets Using Reinforcement Learning","archived":false,"fork":false,"pushed_at":"2026-05-22T16:06:04.000Z","size":277632,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-22T17:56:05.862Z","etag":null,"topics":["optimization","pedestrian","reinforcement-learning","sumo","traffic","vehicles"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/poudel-bibek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-04-25T22:34:05.000Z","updated_at":"2026-05-22T16:06:09.000Z","dependencies_parsed_at":"2025-04-28T23:35:53.700Z","dependency_job_id":"422acff6-5218-46e8-9ea7-f8610e2d8874","html_url":"https://github.com/poudel-bibek/DeCoR","commit_stats":null,"previous_names":["poudel-bibek/urban_design","poudel-bibek/hierarchical-design-and-control","poudel-bibek/decor"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/poudel-bibek/DeCoR","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poudel-bibek%2FDeCoR","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poudel-bibek%2FDeCoR/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poudel-bibek%2FDeCoR/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poudel-bibek%2FDeCoR/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/poudel-bibek","download_url":"https://codeload.github.com/poudel-bibek/DeCoR/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poudel-bibek%2FDeCoR/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33797128,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["optimization","pedestrian","reinforcement-learning","sumo","traffic","vehicles"],"created_at":"2026-06-01T23:03:39.885Z","updated_at":"2026-06-01T23:03:40.485Z","avatar_url":"https://github.com/poudel-bibek.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## DeCoR: Design and Control Co-Optimization for Urban Streets Using Reinforcement Learning\n\n\u003ca href=\"https://arxiv.org/pdf/2605.21311\"\u003e\u003cimg src=\"https://img.shields.io/badge/arXiv--green\"\u003e\u003c/a\u003e \u003ca href=\"https://www.youtube.com/watch?v=fmLydgvk2p4\"\u003e\u003cimg src=\"https://img.shields.io/badge/Presentation--red\"\u003e\u003c/a\u003e\n[![GitHub release](https://img.shields.io/github/v/release/poudel-bibek/DeCoR)](https://github.com/poudel-bibek/DeCoR/releases)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/header_anim.gif\" alt=\"DeCoR animation\" style=\"width:800px\"/\u003e\n\u003c/p\u003e\n\n### 📌 Overview\n\nDeCoR is a two-stage reinforcement learning framework for co-optimizing mid-block crosswalk placement and adaptive traffic signal control. It uses pedestrian and vehicle flow observations to generate crosswalk layouts, evaluate them in closed-loop traffic simulation, and learn signal timings that reduce delay for both pedestrians and vehicles.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/system_overview.png\" alt=\"DeCoR system overview\" style=\"width:800px\"/\u003e\n  \u003cbr\u003e\n  \u003cem\u003e\n  Overview of DeCoR. A design agent proposes mid-block crosswalk layouts, while a control agent learns adaptive signal timings for each layout through closed-loop traffic simulation with pedestrian and vehicle demand.\n  \u003c/em\u003e\n\u003c/p\u003e\n\n---\n### 📊 Data\n\nThe default corridor and demand inputs are stored in `simulation/` as SUMO-compatible files.\n\n| Input | Location | Description |\n| --- | --- | --- |\n| Corridor network | `simulation/Craver_traffic_lights_wide.net.xml` | SUMO network for the Craver Road study corridor. |\n| Pedestrian demand | `simulation/original_pedtrips.xml` | `2,221` pedestrian `\u003cperson\u003e` / `\u003cwalk\u003e` records over roughly one hour, with `14` TAZ labels and `24` origin/destination edges. |\n| Vehicle demand | `simulation/original_vehtrips.xml` | `200` vehicle `\u003ctrip\u003e` records over roughly one hour, balanced between TAZ `1 -\u003e 7` and `7 -\u003e 1` with one default vehicle type. |\n\nThe demand XML files encode origin-destination demand, not fully routed paths; realized routes depend on the SUMO network and routing configuration.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/demand_v2.png\" alt=\"Observed pedestrian and vehicle demand\" style=\"width:800px\"/\u003e\n  \u003cbr\u003e\n  \u003cem\u003e\n  Observed pedestrian and vehicle departures, train/evaluation split, and pedestrian OD flows across the 14-zone corridor; 69.6% of pedestrian trips require crossing the corridor.\n  \u003c/em\u003e\n\u003c/p\u003e\n\n---\n### 📦 Checkpoints and Results\n\n| Artifact | Location | Notes |\n| --- | --- | --- |\n| Pretrained policy | `runs/readout_32/May09_11-34-05/saved_policies/policy_at_7603200.pth` | Checkpoint used by the default `eval_model_path`. |\n| Paper evaluation JSONs | `runs/readout_32/May09_11-34-05/results/eval_May10_16-16-52/` | Includes DeCoR control, fixed-time, unsignalized, and real-world unsignalized evaluation outputs. |\n| Design baseline JSON | `runs/baselines_experiment/baseline_results.json` | Stored uniform/random design baseline results used by plotting utilities. |\n\n---\n### ⚙️ Setup\n\n- Install Eclipse SUMO 1.21 or [SUMO 1.22.0](https://github.com/eclipse-sumo/sumo/releases/tag/v1_22_0). Make sure `sumo`, `sumo-gui`, and `netconvert` are available on your `PATH`.\n- Verify SUMO:\n  ```bash\n  sumo --version\n  ```\n- Install Python 3.12 and [uv](https://docs.astral.sh/uv/). Python dependencies are defined in `pyproject.toml` and locked in `uv.lock`; `sumolib` and `traci` are pinned to `1.22.0`.\n- Sync the project environment:\n  ```bash\n  uv sync\n  ```\n\n---\n### 🚀 Training\n\nFor training, set these values in `config.py`:\n\n```python\n\"evaluate\": False,\n\"gui\": False,\n```\n\nThen run:\n\n```bash\nuv run python main.py\n```\n\nTraining writes a timestamped run folder under `runs/\u003ctimestamp\u003e/`, including `config.json`, TensorBoard logs, generated SUMO networks, and policies under `saved_policies/`. If `eval_freq \u003e 0`, training also writes intermediate evaluation JSONs under `runs/\u003ctimestamp\u003e/results/train_\u003ctimestamp\u003e/`.\n\nTo monitor TensorBoard:\n\n```bash\nuv run tensorboard --logdir runs\n```\n\n### 🧠 Trained Design Policy\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/gmm_design_animation.gif\" alt=\"Gaussian mixture model learned by the design agent\" style=\"width:800px\"/\u003e\n  \u003cbr\u003e\n  \u003cem\u003e\n  The design agent learns a Gaussian mixture over crosswalk location and width, where density peaks correspond to selected mid-block crosswalk proposals.\n  \u003c/em\u003e\n\u003c/p\u003e\n\n---\n### 📈 Evaluation\n\nSet `evaluate=True` in `config.py` and point `eval_model_path` to a saved checkpoint:\n\n```python\n\"evaluate\": True,\n\"eval_model_path\": \"runs/\u003crun_name\u003e/saved_policies/\u003ccheckpoint\u003e.pth\",\n```\n\nThen run:\n\n```bash\nuv run python main.py\n```\n\nThe active evaluation path in `main.py` evaluates the trained DeCoR policy over the configured demand scales and writes:\n\n```text\nruns/\u003crun_name\u003e/results/eval_\u003ctimestamp\u003e/\u003ccheckpoint\u003e_ppo.json\n```\n\nPaper comparison results are included under `runs/readout_32/May09_11-34-05/results/eval_May10_16-16-52/` for real-world unsignalized, DeCoR unsignalized, DeCoR fixed-time, and DeCoR control settings.\n\n### 📝 Code Structure\n\n```text\n├── main.py                  # Training and evaluation entry point\n├── config.py                # Runtime configuration and argument grouping\n├── utils.py                 # Policy IO, demand scaling, result aggregation\n├── pyproject.toml           # uv project metadata and direct dependencies\n├── uv.lock                  # Locked dependency resolution\n├── images/                  # Tracked README and corridor visual assets\n├── plots/\n│   ├── training_plots.py    # Training-era control/design plots and videos\n│   ├── result_plots.py      # Paper result figures and combined plots\n│   └── pedestrian_flow_plot.py\n│                            # Standalone pedestrian flow allocation figure\n├── ppo/\n│   ├── models.py            # Lower MLP policy and higher GAT/GMM policy\n│   ├── ppo.py               # PPO update implementation\n│   └── ppo_utils.py         # Memory, normalizers, graph batching helpers\n├── simulation/\n│   ├── Craver_traffic_lights_wide.net.xml\n│   ├── original_vehtrips.xml\n│   ├── original_pedtrips.xml\n│   ├── design_env.py        # Higher-level crosswalk design environment\n│   ├── control_env.py       # Lower-level TraCI/SUMO control environment\n│   ├── worker.py            # Parallel training/evaluation workers\n│   ├── sim_setup.py         # Phase definitions and lane/crosswalk metadata\n│   └── env_utils.py         # SUMO config, graph, and geometry helpers\n└── runs/\n    └── readout_32/...       # Included checkpoint and paper result artifacts\n```\n\n---\n### 🔧 Important Configuration Values\n\n| Key | Default | Notes |\n| --- | ---: | --- |\n| `evaluate` | `True` | Set to `False` for training. |\n| `gui` | `True` | Set to `False` for faster headless SUMO runs. |\n| `gpu` | `True` | Uses CUDA when available; falls back to CPU otherwise. |\n| `total_timesteps` | `15000000` | Total lower-level simulation timesteps for training. |\n| `lower_num_processes` | `10` | Parallel lower-level training workers. Adjust to your CPU. |\n| `lower_max_timesteps` | `360` | Episode horizon, excluding warmup. |\n| `lower_step_length` | `1.0` | SUMO seconds per simulation step. |\n| `lower_action_duration` | `10` | Simulation steps per control action. |\n| `lower_warmup_steps` | `[40, 140]` | Randomized warmup before policy control. |\n| `demand_scale_min/max` | `1.0 / 2.25` | Training demand scale range. |\n| `eval_lower_timesteps` | `450` | Evaluation episode horizon, excluding warmup. |\n| `eval_lower_workers` | `10` | Parallel evaluation workers. |\n| `eval_worker_device` | `\"gpu\"` | Evaluation policy device preference. |\n| `max_proposals` | `10` | Maximum crosswalk proposals from the design agent. |\n| `min_thickness/max_thickness` | `2.0 / 15.0` | Crosswalk width bounds in meters. |\n| `num_mixtures` | `7` | GMM components for the design policy. |\n\n---\n### ⚠️ Debugging\n\n- Running with `gui=True` is useful for visual checks but substantially slower than headless SUMO.\n- On Linux or WSL, if multiprocessing fails because too many files are open, increase the file descriptor limit before training:\n  ```bash\n  ulimit -n 20000\n  ```\n- If a run fails, check `netconvert_log.txt`, `sumo_logfile.txt`, and `sumo_errorlog.txt` in the relevant `runs/` subfolder.\n\n---\n### 📖 Citation\n\nIf you find this work useful in your own research:\n\n```bibtex\n@misc{poudel2026decor,\n  title = {DeCoR: Design and Control Co-Optimization for Urban Streets Using Reinforcement Learning},\n  author = {Poudel, Bibek and Zhu, Lei and Heaslip, Kevin and Swaminathan, Sai and Li, Weizi},\n  year = {2026},\n  eprint = {2605.21311},\n  archivePrefix = {arXiv},\n  note = {Preprint}\n}\n```\n\n---\n### 🙏 Acknowledgements\n\nWe thank Jakob Erdmann ([@namdre](https://github.com/namdre)) of SUMO for helping with technical issues in simulation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoudel-bibek%2Fdecor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpoudel-bibek%2Fdecor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoudel-bibek%2Fdecor/lists"}