emodpy.emod_task module#

class emodpy.emod_task.EMODTask(command: str | ~idmtools.entities.command_line.CommandLine = <property object>, platform_requirements: ~typing.Set[~idmtools.entities.platform_requirements.PlatformRequirements] = <factory>, _ITask__pre_creation_hooks: ~typing.List[~typing.Callable[[~idmtools.entities.simulation.Simulation | ~idmtools.entities.iworkflow_item.IWorkflowItem, ~idmtools.entities.iplatform.IPlatform], ~typing.NoReturn]] = <factory>, _ITask__post_creation_hooks: ~typing.List[~typing.Callable[[~idmtools.entities.simulation.Simulation | ~idmtools.entities.iworkflow_item.IWorkflowItem, ~idmtools.entities.iplatform.IPlatform], ~typing.NoReturn]] = <factory>, common_assets: ~idmtools.assets.asset_collection.AssetCollection = <factory>, transient_assets: ~idmtools.assets.asset_collection.AssetCollection = <factory>, eradication_path: str | None = None, demographics: ~emodpy.emod_file.DemographicsFiles = <factory>, migrations: ~emodpy.emod_file.MigrationFiles = <factory>, reporters: ~emodpy.reporters.base.Reporters = <factory>, climate: ~emodpy.emod_file.ClimateFiles = <factory>, config: dict = <factory>, config_file_name: str = 'config.json', campaign: ~emodpy.campaign.emod_campaign.EMODCampaign = <factory>, simulation_demographics: ~emodpy.emod_file.DemographicsFiles = <factory>, simulation_migrations: ~emodpy.emod_file.MigrationFiles = <factory>, schema_path: str | None = None, use_embedded_python: bool = False, py_path_list: list = <factory>, is_linux: bool = False, implicit_configs: list = <factory>, sif_filename: str | None = None)[source]#

Bases: ITask

EMODTask allows easy running and configuration of EMOD Experiments and Simulations

eradication_path: str = None#: Eradication path. Can also be set through config file

demographics: DemographicsFiles#: Common Demographics

migrations: MigrationFiles#: Common Migrations

reporters: Reporters#: Common Reports

climate: ClimateFiles#: Common Climate

config: dict#: Represents config.jon

config_file_name: str = 'config.json'#

campaign: EMODCampaign#: Campaign configuration

simulation_demographics: DemographicsFiles#: Simulation level demographics such as overlays

simulation_migrations: MigrationFiles#: Simulation level migrations

schema_path: str = None#

use_embedded_python: bool = False#: Add –python-script-path to command line

py_path_list: list#

is_linux: bool = False#

implicit_configs: list#

sif_filename: str = None#

sif_path = None#

create_campaign_from_callback(builder: Callable, verbose: bool = False, bootstrapped: bool = False) → None[source]#

This function is responsible for generating and configuring a campaign using a provided builder function. It also handles the custom events that are generated by the campaign by adding them to the config.

Parameters:

builder –

Function that creates and adds interventions to the campaign module. The function needs to take the campaign module as the first required argument, which can then be followed by parameters that you want to modify within the interventions. These additional parameters are then available to be modified in a sweep. The function must return the campaign module at the end.

Example:

def campaign_builder(campaign, another_param=0.3):
    from emodpy.campaign.individual_intervention import CommonInterventionParameters, SimpleVaccine, VaccineType
    from emodpy.campaign.distributor import add_intervention_scheduled
    import emodpy.campaign.waning_config as waning_config

    this_waning_config = waning_config.BoxExponential(25, 60, 0.89)
    common_intervention_parameters = CommonInterventionParameters(cost=0.5,
                                                                  dont_allow_duplicates=True)
    vaccine = SimpleVaccine(campaign,
                            waning_config=this_waning_config,
                            vaccine_take=another_param,
                            vaccine_type=VaccineType.TransmissionBlocking,
                            common_intervention_parameters=common_intervention_parameters)
    add_intervention_scheduled(campaign, intervention_list=[vaccine], start_day=2)
    return campaign

verbose – If True, prints debug information about the generated file.
bootstrapped – Set to True if the campaign builder will build a campaign from scratch itself. False if it will accept an initialized campaign from this function instead and then modify it. Default False.

Returns:

None

create_demographics_from_callback(builder: Callable, from_sweep: bool = False, verbose: bool = False) → None[source]#

Creates a demographics file using a builder function and manages its storage.

Parameters:

builder – A function that generates the demographics object.
from_sweep (bool) – If True, the demographics file is stored in a temporary location.
verbose (bool) – If True, prints debug information about the generated file.

