dsf-suite 6.3.3

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)
• For Developers
  • Testing
  • Benchmarking
• Citing
• Bibliography

Installation

The library is available on PyPI:

pip install dsf-suite

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

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 tbb installed:

sudo apt install 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.

For Developers

This project as a pre-commit configuration. To use it properly, please install:

pip install pre-commit
pre-commit install

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.