pymor.vectorarrays package

Submodules

block module


class pymor.vectorarrays.block.BlockVectorArray(blocks, space)[source]

Bases: pymor.vectorarrays.interfaces.VectorArrayInterface

VectorArray where each vector is a direct sum of sub-vectors.

Given a list of equal length VectorArrays blocks, this VectorArray represents the direct sums of the vectors contained in the arrays. The associated VectorSpaceInterface is BlockVectorSpace.

BlockVectorArray can be used in conjunction with BlockOperator.

block(ind)[source]

Returns a copy of each block (no slicing).


class pymor.vectorarrays.block.BlockVectorArrayView(base, ind)[source]

Bases: pymor.vectorarrays.block.BlockVectorArray


class pymor.vectorarrays.block.BlockVectorSpace(subspaces, id_=None)[source]

Bases: pymor.vectorarrays.interfaces.VectorSpaceInterface

VectorSpaceInterface of BlockVectorArrays.

A BlockVectorSpace is defined by the VectorSpaces of the individual subblocks which constitute a given array. In particular for a given :class`BlockVectorArray` U, we have the identity

(U.blocks[0].space, U.blocks[1].space, ..., U.blocks[-1].space) == U.space.

Parameters

subspaces
The tuple defined above.

constructions module


pymor.vectorarrays.constructions.cat_arrays(vector_arrays)[source]

Return a new VectorArray which is a concatenation of the arrays in vector_arrays.

interfaces module


class pymor.vectorarrays.interfaces.VectorArrayInterface[source]

Bases: pymor.core.interfaces.BasicInterface

Interface for vector arrays.

A vector array should be thought of as a list of (possibly high-dimensional) vectors. While the vectors themselves will be inaccessible in general (e.g. because they are managed by an external PDE solver code), operations on the vectors like addition can be performed via this interface.

It is assumed that the number of vectors is small enough such that scalar data associated to each vector can be handled on the Python side. As such, methods like l2_norm or gramian will always return NumPy arrays.

An implementation of the VectorArrayInterface via NumPy arrays is given by NumpyVectorArray. In general, it is the implementors decision how memory is allocated internally (e.g. continuous block of memory vs. list of pointers to the individual vectors.) Thus, no general assumptions can be made on the costs of operations like appending to or removing vectors from the array. As a hint for ‘continuous block of memory’ implementations, zeros provides a reserve keyword argument which allows to specify to what size the array is assumed to grow.

As with NumPy array, VectorArrays can be indexed with numbers, slices and lists or one-dimensional NumPy arrays. Indexing will always return a new VectorArray which acts as a view into the original data. Thus, if the indexed array is modified via scal or axpy, the vectors in the original array will be changed. Indices may be negative, in which case the vector is selected by counting from the end of the array. Moreover indices can be repeated, in which case the corresponding vector is selected several times. The resulting view will be immutable, however.

Note

It is disallowed to append vectors to a VectorArray view or to remove vectors from it. Removing vectors from an array with existing views will lead to undefined behavior of these views. As such, it is generally advisable to make a copy of a view for long term storage. Since copy has copy-on-write semantics, this will usually cause little overhead.

data

Implementors can provide a data property which returns a NumPy array of shape (len(v), v.dim) containing the data stored in the array. Access should be assumed to be slow and is mainly intended for debugging / visualization purposes or to once transfer data to pyMOR and further process it using NumPy. In the case of NumpyVectorArray, an actual view of the internally used NumPy array is returned, so changing it, will alter the VectorArray. Thus, you cannot assume to own the data returned to you, in general.

dim

The dimension of the vectors in the array.

is_view

True if the array is a view obtained by indexing another array.

space

The VectorSpaceInterface the array belongs to.

__add__(other)[source]

The pairwise sum of two VectorArrays.

__delitem__(ind)[source]

Remove vectors from the array.

__getitem__(ind)[source]

Return a VectorArray view onto a subset of the vectors in the array.

__iadd__(other)[source]

In-place pairwise addition of VectorArrays.

__imul__(other)[source]

In-place product by a scalar.

__isub__(other)[source]

In-place pairwise difference of VectorArrays.

__len__()[source]

The number of vectors in the array.

__mul__(other)[source]

Product by a scalar.

__neg__()[source]

Product by -1.

__radd__(other)

The pairwise sum of two VectorArrays.

__rmul__(other)

Product by a scalar.

__sub__(other)[source]

The pairwise difference of two VectorArrays.

amax()[source]

The maximum absolute value of the vectors contained in the array.

Returns

max_ind
NumPy array containing for each vector an index at which the maximum is attained.
max_val
NumPy array containing for each vector the maximum absolute value of its components.
append(other, remove_from_other=False)[source]

