pymor.core package¶

Submodules¶

base module¶

This module provides base classes from which most classes in pyMOR inherit.

The purpose of these classes is to provide some common functionality for all objects in pyMOR. The most notable features provided by BasicObject are the following:

BasicObject sets class UberMeta as metaclass which itself inherits from abc.ABCMeta. Thus it is possible to define interface classes with abstract methods using the abstractmethod decorator. There are also decorators for abstract class methods, static methods, and properties.

Using metaclass magic, each class deriving from BasicObject comes with its own logger instance accessible through its logger attribute. The logger prefix is automatically set to the class name.

Logging can be disabled and re-enabled for each instance using the BasicObject.disable_logging and BasicObject.enable_logging methods.

BasicObject.uid provides a unique id for each instance. While id(obj) is only guaranteed to be unique among all living Python objects, BasicObject.uid will be (almost) unique among all pyMOR objects that have ever existed, including previous runs of the application. This is achieved by building the id from a uuid4 which is newly created for each pyMOR run and a counter which is increased for any object that requests an uid.

If not set by the user to another value, BasicObject.name is set to the name of the object’s class.

ImmutableObject derives from BasicObject and adds the following functionality:

Using more metaclass magic, each instance which derives from ImmutableObject is locked after its __init__ method has returned. Each attempt to change one of its attributes raises an exception. Private attributes (of the form _name) are exempted from this rule.
ImmutableObject.with_ can be used to create a copy of an instance with some changed attributes. E.g.
obj.with_(a=x, b=y)
creates a copy with the a and b attributes of obj set to x and y. with_ is implemented by creating a new instance, passing the arguments of with_ to __init__. The missing __init__ arguments are taken from instance attributes of the same name.

class pymor.core.base.BasicObject[source]¶

Bases: object

Base class for most classes in pyMOR.

Methods

BasicObject

disable_logging, enable_logging

Attributes

BasicObject

logger, logging_disabled, name, uid

logger¶: A per-class instance of logging.Logger with the class name as prefix.

logging_disabled¶: True if logging has been disabled.

name¶: The name of the instance. If not set by the user, the name is set to the class name.

uid¶: A unique id for each instance. The uid is obtained by using UID and is unique for all pyMOR objects ever created.

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

disable_logging(doit=True)[source]¶: Disable logging output for this instance.

enable_logging(doit=True)[source]¶: Enable logging output for this instance.

class pymor.core.base.ImmutableMeta(classname, bases, classdict)[source]¶

Bases: pymor.core.base.UberMeta

Metaclass for ImmutableObject.

Methods

`ABCMeta`	`register`, `__instancecheck__`, `__subclasscheck__`
`type`	`mro`, `__dir__`, `__prepare__`, `__sizeof__`, `__subclasses__`

static __new__(cls, classname, bases, classdict)[source]¶

I copy docstrings from base class methods to deriving classes.

Copying of docstrings is disabled when the PYMOR_WITH_SPHINX environment variable is set to 1.

class pymor.core.base.ImmutableObject(*args, **kwargs)[source]¶

Bases: pymor.core.base.BasicObject

Base class for immutable objects in pyMOR.

Instances of ImmutableObject are immutable in the sense that after execution of __init__, any modification of a non-private attribute will raise an exception.

Warning

For instances of ImmutableObject, the result of member function calls should be completely determined by the function’s arguments together with the object’s __init__ arguments and the current state of pyMOR’s global defaults.

While, in principle, you are allowed to modify private members after instance initialization, this should never affect the outcome of future method calls. In particular, if you update any internal state after initialization, you have to ensure that this state is not affected by possible changes of the global defaults.

Methods

`ImmutableObject`	`with_`, `__setattr__`
`BasicObject`	`disable_logging`, `enable_logging`

Attributes

BasicObject

logger, logging_disabled, name, uid

__setattr__(key, value)[source]¶: depending on _locked state I delegate the setattr call to object or raise an Exception

with_(new_type=None, **kwargs)[source]¶

Returns a copy with changed attributes.

A a new class instance is created with the given keyword arguments as arguments for __init__. Missing arguments are obtained form instance attributes with the same name.

