slepc4py.SLEPc.DS — slepc4py 3.24.2 documentation

Skip to main content
`Ctrl`+`K`

# 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` | Indicates the parallel mode that the direct solver will use.
  `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 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.
  `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

    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`

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

  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

    See also

    `setOptionsPrefix`, `getOptionsPrefix`, `DSSetOptionsPrefix`

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

  cond()

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

    Logically collective.

    Returns:

      Condition number.

    Return type:

      `float`

    See also

    `DSCond`

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

  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

    See also

    `duplicate`, `DSCreate`

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

  destroy()

    Destroy the DS object.

    Collective.

    See also

    `DSDestroy`

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

    Return type:

      Self

  duplicate()

    Duplicate the DS object with the same type and dimensions.

    Collective.

    Returns:

      The new object.

    Return type:

      `DS`

    Notes

    This method does not copy the matrices, and the new object does not even have internal arrays allocated. Use `allocate()` to use the new `DS`.

    See also

    `create`, `allocate`, `DSDuplicate`

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

  getArray(matname)

    Return the array where the data is stored.

    Not collective.

    Parameters:

      matname (MatType) – The selected matrix.

    Returns:

      The array.

    Return type:

      `ArrayScalar`

    See also

    `DSGetArray`

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

  getBlockSize()

    Get the block size.

    Not collective.

    Returns:

      The block size.

    Return type:

      `int`

    See also

    `setBlockSize`, `DSGetBlockSize`

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

  getCompact()

    Get the compact storage flag.

    Not collective.

    Returns:

      The flag.

    Return type:

      `bool`

    See also

    `setCompact`, `DSGetCompact`

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

  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]

    Notes

    The `t` value makes sense only if `truncate()` has been called. Otherwise it is equal to `n`.

    See also

    `setDimensions`, `truncate`, `getLeadingDimension`, `DSGetDimensions`

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

  getExtraRow()

    Get the extra row flag.

    Not collective.

    Returns:

      The flag.

    Return type:

      `bool`

    See also

    `setExtraRow`, `DSGetExtraRow`

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

  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]

    See also

    `setGSVDDimensions`, `DSGSVDGetDimensions`

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

  getHSVDDimensions()

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

    Not collective.

    Returns:

      The number of columns.

    Return type:

      `int`

    See also

    `setHSVDDimensions`, `DSHSVDGetDimensions`

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

  getLeadingDimension()

    Get the leading dimension of the allocated matrices.

    Not collective.

    Returns:

      Leading dimension (maximum allowed dimension for the matrices).

    Return type:

      `int`

    See also

    `allocate`, `setDimensions`, `DSGetLeadingDimension`

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

  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`

    Notes

    The returned matrix has sizes equal to the current `DS` dimensions (see `setDimensions()`), and contains the values that would be obtained with `getArray()`. If the `DS` was truncated, then the number of rows is equal to the dimension prior to truncation, see `truncate()`.

    When no longer needed the user must call `restoreMat()`.

    See also

    `restoreMat`, `setDimensions`, `getArray`, `truncate`, `DSGetMat`

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

  getMethod()

    Get the method currently used in the DS.

    Not collective.

    Returns:

      Identifier of the method.

    Return type:

      `int`

    See also

    `setMethod`, `DSGetMethod`

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

  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`

    See also

    `appendOptionsPrefix`, `setOptionsPrefix`, `DSSetOptionsPrefix`

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

  getPEPCoefficients()

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

    Not collective.

    Returns:

      Coefficients.

    Return type:

      `ArrayReal`

    See also

    `setPEPCoefficients`, `DSPEPGetCoefficients`

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

  getPEPDegree()

    Get the polynomial degree of a `DS` of type `PEP`.

    Not collective.

    Returns:

      The polynomial degree.

    Return type:

      `int`

    See also

    `setPEPDegree`, `DSPEPGetDegree`

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

  getParallel()

    Get the mode of operation in parallel runs.

    Not collective.

    Returns:

      The parallel mode.

    Return type:

      `ParallelType`

    See also

    `setParallel`, `DSGetParallel`

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

  getRefined()

    Get the refined vectors flag.

    Not collective.

    Returns:

      The flag.

    Return type:

      `bool`

    See also

    `setRefined`, `DSGetRefined`

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

  getSVDDimensions()

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

    Not collective.

    Returns:

      The number of columns.

    Return type:

      `int`

    See also

    `setSVDDimensions`, `DSSVDGetDimensions`

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

  getState()

    Get the current state.

    Not collective.

    Returns:

      The current state.

    Return type:

      `StateType`

    See also

    `setState`, `DSGetState`

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

  getType()

    Get the DS type of this object.

    Not collective.

    Returns:

      The direct solver type currently being used.

    Return type:

      `str`

    See also

    `setType`, `DSGetType`

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

  reset()

    Reset the DS object.

    Collective.

    See also

    `allocate`, `DSReset`

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

    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

    See also

    `getMat`, `DSRestoreMat`

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

  setBlockSize(bs)

    Set the block size.

    Logically collective.

    Parameters:

      bs (int) – The block size.

    Return type:

      None

    See also

    `getBlockSize`, `DSSetBlockSize`

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

  setCompact(comp)

    Set the compact flag for storage of matrices.

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

    See also

    `getCompact`, `DSSetCompact`

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

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

    Set the matrix 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.

    Some `DS` types have additional dimensions, e.g., the number of columns in `DS.Type.SVD`. For these, you should call a specific interface function.

    See also

    `getDimensions`, `allocate`, `DSSetDimensions`

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

  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 \((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

    `getExtraRow`, `solve`, `allocate`, `DSSetExtraRow`

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

  setFromOptions()

    Set DS options from the options database.

    Collective.

    Notes

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

    See also

    `setOptionsPrefix`, `DSSetFromOptions`

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

    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

    Notes

    This call is complementary to `setDimensions()`, to provide dimensions that are specific to this `DS.Type`.

    See also

    `setDimensions`, `getGSVDDimensions`, `DSGSVDSetDimensions`

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

  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

    Notes

    This call is complementary to `setDimensions()`, to provide a dimension that is specific to this `DS.Type`.

    See also

    `setDimensions`, `getHSVDDimensions`, `DSHSVDSetDimensions`

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

  setIdentity(matname)

    Set the identity on the active part of a matrix.

    Logically collective.

    Parameters:

      matname (MatType) – The matrix to be changed.

    Return type:

      None

    See also

    `DSSetIdentity`

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

  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

    See also

    `getMethod`, `DSSetMethod`

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

  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.

    See also

    `appendOptionsPrefix`, `getOptionsPrefix`, `DSSetOptionsPrefix`

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

  setPEPCoefficients(pbc)

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

    Logically collective.

    Parameters:

      pbc (Sequence[float]) – Coefficients.

    Return type:

      None

    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

    `getPEPCoefficients`, `DSPEPSetCoefficients`

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

  setPEPDegree(deg)

    Set the polynomial degree of a `DS` of type `PEP`.

    Logically collective.

    Parameters:

      deg (int) – The polynomial degree.

    Return type:

      None

    See also

    `getPEPDegree`, `DSPEPSetDegree`

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

  setParallel(pmode)

    Set the mode of operation in parallel runs.

    Logically collective.

    Parameters:

      pmode (ParallelType) – The parallel mode.

    Return type:

      None

    See also

    `getParallel`, `DSSetParallel`

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

  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 \(\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

    `getRefined`, `vectors`, `setExtraRow`, `DSSetRefined`

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

  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

    Notes

    This call is complementary to `setDimensions()`, to provide a dimension that is specific to this `DS.Type`.

    See also

    `setDimensions`, `getSVDDimensions`, `DSSVDSetDimensions`

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

  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.

    The state is automatically changed in functions such as `solve()` or `truncate()`. This function is normally used to return to the raw state when the condensed structure is destroyed, or to indicate that `solve()` must start with a problem that already has an intermediate form.

    See also

    `getState`, `solve`, `truncate`, `DSSetState`

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

  setType(ds_type)

    Set the type for the DS object.

    Logically collective.

    Parameters:

      ds_type (Type | str) – The direct solver type to be used.

    Return type:

      None

    See also

    `getType`, `DSSetType`

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

  solve()

    Solve the problem.

    Logically collective.

    Returns:

      Eigenvalues or singular values.

    Return type:

      `ArrayScalar`

    See also

    `DSSolve`

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

  truncate(n, trim=False)

    Truncate the system represented in the DS object.

    Logically collective.

    Parameters:

      - n (int) – The new size.

      - trim (bool) – A flag to indicate if the factorization must be trimmed.

    Return type:

      None

    See also

    `setDimensions`, `setExtraRow`, `DSTruncate`

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

  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

    `DSUpdateExtraRow`

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

    Return type:

      None

  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:

      None

    See also

    `DSVectors`

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

  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:

      None

    See also

    `DSView`

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

  Attributes Documentation

  block_size

    The block size.

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

  compact

    Compact storage of matrices.

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

  extra_row

    If the matrix has one extra row.

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

  method

    The method to be used to solve the problem.

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

  parallel

    The mode of operation in parallel runs.

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

  refined

    If refined vectors must be computed.

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

  state

    The state of the DS object.

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