Skip to content

Contribution guidelines

Jump to bottom
Anders Reenberg Andersen edited this page Apr 16, 2025 · 13 revisions

Everyone is welcome to contribute to MDPSolver! The following contains a short description of how to add features, raise issues, and contact the authors.

Adding features

MDPSolver consists of a C++-based optimization module (for deriving the policy and value vector) and a Python-based class for communicating with the optimization module. Features can be added to MDPSolver by modifying the C++ code under CPP_Source_Code and/or the Python code under Python/src/mdpsolver.

Compile and install the C++ module

Follow these steps to compile and install the optimization module:

Linux

  1. Start by creating a Python virtual environment using conda (note: replace python=3.13 with the target Python version):
conda create --name myenv python=3.13
conda activate myenv
  1. Install python3.13-config (Ubuntu users: sudo apt-get install python3.13-dev).
  2. Install pybind11: pip install pybind11.
  3. Install NumPy: pip install numpy.
  4. Clone MDPSolver: git clone https://github.com/areenberg/mdpsolver.git.
  5. Navigate to MDPSolver: cd mdpsolver.
  6. Now run sh build_and_test_linux.sh to automatically compile, install, and test the new module.
  7. The Python/src directory contains the updated MDPSolver package.

Manual approach

  1. To manually compile the optimization module on Linux, navigate to CPP_Source_Code and run:
g++ -O3 -fopenmp -shared -std=c++11 -fPIC `python3 -m pybind11 --includes` *.cpp -o solvermodule`python3-config --extension-suffix`
  1. The above will create an SO-file containing the compiled module. Check that the SO-file exists (e.g. solvermodule.cpython-313-x86_64-linux-gnu.so).
  2. To install the module in the MDPSolver package, copy the SO-file to Python/src/mdpsolver (e.g. cp solvermodule.cpython-310-x86_64-linux-gnu.so ../Python/src/mdpsolver/).
  3. Now navigate to the tests: cd ../Python/tests.
  4. Run test 1 with python3 test1.py and test 2 with python3 test2.py.

GLIBC not found

Users attempting to fix the version 'GLIBC_2.32' not found error will have to replace the version installed using pip install mdpsolver with the updated MDPSolver package located in Python/src.

  1. Start by locating the pip installation of MDPSolver: pip show mdpsolver (e.g. /home/anders/.local/lib/python3.10/site-packages).
  2. Overwrite the version installed by pip with the updated package (e.g. cp -r Python/src/mdpsolver /home/anders/.local/lib/python3.10/site-packages).

Windows

  1. Install Visual Studio 2022 (17.9) with MSVC C++ compiler and libraries.
  2. Install CMake.
  3. Install pybind11: pip install pybind11.
  4. Install NumPy: pip install numpy.
  5. Clone MDPSolver: git clone https://github.com/areenberg/mdpsolver.git.
  6. Navigate to MDPSolver: cd mdpsolver.
  7. Now run .\build_and_test_windows.bat (or simply double-click the file) to automatically compile, install, and test the new module.
  8. The Python/src directory contains the updated MDPSolver package.

Manual approach

  1. Navigate to CPP_Source_Code and check that CMakeLists.txt exists and contains the following:
cmake_minimum_required(VERSION 3.13)

project(solvermodule)

add_subdirectory(pybind11)

file(GLOB SOURCES "*.cpp")

pybind11_add_module(solvermodule ${SOURCES})

set_target_properties(solvermodule PROPERTIES CXX_STANDARD 11)

#Include OpenMP
find_package(OpenMP)
if(OpenMP_CXX_FOUND)
    target_compile_options(solvermodule PRIVATE "$<$<CXX_COMPILER_ID:MSVC>:/openmp:llvm>")
    target_link_libraries(solvermodule PUBLIC OpenMP::OpenMP_CXX)
endif()

Note: replace cmake_minimum_required(VERSION 3.13) with the target Python version.

  1. Run the following commands from the command prompt:
mkdir build

cd build

cmake ..

cmake --build . --config Release
  1. This will create a PYD-file containing the compiled module in the directory CPP_Source_Code/build/Release. Check that the file exists (e.g. solvermodule.cp313-win_amd64.pyd).
  2. To install the module in the MDPSolver package, copy the PYD-file to Python/src/mdpsolver.
  3. Now navigate to Python/tests.
  4. Run test 1 with python test1.py and test 2 with python test2.py.

Contributing to MDPSolver

Contact the authors if you want your modifications to be available in the official release of MDPSolver.

Issues and support

Bugs and issues can be raised in the Issues tab. Before creating a new issue, make sure to (1) check the installation instructions for your operating system, and (2) that your issue has not already been raised.

Should you have any questions about how to add features, perform other modifications, or ideas for the direction of MDPSolver, you can always contact the authors:

Clone this wiki locally