Package slepc4py :: Module SLEPc :: Class BV
[hide private]
[frames] | no frames]

Class BV


BV
Nested Classes [hide private]
  BlockType
BV block-orthogonalization types
  MatMultType
BV mat-mult types
  OrthogBlockType
BV block-orthogonalization types
  OrthogRefineType
BV orthogonalization refinement types
  OrthogType
BV orthogonalization types
  RefineType
BV orthogonalization refinement types
  Type
BV type
Instance Methods [hide private]
a new object with type S, a subtype of T
__new__(S, ...)
 
applyMatrix(self, Vec x, Vec y)
Multiplies a vector with the matrix associated to the bilinear form.
 
copy(self, BV result=None)
Copies a basis vector object into another one.
 
copyColumn(self, j, i)
Copies the values from one of the columns to another one.
 
copyVec(self, j, Vec v)
Copies one of the columns of a basis vectors object into a Vec.
 
create(self, comm=None)
Creates the BV object.
 
createFromMat(self, Mat A)
Creates a basis vectors object from a dense Mat object.
 
createMat(self)
Creates a new Mat object of dense type and copies the contents of the BV object.
 
createVec(self)
Creates a new Vec object with the same type and dimensions as the columns of the basis vectors object.
 
destroy(self)
Destroys the BV object.
 
dot(self, BV Y)
M = Y^H*X (m_ij = y_i^H x_j) or M = Y^H*B*X
 
dotColumn(self, j)
Computes multiple dot products of a column against all the column vectors of a BV.
 
dotVec(self, Vec v)
Computes multiple dot products of a vector against all the column vectors of a BV.
 
duplicate(self)
Duplicate the BV object with the same type and dimensions.
 
duplicateResize(self, m)
Creates a new BV object of the same type and dimensions as an existing one, but with possibly different number of columns.
 
getActiveColumns(self)
Returns the current active dimensions.
 
getColumn(self, j)
Returns a Vec object that contains the entries of the requested column of the basis vectors object.
 
getDefiniteTolerance(self)
Gets the tolerance to be used when checking a definite inner product.
 
getMat(self)
Returns a Mat object of dense type that shares the memory of the basis vectors object.
 
getMatMultMethod(self)
Gets the method used for the matMult() operation.
 
getMatrix(self)
Retrieves the matrix representation of the inner product.
 
getNumConstraints(self)
Gets the number of constraints.
 
getOptionsPrefix(self)
Gets the prefix used for searching for all BV options in the database.
 
getOrthogonalization(self)
Gets the orthogonalization settings from the BV object.
 
getRandomContext(self)
Gets the PETSc.Random object associated with the BV.
 
getSizes(self)
Returns the local and global sizes, and the number of columns.
 
getType(self)
Gets the BV type of this object.
 
insertConstraints(self, C)
Insert a set of vectors as constraints.
 
insertVec(self, j, Vec w)
Insert a vector into the specified column.
 
insertVecs(self, s, W, bool orth)
Insert a set of vectors into specified columns.
 
matMult(self, Mat A, BV Y=None)
Computes the matrix-vector product for each column, Y = A*V.
 
matMultColumn(self, Mat A, j)
Computes the matrix-vector product for a specified column, storing the result in the next column: v_{j+1}=A*v_j.
 
matMultHermitianTranspose(self, Mat A, BV Y=None)
Computes the matrix-vector product with the conjugate transpose of a matrix for each column, Y=A^H*V.
 
matMultHermitianTransposeColumn(self, Mat A, j)
Computes the conjugate-transpose matrix-vector product for a specified column, storing the result in the next column: v_{j+1}=A^H*v_j.
 
matMultTransposeColumn(self, Mat A, j)
Computes the transpose matrix-vector product for a specified column, storing the result in the next column: v_{j+1}=A^T*v_j.
 
matProject(self, Mat A, BV Y)
Computes the projection of a matrix onto a subspace.
 
mult(self, alpha, beta, BV X, Mat Q)
Computes Y = beta*Y + alpha*X*Q.
 
multColumn(self, alpha, beta, j, q)
Computes y = beta*y + alpha*X*q, where y is the j-th column.
 
multInPlace(self, Mat Q, s, e)
Update a set of vectors as V(:,s:e-1) = V*Q(:,s:e-1).
 
