

1. Compiling

The program uses only standard C++ libraries, so the provided Makefile under src/ should do via

make epidemic

In addition

make clean

can be used to delete all object files.


2. Running

The program is ran from the commandline with a configuration file name as argument as e.g.

./epidemic myconfig.cfg

The output will be to console and to a series of files with the base filename specified in the configuration tile. These are <base_name>.dat (containing time, cumulative number of infected, current number of sick, current number of immune), <base_name>_growth.dat (containing the day to day growth of the cumulative number), <base_name>_2d.dat (containing a spatial grid written with 0 for healthy and 1 for infected or immune people in gnuplot format) and, if so requested, <base_name>_2d<timestamp>.dat grids for specific timestamps. There is no graphical output provided, instead any external plotting (or math analysis) tool (such as e.g. gnuplot) can be used to visualize results. A couple of sample config files is provided in the config/ subfolder.

3. Config file format

The config file needs to contain both single word and two word instructions. Single keywords delimit blocks, two keywords form a key-value pair that sets a parameter.

Valid block-delimiting keywords are
* simulation: allows to set general parameters
* disease: specifies the characteristics of a disease
* population: specifies size and social structure of a population
* class: specifies the properties of a social class inside a population
* measures: specifies measures taken to contain the disease
* measure: specifies start date, duration and the restrictions imposed by a measure
* seedings: specifies an external perturbation by random infections imposed on the grid
* seeding: specifies start date, number and virus strain of the random infections
* end: signals the end of the config file


3.1 Simulation settings

The simulation block supports the following keys and values (if a default is given, the key is optional and does not have to appear in the file):

* num_timesteps: the number of timesteps for which the simulation is run
* snapshot_interval: the number of timesteps after which a 2d snapshot of the spatial distribution is written (defaults to num_timesteps, i.e. only writes once in the end)
* filename_base: a string that is contained in all file names that are written (defaults to "epidemic")
* random_seed: an integer number to reliably produce the same pseudo-random sequence (defaults to being initialized by system time)

3.2 Disease settings

The disease block characterizes the disease that is simulated.

* recovery time: the time interval during which a person will be contagious
* p_transmission: the per-day probability to transmit the disease to another person that isn't sick or immune

3.3 Population settings

The population block deals with general characteristics of the population on the grid.

* grid_size: the size of the simulated grid, the total number of simulated people will be the square of the grid size
* num_classes: the number of social classes inside the population (need to be declared below)
* immune_fraction: the fraction of the population with natural or vaccination prior immunity

3.4 Class settings

Properties of a social class inside the population:

* mobility: number of grid cells a person can move per day to visit other cells
* p_mobility: the per-day probability to move at all (rather than stay at home)
* fraction: the fraction of the total population that's taken by the current social class 

Note: Factions of all classes must sum to 1!

3.5 Measures settings

The gross properties of infection containment measures (note that measures are optional):

* num_measures: the number of measures imposed

3.6 Measure settings

Properties of a containment measure:

* start: the starting timestep of the measure
* duration: the duration during which the measure is imposed
* mobility: the maximal mobility allowed in the simulation while the measure is in force
* transmission: the maximal transmission probability of the disease while the measure is in force 
* transmission_factor: alternatively the factor by which the base transmission probability of the disease is modified
* vaccinations: the daily amount of vaccination attempts while the measure is imposed

3.7 Seeding settings

The gross properties of infection seedings:

* num_seedings: the number of different seedings that are done in the simulation

For each seeding, the following parameters need to be specified:

* time: the timestep in which the random infections are added
* number: the number of random infections that are imposed
* transmission: the transmission probability of the imposed disease - may be different from the original strain in the disease definition
* tag_index: an optional index to distinguish the infection caused by the seeded strain from the original in 2d plots

4.0 Comments

The software is written to provide a general insight into the spread of epidemics with no claim of an ability to predict an actual spread pattern found in nature.

A series of tutorials can be found at 

http://www.science-and-fiction.org/science/epidemics.html

Feedback and Patches are welcome!

Thorsten Renk 2020-2021
thorsten@science-and-fiction.org
