scitools.multipleloop

This module provides a tool for handling computer experiments with of a set of input parameters, where each input parameter is varied in a prescribed fashion.

In short, the parameters are held in a dictionary where the keys are the names of the parameters and the values are the numerical, string or other values of the parameters. The value can take on multiple values: e.g., an integer parameter ‘a’ can have values -1, 1 and 10. Similarly, a string parameter ‘method’ can have values ‘Newton’ and ‘Bisection’. The module will generate all combination of all parameters and values, which in the mentioned example will be (-1, ‘Newton’), (1, ‘Newton’), (10, ‘Newton’), (-1, ‘Bisection’), (1, ‘Bisection’), and (10, ‘Bisection’). Particular combination of values can easily be removed.

The usage and implementation of the module are documented in the book “Python Scripting for Computational Science” (H. P. Langtangen, Springer, 2009), Chapter 12.1.

Simple use of basic functionality in the module are shown below. See the book for explanations and more comprehensive examples.

>>> from scitools.multipleloop import *
>>>
>>> # parameter names and multiple values,
>>> # using the special multipleloop syntax:
>>> p = {'A': '1 & 2 & 5', 'B': 'hello & world'}
>>>
>>> # turn multiple values syntax like 1 & 2 & 5 into list of values
>>> input2values(p['A'])
[1, 2, 5]
>>>
>>> prm_values = [(name, input2values(p[name])) for name in p]
>>> import pprint
>>> pprint.pprint(prm_values)
[('A', [1, 2, 5]), ('B', ['hello', 'world'])]
>>>
>>> # main function:
>>> all, names, varied = combine(prm_values)
>>>
>>> # all[i] holds all parameter values in experiment no i,
>>> # names holds the parameter names, and varied holds the
>>> # parameter names that are actually varied (not fixed values)
>>> print names
['A', 'B']
>>> print varied
['A', 'B']
>>> pprint.pprint(all)
[[1, 'hello'],
 [2, 'hello'],
 [5, 'hello'],
 [1, 'world'],
 [2, 'world'],
 [5, 'world']]
>>>
>>> e = 1
>>> for experiment in all:
...     print 'Experiment %4d:' % e,
...     for name, value in zip(names, experiment):
...         print '%s: %s' % (name, value),
...     print # newline
...     e += 1  # experiment counter
...
Experiment    1: A: 1 B: hello
Experiment    2: A: 2 B: hello
Experiment    3: A: 5 B: hello
Experiment    4: A: 1 B: world
Experiment    5: A: 2 B: world
Experiment    6: A: 5 B: world
>>>
>>> # turn parameter names and values into command-line options
>>> # (useful for running a program that takes parameter names prefixed
>>> # by - or -- as command-line options):
>>> cmd = options(all, names, prefix='-')
>>> for c in cmd:
...     print c
...     #commands.getstatusoutput(programname + ' ' + c)
...
-A True -B 'hello'
-A True -B 'hello'
-A True -B 'hello'
-A True -B 'world'
-A True -B 'world'
-A True -B 'world'
>>>
>>> print 'all combinations: %d' % len(all)
all combinations: 6
>>>
>>> # compute pairs:
>>> all = pairs(prm_values)
>>> print 'all pairs: %d' % len(all); pprint.pprint(all)
all pairs: 6
[[1, 'hello'],
 [2, 'hello'],
 [5, 'hello'],
 [5, 'world'],
 [2, 'world'],
 [1, 'world']]
>>>
>>> # alternative class interface:
>>> experiments = MultipleLoop(option_prefix='-')
>>> for name in p:
...     experiments.register_parameter(name, p[name])
...
>>> experiments.combine()  # compute all combinations
>>>
>>> # remove all experiments corresponding to a condition:
>>> nremoved = experiments.remove('A == 5')
>>>
>>> # look at the attributes of this instance:
>>> pprint.pprint(experiments.all)
[[1, 'hello'], [2, 'hello'], [1, 'world'], [2, 'world']]
>>> print experiments.names
['A', 'B']
>>> print experiments.varied
['A', 'B']
>>> print experiments.options
["-A True -B 'hello'", "-A True -B 'hello'", "-A True -B 'world'",
 "-A True -B 'world'"]
>>> pprint.pprint(experiments.prm_values)
[('A', [1, 2, 5]), ('B', ['hello', 'world'])]

Here is another example with more experiments:

>>> p = {'b': '1 & 0 & 0.5', 'func': 'y & siny', 'w': '[1:1.3,0.1]'}
>>> prm_values = [(name, input2values(p[name])) for name in p]
>>> import pprint
>>> pprint.pprint(prm_values)