multVec(self, alpha, beta, Vec y, q)
Computes y = beta*y + alpha*X*q.
 
norm(self, norm_type=None)
Computes the matrix norm of the BV.
 
normColumn(self, int j, norm_type=None)
Computes the matrix norm of the BV.
 
orthogonalize(self, Mat R=None, **kargs)
Orthogonalize all columns (except leading ones), that is, compute the QR decomposition.
 
orthogonalizeColumn(self, j)
Orthogonalize one of the column vectors with respect to the previous ones.
 
orthogonalizeVec(self, Vec v)
Orthogonalize a vector with respect to a set of vectors.
 
orthonormalizeColumn(self, j, replace=False)
Orthonormalize one of the column vectors with respect to the previous ones.
 
resize(self, m, copy=True)
Change the number of columns.
 
restoreColumn(self, j, Vec v)
Restore a column obtained with getColumn().
 
restoreMat(self, Mat A)
Restores the Mat obtained with getMat().
 
scale(self, alpha)
Multiply the entries by a scalar value.
 
scaleColumn(self, j, alpha)
Scale column j by alpha
 
setActiveColumns(self, l, k)
Specify the columns that will be involved in operations.
 
setDefiniteTolerance(self, deftol)
Sets the tolerance to be used when checking a definite inner product.
 
setFromOptions(self)
Sets BV options from the options database.
 
setMatMultMethod(self, method)
Specifies the method used for the matMult() operation.
 
setMatrix(self, Mat mat, bool indef)
Sets the bilinear form to be used for inner products.
 
setNumConstraints(self, nc)
Sets the number of constraints.
 
setOptionsPrefix(self, prefix)
Sets the prefix used for searching for all BV options in the database.
 
setOrthogonalization(self, otype=None, refine=None, eta=None, block=None)
Specifies the method used for the orthogonalization of vectors (classical or modified Gram-Schmidt with or without refinement), and for the block-orthogonalization (simultaneous orthogonalization of a set of vectors).
 
setRandom(self)
Set the active columns of the BV to random numbers.
 
setRandomColumn(self, j)
Set one column of the BV to random numbers.
 
setRandomCond(self, condn)
Set the columns of a BV to random numbers, in a way that the generated matrix has a given condition number.
 
setRandomContext(self, Random rnd)
Sets the PETSc.Random object associated with the BV, to be used in operations that need random numbers.
 
setRandomNormal(self)
Set the active columns of the BV to random numbers (with normal distribution).
 
setRandomSign(self)
Set the entries of a BV to values 1 or -1 with equal probability.
 
setSizes(self, sizes, m)
Sets the local and global sizes, and the number of columns.
 
setSizesFromVec(self, Vec w, m)
Sets the local and global sizes, and the number of columns.
 
setType(self, bv_type)
Selects the type for the BV object.
 
view(self, Viewer viewer=None)
Prints the BV data structure.

Inherited from petsc4py.PETSc.Object: __copy__, __deepcopy__, __eq__, __ge__, __gt__, __le__, __lt__, __ne__, __nonzero__, compose, decRef, getAttr, getClassId, getClassName, getComm, getDict, getName, getRefCount, getTabLevel, incRef, incrementTabLevel, query, setAttr, setName, setTabLevel, stateIncrease, viewFromOptions

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __init__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Properties [hide private]

Inherited from petsc4py.PETSc.Object: classid, comm, fortran, handle, klass, name, prefix, refcount, type

Inherited from object: __class__

Method Details [hide private]

__new__(S, ...)

 
Returns: a new object with type S, a subtype of T
Overrides: object.__new__

applyMatrix(self, Vec x, Vec y)

 

Multiplies a vector with the matrix associated to the bilinear form.

Parameters

x: Vec
The input vector.
y: Vec
The result vector.

Notes

If the bilinear form has no associated matrix this function copies the vector.

copy(self, BV result=None)

 

Copies a basis vector object into another one.

Parameters

result: BV, optional
The copy.

copyColumn(self, j, i)

 

Copies the values from one of the columns to another one.

Parameters

j: int
The number of the source column.
i: int
The number of the destination column.

copyVec(self, j, Vec v)

 

