Extended simulation framework for modeling biomarker propagation in the human circulatory system for infection source localization.
This repository contains an extended and adapted version of the BloodVoyagerS (BVS) simulator, used for biomarker-based infection source localization as presented in the paper: Machine Learning-Driven Localization of Infection Sources in the Human Cardiovascular System
S. Pal, J. Torres Gómez, L. Y. Debus, R. Wendt, F.-L. Lau, C. Khandanpour, M. Sieren, S. Fischer, & F. Dressler. (2025). "ML-Driven Localization of Infection Sources in the Human Cardiovascular System," IEEE Transactions on Molecular, Biological and Multi-Scale Communications, Sep. 2025, 10.1109/TMBMC.2025.3605770.
Original Simulator: The original BloodVoyagerS (BVS) simulator was developed by Regine Wendt and released as an ns-3 module.
Existing code: https://github.com/RegineWendt/blood-voyager-s Regine Wendt <wendt@itm.uni-luebeck.de> v1.1, 2019-04-24
The BVS framework integrates a human body model into ns-3, modeling transport in a simplified cardiovascular system.
In BVS v2.1, biomarker propagation is simulated, while infection sources are modeled as continuous emitters within selected blood vessels. Gateways function as passive observers that record biomarker passage, and decay is modeled using an exponential process.
To focus on large-scale transport and source localization, we excluded diffusion, vessel wall interactions, temperature effects, and biochemical reactions, enabling controlled generation of time-series data for machine-learning-based localization.
-
Simulation of infection source locations within the cardiovascular system (e.g., head, thorax, kidneys).
-
Continuous biomarker release models associated with infection sites.
-
Biomarker transport and decay modeling, consistent with biological degradation processes.
-
Generation of gateway-level time-series data for downstream machine learning tasks.
-
Support for multi-scenario simulation runs to generate labeled datasets for training and evaluation.
-
Output formats aligned with the experimental pipeline described in the paper.
-
3D coordinates of major vessels and organs
-
Continuous mobility simulation within a simplified cardiovascular system
-
Injection of simulated entities at specific vessels
-
Global position tracking and CSV-based output (/ns-3.2x/csvNano.csv)
-
Compatibility with ns-3-based analysis workflows
This simulator is implemented as an extension of the original BVS framework. For installation, configuration, and build instructions, users should follow the setup procedure of the original BVS project.
During simulation, each detected biomarker event is written as a single row to the output CSV file. The simulator logs the spatial position, timing, and metadata of biomarkers as they pass the gateway.
Each simulation run generates CSV files containing gateway-level biomarker measurements.
Output files follow the pattern: csvB<DECAY_RATE>_<SOURCE_ID>_<RUN_ID>.csv
where:
<DECAY_RATE> denotes the biomarker decay rate, encoded as a three-digit value
<SOURCE_ID> is the infection source vessel ID (the vessel/region where biomarkers are emitted)
<RUN_ID> is the run index (e.g., repeated runs for the same source ID or parameter configuration)
Example files such as csvB007_9_19.csv indicate that the simulation was executed with a biomarker decay rate of 0.007, an infection source located in vessel ID 9, and correspond to the 19th run for this specific parameter configuration.
The preprocessed and labeled datasets used for the machine learning experiments presented in the paper are publicly available via Zenodo: https://doi.org/10.5281/zenodo.15303191
These datasets were derived from the raw simulator outputs generated using the BVS v2.1 framework and subsequently processed to construct labeled feature representations suitable for machine learning–based infection source localization.
The Zenodo archive contains:
-
curated and labeled datasets used for training and evaluation,
-
data corresponding to different infection source locations and decay rates,
-
files formatted according to the experimental pipeline described in the paper.
Raw simulator outputs can be regenerated using the simulator provided in this repository by following the setup instructions and parameter configurations described above.
The simulator implementation in this repository was used to generate the raw biomarker time-series data, which were then preprocessed and labeled for machine learning. The final datasets used in the paper are available via Zenodo, enabling reproducibility of the reported results without re-running the full simulation pipeline.
This repository accompanies the paper and is intended to support transparency and reproducibility of the presented results.