[(‘b’, [1, 0, 0.5]),

(‘w’, [1, 1.1000000000000001, 1.2000000000000002]), (‘func’, [‘y’, ‘siny’])]

>>>
>>> # main function:
>>> all, names, varied = combine(prm_values)
>>>
>>> print names
['b', 'w', 'func']
>>> print varied
['b', 'w', 'func']
>>> pprint.pprint(all)
[[1, 1, 'y'],
 [0, 1, 'y'],
 [0.5, 1, 'y'],
 [1, 1.1000000000000001, 'y'],
 [0, 1.1000000000000001, 'y'],
 [0.5, 1.1000000000000001, 'y'],
 [1, 1.2000000000000002, 'y'],
 [0, 1.2000000000000002, 'y'],
 [0.5, 1.2000000000000002, 'y'],
 [1, 1, 'siny'],
 [0, 1, 'siny'],
 [0.5, 1, 'siny'],
 [1, 1.1000000000000001, 'siny'],
 [0, 1.1000000000000001, 'siny'],
 [0.5, 1.1000000000000001, 'siny'],
 [1, 1.2000000000000002, 'siny'],
 [0, 1.2000000000000002, 'siny'],
 [0.5, 1.2000000000000002, 'siny']]
>>>
>>> print 'all combinations: %d' % len(all)
all combinations: 18
>>>
>>> # compute pairs:
>>> all = pairs(prm_values)
>>> print 'all pairs: %d' % len(all); pprint.pprint(all)
all pairs: 9
[[1, 1, 'y'],
 [0, 1.1000000000000001, 'y'],
 [0.5, 1.2000000000000002, 'y'],
 [0.5, 1.1000000000000001, 'siny'],
 [0, 1, 'siny'],
 [1, 1.2000000000000002, 'siny'],
 [1, 1.1000000000000001, 'siny'],
 [0, 1.2000000000000002, 'siny'],
 [0.5, 1, 'siny']]
>>>
>>> # alternative class interface:
>>> experiments = MultipleLoop(option_prefix='-')
>>> for name in p:
...     experiments.register_parameter(name, p[name])
...
>>> experiments.combine()
>>>
>>> # remove all experiments corresponding to a condition:
>>> nremoved = experiments.remove('b == 1')
>>>
>>> # look at the attributes of this instance:
>>> pprint.pprint(experiments.all)
[[0, 1, 'y'],
 [0.5, 1, 'y'],
 [0, 1.1000000000000001, 'y'],
 [0.5, 1.1000000000000001, 'y'],
 [0, 1.2000000000000002, 'y'],
 [0.5, 1.2000000000000002, 'y'],
 [0, 1, 'siny'],
 [0.5, 1, 'siny'],
 [0, 1.1000000000000001, 'siny'],
 [0.5, 1.1000000000000001, 'siny'],
 [0, 1.2000000000000002, 'siny'],
 [0.5, 1.2000000000000002, 'siny']]

