slepc4py.SLEPc.SVD — slepc4py 3.25.0 documentation

Skip to main content
`Ctrl`+`K`

# slepc4py.SLEPc.SVD

class slepc4py.SLEPc.SVD

  Bases: `Object`

  Singular Value Decomposition Solver.

  The Singular Value Decomposition Solver (`SVD`) is very similar to the `EPS` object, but intended for the computation of the partial SVD of a rectangular matrix. With this type of object, the user can specify an SVD problem and solve it with any of the different solvers encapsulated by the package. Some of these solvers are actually implemented through calls to `EPS` eigensolvers.

  Enumerations

  `Conv` | SVD convergence test.
  `ConvergedReason` | SVD convergence reasons.
  `ErrorType` | SVD error type to assess accuracy of computed solutions.
  `ProblemType` | SVD problem type.
  `Stop` | SVD stopping test.
  `TRLanczosGBidiag` | SVD TRLanczos bidiagonalization choices for the GSVD case.
  `Type` | SVD type.
  `Which` | SVD desired part of spectrum.

  Methods Summary

  `appendOptionsPrefix`([prefix]) | Append to the prefix used for searching for all SVD options in the database.
  `cancelMonitor`() | Clear all monitors for an `SVD` object.
  `computeError`(i[, etype]) | Compute the error associated with the i-th singular triplet.
  `create`([comm]) | Create the SVD object.
  `destroy`() | Destroy the SVD object.
  `errorView`([etype, viewer]) | Display the errors associated with the computed solution.
  `getBV`() | Get the basis vectors objects associated to the SVD object.
  `getConverged`() | Get the number of converged singular triplets.
  `getConvergedReason`() | Get the reason why the `solve()` iteration was stopped.
  `getConvergenceTest`() | Get the method used to compute the error estimate used in the convergence test.
  `getCrossEPS`() | Get the eigensolver object associated to the singular value solver.
  `getCrossExplicitMatrix`() | Get the flag indicating if \(A^*A\) is built explicitly.
  `getCyclicEPS`() | Get the eigensolver object associated to the singular value solver.
  `getCyclicExplicitMatrix`() | Get the flag indicating if \(H(A)\) is built explicitly.
  `getDS`() | Get the direct solver associated to the singular value solver.
  `getDimensions`() | Get the number of singular values to compute and the dimension of the subspace.
  `getImplicitTranspose`() | Get the mode used to handle the transpose of the associated matrix.
  `getIterationNumber`() | Get the current iteration number.
  `getLanczosOneSide`() | Get if the variant of the Lanczos method to be used is one-sided or two-sided.
  `getMonitor`() | Get the list of monitor functions.
  `getOperators`() | Get the matrices associated with the singular value problem.
  `getOptionsPrefix`() | Get the prefix used for searching for all SVD options in the database.
  `getProblemType`() | Get the problem type from the SVD object.
  `getSignature`([omega]) | Get the signature matrix defining a hyperbolic singular value problem.
  `getSingularTriplet`(i[, U, V]) | Get the i-th triplet of the singular value decomposition.
  `getStoppingTest`() | Get the stopping test function.
  `getTRLanczosExplicitMatrix`() | Get the flag indicating if \(Z=[A^*,B^*]^*\) is built explicitly.
  `getTRLanczosGBidiag`() | Get bidiagonalization choice used in the GSVD TRLanczos solver.
  `getTRLanczosKSP`() | Get the linear solver object associated with the SVD solver.
  `getTRLanczosLocking`() | Get the locking flag used in the thick-restart Lanczos method.
  `getTRLanczosOneSide`() | Get if the variant of the method to be used is one-sided or two-sided.
  `getTRLanczosRestart`() | Get the restart parameter used in the thick-restart Lanczos method.
  `getThreshold`() | Get the threshold used in the threshold stopping test.
  `getTolerances`() | Get the tolerance and maximum iteration count.
  `getTrackAll`() | Get the flag indicating if all residual norms must be computed or not.
  `getType`() | Get the SVD type of this object.
  `getValue`(i) | Get the i-th singular value as computed by `solve()`.
  `getVectors`(i, U, V) | Get the i-th left and right singular vectors as computed by `solve()`.
  `getWhichSingularTriplets`() | Get which singular triplets are to be sought.
  `isGeneralized`() | Tell if the SVD corresponds to a generalized singular value problem.
  `isHyperbolic`() | Tell whether the SVD object corresponds to a hyperbolic singular value problem.
  `reset`() | Reset the SVD object.
  `setBV`(V[, U]) | Set basis vectors objects associated to the SVD solver.
  `setConvergenceTest`(conv) | Set how to compute the error estimate used in the convergence test.
  `setCrossEPS`(eps) | Set an eigensolver object associated to the singular value solver.
  `setCrossExplicitMatrix`([flag]) | Set if the eigensolver operator \(A^*A\) must be computed.
  `setCyclicEPS`(eps) | Set an eigensolver object associated to the singular value solver.
  `setCyclicExplicitMatrix`([flag]) | Set if the eigensolver operator \(H(A)\) must be computed explicitly.
  `setDS`(ds) | Set a direct solver object associated to the singular value solver.
  `setDimensions`([nsv, ncv, mpd]) | Set the number of singular values to compute and the dimension of the subspace.
  `setFromOptions`() | Set SVD options from the options database.
  `setImplicitTranspose`(mode) | Set how to handle the transpose of the associated matrix.
  `setInitialSpace`([spaceright, spaceleft]) | Set the initial spaces from which the SVD solver starts to iterate.
  `setLanczosOneSide`([flag]) | Set if the variant of the Lanczos method to be used is one-sided or two-sided.
  `setMonitor`(monitor[, args, kargs]) | Append a monitor function to the list of monitors.
  `setOperators`(A[, B]) | Set the matrices associated with the singular value problem.
  `setOptionsPrefix`([prefix]) | Set the prefix used for searching for all SVD options in the database.
  `setProblemType`(problem_type) | Set the type of the singular value problem.
  `setSignature`([omega]) | Set the signature matrix defining a hyperbolic singular value problem.
  `setStoppingTest`(stopping[, args, kargs]) | Set a function to decide when to stop the outer iteration of the eigensolver.
  `setTRLanczosExplicitMatrix`([flag]) | Set if the matrix \(Z=[A^*,B^*]^*\) must be built explicitly.
  `setTRLanczosGBidiag`(bidiag) | Set the bidiagonalization choice to use in the GSVD TRLanczos solver.
  `setTRLanczosKSP`(ksp) | Set a linear solver object associated to the SVD solver.
  `setTRLanczosLocking`(lock) | Toggle between locking and non-locking variants of TRLanczos.
  `setTRLanczosOneSide`([flag]) | Set if the variant of the method to be used is one-sided or two-sided.
  `setTRLanczosRestart`(keep) | Set the restart parameter for the thick-restart Lanczos method.
  `setThreshold`(thres[, rel]) | Set the threshold used in the threshold stopping test.
  `setTolerances`([tol, max_it]) | Set the tolerance and maximum iteration count used.
  `setTrackAll`(trackall) | Set flag to compute the residual of all singular triplets.
  `setType`(svd_type) | Set the particular solver to be used in the SVD object.
  `setUp`() | Set up all the internal data structures.
  `setWhichSingularTriplets`(which) | Set which singular triplets are to be sought.
  `solve`() | Solve the singular value problem.
  `valuesView`([viewer]) | Display the computed singular values in a viewer.
  `vectorsView`([viewer]) | Output computed singular vectors to a viewer.
  `view`([viewer]) | Print the SVD data structure.

  Attributes Summary

  `ds` | The direct solver (`DS`) object associated.
  `max_it` | The maximum iteration count.
  `problem_type` | The type of the eigenvalue problem.
  `tol` | The tolerance.
  `track_all` | Compute the residual norm of all approximate eigenpairs.
  `transpose_mode` | How to handle the transpose of the matrix.
  `which` | The portion of the spectrum to be sought.

  Methods Documentation

  appendOptionsPrefix(prefix=None)

    Append to the prefix used for searching for all SVD options in the database.

    Logically collective.

    Parameters:

      prefix (str | None) – The prefix string to prepend to all SVD option requests.

    Return type:

      None

    See also

    `setOptionsPrefix`, `getOptionsPrefix`, `SVDAppendOptionsPrefix`

    Source code at slepc4py/SLEPc/SVD.pyx:357

  cancelMonitor()

    Clear all monitors for an `SVD` object.

    Logically collective.

    See also

    `SVDMonitorCancel`

    Source code at slepc4py/SLEPc/SVD.pyx:1149

    Return type:

      None

  computeError(i, etype=None)

    Compute the error associated with the i-th singular triplet.

    Collective.

    Compute the error (based on the residual norm) associated with the i-th singular triplet.

    Parameters:

      - i (int) – Index of the solution to be considered.

      - etype (ErrorType | None) – The error type to compute.

    Returns:

      The error bound, computed in various ways from the residual norm \(\sqrt{\eta_1^2+\eta_2^2}\) where \(\eta_1 = \|A v - \sigma u\|_2\), \(\eta_2 = \|A^* u - \sigma v\|_2\), \(\sigma\) is the approximate singular value, \(u\) and \(v\) are the left and right singular vectors.

    Return type:

      `float`

    Notes

    The index `i` should be a value between `0` and `nconv-1` (see `getConverged()`).

    In the case of the GSVD, the two components of the residual norm are \(\eta_1 = \|s^2 A^*u-cB^*Bx\|_2\) and \(\eta_2 = ||c^2 B^*v-sA^*Ax||_2\), where \((\sigma,u,v,x)\) is the approximate generalized singular quadruple, with \(\sigma=c/s\).

    See also

    `solve`, `SVDComputeError`

    Source code at slepc4py/SLEPc/SVD.pyx:1377

  create(comm=None)

    Create the SVD object.

    Collective.

    Parameters:

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

    Return type:

      Self

    See also

    `SVDCreate`

    Source code at slepc4py/SLEPc/SVD.pyx:240

  destroy()

    Destroy the SVD object.

    Collective.

    See also

    `SVDDestroy`

    Source code at slepc4py/SLEPc/SVD.pyx:214

    Return type:

      Self

  errorView(etype=None, viewer=None)

    Display the errors associated with the computed solution.

    Collective.

    Display the errors and the singular values.

    Parameters:

      - etype (ErrorType | None) – The error type to compute.

      - viewer (petsc4py.PETSc.Viewer | None) – Visualization context; if not provided, the standard output is used.

    Return type:

      None

    Notes

    By default, this function checks the error of all singular triplets and prints the singular values if all of them are below the requested tolerance. If the viewer has format `ASCII_INFO_DETAIL` then a table with singular values and corresponding errors is printed.

    See also

    `solve`, `valuesView`, `vectorsView`, `SVDErrorView`

    Source code at slepc4py/SLEPc/SVD.pyx:1424

  getBV()

    Get the basis vectors objects associated to the SVD object.

    Not collective.

    Returns:

      - V (`BV`) – The basis vectors context for right singular vectors.

      - U (`BV`) – The basis vectors context for left singular vectors.

    Return type:

      tuple[BV, BV]

    See also

    `setBV`, `SVDGetBV`

    Source code at slepc4py/SLEPc/SVD.pyx:829

  getConverged()

    Get the number of converged singular triplets.

    Not collective.

    Returns:

      nconv – Number of converged singular triplets.

    Return type:

      `int`

    Notes

    This function should be called after `solve()` has finished.

    The value `nconv` may be different from the number of requested solutions `nsv`, but not larger than `ncv`, see `setDimensions()`.

    See also

    `setDimensions`, `solve`, `getValue`, `SVDGetConverged`

    Source code at slepc4py/SLEPc/SVD.pyx:1248

  getConvergedReason()

    Get the reason why the `solve()` iteration was stopped.

    Not collective.

    Returns:

      Negative value indicates diverged, positive value converged.

    Return type:

      `ConvergedReason`

    See also

    `setTolerances`, `solve`, `SVDGetConvergedReason`

    Source code at slepc4py/SLEPc/SVD.pyx:1229

  getConvergenceTest()

    Get the method used to compute the error estimate used in the convergence test.

    Not collective.

    Returns:

      The method used to compute the error estimate used in the convergence test.

    Return type:

      `Conv`

    See also

    `setConvergenceTest`, `SVDGetConvergenceTest`

    Source code at slepc4py/SLEPc/SVD.pyx:674

  getCrossEPS()

    Get the eigensolver object associated to the singular value solver.

    Collective.

    Returns:

      The eigensolver object.

    Return type:

      `EPS`

    See also

    `setCrossEPS`, `SVDCrossGetEPS`

    Source code at slepc4py/SLEPc/SVD.pyx:1513

  getCrossExplicitMatrix()

    Get the flag indicating if \(A^*A\) is built explicitly.

    Not collective.

    Returns:

      `True` if \(A^*A\) is built explicitly.

    Return type:

      `bool`

    See also

    `setCrossExplicitMatrix`, `SVDCrossGetExplicitMatrix`

    Source code at slepc4py/SLEPc/SVD.pyx:1560

  getCyclicEPS()

    Get the eigensolver object associated to the singular value solver.

    Collective.

    Returns:

      The eigensolver object.

    Return type:

      `EPS`

    See also

    `setCyclicEPS`, `SVDCyclicGetEPS`

    Source code at slepc4py/SLEPc/SVD.pyx:1596

  getCyclicExplicitMatrix()

    Get the flag indicating if \(H(A)\) is built explicitly.

    Not collective.

    Get the flag indicating if \(H(A) = [ 0\; A ; A^T\; 0 ]\) is built explicitly.

    Returns:

      `True` if \(H(A)\) is built explicitly.

    Return type:

      `bool`

    See also

    `setCyclicExplicitMatrix`, `SVDCyclicGetExplicitMatrix`

    Source code at slepc4py/SLEPc/SVD.pyx:1645

  getDS()

    Get the direct solver associated to the singular value solver.

    Not collective.

    Returns:

      The direct solver context.

    Return type:

      `DS`

    See also

    `setDS`, `SVDGetDS`

    Source code at slepc4py/SLEPc/SVD.pyx:874

  getDimensions()

    Get the number of singular values to compute and the dimension of the subspace.

    Not collective.

    Returns:

      - nsv (`int`) – Number of singular values to compute.

      - ncv (`int`) – Maximum dimension of the subspace to be used by the solver.

      - mpd (`int`) – Maximum dimension allowed for the projected problem.

    Return type:

      tuple[int, int, int]

    See also

    `setDimensions`, `SVDGetDimensions`

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

  getImplicitTranspose()

    Get the mode used to handle the transpose of the associated matrix.

    Not collective.

    Returns:

      How to handle the transpose (implicitly or not).

    Return type:

      `bool`

    See also

    `setImplicitTranspose`, `SVDGetImplicitTranspose`

    Source code at slepc4py/SLEPc/SVD.pyx:478

  getIterationNumber()

    Get the current iteration number.

    Not collective.

    If the call to `solve()` is complete, then it returns the number of iterations carried out by the solution method.

    Returns:

      Iteration number.

    Return type:

      `int`

    See also

    `getConvergedReason`, `setTolerances`, `SVDGetIterationNumber`

    Source code at slepc4py/SLEPc/SVD.pyx:1207

  getLanczosOneSide()

    Get if the variant of the Lanczos method to be used is one-sided or two-sided.

    Not collective.

    Returns:

      `True` if the method is one-sided.

    Return type:

      `bool`

    See also

    `setLanczosOneSide`, `SVDLanczosGetOneSide`

    Source code at slepc4py/SLEPc/SVD.pyx:1693

  getMonitor()

    Get the list of monitor functions.

    Not collective.

    Returns:

      The list of monitor functions.

    Return type:

      `SVDMonitorFunction`

    See also

    `setMonitor`

    Source code at slepc4py/SLEPc/SVD.pyx:1132

  getOperators()

    Get the matrices associated with the singular value problem.

    Collective.

    Returns:

      - A (`petsc4py.PETSc.Mat`) – The matrix associated with the singular value problem.

      - B (`petsc4py.PETSc.Mat`) – The second matrix in the case of GSVD.

    Return type:

      tuple[Mat, Mat] | tuple[Mat, None]

    See also

    `setOperators`, `SVDGetOperators`

    Source code at slepc4py/SLEPc/SVD.pyx:911

  getOptionsPrefix()

    Get the prefix used for searching for all SVD options in the database.

    Not collective.

    Returns:

      The prefix string set for this SVD object.

    Return type:

      `str`

    See also

    `setOptionsPrefix`, `appendOptionsPrefix`, `SVDGetOptionsPrefix`

    Source code at slepc4py/SLEPc/SVD.pyx:307

  getProblemType()

    Get the problem type from the SVD object.

    Not collective.

    Returns:

      The problem type that was previously set.

    Return type:

      `ProblemType`

    See also

    `setProblemType`, `SVDGetProblemType`

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

  getSignature(omega=None)

    Get the signature matrix defining a hyperbolic singular value problem.

    Collective.

    Parameters:

      omega (Vec | None) – Optional vector to store the diagonal elements of the signature matrix.

    Returns:

      A vector containing the diagonal elements of the signature matrix.

    Return type:

      `petsc4py.PETSc.Vec`

    See also

    `setSignature`, `SVDGetSignature`

    Source code at slepc4py/SLEPc/SVD.pyx:958

  getSingularTriplet(i, U=None, V=None)

    Get the i-th triplet of the singular value decomposition.

    Collective.

    Get the i-th triplet of the singular value decomposition as computed by `solve()`. The solution consists of the singular value and its left and right singular vectors.

    Parameters:

      - i (int) – Index of the solution to be obtained.

      - U (Vec | None) – Placeholder for the returned left singular vector.

      - V (Vec | None) – Placeholder for the returned right singular vector.

    Returns:

      The computed singular value.

    Return type:

      `float`

    Notes

    The index `i` should be a value between `0` and `nconv-1` (see `getConverged()`. Singular triplets are indexed according to the ordering criterion established with `setWhichSingularTriplets()`.

    See also

    `getConverged`, `setWhichSingularTriplets`, `SVDGetSingularTriplet`

    Source code at slepc4py/SLEPc/SVD.pyx:1334

  getStoppingTest()

    Get the stopping test function.

    Not collective.

    Returns:

      The stopping test function.

    Return type:

      `SVDStoppingFunction`

    See also

    `setStoppingTest`

    Source code at slepc4py/SLEPc/SVD.pyx:1088

  getTRLanczosExplicitMatrix()

    Get the flag indicating if \(Z=[A^*,B^*]^*\) is built explicitly.

    Not collective.

    Returns:

      `True` if \(Z=[A^*,B^*]^*\) is built explicitly.

    Return type:

      `bool`

    See also

    `setTRLanczosExplicitMatrix`, `SVDTRLanczosGetExplicitMatrix`

    Source code at slepc4py/SLEPc/SVD.pyx:1948

  getTRLanczosGBidiag()

    Get bidiagonalization choice used in the GSVD TRLanczos solver.

    Not collective.

    Returns:

      The bidiagonalization choice.

    Return type:

      `TRLanczosGBidiag`

    See also

    `setTRLanczosGBidiag`, `SVDTRLanczosGetGBidiag`

    Source code at slepc4py/SLEPc/SVD.pyx:1780

  getTRLanczosKSP()

    Get the linear solver object associated with the SVD solver.

    Collective.

    Returns:

      The linear solver object.

    Return type:

      `petsc4py.PETSc.KSP`

    See also

    `setTRLanczosKSP`, `SVDTRLanczosGetKSP`

    Source code at slepc4py/SLEPc/SVD.pyx:1905

  getTRLanczosLocking()

    Get the locking flag used in the thick-restart Lanczos method.

    Not collective.

    Returns:

      The locking flag.

    Return type:

      `bool`

    See also

    `setTRLanczosLocking`, `SVDTRLanczosGetLocking`

    Source code at slepc4py/SLEPc/SVD.pyx:1869

  getTRLanczosOneSide()

    Get if the variant of the method to be used is one-sided or two-sided.

    Not collective.

    Get if the variant of the thick-restart Lanczos method to be used is one-sided or two-sided.

    Returns:

      `True` if the method is one-sided.

    Return type:

      `bool`

    See also

    `setTRLanczosOneSide`, `SVDLanczosGetOneSide`

    Source code at slepc4py/SLEPc/SVD.pyx:1740

  getTRLanczosRestart()

    Get the restart parameter used in the thick-restart Lanczos method.

    Not collective.

    Returns:

      The number of vectors to be kept at restart.

    Return type:

      `float`

    See also

    `setTRLanczosRestart`, `SVDTRLanczosGetRestart`

    Source code at slepc4py/SLEPc/SVD.pyx:1825

  getThreshold()

    Get the threshold used in the threshold stopping test.

    Not collective.

    Returns:

      - thres (`float`) – The threshold.

      - rel (`bool`) – Whether the threshold is relative or not.

    Return type:

      tuple[float, bool]

    See also

    `setThreshold`, `SVDGetThreshold`

    Source code at slepc4py/SLEPc/SVD.pyx:561

  getTolerances()

    Get the tolerance and maximum iteration count.

    Not collective.

    Get the tolerance and maximum iteration count used by the default SVD convergence tests.

    Returns:

      - tol (`float`) – The convergence tolerance.

      - max_it (`int`) – The maximum number of iterations.

    Return type:

      tuple[float, int]

    See also

    `setTolerances`, `SVDGetTolerances`

    Source code at slepc4py/SLEPc/SVD.pyx:618

  getTrackAll()

    Get the flag indicating if all residual norms must be computed or not.

    Not collective.

    Returns:

      Whether the solver computes all residuals or not.

    Return type:

      `bool`

    See also

    `setTrackAll`, `SVDGetTrackAll`

    Source code at slepc4py/SLEPc/SVD.pyx:713

  getType()

    Get the SVD type of this object.

    Not collective.

    Returns:

      The solver currently being used.

    Return type:

      `str`

    See also

    `setType`, `SVDGetType`

    Source code at slepc4py/SLEPc/SVD.pyx:288

  getValue(i)

    Get the i-th singular value as computed by `solve()`.

    Collective.

    Parameters:

      i (int) – Index of the solution to be obtained.

    Returns:

      The computed singular value.

    Return type:

      `float`

    Notes

    The index `i` should be a value between `0` and `nconv-1` (see `getConverged()`. Singular triplets are indexed according to the ordering criterion established with `setWhichSingularTriplets()`.

    See also

    `getConverged`, `setWhichSingularTriplets`, `SVDGetSingularTriplet`

    Source code at slepc4py/SLEPc/SVD.pyx:1274

  getVectors(i, U, V)

    Get the i-th left and right singular vectors as computed by `solve()`.

    Collective.

    Parameters:

      - i (int) – Index of the solution to be obtained.

      - U (Vec) – Placeholder for the returned left singular vector.

      - V (Vec) – Placeholder for the returned right singular vector.

    Return type:

      None

    Notes

    The index `i` should be a value between `0` and `nconv-1` (see `getConverged()`. Singular triplets are indexed according to the ordering criterion established with `setWhichSingularTriplets()`.

    See also

    `getConverged`, `setWhichSingularTriplets`, `SVDGetSingularTriplet`

    Source code at slepc4py/SLEPc/SVD.pyx:1305

  getWhichSingularTriplets()

    Get which singular triplets are to be sought.

    Not collective.

    Returns:

      The singular values to be sought (either largest or smallest).

    Return type:

      `Which`

    See also

    `setWhichSingularTriplets`, `SVDGetWhichSingularTriplets`

    Source code at slepc4py/SLEPc/SVD.pyx:524

  isGeneralized()

    Tell if the SVD corresponds to a generalized singular value problem.

    Not collective.

    Returns:

      `True` if two matrices were set with `setOperators()`.

    Return type:

      `bool`

    See also

    `setProblemType`, `isHyperbolic`, `SVDIsGeneralized`

    Source code at slepc4py/SLEPc/SVD.pyx:438

  isHyperbolic()

    Tell whether the SVD object corresponds to a hyperbolic singular value problem.

    Not collective.

    Returns:

      `True` if the problem was specified as hyperbolic.

    Return type:

      `bool`

    See also

    `setProblemType`, `isGeneralized`, `SVDIsHyperbolic`

    Source code at slepc4py/SLEPc/SVD.pyx:457

  reset()

    Reset the SVD object.

    Collective.

    See also

    `SVDReset`

    Source code at slepc4py/SLEPc/SVD.pyx:228

    Return type:

      None

  setBV(V, U=None)

    Set basis vectors objects associated to the SVD solver.

    Collective.

    Parameters:

      - V (BV) – The basis vectors context for right singular vectors.

      - U (BV | None) – The basis vectors context for left singular vectors.

    Return type:

      None

    See also

    `getBV`, `SVDSetBV`

    Source code at slepc4py/SLEPc/SVD.pyx:853

  setConvergenceTest(conv)

    Set how to compute the error estimate used in the convergence test.

    Logically collective.

    Parameters:

      conv (Conv) – The method used to compute the error estimate used in the convergence test.

    Return type:

      None

    See also

    `getConvergenceTest`, `SVDSetConvergenceTest`

    Source code at slepc4py/SLEPc/SVD.pyx:694

  setCrossEPS(eps)

    Set an eigensolver object associated to the singular value solver.

    Collective.

    Parameters:

      eps (EPS) – The eigensolver object.

    Return type:

      None

    See also

    `getCrossEPS`, `SVDCrossSetEPS`

    Source code at slepc4py/SLEPc/SVD.pyx:1496

  setCrossExplicitMatrix(flag=True)

    Set if the eigensolver operator \(A^*A\) must be computed.

    Logically collective.

    Parameters:

      flag (bool) – `True` to build \(A^*A\) explicitly.

    Return type:

      None

    Notes

    In GSVD there are two cross product matrices, \(A^*A\) and \(B^*B\). In HSVD the expression for the cross product matrix is different, \(A^*\Omega A\).

    By default the matrices are not built explicitly, but handled as shell matrices

    See also

    `getCrossExplicitMatrix`, `SVDCrossSetExplicitMatrix`

    Source code at slepc4py/SLEPc/SVD.pyx:1533

  setCyclicEPS(eps)

    Set an eigensolver object associated to the singular value solver.

    Collective.

    Parameters:

      eps (EPS) – The eigensolver object.

    Return type:

      None

    See also

    `getCyclicEPS`, `SVDCyclicSetEPS`

    Source code at slepc4py/SLEPc/SVD.pyx:1579

  setCyclicExplicitMatrix(flag=True)

    Set if the eigensolver operator \(H(A)\) must be computed explicitly.

    Logically collective.

    Set if the eigensolver operator \(H(A) = [ 0\; A ; A^T\; 0 ]\) must be computed explicitly.

    Parameters:

      flag (bool) – `True` if \(H(A)\) must be built explicitly.

    Return type:

      None

    Notes

    In GSVD and HSVD the equivalent eigenvalue problem has generalized form, and hence two matrices are built.

    By default the matrices are not built explicitly, but handled as shell matrices.

    See also

    `getCyclicExplicitMatrix`, `SVDCyclicSetExplicitMatrix`

    Source code at slepc4py/SLEPc/SVD.pyx:1616

  setDS(ds)

    Set a direct solver object associated to the singular value solver.

    Collective.

    Parameters:

      ds (DS) – The direct solver context.

    Return type:

      None

    See also

    `getDS`, `SVDSetDS`

    Source code at slepc4py/SLEPc/SVD.pyx:894

  setDimensions(nsv=None, ncv=None, mpd=None)

    Set the number of singular values to compute and the dimension of the subspace.

    Logically collective.

    Parameters:

      - nsv (int | None) – Number of singular values to compute.

      - ncv (int | None) – Maximum dimension of the subspace to be used by the solver.

      - mpd (int | None) – Maximum dimension allowed for the projected problem.

    Return type:

      None

    Notes

    Use `DETERMINE` for `ncv` and `mpd` to assign a reasonably good value, which is dependent on the solution method.

    The parameters `ncv` and `mpd` are intimately related, so that the user is advised to set one of them at most. Normal usage is the following:

    - In cases where `nsv` is small, the user sets `ncv` (a reasonable default is 2 * `nsv`).

    - In cases where `nsv` is large, the user sets `mpd`.

    The value of `ncv` should always be between `nsv` and (`nsv` + `mpd`), typically `ncv` = `nsv` + `mpd`. If `nsv` is not too large, `mpd` = `nsv` is a reasonable choice, otherwise a smaller value should be used.

    See also

    `getDimensions`, `SVDSetDimensions`

    Source code at slepc4py/SLEPc/SVD.pyx:778

  setFromOptions()

    Set SVD options from the options database.

    Collective.

    Notes

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

    This routine must be called before `setUp()` if the user is to be allowed to set the solver type.

    See also

    `setOptionsPrefix`, `SVDSetFromOptions`

    Source code at slepc4py/SLEPc/SVD.pyx:376

    Return type:

      None

  setImplicitTranspose(mode)

    Set how to handle the transpose of the associated matrix.

    Logically collective.

    Parameters:

      - impl – How to handle the transpose (implicitly or not).

      - mode (bool)

    Return type:

      None

    Notes

    By default, the transpose of the matrix is explicitly built (if the matrix has defined the `Mat.transpose()` operation).

    If this flag is set to `True`, the solver does not build the transpose, but handles it implicitly via `Mat.multTranspose()` (or `Mat.multHermitianTranspose()` in the complex case).

    See also

    `getImplicitTranspose`, `SVDSetImplicitTranspose`

    Source code at slepc4py/SLEPc/SVD.pyx:497

  setInitialSpace(spaceright=None, spaceleft=None)

    Set the initial spaces from which the SVD solver starts to iterate.

    Collective.

    Parameters:

      - spaceright (list[Vec] | None) – The right initial space.

      - spaceleft (list[Vec] | None) – The left initial space.

    Return type:

      None

    Notes

    The initial right and left spaces are rough approximations to the right and/or left singular subspaces from which the solver starts to iterate. It is not necessary to provide both sets of vectors.

    Some solvers start to iterate on a single vector (initial vector). In that case, the other vectors are ignored.

    These vectors do not persist from one `solve()` call to the other, so the initial spaces should be set every time.

    The vectors do not need to be mutually orthonormal, since they are explicitly orthonormalized internally.

    Common usage of this function is when the user can provide a rough approximation of the wanted singular spaces. Then, convergence may be faster.

    See also

    `SVDSetInitialSpaces`

    Source code at slepc4py/SLEPc/SVD.pyx:1007

  setLanczosOneSide(flag=True)

    Set if the variant of the Lanczos method to be used is one-sided or two-sided.

    Logically collective.

    Parameters:

      flag (bool) – `True` if the method is one-sided.

    Return type:

      None

    Notes

    By default, a two-sided variant is selected, which is sometimes slightly more robust. However, the one-sided variant is faster because it avoids the orthogonalization associated to left singular vectors. It also saves the memory required for storing such vectors.

    See also

    `getLanczosOneSide`, `SVDLanczosSetOneSide`

    Source code at slepc4py/SLEPc/SVD.pyx:1667

  setMonitor(monitor, args=None, kargs=None)

    Append a monitor function to the list of monitors.

    Logically collective.

    See also

    `getMonitor`, `cancelMonitor`, `SVDMonitorSet`

    Source code at slepc4py/SLEPc/SVD.pyx:1107

    Parameters:

      - monitor (SVDMonitorFunction | None)

      - args (tuple[Any, ...] | None)

      - kargs (dict[str, Any] | None)

    Return type:

      None

  setOperators(A, B=None)

    Set the matrices associated with the singular value problem.

    Collective.

    Parameters:

      - A (Mat) – The matrix associated with the singular value problem.

      - B (Mat | None) – The second matrix in the case of GSVD.

    Return type:

      None

    See also

    `getOperators`, `SVDSetOperators`

    Source code at slepc4py/SLEPc/SVD.pyx:938

  setOptionsPrefix(prefix=None)

    Set the prefix used for searching for all SVD options in the database.

    Logically collective.

    Parameters:

      prefix (str | None) – The prefix string to prepend to all SVD 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.

    For example, to distinguish between the runtime options for two different SVD contexts, one could call:

        S1.setOptionsPrefix("svd1_")
        S2.setOptionsPrefix("svd2_")

    See also

    `appendOptionsPrefix`, `getOptionsPrefix`, `SVDGetOptionsPrefix`

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

  setProblemType(problem_type)

    Set the type of the singular value problem.

    Logically collective.

    Parameters:

      problem_type (ProblemType) – The problem type to be set.

    Return type:

      None

    Notes

    The GSVD requires that two matrices have been passed via `setOperators()`. The HSVD requires that a signature matrix has been passed via `setSignature()`.

    See also

    `setOperators`, `setSignature`, `getProblemType`, `SVDSetProblemType`

    Source code at slepc4py/SLEPc/SVD.pyx:414

  setSignature(omega=None)

    Set the signature matrix defining a hyperbolic singular value problem.

    Collective.

    Parameters:

      omega (Vec | None) – A vector containing the diagonal elements of the signature matrix.

    Return type:

      None

    See also

    `getSignature`, `SVDSetSignature`

    Source code at slepc4py/SLEPc/SVD.pyx:987

  setStoppingTest(stopping, args=None, kargs=None)

    Set a function to decide when to stop the outer iteration of the eigensolver.

    Logically collective.

    See also

    `getStoppingTest`, `SVDSetStoppingTestFunction`

    Source code at slepc4py/SLEPc/SVD.pyx:1064

    Parameters:

      - stopping (SVDStoppingFunction | None)

      - args (tuple[Any, ...] | None)

      - kargs (dict[str, Any] | None)

    Return type:

      None

  setTRLanczosExplicitMatrix(flag=True)

    Set if the matrix \(Z=[A^*,B^*]^*\) must be built explicitly.

    Logically collective.

    Parameters:

      flag (bool) – `True` if \(Z=[A^*,B^*]^*\) is built explicitly.

    Return type:

      None

    Notes

    This option is relevant for the GSVD case only. \(Z\) is the coefficient matrix of the least-squares solver used internally.

    See also

    `getTRLanczosExplicitMatrix`, `SVDTRLanczosSetExplicitMatrix`

    Source code at slepc4py/SLEPc/SVD.pyx:1925

  setTRLanczosGBidiag(bidiag)

    Set the bidiagonalization choice to use in the GSVD TRLanczos solver.

    Logically collective.

    Parameters:

      bidiag (TRLanczosGBidiag) – The bidiagonalization choice.

    Return type:

      None

    See also

    `getTRLanczosGBidiag`, `SVDTRLanczosSetGBidiag`

    Source code at slepc4py/SLEPc/SVD.pyx:1762

  setTRLanczosKSP(ksp)

    Set a linear solver object associated to the SVD solver.

    Collective.

    Parameters:

      ksp (KSP) – The linear solver object.

    Return type:

      None

    See also

    `getTRLanczosKSP`, `SVDTRLanczosSetKSP`

    Source code at slepc4py/SLEPc/SVD.pyx:1888

  setTRLanczosLocking(lock)

    Toggle between locking and non-locking variants of TRLanczos.

    Logically collective.

    Parameters:

      lock (bool) – `True` if the locking variant must be selected.

    Return type:

      None

    Notes

    The default is to lock converged singular triplets when the method restarts. This behavior can be changed so that all directions are kept in the working subspace even if already converged to working accuracy (the non-locking variant).

    See also

    `getTRLanczosLocking`, `SVDTRLanczosSetLocking`

    Source code at slepc4py/SLEPc/SVD.pyx:1844

  setTRLanczosOneSide(flag=True)

    Set if the variant of the method to be used is one-sided or two-sided.

    Logically collective.

    Set if the variant of the thick-restart Lanczos method to be used is one-sided or two-sided.

    Parameters:

      flag (bool) – `True` if the method is one-sided.

    Return type:

      None

    Notes

    By default, a two-sided variant is selected, which is sometimes slightly more robust. However, the one-sided variant is faster because it avoids the orthogonalization associated to left singular vectors.

    See also

    `getTRLanczosOneSide`, `SVDLanczosSetOneSide`

    Source code at slepc4py/SLEPc/SVD.pyx:1712

  setTRLanczosRestart(keep)

    Set the restart parameter for the thick-restart Lanczos method.

    Logically collective.

    Set the restart parameter for the thick-restart Lanczos method, in particular the proportion of basis vectors that must be kept after restart.

    Parameters:

      keep (float) – The number of vectors to be kept at restart.

    Return type:

      None

    Notes

    Allowed values are in the range [0.1,0.9]. The default is 0.5.

    See also

    `getTRLanczosRestart`, `SVDTRLanczosSetRestart`

    Source code at slepc4py/SLEPc/SVD.pyx:1799

  setThreshold(thres, rel=False)

    Set the threshold used in the threshold stopping test.

    Logically collective.

    Parameters:

      - thres (float) – The threshold.

      - rel (bool) – Whether the threshold is relative or not.

    Return type:

      None

    Notes

    This function internally sets a special stopping test based on the threshold, where singular values are computed in sequence until one of the computed singular values is below/above the threshold (depending on whether largest or smallest singular values are computed).

    In the case of largest singular values, the threshold can be made relative with respect to the largest singular value (i.e., the matrix norm).

    The details are given in `SVDSetThreshold`.

    See also

    `setStoppingTest`, `getThreshold`, `SVDSetThreshold`

    Source code at slepc4py/SLEPc/SVD.pyx:583

  setTolerances(tol=None, max_it=None)

    Set the tolerance and maximum iteration count used.

    Logically collective.

    Set the tolerance and maximum iteration count used by the default SVD convergence tests.

    Parameters:

      - tol (float | None) – The convergence tolerance.

      - max_it (int | None) – The maximum number of iterations

    Return type:

      None

    Notes

    Use `DETERMINE` for `max_it` to assign a reasonably good value, which is dependent on the solution method.

    See also

    `getTolerances`, `SVDSetTolerances`

    Source code at slepc4py/SLEPc/SVD.pyx:643

  setTrackAll(trackall)

    Set flag to compute the residual of all singular triplets.

    Logically collective.

    Set if the solver must compute the residual of all approximate singular triplets or not.

    Parameters:

      trackall (bool) – Whether to compute all residuals or not.

    Return type:

      None

    See also

    `getTrackAll`, `SVDSetTrackAll`

    Source code at slepc4py/SLEPc/SVD.pyx:732

  setType(svd_type)

    Set the particular solver to be used in the SVD object.

    Logically collective.

    Parameters:

      svd_type (Type | str) – The solver to be used.

    Return type:

      None

    Notes

    The default is `CROSS`. Normally, it is best to use `setFromOptions()` and then set the SVD type from the options database rather than by using this routine. Using the options database provides the user with maximum flexibility in evaluating the different available methods.

    See also

    `getType`, `SVDSetType`

    Source code at slepc4py/SLEPc/SVD.pyx:261

  setUp()

    Set up all the internal data structures.

    Collective.

    Notes

    Sets up all the internal data structures necessary for the execution of the singular value solver.

    This function need not be called explicitly in most cases, since `solve()` calls it. It can be useful when one wants to measure the set-up time separately from the solve time.

    See also

    `solve`, `SVDSetUp`

    Source code at slepc4py/SLEPc/SVD.pyx:1164

    Return type:

      None

  setWhichSingularTriplets(which)

    Set which singular triplets are to be sought.

    Logically collective.

    Parameters:

      which (Which) – The singular values to be sought (either largest or smallest).

    Return type:

      None

    See also

    `getWhichSingularTriplets`, `SVDSetWhichSingularTriplets`

    Source code at slepc4py/SLEPc/SVD.pyx:543

  solve()

    Solve the singular value problem.

    Collective.

    Notes

    The problem matrices are specified with `setOperators()`.

    `solve()` will return without generating an error regardless of whether all requested solutions were computed or not. Call `getConverged()` to get the actual number of computed solutions, and `getConvergedReason()` to determine if the solver converged or failed and why.

    See also

    `setUp`, `setOperators`, `getConverged`, `getConvergedReason`, `SVDSolve`

    Source code at slepc4py/SLEPc/SVD.pyx:1185

    Return type:

      None

  valuesView(viewer=None)

    Display the computed singular values in a viewer.

    Collective.

    Parameters:

      viewer (Viewer | None) – Visualization context; if not provided, the standard output is used.

    Return type:

      None

    See also

    `solve`, `vectorsView`, `errorView`, `SVDValuesView`

    Source code at slepc4py/SLEPc/SVD.pyx:1456

  vectorsView(viewer=None)

    Output computed singular vectors to a viewer.

    Collective.

    Parameters:

      viewer (Viewer | None) – Visualization context; if not provided, the standard output is used.

    Return type:

      None

    See also

    `solve`, `valuesView`, `errorView`, `SVDVectorsView`

    Source code at slepc4py/SLEPc/SVD.pyx:1475

  view(viewer=None)

    Print the SVD data structure.

    Collective.

    Parameters:

      viewer (Viewer | None) – Visualization context; if not provided, the standard output is used.

    Return type:

      None

    See also

    `SVDView`

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

  Attributes Documentation

  ds

    The direct solver (`DS`) object associated.

    Source code at slepc4py/SLEPc/SVD.pyx:2013

  max_it

    The maximum iteration count.

    Source code at slepc4py/SLEPc/SVD.pyx:1999

  problem_type

    The type of the eigenvalue problem.

    Source code at slepc4py/SLEPc/SVD.pyx:1971

  tol

    The tolerance.

    Source code at slepc4py/SLEPc/SVD.pyx:1992

  track_all

    Compute the residual norm of all approximate eigenpairs.

    Source code at slepc4py/SLEPc/SVD.pyx:2006

  transpose_mode

    How to handle the transpose of the matrix.

    Source code at slepc4py/SLEPc/SVD.pyx:1978

  which

    The portion of the spectrum to be sought.

    Source code at slepc4py/SLEPc/SVD.pyx:1985