This is the home of the RESPOND model [1], first created by the Syndemics Lab in 2018, now rewritten with a focus on four primary goals:
- Improve the Maintainability/Scalability of the Model
- Improve the Overall Efficiency of the Model
- Improve the Portability
- Improve Testing
The original RESPOND model was built using a combination of the R and C++ programming languages. This proved computationally slow, and it required a very skilled developer who actively remembered all of the details at the core of the software. As such, it proved incredibly difficult to onboard new engineers, analysts, and researchers to the model. Worse yet, in order to make changes to the model, all requirements inevitably filtered back to the software engineer. Following the software "inversion of control" paradigm, this refactoring focused on abstracting the model to its core components and allowing users to customize it to their needs rather than holding to a general rigid structure.
RESPOND makes full use of the CMake build system. It is a common tool used throughout the C++ user-base and we utilize it for dependency management, linking, and testing. As C++ has poor package management, we intentionally decided to move our focus away from tools such as conan and vcpkg and stay with pure CMake. Not to say we would never publish with such package managers, but it is not a core focus of the refactor/engineering team.
We natively support 5 different build workflows with the CMakePresets.json file. They are:
test-debug-gcc-linux-shared-workflowtest-debug-gcc-linux-static-workflowpackage-release-gcc-linux-shared-workflowpackage-release-gcc-linux-static-workflowbenchmark-linux-static-workflow
These workflows follow the pattern {function}-{build}-gcc-linux-{library}-workflow and have corresponding presets for build, test, and package. As we adopt more operating systems and compilers we will expand beyond gcc and linux.
Overall, we make use of 10 CMake variables. They are found in the options.cmake file and all are set accordingly in the CMakePresets.json.
We make abundant use of the CMake FetchContent feature released in CMake 3.11. We utilize features added in CMake 3.24 to check if the package is previously installed, so the minimum required version of CMake is 3.24.
The required dependencies are:
Building tests is optional, but when doing so it requires:
If you would like to clone and build this locally, it is a relatively straightforward process:
git clone https://github.com/SyndemicsLab/respond.git
cd respond
cmake --workflow --preset test-debug-gcc-linux-shared-workflowAnd then the model is build and installed. Our default location is a build directory in the repository, but the CMake Install Directory can be pointed to wherever the user desires.
As this is a library, we are currently working on expanding the ability to install and work with RESPOND. If building a new project using CMake we encourage the use of FetchContent. However, we do also provide debian and tarball installations as well. We are currently working on building a Windows executable as well.
To access our Debian installer, please navigate to the release you wish to install and download the Debian package (.deb).
From there, a simple
sudo dpkg -i respond-xxx.debcommand will result in the appropriate installation. The only files added are the public headers, the compiled static library, and the CMake configuration files.
If you would like to make use of Fetch Content to extract the library:
include(FetchContent)
FetchContent_Declare(
respond
GIT_REPOSITORY https://github.com/SyndemicsLab/respond.git
GIT_TAG 5d4dde64b2e1f4ca4cea26851b82000379dbf7cb
OVERRIDE_FIND_PACKAGE
)
set(RESPOND_INSTALL ON)
find_package(respond REQUIRED)
target_link_libraries(${PROJECT_NAME}
PRIVATE
respond::respond_model
)If you would prefer a single bash script to add the project to the build tree, run:
tools/build.shThe recommended way to use the RESPOND model is via the Python package, with source on GitHub.
For C++ developers wishing to use RESPOND as a library, please refer to the C++ API Guide in the documentation for usage examples, design patterns, and best practices.
If you wish to use RESPOND via a legacy local executable, please refer to release v0.3.0.
Complete documentation is available in the docs/src/ directory:
- C++ API Guide - Developer guide for using RESPOND as a C++ library
- Architecture and Design - Design patterns, component architecture, and extensibility
- Data Management - Configuration files and data requirements
- Installation - Build and installation instructions
- Running the Model - Execution instructions
- Math Background - Mathematical foundations and equations
- Limitations - Known constraints and future work
- FAQs - Frequently asked questions
For auto-generated API documentation, build and open the Doxygen output at build/docs/doxygen/html/index.html.
If building a new project with CMake, use FetchContent:
include(FetchContent)
FetchContent_Declare(
respond
GIT_REPOSITORY https://github.com/SyndemicsLab/respond.git
GIT_TAG main
OVERRIDE_FIND_PACKAGE
)
set(RESPOND_INSTALL ON)
find_package(respond REQUIRED)
target_link_libraries(${PROJECT_NAME}
PRIVATE
respond::respond_model
)Then see the C++ API Guide for usage examples.
To build the Doxygen documentation:
cmake --build build/static --target doxygen_docsOpen build/static/docs/doxygen/html/index.html in a browser.
After building with tests enabled:
cmake --workflow --preset test-debug-gcc-linux-static-workflowTests verify all core components (models, transitions, history tracking).
- Madushani RWMA, Wang J, Weitz M, Linas BP, White LF, Chrysanthopoulou SA (2025) Empirical calibration of a simulation model of opioid use disorder. PLoS ONE 20(3): e0310763. https://doi.org/10.1371/journal.pone.0310763