[Feat] Release!

Co-authored-by: Chuanbo Hua <[email protected]>
Co-authored-by: Laurin Luttmann <[email protected]>
Co-authored-by: Jiwoo Son <[email protected]>

Author: 4 people

.gitignore

@@ -0,0 +1,177 @@
+# data and log
+.data/
+lightning_logs/
+*.npz
+logs/
+outputs/
+/data/
+/notebooks/data/
+
+
+#cache
+cache/
+
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+/env
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# VSCode debug launch file
+.vscode/

.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+fail_fast: true
+
+repos:
+
+- repo: https://github.com/psf/black
+  rev: 23.3.0
+  hooks:
+    - id: black
+      args: [--config, pyproject.toml]
+      types: [python]
+
+- repo: https://github.com/charliermarsh/ruff-pre-commit
+  rev: "v0.0.272"
+  hooks:
+    - id: ruff
+      args: [--fix, --exit-non-zero-on-fix]
+
+-  repo: https://github.com/pre-commit/pre-commit-hooks
+   rev: v4.4.0
+   hooks:
+   -   id: check-toml
+       id: check-yaml
+       id: detect-private-key
+       id: end-of-file-fixer
+       id: trailing-whitespace

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 AI4CO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,106 @@
+# PARCO
+
+[![arXiv](https://img.shields.io/badge/arXiv-2409.03811-b31b1b.svg)](https://arxiv.org/abs/2409.03811) [![Slack](https://img.shields.io/badge/slack-chat-611f69.svg?logo=slack)](https://join.slack.com/t/rl4co/shared_invite/zt-1ytz2c1v4-0IkQ8NQH4TRXIX8PrRmDhQ)
+[![License: MIT](https://img.shields.io/badge/License-MIT-red.svg)](https://opensource.org/licenses/MIT)
+
+Code repository for "PARCO: Learning Parallel Autoregressive Policies for Efficient Multi-Agent Combinatorial Optimization"
+
+
+<div align="center">
+    <img src="assets/ar-vs-par.png" style="width: 100%; height: auto;">
+    <i> Autoregressive policy (AR) and Parallel Autoregressive (PAR) decoding </i>
+</div>
+
+<br>
+
+<div align="center">
+    <img src="assets/parco-model.png" style="width: 100%; height: auto;">
+    <i> PARCO Model</i>
+</div>
+
+
+## 🚀 Usage
+
+### Installation
+
+```bash
+pip install -e .
+```
+
+Note: we recommend using a virtual environment. Using Conda:
+
+```bash
+conda create -n parco
+conda activate parco
+```
+
+### Data generation
+You can generate data using the `generate_data.py`, which will automatically generate all the data we use for training and testing:
+
+```bash
+python generate_data.py
+```
+
+### Quickstart Notebooks
+We made examples for each problem that can be trained under two minutes on consumer hardware. You can find them in the `examples/` folder:
+
+- [1.quickstart-hcvrp.ipynb](examples/1.quickstart-hcvrp.ipynb): HCVRP (Heterogeneous Capacitated Vehicle Routing Problem)
+- [2.quickstart-omdcpdp.ipynb](examples/2.quickstart-omdcpdp.ipynb): OMDCPDP (Open Multi-Depot Capacitated Pickup and Delivery Problem)
+- [3.quickstart-ffsp.ipynb](examples/3.quickstart-ffsp.ipynb): FFSP (Flexible Flow Shop Scheduling Problem)
+
+
+### Train your own model
+You can train your own model using the `train.py` script. For example, to train a model for the HCVRP problem, you can run:
+
+```bash
+python train.py experiment=hcvrp
+```
+
+you can change the `experiment` parameter to `omdcpdp` or `ffsp` to train the model for the OMDCPDP or FFSP problem, respectively.
+
+
+Note on legacy FFSP code: the initial version we made was not yet integrated in RL4CO, so we left it the [`parco/tasks/ffsp_old`](parco/tasks/ffsp_old/README.md) folder, so you can still use it.
+
+
+### Testing
+
+You may run the `test.py` script to evaluate the model, e.g. with:
+
+```bash
+python test.py --problem hcvrp --decode_type greedy --batch_size 128 --sample_size 1
+```
+
+
+## 🤩 Citation
+
+If you find PARCO valuable for your research or applied projects:
+
+```bibtex
+@article{berto2024parco,
+    title={{PARCO: Learning Parallel Autoregressive Policies for Efficient Multi-Agent Combinatorial Optimization}},
+    author={Federico Berto and Chuanbo Hua and Laurin Luttmann and Jiwoo Son and Junyoung Park and Kyuree Ahn and Changhyun Kwon and Lin Xie and Jinkyoo Park},
+    year={2024},
+    journal={arXiv preprint arXiv:2409.03811},
+    note={\url{https://github.com/ai4co/parco}}
+}
+```
+
+We will also be happy if you cite the RL4CO framework that we used to create PARCO:
+
+```bibtex
+@article{berto2024rl4co,
+    title={{RL4CO: an Extensive Reinforcement Learning for Combinatorial Optimization Benchmark}},
+    author={Federico Berto and Chuanbo Hua and Junyoung Park and Laurin Luttmann and Yining Ma and Fanchen Bu and Jiarui Wang and Haoran Ye and Minsu Kim and Sanghyeok Choi and Nayeli Gast Zepeda and Andr\'e Hottung and Jianan Zhou and Jieyi Bi and Yu Hu and Fei Liu and Hyeonah Kim and Jiwoo Son and Haeyeon Kim and Davide Angioni and Wouter Kool and Zhiguang Cao and Jie Zhang and Kijung Shin and Cathy Wu and Sungsoo Ahn and Guojie Song and Changhyun Kwon and Lin Xie and Jinkyoo Park},
+    year={2024},
+    journal={arXiv preprint arXiv:2306.17100},
+    note={\url{https://github.com/ai4co/rl4co}}
+}
+```
+
+---
+
+<div align="center">
+    <a href="https://github.com/ai4co">
+        <img src="https://raw.githubusercontent.com/ai4co/assets/main/svg/ai4co_animated_full.svg" alt="AI4CO Logo" style="width: 30%; height: auto;">
+    </a>
+</div>

assets/ar-vs-par.png

@@ -0,0 +1 @@
+# this file is needed here to include configs when building project as a package

assets/parco-model.png

@@ -0,0 +1,19 @@
+defaults:
+  - model_checkpoint.yaml
+  - model_summary.yaml
+  - rich_progress_bar.yaml
+  - speed_monitor.yaml
+  - learning_rate_monitor.yaml
+  - _self_
+
+model_checkpoint:
+  dirpath: ${paths.output_dir}/checkpoints
+  filename: "epoch_{epoch:03d}"
+  monitor: "val/reward"
+  mode: "max"
+  save_last: True
+  auto_insert_metric_name: False
+  save_top_k: 1 # set to -1 to save all checkpoints
+
+model_summary:
+  max_depth: 5 # change to -1 to show all. 5 strikes a good balance between readability and completeness

checkpoints/hcvrp/parco.ckpt

@@ -0,0 +1,17 @@
+# https://pytorch-lightning.readthedocs.io/en/latest/api/lightning.callbacks.EarlyStopping.html
+
+# Monitor a metric and stop training when it stops improving.
+# Look at the above link for more detailed information.
+early_stopping:
+  _target_: lightning.pytorch.callbacks.EarlyStopping
+  monitor: ??? # quantity to be monitored, must be specified !!!
+  min_delta: 0. # minimum change in the monitored quantity to qualify as an improvement
+  patience: 3 # number of checks with no improvement after which training will be stopped
+  verbose: False # verbosity mode
+  mode: "min" # "max" means higher metric value is better, can be also "min"
+  strict: True # whether to crash the training if monitor is not found in the validation metrics
+  check_finite: True # when set True, stops training when the monitor becomes NaN or infinite
+  stopping_threshold: null # stop training immediately once the monitored quantity reaches this threshold
+  divergence_threshold: null # stop training as soon as the monitored quantity becomes worse than this threshold
+  check_on_train_epoch_end: null # whether to run early stopping at the end of the training epoch
+  # log_rank_zero_only: False  # this keyword argument isn't available in stable version

checkpoints/omdcpdp/parco.ckpt

@@ -0,0 +1,3 @@
+learning_rate_monitor:
+  _target_: lightning.pytorch.callbacks.LearningRateMonitor
+  logging_interval: epoch