Returns:

None

handle_implicit_configs() → None[source]#

Execute the implicit config functions created by the demographics builder.

Returns:: None

static build_default_config(schema_path: str | Path) → ReadOnlyDict[source]#

Build the default config object from the schema.

Parameters:: schema_path – Path to the schema file.
Returns:: The default config based on the schema.
Return type:: ReadOnlyDict

static build_default_campaign(schema_path: str | Path)[source]#

Build the default (empty) campaign and set its schema_path.

Parameters:: schema_path – Path to the schema file.
Returns:: Fresh initialized campaign module with schema_path set

Create a task from emod-api defaults and functions to update them.

Parameters:

schema_path – Path to processed schema.json, including the filename.
eradication_path – Path to Eradication binary, including the filename. You can also add Eradication as an asset.

config_builder –

Function that sets parameters for config. The function must have config object as the parameter and return the config object. Inside the function, the config object will be modified in the following way: config.parameters.<parameter_name> = <value>, with <parameter_name> being an attribute.

Example:

def config_builder(config):
    import emodpy.emod_enum as emod_enum
    config.parameters.Incubation_Period_Distribution = emod_enum.DistributionType.CONSTANT_DISTRIBUTION
    config.parameters.Incubation_Period_Constant = 5
    config.parameters.Infectious_Period_Distribution = emod_enum.DistributionType.CONSTANT_DISTRIBUTION
    config.parameters.Infectious_Period_Constant = 5
    config.parameters.Simulation_Duration = 80
    return config

campaign_builder –

Example:

def campaign_builder(campaign, additional_param=0.3):
    from emodpy.campaign.individual_intervention import CommonInterventionParameters, SimpleVaccine, VaccineType
    from emodpy.campaign.distributor import add_intervention_scheduled
    import emodpy.campaign.waning_config as waning_config

    this_waning_config = waning_config.BoxExponential(box_duration=25,
                                                      decay_time_constant=60,
                                                      initial_effect=0.89)
    common_intervention_parameters = CommonInterventionParameters(cost=0.5,
                                                                  dont_allow_duplicates=True)
    vaccine = SimpleVaccine(campaign,
                            waning_config=this_waning_config,
                            vaccine_take=additional_param,
                            vaccine_type=VaccineType.TransmissionBlocking,
                            common_intervention_parameters=common_intervention_parameters)
    add_intervention_scheduled(campaign, intervention_list=[vaccine], start_day=2)
    return campaign

demographics_builder –

Function that builds the demographics configuration and optional migration configuration.

Example:

def demographics_builder():
    import emodpy.demographics.Demographics as Demographics

    demographics_object = Demographics.from_template_node(pop=500)
    # other code setting demographics parameters
    return demographics_object

report_builder –

Function that creates reports to be used in the experiment. The function must have Reporters object as the parameter and return that object. It is assumed that all the reporters come from the reporters that are part of EMOD main code. EMOD also supports reporters as custom plug-in dlls, however, not through the current emodpy system.

Example:

def report_builder(reporters):
    from emodpy.reporters.reporters import ReportEventCounter, ReportFilter

    report_filter = ReportFilter(start_day=0, end_day=365, filename_suffix="LifeEvents")
    reporters.add(ReportEventCounter(reporters_object=reporters,
                       report_filter=report_filter,
                       event_list=["DiseaseDeaths", "Births", "HappyBirthday"]))
    return reporters

embedded_python_scripts_path – Path to folder with python scripts or a list of paths to specific python scripts. When path to folder, all python scripts in the folder will be added to the experiment. embedded_python_scripts_path may also be a list of such items, each added independently. Note: We no longer support passing in a function for this parameter.
serialized_population_files – Path to folder containing .dtk serialized population files or specific .dtk file, including the filename. All .dtk files in the folder will be added and used in the experiment.
bootstrapped – Set to True if the campaign builder will build a campaign from scratch itself. False if it will accept an initialized campaign from this function instead and then modify it. Default False.

Returns:

EMODTask

Load custom EMOD files when creating EMODTask.

Parameters:

eradication_path – Path to Eradication binary, including the filename.
config_path – Path to the configuration file, including the filename.
campaign_path – Path to the campaign file, including the filename.
demographics_paths – Path or a list of paths to the folder containing demographics files or path to a specific demographics file, including the filename. When path to folder, all .json files in the folder will be added to the experiment as demographics files.
custom_reports_path – Path to the custom reports file, including the filename. It is assumed that all the reporters in the file come from the reporters that are part of EMOD main code. EMOD also supports reporters as custom plug-in dlls, however, not through the current emodpy system.
embedded_python_scripts_path – Path to folder with python scripts or path to a specific python script, including the filename. When path to folder, all python scripts in the folder will be added to the experiment. Note: We no longer support passing in a function for this parameter.
serialized_population_files – Path to folder containing .dtk serialized population files or specific .dtk file, including the filename. All .dtk files in the folder will be added and used in the experiment.
asset_path – Path to migration and/or climate files.

