Example: How to Contribute an Observation Function¶
To contribute an observation (or reward) function, there are a few files to modify. For the purpose of example, let us call our observation Cookie. We recommend looking, at every step, to other observation functions as examples.
Be sure to read the contribution guidelines to figure out how to get started and running the tests.
Create the Observation¶
The C++ code is typically separated into headers and source files.
Headers care not compiled and should only contains the public
or classes/functions signature (except for tempalted code).
#include the minimal headers to be self contained.
Create the header file
libecole/include/ecole/observation/cookie.hpp, and add the observation function declaration.
Source files contain the definition of the functions, _i.e._ their implementation.
Create the source file
Add the inclusion of your header
Add the definition of your observation function (you can also add helper functions/classes here),
Explicitly add the source file in CMake, in
Test Your Code¶
Tests are not part of a library, so they only need a source file.
Create the test file
Add unit tests to ensure the observation function abides to the required interface,
Add functional tests to ensure the observation function is correct,
Explicitly add the test file in CMake, in
Bind Code to Python¶
To expose the code in Python, we are using PyBind directly from C++.
python/src/ecole/core/observation.cpp, and bind the class using
Add the docstring.
Due to some discrepencies between C++ and Python, not all bindings are straightforward. More complex types need to be handled on a case-by-case basis.
Test the Bindings¶
We need to make sure nothing is forgotten or raises runtime errors when used from Python.
python/tests/test_observation.py, test the interface, and the return types.
Reference the Observation in the Documentation¶
Documentation from docstring is automatically read by Sphinx, so we only need to tell it where to display it.
Add the observation function in the list in
Remember to run the tests and code checks before pushing.