Pyclaw Utility Module

pyclaw.util

Pyclaw utility methods

class pyclaw.util.FrameCounter

Simple frame counter

Simple frame counter to keep track of current frame number. This can also be used to keep multiple runs frames separated by having multiple counters at once.

Initializes to 0

get_counter()

Get the current frame number

increment()

Increment the counter by one

reset_counter()

Reset the counter to 0

set_counter(new_frame_num)

Set the counter to new_frame_num

exception pyclaw.util.VerifyError

pyclaw.util.add_parent_doc(parent)

add parent documentation for a class

pyclaw.util.check_diff(expected, test, **kwargs)

Checks the difference between expected and test values, return None if ok

This function expects either the keyword argument ‘abstol’ or ‘reltol’.

pyclaw.util.compile_library(source_list, module_name, interface_functions=[], local_path='./', library_path='./', f2py_flags='', FC=None, FFLAGS=None, recompile=False, clean=False)

Compiles and wraps fortran source into a callable module in python.

This function uses f2py to create an interface from python to the fortran sources in source_list. The source_list can either be a list of names of source files in which case compile_library will search for the file in local_path and then in library_path. If a path is given, the file will be checked to see if it exists, if not it will look for the file in the above resolution order. If any source file is not found, an IOException is raised.

The list interface_functions allows the user to specify which fortran functions are actually available to python. The interface functions are assumed to be in the file with their name, i.e. claw1 is located in ‘claw1.f95’ or ‘claw1.f’.

The interface from fortran may be different than the original function call in fortran so the user should make sure to check the automatically created doc string for the fortran module for proper use.

Source files will not be recompiled if they have not been changed.

One set of options of note is for enabling OpenMP, it requires the usual fortran flags but the OpenMP library also must be compiled in, this is done with the flag -lgomp. The call to compile_library would then be:

compile_library(src,module_name,f2py_flags=’-lgomp’,FFLAGS=’-fopenmp’)

For complete optimization use:

FFLAGS=’-O3 -fopenmp -funroll-loops -finline-functions -fdefault-real-8’

Input

• source_list - (list of strings) List of source files, if these are just names of the source files, i.e. ‘bc1.f’ then they will be searched for in the default source resolution order, if an explicit path is given, i.e. ‘./bc1.f’, then the function will use that source if it can find it.

• module_name - (string) Name of the resulting module

• interface_functions - (list of strings) List of function names to provide access to, if empty, all functions are accessible to python. Defaults to [].

• local_path - (string) The base path for source resolution, defaults to ‘./’.

• library_path - (string) The library path for source resolution, defaults to ‘./’.

• f2py_flags - (string) f2py flags to be passed

• FC - (string) Override the environment variable FC and use it to compile, note that this does not replace the compiler that f2py uses, only the object file compilation (functions that do not have interfaces)

• FFLAGS - (string) Override the environment variable FFLAGS and pass them to the fortran compiler

• recompile - (bool) Force recompilation of the library, defaults to False

• clean - (bool) Force a clean build of all source files

pyclaw.util.construct_function_handle(path, function_name=None)

Constructs a function handle from the file at path.

This function will attempt to construct a function handle from the python file at path.

Input

• path - (string) Path to the file containing the function

• function_name - (string) Name of the function defined in the file that the handle will point to. Defaults to the same name as the file without the extension.

Output

• (func) Function handle to the constructed function, None if this has failed.

pyclaw.util.convert_fort_double_to_float(number)

Converts a fortran format double to a float

Converts a fortran format double to a python float.

number: is a string representation of the double. Number should be of the form “1.0d0”

pyclaw.util.gen_variants(application, verifier, kernel_languages=('Fortran', ), disable_petsc=False, **kwargs)

Generator of runnable variants of a test application given a verifier

Given an application, a script for verifying its output, and a list of kernel languages to try, generates all possible variants of the application to try by taking a product of the available kernel_languages and (petclaw/pyclaw). For many applications, this will generate 4 variants: the product of the two main kernel languages (‘Fortran’ and ‘Python’), against the the two parallel modes (petclaw and pyclaw).

For more information on how the verifier function should be implemented, see util.test_app for a description, and util.check_diff for an example.

All unrecognized keyword arguments are passed through to the application.

pyclaw.util.read_data_line(inputfile, num_entries=1, data_type=<class 'float'>)

Read data a single line from an input file

Reads one line from an input file and returns an array of values

inputfile: a file pointer to an open file object num_entries: number of entries that should be read, defaults to only 1 type: Type of the values to be read in, they all must be the same type

This function will return either a single value or an array of values depending on if num_entries > 1

pyclaw.util.run_app_from_main(application, setplot=None)

Runs an application from pyclaw/examples/, automatically parsing command line keyword arguments (key=value) as parameters to the application, with positional arguments being passed to PETSc (if it is enabled).

Perhaps we should take the PETSc approach of having a database of PyClaw options that can be queried for options on specific objects within the PyClaw runtime instead of front-loading everything through the application main…

pyclaw.util.run_serialized(fun)

Decorates a function to only run serially, even if called in parallel.

In a parallel communicator, the first process will run while the remaining processes block on a barrier. In a serial run, the function will be called directly.

This currently assumes the global communicator is PETSc.COMM_WORLD, but is easily generalized.

pyclaw.util.test_app(application, verifier, kwargs)

Test the output of a given application against its verifier method.

This function performs the following two function calls:

output = application(**kwargs)
check_values = verifier(output)

The verifier method should return None if the output is correct, otherwise it should return an indexed sequence of three items:

0 - expected value
1 - test value
2 - string describing the tolerance type (abs/rel) and value.

This information is used to present descriptive help if an error is detected. For an example verifier method, see util.check_diff