Append vectors to the array.

Parameters

other
A VectorArray containing the vectors to be appended.
remove_from_other
If True, the appended vectors are removed from other. For list-like implementations this can be used to prevent unnecessary copies of the involved vectors.
axpy(alpha, x)[source]

BLAS AXPY operation.

This method forms the sum

self = alpha*x + self

If the length of x is 1, the same x vector is used for all vectors in self. Otherwise, the lengths of self and x have to agree. If alpha is a scalar, each x vector is multiplied with the same factor alpha. Otherwise, alpha has to be a one-dimensional NumPy array of the same length as self containing the coefficients for each x vector.

Parameters

alpha
The scalar coefficient or one-dimensional NumPy array of coefficients with which the vectors in x are multiplied.
x
A VectorArray containing the x-summands.
check_ind(ind)[source]

Check if ind is an admissable list of indices in the sense of the class documentation.

check_ind_unique(ind)[source]

Check if ind is an admissable list of non-repeated indices in the sense of the class documentation.

components(component_indices)[source]

Extract components of the vectors contained in the array.

Parameters

component_indices
List or 1D NumPy array of indices of the vector components that are to be returned.

Returns

A NumPy array result such that result[i, j] is the component_indices[j]-th component of the i-th vector of the array.

copy(deep=False)[source]

Returns a copy of a subarray.

All VectorArray implementations in pyMOR have copy-on-write semantics: if not specified otherwise by setting deep to True, the returned copy will hold a handle to the same array data as the original array, and a deep copy of the data will only be performed when one of the arrays is modified.

Note that for NumpyVectorArray, a deep copy is always performed when only some vectors in the array are copied.

Parameters

deep
Ensure that an actual copy of the array data is made (see above).

Returns

A copy of the VectorArray.

dot(other)[source]

Returns the inner products between VectorArray elements.

Parameters

other
A VectorArray containing the second factors.

Returns

A NumPy array result such that

result[i, j] = ( self[i], other[j] ).
empty(reserve=0)[source]

Create an empty VectorArray of the same VectorSpaceInterface.

This is a shorthand for self.space.zeros(0, reserve).

Parameters

reserve
Hint for the backend to which length the array will grow.

Returns

An empty VectorArray.

gramian()[source]

Shorthand for self.dot(self).

l1_norm()[source]

The l1-norms of the vectors contained in the array.

Returns

A NumPy array result such that result[i] contains the norm of self[i].

l2_norm()[source]

The l2-norms of the vectors contained in the array.

Returns

A NumPy array result such that result[i] contains the norm of self[i].

l2_norm2()[source]

The squared l2-norms of the vectors contained in the array.

Returns

A NumPy array result such that result[i] contains the norm of self[i].

len_ind(ind)[source]

Return the number of given indices.

len_ind_unique(ind)[source]

Return the number of specified unique indices.

lincomb(coefficients)[source]

Returns linear combinations of the vectors contained in the array.

Parameters

coefficients
A NumPy array of dimension 1 or 2 containing the linear coefficients. coefficients.shape[-1] has to agree with len(self).

Returns

A VectorArray result such that

result[i] = ∑ self[j] * coefficients[i,j]

in case coefficients is of dimension 2, otherwise len(result) == 1 and

result[0] = ∑ self[j] * coefficients[j].
normalize_ind(ind)[source]

Normalize given indices such that they are independent of the array length.

pairwise_dot(other)[source]

Returns the pairwise inner products between VectorArray elements.

Parameters

other
A VectorArray containing the second factors.

Returns

A NumPy array result such that

result[i] = ( self[i], other[i] ).
scal(alpha)[source]

BLAS SCAL operation (in-place scalar multiplication).

This method calculates

self = alpha*self

If alpha is a scalar, each vector is multiplied by this scalar. Otherwise, alpha has to be a one-dimensional NumPy array of the same length as self containing the factors for each vector.

Parameters

alpha
The scalar coefficient or one-dimensional NumPy array of coefficients with which the vectors in self are multiplied.
sub_index(ind, ind_ind)[source]

Return indices corresponding to the view self[ind][ind_ind]

sup_norm()[source]

The l-infinity–norms of the vectors contained in the array.

Returns

A NumPy array result such that result[i] contains the norm of self[i].

zeros(count=1, reserve=0)[source]

Create a VectorArray of null vectors of the same VectorSpaceInterface.

This is a shorthand for self.space.zeros(count, reserve).

Parameters

count
The number of vectors.
reserve
Hint for the backend to which length the array will grow.

Returns

A VectorArray containing count vectors whith each component zero.


class pymor.vectorarrays.interfaces.VectorSpaceInterface[source]