Parameters

new_type: If not None, return an instance of this class (instead of type(self)).
**kwargs: Names of attributes to change with their new values. Each attribute name has to be an argument to __init__.

Returns

Copy of self with changed attributes.

class pymor.core.base.UID[source]¶

Bases: object

Provides unique, quickly computed ids by combining a session UUID4 with a counter.

Attributes

UID

counter, prefix, uid

class pymor.core.base.UberMeta(classname, bases, classdict)[source]¶

Bases: abc.ABCMeta

Methods

`UberMeta`	`__new__`
`ABCMeta`	`register`, `__instancecheck__`, `__subclasscheck__`
`type`	`mro`, `__dir__`, `__prepare__`, `__sizeof__`, `__subclasses__`

static __new__(cls, classname, bases, classdict)[source]¶

I copy docstrings from base class methods to deriving classes.

Copying of docstrings is disabled when the PYMOR_WITH_SPHINX environment variable is set to 1.

class pymor.core.base.classinstancemethod(cls_meth)[source]¶

Bases: object

Methods

classinstancemethod

instancemethod

cache module¶

This module provides the caching facilities of pyMOR.

Any class that wishes to provide cached method calls should derive from CacheableObject. Methods which are to be cached can then be marked using the cached decorator.

To ensure consistency, CacheableObject derives from ImmutableObject: The return value of a cached method call should only depend on its arguments as well as the immutable state of the class instance.

Making this assumption, the keys for cache lookup are created from the following data:

the instance’s cache_id in case of a persistent CacheRegion, else the instance’s uid,

the method’s __name__,

the method’s arguments.

Note that instances of ImmutableObject are allowed to have mutable private attributes. It is the implementors responsibility not to break things. (See this warning.)

Backends for storage of cached return values derive from CacheRegion. Currently two backends are provided for memory-based and disk-based caching (MemoryRegion and DiskRegion). The available regions are stored in the module level cache_regions dict. The user can add additional regions (e.g. multiple disk cache regions) as required. CacheableObject.cache_region specifies a key of the cache_regions dict to select a cache region which should be used by the instance. (Setting cache_region to None or 'none' disables caching.)

By default, a ‘memory’, a ‘disk’ and a ‘persistent’ cache region are configured. The paths and maximum sizes of the disk regions, as well as the maximum number of keys of the memory cache region can be configured via the pymor.core.cache.default_regions.disk_path, pymor.core.cache.default_regions.disk_max_size, pymor.core.cache.default_regions.persistent_path, pymor.core.cache.default_regions.persistent_max_size and pymor.core.cache.default_regions.memory_max_keys defaults.

There two ways to disable and enable caching in pyMOR:

Calling disable_caching (enable_caching), to disable (enable) caching globally.

Calling CacheableObject.disable_caching (CacheableObject.enable_caching) to disable (enable) caching for a given instance.

Caching of a method is only active if caching has been enabled both globally (enabled by default) and on instance level. For debugging purposes, it is moreover possible to set the environment variable PYMOR_CACHE_DISABLE=1 which overrides any call to enable_caching.

A cache region can be emptied using CacheRegion.clear. The function clear_caches clears each cache region registered in cache_regions.

class pymor.core.cache.CacheRegion[source]¶

Bases: object

Base class for all pyMOR cache regions.

Methods

CacheRegion

clear, get, set

Attributes

CacheRegion

persistent

persistent¶: If True, cache entries are kept between multiple program runs.

clear()[source]¶: Clear the entire cache region.

get(key)[source]¶

Return cache entry for given key.

Parameters

key: The key for the cache entry.

Returns

(True, entry): in case the key has been found in the cache region.
(False, None): in case the key is not present in the cache region.

set(key, value)[source]¶

Set cache entry for key to given value.

This method is usually called only once for any given key (with the exemption of issues due to concurrency).

class pymor.core.cache.CacheableObject(*args, **kwargs)[source]¶

Bases: pymor.core.base.ImmutableObject

Base class for anything that wants to use our built-in caching.

Methods

