Package slepc4py :: Module SLEPc :: Class BV

[hide private]
[frames] | no frames]

# type BV

BV

Nested Classes | [hide private]

BlockType BV block-orthogonalization 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) |

create(self, comm=None) Creates the BV object. |

createMat(self) Creates a new Mat object of dense type and copies the contents of the BV 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 |

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

getActiveColumns(self) Returns the current active dimensions. |

getColumn(self, int j) Returns a Vec object that contains the entries of the requested column of the basis vectors object. |

getMatrix(self) Retrieves the matrix representation of the inner product. |

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

getSizes(self) Returns the local and global sizes, and the number of columns. |

getType(self) Gets the BV type of this object. |

insertVec(self, int j, Vec w) Insert a vector into the specified column. |

insertVecs(self, int 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. |

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

matProject(self, Mat A, BV Y) Computes the projection of a matrix onto a subspace. |

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

orthogonalizeVec(self, Vec v) Orthogonalize a vector with respect to a set of vectors. |

resize(self, m, copy=True) Change the number of columns. |

restoreColumn(self, int j, Vec v) Restore a column obtained with BVGetColumn(). |

scale(self, alpha) Multiply the entries by a scalar value. |

scaleColumn(self, int j, alpha) Scale column j by alpha |

setActiveColumns(self, int l, int k) Specify the columns that will be involved in operations. |

setFromOptions(self) Sets BV options from the options database. |

setMatrix(self, Mat mat, bool indef) Sets the bilinear form to be used for inner products. |

setOptionsPrefix(self, prefix) Sets the prefix used for searching for all BV options in the database. |

setOrthogonalization(self, type=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 BV to random numbers. |

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`

Properties | [hide private]

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

Method Details | [hide private]

### __new__(S, ...)

Returns: a new object with type S, a subtype of T
Overrides: petsc4py.PETSc.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.

### create(self, comm=None)

Creates the BV object.

# Parameters

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

### createMat(self)

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

# Returns

mat: the new matrix.

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

### 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: Vec
  A vector with the results.

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.

### getActiveColumns(self)

Returns the current active dimensions.

# Returns

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

### getColumn(self, int 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.

### getMatrix(self)

Retrieves the matrix representation of the inner product.

# Returns

mat: the matrix of the inner product

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

### 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

### insertVec(self, int 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, int 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.

### 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().

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

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

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

# Parameter

alpha: scalar beta: scalar q: scalar or sequence of scalars

# Return

y: Vec
  The result.

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

### 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: boolean
  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.

### resize(self, m, copy=True)

Change the number of columns.

# Parameters

m - the new number of columns. copy - 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, int j, Vec v)

Restore a column obtained with BVGetColumn().

# Parameters

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

# Notes

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

### 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, int j, alpha)

Scale column j by alpha

# Parameters

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

### setActiveColumns(self, int l, int 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.

### 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

### 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

### 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, type=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

type: 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 BV to random numbers.

# 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