pymor.core package

Submodules

backports module

This module contains pure python backports of library features from python >= 3 to 2.7


class pymor.core.backports.abstractclassmethod(callable_method)[source]

Bases: classmethod

A decorator indicating abstract classmethods.

Similar to abstractmethod.

Usage:

class C(metaclass=ABCMeta):
    @abstractclassmethod
    def my_abstract_classmethod(cls, ...):
        ...

‘abstractclassmethod’ is deprecated. Use ‘classmethod’ with ‘abstractmethod’ instead.

Methods

classmethod __new__

class pymor.core.backports.abstractstaticmethod(callable_method)[source]

Bases: staticmethod

A decorator indicating abstract staticmethods.

Similar to abstractmethod.

Usage:

class C(metaclass=ABCMeta):
    @abstractstaticmethod
    def my_abstract_staticmethod(...):
        ...

‘abstractstaticmethod’ is deprecated. Use ‘staticmethod’ with ‘abstractmethod’ instead.

Methods

staticmethod __new__

cache module

This module provides the caching facilities of pyMOR.

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

To ensure consistency, CacheableInterface derives from ImmutableInterface: 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:

  1. the instance’s state id in case of a persistent CacheRegion, else the instance’s uid,
  2. the method’s __name__,
  3. the state id of the arguments,
  4. the state id of pyMOR’s global defaults.

Note that instances of ImmutableInterface 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 SQLiteRegion). 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. CacheableInterface.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:

  1. Calling disable_caching (enable_caching), to disable (enable) caching globally.
  2. Calling CacheableInterface.disable_caching (CacheableInterface.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.CacheableInterface[source]

Bases: pymor.core.interfaces.ImmutableInterface

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

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.

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)[source]

Enable caching for this instance.

When setting the object’s cache region to a persistent CacheRegion, the object’s state id will be computed.

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.

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

Bases: pymor.core.cache.CacheRegion

Attributes

MemoryRegion NO_VALUE
CacheRegion persistent

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

Bases: pymor.core.cache.CacheRegion

Methods

SQLiteRegion clear, get, housekeeping, set

Attributes

CacheRegion persistent

pymor.core.cache.cached(function)[source]

Decorator to make a method of CacheableInterface actually cached.


pymor.core.cache.cleanup_non_persisten_regions()[source]

pymor.core.cache.clear_caches()[source]

Clear all cache regions.