`CacheableObject`	`cached_method_call`, `disable_caching`, `enable_caching`
`ImmutableObject`	`with_`, `__setattr__`
`BasicObject`	`disable_logging`, `enable_logging`

Attributes

`CacheableObject`	`cache_id`, `cache_region`
`BasicObject`	`logger`, `logging_disabled`, `name`, `uid`

cache_region¶: Name of the CacheRegion to use. Must correspond to a key in the cache_regions dict. If None or 'none', caching is disabled.

cache_id¶: Identifier for the object instance on which a cached method is called.

cached_method_call(method, *args, **kwargs)[source]¶

Call a given method and cache the return value.

This method can be used as an alternative to the cached decorator.

Parameters

method: The method that is to be called. This has to be a method of self.
args: Positional arguments for method.
kwargs: Keyword arguments for method

Returns

The (possibly cached) return value of method(*args, **kwargs).

disable_caching()[source]¶: Disable caching for this instance.

enable_caching(region, cache_id=None)[source]¶

Enable caching for this instance.

Warning

Note that using with_ will reset cache_region and cache_id to their class defaults.

Parameters

region: Name of the CacheRegion to use. Must correspond to a key in the cache_regions dict. If None or 'none', caching is disabled.
cache_id: Identifier for the object instance on which a cached method is called. Must be specified when region is persistent. When region is not persistent and no cache_id is given, the object’s uid is used instead.

class pymor.core.cache.DiskRegion(path, max_size, persistent)[source]¶

Bases: pymor.core.cache.CacheRegion

Methods

DiskRegion

clear, get, set

Attributes

CacheRegion

persistent

clear()[source]¶: Clear the entire cache region.

get(key)[source]¶

Return cache entry for given key.

Parameters

key: The key for the cache entry.

Returns

(True, entry): in case the key has been found in the cache region.
(False, None): in case the key is not present in the cache region.

set(key, value)[source]¶

Set cache entry for key to given value.

This method is usually called only once for any given key (with the exemption of issues due to concurrency).

class pymor.core.cache.MemoryRegion(max_keys)[source]¶

Bases: pymor.core.cache.CacheRegion

Methods

MemoryRegion

clear, get, set

Attributes

`MemoryRegion`	`NO_VALUE`
`CacheRegion`	`persistent`

clear()[source]¶: Clear the entire cache region.

get(key)[source]¶

Return cache entry for given key.

Parameters

key: The key for the cache entry.

Returns

(True, entry): in case the key has been found in the cache region.
(False, None): in case the key is not present in the cache region.

set(key, value)[source]¶

Set cache entry for key to given value.

This method is usually called only once for any given key (with the exemption of issues due to concurrency).

pymor.core.cache.build_cache_key(obj)[source]¶

pymor.core.cache.cached(function)[source]¶: Decorator to make a method of CacheableObject actually cached.

pymor.core.cache.cleanup_non_persistent_regions()[source]¶

pymor.core.cache.clear_caches()[source]¶: Clear all cache regions.

pymor.core.cache.default_regions(disk_path='/tmp/pymor.cache.root', disk_max_size=1073741824, persistent_path='/tmp/pymor.persistent.cache.root', persistent_max_size=1073741824, memory_max_keys=1000)[source]¶

pymor.core.cache.disable_caching()[source]¶: Globally disable caching.

pymor.core.cache.enable_caching()[source]¶: Globally enable caching.

config module¶

class pymor.core.config.Config[source]¶

Bases: object

Attributes

Config

version

__dir__(old=False)[source]¶: Default dir() implementation.

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

pymor.core.config.is_jupyter()[source]¶: This Method is not foolprof and might fail with any given jupyter release :return: True if we believe to be running in a Jupyter Notebook or Lab

pymor.core.config.is_macos_platform()[source]¶

pymor.core.config.is_nbconvert()[source]¶: In some visualization cases we need to be able to detect if a notebook is executed with nbconvert to disable async loading

pymor.core.config.is_windows_platform()[source]¶

defaults module¶

This module contains pyMOR’s facilities for handling default values.