Bases: pymor.core.interfaces.ImmutableInterface

Class describing a vector space.

Vector spaces act as factories for VectorArrays of vectors contained in them. As such, they hold all data necessary to create VectorArrays of a given type (e.g. the dimension of the vectors, or a socket for communication with an external PDE solver).

New VectorArrays of null vectors are created via zeros. The make_array method builds a new VectorArray from given raw data of the underlying linear algebra backend (e.g. a NumPy array in the case of NumpyVectorSpace). Some vector spaces can create new VectorArrays from a given NumPy array via the from_data method.

Each vector space has a string id to distinguish mathematically different spaces appearing in the formulation of a given problem.

Vector spaces can be compared for equality via the == and != operators. To test if a given VectorArray is an element of the space, the in operator can be used.

id

None, or a string describing the mathematical identity of the vector space (for instance to distinguish different components in an equation system).

dim

The dimension (number of degrees of freedom) of the vectors contained in the space.

is_scalar

Equivalent to isinstance(space, NumpyVectorSpace) and space.dim == 1.

empty(reserve=0)[source]

Create an empty VectorArray

This is a shorthand for self.zeros(0, reserve).

Parameters

reserve
Hint for the backend to which length the array will grow.

Returns

An empty VectorArray.

from_data(data)[source]

Create a VectorArray from a NumPy array

Note that this method will not be supported by all vector space implementations.

Parameters

data
NumPy array.

Returns

A VectorArray with data as data.

make_array(*args, **kwargs)[source]

Create a VectorArray from raw data.

This method is used in the implementation of Operators and Discretizations to create new VectorArrays from raw data of the underlying solver backends. The ownership of the data is transferred to the newly created array.

The exact signature of this method depends on the wrapped solver backend.

zeros(count=1, reserve=0)[source]

Create a VectorArray of null vectors

Parameters

count
The number of vectors.
reserve
Hint for the backend to which length the array will grow.

Returns

A VectorArray containing count vectors with each component zero.

list module


class pymor.vectorarrays.list.CopyOnWriteVector[source]

Bases: pymor.vectorarrays.list.VectorInterface

Methods

CopyOnWriteVector axpy, copy, from_instance, scal
VectorInterface amax, components, dot, l1_norm, l2_norm, l2_norm2, sup_norm
BasicInterface disable_logging, enable_logging, has_interface_name, implementor_names, implementors

class pymor.vectorarrays.list.ListVectorArray(vectors, space)[source]

Bases: pymor.vectorarrays.interfaces.VectorArrayInterface

VectorArray implemented as a Python list of vectors.

This VectorArray implementation is the first choice when creating pyMOR wrappers for external solvers which are based on single vector objects. In order to do so, a wrapping subclass of VectorInterface has to be provided on which the implementation of ListVectorArray will operate. The associated VectorSpaceInterface is a subclass of ListVectorSpace.

For an example, see NumpyVector, NumpyListVectorSpace or FenicsVector, FenicsVectorSpace.


class pymor.vectorarrays.list.ListVectorArrayView(base, ind)[source]

Bases: pymor.vectorarrays.list.ListVectorArray


class pymor.vectorarrays.list.ListVectorSpace[source]

Bases: pymor.vectorarrays.interfaces.VectorSpaceInterface

VectorSpaceInterface of ListVectorArrays.


class pymor.vectorarrays.list.NumpyListVectorSpace(dim, id_=None)[source]

Bases: pymor.vectorarrays.list.ListVectorSpace


class pymor.vectorarrays.list.NumpyVector(array)[source]

Bases: pymor.vectorarrays.list.CopyOnWriteVector

Vector stored in a NumPy 1D-array.

Methods

NumpyVector amax, components, dot, from_instance, l1_norm, l2_norm, l2_norm2
CopyOnWriteVector axpy, copy, scal
VectorInterface sup_norm
BasicInterface disable_logging, enable_logging, has_interface_name, implementor_names, implementors

class pymor.vectorarrays.list.VectorInterface[source]

Bases: pymor.core.interfaces.BasicInterface

Interface for vectors used in conjunction with ListVectorArray.

This interface must be staisfied by the individual entries of the vector list managed by ListVectorArray. All interface methods have a direct counterpart in the VectorArray interface.

Methods

VectorInterface amax, axpy, components, copy, dot, l1_norm, l2_norm, l2_norm2, scal, sup_norm
BasicInterface disable_logging, enable_logging, has_interface_name, implementor_names, implementors

mpi module

Wrapper classes for building MPI distributed VectorArrays.

This module contains several wrapper classes which allow to transform single rank VectorArrays into MPI distributed VectorArrays which can be used on rank 0 like ordinary VectorArrays.

