pymor.tools package¶

pymor.core.tools collects modules used throughout pyMOR that generally do not depend on any of pyMOR’s abstraction objects.

Submodules¶

context module¶

class pymor.tools.context.NoContext[source]¶: Bases: object

counter module¶

class pymor.tools.counter.Counter(start=0)[source]¶

Bases: object

Methods

Counter

inc

deprecated module¶

class pymor.tools.deprecated.Deprecated(alt='no alternative given')[source]¶

Bases: object

This is a decorator which can be used to mark functions as deprecated. It will result in a warning being emitted when the function is used.

Methods

Deprecated

__get__

__call__(func)[source]¶: Call self as a function.

__get__(obj, ownerClass=None)[source]¶: Return a wrapper that binds self as a method of obj (!)

floatcmp module¶

pymor.tools.floatcmp.almost_less(x, y, rtol=None, atol=None)[source]¶

pymor.tools.floatcmp.bounded(lower, upper, x, rtol=None, atol=None)[source]¶

Check if x is strictly in bounds (lower, upper) or float_compares equal to lower or upper

Parameters

lower: Lower bound
upper: Upper bound
x: value to check
rtol: relative tolerance for float_cmp
atol: absolute tolerance for float_cmp

pymor.tools.floatcmp.compare_with_tolerance(x, y, comparison_op, rtol=1e-14, atol=1e-14)[source]¶

‘One-sided’ Comparison x and y component-wise with given comparison op.

For scalars we define almost equality as

compare_with_tolerance(x,y) <=> op(x - y, atol + y*rtol)

Parameters

x, y: NumPy arrays to be compared. Have to be broadcastable to the same shape.
comparison_op: binary operator object, see Operator module.
rtol: The relative tolerance.
atol: The absolute tolerance.

Defaults

rtol, atol (see pymor.core.defaults)

pymor.tools.floatcmp.float_cmp(x, y, rtol=1e-14, atol=1e-14)[source]¶

Compare x and y component-wise for almost equality.

For scalars we define almost equality as

float_cmp(x,y) <=> |x - y| <= atol + |y|*rtol

Note

Numpy’s allclose method uses the same definition but treats arrays containing infinities as close if the infinities are at the same places and all other entries are close. In our definition, arrays containing infinities can never be close which seems more appropriate in most cases.

Parameters

x, y: NumPy arrays to be compared. Have to be broadcastable to the same shape.
rtol: The relative tolerance.
atol: The absolute tolerance.

Defaults

rtol, atol (see pymor.core.defaults)

pymor.tools.floatcmp.float_cmp_all(x, y, rtol=None, atol=None)[source]¶

Compare x and y for almost equality.

Returns True if all components of x are almost equal to the corresponding components of y.

See float_cmp.

formatrepr module¶

pymor.tools.formatrepr.format_repr(obj, max_width=120, verbosity=1)[source]¶

pymor.tools.formatrepr.indent_value(val, indent)[source]¶

pymor.tools.formatrepr.register_format_handler(cls, handler)[source]¶

frozendict module¶

class pymor.tools.frozendict.FrozenDict(*args, **kwargs)[source]¶

Bases: dict

An immutable dictionary.

Methods

dict

copy, fromkeys, get, items, keys, values, __contains__, __getitem__, __sizeof__

Attributes

FrozenDict

clear, pop, popitem, setdefault, update

static __new__(cls, *args, **kwargs)[source]¶: Create and return a new object. See help(type) for accurate signature.

__reduce__()[source]¶: Helper for pickle.

__repr__()[source]¶: Return repr(self).

class pymor.tools.frozendict.SortedFrozenDict(*args, **kwargs)[source]¶

Bases: pymor.tools.frozendict.FrozenDict

A sorted immutable dictionary.

Methods

dict

copy, fromkeys, get, items, keys, values, __contains__, __getitem__, __sizeof__

Attributes

FrozenDict

clear, pop, popitem, setdefault, update

static __new__(cls, *args, **kwargs)[source]¶: Create and return a new object. See help(type) for accurate signature.

__repr__()[source]¶: Return repr(self).

io module¶

pymor.tools.io.SafeTemporaryFileName(name=None, parent_dir=None)[source]¶

Cross Platform safe equivalent of re-opening a NamedTemporaryFile Creates an automatically cleaned up temporary directory with a single file therein.

name: filename component, defaults to ‘temp_file’ dir: the parent dir of the new tmp dir. defaults to tempfile.gettempdir()

pymor.tools.io.load_matrix(path, key=None)[source]¶

mpi module¶

This module provides helper methods to use pyMOR in parallel with MPI.

Executing this module will run event_loop on all MPI ranks except for rank 0 where either a given script is executed:

mpirun -n 16 python -m pymor.tools.mpi /path/to/script

or an interactive session is started:

mpirun -n 16 python -m pymor.tools.mpi

When IPython is available, an IPython kernel is started which the user can connect to by calling:

ipython console --existing file_name_printed_by_ipython.json

(Starting the IPython console directly will not work properly with most MPI implementations.) When IPython is not available, the builtin Python REPL is started.

When event_loop is running on the MPI ranks, call can be used on rank 0 to execute the same Python function (given as first argument) simultaneously on all MPI ranks (including rank 0). Calling quit will exit event_loop on all MPI ranks.

Additionally, this module provides several helper methods which are intended to be used in conjunction with call: mpi_info will print a summary of all active MPI ranks, run_code will execute the given code string on all MPI ranks, import_module imports the module with the given path.