Copies one of the columns of a basis vectors object into a Vec.

Parameters

j: int
The column number to be copied.
v: Vec
A vector.

create(self, comm=None)

 

Creates the BV object.

Parameters

comm: Comm, optional
MPI communicator; if not provided, it defaults to all processes.

createFromMat(self, Mat A)

 

Creates a basis vectors object from a dense Mat object.

Parameters

A: Mat
A dense tall-skinny matrix.

createMat(self)

 

Creates a new Mat object of dense type and copies the contents of the BV object.

Returns

mat: the new matrix.

createVec(self)

 

Creates a new Vec object with the same type and dimensions as the columns of the basis vectors object.

Returns

v: Vec
New vector.

destroy(self)

 
Destroys the BV object.
Overrides: petsc4py.PETSc.Object.destroy

dot(self, BV Y)

 
Computes the 'block-dot' product of two basis vectors objects.
M = Y^H*X (m_ij = y_i^H x_j) or M = Y^H*B*X

Parameters

Y: BV
Left basis vectors, can be the same as self, giving M = X^H X.

Returns

M: Mat
The resulting matrix.

Notes

This is the generalization of VecDot() for a collection of vectors, M = Y^H*X. The result is a matrix M whose entry m_ij is equal to y_i^H x_j (where y_i^H denotes the conjugate transpose of y_i).

X and Y can be the same object.

If a non-standard inner product has been specified with setMatrix(), then the result is M = Y^H*B*X. In this case, both X and Y must have the same associated matrix.

Only rows (resp. columns) of M starting from ly (resp. lx) are computed, where ly (resp. lx) is the number of leading columns of Y (resp. X).

dotColumn(self, j)

 

Computes multiple dot products of a column against all the column vectors of a BV.

Parameters

j: int
The index of the column.

Returns

m: array of scalars
The computed values.

dotVec(self, Vec v)

 

Computes multiple dot products of a vector against all the column vectors of a BV.

Parameters

v: Vec
A vector.

Returns

m: array of scalars
The computed values.

Notes

This is analogue to VecMDot(), but using BV to represent a collection of vectors. The result is m = X^H*y, so m_i is equal to x_j^H y. Note that here X is transposed as opposed to BVDot().

If a non-standard inner product has been specified with BVSetMatrix(), then the result is m = X^H*B*y.

duplicateResize(self, m)

 

Creates a new BV object of the same type and dimensions as an existing one, but with possibly different number of columns.

Parameters

m: int
The number of columns.

getActiveColumns(self)

 

Returns the current active dimensions.

Returns

l: int
The leading number of columns.
k: int
The active number of columns.

getColumn(self, j)

 

Returns a Vec object that contains the entries of the requested column of the basis vectors object.

Parameters

j: int
The index of the requested column.

Returns

v: Vec
The vector containing the jth column.

Notes

Modifying the returned Vec will change the BV entries as well.

getDefiniteTolerance(self)

 

Gets the tolerance to be used when checking a definite inner product.

Returns

deftol: float
The tolerance.

getMat(self)

 

Returns a Mat object of dense type that shares the memory of the basis vectors object.

Returns

A: Mat
The matrix

Notes

The returned matrix contains only the active columns. If the content of the Mat is modified, these changes are also done in the BV object. The user must call restoreMat() when no longer needed.

getMatMultMethod(self)

 

Gets the method used for the matMult() operation.

Returns

method: BV.MatMultType enumerate
The method for the matMult() operation.

getMatrix(self)

 

Retrieves the matrix representation of the inner product.

Returns

mat: the matrix of the inner product

getNumConstraints(self)

 

Gets the number of constraints.

Returns

nc: int
The number of constraints.

getOptionsPrefix(self)

 

Gets the prefix used for searching for all BV options in the database.

Returns

prefix: string
The prefix string set for this BV object.
Overrides: petsc4py.PETSc.Object.getOptionsPrefix

getOrthogonalization(self)

 

Gets the orthogonalization settings from the BV object.

Returns

type: BV.OrthogType enumerate
The type of orthogonalization technique.
refine: BV.OrthogRefineType enumerate
The type of refinement.
eta: float
Parameter for selective refinement (used when the the refinement type BV.OrthogRefineType.IFNEEDED).
block: BV.OrthogBlockType enumerate
The type of block orthogonalization .

