idmtools.builders.simulation_builder module

idmtools SimulationBuilder definition.

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

class idmtools.builders.simulation_builder.SimulationBuilder

Bases: object

Class that represents an experiment builder.

Examples

import os
import sys

from idmtools.assets import AssetCollection
from idmtools.builders 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('Calculon'):
    base_task = JSONConfiguredPythonTask(
        script_path=os.path.join(COMMON_INPUT_PATH, "compsplatform", "working_model.py"),
        # 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))
    ts.add_builder(builder)

    e = Experiment.from_template(ts, name=os.path.split(sys.argv[0])[1])
    e.run(wait_until_done=True)
    # 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'

__init__()

Constructor.

property count

add_sweep_definition(function: Callable[[Simulation, Any], Dict[str, Any]] | partial, *args, **kwargs)

Add a sweep definition callback that takes possible multiple parameters (None or many).

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

Parameters:

• 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

Returns:

None. Updates the Sweeps

Examples

Examples of valid functions:

 # This function takes one parameter
 def myFunction(simulation, parameter_a):
     pass

# This function takes one parameter with default value
 def myFunction(simulation, parameter_a=6):
     pass

 # This function takes two parameters (parameters may have default values)
 def myFunction(simulation, parameter_a, parameter_b=9):
     pass

 # Function that takes three parameters (parameters may have default values)
 def three_param_callback(simulation, parameter_a, parameter_b, parameter_c=10):
     pass

Calling Sweeps that take multiple parameters:

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

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

sb2 = SimulationBuilder()
# Example calling using a dictionary instead
sb.add_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_sweep_definition(three_param_callback, **dict(parameter_a=range(1,5), parameter_b=["a", "b"], parameter_c=range(4,5))

sb3 = SimulationBuilder()
# If all parameters have default values, we can even simply do
sb3.add_sweep_definition(three_param_callback)

Remark: in general:

def my_callback(simulation, parameter_1, parameter_2, ..., parameter_n):
    pass

Calling Sweeps that take multiple parameters:

sb = SimulationBuilder()
sb.add_sweep_definition(my_callback, Iterable_1, Iterable_2, ..., Iterable_m)

# Note: the # of Iterable object must match the parameters # of my_callback, which don't have default values

# Or use the key (parameter names)

sb = SimulationBuilder()
sb.add_sweep_definition(my_callback, parameter_1=Iterable_1, parameter_2=Iterable_2, ..., parameter_m=Iterable_m)
# The following is equivalent
sb.add_sweep_definition(my_callback, dict(parameter_1=Iterable_1, parameter_2=Iterable_2, ..., parameter_m=Iterable_m))
# and
sb.add_sweep_definition(my_callback, **dict(parameter_1=Iterable_1, parameter_2=Iterable_2, ..., parameter_m=Iterable_m))

case_args_tuple(function: Callable[[Simulation, Any], Dict[str, Any]] | partial, remaining_parameters, values)

case_kwargs(function: Callable[[Simulation, Any], Dict[str, Any]] | partial, remaining_parameters, values)

add_multiple_parameter_sweep_definition(function: Callable[[Simulation, Any], Dict[str, Any]] | partial, *args, **kwargs)

Add a sweep definition callback that takes possible multiple parameters (None or many).

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

Parameters:

• 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

Returns:

None. Updates the Sweeps

Examples

Refer to the comments in the add_sweep_definition function for examples