Simulation

class nepidemix.simulation.Simulation

Captures the functionality of a simulation in a class.

A simulation has three stages: configuration, execution, and data export. Configuration is made using an ini-like language, and the configure method takes a Python ConfigParser compatible structure. Once the simulation is configured it is started by execute, and finally call saveData in order to save any simulation data to disc.

What data is saved depends on how the simulation is configured (as outlined below) and on which process is used. Currently the simulation can be set up to track the number of nodes in each mean field state defined by the process and/or the full network (topology and states).

A very short example running a simulation (given a configuration file named ‘myconfig.ini’:

cfParser = nepidemix.utilities.NepidemiXConfigParser()

configFileName = 'myconfig.ini'

with open(configFileName) as f:
        cfParser.readfp(f)

S = nepidemix.simulation.Simulation()

S.configure(cfParser)

S.execute()

S.saveData()

Configuration files are written in an ini-like language with sections and <option> = <value> pairs in each. The Section and Option names are given by the CFG-prefixed attributes of the Simulation class.

The following table contains explanations of all valid ini-file configuration sections.

List of configuration sections
Section	Explanation
Simulation	This section contains general simulation information such as what network generation and process to use. See table of Simulation section options below for specific settings.
NetworkParameters	This is a special section. All options will be sent as parameters to the network generation function (set by the network_func option in the Simulation section). Thus the options in this section is dependent on the function chosen, and must match that function exactly. See nepidemix.utilities.networkgeneratorwrappers for a list of network generation functions.
ProcessParameters	This is a special section. All options will be sent as parameters to the process class (set by the process_class option in the Simulation section) initialization method. Thus the options in this section is dependent on the process chosen, and must match that class exactly. See nepidemix.Process for a brief introduction, and the tutorial for examples.
NodeStateDistribution	This is a special section. The section will be ignored if network_init is turned off. All options will be sent as parameters to the process class (set by the process_class option in the Simulation section) and used to distribute the initial node states over the network. While it is possible for generic classes to override, the format of this section should be so that the option names should be the names of the network node states used by the process and their values should be the fraction of nodes, alternatively the number of nodes, that will be assigned to each state initially. If the sum of the states add up to the size of the network the exact number of nodes will be used. If not, a fraction of the network equal to (network size * state dist)/(sum of all state dist) will be used. I.e. normalized. It is recommended to either use exact numbers or fractions of the network size here for readability. The state names must match those specified by the network process class. If this section is left out an equal number of nodes are allocated to each state.
EdgeStateDistribution	This is a special section, and analogous to the NodeStateDistribution described above but for edges.
Output	This section contains options controlling simulation output and saving of data. See table of Output section options below for specific settings.
Logging	Contains options on software log output for nepidemix.

Configuration options

Below are tables listing available options for sections having them.

Simulation section options
Option key	Explanation
iterations	Run the simulation this many iterations.
dt	The time step taken each iteration. Should be a fraction in the range 0,1.
process_class	This is the name of the process object. See nepidemix.process or tutorial for options.
process_class_module	This is the python module/package where the class given in the option process_class resides. Default: nepidemix.process for built-in processes. Use the base name of your own file if you programmed your own process in python. See tutorial for examples. Optional.
network_func	This is the name of the network generation function. See nepidemix.utilities.networkgeneratorwrappers for a list of network generation functions.
network_func_module	This is the python module where the network function resides. If you do not write your own network generation functions this can be left undefined. Optional.
network_init	This switch (on/off, true/false, yes/no, 1/0) is optional (default value true) and tells the simulation if the network should be initialized by the current process or not. Note that not initializing the network may lead to errors or strange behavior. Only switch off if network is loaded from disk and you don’t want it to be re-initialized with new state (thus keeping the states), or if the network is initialized by some other mechanism.
node_init	This switch (on/off, true/false, yes/no, 1/0) is optional (default value true) and tells the simulation if the network nodes should be initialized by the current process or not. Note: This option is only interpreted if network_init is set to on (true, yes, 1) and is ignored otherwise. Optional. Default: true
edge_init	This switch (on/off, true/false, yes/no, 1/0) is optional (default value true) and tells the simulation if the network edges should be initialized by the current process or not. Note: This option is only interpreted if network_init is set to on (true, yes, 1) and is ignored otherwise. Optional. Default: true.
module_paths	This is an optional list (comma-separated) of directory paths that the simulation will add to the python path before loading the network generation and process routines. Useful if you have written your own functions that reside in some directory not on the path. See the tutorial for examples on how this option is used.
include_files	Optional list (comma-separated) containing names of additional configuration files to include. The files will be read in order and their sections added to the configuration. This allows for splitting of large configuration files into logical sections and store them in individual files.

Output section options
Option key	Explanation
output_dir	Output directory where files will be saved. The directory must exist and be writable.
base_name	This is the base name of all files generated by the run.
unique	Optional (default value true) switch (on/off, true/false, yes/no, 1/0). If unique is defined as true, yes, 1, or on, unique file names will be created (time stamp added).
save_config	Switch (on/off, true/false, yes/no, 1/0). If this is true, yes, 1, or on, a copy of the full program config, plus an Info section will be saved.
save_state_count	Optional (default value true) switch (on/off, true/false, yes/no, 1/0). If this is true/yes/on, the network node states will be counted and saved as a csv file. Note: only valid if the current process support node updates. If not, nothing will be saved.
save_state_count_interval	Optional (default value 1). Count nodes every <value> iterations. Value should be an integer >= 1. Note, initial and final node state counts are always saved even if they are not covered by the interval.
save_state_influx	Optional (default value true) switch (on/off, true/false, yes/no, 1/0). If this is true/yes/on, the network node states influx (total num new nodes in state) will be saved to a csv file. Note: only valid if the current process support node updates. If not, nothing will be saved.
save_state_influx_interval	Optional (default value 1). Save influx everu <value> iteration. Value is integer >= 1. Note, initial and final node state influx are always saved even if they are not covered by the interval.
save_network_compress_file	Optional (default value true) switch (on/off, true/false, yes/no, 1/0). Denotes if the saved network files should be bz2 compressed.

Logging section options
Option key	Explanation
level	Optional (default value DEBUG). Must be one of DEBUG/INFO/WARN/SILENT.

Methods

configure(settings)	Configure simulation.
execute()	Execute simulation.
saveData()	Save any computed data as per configuration.

__init__()

Initialization method.

Methods

__init__()	Initialization method.
configure(settings)	Configure simulation.
execute()	Execute simulation.
saveData()	Save any computed data as per configuration.

Attributes

CFG_PARAM_avgclust	str(object) -> string
CFG_PARAM_avgdegree	str(object) -> string
CFG_PARAM_baseFileName	str(object) -> string
CFG_PARAM_dt	str(object) -> string
CFG_PARAM_edge_init	str(object) -> string
CFG_PARAM_execute_time	str(object) -> string
CFG_PARAM_include_files	str(object) -> string
CFG_PARAM_iterations	str(object) -> string
CFG_PARAM_mod_path	str(object) -> string
CFG_PARAM_network_init	str(object) -> string
CFG_PARAM_network_module	str(object) -> string
CFG_PARAM_network_name	str(object) -> string
CFG_PARAM_node_init	str(object) -> string
CFG_PARAM_outputDir	str(object) -> string
CFG_PARAM_process_module	str(object) -> string
CFG_PARAM_process_name	str(object) -> string
CFG_PARAM_save_config	str(object) -> string
CFG_PARAM_save_network	str(object) -> string
CFG_PARAM_save_network_compress_file	str(object) -> string
CFG_PARAM_save_network_format	str(object) -> string
CFG_PARAM_save_network_interval	str(object) -> string
CFG_PARAM_save_state_count	str(object) -> string
CFG_PARAM_save_state_count_interval	str(object) -> string
CFG_PARAM_save_state_influx	str(object) -> string
CFG_PARAM_save_state_influx_interval	str(object) -> string
CFG_PARAM_uniqueFileName	str(object) -> string
CFG_SECTION_EDGE_STATE_DIST	str(object) -> string
CFG_SECTION_INFO	str(object) -> string
CFG_SECTION_LOG	str(object) -> string
CFG_SECTION_MOD	str(object) -> string
CFG_SECTION_NETWORK	str(object) -> string
CFG_SECTION_NODE_STATE_DIST	str(object) -> string
CFG_SECTION_OUTPT	str(object) -> string
CFG_SECTION_SIM	str(object) -> string
STATE_COUNT_FIELD_NAME	str(object) -> string
STATE_INFLUX_FIELD_NAME	str(object) -> string
TIME_FIELD_NAME	str(object) -> string