getRandomContext(self)

 

Gets the PETSc.Random object associated with the BV.

Returns

rnd: PETSc.Random
The random number generator context.

getSizes(self)

 

Returns the local and global sizes, and the number of columns.

Returns

sizes: two-tuple of int
The local and global sizes (n, N).
m: int
The number of columns.

getType(self)

 

Gets the BV type of this object.

Returns

type: BV.Type enumerate
The inner product type currently being used.
Overrides: petsc4py.PETSc.Object.getType

insertConstraints(self, C)

 

Insert a set of vectors as constraints.

Parameters

C: Vec or sequence of Vec.
Set of vectors to be inserted as constraints.

Returns

nc: int
Number of linearly independent vectors.

Notes

The constraints are relevant only during orthogonalization. Constraint vectors span a subspace that is deflated in every orthogonalization operation, so they are intended for removing those directions from the orthogonal basis computed in regular BV columns.

insertVec(self, j, Vec w)

 

Insert a vector into the specified column.

Parameters

j: int
The column to be overwritten.
w: Vec
The vector to be copied.

insertVecs(self, s, W, bool orth)

 

Insert a set of vectors into specified columns.

Parameters

s: int
The first column to be overwritten.
W: Vec or sequence of Vec.
Set of vectors to be copied.
orth:
Flag indicating if the vectors must be orthogonalized.

Returns

m: int
Number of linearly independent vectors.

Notes

Copies the contents of vectors W into self(:,s:s+n), where n is the length of W. If orthogonalization flag is set then the vectors are copied one by one then orthogonalized against the previous one. If any are linearly dependent then it is discared and the value of m is decreased.

matMult(self, Mat A, BV Y=None)

 

Computes the matrix-vector product for each column, Y = A*V.

Parameters

A: Mat
The matrix.

Returns

Y: BV
The result.

Notes

Only active columns (excluding the leading ones) are processed.

It is possible to choose whether the computation is done column by column or using dense matrices using the options database keys:

-bv_matmult_vecs -bv_matmult_mat

The default is bv_matmult_mat.

matMultColumn(self, Mat A, j)

 

Computes the matrix-vector product for a specified column, storing the result in the next column: v_{j+1}=A*v_j.

Parameters

A: Mat
The matrix.
j: int
Index of column.

matMultHermitianTranspose(self, Mat A, BV Y=None)

 

Computes the matrix-vector product with the conjugate transpose of a matrix for each column, Y=A^H*V.

Parameters

A: Mat
The matrix.

Returns

Y: BV
The result.

Notes

Only active columns (excluding the leading ones) are processed.

As opoosed to matMult(), this operation is always done by column by column, with a sequence of calls to MatMultHermitianTranspose().

matMultHermitianTransposeColumn(self, Mat A, j)

 

Computes the conjugate-transpose matrix-vector product for a specified column, storing the result in the next column: v_{j+1}=A^H*v_j.

Parameters

A: Mat
The matrix.
j: int
Index of column.

matMultTransposeColumn(self, Mat A, j)

 

Computes the transpose matrix-vector product for a specified column, storing the result in the next column: v_{j+1}=A^T*v_j.

Parameters

A: Mat
The matrix.
j: int
Index of column.

matProject(self, Mat A, BV Y)

 

Computes the projection of a matrix onto a subspace.

M = Y^H A X

Parameters

A: Mat or None
Matrix to be projected.
Y: BV
Left basis vectors, can be the same as self, giving M = X^H A X.

Returns

M: Mat
Projection of the matrix A onto the subspace.

mult(self, alpha, beta, BV X, Mat Q)

 

Computes Y = beta*Y + alpha*X*Q.

Parameters

alpha: scalar
Coefficient that multiplies X.
beta: scalar
Coefficient that multiplies Y.
X: BV
Input basis vectors.
Q: Mat
Input matrix.

multColumn(self, alpha, beta, j, q)

 

Computes y = beta*y + alpha*X*q, where y is the j-th column.

Parameters

alpha: scalar
Coefficient that multiplies X.
beta: scalar
Coefficient that multiplies y.
j: int
The column index.
q: Array of scalar
Input coefficients.