Returns:

An initialized experiment

pre_creation(parent: Simulation | IWorkflowItem, platform: IPlatform)[source]#: Call before a task is executed. This ensures our configuration is properly done

set_command_line() → None[source]#

Build and set the command line object.

Returns:

add_py_path(path_to_add) → None[source]#

Add path to list of python paths prepended to sys.path in embedded interpreter

Returns:

set_sif(path_to_sif: Path | str, platform: IPlatform) → None[source]#

Set the singularity image file to use for creating the EMOD execution environment.

Parameters:

path_to_sif –
non-COMPSPlatforms: The file system path to the sif file for creating the EMOD execution environment. COMPSPlatform: Either:
1. The same sif file path as with other platforms
2. A .id file containing a COMPS AssetCollection id containing the desired sif file, formatted e.g.:
  8df53802-53f3-ec11-a9f9-b88303911bc1::Asset Collection
ContainerPlatform: No sif file specification is used.
platform – Platform object to use for this task.

Returns:

None

gather_common_assets() → AssetCollection[source]#: Gather Experiment Level Assets Returns:

gather_transient_assets() → AssetCollection[source]#: Gather assets that are per simulation :returns: AssetCollection

copy_simulation(base_simulation: Simulation) → Simulation[source]#

Called when making copies of a simulation. We deep copy parts of the simulation to ensure we don’t accidentally share objects between simulations.

Parameters:: base_simulation – Base Simulation
Returns:: New Simulation

set_parameter(name: str, value: any) → dict[source]#

Set a value in the EMOD config.json file. This will be deprecated in the future in favour of emod_api.config.

Parameters:

name – Name of parameter to set
value – Value to set

Returns:

Tags to set

static set_parameter_sweep_callback(simulation: Simulation, param: str, value: Any) → Dict[str, Any][source]#

Convenience callback for sweeps

Parameters:

simulation – Simulation we are updating
param – Parameter
value – Value

Returns:

Tags to set on simulation

classmethod set_parameter_partial(parameter: str)[source]#

Convenience callback for sweeps

Parameters:: parameter – Parameter to set
Returns:: Partial function

get_parameter(name: str, default: Any | None = None)[source]#

Get a parameter in the simulation.

Parameters:

name – The name of the parameter.
default – Optional, the default value.

Returns:

The value of the parameter.

add_embedded_python_scripts_from_path(path: str | Path | List[str | Path]) → None[source]#

Adds embedded python scripts from the path to the common assets

Parameters:: path – Relative or absolute path to the file (including the file name) or to a folder containing python scripts. Please note, all the python scripts in a specified folder will be added to the simulation. path may also be a list of such items, each added independently.

add_serialized_population_files_from_path(path: str) → None[source]#

Adds serialized population files from the path to the common assets

Parameters:: path – Relative or absolute path to the file (including the file name) or to the folder containing the .dtk files. Please note, all the .dtk files in the folder will be added and be used in the simulations.

reload_from_simulation(simulation: Simulation)[source]#: Optional hook that is called when loading simulations from a platform.

class emodpy.emod_task.EMODTaskSpecification[source]#

Bases: TaskSpecification

Idmtools implemented each platform and task as a Plugin and idmtools is able to identify them and use them dynamically. For example, idmtools workflow is able to crete each Platform with Plaform Factory and each Task with Task Factory. The link defined in setup.py entrypoint is the way to allow idmtools workflow to identify them.

Take EMODTaskSpecification as an example, idmtools uses it internally and indirectly (user usually doesn’t create an instance of it, but idmtools work may do in certain case). This EMODTaskSpecification entry in setup.py has been used in idmtools workflow in two places:

CLI command - check idmtools related packages installed (version including plugins): idmtools version - check available Task: idmtools info plugins task

get(configuration: dict) → EMODTask[source]#

Return an EMODTask object using provided configuration :param configuration: Configuration for Task

Returns:: EMODTask for configuration

get_description() → str[source]#

Defines a description of the plugin

Returns:: Plugin description

get_type() → Type[EMODTask][source]#

Returns the Task type defined by specification

Returns:

get_version() → str[source]#

Return the version string for EMODTask. This should be the module version so return that

Returns:: Version