The implementations are based on the event loop provided by pymor.tools.mpi.


class pymor.vectorarrays.mpi.MPIVectorArray(obj_id, space)[source]

Bases: pymor.vectorarrays.interfaces.VectorArrayInterface

MPI distributed VectorArray.

Given a local VectorArray on each MPI rank, this wrapper class uses the event loop from pymor.tools.mpi to build a global MPI distributed vector array from these local arrays.

Instances of MPIVectorArray can be used on rank 0 like any other (non-distributed) VectorArray.

Note, however, that the implementation of the local VectorArrays needs to be MPI aware. For instance, cls.dot must perform the needed MPI communication to sum up the local inner products and return the sums on rank 0.

Default implementations for all communication requiring interface methods are provided by MPIVectorArrayAutoComm (also see MPIVectorArrayNoComm).

Note that resource cleanup is handled by object.__del__. Please be aware of the peculiarities of destructors in Python!

The associated VectorSpaceInterface is MPIVectorSpace.


class pymor.vectorarrays.mpi.MPIVectorArrayAutoComm(obj_id, space)[source]

Bases: pymor.vectorarrays.mpi.MPIVectorArray

MPI distributed VectorArray.

This is a subclass of MPIVectorArray which provides default implementations for all communication requiring interface methods for the case when the wrapped array is not MPI aware.

Note, however, that depending on the discretization these default implementations might lead to wrong results (for instance in the presence of shared DOFs).

The associated VectorSpaceInterface is MPIVectorSpaceAutoComm.


class pymor.vectorarrays.mpi.MPIVectorArrayNoComm(obj_id, space)[source]

Bases: pymor.vectorarrays.mpi.MPIVectorArray

MPI distributed VectorArray.

This is a subclass of MPIVectorArray which overrides all communication requiring interface methods to raise NotImplementedError.

This is mainly useful as a security measure when wrapping arrays for which simply calling the respective method on the wrapped arrays would lead to wrong results and MPIVectorArrayAutoComm cannot be used either (for instance in the presence of shared DOFs).

The associated VectorSpaceInterface is MPIVectorSpaceNoComm.


class pymor.vectorarrays.mpi.MPIVectorSpace(local_spaces)[source]

Bases: pymor.vectorarrays.interfaces.VectorSpaceInterface

VectorSpaceInterface of MPIVectorArrays.

Parameters

local_spaces
tuple of the different VectorSpaces of the local VectorArrays on the MPI ranks. Alternatively, the length of local_spaces may be 1, in which case the same VectorSpaceInterface is assumed for all ranks.
array_type

alias of MPIVectorArray

make_array(obj_id)[source]

Create array from rank-local VectorArray instances.

Parameters

obj_id
ObjectId of the MPI distributed instances of cls wrapped by this array.

Returns

The newly created : class:MPIVectorArray.


class pymor.vectorarrays.mpi.MPIVectorSpaceAutoComm(local_spaces)[source]

Bases: pymor.vectorarrays.mpi.MPIVectorSpace

VectorSpaceInterface for MPIVectorArrayAutoComm.

array_type

alias of MPIVectorArrayAutoComm


class pymor.vectorarrays.mpi.MPIVectorSpaceNoComm(local_spaces)[source]

Bases: pymor.vectorarrays.mpi.MPIVectorSpace

VectorSpaceInterface for MPIVectorArrayNoComm.

array_type

alias of MPIVectorArrayNoComm


class pymor.vectorarrays.mpi.RegisteredLocalSpace[source]

Bases: int

Methods

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

Attributes

int denominator, imag, numerator, real

numpy module


class pymor.vectorarrays.numpy.NumpyVectorArray(array, space)[source]

Bases: pymor.vectorarrays.interfaces.VectorArrayInterface

VectorArray implementation via NumPy arrays.

This is the default VectorArray type used by all Operators in pyMOR’s discretization toolkit. Moreover, all reduced Operators are based on NumpyVectorArray.

This class is just a thin wrapper around the underlying NumPy array. Thus, while operations like axpy or dot will be quite efficient, removing or appending vectors will be costly.

The associated VectorSpaceInterface is NumpyVectorSpace.


class pymor.vectorarrays.numpy.NumpyVectorArrayView(array, ind)[source]

Bases: pymor.vectorarrays.numpy.NumpyVectorArray


class pymor.vectorarrays.numpy.NumpyVectorSpace(dim, id_=None)[source]

Bases: pymor.vectorarrays.interfaces.VectorSpaceInterface

VectorSpaceInterface of NumpyVectorArrays.

Parameters

dim
The dimension of the vectors contained in the space.
id
See id.