A default value in pyMOR is always the default value of some function argument. To mark the value of an optional function argument as a user-modifiable default value use the defaults decorator. As an additional feature, if None is passed for such an argument, its default value is used instead of None. This is useful for writing code of the following form:

@default('option')
def algorithm(U, option=42):
    ...

def method_called_by_user(V, option_for_algorithm=None):
    ...
    algorithm(U, option=option_for_algorithm)
    ...

If the user does not provide option_for_algorithm to method_called_by_user, the default 42 is automatically chosen without the implementor of method_called_by_user having to care about this.

The user interface for handling default values in pyMOR is provided by set_defaults, load_defaults_from_file, write_defaults_to_file and print_defaults.

If pyMOR is imported, it will automatically search for a configuration file named pymor_defaults.py in the current working directory. If found, the file is loaded via load_defaults_from_file. However, as a security precaution, the file will only be loaded if it is owned by the user running the Python interpreter (load_defaults_from_file uses exec to load the configuration). As an alternative, the environment variable PYMOR_DEFAULTS can be used to specify the path of a configuration file. If empty or set to NONE, no configuration file will be loaded whatsoever.

Warning

Note that changing defaults may affect the result of a (cached) function call. pyMOR will emit a warning, when a result is retrieved from the cache that has been computed using an earlier set of defaults (see defaults_changes).

class pymor.core.defaults.DefaultContainer[source]¶

Bases: object

Internal singleton class holding all default values defined in pyMOR.

Not to be used directly.

Methods

DefaultContainer

get, import_all, keys, update

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

pymor.core.defaults.defaults(*args)[source]¶

Function decorator for marking function arguments as user-configurable defaults.

If a function decorated with defaults is called, the values of the marked default parameters are set to the values defined via load_defaults_from_file or set_defaults in case no value has been provided by the caller of the function. Moreover, if None is passed as a value for a default argument, the argument is set to its default value, as well. If no value has been specified using set_defaults or load_defaults_from_file, the default value provided in the function signature is used.

If the argument arg of function f in sub-module m of package p is marked as a default value, its value will be changeable by the aforementioned methods under the path p.m.f.arg.

Note that the defaults decorator can also be used in user code.

Parameters

args: List of strings containing the names of the arguments of the decorated function to mark as pyMOR defaults. Each of these arguments has to be a keyword argument (with a default value).

pymor.core.defaults.defaults_changes()[source]¶

Returns the number of changes made to to pyMOR’s global defaults.

This methods returns the number of changes made to the state of pyMOR’s global defaults via set_defaults or load_defaults_from_file since the start of program execution.

Since changing defaults may affect the result of a (cached) function call, this value is used to warn when a result is retrieved from the cache that has been computed using an earlier set of defaults.

Warning

Note that when using parallelization, workers might set different defaults at the same time, resulting in equal change counts but different states of defaults at each worker.

pymor.core.defaults.load_defaults_from_file(filename='./pymor_defaults.py')[source]¶

Loads default values defined in configuration file.

Suitable configuration files can be created via write_defaults_to_file. The file is loaded via Python’s exec function, so be very careful with configuration files you have not created your own. You have been warned!

Parameters

filename: Path of the configuration file.

pymor.core.defaults.print_defaults(import_all=True, shorten_paths=2)[source]¶

Print all default values set in pyMOR.

Parameters

import_all: While print_defaults will always print all defaults defined in loaded configuration files or set via set_defaults, default values set in the function signature can only be printed after the modules containing these functions have been imported. If import_all is set to True, print_defaults will therefore first import all of pyMOR’s modules, to provide a complete lists of defaults.
shorten_paths: Shorten the paths of all default values by shorten_paths components. The last two path components will always be printed.

pymor.core.defaults.set_defaults(defaults)[source]¶

Set default values.

This method sets the default value of function arguments marked via the defaults decorator, overriding default values specified in the function signature or set earlier via load_defaults_from_file or previous set_defaults calls.

Parameters

defaults: Dictionary of default values. Keys are the full paths of the default values (see defaults).

pymor.core.defaults.write_defaults_to_file(filename='./pymor_defaults.py', packages='pymor')[source]¶

