CommonRoad Rule Simplification: Extract Scenario-Specific Knowledge to Simplify Traffic Rules

CommonRoad Rule Simplification is a toolbox for simplifying complex traffic rules for concrete traffic situations in the CommonRoad framework. The simplification is based on scenario-specific knowledge, which is extracted from the CommonRoad scenario. By augmenting the traffic rule specifications with this knowledge, we obtain a simplified rule set that is tailored to the concrete traffic situation at hand. Thus, the simplified rules are more efficient to use in subsequent motion planning tasks.

System Requirements

The software is written in Python 3.10 and C++-20, and was tested on Ubuntu 22.04.

Building from Source

Note: If you want to use this package with the PyPI versions of its dependencies, you need to compile it using GCC 10 (which is the compiler we use to create the PyPI wheels). Otherwise, nanobind will not be able to detect the Python bindings of the dependencies correctly (see here). To do so, indicate the path to GCC 10 in the CXX environment variable before building the code (e.g. export CXX=/usr/bin/g++-10). Note that you need to start with a fresh build directory if you change the compiler, as CMake caches the compiler used for the build. Alternatively, if you cannot use GCC 10 for some reason, you can install the following packages from source using the compiler of your choice: commonroad-clcs. Make sure to use the correct versions of these packages as specified in the pyproject.toml file.

Third-Party Dependencies

While most of these dependencies are added automatically during the build process, you can install them manually via your package manager to speed up the build process.

Manual installation recommended to speed up the build:

• Boost

Manual installation optional:

• Eigen3
• spdlog

Optional dependencies:

• GTest (optional: for building unit tests)

The additional Python dependencies are listed in pyproject.toml.

Building the Code

1. We strongly recommend installing this package in a virtual Python environment using one of the following tools:

• uv
• Anaconda
• Miniconda

2. Install C++ dependencies:

sudo apt-get update
sudo apt-get install libboost-all-dev libeigen3-dev libspdlog-dev libgtest-dev libgmock-dev

3. Build the C++ extension and install the Python package:

pip install -v .

or, if you are using uv:

uv sync -v

This will build the Python bindings (knowledge_extraction_core) required for C++-boosted computations.

Note: The -v flag (verbose) prints information about the build progress

Optional:

• To build the code in Debug mode, add the flag
  • --config-settings=cmake.build-type="Debug" if you are using pip
  • --config-settings-package cr_rule_simplification:cmake.build-type="Debug" if you are using uv

See here for further information on configuring CMake arguments via our build system (scikit-build-core).

Note: scikit-build-core uses ninja for building the C++ extension by default. Thus, the build is automatically parallelized using all available CPU cores. If you want to explicitly configure the number of build jobs, you can do so by passing the flag --config-settings=cmake.define.CMAKE_BUILD_PARALLEL_LEVEL=$BUILD_JOBS to the pip command, where $BUILD_JOBS is the number of parallel jobs to use. For uv, use --config-settings-package cr_rule_simplification:cmake.define.CMAKE_BUILD_PARALLEL_LEVEL=$BUILD_JOBS. See here for further details.

Note: Building the package in Debug mode (see above) significantly increases the computation time of the C++ backend. Please make sure you are building in Release mode (default setting) if you require fast computations.

You can also have a look at the Dockerfile for the CI pipeline to see how to set up a consistent development environment on Debian/Ubuntu.

Running the Code

Run the example script main.py to compute specification-compliant reachable sets:

python main.py

or, if you are using uv:

uv run main.py

Possible Installation Problems

• Protobuf error like this CHECK failed: GeneratedDatabase()->Add(encoded_file_descriptor, size): this is caused by the commonroad_cpp Python package and the version of the environment model used by our C++ code trying to register the same type with the same protobuf instance twice. To work around this issue, you can add the --config-settings=cmake.define.COMMONROAD_SYSTEM_PROTOBUF=OFF option to the pip install command.

Documentation

To generate the documentation, first make sure that you have installed the documentation dependencies listed in pyproject.toml. Then, you can generate the documentation by running:

mkdocs build

To view the documentation, you can start a local server by running:

mkdocs serve

Development

Check out the README_FOR_DEVS for information on setting up your development environment.