multInPlace(self, Mat Q, s, e)

 

Update a set of vectors as V(:,s:e-1) = V*Q(:,s:e-1).

Parameters

Q: Mat
A sequential dense matrix.
s: int
First column to be overwritten.
e: int
Last column to be overwritten.

multVec(self, alpha, beta, Vec y, q)

 

Computes y = beta*y + alpha*X*q.

Parameters

alpha: scalar
Coefficient that multiplies X.
beta: scalar
Coefficient that multiplies y.
y: Vec
Input/output vector.
q: Array of scalar
Input coefficients.

norm(self, norm_type=None)

 

Computes the matrix norm of the BV.

Parameters

norm_type: PETSC.NormType enumerate
The norm type.

Returns

norm: float

Notes

All active columns (except the leading ones) are considered as a matrix. The allowed norms are NORM_1, NORM_FROBENIUS, and NORM_INFINITY.

This operation fails if a non-standard inner product has been specified with BVSetMatrix().

normColumn(self, int j, norm_type=None)

 

Computes the matrix norm of the BV.

Parameters

j: int
Index of column.
norm_type: PETSc.NormType enumerate
The norm type.

Returns

norm: float

Notes

The norm of V[j] is computed (NORM_1, NORM_2, or NORM_INFINITY).

If a non-standard inner product has been specified with BVSetMatrix(), then the returned value is sqrt(V[j]'* B*V[j]), where B is the inner product matrix (argument 'type' is ignored).

orthogonalize(self, Mat R=None, **kargs)

 

Orthogonalize all columns (except leading ones), that is, compute the QR decomposition.

Parameters

R: Mat, optional
A sequential dense matrix.

Notes

The output satisfies V0 = V*R (where V0 represent the input V) and V'*V = I.

orthogonalizeColumn(self, j)

 

Orthogonalize one of the column vectors with respect to the previous ones.

Parameters

j: int
Index of the column to be orthogonalized.

Returns

norm: float
The norm of the resulting vector.
lindep: bool
Flag indicating that refinement did not improve the quality of orthogonalization.

Notes

This function applies an orthogonal projector to project vector V[j] onto the orthogonal complement of the span of the columns V[0..j-1], where V[.] are the vectors of the BV. The columns V[0..j-1] are assumed to be mutually orthonormal.

This routine does not normalize the resulting vector.

orthogonalizeVec(self, Vec v)

 

Orthogonalize a vector with respect to a set of vectors.

Parameters

v: Vec
Vector to be orthogonalized, modified on return.

Returns

norm: float
The norm of the resulting vector.
lindep: bool
Flag indicating that refinement did not improve the quality of orthogonalization.

Notes

This function applies an orthogonal projector to project vector v onto the orthogonal complement of the span of the columns of the BV.

This routine does not normalize the resulting vector.

orthonormalizeColumn(self, j, replace=False)

 

Orthonormalize one of the column vectors with respect to the previous ones. This is equivalent to a call to orthogonalizeColumn() followed by a call to scaleColumn() with the reciprocal of the norm.

Parameters

j: int
Index of the column to be orthonormalized.
replace: bool, optional
Whether it is allowed to set the vector randomly.

Returns

norm: float
The norm of the resulting vector.
lindep: bool
Flag indicating that refinement did not improve the quality of orthogonalization.

resize(self, m, copy=True)

 

Change the number of columns.

Parameters

m: int
The new number of columns.
copy: bool
A flag indicating whether current values should be kept.

Notes

Internal storage is reallocated. If copy is True, then the contents are copied to the leading part of the new space.

restoreColumn(self, j, Vec v)

 

Restore a column obtained with getColumn().

Parameters

j: int
The index of the requested column.
v: Vec
The vector obtained with getColumn().

Notes

The arguments must match the corresponding call to getColumn().

restoreMat(self, Mat A)

 

Restores the Mat obtained with getMat().

Parameters

A: Mat
The matrix obtained with getMat().

Notes

A call to this function must match a previous call of getMat(). The effect is that the contents of the Mat are copied back to the BV internal data structures.

scale(self, alpha)

 

Multiply the entries by a scalar value.

Parameters

alpha: float
scaling factor.

Notes

All active columns (except the leading ones) are scaled.

scaleColumn(self, j, alpha)

 

Scale column j by alpha

Parameters

j: int
column number to be scaled.
alpha: float
scaling factor.

setActiveColumns(self, l, k)

 

Specify the columns that will be involved in operations.

Parameters

l: int
The leading number of columns.
k: int
The active number of columns.

setDefiniteTolerance(self, deftol)

 

Sets the tolerance to be used when checking a definite inner product.

Parameters

deftol: float
The tolerance.

setFromOptions(self)

 

Sets BV options from the options database.

Notes

To see all options, run your program with the -help option.

Overrides: petsc4py.PETSc.Object.setFromOptions

setMatMultMethod(self, method)

 

Specifies the method used for the matMult() operation.

Parameters

method: BV.MatMultType enumerate
The method for the matMult() operation.

setMatrix(self, Mat mat, bool indef)

 

Sets the bilinear form to be used for inner products.

Parameters

mat: Mat or None
The matrix of the inner product.
indef: bool, optional
Whether the matrix is indefinite

setNumConstraints(self, nc)

 

Sets the number of constraints.

Parameters

nc: int
The number of constraints.

setOptionsPrefix(self, prefix)

 

Sets the prefix used for searching for all BV options in the database.

Parameters

prefix: string
The prefix string to prepend to all BV option requests.

Notes

A hyphen (-) must NOT be given at the beginning of the prefix name. The first character of all runtime options is AUTOMATICALLY the hyphen.

Overrides: petsc4py.PETSc.Object.setOptionsPrefix

setOrthogonalization(self, otype=None, refine=None, eta=None, block=None)

 

Specifies the method used for the orthogonalization of vectors (classical or modified Gram-Schmidt with or without refinement), and for the block-orthogonalization (simultaneous orthogonalization of a set of vectors).

Parameters

otype: BV.OrthogType enumerate, optional
The type of orthogonalization technique.
refine: BV.OrthogRefineType enumerate, optional
The type of refinement.
eta: float, optional
Parameter for selective refinement.
block: BV.OrthogBlockType enumerate, optional
The type of block orthogonalization.

Notes

The default settings work well for most problems.

The parameter eta should be a real value between 0 and 1 (or DEFAULT). The value of eta is used only when the refinement type is BV.OrthogRefineType.IFNEEDED.

When using several processors, BV.OrthogType.MGS is likely to result in bad scalability.

If the method set for block orthogonalization is GS, then the computation is done column by column with the vector orthogonalization.

setRandom(self)

 

Set the active columns of the BV to random numbers.

Notes

All active columns (except the leading ones) are modified.

setRandomColumn(self, j)

 

Set one column of the BV to random numbers.

Parameters

j: int
Column number to be set.

setRandomCond(self, condn)

 

Set the columns of a BV to random numbers, in a way that the generated matrix has a given condition number.

Parameters

condn: float
Condition number.

setRandomContext(self, Random rnd)

 

Sets the PETSc.Random object associated with the BV, to be used in operations that need random numbers.

Parameters

rnd: PETSc.Random
The random number generator context.

setRandomNormal(self)

 

Set the active columns of the BV to random numbers (with normal distribution).

Notes

All active columns (except the leading ones) are modified.

setRandomSign(self)

 

Set the entries of a BV to values 1 or -1 with equal probability.

Notes

All active columns (except the leading ones) are modified.

setSizes(self, sizes, m)

 

Sets the local and global sizes, and the number of columns.

Parameters

sizes: int or two-tuple of int
The global size N or a two-tuple (n, N) with the local and global sizes.
m: int
The number of columns.

Notes

Either n or N (but not both) can be PETSc.DECIDE or None to have it automatically set.

setSizesFromVec(self, Vec w, m)

 

Sets the local and global sizes, and the number of columns. Local and global sizes are specified indirectly by passing a template vector.

Parameters

w: Vec
The template vector.
m: int
The number of columns.

setType(self, bv_type)

 

Selects the type for the BV object.

Parameters

bv_type: BV.Type enumerate
The inner product type to be used.

view(self, Viewer viewer=None)

 

Prints the BV data structure.

Parameters

viewer: Viewer, optional
Visualization context; if not provided, the standard output is used.
Overrides: petsc4py.PETSc.Object.view