Simulation setup#
These parameters determine the basic setup of a simulation including the type of simulation you are running, such as “GENERIC_SIM” or “MALARIA_SIM”, the simulation duration, and the time step duration.
Note
Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.
EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.
JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Config_Name |
string |
NA |
NA |
UNINITIALIZED STRING |
The optional, user-supplied title naming a configuration file. |
{
"Config_Name": "My_First_Config"
}
|
Custom_Coordinator_Events |
array of strings |
NA |
NA |
[] |
The list of valid, user-defined Coordinator Events that will be included in the campaign. These are specifically events which apply with EventCoordinators, such completing distribution of a collection of interventions. Any event used in the campaign must be in this list. |
{
"Custom_Coordinator_Events": [
"Coordinator_Event_1",
"Coordinator_Event_2",
"Coordinator_Event_3"
]
}
|
Custom_Individual_Events |
array of strings |
NA |
NA |
[] |
The list of valid, user-defined Individual Events that will be included in the campaign. These are specifically events which apply at an individual level, such as receiving a vaccine. Any individual event used in the campaign must either be one of the built-in events or in this list. See Event list for a list of all possible built-in events. |
{
"Custom_Individual_Events": [
"Individual_Event_1",
"Individual_Event_2",
"Individual_Event_3"
]
}
|
Custom_Node_Events |
array of strings |
NA |
NA |
[] |
The list of valid, user-defined Node Events that will be included in the campaign. These are specifically events which apply at the node/location level, such as finishing using an EnvironmentalDiagnostic. Any event used in the campaign must be in this list. |
{
"Custom_Node_Events": [
"Node_Event_1",
"Node_Event_2",
"Node_Event_3"
]
}
|
Enable_Interventions |
boolean |
0 |
1 |
0 |
Controls whether or not campaign interventions will be used in the simulation. Set Campaign_Filename to the path of the file that contains the campaign interventions. |
{
"Enable_Interventions": 1,
"Campaign_Filename": "campaign.json"
}
|
Enable_Random_Generator_From_Serialized_Population |
boolean |
0 |
1 |
0 |
Determines if the random number generator(s) should be extracted from a serialized population file. Enabling this will start a simulation from this file with the exact same random number stream and location in that stream as when the file was serialized. |
{
"Run_Number": 12,
"Random_Number_Generator_Type": "USE_AES_COUNTER",
"Random_Number_Generator_Policy": "ONE_PER_NODE",
"Enable_Random_Generator_From_Serialized_Population": 1
}
|
Enable_Skipping |
boolean |
0 |
1 |
0 |
Controls whether or not the simulation uses an optimization that can increase performance by up to 50% in some cases by probabilistically exposing individuals rather than exposing every single person. Useful in low-prevalence, high-population scenarios. |
{
"Enable_Skipping": 0
}
|
Enable_Termination_On_Zero_Total_Infectivity |
boolean |
0 |
1 |
0 |
Controls whether or not the simulation should be ended when total infectivity falls to zero. Supported only in single-node simulations. |
{
"Enable_Termination_On_Zero_Total_Infectivity": 1,
"Minimum_End_Time": 3650
}
|
Listed_Events |
array of strings |
NA |
NA |
[] |
The list of valid, user-defined events that will be included in the campaign. Any event used in the campaign must either be one of the built-in events or in this list. |
{
"Listed_Events": [
"Vaccinated",
"VaccineExpired"
]
}
|
Malaria_Model |
enum |
NA |
NA |
MALARIA_MECHANISTIC_MODEL |
The type of malaria model used in a simulation. Possible values are:
Note Most malaria simulations should use MALARIA_MECHANISTIC_MODEL. |
{
"Malaria_Model": "MALARIA_MECHANISTIC_MODEL"
}
|
Memory_Usage_Halting_Threshold_Working_Set_MB |
integer |
0 |
1.00E+06 |
8000 |
The maximum size (in MB) of working set memory before the system throws an exception and halts. |
{
"Memory_Usage_Halting_Threshold_Working_Set_MB": 4000
}
|
Memory_Usage_Warning_Threshold_Working_Set_MB |
integer |
0 |
1.00E+06 |
7000 |
The maximum size (in MB) of working set memory before memory usage statistics are written to the log regardless of log level. |
{
"Memory_Usage_Warning_Threshold_Working_Set_MB": 3500
}
|
Minimum_End_Time |
float |
0 |
1000000 |
0 |
The minimum time that the simulation must reach before checking for early termination conditions. Enable_Abort_Zero_Infectivity must be set to 1 (true). |
{
"Enable_Abort_Zero_Infectivity": 1,
"Minimum_End_Time": 3650
}
|
Node_Grid_Size |
float |
0.00416 |
90 |
0.004167 |
The spatial resolution indicating the node grid size for a simulation in degrees. |
{
"Node_Grid_Size": 0.042
}
|
Random_Number_Generator_Policy |
enum |
NA |
NA |
ONE_PER_CORE |
The policy that determines if random numbers are generated for objects in a simulation on a per-core or per-node basis. The following values are available:
|
{
"Run_Number": 15,
"Random_Number_Generator_Type": "USE_AES_COUNTER",
"Random_Number_Generator_Policy": "ONE_PER_NODE"
}
|
Random_Number_Generator_Type |
enum |
NA |
NA |
USE_PSEUDO_DES |
The type of random number generator to use for objects in a simulation. Must set the RNG seed in Run_Number. The following values are available:
|
{
"Run_Number": 15,
"Random_Number_Generator_Type": "USE_LINEAR_CONGRUENTIAL",
"Random_Number_Generator_Policy": "ONE_PER_NODE",
"Enable_Random_Generator_From_Serialized_Population": 1
}
|
Run_Number |
integer |
0 |
65535 |
1 |
Sets the random number seed used with Random_Number_Generator_Type and Random_Number_Generator_Policy to assign random numbers to objects in a simulation. This value must be different for each simulation run to ensure model stochasticity. |
{
"Run_Number": 15,
"Random_Number_Generator_Type": "USE_PSEUDO_DES",
"Random_Number_Generator_Policy": "ONE_PER_NODE",
"Enable_Random_Generator_From_Serialized_Population": 1
}
|
Serialization_Times |
array of floats |
0 |
The list of times at which to save the serialized state to file. 0 indicates the initial state before simulation, n indicates the time to serialize in terms of start time and step size, and will be rounded up to the nearest time step. The serialized population files can then be loaded at the beginning of a simulation using Serialized_Population_Filenames and Serialized_Population_Path. |
{
"Serialization_Type": "TIME",
"Serialization_Times": [
40.5,
81
]
}
|
||
Serialization_Time_Steps |
array of integers |
0 |
2.15E+09 |
The list of time steps after which to save the serialized state to file. 0 (zero) indicates the initial state before simulation, n indicates after the nth time step. Serialization_Type must be set to TIMESTEP. The serialized population files can then be loaded at the beginning of a simulation using Serialized_Population_Filenames and Serialized_Population_Path. |
{
"Serialization_Type": "TIMESTEP",
"Serialization_Time_Steps": [
0,
10
]
}
|
|
Serialization_Type |
enum |
NA |
NA |
NONE |
The type of serialization to perform. Serialization saves the population state at particular times so you can start from that state in other simulations. Accepted values are:
|
{
"Serialization_Times": [
365,
3650
],
"Serialization_Type": "TIMSTEP"
}
j {}
|
Serialized_Population_Filenames |
array of strings |
NA |
NA |
NA |
An array of filenames with serialized population data. The number of filenames must match the number of cores used for the simulation. The files must be in .dtk format. Serialized population files are created using Serialization_Time_Steps. |
{
"Serialized_Population_Filenames": [
"state-00010.dtk"
]
}
|
Serialized_Population_Path |
string |
NA |
NA |
. |
The root path for the serialized population files. Serialized population files are created using Serialization_Time_Steps. |
{
"Serialized_Population_Path": "../00_Generic_Version_1_save/output"
}
|
Simulation_Duration |
float |
0 |
1000000 |
1 |
The elapsed time (in days) from the start to the end of a simulation. |
{
"Simulation_Duration": 7300
}
|
Simulation_Timestep |
float |
0 |
1000000 |
1 |
The duration of a simulation time step, in days. |
{
"Simulation_Timestep": 1
}
|
Simulation_Type |
enum |
NA |
NA |
GENERIC_SIM |
The type of disease being simulated. Possible IDM-supported values are:
|
{
"Simulation_Type": "STI_SIM"
}
|
Start_Time |
float |
0 |
1000000 |
1 |
The time, in days, when the simulation begins. This time is used to identify the starting values of the temporal input data, such as specifying which day’s climate values should be used for the first day of the simulation. Note The Start_Day of campaign events is in absolute time, so time relative to the beginning of the simulation depends on this parameter. |
{
"Start_Time": 365
}
|