pybind_im_and_psbmpc

This repository contains Python wrappers for C++ software in the PSB-MPC and the Ship Intention Inference repository.

The implementation of the interfaces, can respectively be found in the intention_model_interface/ and in the psbmpc_interface/ directories. The Ship Intention Inference Interface is made up of the IMInterface Python module, and the PSB-MPC Interface is made up of the PSBMPCInterface module.

Citation

If you use the pybind_im_and_psbmpc interface in your work, please refer to the following citation.

@software{psbmpc_and_im_interface_2024,
    title = {Probabilistic Scenario-Based Model Predictive Control and Ship Intention Inference Model Interface},
    author = {Myklebust, J{\o}rgen and Fol{\aa}sen, Steffen and Wien, Ragnar Norbye},
    note = {GitHub repository by NTNU - ITK},
    year = {2024}
}

colav-simulator: PSB-MPC Submodule Setup Guide

This README details how the PSB-MPC can be utilized as a COLAV system within the COLAV simulation framework. The PSB-MPC can be set to utilize the Intention Model (IM) through use of the .yaml files in the /configs directory in this repository.

1. Setup and test the colav-simulator on the main branch

First, before you start this setup procedure, ensure that your setup of the colav-simulator works by completing the setup procedures and tests which are outlined on the main branch of the simulator.

2. C++ compiler, CMake and Python environment

If you do not already have CMake or a virtual Python environment set up on your system, run the following commands. Ensure that your CMake version is greater than or equal to 3.22, and that you are using Python 3.11. You should either use the Python environment you have already set up to use in the colav-simulator or set up a new one that mirrors the one which you already set up. Also do make sure that you have a C++ compiler, such as G++ or Clang installed. This can be affirmed by running gcc -v or clang -v. If you do not have a compiler installed on your system sudo apt-get install build-essential can be executed to install G++.

sudo apt install cmake
cmake --version

conda create -n <venvname> python=3.11
conda activate <venvname>

3. Setting up the PSB-MPC branch

In the colav-simulator, set up the PSB-MPC branch by fetching and checking out the feature/psbmpc_submodule branch.

git fetch origin feature/psbmpc_submodule
git checkout feature/psbmpc_submodule

4. Cloning the pybind_im_and_psbmpc repository

Clone the pybind_im_and_psbmpc repository into the root folder that contains the other ntnu-itk-autonomous-ship-lab codebases you are using; such as the seacharts, ship_intention_inference, vimmjipda, colav_evaluation_tool, colav_simulator and rrt-rs repositories.

git clone git@github.com:ntnu-itk-autonomous-ship-lab/pybind_im_and_psbmpc.git --recursive

5. Setting up PyBind11

The PSB-MPC interface was built with PyBind11. It allows Python to use compiled C++ code. From the root of this repository, run the following commands to set up PyBind11. The two last commands can be run to verify the PyBind11 installation.

cd pybind_im_and_psbmpc

cd external/pybind11
cmake -S . -B build
cmake --build build
cmake --install build

conda install -c conda-forge pybind11

cmake -S . -B build --debug-find
pip show pybind11

6. PSB-MPC and IM Dependencies

The following dependencies are required to be able to compile the PSB-MPC and IM C++ code. The last three commands can be run to verify the installations.

sudo apt -y install libboost-all-dev
sudo apt -y install libgeographiclib-dev
sudo apt -y install libeigen3-dev

dpkg -l libboost-all-dev
dpkg -l libgeographic-dev
dpkg -l libeigen3-dev

The Ship Intention Inference repository requires further setup. The C++ SMILE library and a SMILE Academic license, that is the .h files of the C++ SMILE library and the smile_license.h file, must be downloaded from the Bayesfusion website and extracted into the smile/ directory. It should be inside the external/ directory in the repository.

cd pybind_im_and_psbmpc/external/ship_intention_inference/external
mkdir smile
cd smile

The dev/pybind_interface branch must be checked out in the Collision Avoidance algorithm repository. Go to the root of the repository, and run the following commands.

cd pybind_im_and_psbmpc/external/thecolavrepo
git pull origin dev/pybind_interface
git checkout dev/pybind_interface

7. Compiling the Interface/Wrapper: pybind_im_and_psbmpc

The last step is to compile the interface (which itself compiles the PSB-MPC and IM code). Whenever changes are made to the C++ code, that is either the pybind_im_and_psbmpc interface, the Collision Avoidance algorithm repository, or the Ship Intention Inference repository, the wrappers must be recompiled. To compile the code navigate to the root folder, pybind_im_and_psbmpc/, and run the following commmands. (If CMake finds the wrong Python version you can try to use cmake -S . -B build -DPython_EXECUTABLE=$(which python), instead of cmake -S . -B build).

cd pybind_im_and_psbmpc
cmake -S . -B build 
cmake --build build

Testing the PSB-MPC

Test files, such as test_psbmpc.py and test_sbmpc.py, can be found inside the examples/ directory of this repository. Run these to verify that your installation has been successful.

General Usage of the Python Modules

To use the interface modules in Python, simply add the following lines of code at the top of your .py file.

import sys
sys.path.append("build/")
import IMInterface
import PSBMPCInterface

Note that the "build/" string has to be replaced with the path from the .py file to the folder which contains the .so files.

Git Workflow

All contributors are obligated to follow methods as outlined in https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow for ensuring a pain-free workflow with the repository.

If you're unfamiliar with git, check out https://try.github.io/ to get familiar, and use https://learngitbranching.js.org/ for trying out topics on your own.