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('BELEGOST'):
    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.

add_sweep_definition(function: Callable[[Simulation, Any], Dict[str, Any]] | 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.

Parameters:

• 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

Examples of valid function:

def myFunction(simulation, parameter):
    pass

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

python
def myFunction(simulation, a, b):
    pass

Partial solution:

python
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: Callable[[Simulation, Any], Dict[str, Any]] | 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.

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 two parameters
def myFunction(simulation, parameter_a, parameter_b):
    pass

# Function that takes three parameters
def three_param_callback(simulation, parameter_a, parameter_b, parameter_c):
    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 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))