TestProgram

class puq.TestProgram(name='', exe='', func=None, func_args=None, newdir=False, infiles='', desc='', outfiles='', paramsByFile=False)

Class implementing a TestProgram object representing the simulation to run.

Parameters:

• name (string) – Name of the program. This is the executable if no exe is defined.

• exe (string) – An executable command template to run. Strings of the form ‘$var’ are replaced with the value of var. See python template strings (http://docs.python.org/2/library/string.html#template-strings). Can be used with any host EXCEPT InteractiveHostMP.

• func – a python function to execute. If func is specified, name and exe are ignored. Note: func must be a module-level function. It cannot be in a class or another function. Can only be used with InteractiveHostMP.

• func_args – the arguments to the python function. See example 4.

• desc – Optional description of the test program.

• newdir (boolean) – Run each job in its own directory. Necessary if the simulation generates output files. Default is False.

• infiles (list) – If newdir is True, then this is an optional list of files that should be copied to each new directory.

• outfiles (list) – An optional list of files that will be saved into the HDF5 file upon completion. The files will be in /output/jobs/n where ‘n’ is the job number.

• paramsByFile (boolean) – If True, passes parameters to the TestProgram via a file rather than on the command line. The file name is specified via - -paramsFile=xxx in the exe string. This option must be used with newdir=True. See Example 3.

  Furthermore, when paramsByFile is True, custom command line arguments may be passed to the test program without interfering with the parameter values passed to puq.

Example1:

p1 = UniformParameter('x', 'x', min=-2, max=2)
p2 = UniformParameter('y', 'y', min=-2, max=2)

prog = TestProgram('./rosen_prog.py', desc='Rosenbrock Function')

# or, the equivalent using template strings

prog = TestProgram(exe='./rosen_prog.py --x=$x --y=$y',
  desc='Rosenbrock Function')

Example2:

# Using newdir and infiles. Will run each job in a new directory
# with a copy of all the infiles.

prog = TestProgram('PM2', newdir=True, desc='MPM Scaling',
  infiles=['pm2geometry', 'pm2input', 'pmgrid_geom.nc',
  'pmpart_geom.nc'])

Example3:

# Using newdir and paramsByFile
# In this case, all parameters to rosen_prog.py located in the same directory
# as this script will be passed in the file named input_params.txt
# located in a subdirectory of the control script's directory. Ie., for the
# example below, the file structure is the following (assuming this script
# is named rosen.py contained in a directory called Rosen)
# Rosen
#   |_ rosen.py
#   |_ rosen_prog.py
#   |_ Run 1
#       |__ input_params.txt
#   |_ Run 2
#       |__ input_params.txt
#      .
#      .
#      .
#
# input_params.txt contains 3 columns, separated by whitespace.
# The first column is the parameter name, the second is the parameter value,
# the third is the parameter description.
#
# Rosen_prog then reads the parameters from the file name passed to it in the
# --paramsFile argument. The contents of input_params.txt can be loaded using numpy's loadtxt
# with record-data type.

prog = TestProgram(exe='python ../rosen_prog.py --paramsFile=input_params.txt',
  newdir=True, paramsByFile=True, desc='Rosenbrock Function')

Example4:

# Instead of running an executable or python script directly, can call a python function
# instead. This results in much faster execution if the test program is a python scripty
# since the overhead of starting a new python interpreter is eliminated. Note this can
# only be used with InteractiveHostMP.
#
# The equivalent of example 3 is given below. Note that rosen_prog must have a function
# named 'run' with the signature
#           def run(args=None, jobinfo=None)
# The 'run' function must ALWAYS return the jobinfo argument on every possible exit path of
# the function.
# The argument 'args' is the same string as would be passed when using exe (see example1) and
# is given by func_args of the TestProgram constructor. 'args' can be directly parsed by
# argparse or optparse.

import rosen_prog
prog=TestProgram(func=rosen_prog.run, func_args='--paramsFile=input_params.txt',
  newdir=True, paramsByFile=True desc='Rosenbrock Function')