>>> # explore the response of varied parameters:
>>> # function = []  # list of (response, (param1, param2, ...))
>>> # the (param1, param2, ...) list equals the varied parameter values
>>> # in each experiment (varied_parameters in the loop below)
>>>
>>> for cmlargs, parameters, varied_parameters in experiments:
...     args = ', '.join(['%s=%s' % (name,value) for name, value in zip(experiments.names, parameters)])
...     print
...     print 'can call some function:'
...     print 'response = myfunc(%s)' % args
...     print 'or run some program with options:'
...     print 'prompt> myprog ', cmlargs
...     print 'and extract a response from the program output'
...     print 'function.append((response, varied_parameters))'
...
can call some function:
response = myfunc(b=0, w=1, func=y)
or run some program with options:
prompt> myprog  -b False -w True -func 'y'
and extract a response from the program output
function.append((response, varied_parameters))
can call some function:
response = myfunc(b=0.5, w=1, func=y)
or run some program with options:
prompt> myprog  -b 0.5 -w True -func 'y'
and extract a response from the program output
function.append((response, varied_parameters))
can call some function:
response = myfunc(b=0, w=1.1, func=y)
or run some program with options:
prompt> myprog  -b False -w 1.1000000000000001 -func 'y'
and extract a response from the program output
function.append((response, varied_parameters))
can call some function:
response = myfunc(b=0.5, w=1.1, func=y)
or run some program with options:
prompt> myprog  -b 0.5 -w 1.1000000000000001 -func 'y'
and extract a response from the program output
function.append((response, varied_parameters))
can call some function:
response = myfunc(b=0, w=1.2, func=y)
or run some program with options:
prompt> myprog  -b False -w 1.2000000000000002 -func 'y'
and extract a response from the program output
function.append((response, varied_parameters))
can call some function:
response = myfunc(b=0.5, w=1.2, func=y)
or run some program with options:
prompt> myprog  -b 0.5 -w 1.2000000000000002 -func 'y'
and extract a response from the program output
function.append((response, varied_parameters))
can call some function:
response = myfunc(b=0, w=1, func=siny)
or run some program with options:
prompt> myprog  -b False -w True -func 'siny'
and extract a response from the program output
function.append((response, varied_parameters))
can call some function:
response = myfunc(b=0.5, w=1, func=siny)
or run some program with options:
prompt> myprog  -b 0.5 -w True -func 'siny'
and extract a response from the program output
function.append((response, varied_parameters))
can call some function:
response = myfunc(b=0, w=1.1, func=siny)
or run some program with options:
prompt> myprog  -b False -w 1.1000000000000001 -func 'siny'
and extract a response from the program output
function.append((response, varied_parameters))
can call some function:
response = myfunc(b=0.5, w=1.1, func=siny)
or run some program with options:
prompt> myprog  -b 0.5 -w 1.1000000000000001 -func 'siny'
and extract a response from the program output
function.append((response, varied_parameters))
can call some function:
response = myfunc(b=0, w=1.2, func=siny)
or run some program with options:
prompt> myprog  -b False -w 1.2000000000000002 -func 'siny'
and extract a response from the program output
function.append((response, varied_parameters))
can call some function:
response = myfunc(b=0.5, w=1.2, func=siny)
or run some program with options:
prompt> myprog  -b 0.5 -w 1.2000000000000002 -func 'siny'
and extract a response from the program output
function.append((response, varied_parameters))

class scitools.multipleloop.MultipleLoop(option_prefix='--')

High-level, simplified interface to the functionality in the multipleloop module.

Typical application:

p = {'name1': 'multiple values', 'name2': 'values', ...}
experiments = scitools.multipleloop.MultipleLoop(option_prefix='-')
for name in p:
    experiments.register_parameter(name, p[name])
experiments.combine()  # find all combinations of all parameters
for cmlargs, parameters, varied_parameters in experiments:
    <run experiment: some program + cmlargs>
    <extract response, varied_parameters holds the values of
     the parameters that were varied in this experiment (the
     independent variables mapping onto the response)

Attributes (m is some MultipleLoop object):

m.names	names of all parameters
m.varied	names of parameters with multiple values (the rest of the parameters have constant values throughout the experiments)
m.options	list of strings of all command-line arguments (-name value), one for each experiment
m.all	list of all experiments
m.prm_values	list of (name, valuelist) tuples

Example:

>>> p = {'b': '1 & 0 & 0.5', 'func': 'y & siny', 'w': '[1:1.3,0.1]'}
>>> experiments = MultipleLoop(option_prefix='-')
>>> for name in p:
...     experiments.register_parameter(name, p[name])
...
>>> experiments.combine()
>>>
>>> # remove all experiments corresponding to a condition:
>>> nremoved = experiments.remove('b == 1')
>>>
>>> # look at the attributes of this instance:
>>> pprint.pprint(experiments.all)
[[0, 1, 'y'],
 [0.5, 1, 'y'],
 [0, 1.1000000000000001, 'y'],
 [0.5, 1.1000000000000001, 'y'],
 [0, 1.2000000000000002, 'y'],
 [0.5, 1.2000000000000002, 'y'],
 [0, 1, 'siny'],
 [0.5, 1, 'siny'],
 [0, 1.1000000000000001, 'siny'],
 [0.5, 1.1000000000000001, 'siny'],
 [0, 1.2000000000000002, 'siny'],
 [0.5, 1.2000000000000002, 'siny']]

Methods

add(name, values)	Register a parameter and its value or multiple values.
combine()	Compute all combinations of all parameters.
next()
register_parameter(name, values)	Register a parameter and its value or multiple values.
remove(condition)	Remove experiments that fulfill a boolean condition.

__init__(option_prefix='--')

option_prefix is the prefix that will be used in command-line options (typically ‘-‘ or ‘–’).

__iter__()

__module__ = 'scitools.multipleloop'

add(name, values)

Register a parameter and its value or multiple values.

combine()

Compute all combinations of all parameters.

next()

register_parameter(name, values)

Register a parameter and its value or multiple values.

remove(condition)

Remove experiments that fulfill a boolean condition. Example:

