slepc4py.SLEPc.BV#
- class slepc4py.SLEPc.BV#
Bases:
ObjectBasis Vectors.
The
BVpackage provides the concept of a block of vectors that represent the basis of a subspace. It is a convenient way of handling a collection of vectors that often operate together, rather than working with an array ofpetsc4py.PETSc.Vec.Enumerations
BV mat-mult types.
BV block-orthogonalization types.
BV orthogonalization refinement types.
BV orthogonalization types.
BV methods for computing the SVD.
BV type.
Methods Summary
appendOptionsPrefix([prefix])Append to the prefix used for searching for all BV options in the database.
applyMatrix(x, y)Multiply a vector with the matrix associated to the bilinear form.
copy([result])Copy a basis vector object into another one.
copyColumn(j, i)Copy the values from one of the columns to another one.
copyVec(j, v)Copy one of the columns of a basis vectors object into a Vec.
create([comm])Create the BV object.
Create a basis vectors object from a dense Mat object.
Create a new Mat object of dense type and copy the contents of the BV.
Create a Vec with the type and dimensions of the columns of the BV.
destroy()Destroy the BV object.
dot(Y)Compute the 'block-dot' product of two basis vectors objects.
dotColumn(j)Dot products of a column against all the column vectors of a BV.
dotVec(v)Dot products of a vector against all the column vectors of the BV.
Duplicate the BV object with the same type and dimensions.
Create a BV object of the same type and dimensions as an existing one.
Get the current active dimensions.
getArray([readonly])Return the array where the data is stored.
getColumn(j)Get a Vec object with the entries of the column of the BV object.
Get the tolerance to be used when checking a definite inner product.
Get the leading dimension.
getMat()Get a Mat object of dense type that shares the memory of the BV object.
Get the method used for the
matMult()operation.Get the matrix representation of the inner product.
Get the number of constraints.
Get the prefix used for searching for all BV options in the database.
Get the orthogonalization settings from the BV object.
Get the
petsc4py.PETSc.Randomobject associated with the BV.getSizes()Get the local and global sizes, and the number of columns.
getType()Get the BV type of this object.
Get the vector type used by the basis vectors object.
Insert a set of vectors as constraints.
insertVec(j, w)Insert a vector into the specified column.
insertVecs(s, W[, orth])Insert a set of vectors into specified columns.
matMult(A[, Y])Compute the matrix-vector product for each column, \(Y = A V\).
matMultColumn(A, j)Mat-vec product for a column, storing the result in the next column.
matMultHermitianTranspose(A[, Y])Pre-multiplication with the conjugate transpose of a matrix.
Conjugate-transpose matrix-vector product for a specified column.
matMultTranspose(A[, Y])Pre-multiplication with the transpose of a matrix.
matMultTransposeColumn(A, j)Transpose matrix-vector product for a specified column.
matProject(A, Y)Compute the projection of a matrix onto a subspace.
mult(alpha, beta, X, Q)Compute \(Y = beta Y + alpha X Q\).
multColumn(alpha, beta, j, q)Compute \(y = beta y + alpha X q\).
multInPlace(Q, s, e)Update a set of vectors as \(V(:,s:e-1) = V Q(:,s:e-1)\).
multVec(alpha, beta, y, q)Compute \(y = beta y + alpha X q\).
norm([norm_type])Compute the matrix norm of the BV.
normColumn(j[, norm_type])Compute the vector norm of a selected column.
orthogonalize([R])Orthogonalize all columns (except leading ones) (QR decomposition).
Orthogonalize a column vector with respect to the previous ones.
Orthogonalize a vector with respect to a set of vectors.
orthonormalizeColumn(j[, replace])Orthonormalize a column vector with respect to the previous ones.
resize(m[, copy])Change the number of columns.
restoreColumn(j, v)Restore a column obtained with
getColumn().restoreMat(A)Restore the Mat obtained with
getMat().scale(alpha)Multiply the entries by a scalar value.
scaleColumn(j, alpha)Scale column j by alpha.
setActiveColumns(l, k)Set the columns that will be involved in operations.
setDefiniteTolerance(deftol)Set the tolerance to be used when checking a definite inner product.
Set BV options from the options database.
Set the leading dimension.
setMatMultMethod(method)Set the method used for the
matMult()operation.setMatrix(mat[, indef])Set the bilinear form to be used for inner products.
Set the number of constraints.
setOptionsPrefix([prefix])Set the prefix used for searching for all BV options in the database.
setOrthogonalization([otype, refine, eta, block])Set the method used for the (block-)orthogonalization of vectors.
Set the active columns of the BV to random numbers.
Set one column of the BV to random numbers.
setRandomCond(condn)Set the columns of a BV to random numbers.
setRandomContext(rnd)Set the
petsc4py.PETSc.Randomobject associated with the BV.Set the active columns of the BV to normal random numbers.
Set the entries of a BV to values 1 or -1 with equal probability.
setSizes(sizes, m)Set the local and global sizes, and the number of columns.
setSizesFromVec(w, m)Set the local and global sizes, and the number of columns.
setType(bv_type)Set the type for the BV object.
setVecType(vec_type)Set the vector type.
view([viewer])Print the BV data structure.
Attributes Summary
Basis vectors column size.
Basis vectors local size.
Basis vectors global size.
Basis vectors local and global sizes, and the number of columns.
Methods Documentation
- appendOptionsPrefix(prefix=None)#
Append to the prefix used for searching for all BV options in the database.
Logically collective.
- applyMatrix(x, y)#
Multiply a vector with the matrix associated to the bilinear form.
Neighbor-wise collective.
Notes
If the bilinear form has no associated matrix this function copies the vector.
- copy(result=None)#
Copy a basis vector object into another one.
Logically collective.
- copyColumn(j, i)#
Copy the values from one of the columns to another one.
Logically collective.
- Parameters:
- Return type:
- copyVec(j, v)#
Copy one of the columns of a basis vectors object into a Vec.
Logically collective.
- create(comm=None)#
Create the BV object.
Collective.
- createFromMat(A)#
Create a basis vectors object from a dense Mat object.
Collective.
- createMat()#
Create a new Mat object of dense type and copy the contents of the BV.
Collective.
- Returns:
The new matrix.
- Return type:
- createVec()#
Create a Vec with the type and dimensions of the columns of the BV.
Collective.
- Returns:
New vector.
- Return type:
- destroy()#
Destroy the BV object.
Collective.
Source code at slepc4py/SLEPc/BV.pyx:187
- Return type:
- dot(Y)#
Compute the ‘block-dot’ product of two basis vectors objects.
Collective.
\(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:
The resulting matrix.
- Return type:
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(j)#
Dot products of a column against all the column vectors of a BV.
Collective.
- Parameters:
j (int) – The index of the column.
- Returns:
The computed values.
- Return type:
- dotVec(v)#
Dot products of a vector against all the column vectors of the BV.
Collective.
- Parameters:
v (Vec) – A vector.
- Returns:
The computed values.
- Return type:
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\).
- duplicate()#
Duplicate the BV object with the same type and dimensions.
Collective.
Source code at slepc4py/SLEPc/BV.pyx:246
- Return type:
- duplicateResize(m)#
Create a BV object of the same type and dimensions as an existing one.
Collective.
Notes
With possibly different number of columns.
- getActiveColumns()#
Get the current active dimensions.
Not collective.
- Returns:
- Return type:
- getArray(readonly=False)#
Return the array where the data is stored.
Not collective.
- Parameters:
readonly (bool) – Enable to obtain a read only array.
- Return type:
See also
- getColumn(j)#
Get a Vec object with the entries of the column of the BV object.
Logically collective.
- Parameters:
j (int) – The index of the requested column.
- Returns:
The vector containing the jth column.
- Return type:
Notes
Modifying the returned Vec will change the BV entries as well.
- getDefiniteTolerance()#
Get the tolerance to be used when checking a definite inner product.
Not collective.
- Returns:
The tolerance.
- Return type:
- getLeadingDimension()#
Get the leading dimension.
Not collective.
- Returns:
The leading dimension.
- Return type:
- getMat()#
Get a Mat object of dense type that shares the memory of the BV object.
Collective.
- Returns:
The matrix.
- Return type:
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()#
Get the method used for the
matMult()operation.Not collective.
- Returns:
The method for the
matMult()operation.- Return type:
- getMatrix()#
Get the matrix representation of the inner product.
Not collective.
- Returns:
mat (
petsc4py.PETSc.Mat) – The matrix of the inner productindef (
bool) – Whether the matrix is indefinite
- Return type:
- getNumConstraints()#
Get the number of constraints.
Not collective.
- Returns:
The number of constraints.
- Return type:
- getOptionsPrefix()#
Get the prefix used for searching for all BV options in the database.
Not collective.
- Returns:
The prefix string set for this BV object.
- Return type:
- getOrthogonalization()#
Get the orthogonalization settings from the BV object.
Not collective.
- Returns:
type (
OrthogType) – The type of orthogonalization technique.refine (
OrthogRefineType) – The type of refinement.eta (
float) – Parameter for selective refinement (used when the refinement type isBV.OrthogRefineType.IFNEEDED).block (
OrthogBlockType) – The type of block orthogonalization .
- Return type:
- getRandomContext()#
Get the
petsc4py.PETSc.Randomobject associated with the BV.Collective.
- Returns:
The random number generator context.
- Return type:
- getSizes()#
Get the local and global sizes, and the number of columns.
Not collective.
- Returns:
- Return type:
- getType()#
Get the BV type of this object.
Not collective.
- Returns:
The basis vectors type currently being used.
- Return type:
- getVecType()#
Get the vector type used by the basis vectors object.
Not collective.
Source code at slepc4py/SLEPc/BV.pyx:905
- Return type:
- insertConstraints(C)#
Insert a set of vectors as constraints.
Collective.
- Parameters:
C (Vec | list[Vec]) – Set of vectors to be inserted as constraints.
- Returns:
Number of constraints.
- Return type:
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(j, w)#
Insert a vector into the specified column.
Logically collective.
- Parameters:
- Return type:
- insertVecs(s, W, orth=False)#
Insert a set of vectors into specified columns.
Collective.
- Parameters:
- Returns:
Number of linearly independent vectors.
- Return type:
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(A, Y=None)#
Compute the matrix-vector product for each column, \(Y = A V\).
Neighbor-wise collective.
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(A, j)#
Mat-vec product for a column, storing the result in the next column.
Neighbor-wise collective.
\(v_{j+1} = A v_j\).
- matMultHermitianTranspose(A, Y=None)#
Pre-multiplication with the conjugate transpose of a matrix.
Neighbor-wise collective.
\(Y = A^H V\).
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(A, j)#
Conjugate-transpose matrix-vector product for a specified column.
Neighbor-wise collective.
Store the result in the next column: \(v_{j+1} = A^H v_j\).
- matMultTranspose(A, Y=None)#
Pre-multiplication with the transpose of a matrix.
Neighbor-wise collective.
\(Y = A^T V\).
Notes
Only active columns (excluding the leading ones) are processed.
- matMultTransposeColumn(A, j)#
Transpose matrix-vector product for a specified column.
Neighbor-wise collective.
Store the result in the next column: \(v_{j+1} = A^T v_j\).
- matProject(A, Y)#
Compute the projection of a matrix onto a subspace.
Collective.
\(M = Y^H A X\)
- Parameters:
A (petsc4py.PETSc.Mat | None) – Matrix to be projected.
Y (BV) – Left basis vectors, can be the same as self, giving \(M = X^H A X\).
- Returns:
Projection of the matrix A onto the subspace.
- Return type:
- mult(alpha, beta, X, Q)#
Compute \(Y = beta Y + alpha X Q\).
Logically collective.
- Parameters:
- Return type:
- multColumn(alpha, beta, j, q)#
Compute \(y = beta y + alpha X q\).
Logically collective.
Compute \(y = beta y + alpha X q\), where \(y\) is the \(j^{th}\) column.
- Parameters:
- Return type:
- multInPlace(Q, s, e)#
Update a set of vectors as \(V(:,s:e-1) = V Q(:,s:e-1)\).
Logically collective.
- Parameters:
- Return type:
- multVec(alpha, beta, y, q)#
Compute \(y = beta y + alpha X q\).
Logically collective.
- Parameters:
- Return type:
- norm(norm_type=None)#
Compute the matrix norm of the BV.
Collective.
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(j, norm_type=None)#
Compute the vector norm of a selected column.
Collective.
- Parameters:
- Returns:
The norm.
- Return type:
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^H B V_j}\), where \(B\) is the inner product matrix (argument ‘type’ is ignored).
- orthogonalize(R=None, **kargs)#
Orthogonalize all columns (except leading ones) (QR decomposition).
Collective.
Notes
The output satisfies \(V_0 = V R\) (where \(V_0\) represent the input \(V\)) and \(V' V = I\).
- orthogonalizeColumn(j)#
Orthogonalize a column vector with respect to the previous ones.
Collective.
- Parameters:
j (int) – Index of the column to be orthogonalized.
- Returns:
- Return type:
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(v)#
Orthogonalize a vector with respect to a set of vectors.
Collective.
- Parameters:
v (Vec) – Vector to be orthogonalized, modified on return.
- Returns:
- Return type:
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(j, replace=False)#
Orthonormalize a column vector with respect to the previous ones.
Collective.
This is equivalent to a call to
orthogonalizeColumn()followed by a call toscaleColumn()with the reciprocal of the norm.- Parameters:
- Returns:
- Return type:
- resize(m, copy=True)#
Change the number of columns.
Collective.
- Parameters:
- Return type:
Notes
Internal storage is reallocated. If copy is True, then the contents are copied to the leading part of the new space.
- restoreColumn(j, v)#
Restore a column obtained with
getColumn().Logically collective.
- Parameters:
j (int) – The index of the requested column.
v (Vec) – The vector obtained with
getColumn().
- Return type:
Notes
The arguments must match the corresponding call to
getColumn().
- restoreMat(A)#
Restore the Mat obtained with
getMat().Logically collective.
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(alpha)#
Multiply the entries by a scalar value.
Logically collective.
Notes
All active columns (except the leading ones) are scaled.
- scaleColumn(j, alpha)#
Scale column j by alpha.
Logically collective.
- Parameters:
- Return type:
- setActiveColumns(l, k)#
Set the columns that will be involved in operations.
Logically collective.
- Parameters:
- Return type:
- setDefiniteTolerance(deftol)#
Set the tolerance to be used when checking a definite inner product.
Logically collective.
- setFromOptions()#
Set BV options from the options database.
Collective.
Notes
To see all options, run your program with the
-helpoption.Source code at slepc4py/SLEPc/BV.pyx:508
- Return type:
- setLeadingDimension(ld)#
Set the leading dimension.
Not collective.
- setMatMultMethod(method)#
Set the method used for the
matMult()operation.Logically collective.
- Parameters:
method (MatMultType) – The method for the
matMult()operation.- Return type:
- setMatrix(mat, indef=False)#
Set the bilinear form to be used for inner products.
Collective.
- Parameters:
- Return type:
- setNumConstraints(nc)#
Set the number of constraints.
Logically collective.
- setOptionsPrefix(prefix=None)#
Set the prefix used for searching for all BV options in the database.
Logically collective.
- Parameters:
prefix (str | None) – The prefix string to prepend to all BV option requests.
- Return type:
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.
- setOrthogonalization(otype=None, refine=None, eta=None, block=None)#
Set the method used for the (block-)orthogonalization of vectors.
Logically collective.
Ortogonalization 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 (OrthogType | None) – The type of orthogonalization technique.
refine (OrthogRefineType | None) – The type of refinement.
block (OrthogBlockType | None) – The type of block orthogonalization.
- Return type:
Notes
The default settings work well for most problems.
The parameter
etashould be a real value between0and1(orDETERMINE). The value ofetais used only when the refinement type isBV.OrthogRefineType.IFNEEDED.When using several processors,
BV.OrthogType.MGSis 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()#
Set the active columns of the BV to random numbers.
Logically collective.
Notes
All active columns (except the leading ones) are modified.
Source code at slepc4py/SLEPc/BV.pyx:1581
- Return type:
- setRandomColumn(j)#
Set one column of the BV to random numbers.
Logically collective.
- setRandomCond(condn)#
Set the columns of a BV to random numbers.
Logically collective.
The generated matrix has a prescribed condition number.
- setRandomContext(rnd)#
Set the
petsc4py.PETSc.Randomobject associated with the BV.Collective.
To be used in operations that need random numbers.
- setRandomNormal()#
Set the active columns of the BV to normal random numbers.
Logically collective.
Notes
All active columns (except the leading ones) are modified.
Source code at slepc4py/SLEPc/BV.pyx:1593
- Return type:
- setRandomSign()#
Set the entries of a BV to values 1 or -1 with equal probability.
Logically collective.
Notes
All active columns (except the leading ones) are modified.
Source code at slepc4py/SLEPc/BV.pyx:1605
- Return type:
- setSizes(sizes, m)#
Set the local and global sizes, and the number of columns.
Collective.
- Parameters:
sizes (LayoutSizeSpec) – The global size
Nor a two-tuple(n, N)with the local and global sizes.m (int) – The number of columns.
- Return type:
Notes
Either
norN(but not both) can bePETSc.DECIDEorNoneto have it automatically set.
- setSizesFromVec(w, m)#
Set the local and global sizes, and the number of columns.
Collective.
Local and global sizes are specified indirectly by passing a template vector.
- setType(bv_type)#
Set the type for the BV object.
Logically collective.
- setVecType(vec_type)#
Set the vector type.
Collective.
- Parameters:
vec_type (petsc4py.PETSc.Vec.Type | str) – Vector type used when creating vectors with
createVec.- Return type:
- view(viewer=None)#
Print the BV data structure.
Collective.
Attributes Documentation
- column_size#
Basis vectors column size.
- local_size#
Basis vectors local size.
- size#
Basis vectors global size.
- sizes#
Basis vectors local and global sizes, and the number of columns.