A simple object management is implemented with the manage_object, get_object and remove_object methods. It is the user’s responsibility to ensure that calls to manage_object are executed in the same order on all MPI ranks to ensure that the returned ObjectId refers to the same distributed object on all ranks. The functions function_call, function_call_manage, method_call, method_call_manage map instances ObjectId transparently to distributed objects. function_call_manage and method_call_manage will call manage_object on the return value and return the corresponding ObjectId. The functions method_call and method_call_manage are given an ObjectId and a string as first and second argument and execute the method named by the second argument on the object referred to by the first argument.

class pymor.tools.mpi.ObjectId[source]¶

Bases: int

A handle to an MPI distributed object.

Methods

int

bit_length, conjugate, from_bytes, to_bytes, __ceil__, __floor__, __new__, __round__, __sizeof__, __trunc__

Attributes

int

denominator, imag, numerator, real

pymor.tools.mpi.call(method, *args, **kwargs)[source]¶

Execute method on all MPI ranks.

Assuming event_loop is running on all MPI ranks (except rank 0), this will execute method on all ranks (including rank 0) with positional arguments args and keyword arguments kwargs.

Parameters

method: The function to execute on all ranks (must be picklable).
args: The positional arguments for method.
kwargs: The keyword arguments for method.

Returns

The return value of method on rank 0.

pymor.tools.mpi.event_loop()[source]¶

Launches an MPI-based event loop.

Events can be sent by either calling call on rank 0 to execute an arbitrary method on all ranks or by calling quit to exit the loop.

pymor.tools.mpi.event_loop_settings(auto_launch=True)[source]¶

Settings for pyMOR’s MPI event loop.

Parameters

auto_launch: If True, automatically execute event_loop on all MPI ranks (except 0) when pyMOR is imported.

Defaults

auto_launch (see pymor.core.defaults)

pymor.tools.mpi.function_call(f, *args, **kwargs)[source]¶

Execute the function f with given arguments.

Intended to be used in conjunction with call. Arguments of type ObjectId are transparently mapped to the object they refer to.

pymor.tools.mpi.function_call_manage(f, *args, **kwargs)[source]¶

Execute the function f and manage the return value.

Intended to be used in conjunction with call. The return value of f is managed by calling manage_object and the corresponding ObjectId is returned. Arguments of type ObjectId are transparently mapped to the object they refer to.

pymor.tools.mpi.get_object(obj_id)[source]¶: Return the object referred to by obj_id.

pymor.tools.mpi.import_module(path)[source]¶

Import the module named by path.

Intended to be used in conjunction with call.

pymor.tools.mpi.manage_object(obj)[source]¶: Keep track of obj and return an ObjectId handle.

pymor.tools.mpi.method_call(obj_id, name_, *args, **kwargs)[source]¶

Execute a method with given arguments.

Intended to be used in conjunction with call. Arguments of type ObjectId are transparently mapped to the object they refer to.

Parameters

obj_id: The ObjectId of the object on which to call the method.
name_: Name of the method to call.
args: Positional arguments for the method.
kwargs: Keyword arguments for the method.

pymor.tools.mpi.method_call_manage(obj_id, name_, *args, **kwargs)[source]¶

Execute a method with given arguments and manage the return value.

Intended to be used in conjunction with call. The return value of the called method is managed by calling manage_object and the corresponding ObjectId is returned. Arguments of type ObjectId are transparently mapped to the object they refer to.

Parameters

obj_id: The ObjectId of the object on which to call the method.
name_: Name of the method to call.
args: Positional arguments for the method.
kwargs: Keyword arguments for the method.

pymor.tools.mpi.mpi_info()[source]¶

Print some information on the MPI setup.

Intended to be used in conjunction with call.

pymor.tools.mpi.quit()[source]¶

Exit the event loop on all MPI ranks.

This will cause event_loop to terminate on all MPI ranks.

pymor.tools.mpi.remove_object(obj_id)[source]¶: Remove the object referred to by obj_id from the registry.

pymor.tools.mpi.run_code(code)[source]¶

Execute the code string code.

Intended to be used in conjunction with call.

pprint module¶

pymor.tools.pprint.format_array(array, compact_print=False)[source]¶

Creates a formatted string representation of a NumPy array.

Parameters

array: the NumPy array to be formatted
compact_print: If True, return a shorter version of string representation.

Returns

The string representation.

Defaults

compact_print (see pymor.core.defaults)

random module¶

pymor.tools.random.default_random_state(seed=42)[source]¶

Returns the default NumPy RandomState.

Parameters

seed: Seed to use for initializing the random state.

Returns

The default RandomState object.

Defaults

seed (see pymor.core.defaults)

pymor.tools.random.get_random_state(random_state=None, seed=None)[source]¶

Returns a NumPy RandomState.

Parameters

random_state: If specified, this state is returned.
seed: If specified, the seed to initialize a new random state.

Returns

Either the provided, a newly created or the default RandomState object.

table module¶

pymor.tools.table.format_table(rows, width='AUTO', title=None)[source]¶

timing module¶

class pymor.tools.timing.Timer(section, log=<Logger pymor.tools.timing (INFO)>)[source]¶

Bases: object

You can use me as a context manager, plain instance or decorator to time execution of a code scope:

with Timer() as timer:
    do_some_stuff()
    do more stuff()
#outputs time in (s)

### OR ###

@timing.Timer('name', logging.debug)
def function(*args):
    do_stuff

function(1)
#outputs time in (s) to logging.debug

### OR ###

timer = timing.Timer()
timer.start()
do_stuff()
timer.stop()
print(timer.dt)

Methods

Timer

start, stop

__call__(func)[source]¶: Call self as a function.

pymor.tools.timing.busywait(amount)[source]¶