Build instructions

The MEmilio core library (MEmilio C++) is written in C++ and uses CMake as build system. Before installing MEmilio C++, make sure a C++20 compiler, CMake and a build tool (like GNU Make or Ninja) is installed on your device. The following guide will make use of the command line, but you can use graphical build tools from an IDE as well.

Quick start

These are minimal build instructions. More detailed steps and explanations are given below.

git clone https://github.com/SciCompMod/memilio  # download the project
cd memilio                                       # go into the project directory
cmake -S cpp -B cpp/build                        # *configure* the project, creating a "build" directory under cpp/
cmake --build cpp/build -j 2                     # *build* all targets from the project with 2 threads

After the build process is done, you can run files from “cpp/build/bin”, for example our test suite:

./cpp/build/bin/memilio-test

This will run several tests and should write out [ PASSED ] in the end.

Requirements

MEmilio C++ is regularly tested with the following compilers (list will be extended over time):

GCC, versions 11 and 13
Clang, version 14 and 17
MSVC, version 19.43 (Visual Studio 2022)

MEmilio C++ is regularly tested on GitHub runners using Ubuntu 22.04 and 24.04 and Windows Server 2022 and 2025. It is expected to run on any comparable Linux or Windows system. It is currently not tested on macOS.

The following table lists the dependencies that are used. Most of them are required, but some are optional. The library can be used without them but with slightly reduced features. CMake will warn about them during configuration. Most of them are bundled with this library and do not need to be installed manually. Bundled libraries are either included with this project or loaded from the web on demand. For each dependency, there is a CMake option to use an installed version instead. Version compatibility needs to be ensured by the user, the version we currently use is included in the table.

Library	Version	Required	Bundled	Notes
spdlog	1.15.0	Yes	Yes (git repo)	https://github.com/gabime/spdlog
Eigen	3.4.0	Yes	Yes (git repo)	http://gitlab.com/libeigen/eigen
Boost	1.84.0	Yes	Yes (git repo)	https://github.com/boostorg/boost
JsonCpp	1.9.6	No	Yes (git repo)	https://github.com/open-source-parsers/jsoncpp
HDF5	1.12.0	No	No	https://www.hdfgroup.org/, package libhdf5-dev on apt (Ubuntu)
GoogleTest	1.10	For Tests only	Yes (git repo)	https://github.com/google/googletest
LibSBML	5.20.2	No	No	https://sbml.org/software/libsbml/ (For SBML integration only)

See the thirdparty directory for more details.

Step-by-step instructions

Download

Start by downloading the newest version (or a specific release) of MEmilio from our github repository to a directory of your choice, or clone it directly using git by first opening a terminal in that directory and then running

git clone https://github.com/SciCompMod/memilio

This will create a new directory called “memilio”. Change into this directory.

cd memilio

Configuration

Before we can build anything, we need to configure the project first. If you want to use its default options, simply run

cmake -S cpp -B cpp/build

Additional options can be specified by appending one or more -D<OPTION>=<VALUE>, or by editing the file cpp/build/CMakeCache.txt after a successful configuration. The following options are known to the library:

Option	Description
`MEMILIO_BUILD_TESTS`	Build unit tests in the test directory, ON or OFF, default ON.
`MEMILIO_BUILD_EXAMPLES`	Build the example applications in the examples directory, ON or OFF, default ON.
`MEMILIO_BUILD_MODELS`	Build the separate model libraries in the models directory, ON or OFF, default ON.
`MEMILIO_BUILD_SIMULATIONS`	Build the simulation applications in the simulations directory, ON or OFF, default ON.
`MEMILIO_USE_BUNDLED_SPDLOG/_BOOST/_EIGEN/_JSONCPP`:	Use the corresponding dependency bundled with this project, ON or OFF, default ON.
`MEMILIO_BUILD_BENCHMARKS`	Build the benchmarks for this project, ON or OFF, default OFF.
`MEMILIO_SANITIZE_ADDRESS/_UNDEFINED`	Compile with specified sanitizers to check correctness, ON or OFF, default OFF.
`MEMILIO_ENABLE_OPENMP`	Compile MEmilio with multithreading using OpenMP, ON or OFF, default OFF.
`MEMILIO_ENABLE_MPI`	Compile MEmilio with distributed memory parallelization using MPI. ON or OFF, default OFF. Requires an MPI implementation to be installed on the system.
`MEMILIO_ENABLE_HDF5`	Build MEmilio with HDF5 IO support, ON or OFF, default ON. If OFF, HDF5 is not searched for and features like `save_result`/`read_result` are disabled.
`MEMILIO_ENABLE_SBML`	Build the SBML importer and imported models, i.e. everything in the folder `sbml_model_generation`, ON or OFF, default OFF. You may need to set `sbml_DIR`
`MEMILIO_ENABLE_WARNINGS`	Enable compilation warnings (beyond those enabled in the compiler by default). ON or OFF, default ON.
`MEMILIO_ENABLE_WARNINGS_AS_ERRORS`	Compilation warnings are treated as compilation errors. ON or OFF, default ON.
`MEMILIO_ENABLE_PROFILING`	Compile with runtime profiling support. ON or OFF, default OFF. See here for information.
`MEMILIO_ENABLE_LIKWID_MARKER`	Compile MEmilio with likwid markers. ON or OFF, default OFF.

Other important options you may need:

Option	Description
`CMAKE_BUILD_TYPE`	Controls compiler optimizations and diagnostics, Debug, Release, or RelWithDebInfo; not available for Multi-Config CMake Generators like Visual Studio, set the build type in the IDE or when running the compiler.
`CMAKE_INSTALL_PREFIX`	Controls the location where the project will be installed
`HDF5_DIR`	If you have HDF5 installed, but it is not found by CMake (usually on the Windows OS), you may have to set this option to the directory in your installation that contains the `hdf5-config.cmake` file.
`sbml_DIR`	If you have the SBML library installed, but it is not found by CMake, you may have to set this option to the directory in your installation that contains the `sbml-config.cmake` file.

Tip

Example: You can disable unit tests and enable building benchmarks using

cmake -S cpp -B cpp/build -DMEMILIO_BUILD_TESTS=OFF -DMEMILIO_BUILD_BENCHMARKS=ON

Building

Finally, you can build the project by running

cmake --build cpp/build -j <N>

Here, <N> must be set to the number of jobs used for building MEmilio C++, e.g. the number of available CPU threads on your system minus two. The argument -j <N> is optional, but will significantly speed up the compilation.

Once the build command has finished successfully, you can find the compiled binaries in the directory cpp/build/bin/.

You can check that everything is working as intended by running the test suite (if you did not disable it during configuration):

./cpp/build/bin/memilio-test

Also try out the example binaries (ending in _example)!

Integration into other projects

Using CMake, integration is simple.

If you installed the project, there is a memilio-config.cmake file included with your installation. This config file will tell CMake which libraries and directories have to be included. Look up the config using the command find_package(memilio) in your own CMakeLists.txt. On Linux, the file should be found automatically if you installed it in the normal GNU directories. Otherwise, or if you are working on Windows, you have to specify the memilio_DIR variable when running CMake to point it to the memilio-config.cmake file. Add the main framework as a dependency with the command target_link_libraries(<your target> PRIVATE memilio::memilio). Other targets that are exported are memilio::secir, memilio::seir, and memilio::abm. This will set all required include directories and libraries, even transitive ones.

Alternatively, MEmilio can be integrated as a subdirectory of your project with add_subdirectory(memilio/cpp), then you can use the same target_link_libraries command as above.

Installation

Warning

Installing currently is not tested and probably does not work as expected or at all. If you want to integrate the project into yours, use the add_subdirectory way.

After having built MEmilio C++ as described above, you can install it to the location given in the CMAKE_INSTALL_PREFIX variable by running

cmake --install cpp/build

This will install the libraries, headers, and executables that were built, i.e. where MEMILIO_BUILD_<PART>=ON.

Known issues

Installing currently is not tested and probably does not work as expected or at all. If you want to integrate the project into yours, use the add_subdirectory way.
On Windows, automatic detection of HDF5 installations does not work reliably. If you get HDF5 related errors during the build, you may have to supply the HDF5_DIR variable during CMake configuration, see above.