Reproducibility and run_multiple

Overview

In Epiworld, the run and run_multiple methods are important for executing simulations of agent-based models. These methods provide users with the flexibility to perform single or multiple runs of a simulation, depending on the requirements of the analysis. The run method is designed for executing a single simulation, while run_multiple extends this functionality to perform multiple independent runs, each with its own random seed.

The run_multiple method also supports parallel execution, using OpenMP to distribute simulations across multiple threads. This significantly reduces the time required for large-scale experiments, making it feasible to explore a wide range of scenarios and parameter combinations. If embedding epiworld in another application, OpenMP has some considerations to keep in mind; these can be found online, and will not be discussed here. Users can further customize the behavior of run_multiple by providing a saver callback function, which is executed after each simulation. This function can be used to save results, log progress, or perform additional analysis.

Single Runs

The run method in the Model class executes a single simulation of the model for a specified number of days. It initializes the simulation, processes global events, updates agent states, and applies rewiring or mutations as needed. The method ensures that the simulation is reproducible by allowing users to specify a seed for the random number generator. If no seed is provided, the simulation uses the current state of the random engine.

#include "epiworld/model-bones.hpp"
#include <iostream>

int main() {
    Model<int> model(100); /* Create a model with 100 agents. */

    /* Run the simulation for 30 days with a fixed seed. */
    model.run(30, 42);

    std::cout << "Simulation completed." << std::endl;
    return 0;
}

In this example: - The model is initialized with 100 agents. - The simulation runs for 30 days, using a fixed seed (42) to ensure reproducibility.

Multiple Runs

The run_multiple method extends the functionality of run by executing the model multiple times, each with a different random seed. This is useful for studying the variability of outcomes under the same configuration or for generating data for statistical analysis. The method supports parallel execution using OpenMP, allowing multiple simulations to run concurrently on different threads.

In this example, the simulation runs 10 times, each for 30 days. A custom callback function (save_results) is executed after each run to save the results. and Tte run_multiple method uses 4 threads for parallel execution.

#include "epiworld/model-bones.hpp"
#include <iostream>

void save_results(size_t run_id, Model<int>* model) {
    std::cout << "Saving results for run " << run_id << "\n";
    /* ... */
}

int main() {
    Model<int> model(100); /* Create a model with 100 agents. */

    /* Run the simulation 10 times, each for 30 days. */
    model.run_multiple(30, 10, 42, save_results, true, true, 4);

    std::cout << "All simulations completed." << "\n";
    return 0;
}

Saver Callbacks

The fun parameter in run_multiple allows users to specify a callback function that is executed after each simulation. This function can be used to save results, log progress, or perform a custom analysis.

#include "epiworld/model-bones.hpp"

int main() {
    Model<int> model(100); /* Create a model with 100 agents. */

    /* Use the default saver function to save results to files. */
    model.run_multiple(30, 10, 42, make_save_run<int>(), true, true, 4);

    return 0;
}

To access this information, refer to the DataBase documentation.