pymor.core.cache.default_regions(disk_path='/tmp/pymor.cache.docs', disk_max_size=1073741824, persistent_path='/tmp/pymor.persistent.cache.docs', 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

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

The state of pyMOR’s global defaults enters the calculation of each state id. Thus, if you first instantiate an immutable object and then change the defaults, the resulting object will have a different state id than if you first change the defaults. (This is necessary as the object can save internal state upon initialization, which depends on the state of the global defaults.) As a consequence, the key generated for caching will depend on the time the defaults have been changed. While no wrong results will be produced, changing defaults at different times will cause unnecessary cache misses and will pollute the cache with duplicate entries.

An exemption from this rule are defaults which are listed in the sid_ignore argument of the defaults decorator. Such defaults will not enter the state id calculation. This allows the user to change defaults related to input/output, e.g. logging, without breaking caching. Before marking defaults as ignored in your own code, however, make sure to double check that these defaults will not affect the result of any mathematical algorithm.


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

Attributes

DefaultContainer sid

pymor.core.defaults.defaults(*args, sid_ignore=(), qualname=None)[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).
sid_ignore
List of strings naming the defaults in args which should not enter state id calculation (because they do not affect the outcome of any computation). Such defaults will typically be IO related. Use with extreme caution!
qualname
If a method of a class is decorated, the fully qualified name of the method has to be provided, as this name cannot be derived at decoration time in Python 2.

pymor.core.defaults.defaults_sid()[source]

Return a state id for pyMOR’s global defaults.

This method is used for the calculation of state ids of immutable objects and for cache key generation.


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!

Note that defaults should generally only be changed/loaded before state ids have been calculated. See this warning for details.

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.

Note that defaults should generally only be changed/loaded before state ids have been calculated. See this warning for details.

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.

dynamic module

This is an empty module usable as a placeholder(-dict) for dynamically created types and such

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.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.GmshError[source]

Bases: Exception

Is raised when a Gmsh related error occurs.

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.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.SIDGenerationError[source]

Bases: Exception

Is raised when generate_sid fails.

Methods

Exception __new__
BaseException with_traceback

Attributes

BaseException args

interfaces 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 BasicInterface are the following:

  1. BasicInterface 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.
  2. Using metaclass magic, each class deriving from BasicInterface comes with its own logger instance accessible through its logger attribute. The logger prefix is automatically set to the class name.
  3. Logging can be disabled and re-enabled for each instance using the BasicInterface.disable_logging and BasicInterface.enable_logging methods.
  4. BasicInterface.uid provides a unique id for each instance. While id(obj) is only guaranteed to be unique among all living Python objects, BasicInterface.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.
  5. If not set by the user to another value, BasicInterface.name is set to the name of the object’s class.

ImmutableInterface derives from BasicInterface and adds the following functionality:

  1. Using more metaclass magic, each instance which derives from ImmutableInterface 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.

  2. A unique state id for the instance can be calculated by calling generate_sid and is then stored as the object’s sid attribute. The state id is obtained by deterministically serializing the object’s state and then computing a checksum of the resulting byte stream.

  3. ImmutableInterface.sid_ignore can be set to a set of attribute names which should be excluded from state id calculation.

  4. ImmutableInterface.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. (Note that in general a and b do not necessarily have to correspond to class attributes of obj; it is up to the implementor to interpret the provided arguments.) ImmutableInterface.with_arguments holds the set of allowed arguments.

    ImmutableInterface provides a default implementation of with_ which works 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.interfaces.BasicInterface[source]

Bases: object

Base class for most classes in pyMOR.

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.

disable_logging(doit=True)[source]

Disable logging output for this instance.

enable_logging(doit=True)[source]

Enable logging output for this instance.

classmethod has_interface_name()[source]

True if the class name ends with Interface. Used for introspection.

classmethod implementor_names(descend=False)[source]

For convenience I return a list of my implementor names instead of class objects

classmethod implementors(descend=False)[source]

I return a, potentially empty, list of my subclass-objects. If descend is True, I traverse my entire subclass hierarchy and return a flattened list.


class pymor.core.interfaces.ImmutableInterface[source]

Bases: pymor.core.interfaces.BasicInterface

Base class for immutable objects in pyMOR.

Instances of ImmutableInterface 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 ImmutableInterface, the result of member function calls should be completely determined by the function’s arguments together with the object’s state id 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.

Also note that mutable private attributes will cause false cache misses when these attributes enter state id calculation. If your implementation uses such attributes, you should therefore add their names to the sid_ignore set.

add_with_arguments

Set of additional arguments for with_. (See with_arguments.)

sid

The objects state id. Only available after generate_sid has been called.

sid_ignore

Set of attributes not to include in state id calculation.

with_arguments

Set of allowed keyword arguments for with_. This is the union of the argument names of __init__ and the names specified via add_with_arguments.

__setattr__(key, value)[source]

depending on _locked state I delegate the setattr call to object or raise an Exception

generate_sid(debug=False)[source]

Generate a unique state id for the given object.

The generated state id is stored in the object’s sid attribute.

Parameters

debug
If True, produce some debugging output.

Returns

The generated state id.

with_(**kwargs)[source]

Returns a copy with changed attributes.

The default implementation is to create a new class instance with the given keyword arguments as arguments for __init__. Missing arguments are obtained form instance attributes with the same name.

Parameters

**kwargs
Names of attributes to change with their new values. Each attribute name has to be contained in with_arguments.

Returns

Copy of self with changed attributes.


class pymor.core.interfaces.ImmutableMeta(name, bases, namespace)[source]

Bases: pymor.core.interfaces.UberMeta

Metaclass for ImmutableInterface.

Methods

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

class pymor.core.interfaces.UID[source]

Bases: object

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

Attributes

UID counter, prefix, uid

class pymor.core.interfaces.UberMeta(name, bases, namespace)[source]

Bases: abc.ABCMeta

Methods

UberMeta __new__
ABCMeta register, __instancecheck__, __subclasscheck__
type mro, __dir__, __prepare__, __sizeof__, __subclasses__
static __new__(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.interfaces.classinstancemethod(cls_meth)[source]

Bases: object

Methods

classinstancemethod instancemethod

pymor.core.interfaces.generate_sid(obj, debug=False)[source]

Generate a unique state id for the current state of the given object.

Parameters

obj
The object for which to compute the state sid.
debug
If True, produce some debug output.

Returns

The generated state id.

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
Formatter converter, formatException, formatMessage, formatStack, formatTime, usesTime

Attributes

Formatter default_msec_format, default_time_format

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.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.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:

  1. The function’s code object is serialized using the marshal module.
  2. 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.
  3. All default arguments are pickled.
  4. 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.