Skip to main content
`Ctrl`+`K`

# slepc4py.SLEPc.DS

class slepc4py.SLEPc.DS

  Bases: `Object`

  DS.

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

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

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

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

  destroy()

    Destroy the DS object.

    Collective.

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

    Return type:

      Self

  duplicate()

    Duplicate the DS object with the same type and dimensions.

    Collective.

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

    Return type:

      DS

  getBlockSize()

    Get the block size.

    Not collective.

    Returns:

      The block size.

    Return type:

      `int`

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

  getCompact()

    Get the compact storage flag.

    Not collective.

    Returns:

      The flag.

    Return type:

      `bool`

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

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

  getExtraRow()

    Get the extra row flag.

    Not collective.

    Returns:

      The flag.

    Return type:

      `bool`

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

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

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

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

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

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

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

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

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

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

  getRefined()

    Get the refined vectors flag.

    Not collective.

    Returns:

      The flag.

    Return type:

      `bool`

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

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

  getState()

    Get the current state.

    Not collective.

    Returns:

      The current state.

    Return type:

      `StateType`

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

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

  reset()

    Reset the DS object.

    Collective.

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

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

  setBlockSize(bs)

    Set the block size.

    Logically collective.

    Parameters:

      bs (int) – The block size.

    Return type:

      None

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  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

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

  solve()

    Solve the problem.

    Logically collective.

    Returns:

      Eigenvalues or singular values.

    Return type:

      `ArrayScalar`

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

  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

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

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

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

    Return type:

      None

  vectors(matname=X)

    Compute vectors associated to the dense system such as eigenvectors.

    Logically collective.

    Parameters:

      matname (`DS.MatType` enumerate) – The matrix, used to indicate which vectors are required.

    Return type:

      None

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

  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

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

  Attributes Documentation

  block_size

    The block size.

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

  compact

    Compact storage of matrices.

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

  extra_row

    If the matrix has one extra row.

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

  method

    The method to be used to solve the problem.

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

  parallel

    The mode of operation in parallel runs.

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

  refined

    If refined vectors must be computed.

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

  state

    The state of the DS object.

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