slepc4py.SLEPc.DS#

class slepc4py.SLEPc.DS#

Bases: Object

Direct Solver (or Dense System).

The DS package 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

`MatType`	To refer to one of the matrices stored internally in DS.
`ParallelType`	DS parallel types.
`StateType`	DS state types.
`Type`	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`()	Duplicate the DS object with the same type and dimensions.
`getArray`(matname)	Return the array where the data is stored.
`getBlockSize`()	Get the block size.
`getCompact`()	Get the compact storage flag.
`getDimensions`()	Get the current dimensions.
`getExtraRow`()	Get the extra row flag.
`getGSVDDimensions`()	Get the number of columns and rows of a `DS` of type `GSVD`.
`getHSVDDimensions`()	Get the number of columns of a `DS` of type `HSVD`.
`getLeadingDimension`()	Get the leading dimension of the allocated matrices.
`getMat`(matname)	Get the requested matrix as a sequential dense Mat object.
`getMethod`()	Get the method currently used in the DS.
`getOptionsPrefix`()	Get the prefix used for searching for all DS options in the database.
`getPEPCoefficients`()	Get the polynomial basis coefficients of a `DS` of type `PEP`.
`getPEPDegree`()	Get the polynomial degree of a `DS` of type `PEP`.
`getParallel`()	Get the mode of operation in parallel runs.
`getRefined`()	Get the refined vectors flag.
`getSVDDimensions`()	Get the number of columns of a `DS` of type `SVD`.
`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 matrices' compact storage flag.
`setDimensions`([n, l, k])	Set the matrices sizes in the DS object.
`setExtraRow`(ext)	Set a flag to indicate that the matrix has one extra row.
`setFromOptions`()	Set DS options from the options database.
`setGSVDDimensions`(m, p)	Set the number of columns and rows of a `DS` of type `GSVD`.
`setHSVDDimensions`(m)	Set the number of columns of a `DS` of type `HSVD`.
`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)	Set the polynomial basis coefficients of a `DS` of type `PEP`.
`setPEPDegree`(deg)	Set the polynomial degree of a `DS` of type `PEP`.
`setParallel`(pmode)	Set the mode of operation in parallel runs.
`setRefined`(ref)	Set a flag to indicate that refined vectors must be computed.
`setSVDDimensions`(m)	Set the number of columns of a `DS` of type `SVD`.
`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.
`updateExtraRow`()	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

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

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:: None

Source code at slepc4py/SLEPc/DS.pyx:271

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:: None

Source code at slepc4py/SLEPc/DS.pyx:216

cond()#

Compute the inf-norm condition number of the first matrix.

Logically collective.

Returns:: Condition number.
Return type:: float

Source code at slepc4py/SLEPc/DS.pyx:715

create(comm=None)#

Create the DS object.

Collective.

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

Source code at slepc4py/SLEPc/DS.pyx:148

destroy()#

Destroy the DS object.

Collective.

Source code at slepc4py/SLEPc/DS.pyx:130

Return type:: Self

duplicate()#

Duplicate the DS object with the same type and dimensions.

Collective.

Source code at slepc4py/SLEPc/DS.pyx:259

Return type:: DS

getArray(matname)#

Return the array where the data is stored.

Not collective.

Parameters:

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

Return type:

ArrayScalar

See also

DSGetArray

Source code at slepc4py/SLEPc/DS.pyx:664

getBlockSize()#

Get the block size.

Not collective.

Returns:: The block size.
Return type:: int

Source code at slepc4py/SLEPc/DS.pyx:435

getCompact()#

Get the compact storage flag.

Not collective.

Returns:: The flag.
Return type:: bool

Source code at slepc4py/SLEPc/DS.pyx:503

getDimensions()#

Get the current dimensions.

Not collective.

Returns:

n (int) – The new size.
l (int) – Number of locked (inactive) leading columns.
k (int) – Intermediate dimension (e.g., position of arrow).
t (int) – Truncated length.

Return type:

tuple[int, int, int, int]

Source code at slepc4py/SLEPc/DS.pyx:397

getExtraRow()#

Get the extra row flag.

Not collective.

Returns:: The flag.
Return type:: bool

Source code at slepc4py/SLEPc/DS.pyx:542

getGSVDDimensions()#

Get the number of columns and rows of a DS of type GSVD.

Not collective.

Returns:

m (int) – The number of columns.
p (int) – The number of rows for the second matrix.

Return type:

tuple[int, int]

Source code at slepc4py/SLEPc/DS.pyx:845

getHSVDDimensions()#

Get the number of columns of a DS of type HSVD.

Not collective.

Returns:: The number of columns.
Return type:: int

Source code at slepc4py/SLEPc/DS.pyx:813

getLeadingDimension()#

Get the leading dimension of the allocated matrices.

Not collective.

Returns:: Leading dimension (maximum allowed dimension for the matrices).
Return type:: int

Source code at slepc4py/SLEPc/DS.pyx:286

getMat(matname)#

Get the requested matrix as a sequential dense Mat object.

Not collective.

Parameters:: matname (MatType) – The requested matrix.
Returns:: The matrix.
Return type:: petsc4py.PETSc.Mat

Source code at slepc4py/SLEPc/DS.pyx:625

getMethod()#

Get the method currently used in the DS.

Not collective.

Returns:: Identifier of the method.
Return type:: int

Source code at slepc4py/SLEPc/DS.pyx:464

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:: str

Source code at slepc4py/SLEPc/DS.pyx:231

getPEPCoefficients()#

Get the polynomial basis coefficients of a DS of type PEP.

Not collective.

Returns:: Coefficients.
Return type:: ArrayReal

Source code at slepc4py/SLEPc/DS.pyx:908

