idmtools SimulationBuilder definition.

Copyright 2021, Bill & Melinda Gates Foundation. All rights reserved.


Bases: object

Class that represents an experiment builder.


import os
import sys

from idmtools.assets import AssetCollection
from import SimulationBuilder
from idmtools.core.platform_factory import platform
from idmtools.entities.experiment import Experiment
from idmtools.entities.templated_simulation import TemplatedSimulations
from idmtools_models.python.json_python_task import JSONConfiguredPythonTask
from idmtools_test import COMMON_INPUT_PATH

with platform('BELEGOST'):
    base_task = JSONConfiguredPythonTask(
        script_path=os.path.join(COMMON_INPUT_PATH, "compsplatform", ""),
        # add common assets from existing collection
        common_assets=AssetCollection.from_id('41c1b14d-0a04-eb11-a2c7-c4346bcb1553', as_copy=True)

    ts = TemplatedSimulations(base_task=base_task)
    # sweep parameter
    builder = SimulationBuilder()
    builder.add_sweep_definition(JSONConfiguredPythonTask.set_parameter_partial("min_x"), range(-2, 0))
    builder.add_sweep_definition(JSONConfiguredPythonTask.set_parameter_partial("max_x"), range(1, 3))

    e = Experiment.from_template(ts, name=os.path.split(sys.argv[0])[1])
    # use system status as the exit code
    sys.exit(0 if e.succeeded else -1)

Add tags with builder callbacks:

def update_sim(sim, parameter, value):
    sim.task.set_parameter(parameter, value)
    # set sim tasks,
    return {'custom': 123, parameter:value)

builder = SimulationBuilder()
set_run_number = partial(update_sim, param="Run_Number")
builder.add_sweep_definition(set_run_number, range(0, 2))
# create experiment from builder
exp = Experiment.from_builder(builder, task, name=expname)
SIMULATION_ATTR = 'simulation'


add_sweep_definition(function: Union[Callable[[idmtools.entities.simulation.Simulation, Any], Dict[str, Any]], functools.partial], values)

Add a parameter sweep definition.

A sweep definition is composed of a function and a list of values to call the function with.

  • function – The sweep function, which must include a simulation parameter (or whatever is specified in SIMULATION_ATTR). The function also must include EXACTLY ONE free parameter, which the values will be passed to. The function can also be a partial–any Callable type will work.

  • values – The list of values to call the function with.


Examples of valid function:

def myFunction(simulation, parameter):

How to deal with functions requiring more than one parameter? Consider the following function:

def myFunction(simulation, a, b):

Partial solution:

from functools import partial
func = partial(myFunction, a=3)
eb.add_sweep_definition(func, [1,2,3])

Callable class solution:

class setP:
    def __init__(self, a):
        self.a = a

    def __call__(self, simulation, b):
        return param_update(simulation, self.a, b)

eb.add_sweep_definition(setP(3), [1,2,3])
add_multiple_parameter_sweep_definition(function: Union[Callable[[idmtools.entities.simulation.Simulation, Any], Dict[str, Any]], functools.partial], *args, **kwargs)

Add a sweep definition callback that takes multiple parameters.

The sweep will be defined as a cross-product between the parameters passed.

  • function – The sweep function, which must include a simulation parameter (or whatever is specified in SIMULATION_ATTR).

  • args – List of arguments to be passed

  • kwargs – List of keyword arguments to be passed


None. Updates the Sweeps


Examples of valid functions:

# This function takes two parameters
def myFunction(simulation, parameter_a, parameter_b):

# Function that takes three parameters
def three_param_callback(simulation, parameter_a, parameter_b, parameter_c):

Calling Sweeps that take multiple parameters:

# This example references the above valid function example
sb = SimulationBuilder()

# Add a sweep on the myFunction that takes two parameters.
# Here we sweep the values 1-4 on parameter_a and a,b on parameter_b
sb.add_multiple_parameter_sweep_definition(myFunction, range(1,5), ["a", "b"])

sb2 = SimulationBuilder()
# Example calling using a dictionary instead
sb.add_multiple_parameter_sweep_definition(three_param_callback, dict(parameter_a=range(1,5), parameter_b=["a", "b"], parameter_c=range(4,5))
# The following is equivalent
sb.add_multiple_parameter_sweep_definition(three_param_callback, **dict(parameter_a=range(1,5), parameter_b=["a", "b"], parameter_c=range(4,5))