Write the currently set default values to a configuration file.

The resulting file is an ordinary Python script and can be modified by the user at will. It can be loaded in a later session using load_defaults_from_file.

Parameters

filename: Name of the file to write to.
packages: List of package names. To discover all default values that have been defined using the defaults decorator, write_defaults_to_file will recursively import all sub-modules of the named packages before creating the configuration file.

exceptions module¶

class pymor.core.exceptions.AccuracyError[source]¶

Bases: Exception

Is raised if the result of a computation is inaccurate

Methods

`Exception`	`__new__`
`BaseException`	`with_traceback`

Attributes

BaseException

args

class pymor.core.exceptions.CacheKeyGenerationError[source]¶

Bases: Exception

Is raised when cache key generation fails due to unspported arguments.

Methods

`Exception`	`__new__`
`BaseException`	`with_traceback`

Attributes

BaseException

args

class pymor.core.exceptions.ConstError[source]¶

Bases: Exception

I get thrown when you try to add a new member to a locked class instance

Methods

`Exception`	`__new__`
`BaseException`	`with_traceback`

Attributes

BaseException

args

class pymor.core.exceptions.ExtensionError[source]¶

Bases: Exception

Is raised if a (basis) extension algorithm fails.

This will mostly happen during a basis extension when the new snapshot is already in the span of the basis.

Methods

`Exception`	`__new__`
`BaseException`	`with_traceback`

Attributes

BaseException

args

class pymor.core.exceptions.GmshMissing[source]¶

Bases: Exception

Is raised when a Gmsh is not found.

Methods

`Exception`	`__new__`
`BaseException`	`with_traceback`

Attributes

BaseException

args

class pymor.core.exceptions.ImageCollectionError(op)[source]¶

Bases: Exception

Is raised when a pymor.algorithms.image.estimate_image fails for given operator.

Methods

`Exception`	`__new__`
`BaseException`	`with_traceback`

Attributes

BaseException

args

class pymor.core.exceptions.InversionError[source]¶

Bases: Exception

Is raised if an operator inversion algorithm fails.

Methods

`Exception`	`__new__`
`BaseException`	`with_traceback`

Attributes

BaseException

args

class pymor.core.exceptions.LinAlgError[source]¶

Bases: Exception

Is raised if a linear algebra operation fails.

Methods

`Exception`	`__new__`
`BaseException`	`with_traceback`

Attributes

BaseException

args

class pymor.core.exceptions.MeshioMissing[source]¶

Bases: Exception

Is raised when meshio is not available.

Methods

`Exception`	`__new__`
`BaseException`	`with_traceback`

Attributes

BaseException

args

class pymor.core.exceptions.NeuralNetworkTrainingFailed[source]¶

Bases: Exception

Is raised when training of a neural network fails.

Methods

`Exception`	`__new__`
`BaseException`	`with_traceback`

Attributes

BaseException

args

class pymor.core.exceptions.NewtonError[source]¶

Bases: Exception

Is raised if the Newton algorithm fails to converge.

Methods

`Exception`	`__new__`
`BaseException`	`with_traceback`

Attributes

BaseException

args

class pymor.core.exceptions.NoMatchingRuleError(obj)[source]¶

Bases: NotImplementedError

Methods

`NotImplementedError`	`__new__`
`BaseException`	`with_traceback`

Attributes

BaseException

args

class pymor.core.exceptions.QtMissing(msg=None)[source]¶

Bases: ImportError

Raise me where having importable Qt bindings is non-optional

Methods

`Exception`	`__new__`
`BaseException`	`with_traceback`

Attributes

`ImportError`	`msg`, `name`, `path`
`BaseException`	`args`

class pymor.core.exceptions.RuleNotMatchingError[source]¶

Bases: NotImplementedError

Methods

`NotImplementedError`	`__new__`
`BaseException`	`with_traceback`

Attributes

BaseException

args

class pymor.core.exceptions.TorchMissing(msg=None)[source]¶

Bases: ImportError

Raise me where having importable torch version is non-optional

Methods

