`pymor.vectorarrays.interface`¶

Module Contents¶

class pymor.vectorarrays.interface.VectorArray(space, impl, base=None, ind=None, _len=None)[source]¶

Bases: pymor.core.base.BasicObject

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 norm or gramian will always return NumPy arrays.

An implementation of the VectorArray 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.

dim[source]¶: The dimension of the vectors in the array.

is_view[source]¶: True if the array is a view obtained by indexing another array.

space[source]¶: The VectorSpace the array belongs to.

base[source]¶: In case the array is a view, the VectorArray this array refers to. None otherwise.

ind[source]¶: In case the array is a view, the indices with which the base array is indexed with.

real[source]¶: The real part of the vectors in the array.

imag[source]¶: The imaginary part of the vectors in the array.

Methods

`amax`	The maximum absolute value of the DOFs contained in the array.
`append`	Append vectors to the array.
`axpy`	BLAS AXPY operation.
`check_ind`	Check if index is admissible.
`check_ind_unique`	Check if index is admissible and unique.
`conj`	Complex conjugation.
`copy`	Returns a copy of the array.
`dofs`	Extract DOFs of the vectors contained in the array.
`empty`	Create an empty `VectorArray` of the same `VectorSpace`.
`full`	Create a `VectorArray` of vectors with all DOFs set to the same value.
`gramian`	Shorthand for `self.inner(self, product)`.
`inner`	Returns the inner products between `VectorArray` elements.
`len_ind`	Return the number of given indices.
`len_ind_unique`	Return the number of specified unique indices.
`lincomb`	Returns linear combinations of the vectors contained in the array.
`norm`	Norm with respect to a given inner product.
`norm2`	Squared norm with respect to a given inner product.
`ones`	Create a `VectorArray` of vectors of the same `VectorSpace` with all DOFs set to one.
`pairwise_inner`	Returns the pairwise inner products between `VectorArray` elements.
`random`	Create a `VectorArray` of vectors with random entries.
`scal`	BLAS SCAL operation (in-place scalar multiplication).
`sup_norm`	The l-infinity-norms of the vectors contained in the array.
`to_numpy`	Return (len(self), self.dim) NumPy Array with the data stored in the array.
`zeros`	Create a `VectorArray` of null vectors of the same `VectorSpace`.

impl_type = None[source]¶

amax()[source]¶

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

Returns

max_ind: NumPy array containing for each vector a DOF index at which the maximum is attained.
max_val: NumPy array containing for each vector the maximum absolute value of its DOFs.

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 index is admissible.

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

check_ind_unique(ind)[source]¶

Check if index is admissible and unique.

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

conj()[source]¶: Complex conjugation.

copy(deep=False)[source]¶

Returns a copy of the array.

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.

dofs(dof_indices)[source]¶

Extract DOFs of the vectors contained in the array.

Parameters

dof_indices: List or 1D NumPy array of indices of the DOFs that are to be returned.

Returns

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

empty(reserve=0)[source]¶

Create an empty VectorArray of the same VectorSpace.

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.

full(value, count=1, reserve=0)[source]¶

Create a VectorArray of vectors with all DOFs set to the same value.

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

Parameters

value: The value each DOF should be set to.
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 DOF set to value.

gramian(product=None)[source]¶: Shorthand for self.inner(self, product).

inner(other, product=None)[source]¶

Returns the inner products between VectorArray elements.

If product is None, the Euclidean inner product between the dofs of self and other are returned, i.e.

U.inner(V)

is equivalent to:

U.dofs(np.arange(U.dim)) @ V.dofs(np.arange(V.dim)).T

(Note, that dofs is only intended to be called for a small number of DOF indices.)

If a product Operator is specified, this Operator is used to compute the inner products using apply2, i.e. U.inner(V, product) is equivalent to:

product.apply2(U, V)

which in turn is, by default, implemented as:

U.inner(product.apply(V))

In the case of complex numbers, this is antilinear in the first argument, i.e. in ‘self’. Complex conjugation is done in the first argument because most numerical software in the community handles it this way: Numpy, DUNE, FEniCS, Eigen, Matlab and BLAS do complex conjugation in the first argument, only PetSc and deal.ii do complex conjugation in the second argument.

Parameters

