slepc4py.SLEPc.DS#
- class slepc4py.SLEPc.DS#
Bases:
ObjectDirect Solver (or Dense System).
The
DSpackage provides auxiliary routines that are internally used by the different slepc4py solvers. It is used to represent low-dimensional eigenproblems that must be solved within iterative solvers with direct methods. It can be seen as a structured wrapper to LAPACK functionality.Enumerations
To refer to one of the matrices stored internally in DS.
Indicates the parallel mode that the direct solver will use.
DS state types.
DS type.
Methods Summary
allocate(ld)Allocate memory for internal storage or matrices in DS.
appendOptionsPrefix([prefix])Append to the prefix used for searching for all DS options in the database.
cond()Compute the inf-norm condition number of the first matrix.
create([comm])Create the DS object.
destroy()Destroy the DS object.
Duplicate the DS object with the same type and dimensions.
getArray(matname)Return the array where the data is stored.
Get the block size.
Get the compact storage flag.
Get the current dimensions.
Get the extra row flag.
Get the leading dimension of the allocated matrices.
getMat(matname)Get the requested matrix as a sequential dense
Matobject.Get the method currently used in the DS.
Get the prefix used for searching for all DS options in the database.
Get the mode of operation in parallel runs.
Get the refined vectors flag.
getState()Get the current state.
getType()Get the DS type of this object.
reset()Reset the DS object.
restoreMat(matname, mat)Restore the previously seized matrix.
setBlockSize(bs)Set the block size.
setCompact(comp)Set the compact flag for storage of matrices.
setDimensions([n, l, k])Set the matrix sizes in the DS object.
setExtraRow(ext)Set a flag to indicate that the matrix has one extra row.
Set DS options from the options database.
setGSVDDimensions(m, p)setIdentity(matname)Set the identity on the active part of a matrix.
setMethod(meth)Set the method to be used to solve the problem.
setOptionsPrefix([prefix])Set the prefix used for searching for all DS options in the database.
setPEPCoefficients(pbc)setPEPDegree(deg)setParallel(pmode)Set the mode of operation in parallel runs.
setRefined(ref)Set a flag to indicate that refined vectors must be computed.
setState(state)Set the state of the DS object.
setType(ds_type)Set the type for the DS object.
solve()Solve the problem.
truncate(n[, trim])Truncate the system represented in the DS object.
Ensure that the extra row gets up-to-date after a call to
DS.solve().vectors([matname])Compute vectors associated to the dense system such as eigenvectors.
view([viewer])Print the DS data structure.
Attributes Summary
The block size.
Compact storage of matrices.
If the matrix has one extra row.
The method to be used to solve the problem.
The mode of operation in parallel runs.
If refined vectors must be computed.
The state of the DS object.
Methods Documentation
- allocate(ld)#
Allocate memory for internal storage or matrices in DS.
Logically collective.
- Parameters:
ld (int) – Leading dimension (maximum allowed dimension for the matrices, including the extra row if present).
- Return type:
Notes
If the leading dimension is different from a previously set value, then all matrices are destroyed with
reset().See also
getLeadingDimension,setDimensions,setExtraRow,reset,DSAllocate
- appendOptionsPrefix(prefix=None)#
Append to the prefix used for searching for all DS options in the database.
Logically collective.
- Parameters:
prefix (str | None) – The prefix string to prepend to all DS option requests.
- Return type:
See also
- cond()#
Compute the inf-norm condition number of the first matrix.
Logically collective.
- Returns:
Condition number.
- Return type:
See also
- create(comm=None)#
Create the DS object.
Collective.
- destroy()#
Destroy the DS object.
Collective.
See also
Source code at slepc4py/SLEPc/DS.pyx:146
- Return type:
- duplicate()#
Duplicate the DS object with the same type and dimensions.
Collective.
- Returns:
The new object.
- Return type:
Notes
This method does not copy the matrices, and the new object does not even have internal arrays allocated. Use
allocate()to use the newDS.See also
- getArray(matname)#
Return the array where the data is stored.
Not collective.
- Parameters:
matname (MatType) – The selected matrix.
- Returns:
The array.
- Return type:
See also
- getBlockSize()#
Get the block size.
Not collective.
- Returns:
The block size.
- Return type:
See also
- getCompact()#
Get the compact storage flag.
Not collective.
- Returns:
The flag.
- Return type:
See also
- getDimensions()#
Get the current dimensions.
Not collective.
- Returns:
- Return type:
Notes
The
tvalue makes sense only iftruncate()has been called. Otherwise it is equal ton.See also
setDimensions,truncate,getLeadingDimension,DSGetDimensions
- getExtraRow()#
Get the extra row flag.
Not collective.
- Returns:
The flag.
- Return type:
See also
- getGSVDDimensions()#
Get the number of columns and rows of a
DSof typeGSVD.Not collective.
- Returns:
- Return type:
See also
- getHSVDDimensions()#
Get the number of columns of a
DSof typeHSVD.Not collective.
- Returns:
The number of columns.
- Return type:
See also
- getLeadingDimension()#
Get the leading dimension of the allocated matrices.
Not collective.
- Returns:
Leading dimension (maximum allowed dimension for the matrices).
- Return type:
See also
- getMat(matname)#
Get the requested matrix as a sequential dense
Matobject.Not collective.
- Parameters:
matname (MatType) – The requested matrix.
- Returns:
The matrix.
- Return type:
Notes
The returned matrix has sizes equal to the current
DSdimensions (seesetDimensions()), and contains the values that would be obtained withgetArray(). If theDSwas truncated, then the number of rows is equal to the dimension prior to truncation, seetruncate().When no longer needed the user must call
restoreMat().See also
- getMethod()#
Get the method currently used in the DS.
Not collective.
- Returns:
Identifier of the method.
- Return type:
See also
- getOptionsPrefix()#
Get the prefix used for searching for all DS options in the database.
Not collective.
- Returns:
The prefix string set for this DS object.
- Return type:
- getPEPCoefficients()#
Get the polynomial basis coefficients of a
DSof typePEP.Not collective.
- Returns:
Coefficients.
- Return type:
See also
- getPEPDegree()#
Get the polynomial degree of a
DSof typePEP.Not collective.
- Returns:
The polynomial degree.
- Return type:
See also
- getParallel()#
Get the mode of operation in parallel runs.
Not collective.
- Returns:
The parallel mode.
- Return type:
See also
- getRefined()#
Get the refined vectors flag.
Not collective.
- Returns:
The flag.
- Return type:
See also
- getSVDDimensions()#
Get the number of columns of a
DSof typeSVD.Not collective.
- Returns:
The number of columns.
- Return type:
See also
- getState()#
Get the current state.
Not collective.
- Returns:
The current state.
- Return type:
See also
- getType()#
Get the DS type of this object.
Not collective.
- Returns:
The direct solver type currently being used.
- Return type:
- reset()#
Reset the DS object.
Collective.
Source code at slepc4py/SLEPc/DS.pyx:160
- Return type:
- restoreMat(matname, mat)#
Restore the previously seized matrix.
Not collective.
- Parameters:
matname (MatType) – The selected matrix.
mat (petsc4py.PETSc.Mat) – The matrix previously obtained with
getMat().
- Return type:
See also
- setBlockSize(bs)#
Set the block size.
Logically collective.
See also
- setCompact(comp)#
Set the compact flag for storage of matrices.
Logically collective.
Notes
Compact storage is used in some
DStypes such asDS.Type.HEPwhen the matrix is tridiagonal. This flag can be used to indicate whether the user provides the matrix entries via the compact form (the tridiagonalDS.MatType.T) or the non-compact one (DS.MatType.A).The default is
False.See also
- setDimensions(n=None, l=None, k=None)#
Set the matrix sizes in the DS object.
Logically collective.
- Parameters:
- Return type:
Notes
The internal arrays are not reallocated.
Some
DStypes have additional dimensions, e.g., the number of columns inDS.Type.SVD. For these, you should call a specific interface function.See also
- setExtraRow(ext)#
Set a flag to indicate that the matrix has one extra row.
Logically collective.
Notes
In Krylov methods it is useful that the matrix representing the direct solver has one extra row, i.e., has \((n+1)\) rows and \((n+1)\) columns. If this flag is activated, all transformations applied to the right of the matrix also affect this additional row. In that case, \((n+1)\) must be less or equal than the leading dimension.
The default is
False.See also
- setFromOptions()#
Set DS options from the options database.
Collective.
Notes
To see all options, run your program with the
-helpoption.See also
Source code at slepc4py/SLEPc/DS.pyx:294
- Return type:
- setGSVDDimensions(m, p)#
Set the number of columns and rows of a
DSof typeGSVD.Logically collective.
- Parameters:
- Return type:
Notes
This call is complementary to
setDimensions(), to provide dimensions that are specific to thisDS.Type.See also
- setHSVDDimensions(m)#
Set the number of columns of a
DSof typeHSVD.Logically collective.
Notes
This call is complementary to
setDimensions(), to provide a dimension that is specific to thisDS.Type.See also
- setIdentity(matname)#
Set the identity on the active part of a matrix.
Logically collective.
See also
- setMethod(meth)#
Set the method to be used to solve the problem.
Logically collective.
See also
- setOptionsPrefix(prefix=None)#
Set the prefix used for searching for all DS options in the database.
Logically collective.
- Parameters:
prefix (str | None) – The prefix string to prepend to all DS 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.
- setPEPCoefficients(pbc)#
Set the polynomial basis coefficients of a
DSof typePEP.Logically collective.
Notes
This function is required only in the case of a polynomial specified in a non-monomial basis, to provide the coefficients that will be used during the linearization, multiplying the identity blocks on the three main diagonal blocks. Depending on the polynomial basis (Chebyshev, Legendre, …) the coefficients must be different.
There must be a total of \(3(d+1)\) coefficients, where \(d\) is the degree of the polynomial. The coefficients are arranged in three groups, \(a_i, b_i, c_i\), according to the definition of the three-term recurrence. In the case of the monomial basis, \(a_i=1\) and \(b_i=c_i=0\), in which case it is not necessary to invoke this function.
See also
- setParallel(pmode)#
Set the mode of operation in parallel runs.
Logically collective.
- Parameters:
pmode (ParallelType) – The parallel mode.
- Return type:
See also
- setRefined(ref)#
Set a flag to indicate that refined vectors must be computed.
Logically collective.
Notes
Normally the vectors returned in
DS.MatType.Xare eigenvectors of the projected matrix. With this flag activated,vectors()will return the right singular vector of the smallest singular value of matrix \(\hat A - \eta I\), where \(\hat A\) is the extended matrix (with extra row) and \(\eta\) is the Ritz value. This is used in the refined Ritz approximation.The default is
False.See also
- setSVDDimensions(m)#
Set the number of columns of a
DSof typeSVD.Logically collective.
Notes
This call is complementary to
setDimensions(), to provide a dimension that is specific to thisDS.Type.See also
- setState(state)#
Set the state of the DS object.
Logically collective.
Notes
The state indicates that the dense system is in an initial state (raw), in an intermediate state (such as tridiagonal, Hessenberg or Hessenberg-triangular), in a condensed state (such as diagonal, Schur or generalized Schur), or in a truncated state.
The state is automatically changed in functions such as
solve()ortruncate(). This function is normally used to return to the raw state when the condensed structure is destroyed, or to indicate thatsolve()must start with a problem that already has an intermediate form.See also
- setType(ds_type)#
Set the type for the DS object.
Logically collective.
- solve()#
Solve the problem.
Logically collective.
- Returns:
Eigenvalues or singular values.
- Return type:
See also
- truncate(n, trim=False)#
Truncate the system represented in the DS object.
Logically collective.
- Parameters:
- Return type:
See also
- updateExtraRow()#
Ensure that the extra row gets up-to-date after a call to
DS.solve().Logically collective.
Perform all necessary operations so that the extra row gets up-to-date after a call to
DS.solve().See also
Source code at slepc4py/SLEPc/DS.pyx:774
- Return type:
- vectors(matname=X)#
Compute vectors associated to the dense system such as eigenvectors.
Logically collective.
- Parameters:
matname – The matrix, used to indicate which vectors are required.
- Return type:
See also
- view(viewer=None)#
Print the DS data structure.
Collective.
- Parameters:
viewer (Viewer | None) – Visualization context; if not provided, the standard output is used.
- Return type:
See also
Attributes Documentation
- block_size#
The block size.
- compact#
Compact storage of matrices.
- extra_row#
If the matrix has one extra row.
- method#
The method to be used to solve the problem.
- parallel#
The mode of operation in parallel runs.
- refined#
If refined vectors must be computed.
- state#
The state of the DS object.