getPEPDegree()#

Get the polynomial degree of a DS of type PEP.

Not collective.

Returns:: The polynomial degree.
Return type:: int

Source code at slepc4py/SLEPc/DS.pyx:877

getParallel()#

Get the mode of operation in parallel runs.

Not collective.

Returns:: The parallel mode.
Return type:: ParallelType

Source code at slepc4py/SLEPc/DS.pyx:355

getRefined()#

Get the refined vectors flag.

Not collective.

Returns:: The flag.
Return type:: bool

Source code at slepc4py/SLEPc/DS.pyx:582

getSVDDimensions()#

Get the number of columns of a DS of type SVD.

Not collective.

Returns:: The number of columns.
Return type:: int

Source code at slepc4py/SLEPc/DS.pyx:784

getState()#

Get the current state.

Not collective.

Returns:: The current state.
Return type:: StateType

Source code at slepc4py/SLEPc/DS.pyx:326

getType()#

Get the DS type of this object.

Not collective.

Returns:: The direct solver type currently being used.
Return type:: str

Source code at slepc4py/SLEPc/DS.pyx:180

reset()#

Reset the DS object.

Collective.

Source code at slepc4py/SLEPc/DS.pyx:140

Return type:: None

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:

None

Source code at slepc4py/SLEPc/DS.pyx:647

setBlockSize(bs)#

Set the block size.

Logically collective.

Parameters:: bs (int) – The block size.
Return type:: None

Source code at slepc4py/SLEPc/DS.pyx:421

setCompact(comp)#

Set the matrices’ compact storage flag.

Logically collective.

Parameters:: comp (bool) – True means compact storage.
Return type:: None

Notes

Compact storage is used in some DS types such as DS.Type.HEP when the matrix is tridiagonal. This flag can be used to indicate whether the user provides the matrix entries via the compact form (the tridiagonal DS.MatType.T) or the non-compact one (DS.MatType.A).

The default is False.

Source code at slepc4py/SLEPc/DS.pyx:479

setDimensions(n=None, l=None, k=None)#

Set the matrices sizes in the DS object.

Logically collective.

Parameters:

n (int | None) – The new size.
l (int | None) – Number of locked (inactive) leading columns.
k (int | None) – Intermediate dimension (e.g., position of arrow).

Return type:

None

Notes

The internal arrays are not reallocated.

Source code at slepc4py/SLEPc/DS.pyx:370

setExtraRow(ext)#

Set a flag to indicate that the matrix has one extra row.

Logically collective.

Parameters:: ext (bool) – True if the matrix has extra row.
Return type:: None

Notes

In Krylov methods it is useful that the matrix representing the direct solver has one extra row, i.e., has dimension \((n+1) n\). 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.

Source code at slepc4py/SLEPc/DS.pyx:518

setFromOptions()#

Set DS options from the options database.

Collective.

Notes

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

Source code at slepc4py/SLEPc/DS.pyx:246

Return type:: None

setGSVDDimensions(m, p)#

Set the number of columns and rows of a DS of type GSVD.

Logically collective.

Parameters:

m (int) – The number of columns.
p (int) – The number of rows for the second matrix.

Return type:

None

Source code at slepc4py/SLEPc/DS.pyx:828

setHSVDDimensions(m)#

Set the number of columns of a DS of type HSVD.

Logically collective.

Parameters:: m (int) – The number of columns.
Return type:: None

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

setIdentity(matname)#

Set the identity on the active part of a matrix.

Logically collective.

Parameters:: matname (MatType) – The requested matrix.
Return type:: None

Source code at slepc4py/SLEPc/DS.pyx:699

setMethod(meth)#

Set the method to be used to solve the problem.

Logically collective.

Parameters:: meth (int) – An index identifying the method.
Return type:: None

Source code at slepc4py/SLEPc/DS.pyx:450

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

Source code at slepc4py/SLEPc/DS.pyx:195

setPEPCoefficients(pbc)#

Set the polynomial basis coefficients of a DS of type PEP.

Logically collective.

Parameters:: pbc (Sequence[float]) – Coefficients.
Return type:: None

Source code at slepc4py/SLEPc/DS.pyx:892

setPEPDegree(deg)#

Set the polynomial degree of a DS of type PEP.

Logically collective.

Parameters:: deg (int) – The polynomial degree.
Return type:: None

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

setParallel(pmode)#

Set the mode of operation in parallel runs.

Logically collective.

Parameters:: pmode (ParallelType) – The parallel mode.
Return type:: None

Source code at slepc4py/SLEPc/DS.pyx:341

setRefined(ref)#

Set a flag to indicate that refined vectors must be computed.

Logically collective.

Parameters:: ref (bool) – True if refined vectors must be used.
Return type:: None

Notes

Normally the vectors returned in DS.MatType.X are eigenvectors of the projected matrix. With this flag activated, vectors() will return the right singular vector of the smallest singular value of matrix \(At - theta I\), where \(At\) is the extended \((n+1) times n\) matrix and \(theta\) is the Ritz value. This is used in the refined Ritz approximation.

The default is False.

Source code at slepc4py/SLEPc/DS.pyx:557

setSVDDimensions(m)#

Set the number of columns of a DS of type SVD.

Logically collective.

Parameters:: m (int) – The number of columns.
Return type:: None

Source code at slepc4py/SLEPc/DS.pyx:770

setState(state)#

Set the state of the DS object.

Logically collective.

Parameters:: state (StateType) – The new state.
Return type:: None

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.

This function is normally used to return to the raw state when the condensed structure is destroyed.

Source code at slepc4py/SLEPc/DS.pyx:301

setType(ds_type)#

Set the type for the DS object.

Logically collective.