slepc4py.SLEPc.BV — slepc4py 3.24.3 documentation

Skip to main content
`Ctrl`+`K`

# slepc4py.SLEPc.BV

class slepc4py.SLEPc.BV

  Bases: `Object`

  Basis Vectors.

  The `BV` package 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 of `petsc4py.PETSc.Vec`.

  Enumerations

  `MatMultType` | BV mat-mult types.
  `OrthogBlockType` | BV block-orthogonalization types.
  `OrthogRefineType` | BV orthogonalization refinement types.
  `OrthogType` | BV orthogonalization types.
  `SVDMethod` | BV methods for computing the SVD.
  `Type` | 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 vector.
  `create`([comm]) | Create the BV object.
  `createFromMat`(A) | Create a basis vectors object from a dense matrix.
  `createMat`() | Create a new dense matrix and copy the contents of the BV.
  `createVec`() | Create a vector 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`() | Duplicate the BV object with the same type and dimensions.
  `duplicateResize`(m) | Create a BV object of the same type and dimensions as an existing one.
  `getActiveColumns`() | Get the current active dimensions.
  `getArray`([readonly]) | Return the array where the data is stored.
  `getColumn`(j) | Get a vector with the entries of the column of the BV object.
  `getDefiniteTolerance`() | Get the tolerance to be used when checking a definite inner product.
  `getLeadingDimension`() | Get the leading dimension.
  `getMat`() | Get a matrix of dense type that shares the memory of the BV object.
  `getMatMultMethod`() | Get the method used for the `matMult()` operation.
  `getMatrix`() | Get the matrix representation of the inner product.
  `getNumConstraints`() | Get the number of constraints.
  `getOptionsPrefix`() | Get the prefix used for searching for all BV options in the database.
  `getOrthogonalization`() | Get the orthogonalization settings from the BV object.
  `getRandomContext`() | Get the `petsc4py.PETSc.Random` object associated with the BV.
  `getSizes`() | Get the local and global sizes, and the number of columns.
  `getType`() | Get the BV type of this object.
  `getVecType`() | Get the vector type used when creating vectors via `createVec()`.
  `insertConstraints`(C) | 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 the 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.
  `matMultHermitianTransposeColumn`(A, j) | 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`(delta, gamma, X, Q) | Compute \(Y = \gamma Y + \delta X Q\).
  `multColumn`(delta, gamma, j, q) | Compute \(y = \gamma y + \delta X q\).
  `multInPlace`(Q, s, e) | Update a set of vectors as \(V(:,s:e-1) = V Q(:,s:e-1)\).
  `multVec`(delta, gamma, y, q) | Compute \(y = \gamma y + \delta 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).
  `orthogonalizeColumn`(j) | Orthogonalize a column vector with respect to the previous ones.
  `orthogonalizeVec`(v) | Orthogonalize a vector with respect to all active columns.
  `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 matrix obtained with `getMat()`.
  `scale`(alpha) | Multiply the entries by a scalar value.
  `scaleColumn`(j, alpha) | Scale a column of a BV.
  `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.
  `setFromOptions`() | Set BV options from the options database.
  `setLeadingDimension`(ld) | Set the leading dimension.
  `setMatMultMethod`(method) | Set the method used for the `matMult()` operation.
  `setMatrix`(B[, indef]) | Set the bilinear form to be used for inner products.
  `setNumConstraints`(nc) | 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.
  `setRandom`() | Set the active columns of the BV to random numbers.
  `setRandomColumn`(j) | 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.Random` object associated with the BV.
  `setRandomNormal`() | Set the active columns of the BV to normal random numbers.
  `setRandomSign`() | 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 to be used when creating vectors via `createVec()`.
  `view`([viewer]) | Print the BV data structure.

  Attributes Summary

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

  Methods Documentation

  appendOptionsPrefix(prefix=None)

    Append to 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:

      None

    See also

    `setOptionsPrefix`, `getOptionsPrefix`, `BVAppendOptionsPrefix`

    Source code at slepc4py/SLEPc/BV.pyx:618

  applyMatrix(x, y)

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

    Neighbor-wise collective.

    Parameters:

      - x (Vec) – The input vector.

      - y (Vec) – The result vector.

    Return type:

      None

    Notes

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

    See also

    `setMatrix`, `BVApplyMatrix`

    Source code at slepc4py/SLEPc/BV.pyx:863

  copy(result=None)

    Copy a basis vector object into another one.

    Logically collective.

    Returns:

      The copy.

    Return type:

      `BV`

    Parameters:

      result (BV | None) – The copy.

    Notes

    Both objects must be distributed in the same manner; local copies are done. Only active columns (excluding the leading ones) are copied. In the destination BV, columns are overwritten starting from the leading ones. Constraints are not copied.

    See also

    `BVCopy`

    Source code at slepc4py/SLEPc/BV.pyx:354

  copyColumn(j, i)

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

    Logically collective.

    Parameters:

      - j (int) – The index of the source column.

      - i (int) – The index of the destination column.

    Return type:

      None

    See also

    `copy`, `copyVec`, `BVCopyColumn`

    Source code at slepc4py/SLEPc/BV.pyx:1235

  copyVec(j, v)

    Copy one of the columns of a basis vectors object into a vector.

    Logically collective.

    Parameters:

      - j (int) – The column index to be copied.

      - v (Vec) – A vector.

    Return type:

      None

    Notes

    The BV and `v` must be distributed in the same manner; local copies are done.

    See also

    `copy`, `copyColumn`, `BVCopyVec`

    Source code at slepc4py/SLEPc/BV.pyx:1210

  create(comm=None)

    Create the BV object.

    Collective.

    Parameters:

      comm (Comm | None) – MPI communicator; if not provided, it defaults to all processes.

    Return type:

      Self

    See also

    `createFromMat`, `BVCreate`

    Source code at slepc4py/SLEPc/BV.pyx:225

  createFromMat(A)

    Create a basis vectors object from a dense matrix.

    Collective.

    Parameters:

      A (Mat) – A dense tall-skinny matrix.

    Return type:

      Self

    Notes

    The matrix values are copied to the `BV` data storage, memory is not shared.

    The communicator of the `BV` object will be the same as `A`, and so will be the dimensions.

    See also

    `create`, `createMat`, `BVCreateFromMat`

    Source code at slepc4py/SLEPc/BV.pyx:247

  createMat()

    Create a new dense matrix and copy the contents of the BV.

    Collective.

    Returns:

      The new matrix.

    Return type:

      `petsc4py.PETSc.Mat`

    Notes

    The matrix contains all columns of the `BV`, not just the active columns.

    See also

    `createFromMat`, `createVec`, `getMat`, `BVCreateMat`

    Source code at slepc4py/SLEPc/BV.pyx:275

  createVec()

    Create a vector with the type and dimensions of the columns of the BV.

    Collective.

    Returns:

      New vector.

    Return type:

      `petsc4py.PETSc.Vec`

    See also

    `createMat`, `setVecType`, `BVCreateVec`

    Source code at slepc4py/SLEPc/BV.pyx:1147

  destroy()

    Destroy the BV object.

    Collective.

    See also

    `BVDestroy`

    Source code at slepc4py/SLEPc/BV.pyx:211

    Return type:

      Self

  dot(Y)

    Compute the ‘block-dot’ product of two basis vectors objects.

    Collective.

    \(M = Y^* X\) \((m_{ij} = y_i^* x_j)\) or \(M = Y^* B X\)

    Parameters:

      Y (BV) – Left basis vectors, can be the same as self, giving \(M = X^* X\).

    Returns:

      The resulting matrix.

    Return type:

      `petsc4py.PETSc.Mat`

    Notes

    This is the generalization of `Vec.dot()` for a collection of vectors, \(M = Y^* X\). The result is a matrix \(M\) whose entry \(m_{ij}\) is equal to \(y_i^* x_j\) (where \(y_i^*\) 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^* B X\). In this case, both \(X\) and \(Y\) must have the same associated matrix.

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

    See also

    `dotVec`, `dotColumn`, `setActiveColumns`, `setMatrix`, `BVDot`

    Source code at slepc4py/SLEPc/BV.pyx:1500

  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:

      `ArrayScalar`

    Notes

    This operation is equivalent to `dotVec()` but it uses column `j` of the BV rather than taking a vector as an argument. The number of active columns of the BV is set to `j` before the computation, and restored afterwards. If the BV has leading columns specified, then these columns do not participate in the computation. Therefore, the length of the returned array will be `j` minus the number of leading columns.

    See also

    `dot`, `dotVec`, `BVDotColumn`

    Source code at slepc4py/SLEPc/BV.pyx:1344

  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:

      `ArrayScalar`

    Notes

    This is analogue to `Vec.mDot()`, but using `BV` to represent a collection of vectors `X`. The result is \(m = X^* v\), so \(m_i\) is equal to \(x_j^* v\). Note that here \(X\) is transposed as opposed to `dot()`.

    If a non-standard inner product has been specified with `setMatrix()`, then the result is \(m = X^* B v\).

    See also

    `dot`, `dotColumn`, `setMatrix`, `BVDotVec`

    Source code at slepc4py/SLEPc/BV.pyx:1304

  duplicate()

    Duplicate the BV object with the same type and dimensions.

    Collective.

    Returns:

      The new object.

    Return type:

      `BV`

    Notes

    This function does not copy the entries, it just allocates the storage for the new `BV`. Use `copy()` to copy the content.

    See also

    `duplicateResize`, `BVDuplicate`

    Source code at slepc4py/SLEPc/BV.pyx:299

  duplicateResize(m)

    Create a BV object of the same type and dimensions as an existing one.

    Collective.

    Parameters:

      m (int) – The number of columns.

    Returns:

      The new object.

    Return type:

      `BV`

    Notes

    This is equivalent to a call to `duplicate()` followed by `resize()` with possibly different number of columns. The contents of this `BV` are not copied to the new one.

    See also

    `duplicate`, `resize`, `BVDuplicateResize`

    Source code at slepc4py/SLEPc/BV.pyx:323

  getActiveColumns()

    Get the current active dimensions.

    Not collective.

    Returns:

      - l (`int`) – The leading number of columns.

      - k (`int`) – The active number of columns.

    Return type:

      tuple[int, int]

    See also

    `setActiveColumns`, `BVGetActiveColumns`

    Source code at slepc4py/SLEPc/BV.pyx:924

  getArray(readonly=False)

    Return the array where the data is stored.

    Not collective.

    Parameters:

      readonly (bool) – Enable to obtain a read only array.

    Returns:

      The array.

    Return type:

      `ArrayScalar`

    See also

    `BVGetArray`, `BVGetArrayRead`

    Source code at slepc4py/SLEPc/BV.pyx:546

  getColumn(j)

    Get a vector 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 `j`-th column.

    Return type:

      `petsc4py.PETSc.Vec`

    Notes

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

    The returned vector must not be destroyed, `restoreColumn()` must be called when it is no longer needed. At most, two columns can be fetched, that is, this function can only be called twice before the corresponding `restoreColumn()` is invoked.

    A negative index `j` selects the `i`-th constraint, where `i=-j`. Constraints should not be modified.

    See also

    `restoreColumn`, `insertConstraints`, `BVGetColumn`

    Source code at slepc4py/SLEPc/BV.pyx:1384

  getDefiniteTolerance()

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

    Not collective.

    Returns:

      The tolerance.

    Return type:

      `float`

    See also

    `setDefiniteTolerance`, `BVGetDefiniteTolerance`

    Source code at slepc4py/SLEPc/BV.pyx:1285

  getLeadingDimension()

    Get the leading dimension.

    Not collective.

    Returns:

      The leading dimension.

    Return type:

      `int`

    Notes

    The returned value may be different in different processes.

    The leading dimension must be used when accessing the internal array via `getArray()`.

    See also

    `setLeadingDimension`, `BVGetLeadingDimension`

    Source code at slepc4py/SLEPc/BV.pyx:520

  getMat()

    Get a matrix of dense type that shares the memory of the BV object.

    Collective.

    Returns:

      The matrix.

    Return type:

      `petsc4py.PETSc.Mat`

    Notes

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

    This operation implies a call to `getArray()`, which may result in data copies.

    See also

    `restoreMat`, `createMat`, `getArray`, `BVGetMat`

    Source code at slepc4py/SLEPc/BV.pyx:1447

  getMatMultMethod()

    Get the method used for the `matMult()` operation.

    Not collective.

    Returns:

      The method for the `matMult()` operation.

    Return type:

      `MatMultType`

    See also

    `matMult`, `setMatMultMethod`, `BVGetMatMultMethod`

    Source code at slepc4py/SLEPc/BV.pyx:760

  getMatrix()

    Get the matrix representation of the inner product.

    Not collective.

    Returns:

      - B (`petsc4py.PETSc.Mat`) – The matrix of the inner product.

      - indef (`bool`) – Whether the matrix is indefinite.

    Return type:

      tuple[Mat, bool] | tuple[None, bool]

    See also

    `setMatrix`, `BVGetMatrix`

    Source code at slepc4py/SLEPc/BV.pyx:799

  getNumConstraints()

    Get the number of constraints.

    Not collective.

    Returns:

      The number of constraints.

    Return type:

      `int`

    See also

    `insertConstraints`, `setNumConstraints`, `BVGetNumConstraints`

    Source code at slepc4py/SLEPc/BV.pyx:1128

  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:

      `str`

    See also

    `setOptionsPrefix`, `appendOptionsPrefix`, `BVGetOptionsPrefix`

    Source code at slepc4py/SLEPc/BV.pyx:637

  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 is `IFNEEDED`).

      - block (`OrthogBlockType`) – The type of block orthogonalization.

    Return type:

      tuple[OrthogType, OrthogRefineType, float, OrthogBlockType]

    See also

    `setOrthogonalization`, `BVGetOrthogonalization`

    Source code at slepc4py/SLEPc/BV.pyx:675

  getRandomContext()

    Get the `petsc4py.PETSc.Random` object associated with the BV.

    Collective.

    Returns:

      The random number generator context.

    Return type:

      `petsc4py.PETSc.Random`

    See also

    `setRandomContext`, `BVGetRandomContext`

    Source code at slepc4py/SLEPc/BV.pyx:2133

  getSizes()

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

    Not collective.

    Returns:

      - (n, N) (`tuple` of `int`) – The local and global sizes.

      - m (`int`) – The number of columns.

    Return type:

      tuple[LayoutSizeSpec, int]

    See also

    `setSizes`, `setSizesFromVec`, `BVGetSizes`

    Source code at slepc4py/SLEPc/BV.pyx:477

  getType()

    Get the BV type of this object.

    Not collective.

    Returns:

      The basis vectors type currently being used.

    Return type:

      `str`

    See also

    `setType`, `BVGetType`

    Source code at slepc4py/SLEPc/BV.pyx:407

  getVecType()

    Get the vector type used when creating vectors via `createVec()`.

    Not collective.

    Returns:

      The vector type.

    Return type:

      `str`

    See also

    `createVec`, `setVecType`, `BVGetVecType`

    Source code at slepc4py/SLEPc/BV.pyx:1191

  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 linearly independent constraints.

    Return type:

      `int`

    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.

    Constraints are not stored in regular columns, but in a special part of the storage. They can be accessed with negative indices in `getColumn()`.

    This operation is DESTRUCTIVE, meaning that all data contained in the columns of the BV is lost. This is typically invoked just after creating the BV. Once a set of constraints has been set, it is not allowed to call this function again.

    The vectors are copied one by one and then orthogonalized against the previous ones. If any of them is linearly dependent then it is discarded and not counted in the return value. The behavior is similar to `insertVecs()`.

    See also

    `insertVecs`, `setNumConstraints`, `BVInsertConstraints`

    Source code at slepc4py/SLEPc/BV.pyx:1051

  insertVec(j, w)

    Insert a vector into the specified column.

    Logically collective.

    Parameters:

      - j (int) – The column to be overwritten.

      - w (Vec) – The vector to be copied.

    Return type:

      None

    See also

    `insertVecs`, `BVInsertVec`

    Source code at slepc4py/SLEPc/BV.pyx:988

  insertVecs(s, W, orth=False)

    Insert a set of vectors into the specified columns.

    Collective.

    Parameters:

      - s (int) – The first column to be overwritten.

      - W (Vec | list[Vec]) – Set of vectors to be copied.

      - orth (bool) – Flag indicating if the vectors must be orthogonalized.

    Returns:

      Number of linearly independent vectors.

    Return type:

      `int`

    Notes

    Copies the contents of vectors `W` into the BV columns `s:s+n`, where `n` is the length of `W`. If `orth` is set, then the vectors are copied one by one and then orthogonalized against the previous one. If any of them is linearly dependent then it is discarded and the not counted in the return value.

    See also

    `insertVec`, `orthogonalizeColumn`, `BVInsertVecs`

    Source code at slepc4py/SLEPc/BV.pyx:1008

  matMult(A, Y=None)

    Compute the matrix-vector product for each column, \(Y = A V\).

    Neighbor-wise collective.

    Parameters:

      - A (Mat) – The matrix.

      - Y (BV | None)

    Returns:

      The result.

    Return type:

      `BV`

    Notes

    Only active columns (excluding the leading ones) are processed. If `Y` is `None` a new BV is created.

    It is possible to choose whether the computation is done column by column or as a dense matrix-matrix product with `setMatMultMethod()`.

    See also

    `copy`, `matMultColumn`, `matMultTranspose`, `setMatMultMethod`, `BVMatMult`

    Source code at slepc4py/SLEPc/BV.pyx:1598

  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\).

    Parameters:

      - A (Mat) – The matrix.

      - j (int) – Index of column.

    Return type:

      None

    See also

    `matMult`, `BVMatMultColumn`

    Source code at slepc4py/SLEPc/BV.pyx:1743

  matMultHermitianTranspose(A, Y=None)

    Pre-multiplication with the conjugate transpose of a matrix.

    Neighbor-wise collective.

    \(Y = A^* V\).

    Parameters:

      - A (Mat) – The matrix.

      - Y (BV | None)

    Returns:

      The result.

    Return type:

      `BV`

    Notes

    Only active columns (excluding the leading ones) are processed. If `Y` is `None` a new BV is created.

    See also

    `matMult`, `matMultHermitianTransposeColumn`, `BVMatMultHermitianTranspose`

    Source code at slepc4py/SLEPc/BV.pyx:1695

  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^* v_j\).

    Parameters:

      - A (Mat) – The matrix.

      - j (int) – Index of column.

    Return type:

      None

    See also

    `matMultColumn`, `BVMatMultHermitianTransposeColumn`

    Source code at slepc4py/SLEPc/BV.pyx:1787

  matMultTranspose(A, Y=None)

    Pre-multiplication with the transpose of a matrix.

    Neighbor-wise collective.

    \(Y = A^T V\).

    Parameters:

      - A (Mat) – The matrix.

      - Y (BV | None)

    Returns:

      The result.

    Return type:

      `BV`

    Notes

    Only active columns (excluding the leading ones) are processed. If `Y` is `None` a new BV is created.

    See also

    `matMult`, `matMultTransposeColumn`, `BVMatMultTranspose`

    Source code at slepc4py/SLEPc/BV.pyx:1647

  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\).

    Parameters:

      - A (Mat) – The matrix.

      - j (int) – Index of column.

    Return type:

      None

    See also

    `matMultColumn`, `BVMatMultTransposeColumn`

    Source code at slepc4py/SLEPc/BV.pyx:1765

  matProject(A, Y)

    Compute the projection of a matrix onto a subspace.

    Collective.

    \(M = Y^* A X\)

    Parameters:

      - A (Mat | None) – Matrix to be projected.

      - Y (BV) – Left basis vectors, can be the same as self, giving \(M = X^* A X\).

    Returns:

      Projection of the matrix `A` onto the subspace.

    Return type:

      `petsc4py.PETSc.Mat`

    Notes

    If `A` is `None`, then it is assumed that the BV already contains \(AX\).

    This operation is similar to `dot()`, with important differences. The goal is to compute the matrix resulting from the orthogonal projection of `A` onto the subspace spanned by the columns of the BV, \(M = X^*AX\), or the oblique projection onto the BV along the second one `Y`, \(M = Y^*AX\).

    A difference with respect to `dot()` is that the standard inner product is always used, regardless of a non-standard inner product being specified with `setMatrix()`.

    See also

    `dot`, `setActiveColumns`, `setMatrix`, `BVMatProject`

    Source code at slepc4py/SLEPc/BV.pyx:1549

  mult(delta, gamma, X, Q)

    Compute \(Y = \gamma Y + \delta X Q\).

    Logically collective.

    Parameters:

      - delta (Scalar) – Coefficient that multiplies `X`.

      - gamma (Scalar) – Coefficient that multiplies self (`Y`).

      - X (BV) – Input basis vectors.

      - Q (Mat | None) – Input matrix, if not given the identity matrix is assumed.

    Return type:

      None

    Notes

    `X` must be different from self (`Y`). The case `X=Y` can be addressed with `multInPlace()`.

    See also

    `multVec`, `multColumn`, `multInPlace`, `BVMult`

    Source code at slepc4py/SLEPc/BV.pyx:1809

  multColumn(delta, gamma, j, q)

    Compute \(y = \gamma y + \delta X q\).

    Logically collective.

    Compute \(y = \gamma y + \delta X q\), where \(y\) is the `j`-th column.

    Parameters:

      - delta (Scalar) – Coefficient that multiplies self (`X`).

      - gamma (Scalar) – Coefficient that multiplies \(y\).

      - j (int) – The column index.

      - q (Sequence[Scalar]) – Input coefficients.

    Return type:

      None

    See also

    `mult`, `multVec`, `multInPlace`, `BVMultColumn`

    Source code at slepc4py/SLEPc/BV.pyx:1863

  multInPlace(Q, s, e)

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

    Logically collective.

    Parameters:

      - Q (Mat) – A sequential dense matrix.

      - s (int) – First column to be overwritten.

      - e (int) – Last column to be overwritten.

    Return type:

      None

    See also

    `mult`, `multVec`, `BVMultInPlace`

    Source code at slepc4py/SLEPc/BV.pyx:1840

  multVec(delta, gamma, y, q)

    Compute \(y = \gamma y + \delta X q\).

    Logically collective.

    Parameters:

      - delta (Scalar) – Coefficient that multiplies self (`X`).

      - gamma (Scalar) – Coefficient that multiplies `y`.

      - y (Vec) – Input/output vector.

      - q (Sequence[Scalar]) – Input coefficients.

    Return type:

      None

    See also

    `mult`, `multColumn`, `multInPlace`, `BVMultVec`

    Source code at slepc4py/SLEPc/BV.pyx:1898

  norm(norm_type=None)

    Compute the matrix norm of the BV.

    Collective.

    Parameters:

      norm_type (NormType | None) – The norm type.

    Returns:

      The norm.

    Return type:

      `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 `setMatrix()`.

    See also

    `normColumn`, `setMatrix`, `BVNorm`

    Source code at slepc4py/SLEPc/BV.pyx:1967

  normColumn(j, norm_type=None)

    Compute the vector norm of a selected column.

    Collective.

    Parameters:

      - j (int) – Index of column.

      - norm_type (NormType | None) – The norm type.

    Returns:

      The norm.

    Return type:

      `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 `setMatrix()`, then the returned value is \(\sqrt{v_j^* B v_j}\), where \(B\) is the inner product matrix (argument ‘norm_type’ is ignored).

    See also

    `norm`, `setMatrix`, `BVNormColumn`

    Source code at slepc4py/SLEPc/BV.pyx:1929

  orthogonalize(R=None, **kargs)

    Orthogonalize all columns (except leading ones) (QR decomposition).

    Collective.

    Parameters:

      - R (Mat | None) – A sequential dense matrix.

      - kargs (Any)

    Return type:

      None

    Notes

    The output satisfies \(V_0 = V R\) (where \(V_0\) represent the input \(V\)) and \(V^* V = I\) (or \(V^*BV=I\) if an inner product matrix \(B\) has been specified with `setMatrix()`).

    See also

    `orthogonalizeColumn`, `setMatrix`, `setOrthogonalization`, `BVOrthogonalize`

    Source code at slepc4py/SLEPc/BV.pyx:2263

  orthogonalizeColumn(j)

    Orthogonalize a column vector with respect to the previous ones.

    Collective.

    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.

    Return type:

      tuple[float, bool]

    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.

    See also

    `orthogonalizeVec`, `setOrthogonalization`

    Source code at slepc4py/SLEPc/BV.pyx:2189

  orthogonalizeVec(v)

    Orthogonalize a vector with respect to all active columns.

    Collective.

    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.

    Return type:

      tuple[float, bool]

    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.

    See also

    `orthogonalizeColumn`, `setOrthogonalization`

    Source code at slepc4py/SLEPc/BV.pyx:2153

  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 to `scaleColumn()` with the reciprocal of the norm.

    Parameters:

      - j (int) – Index of the column to be orthonormalized.

      - replace (bool) – 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.

    Return type:

      tuple[float, bool]

    See also

    `orthogonalizeColumn`, `setOrthogonalization`

    Source code at slepc4py/SLEPc/BV.pyx:2227

  resize(m, copy=True)

    Change the number of columns.

    Collective.

    Parameters:

      - m (int) – The new number of columns.

      - copy (bool) – A flag indicating whether current values should be kept.

    Return type:

      None

    Notes

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

    See also

    `setSizes`, `setSizesFromVec`, `BVResize`

    Source code at slepc4py/SLEPc/BV.pyx:2002

  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:

      None

    Notes

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

    See also

    `getColumn`, `BVRestoreColumn`

    Source code at slepc4py/SLEPc/BV.pyx:1422

  restoreMat(A)

    Restore the matrix obtained with `getMat()`.

    Logically collective.

    Parameters:

      A (Mat) – The matrix obtained with `getMat()`.

    Return type:

      None

    Notes

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

    See also

    `getMat`, `BVRestoreMat`

    Source code at slepc4py/SLEPc/BV.pyx:1476

  scale(alpha)

    Multiply the entries by a scalar value.

    Logically collective.

    Parameters:

      alpha (Scalar) – scaling factor.

    Return type:

      None

    Notes

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

    See also

    `scaleColumn`, `setActiveColumns`, `BVScale`

    Source code at slepc4py/SLEPc/BV.pyx:966

  scaleColumn(j, alpha)

    Scale a column of a BV.

    Logically collective.

    Parameters:

      - j (int) – column index to be scaled.

      - alpha (Scalar) – scaling factor.

    Return type:

      None

    See also

    `scale`, `BVScaleColumn`

    Source code at slepc4py/SLEPc/BV.pyx:945

  setActiveColumns(l, k)

    Set the columns that will be involved in operations.

    Logically collective.

    Parameters:

      - l (int) – The leading number of columns.

      - k (int) – The active number of columns.

    Return type:

      None

    Notes

    In operations such as `mult()` or `dot()`, only the first `k` columns are considered. This is useful when the BV is filled from left to right, so the last `m-k` columns do not have relevant information.

    Also in operations such as `mult()` or `dot()`, the first `l` columns are normally not included in the computation.

    In orthogonalization operations, the first `l` columns are treated differently, they participate in the orthogonalization but the computed coefficients are not stored.

    Use `CURRENT` to leave any of the values unchanged. Use `DETERMINE` to set `l` to the minimum value (`0`) and `k` to the maximum (`m`).

    See also

    `getActiveColumns`, `setSizes`, `BVSetActiveColumns`

    Source code at slepc4py/SLEPc/BV.pyx:887

  setDefiniteTolerance(deftol)

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

    Logically collective.

    Parameters:

      deftol (float) – The tolerance.

    Return type:

      None

    Notes

    When using a non-standard inner product, see `setMatrix()`, the solver needs to compute \(\sqrt{z^*B z}\) for various vectors \(z\). If the inner product has not been declared indefinite, the value \(z^*B z\) must be positive, but due to rounding error a tiny value may become negative. A tolerance is used to detect this situation. Likewise, in complex arithmetic \(z^*B z\) should be real, and we use the same tolerance to check whether a nonzero imaginary part can be considered negligible.

    See also

    `setMatrix`, `getDefiniteTolerance`, `BVSetDefiniteTolerance`

    Source code at slepc4py/SLEPc/BV.pyx:1256

  setFromOptions()

    Set BV options from the options database.

    Collective.

    Notes

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

    See also

    `setOptionsPrefix`, `BVSetFromOptions`

    Source code at slepc4py/SLEPc/BV.pyx:656

    Return type:

      None

  setLeadingDimension(ld)

    Set the leading dimension.

    Not collective.

    Parameters:

      ld (int) – The leading dimension.

    Return type:

      None

    Notes

    This parameter is relevant for a BV of `BV.Type.MAT`.

    See also

    `getLeadingDimension`, `BVSetLeadingDimension`

    Source code at slepc4py/SLEPc/BV.pyx:498

  setMatMultMethod(method)

    Set the method used for the `matMult()` operation.

    Logically collective.

    Parameters:

      method (MatMultType) – The method for the `matMult()` operation.

    Return type:

      None

    See also

    `matMult`, `getMatMultMethod`, `BVSetMatMultMethod`

    Source code at slepc4py/SLEPc/BV.pyx:779

  setMatrix(B, indef=False)

    Set the bilinear form to be used for inner products.

    Collective.

    Parameters:

      - B (Mat | None) – The matrix of the inner product.

      - indef (bool) – Whether the matrix is indefinite.

    Return type:

      None

    Notes

    This is used to specify a non-standard inner product, whose matrix representation is given by `B`. Then, all inner products required during orthogonalization are computed as \((x,y)_B=y^*Bx\) rather than the standard form \((x,y)=y^*x\).

    Matrix `B` must be real symmetric (or complex Hermitian). A genuine inner product requires that `B` is also positive (semi-)definite. However, we also allow for an indefinite `B` (setting `indef=True`), in which case the orthogonalization uses an indefinite inner product.

    This affects operations `dot()`, `norm()`, `orthogonalize()`, and variants.

    Omitting `B` has the same effect as if the identity matrix was passed.

    See also

    `getMatrix`, `BVSetMatrix`

    Source code at slepc4py/SLEPc/BV.pyx:825

  setNumConstraints(nc)

    Set the number of constraints.

    Logically collective.

    Parameters:

      nc (int) – The number of constraints.

    Return type:

      None

    Notes

    This function sets the number of constraints to `nc` and marks all remaining columns as regular. Normal usage would be to call `insertConstraints()` instead.

    If `nc` is smaller than the previously set value, then some of the constraints are discarded. In particular, using `nc=0` removes all constraints preserving the content of regular columns.

    See also

    `insertConstraints`, `getNumConstraints`, `BVSetNumConstraints`

    Source code at slepc4py/SLEPc/BV.pyx:1101

  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:

      None

    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.

    See also

    `appendOptionsPrefix`, `getOptionsPrefix`, `BVGetOptionsPrefix`

    Source code at slepc4py/SLEPc/BV.pyx:593

  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.

      - eta (float | None) – Parameter for selective refinement.

      - block (OrthogBlockType | None) – The type of block orthogonalization.

    Return type:

      None

    Notes

    The default settings work well for most problems.

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

    When using several processes, `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.

    See also

    `getOrthogonalization`, `BVSetOrthogonalization`

    Source code at slepc4py/SLEPc/BV.pyx:704

  setRandom()

    Set the active columns of the BV to random numbers.

    Logically collective.

    Notes

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

    See also

    `setRandomContext`, `setRandomColumn`, `setRandomNormal`, `BVSetRandom`

    Source code at slepc4py/SLEPc/BV.pyx:2028

    Return type:

      None

  setRandomColumn(j)

    Set one column of the BV to random numbers.

    Logically collective.

    Parameters:

      j (int) – Column index to be set.

    Return type:

      None

    See also

    `setRandomContext`, `setRandom`, `setRandomNormal`, `BVSetRandomColumn`

    Source code at slepc4py/SLEPc/BV.pyx:2076

  setRandomCond(condn)

    Set the columns of a BV to random numbers.

    Logically collective.

    The generated matrix has a prescribed condition number.

    Parameters:

      condn (float) – Condition number.

    Return type:

      None

    See also

    `setRandomContext`, `setRandomSign`, `setRandomNormal`, `BVSetRandomCond`

    Source code at slepc4py/SLEPc/BV.pyx:2094

  setRandomContext(rnd)

    Set the `petsc4py.PETSc.Random` object associated with the BV.

    Collective.

    To be used in operations that need random numbers.

    Parameters:

      rnd (Random) – The random number generator context.

    Return type:

      None

    See also

    `getRandomContext`, `setRandom`, `setRandomColumn`, `BVSetRandomContext`

    Source code at slepc4py/SLEPc/BV.pyx:2114

  setRandomNormal()

    Set the active columns of the BV to normal random numbers.

    Logically collective.

    Notes

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

    See also

    `setRandomContext`, `setRandom`, `setRandomSign`, `BVSetRandomNormal`

    Source code at slepc4py/SLEPc/BV.pyx:2044

    Return type:

      None

  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.

    See also

    `setRandomContext`, `setRandom`, `setRandomNormal`, `BVSetRandomSign`

    Source code at slepc4py/SLEPc/BV.pyx:2060

    Return type:

      None

  setSizes(sizes, m)

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

    Collective.

    Parameters:

      - sizes (LayoutSizeSpec) – The global size `N` or a two-tuple `(n, N)` with the local and global sizes.

      - m (int) – The number of columns.

    Return type:

      None

    Notes

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

    See also

    `setSizesFromVec`, `getSizes`, `BVSetSizes`

    Source code at slepc4py/SLEPc/BV.pyx:426

  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.

    Parameters:

      - w (Vec) – The template vector.

      - m (int) – The number of columns.

    Return type:

      None

    See also

    `setSizes`, `getSizes`, `BVSetSizesFromVec`

    Source code at slepc4py/SLEPc/BV.pyx:454

  setType(bv_type)

    Set the type for the BV object.

    Logically collective.

    Parameters:

      bv_type (Type | str) – The basis vectors type to be used.

    Return type:

      None

    See also

    `getType`, `BVSetType`

    Source code at slepc4py/SLEPc/BV.pyx:388

  setVecType(vec_type)

    Set the vector type to be used when creating vectors via `createVec()`.

    Collective.

    Parameters:

      vec_type (petsc4py.PETSc.Vec.Type | str) – Vector type used when creating vectors with `createVec`.

    Return type:

      None

    Notes

    This is not needed if the BV object is set up with `setSizesFromVec()`, but may be required in the case of `setSizes()` if one wants to work with non-standard vectors.

    See also

    `createVec`, `getVecType`, `setSizes`, `setSizesFromVec`, `BVSetVecType`

    Source code at slepc4py/SLEPc/BV.pyx:1166

  view(viewer=None)

    Print the BV data structure.

    Collective.

    Parameters:

      viewer (Viewer | None) – Visualization context; if not provided, the standard output is used.

    Return type:

      None

    See also

    `BVView`

    Source code at slepc4py/SLEPc/BV.pyx:192

  Attributes Documentation

  column_size

    Basis vectors column size.

    Source code at slepc4py/SLEPc/BV.pyx:2305

  local_size

    Basis vectors local size.

    Source code at slepc4py/SLEPc/BV.pyx:2300

  size

    Basis vectors global size.

    Source code at slepc4py/SLEPc/BV.pyx:2295

  sizes

    Basis vectors local and global sizes, and the number of columns.

    Source code at slepc4py/SLEPc/BV.pyx:2290