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
• Visualization & GUI
• Projects Using DSF
• 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 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 via standard pip:

pip install .

After installation, verify the import 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 being migrated. You can build legacy C++ examples by passing -DDSF_EXAMPLES=ON to CMake; output binaries will be generated under the examples/ directory.

Updated and active examples are maintained in dsf-examples.

Visualization & GUI

For real-time dynamic visualization and visual inspection of network flows, see dsf-gui. It offers an interactive front-end designed specifically for monitoring simulations, analyzing queue dynamics, and visual debugging.

Projects Using DSF

• bdt-mobility — Bologna Digital Twin Mobility Toolkit: Data extraction pipeline and policy-impact traffic simulation framework built for defined Zones of Interest (ZOI).

For Developers

This project includes a pre-commit hook setup. To enable it locally, run:

pip install pre-commit
pre-commit install

Testing

This project uses Doctest for unit testing.

Tests are built automatically in Debug or Coverage mode. To manually force test compilation:

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

To execute the test suite:

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

Benchmarking

Core performance critical components are benchmarked using Google Benchmark.

To build benchmark targets:

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

To run all benchmark executables:

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

Citing

If you use this software, please cite it using the metadata in CITATION.cff (GitHub's "Cite this repository" button exports it as BibTeX/APA), or via Zenodo DOI: 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.