Skip to content

Running a simulation

Running a JUNE Simulation

After creating a world, the next step is to run an epidemiological simulation. For an example script see example_scripts/run_simulation_2.py. Below is a summary of how to set up and run a basic simulation:

Understanding JUNE Simulations

A JUNE simulation involves: - Loading a previously created world - Setting up disease parameters and infection dynamics - Configuring policies (interventions, restrictions, etc.) - Defining interaction patterns - Running the simulation over a time period - Recording and analysing results

Example: Running a Basic Simulation

Here's a step-by-step guide to running a simulation:

  1. Activate your JUNE environment: bash conda activate JUNE

  2. Create a simulation script or use the example at example_scripts/run_simulation.py

  3. Set simulation parameters: ```python import os from june.epidemiology.infection.disease_config import DiseaseConfig from june.global_context import GlobalContext

# Choose a disease model disease = "covid19" # Options: "covid19", "measles", "ev-d68-v"

# Initial infection rate (proportion of population) cpc = 0.01 # Cases per capita (e.g., 0.01 = 1% of population)

# Set the starting date of the simulation seeding_date = "2020-03-01 8:00"

# Configure the disease model disease_config = DiseaseConfig(disease) GlobalContext.set_disease_config(disease_config) ```

  1. Load the world and set up the simulator: ```python from june.simulator import Simulator from june.interaction import Interaction from june.epidemiology.epidemiology import Epidemiology from june.epidemiology.infection_seed import InfectionSeed, InfectionSeeds from june.epidemiology.infection import InfectionSelector, InfectionSelectors from june.records import Record from june.policy import Policies from june.event import Events from june.groups.travel import Travel from june.groups.leisure import generate_leisure_for_config

# Create a directory for results results_folder = "results" if not os.path.exists(results_folder): os.makedirs(results_folder)

# Load the world (assuming you're using a Domain for better performance) from june.domains import Domain

# For a simple setup without MPI: with h5py.File("my_world.hdf5", "r") as f: super_area_ids = f["geography"]["super_area_id"] # Map all super areas to domain 0 super_area_ids_to_domain_dict = {int(id): 0 for id in super_area_ids}

domain = Domain.from_hdf5( domain_id=0, super_areas_to_domain_dict=super_area_ids_to_domain_dict, hdf5_file_path="my_world.hdf5", interaction_config="config/interaction.yaml" )

# Set up recording record = Record(record_path=results_folder, record_static_data=True)

# Configure leisure activities leisure = generate_leisure_for_config(domain, "config/config.yaml")

# Set up disease and infection parameters selector = InfectionSelector.from_disease_config(disease_config) selectors = InfectionSelectors([selector])

# Seed initial infections infection_seed = InfectionSeed.from_uniform_cases( world=domain, infection_selector=selector, cases_per_capita=cpc, date=seeding_date, seed_past_infections=True, ) infection_seeds = InfectionSeeds([infection_seed])

# Create epidemiology module epidemiology = Epidemiology( infection_selectors=selectors, infection_seeds=infection_seeds )

# Set up other simulation components interaction = Interaction.from_file() policies = Policies.from_file(disease_config=disease_config) events = Events.from_file() travel = Travel()

# Create the simulator simulator = Simulator.from_file( world=domain, policies=policies, events=events, interaction=interaction, leisure=leisure, travel=travel, epidemiology=epidemiology, config_filename="config/config.yaml", record=record ) ```

  1. Run the simulation: python # Run the simulation simulator.run()

  2. Run your script: bash python run_simulation.py

  3. Command-line Arguments: The simulation script supports various command-line arguments to customise behaviour:

bash python run_simulation.py --world_path my_world.hdf5 --save_path results

Common arguments include: - --world_path: Path to the saved world HDF5 file - --save_path: Directory to save results - --household_beta: Transmission rate in households - --n_seeding_days: Number of days to seed infections - --mask_wearing: Enable mask wearing policies - --vaccine: Enable vaccination policies

Using MPI for Large-Scale Simulations

For large simulations, JUNE supports MPI (Message Passing Interface) to run in parallel:

mpirun -n 4 python run_simulation.py --world_path my_world.hdf5

This distributes the simulation across 4 processes, which can significantly speed up large simulations.

Simulation Results

After running a simulation, results are saved in the specified output directory (default: "results"):

Common Issues with Simulations

  • Memory usage: Simulations can require significant memory, especially for large worlds
  • Runtime: Complex simulations can take hours or days to run
  • Convergence: Results may vary depending on random seeding; consider running multiple simulations
  • MPI configuration: When using MPI, ensure all processes can access the necessary files
  • Data output size: Large simulations can generate gigabytes of data; plan storage accordingly

Example Script

For an example script see example_scripts/run_simulation_2.py