other: A VectorArray containing the second factors.
product: If not None an Operator representing the inner product bilinear form.

Returns

A NumPy array result such that

result[i, j] = ( self[i], other[j] ).

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

norm(product=None, tol=None, raise_complex=None)[source]¶

Norm with respect to a given inner product.

If product is None, the Euclidean norms of the dofs of the array are returned, i.e.

U.norm()

is equivalent to:

np.sqrt(U.pairwise_inner(U))

If a product Operator is specified, this Operator is used to compute the norms via:

np.sqrt(product.pairwise_apply2(U, U))

Parameters

product: If not None, the inner product Operator used to compute the norms.
tol: If raise_complex is True, a ValueError exception is raised if there are complex norm squares with an imaginary part of absolute value larger than tol.
raise_complex: See tol.

Returns

A one-dimensional NumPy array of the norms of the vectors in the array.

norm2(product=None, tol=1e-10, raise_complex=True)[source]¶

Squared norm with respect to a given inner product.

If product is None, the Euclidean norms of the dofs of the array are returned, i.e.

U.norm()

is equivalent to:

U.pairwise_inner(U)

If a product Operator is specified, this Operator is used to compute the norms via:

product.pairwise_apply2(U, U)

Parameters

product: If not None, the inner product Operator used to compute the norms.
tol: If raise_complex is True, a ValueError exception is raised if there are complex norm squares with an imaginary part of absolute value larger than tol.
raise_complex: See tol.

Returns

A one-dimensional NumPy array of the squared norms of the vectors in the array.

ones(count=1, reserve=0)[source]¶

Create a VectorArray of vectors of the same VectorSpace with all DOFs set to one.