`Exception`	`__new__`
`BaseException`	`with_traceback`

Attributes

`ImportError`	`msg`, `name`, `path`
`BaseException`	`args`

logger module¶

This module contains pyMOR’s logging facilities.

pyMOR’s logging facilities are based on the logging module of the Python standard library. To obtain a new logger object use getLogger. Logging can be configured via the set_log_format and set_log_levels methods.

class pymor.core.logger.ColoredFormatter[source]¶

Bases: logging.Formatter

A logging.Formatter that inserts tty control characters to color loglevel keyword output. Coloring can be disabled by setting the PYMOR_COLORS_DISABLE environment variable to 1.

Methods

`ColoredFormatter`	`format`, `format_html`
`Formatter`	`converter`, `formatException`, `formatMessage`, `formatStack`, `formatTime`, `usesTime`

Attributes

Formatter

default_msec_format, default_time_format

format(record)[source]¶

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

class pymor.core.logger.DummyLogger[source]¶

Bases: object

Methods

DummyLogger

block, critical, debug, error, exception, getChild, getEffectiveLevel, info, info2, info3, isEnabledFor, log, nop, warn, warning

Attributes

DummyLogger

propagate

class pymor.core.logger.LogIndenter(logger, doit)[source]¶: Bases: object

pymor.core.logger.default_handler(filename='')[source]¶

pymor.core.logger.getLogger(module, level=None, filename='')[source]¶

Get the logger of the respective module for pyMOR’s logging facility.

Parameters

module: Name of the module.
level: If set, logger.setLevel(level) is called (see setLevel).
filename: If not empty, path of an existing file where everything logged will be written to.

Defaults

filename (see pymor.core.defaults)

pymor.core.logger.log_levels(level_mapping)[source]¶

Change levels for given loggers on entry and reset to before state on exit.

Parameters

level_mapping: a dict of logger name -> level name

pymor.core.logger.set_log_format(max_hierarchy_level=1, indent_blocks=True, block_timings=False)[source]¶

Set log levels for pyMOR’s logging facility.

Parameters

max_hierarchy_level: The number of components of the loggers name which are printed. (The first component is always stripped, the last component always preserved.)
indent_blocks: If True, indent log messages inside a code block started with with logger.block(...).
block_timings: If True, measure the duration of a code block started with with logger.block(...).

Defaults

max_hierarchy_level, indent_blocks, block_timings (see pymor.core.defaults)

pymor.core.logger.set_log_levels(levels=None)[source]¶

Set log levels for pyMOR’s logging facility.

Parameters

levels: Dict of log levels. Keys are names of loggers (see logging.getLogger), values are the log levels to set for the loggers of the given names (see setLevel).

Defaults

levels (see pymor.core.defaults)

pickle module¶

This module contains methods for object serialization.

Instead of importing serialization functions from Python’s pickle module directly, you should use the dump, dumps, load, loads functions defined here. In particular, these methods will use dumps_function to serialize function objects which cannot be pickled by Python’s standard methods. Note, however, pickling such methods should be avoided since the implementation of dumps_function uses non-portable implementation details of CPython to achieve its goals.

class pymor.core.pickle.Module(mod)[source]¶: Bases: object

pymor.core.pickle._global_names(code_object)[source]¶: Return all names in code_object.co_names which are used in a LOAD_GLOBAL statement.

pymor.core.pickle.dump(obj, file, protocol=None)[source]¶

pymor.core.pickle.dumps(obj, protocol=None)[source]¶

pymor.core.pickle.dumps_function(function)[source]¶

Tries hard to pickle a function object:

The function’s code object is serialized using the marshal module.

For all global names used in the function’s code object the corresponding object in the function’s global namespace is pickled. In case this object is a module, the modules __package__ name is pickled.

All default arguments are pickled.

All objects in the function’s closure are pickled.

Note that also this is heavily implementation specific and will probably only work with CPython. If possible, avoid using this method.

pymor.core.pickle.load(file)[source]¶

pymor.core.pickle.loads(str)[source]¶

pymor.core.pickle.loads_function(s)[source]¶: Restores a function serialized with dumps_function.