e.remove('w < 1.0 and p = 1.2) or (q in (1,2,3) and f < 0.1')

(names of the parametes must be used)

class scitools.multipleloop.ReportHTML(filename)

Methods

dump(text)
experiment_section(parameters, names, varied)	Start new H1 section in the HTML document.

__init__(filename)

__module__ = 'scitools.multipleloop'

dump(text)

experiment_section(parameters, names, varied)

Start new H1 section in the HTML document. parameters is a list of the values of all parameters in an experiment, names holds the names of all parameters, and varied holds the names of the parameters that are actually varied. The three input lists are computed by functions in this module (or the MultipleLoops class).

scitools.multipleloop.combine(prm_values)

Compute the combination of all parameter values in the prm_values (nested) list. Main function in this module.

param prm_values: nested list (parameter_name, list_of_parameter_values) or dictionary prm_values[parameter_name] = list_of_parameter_values. return: (all, names, varied) where

• all contains all combinations (experiments) all[i] is the list of individual parameter values in experiment no i
• names contains a list of all parameter names
• varied holds a list of parameter names that are varied (i.e. where there is more than one value of the parameter, the rest of the parameters have fixed values)

Code example:

>>> dx = array([1.0/2**k for k in range(2,5)])
>>> dt = 3*dx;  dt = dt[:-1]
>>> p = {'dx': dx, 'dt': dt}
>>> p
{'dt': [ 0.75 , 0.375,], 'dx': [ 0.25  , 0.125 , 0.0625,]}
>>> all, names, varied = combine(p)
>>> all
[[0.75, 0.25], [0.375, 0.25], [0.75, 0.125], [0.375, 0.125],
 [0.75, 0.0625], [0.375, 0.0625]]

scitools.multipleloop.input2values(s)

Translate a string s with multiple loop syntax into a list of single values (for the corresponding parameter).

Multiple loop syntax: ‘-1 & -3.4 & 20 & 70 & [0:10,1.3] & [0:10] & 11.76’

That is, & is delimiter between different values, [0:10,1.3] generates a loop from 0 up to and including 10 with steps 1.3, [0:10] generates the integers 1,2,...,10.

Interactive session:

>>> input2values('-1 & -3.4 & 20 & 70 & [0:10,1.3] & [0:10] & 11.76')

[-1, -3.3999999999999999, 20, 70, 0, 1.3, 2.6000000000000001,

3.9000000000000004, 5.2000000000000002, 6.5, 7.7999999999999998, 9.0999999999999996, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11.76]

>>> p = {'w': '[0.7:1.3,0.1]', 'b': '1 & 0.3 & 0', 'func': 'y & siny'}
>>> print input2values(p['w'])
[0.69999999999999996, 0.79999999999999993, 0.89999999999999991,
 0.99999999999999989, 1.0999999999999999, 1.2, 1.3]
>>> print input2values(p['b'])
[1, 0.29999999999999999, 0]
>>> print input2values(p['func'])
['y', 'siny']
>>> prm_values = [(name, input2values(p[name])) for name in p]
>>> prm_values
[('b', [1, 0.29999999999999999, 0]),
 ('func', ['y', 'siny']),
 ('w', [0.69999999999999996, 0.79999999999999993, 0.89999999999999991,
        0.99999999999999989, 1.0999999999999999, 1.2, 1.3])]

scitools.multipleloop.options(all, names, prefix='--')

Return a list of command-line options and their values.

all	all[i] holds a list of parameter values in experiment no i
names	names[i] holds name of parameter no. i
prefix	an option equals prefix + name (prefix is ‘–’ or ‘-‘)
return	cmd[i] holds -name value pairs of all parameters in experiment no. i

scitools.multipleloop.pairs(prm_values, n=2)

Compute parameter combinations of the parameter values in prm_values (list of (name, values) pairs, where values is a list of values). Not all combinations are computed (as in function combine), but only a subset so that all pairs of all parameter values appear once. This gives a substantially smaller set of combinations than when all parameter values are combined with all others. n=2 correspond to pairs, n=3 to triplets, and so on.

The computations are performed with the aid of the AllPairs package developed and maintained by MetaCommunications Engineering, see http://pypi.python.org/pypi/AllPairs/2.0.1. Only input and output are adapted here to the syntax of the multipleloop module.

scitools.multipleloop.remove(condition, all, names)

Remove experiments that fulfill a boolean condition. Example:

all = remove('w < 1.0 and p = 1.2) or (q in (1,2,3) and f < 0.1', all, names)

(names of the parametes must be used)