This is a shorthand for self.space.full(1., 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 with each DOF set to one.

pairwise_inner(other, product=None)[source]¶

Returns the pairwise inner products between VectorArray elements.

If product is None, the Euclidean inner product between the dofs of self and other are returned, i.e.

U.pairwise_inner(V)

is equivalent to:

np.sum(U.dofs(np.arange(U.dim)) * V.dofs(np.arange(V.dim)), axis=-1)

(Note, that dofs is only intended to be called for a small number of DOF indices.)

If a product Operator is specified, this Operator is used to compute the inner products using pairwise_apply2, i.e. U.inner(V, product) is equivalent to:

product.pairwise_apply2(U, V)

which in turn is, by default, implemented as:

U.pairwise_inner(product.apply(V))

In the case of complex numbers, this is antilinear in the first argument, i.e. in ‘self’. Complex conjugation is done in the first argument because most numerical software in the community handles it this way: Numpy, DUNE, FEniCS, Eigen, Matlab and BLAS do complex conjugation in the first argument, only PetSc and deal.ii do complex conjugation in the second argument.

Parameters

other: A VectorArray containing the second factors.
product: If not None an Operator representing the inner product bilinear form.

Returns

A NumPy array result such that

result[i] = ( self[i], other[i] ).

random(count=1, distribution='uniform', reserve=0, **kwargs)[source]¶

Create a VectorArray of vectors with random entries.

This is a shorthand for self.space.random(count, distribution, **kwargs).

Supported random distributions:

'uniform': Uniform distribution in half-open interval
           [`low`, `high`).
'normal':  Normal (Gaussian) distribution with mean
           `loc` and standard deviation `scale`.

Note that not all random distributions are necessarily implemented by all VectorSpace implementations.

Parameters

count: The number of vectors.
distribution: Random distribution to use ('uniform', 'normal').
low: Lower bound for 'uniform' distribution (defaults to 0).
high: Upper bound for 'uniform' distribution (defaults to 1).
loc: Mean for 'normal' distribution (defaults to 0).
scale: Standard deviation for 'normal' distribution (defaults to 1).
reserve: Hint for the backend to which length the array will grow.

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.

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

to_numpy(ensure_copy=False)[source]¶

Return (len(self), self.dim) NumPy Array with the data stored in the array.

Parameters

ensure_copy: If False, modifying the returned NumPy array might alter the original VectorArray. If True always a copy of the array data is made.

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

Create a VectorArray of null vectors of the same VectorSpace.

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 with each DOF set to zero.

class pymor.vectorarrays.interface.VectorArrayImpl[source]¶

Bases: pymor.core.base.BasicObject

Implementation of a VectorArray.

The VectorArray base class defers all calls to interface methods to an internal impl object of this type. Indexing, error checking or non-standard inner products are handled by VectorArray. Possible indices are passed to the methods of VectorArrayImpl as ind, oind or xind parameters. These can either be None, in case the array has not been indexed, a slice object, or a Python list of non-negative numbers.

Methods

`amax`
`append`
`axpy`
`axpy_copy`
`conj`
`copy`
`delete`
`dofs`
`gramian`
`imag`
`inner`
`len_ind`
`lincomb`
`norm`
`norm2`
`pairwise_inner`
`real`
`scal`
`scal_copy`
`to_numpy`

abstract amax(ind)[source]¶

abstract append(other, remove_from_other, oind)[source]¶

abstract axpy(alpha, x, ind, xind)[source]¶

axpy_copy(alpha, x, ind, xind)[source]¶

abstract conj(ind)[source]¶

abstract copy(deep, ind)[source]¶

abstract delete(ind)[source]¶

abstract dofs(dof_indices, ind)[source]¶

gramian(ind)[source]¶

abstract imag(ind)[source]¶

abstract inner(other, ind, oind)[source]¶

len_ind(ind)[source]¶

abstract lincomb(coefficients, ind)[source]¶

norm(ind)[source]¶

abstract norm2(ind)[source]¶

abstract pairwise_inner(other, ind, oind)[source]¶

abstract real(ind)[source]¶

abstract scal(alpha, ind)[source]¶

scal_copy(alpha, ind)[source]¶

abstract to_numpy(ensure_copy, ind)[source]¶

class pymor.vectorarrays.interface.VectorSpace[source]¶

Bases: pymor.core.base.ImmutableObject

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_numpy 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[source]¶: None, or a string describing the mathematical identity of the vector space (for instance to distinguish different components in an equation system).

dim[source]¶: The dimension (number of degrees of freedom) of the vectors contained in the space.

is_scalar[source]¶: Equivalent to isinstance(space, NumpyVectorSpace) and space.dim == 1 and space.id is None.

Methods

`empty`	Create an empty `VectorArray`.
`from_numpy`	Create a `VectorArray` from a `NumPy array`.
`full`	Create a `VectorArray` of vectors with all DOFs set to the same value.
`make_array`	Create a `VectorArray` from raw data.
`ones`	Create a `VectorArray` of vectors with all DOFs set to one.
`random`	Create a `VectorArray` of vectors with random entries.
`zeros`	Create a `VectorArray` of null vectors.

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.

abstract from_numpy(data, ensure_copy=False)[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 of shape (len, dim) where len is the number of vectors and dim their dimension.
ensure_copy: If False, modifying the returned VectorArray might alter the original NumPy array. If True always a copy of the array data is made.

Returns

A VectorArray with data as data.

full(value, count=1, reserve=0)[source]¶

Create a VectorArray of vectors with all DOFs set to the same value.

Parameters

value: The value each DOF should be set to.
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 DOF set to value.

abstract make_array(**kwargs)[source]¶

Create a VectorArray from raw data.

This method is used in the implementation of Operators and Models 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.

ones(count=1, reserve=0)[source]¶

Create a VectorArray of vectors with all DOFs set to one.

This is a shorthand for self.full(1., 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 with each DOF set to one.

random(count=1, distribution='uniform', reserve=0, **kwargs)[source]¶

Create a VectorArray of vectors with random entries.

Supported random distributions:

'uniform': Uniform distribution in half-open interval
           [`low`, `high`).
'normal':  Normal (Gaussian) distribution with mean
           `loc` and standard deviation `scale`.

Note that not all random distributions are necessarily implemented by all VectorSpace implementations.

Parameters

count: The number of vectors.
distribution: Random distribution to use ('uniform', 'normal').
low: Lower bound for 'uniform' distribution (defaults to 0).
high: Upper bound for 'uniform' distribution (defaults to 1).
loc: Mean for 'normal' distribution (defaults to 0).
scale: Standard deviation for 'normal' distribution (defaults to 1).
reserve: Hint for the backend to which length the array will grow.

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

pymor.vectorarrays.interface¶

Module Contents¶

`pymor.vectorarrays.interface`¶