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)
• Examples
• GUI
• 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 nanobind. 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.

Examples

Examples in this repository are (slowly) being deprecated. You can build them by adding the cmake flag -DDSF_EXAMPLES=ON and you will find the exectuables under the examples folder. You can also find some Python examples.

New examples are being updated on dsf-examples.

GUI

If you need a visualization tool there is one available on dsf-gui. It is still in alpha stage but is already useful for some purposes.

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.