ctwrap Handler

The handler module defines a SimulationHandler object that handles batch jobs of wrapped Simulation module runs.

Usage

SimulationHandler objects run batch jobs based on YAML configuration files. A simple example for a YAML configuration is:

strategy: # parameter variation
  sequence-1:
    spam: [0.4, 0.6, 0.8, 1.0, 1.2, 1.4, 1.6, 1.8]
  sequence-2:
    eggs: [1, 2, 3]
defaults: # default parameters
  spam: 0.5
  eggs: 1
output:
  format: h5

In the following, a SimulationHandler object is used to run batch simulations of a Simulation module defined in my_test.py, where the run method takes two arguments (spam and eggs). Assuming that the YAML configuration file my_test.yaml corresponds to the YAML block above, the simulation strategy sequence-2 is loaded by issuing

import ctwrap as cw

seq = cw.SimulationHandler('my_test.yaml', strategy='sequence-2')
tasks = seq.tasks # dictionary with entries 'eggs_1', 'eggs_2', 'eggs_3'

Once loaded, tasks are passed to a Simulation object wrapping my_test.py:

sim = cw.Simulation.from_module('my_test.py')

seq.configuration('eggs_2) # return task configuration
seq.run_task(sim, 'eggs_2') # run a single simulation task

seq.run_serial(sim) # run all tasks in series
seq.run_parallel(sim) # run all tasks as parallel processes

Class Definition

class ctwrap.handler.SimulationHandler(strategy=None, defaults=None, output=None, verbosity=0)

Class handling parameter variations. Class adds methods to switch between multiple configurations.

Note

SimulationHandler objects should be instantiated using factory methods from_yaml() or from_dict().

Parameters

• strategy (Optional[Strategy]) – Batch simulation strategy

• defaults (Optional[Dict[str, Any]]) – Dictionary containing simulation defaults

• output (Optional[Dict[str, Any]]) – Dictionary specifying file output

• verbosity (Optional[int]) – Verbosity level

classmethod from_yaml(yaml_file, strategy=None, output_name=None, database=None, **kwargs)

Alternate constructor using YAML file as input.

The from_yaml() method is intended as the main route for the creation of SimulationHandler objects.

Parameters

• yaml_file (str) – YAML file located in current folder, database (argument), or ctwrap’s preconfigured YAML database (yaml folder)

• strategy (Optional[str]) – Batch job strategy name (only needed if more than one are defined)

• output_name (Optional[str]) – Output name (overrides YAML configuration)

• database (Optional[str]) – File database (both YAML configuration and output)

• **kwargs – Dependent on implementation

classmethod from_dict(content, strategy=None, output_name=None, output_path=None, **kwargs)

Alternate constructor using a dictionary as input.

Parameters

• content (Dict[str, Any]) – Dictionary from YAML input

• strategy (Optional[str]) – Batch job strategy name (only needed if more than one are defined)

• output_name (Optional[str]) – Output name (overrides YAML configuration)

• output_path (Optional[str]) – Output path (overrides YAML configuration)

• **kwargs – Dependent on implementation

Return type

Union[SimulationHandler, Dict[str, Any], str]

configuration(task)

Return configuration.

Parameters

task (str) – Task to do

Returns

updated configuration dictionary based on the task

property verbose

verbosity

property output_name

return output name

property tasks

tasks defined in terms of the variation entry and values

run_task(sim, task, **kwargs)

Function to run a specific task.

The run_task() method calls the module’s run method and saves the resulting output and metadata. A simple example is:

# Runs the task `sleep_0.4` using `sim` object
sh.run_task(sim, 'sleep_0.4' )

Parameters

• sim (Simulation) – instance of Simulation class

• task (str) – task to do

• **kwargs – dependent on implementation

run_serial(sim, verbosity=None, **kwargs)

Run variation in series.

The run_serial() method runs all the strategy entries in the input file in serial and also saves metadata. A simple usage example is:

# Runs all the variations serially
sh.run_serial(sim)

Parameters

• sim (Simulation) – instance of Simulation class

• verbosity (Optional[int]) – verbosity

• **kwargs – dependent on implementation

Return type

bool

Returns

True when task is completed

run_parallel(sim, number_of_processes=None, verbosity=None, **kwargs)

Run variation using multiprocessing.

The run_parallel() method runs all the strategy entries in the input file in parallel using python multiprocessing. and also saves metadata.

# Runs all the variations in parallel
sh.run_parallel(sim) # run

Parameters

• sim (Simulation) – instance of Simulation class

• number_of_processes (Optional[int]) – number of processes

• verbosity (Optional[int]) – verbosity level

• **kwargs – dependent on implementation

Return type

bool

Returns

True when task is completed