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.

__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]

formatsrc module


pymor.tools.formatsrc.format_source(obj)[source]

pymor.tools.formatsrc.print_source(obj)[source]

pymor.tools.formatsrc.source_repr(obj)[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]

typer module


pymor.tools.typer.Choices(choices)[source]

Multipe-choice options for typer.

This is a convenicence function that creates string Enums to be used as the type of command-line arguments that can take a fixed set of values. For example, the command:

@app.command()
def main(arg: Choices('value1 value2')):
    pass

takes one argument that may either have the value value1 or the value value2.