caseset – runs a case for a set of different input parameters

This module defines the CaseSet class that runs a case for a set of different parameters. The cases are defined with a table of the form:

#
# Filename:  file1     file2     file3
# Index:      ind1      ind2      ind3
# Casename    par1      par2      par3
case1          0.1       4.3      3.14
case2          0.2       4.3      3.14
case3          0.1       4.5      3.14
case4          0.2       4.5      3.14
case5          0.2       4.5      6.28

Each row correspond to a case. The first column gives the case names while the remaining columns gives the new values of the parameters that are changed. The table data is preceeded by three or more comment rows starting with a hash (#). The three last comment lines must in the first column have the keywords (in this order):

“Filename:”

This row gives the name of the file in which the parameters are defined. All files provided on this row are automatically copied from the case directory to the working directory for each case. Possible values are:

filename:The parameter will be read from this file. “-“:The parameter is ignored by CaseSet. It is still available for the case through the casepar property. “->”:A keyword argument parameters holding a dict is passed to the run() or target() function for the case. The name-value pair of the current parameter is added to this dict.

“Index:”

The columns following “Index:” must be either:

index:Any valid NumPy indexing, indicating that the parameter is indexable with a name corresponding to a table column. If a file name is given in the row above, it is assumed to be table and will be read and rewritten with pario.recio. “-“:Indicates that the parameter can/shall not be indexed. If a file name is given in the row above, it is assumed to be a parameter file and will be read and rewritten with pario.Parameters.

“Casename”

Finally the row starting “Casename” is the table header containing the parameter names.

Warning

The implementation uses eval() for treating indices given in the “Index:” row correctly. This might be a security risk if the table comes from a untrusted source.

Examples

>>> import numpy as np

>>> import pario
>>> from caseset import CaseSet

Create case table

>>> table = r'''#
... # Filename:   a.txt    b.txt        ->
... # Index:      -1       -            -
... # Casename    time(s)  startpos(m)  v(m/s)   
...   slow1       120.     0.           2.
...   slow2       120.     500.         2.
...   fast1       60.      0.           10.
...   fast2       60.      250.         10.
... '''

Create input files

>>> t = np.linspace(0., 60, 7)
>>> dummy = t * 5 - 50.
>>> r = np.rec.fromarrays([t, dummy], names=['time(s)', 'dummy'])
>>> pario.recio.write('a.txt', r)

>>> p = pario.parameters.Parameters()
>>> p.startdate = '2014-05-20'
>>> p.starttime = '14:45'
>>> p._set('startpos', 0.0, 'm')
>>> p._write('b.txt')

Case function

>>> def target():
...     pass

>>> c = CaseSet()

CaseSet object

class pario.caseset.CaseSet(casedir=None, tmpdir=None, cleanup=None, target=None, cls=None)

A class for running a modelling case several times with different parameters.

Parameters :

casedir : None | string

Directory with all inputfiles for the case. If None, it defaults to the current working directory.

tmpdir : None | string

Directory for temporary working directories. If None, the environment variable CASE_TMPDIR will be used. If this isn’t defined, a subdirectory “tmp” in the current working directory will be used (created if it does not exists).

cleanup : None, bool | “on_success”

Whether to automatically remove the temporary working directories when the cases has finished. If the special value of “on_success” is given, workdir is only removed if no unhandled exception is raised during the execution of run(). This might be very useful for debugging. The default is False if workdir is provided and “on_success” otherwise.

target : callable

A callable object that will be invoked when the start() method is called. It will be called as target(case, *args, **kwargs), where case is a reference to the Case object and args and kwargs are the arguments passed to start().

Note

If “->” is given as file name in the case table, target() will be called with a keyword argument parameters holding a dict mapping the names of not already handled parameters to a tuple with its new value(s).

start(cases, args=None, kwargs=None, nthreads=None)