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
orgramian
will always returnNumPy arrays
.An implementation of the
VectorArray
viaNumPy arrays
is given byNumpyVectorArray
. 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 areserve
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-dimensionalNumPy arrays
. Indexing will always return a newVectorArray
which acts as a view into the original data. Thus, if the indexed array is modified viascal
oraxpy
, 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 acopy
of a view for long term storage. Sincecopy
has copy-on-write semantics, this will usually cause little overhead.- 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.
Methods
The maximum absolute value of the DOFs contained in the array.
Append vectors to the array.
BLAS AXPY operation.
Check if index is admissible.
Check if index is admissible and unique.
Complex conjugation.
Returns a copy of the array.
Extract DOFs of the vectors contained in the array.
Create an empty
VectorArray
of the sameVectorSpace
.Create a
VectorArray
of vectors with all DOFs set to the same value.Shorthand for
self.inner(self, product)
.Returns the inner products between
VectorArray
elements.Return the number of given indices.
Return the number of specified unique indices.
Returns linear combinations of the vectors contained in the array.
Norm with respect to a given inner product.
Squared norm with respect to a given inner product.
Create a
VectorArray
of vectors of the sameVectorSpace
with all DOFs set to one.Returns the pairwise inner products between
VectorArray
elements.Create a
VectorArray
of vectors with random entries.BLAS SCAL operation (in-place scalar multiplication).
The l-infinity-norms of the vectors contained in the array.
Return (len(self), self.dim) NumPy Array with the data stored in the array.
Create a
VectorArray
of null vectors of the sameVectorSpace
.- 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 fromother
. 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 samex
vector is used for all vectors inself
. Otherwise, the lengths ofself
andx
have to agree. Ifalpha
is a scalar, eachx
vector is multiplied with the same factoralpha
. Otherwise,alpha
has to be a one-dimensionalNumPy array
of the same length asself
containing the coefficients for eachx
vector.Parameters
- alpha
The scalar coefficient or one-dimensional
NumPy array
of coefficients with which the vectors inx
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.
- 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 settingdeep
toTrue
, 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 thatresult[i, j]
is thedof_indices[j]
-th DOF of thei
-th vector of the array.
- empty(reserve=0)[source]¶
Create an empty
VectorArray
of the sameVectorSpace
.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
containingcount
vectors with each DOF set tovalue
.
- inner(other, product=None)[source]¶
Returns the inner products between
VectorArray
elements.If
product
isNone
, the Euclidean inner product between thedofs
ofself
andother
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, thisOperator
is used to compute the inner products usingapply2
, 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
anOperator
representing the inner product bilinear form.
- 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 withlen(self)
.
Returns
A
VectorArray
result
such thatresult[i] = ∑ self[j] * coefficients[i,j]
in case
coefficients
is of dimension 2, otherwiselen(result) == 1
andresult[0] = ∑ self[j] * coefficients[j].
- norm(product=None, tol=None, raise_complex=None)[source]¶
Norm with respect to a given inner product.
If
product
isNone
, the Euclidean norms of thedofs
of the array are returned, i.e.U.norm()
is equivalent to:
np.sqrt(U.pairwise_inner(U))
If a
product
Operator
is specified, thisOperator
is used to compute the norms via:np.sqrt(product.pairwise_apply2(U, U))
Parameters
- product
If not
None
, the inner productOperator
used to compute the norms.- tol
If
raise_complex
isTrue
, aValueError
exception is raised if there are complex norm squares with an imaginary part of absolute value larger thantol
.- 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
isNone
, the Euclidean norms of thedofs
of the array are returned, i.e.U.norm()
is equivalent to:
U.pairwise_inner(U)
If a
product
Operator
is specified, thisOperator
is used to compute the norms via:product.pairwise_apply2(U, U)
Parameters
- product
If not
None
, the inner productOperator
used to compute the norms.- tol
If
raise_complex
isTrue
, aValueError
exception is raised if there are complex norm squares with an imaginary part of absolute value larger thantol
.- 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 sameVectorSpace
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
containingcount
vectors with each DOF set to one.
- pairwise_inner(other, product=None)[source]¶
Returns the pairwise inner products between
VectorArray
elements.If
product
isNone
, the Euclidean inner product between thedofs
ofself
andother
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, thisOperator
is used to compute the inner products usingpairwise_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
anOperator
representing the inner product bilinear form.
- 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 to0
).- high
Upper bound for
'uniform'
distribution (defaults to1
).- loc
Mean for
'normal'
distribution (defaults to0
).- scale
Standard deviation for
'normal'
distribution (defaults to1
).- 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-dimensionalNumPy array
of the same length asself
containing the factors for each vector.Parameters
- alpha
The scalar coefficient or one-dimensional
NumPy array
of coefficients with which the vectors inself
are multiplied.
- sup_norm()[source]¶
The l-infinity-norms of the vectors contained in the array.
Returns
A
NumPy array
result
such thatresult[i]
contains the norm ofself[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 returnedNumPy array
might alter the originalVectorArray
. IfTrue
always a copy of the array data is made.
- zeros(count=1, reserve=0)[source]¶
Create a
VectorArray
of null vectors of the sameVectorSpace
.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
containingcount
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 internalimpl
object of this type. Indexing, error checking or non-standard inner products are handled byVectorArray
. Possible indices are passed to the methods ofVectorArrayImpl
asind
,oind
orxind
parameters. These can either beNone
, in case the array has not been indexed, aslice
object, or a Python list of non-negative numbers.Methods
- 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 createVectorArrays
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 viazeros
. Themake_array
method builds a newVectorArray
from given raw data of the underlying linear algebra backend (e.g. aNumPy array
in the case ofNumpyVectorSpace
). Some vector spaces can create newVectorArrays
from a givenNumPy array
via thefrom_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 givenVectorArray
is an element of the space, thein
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).
- is_scalar[source]¶
Equivalent to
isinstance(space, NumpyVectorSpace) and space.dim == 1 and space.id is None
.
Methods
Create an empty
VectorArray
.Create a
VectorArray
from aNumPy array
.Create a
VectorArray
of vectors with all DOFs set to the same value.Create a
VectorArray
from raw data.Create a
VectorArray
of vectors with all DOFs set to one.Create a
VectorArray
of vectors with random entries.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 aNumPy array
.Note that this method will not be supported by all vector space implementations.
Parameters
- data
NumPy
array of shape(len, dim)
wherelen
is the number of vectors anddim
their dimension.- ensure_copy
If
False
, modifying the returnedVectorArray
might alter the originalNumPy array
. IfTrue
always a copy of the array data is made.
Returns
A
VectorArray
withdata
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
containingcount
vectors with each DOF set tovalue
.
- abstract make_array(**kwargs)[source]¶
Create a
VectorArray
from raw data.This method is used in the implementation of
Operators
andModels
to create newVectorArrays
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
containingcount
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 to0
).- high
Upper bound for
'uniform'
distribution (defaults to1
).- loc
Mean for
'normal'
distribution (defaults to0
).- scale
Standard deviation for
'normal'
distribution (defaults to1
).- 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
containingcount
vectors with each component zero.