Developer Guide¶
This section is intended for developers who want to contribute to the PyOptInterface library. It provides an overview of the codebase, the development process, and the guidelines for contributing to the project.
Codebase Overview¶
The PyOptInterface library is a C++/Python mixed library. The core parts are implemented in C++ and exposed to Python via nanobind. The build system is based on scikit-build-core.
The codebase is organized as follows:
include/pyoptinterface
: The header files of the C++ library.lib
: The source files of the C++ library.src
: The Python interface.tests
: The test cases.thirdparty
: The third-party dependencies.
Development Process¶
Supposing you want to contribute to PyOptInterface, you can follow these steps:
Firstly, fork the PyOptInterface repository on GitHub and clone your forked repository to your local machine: git clone https://github.com/<your-username>/PyOptInterface.git
.
Next, you should set up the development environment. The third-party optimizers must be configured following the instructions in getting started. In order to build PyOptInterface from source, you need the following dependencies:
CMake
A recent C++ compiler (We routinely test with GCC 10, latest MSVC and Apple Clang on the CI)
Python 3.8 or later
Python packages:
scikit-build-core
, can be installed by runningpip install scikit-build-core[pyproject]
Then, you can build the project by running the following commands:
pip install --no-build-isolation -ve .
You will see a new build
directory created in the project root. The Python package is installed in editable mode, so you can modify the source code and test the changes without reinstalling the package.
After making changes to the code, you should run the test cases to ensure that everything is working as expected. You can run the test cases by executing the following command (installing pytest
is required):
pytest tests
The tests of PyOptInterface are still scarce, so you are encouraged to write new test cases for the new features you add.
Finally, you can submit a pull request to the PyOptInterface repository
Building Documentation¶
The documentation of PyOptInterface is built using Sphinx.
Firstly, you should install the dependencies for building the documentation:
pip install -r docs/requirements.txt
You can build the documentation by running the following commands:
cd docs
make html
The docs are built in the docs/build/html
directory. You can open the index.html
file in a web browser to view the documentation.
Contributing Guidelines¶
When contributing to PyOptInterface, please follow these guidelines:
Make sure that the code is well formatted and documented. The C++ code is formatted using clang-format and the Python code is formatted using black.
For big changes like adding interface for a new optimizer, please open a thread in Discussion to discuss the design before starting the implementation.