PyDFLT is designed to help researchers apply and develop Decision Focused Learning (DFL) tools in Python. It uses CVXPYLayers [1] for differentiable models, PyEPO [2] for models with a linear objective and has an implementation of SFGE [3] and Lancer [4]. To help with research, it supports Weights & Biases (https://wandb.ai/) and Optuna (https://optuna.org). PyDFLT v0.1.0 is now available:
pip install pydflt
Documentation can be found https://pydflt.github.io/documentation.
Weights & Biases is a helpful tool to analyze experiments, while Optuna is an effective tool for hyperparameter tuning. To use either of these tools, make sure to check out the notebooks in the example folder.
If you want to contribute, you can fork the repository and send a pull request. We make use of uv (https://github.com/astral-sh/uv) for the installation and testing. Install uv here. To create the virtual environment:
uv sync --all-extras --all-groups
Notice that your IDE might automatically create the environment, but does only install the basic package dependencies. Make sure to run above command to install all dependencies.
We make use of pre-commit (https://pre-commit.com/) and pytest to ensure code is consistent and functioning properly. Both are part of the dev dependencies and therefore installed in the virtual environment. Before committing make sure to run both:
uv run pre-commit run --all-files
uv run pytest
We use Sphinx (https://www.sphinx-doc.org/en/master/) for the documentation. All files to build the documentation are in the docs directory. To create the docs, run:
uv run make html --directory=docs
Then, open docs/build/html/api/src.html in a browser to view the created docs.
[1] Akshay Agrawal, Brandon Amos, Shane Barratt, Stephen Boyd, Steven Diamond, and J Zico Kolter. Differentiable convex optimization layers. Advances in neural information processing systems, 32, 2019. doi:10.48550/arXiv.1910.12430.
[2] Bo Tang and Elias B. Khalil. Pyepo: a pytorch-based end-to-end predict-then-optimize library for linear and integer programming. Mathematical Programming Computation, 16(3):297–335, 2024. doi:10.1007/s12532-024-00255-x.
[3] Mattia Silvestri, Senne Berden, Jayanta Mandi, Ali ˙Irfan Mahmuto˘gulları, Maxime Mulamba, Allegra De Filippo, Tias Guns, and Michele Lombardi. Score function gradient estimation to widen the applicability of decision-focused learning. CoRR, abs/2307.05213, 2023. doi:10.48550/arXiv.2307.05213.
[4] Arman Zharmagambetov, Brandon Amos, Aaron Ferber, Taoan Huang, Bistra Dilkina, and Yuandong Tian. Landscape surrogate: Learning decision losses for mathematical optimization under partial information. Advances in Neural Information Processing Systems, 36:27332–27350, 2023. doi:10.48550/arXiv.2307.08964.