Overview

Ctwrap is a light-weight batch simulation wrapper written in Python. The wrapper consists of two main classes:

• the Simulation class that wraps a simulation module to be run, and

• the SimulationHandler class that handles parameter variations and switches between multiple configurations.

Parameter variations are based on a YAML configuration file, where the auxiliary Parser class is used to parsed the input file and also handles units using pint. In addition, the Strategy class specifies how the parameter variation is run.

Simulation Module

The wrapper requires a simulation module, - written as a single run python module, - that defines two methods: defaults and run. The layout similar to a conventional script, the main difference is that the code is organized. Specifically:

• The defaults() method returns default input parameters.

• The run() method runs a single simulation and returns a dictionary containing the output object.

The structure of a simulation module is illustrated by the following minimal example:

"""Simulation module illustrating a minimal ctwrap example"""
import time


def defaults():
    """Returns dictionary containing default arguments"""
    return {'foo': 0.2, 'bar': 1}


def run(foo=.2, bar=1):
    """This method 'sleeps' for the specified duration"""
    msg = '    - `minimal`: sleeping for {} * {} = {} seconds ...'
    print(msg.format(foo, bar, foo * bar))
    time.sleep(foo * bar)
    return {'sleep': [foo * bar]}


if __name__ == "__main__":
    """ Main function """
    config = defaults()
    out = run(**config)

YAML Configuration

The inputs are passed through a YAML configuration file. The YAML input has three main fields: strategy, output, and defaults.

• The strategy entry contains information about the variation. At the moment ctwrap supports Sequence and Matrix specifications. The values can be specified as a list or alternatively using modes such as numpy arange or linspace.

• The output entry contains information about the resulting file to be saved such as the file_name, path etc. The output is optional, and in that case, the file is saved with the name of the module to be run.

• The defaults entry contains default inputs required to run the simulation module.

• The ctwrap entry indicates the minimum ctwrap revision that supports the YAML format

The structure of a YAML configuration file is illustrated by the following minimal example:

# YAML file example for the `minimal` simulation module (minimal.py)
# file specifes a parameter variation of sleep duration
strategy:
  sequence: # example for a batch sequence
    foo: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]
  matrix: # example for a batch matrix
    foo: { mode: linspace , limits: [0.1, 0.3], npoints: 3 }
    bar: { mode: arange, limits: [2, -1], step: -1 }
defaults:
  foo: 0.2
  bar: 1
ctwrap: 0.2.0

Running a Batch Job

A parallel batch job for the minimal example using the configuration and the simulation module above can be run from the command line as:

$ ctwrap run minimal minimal.yaml --parallel