pymor.core package


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.


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

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


classmethod __new__

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

Bases: staticmethod

A decorator indicating abstract staticmethods.

Similar to abstractmethod.


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

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


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.


CacheRegion clear, get, set


CacheRegion persistent

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


Clear the entire cache region.


Return cache entry for given key.


The key for the cache entry.


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


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.


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


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


Disable caching for this instance.


Enable caching for this instance.

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


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


MemoryRegion NO_VALUE
CacheRegion persistent

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

Bases: pymor.core.cache.CacheRegion


SQLiteRegion clear, get, housekeeping, set


CacheRegion persistent

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

Bases: object

Decorator to make a method of CacheableInterface actually cached.

__call__(im_self, *args, **kwargs)[source]

Via the magic that is partial functions returned from __get__, im_self is the instance object of the class we’re decorating a method of and [kw]args are the actual parameters to the decorated method

__get__(instance, instancetype)[source]

Implement the descriptor protocol to make decorating instance method possible. Return a partial function where the first argument is the instance of the decorated instance object.



Clear all cache regions.

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


Globally disable caching.


Globally enable caching.

decorators module

Created on Fri Nov 2 10:12:55 2012 Collection of function/class based decorators.

class pymor.core.decorators.DecoratorBase(func)[source]

Bases: object

A base for all decorators that does the common automagic

__get__(obj, ownerClass=None)[source]

Return a wrapper that binds self as a method of obj (!)

class pymor.core.decorators.DecoratorWithArgsBase[source]

Bases: object

A base for all decorators with args that sadly can do little common automagic


DecoratorWithArgsBase mark

class pymor.core.decorators.Deprecated(alt='no alternative given')[source]

Bases: pymor.core.decorators.DecoratorBase

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.


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:

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


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.


DefaultContainer get, import_all, keys, update


DefaultContainer sid

pymor.core.defaults.defaults(*args, **kwargs)[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.


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).
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!
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.


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.


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.


Path of the configuration file.

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

Print all default values set in pyMOR.


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 the paths of all default values by shorten_paths components. The last two path components will always be printed.


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.


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

pymor.core.defaults.write_defaults_to_file(filename='./', 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.


Name of the file to write to.
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: exceptions.Exception

Is raised if the result of a computation is inaccurate


Exception __new__


BaseException args, message

class pymor.core.exceptions.ConstError[source]

Bases: exceptions.Exception

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


Exception __new__


BaseException args, message

class pymor.core.exceptions.ExtensionError[source]

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


Exception __new__


BaseException args, message

class pymor.core.exceptions.GmshError[source]

Bases: exceptions.Exception

Is raised when a Gmsh related error occurs.


Exception __new__


BaseException args, message

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

Bases: exceptions.Exception

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


Exception __new__


BaseException args, message

class pymor.core.exceptions.InversionError[source]

Bases: exceptions.Exception

Is raised if an operator inversion algorithm fails.


Exception __new__


BaseException args, message

class pymor.core.exceptions.NewtonError[source]

Bases: exceptions.Exception

Is raised if the Newton algorithm fails to converge.


Exception __new__


BaseException args, message

class pymor.core.exceptions.SIDGenerationError[source]

Bases: exceptions.Exception

Is raised when generate_sid fails.


Exception __new__


BaseException args, message

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. An instance can be made immutable using BasicInterface.lock. If an instance is locked, each attempt to change one of its attributes raises an exception. Private attributes (of the form _name) are exempted from this rule. Locked instances can be unlocked again using BasicInterface.unlock.
  5. 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.
  6. If not set by the user to another value, 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.

  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.


True if the instance is made immutable using lock.


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


True if logging has been disabled.


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


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

__setattr__(key, value)[source]

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


Disable logging output for this instance.


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.


Make the instance immutable.

Trying to change an attribute after locking raises a ConstError. Private attributes (of the form _attribute) are exempted from this rule.


Make the instance mutable again, after it has been locked using lock.

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 they are locked after __init__ returns.


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.


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


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


Set of attributes not to include in state id calculation.


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.


alias of ImmutableMeta


Generate a unique state id for the given object.

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


If True, produce some debugging output.


The generated state id.


Make the instance mutable.


Unlocking an instance of ImmutableInterface will result in the deletion of its state id. However, this will not delete the state ids of objects referencing it. You really should not unlock an object unless you really know what you are doing.


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.


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


Copy of self with changed attributes.

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

Bases: pymor.core.interfaces.UberMeta

Metaclass for ImmutableInterface.


ABCMeta register, __instancecheck__, __subclasscheck__
type mro, __subclasses__

class pymor.core.interfaces.UID[source]

Bases: object

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


UID counter, prefix, uid

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

Bases: abc.ABCMeta


UberMeta __new__
ABCMeta register, __instancecheck__, __subclasscheck__
type mro, __subclasses__
static __new__(classname, bases, classdict)[source]

I copy docstrings from base class methods to deriving classes. I also forward “abstract{class|static}method” decorations in the base class to “{class|static}method” decorations in the new subclass.

Copying of docstrings can be prevented by setting the PYMOR_COPY_DOCSTRINGS_DISABLE environment variable to 1.

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

Bases: pymor.core.backports.abstractclassmethod

I mark my wrapped function with an additional __isabstractclassmethod__ member, where my abstractclassmethod_base sets __isabstractmethod__ = True.


classmethod __new__

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

Bases: pymor.core.backports.abstractstaticmethod

I mark my wrapped function with an additional __isabstractstaticmethod__ member, where my abstractclassmethod_base sets __isabstractmethod__ = True.


staticmethod __new__

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

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


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


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.

class pymor.core.logger.DummyLogger[source]

Bases: object


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


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.


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


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.


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


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

pymor.core.logger.set_log_levels(levels={'pymor': 'INFO'})[source]

Set log levels for pyMOR’s logging facility.


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


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


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]


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.




Restores a function serialized with dumps_function.