dsf-mobility 5.5.0

DSF C++ core with Python bindings via pybind11

DynamicalSystemFramework

The aim of this project is to rework the original Traffic Flow Dynamics Model. This rework consists of a full code rewriting, in order to implement more features (like intersections) and get advantage from the latest C++ updates.

Table of Contents

• Installation
• Installation (from source)
• Testing
• Benchmarking
• Citing
• Bibliography

Installation

The library is available on PyPI:

pip install dsf-mobility

To check the installation you can simply run

import dsf

print(dsf.__version__)

Installation (from source)

Requirements

The project requires C++20 or greater, cmake, tbb simdjson, spdlog, csv-parser and SQLiteCpp. To install requirements on Ubuntu:

sudo apt install cmake libtbb-dev

To install requirements on macOS:

brew install cmake tbb

Utilities are written in python. To install their dependencies:

pip install -r ./requirements.txt

Installation (C++)

The library can be installed using CMake. To build and install the project in the default folder run:

cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j$(nproc)
sudo cmake --install build

Otherwise, it is possible to customize the installation path:

cmake -B build -DCMAKE_INSTALL_PREFIX=/path/to/install

then building and installing it (eventually in sudo mode) with:

cmake --build build
cmake --install build

Installation (Python)

If you want to use the library from Python, you can build the Python bindings using pybind11. Make sure you have Doxygen installed to generate the docstrings:

sudo apt install doxygen libtbb-dev

Then, the installation is automatic via uv:

uv build

or you can just use the classic pip:

pip install .

After installation, you should be able to import the module in Python:

import dsf

print(dsf.__version__)

If you encounter issues, ensure that the installation path is in your PYTHONPATH environment variable.

Testing

This project uses Doctest for testing.

If the project is compiled in Debug or Coverage mode, tests are always built. Otherwise, you can add the -DDSF_TESTS=ON flag to enable test build.

cmake -B build -DDSF_TESTS=ON
cmake --build build -j$(nproc)

To run the tests use the command:

ctest --test-dir build -j$(nproc) --output-on-failure

Benchmarking

Some functionalities of the library have been benchmarked in order to assess their efficiency.
The benchmarks are performed using Google Benchmarks. To build the benchmarks add the flag -DDSF_BENCHMARKS=ON :

cmake -B build -DDSF_BENCHMARKS=ON
cmake --build build -j$(nproc)

To run all the benchmarks together use the command:

cd benchmark
for f in ./*.out ; do ./$f ; done

Citing

@software{berselli_2026_18745492,
  author       = {Berselli, Gregorio},
  title        = {DynamicalSystemFramework},
  month        = mar,
  year         = 2026,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.18745492},
  url          = {https://doi.org/10.5281/zenodo.18745492},
}

Bibliography

• Mungai, Veronica (2024) Studio dell'ottimizzazione di una rete semaforica. University of Bologna, Bachelor's Degree in Physics [L-DM270]. Link to Thesis.
• Berselli, Gregorio (2024) Advanced queuing traffic model for accurate congestion forecasting and management. University of Bologna, Master's Degree in Physics [LM-DM270]. Link to Thesis.
• Berselli, Gregorio (2022) Modelli di traffico per la formazione della congestione su una rete stradale. University of Bologna, Bachelor's Degree in Physics [L-DM270]. Link to Thesis.