SLEPC4PY(3)

๐Ÿ“ฆ
version 3.25.1 ยท 2 versions
, in ubuntu stonking

๐ŸŒธ SLEPC4PY ๐ŸŒธ

okay bestie, strap in, because slepc4py is a whole moment and this is the manual page for it. It's the Python wrapper situation for SLEPc, and literally everyone who does big eigenvalue stuff fw it. ๐Ÿ’…

Authors: Lisandro Dalcin, Jose E. Roman

Contact: dalcinl@gmail.com, jroman@dsic.upv.es

Web Site: https://gitlab.com/slepc/slepc

Date: Jun 18, 2026

๐ŸŽ€ Abstract ๐ŸŽ€

This document describes slepc4py (https://gitlab.com/slepc/slepc), a Python (https://www.python.org) wrapper to the SLEPc (https://slepc.upv.es) libraries.

SLEPc (https://slepc.upv.es) is a software package for the parallel solution of large-scale eigenvalue problems. It can be used for computing eigenvalues and eigenvectors of large, sparse matrices, or matrix pairs, and also for computing singular values and vectors of a rectangular matrix. It also provides more advanced functionality such as solvers for nonlinear eigenvalue problems (either polynomial or general) and matrix functions. โœจ

SLEPc (https://slepc.upv.es) relies on PETSc (https://petsc.org) for basic functionality such as the representation of matrices and vectors, and the solution of linear systems of equations. Thus, slepc4py (https://gitlab.com/slepc/slepc) must be used together with its companion petsc4py (https://gitlab.com/petsc/petsc). no cap, they're a package deal, they come as a set ๐Ÿซถ

๐Ÿ’ฌ DISCUSSION AND SUPPORT ๐Ÿ’ฌ

๐Ÿ‘‘ ACKNOWLEDGMENTS ๐Ÿ‘‘

L. Dalcin was partially supported by the Extreme Computing Research Center (ECRC), Division of Computer, Electrical, and Mathematical Sciences & Engineering (CEMSE), King Abdullah University of Science and Technology (KAUST).

See additional acknowledgements related to the SLEPc project โ€” https://slepc.upv.es/release/contact/acknowledgement.html

๐Ÿ“š CONTENTS ๐Ÿ“š

๐ŸŒˆ Overview ๐ŸŒˆ

SLEPc for Python (slepc4py) is a Python package that provides convenient access to the functionality of SLEPc.

SLEPc [1], [2] implements algorithms and tools for the numerical solution of large, sparse eigenvalue problems on parallel computers. It can be used for linear eigenvalue problems in either standard or generalized form, with real or complex arithmetic. It can also be used for computing a partial SVD of a large, sparse, rectangular matrix, and to solve nonlinear eigenvalue problems (polynomial or general). Additionally, SLEPc provides solvers for the computation of the action of a matrix function on a vector.

SLEPc is intended for computing a subset of the spectrum of a matrix (or matrix pair). One can for instance approximate the largest magnitude eigenvalues, or the smallest ones, or even those eigenvalues located near a given region of the complex plane. Interior eigenvalues are harder to compute, so SLEPc provides different methodologies. One such method is to use a spectral transformation. Cheaper alternatives are also available. ๐Ÿฆ‹

  1. J. E. Roman, C. Campos, L. Dalcin, E. Romero, A. Tomas. SLEPc Users Manual. DSIC-II/24/02 - Revision 3.25. D. Sistemas Informaticos y Computacion, Universitat Politecnica de Valencia. 2026.
  2. Vicente Hernandez, Jose E. Roman and Vicente Vidal. SLEPc: A Scalable and Flexible Toolkit for the Solution of Eigenvalue Problems, ACM Trans. Math. Softw. 31(3), pp. 351-362, 2005. https://doi.org/10.1145/1089014.1089019

โœจ Features โœจ

Currently, the following types of eigenproblems can be addressed:

  • Standard eigenvalue problem, Ax = \lambda x, either for Hermitian or non-Hermitian matrices.
  • Generalized eigenvalue problem, Ax = \lambda Bx, either Hermitian positive-definite or not.
  • Partial singular value decomposition of a rectangular matrix, Au = \sigma v.
  • Generalized singular values of a matrix pair, Ax = cu, Bx = sv.
  • Polynomial eigenvalue problem, P(\lambda)=0.
  • Nonlinear eigenvalue problem, T(\lambda)=0.
  • Computing the action of a matrix function on a vector, w=f(\alpha A)v.

For the linear eigenvalue problem, the following methods are available:

  • Krylov eigensolvers, particularly Krylov-Schur, Arnoldi, and Lanczos.
  • Davidson-type eigensolvers, including Generalized Davidson and Jacobi-Davidson.
  • Subspace iteration and single vector iterations (inverse iteration, RQI).
  • Conjugate gradient methods such as LOBPCG.
  • A contour integral solver using high-order moments.

For singular value computations, the following alternatives can be used:

  • Use an eigensolver via the cross-product matrix A^*A or the cyclic matrix \left[\begin{smallmatrix}0&A\\A^*&0\end{smallmatrix}\right].
  • Explicitly restarted Lanczos bidiagonalization.
  • Implicitly restarted Lanczos bidiagonalization (thick-restart Lanczos).
  • A basic randomized solver.

For polynomial eigenvalue problems, the following methods are available:

  • Use an eigensolver to solve the generalized eigenvalue problem obtained after linearization.
  • TOAR and Q-Arnoldi, memory efficient variants of Arnoldi for polynomial eigenproblems.
  • Jacobi-Davidson for polynomial eigenproblems.
  • A contour integral solver using high-order moments.

For general nonlinear eigenvalue problems, the following methods can be used:

  • Solve a polynomial eigenproblem obtained via polynomial interpolation.
  • Rational interpolation and linearization (NLEIGS).
  • Newton-type methods such as SLP or RII.
  • A subspace projection method (nonlinear Arnoldi).
  • A contour integral solver using high-order moments.

Computation of interior eigenvalues is supported by means of the following methodologies:

  • Spectral transformations, such as shift-and-invert. This technique implicitly uses the inverse of the shifted matrix A-\sigma I in order to compute eigenvalues closest to a given target value, \sigma.
  • Harmonic extraction, a cheap alternative to shift-and-invert that also tries to approximate eigenvalues closest to a target, \sigma, but without requiring a matrix inversion.

Other remarkable features include:

  • High computational efficiency, by using NumPy and SLEPc under the hood.
  • Data-structure neutral implementation, by using efficient sparse matrix storage provided by PETSc. Implicit matrix representation is also available by providing basic operations such as matrix-vector products as user-defined Python functions.
  • Run-time flexibility, by specifying numerous setting at the command line.
  • Ability to do the computation in parallel and/or using GPUs. ๐Ÿ”ฅ

๐Ÿงš Components ๐Ÿงš

SLEPc provides the following components, which are mirrored by slepc4py for its use from Python. The first six components are solvers for different classes of problems, while the rest can be considered auxiliary object.

  • EPS โ€” The Eigenvalue Problem Solver is the component that provides all the functionality necessary to define and solve an eigenproblem. It provides mechanisms for completely specifying the problem: the problem type (e.g. standard symmetric), number of eigenvalues to compute, part of the spectrum of interest. Once the problem has been defined, a collection of solvers can be used to compute the required solutions. The behavior of the solvers can be tuned by means of a few parameters, such as the maximum dimension of the subspace to be used during the computation.
  • SVD โ€” This component is the analog of EPS for the case of Singular Value Decompositions. The user provides a rectangular matrix and specifies how many singular values and vectors are to be computed, whether the largest or smallest ones, as well as some other parameters for fine tuning the computation. Different solvers are available, as in the case of EPS.
  • PEP โ€” This component is the analog of EPS for the case of Polynomial Eigenvalue Problems. The user provides the coefficient matrices of the polynomial. Several parameters can be specified, as in the case of EPS. It is also possible to indicate whether the problem belongs to a special type, e.g., symmetric or gyroscopic.
  • NEP โ€” This component covers the case of general nonlinear eigenproblems, T(\lambda)=0. The user provides the parameter-dependent matrix T via the split form or by means of callback functions.
  • MFN โ€” This component provides the functionality for computing the action of a matrix function on a vector. Given a matrix A and a vector b, the call MFNSolve(mfn,b,x) computes x=f(A)b, where f is a function such as the exponential.
  • LME โ€” This component provides the functionality for solving linear matrix equations such as Lyapunov or Sylvester where the solution has low rank.
  • ST โ€” The Spectral Transformation is a component that provides convenient implementations of common spectral transformations. These are simple transformations that map eigenvalues to different positions, in such a way that convergence to wanted eigenvalues is enhanced. The most common spectral transformation is shift-and-invert, that allows for the computation of eigenvalues closest to a given target value.
  • BV โ€” This component encapsulates the concept of a set of Basis Vectors spanning a vector space. This component provides convenient access to common operations such as orthogonalization of vectors. The BV component is usually not required by end-users.
  • DS โ€” The Dense System (or Direct Solver) component, used internally to solve dense eigenproblems of small size that appear in the course of iterative eigensolvers.
  • FN โ€” A component used to define mathematical functions. This is required by the end-user for instance to define function T(\cdot) when solving nonlinear eigenproblems with NEP in split form.
  • RG โ€” A component used to define a region of the complex plane such as an ellipse or a rectangle. This is required by end-users in some cases such as contour-integral eigensolvers.

In addition to the above components, some extra functionality is provided in the Sys and Util sections. ๐Ÿ’–

๐ŸŒธ Tutorial ๐ŸŒธ

Below we provide links to tutorial examples intended for learning the basics of slepc4py. For additional information, the reader is referred to:

  • slepc4py Reference (#reference) โ€” manual pages for all slepc4py classes and methods. ๐Ÿ“–

๐ŸŒธ Commented source of demo examples

  • To get started, we highly recommend peeping the source code of the example demo/ex1.py, which has comments inserted inline (so it's giving tutorial energy, not just code energy ๐Ÿ’…). It's also up online here: ../slepc4py/demo/ex1.html. This example solves a standard symmetric eigenvalue problem, no cap.
  • Demo examples for other problems โ€” including linear and nonlinear eigenvalue problems and singular value problems โ€” live in the section slepc4py demos (see #demos). yes there's a whole buffet ๐Ÿ“

๐Ÿ›  Installation

โœจ Install from PyPI using pip

You can use pip to install slepc4py and its dependencies. easy peasy.

If you have a working MPI implementation and the mpicc compiler wrapper is on your search path, it is highly recommended to install mpi4py first โ€” like, do it, don't skip this step:

$ python -m pip install mpi4py

Make sure you've got NumPy and petsc4py installed too:

$ python -m pip install numpy petsc petsc4py

And finally, install slepc4py:

$ python -m pip install slepc slepc4py

If you already have working PETSc and SLEPc installs, set the environment variables SLEPC_DIR and PETSC_DIR (and perhaps PETSC_ARCH for non-prefix installs) to appropriate values, and then use pip:

$ export SLEPC_DIR=/path/to/slepc
$ export PETSC_DIR=/path/to/petsc
$ export PETSC_ARCH=arch-linux2-c-opt
$ python -m pip install petsc4py slepc4py

๐Ÿฆ‹ Install from the SLEPc source tree

If you also want to install petsc4py from the PETSc source tree, follow the instructions on the petsc4py installation page: https://petsc.org/release/petsc4py/install.html.

Set the PETSC_DIR and PETSC_ARCH environment variables, as well as SLEPC_DIR. Then follow the instructions to build SLEPc (https://slepc.upv.es/release/installation/index.html). After that, cd to the top of the SLEPc source tree and run:

$ python -m pip install src/binding/slepc4py

The installation of slepc4py supports multiple PETSC_ARCH values, in the form of a colon separated list:

$ PETSC_ARCH='arch-0:...:arch-N' python -m pip install src/binding/slepc4py

If you are cross-compiling, and the numpy module cannot be loaded on your build host, then before invoking pip, set the NUMPY_INCLUDE environment variable to the path that would be returned by import numpy; numpy.get_include():

$ export NUMPY_INCLUDE=/usr/lib/pythonX/site-packages/numpy/core/include

๐ŸŒŸ Citations

If SLEPc for Python has been significant to a project that leads to an academic publication, please acknowledge that fact by citing the project. (it's the polite thing to do, and also it's how the maintainers eat ๐Ÿซถ)

There is also a whole list of SLEPc-related references at https://slepc.upv.es/release/material. iykyk ๐Ÿ“–

๐Ÿ’€ CHANGES

๐ŸŒˆ Release 3.25

  • Update to SLEPc 3.25.

๐ŸŒˆ Release 3.24

  • Update to SLEPc 3.24.
  • Support (opt-in via setting the environment variable SLEPC4PY_BUILD_PYSABI=1) for building with Py_LIMITED_API (Python Stable ABI) under Python 3.10+ (requires Cython 3.1+). fancy.
  • Add support for standard Python operators for BV and FN classes.
  • Add new LME class.

๐ŸŒˆ Release 3.23

  • Update to SLEPc 3.23.

๐ŸŒˆ Release 3.22

  • Update to SLEPc 3.22.
  • In slepc4py, EPS.getEigenpair() and EPS.getEigenvalue() will now return a real value instead of a complex one, if the problem is of Hermitian or generalized Hermitian type. ok that's a glow-up โœจ

๐ŸŒˆ Release 3.21

  • Update to SLEPc 3.21.

๐ŸŒˆ Release 3.20

  • Update to SLEPc 3.20.

๐ŸŒˆ Release 3.19

  • Update to SLEPc 3.19.

๐ŸŒˆ Release 3.18

  • Update to SLEPc 3.18.

๐ŸŒˆ Release 3.17

  • Update to SLEPc 3.17.

๐ŸŒˆ Release 3.16

  • Update to SLEPc 3.16.

๐ŸŒˆ Release 3.15

  • Update to SLEPc 3.15.
  • Updates in installation scripts.

๐ŸŒˆ Release 3.14

  • Update to SLEPc 3.14.

๐ŸŒˆ Release 3.13

  • Update to SLEPc 3.13.

๐ŸŒˆ Release 3.12

  • Update to SLEPc 3.12.

๐ŸŒˆ Release 3.11

  • Update to SLEPc 3.11.

๐ŸŒˆ Release 3.10

  • Update to SLEPc 3.10.

๐ŸŒˆ Release 3.9

  • Update to SLEPc 3.9.

๐ŸŒˆ Release 3.8

  • Update to SLEPc 3.8.

๐ŸŒˆ Release 3.7

  • Update to SLEPc 3.7.

๐ŸŒˆ Release 3.6

  • Update to SLEPc 3.6.

๐ŸŒˆ Release 3.5

  • Update to SLEPc 3.5.
  • Add RG class introduced in SLEPc 3.5 release.
  • Add PySlepcXXX_New/Get C API functions.
  • Fix compilation problem with complex scalars on OS X.
  • Fix outdated SWIG interface file.

๐ŸŒˆ Release 3.4

  • Update to SLEPc 3.4.

๐ŸŒˆ Release 3.3

  • Update to SLEPc 3.3.
  • Regenerate the wrappers using Cython 0.18 and fix binary compatibility issues with petsc4py 3.3.1.

๐ŸŒˆ Release 1.2

  • Update to SLEPc 3.2.

๐ŸŒˆ Release 1.1

  • Support for new QEP quadratic eigenproblem solver in SLEPc.
  • Support for pip install slepc4py to download and install SLEPc.
  • Support for PETSc/SLEPc static library builds (Linux-only).
  • Preliminary support for Python 3.

๐ŸŒˆ Release 1.0.0

  • This is the fist release of the all-new, Cython-based, implementation of SLEPc for Python. (yes bestie, "fist" โ€” that's literally how it's spelled in the original docs and we respect it ๐Ÿ’€)

๐Ÿ‘‘ Reference

  • slepc4py โ€” SLEPc for Python
  • slepc4py.typing โ€” Typing support.
  • slepc4py.SLEPc โ€” Scalable Library for Eigenvalue Problem Computations

๐Ÿงš slepc4py

๐Ÿ’œ SLEPc for Python

This package is an interface to the SLEPc libraries.

SLEPc (the Scalable Library for Eigenvalue Problem Computations) is a software library for the solution of large scale sparse eigenvalue problems on parallel computers. It's an extension of PETSc, and it can be used for either standard or generalized eigenproblems, with real or complex arithmetic. It can also be used for computing a partial SVD of a large, sparse, rectangular matrix, and to solve nonlinear eigenvalue problems (polynomial or general). And on top of all that, SLEPc provides solvers for the computation of the action of a matrix function on a vector. it does everything fr ๐Ÿ”ฅ

๐Ÿ“ Functions

  • get_config() โ€” Return a dictionary with information about SLEPc.
  • get_include() โ€” Return the directory in the package that contains header files.
  • init([args, arch, comm]) โ€” Initialize SLEPc.

๐ŸŽ€ slepc4py.get_config

slepc4py.get_config()

Return a dictionary with information about SLEPc.

Return type: dict[str, str]

๐ŸŽ€ slepc4py.get_include

slepc4py.get_include()

Return the directory in the package that contains header files.

Extension modules that need to compile against slepc4py should use this function to locate the appropriate include directory.

Example

Using Python distutils or NumPy distutils:

import petscc4py, slepc4py
Extension('extension_name', ...
          include_dirs=[...,
                        petsc4py.get_include(),
                        slepc4py.get_include(),])
ok so that petscc4py with the double-c? that is straight-up copied from the original docs, do not come for me ๐Ÿ™ˆ

Return type: str

๐ŸŽ€ slepc4py.init

slepc4py.init(args=None, arch=None, comm=None)

Initialize SLEPc.

Parameters

  • args (str | list[str] | None) โ€“ Command-line arguments, usually the sys.argv list.
  • arch (str | None) โ€“ Specific configuration to use.
  • comm (Intracomm | None) โ€” the MPI commmunicator ๐Ÿซถ (that's mpi4py.MPI.Intracomm, or just None if you don't have one to hand).

Return type

None โ€” it gives you literally nothing back, and that's fine ๐Ÿ’…

Notes

This function should be called only once, typically at the very beginning of the bootstrap script of an application. One time. At the top. Before anything else happens. Not me calling it twice and wondering why the vibes are off ๐Ÿ˜ญ

โœจ slepc4py.typing โœจ

Typing support. Bestie, this is the whole type-alias wardrobe, and it's giving very organized ๐ŸŽ€

Attributes

  • Scalar โ€” Scalar type. ๐Ÿ’œ
  • ArrayBool โ€” Array of bool.
  • ArrayInt โ€” Array of int.
  • ArrayReal โ€” Array of float.
  • ArrayComplex โ€” Array of complex.
  • ArrayScalar โ€” Array of Scalar numbers. ๐ŸŒธ
  • LayoutSizeSpec โ€” int or 2-tuple of int describing the layout sizes.
  • EPSStoppingFunction โ€” EPS stopping test callback.
  • EPSArbitraryFunction โ€” EPS arbitrary selection callback.
  • EPSEigenvalueComparison โ€” EPS eigenvalue comparison callback.
  • EPSMonitorFunction โ€” EPS monitor callback.
  • PEPStoppingFunction โ€” PEP stopping test callback.
  • PEPEigenvalueComparison โ€” PEP eigenvalue comparison callback.
  • PEPMonitorFunction โ€” PEP monitor callback.
  • NEPStoppingFunction โ€” NEP stopping test callback.
  • NEPEigenvalueComparison โ€” NEP eigenvalue comparison callback.
  • NEPMonitorFunction โ€” NEP monitor callback.
  • NEPFunction โ€” NEP Function callback.
  • NEPJacobian โ€” NEP Jacobian callback.
  • SVDStoppingFunction โ€” SVD stopping test callback.
  • SVDMonitorFunction โ€” SVD monitor callback.
  • MFNMonitorFunction โ€” MFN monitor callback.
  • LMEMonitorFunction โ€” LME monitor callback. ๐Ÿ‘‘

๐Ÿฆ‹ slepc4py.typing.Scalar ๐Ÿฆ‹

slepc4py.typing.Scalar = float | complex

Scalar type. iconic โœจ

Scalars can be either float or complex (but not both) depending on how PETSc was configured:

./configure --with-scalar-type=real|complex

Like, you pick one and you commit, no cap ๐Ÿ’…

๐Ÿ“ slepc4py.typing.ArrayBool ๐Ÿ“

slepc4py.typing.ArrayBool

Array of bool. โœจ

โ€ฆand the alias for it is literally ndarray[tuple[Any, โ€ฆ], dtype[bool]] โœจ โ€” yes bestie, a whole numpy array of bools, no notes, periodt. ๐Ÿ’…

๐Ÿ”— link legend, because these links repeat like a chorus โ€” wherever one of these names shows up below, this is the exact page it points at, iykyk: - ndarray โ†’ https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray - tuple โ†’ https://docs.python.org/3/library/stdtypes.html#tuple - Any โ†’ https://docs.python.org/3/library/typing.html#typing.Any - dtype โ†’ https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype - bool โ†’ https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.bool - int โ†’ https://docs.python.org/3/library/functions.html#int - integer โ†’ https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.integer - float โ†’ https://docs.python.org/3/library/functions.html#float - floating โ†’ https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.floating - complex โ†’ https://docs.python.org/3/library/functions.html#complex - complexfloating โ†’ https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.complexfloating - Callable โ†’ https://docs.python.org/3/library/typing.html#typing.Callable - Vec โ†’ https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Vec.html#petsc4py.PETSc.Vec - None โ†’ https://docs.python.org/3/library/constants.html#None

slepc4py.typing.ArrayInt

an array of int ๐Ÿงฎ โ€” like, a numpy array, but make it ints.

it's an alias of:

ndarray[tuple[Any, โ€ฆ], dtype[integer]]

that's it, that's the whole vibe. ๐Ÿ’œ

slepc4py.typing.ArrayReal

an array of float ๐ŸŒธ โ€” floating point besties, all lined up.

alias of:

ndarray[tuple[Any, โ€ฆ], dtype[floating]]

slepc4py.typing.ArrayComplex

an array of complex ๐ŸŒ€ โ€” real part, imaginary part, the whole situation.

alias of:

ndarray[tuple[Any, โ€ฆ], dtype[complexfloating]]

slepc4py.typing.ArrayScalar

an array of Scalar numbers ๐Ÿ’ซ โ€” and Scalar is the Scalar type from this very module (slepc4py.typing.Scalar), so yes, it's giving "one array type to hold whatever scalar you're on".

alias of:

ndarray[tuple[Any, โ€ฆ], dtype[floating | complexfloating]]

slepc4py.typing.LayoutSizeSpec

slepc4py.typing.LayoutSizeSpec = int | tuple[int, int]

okay so this one is either a plain int or a 2-tuple of int, and it's describing the layout sizes ๐ŸŽ€. which one you hand over changes what it means:

  • a single int = the global size, that's it, that's the whole story ๐Ÿ‘‘
  • a tuple of int = (local_size, global_size) โ€” local first, global second, don't you dare flip them ๐Ÿ’…

slepc4py.typing.EPSStoppingFunction

EPS stopping test callback. ๐Ÿ›‘

alias of:

Callable[[EPS, int, int, int, int], ConvergedReason]

so it hands you an EPS, four ints, and expects a ConvergedReason back โ€” specifically EPS.ConvergedReason, the one that lives on slepc4py.SLEPc.EPS. โœจ

slepc4py.typing.EPSArbitraryFunction

EPS arbitrary selection callback. ๐ŸŽฏ

alias of:

Callable[[float | complex, float | complex, Vec, Vec, float | complex, float | complex], [float | complex, float | complex]]

like, in go six things (two scalar-ish values, two Vecs, then two more scalar-ish values), out come two scalar-ish values. the Vec here is the petsc4py one. no cap. ๐Ÿซถ

slepc4py.typing.EPSEigenvalueComparison

EPS eigenvalue comparison callback. โš–๏ธ

alias of:

Callable[[float | complex, float | complex, float | complex, float | complex], int]

four eigenvalue-ish values in, one int out โ€” classic comparison energy. ๐Ÿ’œ

slepc4py.typing.EPSMonitorFunction

EPS monitor callback. ๐Ÿ“Š

alias of:

Callable[[EPS, int, int, ndarray[tuple[Any, โ€ฆ], dtype[floating | complexfloating]], ndarray[tuple[Any, โ€ฆ], dtype[floating | complexfloating]], ndarray[tuple[Any, โ€ฆ], dtype[floating]], int], None]

look closely bestie: the third array is floating | complexfloating (same as the second one), but the fourth array is plain floating only ๐Ÿ˜ญ โ€” that's not a typo, that's what the original says, so I'm saying it too. and it returns None. that's the whole signature, periodt.

slepc4py.typing.PEPStoppingFunction

PEP stopping test callback. ๐Ÿ›‘

alias of:

Callable[[PEP, int, int, int, int], ConvergedReason]

a PEP plus four ints in, a ConvergedReason out โ€” and that's PEP.ConvergedReason from slepc4py.SLEPc.PEP. ๐Ÿ’–

slepc4py.typing.PEPEigenvalueComparison

PEP eigenvalue comparison callback. โš–๏ธ

๐Ÿ™ˆ real talk: in the source this one's link points at #slepc4py.SLEPc.NEP even though the text says PEP. I'm not fixing it, I'm not hiding it, I'm just telling you. that's the lore.

alias of:

Callable[[float | complex, float | complex, float | complex, float | complex], int]

four eigenvalue-ish values in, one int out. same shape as the EPS one, different parent. ๐Ÿฆ‹

slepc4py.typing.PEPMonitorFunction

PEP monitor callback. ๐Ÿ“Š

that's where this chunk of the page ends, so the signature for this one is coming at you in the next part โ€” stay tuned, don't touch that dial ๐ŸŒˆ

โ€ฆand the very next one is the alias whose name got served at the tail end of the last part โ€” you know the drill, it's just a Callable with a whole lotta types in it:

that PEP callback alias ๐Ÿฆ‹

A PEP callback that hands you the PEP itself, three plain ints, three numpy ndarrays (each one shaped as tuple[Any, โ€ฆ] and typed dtype[floating | complexfloating]), and one more int โ€” and gives you back None because it's a callback, it's not here to return you a gift.

Callable[[PEP, int, int, ndarray[tuple[Any, โ€ฆ], dtype[floating | complexfloating]], ndarray[tuple[Any, โ€ฆ], dtype[floating | complexfloating]], ndarray[tuple[Any, โ€ฆ], dtype[floating | complexfloating]], int], None]
tiny aside so you're not lost, bestie: all these type names are hyperlinked in the original docs โ€” Callable and Any point at docs.python.org/3/library/typing.html, int / float / complex at docs.python.org/3/library/functions.html, tuple at docs.python.org/3/library/stdtypes.html, None at docs.python.org/3/library/constants.html, ndarray / dtype / floating / complexfloating at the numpy docs, and Mat at petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html. iykyk ๐Ÿ’…

slepc4py.typing.NEPStoppingFunction ๐ŸŽ€

The NEP stopping test callback, periodt. Definition-list head and its own name again, iconic.

It's an alias of:

Callable[[NEP, int, int, int, int], ConvergedReason]

So: the NEP, four ints, and you hand back a ConvergedReason โ€” specifically slepc4py.SLEPc.NEP.ConvergedReason. slay.

slepc4py.typing.NEPEigenvalueComparison ๐ŸŒธ

The NEP eigenvalue comparison callback. it's giving "sort my eigenvalues please."

Alias of:

Callable[[float | complex, float | complex, float | complex, float | complex], int]

Four eigenvalue-ish values, each allowed to be float or complex, and it hands back an int. literally that's it.

slepc4py.typing.NEPMonitorFunction โœจ

The NEP monitor callback โ€” the little narrator that watches every iteration.

Alias of:

Callable[[NEP, int, int, ndarray[tuple[Any, โ€ฆ], dtype[floating | complexfloating]], ndarray[tuple[Any, โ€ฆ], dtype[floating | complexfloating]], ndarray[tuple[Any, โ€ฆ], dtype[floating | complexfloating]], int], None]

NEP, two ints, three ndarrays (tuple[Any, โ€ฆ] shaped, dtype[floating | complexfloating] typed), one more int, and None on the way out. no cap. ๐Ÿ”ฅ

slepc4py.typing.NEPFunction ๐Ÿ’–

The NEP Function callback โ€” capital F, we respect it.

Alias of:

Callable[[NEP, float | complex, Mat, Mat], None]

That's the NEP, a float | complex, and two Mats (the petsc4py PETSc.Mat kind, obvi), returning None.

slepc4py.typing.NEPJacobian ๐Ÿงš

The NEP Jacobian callback. yes babe, the J-word. ๐Ÿ’€

Alias of:

Callable[[NEP, float | complex, Mat], None]

The NEP, a float | complex, one Mat, and back comes None.

slepc4py.typing.SVDStoppingFunction ๐ŸŒˆ

The SVD stopping test callback.

Alias of:

Callable[[SVD, int, int, int, int], ConvergedReason]

SVD, four ints, and you return a ConvergedReason โ€” the slepc4py.SLEPc.SVD.ConvergedReason flavor, to be precise.

slepc4py.typing.SVDMonitorFunction ๐Ÿ“

The SVD monitor callback, aka the group chat that reads every iteration out loud.

Alias of:

Callable[[SVD, int, int, ndarray[tuple[Any, โ€ฆ], dtype[floating]], ndarray[tuple[Any, โ€ฆ], dtype[floating]], int], None]

Careful here bestie, this one's dtype[floating] โ€” not floating | complexfloating, there's no complex invite at this party. So: SVD, two ints, ndarray of tuple[Any, โ€ฆ] / dtype[floating], another one of those, one more int, then None.

slepc4py.typing.MFNMonitorFunction ๐Ÿ‘‘

The MFN monitor callback.

Alias of:

Callable[[MFN, int, float], None]

MFN, an int, a float, None. short, sweet, ate. ๐Ÿซถ

slepc4py.typing.LMEMonitorFunction ๐Ÿ’œ

The LME monitor callback. same energy as the last one, different acronym.

Alias of:

Callable[[LME, int, float], None]

LME, int, float, None. periodt.

slepc4py.SLEPc โญ

And here's the main character herself, the module we've all been waiting for:

Scalable Library for Eigenvalue Problem Computations

(that's the one-liner, verbatim โ€” queen behavior ๐Ÿ‘‘)

โ€ฆand that's exactly where we're picking up next, because there is so much more of this module to go, and we are not even close to done. ๐Ÿ’…

๐Ÿ’… Classes

okay so these are the entire cast of characters in SLEPc, and honestly? every single one of them is a main character. quick little roster so u know who's who ๐ŸŽ€

  • BV โ€” Basis Vectors.
  • DS โ€” Direct Solver (or Dense System).
  • EPS โ€” Eigenvalue Problem Solver.
  • FN โ€” Mathematical Function.
  • LME โ€” Linear Matrix Equation.
  • MFN โ€” Matrix Function.
  • NEP โ€” Nonlinear Eigenvalue Problem Solver.
  • PEP โ€” Polynomial Eigenvalue Problem Solver.
  • RG โ€” Region.
  • ST โ€” Spectral Transformation.
  • SVD โ€” Singular Value Decomposition Solver.
  • Sys โ€” System utilities.
  • Util โ€” Other utilities such as the creation of structured matrices.

๐ŸŒˆ slepc4py.SLEPc.BV

class slepc4py.SLEPc.BV

Bases: petsc4py.PETSc.Object

Basis Vectors. ๐Ÿฆ‹

bestie. listen. the BV package gives u the whole concept of a block of vectors โ€” like a lil squad of vectors that represent the basis of a subspace. the entire point is that these vectors usually get up to stuff together, so it's way more convenient to handle them as one group than to be out here juggling an array of petsc4py.PETSc.Vec by urself. it's giving organized. it's giving found family. ๐Ÿ’–

Enumerations

  • MatMultType โ€” BV mat-mult types.
  • OrthogBlockType โ€” BV block-orthogonalization types.
  • OrthogRefineType โ€” BV orthogonalization refinement types.
  • OrthogType โ€” BV orthogonalization types.
  • SVDMethod โ€” BV methods for computing the SVD.
  • Type โ€” BV type.

โœจ slepc4py.SLEPc.BV.MatMultType

class slepc4py.SLEPc.BV.MatMultType

Bases: object

BV mat-mult types. literally what it says on the tin ๐Ÿ’…

  • VECS: Perform a matrix-vector multiply per each column.
  • MAT: Carry out a Mat-Mat product with a dense matrix.
๐ŸŒธ See also: BVMatMultType โ€” https://slepc.upv.es/release/manualpages/BV/BVMatMultType.html

Attributes Summary

  • MAT โ€” Constant MAT of type int
  • VECS โ€” Constant VECS of type int

Attributes Documentation

  • MAT: int = MAT โ€” Constant MAT of type int.
  • VECS: int = VECS โ€” Constant VECS of type int.

also chilling in here, no notes: ๐Ÿ™ˆ

  • __init__()
  • classmethod __new__(*args, **kwargs)

๐Ÿ’œ slepc4py.SLEPc.BV.OrthogBlockType

class slepc4py.SLEPc.BV.OrthogBlockType

Bases: object

BV block-orthogonalization types. aka all the different ways we can make a whole block of vectors behave and stop being messy ๐Ÿซถ

  • GS: Gram-Schmidt, column by column.
  • CHOL: Cholesky QR method.
  • TSQR: Tall-skinny QR method.
  • TSQRCHOL: Tall-skinny QR, but computing the triangular factor only.
  • SVQB: SVQB method.
โญ See also: BVOrthogBlockType โ€” https://slepc.upv.es/release/manualpages/BV/BVOrthogBlockType.html

๐ŸŒˆ Attributes Summary ๐ŸŒˆ

okay so this is the little cheat-sheet of all the constants this enum has to offer, bestie ๐Ÿ’–

๐Ÿ“– Attributes Documentation ๐Ÿ“–

the receipts, one by one ๐Ÿงพโœจ

CHOL ๐Ÿ’…

CHOL: int โ€” https://docs.python.org/3/library/functions.html#int โ€” = CHOL

Constant CHOL of type int (https://docs.python.org/3/library/functions.html#int)

GS ๐ŸŽ€

GS: int โ€” https://docs.python.org/3/library/functions.html#int โ€” = GS

Constant GS of type int (https://docs.python.org/3/library/functions.html#int)

SVQB ๐Ÿฆ‹

SVQB: int โ€” https://docs.python.org/3/library/functions.html#int โ€” = SVQB

Constant SVQB of type int (https://docs.python.org/3/library/functions.html#int)

TSQR ๐ŸŒธ

TSQR: int โ€” https://docs.python.org/3/library/functions.html#int โ€” = TSQR

Constant TSQR of type int (https://docs.python.org/3/library/functions.html#int)

TSQRCHOL ๐Ÿ‘‘

TSQRCHOL: int โ€” https://docs.python.org/3/library/functions.html#int โ€” = TSQRCHOL

Constant TSQRCHOL of type int (https://docs.python.org/3/library/functions.html#int)

__init__() ๐Ÿซถ

literally just this:

__init__()

classmethod __new__(*args, **kwargs) โญ

classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.BV.OrthogRefineType ๐Ÿ’œ

class slepc4py.SLEPc.BV.OrthogRefineType

Bases: object (https://docs.python.org/3/library/functions.html#object)

BV orthogonalization refinement types. so like, do we re-orthogonalize or nah? that's the whole personality of this enum ๐Ÿ˜Œ

  • IFNEEDED: Reorthogonalize if a criterion is satisfied.
  • NEVER: Never reorthogonalize.
  • ALWAYS: Always reorthogonalize.

See also:

๐ŸŒˆ Attributes Summary ๐ŸŒˆ

๐Ÿ“– Attributes Documentation ๐Ÿ“–

ALWAYS ๐Ÿ”ฅ

ALWAYS: int โ€” https://docs.python.org/3/library/functions.html#int โ€” = ALWAYS

Constant ALWAYS of type int (https://docs.python.org/3/library/functions.html#int)

IFNEEDED โœจ

IFNEEDED: int โ€” https://docs.python.org/3/library/functions.html#int โ€” = IFNEEDED

Constant IFNEEDED of type int (https://docs.python.org/3/library/functions.html#int)

NEVER ๐Ÿ’€

NEVER: int โ€” https://docs.python.org/3/library/functions.html#int โ€” = NEVER

Constant NEVER of type int (https://docs.python.org/3/library/functions.html#int)

__init__() ๐Ÿซถ

__init__()

classmethod __new__(*args, **kwargs) โญ

classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.BV.OrthogType ๐ŸŽ€

class slepc4py.SLEPc.BV.OrthogType

Bases: object (https://docs.python.org/3/library/functions.html#object)

BV orthogonalization types. two flavours, pick your fighter ๐ŸฅŠ

  • CGS: Classical Gram-Schmidt.
  • MGS: Modified Gram-Schmidt.

See also:

๐ŸŒˆ Attributes Summary ๐ŸŒˆ

๐Ÿ“– Attributes Documentation ๐Ÿ“–

CGS ๐ŸŒธ

CGS: int โ€” https://docs.python.org/3/library/functions.html#int โ€” = CGS

Constant CGS of type int (https://docs.python.org/3/library/functions.html#int)

MGS ๐Ÿฆ‹

MGS: int โ€” https://docs.python.org/3/library/functions.html#int โ€” = MGS

Constant MGS of type int (https://docs.python.org/3/library/functions.html#int)

__init__() ๐Ÿซถ

__init__()

classmethod __new__(*args, **kwargs) โญ

classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.BV.SVDMethod ๐Ÿ‘‘

class slepc4py.SLEPc.BV.SVDMethod

Bases: object (https://docs.python.org/3/library/functions.html#object)

BV methods for computing the SVD. three whole routes to the same glow-up โœจ

  • REFINE: Based on the SVD of the cross product matrix S^* S, with refinement.
  • QR: Based on the SVD of the triangular factor of qr(S).
  • QR_CAA: Variant of QR intended for use in communication-avoiding. Arnoldi.

See also:

๐ŸŒˆ Attributes Summary ๐ŸŒˆ

๐Ÿ“– Attributes Documentation ๐Ÿ“–

QR ๐Ÿ’…

QR: int โ€” https://docs.python.org/3/library/functions.html#int โ€” = QR

Constant QR of type int (https://docs.python.org/3/library/functions.html#int)

  • QR_CAA: int = QR_CAA โ€” constant QR_CAA, and its type is straight-up int and nothing else, bestie. Constant QR_CAA of type int. โœจ
  • REFINE: int = REFINE โ€” constant REFINE, also vibing as an int. Constant REFINE of type int. ๐ŸŽ€

__init__() โ€” the init, doing init things. ๐Ÿ’…

classmethod __new__(*args, **kwargs) โ€” the classmethod __new__, taking *args and **kwargs, exactly like that, no notes. ๐Ÿซถ

๐ŸŒˆ class slepc4py.SLEPc.BV.Type

class slepc4py.SLEPc.BV.Type

Bases: object

Okay so this is the BV type type, and it's the little menu of ways a BV can be stored. Not me being obsessed with storage layouts but??? it matters. ๐Ÿ˜ญ

  • MAT โ€” a BV stored as a dense Mat. Dense. Mat. Energy. ๐Ÿ”ฅ
  • SVEC โ€” a BV stored as a single Vec. One vec, that's it, she's simple, she's iconic. โœจ
  • VECS โ€” a BV stored as an array of independent Vecs. Freedom. Independence. Main character energy. ๐Ÿ‘‘
  • CONTIGUOUS โ€” a BV stored as an array of Vec that all share a contiguous array of scalars. They're sharing, bestie, it's giving community. ๐Ÿซถ
  • TENSOR โ€” a special BV represented in compact form as V = (I \otimes U) S. Yes the math is mathing. ๐Ÿงš
See also: BVType โ€” https://slepc.upv.es/release/manualpages/BV/BVType.html

๐Ÿ’– Attributes Summary

  • CONTIGUOUS โ€” object CONTIGUOUS of type str
  • MAT โ€” object MAT of type str
  • SVEC โ€” object SVEC of type str
  • TENSOR โ€” object TENSOR of type str
  • VECS โ€” object VECS of type str

โœจ Attributes Documentation

  • CONTIGUOUS: str = CONTIGUOUS โ€” object CONTIGUOUS of type str. ๐ŸŽ€
  • MAT: str = MAT โ€” object MAT of type str. ๐ŸŽ€
  • SVEC: str = SVEC โ€” object SVEC of type str. ๐ŸŽ€
  • TENSOR: str = TENSOR โ€” object TENSOR of type str. ๐ŸŽ€
  • VECS: str = VECS โ€” object VECS of type str. ๐ŸŽ€

__init__() โ€” yep, it's the init again. ๐Ÿ’…

classmethod __new__(*args, **kwargs) โ€” and the classmethod __new__, taking *args and **kwargs. identical signature, different class, we contain multitudes ๐ŸŒˆ

๐Ÿ’– Methods Summary ๐Ÿ’–

okay bestie, here's the full lineup of methods this object gives you ๐ŸŒˆ we are NOT skipping any of them, every single one is getting its moment, periodt โœจ

  • appendOptionsPrefix([prefix]) โ€” staples some extra text onto the prefix that's used when hunting down all the BV options in the database ๐Ÿ”
  • applyMatrix(x, y) โ€” multiplies a vector by the matrix that's tied to the bilinear form ๐Ÿ’ซ
  • copy([result]) โ€” copies one basis vector object straight into another one, like a glow-up transplant ๐Ÿซถ
  • copyColumn(j, i) โ€” takes the values sitting in one of the columns and drops them into another column ๐Ÿ“‹
  • copyVec(j, v) โ€” grabs one of the columns of a basis vectors object and copies it into a vector, easy peasy ๐Ÿ“
  • create([comm]) โ€” makes the BV object exist. iconic birth moment ๐Ÿ‘‘
  • createFromMat(A) โ€” builds a basis vectors object fresh out of a dense matrix โœจ
  • createMat() โ€” spins up a brand new dense matrix and copies all the BV's contents into it ๐Ÿ“ฆ
  • createVec() โ€” makes a vector that matches the type and dimensions of the BV's columns ๐Ÿงš
  • destroy() โ€” destroys the BV object. it's giving closure, respectfully ๐Ÿ’€
  • dot(Y) โ€” computes the 'block-dot' product of two basis vectors objects ๐Ÿ”ฅ
  • dotColumn(j) โ€” dot products of one column against all the column vectors of a BV ๐ŸŒธ
  • dotVec(v) โ€” dot products of a vector against all the column vectors of the BV ๐Ÿ’œ
  • duplicate() โ€” duplicates the BV object with the exact same type and dimensions, twin behavior fr fr ๐Ÿ‘ฏ
  • duplicateResize(m) โ€” creates a BV object with the same type and dimensions as an existing one ๐Ÿฆ‹
  • getActiveColumns() โ€” hands you the current active dimensions โญ
  • getArray([readonly]) โ€” returns the array where all the data is actually stored ๐Ÿ“š
  • getColumn(j) โ€” gives you a vector holding the entries from the column of the BV object ๐ŸŒท
  • getDefiniteTolerance() โ€” gets the tolerance used when checking a definite inner product ๐ŸŽฏ
  • getLeadingDimension() โ€” gets the leading dimension, no cap ๐Ÿ“
  • getMat() โ€” gets a matrix of dense type that shares memory with the BV object, bestie they're literally sharing ๐Ÿซ‚
  • getMatMultMethod() โ€” gets the method that's used for the matMult() operation โš™๏ธ
  • getMatrix() โ€” gets the matrix representation of the inner product ๐Ÿ’…
  • getNumConstraints() โ€” gets how many constraints there are ๐Ÿ”ข
  • getOptionsPrefix() โ€” gets the prefix used when searching for all the BV options in the database ๐Ÿ”
  • getOrthogonalization() โ€” gets the orthogonalization settings straight off the BV object โœจ
  • getRandomContext() โ€” gets the petsc4py.PETSc.Random โ€” https://petsc.org/
  • getSizes() โ€” bestie this one just tells you the local size, the global size, and how many columns you're working with. all three, no gatekeeping ๐Ÿ’…
  • getType() โ€” hands you the BV type of this object. that's the whole job. iconic behaviour honestly โœจ
  • getVecType() โ€” tells you which vector type gets used when you make vectors via createVec(). useful when you gotta know what you're spawning ๐Ÿฆ‹
  • insertConstraints(C) โ€” shove a whole set of vectors in as constraints. they're not regular columns, they're rules. periodt.
  • insertVec(j, w) โ€” drop a single vector w into the specified column j. one vector, one column, no drama ๐ŸŽ€
  • insertVecs(s, W[, orth]) โ€” insert a whole set of vectors into the specified columns starting at s, with optional orth. batch insert energy fr fr ๐ŸŒˆ
  • matMult(A[, Y]) โ€” compute the matrix-vector product for every single column: Y = A V. all of them. at once. slay ๐Ÿ”ฅ
  • matMultColumn(A, j) โ€” mat-vec product for just column j, and the result goes into the next column. heads up, it writes forward, not back ๐Ÿ‘€
  • matMultHermitianTranspose(A[, Y]) โ€” pre-multiplication with the conjugate transpose of a matrix. hermitian girlies rise ๐Ÿ™ˆ
  • matMultHermitianTransposeColumn(A, j) โ€” the conjugate-transpose matrix-vector product, but just for one specified column. same deal, one column only ๐Ÿ’œ
  • matMultTranspose(A[, Y]) โ€” pre-multiplication with the plain transpose of a matrix. no conjugation here, just flipping โœจ
  • matMultTransposeColumn(A, j) โ€” transpose matrix-vector product for a specified column. one at a time bestie ๐Ÿซถ
  • matProject(A, Y) โ€” compute the projection of a matrix onto a subspace. it's giving linear algebra selfie ๐Ÿ’…
  • mult(delta, gamma, X, Q) โ€” compute Y = \gamma Y + \delta X Q. yes those are real greek letters and yes you need both ๐Ÿ“
  • multColumn(delta, gamma, j, q) โ€” compute y = \gamma y + \delta X q for a single column j. lowercase version, same vibe ๐ŸŒธ
  • multInPlace(Q, s, e) โ€” updates a set of vectors like so: V(:,s:e-1) = V Q(:,s:e-1). it's in place so your old V is gone, she's new now ๐Ÿ’€
  • multVec(delta, gamma, y, q) โ€” compute y = \gamma y + \delta X q. single vector edition, still got the greeks โœจ
  • norm([norm_type]) โ€” compute the matrix norm of the BV. pass norm_type if you're picky about which norm, otherwise default behaviour ๐ŸŽ€
  • normColumn(j[, norm_type]) โ€” compute the vector norm of one selected column j, with optional norm_type. just one, not all, we're being specific ๐Ÿ˜Œ
  • orthogonalize([R]) โ€” orthogonalize all the columns (except the leading ones), via QR decomposition. optionally stash the R factor ๐Ÿฆ‹
  • orthogonalizeColumn(j) โ€” orthogonalize column vector j against all the previous ones. one column, fighting for her independence ๐Ÿ’ช
  • orthogonalizeVec(v) โ€” orthogonalize a vector v with respect to every active column. all of them at once, brave ๐Ÿซถ
  • orthonormalizeColumn(j[, replace]) โ€” orthonormalize column vector j with respect to the previous ones. yes there's a difference from orthogonalize, and yes the replace option is there ๐ŸŒŸ
  • resize(m[, copy]) โ€” change the number of columns to m. optional copy decides if the old ones come along for the ride ๐Ÿงณ
  • restoreColumn(j, v) โ€” give back a column v that you got from getColumn(). return your library books bestie ๐Ÿ“š
  • restoreMat(A) โ€” restore the matrix A you got from getMat(). same energy, clean up after yourself ๐ŸŽ€
  • scale(alpha) โ€” multiply every entry by the scalar value alpha. glow up for the whole BV โœจ
  • scaleColumn(j, alpha) โ€” Scale a column of a BV. That's it, that's the whole job. One column, one glow-up. ๐Ÿ’…
  • setActiveColumns(l, k) โ€” Set the columns that will be involved in operations. Picking the squad that actually gets to participate. โœจ
  • setDefiniteTolerance(deftol) โ€” Set the tolerance to be used when checking a definite inner product. Yes bestie, we're being precise about definiteness. ๐ŸŽ€
  • setFromOptions() โ€” Set BV options from the options database. Let the command line do the talking, fr fr.
  • setLeadingDimension(ld) โ€” Set the leading dimension. The ld in question. ๐Ÿ‘‘
  • setMatMultMethod(method) โ€” Set the method used for the matMult() operation.
  • setMatrix(B[, indef]) โ€” Set the bilinear form to be used for inner products.
  • setNumConstraints(nc) โ€” Set the number of constraints. Boundaries, but make them explicit. ๐Ÿฆ‹
  • setOptionsPrefix([prefix]) โ€” Set the prefix used for searching for all BV options in the database.
  • setOrthogonalization([otype, refine, eta, block]) โ€” Set the method used for the (block-)orthogonalization of vectors. Keeping the vectors in their own lanes, no overlap, iconic behaviour. ๐ŸŒธ
  • setRandom() โ€” Set the active columns of the BV to random numbers. Chaos, but stored neatly. ๐Ÿ’€
  • setRandomColumn(j) โ€” Set one column of the BV to random numbers. Just the one, lowkey.
  • setRandomCond(condn) โ€” Set the columns of a BV to random numbers.
  • setRandomContext(rnd) โ€” Set the petsc4py.PETSc.Random object associated with the BV. Yes, that one โ€” the petsc4py.PETSc.Random object. ๐Ÿ™ˆ
  • setRandomNormal() โ€” Set the active columns of the BV to normal random numbers. Normal distribution, abnormal vibes. ๐Ÿ“
  • setRandomSign() โ€” Set the entries of a BV to values 1 or -1 with equal probability. Coin flip energy, 50/50 no cap. ๐Ÿช™
  • setSizes(sizes, m) โ€” Set the local and global sizes, and the number of columns. All the numbers at once, we love efficiency. ๐Ÿ’œ
  • setSizesFromVec(w, m) โ€” Set the local and global sizes, and the number of columns. Same deal, but you're stealing the sizes off a vector w. ๐Ÿงš
  • setType(bv_type) โ€” Set the type for the BV object. Choose your fighter. ๐Ÿ”ฅ
  • setVecType(vec_type) โ€” Set the vector type to be used when creating vectors via createVec(). Future vectors inherit the drip. โœจ
  • view([viewer]) โ€” Print the BV data structure. Show me everything bestie, no secrets in this house. ๐Ÿ‘€

๐ŸŒˆ Attributes Summary ๐ŸŒˆ

  • column_size โ€” Basis vectors column size.
  • local_size โ€” Basis vectors local size.
  • size โ€” Basis vectors global size.
  • sizes โ€” Basis vectors local and global sizes, and the number of columns.

๐Ÿซถ Methods Documentation ๐Ÿซถ

appendOptionsPrefix(prefix=None)

Append to the prefix used for searching for all BV options in the database. Not set โ€” append. Like adding a lil accessory to the fit instead of rebuilding the whole outfit. ๐ŸŽ€

Logically collective. Everybody's on the same page here, no rogue processes. ๐Ÿซถ

Parameters

  • prefix (str | None) โ€“ The prefix string to prepend to all BV option requests.

Return type

  • None

See also:

  • setOptionsPrefix
  • getOptionsPrefix
  • BVAppendOptionsPrefix

Source code at slepc4py/SLEPc/BV.pyx:618 โญ

applyMatrix(x, y) โœจ

okay so this one multiplies a vector by the matrix that's associated to the bilinear form. that's the whole vibe.

Neighbor-wise collective. ๐Ÿ‘ฏ (so talk to your neighbors, bestie)

Parameters

Return type

None <https://docs.python.org/3/library/constants.html#None>

Notes

fr fr, if the bilinear form has no associated matrix, this function just copies the vector. no matrix, no multiply, just copy. iconic behaviour honestly ๐Ÿ™ˆ

See also: setMatrix, BVApplyMatrix <https://slepc.upv.es/release/manualpages/BV/BVApplyMatrix.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:863 <slepc4py/SLEPc/BV.pyx#L863>``

copy(result=None) ๐ŸŽ€

copy a basis vector object into another one. literally just duplicate the energy.

Logically collective.

Returns โ€” the copy.

Return type โ€” BV <#slepc4py.SLEPc.BV>

Parameters

Notes

Both objects must be distributed in the same manner; local copies are done. Only active columns (excluding the leading ones) are copied. In the destination BV, columns are overwritten starting from the leading ones. Constraints are not copied โ€” they stay home. ๐Ÿšซ

See also: BVCopy <https://slepc.upv.es/release/manualpages/BV/BVCopy.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:354 <slepc4py/SLEPc/BV.pyx#L354>``

copyColumn(j, i) ๐Ÿฆ‹

copy the values from one of the columns to another one. column glow-up, basically.

Logically collective.

Parameters

Return type โ€” None <https://docs.python.org/3/library/constants.html#None>

See also: copy, copyVec, BVCopyColumn <https://slepc.upv.es/release/manualpages/BV/BVCopyColumn.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:1235 <slepc4py/SLEPc/BV.pyx#L1235>``

copyVec(j, v) ๐Ÿ’–

copy one of the columns of a basis vectors object into a vector. giving extract-the-column energy.

Logically collective.

Parameters

Return type โ€” None <https://docs.python.org/3/library/constants.html#None>

Notes

The BV and v must be distributed in the same manner; local copies are done. like, they have to match, no cap ๐Ÿซถ

See also: copy, copyColumn, BVCopyVec <https://slepc.upv.es/release/manualpages/BV/BVCopyVec.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:1210 <slepc4py/SLEPc/BV.pyx#L1210>``

create(comm=None) ๐ŸŒŸ

create the BV object. the origin story. the main character entrance. ๐Ÿ‘‘

Collective.

Parameters

Return type โ€” Self <https://docs.python.org/3/library/typing.html#typing.Self>

See also: createFromMat, BVCreate <https://slepc.upv.es/release/manualpages/BV/BVCreate.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:225 <slepc4py/SLEPc/BV.pyx#L225>``

createFromMat(A) โœจ

create a basis vectors object from a dense matrix. yes bestie, the matrix is the blueprint.

Collective.

Parameters

Return type โ€” Self <https://docs.python.org/3/library/typing.html#typing.Self>

Notes

The matrix values are copied to the BV data storage, memory is not shared โ€” so it's a whole separate thing, not a link-up. ๐Ÿ”—๐Ÿšซ

The communicator of the BV object will be the same as A <#slepc4py.SLEPc.DS.MatType.A>, and so will be the dimensions.

See also: create, createMat, BVCreateFromMat <https://slepc.upv.es/release/manualpages/BV/BVCreateFromMat.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:247 <slepc4py/SLEPc/BV.pyx#L247>``

createMat() ๐Ÿงš

create a new dense matrix and copy the contents of the BV. reversing the whole situation, love that for us.

Collective.

Returns โ€” the new matrix.

Return type โ€” petsc4py.PETSc.Mat <https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat>

Notes

The matrix contains all columns of the BV, not just the active columns. yeah, all of them. the whole squad. ๐Ÿ‘‘

See also: createFromMat, createVec, getMat, BVCreateMat <https://slepc.upv.es/release/manualpages/BV/BVCreateMat.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:275 <slepc4py/SLEPc/BV.pyx#L275>``

createVec() ๐ŸŒˆ

create a vector with the type and dimensions of the columns of the BV. matching set energy, we love a coordinated fit.

Collective.

Returns โ€” new vector.

Return type โ€” petsc4py.PETSc.Vec <https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Vec.html#petsc4py.PETSc.Vec>

See also: createMat, setVecType, BVCreateVec <https://slepc.upv.es/release/manualpages/BV/BVCreateVec.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:1147 <slepc4py/SLEPc/BV.pyx#L1147>``

destroy() ๐Ÿ’€

destroy the BV object. it's over, it's done, say bye ๐Ÿซถ

Collective.

See also: BVDestroy <https://slepc.upv.es/release/manualpages/BV/BVDestroy.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:211 <slepc4py/SLEPc/BV.pyx#L211>``

Return type โ€” Self <https://docs.python.org/3/library/typing.html#typing.Self>

dot(Y)

Compute the โ€˜block-dotโ€™ product of two basis vectors objects. it's giving dot product but make it a whole group project. ๐Ÿ˜ญ

Collective.

M = Y^* X (m_{ij} = y_i^* x_j) or M = Y^* B X

Parameters

  • Y (BV <#slepc4py.SLEPc.BV>) โ€” Left basis vectors, can be the same as self, giving M = X^* X. self-love, literally. ๐Ÿ’…

Returns โ€” the resulting matrix.

Return type โ€” petsc4py.PETSc.Mat <https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat>

Notes

This is the generalization of Vec.dot() for a collection of vectors, M = Y^* X. The result is a matrix M whose entry m_{ij} is equal to y_i^* x_j (where y_i^* denotes the conjugate transpose of y_i).

X and Y can be the same object.

If a non-standard inner product has been specified with setMatrix(), then the result is M = Y^* B X. In this case, both X and Y must have the same associated matrix โ€” no mixing, bestie, they have to match. ๐Ÿšซ

Only rows (resp. columns) of M starting from l_y (resp. l_x) are computed, where l_y (resp. l_x) is the number of leading columns of Y (resp. X).

See also: dotVec, dotColumn, setActiveColumns, setMatrix, BVDot <https://slepc.upv.es/release/manualpages/BV/BVDot.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:1500 <slepc4py/SLEPc/BV.pyx#L1500>``

dotColumn(j) ๐ŸŒธ

dot products of a column against all the column vectors of a BV. one column vs. the entire friend group. ๐Ÿ‘ฏ

Collective.

Parameters

Returns โ€” the computed values.

Return type โ€” ArrayScalar <#slepc4py.typing.ArrayScalar>

Notes

This operation is equivalent to dotVec() but it uses column j of the BV rather than taking a vector as an argument. The number of active columns of the BV is set to j before the computation, and restored afterwards. If the BV has leading columns specified, then these columns do not participate in the computation. Therefore, the length of the returned array will be j minus the number of leading columns.

See also: dot, dotVec, BVDotColumn <https://slepc.upv.es/release/manualpages/BV/BVDotColumn.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:1584 <slepc4py/SLEPc/BV.pyx#L1584>``

๐Ÿ“Ž :sources: Source code at slepc4py/SLEPc/BV.pyx:1344 <slepc4py/SLEPc/BV.pyx#L1344>

๐ŸŽ€ dotVec(v) ๐ŸŽ€

okay so bestie, this is the one that takes one vector and dots it against every single column vector of the BV. All of them. At once. It's giving Vec.mDot() but with main character energy, because the vectors live inside a BV instead.

Collective.

Parameters

Returns โ€” the computed values.

Return type โ€” ArrayScalar (<#slepc4py.typing.ArrayScalar>)

Notes ๐Ÿซถ

So this is the analogue to Vec.mDot(), but you're using BV to represent a collection of vectors X. The result is m = X^* v, which means m_i is equal to x_j^* v. And ngl, this detail matters: here X is transposed, as opposed to dot(). not me getting emotional over transposes ๐Ÿ˜ญ

If a non-standard inner product has been specified with setMatrix(), then the result is m = X^* B v. periodt ๐Ÿ’…

See also ๐Ÿฆ‹

๐Ÿ“Ž :sources: Source code at slepc4py/SLEPc/BV.pyx:1304 <slepc4py/SLEPc/BV.pyx#L1304>

โœจ duplicate() โœจ

Duplicate the BV object with the same type and dimensions. literally a copy of the shape, not the stuff, iykyk.

Collective.

Returns โ€” the new object.

Return type โ€” BV

Notes ๐ŸŒธ

This function does not copy the entries, bestie โ€” it just allocates the storage for the new BV. You want the content too? Use copy(). no cap.

See also ๐ŸŽ€

๐Ÿ“Ž :sources: Source code at slepc4py/SLEPc/BV.pyx:299 <slepc4py/SLEPc/BV.pyx#L299>

๐Ÿฆ‹ duplicateResize(m) ๐Ÿฆ‹

Create a BV object of the same type and dimensions as an existing one โ€” but you get to pick how many columns you want, bestie. glow-up edition ๐Ÿ’–

Collective.

Parameters

Returns โ€” the new object.

Return type โ€” BV

Notes ๐Ÿ’œ

This is equivalent to a call to duplicate() followed by resize() with possibly different number of columns. The contents of this BV are not copied to the new one. So like, blank slate energy โœจ

See also ๐ŸŒˆ

๐Ÿ“Ž :sources: Source code at slepc4py/SLEPc/BV.pyx:323 <slepc4py/SLEPc/BV.pyx#L323>

๐Ÿ’ซ getActiveColumns() ๐Ÿ’ซ

Get the current active dimensions. two numbers, zero drama.

Not collective. (just you, bestie ๐Ÿ’…)

Returns

Return type โ€” tuple (<https://docs.python.org/3/library/stdtypes.html#tuple>) [int (<https://docs.python.org/3/library/functions.html#int>), int (<https://docs.python.org/3/library/functions.html#int>)]

See also ๐Ÿ“

๐Ÿ“Ž :sources: Source code at slepc4py/SLEPc/BV.pyx:924 <slepc4py/SLEPc/BV.pyx#L924>

๐Ÿงš getArray(readonly=False) ๐Ÿงš

Return the array where the data is stored. the raw goods, fr fr.

Not collective.

Parameters

Returns โ€” the array.

Return type โ€” ArrayScalar (<#slepc4py.typing.ArrayScalar>)

See also ๐Ÿ’–

๐Ÿ“Ž :sources: Source code at slepc4py/SLEPc/BV.pyx:546 <slepc4py/SLEPc/BV.pyx#L546>

๐ŸŒธ getColumn(j) ๐ŸŒธ

Get a vector with the entries of the column of the BV object. one column, served fresh โœจ

Logically collective.

Parameters

Returns โ€” the vector containing the j-th column.

Return type โ€” petsc4py.PETSc.Vec (<https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Vec.html#petsc4py.PETSc.Vec>)

Notes ๐Ÿ‘‘

  • Modifying the returned vector will change the BV entries as well. the way that they share memoryโ€ฆ iconic but also be careful bestie ๐Ÿ˜ญ
  • The returned vector must not be destroyed โ€” restoreColumn() must be called when it is no longer needed. At most, two columns can be fetched, that is, this function can only be called twice before the corresponding restoreColumn() is invoked.
  • A negative index j selects the i-th constraint, where i=-j. Constraints should not be modified. respectfully, hands off ๐Ÿ™ˆ

See also ๐Ÿ’œ

๐Ÿ“Ž :sources: Source code at slepc4py/SLEPc/BV.pyx:1384 <slepc4py/SLEPc/BV.pyx#L1384>

๐ŸŽ€ getDefiniteTolerance() ๐ŸŽ€

Get the tolerance to be used when checking a definite inner product. tiny number, big responsibility.

Not collective.

Returns โ€” the tolerance.

Return type โ€” float (<https://docs.python.org/3/library/functions.html#float>)

See also โญ

๐Ÿ“Ž :sources: Source code at slepc4py/SLEPc/BV.pyx:1285 <slepc4py/SLEPc/BV.pyx#L1285>

๐Ÿ’… getLeadingDimension() ๐Ÿ’…

Get the leading dimension.

Not collective.

Returns โ€” the leading dimension.

Return type โ€” int (<https://docs.python.org/3/library/functions.html#int>)

Notes ๐Ÿฆ‹

  • The returned value may be different in different processes. lowkey chaotic, but that's how it is ๐Ÿ’€
  • The leading dimension must be used when accessing the internal array via getArray(). don't skip it, bestie.

See also ๐ŸŒˆ

๐Ÿ“Ž :sources: Source code at slepc4py/SLEPc/BV.pyx:520 <slepc4py/SLEPc/BV.pyx#L520>

๐Ÿ’– getMat() ๐Ÿ’–

Get a matrix of dense type that shares the memory of the BV object. same memory, two outfits ๐Ÿ’…

Collective.

Returns โ€” the matrix.

Return type โ€” petsc4py.PETSc.Mat (<https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat>)

Notes ๐Ÿซถ

  • The returned matrix contains only the active columns. If the content of the matrix is modified, these changes are also done in the BV object. The user must call restoreMat() when no longer needed.
  • This operation implies a call to getArray(), which may result in data copies. just so you know bestie, it's not free ๐Ÿ‘‘

See also โœจ

๐Ÿ“Ž :sources: Source code at slepc4py/SLEPc/BV.pyx:1447 <slepc4py/SLEPc/BV.pyx#L1447>

๐Ÿ“ getMatMultMethod() ๐Ÿ“

Get the method used for the matMult() operation. which flavour of matMult are we doing today ๐Ÿ™ˆ

Not collective.

Returns โ€” the method for the matMult() operation.

Return type โ€” MatMultType (<#slepc4py.SLEPc.BV.MatMultType>)

See also ๐Ÿงš

๐Ÿ“Ž :sources: Source code at slepc4py/SLEPc/BV.pyx:760 <slepc4py/SLEPc/BV.pyx#L760>

๐Ÿ’œ getMatrix() ๐Ÿ’œ

Get the matrix representation of the inner product. the whole vibe of the inner product, in matrix form โœจ

Not collective.

Returns

Return type โ€” tuple (<https://docs.python.org/3/library/stdtypes.html#tuple>) [Mat (<https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat>), bool (<https://docs.python.org/3/library/functions.html#bool>)] | tuple (<https://docs.python.org/3/library/stdtypes.html#tuple>) [None (<https://docs.python.org/3/library/constants.html#None>), bool (<https://docs.python.org/3/library/functions.html#bool>)]

See also ๐Ÿ’ซ

### getNumConstraints()`` โ€” wait, that's part 13's closer, so just the little receipt line, bestie ๐Ÿ’…

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

โœจ getNumConstraints() โœจ

Okay so this one just tells you how many constraints you've got hanging out on your BV. That's it. That's the whole vibe.

Not collective, so every process can call it and get the tea independently ๐Ÿซ–

Returns the number of constraints.

Return type: int

See also: insertConstraints, setNumConstraints, BVGetNumConstraints โ€” https://slepc.upv.es/release/manualpages/BV/BVGetNumConstraints.html

Source code at slepc4py/SLEPc/BV.pyx:1128

๐Ÿ’– getOptionsPrefix() ๐Ÿ’–

Grab the prefix this BV is using to hunt down all its options in the big options database. You know, the little string that goes in front so it knows which options are its options. iykyk.

Not collective.

Returns the prefix string set for this BV object.

Return type: str

See also: setOptionsPrefix, appendOptionsPrefix, BVGetOptionsPrefix โ€” https://slepc.upv.es/release/manualpages/BV/BVGetOptionsPrefix.html

Source code at slepc4py/SLEPc/BV.pyx:637

๐Ÿฆ‹ getOrthogonalization() ๐Ÿฆ‹

Getting the full orthogonalization setup from your BV object โ€” like a little peek at how this thing is choosing to keep its vectors all clean and non-overlapping. Bestie, it's giving settings reveal ๐Ÿ’…

Not collective.

Returns a tuple with:

  • type (OrthogType) โ€” the type of orthogonalization technique.
  • refine (OrthogRefineType) โ€” the type of refinement.
  • eta (float) โ€” parameter for selective refinement (used when the refinement type is IFNEEDED).
  • block (OrthogBlockType) โ€” the type of block orthogonalization.

Return type: tuple[OrthogType, OrthogRefineType, float, OrthogBlockType]

See also: setOrthogonalization, BVGetOrthogonalization โ€” https://slepc.upv.es/release/manualpages/BV/BVGetOrthogonalization.html

Source code at slepc4py/SLEPc/BV.pyx:675

๐ŸŽ€ getRandomContext() ๐ŸŽ€

Fetches the petsc4py.PETSc.Random object that's been vibing with this BV โ€” yes, the random number generator context. cute, iconic, random โœจ

Collective.

Returns the random number generator context.

Return type: petsc4py.PETSc.Random

See also: setRandomContext, BVGetRandomContext โ€” https://slepc.upv.es/release/manualpages/BV/BVGetRandomContext.html

Source code at slepc4py/SLEPc/BV.pyx:2133

๐ŸŒธ getSizes() ๐ŸŒธ

Asking the BV for its local size, its global size, and how many columns it's carrying. The three-for-one special, no cap ๐Ÿ“

Not collective.

Returns a tuple of:

  • (n, N) (tuple of int) โ€” the local and global sizes.
  • m (int) โ€” the number of columns.

Return type: tuple[LayoutSizeSpec, int]

See also: setSizes, setSizesFromVec, BVGetSizes โ€” https://slepc.upv.es/release/manualpages/BV/BVGetSizes.html

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

๐Ÿ‘‘ getType() ๐Ÿ‘‘

Tells you what kind of BV this object is โ€” the basis vectors type currently being used. Main character energy, but for a type string ๐Ÿ’œ

Not collective.

Returns the basis vectors type currently being used.

Return type: str

See also: setType, BVGetType โ€” https://slepc.upv.es/release/manualpages/BV/BVGetType.html

Source code at slepc4py/SLEPc/BV.pyx:407

๐ŸŒˆ getVecType() ๐ŸŒˆ

What vec type is this BV gonna use when it makes new vectors via createVec()? This is the girl that tells you ๐Ÿ‘€

Not collective.

Returns the vector type.

Return type: str

See also: createVec, setVecType, BVGetVecType โ€” https://slepc.upv.es/release/manualpages/BV/BVGetVecType.html

Source code at slepc4py/SLEPc/BV.pyx:1191

๐Ÿ’… insertConstraints(C) ๐Ÿ’…

Okay bestie, this one drops a whole set of vectors in as constraints. Very serious, very slay.

Collective.

Parameters:

  • C (Vec | list[Vec]) โ€” set of vectors to be inserted as constraints.

Returns the number of linearly independent constraints.

Return type: int

Notes ๐Ÿซถ

The constraints are relevant only during orthogonalization. Constraint vectors span a subspace that gets deflated in every orthogonalization operation, so the whole point is removing those directions from the orthogonal basis computed in the regular BV columns.

Constraints are not stored in regular columns โ€” they live in a special part of the storage. You can reach them with negative indices in getColumn().

โš ๏ธ Heads up: this operation is DESTRUCTIVE, meaning all data contained in the columns of the BV is lost. It's typically invoked just after creating the BV. Once a set of constraints has been set, it is not allowed to call this function again. periodt.

The vectors are copied one by one and then orthogonalized against the previous ones. If any of them is linearly dependent, it gets discarded and not counted in the return value. The behavior is similar to insertVecs().

See also: insertVecs, setNumConstraints, BVInsertConstraints โ€” https://slepc.upv.es/release/manualpages/BV/BVInsertConstraints.html

Source code at slepc4py/SLEPc/BV.pyx:1051

๐ŸŒŸ insertVec(j, w) ๐ŸŒŸ

Slot a single vector into one specific column. Just one. A lil drop, a lil placement ๐ŸŽฏ

Logically collective.

Parameters:

  • j (int) โ€” the column to be overwritten.
  • w (Vec) โ€” the vector to be copied.

Return type: None

See also: insertVecs, BVInsertVec โ€” https://slepc.upv.es/release/manualpages/BV/BVInsertVec.html

Source code at slepc4py/SLEPc/BV.pyx:988

๐Ÿ”ฅ insertVecs(s, W, orth=False) ๐Ÿ”ฅ

The group version โ€” drop a whole set of vectors into the columns you choose. s says where you start, W is the squad, and orth decides whether they get the orthogonalization treatment before they take their seats โœจ

Collective.

Parameters:

  • s (int) โ€” the first column to be overwritten.
  • W (Vec | list[Vec]) โ€” set of vectors to be copied.
  • orth (bool) โ€” flag indicating if the vectors must be orthogonalized.

Returns the number of linearly independent vectors.

Return type: int

Notes

  • insertVecs(W, s, orth=False) โ€” copies the contents of vectors W into the BV columns s:s+n, where n is the length of W. If orth is set, then the vectors are copied one by one and then orthogonalized against the previous one. If any of them is linearly dependent then it is discarded and is not counted in the return value.

See also: insertVec, orthogonalizeColumn, BVInsertVecs <https://slepc.upv.es/release/manualpages/BV/BVInsertVecs.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:1008 <slepc4py/SLEPc/BV.pyx#L1008>

  • matMult(A, Y=None) โ€” compute the matrix-vector product for each column, Y = A V.

Neighbor-wise collective.

Parameters

Returns The result.

Return type BV

Notes

Only active columns (excluding the leading ones) are processed. If Y is None a new BV is created.

It is possible to choose whether the computation is done column by column or as a dense matrix-matrix product with setMatMultMethod().

See also: copy, matMultColumn, matMultTranspose, setMatMultMethod, BVMatMult <https://slepc.upv.es/release/manualpages/BV/BVMatMult.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:1598 <slepc4py/SLEPc/BV.pyx#L1598>

  • matMultColumn(A, j) โ€” mat-vec product for a column, storing the result in the next column.

Neighbor-wise collective.

v_{j+1} = A v_j.

Parameters

Return type None <https://docs.python.org/3/library/constants.html#None>

See also: matMult, BVMatMultColumn <https://slepc.upv.es/release/manualpages/BV/BVMatMultColumn.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:1743 <slepc4py/SLEPc/BV.pyx#L1743>

  • matMultHermitianTranspose(A, Y=None) โ€” pre-multiplication with the conjugate transpose of a matrix.

Neighbor-wise collective.

Y = A^* V.

Parameters

Returns The result.

Return type BV

Notes

Only active columns (excluding the leading ones) are processed. If Y is None a new BV is created.

See also: matMult, matMultHermitianTransposeColumn, BVMatMultHermitianTranspose <https://slepc.upv.es/release/manualpages/BV/BVMatMultHermitianTranspose.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:1695 <slepc4py/SLEPc/BV.pyx#L1695>

  • matMultHermitianTransposeColumn(A, j) โ€” conjugate-transpose matrix-vector product for a specified column.

Neighbor-wise collective.

Store the result in the next column: v_{j+1} = A^* v_j.

Parameters

Return type None <https://docs.python.org/3/library/constants.html#None>

See also: matMultColumn, BVMatMultHermitianTransposeColumn <https://slepc.upv.es/release/manualpages/BV/BVMatMultHermitianTransposeColumn.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:1787 <slepc4py/SLEPc/BV.pyx#L1787>

  • matMultTranspose(A, Y=None) โ€” pre-multiplication with the transpose of a matrix.

Neighbor-wise collective.

Y = A^T V.

Parameters

Returns The result.

Return type BV

Notes

Only active columns (excluding the leading ones) are processed. If Y is None a new BV is created.

See also: matMult, matMultTransposeColumn, BVMatMultTranspose <https://slepc.upv.es/release/manualpages/BV/BVMatMultTranspose.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:1647 <slepc4py/SLEPc/BV.pyx#L1647>

  • matMultTransposeColumn(A, j) โ€” transpose matrix-vector product for a specified column.

Neighbor-wise collective.

Store the result in the next column: v_{j+1} = A^T v_j.

Parameters

Return type None <https://docs.python.org/3/library/constants.html#None>

See also: matMultColumn, BVMatMultTransposeColumn <https://slepc.upv.es/release/manualpages/BV/BVMatMultTransposeColumn.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:1765 <slepc4py/SLEPc/BV.pyx#L1765>

  • matProject(A, Y) โ€” compute the projection of a matrix onto a subspace.

Collective.

M = Y^* A X

Parameters

Returns Projection of the matrix A onto the subspace.

Return type petsc4py.PETSc.Mat <https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat>

Notes

If A is None, then it is assumed that the BV already contains AX.

This operation is similar to dot(), with important differences. The goal is to compute the matrix resulting from the orthogonal projection of A onto the subspace spanned by the columns of the BV, M = X^*AX, or the oblique projection onto the BV along the second one Y, M = Y^*AX.

A difference with respect to dot() is that the standard inner product is always used, regardless of a non-standard inner product being specified with setMatrix().

See also: dot, setActiveColumns, setMatrix, BVMatProject <https://slepc.upv.es/release/manualpages/BV/BVMatProject.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:1549 <slepc4py/SLEPc/BV.pyx#L1549>

  • mult(delta, gamma, X, Q) โ€” compute Y = \gamma Y + \delta X Q.

Logically collective.

Parameters

Return type None <https://docs.python.org/3/library/constants.html#None>

Notes

X must be different from self (Y). The case X=Y can be addressed with multInPlace().

See also: multVec, multColumn, multInPlace, BVMult <https://slepc.upv.es/release/manualpages/BV/BVMult.html>

:sources:Source code at slepc4py/SLEPc/BV.pyx:1809 <slepc4py/SLEPc/BV.pyx#L1809>

  • multColumn(delta, gamma, j, q) โ€” compute y = \gamma y + \delta X q.

Logically collective.

Compute y = \gamma y + \delta X q, where y is the j-th column.

Parameters

(still on multColumn's parameter list, bestie, we're not done yet ๐Ÿ’…)

  • delta (Scalar) โ€” the coefficient that multiplies self (which is X). ๐Ÿซถ
  • gamma (Scalar) โ€” the coefficient that multiplies y.
  • j (int) โ€” the column index. ๐ŸŽ€
  • q (Sequence[Scalar]) โ€” the input coefficients.

Return type None

See also: mult, multVec, multInPlace, BVMultColumn

:sources:Source code at `slepc4py/SLEPc/BV.pyx:1863``

multInPlace(Q, s, e)

Update a whole set of vectors like this: V(:,s:e-1) = V Q(:,s:e-1). Slay โœจ

Logically collective โ€” so like, everybody has to be on the same page, no cap.

Parameters

  • Q (Mat) โ€” a sequential dense matrix.
  • s (int) โ€” first column to be overwritten.
  • e (int) โ€” last column to be overwritten. (Yeah it's the last one, not last-plus-one, read carefully bestie ๐Ÿ˜ญ)

Return type None

See also: mult, multVec, BVMultInPlace

:sources:Source code at `slepc4py/SLEPc/BV.pyx:1840``

multVec(delta, gamma, y, q)

Computes y = \gamma y + \delta X q. Math girlies rise ๐Ÿฆ‹

Logically collective.

Parameters

  • delta (Scalar) โ€” coefficient that multiplies self (that's X).
  • gamma (Scalar) โ€” coefficient that multiplies y.
  • y (Vec) โ€” input/output vector. She goes in, she comes back changed ๐Ÿ’œ
  • q (Sequence[Scalar]) โ€” input coefficients.

Return type None

See also: mult, multColumn, multInPlace, BVMultVec

:sources:Source code at `slepc4py/SLEPc/BV.pyx:1898``

norm(norm_type=None)

Compute the matrix norm of the BV. ๐Ÿ‘‘

Collective.

Parameters

  • norm_type (NormType | None) โ€” the norm type.

Returns The norm.

Return type float

Notes

All the active columns (except the leading ones) get treated as a matrix, okay? And the only norms allowed here are NORM_1, NORM_FROBENIUS, and NORM_INFINITY.

Also important, queen: this operation fails if a non-standard inner product was specified with setMatrix(). Like, it's not a "meh it'll figure itself out" situation, it just taps out ๐Ÿ’€

See also: normColumn, setMatrix, BVNorm

:sources:Source code at `slepc4py/SLEPc/BV.pyx:1967``

normColumn(j, norm_type=None)

Compute the vector norm of one specific column you picked out. ๐ŸŒธ

Collective.

Parameters

  • j (int) โ€” index of the column.
  • norm_type (NormType | None) โ€” the norm type.

Returns The norm.

Return type float

Notes

You get the norm of v_j, and the options are NORM_1, NORM_2, or NORM_INFINITY.

BUT โ€” plot twist ๐Ÿ™ˆ โ€” if a non-standard inner product was specified with setMatrix(), then what you get back is \sqrt{v_j^* B v_j}, where B is the inner product matrix. And in that case the norm_type argument is justโ€ฆ ignored. Fully ghosted, bestie, she does not get a say.

See also: norm, setMatrix, BVNormColumn

:sources:Source code at `slepc4py/SLEPc/BV.pyx:1929``

orthogonalize(R=None, **kargs)

Orthogonalize all the columns (except the leading ones) โ€” it's giving QR decomposition โœจ

Collective.

Parameters

  • R (Mat | None) โ€” a sequential dense matrix.
  • kargs (Any)

Return type None

Notes

What comes out satisfies V_0 = V R (where V_0 is the input V you handed over) and V^* V = I โ€” or V^*BV=I if an inner product matrix B was specified with setMatrix(). So clean ๐Ÿงš

See also: orthogonalizeColumn, setMatrix, setOrthogonalization, BVOrthogonalize

:sources:Source code at `slepc4py/SLEPc/BV.pyx:2263``

orthogonalizeColumn(j)

Orthogonalize a single column vector against all the previous ones. ๐ŸŽ€

Collective.

Parameters

  • j (int) โ€” index of the column that's getting orthogonalized.

Returns

  • norm (float) โ€” the norm of the resulting vector.
  • lindep (bool) โ€” a flag telling you that the refinement did not improve the quality of the orthogonalization. (Yeah, that's the tea ๐Ÿ˜ฌ)

Return type tuple[float, bool]

Notes

So what happens here: it applies an orthogonal projector that projects vector v_j onto the orthogonal complement of the span of columns V[0..j-1], where those V[.] are the vectors of the BV. And heads up โ€” the columns V[0..j-1] are assumed to be mutually orthonormal. It trusts you, don't betray it ๐Ÿซถ

Also, this routine does not normalize the resulting vector. It just leaves her as-is. Periodt.

See also: orthogonalizeVec, setOrthogonalization

:sources:Source code at `slepc4py/SLEPc/BV.pyx:2189``

orthogonalizeVec(v)

Orthogonalize a vector against every active column. ๐Ÿ’œ

Collective.

Parameters

  • v (Vec) โ€” the vector to be orthogonalized, and yes, she gets modified on return.

Returns

  • norm (float) โ€” the norm of the resulting vector.
  • lindep (bool) โ€” flag saying refinement did not improve the quality of the orthogonalization.

Return type tuple[float, bool]

Notes

This one applies an orthogonal projector to project vector v onto the orthogonal complement of the span of the columns of the BV.

And same deal as before: this routine does not normalize the resulting vector. No glow-up, no nothing ๐ŸŒˆ

See also: orthogonalizeColumn, setOrthogonalization

:sources:Source code at `slepc4py/SLEPc/BV.pyx:2153``

orthonormalizeColumn(j, replace=False)

Orthonormalize a column vector with respect to the previous ones. (Yes, orthonormalize โ€” the extra glow โœจ)

Collective.

Lowkey this is just a call to orthogonalizeColumn() and then a call to scaleColumn() with the reciprocal of the norm. Two-step glow-up, honestly. โœจ

Parameters

  • j (int) โ€” index of the column to be orthonormalized ๐Ÿ’…
  • replace (bool) โ€” whether it is allowed to set the vector randomly

Returns

  • norm (float) โ€” the norm of the resulting vector
  • lindep (bool) โ€” flag saying that refinement did not improve the quality of orthogonalization ๐Ÿ˜ญ

Return type

tuple[float, bool]

See also: orthogonalizeColumn, setOrthogonalization

Source code: slepc4py/SLEPc/BV.pyx:2227

resize(m, copy=True) ๐Ÿฆ‹

Change the number of columns. Iconic behaviour, truly.

Collective.

Parameters

  • m (int) โ€” the new number of columns
  • copy (bool) โ€” a flag saying whether the current values should be kept

Return type

None

Notes

Internal storage gets reallocated, no cap. If copy is True, then the contents are copied to the leading part of the new space. Bestie, don't forget that part or you'll be crying. ๐Ÿฅฒ

See also: setSizes, setSizesFromVec, BVResize

Source code: slepc4py/SLEPc/BV.pyx:2002

restoreColumn(j, v) ๐ŸŽ€

Give back a column that you got with getColumn(). Return it, don't keep it, that's the whole vibe.

Logically collective.

Parameters

  • j (int) โ€” the index of the requested column
  • v (Vec) โ€” the vector obtained with getColumn()

Return type

None

Notes

The arguments have to match the corresponding call to getColumn(). Like, match match. Don't be out here swapping things around. ๐Ÿ’€

See also: getColumn, BVRestoreColumn

Source code: slepc4py/SLEPc/BV.pyx:1422

restoreMat(A) ๐ŸŒธ

Give back the matrix you got with getMat().

Logically collective.

Parameters

  • A (Mat) โ€” the matrix obtained with getMat()

Return type

None

Notes

A call to this function must match a previous call of getMat(). The effect is that the contents of the matrix get copied back into the BV internal data structures. It's giving boomerang energy. ๐Ÿชƒ

See also: getMat, BVRestoreMat

Source code: slepc4py/SLEPc/BV.pyx:1476

scale(alpha) โœจ

Multiply the entries by a scalar value. Simple. Elegant. Ate.

Logically collective.

Parameters

  • alpha (Scalar) โ€” scaling factor

Return type

None

Notes

All active columns (except the leading ones) get scaled. Yes, only the active ones, read that again bestie. ๐Ÿ‘‘

See also: scaleColumn, setActiveColumns, BVScale

Source code: slepc4py/SLEPc/BV.pyx:966

scaleColumn(j, alpha) ๐Ÿ’œ

Scale one (1) column of a BV. Single-column treatment, main character energy for real.

Logically collective.

Parameters

  • j (int) โ€” column index to be scaled
  • alpha (Scalar) โ€” scaling factor

Return type

None

See also: scale, BVScaleColumn

Source code: slepc4py/SLEPc/BV.pyx:945

setActiveColumns(l, k) ๐Ÿ”ฅ

Set the columns that will be involved in operations. This is the "who's invited to the party" function.

Logically collective.

Parameters

  • l (int) โ€” the leading number of columns
  • k (int) โ€” the active number of columns

Return type

None

Notes

In operations such as mult() or dot(), only the first k columns are considered. This is useful when the BV is filled from left to right, so the last m-k columns do not have relevant information. Rude but valid.

Also in operations such as mult() or dot(), the first l columns are normally not included in the computation.

In orthogonalization operations, the first l columns are treated differently: they participate in the orthogonalization but the computed coefficients are not stored. iykyk. ๐Ÿคซ

Use CURRENT to leave any of the values unchanged. Use DETERMINE to set l to the minimum value (0) and k to the maximum (m).

See also: getActiveColumns, setSizes, BVSetActiveColumns

Source code: slepc4py/SLEPc/BV.pyx:887

setDefiniteTolerance(deftol) ๐ŸŒˆ

Set the tolerance to be used when checking a definite inner product.

Logically collective.

Parameters

  • deftol (float) โ€” the tolerance

Return type

None

Notes

When using a non-standard inner product, see setMatrix(), the solver needs to compute \sqrt{z^*B z} for various vectors z. If the inner product has not been declared indefinite, the value z^*B z must be positive, but due to rounding error a tiny value may become negative. A tolerance is used to detect this situation. Likewise, in complex arithmetic z^*B z should be real, and we use the same tolerance to check whether a nonzero imaginary part can be considered negligible. It's literally the vibe check for roundoff. ๐Ÿง

See also: setMatrix, getDefiniteTolerance, BVSetDefiniteTolerance

Source code: slepc4py/SLEPc/BV.pyx:1256

setFromOptions() โญ

Set BV options from the options database. Let the command line do the talking, periodt.

Collective.

Notes

To see all options, run your program with the -help option. Fr fr, just do it. ๐Ÿ™ˆ

See also: setOptionsPrefix, BVSetFromOptions

Source code: slepc4py/SLEPc/BV.pyx:656

Return type

None

setLeadingDimension(ld) ๐Ÿ“

Set the leading dimension.

Not collective.

Parameters

  • ld (int) โ€” the leading dimension

Return type

None

Notes

This parameter is relevant for a BV of BV.Type.MAT. Only relevant there, bestie โ€” don't come at it from anywhere else. ๐Ÿ’…

See also: getLeadingDimension, BVSetLeadingDimension

  • setMatMultMethod(method) โ€” sets the method used for the matMult() operation. logically collective btw, so like, everybody's gotta be on the same page ๐Ÿ’ซ

Parameters

  • method (MatMultType) โ€“ the method for the matMult() operation.

Return type None

See also: matMult, getMatMultMethod, BVSetMatMultMethod

:sources: Source code at slepc4py/SLEPc/BV.pyx:498

  • setMatrix(B, indef=False) โ€” sets the bilinear form to be used for inner products. Collective, bestie, everybody pulls up together ๐Ÿซถ

Parameters

  • B (Mat | None) โ€“ the matrix of the inner product.
  • indef (bool) โ€“ whether the matrix is indefinite.

Return type None

Notes

Okay so this one is lowkey important: it lets you specify a non-standard inner product, whose matrix representation is given by B. Then, all inner products required during orthogonalization are computed as (x,y)_B=y^*Bx rather than the standard form (x,y)=y^*x. not me explaining math in the group chat ๐Ÿ˜ญ

Matrix B must be real symmetric (or complex Hermitian). A genuine inner product requires that B is also positive (semi-)definite. However, we also allow for an indefinite B (setting indef=True), in which case the orthogonalization uses an indefinite inner product.

This affects operations dot(), norm(), orthogonalize(), and variants. it's giving very "affects everything" energy โœจ

Omitting B has the same effect as if the identity matrix was passed.

See also: getMatrix, BVSetMatrix

:sources: Source code at slepc4py/SLEPc/BV.pyx:825

  • setNumConstraints(nc) โ€” sets the number of constraints. logically collective ๐Ÿ’…

Parameters

  • nc (int) โ€“ the number of constraints.

Return type None

Notes

This function sets the number of constraints to nc and marks all remaining columns as regular. Normal usage would be to call insertConstraints() instead. ๐Ÿ‘€ so like, bestie, this is the manual way okay

If nc is smaller than the previously set value, then some of the constraints are discarded. In particular, using nc=0 removes all constraints preserving the content of regular columns. careful with this one fr fr ๐Ÿšจ

See also: insertConstraints, getNumConstraints, BVSetNumConstraints

:sources: Source code at slepc4py/SLEPc/BV.pyx:1101

  • setOptionsPrefix(prefix=None) โ€” sets the prefix used for searching for all BV options in the database. logically collective โœจ

Parameters

  • prefix (str | None) โ€“ the prefix string to prepend to all BV 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. no cap, it just does it for you ๐Ÿ’…

See also: appendOptionsPrefix, getOptionsPrefix, BVGetOptionsPrefix

:sources: Source code at slepc4py/SLEPc/BV.pyx:593

  • setOrthogonalization(otype=None, refine=None, eta=None, block=None) โ€” sets the method used for the (block-)orthogonalization of vectors. logically collective ๐Ÿฆ‹

Orthogonalization of vectors (classical or modified Gram-Schmidt with or without refinement), and for the block-orthogonalization (simultaneous orthogonalization of a set of vectors). it's giving math class but make it cute

Parameters

  • otype (OrthogType | None) โ€“ the type of orthogonalization technique.
  • refine (OrthogRefineType | None) โ€“ the type of refinement.
  • eta (float | None) โ€“ parameter for selective refinement.
  • block (OrthogBlockType | None) โ€“ the type of block orthogonalization.

Return type None

Notes

The default settings work well for most problems. slay, less work for u ๐Ÿ’–

The parameter eta should be a real value between 0 and 1 (or DETERMINE). The value of eta is used only when the refinement type is IFNEEDED.

When using several processes, MGS is likely to result in bad scalability. not the scalability bestie ๐Ÿ’€

If the method set for block orthogonalization is GS, then the computation is done column by column with the vector orthogonalization.

See also: getOrthogonalization, BVSetOrthogonalization

:sources: Source code at slepc4py/SLEPc/BV.pyx:704

  • setRandom() โ€” sets the active columns of the BV to random numbers. logically collective ๐ŸŽฒ

Notes

All active columns (except the leading ones) are modified. important detail, don't forget it

See also: setRandomContext, setRandomColumn, setRandomNormal, BVSetRandom

:sources: Source code at slepc4py/SLEPc/BV.pyx:2028

Return type None

  • setRandomColumn(j) โ€” sets one column of the BV to random numbers. logically collective ๐ŸŽ€

Parameters

  • j (int) โ€“ column index to be set.

Return type None

See also: setRandomContext, setRandom, setRandomNormal, BVSetRandomColumn

:sources: Source code at slepc4py/SLEPc/BV.pyx:2076

  • setRandomCond(condn) โ€” sets the columns of a BV to random numbers. logically collective ๐ŸŒธ

The generated matrix has a prescribed condition number. fancy fr fr

Parameters

  • condn (float) โ€“ condition number.

Return type None

See also: setRandomContext, setRandomSign, setRandomNormal, BVSetRandomCond

:sources: Source code at slepc4py/SLEPc/BV.pyx:2094

  • setRandomContext(rnd) โ€” sets the petsc4py.PETSc.Random object associated with the BV. Collective ๐ŸŽฒ

To be used in operations that need random numbers. iykyk

Parameters

  • rnd (Random) โ€“ the random number generator context.

Return type None

:sources: โ€”

See also: getRandomContext, setRandom, setRandomColumn, BVSetRandomContext โ€” https://slepc.upv.es/release/manualpages/BV/BVSetRandomContext.html

Source code at slepc4py/SLEPc/BV.pyx:2114 โ€” https://github.com/slepc/slepc4py/blob/main/slepc4py/SLEPc/BV.pyx#L2114

โœจ setRandomNormal()

Set the active columns of the BV to normal random numbers. ๐ŸŽฒ

Logically collective. Like, everybody has to be on the same page, bestie.

Notes

All active columns (except the leading ones) are modified. (so heads up, your first few columns are safe โ€” the rest are getting a glow-up with fresh random numbers ๐Ÿ’…)

See also: setRandomContext, setRandom, setRandomSign, BVSetRandomNormal โ€” https://slepc.upv.es/release/manualpages/BV/BVSetRandomNormal.html

Source code at slepc4py/SLEPc/BV.pyx:2044 โ€” https://github.com/slepc/slepc4py/blob/main/slepc4py/SLEPc/BV.pyx#L2044

Return type None โ€” https://docs.python.org/3/library/constants.html#None

โœจ setRandomSign()

Set the entries of a BV to values 1 or -1 with equal probability. ๐Ÿช™ It's giving coin flip energy, fr fr.

Logically collective.

Notes

All active columns (except the leading ones) are modified. (yes, again โ€” the leading columns just mind their own business ๐Ÿซถ)

See also: setRandomContext, setRandom, setRandomNormal, BVSetRandomSign โ€” https://slepc.upv.es/release/manualpages/BV/BVSetRandomSign.html

Source code at slepc4py/SLEPc/BV.pyx:2060 โ€” https://github.com/slepc/slepc4py/blob/main/slepc4py/SLEPc/BV.pyx#L2060

Return type None โ€” https://docs.python.org/3/library/constants.html#None

โœจ setSizes(sizes, m)

Set the local and global sizes, and the number of columns. ๐Ÿ“

Collective.

Parameters

Return type None โ€” https://docs.python.org/3/library/constants.html#None

Notes

Either n or N (but not both) can be DETERMINE (https://slepc4py.readthedocs.io/en/latest/reference/index.html#slepc4py.SLEPc.DETERMINE) or None to have it automatically set. It's like letting the code choose your outfit for you โ€” one item, not both, okay? ๐ŸŽ€

See also: setSizesFromVec, getSizes, BVSetSizes โ€” https://slepc.upv.es/release/manualpages/BV/BVSetSizes.html

Source code at slepc4py/SLEPc/BV.pyx:426 โ€” https://github.com/slepc/slepc4py/blob/main/slepc4py/SLEPc/BV.pyx#L426

โœจ setSizesFromVec(w, m)

Set the local and global sizes, and the number of columns. ๐Ÿ“โœจ

Collective.

Local and global sizes are specified indirectly by passing a template vector. Iconic shortcut behavior, ngl โ€” you hand it a vector and it just knows. ๐Ÿ‘‘

Parameters

Return type None โ€” https://docs.python.org/3/library/constants.html#None

See also: setSizes, getSizes, BVSetSizesFromVec โ€” https://slepc.upv.es/release/manualpages/BV/BVSetSizesFromVec.html

Source code at slepc4py/SLEPc/BV.pyx:454 โ€” https://github.com/slepc/slepc4py/blob/main/slepc4py/SLEPc/BV.pyx#L454

โœจ setType(bv_type)

Set the type for the BV object. ๐ŸŒˆ

Logically collective.

Parameters

Return type None โ€” https://docs.python.org/3/library/constants.html#None

See also: getType, BVSetType โ€” https://slepc.upv.es/release/manualpages/BV/BVSetType.html

Source code at slepc4py/SLEPc/BV.pyx:388 โ€” https://github.com/slepc/slepc4py/blob/main/slepc4py/SLEPc/BV.pyx#L388

โœจ setVecType(vec_type)

Set the vector type to be used when creating vectors via createVec(). ๐Ÿงต

Collective.

Parameters

Return type None โ€” https://docs.python.org/3/library/constants.html#None

Notes

This is not needed if the BV object is set up with setSizesFromVec(), but may be required in the case of setSizes() if one wants to work with non-standard vectors. Like, if your vectors are a little extra, you gotta say so. ๐Ÿ’…

See also: createVec, getVecType, setSizes, setSizesFromVec, BVSetVecType โ€” https://slepc.upv.es/release/manualpages/BV/BVSetVecType.html

Source code at slepc4py/SLEPc/BV.pyx:1166 โ€” https://github.com/slepc/slepc4py/blob/main/slepc4py/SLEPc/BV.pyx#L1166

โœจ view(viewer=None)

Print the BV data structure. ๐Ÿ–จ๏ธโœจ

Collective.

Parameters

Return type None โ€” https://docs.python.org/3/library/constants.html#None

See also: BVView โ€” https://slepc.upv.es/release/manualpages/BV/BVView.html

Source code at slepc4py/SLEPc/BV.pyx:192 โ€” https://github.com/slepc/slepc4py/blob/main/slepc4py/SLEPc/BV.pyx#L192

๐ŸŽ€ Attributes Documentation ๐ŸŽ€

column_size

Basis vectors column size. ๐Ÿ“

Source code at slepc4py/SLEPc/BV.pyx:2305 โ€” https://github.com/slepc/slepc4py/blob/main/slepc4py/SLEPc/BV.pyx#L2305

local_size

Basis vectors local size. ๐Ÿ“

Source code at slepc4py/SLEPc/BV.pyx:2300 โ€” https://github.com/slepc/slepc4py/blob/main/slepc4py/SLEPc/BV.pyx#L2300

size

Basis vectors global size. ๐ŸŒ

Source code at slepc4py/SLEPc/BV.pyx:2295 โ€” https://github.com/slepc/slepc4py/blob/main/slepc4py/SLEPc/BV.pyx#L2295

sizes

Basis vectors local and global sizes, and the number of columns. ๐Ÿ“๐ŸŒ

Source code at slepc4py/SLEPc/BV.pyx:2290 โ€” https://github.com/slepc/slepc4py/blob/main/slepc4py/SLEPc/BV.pyx#L2290

__init__()

Bestie, the initializer. Nothing extra to say here, it just be doing init things. ๐Ÿ™ˆ

classmethod __new__(*args, **kwargs)

And the classmethod that makes the whole thing exist in the first place. Manifesting a new object, fr fr. โœจ

๐Ÿฆ‹ slepc4py.SLEPc.DS

class slepc4py.SLEPc.DS

Bases: Object โ€” https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Object.html#petsc4py.PETSc.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. (lowkey just a cute little structured wrapper around LAPACK โ€” don't overthink it ๐Ÿ’–)

Enumerations

๐Ÿ’œ slepc4py.SLEPc.DS.MatType

class slepc4py.SLEPc.DS.MatType

Bases: object โ€” https://docs.python.org/3/library/functions.html#object

To refer to one of the matrices stored internally in DS. ๐Ÿ—‚๏ธ

  • A: first matrix of eigenproblem/singular value problem.
  • B: second matrix of a generalized eigenproblem.
  • C: third matrix of a quadratic eigenproblem.
  • T: tridiagonal matrix.
  • D: diagonal matrix.
  • Q: orthogonal matrix of (right) Schur vectors.
  • Z: orthogonal matrix of left Schur vectors.
  • X: right eigenvectors.
  • Y: left eigenvectors.
  • U: left singular vectors.
  • V: right singular vectors.
  • W: workspace matrix.

See also: DSMatType โ€” https://slepc.upv.es/release/manualpages/DS/DSMatType.html

๐ŸŒธ Attributes Summary ๐ŸŒธ

okay so this is the little family of constants, and they're all just ints, bestie. Every single one of them:

and yes it literally hops from D straight to Q โ€” that's just the list, we don't ask questions, we just scroll ๐Ÿ’€

๐Ÿ’– Attributes Documentation ๐Ÿ’–

the receipts, one by one, with the exact values they hold:

and then, because of course there's more:

  • __init__()
  • classmethod __new__(*args, **kwargs)

๐Ÿฆ‹ slepc4py.SLEPc.DS.ParallelType

class slepc4py.SLEPc.DS.ParallelType

Bases: object (https://docs.python.org/3/library/functions.html#object)

okay so this one tells you which parallel mode the direct solver is gonna use โ€” it's giving traffic-controller energy, and honestly? iconic of it.

  • REDUNDANT: Every process performs the computation redundantly.
  • SYNCHRONIZED: The first process sends the result to the rest.
  • DISTRIBUTED: Used in some cases to distribute the computation among processes.

See also:

DSParallelType (https://slepc.upv.es/release/manualpages/DS/DSParallelType.html)

no cap, go read that one too, it's the whole extended universe ๐Ÿซถ

๐ŸŒˆ Attributes Summary ๐ŸŒˆ

three constants, all ints, all ready to party:

โœจ Attributes Documentation โœจ

and the usual lil duo hanging out at the bottom:

  • __init__()
  • classmethod __new__(*args, **kwargs)

๐ŸŽ€ slepc4py.SLEPc.DS.StateType

class slepc4py.SLEPc.DS.StateType

Bases: object (https://docs.python.org/3/library/functions.html#object)

and that's where this part ends, bestie โ€” we're literally mid-thought, so buckle up for the next chunk ๐Ÿ’…

DS state types ๐Ÿฆ‹

okay so bestie, your DS can be in one of these states, and they're literally the stages of its transformation, no cap:

  • RAW โ€” Not processed yet. It's giving fresh-out-the-box, untouched, no filter needed. โœจ
  • INTERMEDIATE โ€” Reduced to Hessenberg or tridiagonal form (or equivalent). Like it's halfway through a glow-up, still cooking. ๐Ÿ’…
  • CONDENSED โ€” Reduced to Schur or diagonal form (or equivalent). Fully transformed and ready to serve looks, periodt. ๐Ÿ”ฅ
  • TRUNCATED โ€” Condensed form truncated to a smaller size. When you Marie Kondo that matrix, because less is more, bestie. ๐ŸŽ€

See also: DSStateType <https://slepc.upv.es/release/manualpages/DS/DSStateType.html>

Attributes Summary โœจ

Attributes Documentation ๐Ÿ’…

  • __init__()
  • classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.DS.Type ๐ŸŒˆ

DS type.

  • HEP โ€” Dense Hermitian Eigenvalue Problem.
  • NHEP โ€” Dense Non-Hermitian Eigenvalue Problem.
  • GHEP โ€” Dense Generalized Hermitian Eigenvalue Problem.
  • GHIEP โ€” Dense Generalized Hermitian Indefinite Eigenvalue Problem.
  • GNHEP โ€” Dense Generalized Non-Hermitian Eigenvalue Problem.
  • NHEPTS โ€” Dense Non-Hermitian Eigenvalue Problem (special variant intended for two-sided Krylov solvers).
  • SVD โ€” Dense Singular Value Decomposition.
  • HSVD โ€” Dense Hyperbolic Singular Value Decomposition.
  • GSVD โ€” Dense Generalized Singular Value Decomposition.
  • PEP โ€” Dense Polynomial Eigenvalue Problem.
  • NEP โ€” Dense Nonlinear Eigenvalue Problem.

See also: DSType <https://slepc.upv.es/release/manualpages/DS/DSType.html>

Attributes Summary โœจ

Attributes Documentation ๐Ÿ’…

๐ŸŒธ Methods ๐ŸŒธ

  • __init__() โ€” the classic init hook, doing its little setup thing. โœจ
  • classmethod __new__(*args, **kwargs) โ€” a classmethod version of __new__, taking *args and **kwargs, because sometimes you gotta make the object before you init the object. Main character energy, fr fr ๐Ÿ’–
  • allocate(ld) โ€” babes, this is the memory glow-up โœจ it allocates memory for internal storage or for the matrices inside DS.
  • appendOptionsPrefix([prefix]) โ€” appends to the prefix that DS uses when it's out here searching for all its options in the database ๐Ÿ’…
  • cond() โ€” computes the inf-norm condition number of the first matrix. number-crunching queen ๐Ÿ‘‘
  • create([comm]) โ€” creates the DS object. new object, who dis ๐Ÿฆ‹
  • destroy() โ€” destroys the DS object. say bye bestie ๐Ÿ˜ญ๐Ÿ’”
  • duplicate() โ€” duplicates the DS object with the same type and the same dimensions. it's giving twin energy fr fr ๐Ÿ‘ฏ
  • getArray(matname) โ€” returns the array where the data is stored. here's where it actually lives ๐Ÿ 
  • getBlockSize() โ€” gets the block size.
  • getCompact() โ€” gets the compact storage flag.
  • getDimensions() โ€” gets the current dimensions. how big are we today honey ๐Ÿ“
  • getExtraRow() โ€” gets the extra row flag.
  • getGSVDDimensions() โ€” gets the number of columns and rows of a DS of type GSVD <#slepc4py.SLEPc.DS.Type.GSVD>. both numbers, we're thorough ๐Ÿ’–
  • getHSVDDimensions() โ€” gets the number of columns of a DS of type HSVD <#slepc4py.SLEPc.DS.Type.HSVD>. just the columns this time ๐ŸŽ€
  • getLeadingDimension() โ€” gets the leading dimension of the allocated matrices.
  • getMat(matname) โ€” gets the requested matrix as a sequential dense Mat object. dense and thriving ๐ŸŒธ
  • getMethod() โ€” gets the method currently used in the DS. what's your technique rn ๐Ÿงš
  • getOptionsPrefix() โ€” gets the prefix used for searching for all DS options in the database.
  • getPEPCoefficients() โ€” gets the polynomial basis coefficients of a DS of type PEP <#slepc4py.SLEPc.PEP>. coefficients, served fresh ๐Ÿ“
  • getPEPDegree() โ€” gets the polynomial degree of a DS of type PEP <#slepc4py.SLEPc.PEP>.
  • getParallel() โ€” gets the mode of operation in parallel runs. parallel baddie behavior ๐Ÿ”ฅ
  • getRefined() โ€” gets the refined vectors flag.
  • getSVDDimensions() โ€” gets the number of columns of a DS of type SVD <#slepc4py.SLEPc.SVD>.
  • getState() โ€” gets the current state. vibe check, but make it official โญ
  • getType() โ€” gets the DS type of this object.
  • reset() โ€” resets the DS object. clean slate era ๐ŸŒˆ
  • restoreMat(matname, mat) โ€” restores the previously seized matrix. hand it back, no take-backsies ๐Ÿ™ˆ
  • setBlockSize(bs) โ€” sets the block size.
  • setCompact(comp) โ€” sets the compact flag for storage of matrices. storage but make it compact ๐Ÿ’œ
  • setDimensions([n, l, k]) โ€” sets the matrix sizes in the DS object.
  • setExtraRow(ext) โ€” sets a flag to indicate that the matrix has one extra row. one (1) extra row, iconic behavior ๐Ÿ‘‘
  • setFromOptions() โ€” Set DS options from the options database. ๐Ÿ’…
  • setGSVDDimensions(m, p) โ€” Set the number of columns and rows of a DS of type GSVD (slepc4py.SLEPc.DS.Type.GSVD).
  • setHSVDDimensions(m) โ€” Set the number of columns of a DS of type HSVD (slepc4py.SLEPc.DS.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 (slepc4py.SLEPc.PEP).
  • setPEPDegree(deg) โ€” Set the polynomial degree of a DS of type PEP (slepc4py.SLEPc.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 (slepc4py.SLEPc.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 โœจ

okay bestie, this is the part where we actually get into the receipts on each method, one by one ๐Ÿ’–

allocate(ld)

Allocate memory for internal storage or matrices in DS. Logically collective, so everybody in the group chat (the whole communicator, bestie) is in on this one. ๐Ÿ™ˆ

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(). ๐Ÿ’€ so like, if you're gonna change ld, just know everything's getting nuked and rebuilt, no cap.

See also:

getLeadingDimension, setDimensions, setExtraRow, reset, DSAllocate

:sources:Source code at slepc4py/SLEPc/DS.pyx:338 <slepc4py/SLEPc/DS.pyx#L338>

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 โ€” https://slepc.upv.es/release/manualpages/DS/DSSetOptionsPrefix.html

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

cond()

Bestie. It computes the inf-norm condition number of the first matrix. That's the whole job. Slay. โœจ

Logically collective. (everyone in the communicator has to call it, no stragglers ๐Ÿ’…)

Returns: the condition number.

Return type: float โ€” https://docs.python.org/3/library/functions.html#float

See also: DSCond โ€” https://slepc.upv.es/release/manualpages/DS/DSCond.html

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

create(comm=None)

Creates the DS object. Your baby is born ๐Ÿซถ

Collective.

Parameters:

Return type: Self โ€” https://docs.python.org/3/library/typing.html#typing.Self

See also: duplicate, DSCreate โ€” https://slepc.upv.es/release/manualpages/DS/DSCreate.html

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

destroy()

Destroys the DS object. It's giving closure, it's giving moving on ๐Ÿฆ‹

Collective.

See also: DSDestroy โ€” https://slepc.upv.es/release/manualpages/DS/DSDestroy.html

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

Return type: Self โ€” https://docs.python.org/3/library/typing.html#typing.Self

duplicate()

Duplicates the DS object with the same type and dimensions. Twin energy fr fr ๐Ÿ‘‘

Collective.

Returns: the new object.

Return type: DS

Notes

๐Ÿ˜ญ Heads up: this method does not copy the matrices, and the new object doesn't even have the internal arrays allocated. Call allocate() if you actually want to use the new DS. No cap.

See also: create, allocate, DSDuplicate โ€” https://slepc.upv.es/release/manualpages/DS/DSDuplicate.html

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

getArray(matname)

Returns the array where the data is stored. Just hands you the array, no drama ๐ŸŒธ

Not collective.

Parameters:

  • matname (MatType โ€” see the MatType docs: #slepc4py.SLEPc.DS.MatType) โ€” the selected matrix.

Returns: the array.

Return type: ArrayScalar โ€” #slepc4py.typing.ArrayScalar

See also: DSGetArray โ€” https://slepc.upv.es/release/manualpages/DS/DSGetArray.html

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

getBlockSize()

Gets the block size. Simple. Iconic. ๐Ÿ’…

Not collective.

Returns: the block size.

Return type: int โ€” https://docs.python.org/3/library/functions.html#int

See also: setBlockSize, DSGetBlockSize โ€” https://slepc.upv.es/release/manualpages/DS/DSGetBlockSize.html

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

getCompact()

Gets the compact storage flag. Read the vibe of that flag ๐Ÿ’–

Not collective.

Returns: the flag.

Return type: bool โ€” https://docs.python.org/3/library/functions.html#bool

See also: setCompact, DSGetCompact โ€” https://slepc.upv.es/release/manualpages/DS/DSGetCompact.html

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

getDimensions()

Gets the current dimensions. The whole squad of numbers, all at once ๐ŸŽ€

Not collective.

Returns:

Return type: tuple of int, int, int, int โ€” https://docs.python.org/3/library/stdtypes.html#tuple , https://docs.python.org/3/library/functions.html#int

Notes

๐Ÿซถ The t value only makes sense if truncate() has been called. Otherwise it's literally just equal to n. That's it, that's the note.

See also: setDimensions, truncate, getLeadingDimension, DSGetDimensions โ€” https://slepc.upv.es/release/manualpages/DS/DSGetDimensions.html

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

getExtraRow()

Gets the extra row flag. Extra. Like me. ๐Ÿ’€

Not collective.

Returns: the flag.

Return type: bool โ€” https://docs.python.org/3/library/functions.html#bool

See also: setExtraRow, DSGetExtraRow โ€” https://slepc.upv.es/release/manualpages/DS/DSGetExtraRow.html

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

getGSVDDimensions()

Gets the number of columns and rows of a DS of type GSVD (that's slepc4py.SLEPc.DS.Type.GSVD bestie, type it exactly ๐Ÿฆ‹).

Not collective.

Returns:

Return type: tuple of int, int โ€” https://docs.python.org/3/library/stdtypes.html#tuple , https://docs.python.org/3/library/functions.html#int

See also: setGSVDDimensions, DSGSVDGetDimensions โ€” https://slepc.upv.es/release/manualpages/DS/DSGSVDGetDimensions.html

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

getHSVDDimensions()

Gets the number of columns of a DS of type HSVD (yup, slepc4py.SLEPc.DS.Type.HSVD, exactly that โœจ).

Not collective.

Returns: the number of columns.

Return type: int โ€” https://docs.python.org/3/library/functions.html#int

See also: setHSVDDimensions, DSHSVDGetDimensions โ€” https://slepc.upv.es/release/manualpages/DS/DSHSVDGetDimensions.html

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

getLeadingDimension()

Gets the leading dimension of the allocated matrices. It's the ceiling, the limit, the main character of dimensions ๐ŸŒˆ

Not collective.

Returns: the leading dimension (the maximum allowed dimension for the matrices).

Return type: int โ€” https://docs.python.org/3/library/functions.html#int

See also: allocate, setDimensions, DSGetLeadingDimension โ€” https://slepc.upv.es/release/manualpages/DS/DSGetLeadingDimension.html

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

getMat(matname)

Gets the requested matrix as a sequential dense Mat object. Actual matrix, in your hands, periodt ๐Ÿ”ฅ

Not collective.

Parameters:

  • matname (MatType โ€” see the MatType docs: #slepc4py.SLEPc.DS.MatType) โ€” the requested matrix.

Returns: the matrix.

Return type: petsc4py.PETSc.Mat โ€” https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat

Notes

๐ŸŒธ Okay so listen: the matrix it hands back has sizes equal to the current DS dimensions (peep setDimensions()), and it holds the values you'd get from getArray(). And if the DS was truncated, then the number of rows equals the dimension prior to truncation โ€” see truncate(). ๐Ÿ’€ And when you're done with it, you must call restoreMat(). Do not forget. Do not ghost it.

See also: restoreMat, setDimensions, getArray, truncate, DSGetMat โ€” https://slepc.upv.es/release/manualpages/DS/DSGetMat.html

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

getMethod()

Gets the method currently used in the DS. Which method? The one it's using, bestie ๐Ÿ’œ

Not collective.

Returns โ€” the identifier of the method, as an int โœจ

See also: setMethod, DSGetMethod โ€” https://slepc.upv.es/release/manualpages/DS/DSGetMethod.html

:sources:Source code at slepc4py/SLEPc/DS.pyx:592 <slepc4py/SLEPc/DS.pyx#L592>

getOptionsPrefix()

okay so this one grabs the prefix that gets used when the code goes searching for all the DS options in the options database ๐Ÿ’…

Not collective, bestie โ€” every process is on its own here.

Returns โ€” the prefix string that's been set for this DS object. Return type is str.

See also: appendOptionsPrefix, setOptionsPrefix, DSSetOptionsPrefix โ€” https://slepc.upv.es/release/manualpages/DS/DSSetOptionsPrefix.html

:sources:Source code at slepc4py/SLEPc/DS.pyx:275 <slepc4py/SLEPc/DS.pyx#L275>

getPEPCoefficients()

Get the polynomial basis coefficients of a DS of type PEP โ€” yes, that exact vibe ๐ŸŒธ

Not collective.

Returns โ€” the coefficients. Return type is ArrayReal.

See also: setPEPCoefficients, DSPEPGetCoefficients โ€” https://slepc.upv.es/release/manualpages/DS/DSPEPGetCoefficients.html

:sources:Source code at slepc4py/SLEPc/DS.pyx:1176 <slepc4py/SLEPc/DS.pyx#L1176>

getPEPDegree()

Grabs the polynomial degree of a DS of type PEP ๐ŸŽ€

Not collective.

Returns โ€” the polynomial degree, as an int.

See also: setPEPDegree, DSPEPGetDegree โ€” https://slepc.upv.es/release/manualpages/DS/DSPEPGetDegree.html

:sources:Source code at slepc4py/SLEPc/DS.pyx:1122 <slepc4py/SLEPc/DS.pyx#L1122>

getParallel()

Asks the DS how it wants to behave when stuff runs in parallel ๐Ÿ‘‘

Not collective.

Returns โ€” the parallel mode. Return type is ParallelType.

See also: setParallel, DSGetParallel โ€” https://slepc.upv.es/release/manualpages/DS/DSGetParallel.html

:sources:Source code at slepc4py/SLEPc/DS.pyx:450 <slepc4py/SLEPc/DS.pyx#L450>

getRefined()

Gets the refined vectors flag, periodt โœจ

Not collective.

Returns โ€” the flag, as a bool.

See also: setRefined, DSGetRefined โ€” https://slepc.upv.es/release/manualpages/DS/DSGetRefined.html

:sources:Source code at slepc4py/SLEPc/DS.pyx:734 <slepc4py/SLEPc/DS.pyx#L734>

getSVDDimensions()

Get the number of columns of a DS of type SVD ๐Ÿฆ‹

Not collective.

Returns โ€” the number of columns, as an int.

See also: setSVDDimensions, DSSVDGetDimensions โ€” https://slepc.upv.es/release/manualpages/DS/DSSVDGetDimensions.html

:sources:Source code at slepc4py/SLEPc/DS.pyx:995 <slepc4py/SLEPc/DS.pyx#L995>

getState()

Literally just: what's the current state? state check, but make it linear algebra ๐Ÿ’…

Not collective.

Returns โ€” the current state. Return type is StateType.

See also: setState, DSGetState โ€” https://slepc.upv.es/release/manualpages/DS/DSGetState.html

:sources:Source code at slepc4py/SLEPc/DS.pyx:413 <slepc4py/SLEPc/DS.pyx#L413>

getType()

Tells you the DS type of this object ๐Ÿ’–

Not collective.

Returns โ€” the direct solver type currently being used. Return type is str.

See also: setType, DSGetType โ€” https://slepc.upv.es/release/manualpages/DS/DSGetType.html

:sources:Source code at slepc4py/SLEPc/DS.pyx:212 <slepc4py/SLEPc/DS.pyx#L212>

reset()

Resets the DS object โ€” fresh start energy, we love a clean slate ๐Ÿงš

This one is Collective, so everybody has to show up for it, no skipping.

See also: allocate, DSReset โ€” https://slepc.upv.es/release/manualpages/DS/DSReset.html

:sources:Source code at slepc4py/SLEPc/DS.pyx:160 <slepc4py/SLEPc/DS.pyx#L160>

Return type โ€” None

restoreMat(matname, mat)

Hands back a matrix you previously seized โ€” give it back, it's not yours anymore ๐Ÿ™ˆ

Not collective.

Parameters

Return type โ€” None

See also: getMat, DSRestoreMat โ€” https://slepc.upv.es/release/manualpages/DS/DSRestoreMat.html

:sources:Source code at slepc4py/SLEPc/DS.pyx:824 <slepc4py/SLEPc/DS.pyx#L824>

setBlockSize(bs)

Sets the block size ๐Ÿ’…

Logically collective โ€” so like, keep your story straight across ranks.

Parameters

  • bs (int) โ€” the block size.

Return type โ€” None

See also: getBlockSize, DSSetBlockSize โ€” https://slepc.upv.es/release/manualpages/DS/DSSetBlockSize.html

:sources:Source code at slepc4py/SLEPc/DS.pyx:537 <slepc4py/SLEPc/DS.pyx#L537>

setCompact(comp)

Sets the compact flag for how matrices get stored ๐ŸŽ€

Logically collective.

Parameters

  • comp (bool) โ€” True means compact storage.

Return type โ€” None

Notes

Compact storage gets used in some DS types such as DS.Type.HEP when the matrix is tridiagonal. This flag is how you tell it whether the user is handing over the matrix entries in the compact form (the tridiagonal DS.MatType.T) or the non-compact one (DS.MatType.A) โœจ

The default is False. lowkey important, don't forget it.

See also: getCompact, DSSetCompact โ€” https://slepc.upv.es/release/manualpages/DS/DSSetCompact.html

:sources:Source code at slepc4py/SLEPc/DS.pyx:611 <slepc4py/SLEPc/DS.pyx#L611>

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

Sets the matrix sizes inside 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. Like, it sets the numbers, it does not go do memory magic for you. ๐Ÿ’€

Some DS types have extra dimensions of their own, e.g., the number of columns in DS.Type.SVD. For those, you should call a specific interface function instead.

See also: getDimensions, allocate, DSSetDimensions โ€” https://slepc.upv.es/release/manualpages/DS/DSSetDimensions.html

:sources:Source code at slepc4py/SLEPc/DS.pyx:469 <slepc4py/SLEPc/DS.pyx#L469>

setExtraRow(ext)

Sets a flag saying "hey, this matrix has one extra row" ๐Ÿ‘‘

Logically collective.

Parameters

  • ext (bool) โ€” True if the matrix has an extra row.

Return type โ€” None

Notes

  • (n+1) โ€” in Krylov methods it's lowkey essential that the matrix doing the direct-solver thing has one extra row, like it's got (n+1) rows and (n+1) columns, periodt. Flip this flag on and every transformation you apply on the right of the matrix ALSO hits that extra row too ๐Ÿ’…. When that's happening, (n+1) has to be less than or equal to the leading dimension, no exceptions bestie.

The default is False.

See also: getExtraRow, solve, allocate, DSSetExtraRow (https://slepc.upv.es/release/manualpages/DS/DSSetExtraRow.html)

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

โœจ setFromOptions() โœจ

Set DS options from the options database. It's giving "let the user decide at runtime" energy ๐ŸŽ€.

Collective, btw โ€” everyone in the group chat has to show up.

Notes

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

See also: setOptionsPrefix, DSSetFromOptions (https://slepc.upv.es/release/manualpages/DS/DSSetFromOptions.html)

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

Return type None (https://docs.python.org/3/library/constants.html#None)

๐Ÿฆ‹ setGSVDDimensions(m, p) ๐Ÿฆ‹

Set the number of columns and rows of a DS of type GSVD (#slepc4py.SLEPc.DS.Type.GSVD).

Logically collective.

Parameters

  • m (int) โ€” The number of columns.
  • p (int) โ€” The number of rows for the second matrix.

Return type None (https://docs.python.org/3/library/constants.html#None)

Notes

This call is complementary to setDimensions(), so you can provide the dimensions that are specific to this DS.Type (#slepc4py.SLEPc.DS.Type). Like, setDimensions does the main character work and this one handles the special-case glow-up โœจ.

See also: setDimensions, getGSVDDimensions, DSGSVDSetDimensions (https://slepc.upv.es/release/manualpages/DS/DSGSVDSetDimensions.html)

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

๐ŸŒธ setHSVDDimensions(m) ๐ŸŒธ

Set the number of columns of a DS of type HSVD (#slepc4py.SLEPc.DS.Type.HSVD).

Logically collective.

Parameters

  • m (int) โ€” The number of columns.

Return type None (https://docs.python.org/3/library/constants.html#None)

Notes

This call is complementary to setDimensions(), to provide a dimension that is specific to this DS.Type (#slepc4py.SLEPc.DS.Type). iykyk ๐Ÿ’œ

See also: setDimensions, getHSVDDimensions, DSHSVDSetDimensions (https://slepc.upv.es/release/manualpages/DS/DSHSVDSetDimensions.html)

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

๐Ÿ’– setIdentity(matname) ๐Ÿ’–

Set the identity on the active part of a matrix. Just the active part bestie, not the whole thing ๐Ÿ˜Œ.

Logically collective.

Parameters

  • matname (MatType (#slepc4py.SLEPc.DS.MatType)) โ€” The matrix to be changed.

Return type None (https://docs.python.org/3/library/constants.html#None)

See also: DSSetIdentity (https://slepc.upv.es/release/manualpages/DS/DSSetIdentity.html)

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

๐ŸŽ€ setMethod(meth) ๐ŸŽ€

Set the method to be used to solve the problem. Pick your fighter, bestie โš”๏ธ.

Logically collective.

Parameters

  • meth (int) โ€” An index identifying the method.

Return type None (https://docs.python.org/3/library/constants.html#None)

See also: getMethod, DSSetMethod (https://slepc.upv.es/release/manualpages/DS/DSSetMethod.html)

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

โญ setOptionsPrefix(prefix=None) โญ

Set the prefix used for searching for all DS options in the database. Lowkey the nametag for your options ๐Ÿท๏ธ.

Logically collective.

Parameters

  • prefix (str | None) โ€” The prefix string to prepend to all DS option requests.

Return type None (https://docs.python.org/3/library/constants.html#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. So bestie, do not add your own, it's handled, trust ๐Ÿ™.

See also: appendOptionsPrefix, getOptionsPrefix, DSSetOptionsPrefix (https://slepc.upv.es/release/manualpages/DS/DSSetOptionsPrefix.html)

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

๐Ÿงš setPEPCoefficients(pbc) ๐Ÿงš

Set the polynomial basis coefficients of a DS of type PEP (#slepc4py.SLEPc.PEP).

Logically collective.

Parameters

  • pbc (Sequence[float]) โ€” Coefficients.

Return type None (https://docs.python.org/3/library/constants.html#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. So yeah, one size does NOT fit all here ๐Ÿ˜ญ.

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. Monomial girlies stay winning ๐Ÿ’….

See also: getPEPCoefficients, DSPEPSetCoefficients (https://slepc.upv.es/release/manualpages/DS/DSPEPSetCoefficients.html)

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

๐ŸŒˆ setPEPDegree(deg) ๐ŸŒˆ

Set the polynomial degree of a DS of type PEP (#slepc4py.SLEPc.PEP).

Logically collective.

Parameters

  • deg (int) โ€” The polynomial degree.

Return type None (https://docs.python.org/3/library/constants.html#None)

See also: getPEPDegree, DSPEPSetDegree (https://slepc.upv.es/release/manualpages/DS/DSPEPSetDegree.html)

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

๐Ÿ”ฅ setParallel(pmode) ๐Ÿ”ฅ

Set the mode of operation in parallel runs. Teamwork makes the dream work fr fr ๐Ÿค.

Logically collective.

Parameters

  • pmode (ParallelType (#slepc4py.SLEPc.DS.ParallelType)) โ€” The parallel mode.

Return type None (https://docs.python.org/3/library/constants.html#None)

See also: getParallel, DSSetParallel (https://slepc.upv.es/release/manualpages/DS/DSSetParallel.html)

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 (https://docs.python.org/3/library/constants.html#None)

Notes

Normally the vectors returned in DS.MatType.X (#slepc4py.SLEPc.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. She's refined, she's elegant, she's precise โœจ.

The default is False.

See also: getRefined, vectors, setExtraRow, DSSetRefined (https://slepc.upv.es/release/manualpages/DS/DSSetRefined.html)

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

๐Ÿ’œ setSVDDimensions(m) ๐Ÿ’œ

Set the number of columns of a DS of type SVD (#slepc4py.SLEPc.SVD).

Logically collective.

Parameters

  • m (int) โ€” The number of columns.

Return type: None โ€” yes bestie, literally nothing comes back, just good old None (https://docs.python.org/3/library/constants.html#None) ๐Ÿซถ

Notes โœจ

This call is besties with setDimensions() โ€” it's the complement, there to hand you a dimension that's specific to this DS.Type (anchor: #slepc4py.SLEPc.DS.Type). iykyk ๐Ÿ’…

See also: setDimensions, getSVDDimensions, DSSVDSetDimensions (https://slepc.upv.es/release/manualpages/DS/DSSVDSetDimensions.html)

Source code at slepc4py/SLEPc/DS.pyx:972 (slepc4py/SLEPc/DS.pyx#L972)

setState(state)

Set the state of the DS object. Like, tell it what era it's in ๐Ÿ’…

Logically collective โ€” everybody has to show up for this one, no lurkers.

Parameters

  • state (StateType, anchor #slepc4py.SLEPc.DS.StateType) โ€“ The new state. Slay.

Return type: None (https://docs.python.org/3/library/constants.html#None)

Notes ๐ŸŒธ

The state is basically the vibe check of your dense system:

  • an initial state (raw) โ€” no โœจtreatmentโœจ yet
  • an intermediate state (such as tridiagonal, Hessenberg or Hessenberg-triangular) โ€” mid-transformation era
  • a condensed state (such as diagonal, Schur or generalized Schur) โ€” fully done up
  • or a truncated state

The state gets changed automatically inside functions like solve() or truncate(). This function is normally the one you call to go back to the raw state once the condensed structure is destroyed, or to say "hey, solve() should start from a problem that already has an intermediate form." ๐Ÿ‘‘

See also: getState, solve, truncate, DSSetState (https://slepc.upv.es/release/manualpages/DS/DSSetState.html)

Source code at slepc4py/SLEPc/DS.pyx:381 (slepc4py/SLEPc/DS.pyx#L381)

setType(ds_type)

Set the type for the DS object.

Logically collective โ€” group activity fr fr.

Parameters

Return type: None (https://docs.python.org/3/library/constants.html#None)

See also: getType, DSSetType (https://slepc.upv.es/release/manualpages/DS/DSSetType.html)

Source code at slepc4py/SLEPc/DS.pyx:193 (slepc4py/SLEPc/DS.pyx#L193)

solve()

Solve the problem. That's it, that's the whole job ๐Ÿ’–

Logically collective.

Returns: Eigenvalues or singular values.

Return type: ArrayScalar (anchor #slepc4py.typing.ArrayScalar)

See also: DSSolve (https://slepc.upv.es/release/manualpages/DS/DSSolve.html)

Source code at slepc4py/SLEPc/DS.pyx:924 (slepc4py/SLEPc/DS.pyx#L924)

truncate(n, trim=False)

Truncate the system represented in the DS object. Shrink it, cute lil thing ๐ŸŽ€

Logically collective.

Parameters

Return type: None (https://docs.python.org/3/library/constants.html#None)

See also: setDimensions, setExtraRow, DSTruncate (https://slepc.upv.es/release/manualpages/DS/DSTruncate.html)

Source code at slepc4py/SLEPc/DS.pyx:753 (slepc4py/SLEPc/DS.pyx#L753)

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(). Basically it's the "hey bestie, catch up" function ๐Ÿ™ˆ

See also: DSUpdateExtraRow (https://slepc.upv.es/release/manualpages/DS/DSUpdateExtraRow.html)

Source code at slepc4py/SLEPc/DS.pyx:774 (slepc4py/SLEPc/DS.pyx#L774)

Return type: None (https://docs.python.org/3/library/constants.html#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. It defaults to X.

Return type: None (https://docs.python.org/3/library/constants.html#None)

See also: DSVectors (https://slepc.upv.es/release/manualpages/DS/DSVectors.html)

Source code at slepc4py/SLEPc/DS.pyx:952 (slepc4py/SLEPc/DS.pyx#L952)

view(viewer=None)

Print the DS data structure. Show me the receipts ๐Ÿ‘‘

Collective.

Parameters

Return type: None (https://docs.python.org/3/library/constants.html#None)

See also: DSView (https://slepc.upv.es/release/manualpages/DS/DSView.html)

Source code at slepc4py/SLEPc/DS.pyx:127 (slepc4py/SLEPc/DS.pyx#L127)

Attributes Documentation ๐Ÿ’…

  • block_size โ€” The block size. Source code at slepc4py/SLEPc/DS.pyx:1218 (slepc4py/SLEPc/DS.pyx#L1218)
  • compact โ€” Compact storage of matrices. Source code at slepc4py/SLEPc/DS.pyx:1232 (slepc4py/SLEPc/DS.pyx#L1232)
  • extra_row โ€” If the matrix has one extra row. Source code at slepc4py/SLEPc/DS.pyx:1239 (slepc4py/SLEPc/DS.pyx#L1239)
  • method โ€” The method to be used to solve the problem. Source code at slepc4py/SLEPc/DS.pyx:1225 (slepc4py/SLEPc/DS.pyx#L1225)
  • parallel โ€” The mode of operation in parallel runs. Source code at slepc4py/SLEPc/DS.pyx:1211 (slepc4py/SLEPc/DS.pyx#L1211)
  • refined โ€” If refined vectors must be computed. Source code at slepc4py/SLEPc/DS.pyx:1246 (slepc4py/SLEPc/DS.pyx#L1246)
  • state โ€” The state of the DS object. Source code at slepc4py/SLEPc/DS.pyx:1204 (slepc4py/SLEPc/DS.pyx#L1204)

__init__()

classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.EPS

class slepc4py.SLEPc.EPS

Bases: Object (https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Object.html#petsc4py.PETSc.Object)

Eigenvalue Problem Solver. ๐ŸŒˆ

The Eigenvalue Problem Solver (EPS) is the object provided by slepc4py for specifying a linear eigenvalue problem, either in standard or generalized form. It provides uniform and efficient access to all of the linear eigensolvers included in the package. Like, every single one. Obsessed. โœจ

๐ŸŒˆ Enumerations ๐ŸŒˆ

okay bestie, here's the whole roster of EPS enums โ€” every single one, no skips, no shortcuts ๐Ÿ’…

  • Balance (#slepc4py.SLEPc.EPS.Balance) โ€” EPS type of balancing used for non-Hermitian problems.
  • CISSExtraction (#slepc4py.SLEPc.EPS.CISSExtraction) โ€” EPS CISS extraction technique.
  • CISSQuadRule (#slepc4py.SLEPc.EPS.CISSQuadRule) โ€” EPS CISS quadrature rule.
  • Conv (#slepc4py.SLEPc.EPS.Conv) โ€” EPS convergence test.
  • ConvergedReason (#slepc4py.SLEPc.EPS.ConvergedReason) โ€” EPS convergence reasons.
  • ErrorType (#slepc4py.SLEPc.EPS.ErrorType) โ€” EPS error type to assess accuracy of computed solutions.
  • Extraction (#slepc4py.SLEPc.EPS.Extraction) โ€” EPS extraction technique.
  • KrylovSchurBSEType (#slepc4py.SLEPc.EPS.KrylovSchurBSEType) โ€” EPS Krylov-Schur method for BSE problems.
  • LanczosReorthogType (#slepc4py.SLEPc.EPS.LanczosReorthogType) โ€” EPS Lanczos reorthogonalization type.
  • PowerShiftType (#slepc4py.SLEPc.EPS.PowerShiftType) โ€” EPS Power shift type.
  • ProblemType (#slepc4py.SLEPc.EPS.ProblemType) โ€” EPS problem type.
  • Stop (#slepc4py.SLEPc.EPS.Stop) โ€” EPS stopping test.
  • Type (#slepc4py.SLEPc.EPS.Type) โ€” EPS type.
  • Which (#slepc4py.SLEPc.EPS.Which) โ€” EPS desired part of spectrum.

slepc4py.SLEPc.EPS.Balance</p> ๐Ÿ’–

class slepc4py.SLEPc.EPS.Balance

Bases: object (https://docs.python.org/3/library/functions.html#object)

EPS type of balancing used for non-Hermitian problems.

  • NONE โ€” None. (nothing, nada, bye ๐Ÿซถ)
  • ONESIDE โ€” One-sided balancing.
  • TWOSIDE โ€” Two-sided balancing.
  • USER โ€” User-provided balancing matrices.

See also: EPSBalance (https://slepc.upv.es/release/manualpages/EPS/EPSBalance.html)

โœจ Attributes Summary โœจ

๐ŸŽ€ Attributes Documentation ๐ŸŽ€

NONE: int = NONE โ€” its int link lives at (https://docs.python.org/3/library/functions.html#int)

Constant NONE of type int (https://docs.python.org/3/library/functions.html#int).

ONESIDE: int = ONESIDE โ€” its int link lives at (https://docs.python.org/3/library/functions.html#int)

Constant ONESIDE of type int (https://docs.python.org/3/library/functions.html#int).

TWOSIDE: int = TWOSIDE โ€” its int link lives at (https://docs.python.org/3/library/functions.html#int)

Constant TWOSIDE of type int (https://docs.python.org/3/library/functions.html#int).

USER: int = USER โ€” its int link lives at (https://docs.python.org/3/library/functions.html#int)

Constant USER of type int (https://docs.python.org/3/library/functions.html#int).

__init__()
classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.EPS.CISSExtraction ๐Ÿฆ‹

class slepc4py.SLEPc.EPS.CISSExtraction

Bases: object (https://docs.python.org/3/library/functions.html#object)

EPS CISS extraction technique.

  • RITZ โ€” Ritz extraction.
  • HANKEL โ€” Extraction via Hankel eigenproblem.

See also: EPSCISSExtraction (https://slepc.upv.es/release/manualpages/EPS/EPSCISSExtraction.html)

โœจ Attributes Summary โœจ

๐ŸŽ€ Attributes Documentation ๐ŸŽ€

HANKEL: int = HANKEL โ€” its int link lives at (https://docs.python.org/3/library/functions.html#int)

Constant HANKEL of type int (https://docs.python.org/3/library/functions.html#int).

RITZ: int = RITZ โ€” its int link lives at (https://docs.python.org/3/library/functions.html#int)

Constant RITZ of type int (https://docs.python.org/3/library/functions.html#int).

__init__()
classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.EPS.CISSQuadRule ๐ŸŒธ

class slepc4py.SLEPc.EPS.CISSQuadRule

Bases: object (https://docs.python.org/3/library/functions.html#object)

EPS CISS quadrature rule.

  • TRAPEZOIDAL โ€” Trapezoidal rule. classic, dependable, does exactly what it says ๐Ÿ’…
  • CHEBYSHEV โ€” Chebyshev points. the โœจaestheticโœจ choice, clustering at the edges like it's got somewhere to be

See also: EPSCISSQuadRule โ€” the C side of this whole situation lives at https://slepc.upv.es/release/manualpages/EPS/EPSCISSQuadRule.html ๐Ÿซถ

โœจ Attributes Summary โœจ

okay bestie, here's the lil roster of constants this class is carrying around. every single one is an int (yes, that int, the Python one, over at https://docs.python.org/3/library/functions.html#int):

๐ŸŒธ Attributes Documentation ๐ŸŒธ

__init__()

classmethod __new__(*args, **kwargs)

๐Ÿ‘‘ class slepc4py.SLEPc.EPS.Conv

Bases: object (https://docs.python.org/3/library/functions.html#object)

not me introducing the glow-up that is EPS convergence test ๐Ÿ’– this is literally just the menu of ways your solver can decide "yeah, that eigenpair is cooked" or "nope, try again":

  • ABS โ€” Absolute convergence test.
  • REL โ€” Convergence test relative to the eigenvalue.
  • NORM โ€” Convergence test relative to the matrix norms.
  • USER โ€” User-defined convergence test. your rules, your world, main character energy fr fr

See also: EPSConv โ€” https://slepc.upv.es/release/manualpages/EPS/EPSConv.html

โœจ Attributes Summary โœจ

๐ŸŒˆ Attributes Documentation ๐ŸŒˆ

__init__()

classmethod __new__(*args, **kwargs)

๐Ÿฆ‹ class slepc4py.SLEPc.EPS.ConvergedReason

Bases: object (https://docs.python.org/3/library/functions.html#object)

this is the "how did it end" report card, bestie. EPS convergence reasons โ€” the receipts on your solve:

  • CONVERGED_TOL โ€” All eigenpairs converged to requested tolerance. ate and left no crumbs ๐Ÿ’…
  • CONVERGED_USER โ€” User-defined convergence criterion satisfied.
  • DIVERGED_ITS โ€” Maximum number of iterations exceeded. it ran out of breath ๐Ÿ˜ญ
  • DIVERGED_BREAKDOWN โ€” Solver failed due to breakdown.
  • DIVERGED_SYMMETRY_LOST โ€” Lanczos-type method could not preserve symmetry. it fumbled the symmetry, tragic fr
  • CONVERGED_ITERATING โ€” Iteration not finished yet. still cooking ๐Ÿ“

See also: EPSConvergedReason โ€” https://slepc.upv.es/release/manualpages/EPS/EPSConvergedReason.html

โœจ Attributes Summary โœจ

๐Ÿ’œ Attributes Documentation ๐Ÿ’œ

slepc4py.SLEPc.EPS.ErrorType</p>

class slepc4py.SLEPc.EPS.ErrorType

Bases: object (https://docs.python.org/3/library/functions.html#object)

Okay bestie, this one is literally the EPS error type โ€” it's what you use to assess the accuracy of computed solutions. Like, how close did we actually get? vibe check on your eigenvalues ๐Ÿ“โœจ

  • ABSOLUTE โ€” Absolute error.
  • RELATIVE โ€” Relative error.
  • BACKWARD โ€” Backward error.

See also:

Attributes Summary

Attributes Documentation

slepc4py.SLEPc.EPS.Extraction</p>

class slepc4py.SLEPc.EPS.Extraction

Bases: object (https://docs.python.org/3/library/functions.html#object)

This is the EPS extraction technique โ€” as in, which flavour of extraction you're running. Pick your fighter, they're all iconic in their own way ๐Ÿ‘‘

  • RITZ โ€” Standard Rayleigh-Ritz extraction.
  • HARMONIC โ€” Harmonic extraction.
  • HARMONIC_RELATIVE โ€” Harmonic extraction relative to the eigenvalue.
  • HARMONIC_RIGHT โ€” Harmonic extraction for rightmost eigenvalues.
  • HARMONIC_LARGEST โ€” Harmonic extraction for largest magnitude (without target).
  • REFINED โ€” Refined extraction.
  • REFINED_HARMONIC โ€” Refined harmonic extraction.

See also:

Attributes Summary

Attributes Documentation

slepc4py.SLEPc.EPS.KrylovSchurBSEType</p>

class slepc4py.SLEPc.EPS.KrylovSchurBSEType

Bases: object (https://docs.python.org/3/library/functions.html#object)

This is the EPS Krylov-Schur method for BSE problems โ€” three whole flavours of Lanczos recurrence for you to choose from, bestie ๐Ÿ’…

  • SHAO โ€” Lanczos recurrence for H square.
  • GRUNING โ€” Lanczos recurrence for H.
  • PROJECTEDBSE โ€” Lanczos where the projected problem has BSE structure.

See also:

โœจ Attributes Summary โœจ

okay bestie, quick vibe check on the constants living in here ๐Ÿ” every single one is a plain-ol' int, link included, no cap:

๐Ÿ’– Attributes Documentation ๐Ÿ’–

__init__()

classmethod __new__(*args, **kwargs)

๐Ÿฆ‹ class slepc4py.SLEPc.EPS.LanczosReorthogType

class slepc4py.SLEPc.EPS.LanczosReorthogType

Bases: object (https://docs.python.org/3/library/functions.html#object)

so this is the EPS Lanczos reorthogonalization type ๐ŸŒธ she's the queen of deciding how much work we do to keep those Lanczos vectors honest:

  • LOCAL: local reorthogonalization only.
  • FULL: full reorthogonalization.
  • SELECTIVE: selective reorthogonalization.
  • PERIODIC: periodic reorthogonalization.
  • PARTIAL: partial reorthogonalization.
  • DELAYED: delayed reorthogonalization.

See also:

โœจ Attributes Summary โœจ

๐Ÿ’– Attributes Documentation ๐Ÿ’–

__init__()

classmethod __new__(*args, **kwargs)

๐ŸŒˆ class slepc4py.SLEPc.EPS.PowerShiftType

class slepc4py.SLEPc.EPS.PowerShiftType

Bases: object (https://docs.python.org/3/library/functions.html#object)

EPS Power shift type โšก she's the one who picks what shift we're throwing around, and honestly? iconic:

  • CONSTANT: constant shift.
  • RAYLEIGH: Rayleigh quotient.
  • WILKINSON: Wilkinson shift.

See also:

โœจ Attributes Summary โœจ

๐Ÿ’– Attributes Documentation ๐Ÿ’–

__init__()

classmethod __new__(*args, **kwargs)

๐ŸŽ€ class slepc4py.SLEPc.EPS.ProblemType

class slepc4py.SLEPc.EPS.ProblemType

Bases: object (https://docs.python.org/3/library/functions.html#object)

EPS problem type ๐Ÿ‘‘ this is the "what flavor of eigenproblem are we even solving" menu, and the vibes are immaculate:

  • HEP: Hermitian eigenproblem.
  • NHEP: Non-Hermitian eigenproblem.
  • GHEP: Generalized Hermitian eigenproblem.
  • GNHEP: Generalized Non-Hermitian eigenproblem.
  • PGNHEP: Generalized Non-Hermitian eigenproblem with positive definite B.
  • GHIEP: Generalized Hermitian-indefinite eigenproblem.
  • BSE: Structured Bethe-Salpeter eigenproblem.
  • HAMILT โ€” Hamiltonian eigenproblem. ๐ŸŒธ
  • LREP โ€” Structured Linear Response eigenvalue problem. โœจ

See also:

๐ŸŒˆ Attributes Summary ๐ŸŒˆ

bestie these are all just constants, and every single one of them is a plain ol' int (link for the curious: https://docs.python.org/3/library/functions.html#int). Here's the whole squad:

๐Ÿ’– Attributes Documentation ๐Ÿ’–

okay so now the receipts, one by one, no skips:

Constant BSE of type int (https://docs.python.org/3/library/functions.html#int)

Constant GHEP of type int (https://docs.python.org/3/library/functions.html#int)

Constant GHIEP of type int (https://docs.python.org/3/library/functions.html#int)

Constant GNHEP of type int (https://docs.python.org/3/library/functions.html#int)

Constant HAMILT of type int (https://docs.python.org/3/library/functions.html#int)

Constant HEP of type int (https://docs.python.org/3/library/functions.html#int)

Constant LREP of type int (https://docs.python.org/3/library/functions.html#int)

Constant NHEP of type int (https://docs.python.org/3/library/functions.html#int)

Constant PGNHEP of type int (https://docs.python.org/3/library/functions.html#int)

__init__()

literally just that. no args, no drama, she's empty. ๐ŸŽ€

classmethod __new__(*args, **kwargs)

and she takes *args, **kwargs, because sometimes you gotta be flexible, periodt. ๐Ÿ’…

๐Ÿ›‘ class slepc4py.SLEPc.EPS.Stop

class slepc4py.SLEPc.EPS.Stop

Bases: object (https://docs.python.org/3/library/functions.html#object)

EPS stopping test. a.k.a. how your solver decides she's done. ๐ŸŒธ

  • BASIC โ€” Default stopping test.
  • USER โ€” User-defined stopping test. (yes queen, write your own)
  • THRESHOLD โ€” Threshold stopping test.

See also:

โœจ Attributes Summary โœจ

๐Ÿ’– Attributes Documentation ๐Ÿ’–

Constant BASIC of type int (https://docs.python.org/3/library/functions.html#int)

Constant THRESHOLD of type int (https://docs.python.org/3/library/functions.html#int)

Constant USER of type int (https://docs.python.org/3/library/functions.html#int)

__init__()

same energy as before, empty and unbothered. ๐Ÿ™ˆ

classmethod __new__(*args, **kwargs)

again with the *args, **kwargs. consistent king. ๐Ÿ‘‘

๐Ÿ‘‘ class slepc4py.SLEPc.EPS.Type

class slepc4py.SLEPc.EPS.Type

Bases: object (https://docs.python.org/3/library/functions.html#object)

EPS type. this is the menu, bestie โ€” pick your solver. ๐Ÿ“

Native eigenvalue solvers. (the homegrown ones, SO talented)

  • POWER โ€” Power Iteration, Inverse Iteration, RQI.
  • SUBSPACE โ€” Subspace Iteration.
  • ARNOLDI โ€” Arnoldi.
  • LANCZOS โ€” Lanczos.
  • KRYLOVSCHUR โ€” Krylov-Schur (default). the moment. ๐Ÿ’…
  • GD โ€” Generalized Davidson.
  • JD โ€” Jacobi-Davidson.
  • RQCG โ€” Rayleigh Quotient Conjugate Gradient.
  • LOBPCG โ€” Locally Optimal Block Preconditioned Conjugate Gradient.
  • CISS โ€” Contour Integral Spectrum Slicing.
  • LYAPII โ€” Lyapunov inverse iteration.

Wrappers to external eigensolvers โ€” heads up: these should be enabled during installation of SLEPc, so if one of them is ghosting you, that's a build thing, not a you thing. โœจ

  • LAPACK โ€” Sequential dense eigensolver.
  • ARPACK โ€” Iterative Krylov-based eigensolver.
  • BLOPEX โ€” Implementation of LOBPCG.
  • PRIMME โ€” Iterative eigensolvers of Davidson type.
  • FEAST โ€” Contour integral eigensolver.
  • SCALAPACK โ€” Parallel dense eigensolver for symmetric problems.
  • ELPA โ€” Parallel dense eigensolver for symmetric problems.
  • ELEMENTAL โ€” Parallel dense eigensolver for symmetric problems.
  • EVSL โ€” Iterative eigensolver based on polynomial filters. ๐Ÿ’…
  • CHASE โ€” Subspace iteration, but make it accelerated with polynomials. Slay. ๐Ÿ”ฅ

See also:

๐ŸŽ€ Attributes Summary ๐ŸŽ€

okay bestie, quick tea before the full breakdown: every single one of these is an object of type str (that's Python's built-in string type, and the docs for it are right here: https://docs.python.org/3/library/stdtypes.html#str). Like, they're literally just fancy strings, bestie. Strings that define eigensolver vibes. Not me finding that iconic. ๐Ÿ˜ญ

  • ARNOLDI โ€” Object ARNOLDI of type str ๐Ÿ’–
  • ARPACK โ€” Object ARPACK of type str โœจ
  • BLOPEX โ€” Object BLOPEX of type str ๐ŸŽ€
  • CHASE โ€” Object CHASE of type str ๐Ÿฆ‹
  • CISS โ€” Object CISS of type str ๐ŸŒธ
  • ELEMENTAL โ€” Object ELEMENTAL of type str ๐Ÿ’…
  • ELPA โ€” Object ELPA of type str ๐Ÿซถ
  • EVSL โ€” Object EVSL of type str ๐Ÿ˜ญ
  • FEAST โ€” Object FEAST of type str ๐Ÿ”ฅ
  • GD โ€” Object GD of type str ๐Ÿ‘‘
  • JD โ€” Object JD of type str ๐ŸŒˆ
  • KRYLOVSCHUR โ€” Object KRYLOVSCHUR of type str โญ
  • LANCZOS โ€” Object LANCZOS of type str ๐Ÿ’€
  • LAPACK โ€” Object LAPACK of type str ๐Ÿ™ˆ
  • LOBPCG โ€” Object LOBPCG of type str ๐Ÿ“
  • LYAPII โ€” Object LYAPII of type str ๐Ÿงš
  • POWER โ€” Object POWER of type str ๐Ÿ’œ
  • PRIMME โ€” Object PRIMME of type str ๐Ÿ’–
  • RQCG โ€” Object RQCG of type str โœจ
  • SCALAPACK โ€” Object SCALAPACK of type str ๐ŸŽ€
  • SUBSPACE โ€” Object SUBSPACE of type str ๐Ÿฆ‹

โญ Attributes Documentation โญ

alright, now the receipts. one by one, no skips, no cap. ๐Ÿ‘‘

๐Ÿ’œ ARNOLDI

ARNOLDI: str = ARNOLDI

Object ARNOLDI of type str (https://docs.python.org/3/library/stdtypes.html#str). ๐Ÿ’œ

๐Ÿ’– ARPACK

ARPACK: str = ARPACK

Object ARPACK of type str (https://docs.python.org/3/library/stdtypes.html#str). ๐Ÿ’–

๐ŸŽ€ BLOPEX

BLOPEX: str = BLOPEX

Object BLOPEX of type str (https://docs.python.org/3/library/stdtypes.html#str). ๐ŸŽ€

๐Ÿฆ‹ CHASE

CHASE: str = CHASE

Object CHASE of type str (https://docs.python.org/3/library/stdtypes.html#str). ๐Ÿฆ‹

๐ŸŒธ CISS

CISS: str = CISS

Object CISS of type str (https://docs.python.org/3/library/stdtypes.html#str). ๐ŸŒธ

  • ELEMENTAL: str = ELEMENTAL โ€” an object ELEMENTAL of type str. That's it, that's the whole vibe ๐Ÿ’…
  • ELPA: str = ELPA โ€” an object ELPA of type str โœจ
  • EVSL: str = EVSL โ€” an object EVSL of type str โœจ
  • FEAST: str = FEAST โ€” an object FEAST of type str โœจ
  • GD: str = GD โ€” an object GD of type str โœจ
  • JD: str = JD โ€” an object JD of type str โœจ
  • KRYLOVSCHUR: str = KRYLOVSCHUR โ€” an object KRYLOVSCHUR of type str (yes bestie they really just wrote it twice, that's the documentation, not me being lazy ๐Ÿ˜ญ) โœจ
  • LANCZOS: str = LANCZOS โ€” an object LANCZOS of type str โœจ
  • LAPACK: str = LAPACK โ€” an object LAPACK of type str โœจ
  • LOBPCG: str = LOBPCG โ€” an object LOBPCG of type str โœจ
  • LYAPII: str = LYAPII โ€” an object LYAPII of type str โœจ
  • POWER: str = POWER โ€” an object POWER of type str โœจ
  • PRIMME: str = PRIMME โ€” an object PRIMME of type str โœจ
  • RQCG: str = RQCG โ€” an object RQCG of type str โœจ
  • SCALAPACK: str = SCALAPACK โ€” an object SCALAPACK of type str โœจ
  • SUBSPACE: str = SUBSPACE โ€” an object SUBSPACE of type str โœจ
  • __init__() โ€” the init, doing absolutely nothing dramatic, just being there ๐Ÿซถ
  • classmethod __new__(*args, **kwargs) โ€” the constructor hook, taking *args and **kwargs and keeping it mysterious ๐Ÿ˜Œ

๐Ÿฆ‹ slepc4py.SLEPc.EPS.Which ๐Ÿฆ‹

class slepc4py.SLEPc.EPS.Which

Bases: object (just plain object, humble queen)

It's givingโ€ฆ EPS desired part of spectrum. Which part of the spectrum do you want your eigenvalues from? That's the whole entire question this class answers bestie ๐Ÿ’–

  • LARGEST_MAGNITUDE โ€” Largest magnitude (this is the default, so if you don't pick anything, this is what you get ๐ŸŒŸ)
  • SMALLEST_MAGNITUDE โ€” Smallest magnitude
  • LARGEST_REAL โ€” Largest real parts
  • SMALLEST_REAL โ€” Smallest real parts
  • LARGEST_IMAGINARY โ€” Largest imaginary parts in magnitude
  • SMALLEST_IMAGINARY โ€” Smallest imaginary parts in magnitude
  • TARGET_MAGNITUDE โ€” Closest to target, measured in magnitude
  • TARGET_REAL โ€” Real part closest to target
  • TARGET_IMAGINARY โ€” Imaginary part closest to target
  • ALL โ€” All eigenvalues in an interval ๐Ÿ’€ (yes all of them, good luck)
  • USER โ€” User defined selection, you're the main character now

See also:

  • EPSWhich โ€” go look at the C manual page for the real tea ๐Ÿ“

๐ŸŒธ Attributes Summary ๐ŸŒธ

  • ALL โ€” Constant ALL of type int
  • LARGEST_IMAGINARY โ€” Constant LARGEST_IMAGINARY of type int
  • LARGEST_MAGNITUDE โ€” Constant LARGEST_MAGNITUDE of type int
  • LARGEST_REAL โ€” Constant LARGEST_REAL of type int
  • SMALLEST_IMAGINARY โ€” Constant SMALLEST_IMAGINARY of type int
  • SMALLEST_MAGNITUDE โ€” Constant SMALLEST_MAGNITUDE of type int
  • SMALLEST_REAL โ€” Constant SMALLEST_REAL of type int
  • TARGET_IMAGINARY โ€” Constant TARGET_IMAGINARY of type int
  • TARGET_MAGNITUDE โ€” Constant TARGET_MAGNITUDE of type int
  • TARGET_REAL โ€” Constant TARGET_REAL of type int
  • USER โ€” Constant USER of type int
Not a table bestie, sorry, but every single one of them is in there, no cap ๐Ÿซถ

โœจ Attributes Documentation โœจ

  • ALL: int = ALL โ€” Constant ALL of type int ๐Ÿ’–
  • LARGEST_IMAGINARY: int = LARGEST_IMAGINARY โ€” Constant LARGEST_IMAGINARY of type int ๐Ÿ’–
  • LARGEST_MAGNITUDE: int = LARGEST_MAGNITUDE โ€” Constant LARGEST_MAGNITUDE, and it's of type int. That's the whole vibe, bestie. ๐Ÿ“
  • LARGEST_REAL: int = LARGEST_REAL โ€” Constant LARGEST_REAL, type int. ๐Ÿ’–
  • SMALLEST_IMAGINARY: int = SMALLEST_IMAGINARY โ€” Constant SMALLEST_IMAGINARY, type int. Tiny imaginary energy, love that for it. ๐Ÿฆ‹
  • SMALLEST_MAGNITUDE: int = SMALLEST_MAGNITUDE โ€” Constant SMALLEST_MAGNITUDE, type int. ๐Ÿ“
  • SMALLEST_REAL: int = SMALLEST_REAL โ€” Constant SMALLEST_REAL, type int. โœจ
  • TARGET_IMAGINARY: int = TARGET_IMAGINARY โ€” Constant TARGET_IMAGINARY, type int. ๐ŸŽฏ
  • TARGET_MAGNITUDE: int = TARGET_MAGNITUDE โ€” Constant TARGET_MAGNITUDE, type int. ๐ŸŽ€
  • TARGET_REAL: int = TARGET_REAL โ€” Constant TARGET_REAL, type int. โญ
  • USER: int = USER โ€” Constant USER, type int. it's giving "you, specifically" ๐Ÿ’…

okay and then the actual callable bits, bestie ๐Ÿ‘‘

__init__()

that's it, no args, no nothing โ€” just vibes ๐Ÿ’œ

classmethod __new__(*args, **kwargs)

a classmethod __new__ that takes *args and **kwargs, fr fr. ๐Ÿงš

  • appendOptionsPrefix([prefix]) โ€” tacks prefix onto the prefix that's used to hunt down all the EPS options in the database ๐Ÿ’…
  • cancelMonitor() โ€” nukes every monitor on an EPS object, all of them, gone ๐Ÿซถ
  • computeError(i[, etype]) โ€” crunches the error for the i-th computed eigenpair โœจ
  • create([comm]) โ€” births a whole new EPS object, icon behavior ๐ŸŽ€
  • destroy() โ€” destroys the EPS object, bye bestie ๐Ÿ’€
  • errorView([etype, viewer]) โ€” shows off the errors attached to the computed solution ๐Ÿ‘‘
  • getArbitrarySelection() โ€” grabs the arbitrary selection function
  • getArnoldiDelayed() โ€” tells you which flavor of reorthogonalization was used during the Arnoldi iteration ๐ŸŒˆ
  • getBV() โ€” hands you the basis vectors object that's associated to the eigensolver
  • getBalance() โ€” gets the balancing type the EPS is using, plus all the associated params ๐Ÿ’œ
  • getCISSExtraction() โ€” gets the extraction technique used in the CISS solver
  • getCISSKSPs() โ€” returns the array of linear solver objects associated with the CISS solver
  • getCISSQuadRule() โ€” gets the quadrature rule used in the CISS solver
  • getCISSRefinement() โ€” gets the values of the various refinement parameters in the CISS solver
  • getCISSSizes() โ€” gets the values of the various size parameters in the CISS solver
  • getCISSThreshold() โ€” gets the values of the various threshold parameters in the CISS solver ๐Ÿ“
  • getCISSUseST() โ€” gets the flag that says whether the ST <#slepc4py.SLEPc.ST> object is being used in the CISS solver
  • getConverged() โ€” tells you how many eigenpairs actually converged, living for it ๐Ÿ˜ญ
  • getConvergedReason() โ€” gets the reason why the solve() iteration stopped, the tea on why it quit โ˜•
  • getConvergenceTest() โ€” gets how the error estimate used in the convergence test is computed
  • getDS() โ€” gets the direct solver associated to the eigensolver
  • getDimensions() โ€” gets the number of eigenvalues to compute and the dimension of the subspace
  • getEigenpair(i[, Vr, Vi]) โ€” grabs the i-th solution of the eigenproblem as computed by solve() ๐Ÿ’–
  • getEigenvalue(i) โ€” grabs the i-th eigenvalue as computed by solve()
  • getEigenvalueComparison() โ€” gets the eigenvalue comparison function
  • getEigenvector(i[, Vr, Vi]) โ€” grabs the i-th right eigenvector as computed by solve() โญ
  • getErrorEstimate(i) โ€” hands you the error estimate that goes with the i-th computed eigenpair ๐Ÿ’– like a lil receipt for how sure it is about that one.
  • getExtraction() โ€” tells you which extraction type the EPS object is out here using, no mystery.
  • getGDBOrth() โ€” the orthogonalization technique in play over in the search subspace ๐ŸŒธ
  • getGDBlockSize() โ€” how many vectors get added into the searching space, that's the whole vibe.
  • getGDDoubleExpansion() โ€” returns a flag saying whether the double expansion variant is active or nah ๐Ÿฆ‹
  • getGDInitialSize() โ€” the starting size of the searching space, its origin story basically.
  • getGDKrylovStart() โ€” a flag telling you if the search subspace kicks off with a Krylov basis โœจ
  • getGDRestart() โ€” how many vectors of the search space are left hanging after a restart.
  • getInterval() โ€” the computational interval it's working with for spectrum slicing, iconic.
  • getInvariantSubspace() โ€” serves up an orthonormal basis of the computed invariant subspace, periodt ๐Ÿ’…
  • getIterationNumber() โ€” the current iteration number, like where are we on the journey bestie.
  • getJDBOrth() โ€” the orthogonalization used in the search subspace (JDB edition) ๐ŸŒˆ
  • getJDBlockSize() โ€” number of vectors being added to the searching space, fr fr.
  • getJDConstCorrectionTol() โ€” a flag saying whether the dynamic stopping is being used or not.
  • getJDFix() โ€” the threshold for changing the target inside the correction equation ๐ŸŽ€
  • getJDInitialSize() โ€” the initial size of the searching space, its humble beginnings.
  • getJDKrylovStart() โ€” flag check: is the search subspace started with a Krylov basis? ๐Ÿ‘‘
  • getJDRestart() โ€” how many vectors of the search space survive after restart.
  • getKrylovSchurBSEType() โ€” the method used for BSE structured eigenproblems, specifically the Krylov-Schur one ๐Ÿ“
  • getKrylovSchurDetectZeros() โ€” the flag that enforces zero detection in spectrum slicing, no zeros slipping through unnoticed.
  • getKrylovSchurDimensions() โ€” the dimensions used for each subsolve step in spectrum slicing.
  • getKrylovSchurInertias() โ€” the values of the shifts, plus their corresponding inertias, all together ๐Ÿ’œ
  • getKrylovSchurKSP() โ€” the linear solver object associated with the internal EPS object. it's giving nested objects.
  • getKrylovSchurLocking() โ€” the locking flag used in the Krylov-Schur method ๐Ÿ”ฅ
  • getKrylovSchurPartitions() โ€” Get the number of
  • โ€ฆ*partitions of the communicator (spectrum slicing)*. yeah that was the tail end of the last one, we're back ๐Ÿ’…
  • getKrylovSchurRestart() โ€” hands you the restart parameter that the Krylov-Schur method is using. ๐Ÿ”
  • getKrylovSchurSubcommInfo() โ€” gives you the info related to the case of doing spectrum slicing. she's niche and she knows it ๐ŸŒˆ
  • getKrylovSchurSubcommMats() โ€” the eigenproblem matrices, except stored in the subcommunicator. ๐Ÿ“ฆ
  • getKrylovSchurSubcommPairs(i[, v]) โ€” grabs the i-th eigenpair stored in the multi-communicator of the process. the v is optional bestie, you don't have to bring it ๐ŸŽ€
  • getKrylovSchurSubintervals() โ€” the points that delimit the subintervals. map the territory โœจ
  • getLOBPCGBlockSize() โ€” the block size used in the LOBPCG method. ๐Ÿงฑ
  • getLOBPCGLocking() โ€” the locking flag used in the LOBPCG method. ๐Ÿ”’
  • getLOBPCGRestart() โ€” the restart parameter used in the LOBPCG method. ๐Ÿ”
  • getLanczosReorthogType() โ€” the type of reorthogonalization used during the Lanczos iteration. she's reorthogonalizing, respectfully ๐Ÿ’œ
  • getLeftEigenvector(i[, Wr, Wi]) โ€” the i-th left eigenvector as computed by solve(). Wr and Wi are optional โ€” real part, imaginary part, you know the drill ๐Ÿฆ‹
  • getLyapIIRanks() โ€” the rank values used for the Lyapunov step. ๐Ÿ“
  • getMonitor() โ€” the list of monitor functions. who's watching? ๐Ÿ‘€
  • getOperators() โ€” the matrices associated with the eigenvalue problem. the whole crew ๐Ÿซถ
  • getOptionsPrefix() โ€” the prefix used for searching for all EPS options in the database. ๐Ÿ”
  • getPowerShiftType() โ€” the type of shifts used during the power iteration. โšก
  • getProblemType() โ€” the problem type, straight from the EPS object. ๐Ÿ’ซ
  • getPurify() โ€” the flag indicating whether purification is activated or not. cleanse her ๐Ÿงผ
  • getRG() โ€” the region object associated to the eigensolver. ๐Ÿ—บ๏ธ
  • getRQCGReset() โ€” the reset parameter used in the RQCG method. ๐Ÿ”„
  • getST() โ€” the spectral transformation object associated to the eigensolver. the ST!! iconic ๐Ÿ‘‘
  • getStoppingTest() โ€” the stopping test function. know when to stop, queen ๐Ÿ’…
  • getTarget() โ€” the value of the target. ๐ŸŽฏ
  • getThreshold() โ€” the threshold used in the threshold stopping test. ๐Ÿ“
  • getTolerances() โ€” the tolerance and max. that's it, that's the description ๐Ÿ˜ญ
  • getTrackAll() โ€” the flag indicating if all residual norms must be computed or not. all of them?? all?? ๐Ÿ’€
  • getTrueResidual() โ€” the flag indicating if true residual must be
  • getTwoSided() โ€” bestie, this one returns the flag that tells you if the two-sided variant of the algorithm is currently being used ๐Ÿ’…
  • getType() โ€” grabs the EPS type of this object, like what flavor of eigensolver we're dealing with โœจ
  • getWhichEigenpairs() โ€” tells you which portion of the spectrum is to be sought, so you know where to look ๐Ÿ”
  • isGeneralized() โ€” asks if the EPS object corresponds to a generalized eigenproblem, returns the tea ๐Ÿ’–
  • isHermitian() โ€” checks if the EPS object is giving Hermitian eigenproblem energy, no cap ๐ŸŒธ
  • isPositive() โ€” tells you if the eigenproblem requires a positive (semi-) definite matrix B, periodt ๐Ÿ’…
  • isStructured() โ€” is it a structured eigenvalue problem? this returns the answer ๐Ÿ‘‘
  • reset() โ€” resets the EPS object, fresh start, clean slate, we love a reset ๐Ÿงผ
  • setArbitrarySelection(arbitrary[, args, kargs]) โ€” sets an arbitrary selection criterion function โ€” you bring the function, it handles the rest ๐ŸŽ€
  • setArnoldiDelayed(delayed) โ€” sets (toggles) delayed reorthogonalization in the Arnoldi iteration, fancy ๐Ÿ’…
  • setBV(bv) โ€” attaches a basis vectors object to the eigensolver, like giving it a little buddy ๐Ÿซถ
  • setBalance([balance, iterations, cutoff]) โ€” sets the balancing technique to be used by the eigensolver โ€” you can pass balance, iterations, cutoff if you want to be specific โœจ
  • setCISSExtraction(extraction) โ€” picks the extraction technique used in the CISS solver ๐Ÿ”ฅ
  • setCISSQuadRule(quad) โ€” sets the quadrature rule used in the CISS solver, math vibes ๐Ÿงฎ
  • setCISSRefinement([inner, blsize]) โ€” sets the values of various refinement parameters in the CISS solver โ€” inner and blsize are optional but iconic ๐Ÿ’–
  • setCISSSizes([ip, bs, ms, npart, bsmax, ...]) โ€” sets the values of various size parameters in the CISS solver: ip, bs, ms, npart, bsmax, and more if you got 'em ๐Ÿ‘‘
  • setCISSThreshold([delta, spur]) โ€” sets the values of various threshold parameters in the CISS solver โ€” delta and spur are the optional besties here ๐ŸŒธ
  • setCISSUseST(usest) โ€” sets a flag indicating that the CISS solver will use the ST <#slepc4py.SLEPc.ST> object โ€” big yes ๐Ÿ’…
  • setConvergenceTest(conv) โ€” sets how to compute the error estimate used in the convergence test, crucial ๐Ÿ”
  • setDS(ds) โ€” hooks up a direct solver object associated to the eigensolver, match made in heaven ๐Ÿซถ
  • setDeflationSpace(space) โ€” sets vectors to form a basis of the deflation space, deflate to inflate โœจ
  • setDimensions([nev, ncv, mpd]) โ€” sets the number of eigenvalues to compute and the dimension of the subspace โ€” nev, ncv, mpd are the optional knobs ๐ŸŽ›๏ธ
  • setEigenvalueComparison(comparison[, args, ...]) โ€” sets an eigenvalue comparison function โ€” you can pass extra args too ๐Ÿ’–
  • setExtraction(extraction) โ€” sets the extraction type used by the eigensolver, extraction is the move ๐Ÿ”ฅ
  • setFromOptions() โ€” pulls EPS options straight from the options database, set it and forget it ๐Ÿ’…
  • setGDBOrth(borth) โ€” sets the orthogonalization that will be used in the
  • setGDBlockSize(bs) โ€” sets the number of vectors to be added to the searching space. block size but make it GD, bestie. ๐Ÿ’…
  • setGDDoubleExpansion(doubleexp) โ€” sets that the search subspace is expanded with double expansion. double expansion, double the drama. ๐Ÿ”ฅ
  • setGDInitialSize(initialsize) โ€” sets the initial size of the searching space. the starting size, periodt. ๐ŸŒธ
  • setGDKrylovStart([krylovstart]) โ€” sets (or toggles) starting the search subspace with a Krylov basis. Krylov start, on or off. โญ
  • setGDRestart([minv, plusk]) โ€” sets the number of vectors of the search space after restart. restart math with [minv, plusk]. ๐Ÿ’œ
  • setInitialSpace(space) โ€” sets the initial space from which the eigensolver starts to iterate. the launchpad, fr fr. โœจ
  • setInterval(inta, intb) โ€” sets the computational interval for spectrum slicing. gives the slice a range. ๐Ÿ’–
  • setJDBOrth(borth) โ€” sets the orthogonalization that will be used in the search subspace. JDB orth, iconic. ๐ŸŽ€
  • setJDBlockSize(bs) โ€” sets the number of vectors to be added to the searching space. JD block size, same energy as GD but JD. ๐Ÿ’…
  • setJDConstCorrectionTol(constant) โ€” deactivates the dynamic stopping criterion. turning off dynamic tol, no cap. ๐Ÿ’€
  • setJDFix(fix) โ€” sets the threshold for changing the target in the correction equation. threshold for target switching. ๐Ÿ‘‘
  • setJDInitialSize(initialsize) โ€” sets the initial size of the searching space. JD starting size. ๐ŸŒˆ
  • setJDKrylovStart([krylovstart]) โ€” sets (or toggles) starting the search subspace with a Krylov basis. JD Krylov start toggle. โญ
  • setJDRestart([minv, plusk]) โ€” sets the number of vectors of the search space after restart. JD restart numbers. ๐Ÿ’œ
  • setKrylovSchurBSEType(bse) โ€” sets the Krylov-Schur variant used for BSE structured eigenproblems. BSE type, slay. ๐Ÿฆ‹
  • setKrylovSchurDetectZeros(detect) โ€” sets the flag that enforces zero detection in spectrum slicing. zero detection flag. ๐Ÿ”ฅ
  • setKrylovSchurDimensions([nev, ncv, mpd]) โ€” sets the dimensions used for each subsolve step (spectrum slicing). dims: [nev, ncv, mpd]. โœจ
  • setKrylovSchurLocking(lock) โ€” sets (or toggles) locking/non-locking variants of the Krylov-Schur method. lock or no lock. ๐Ÿ’…
  • setKrylovSchurPartitions(npart) โ€” sets the number of partitions of the communicator (spectrum slicing). partitions count. ๐ŸŽ€
  • setKrylovSchurRestart(keep) โ€” sets the restart parameter for the Krylov-Schur method. keep it. ๐Ÿ’–
  • setKrylovSchurSubintervals(subint) โ€” sets the subinterval boundaries. subinterval boundaries, bestie. ๐ŸŒธ
  • setLOBPCGBlockSize(bs) โ€” sets the block size of the LOBPCG method. LOBPCG block size. ๐Ÿซถ
  • setLOBPCGLocking(lock) โ€” toggles between locking and non-locking (LOBPCG method). lock toggle. ๐Ÿ’…
  • setLOBPCGRestart(restart) โ€” sets the restart parameter for the LOBPCG method. restart param. โญ
  • setLanczosReorthogType(reorthog) โ€” sets the type of reorthogonalization used during the Lanczos iteration. reorthog type, periodt. ๐Ÿ‘‘
  • setLeftInitialSpace(space) โ€” literally tells the solver where to start iterating from on the left side ๐Ÿ’… give it an initial space and it'll use that as its starting vibe for the eigensolver.
  • setLyapIIRanks([rkc, rkl]) โ€” sets the ranks <italic>rkc</italic> and <italic>rkl</italic> used when solving the Lyapunov equation โœจ both are optional, defaults live in the docs.
  • setMonitor(monitor[, args, kargs]) โ€” appends a monitor function to the list of monitors ๐Ÿ‘‘ pass the function, plus optional args/kargs, and it joins the monitoring lineup.
  • setOperators(A[, B]) โ€” sets the matrices associated with the eigenvalue problem ๐ŸŽ€ A is the main one, B is optional.
  • setOptionsPrefix([prefix]) โ€” sets the prefix used for searching for all EPS options in the database ๐ŸŒธ prefix is optional, but it's how you namespace your options, iykyk.
  • setPowerShiftType(shift) โ€” sets the type of shifts used during the power iteration โญ shift tells it which shift flavour to run.
  • setProblemType(problem_type) โ€” sets the type of the eigenvalue problem ๐Ÿฆ‹ pass in problem_type and it knows what kind of eigenproblem it's solving.
  • setPurify([purify]) โ€” set (or toggle) eigenvector purification ๐Ÿ’œ optional purify, does what it says on the tin.
  • setRG(rg) โ€” attaches a region object to the eigensolver ๐ŸŒˆ rg is the region, and now the solver knows where to look.
  • setRQCGReset(nrest) โ€” sets the reset parameter of the RQCG iteration ๐Ÿ”ฅ nrest, that's it.
  • setST(st) โ€” hands the eigensolver a spectral transformation object ๐Ÿ’– st is that object, and it's giving transformation energy.
  • setStoppingTest(stopping[, args, kargs]) โ€” sets a function that decides when to stop the outer iteration of the eigensolver ๐Ÿ‘‘ stopping is the function, plus optional args and kargs.
  • setTarget(target) โ€” sets the value of the target ๐ŸŽฏ target = the value. That's the whole thing.
  • setThreshold(thres[, rel]) โ€” sets the threshold used in the threshold stopping test โญ thres is required, rel is optional.
  • setTolerances([tol, max_it]) โ€” set the tolerance and max. ๐Ÿ’€ both tol and max_it are optional; this is where you tune how picky the solver is and how many iterations it gets.
  • setTrackAll(trackall) โ€” sets whether the solver must compute the residual of all approximate eigenpairs ๐Ÿฆ‹ trackall on means yes, track everything.
  • setTrueResidual(trueres) โ€” sets whether the solver must compute the true residual explicitly or not ๐Ÿ™ˆ trueres toggles it.
  • setTwoSided(twosided) โ€” set to use a two-sided variant that also computes left eigenvectors โœจ twosided โ€” left eigenvectors get computed too, extra credit.
  • setType(eps_type) โ€” sets the particular solver to be used in the EPS object ๐Ÿ’… eps_type picks your solver flavour, this is a big one, bestie.
  • setUp() โ€” sets up all the internal data structures ๐Ÿ”ง no arguments, just get everything ready.
  • setWhichEigenpairs(which) โ€” sets which portion of the spectrum is to be sought ๐Ÿ‘‘ which decides what part of the spectrum you're chasing.
  • solve() โ€” solves the eigensystem ๐ŸŒŸ no args, this is the main event.
  • updateKrylovSchurSubcommMats([s, a, Au, t, ...]) โ€” updates the eigenproblem matrices stored internally in the communicator ๐Ÿ”ฅ takes optional s, a, Au, t, and more (...).
  • valuesView([viewer]) โ€” displays the computed eigenvalues in a viewer ๐ŸŒธ optional viewer.
  • vectorsView([viewer]) โ€” outputs the computed eigenvectors to a viewer ๐ŸŽ€ optional viewer.
  • view([viewer]) โ€” prints the EPS data structure ๐Ÿ’œ optional viewer, pure introspection vibes.

๐Ÿ’… Attributes Summary ๐Ÿ’…

okay bestie, before we get into the methods, here's the whole vibe-board of what an EPS object is carrying around, fr fr:

  • bv โ€” the basis vectors (BV) object that's associated. it's giving "the squad that holds the vectors".
  • ds โ€” the direct solver (DS) object that's associated.
  • extraction โ€” the type of extraction technique to be employed. โœจ
  • max_it โ€” the maximum iteration count. that's the ceiling, periodt.
  • problem_type โ€” the type of the eigenvalue problem.
  • purify โ€” eigenvector purification. yes she cleans up ๐Ÿ’…
  • rg โ€” the region (RG) object that's associated.
  • st โ€” the spectral transformation (ST) object that's associated.
  • target โ€” the value of the target. ๐ŸŽฏ
  • tol โ€” the tolerance.
  • track_all โ€” compute the residual norm of all approximate eigenpairs.
  • true_residual โ€” compute the true residual explicitly. no cap.
  • two_sided โ€” two-sided that also computes left eigenvectors.
  • which โ€” the portion of the spectrum to be sought. ๐Ÿ‘‘

๐Ÿ› ๏ธ Methods Documentation ๐Ÿ› ๏ธ

appendOptionsPrefix(prefix=None)

Append to the prefix used for searching for all EPS options in the database. Logically collective, so everybody's in on it together ๐Ÿซถ

Parameters

  • prefix (str | None) โ€“ the prefix string to prepend to all EPS option requests.

Return type

None

See also:

setOptionsPrefix, getOptionsPrefix, EPSAppendOptionsPrefix

:sources: Source code at slepc4py/SLEPc/EPS.pyx:515

cancelMonitor()

Clear all monitors for an EPS object. wipe the slate, bestie ๐Ÿงฝ

Logically collective.

See also:

EPSMonitorCancel

:sources: Source code at slepc4py/SLEPc/EPS.pyx:1862

Return type

None

computeError(i, etype=None)

Compute the error associated with the i-th computed eigenpair.

Collective.

Like, literally: compute the error (based on the residual norm) associated with the i-th computed eigenpair.

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 \|Ax-\lambda Bx\|_2 where \lambda is the eigenvalue and x is the eigenvector.

Return type

float

Notes

The index i should be a value between 0 and nconv-1 (see getConverged()). don't be out here indexing past the edge, bestie ๐Ÿ˜ญ

If the computation of left eigenvectors was enabled with setTwoSided(), then the error will be computed using the maximum of the value above and the left residual norm \|y^*A-\lambda y^*B\|_2, where y is the approximate left eigenvector.

See also:

getErrorEstimate, setTwoSided, EPSComputeError

:sources: Source code at slepc4py/SLEPc/EPS.pyx:2216

create(comm=None)

Create the EPS object. making her exist โœจ

Collective.

Parameters

  • comm (Comm | None) โ€“ MPI communicator; if not provided, it defaults to all processes.

Return type

Self

See also:

EPSCreate

:sources: Source code at slepc4py/SLEPc/EPS.pyx:398

destroy()

Destroy the EPS object. she's done, she served her purpose, we love her ๐Ÿ’–

Collective.

See also:

EPSDestroy

:sources: Source code at slepc4py/SLEPc/EPS.pyx:372

Return type

Self

errorView(etype=None, viewer=None)

Display the errors associated with the computed solution. show us the receipts ๐Ÿ“Š

Collective.

Display the errors and the eigenvalues.

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 eigenpairs and prints the eigenvalues if all of them are below the requested tolerance. If the viewer has format ASCII_INFO_DETAIL then a table with eigenvalues and corresponding errors is printed. a whole table?? she's organized fr.

See also:

solve, valuesView, vectorsView, EPSErrorView

:sources: Source code at slepc4py/SLEPc/EPS.pyx:2259

getArbitrarySelection()

Get the arbitrary selection function.

Not collective.

  • ### getArbitrarySelection() โ€” Returns the arbitrary selection function.

Returns: the arbitrary selection function.

Return type: EPSArbitraryFunction

See also: setArbitrarySelection

:sources: Source code at slepc4py/SLEPc/EPS.pyx:1756

  • ### getArnoldiDelayed() โ€” Get the type of reorthogonalization used during the Arnoldi iteration.

Not collective.

Returns: True if delayed reorthogonalization is to be used.

Return type: bool

See also: setArnoldiDelayed, EPSArnoldiGetDelayed

:sources: Source code at slepc4py/SLEPc/EPS.pyx:2414

  • ### getBV() โ€” Get the basis vectors object associated to the eigensolver.

Not collective, bestie, so like, everyone's on their own vibe ๐Ÿ’…

Returns: the basis vectors context.

Return type: BV

See also: setBV, EPSGetBV

:sources: Source code at slepc4py/SLEPc/EPS.pyx:1409

  • ### getBalance() โ€” Get the balancing type used by the EPS, and the associated parameters.

Not collective โœจ

Returns:

  • balance (Balance) โ€” the balancing method.
  • iterations (int) โ€” number of iterations of the balancing algorithm.
  • cutoff (float) โ€” cutoff value.

Return type: tuple[Balance, int, float]

See also: setBalance, EPSGetBalance

:sources: Source code at slepc4py/SLEPc/EPS.pyx:695

  • ### getCISSExtraction() โ€” Get the extraction technique used in the CISS solver.

not collective ๐Ÿซถ

Returns: the extraction technique.

Return type: CISSExtraction

See also: setCISSExtraction, EPSCISSGetExtraction

:sources: Source code at slepc4py/SLEPc/EPS.pyx:3960

  • ### getCISSKSPs() โ€” Get the array of linear solver objects associated with the CISS solver.

not collective ๐ŸŒธ

Returns: the linear solver objects.

Return type: list of petsc4py.PETSc.KSP

Notes

okay so the number of petsc4py.PETSc.KSP solvers is literally equal to the number of integration points divided by the number of partitions periodt. This value gets halved when you have real matrices with a region centered at the real axis ๐Ÿค“

See also: setCISSSizes, EPSCISSGetKSPs

:sources: Source code at slepc4py/SLEPc/EPS.pyx:4241

  • ### getCISSQuadRule() โ€” Get the quadrature rule used in the CISS solver.

not collective ๐Ÿ’–

Returns: the quadrature rule.

Return type: CISSQuadRule

See also: setCISSQuadRule, EPSCISSGetQuadRule

:sources: Source code at slepc4py/SLEPc/EPS.pyx:3997

  • ### getCISSRefinement() โ€” Get the values of various refinement parameters in the CISS solver.

not collective โœจ

Returns:

  • inner (int) โ€” number of iterative refinement iterations (inner loop).
  • blsize (int) โ€” number of iterative refinement iterations (blocksize loop).

Return type: tuple[int, int]

See also: setCISSRefinement, EPSCISSGetRefinement

:sources: Source code at slepc4py/SLEPc/EPS.pyx:4172

  • ### getCISSSizes() โ€” Get the values of various size parameters in the CISS solver.

not collective ๐ŸŽ€

Returns:

  • ip (int) โ€” number of integration points.
  • bs (int) โ€” block size.
  • ms (int) โ€” moment size.
  • npart (int) โ€” number of partitions when splitting the communicator.
  • bsmax (int) โ€” maximum block size.
  • realmats (bool) โ€” True if A and B are real.

Return type: tuple[int, int, int, int, int, bool]

See also: setCISSSizes, EPSCISSGetSizes

:sources: Source code at slepc4py/SLEPc/EPS.pyx:4070

  • ### getCISSThreshold() โ€” Get the values of various threshold parameters in the CISS solver.

not collective ๐Ÿฆ‹

Returns:

  • delta (float) โ€” threshold for numerical rank.
  • spur (float) โ€” spurious threshold (to discard spurious eigenpairs.
yes bestie, that parenthesis in the original is missing its closing ) and we are not fixing it, it's canon now ๐Ÿ˜ญ the facts stay exactly as they are.

Return type: tuple[float, float]

See also: setCISSThreshold, EPSCISSGetThreshold

:sources: Source code at slepc4py/SLEPc/EPS.pyx:4127

  • ### getCISSUseST() โ€” Get the flag indicating the use of the ST object in the CISS solver.

not collective ๐Ÿ’œ

Returns: whether to use the ST object or not.

Return type: bool

See also: setCISSUseST, EPSCISSGetUseST

:sources: Source code at slepc4py/SLEPc/EPS.pyx:4222

  • ### getConverged() โ€” Get the number of converged eigenpairs.

not collective โญ

Returns: nconv โ€” number of converged eigenpairs.

Return type: int

Notes

this function should be called after solve() has finished. like fr fr, don't come knocking before the party's over ๐Ÿซถ

:sources: Source code at slepc4py/SLEPc/EPS.pyx:1409

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

See also: setDimensions, solve, getEigenpair, EPSGetConverged (https://slepc.upv.es/release/manualpages/EPS/EPSGetConverged.html)

:sources:Source code at slepc4py/SLEPc/EPS.pyx:1962 <slepc4py/SLEPc/EPS.pyx#L1962>

getConvergedReason()

okay bestie, this is the one that tells you why your solve() iteration decided to stop. Like, was it a slay or was it a flop? ๐Ÿ’…

Not collective.

Returns Negative value indicates diverged, positive value converged.

Return type ConvergedReason <#slepc4py.SLEPc.EPS.ConvergedReason>

See also: setTolerances, solve, EPSGetConvergedReason (https://slepc.upv.es/release/manualpages/EPS/EPSGetConvergedReason.html)

:sources:Source code at slepc4py/SLEPc/EPS.pyx:1943 <slepc4py/SLEPc/EPS.pyx#L1943>

getConvergenceTest()

Get how 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 <#slepc4py.SLEPc.EPS.Conv>

See also: setConvergenceTest, EPSGetConvergenceTest (https://slepc.upv.es/release/manualpages/EPS/EPSGetConvergenceTest.html)

:sources:Source code at slepc4py/SLEPc/EPS.pyx:1179 <slepc4py/SLEPc/EPS.pyx#L1179>

getDS()

Get the direct solver associated to the eigensolver. It's giving โœจmain characterโœจ but for linear algebra. ๐ŸŽ€

Not collective.

Returns The direct solver context.

Return type DS <#slepc4py.SLEPc.DS>

See also: setDS, EPSGetDS (https://slepc.upv.es/release/manualpages/EPS/EPSGetDS.html)

:sources:Source code at slepc4py/SLEPc/EPS.pyx:1446 <slepc4py/SLEPc/EPS.pyx#L1446>

getDimensions()

Get number of eigenvalues to compute and the dimension of the subspace. Basically the tea on how big this whole thing is. ๐Ÿซถ

Not collective.

Returns

Return type tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]

See also: setDimensions, EPSGetDimensions (https://slepc.upv.es/release/manualpages/EPS/EPSGetDimensions.html)

:sources:Source code at slepc4py/SLEPc/EPS.pyx:1292 <slepc4py/SLEPc/EPS.pyx#L1292>

getEigenpair(i, Vr=None, Vi=None)

Get the i-th solution of the eigenproblem as computed by solve(). ๐ŸŒธ

Collective.

The solution consists of both the eigenvalue and the eigenvector. yeah she's a package deal, no splitting them up bestie. ๐Ÿ’–

Parameters

Returns e โ€“ The computed eigenvalue. It will be a real variable in case of a Hermitian or generalized Hermitian eigenproblem. Otherwise it will be a complex variable (possibly with zero imaginary part).

Return type Scalar <#slepc4py.typing.Scalar>

Notes

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

The 2-norm of the eigenvector is one unless the problem is generalized Hermitian. In this case the eigenvector is normalized with respect to the norm defined by the B matrix.

lowkey important: if you go out of that 0 to nconv-1 range, you're on your own bestie, that's not a vibe. ๐Ÿ’€

See also: solve, getConverged, setWhichEigenpairs, EPSGetEigenpair (https://slepc.upv.es/release/manualpages/EPS/EPSGetEigenpair.html)

:sources:Source code at slepc4py/SLEPc/EPS.pyx:2093 <slepc4py/SLEPc/EPS.pyx#L2093>

getEigenvalue(i)

Get the i-th eigenvalue as computed by solve(). Just the eigenvalue tho, no vector, she's independent. ๐Ÿ‘‘

Not collective.

Parameters i (int <https://docs.python.org/3/library/functions.html#int>) โ€“ Index of the solution to be obtained.

Returns The computed eigenvalue. It will be a real variable in case of a Hermitian or generalized Hermitian eigenproblem, and in some structured eigenvalue problems. Otherwise it will be a complex variable (possibly with zero imaginary part).

Return type Scalar <#slepc4py.typing.Scalar>

Notes

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

See also: getConverged, setWhichEigenpairs, getEigenpair, EPSGetEigenvalue (https://slepc.upv.es/release/manualpages/EPS/EPSGetEigenvalue.html)

:sources:Source code at slepc4py/SLEPc/EPS.pyx:1988 <slepc4py/SLEPc/EPS.pyx#L1988>

getEigenvalueComparison()

Get the eigenvalue comparison function. yes bestie, the thing that decides the order of everything. it's giving referee energy. ๐Ÿงš

Not collective.

Returns The eigenvalue comparison function.

Return type EPSEigenvalueComparison <#slepc4py.typing.EPSEigenvalueComparison>

See also: setEigenvalueComparison

:sources:Source code at slepc4py/SLEPc/EPS.pyx:1803 <slepc4py/SLEPc/EPS.pyx#L1803>

getEigenvector(i, Vr=None, Vi=None)

Get the i-th right eigenvector as computed by solve(). ๐ŸŒˆ

Collective.

Parameters

Return type None <https://docs.python.org/3/library/constants.html#None>

Notes

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

The 2-norm of the eigenvector is one unless the problem is generalized Hermitian. In this case the eigenvector is normalized with respect to the norm defined by the B matrix.

See also: getConverged, setWhichEigenpairs, getEigenpair, EPSGetEigenvector (https://slepc.upv.es/release/manualpages/EPS/EPSGetEigenvector.html)

:sources:Source code at slepc4py/SLEPc/EPS.pyx:2027 <slepc4py/SLEPc/EPS.pyx#L2027>

getErrorEstimate(i)

Get the error estimate associated to the i-th computed eigenpair. like a lil vibe check on how wrong you are. ๐Ÿ“

Not collective.

Parameters i (int <https://docs.python.org/3/library/functions.html#int>) โ€“ Index of the solution to be considered.

Returns Error estimate.

Return type float <https://docs.python.org/3/library/functions.html#float>

Notes

This is the error estimate used internally by the eigensolver. The actual error bound can be computed with computeError().

ngl these are two different things bestie: this one is the internal estimate, and if you want the actual error bound, go hit up computeError(). don't mix them up. ๐Ÿ™ˆ

See also: computeError, EPSGetErrorEstimate โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGetErrorEstimate.html

Source: slepc4py/SLEPc/EPS.pyx:2187

getExtraction()

Bestie, this one grabs the extraction type that your EPS object is currently vibing with. โœจ

Not collective. (so every process better be on the same page, but nobody's chatting about it)

Returns: the method of extraction โ€” return type Extraction.

See also: setExtraction, EPSGetExtraction โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGetExtraction.html

Source: slepc4py/SLEPc/EPS.pyx:770

getGDBOrth()

Get the orthogonalization used in the search subspace. ๐Ÿฆ‹

Not collective.

Specifically: it gets the orthogonalization used in the search subspace in case of generalized Hermitian problems.

Returns: whether to B-orthogonalize the search subspace โ€” return type bool.

See also: setGDBOrth, EPSGDGetBOrth โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGDGetBOrth.html

Source: slepc4py/SLEPc/EPS.pyx:3337

getGDBlockSize()

Get the number of vectors to be added to the searching space. ๐Ÿ’–

Not collective.

Okay so it's the number of vectors getting added to the searching space in every iteration โ€” yes, every single one, no skipping.

Returns: the number of vectors added to the search space in every iteration โ€” return type int.

See also: setGDBlockSize, EPSGDGetBlockSize โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGDGetBlockSize.html

Source: slepc4py/SLEPc/EPS.pyx:3196

getGDDoubleExpansion()

Get a flag indicating whether the double expansion variant is active. ๐ŸŒˆ

Not collective.

Translation: it tells you whether the double expansion variant has actually been activated or not. Lowkey a yes/no queen.

Returns: True if using double expansion โ€” return type bool.

See also: setGDDoubleExpansion, EPSGDGetDoubleExpansion โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGDGetDoubleExpansion.html

Source: slepc4py/SLEPc/EPS.pyx:3385

getGDInitialSize()

Get the initial size of the searching space. ๐ŸŽ€

Not collective.

Returns: the number of vectors of the initial searching subspace โ€” return type int.

See also: setGDInitialSize, EPSGDGetInitialSize โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGDGetInitialSize.html

Source: slepc4py/SLEPc/EPS.pyx:3297

getGDKrylovStart()

Get a flag indicating if the search subspace is started with a Krylov basis. ๐Ÿ’…

Not collective.

Returns: True if starting the search subspace with a Krylov basis โ€” return type bool.

See also: setGDKrylovStart, EPSGDGetKrylovStart โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGDGetKrylovStart.html

Source: slepc4py/SLEPc/EPS.pyx:3156

getGDRestart()

Get the number of vectors of the search space after restart. โญ

Not collective.

So it hands you both the number of vectors of the search space after restart and the number of vectors saved from the previous iteration. Two-for-one, iconic.

Returns:

  • minv (int) โ€” the number of vectors of the search subspace after restart.
  • plusk (int) โ€” the number of vectors saved from the previous iteration.

Return type: tuple[int, int]

See also: setGDRestart, EPSGDGetRestart โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGDGetRestart.html

Source: slepc4py/SLEPc/EPS.pyx:3244

getInterval()

Get the computational interval for spectrum slicing. ๐Ÿ“

Not collective.

Returns:

  • inta (float) โ€” the left end of the interval.
  • intb (float) โ€” the right end of the interval.

Return type: tuple[float, float]

Notes

If the interval was not set by the user, then zeros are returned. So don't be out here acting surprised when you get a couple of 0.0s, okay? ๐Ÿ˜ญ

See also: setInterval, EPSGetInterval โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGetInterval.html

Source: slepc4py/SLEPc/EPS.pyx:974

getInvariantSubspace()

Get an orthonormal basis of the computed invariant subspace. ๐Ÿ‘‘

Collective. (everyone's in on this one, no solo missions)

Returns: the basis of the invariant subspace โ€” return type list of petsc4py.PETSc.Vec.

Notes

This function should be called after solve() has finished. Do not jump the gun, bestie, the timing is the whole plot. ๐Ÿ’€

The returned vectors span an invariant subspace associated with the computed eigenvalues. An invariant subspace X of A satisfies A x \in X, for all x \in X (a similar definition applies for generalized eigenproblems).

See also: getEigenpair, getConverged, solve, EPSGetInvariantSubspace โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGetInvariantSubspace.html

Source: slepc4py/SLEPc/EPS.pyx:2143

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. So like โ€” a little progress bar for your soul.

Returns: the iteration number โ€” return type int.

See also: getConvergedReason, setTolerances, EPSGetIterationNumber โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGetIterationNumber.html

Source: slepc4py/SLEPc/EPS.pyx:1921

getJDBOrth()

Get the orthogonalization used in the search subspace. ๐Ÿงš

Not collective.

Get the orthogonalization used in the search subspace in case of generalized Hermitian problems.

Returns: whether to B-orthogonalize the search subspace โ€” return type bool.

See also: setJDBOrth, EPSJDGetBOrth โ€” https://slepc.upv.es/release/manualpages/EPS/EPSJDGetBOrth.html

Source: slepc4py/SLEPc/EPS.pyx:3696

getJDBlockSize()

Get the number of vectors to be added to the searching space. ๐ŸŒธ

Not collective.

Get the number of vectors to be added to the searching space in every iteration.

Returns: the number of vectors added to the search space in every iteration โ€” return type int.

See also: setJDBlockSize, EPSJDGetBlockSize โ€” https://slepc.upv.es/release/manualpages/EPS/EPSJDGetBlockSize.html

Source: slepc4py/SLEPc/EPS.pyx:3467

getJDConstCorrectionTol()

Get the flag indicating if the dynamic stopping is being used. ๐Ÿ™ˆ

Not collective.

  • Returns โ€” True if the dynamic stopping criterion is not being used. bestie if you're not running a dynamic stop, this one's just gonna nod at you ๐Ÿซถ
  • getJDFix() โ€” gets the threshold for changing the target in the correction equation. like, how stubborn is the target allowed to be before we swap it ๐ŸŽฏ
  • getJDInitialSize() โ€” gets the initial size of the searching space. the baby subspace, before it grows up ๐ŸŒฑ
  • getJDKrylovStart() โ€” gets a flag saying whether the search subspace gets started with a Krylov basis. yes queen, start it the Krylov way โœจ
  • getJDRestart() โ€” gets the number of vectors of the search space after restart. ๐Ÿ’…
    • Not collective.
    • also, like, gets the number of vectors of the search space after restart and the number of vectors saved from the previous iteration. two for one, we love a bundle ๐ŸŽ€
    • Returns
      • minv (int) โ€” the number of vectors of the search subspace after restart.
      • plusk (int) โ€” the number of vectors saved from the previous iteration.
    • Return type โ€” tuple[int, int]
    • See also: setJDRestart, EPSJDGetRestart (https://slepc.upv.es/release/manualpages/EPS/EPSJDGetRestart.html)
    • :sources: Source code at slepc4py/SLEPc/EPS.pyx:3515
  • getKrylovSchurBSEType() โ€” gets the method used for BSE structured eigenproblems (Krylov-Schur). crown behavior for the BSE girlies ๐Ÿ‘‘
  • getKrylovSchurDetectZeros() โ€” gets the flag that enforces zero detection in spectrum slicing. keeping an eye out for zeros like a suspicious bestie ๐Ÿ‘€
  • getKrylovSchurDimensions() โ€” gets the dimensions used for each subsolve step (spectrum slicing). the measurements, the fit check ๐Ÿ“
    • Not collective.
    • Returns
      • nev (int) โ€” number of eigenvalues 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: setKrylovSchurDimensions, EPSKrylovSchurGetDimensions (https://slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurGetDimensions.html)
    • :sources: Source code at slepc4py/SLEPc/EPS.pyx:2755
  • getKrylovSchurInertias() โ€” gets the values of the shifts and their corresponding inertias. ๐Ÿ”ฅ
    • Not collective.
    • like, gets the values of the shifts and their corresponding inertias in case of doing spectrum slicing for a computational interval.
    • Returns
      • shifts (ArrayReal, aka #slepc4py.typing.ArrayReal) โ€” the values of the shifts used internally in the solver.
      • inertias (ArrayInt, aka #slepc4py.typing.ArrayInt) โ€” the values of the inertia in each shift.
    • Return type โ€” tuple[ArrayReal, ArrayInt]
    • Notes ๐Ÿ“
      • This call makes sense only for spectrum slicing runs, that is, when an interval has been given with setInterval() and SINVERT (#slepc4py.SLEPc.ST.Type.SINVERT) is set.
      • If called after solve(), all shifts used internally by the solver are returned (including both endpoints and any intermediate ones). If called before solve() and after setUp() then only the information of the endpoints of subintervals is available.
    • See also: setInterval, setKrylovSchurSubintervals, EPSKrylovSchurGetInertias (https://slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurGetInertias.html)
    • :sources: Source code at slepc4py/SLEPc/EPS.pyx:3053
  • getKrylovSchurKSP() โ€” gets the linear solver object associated with the internal EPS object. ๐Ÿงš
    • Collective.
    • gets the linear solver object associated with the internal EPS object in case of doing spectrum slicing for a computational interval.
    • Returns โ€” the linear solver object.
    • Return type โ€” petsc4py.PETSc.KSP (https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.KSP.html#petsc4py.PETSc.KSP)
    • Notes ๐Ÿ“
      • This call makes sense only for spectrum slicing runs, that is, when an interval has been given with setInterval() and SINVERT (#slepc4py.SLEPc.ST.Type.SINVERT) is set.
      • When invoked to compute all eigenvalues in an interval with spectrum slicing, KRYLOVSCHUR (#slepc4py.SLEPc.EPS.Type.KRYLOVSCHUR) creates another EPS object internally that is used to compute eigenvalues by chunks near selected shifts. This function allows access to the KSP object associated to this internal EPS object.
      • In case of having more than one partition, the returned KSP will be different in MPI processes belonging to different partitions. Hence, if required, setKrylovSchurPartitions() must be called BEFORE this function. โš ๏ธ order matters, do not play with her
    • See also: setInterval, setKrylovSchurPartitions, EPSKrylovSchurGetKSP (https://slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurGetKSP.html)
    • :sources: Source code at slepc4py/SLEPc/EPS.pyx:3097
  • getKrylovSchurLocking() โ€” gets the locking flag used in the Krylov-Schur method. locked in, literally ๐Ÿ”’
    • Not collective.
    • Returns โ€” the locking flag.
    • Return type โ€” bool

See also: setKrylovSchurLocking, EPSKrylovSchurGetLocking โ€” https://slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurGetLocking.html

Source code at slepc4py/SLEPc/EPS.pyx:2589 (slepc4py/SLEPc/EPS.pyx#L2589) ๐Ÿซถ

getKrylovSchurPartitions() ๐Ÿ’…

okay so bestie, this one gets you the number of partitions of the communicator โ€” aka spectrum slicing, the iconic split-the-work move. โœจ

Not collective. (so every process can just ask, no gossip needed ๐Ÿซถ)

Returns

  • The number of partitions.

Return type

int โ€” yes that's Python's own int (https://docs.python.org/3/library/functions.html#int)

See also: setKrylovSchurPartitions, EPSKrylovSchurGetPartitions โ€” https://slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurGetPartitions.html

Source code at slepc4py/SLEPc/EPS.pyx:2643 (slepc4py/SLEPc/EPS.pyx#L2643) ๐Ÿ‘‘

getKrylovSchurRestart() ๐ŸŽ€

Get the restart parameter used in the Krylov-Schur method. she's the one deciding how much you keep when you hit reset, no cap.

Not collective.

Returns

  • The number of vectors to be kept at restart.

Return type

float (https://docs.python.org/3/library/functions.html#float) โ€” a float, even though it's literally counting vectors, we don't make the rules ๐ŸŒธ

See also: setKrylovSchurRestart, EPSKrylovSchurGetRestart โ€” https://slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurGetRestart.html

Source code at slepc4py/SLEPc/EPS.pyx:2545 (slepc4py/SLEPc/EPS.pyx#L2545) ๐Ÿ’–

getKrylovSchurSubcommInfo() ๐ŸŒˆ

Get the tea related to the case of doing spectrum slicing โ€” specifically, spectrum slicing for a computational interval with multiple communicators. it's giving "who am I, and how many eigenvalues did my little squad find" energy.

Collective on the subcommunicator.

Returns

Return type

tuple[int, int, Vec] (https://docs.python.org/3/library/stdtypes.html#tuple, https://docs.python.org/3/library/functions.html#int, https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Vec.html#petsc4py.PETSc.Vec)

Notes

This call makes sense only for spectrum slicing runs, that is, when an interval has been given with setInterval() and SINVERT is set. periodt. ๐Ÿ’…

See also: getKrylovSchurSubcommPairs, EPSKrylovSchurGetSubcommInfo โ€” https://slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurGetSubcommInfo.html

Source code at slepc4py/SLEPc/EPS.pyx:2780 (slepc4py/SLEPc/EPS.pyx#L2780) ๐Ÿฆ‹

getKrylovSchurSubcommMats() ๐Ÿ”ฅ

Get the eigenproblem matrices stored in the subcommunicator โ€” like internally, in the subcommunicator that you, bestie, happen to belong to.

Collective on the subcommunicator.

Returns

Return type

tuple[Mat, Mat] | tuple[Mat, None] (https://docs.python.org/3/library/stdtypes.html#tuple, https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat, https://docs.python.org/3/library/constants.html#None)

Notes

This call makes sense only for spectrum slicing runs โ€” meaning an interval was given with setInterval() and SINVERT is set. And it's only relevant when the number of partitions (setKrylovSchurPartitions()) is larger than one.

This is the analog of getOperators(), except it hands back the matrices distributed differently โ€” in the subcommunicator rather than in the parent communicator. same vibes, different zip code tbh.

These matrices should not be modified by the user. hands off, bestie, no cap. ๐Ÿ™ˆ

See also: setInterval, setKrylovSchurPartitions, EPSKrylovSchurGetSubcommMats โ€” https://slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurGetSubcommMats.html

Source code at slepc4py/SLEPc/EPS.pyx:2858 (slepc4py/SLEPc/EPS.pyx#L2858) ๐Ÿ‘‘

getKrylovSchurSubcommPairs(i, v=None) โœจ

Get the i-th eigenpair stored in the multi-communicator of the process.

Collective on the subcommunicator (if v is given).

Get the i-th eigenpair stored internally in the multi-communicator to which the calling process belongs. lowkey iconic that you can just ask for it.

Parameters

Returns

  • The computed eigenvalue.

Return type

Scalar (#slepc4py.typing.Scalar)

Notes

This call makes sense only for spectrum slicing runs, that is, when an interval has been given with setInterval() and SINVERT is set. And it's only relevant when the number of partitions (setKrylovSchurPartitions()) is larger than one.

Argument v must be a valid Vec object, created by calling getKrylovSchurSubcommInfo(). ๐Ÿซถ

The index i should be a value between 0 and n-1, where n is the number of vectors in the local subinterval โ€” see getKrylovSchurSubcommInfo(). don't go off-script with the index, she will not forgive you ๐Ÿ’€

See also: getKrylovSchurSubcommMats, EPSKrylovSchurGetSubcommPairs โ€” https://slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurGetSubcommPairs.html

Source code at slepc4py/SLEPc/EPS.pyx:2814 (slepc4py/SLEPc/EPS.pyx#L2814) ๐ŸŒธ

getKrylovSchurSubintervals() ๐Ÿงš

Get the points that delimit the subintervals.

Not collective.

Get the points that delimit the subintervals used in spectrum slicing with several partitions. it's giving "where do the little slices start and end" ๐ŸŽ€

Returns

  • Real values specifying subintervals.

Return type

ArrayReal (#slepc4py.typing.ArrayReal)

Notes

This call makes sense only for spectrum slicing runs, that is, when an interval has been given with setInterval() and SINVERT is set.

If the user passed values with setKrylovSchurSubintervals(), then the same values are returned here. Otherwise, the values computed internally are obtained. either way you get answers, we love a flexible queen ๐Ÿ’…

See also: setKrylovSchurSubintervals, EPSKrylovSchurGetSubintervals โ€” https://slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurGetSubintervals.html

Source code at slepc4py/SLEPc/EPS.pyx:3015 (slepc4py/SLEPc/EPS.pyx#L3015) ๐ŸŒˆ

getLOBPCGBlockSize() ๐Ÿ’–

Get the block size used in the LOBPCG method. yes bestie, block size, as in how chunky she goes.

Not collective.

Returns

  • The block size.

Return type

int (https://docs.python.org/3/library/functions.html#int)

See also: setLOBPCGBlockSize, EPSLOBPCGGetBlockSize โ€” https://slepc.upv.es/release/manualpages/EPS/EPSLOBPCGGetBlockSize.html

Source code at slepc4py/SLEPc/EPS.pyx:3780 (slepc4py/SLEPc/EPS.pyx#L3780) ๐Ÿ”ฅ

getLOBPCGLocking() ๐Ÿฆ‹

Get the locking flag used in the LOBPCG method. locking on or locking off, that is the question.

Not collective.

Returns

  • The locking flag.

Return type

bool (https://docs.python.org/3/library/functions.html#bool)

See also: setLOBPCGLocking, EPSLOBPCGGetLocking โ€” https://slepc.upv.es/release/manualpages/EPS/EPSLOBPCGGetLocking.html

getLOBPCGRestart()

Grab the restart parameter that the LOBPCG method is using rn. โœจ

Not collective. (so like, everyone doesn't need to call it together, okay?)

Returns: the restart parameter.

Return type: float

See also: setLOBPCGRestart, EPSLOBPCGGetRestart <https://slepc.upv.es/release/manualpages/EPS/EPSLOBPCGGetRestart.html>

:source: Source code at slepc4py/SLEPc/EPS.pyx:3824 <slepc4py/SLEPc/EPS.pyx#L3824>

getLanczosReorthogType()

Get the type of reorthogonalization being used during the Lanczos iteration. ๐ŸŒ€

Not collective.

Returns: the type of reorthogonalization.

Return type: LanczosReorthogType <#slepc4py.SLEPc.EPS.LanczosReorthogType>

See also: setLanczosReorthogType, EPSLanczosGetReorthog <https://slepc.upv.es/release/manualpages/EPS/EPSLanczosGetReorthog.html>

:source: Source code at slepc4py/SLEPc/EPS.pyx:2456 <slepc4py/SLEPc/EPS.pyx#L2456>

getLeftEigenvector(i, Wr=None, Wi=None)

Bestie, this one hands you the i-th left eigenvector, exactly like solve() computed it. ๐Ÿ’œ

Collective.

Parameters:

  • i (int) โ€” index of the solution you wanna get.
  • Wr (Vec | None) โ€” placeholder for the returned left eigenvector (real part).
  • Wi (Vec | None) โ€” placeholder for the returned left eigenvector (imaginary part).

Return type: None

Notes

That i has to be a value between 0 and nconv-1 (peep getConverged()). Eigensolutions get indexed according to the ordering criterion you set up with setWhichEigenpairs().

Also โ€” left eigenvectors are only available if you turned on the twosided flag with setTwoSided(). No flag, no left vectors, that's the deal. ๐Ÿ™ˆ

See also: getConverged, setWhichEigenpairs, getEigenpair, EPSGetLeftEigenvector <https://slepc.upv.es/release/manualpages/EPS/EPSGetLeftEigenvector.html>

:source: Source code at slepc4py/SLEPc/EPS.pyx:2061 <slepc4py/SLEPc/EPS.pyx#L2061>

getLyapIIRanks()

Get the rank values that were used for the Lyapunov step. ๐ŸŽ€

Not collective.

Returns:

  • rkc (int) โ€” the compressed rank.
  • rkl (int) โ€” the Lyapunov rank.

Return type: tuple[int, int]

See also: setLyapIIRanks, EPSLyapIIGetRanks <https://slepc.upv.es/release/manualpages/EPS/EPSLyapIIGetRanks.html>

:source: Source code at slepc4py/SLEPc/EPS.pyx:3918 <slepc4py/SLEPc/EPS.pyx#L3918>

getMonitor()

Get the list of monitor functions. ๐Ÿ‘€ Basically "who's watching this solve".

Not collective.

Returns: the list of monitor functions.

Return type: EPSMonitorFunction <#slepc4py.typing.EPSMonitorFunction>

See also: setMonitor

:source: Source code at slepc4py/SLEPc/EPS.pyx:1845 <slepc4py/SLEPc/EPS.pyx#L1845>

getOperators()

Get the matrices that are associated with the eigenvalue problem. ๐Ÿงฎ

Collective.

Returns:

  • A (petsc4py.PETSc.Mat) โ€” the matrix associated with the eigensystem.
  • B (petsc4py.PETSc.Mat) โ€” the second matrix, in the case of generalized eigenproblems.

Return type: tuple[Mat, Mat] | tuple[Mat, None]

Ngl, that second one lowkey tells you whether you're in a generalized eigenproblem or not โ€” if B comes back as None, you're not. ๐Ÿ‘‘

See also: setOperators, EPSGetOperators <https://slepc.upv.es/release/manualpages/EPS/EPSGetOperators.html>

:source: Source code at slepc4py/SLEPc/EPS.pyx:1520 <slepc4py/SLEPc/EPS.pyx#L1520>

getOptionsPrefix()

Get the prefix that's used for searching for all EPS options in the database. ๐Ÿ”

Not collective.

Returns: the prefix string set for this EPS object.

Return type: str

See also: setOptionsPrefix, appendOptionsPrefix, EPSGetOptionsPrefix <https://slepc.upv.es/release/manualpages/EPS/EPSGetOptionsPrefix.html>

:source: Source code at slepc4py/SLEPc/EPS.pyx:465 <slepc4py/SLEPc/EPS.pyx#L465>

getPowerShiftType()

Get the type of shifts that get used during the power iteration. โšก

Not collective.

Returns: the type of shift.

Return type: PowerShiftType <#slepc4py.SLEPc.EPS.PowerShiftType>

See also: setPowerShiftType, EPSPowerGetShiftType <https://slepc.upv.es/release/manualpages/EPS/EPSPowerGetShiftType.html>

:source: Source code at slepc4py/SLEPc/EPS.pyx:2367 <slepc4py/SLEPc/EPS.pyx#L2367>

getProblemType()

Get the problem type straight off the EPS object. ๐ŸŒธ

Not collective.

Returns: the problem type that was previously set.

Return type: ProblemType <#slepc4py.SLEPc.EPS.ProblemType>

See also: setProblemType, EPSGetProblemType <https://slepc.upv.es/release/manualpages/EPS/EPSGetProblemType.html>

:source: Source code at slepc4py/SLEPc/EPS.pyx:555 <slepc4py/SLEPc/EPS.pyx#L555>

getPurify()

Get the flag telling you whether purification is activated or not. โœจ It's giving "are we polishing these eigenvectors or nah".

Not collective.

Returns: whether purification is activated or not.

Return type: bool

See also: setPurify, EPSGetPurify <https://slepc.upv.es/release/manualpages/EPS/EPSGetPurify.html>

:source: Source code at slepc4py/SLEPc/EPS.pyx:1134 <slepc4py/SLEPc/EPS.pyx#L1134>

getRG()

Get the region object that's associated to the eigensolver. ๐Ÿ—บ๏ธ

Not collective.

Returns: the region context.

Return type: RG <#slepc4py.SLEPc.RG>

See also: setRG, EPSGetRG <https://slepc.upv.es/release/manualpages/EPS/EPSGetRG.html>

:source: Source code at slepc4py/SLEPc/EPS.pyx:1483 <slepc4py/SLEPc/EPS.pyx#L1483>

getRQCGReset()

Get the reset parameter used in the RQCG method. ๐Ÿ”„

Not collective.

Returns: the number of iterations between resets.

Return type: int

See also: setRQCGReset, EPSRQCGGetReset <https://slepc.upv.es/release/manualpages/EPS/EPSRQCGGetReset.html>

:source: Source code at slepc4py/SLEPc/EPS.pyx:3743 <slepc4py/SLEPc/EPS.pyx#L3743>

getST()

Get the spectral transformation object associated to the eigensolver. ๐Ÿ’…

Not collective.

Returns: the spectral transformation.

Return type: ST <#slepc4py.SLEPc.ST>

See also: setST, EPSGetST <https://slepc.upv.es/release/manualpages/EPS/EPSGetST.html>

:source: Source code at slepc4py/SLEPc/EPS.pyx:1372 <slepc4py/SLEPc/EPS.pyx#L1372>

getStoppingTest()

Get the stopping test function. ๐Ÿ›‘

Not collective.

Returns: the sto

  • Return type โ€” EPSStoppingFunction <#slepc4py.typing.EPSStoppingFunction> ๐Ÿ’–
  • See also: setStoppingTest
  • Source: slepc4py/SLEPc/EPS.pyx:1710 <slepc4py/SLEPc/EPS.pyx#L1710>

getTarget()

Bestie this one just hands you back the value of the target. ๐ŸŽฏ Not collective, no drama, no group chat needed.

  • Returns โ€” the value of the target.
  • Return type โ€” Scalar <#slepc4py.typing.Scalar>

Notes

If the target was never set by the user, then zero is returned. That's it, that's the whole story. ๐Ÿ’€

See also: setTarget, EPSGetTarget (https://slepc.upv.es/release/manualpages/EPS/EPSGetTarget.html)

Source: slepc4py/SLEPc/EPS.pyx:924 <slepc4py/SLEPc/EPS.pyx#L924>

getThreshold()

Get the threshold used in the threshold stopping test. Not collective, we're doing this solo. ๐Ÿ’…

See also: setThreshold, EPSGetThreshold (https://slepc.upv.es/release/manualpages/EPS/EPSGetThreshold.html)

Source: slepc4py/SLEPc/EPS.pyx:873 <slepc4py/SLEPc/EPS.pyx#L873>

getTolerances()

Get the tolerance and max. iter. count used for convergence tests. Not collective. โœจ

Like, this is the tolerance and iteration limit that the default EPS convergence tests are out here using. It's giving "how chill are we about calling it converged".

See also: setTolerances, EPSGetTolerances (https://slepc.upv.es/release/manualpages/EPS/EPSGetTolerances.html)

Source: slepc4py/SLEPc/EPS.pyx:1034 <slepc4py/SLEPc/EPS.pyx#L1034>

getTrackAll()

Get the flag indicating if all residual norms must be computed or not. Not collective. ๐Ÿฆ‹

See also: setTrackAll, EPSGetTrackAll (https://slepc.upv.es/release/manualpages/EPS/EPSGetTrackAll.html)

Source: slepc4py/SLEPc/EPS.pyx:1255 <slepc4py/SLEPc/EPS.pyx#L1255>

getTrueResidual()

Get the flag indicating if true residual must be computed explicitly. Not collective. ๐Ÿซถ

See also: setTrueResidual, EPSGetTrueResidual (https://slepc.upv.es/release/manualpages/EPS/EPSGetTrueResidual.html)

Source: slepc4py/SLEPc/EPS.pyx:1218 <slepc4py/SLEPc/EPS.pyx#L1218>

getTwoSided()

Get the flag indicating if a two-sided variant of the algorithm is being used. Not collective โ€” both sides of the algorithm, but only one of us asking, iykyk. โœŒ๏ธ

See also: setTwoSided, EPSGetTwoSided (https://slepc.upv.es/release/manualpages/EPS/EPSGetTwoSided.html)

Source: slepc4py/SLEPc/EPS.pyx:1087 <slepc4py/SLEPc/EPS.pyx#L1087>

getType()

Get the EPS type of this object. Not collective. ๐ŸŒธ

See also: setType, EPSGetType (https://slepc.upv.es/release/manualpages/EPS/EPSGetType.html)

Source: slepc4py/SLEPc/EPS.pyx:446 <slepc4py/SLEPc/EPS.pyx#L446>

getWhichEigenpairs()

Get which portion of the spectrum is to be sought. Not collective. ๐Ÿ‘‘

  • Returns โ€” the portion of the spectrum to be sought by the solver.
  • Return type โ€” Which <#slepc4py.SLEPc.EPS.Which>

See also: setWhichEigenpairs, EPSGetWhichEigenpairs (https://slepc.upv.es/release/manualpages/EPS/EPSGetWhichEigenpairs.html)

Source: slepc4py/SLEPc/EPS.pyx:817 <slepc4py/SLEPc/EPS.pyx#L817>

isGeneralized()

Tell if the EPS object corresponds to a generalized eigenproblem. Not collective. ๐Ÿ’œ

See also: isHermitian, isPositive, isStructured, EPSIsGeneralized (https://slepc.upv.es/release/manualpages/EPS/EPSIsGeneralized.html)

Source: slepc4py/SLEPc/EPS.pyx:610 <slepc4py/SLEPc/EPS.pyx#L610>

isHermitian()

Tell if the EPS object corresponds to a Hermitian eigenproblem. Not collective. ๐ŸŒˆ

See also: isGeneralized, isPositive, isStructured, EPSIsHermitian (https://slepc.upv.es/release/manualpages/EPS/EPSIsHermitian.html)

Source: slepc4py/SLEPc/EPS.pyx:629 <slepc4py/SLEPc/EPS.pyx#L629>

isPositive()

Eigenproblem requiring a positive (semi-) definite matrix B. ๐Ÿ“

Not collective.

Tell if the EPS corresponds to an eigenproblem requiring a positive (semi-) definite matrix B.

See also: isGeneralized, isHermitian, isStructured, EPSIsPositive (https://slepc.upv.es/release/manualpages/EPS/EPSIsPositive.html)

Source: slepc4py/SLEPc/EPS.pyx:648 <slepc4py/SLEPc/EPS.pyx#L648>

isStructured()

Tell if the EPS object corresponds to a structured eigenvalue problem. Not collective. ๐ŸŽ€

Notes

The result will be True if the problem type has been set to some structured type such as BSE <#slepc4py.SLEPc.EPS.ProblemType.BSE>. This is independent of whether the input matrix has been built with a certain structure with a helper function. So like, don't get it twisted โ€” this is about the problem type, not about how the matrix got cooked. ๐Ÿ”ฅ

See also: isGeneralized, isHermitian, isPositive, EPSIsStructured (https://slepc.upv.es/release/manualpages/EPS/EPSIsStructured.html)

Source: slepc4py/SLEPc/EPS.pyx:670 <slepc4py/SLEPc/EPS.pyx#L670>

reset()

Reset the EPS object. Collective. ๐Ÿงš

See also: EPSReset (https://slepc.upv.es/release/manualpages/EPS/EPSReset.html)

Source: slepc4py/SLEPc/EPS.pyx:386 <slepc4py/SLEPc/EPS.pyx#L386>

setArbitrarySelection(arbitrary, args=None, kargs=None)

Set an arbitrary selection criterion function. Logically collective. ๐Ÿ’–

Set a function to look for eigenvalues according to an arbitrary selection criterion. This criterion can be based on a computation involving the current eigenvector approximation. Basically you get to make up the rules yourself, main character energy. ๐Ÿ‘‘

See also: getArbitrarySelection, EPSSetArbitrarySelection (https://slepc.upv.es/release/manualpages/EPS/EPSSetArbitrarySelection.html)

Source: slepc4py/SLEPc/EPS.pyx:1727 <slepc4py/SLEPc/EPS.pyx#L1727>

Parameters

Return type: None <https://docs.python.org/3/library/constants.html#None> โ€” it gives nothing back, not even a little heart ๐Ÿซถ

setArnoldiDelayed(delayed)

okay so this one sets (toggles, bestie, it's a toggle ๐Ÿ’…) delayed reorthogonalization in the Arnoldi iteration.

Logically collective.

Parameters

Return type: None <https://docs.python.org/3/library/constants.html#None>

Notes ๐Ÿ“

  • This call is only relevant if the type was set to EPS.Type.ARNOLDI <#slepc4py.SLEPc.EPS.Type.ARNOLDI> with setType().
  • Delayed reorthogonalization is an aggressive optimization for the Arnoldi eigensolver than may provide better scalability, but sometimes makes the solver converge more slowly compared to the default algorithm. ๐Ÿ’€ so like, faster in theory, sometimes crawling in practice, pick your fighter.

See also: getArnoldiDelayed, EPSArnoldiSetDelayed <https://slepc.upv.es/release/manualpages/EPS/EPSArnoldiSetDelayed.html>

:sources: Source code at slepc4py/SLEPc/EPS.pyx:2386 (slepc4py/SLEPc/EPS.pyx#L2386)

setBV(bv)

Set a basis vectors object associated to the eigensolver. ๐Ÿฆ‹

Collective.

Parameters

  • bv (BV <#slepc4py.SLEPc.BV>) โ€” The basis vectors context.

Return type: None <https://docs.python.org/3/library/constants.html#None>

See also: getBV, EPSSetBV <https://slepc.upv.es/release/manualpages/EPS/EPSSetBV.html>

:sources: Source code at slepc4py/SLEPc/EPS.pyx:1429 (slepc4py/SLEPc/EPS.pyx#L1429)

setBalance(balance=None, iterations=None, cutoff=None)

Set the balancing technique to be used by the eigensolver. โœจ

Logically collective.

Parameters

Return type: None <https://docs.python.org/3/library/constants.html#None>

Notes ๐Ÿ“

When balancing is enabled, the solver works implicitly with matrix DAD^{-1}, where D is an appropriate diagonal matrix. This improves the accuracy of the computed results in some cases.

Balancing makes sense only for non-Hermitian problems when the required precision is high (i.e., with a small tolerance). iykyk, high precision + non-Hermitian = this is your moment.

By default, balancing is disabled. The two-sided method is much more effective than the one-sided counterpart, but it requires the system matrices to have the Mat.multTranspose() operation defined. no Mat.multTranspose(), no two-sided glow-up, sorry bestie.

The parameter iterations is the number of iterations performed by the method. The cutoff value is used only in the two-side variant.

See also: setBalance, EPSGetBalance <https://slepc.upv.es/release/manualpages/EPS/EPSGetBalance.html>

:sources: Source code at slepc4py/SLEPc/EPS.pyx:720 (slepc4py/SLEPc/EPS.pyx#L720)

setCISSExtraction(extraction)

Set the extraction technique used in the CISS solver. ๐ŸŽ€

Logically collective.

Parameters

  • extraction (CISSExtraction <#slepc4py.SLEPc.EPS.CISSExtraction>) โ€” The extraction technique.

Return type: None <https://docs.python.org/3/library/constants.html#None>

See also: getCISSExtraction, EPSCISSSetExtraction <https://slepc.upv.es/release/manualpages/EPS/EPSCISSSetExtraction.html>

:sources: Source code at slepc4py/SLEPc/EPS.pyx:3942 (slepc4py/SLEPc/EPS.pyx#L3942)

setCISSQuadRule(quad)

Set the quadrature rule used in the CISS solver. ๐ŸŒธ

Logically collective.

Parameters

  • quad (CISSQuadRule <#slepc4py.SLEPc.EPS.CISSQuadRule>) โ€” The quadrature rule.

Return type: None <https://docs.python.org/3/library/constants.html#None>

See also: getCISSQuadRule, EPSCISSSetQuadRule <https://slepc.upv.es/release/manualpages/EPS/EPSCISSSetQuadRule.html>

:sources: Source code at slepc4py/SLEPc/EPS.pyx:3979 (slepc4py/SLEPc/EPS.pyx#L3979)

setCISSRefinement(inner=None, blsize=None)

Set the values of various refinement parameters in the CISS solver. ๐Ÿ’œ

Logically collective.

Parameters

Return type: None <https://docs.python.org/3/library/constants.html#None>

See also: getCISSRefinement, EPSCISSSetRefinement <https://slepc.upv.es/release/manualpages/EPS/EPSCISSSetRefinement.html>

:sources: Source code at slepc4py/SLEPc/EPS.pyx:4149 (slepc4py/SLEPc/EPS.pyx#L4149)

setCISSSizes(ip=None, bs=None, ms=None, npart=None, bsmax=None, realmats=False)

Set the values of various size parameters in the CISS solver. ๐Ÿ”ฅ six kwargs, whole lil menu, we love a configurable era.

Logically collective.

Parameters

Return type: None <https://docs.python.org/3/library/constants.html#None>

Notes ๐Ÿ“

The default number of partitions is 1. This means the internal petsc4py.PETSc.KSP <https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.KSP.html#petsc4py.PETSc.KSP> object is shared among all processes of the EPS communicator. Otherwise, the communicator is split into npart communicators, so that npart petsc4py.PETSc.KSP <https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.KSP.html#petsc4py.PETSc.KSP> solves proceed simultaneously. one shared solver vs. a whole squad of them running at once, your call ๐Ÿ’…

See also: getCISSSizes, setCISSThreshold, setCISSRefinement, EPSCISSSetSizes <https://slepc.upv.es/release/manualpages/EPS/EPSCISSSetSizes.html>

:sources: Source code at slepc4py/SLEPc/EPS.pyx:4016 (slepc4py/SLEPc/EPS.pyx#L4016)

setCISSThreshold(delta=None, spur=None)

Set the values of various threshold parameters in the CISS solver. ๐Ÿฆ‹

Logically collective.

  • delta (float | None) โ€” your threshold for numerical rank, bestie. It's giving "how small is small enough" energy. โœจ
  • spur (float | None) โ€” the spurious threshold, aka the bouncer at the club door that tosses out spurious eigenpairs. ๐Ÿ’…

Return type None ๐Ÿซถ

See also: getCISSThreshold, EPSCISSSetThreshold (https://slepc.upv.es/release/manualpages/EPS/EPSCISSSetThreshold.html)

Source code at slepc4py/SLEPc/EPS.pyx:4104 ๐Ÿ“

setCISSUseST(usest)

okay so this one sets a flag saying whether the CISS solver is gonna use the ST object. yes queen, decide your destiny. ๐Ÿ‘‘

Logically collective.

Parameters

  • usest (bool) โ€” whether to use the ST object or not. like. true or false. pick one bestie ๐Ÿ’–

Return type None

Notes

So the way this works: when this option is set, the linear solves can be configured by setting options for the petsc4py.PETSc.KSP (https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.KSP.html#petsc4py.PETSc.KSP) object that you get with ST.getKSP().

Otherwise (no ST energy), several petsc4py.PETSc.KSP (https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.KSP.html#petsc4py.PETSc.KSP) objects get created instead, and you can reach those with getCISSKSPs().

The default is to use the ST, unless several partitions have been specified, see setCISSSizes(). not me keeping track of all these defaults, it's literally my roman empire ๐Ÿ˜ญ

See also: getCISSUseST, getCISSKSPs, setCISSSizes, EPSCISSSetUseST (https://slepc.upv.es/release/manualpages/EPS/EPSCISSSetUseST.html)

Source code at slepc4py/SLEPc/EPS.pyx:4194 ๐Ÿ“

setConvergenceTest(conv)

Sets how the error estimate gets computed for the convergence test. the vibe check before we declare victory. ๐ŸŽ€

Logically collective.

Parameters

  • conv (Conv) โ€” the method used to compute the error estimate used in the convergence test.

Return type None

See also: getConvergenceTest, EPSSetConvergenceTest (https://slepc.upv.es/release/manualpages/EPS/EPSSetConvergenceTest.html)

Source code at slepc4py/SLEPc/EPS.pyx:1199 ๐Ÿ“

setDS(ds)

Attaches a direct solver object to the eigensolver. matching them up like it's prom. ๐Ÿ’ž

Collective.

Parameters

  • ds (DS) โ€” the direct solver context.

Return type None

See also: getDS, EPSSetDS (https://slepc.upv.es/release/manualpages/EPS/EPSSetDS.html)

Source code at slepc4py/SLEPc/EPS.pyx:1466 ๐Ÿ“

setDeflationSpace(space)

Gives the solver some vectors that form a basis of the deflation space. no cap, this one's lowkey powerful. ๐Ÿ”ฅ

Collective.

Parameters

  • space (Vec | list[Vec]) โ€” set of basis vectors of the deflation space.

Return type None

See also: setInitialSpace, EPSSetDeflationSpace (https://slepc.upv.es/release/manualpages/EPS/EPSSetDeflationSpace.html)

Source code at slepc4py/SLEPc/EPS.pyx:1578 ๐Ÿ“

Notes

When a deflation space is given, the eigensolver seeks the eigensolution in the restriction of the problem to the orthogonal complement of this space. So it's like, "okay we're doing this over here now." ๐ŸŒˆ

This is useful for instance when an invariant subspace is known beforehand โ€” like the nullspace of the matrix. iconic foresight honestly. ๐Ÿ‘‘

bestie. listen. these vectors do NOT persist from one solve() call to the next, so you gotta set the deflation space every single time. no skipping. ๐Ÿ™ˆ

The vectors don't need to be mutually orthonormal, because they get explicitly orthonormalized internally. so you can just hand them over raw, the solver will handle it. slay. ๐Ÿ’…

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

Sets how many eigenvalues to compute and how big the subspace is. it's giving "let's set some boundaries" energy. ๐Ÿฆ‹

Logically collective.

Parameters

  • nev (int | None) โ€” number of eigenvalues 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

See also: getDimensions, setKrylovSchurDimensions, EPSSetDimensions (https://slepc.upv.es/release/manualpages/EPS/EPSSetDimensions.html)

Source code at slepc4py/SLEPc/EPS.pyx:1317 ๐Ÿ“

Notes

Use DETERMINE for ncv and mpd to assign a reasonably good value, and that value depends on the solution method. let the solver pick, it's capable. โœจ

The parameters ncv and mpd are intimately related ๐Ÿซถ, so the user is advised to set at most one of them. Normal usage goes like this:

  • In cases where nev is small, you set ncv (a reasonable default is 2 * nev).
  • In cases where nev is large, you set mpd.

The value of ncv should always be between nev and (nev + mpd), and typically ncv = nev + mpd. If nev isn't too large, mpd = nev is a reasonable choice; otherwise use a smaller value.

When computing all eigenvalues in an interval, see setInterval(), these parameters lose relevance, and the tuning has to be done with setKrylovSchurDimensions() instead. different era, different rules. periodt. ๐Ÿ’œ

setEigenvalueComparison(comparison, args=None, kargs=None)

Sets an eigenvalue comparison function. a little custom sorter for your eigenvibes. ๐ŸŽ€

Logically collective.

Parameters

  • comparison (EPSEigenvalueComparison | None)
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type None

See also: getEigenvalueComparison, EPSSetEigenvalueComparison (https://slepc.upv.es/release/manualpages/EPS/EPSSetEigenvalueComparison.html)

Source code at slepc4py/SLEPc/EPS.pyx:1773 ๐Ÿ“

Notes

This eigenvalue comparison function gets used when setWhichEigenpairs() is set to EPS.Which.USER. it's the user's moment to shine. main character energy fr fr ๐Ÿ‘‘

setExtraction(extraction)

Sets the extraction type used by the eigensolver. pick your flavor bestie. ๐Ÿ“

Logically collective.

Parameters

  • extraction (Extraction) โ€” the extraction method to be used by the solver.

Return type None

See also: getExtraction, EPSSetExtraction (https://slepc.upv.es/release/manualpages/EPS/EPSSetExtraction.html)

Source code at slepc4py/SLEPc/EPS.pyx:1903 ๐Ÿ“

Notes

Heads up: not all eigensolvers support all types of extraction. so don't just assume, okay? the vibe check matters here. ๐Ÿ’€

By default, it's a plain old standard Rayleigh-Ritz extraction ๐Ÿ’…. But other extractions? Lowkey iconic when you're out here computing interior eigenvalues โœจ.

Harmonic-type extractions don't roll solo โ€” they come as a package deal with a target, so go peek at setTarget() ๐ŸŽฏ.

See also: getExtraction, setTarget, EPSSetExtraction โ€” https://slepc.upv.es/release/manualpages/EPS/EPSSetExtraction.html

Source code lives at slepc4py/SLEPc/EPS.pyx:789 ๐Ÿซถ

setFromOptions()

Okay bestie, this one pulls all your EPS options straight from the options database so you don't have to hand-set every single thing ๐ŸŒˆ.

Collective.

Notes:

  • Wanna see literally every option available? Run your program with the -help option, no cap ๐Ÿ‘€.
  • This routine is required to be called before setUp() if you wanna be the one who gets to set the solver type. Skip it and you lose that privilege ๐Ÿ’….

See also: setOptionsPrefix, EPSSetFromOptions โ€” https://slepc.upv.es/release/manualpages/EPS/EPSSetFromOptions.html

Source code at slepc4py/SLEPc/EPS.pyx:534 โœจ

Return type: None

setGDBOrth(borth)

Sets the orthogonalization that's gonna be used in the search subspace ๐Ÿงš.

Logically collective.

More specifically: it sets the orthogonalization used in the search subspace when you're dealing with generalized Hermitian problems ๐Ÿฆ‹.

Parameters:

  • borth (bool) โ€“ Whether to B-orthogonalize the search subspace.

Return type: None

See also: getGDBOrth, EPSGDSetBOrth โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGDSetBOrth.html

Source code at slepc4py/SLEPc/EPS.pyx:3316 ๐ŸŒธ

setGDBlockSize(bs)

Sets how many vectors get added to the searching space ๐Ÿ“ฆ.

Logically collective.

Like, the number of vectors added to the searching space in every single iteration ๐Ÿ”.

Parameters:

  • bs (int) โ€“ The number of vectors added to the search space in every iteration.

Return type: None

See also: getGDBlockSize, EPSGDSetBlockSize โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGDSetBlockSize.html

Source code at slepc4py/SLEPc/EPS.pyx:3175 ๐Ÿ’œ

setGDDoubleExpansion(doubleexp)

Tells it that the search subspace gets expanded with double expansion ๐Ÿ‘ฏ.

Logically collective.

Parameters:

  • doubleexp (bool) โ€“ True if using double expansion.

Return type: None

Notes:

In the double expansion variant, the search subspace is expanded with K [A x, B x] (double expansion) instead of the classic K r, where K is the preconditioner, x the selected approximate eigenvector and r its associated residual vector. It's giving โœจextraโœจ for a reason, bestie.

See also: getGDDoubleExpansion, EPSGDSetDoubleExpansion โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGDSetDoubleExpansion.html

Source code at slepc4py/SLEPc/EPS.pyx:3359 ๐ŸŽ€

setGDInitialSize(initialsize)

Sets the initial size of the searching space ๐ŸŒฑ.

Logically collective.

Parameters:

  • initialsize (int) โ€“ The number of vectors of the initial searching subspace.

Return type: None

Notes:

Okay listen up, two whole scenarios, don't get it twisted ๐Ÿซถ:

  • If the flag in setGDKrylovStart() is set to False and you (the user) hand over vectors with setInitialSpace(), then up to initialsize vectors will be used. And if the vectors you gave aren't enough? The solver just fills in the rest of the subspace with random vectors ๐ŸŽฒ.
  • If the setGDKrylovStart() flag is True instead, the solver grabs the first vector you provided โ€” or, if there isn't one, a random vector โ€” and expands the Krylov basis up to initialsize vectors ๐Ÿ“ˆ.

See also: setGDKrylovStart, getGDInitialSize, EPSGDSetInitialSize โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGDSetInitialSize.html

Source code at slepc4py/SLEPc/EPS.pyx:3269 ๐ŸŒˆ

setGDKrylovStart(krylovstart=True)

Set (or toggle) whether the search subspace starts with a Krylov basis ๐ŸŒ€.

Logically collective.

Parameters:

  • krylovstart (bool) โ€“ True if starting the search subspace with a Krylov basis.

Return type: None

See also: setGDInitialSize, getGDKrylovStart, EPSGDSetKrylovStart โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGDSetKrylovStart.html

Source code at slepc4py/SLEPc/EPS.pyx:3138 โญ

setGDRestart(minv=None, plusk=None)

Sets how many vectors the search space holds after a restart ๐Ÿ”„.

Logically collective.

It sets the number of vectors of the search space after restart and the number of vectors saved from the previous iteration. Two-for-one, we love to see it ๐Ÿ’….

Parameters:

  • minv (int) โ€“ The number of vectors of the search subspace after restart.
  • plusk (int) โ€“ The number of vectors saved from the previous iteration.

Return type: None

See also: getGDRestart, EPSGDSetRestart โ€” https://slepc.upv.es/release/manualpages/EPS/EPSGDSetRestart.html

Source code at slepc4py/SLEPc/EPS.pyx:3218 ๐Ÿ“

setInitialSpace(space)

Sets the initial space that the eigensolver kicks off its iteration from ๐Ÿš€.

Collective.

Parameters:

  • space (Vec | list[Vec]) โ€“ Set of basis vectors of the initial space.

Return type: None

Notes:

  • Some solvers only ever iterate on a single vector (the initial vector). In that case only the first vector matters and the rest are just ignored ๐Ÿ™ˆ. But other solvers, like SUBSPACE, can actually use the whole initial subspace as an initial guess ๐Ÿ‘‘.
  • Heads up: these vectors do not persist from one solve() call to the next, so you've gotta set the initial space every single time ๐Ÿ˜ญ.
  • No, they don't need to be mutually orthonormal โ€” they get explicitly orthonormalized internally anyway ๐Ÿงผ.
  • Common usage? When you've got a rough approximation of the eigenspace you want. Do that and convergence may be faster โšก.

See also: setDeflationSpace, setLeftInitialSpace, EPSSetInitialSpace โ€” https://slepc.upv.es/release/manualpages/EPS/EPSSetInitialSpace.html

Source code at slepc4py/SLEPc/EPS.pyx:1616 ๐Ÿ’–

setInterval(inta, intb)

Sets the computational interval for spectrum slicing โœ‚๏ธ.

Logically collective.

Parameters:

  • inta (float) โ€“ The left end of the interval.
  • intb (float) โ€“ The right end of the interval.

Return type: None

Notes:

Spectrum slicing is the technique used to compute all eigenvalues of symmetric eigenproblems inside a given interval ๐ŸŒธ. This function is the one that hands over the interval to be considered.

It must be used in combination with EPS.Which.ALL, see setWhichEigenpairs() โš ๏ธ.

A computational interval is also needed when you're using polynomial filters โ€” peep STFILTER. ๐Ÿฆ‹

See also: getInterval, setWhichEigenpairs, EPSSetInterval, STFILTER

Source code at slepc4py/SLEPc/EPS.pyx:1000

setJDBOrth(borth)

Sets the orthogonalization that's gonna be used in the search subspace. ๐Ÿ’…

Logically collective. โœจ

This one sets the orthogonalization used in the search subspace when you've got generalized Hermitian problems going on.

Parameters:

  • borth (bool) โ€” whether to B-orthogonalize the search subspace.

Return type: None

See also: getJDBOrth, EPSJDSetBOrth

Source code at slepc4py/SLEPc/EPS.pyx:3675

setJDBlockSize(bs)

Sets how many vectors get added to the searching space. ๐ŸŽ€

Logically collective. โœจ

Like, it sets the number of vectors added to the searching space in every single iteration.

Parameters:

  • bs (int) โ€” the number of vectors added to the search space in every iteration.

Return type: None

See also: getJDBlockSize, EPSJDSetBlockSize

Source code at slepc4py/SLEPc/EPS.pyx:3446

setJDConstCorrectionTol(constant)

Deactivates the dynamic stopping criterion. ๐Ÿ˜ญ

Logically collective. โœจ

Parameters:

  • constant (bool) โ€” if False, the petsc4py.PETSc.KSP relative tolerance is set to 0.5**i.

Return type: None

Notes

So if this flag is set to False, the petsc4py.PETSc.KSP relative tolerance gets dynamically set to 0.5**i, where i is the number of EPS iterations since the last converged value. By default tho, a constant tolerance is used. ๐Ÿซถ

See also: getJDConstCorrectionTol, EPSJDSetConstCorrectionTol

Source code at slepc4py/SLEPc/EPS.pyx:3630

setJDFix(fix)

Sets the threshold for changing the target in the correction equation. ๐Ÿ”ฅ

Logically collective. โœจ

Parameters:

  • fix (float) โ€” the threshold for changing the target.

Return type: None

Notes

The target in the correction equation is fixed at the first iterations. Then, when the norm of the residual vector drops below the fix value, the target gets set to the corresponding eigenvalue. ๐Ÿ‘‘

See also: getJDFix, EPSJDSetFix

Source code at slepc4py/SLEPc/EPS.pyx:3587

setJDInitialSize(initialsize)

Sets the initial size of the searching space. ๐ŸŒธ

Logically collective. โœจ

Parameters:

  • initialsize (int) โ€” the number of vectors of the initial searching subspace.

Return type: None

Notes

okay so here's the tea: if the flag in setJDKrylovStart() is set to False and the user provides vectors with setInitialSpace(), up to initialsize vectors will be used โ€” and if the vectors provided aren't enough, the solver completes the subspace with random vectors. ๐ŸŽฒ But if the setJDKrylovStart() flag is True, the solver takes the first vector provided by the user (or a random vector if there isn't one) and expands the Krylov basis up to initialsize vectors.

See also: setJDKrylovStart, getJDInitialSize, EPSJDSetInitialSize

Source code at slepc4py/SLEPc/EPS.pyx:3540

setJDKrylovStart(krylovstart=True)

Sets (toggles) starting the search subspace with a Krylov basis. โœจ

Logically collective. โœจ

Parameters:

  • krylovstart (bool) โ€” True if starting the search subspace with a Krylov basis.

Return type: None

See also: setJDInitialSize, getJDKrylovStart, EPSJDSetKrylovStart

Source code at slepc4py/SLEPc/EPS.pyx:3409

setJDRestart(minv=None, plusk=None)

Sets the number of vectors of the search space after restart. ๐Ÿ’œ

Logically collective. โœจ

So it sets the number of vectors of the search space after restart, plus the number of vectors saved from the previous iteration.

Parameters:

  • minv (int | None) โ€” the number of vectors of the search subspace after restart.
  • plusk (int | None) โ€” the number of vectors saved from the previous iteration.

Return type: None

See also: getJDRestart, EPSJDSetRestart

Source code at slepc4py/SLEPc/EPS.pyx:3489

setKrylovSchurBSEType(bse)

Sets the Krylov-Schur variant used for BSE structured eigenproblems. ๐ŸŒˆ

Logically collective. โœจ

Parameters:

  • bse (KrylovSchurBSEType) โ€” the BSE method.

Return type: None

Notes

This call is only relevant if the type was set to EPS.Type.KRYLOVSCHUR with setType() and the problem type was set to EPS.ProblemType.BSE with setProblemType(). iykyk ๐Ÿ’…

See also: createMatBSE, getKrylovSchurBSEType, EPSKrylovSchurSetBSEType

Source code at slepc4py/SLEPc/EPS.pyx:2478

setKrylovSchurDetectZeros(detect)

Sets the flag that enforces zero detection in spectrum slicing. ๐Ÿ”

Logically collective. โœจ

Sets a flag to enforce the detection of zeros during the factorizations all throughout the spectrum slicing computation.

Parameters:

  • detect (bool) โ€” True if zeros must be checked for.

Return type: None

Notes

This call only makes sense for spectrum slicing runs, like, when an interval has been given with setInterval() and SINVERT is set. ๐Ÿ“

A zero in the factorization indicates that a shift coincides with an eigenvalue.

This flag is turned off by default, but honestly sometimes you need it on, especially when several partitions are doing their thing at once. ๐Ÿซถ This feature currently requires an external package for factorizations with support for zero detection, e.g., MUMPS.

See also: setInterval, getKrylovSchurDetectZeros, EPSKrylovSchurSetDetectZeros (upstream manual page: slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurSetDetectZeros.html)

Source: slepc4py/SLEPc/EPS.pyx:2662

setKrylovSchurDimensions(nev=None, ncv=None, mpd=None)

Sets the dimensions used for each subsolve step (spectrum slicing). ๐Ÿ”ชโœจ

Logically collective.

Parameters

  • nev (int | None) โ€” Number of eigenvalues 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

This call makes sense only for spectrum slicing runs, that is, when an interval has been given with setInterval() and SINVERT is set. ๐ŸŽฏ

The meaning of the parameters is the same as in setDimensions(), but the ones here apply to every subsolve done by the child EPS object. Like, every single one. no cap.

See also: setInterval, getKrylovSchurDimensions, EPSKrylovSchurSetDimensions (upstream manual page: slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurSetDimensions.html)

Source: slepc4py/SLEPc/EPS.pyx:2715

setKrylovSchurLocking(lock)

Toggles the locking / non-locking variants of the Krylov-Schur method. ๐Ÿ”’

Logically collective.

Parameters

  • lock (bool) โ€” True if the locking variant must be selected.

Return type: None

Notes

The default is to lock converged eigenpairs 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: getKrylovSchurLocking, EPSKrylovSchurSetLocking (upstream manual page: slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurSetLocking.html)

Source: slepc4py/SLEPc/EPS.pyx:2564

setKrylovSchurPartitions(npart)

Sets the number of partitions of the communicator (spectrum slicing). ๐Ÿฐ๐Ÿฐ๐Ÿฐ

Logically collective.

Set the number of partitions for the case of doing spectrum slicing for a computational interval with the communicator split in several sub-communicators. it's giving divide and conquer.

Parameters

  • npart (int) โ€” The number of partitions.

Return type: None

Notes

This call makes sense only for spectrum slicing runs, that is, when an interval has been given with setInterval() and SINVERT is set. ๐ŸŽฏ

By default, npart=1 so all processes in the communicator participate in the processing of the whole interval. If npart>1 then the interval is divided into npart subintervals, each of them being processed by a subset of processes. ๐Ÿซถ

The interval is split proportionally unless the separation points are specified with setKrylovSchurSubintervals().

See also: setInterval, getKrylovSchurPartitions, EPSKrylovSchurSetPartitions (upstream manual page: slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurSetPartitions.html)

Source: slepc4py/SLEPc/EPS.pyx:2608

setKrylovSchurRestart(keep)

Sets the restart parameter for the Krylov-Schur method. ๐Ÿ”

Logically collective.

It is 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: getKrylovSchurRestart, EPSKrylovSchurSetRestart (upstream manual page: slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurSetRestart.html)

Source: slepc4py/SLEPc/EPS.pyx:2521

setKrylovSchurSubintervals(subint)

Sets the subinterval boundaries. โœ‚๏ธ

Logically collective.

Set the subinterval boundaries for spectrum slicing with a computational interval with several partitions.

Parameters

  • subint (Sequence[float]) โ€” Real values specifying subintervals.

Return type: None

Notes

This call makes sense only for spectrum slicing runs, that is, when an interval has been given with setInterval() and SINVERT is set. ๐ŸŽฏ

This function must be called after setKrylovSchurPartitions(). For npart partitions, the argument subint must contain npart+1 real values sorted in ascending order: subint_0, subint_1, โ€ฆ, subint_npart, where the first and last values must coincide with the interval endpoints set with setInterval(). The subintervals are then defined by two consecutive points: [subint_0,subint_1], [subint_1,subint_2], and so on. ๐ŸŽ€

order matters bestie, ascending only, and don't forget the endpoints have to match your setInterval() ones exactly.

See also: setInterval, setKrylovSchurPartitions, EPSKrylovSchurSetSubintervals (upstream manual page: slepc.upv.es/release/manualpages/EPS/EPSKrylovSchurSetSubintervals.html)

Source: slepc4py/SLEPc/EPS.pyx:2971

setLOBPCGBlockSize(bs)

Sets the block size of the LOBPCG method. ๐Ÿงฑ

Logically collective.

Parameters

  • bs (int) โ€” The block size.

Return type: None

See also: getLOBPCGBlockSize, EPSLOBPCGSetBlockSize (upstream manual page: slepc.upv.es/release/manualpages/EPS/EPSLOBPCGSetBlockSize.html)

Source: slepc4py/SLEPc/EPS.pyx:3762

setLOBPCGLocking(lock)

Toggle between locking and non-locking (LOBPCG method). ๐Ÿ”

Logically collective.

Parameters

  • lock (bool) โ€” True if the locking variant must be selected.

Return type: None

Notes

This flag refers to soft locking (converged vectors within the current block iterate), since hard locking is always used (when nev is larger than the block size). ๐Ÿ‘‘

See also: getLOBPCGLocking, EPSLOBPCGSetLocking (upstream manual page: slepc.upv.es/release/manualpages/EPS/EPSLOBPCGSetLocking.html)

Source: slepc4py/SLEPc/EPS.pyx:3843

setLOBPCGRestart(restart)

Sets the restart parameter for the LOBPCG method. ๐Ÿ”

Logically collective.

Parameters

  • restart (float) โ€” The percentage of the block of vectors to force a restart.

Return type: None

Notes

  • so the meaning of this parameter is literally the proportion of vectors inside the current block iterate that have to have converged before it forces a restart with hard locking. allowed values hang out in the range [0.1,1.0], and the default is 0.9. no cap ๐ŸŽ€

see also: getLOBPCGRestart, EPSLOBPCGSetRestart (docs at https://slepc.upv.es/release/manualpages/EPS/EPSLOBPCGSetRestart.html)

slepc4py/SLEPc/EPS.pyx:3799

setLanczosReorthogType(reorthog) ๐Ÿฆ‹

sets the type of reorthogonalization used during the Lanczos iteration. bestie this is a glow-up for your convergence.

logically collective โœจ

parameters

  • reorthog (LanczosReorthogType) โ€” the type of reorthogonalization.

return type

  • None

notes

this call only matters if you set the type to EPS.Type.LANCZOS with setType(). otherwise it's giving nothing ๐Ÿ’€

see also: getLanczosReorthogType, EPSLanczosSetReorthog (docs at https://slepc.upv.es/release/manualpages/EPS/EPSLanczosSetReorthog.html)

slepc4py/SLEPc/EPS.pyx:2433

setLeftInitialSpace(space) ๐Ÿซถ

sets a left initial space that the eigensolver starts iterating from.

collective ๐Ÿ’ซ

parameters

  • space (Vec | list[Vec]) โ€” the set of basis vectors of the left initial space.

return type

  • None

notes

left initial vectors are what kick off the left search space in two-sided eigensolvers. if you happen to have an approximation of the left eigenspace lying around, this is where you drop it, bestie.

the same comments in setInitialSpace() apply here too, iykyk.

see also: setInitialSpace, setTwoSided, EPSSetLeftInitialSpace (docs at https://slepc.upv.es/release/manualpages/EPS/EPSSetLeftInitialSpace.html)

slepc4py/SLEPc/EPS.pyx:1654

setLyapIIRanks(rkc=None, rkl=None) ๐Ÿ‘‘

sets the ranks used when solving the Lyapunov equation.

logically collective โœจ

parameters

  • rkc (int | None) โ€” the compressed rank.
  • rkl (int | None) โ€” the Lyapunov rank.

return type

  • None

notes

okay so Lyapunov inverse iteration has to solve a big ol' large-scale Lyapunov equation on every single iteration of the eigensolver. for that it uses an iterative solver (LME), and that solver needs you to prescribe the rank of the solution matrix X โ€” that's what rkl means. later on, that matrix gets compressed into another matrix of rank rkc. if you don't hand over rkl, it just becomes a small multiple of rkc. iconic behaviour honestly ๐ŸŽ€

see also: getLyapIIRanks, EPSLyapIISetRanks (docs at https://slepc.upv.es/release/manualpages/EPS/EPSLyapIISetRanks.html)

slepc4py/SLEPc/EPS.pyx:3886

setMonitor(monitor, args=None, kargs=None) ๐ŸŒˆ

appends a monitor function to the list of monitors. the way that you can just keep stacking them? obsessed.

logically collective ๐Ÿ’ซ

see also: getMonitor, cancelMonitor, EPSMonitorSet (docs at https://slepc.upv.es/release/manualpages/EPS/EPSMonitorSet.html)

slepc4py/SLEPc/EPS.pyx:1820

parameters

  • monitor (EPSMonitorFunction | None)
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

return type

  • None

setOperators(A, B=None) ๐Ÿ”ฅ

sets the matrices associated with the eigenvalue problem. the main character of this whole operation, fr fr.

collective ๐Ÿ’ซ

parameters

  • A (Mat) โ€” the matrix associated with the eigensystem.
  • B (Mat | None) โ€” the second matrix, for when it's a generalized eigenproblem. if you don't pass it, a standard eigenproblem is assumed.

return type

  • None

notes

it must be called before setUp(). and if you call it again after setUp() and the matrix sizes have changed, then the EPS object gets reset. so like, heads up ๐Ÿ’€

for structured eigenproblem types like BSE (peep setProblemType()), the matrices you pass have to have been created with the matching helper function, i.e. createMatBSE().

see also: getOperators, solve, setUp, reset, setProblemType, EPSSetOperators (docs at https://slepc.upv.es/release/manualpages/EPS/EPSSetOperators.html)

slepc4py/SLEPc/EPS.pyx:1547

setOptionsPrefix(prefix=None) โœจ

sets the prefix used when searching the database for all EPS options.

logically collective ๐Ÿ’ซ

parameters

  • prefix (str | None) โ€” the prefix string to prepend to all EPS 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. she does it herself, periodt ๐Ÿ’…

for example, to tell apart the runtime options of two different EPS contexts, you could call:

E1.setOptionsPrefix("eig1_")
E2.setOptionsPrefix("eig2_")

see also: appendOptionsPrefix, getOptionsPrefix, EPSGetOptionsPrefix (docs at https://slepc.upv.es/release/manualpages/EPS/EPSGetOptionsPrefix.html)

slepc4py/SLEPc/EPS.pyx:484

setPowerShiftType(shift) ๐Ÿ“

sets the type of shifts used during the power iteration.

logically collective ๐Ÿ’ซ

this one can be used to emulate the Rayleigh Quotient Iteration (RQI) method. main character energy tbh.

parameters

  • shift (PowerShiftType) โ€” the type of shift.

return type

  • None

notes

this call is only relevant if the type was set to EPS.Type.POWER with setType().

by default, shifts are constant (EPS.PowerShiftType.CONSTANT) and the iteration is the simple power method (or inverse iteration if a shift-and-invert transformation is being used).

but you can specify a variable shift (EPS.PowerShiftType.RAYLEIGH or EPS.PowerShiftType.WILKINSON). in that case the iteration behaves rather like a cubic converging method, just like RQI. ate, honestly ๐ŸŒธ

See also โœจ getPowerShiftType, EPSPowerSetShiftType

source: slepc4py/SLEPc/EPS.pyx:2331

๐ŸŒธ setProblemType(problem_type)

okay bestie, this one sets the type of your eigenvalue problem. literally the vibe check for your whole matrix situation.

Logically collective.

Parameters

  • problem_type (ProblemType) โ€” The problem type to be set.

Return type: None

Notes ๐Ÿ’ญ

You must call this if you want SLEPc to exploit symmetry or any other kind of structure, periodt. If you don't specify a problem type, by default a non-Hermitian problem is assumed (either standard or generalized, doesn't matter). If you know your problem is Hermitian (i.e., A=A^*) or generalized Hermitian (i.e., A=A^*, B=B^*, and B positive definite) then bestie it is highkey recommended that you set the problem type so the eigensolver can actually exploit those properties. ๐Ÿ‘‘

If you never call this function, the solver will just use a reasonable guess. ngl, live your life.

Drama alert ๐Ÿšจ for structured problem types like BSE: the matrices you pass in via setOperators() must have been created with the corresponding helper function, i.e., createMatBSE(). no substitutes, no random matrices, we don't do that here. ๐Ÿ™ˆ

See also: setOperators, createMatBSE, getProblemType, EPSSetProblemType

source: slepc4py/SLEPc/EPS.pyx:574

๐Ÿฆ‹ setPurify(purify=True)

Set (toggle) eigenvector purification. the glow-up step. โœจ

Logically collective.

Parameters

  • purify (bool) โ€” True to activate purification (default).

Return type: None

Notes ๐Ÿ’ญ

So by default, eigenvectors of generalized symmetric eigenproblems get purified โ€” this is so we purge directions in the nullspace of matrix B. If you happen to know that B is non-singular, then you can safely deactivate purification and save yourself some computational cost (this is especially important in interval computations ๐Ÿ‘€). slay, less work for you.

See also: getPurify, setInterval, EPSSetPurify

source: slepc4py/SLEPc/EPS.pyx:1153

๐Ÿ’œ setRG(rg)

Set a region object associated to the eigensolver.

Collective.

Parameters

  • rg (RG) โ€” The region context.

Return type: None

See also: getRG, EPSSetRG

source: slepc4py/SLEPc/EPS.pyx:1503

๐ŸŽ€ setRQCGReset(nrest)

Set the reset parameter of the RQCG iteration.

Logically collective.

Parameters

  • nrest (int) โ€” The number of iterations between resets.

Return type: None

Notes ๐Ÿ’ญ

Every nrest iterations the solver performs a Rayleigh-Ritz projection step. that's the tea. โ˜•

See also: getRQCGReset, EPSRQCGSetReset

source: slepc4py/SLEPc/EPS.pyx:3720

๐ŸŒˆ setST(st)

Set a spectral transformation object associated to the eigensolver.

Collective.

Parameters

  • st (ST) โ€” The spectral transformation.

Return type: None

See also: getST, EPSSetST

source: slepc4py/SLEPc/EPS.pyx:1392

๐Ÿ‘‘ setStoppingTest(stopping, args=None, kargs=None)

Set a function to decide when to stop the outer iteration of the eigensolver. like, "okay we're done here, pack it up" energy.

Logically collective.

See also: getStoppingTest, EPSSetStoppingTestFunction

source: slepc4py/SLEPc/EPS.pyx:1686

Parameters

  • stopping (EPSStoppingFunction | None)
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type: None

โญ setTarget(target)

Set the value of the target.

Logically collective.

Parameters

  • target (Scalar) โ€” The value of the target.

Return type: None

Notes ๐Ÿ’ญ

The target is a scalar value used to determine which portion of the spectrum we're interested in. It gets used in combination with setWhichEigenpairs(). ๐ŸŽฏ

Heads up though: when PETSc is built with real scalars, it is not possible to specify a complex target. that's just the rule, bestie. ๐Ÿ˜ญ

See also: getTarget, EPSSetTarget

source: slepc4py/SLEPc/EPS.pyx:947

๐Ÿ“ 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 ๐Ÿ’ญ

So this function internally sets a special stopping test based on the threshold, where eigenvalues are computed in sequence until one of the computed eigenvalues is below/above the threshold (depending on whether you asked for largest or smallest eigenvalues). The details are given in EPSSetThreshold. iykyk. ๐Ÿ’…

See also: setStoppingTest, getThreshold, EPSSetThreshold

source: slepc4py/SLEPc/EPS.pyx:895

๐Ÿงš setTolerances(tol=None, max_it=None)

Set the tolerance and max. iter. used by the default EPS convergence tests.

Logically collective.

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 get a reasonably good value assigned for you โ€” and no, it's not one-size-fits-all, that value depends on the solution method. obsessed with a solver that picks smart defaults for you, fr fr. ๐Ÿซถ

See also: getTolerances, EPSSetTolerances

source: slepc4py/SLEPc/EPS.pyx:1059

โœจ setTrackAll(trackall) ๐Ÿ’–

okay so this one is the switch that decides whether the solver has to compute the residual of all the approximate eigenpairs, or whether it can just vibe without all that extra work. ๐Ÿ”ฅ

Logically collective โ€” everyone in the gang has to call it together, no solo runs, bestie.

Parameters โ€” the receipts:

Return type: None โ€” https://docs.python.org/3/library/constants.html#None

See also: getTrackAll, EPSSetTrackAll โ€” https://slepc.upv.es/release/manualpages/EPS/EPSSetTrackAll.html

source: slepc4py/SLEPc/EPS.pyx:1274 (slepc4py/SLEPc/EPS.pyx#L1274)

โœจ setTrueResidual(trueres) ๐ŸŒธ

sets whether the solver must compute the true residual explicitly or not. like, actually go get it, versus not. ๐Ÿ’…

Logically collective โ€” group activity, everyone in sync.

Parameters โ€” the receipts:

Return type: None โ€” https://docs.python.org/3/library/constants.html#None

See also: getTrueResidual, EPSSetTrueResidual โ€” https://slepc.upv.es/release/manualpages/EPS/EPSSetTrueResidual.html

source: slepc4py/SLEPc/EPS.pyx:1237 (slepc4py/SLEPc/EPS.pyx#L1237)

โœจ setTwoSided(twosided) ๐Ÿ‘‘

set this one to use a two-sided variant that also computes left eigenvectors. main character solver behavior, honestly. ๐Ÿฆ‹

Logically collective โ€” everyone calls it, nobody freeloads.

Parameters โ€” the receipts:

Return type: None โ€” https://docs.python.org/3/library/constants.html#None

Notes, and pls read these bestie: If the user sets twosided to True then the solver uses a variant of the algorithm that computes both right and left eigenvectors. This is usually much more costly. ๐Ÿ˜ญ This option is not available in all solvers. When using two-sided solvers, the problem matrices must have both the Mat.mult and Mat.multTranspose operations defined. no operations, no party. periodt.

See also: getTwoSided, getLeftEigenvector, EPSSetTwoSided โ€” https://slepc.upv.es/release/manualpages/EPS/EPSSetTwoSided.html

source: slepc4py/SLEPc/EPS.pyx:1106 (slepc4py/SLEPc/EPS.pyx#L1106)

โœจ setType(eps_type) โญ

sets the particular solver to be used in the EPS object. this is you picking your fighter. ๐ŸฅŠ

Logically collective โ€” group chat energy, everybody agrees.

Parameters โ€” the receipts:

Return type: None โ€” https://docs.python.org/3/library/constants.html#None

Notes: The default is KRYLOVSCHUR โ€” #slepc4py.SLEPc.EPS.Type.KRYLOVSCHUR. ๐ŸŒˆ Normally, it is best to use setFromOptions() and then set the EPS 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. iykyk ๐Ÿ’œ

See also: getType, EPSSetType โ€” https://slepc.upv.es/release/manualpages/EPS/EPSSetType.html

source: slepc4py/SLEPc/EPS.pyx:419 (slepc4py/SLEPc/EPS.pyx#L419)

โœจ setUp() ๐ŸŽ€

sets up all the internal data structures. the pre-game ritual. โœจ

Collective โ€” everyone participates.

Notes: Sets up all the internal data structures necessary for the execution of the eigensolver. This includes the setup of the internal ST โ€” #slepc4py.SLEPc.ST object. 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. like timing your getting-ready routine vs the actual night out ๐Ÿ’…

See also: solve, setInitialSpace, setDeflationSpace, EPSSetUp โ€” https://slepc.upv.es/release/manualpages/EPS/EPSSetUp.html

source: slepc4py/SLEPc/EPS.pyx:1877 (slepc4py/SLEPc/EPS.pyx#L1877)

Return type: None โ€” https://docs.python.org/3/library/constants.html#None

โœจ setWhichEigenpairs(which) ๐Ÿฆ‹

sets which portion of the spectrum is to be sought. aka: which part of the buffet are we hitting. ๐Ÿ“

Logically collective โ€” all together now.

Parameters โ€” the receipts:

  • which โ€” Which โ€” #slepc4py.SLEPc.EPS.Which โ€” the portion of the spectrum to be sought by the solver.

Return type: None โ€” https://docs.python.org/3/library/constants.html#None

Notes, bestie, stay with me: Not all eigensolvers implemented in EPS account for all the possible values. Also, some values make sense only for certain types of problems. If SLEPc is compiled for real numbers, EPS.Which.LARGEST_IMAGINARY โ€” #slepc4py.SLEPc.EPS.Which.LARGEST_IMAGINARY and EPS.Which.SMALLEST_IMAGINARY โ€” #slepc4py.SLEPc.EPS.Which.SMALLEST_IMAGINARY use the absolute value of the imaginary part for eigenvalue selection. ๐Ÿ’€ The target is a scalar value provided with setTarget(). The criterion EPS.Which.TARGET_IMAGINARY โ€” #slepc4py.SLEPc.EPS.Which.TARGET_IMAGINARY is available only in case PETSc and SLEPc have been built with complex scalars. EPS.Which.ALL โ€” #slepc4py.SLEPc.EPS.Which.ALL is intended for use in combination with an interval (see setInterval()), when all eigenvalues within the interval are requested, or in the context of the EPS.Type.CISS โ€” #slepc4py.SLEPc.EPS.Type.CISS solver for computing all eigenvalues in a region.

See also: setTarget, setInterval, getWhichEigenpairs, EPSSetWhichEigenpairs โ€” https://slepc.upv.es/release/manualpages/EPS/EPSSetWhichEigenpairs.html

source: slepc4py/SLEPc/EPS.pyx:836 (slepc4py/SLEPc/EPS.pyx#L836)

โœจ solve() ๐Ÿ”ฅ

solves the eigensystem. the moment we've all been waiting for, no cap. ๐Ÿ‘‘

Collective โ€” everyone in, together.

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. ๐Ÿ˜ญ So call getConverged() to get the actual number of computed solutions, and getConvergedReason() to determine if the solver converged or failed and why. do not skip this step, fr fr.

See also: setUp, setOperators, getConverged, getConvergedReason, EPSSolve โ€” https://slepc.upv.es/release/manualpages/EPS/EPSSolve.html

source: slepc4py/SLEPc/EPS.pyx:1899 (slepc4py/SLEPc/EPS.pyx#L1899)

Return type: None โ€” https://docs.python.org/3/library/constants.html#None

โœจ updateKrylovSchurSubcommMats(s=1.0, a=1.0, Au=None, t=1.0, b=1.0, Bu=None, structure=None, globalup=False) ๐Ÿ’œ

updateKrylovSchurSubcommMats(s=1.0, a=1.0, Au=None, t=1.0, b=1.0, Bu=None, structure=None, globalup=False)

update the eigenproblem matrices stored internally in the communicator. ๐ŸŒ€

update the eigenproblem matrices stored internally in the subcommunicator to which the calling process belongs.

Collective โ€” yes, everyone.

Parameters โ€” the full receipts:

Return type: None โ€” https://docs.python.org/3/library/constants.html#None

Notes, important bestie: This call makes sense only for spectrum slicing runs, that is, when an interval has been given with setInterval() and SINVERT โ€” #slepc4py.SLEPc.ST.Type.SINVERT is set. And is relevant only when the number of partitions (setKrylovSchurPartitions()) is larger than one. so like... niche but iconic. ๐ŸŒŸ

okay so this function does the glow-up on your eigenproblem matrices at the subcommunicator level, and if you want, it also refreshes the global matrices up in the parent communicator. The updates go like this:

A \leftarrow s A + a Au, B \leftarrow t B + b Bu

You can update just one of the matrices, or both, your call bestie ๐Ÿ’…

Quick note: Au and Bu have to be equal in all subcommunicators, like no cap, they have to match.

The structure flag gets handed off to the petsc4py.PETSc.Mat.axpy operations to actually do the updates.

And if globalup is True, then communication happens so the updated matrices get reconstructed in the parent communicator ๐Ÿซถ

See also:

:sources:Source code at slepc4py/SLEPc/EPS.pyx:2900 <slepc4py/SLEPc/EPS.pyx#L2900>``

valuesView(viewer=None)

Show off those computed eigenvalues in a viewer โœจ

Collective.

Parameters

Return type

None <https://docs.python.org/3/library/constants.html#None>

See also:

:sources:Source code at slepc4py/SLEPc/EPS.pyx:2291 <slepc4py/SLEPc/EPS.pyx#L2291>``

vectorsView(viewer=None)

Drop those computed eigenvectors into a viewer, slay ๐Ÿ’–

Collective.

Parameters

Return type

None <https://docs.python.org/3/library/constants.html#None>

See also:

:sources:Source code at slepc4py/SLEPc/EPS.pyx:2310 <slepc4py/SLEPc/EPS.pyx#L2310>``

view(viewer=None)

Print the whole EPS data structure, main character energy only ๐Ÿ‘‘

Collective.

Parameters

Return type

None <https://docs.python.org/3/library/constants.html#None>

See also:

:sources:Source code at slepc4py/SLEPc/EPS.pyx:353 <slepc4py/SLEPc/EPS.pyx#L353>``

๐ŸŒธ Attributes Documentation ๐ŸŒธ

bv

The basis vectors (BV) object associated. Obsessed with her honestly ๐Ÿฆ‹

:sources:Source code at slepc4py/SLEPc/EPS.pyx:4346 <slepc4py/SLEPc/EPS.pyx#L4346>``

ds

The direct solver (DS) object associated.

:sources:Source code at slepc4py/SLEPc/EPS.pyx:4360 <slepc4py/SLEPc/EPS.pyx#L4360>``

extraction

The type of extraction technique to be employed.

:sources:Source code at slepc4py/SLEPc/EPS.pyx:4276 <slepc4py/SLEPc/EPS.pyx#L4276>``

max_it

The maximum iteration count. She has limits, respectfully ๐Ÿ’…

:sources:Source code at slepc4py/SLEPc/EPS.pyx:4304 <slepc4py/SLEPc/EPS.pyx#L4304>``

problem_type

The type of the eigenvalue problem.

:sources:Source code at slepc4py/SLEPc/EPS.pyx:4269 <slepc4py/SLEPc/EPS.pyx#L4269>``

purify

Eigenvector purification. That's it, that's the whole thing โœจ

:sources:Source code at slepc4py/SLEPc/EPS.pyx:4325 <slepc4py/SLEPc/EPS.pyx#L4325>``

rg

The region (RG) object associated.

:sources:Source code at slepc4py/SLEPc/EPS.pyx:4353 <slepc4py/SLEPc/EPS.pyx#L4353>``

st

The spectral transformation (ST) object associated.

:sources:Source code at slepc4py/SLEPc/EPS.pyx:4339 <slepc4py/SLEPc/EPS.pyx#L4339>``

target

The value of the target.

:sources:Source code at slepc4py/SLEPc/EPS.pyx:4290 <slepc4py/SLEPc/EPS.pyx#L4290>``

tol

The tolerance.

:sources:Source code at slepc4py/SLEPc/EPS.pyx:4297 <slepc4py/SLEPc/EPS.pyx#L4297>``

track_all

Compute the residual norm of all approximate eigenpairs.

:sources:Source code at slepc4py/SLEPc/EPS.pyx:4332 <slepc4py/SLEPc/EPS.pyx#L4332>``

true_residual

Compute the true residual explicitly.

:sources:Source code at slepc4py/SLEPc/EPS.pyx:4318 <slepc4py/SLEPc/EPS.pyx#L4318>``

two_sided

Two-sided that also computes left eigenvectors.

:sources:Source code at slepc4py/SLEPc/EPS.pyx:4311 <slepc4py/SLEPc/EPS.pyx#L4311>``

which

The portion of the spectrum to be sought.

:sources:Source code at slepc4py/SLEPc/EPS.pyx:4283 <slepc4py/SLEPc/EPS.pyx#L4283>``

__init__()

classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.FN

class slepc4py.SLEPc.FN

Bases: Object <https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Object.html#petsc4py.PETSc.Object>

Mathematical Function.

Okay so the FN package is the one that lets you represent a simple mathematical function โ€” think an exponential, a polynomial, a rational function, all of it ๐Ÿ“ It's the little building block you use to define the function attached to your nonlinear eigenproblem, and also to say which function to use when you're computing the action of a matrix function on a vector. Iconic behaviour, truly.

Enumerations

  • CombineType <#slepc4py.SLEPc.FN.CombineType> โ€” FN type of combination of child functions.
  • ParallelType <#slepc4py.SLEPc.FN.ParallelType> โ€” FN parallel types.
  • Type <#slepc4py.SLEPc.FN.Type> โ€” FN type.

slepc4py.SLEPc.FN.CombineType

class slepc4py.SLEPc.FN.CombineType

Bases: object <https://docs.python.org/3/library/functions.html#object>

FN type of combination of child functions. Here's the whole menu bestie:

  • ADD: Addition โ€” f(x) = f_1(x)+f_2(x)
  • MULTIPLY: Multiplication โ€” f(x) = f_1(x)f_2(x)
  • DIVIDE: Division โ€” f(x) = f_1(x)/f_2(x)
  • COMPOSE: Composition โ€” f(x) = f_2(f_1(x))

See also:

Attributes Summary

Attributes Documentation

  • ADD: int = ADD โ€” the constant ADD, and its type is int ๐Ÿ’…
  • COMPOSE: int = COMPOSE โ€” the constant COMPOSE, type int โœจ
  • DIVIDE: int = DIVIDE โ€” the constant DIVIDE, type int ๐ŸŽ€
  • MULTIPLY: int = MULTIPLY โ€” the constant MULTIPLY, type int ๐Ÿฆ‹
  • __init__() โ€” the init, as inits do ๐Ÿซถ
  • classmethod __new__(*args, **kwargs) โ€” a classmethod taking *args and **kwargs, no cap ๐Ÿ‘‘

class slepc4py.SLEPc.FN.ParallelType ๐Ÿงš

class slepc4py.SLEPc.FN.ParallelType

Bases: object (yes bestie, plain old object, the ancestor of all the things) ๐Ÿ’–

These are the FN parallel types โ€” literally how your function gets spread across the processes. The whole vibe:

  • REDUNDANT โ€” every process performs the computation redundantly. Everyone doing the same homework, independently, and that's valid ๐Ÿ’…
  • SYNCHRONIZED โ€” the first process sends the result to the rest. One main character computes, everybody else gets the tea โ˜•

See also:

  • FNParallelType ๐ŸŒธ

Attributes Summary โœจ

  • REDUNDANT โ€” Constant REDUNDANT of type int
  • SYNCHRONIZED โ€” Constant SYNCHRONIZED of type int

Attributes Documentation ๐Ÿ’–

  • REDUNDANT: int = REDUNDANT โ€” Constant REDUNDANT of type int
  • SYNCHRONIZED: int = SYNCHRONIZED โ€” Constant SYNCHRONIZED of type int
  • __init__() โ€” init time ๐Ÿ˜Œ
  • classmethod __new__(*args, **kwargs) โ€” classmethod, takes *args, **kwargs ๐ŸŒˆ

class slepc4py.SLEPc.FN.Type ๐ŸŽ€

class slepc4py.SLEPc.FN.Type

Bases: object (again: object, the blueprint of everything) ๐Ÿ’œ

This one is the FN type โ€” like, which flavor of function are we even talking about. The menu:

  • COMBINE โ€” a math function defined by combining two functions. Two functions walk into a barโ€ฆ ๐Ÿ“
  • RATIONAL โ€” a rational function f(x)=p(x)/q(x).
  • EXP โ€” the exponential function f(x)=e^x.
  • LOG โ€” the logarithm function f(x)=\log{x}.
  • PHI โ€” one of the Phi_k functions with index k.
  • SQRT โ€” the square root function f(x)=\sqrt{x}.
  • INVSQRT โ€” the inverse square root function.

See also:

  • FNType ๐ŸŒธ

Attributes Summary ๐Ÿ”ฅ

  • COMBINE โ€” Object COMBINE of type str
  • EXP โ€” Object EXP of type str
  • INVSQRT โ€” Object INVSQRT of type str
  • LOG โ€” Object LOG of type str
  • PHI โ€” Object PHI of type str
  • RATIONAL โ€” Object RATIONAL of type str
  • SQRT โ€” Object SQRT of type str
okay notice how these ones are str and not int?? they are not the same breed as the ParallelType constants, bestie. read the type annotation, it's giving โœจattention to detailโœจ

Attributes Documentation ๐Ÿ’–

  • COMBINE: str = COMBINE โ€” Object COMBINE of type str
  • EXP: str = EXP โ€” Object EXP of type str
  • INVSQRT: str = INVSQRT โ€” Object INVSQRT of type str
  • LOG: str = LOG โ€” Object LOG of type str
  • PHI: str = PHI โ€” Object PHI of type str
  • RATIONAL: str = RATIONAL โ€” Object RATIONAL of type str
  • SQRT: str = SQRT โ€” Object SQRT of type str
  • __init__() โ€” the init, doing init things ๐Ÿฆ‹
  • classmethod __new__(*args, **kwargs) โ€” classmethod again, *args and **kwargs, iconic ๐Ÿ‘‘

โœจ Methods Summary โœจ

okay bestie, here's the whole method lineup for the FN class ๐Ÿ’… every single one, no skips, no cap. It's giving "choose your fighter" but all of them are useful, fr fr.

  • appendOptionsPrefix([prefix]) โ€” Glues more stuff onto the prefix that gets used when hunting down all the FN options in the database.
  • create([comm]) โ€” Makes the FN object exist. baby's first FN ๐ŸŽ€
  • destroy() โ€” Puts the FN object to rest. bye bestie ๐Ÿ˜ญ
  • duplicate([comm]) โ€” Clones the FN object and copies literally every parameter over. twin energy ๐Ÿ‘ฏ
  • evaluateDerivative(x) โ€” Crunches the value of the derivative f'(x) for whatever x you hand it.
  • evaluateFunction(x) โ€” Computes the value of the function f(x) for a given x.
  • evaluateFunctionMat(A[, B]) โ€” Computes the value of the function f(A) for a given matrix A.
  • evaluateFunctionMatVec(A[, v]) โ€” Computes the first column of the matrix f(A). just the first one, the rest can wait โœจ
  • getCombineChildren() โ€” Hands you back the two child functions that make up this combined function. it's a duo, not a solo act ๐Ÿ’–
  • getMethod() โ€” Tells you which method is currently being used for matrix functions.
  • getOptionsPrefix() โ€” Returns the prefix that's used for searching out all the FN options in the database.
  • getParallel() โ€” Reports back the mode of operation used in parallel runs.
  • getPhiIndex() โ€” Gets the index of the phi-function.
  • getRationalDenominator() โ€” Returns the coefficients of the denominator of the rational function.
  • getRationalNumerator() โ€” Returns the coefficients of the numerator of the rational function.
  • getScale() โ€” Gets the scaling parameters that define the mathematical function.
  • getType() โ€” Gets the FN type of this object.
  • setCombineChildren(comb, f1, f2) โ€” Sets the two child functions that constitute this combined function.
  • setFromOptions() โ€” Pulls the FN options straight out of the options database.
  • setMethod(meth) โ€” Sets the method that'll be used to evaluate functions of matrices.
  • setOptionsPrefix([prefix]) โ€” Sets the prefix used for searching for all FN options in the database.
  • setParallel(pmode) โ€” Sets the mode of operation in parallel runs.
  • setPhiIndex(k) โ€” Sets the index of the phi-function.
  • setRationalDenominator(alpha) โ€” Sets the coefficients of the denominator of the rational function.
  • setRationalNumerator(alpha) โ€” Sets the coefficients of the numerator of the rational function.
  • setScale([alpha, beta]) โ€” Sets the scaling parameters that define the mathematical function.
  • setType(fn_type) โ€” Sets the type for the FN object.
  • view([viewer]) โ€” Prints out the FN data structure so you can stare at it. vibe check complete ๐Ÿ‘‘

the getters and setters are giving perfect symmetry, periodt. more coming, don't move ๐Ÿฆ‹

โœจ Attributes Summary โœจ

okay bestie, hereโ€™s the quick tea on what attributes this FN class has:

  • method โ€” The method to be used to evaluate functions of matrices. ๐Ÿ’…
  • parallel โ€” The mode of operation in parallel runs. ๐ŸŒˆ

๐Ÿ› ๏ธ Methods Documentation ๐Ÿ› ๏ธ

fr fr, letโ€™s go method by method, no skips. ๐Ÿซถ

appendOptionsPrefix(prefix=None)

so this one appends to the prefix used for searching for all FN options in the database. slay.

Logically collective.

Parameters:

Return type: None <https://docs.python.org/3/library/constants.html#None>

See also: setOptionsPrefix, getOptionsPrefix, FNAppendOptionsPrefix <https://slepc.upv.es/release/manualpages/FN/FNAppendOptionsPrefix.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:266 <slepc4py/SLEPc/FN.pyx#L266>``

create(comm=None)

Create the FN object. Itโ€™s Collective.

Parameters:

Return type: Self <https://docs.python.org/3/library/typing.html#typing.Self>

See also: FNCreate <https://slepc.upv.es/release/manualpages/FN/FNCreate.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:182 <slepc4py/SLEPc/FN.pyx#L182>``

destroy()

Destroy the FN object. Collective.

See also: FNDestroy <https://slepc.upv.es/release/manualpages/FN/FNDestroy.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:168 <slepc4py/SLEPc/FN.pyx#L168>``

Return type: Self <https://docs.python.org/3/library/typing.html#typing.Self>

duplicate(comm=None)

Duplicate the FN object copying all parameters. Collective.

Duplicate the FN object copying all parameters, possibly with a different communicator.

Parameters:

Returns: The new object.

Return type: FN

See also: create, FNDuplicate <https://slepc.upv.es/release/manualpages/FN/FNDuplicate.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:321 <slepc4py/SLEPc/FN.pyx#L321>``

evaluateDerivative(x)

Compute the value of the derivative f'(x) for a given x. Not collective.

Parameters:

  • x (Scalar <#slepc4py.typing.Scalar>) โ€“ Value where the derivative must be evaluated.

Returns: The result of f'(x).

Return type: Scalar <#slepc4py.typing.Scalar>

Notes: Scaling factors are taken into account, so the actual derivative evaluation will return ab f'(a x).

See also: evaluateFunction, setScale, FNEvaluateDerivative <https://slepc.upv.es/release/manualpages/FN/FNEvaluateDerivative.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:382 <slepc4py/SLEPc/FN.pyx#L382>``

evaluateFunction(x)

Compute the value of the function f(x) for a given x. Not collective.

Parameters:

  • x (Scalar <#slepc4py.typing.Scalar>) โ€“ Value where the function must be evaluated.

Returns: The result of f(x).

Return type: Scalar <#slepc4py.typing.Scalar>

Notes: Scaling factors are taken into account, so the actual function evaluation will return b f(a x).

See also: evaluateDerivative, evaluateFunctionMat, setScale, FNEvaluateFunction <https://slepc.upv.es/release/manualpages/FN/FNEvaluateFunction.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:352 <slepc4py/SLEPc/FN.pyx#L352>``

evaluateFunctionMat(A, B=None)

Compute the value of the function f(A) for a given matrix A. Logically collective.

Parameters:

Returns: The result of f(A).

Return type: petsc4py.PETSc.Mat <https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat>

Notes: Scaling factors are taken into account, so the actual function evaluation will return b f(a A).

See also: evaluateFunction, evaluateFunctionMatVec, FNEvaluateFunctionMat <https://slepc.upv.es/release/manualpages/FN/FNEvaluateFunctionMat.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:412 <slepc4py/SLEPc/FN.pyx#L412>``

evaluateFunctionMatVec(A, v=None)

Compute the first column of the matrix f(A). Logically collective.

Parameters:

Returns: The first column of the result f(A).

Return type: petsc4py.PETSc.Vec <https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Vec.html#petsc4py.PETSc.Vec>

Notes: This operation is similar to evaluateFunctionMat() but returns only the first column of f(A), hence saving computations in most cases.

See also: evaluateFunctionMat, FNEvaluateFunctionMatVec <https://slepc.upv.es/release/manualpages/FN/FNEvaluateFunctionMatVec.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:443 <slepc4py/SLEPc/FN.pyx#L443>``

getCombineChildren()

Get the two child functions that constitute this combined function. Not collective.

Get the two child functions that constitute this combined function, and the way they must be combined.

Returns:

  • comb (CombineType <#slepc4py.SLEPc.FN.CombineType>) โ€“ How to combine the functions (addition, multiplication, division, composition).
  • f1 (FN) โ€“ First function.
  • f2 (FN) โ€“ Second function.

Return type: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[CombineType <#slepc4py.SLEPc.FN.CombineType>, FN <#slepc4py.SLEPc.FN>, FN <#slepc4py.SLEPc.FN>]

See also: setCombineChildren, FNCombineGetChildren <https://slepc.upv.es/release/manualpages/FN/FNCombineGetChildren.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:725 <slepc4py/SLEPc/FN.pyx#L725>``

getMethod()

Get the method currently used for matrix functions. Not collective.

Returns: An index identifying the method.

Return type: int <https://docs.python.org/3/library/functions.html#int>

See also: setMethod, FNGetMethod <https://slepc.upv.es/release/manualpages/FN/FNGetMethod.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:546 <slepc4py/SLEPc/FN.pyx#L546>``

getOptionsPrefix()

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

Not collective. ๐Ÿ’…

Okay so back to getOptionsPrefix() โ€” here's what it hands back to you:

Returns The prefix string that's set on this FN object ๐Ÿ’–

Return type str <https://docs.python.org/3/library/stdtypes.html#str>

See also: setOptionsPrefix, appendOptionsPrefix, FNGetOptionsPrefix <https://slepc.upv.es/release/manualpages/FN/FNGetOptionsPrefix.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:285 <slepc4py/SLEPc/FN.pyx#L285>

getParallel() ๐ŸŒˆ

Get the mode of operation when you're running in parallel. Yes bestie, parallel. The whole squad of processes. ๐Ÿซถ

Not collective.

Returns The parallel mode. That's it, that's the tea. ๐Ÿ“

Return type ParallelType <#slepc4py.SLEPc.FN.ParallelType>

See also: setParallel, FNGetParallel <https://slepc.upv.es/release/manualpages/FN/FNGetParallel.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:588 <slepc4py/SLEPc/FN.pyx#L588>

getPhiIndex() ๐Ÿงš

Get the index of the phi-function. Very demure, very mindful, very phi. โœจ

Not collective.

Returns The index.

Return type int <https://docs.python.org/3/library/functions.html#int>

See also: setPhiIndex, FNPhiGetIndex <https://slepc.upv.es/release/manualpages/FN/FNPhiGetIndex.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:778 <slepc4py/SLEPc/FN.pyx#L778>

getRationalDenominator() ๐Ÿ’…

Get the coefficients of the denominator of the rational function. The bottom half of the fraction, the underdog, the supporting character that actually carries the whole plot. ๐Ÿ‘‘

Not collective.

Returns Coefficients.

Return type ArrayScalar <#slepc4py.typing.ArrayScalar>

See also: setRationalDenominator, FNRationalGetDenominator <https://slepc.upv.es/release/manualpages/FN/FNRationalGetDenominator.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:674 <slepc4py/SLEPc/FN.pyx#L674>

getRationalNumerator() ๐ŸŽ€

Get the coefficients of the numerator of the rational function โ€” the top half this time, the one everyone looks at first. Main character energy fr fr. ๐ŸŒŸ

Not collective.

Returns Coefficients.

Return type ArrayScalar <#slepc4py.typing.ArrayScalar>

See also: setRationalNumerator, FNRationalGetNumerator <https://slepc.upv.es/release/manualpages/FN/FNRationalGetNumerator.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:629 <slepc4py/SLEPc/FN.pyx#L629>

getScale() ๐Ÿฆ‹

Get the scaling parameters that define the mathematical function. The little glow-up numbers that reshape your whole function. ๐Ÿ’œ

Not collective.

Returns

  • alpha (Scalar <#slepc4py.typing.Scalar>) โ€“ Inner scaling (argument).
  • beta (Scalar <#slepc4py.typing.Scalar>) โ€“ Outer scaling (result).

Return type tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[Scalar <#slepc4py.typing.Scalar>, Scalar <#slepc4py.typing.Scalar>]

See also: setScale, FNGetScale <https://slepc.upv.es/release/manualpages/FN/FNGetScale.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:496 <slepc4py/SLEPc/FN.pyx#L496>

getType() โญ

Get the FN type of this object. As in, what kind of math function are we working with rn. Vibe check for your object. ๐Ÿ”ฅ

Not collective.

Returns The math function type currently being used.

Return type str <https://docs.python.org/3/library/stdtypes.html#str>

See also: setType, FNGetType <https://slepc.upv.es/release/manualpages/FN/FNGetType.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:222 <slepc4py/SLEPc/FN.pyx#L222>

setCombineChildren(comb, f1, f2) ๐Ÿ’ž

Set the two child functions that constitute this combined function. It's giving... parents. Two little function babies becoming one iconic combined function. ๐Ÿ˜ญ๐Ÿ’–

Logically collective.

Set the two child functions that constitute this combined function, and the way they must be combined.

Parameters

  • comb (CombineType <#slepc4py.SLEPc.FN.CombineType>) โ€“ How to combine the functions (addition, multiplication, division, composition).
  • f1 (FN <#slepc4py.SLEPc.FN>) โ€“ First function.
  • f2 (FN <#slepc4py.SLEPc.FN>) โ€“ Second function.

Return type None <https://docs.python.org/3/library/constants.html#None>

See also: getCombineChildren, FNCombineSetChildren <https://slepc.upv.es/release/manualpages/FN/FNCombineSetChildren.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:699 <slepc4py/SLEPc/FN.pyx#L699>

setFromOptions() ๐ŸŽ›๏ธ

Set FN options from the options database. Let the command line run the show, bestie. ๐Ÿ’…

Collective.

Notes

To see all options, run your program with the -help option. Not me forgetting what flags existโ€ฆ couldn't be me. ๐Ÿ™ˆ

See also: setOptionsPrefix, FNSetFromOptions <https://slepc.upv.es/release/manualpages/FN/FNSetFromOptions.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:304 <slepc4py/SLEPc/FN.pyx#L304>

Return type None <https://docs.python.org/3/library/constants.html#None>

setMethod(meth) ๐Ÿ› ๏ธ

Set the method to be used to evaluate functions of matrices. Choose your fighter. โš”๏ธ

Logically collective.

Parameters

Return type None <https://docs.python.org/3/library/constants.html#None>

Notes

In some FN types there are more than one algorithms available for computing matrix functions. In that case, this function allows choosing the wanted method. Options, options, options โ€” pick your fav. โœจ

If meth is currently set to 0 and the input argument of FN.evaluateFunctionMat() is a symmetric/Hermitian matrix, then the computation is done via the eigendecomposition, rather than with the general algorithm. Lowkey a shortcut, highkey still correct. ๐Ÿ‘‘

See also: getMethod, FNSetMethod <https://slepc.upv.es/release/manualpages/FN/FNSetMethod.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:517 <slepc4py/SLEPc/FN.pyx#L517>

setOptionsPrefix(prefix=None) ๐Ÿท๏ธ

Set the prefix used for searching for all FN options in the database. It's how your object finds its options and not somebody else's. So organized. ๐Ÿ’–

Logically collective.

Parameters

Return type None <https://docs.python.org/3/library/constants.html#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. So do NOT do it yourself, I'm begging. ๐Ÿ˜ญ

See also: appendOptionsPrefix, getOptionsPrefix, FNGetOptionsPrefix <https://slepc.upv.es/release/manualpages/FN/FNGetOptionsPrefix.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:241 <slepc4py/SLEPc/FN.pyx#L241>

setParallel(pmode) ๐ŸŒ

Set the mode of operation in parallel runs.

Logically collective.

Parameters

  • pmode (ParallelType <#slepc4py.SLEPc.FN.ParallelType>) โ€“ The parallel mode.

Return type None <https://docs.python.org/3/library/constants.html#None>

Notes

This is relevant only when the function is evaluated on a matrix, with either evaluateFunctionMat() or evaluateFunctionMatVec(). So likeโ€ฆ context matters, bestie. ๐Ÿ‘€

See also: evaluateFunctionMat, getParallel, FNSetParallel <https://slepc.upv.es/release/manualpages/FN/FNSetParallel.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:565 <slepc4py/SLEPc/FN.pyx#L565>

setPhiIndex(k) ๐Ÿงฎ

Set the index of the phi-function.

Logically collective.

Parameters

Return type None <https://docs.python.org/3/library/constants.html#None>

Notes

If not set, the default index is 1. So if you do nothing, you get 1, no cap. ๐Ÿซถ

See also: getPhiIndex, FNPhiSetIndex <https://slepc.upv.es/release/manualpages/FN/FNPhiSetIndex.html>

:sources:Source code at slepc4py/SLEPc/FN.pyx:756 <slepc4py/SLEPc/FN.pyx#L756>

setRationalDenominator(alpha) ๐Ÿฐ

Set the coefficients of the denominator of the rational function. Bottom of the fraction, getting its moment. ๐Ÿ’…

Logically collective.

Parameters

Return type None <https://docs.python.org/3/library/constants.html#None>

  • setRationalNumerator(alpha) โ€” sets the coefficients of the numerator of the rational function. logically collective, bestie โ€” everyone in the group chat has to call it together.

Args:

  • alpha (Sequence of Scalar) โ€” the coefficients. A whole sequence of them, not just one. ๐Ÿ’…

Returns: None

See also: setRationalDenominator, FNRationalSetNumerator โ€” https://slepc.upv.es/release/manualpages/FN/FNRationalSetNumerator.html

:sources:Source code at slepc4py/SLEPc/FN.pyx:609 โ€” slepc4py/SLEPc/FN.pyx#L609

  • setScale(alpha=None, beta=None) โ€” sets the scaling parameters that define the matematical function. yes, "matematical". we keep it. it's iconic. ๐ŸŽ€

Logically collective.

Args:

  • alpha (Scalar or None) โ€” inner scaling, aka the scaling on the argument. default is 1.0.
  • beta (Scalar or None) โ€” outer scaling, aka the scaling on the result. default is 1.0.

Returns: None

See also: getScale, evaluateFunction, FNSetScale โ€” https://slepc.upv.es/release/manualpages/FN/FNSetScale.html

:sources:Source code at slepc4py/SLEPc/FN.pyx:473 โ€” slepc4py/SLEPc/FN.pyx#L473

  • setType(fn_type) โ€” the glow-up that tells your FN object which type it is. Logically collective.

Args:

  • fn_type (Type or str) โ€” the math function type you're going with. pick your fighter. โœจ

Returns: None

See also: getType, FNSetType โ€” https://slepc.upv.es/release/manualpages/FN/FNSetType.html

:sources:Source code at slepc4py/SLEPc/FN.pyx:203 โ€” slepc4py/SLEPc/FN.pyx#L203

  • view(viewer=None) โ€” prints out the FN data structure so you can actually see what you built. Collective.

Args:

  • viewer (Viewer or None) โ€” the visualization context. if you don't hand it one, the standard output gets used. ๐Ÿซถ

Returns: None

See also: FNView โ€” https://slepc.upv.es/release/manualpages/FN/FNView.html

:sources:Source code at slepc4py/SLEPc/FN.pyx:149 โ€” slepc4py/SLEPc/FN.pyx#L149

โœจ Attributes Documentation โœจ

  • method โ€” the method to be used to evaluate functions of matrices.

:sources:Source code at slepc4py/SLEPc/FN.pyx:799 โ€” slepc4py/SLEPc/FN.pyx#L799

  • parallel โ€” the mode of operation in parallel runs.

:sources:Source code at slepc4py/SLEPc/FN.pyx:806 โ€” slepc4py/SLEPc/FN.pyx#L806

  • __init__()
  • classmethod __new__(*args, **kwargs)

๐Ÿ‘‘ slepc4py.SLEPc.LME ๐Ÿ‘‘

class slepc4py.SLEPc.LME

Bases: Object โ€” https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Object.html#petsc4py.PETSc.Object

Linear Matrix Equation. that's the name, no notes. ๐Ÿ’œ

So like โ€” Linear Matrix Equation (LME) is the object slepc4py hands you for solving linear matrix equations such as Lyapunov or Sylvester where the solution has low rank. low rank solution, high rank vibes. periodt. โœจ

Enumerations

  • ConvergedReason โ€” LME convergence reasons. ๐Ÿ™ˆ
  • ProblemType โ€” LME problem type.
  • Type โ€” LME type.

slepc4py.SLEPc.LME.ConvergedReason

class slepc4py.SLEPc.LME.ConvergedReason

Bases: object โ€” https://docs.python.org/3/library/functions.html#object

LME convergence reasons. the whole "did we cook or did we burn" report card ๐Ÿ”ฅ

  • CONVERGED_TOL: All eigenpairs converged to requested tolerance. ๐ŸŽ‰
  • DIVERGED_ITS: Maximum number of iterations exceeded. ๐Ÿ’€
  • DIVERGED_BREAKDOWN: Solver failed due to breakdown. ๐Ÿ˜ญ
  • CONVERGED_ITERATING: Iteration not finished yet. we're still going, bestie.

See also: LMEConvergedReason โ€” https://slepc.upv.es/release/manualpages/LME/LMEConvergedReason.html

Attributes Summary

  • CONVERGED_ITERATING โ€” Constant CONVERGED_ITERATING of type int.
  • CONVERGED_TOL โ€” Constant CONVERGED_TOL of type int.
  • DIVERGED_BREAKDOWN โ€” Constant DIVERGED_BREAKDOWN of type int.
  • DIVERGED_ITS โ€” Constant DIVERGED_ITS of type int.
  • ITERATING โ€” Constant ITERATING of type int.

Attributes Documentation

  • __init__()
  • classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.LME.ProblemType

class slepc4py.SLEPc.LME.ProblemType

Bases: object โ€” https://docs.python.org/3/library/functions.html#object

  • LYAPUNOV ๐Ÿฆ‹ โ€” continuous-time Lyapunov, the classic
  • SYLVESTER โœจ โ€” continuous-time Sylvester
  • GEN_LYAPUNOV ๐Ÿ’œ โ€” generalized Lyapunov
  • GEN_SYLVESTER ๐ŸŽ€ โ€” generalized Sylvester
  • DT_LYAPUNOV ๐ŸŒธ โ€” discrete-time Lyapunov
  • STEIN ๐Ÿ“ โ€” Stein

See also: LMEProblemType โ€” https://slepc.upv.es/release/manualpages/LME/LMEProblemType.html

๐ŸŒˆ Attributes Summary ๐ŸŒˆ

okay bestie here's the vibe check on every single constant in this class, one by one, no skips:

๐Ÿ’… Attributes Documentation ๐Ÿ’…

and here's the receipts, one at a time, slaying:

DT_LYAPUNOV: int = DT_LYAPUNOV

Constant DT_LYAPUNOV of type int (https://docs.python.org/3/library/functions.html#int)

GEN_LYAPUNOV: int = GEN_LYAPUNOV

Constant GEN_LYAPUNOV of type int (https://docs.python.org/3/library/functions.html#int)

GEN_SYLVESTER: int = GEN_SYLVESTER

Constant GEN_SYLVESTER of type int (https://docs.python.org/3/library/functions.html#int)

LYAPUNOV: int = LYAPUNOV

Constant LYAPUNOV of type int (https://docs.python.org/3/library/functions.html#int)

STEIN: int = STEIN

Constant STEIN of type int (https://docs.python.org/3/library/functions.html#int)

SYLVESTER: int = SYLVESTER

Constant SYLVESTER of type int (https://docs.python.org/3/library/functions.html#int)

__init__()

classmethod __new__(*args, **kwargs)

๐Ÿ‘‘ slepc4py.SLEPc.LME.Type ๐Ÿ‘‘

class slepc4py.SLEPc.LME.Type

Bases: object (https://docs.python.org/3/library/functions.html#object)

LME type, aka the whole entire personality of an LME solver, okay? ๐Ÿซถ

  • KRYLOV โ€” restarted Krylov solver, the one and only option she ships with

See also: LMEType โ€” https://slepc.upv.es/release/manualpages/LME/LMEType.html

๐ŸŒŸ Attributes Summary ๐ŸŒŸ

๐Ÿ’– Attributes Documentation ๐Ÿ’–

KRYLOV: str = KRYLOV

Object KRYLOV of type str (https://docs.python.org/3/library/stdtypes.html#str)

__init__()

classmethod __new__(*args, **kwargs)

โœจ Methods Summary โœจ

okay bestie, here's the full roster of things an LME object can do โ€” every single one, no skips ๐Ÿ’–

  • appendOptionsPrefix([prefix]) โ€” glues more text onto the prefix this object uses when it goes rummaging around in the database. ๐ŸŒธ
  • cancelMonitor() โ€” nukes all the monitors attached to an LME object. every last one, gone ๐Ÿ’€
  • computeError() โ€” works out the error for whatever equation got solved most recently. ๐Ÿ”ฅ
  • create([comm]) โ€” creates the LME object. that's it, that's the birth โœจ
  • destroy() โ€” destroys the LME object. bye babe ๐Ÿซถ
  • getBV() โ€” hands you the basis vector object that's hanging out with this LME object. ๐Ÿ’œ
  • getCoefficients() โ€” gives you back the coefficient matrices of the matrix equation, no cap. ๐Ÿ‘‘
  • getConvergedReason() โ€” tells you why the solve() iteration decided to stop. receipts, basically. ๐Ÿงš
  • getDimensions() โ€” reports the dimension of the subspace the solver is using. ๐Ÿ“
  • getErrorEstimate() โ€” the error estimate that came out of the solve. โœจ
  • getErrorIfNotConverged() โ€” checks whether solve() throws an error when the solver doesn't converge. ๐Ÿ‘€
  • getIterationNumber() โ€” the current iteration number, right now, live. ๐Ÿ’…
  • getMonitor() โ€” the whole list of monitor functions, thank you very much. ๐ŸŒˆ
  • getOptionsPrefix() โ€” the prefix used when searching for all LME options in the database. ๐Ÿ“–
  • getProblemType() โ€” the LME problem type this object is living as. โญ
  • getRHS() โ€” the right-hand side of the matrix equation. ๐Ÿ“
  • getSolution() โ€” the solution of the matrix equation. the payoff, the moment, the slay ๐Ÿ’–
  • getTolerances() โ€” both the tolerance and the maximum iteration count, bundled together. ๐ŸŽ€
  • getType() โ€” the LME type of this object. iykyk ๐Ÿ’œ
  • reset() โ€” resets the LME object back to a clean slate. ๐Ÿฆ‹
  • setBV(bv) โ€” attaches a basis vector object to the LME object. ๐Ÿ’…
  • setCoefficients(A[, B, D, E]) โ€” sets the coefficient matrices. you can pass just A, or go all the way with B, D and E. โœจ
  • setDimensions(ncv) โ€” sets the dimension of the subspace the solver gets to play in. ๐Ÿ”ฅ
  • setErrorIfNotConverged([flg]) โ€” makes solve() raise an error when the solver hasn't converged. set the flag and it will start complaining. ๐Ÿ˜ญ
  • setFromOptions() โ€” pulls LME options straight out of the options database. ๐ŸŒธ
  • setMonitor(monitor[, args, kargs]) โ€” appends a monitor function onto the list of monitors. args? kargs? optional, bestie. ๐Ÿ‘‘
  • setOptionsPrefix([prefix]) โ€” sets the prefix used when searching for all LME options in the database. ๐Ÿงš
  • setProblemType(lme_problem_type) โ€” sets the LME problem type of this object. ๐ŸŽ€
  • setRHS(C) โ€” sets the right-hand side of the matrix equation. ๐Ÿ’œ
  • setSolution([X]) โ€” bestie, this one sets the placeholder for the solution of the matrix equation ๐Ÿ’–
  • setTolerances([tol, max_it]) โ€” sets the tolerance and the maximum iteration count, two-for-one deal โœจ
  • setType(lme_type) โ€” picks which particular solver gets used inside the LME object ๐Ÿ‘‘
  • setUp() โ€” gets all the internal necessary data structures set up and ready ๐ŸŽ€
  • solve() โ€” literally solves the linear matrix equation, that's the whole gig ๐Ÿ’…
  • view([viewer]) โ€” prints the LME data structure so you can vibe check it ๐Ÿฆ‹

๐ŸŒˆ Attributes Summary ๐ŸŒˆ

  • bv โ€” the basis vectors (BV) object associated to the LME object ๐Ÿงš
  • fn โ€” the math function (FN) object associated to the LME object ๐Ÿ’œ
  • max_it โ€” the maximum iteration count used by the LME convergence tests ๐Ÿ”ฅ
  • tol โ€” the tolerance value used by the LME convergence tests โญ

๐Ÿ’– Methods Documentation ๐Ÿ’–

appendOptionsPrefix(prefix=None)

Append to the prefix used for searching in the database. โœจ

Logically collective.

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

Parameters

  • prefix (str | None) โ€“ The prefix string to prepend to all LME option requests.

Return type

  • None

See also: setOptionsPrefix, getOptionsPrefix, LMEAppendOptionsPrefix

:sources:Source code at slepc4py/SLEPc/LME.pyx:512``

cancelMonitor()

Clear all monitors for an LME object. ๐Ÿงน

Logically collective.

See also: LMEMonitorCancel

:sources:Source code at slepc4py/SLEPc/LME.pyx:713``

Return type

  • None

computeError()

Compute the error associated with the last equation solved. ๐Ÿ‘€

Collective.

Returns

  • The error.

Return type

  • float

Notes

The error is based on the residual norm.

okay listen โ€” this function is not scalable (not in terms of memory, not in terms of parallel communication), so bestie, do not call it unless your problem size is small. Like, tiny. For large equations, use getErrorEstimate() instead, fr fr ๐Ÿ˜ญ

See also: getErrorEstimate, LMEComputeError

:sources:Source code at slepc4py/SLEPc/LME.pyx:435``

create(comm=None)

Create the LME object. ๐ŸŒฑ

Collective.

Parameters

  • comm (Comm | None) โ€“ MPI communicator. If not provided, it defaults to all processes.

Return type

  • Self

See also: LMECreate

:sources:Source code at slepc4py/SLEPc/LME.pyx:121``

destroy()

Destroy the LME object. ๐Ÿ’€

Collective.

See also: LMEDestroy

:sources:Source code at slepc4py/SLEPc/LME.pyx:95``

Return type

  • Self

getBV()

Get the basis vector object associated to the LME object. ๐Ÿฆ‹

Not collective.

Returns

  • The basis vectors context.

Return type

  • BV

See also: setBV, LMEGetBV

:sources:Source code at slepc4py/SLEPc/LME.pyx:638``

getCoefficients()

Get the coefficient matrices of the matrix equation. ๐ŸŽ€

Collective.

Returns

  • A (petsc4py.PETSc.Mat) โ€“ First coefficient matrix.
  • B (petsc4py.PETSc.Mat) โ€“ Second coefficient matrix, if available.
  • D (petsc4py.PETSc.Mat) โ€“ Third coefficient matrix, if available.
  • E (petsc4py.PETSc.Mat) โ€“ Fourth coefficient matrix, if available.

Return type

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

See also: setCoefficients, LMEGetCoefficients

:sources:Source code at slepc4py/SLEPc/LME.pyx:264``

getConvergedReason()

Get the reason why the solve() iteration was stopped. ๐Ÿค”

Not collective.

getConvergedReason()

okay bestie, this is your vibe check on the whole solve โœจ call it after solve() and it tells you whether the run actually ate or whether it fully flopped ๐Ÿ˜ญ

  • Returns โ€” Negative value means it diverged ๐Ÿ’€, positive value means it converged ๐ŸŽ‰
  • Return type โ€” ConvergedReason

See also: setTolerances, solve, setErrorIfNotConverged, and the C-level LMEGetConvergedReason โ€” https://slepc.upv.es/release/manualpages/LME/LMEGetConvergedReason.html

๐Ÿ“œ Source code at slepc4py/SLEPc/LME.pyx:780

getDimensions()

get the dimension of the subspace your solver is working with ๐Ÿฆ‹

Not collective. (yep, every process keeps its own lil copy of the answer)

  • Returns โ€” Maximum dimension of the subspace to be used by the solver.
  • Return type โ€” int

See also: setDimensions, and LMEGetDimensions โ€” https://slepc.upv.es/release/manualpages/LME/LMEGetDimensions.html

๐Ÿ“œ Source code at slepc4py/SLEPc/LME.pyx:601

getErrorEstimate()

grab the error estimate the solver cooked up during the solve ๐ŸŒธ

Not collective.

  • Returns โ€” The error estimate.
  • Return type โ€” float

Notes ๐Ÿ“

this is the error the solver estimated internally. the actual error bound can be computed with computeError(). also lowkey important โ€” some solvers may just not be able to provide an error estimate at all, no cap.

See also: computeError, and LMEGetErrorEstimate โ€” https://slepc.upv.es/release/manualpages/LME/LMEGetErrorEstimate.html

๐Ÿ“œ Source code at slepc4py/SLEPc/LME.pyx:410

getErrorIfNotConverged()

asks the question: does solve() throw an error when the solver doesn't converge? ๐Ÿ™ˆ

Not collective.

Get a flag indicating whether solve() will generate an error if the solver does not converge.

  • Returns โ€” True indicates you want the error generated.
  • Return type โ€” bool

See also: setErrorIfNotConverged, and LMEGetErrorIfNotConverged โ€” https://slepc.upv.es/release/manualpages/LME/LMEGetErrorIfNotConverged.html

๐Ÿ“œ Source code at slepc4py/SLEPc/LME.pyx:823

getIterationNumber()

get the current iteration number, bestie ๐Ÿ”ข

Not collective.

if the call to solve() is complete, then it returns the number of iterations carried out by the solution method. so it's giving receipts on how much work got done ๐Ÿ“ˆ

  • Returns โ€” Iteration number.
  • Return type โ€” int

See also: getConvergedReason, and LMEGetIterationNumber โ€” https://slepc.upv.es/release/manualpages/LME/LMEGetIterationNumber.html

๐Ÿ“œ Source code at slepc4py/SLEPc/LME.pyx:758

getMonitor()

get the list of monitor functions ๐Ÿ‘€

Not collective.

  • Returns โ€” The list of monitor functions.
  • Return type โ€” LMEMonitorFunction

๐Ÿ“œ Source code at slepc4py/SLEPc/LME.pyx:700

getOptionsPrefix()

get the prefix used for searching for all LME options in the database ๐ŸŽ€

Not collective.

  • Returns โ€” The prefix string set for this LME object.
  • Return type โ€” str

See also: setOptionsPrefix, appendOptionsPrefix, and LMEGetOptionsPrefix โ€” https://slepc.upv.es/release/manualpages/LME/LMEGetOptionsPrefix.html

๐Ÿ“œ Source code at slepc4py/SLEPc/LME.pyx:462

getProblemType()

get the LME problem type of this object ๐Ÿ’œ

Not collective.

  • Returns โ€” The problem type currently being used.
  • Return type โ€” ProblemType

See also: setProblemType, and LMEGetProblemType โ€” https://slepc.upv.es/release/manualpages/LME/LMEGetProblemType.html

๐Ÿ“œ Source code at slepc4py/SLEPc/LME.pyx:206

getRHS()

get the right-hand side of the matrix equation ๐Ÿ“

Collective.

See also: setRHS, and LMEGetRHS โ€” https://slepc.upv.es/release/manualpages/LME/LMEGetRHS.html

๐Ÿ“œ Source code at slepc4py/SLEPc/LME.pyx:327

getSolution()

get the solution of the matrix equation โœจ

Collective.

Notes ๐Ÿ“

  • If called after solve(), X will contain the solution of the equation.
  • The matrix X may have been passed by the user via setSolution(), although this is not required.

See also: solve, setSolution, and LMEGetSolution โ€” https://slepc.upv.es/release/manualpages/LME/LMEGetSolution.html

๐Ÿ“œ Source code at slepc4py/SLEPc/LME.pyx:382

getTolerances()

get the tolerance and the max iteration count ๐ŸŽฏ

Not collective.

See also: setTolerances, and LMEGetTolerances โ€” https://slepc.upv.es/release/manualpages/LME/LMEGetTolerances.html

๐Ÿ“œ Source code at slepc4py/SLEPc/LME.pyx:553

getType()

get the LME type of this object ๐Ÿฆ‹

Not collective.

See also: setType, and LMEGetType โ€” https://slepc.upv.es/release/manualpages/LME/LMEGetType.html

๐Ÿ“œ Source code at slepc4py/SLEPc/LME.pyx:169

reset()

reset the LME object ๐Ÿ”„ like a lil factory reset, but for your solver context

Collective.

See also: LMEReset โ€” https://slepc.upv.es/release/manualpages/LME/LMEReset.html

๐Ÿ“œ Source code at slepc4py/SLEPc/LME.pyx:109

setBV(bv)

give the LME object a basis vector object to hold onto ๐ŸŽ€

Collective.

Parameters

See also: getBV, and LMESetBV โ€” https://slepc.upv.es/release/manualpages/LME/LMESetBV.html

๐Ÿ“œ Source code at slepc4py/SLEPc/LME.pyx:658

setCoefficients(A, B=None, D=None, E=None)

set the coefficient matrices, bestie ๐Ÿ’… this is literally the moment where you tell the solver what equation it's solving

Collective.

Set the coefficient matrices that define the linear matrix equation to be solved.

Parameters

Return type: None

Notes

The matrix equation is giving the general form AXE+DXB=C, where matrix C is not provided here but with setRHS(). Not all four matrices must be passed, so breathe ๐Ÿ’–

This must be called before setUp(). If you call it again after setUp() then the LME object gets reset. Just so you know ๐ŸŒ€

See also: getCoefficients, solve, setRHS, setUp, LMESetCoefficients

:sources: slepc4py/SLEPc/LME.pyx:225

โœจ setDimensions(ncv) โœจ

Set the dimension of the subspace to be used by the solver ๐Ÿ’…

Logically collective.

Parameters

  • ncv (int) โ€” Maximum dimension of the subspace to be used by the solver.

Return type: None

See also: getDimensions, LMESetDimensions

:sources: slepc4py/SLEPc/LME.pyx:620

๐ŸŽ€ setErrorIfNotConverged(flg=True) ๐ŸŽ€

Tells solve() to generate an error if the solver has not converged. No quiet failing in this house ๐Ÿ˜ญ

Logically collective.

Parameters

  • flg (bool) โ€” True indicates you want the error generated.

Return type: None

Notes

Normally SLEPc continues if the solver fails to converge, and you can call getConvergedReason() after a solve() to determine if it has converged. So like, the drama is optional ๐ŸŒธ

See also: getConvergedReason, solve, LMESetErrorIfNotConverged

:sources: slepc4py/SLEPc/LME.pyx:799

๐Ÿ’– setFromOptions() ๐Ÿ’–

Set LME options from the options database.

Collective.

Notes

To see all options, run your program with the -help option. iykyk ๐Ÿ‘‘

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

See also: setOptionsPrefix, LMESetFromOptions

:sources: slepc4py/SLEPc/LME.pyx:534

Return type: None

๐Ÿฆ‹ setMonitor(monitor, args=None, kargs=None) ๐Ÿฆ‹

Append a monitor function to the list of monitors. Keep an eye on things, bestie ๐Ÿ‘€

Logically collective.

See also: getMonitor, cancelMonitor, LMEMonitorSet

:sources: slepc4py/SLEPc/LME.pyx:675

Parameters

  • monitor (LMEMonitorFunction | None)
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type: None

๐ŸŒˆ setOptionsPrefix(prefix=None) ๐ŸŒˆ

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

Logically collective.

Parameters

  • prefix (str | None) โ€” The prefix string to prepend to all LME 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. She does it for you, periodt ๐Ÿ’…

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

L1.setOptionsPrefix("lme1_")
L2.setOptionsPrefix("lme2_")

See also: appendOptionsPrefix, getOptionsPrefix, LMEGetOptionsPrefix

:sources: slepc4py/SLEPc/LME.pyx:481

๐Ÿ‘‘ setProblemType(lme_problem_type) ๐Ÿ‘‘

Set the LME problem type of this object.

Logically collective.

Parameters

  • lme_problem_type (ProblemType | str) โ€” The problem type to be used.

Return type: None

See also: getProblemType, LMESetProblemType

:sources: slepc4py/SLEPc/LME.pyx:188

๐Ÿ“ setRHS(C) ๐Ÿ“

Set the right-hand side of the matrix equation.

Collective.

Parameters

  • C (Mat) โ€” The right-hand side matrix

Return type: None

Notes

The matrix equation has the general form AXE+DXB=C, where matrix C is given with this function. It must be a low-rank matrix of type petsc4py.PETSc.Mat.Type.LRC, that is, C = UDV^* where D is diagonal of order k, and U,V are dense tall-skinny matrices with k columns. No sparse matrix must be provided when creating the LRC matrix. Like, none, bestie ๐Ÿšซ

In equation types that require C to be symmetric, such as Lyapunov, C must be created with V=U.

See also: getRHS, setSolution, LMESetRHS

:sources: slepc4py/SLEPc/LME.pyx:298

๐Ÿงš setSolution(X=None) ๐Ÿงš

Set the placeholder for the solution of the matrix equation. It's the seat you're saving for the answer ๐Ÿ’œ

Collective.

Parameters

  • X (Mat | None) โ€” The solution matrix

Return type: None

Notes

The matrix equation has the general form AXE+DXB=C, where the solution matrix is of low rank and is written in factored form X = UDV^*. This function provides a matrix object of type petsc4py.PETSc.Mat.Type.LRC that stores U,V and (optionally) D. These factors will be computed during solve().

In equation types whose solution X is symmetric, such as Lyapunov, X must be created with V=U.

If the user provides X with this function, then the solver will return a solution with rank at most the number of columns of U. Alternatively, it is possible to let the solver choose the rank of the solution, by passing None and then calling getSolution() after solve(). So chill, she'll pick for you if you let her โœจ

See also: solve, setRHS, getSolution, LMESetSolution

:sources: slepc4py/SLEPc/LME.pyx:347

๐Ÿ’€ setTolerances(tol=None, max_it=None) ๐Ÿ’€

Set the tolerance and maximum iteration count.

Logically collective, bestie ๐Ÿ’ซ everyone in the comm has to be on the same page for this one.

Parameters

  • tol (float | None) โ€” the convergence tolerance, aka how chill we're being about accuracy ๐ŸŽฏ
  • max_it (int | None) โ€” the maximum number of iterations, the hard cap on the grind ๐Ÿ’ช

Return type: None

See also: getTolerances, LMESetTolerances โ€” https://slepc.upv.es/release/manualpages/LME/LMESetTolerances.html

Source code at slepc4py/SLEPc/LME.pyx:575

โœจ setType(lme_type) โœจ

Picks which solver the LME object is gonna use. The main character selection moment ๐Ÿ‘‘

Logically collective, no cap.

Parameters

  • lme_type (Type | str) โ€” the solver to be used. Yes bestie, you can hand it the actual enum or just a string, slay ๐ŸŽ€

Return type: None

Notes

The default is KRYLOV. But listen โ€” normally it is best to use setFromOptions() and then set the LME type from the options database rather than by using this routine. Doing it through the options database gives the user maximum flexibility in evaluating the different available methods. So likeโ€ฆ options database is the vibe, this routine is the emergency backup ๐Ÿ™ˆ

See also: getType, LMESetType โ€” https://slepc.upv.es/release/manualpages/LME/LMESetType.html

Source code at slepc4py/SLEPc/LME.pyx:142

๐ŸŒธ setUp() ๐ŸŒธ

Sets up all the internal data structures it needs. Collective, everybody in sync ๐Ÿซถ

Set up all the internal data structures necessary for the execution of the eigensolver. It's giving "get your room clean before the party" energy ๐Ÿงนโœจ

See also: solve, LMESetUp โ€” https://slepc.upv.es/release/manualpages/LME/LMESetUp.html

Source code at slepc4py/SLEPc/LME.pyx:726

Return type: None

๐Ÿ”ฅ solve() ๐Ÿ”ฅ

Solve the linear matrix equation. Collective. The finale, the main event, the moment we've all been waiting for ๐Ÿ’…

Notes

The matrix coefficients are specified with setCoefficients(). The right-hand side is specified with setRHS(). The placeholder for the solution is specified with setSolution(). So like, you can't just show up empty-handed, you gotta feed it the pieces first ๐Ÿ“

See also: setCoefficients, setRHS, setSolution, LMESolve โ€” https://slepc.upv.es/release/manualpages/LME/LMESolve.html

Source code at slepc4py/SLEPc/LME.pyx:741

Return type: None

๐Ÿ’– view(viewer=None) ๐Ÿ’–

Prints the LME data structure. Collective~ ๐Ÿ“ธ

Parameters

  • viewer (Viewer | None) โ€” visualization context; if it's not provided, the standard output is used. So if you're too lazy to pass one, it just yells into stdout, iconic ๐ŸŒˆ

Return type: None

See also: LMEView โ€” https://slepc.upv.es/release/manualpages/LME/LMEView.html

Source code at slepc4py/SLEPc/LME.pyx:76

โœจ Attributes Documentation โœจ

๐Ÿฆ‹ bv

The basis vectors (BV) object associated to the LME object. Like, its bestie-in-crime ๐Ÿซถ

Source code at slepc4py/SLEPc/LME.pyx:868

๐ŸŽ€ fn

The math function (FN) object associated to the LME object. The function bestie ๐Ÿ’œ

Source code at slepc4py/SLEPc/LME.pyx:861

โญ max_it

The maximum iteration count used by the LME convergence tests. The iconic "how many tries do we allow" number ๐Ÿ”ข

Source code at slepc4py/SLEPc/LME.pyx:854

๐ŸŒธ tol

The tolerance value used by the LME convergence tests. The "close enough is good enough" threshold ๐Ÿ’…

Source code at slepc4py/SLEPc/LME.pyx:847

__init__()

classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.MFN

class slepc4py.SLEPc.MFN

Bases: Object (https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Object.html#petsc4py.PETSc.Object)

Matrix Function. Okay so this is the one computing the action of a matrix function on a vector, and it's lowkey magic ๐Ÿช„

Matrix Function (MFN) is the object provided by slepc4py for computing the action of a matrix function on a vector. Given a matrix A and a vector b, the call mfn.solve(b,x) computes x=f(A)b, where f is a function such as the exponential. Like, you never actually build f(A), you just vibe your way to the answer โœจ

Enumerations

  • ConvergedReason โ€” MFN convergence reasons. The "did it work tho" report card ๐Ÿ“‹
  • Type โ€” MFN type. Which flavor of solver we're running ๐Ÿ“

slepc4py.SLEPc.MFN.ConvergedReason

class slepc4py.SLEPc.MFN.ConvergedReason

Bases: object

MFN convergence reasons. The receipts on how the solve went:

  • CONVERGED_TOL: All eigenpairs converged to requested tolerance. We ate ๐Ÿ’…โœ…
  • CONVERGED_ITS: Solver completed the requested number of steps. Ran out of steps but on purpose ๐Ÿ‘‘
  • DIVERGED_ITS: Maximum number of iterations exceeded. It gave up, respectfully ๐Ÿ’€
  • DIVERGED_BREAKDOWN: Generic breakdown in method. It said "no thoughts, head empty" ๐Ÿ˜ญ

See also: MFNConvergedReason โ€” https://slepc.upv.es/release/manualpages/MFN/MFNConvergedReason.html

Attributes Summary

  • CONVERGED_ITERATING โ€” Constant CONVERGED_ITERATING of type int
  • CONVERGED_ITS โ€” Constant CONVERGED_ITS of type int
  • CONVERGED_TOL โ€” Constant CONVERGED_TOL of type int
  • DIVERGED_BREAKDOWN โ€” Constant DIVERGED_BREAKDOWN of type int
  • DIVERGED_ITS โ€” Constant DIVERGED_ITS of type int
  • ITERATING โ€” Constant ITERATING of type int

Attributes Documentation

๐ŸŒธ the grind continues, stay tuned bestie ๐ŸŒธ

And then we have the usual suspects, bestie:

  • __init__()
  • classmethod __new__(*args, **kwargs)

class slepc4py.SLEPc.MFN.Type

Bases: object <https://docs.python.org/3/library/functions.html#object>

MFN type. ๐Ÿ’–

  • KRYLOV: Restarted Krylov solver. ๐ŸŒ€
  • EXPOKIT: Implementation of the method in Expokit. ๐Ÿš€

See also:

MFNType <https://slepc.upv.es/release/manualpages/MFN/MFNType.html>

Attributes Summary

Attributes Documentation

And one more time for the cheap seats:

  • __init__()
  • classmethod __new__(*args, **kwargs)

Same energy, different line. ๐Ÿ˜ญ

๐Ÿฆ‹ Methods Summary ๐Ÿฆ‹

okay bestie, here's the entire squad of methods that live on the MFN object โ€” every single one, in order, no skips, no "and the rest", nothing left on read ๐Ÿ’…. Square brackets mean the arg is optional, so don't come for me when you see them.

  • appendOptionsPrefix([prefix]) โ€” glues even more text onto the prefix MFN uses when it goes hunting for all MFN options in the database. โœจ
  • cancelMonitor() โ€” wipes all the monitors off an MFN object. clean slate energy ๐Ÿงน.
  • create([comm]) โ€” makes the MFN object. your main character origin story ๐ŸŽ€.
  • destroy() โ€” yeets the MFN object. gone, bye, iconic exit ๐Ÿ’€.
  • getBV() โ€” hands you back the basis vector object that's associated to the MFN object.
  • getConvergedReason() โ€” tells you why the solve() iteration stopped. the receipts, basically ๐Ÿ•ต๏ธ.
  • getDimensions() โ€” returns the dimension of the subspace the solver is using.
  • getErrorIfNotConverged() โ€” checks whether solve() is set to throw an error when the solver doesn't converge. yes/no vibes.
  • getFN() โ€” gives you the math function object associated to the MFN object. ๐ŸŒธ
  • getIterationNumber() โ€” the current iteration number, right now, this second.
  • getMonitor() โ€” returns the list of monitor functions. the whole group chat ๐Ÿ‘ฏ.
  • getOperator() โ€” hands back the matrix that's associated with the MFN object.
  • getOptionsPrefix() โ€” returns the prefix being used to search for all MFN options in the database.
  • getTolerances() โ€” spits out the tolerance and the maximum iteration count. two for one ๐Ÿ’–.
  • getType() โ€” tells you what MFN type this object is.
  • reset() โ€” resets the MFN object. fresh start, no baggage ๐Ÿ”„.
  • setBV(bv) โ€” attaches a basis vector object to the MFN object.
  • setDimensions(ncv) โ€” sets the dimension of the subspace the solver is gonna use.
  • setErrorIfNotConverged([flg]) โ€” flips solve() so it generates an error if the solver doesn't converge. pick your chaos level ๐Ÿซถ.
  • setFN(fn) โ€” attaches a math function object to the MFN object.
  • setFromOptions() โ€” loads MFN options straight out of the options database. โœจ
  • setMonitor(monitor[, args, kargs]) โ€” appends a monitor function onto the list of monitors. more watchers, more data ๐Ÿ‘€.
  • setOperator(A) โ€” sets the matrix associated with the MFN object.
  • setOptionsPrefix([prefix]) โ€” sets the prefix MFN uses when searching for all MFN options in the database.
  • setTolerances([tol, max_it]) โ€” sets the tolerance and the maximum iteration count. tune it, babes ๐ŸŽš๏ธ.
  • setType(mfn_type) โ€” picks which particular solver gets used inside the MFN object. choose your fighter ๐ŸฅŠ.
  • setUp() โ€” builds out all the necessary internal data structures. behind-the-scenes queen ๐Ÿ‘‘.
  • solve(b, x) โ€” solves the matrix function problem. the main event ๐ŸŒŸ.
  • solveTranspose(b, x) โ€” solves the transpose matrix function problem. the remix ๐Ÿ”ฅ.
  • view([viewer]) โ€” prints the MFN data structure so you can actually look at it.

appendOptionsPrefix(prefix=None)</p>

okay so this one is giving "add MORE prefix bestie" ๐Ÿ’… it appends to the prefix that gets used when MFN goes searching for all its options in the database.

Logically collective.

Parameters

  • prefix (str | None) โ€” the prefix string you wanna prepend to literally every single MFN option request.

Return type

None

See also: setOptionsPrefix, getOptionsPrefix, MFNAppendOptionsPrefix

Source code at slepc4py/SLEPc/MFN.pyx:219

cancelMonitor()</p>

clears out all the monitors on an MFN object. bye bye watchers ๐Ÿ‘‹โœจ

Logically collective.

See also: MFNMonitorCancel

Source code at slepc4py/SLEPc/MFN.pyx:498

Return type

None

create(comm=None)</p>

spawns the MFN object into existence, no cap ๐Ÿฆ‹

Collective.

Parameters

  • comm (Comm | None) โ€” the MPI communicator. If you don't hand one over, it just defaults to all processes. easy.

Return type

Self

See also: MFNCreate

Source code at slepc4py/SLEPc/MFN.pyx:102

destroy()</p>

nukes the MFN object. it's over, it's done, we don't talk anymore ๐Ÿ’€

Logically collective.

See also: MFNDestroy

Source code at slepc4py/SLEPc/MFN.pyx:76

Return type

Self

getBV()</p>

grabs the basis vector object that's attached to the MFN object.

Not collective.

Returns

The basis vectors context.

Return type

BV

See also: setBV, MFNGetBV

Source code at slepc4py/SLEPc/MFN.pyx:379

getConvergedReason()</p>

want the tea on why your solve() iteration stopped? this is that โ˜•

Not collective.

Returns

A negative value means it diverged ๐Ÿ˜ญ, a positive value means it converged ๐Ÿ”ฅ.

Return type

ConvergedReason

See also: setTolerances, solve, setErrorIfNotConverged, MFNGetConvergedReason

Source code at slepc4py/SLEPc/MFN.pyx:607

getDimensions()</p>

tells you the dimension of the subspace the solver is chilling in.

Not collective.

Returns

The maximum dimension of the subspace to be used by the solver.

Return type

int

See also: setDimensions, MFNGetDimensions

Source code at slepc4py/SLEPc/MFN.pyx:305

getErrorIfNotConverged()</p>

checks whether solve() is gonna throw an error when the solver refuses to converge. dramatic much.

Not collective.

Get a flag indicating whether solve() will generate an error if the solver does not converge.

Returns

True indicates you want the error generated.

Return type

bool

See also: setErrorIfNotConverged, MFNGetErrorIfNotConverged

Source code at slepc4py/SLEPc/MFN.pyx:650

getFN()</p>

gets the math function object that's associated to the MFN object ๐Ÿงฎโœจ

Not collective.

Returns

The math function context.

Return type

FN

See also: setFN, MFNGetFN

Source code at slepc4py/SLEPc/MFN.pyx:342

getIterationNumber()</p>

the current iteration number, bestie. and if the solve() call already finished, then this hands you the number of iterations that the solution method carried out.

Not collective.

Returns

Iteration number.

Return type

int

See also: getConvergedReason, MFNGetIterationNumber

Source code at slepc4py/SLEPc/MFN.pyx:584

getMonitor()</p>

gets the whole list of monitor functions ๐Ÿ‘‘

Not collective.

Returns

The list of monitor functions.

Return type

MFNMonitorFunction

Source code at slepc4py/SLEPc/MFN.pyx:485

getOperator()</p>

gets the matrix associated with the MFN object.

Collective.

Returns

The matrix for which the matrix function is to be computed.

Return type

petsc4py.PETSc.Mat

See also: setOperator, MFNGetOperator

Source code at slepc4py/SLEPc/MFN.pyx:416

getOptionsPrefix()</p>

gets the prefix that MFN uses when it goes searching for all its options in the database.

Not collective.

Returns

The prefix string set for this MFN object.

Return type

str

See also: setOptionsPrefix, appendOptionsPrefix, MFNGetOptionsPrefix

Source code at slepc4py/SLEPc/MFN.pyx:169

getTolerances()</p>

gets both the tolerance and the max iteration count in one lil call.

Not collective.

Returns

Return type: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[float <https://docs.python.org/3/library/functions.html#float>, int <https://docs.python.org/3/library/functions.html#int>] โ€” so it hands you back a lil pair of numbers, periodt.

See also: setTolerances, MFNGetTolerances <https://slepc.upv.es/release/manualpages/MFN/MFNGetTolerances.html>

Source: slepc4py/SLEPc/MFN.pyx:257 โ€” slepc4py/SLEPc/MFN.pyx#L257

getType()

Get the MFN type of this object. Not collective, so no group-chat sync needed, okay? ๐Ÿฆ‹

Returns: the solver currently being used.

Return type: str <https://docs.python.org/3/library/stdtypes.html#str>

See also: setType, MFNGetType <https://slepc.upv.es/release/manualpages/MFN/MFNGetType.html>

Source: slepc4py/SLEPc/MFN.pyx:150 โ€” slepc4py/SLEPc/MFN.pyx#L150

reset()

Reset the MFN object. Collective โ€” everybody in the MPI crew, assemble. ๐Ÿ‘‘

See also: MFNReset <https://slepc.upv.es/release/manualpages/MFN/MFNReset.html>

Source: slepc4py/SLEPc/MFN.pyx:90 โ€” slepc4py/SLEPc/MFN.pyx#L90

Return type: None <https://docs.python.org/3/library/constants.html#None>

setBV(bv)

Set a basis vector object associated to the MFN object. Collective. ๐Ÿ’–

Parameters:

  • bv (BV <#slepc4py.SLEPc.BV>) โ€” the basis vectors context.

Return type: None <https://docs.python.org/3/library/constants.html#None>

See also: getBV, MFNSetBV <https://slepc.upv.es/release/manualpages/MFN/MFNSetBV.html>

Source: slepc4py/SLEPc/MFN.pyx:399 โ€” slepc4py/SLEPc/MFN.pyx#L399

setDimensions(ncv)

Set the dimension of the subspace to be used by the solver. Logically collective. โœจ

Parameters:

Return type: None <https://docs.python.org/3/library/constants.html#None>

See also: getDimensions, MFNSetDimensions <https://slepc.upv.es/release/manualpages/MFN/MFNSetDimensions.html>

Source: slepc4py/SLEPc/MFN.pyx:324 โ€” slepc4py/SLEPc/MFN.pyx#L324

setErrorIfNotConverged(flg=True)

Set solve() to generate an error if the solver does not converge. Logically collective. ๐Ÿšจ

Parameters:

Return type: None <https://docs.python.org/3/library/constants.html#None>

Notes: Normally SLEPc continues if the solver fails to converge, you can call getConvergedReason() after a solve() to determine if it has converged.

See also: getConvergedReason, solve, MFNSetErrorIfNotConverged <https://slepc.upv.es/release/manualpages/MFN/MFNSetErrorIfNotConverged.html>

Source: slepc4py/SLEPc/MFN.pyx:626 โ€” slepc4py/SLEPc/MFN.pyx#L626

setFN(fn)

Set a math function object associated to the MFN object. Collective. ๐Ÿงš

Parameters:

  • fn (FN <#slepc4py.SLEPc.FN>) โ€” the math function context.

Return type: None <https://docs.python.org/3/library/constants.html#None>

See also: getFN, MFNSetFN <https://slepc.upv.es/release/manualpages/MFN/MFNSetFN.html>

Source: slepc4py/SLEPc/MFN.pyx:362 โ€” slepc4py/SLEPc/MFN.pyx#L362

setFromOptions()

Set MFN 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, MFNSetFromOptions <https://slepc.upv.es/release/manualpages/MFN/MFNSetFromOptions.html>

Source: slepc4py/SLEPc/MFN.pyx:238 โ€” slepc4py/SLEPc/MFN.pyx#L238

Return type: None <https://docs.python.org/3/library/constants.html#None>

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

Append a monitor function to the list of monitors. Logically collective. ๐Ÿ‘€

See also: getMonitor, cancelMonitor, MFNMonitorSet <https://slepc.upv.es/release/manualpages/MFN/MFNMonitorSet.html>

Source: slepc4py/SLEPc/MFN.pyx:460 โ€” slepc4py/SLEPc/MFN.pyx#L460

Parameters:

Return type: None <https://docs.python.org/3/library/constants.html#None>

setOperator(A)

Set the matrix associated with the MFN object. Collective. ๐Ÿ”ฅ

Parameters:

Return type: None <https://docs.python.org/3/library/constants.html#None>

Notes: This must be called before setUp(). If called again after setUp() then the MFN object is reset.

See also: getOperator, MFNSetOperator <https://slepc.upv.es/release/manualpages/MFN/MFNSetOperator.html>

Source: slepc4py/SLEPc/MFN.pyx:436 โ€” slepc4py/SLEPc/MFN.pyx#L436

setOptionsPrefix(prefix=None)

Set the prefix used for searching for all MFN options in the database. Logically collective. ๐ŸŒˆ

Parameters:

Return type: None <https://docs.python.org/3/library/constants.html#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 MFN contexts, one could call:

M1.setOptionsPrefix("mfn1_")
M2.setOptionsPrefix("mfn2_")

See also: appendOptionsPrefix, getOptionsPrefix, MFNGetOptionsPrefix <https://slepc.upv.es/release/manualpages/MFN/MFNGetOptionsPrefix.html>

Source: slepc4py/SLEPc/MFN.pyx:188 โ€” slepc4py/SLEPc/MFN.pyx#L188

setTolerances(tol=None, max_it=None)

Set the tolerance and maximum iteration count. Logically collective. ๐Ÿ’œ

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

Parameters:

Return type: None <https://docs.python.org/3/library/constants.html#None>

See also: getTolerances, MFNSetTolerances <https://slepc.upv.es/release/manualpages/MFN/MFNSetTolerances.html>

Source: slepc4py/SLEPc/MFN.pyx:279 โ€” slepc4py/SLEPc/MFN.pyx#L279

setType(mfn_type)

Set the particular solver to be used in the MFN object. Logically collective.

  • mfn_type (Type or str) โ€” the solver you wanna use, bestie. that's it, that's the whole arg ๐Ÿ’…

Return type: None

Notes

the default is KRYLOV. and okay listen โ€” normally you do NOT want to hard-code this with setType(). do setFromOptions() first and then let the MFN type get set from the options database instead, because that gives you maximum flexibility to evaluate all the different available methods without recompiling your whole personality. periodt.

See also:

getType, MFNSetType (https://slepc.upv.es/release/manualpages/MFN/MFNSetType.html)

:sources: Source code at slepc4py/SLEPc/MFN.pyx:123

setUp()

Set up all the necessary internal data structures. ๐Ÿ› ๏ธโœจ

Collective.

okay so this one sets up all the internal data structures it needs to actually run the eigensolver. like, it's the getting-ready montage before the main character moment. do it. it's giving pre-game ritual. ๐ŸŽ€

See also:

solve, MFNSetUp (https://slepc.upv.es/release/manualpages/MFN/MFNSetUp.html)

:sources: Source code at slepc4py/SLEPc/MFN.pyx:513

Return type: None

solve(b, x)

Solve the matrix function problem. ๐Ÿ”ฅ

Collective.

give it a vector b and out comes x = f(A) b. iconic. that's literally the whole job description, she ate and left no crumbs. ๐Ÿ‘‘

Parameters

Return type: None

Notes

the matrix A gets specified with setOperator(). and the function f? that's specified via the FN object you get from getFN() โ€” or you can just set it yourself with setFN(). iykyk. ๐Ÿ’…

See also:

setOperator, getFN, solveTranspose, MFNSolve (https://slepc.upv.es/release/manualpages/MFN/MFNSolve.html)

:sources: Source code at slepc4py/SLEPc/MFN.pyx:528

solveTranspose(b, x)

Solve the transpose matrix function problem. ๐Ÿฆ‹

Collective.

give it a vector b and you get x = f(A^T) b back. yes, transpose. no cap, that ^T matters. ๐Ÿ™ˆ

Parameters

Return type: None

Notes

again, matrix A comes from setOperator(), and the function f lives in the FN object you grab with getFN() or set with setFN(). same energy, different transpose. โœจ

See also:

setOperator, getFN, solve, MFNSolveTranspose (https://slepc.upv.es/release/manualpages/MFN/MFNSolveTranspose.html)

:sources: Source code at slepc4py/SLEPc/MFN.pyx:556

view(viewer=None)

Print the MFN data structure. ๐Ÿ“ธโœจ

Collective.

it's the vibe check for your object โ€” dump the whole MFN data structure so you can actually see what's in there.

Parameters

Return type: None

See also:

MFNView (https://slepc.upv.es/release/manualpages/MFN/MFNView.html)

:sources: Source code at slepc4py/SLEPc/MFN.pyx:57

Attributes Documentation ๐Ÿ‘‘

bv

the basis vectors (BV) object chillin' alongside the MFN object. ๐Ÿงš

:sources: Source code at slepc4py/SLEPc/MFN.pyx:695

fn

the math function (FN) object that's attached to the MFN object. it's giving mathematical partner-in-crime. ๐Ÿ’œ

:sources: Source code at slepc4py/SLEPc/MFN.pyx:688

max_it

the maximum iteration count that the MFN convergence tests use. ๐Ÿ‘‘

:sources: Source code at slepc4py/SLEPc/MFN.pyx:681

tol

the tolerance count used by the MFN convergence tests. small number, big responsibility. ๐Ÿ“

:sources: Source code at slepc4py/SLEPc/MFN.pyx:674

__init__()

classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.NEP ๐Ÿ’…

class slepc4py.SLEPc.NEP

Bases: Object (https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Object.html)

Nonlinear Eigenvalue Problem Solver. ๐Ÿ”ฅ

so like. the Nonlinear Eigenvalue Problem (NEP) solver is the object slepc4py hands you when your eigenvalue problem is nonlinear with respect to the eigenvalue โ€” and NOT with respect to the eigenvector. important distinction, bestie, don't mix them up. this is meant for general nonlinear problems (as opposed to polynomial eigenproblems, that's a whole different girl) described as:

T(\lambda) x=0

main character equation. periodt. ๐Ÿ‘‘

Enumerations

  • CISSExtraction โ€” NEP CISS extraction technique.
  • Conv โ€” NEP convergence test.
  • ConvergedReason โ€” NEP convergence reasons.
  • ErrorType โ€” NEP error type to assess accuracy of computed solutions.
  • ProblemType โ€” NEP problem type.
  • Refine โ€” NEP refinement strategy.
  • RefineScheme โ€” NEP scheme for solving linear systems during iterative refinement.
  • Stop โ€” NEP stopping test.
  • Type โ€” NEP type.
  • Which โ€” NEP desired part of spectrum.

slepc4py.SLEPc.NEP.CISSExtraction โœจ

class slepc4py.SLEPc.NEP.CISSExtraction

Bases: object (https://docs.python.org/3/library/functions.html#object)

NEP CISS extraction technique. ๐ŸŒˆ

  • RITZ: Ritz extraction. classic, timeless, never misses ๐Ÿ’…
  • HANKEL: extraction via Hankel eigenproblem. different flavor, same slay ๐Ÿฆ‹
  • CAA: communication-avoiding Arnoldi. the overachiever of the group chat ๐Ÿ‘‘

See also:

NEPCISSExtraction (https://slepc.upv.es/release/manualpages/NEP/NEPCISSExtraction.html)

Attributes Summary โœจ

Okay bestie, the class we just covered is giving major int energy, no cap. ๐Ÿ’… These three constants are literally the whole summary:

Attributes Documentation ๐Ÿ“

And here's the full documentation, because we keep every detail, periodt:

Then the constructor vibes:

__init__()

classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.NEP.Conv ๐ŸŽ€

class slepc4py.SLEPc.NEP.Conv

Bases: object (https://docs.python.org/3/library/functions.html#object)

NEP convergence test. It's giving main character energy for sure. ๐Ÿ‘‘

  • ABS: Absolute convergence test.
  • REL: Convergence test relative to the eigenvalue.
  • NORM: Convergence test relative to the matrix norms.
  • USER: User-defined convergence test.

See also: NEPConv (https://slepc.upv.es/release/manualpages/NEP/NEPConv.html)

Attributes Summary โœจ

Attributes Documentation ๐Ÿ“

__init__()

classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.NEP.ConvergedReason ๐Ÿ‘‘

class slepc4py.SLEPc.NEP.ConvergedReason

Bases: object (https://docs.python.org/3/library/functions.html#object)

NEP convergence reasons. These are lowkey iconic: ๐Ÿ’…

  • CONVERGED_TOL: All eigenpairs converged to requested tolerance.
  • CONVERGED_USER: User-defined convergence criterion satisfied.
  • DIVERGED_ITS: Maximum number of iterations exceeded.
  • DIVERGED_BREAKDOWN: Solver failed due to breakdown.
  • DIVERGED_LINEAR_SOLVE: Inner linear solve failed.
  • DIVERGED_SUBSPACE_EXHAUSTED: Run out of space for the basis in an unrestarted solver.
  • CONVERGED_ITERATING: Iteration not finished yet.

See also: NEPConvergedReason (https://slepc.upv.es/release/manualpages/NEP/NEPConvergedReason.html)

โœจ Attributes Documentation โœจ

okay bestie here's where each of those lil constants gets its own moment, no skipping ๐Ÿ’…

CONVERGED_ITERATING: int = CONVERGED_ITERATING

Constant CONVERGED_ITERATING of type int (https://docs.python.org/3/library/functions.html#int) ๐Ÿฆ‹

CONVERGED_TOL: int = CONVERGED_TOL

Constant CONVERGED_TOL of type int (https://docs.python.org/3/library/functions.html#int) ๐ŸŒธ

CONVERGED_USER: int = CONVERGED_USER

Constant CONVERGED_USER of type int (https://docs.python.org/3/library/functions.html#int) ๐ŸŽ€

DIVERGED_BREAKDOWN: int = DIVERGED_BREAKDOWN

Constant DIVERGED_BREAKDOWN of type int (https://docs.python.org/3/library/functions.html#int) ๐Ÿ˜ญ

DIVERGED_ITS: int = DIVERGED_ITS

Constant DIVERGED_ITS of type int (https://docs.python.org/3/library/functions.html#int) ๐Ÿ’€

DIVERGED_LINEAR_SOLVE: int = DIVERGED_LINEAR_SOLVE

Constant DIVERGED_LINEAR_SOLVE of type int (https://docs.python.org/3/library/functions.html#int) ๐Ÿ”ฅ

DIVERGED_SUBSPACE_EXHAUSTED: int = DIVERGED_SUBSPACE_EXHAUSTED

Constant DIVERGED_SUBSPACE_EXHAUSTED of type int (https://docs.python.org/3/library/functions.html#int) ๐Ÿ‘‘

ITERATING: int = ITERATING

Constant ITERATING of type int (https://docs.python.org/3/library/functions.html#int) โญ

__init__()
classmethod __new__(*args, **kwargs)

yes babe, that's the whole thing, it's giving minimal and we love that for it ๐Ÿซถ

slepc4py.SLEPc.NEP.ErrorType

class slepc4py.SLEPc.NEP.ErrorType

Bases: object (https://docs.python.org/3/library/functions.html#object)

So this one is literally the NEP error type to assess accuracy of computed solutions โ€” like, it's the vibe check your eigenvalues go through to see how accurate they actually are ๐Ÿ˜Œโœจ

  • ABSOLUTE: Absolute error. ๐Ÿ’–
  • RELATIVE: Relative error. ๐ŸŒˆ
  • BACKWARD: Backward error. ๐Ÿงš

See also:

NEPErrorType (https://slepc.upv.es/release/manualpages/NEP/NEPErrorType.html)

Attributes Summary

Attributes Documentation

ABSOLUTE: int = ABSOLUTE

Constant ABSOLUTE of type int (https://docs.python.org/3/library/functions.html#int) ๐ŸŒธ

BACKWARD: int = BACKWARD

Constant BACKWARD of type int (https://docs.python.org/3/library/functions.html#int) ๐Ÿ’œ

RELATIVE: int = RELATIVE

Constant RELATIVE of type int (https://docs.python.org/3/library/functions.html#int) ๐Ÿฆ‹

__init__()
classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.NEP.ProblemType

class slepc4py.SLEPc.NEP.ProblemType

Bases: object (https://docs.python.org/3/library/functions.html#object)

And this one? It's the NEP problem type, periodt ๐Ÿ’… like it tells you which flavor of nonlinear eigenproblem you're dealing with:

  • GENERAL: General nonlinear eigenproblem. ๐Ÿ”ฅ
  • RATIONAL: NEP defined in split form with all f_i rational. ๐Ÿ‘‘

See also:

NEPProblemType (https://slepc.upv.es/release/manualpages/NEP/NEPProblemType.html)

โœจ Attributes Summary โœจ

okay bestie, we're back in the NEP module and the vibe check says: constants. lowkey iconic ๐Ÿ’… here's the quick rundown:

no cap, that's the whole summary. fr fr. ๐Ÿซถ

๐ŸŒธ Attributes Documentation ๐ŸŒธ

now for the full receipts ๐Ÿงพ

and then we got the classic duo that every class has:

__init__()

classmethod __new__(*args, **kwargs)

the way that these just show up with no description? it's giving standard behavior, bestie. periodt. ๐Ÿ’–

๐Ÿ‘‘ slepc4py.SLEPc.NEP.Refine

okay so now we're entering the Refine era. main character energy fr.

class slepc4py.SLEPc.NEP.Refine

Bases: object <https://docs.python.org/3/library/functions.html#object>

NEP refinement strategy.

  • NONE: No refinement.
  • SIMPLE: Refine eigenpairs one by one.
  • MULTIPLE: Refine all eigenpairs simultaneously (invariant pair).

See also: NEPRefine <https://slepc.upv.es/release/manualpages/NEP/NEPRefine.html>

๐Ÿ’– Attributes Summary ๐Ÿ’–

the constants are constant-ing โœจ

โœจ Attributes Documentation โœจ

full details, no skips ๐Ÿ’…

__init__()

classmethod __new__(*args, **kwargs)

๐Ÿฆ‹ slepc4py.SLEPc.NEP.RefineScheme

next up: RefineScheme. it's giving solver options ๐Ÿฆ‹

class slepc4py.SLEPc.NEP.RefineScheme

Bases: object <https://docs.python.org/3/library/functions.html#object>

NEP scheme for solving linear systems during iterative refinement.

  • SCHUR: Schur complement.
  • MBE: Mixed block elimination.
  • EXPLICIT: Build the explicit matrix.

See also: NEPRefineScheme <https://slepc.upv.es/release/manualpages/NEP/NEPRefineScheme.html>

๐Ÿ’– Attributes Summary ๐Ÿ’–

โœจ Attributes Documentation โœจ

__init__()

classmethod __new__(*args, **kwargs)

๐ŸŒˆ slepc4py.SLEPc.NEP.Stop

Stop class, stopping test. not me being obsessed with these names ๐ŸŒˆ

class slepc4py.SLEPc.NEP.Stop

Bases: object <https://docs.python.org/3/library/functions.html#object>

NEP stopping test.

  • BASIC: Default stopping test.
  • USER: User-defined stopping test.

See also: NEPStop <https://slepc.upv.es/release/manualpages/NEP/NEPStop.html>

๐Ÿ’– Attributes Summary ๐Ÿ’–

โœจ Attributes Documentation โœจ

__init__()

classmethod __new__(*args, **kwargs)

โญ slepc4py.SLEPc.NEP.Type

finally, the Type class. it's giving variety, bestie โญ

class slepc4py.SLEPc.NEP.Type

Bases: object <https://docs.python.org/3/library/functions.html#object>

NEP type.

  • RII: Residual inverse iteration.
  • SLP: Successive linear problems.
  • NARNOLDI: Nonlinear Arnoldi.
  • NLEIGS: Fully rational Krylov method for nonlinear eigenproblems.
  • CISS: Contour integral spectrum slice.
  • INTERPOL: Polynomial interpolation.

See also: NEPType <https://slepc.upv.es/release/manualpages/NEP/NEPType.html>

โœจ Attributes Summary โœจ

okay bestie, here's the lowkey iconic lineup of NEP attributes. no cap, every single one is a str, and they are all literally serving:

๐Ÿ“– Attributes Documentation ๐Ÿ“–

๐Ÿ› ๏ธ methods, bestie ๐Ÿ› ๏ธ

  • __init__() โ€” the init moment, fr fr.
  • classmethod __new__(*args, **kwargs) โ€” classmethod __new__ doing its *args, **kwargs thing.

๐Ÿ‘‘ slepc4py.SLEPc.NEP.Which ๐Ÿ‘‘

slepc4py.SLEPc.NEP.Which
class slepc4py.SLEPc.NEP.Which

Bases: object <https://docs.python.org/3/library/functions.html#object>

NEP desired part of spectrum.

  • LARGEST_MAGNITUDE: Largest magnitude (default).
  • SMALLEST_MAGNITUDE: Smallest magnitude.
  • LARGEST_REAL: Largest real parts.
  • SMALLEST_REAL: Smallest real parts.
  • LARGEST_IMAGINARY: Largest imaginary parts in magnitude.
  • SMALLEST_IMAGINARY: Smallest imaginary parts in magnitude.
  • TARGET_MAGNITUDE: Closest to target (in magnitude).
  • TARGET_REAL: Real part closest to target.
  • TARGET_IMAGINARY: Imaginary part closest to target.
  • ALL: All eigenvalues in a region.
  • USER: User defined selection.

See also: NEPWhich <https://slepc.upv.es/release/manualpages/NEP/NEPWhich.html>

โœจ Attributes Summary โœจ

๐Ÿ“– Attributes Documentation ๐Ÿ“–

Okay bestie, we're still deep in the constants โœจ every single one of these is an int, and every one of them maps to its own name. Type link for all of them: https://docs.python.org/3/library/functions.html#int โ€” iconic, consistent, we love a theme ๐Ÿ’…

  • ALL: int = ALL โ€” the constant ALL, type int ๐Ÿซถ
  • LARGEST_IMAGINARY: int = LARGEST_IMAGINARY โ€” the constant LARGEST_IMAGINARY, type int ๐Ÿ’–
  • LARGEST_MAGNITUDE: int = LARGEST_MAGNITUDE โ€” the constant LARGEST_MAGNITUDE, type int ๐ŸŒˆ
  • LARGEST_REAL: int = LARGEST_REAL โ€” the constant LARGEST_REAL, type int โญ
  • SMALLEST_IMAGINARY: int = SMALLEST_IMAGINARY โ€” the constant SMALLEST_IMAGINARY, type int ๐Ÿฆ‹
  • SMALLEST_MAGNITUDE: int = SMALLEST_MAGNITUDE โ€” the constant SMALLEST_MAGNITUDE, type int ๐ŸŽ€
  • SMALLEST_REAL: int = SMALLEST_REAL โ€” the constant SMALLEST_REAL, type int ๐ŸŒธ
  • TARGET_IMAGINARY: int = TARGET_IMAGINARY โ€” the constant TARGET_IMAGINARY, type int ๐Ÿ’œ
  • TARGET_MAGNITUDE: int = TARGET_MAGNITUDE โ€” the constant TARGET_MAGNITUDE, type int ๐Ÿ”ฅ
  • TARGET_REAL: int = TARGET_REAL โ€” the constant TARGET_REAL, type int ๐Ÿ‘‘
  • USER: int = USER โ€” the constant USER, type int ๐Ÿ’€
ngl bestie, they all just equal themselves โ€” no fancy math, no secret values, just int after int after int. Take it literally. fr fr ๐Ÿ™ˆ

And then, the last two things this page has for us:

  • __init__() โ€” the initializer, no parameters listed, no description beyond its own name. Lowkey the most mysterious entry here ๐Ÿงš
  • classmethod __new__(*args, **kwargs) โ€” a classmethod __new__ that takes *args and **kwargs, exactly like that, no more detail given ๐ŸŒŸ

okay so bestie, we're deep in the NEP method buffet now and it is giving โœจ every single one of these is a lil handle you can grab on a NEP object, so let's go one by one, no skipping, we eat every crumb ๐Ÿ“

  • appendOptionsPrefix([prefix]) โ€” tack more onto the prefix that the solver uses when it goes rummaging through the options database looking for all your NEP settings ๐Ÿ”
  • applyResolvent(omega, v, r[, rg]) โ€” actually apply the resolvent T^{-1}(z) to a vector you hand it. yes ma'am, real math happening ๐Ÿ’…
  • cancelMonitor() โ€” wipe out all the monitors attached to a NEP object. gone, deleted, no more updates ๐Ÿ“ต
  • computeError(i[, etype]) โ€” crunch the error for the i-th eigenpair you already computed. gotta know how cooked it is ๐Ÿ˜ญ
  • create([comm]) โ€” birth the NEP object. welcome to the world lil guy ๐ŸŒฑ
  • destroy() โ€” bye bye NEP object, release it back into the void ๐Ÿฆ‹
  • errorView([etype, viewer]) โ€” show off the errors that came with your computed solution, on display for the whole timeline ๐Ÿ“Š
  • getBV() โ€” hand you the basis vectors object that's tied to the eigensolver ๐Ÿงบ
  • getCISSExtraction() โ€” what extraction technique is the CISS solver using rn? this tells you ๐Ÿ”Ž
  • getCISSKSPs() โ€” the whole list of linear solver objects linked up with the CISS solver, pls ๐Ÿ“‹
  • getCISSRefinement() โ€” all the various refinement parameters living inside the CISS solver โœจ
  • getCISSSizes() โ€” and now the size parameters of the CISS solver, same energy ๐Ÿ“
  • getCISSThreshold() โ€” oh and the threshold parameters too, CISS solver stays mysterious ๐Ÿ’…
  • getConverged() โ€” how many eigenpairs actually converged? the number. the count. we love a W ๐ŸŽ‰
  • getConvergedReason() โ€” the why behind solve() calling it quits on the iteration. the tea โ˜•
  • getConvergenceTest() โ€” which method is being used to compute the error estimate that feeds the convergence test ๐Ÿงช
  • getDS() โ€” grab the direct solver that's associated with the eigensolver ๐Ÿ› ๏ธ
  • getDimensions() โ€” number of eigenvalues we're trying to compute, the goalpost fr fr ๐Ÿฅ…
  • getEigenpair(i[, Vr, Vi]) โ€” pull the i-th solution of the eigenproblem exactly as solve() computed it. the receipts ๐Ÿงพ
  • getEigenvalueComparison() โ€” the eigenvalue comparison function, get it ๐Ÿ‘‘
  • getErrorEstimate(i) โ€” the error estimate that belongs to the i-th computed eigenpair, bestie wants stats ๐Ÿ“ˆ
  • getFunction() โ€” the function used to compute the nonlinear Function T(\lambda) ๐ŸŒ€
  • getInterpolInterpolation() โ€” the tolerance and the maximum degree for the interpolation polynomial, both of em ๐ŸŽ€
  • getInterpolPEP() โ€” the polynomial eigensolver object that's hanging around with it ๐ŸŒˆ
  • getIterationNumber() โ€” where are we in the iteration count rn? current number, live ๐ŸŽข
  • getJacobian() โ€” the function that computes the Jacobian T'(\lambda) and J ๐Ÿ”ฅ

and that's the vibe check on this chunk, but we are not done, keep scrolling bestie, there's more ๐Ÿ’œ

  • getLeftEigenvector(i, Wr[, Wi]) โ€” get the i-th left eigenvector, the one that solve() went and computed for you ๐Ÿซถ
  • getMonitor() โ€” get the whole list of monitor functions that are currently hooked up ๐Ÿ“‹โœจ
  • getNArnoldiKSP() โ€” get the linear solver object that's besties with the nonlinear eigensolver ๐Ÿ”—
  • getNArnoldiLagPreconditioner() โ€” get how often the preconditioner gets rebuilt, no cap ๐Ÿ”
  • getNLEIGSEPS() โ€” get the linear eigensolver object that hangs out with the nonlinear eigensolver ๐ŸŒธ
  • getNLEIGSFullBasis() โ€” get that flag telling you whether NLEIGS is running the full-basis variant or not ๐ŸŽ€
  • getNLEIGSInterpolation() โ€” get the tolerance and the maximum degree for the interpolation polynomial ๐Ÿ“โœจ
  • getNLEIGSKSPs() โ€” get the list of linear solver objects associated with the NLEIGS solver, all of them, the whole squad ๐Ÿ’…
  • getNLEIGSLocking() โ€” get the locking flag used in the NLEIGS method ๐Ÿ”’
  • getNLEIGSRKShifts() โ€” get the list of shifts used in the Rational Krylov method ๐Ÿ“
  • getNLEIGSRestart() โ€” get the restart parameter used in the NLEIGS method ๐Ÿ”„
  • getOptionsPrefix() โ€” get the prefix used for searching for all NEP options in the database ๐Ÿ”
  • getProblemType() โ€” get the problem type straight off the NEP object ๐Ÿท๏ธ
  • getRG() โ€” get the region object associated to the eigensolver ๐Ÿ—บ๏ธ
  • getRIIConstCorrectionTol() โ€” get the constant tolerance flag โœ…
  • getRIIDeflationThreshold() โ€” get the threshold value that controls deflation ๐Ÿ“‰
  • getRIIHermitian() โ€” get whether the Hermitian version has to be used by the solver ๐Ÿชž
  • getRIIKSP() โ€” get the linear solver object associated with the nonlinear eigensolver ๐Ÿ”—
  • getRIILagPreconditioner() โ€” get how often the preconditioner is rebuilt ๐Ÿ”
  • getRIIMaximumIterations() โ€” get the max number of inner iterations of RII ๐Ÿ”ข
  • getRefine() โ€” get the refinement strategy the NEP object is using ๐Ÿ’Ž
  • getRefineKSP() โ€” get the KSP object the eigensolver uses during the refinement phase ๐Ÿ› ๏ธ
  • getSLPDeflationThreshold() โ€” get the threshold value that controls deflation ๐Ÿ“‰
  • getSLPEPS() โ€” get the linear eigensolver object associated with the nonlinear eigensolver ๐ŸŒธ
  • getSLPEPSLeft() โ€” get the left eigensolver ๐Ÿ‘ˆ
  • getSLPKSP() โ€” get the linear solver object associated with the nonlinear eigensolver ๐Ÿ”—
  • getSplitOperator() โ€” get the operator of the

โ€ฆnonlinear eigenvalue problem in split form. ๐Ÿ’… ok bestie we are still in the big method roster, and honestly it's giving phone-book energy, but every single one of these matters so we're doing them all. no skipping. periodt. ๐Ÿซถ

  • getSplitPreconditioner() โ€” hands you back the operator of the split preconditioner. that's the thing. ๐Ÿ’–
  • getStoppingTest() โ€” gives you the stopping test function. yep, the one that decides when to stop. โœจ
  • getTarget() โ€” returns the value of the target. the target!! ๐ŸŽฏ
  • getTolerances() โ€” tells you the tolerance and the maximum iteration count. both. in one go. iconic. ๐ŸŒธ
  • getTrackAll() โ€” returns the flag saying whether all residual norms have to be computed. it's a flag, it's boolean-coded, we love her. ๐Ÿฆ‹
  • getTwoSided() โ€” returns the flag indicating if a two-sided variant is being used. two-sided! both sides! ๐Ÿ’…
  • getType() โ€” grab the NEP type of this object. literally just its whole identity. main character reveal. ๐Ÿ‘‘
  • getWhichEigenpairs() โ€” returns which portion of the spectrum is being sought. which ones? this tells you which ones. ๐ŸŒˆ
  • reset() โ€” resets the NEP object. clean slate, new era, no baggage. ๐Ÿงš
  • setBV(bv) โ€” sets the basis vectors object associated to the eigensolver. ๐Ÿ’œ
  • setCISSExtraction(extraction) โ€” sets the extraction technique used in the CISS solver. the technique! for the extracting! ๐Ÿ”ฅ
  • setCISSRefinement([inner, blsize]) โ€” sets the values of various refinement parameters in the CISS solver. the optional args are inner and blsize, no cap. โœจ
  • setCISSSizes([ip, bs, ms, npart, bsmax, ...]) โ€” sets the values of various size parameters in the CISS solver. yes there's a little ... at the end, bestie, she contains multitudes. ๐Ÿ’–
  • setCISSThreshold([delta, spur]) โ€” sets the values of various threshold parameters in the CISS solver. the thresholds. the limits. the lines. ๐ŸŽ€
  • setConvergenceTest(conv) โ€” sets how to compute the error estimate used in the convergence test. how, exactly, do we judge you. ๐Ÿ˜ญ
  • setDS(ds) โ€” sets a direct solver object associated to the eigensolver. ds = direct solver. slay. ๐Ÿฆ‹
  • setDimensions([nev, ncv, mpd]) โ€” sets the number of eigenvalues to compute. nev, ncv, mpd, all optional, all important. ๐ŸŒธ
  • setEigenvalueComparison(comparison[, args, ...]) โ€” sets an eigenvalue comparison function. you can pass extra args and more, iykyk. ๐Ÿ’…
  • setFromOptions() โ€” sets NEP options from the options database. the command line said so, so it shall be so. โœจ
  • setFunction(function[, F, P, args, kargs]) โ€” sets the function used to compute the nonlinear Function T(\lambda). yes, backslash-lambda, we're being fancy today. the optional extras are F, P, args and kargs. ๐Ÿ’œ
  • setInitialSpace(space) โ€” sets the initial space from which the eigensolver starts to iterate. the starting point!! the origin story!! ๐ŸŒˆ
  • setInterpolInterpolation([tol, deg]) โ€” sets the tolerance and maximum degree for the interpolation polynomial. tol and deg, both optional. ๐Ÿ”ฅ
  • setInterpolPEP(pep) โ€” sets a polynomial eigensolver object associated to the nonlinear eigensolver. two solvers, one bond. ๐Ÿซถ
  • setJacobian(jacobian[, J, args, kargs]) โ€” sets the function used to compute the Jacobian T'(\lambda). note the lil apostrophe, she's doing calculus. optional J, args, kargs. ๐Ÿ‘‘
  • setMonitor(monitor[, args, kargs]) โ€” appends a monitor function to the list of monitors. appends, bestie, it does not replace. the list grows. ๐ŸŒธ
  • setNArnoldiKSP(ksp) โ€” sets a linear solver object associated to the nonlinear eigensolver. ๐ŸŽ€

okay so the method list is still scrolling, bestie, and it's giving โœจinfiniteโœจ but every single one of these is iconic in its own way so we're doing them all, no skips, no cap ๐Ÿ’…

  • setNArnoldiLagPreconditioner(lag) โ€” sets when the preconditioner gets rebuilt during the nonlinear solve. timing is everything, fr fr ๐Ÿ•
  • setNLEIGSEPS(eps) โ€” hands the nonlinear eigensolver a linear eigensolver object to work with. it's giving "here bestie, hold my eps" ๐Ÿซถ
  • setNLEIGSFullBasis([fullbasis]) โ€” picks between the TOAR-basis variant (that's the default, iykyk) and the full-basis variants of the NLEIGS method. choose your fighter ๐ŸฅŠ
  • setNLEIGSInterpolation([tol, deg]) โ€” sets the tolerance and the maximum degree for the interpolation polynomial. two for one, we love a multitasker ๐Ÿ’–
  • setNLEIGSLocking(lock) โ€” toggles between the locking and non-locking variants of the NLEIGS method. flip the switch, main character energy ๐Ÿ”ฅ
  • setNLEIGSRKShifts(shifts) โ€” sets a list of shifts to be used in the Rational Krylov method. shifts = the whole vibe of RK, periodt โœจ
  • setNLEIGSRestart(keep) โ€” sets the restart parameter for the NLEIGS method. keep it, bestie, don't lose the plot ๐ŸŽ€
  • setOptionsPrefix([prefix]) โ€” sets the prefix used when searching for all NEP options in the database. basically giving your options their own little name tag ๐Ÿท๏ธ
  • setProblemType(problem_type) โ€” sets the type of the eigenvalue problem. gotta know what kind of problem you're in before you solve it, lowkey relatable ๐Ÿ˜ญ
  • setRG(rg) โ€” attaches a region object to the eigensolver. it's the "where do you want the eigenvalues to live" zone ๐ŸŒธ
  • setRIIConstCorrectionTol(cct) โ€” sets a flag to keep the tolerance used in the linear solver constant. no fluctuations allowed here ๐Ÿ’€
  • setRIIDeflationThreshold(deftol) โ€” sets the threshold that decides when to switch between the deflated and non-deflated modes. the deflation version of a vibe check ๐Ÿฆ‹
  • setRIIHermitian(herm) โ€” sets a flag to use the Hermitian version of the solver. Hermitian solver era ๐Ÿ’œ
  • setRIIKSP(ksp) โ€” gives the nonlinear eigensolver a linear solver object to hang out with. besties ๐Ÿค
  • setRIILagPreconditioner(lag) โ€” sets when the preconditioner is rebuilt in the nonlinear solve. (yes it's the RII twin of the Arnoldi one, they're matching ๐Ÿคญ)
  • setRIIMaximumIterations(its) โ€” sets the max. (yep, that's literally the whole line in the original, girlie said "the max" and left it at that ๐Ÿ˜ญ)
  • setRefine(ref[, npart, tol, its, scheme]) โ€” sets the refinement strategy used by the NEP object. glow-up mode for your eigenpairs โœจ๐ŸŽ€
  • setSLPDeflationThreshold(deftol) โ€” sets the threshold used to switch between deflated and non-deflated. same energy as the RII one, just SLP flavored ๐Ÿ’…
  • setSLPEPS(eps) โ€” sets a linear eigensolver object associated to the nonlinear eigensolver. another +1 to the eigensolver friendship circle ๐ŸŒˆ
  • setSLPEPSLeft(eps) โ€” sets a linear eigensolver object associated to the nonlinear eigensolver. this is the left one, so like... the other side of the equation, iconic โญ
  • setSLPKSP(ksp) โ€” sets a linear solver object associated to the nonlinear eigensolver. SLP needed a ksp bestie too, obviously ๐Ÿซถ
  • setSplitOperator(A, f[, structure]) โ€” sets the operator of the nonlinear eigenvalue problem in split form. A and f, doing their own lil thing ๐Ÿ“
  • setSplitPreconditioner(P[, structure]) โ€” sets the operator in split form. the preconditioner said "me too" ๐Ÿ’…
  • setStoppingTest(stopping[, args, kargs]) โ€” sets a function that decides when to stop the outer iteration of the eigensolver. you can even pass it args and kargs, bougie behavior โœจ
  • setTarget(target) โ€” sets the value of the target. know your goal bestie, manifest it ๐ŸŽฏ
  • setTolerances([tol, maxit]) โ€” sets the tolerance and max.

and yeah, that last one literally cuts off right there in the source โ€” "the tolerance and max." and then the page just... leaves us hanging ๐Ÿ˜ญ the next part picks it up, don't worry, we're not abandoning the bit ๐Ÿซถ

  • setTrackAll(trackall) โ€” okay so this sets if the solver must compute the residual of all approximate eigenpairs. literally every single one. ๐Ÿ’–
  • setTwoSided(twosided) โ€” sets the solver to use a two-sided variant. no cap. โœจ
  • setType(nep_type) โ€” sets the particular solver to be used in the NEP object. choose your fighter. ๐Ÿ’…
  • setUp() โ€” sets up all the internal data structures. backstage prep moment. ๐ŸŽ€
  • setWhichEigenpairs(which) โ€” sets which portion of the spectrum is to be sought. know your target. ๐Ÿฆ‹
  • solve() โ€” solves the nonlinear eigenproblem. main character energy. ๐Ÿ”ฅ
  • valuesView([viewer]) โ€” displays the computed eigenvalues in a viewer. show them off. ๐Ÿ‘‘
  • vectorsView([viewer]) โ€” outputs computed eigenvectors to a viewer. the whole ensemble. ๐ŸŒธ
  • view([viewer]) โ€” prints the NEP data structure. receipts. ๐Ÿ’œ

โœจ Attributes Summary โœจ

  • bv โ€” The basis vectors (BV <#slepc4py.SLEPc.BV>) object associated. your basis bestie. ๐Ÿ’–
  • ds โ€” The direct solver (DS <#slepc4py.SLEPc.DS>) object associated. direct solver drip. โœจ
  • max_it โ€” The maximum iteration count used by the NEP convergence tests. the limit. ๐Ÿ”ฅ
  • problem_type โ€” The problem type from the NEP object. the genre of the math. ๐ŸŒˆ
  • rg โ€” The region (RG <#slepc4py.SLEPc.RG>) object associated. region vibes. ๐ŸŽ€
  • target โ€” The value of the target. aim here. ๐ŸŽฏ
  • tol โ€” The tolerance used by the NEP convergence tests. how close is close enough. ๐Ÿ’…
  • track_all โ€” Compute the residual of all approximate eigenpairs. all of them, periodt. ๐Ÿ’–
  • which โ€” The portion of the spectrum to be sought. the chosen slice. ๐Ÿฆ‹

๐Ÿ’… Methods Documentation ๐Ÿ’…

appendOptionsPrefix(prefix=None)

Append to the prefix used for searching for all NEP options in the database. Logically collective. ๐Ÿ’–

Parameters

Return type None <https://docs.python.org/3/library/constants.html#None>

See also: setOptionsPrefix, getOptionsPrefix, NEPAppendOptionsPrefix <https://slepc.upv.es/release/manualpages/NEP/NEPAppendOptionsPrefix.html>

Source code at slepc4py/SLEPc/NEP.pyx:385 (slepc4py/SLEPc/NEP.pyx#L385)

applyResolvent(omega, v, r, rg=None)

Apply the resolvent T^{-1}(z) to a given vector. Collective. ๐Ÿฆ‹

Parameters

Return type None <https://docs.python.org/3/library/constants.html#None>

Notes

The resolvent T^{-1}(z)=\sum_i(z-\lambda_i)^{-1}x_iy_i^* is evaluated at z=\omega and the matrix-vector product r = T^{-1}(\omega) v is computed. Vectors x_i,y_i are right and left eigenvectors, respectively, normalized so that y_i^*T'(\lambda_i)x_i=1. The sum contains only eigenvectors that have been previously computed with solve(), and if a region rg is given then only those corresponding to eigenvalues inside the region are considered. iykyk. โœจ

See also: solve, getLeftEigenvector, NEPApplyResolvent <https://slepc.upv.es/release/manualpages/NEP/NEPApplyResolvent.html>

Source code at slepc4py/SLEPc/NEP.pyx:1834 (slepc4py/SLEPc/NEP.pyx#L1834)

cancelMonitor()

Clear all monitors for a NEP object. Logically collective. ๐Ÿ’–

See also: NEPMonitorCancel <https://slepc.upv.es/release/manualpages/NEP/NEPMonitorCancel.html>

Source code at slepc4py/SLEPc/NEP.pyx:1159 (slepc4py/SLEPc/NEP.pyx#L1159)

Return type None <https://docs.python.org/3/library/constants.html#None>

computeError(i, etype=None)

Compute the error associated with the i-th computed eigenpair. Collective. ๐Ÿฆ‹

Compute the error (based on the residual norm) associated with the i-th computed eigenpair. same thing, extra emphasis. ๐Ÿ’…

Parameters

Returns

The error bound ๐Ÿ’… โ€” computed in various ways from the residual norm \|T(\lambda)x\|_2, where \lambda is the eigenvalue and x is the eigenvector. That's the whole tea.

Return type

float

Notes

  • The index i should be a value between 0 and nconv-1 (peep getConverged() for that, bestie).
  • If the computation of left eigenvectors was enabled with setTwoSided(), then the error gets computed using the maximum of the value above and the left residual norm \|y^*T(\lambda)\|_2, where y is the approximate left eigenvector. Two-sided error, double the drama. โœจ

See also: getErrorEstimate, setTwoSided, NEPComputeError

๐Ÿซถ Source code at slepc4py/SLEPc/NEP.pyx:1385

create(comm=None)

Create the NEP object. Main character origin story fr.

Collective.

Parameters

  • comm (Comm | None) โ€“ MPI communicator. If you don't hand one over, it defaults to all processes. Lowkey generous of it.

Return type

Self

See also: NEPCreate

๐Ÿซถ Source code at slepc4py/SLEPc/NEP.pyx:268

destroy()

Destroy the NEP object. Gotta let it go, bestie ๐Ÿ’€.

Collective.

See also: NEPDestroy

๐Ÿซถ Source code at slepc4py/SLEPc/NEP.pyx:242

Return type

Self

errorView(etype=None, viewer=None)

Display the errors associated with the computed solution. Basically the vibe check for your solve ๐Ÿ˜ญ.

Collective.

Display the errors and the eigenvalues.

Parameters

  • etype (ErrorType | None) โ€“ The error type to compute.
  • viewer (petsc4py.PETSc.Viewer | None) โ€“ Visualization context; if you don't pass one, the standard output is used.

Return type

None

Notes

By default, this function checks the error of all eigenpairs and prints the eigenvalues if all of them are below the requested tolerance. If the viewer has format ASCII_INFO_DETAIL then a table with eigenvalues and corresponding errors is printed. Table? Iconic. ๐Ÿ‘‘

See also: solve, valuesView, vectorsView, NEPErrorView

๐Ÿซถ Source code at slepc4py/SLEPc/NEP.pyx:1428

getBV()

Get the basis vectors object associated to the eigensolver. It's giving "where's my BV at" and the BV is right there.

Not collective.

Returns

The basis vectors context.

Return type

BV

See also: setBV, NEPGetBV

๐Ÿซถ Source code at slepc4py/SLEPc/NEP.pyx:877

getCISSExtraction()

Get the extraction technique used in the CISS solver. Pulling up the receipts on how it extracts, no cap.

Not collective.

Returns

The extraction technique.

Return type

CISSExtraction

See also: setCISSExtraction, NEPCISSGetExtraction

๐Ÿซถ Source code at slepc4py/SLEPc/NEP.pyx:2792

getCISSKSPs()

Get the list of linear solver objects associated with the CISS solver. A whole little squad of KSPs ๐Ÿซถ.

Collective.

Returns

The linear solver objects.

Return type

list of petsc4py.PETSc.KSP

Notes

The number of petsc4py.PETSc.KSP solvers is equal to the number of integration points divided by the number of partitions. This value is halved in the case of real matrices with a region centered at the real axis. Math said halve it, so it halved it. ๐Ÿ’…

See also: setCISSSizes, NEPCISSGetKSPs

๐Ÿซถ Source code at slepc4py/SLEPc/NEP.pyx:2989

getCISSRefinement()

Get the values of various refinement parameters in the CISS solver. Refinement is self-care, honestly โœจ.

Not collective.

Returns

  • inner (int) โ€“ Number of iterative refinement iterations (inner loop).
  • blsize (int) โ€“ Number of iterative refinement iterations (blocksize loop).

Return type

tuple[int, int]

See also: setCISSRefinement, NEPCISSGetRefinement

๐Ÿซถ Source code at slepc4py/SLEPc/NEP.pyx:2967

getCISSSizes()

Get the values of various size parameters in the CISS solver. Sizes on sizes on sizes ๐Ÿ”ฅ.

Not collective.

Returns

  • ip (int) โ€“ Number of integration points.
  • bs (int) โ€“ Block size.
  • ms (int) โ€“ Moment size.
  • npart (int) โ€“ Number of partitions when splitting the communicator.
  • bsmax (int) โ€“ Maximum block size.
  • realmats (bool) โ€“ True if A and B are real.

Return type

tuple[int, int, int, int, int, bool]

See also: setCISSSizes, NEPCISSGetSizes

๐Ÿซถ Source code at slepc4py/SLEPc/NEP.pyx:2865

getCISSThreshold()

Get the values of various threshold parameters in the CISS solver. Thresholds are the boundaries, and we respect boundaries here ๐Ÿ’œ.

Not collective.

Returns

  • delta (float) โ€“ Threshold for numerical rank.
  • spur (float) โ€“ Spurious threshold (to discard spurious eigenpairs.

Return type

tuple[float, float]

See also: setCISSThreshold, NEPCISSGetThreshold

๐Ÿซถ Source code at slepc4py/SLEPc/NEP.pyx:2922

๐Ÿ’– getConverged()

Bestie, this one hands you the number of converged eigenpairs. That's it, that's the whole vibe check.

Not collective โœจ

Returns

  • nconv โ€” Number of converged eigenpairs.

Return type

int โ€” https://docs.python.org/3/library/functions.html#int

Notes ๐ŸŽ€

You gotta call this one after solve() has already finished, okay? Timing matters, queen.

The value nconv may lowkey be different from the number of requested solutions nev, but it will never be larger than ncv โ€” peep setDimensions() for that tea.

See also:

setDimensions, solve, getEigenpair, NEPGetConverged โ€” https://slepc.upv.es/release/manualpages/NEP/NEPGetConverged.html

Source code at slepc4py/SLEPc/NEP.pyx:1256 โ€” slepc4py/SLEPc/NEP.pyx#L1256

๐Ÿ”ฅ getConvergedReason()

Get the reason why the solve() iteration was stopped. Like, why did it stop, bestie? What was the drama? ๐Ÿ™ˆ

Not collective

Returns

Negative value indicates diverged ๐Ÿ˜ญ, positive value converged ๐Ÿ’….

Return type

ConvergedReason โ€” https://slepc4py.SLEPc.NEP.ConvergedReason

See also:

setTolerances, solve, NEPGetConvergedReason โ€” https://slepc.upv.es/release/manualpages/NEP/NEPGetConvergedReason.html

Source code at slepc4py/SLEPc/NEP.pyx:1237 โ€” slepc4py/SLEPc/NEP.pyx#L1237

๐ŸŒธ getConvergenceTest()

Gets the method used to compute the error estimate that gets used in the convergence test. The whole โœจbehind-the-scenesโœจ math moment.

Not collective

Returns

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

Return type

Conv โ€” https://slepc4py.SLEPc.NEP.Conv

See also:

setConvergenceTest, NEPGetConvergenceTest โ€” https://slepc.upv.es/release/manualpages/NEP/NEPGetConvergenceTest.html

Source code at slepc4py/SLEPc/NEP.pyx:624 โ€” slepc4py/SLEPc/NEP.pyx#L624

๐Ÿฆ‹ getDS()

Get the direct solver that's associated to the eigensolver. It's giving "who's your plus-one" energy. ๐Ÿ’œ

Not collective

Returns

The direct solver context.

Return type

DS โ€” https://slepc4py.SLEPc.DS

See also:

setDS, NEPGetDS โ€” https://slepc.upv.es/release/manualpages/NEP/NEPGetDS.html

Source code at slepc4py/SLEPc/NEP.pyx:951 โ€” slepc4py/SLEPc/NEP.pyx#L951

๐Ÿ‘‘ getDimensions()

Get the number of eigenvalues to compute. But plot twist โ€” it also scoops up the dimension of the subspace while it's at it. Main character multitasking. โœจ

Not collective

Get the number of eigenvalues to compute, and the dimension of the subspace.

Returns

Return type

tuple โ€” https://docs.python.org/3/library/stdtypes.html#tuple[int โ€” https://docs.python.org/3/library/functions.html#int, int โ€” https://docs.python.org/3/library/functions.html#int, int โ€” https://docs.python.org/3/library/functions.html#int]

See also:

setDimensions, NEPGetDimensions โ€” https://slepc.upv.es/release/manualpages/NEP/NEPGetDimensions.html

Source code at slepc4py/SLEPc/NEP.pyx:795 โ€” slepc4py/SLEPc/NEP.pyx#L795

๐ŸŽ€ getEigenpair(i, Vr=None, Vi=None)

Grab the i-th solution of the eigenproblem, exactly as computed by solve(). Iconic behaviour, no notes. ๐Ÿ’…

Collective

The solution serves up both the eigenvalue and the eigenvector. Two for one, we love to see it.

Parameters

Returns

The computed eigenvalue.

Return type

complex โ€” https://docs.python.org/3/library/functions.html#complex

Notes ๐Ÿซถ

The index i should be a value between 0 and nconv-1 (peep getConverged()). Eigenpairs get indexed according to the ordering criterion you set up with setWhichEigenpairs().

The eigenvector is normalized to have unit norm. Periodt. โœจ

See also:

solve, getConverged, setWhichEigenpairs, NEPGetEigenpair โ€” https://slepc.upv.es/release/manualpages/NEP/NEPGetEigenpair.html

Source code at slepc4py/SLEPc/NEP.pyx:1282 โ€” slepc4py/SLEPc/NEP.pyx#L1282

๐ŸŒˆ getEigenvalueComparison()

Get the eigenvalue comparison function. The lil function deciding who's who and what ranks above what. ๐Ÿงš

Not collective

Returns

The eigenvalue comparison function.

Return type

NEPEigenvalueComparison โ€” https://slepc4py.typing.NEPEigenvalueComparison

See also:

setEigenvalueComparison

Source code at slepc4py/SLEPc/NEP.pyx:1100 โ€” slepc4py/SLEPc/NEP.pyx#L1100

๐Ÿ’œ getErrorEstimate(i)

Get the error estimate associated to the i-th computed eigenpair. Little accuracy gut-check, bestie.

Not collective

Parameters

Returns

Error estimate.

Return type

float โ€” https://docs.python.org/3/library/functions.html#float

Notes ๐Ÿ˜ญ

This here is the error estimate used internally by the eigensolver. The actual error bound can be computed with computeError().

See also:

computeError, NEPGetErrorEstimate โ€” https://slepc.upv.es/release/manualpages/NEP/NEPGetErrorEstimate.html

Source code at slepc4py/SLEPc/NEP.pyx:1356 โ€” slepc4py/SLEPc/NEP.pyx#L1356

โญ getFunction()

Get the function to compute the nonlinear Function T(\lambda). The absolute moment of the whole nonlinear-eigenproblem situation. ๐Ÿ”ฅ

Collective

Get the function to compute the nonlinear Function T(\lambda) and the matrix. Surprise, you get both.

Returns

Return type

tuple โ€” https://docs.python.org/3/library/stdtypes.html#tuple[petsc4py.PETSc.Mat โ€” https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat, petsc4py.PETSc.Mat โ€” https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat, NEPFunction โ€” https://slepc4py.typing.NEPFunction]

See also:

setFunction, NEPGetFunction โ€” https://slepc.upv.es/release/manualpages/NEP/NEPGetFunction.html

Source code at slepc4py/SLEPc/NEP.pyx:1540 โ€” slepc4py/SLEPc/NEP.pyx#L1540

๐Ÿ“ getInterpolInterpolation()

Get the tolerance and the maximum degree for the interpolation polynomial. Two lil values, one call, we love an efficient queen. โœจ

Not collective

Returns

Return type

tuple โ€” https://docs.python.org/3/library/stdtypes.html#tuple[float โ€” https://docs.python.org/3/library/functions.html#float, int โ€” https://docs.python.org/3/library/functions.html#int]

See also:

setInterpolInterpolation, NEPInterpolGetInterpolation โ€” https://slepc.upv.es/release/manualpages/NEP/NEPInterpolGetInterpolation.html

Source code at slepc4py/SLEPc/NEP.pyx:2444 โ€” slepc4py/SLEPc/NEP.pyx#L2444

๐Ÿฆ‹ getInterpolPEP()

Get the associated polynomial eigensolver object.

Collective. (everybody's in on this one, no solo missions ๐Ÿ’…)

Returns: the polynomial eigensolver.

Return type: PEP

See also: setInterpolPEP, NEPInterpolGetPEP

Source: slepc4py/SLEPc/NEP.pyx:2401

getIterationNumber()</p> ๐Ÿ”ข

Grab the current iteration number, bestie.

Not collective. (she's doing this one all by herself โœจ)

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

Returns: iteration number.

Return type: int

See also: getConvergedReason, setTolerances, NEPGetIterationNumber

Source: slepc4py/SLEPc/NEP.pyx:1215

getJacobian()</p> ๐Ÿงฎ

Get the function to compute the Jacobian T'(\lambda) and J. The way this method serves double dutyโ€ฆ iconic.

Collective.

Get the function to compute the Jacobian T'(\lambda) and the matrix. yeah, both. she contains multitudes ๐Ÿ’–

Returns:

  • J (petsc4py.PETSc.Mat) โ€“ Jacobian matrix.
  • jacobian (NEPJacobian) โ€“ Jacobian evaluation routine.

Return type: tuple[petsc4py.PETSc.Mat, NEPJacobian]

See also: setJacobian, NEPGetJacobian

Source: slepc4py/SLEPc/NEP.pyx:1606

getLeftEigenvector(i, Wr, Wi=None)</p> ๐Ÿฆ‹

Get the i-th left eigenvector as computed by solve(). slay.

Collective.

Parameters:

  • i (int) โ€“ Index of the solution to be obtained.
  • Wr (Vec) โ€“ Placeholder for the returned eigenvector (real part).
  • Wi (Vec | None) โ€“ Placeholder for the returned eigenvector (imaginary part).

Return type: None

Notes

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

Left eigenvectors are available only if the twosided flag was set with setTwoSided(). no flag, no left vectors, periodt. ๐Ÿ˜ญ

See also: getEigenpair, getConverged, setTwoSided, NEPGetLeftEigenvector

Source: slepc4py/SLEPc/NEP.pyx:1323

getMonitor()</p> ๐Ÿ‘€

Get the list of monitor functions.

Not collective.

Returns: the list of monitor functions.

Return type: NEPMonitorFunction

See also: setMonitor

Source: slepc4py/SLEPc/NEP.pyx:1142

getNArnoldiKSP()</p> ๐ŸŽ€

Get the linear solver object associated with the nonlinear eigensolver.

Collective.

Returns: the linear solver object.

Return type: petsc4py.PETSc.KSP

See also: setNArnoldiKSP, NEPNArnoldiGetKSP

Source: slepc4py/SLEPc/NEP.pyx:2318

getNArnoldiLagPreconditioner()</p> โณ

Get how often the preconditioner is rebuilt. (she's keeping count, bestie ๐Ÿซถ)

Not collective.

Returns: the lag parameter.

Return type: int

See also: setNArnoldiLagPreconditioner, NEPNArnoldiGetLagPreconditioner

Source: slepc4py/SLEPc/NEP.pyx:2363

getNLEIGSEPS()</p> ๐ŸŒธ

Get the linear eigensolver object associated with the nonlinear eigensolver.

Collective.

Returns: the linear eigensolver.

Return type: EPS

See also: setNLEIGSEPS, NEPNLEIGSGetEPS

Source: slepc4py/SLEPc/NEP.pyx:2675

getNLEIGSFullBasis()</p> ๐Ÿงบ

Get the flag that indicates if NLEIGS is using the full-basis variant.

Not collective.

Returns: True if the full-basis variant is selected.

Return type: bool

See also: setNLEIGSFullBasis, NEPNLEIGSGetFullBasis

Source: slepc4py/SLEPc/NEP.pyx:2639

getNLEIGSInterpolation()</p> ๐Ÿ“

Get the tolerance and maximum degree for the interpolation polynomial.

Not collective.

Get the tolerance and maximum degree when building the interpolation via divided differences. math girlies rise ๐Ÿ™ˆ

Returns:

  • tol (float) โ€“ The tolerance to stop computing divided differences.
  • deg (int) โ€“ The maximum degree of interpolation.

Return type: tuple[float, int]

See also: setNLEIGSInterpolation, NEPNLEIGSGetInterpolation

Source: slepc4py/SLEPc/NEP.pyx:2581

getNLEIGSKSPs()</p> ๐Ÿ”ฅ

Get the list of linear solver objects associated with the NLEIGS solver. not a solver โ€” the whole roster ๐Ÿ‘‘

Collective.

Returns: the linear solver objects.

Return type: list of petsc4py.PETSc.KSP

Notes

The number of petsc4py.PETSc.KSP solvers is equal to the number of shifts provided by the user, or 1 if the user did not provide shifts. literally one per shift, or just the one lonely KSP fr fr.

See also: setNLEIGSRKShifts, NEPNLEIGSGetKSPs

Source: slepc4py/SLEPc/NEP.pyx:2747

getNLEIGSLocking()</p> ๐Ÿ”’

Get the locking flag used in the NLEIGS method.

Not collective.

Returns: the locking flag.

Return type: bool

See also: setNLEIGSLocking, NEPNLEIGSGetLocking

Source: slepc4py/SLEPc/NEP.pyx:2536

getNLEIGSRKShifts()</p> ๐ŸŒˆ

Get the list of shifts used in the Rational Krylov method. main character shifts, honestly โœจ

Not collective.

Returns: the shift values.

Return type: ArrayScalar

๐Ÿ“Ž source: slepc4py/SLEPc/NEP.pyx:2722

See also: setNLEIGSRKShifts, NEPNLEIGSGetRKShifts

๐Ÿ’ซ getNLEIGSRestart()

Get the restart parameter used in the NLEIGS method. bestie this is the "how much do we keep when we hit reset" knob โœจ

Not collective โ€” every process does its own thing, no group chat required ๐Ÿ’…

Returns: the number of vectors to be kept at restart.

Return type: float

See also: setNLEIGSRestart, NEPNLEIGSGetRestart

๐Ÿ“Ž source: slepc4py/SLEPc/NEP.pyx:2492

๐ŸŽ€ getOptionsPrefix()

Get the prefix used for searching for all NEP options in the database. basically the little name tag your options wear so the object can find them ๐Ÿท๏ธ

Not collective.

Returns: the prefix string set for this NEP object.

Return type: str

See also: setOptionsPrefix, appendOptionsPrefix, NEPGetOptionsPrefix

๐Ÿ“Ž source: slepc4py/SLEPc/NEP.pyx:335

๐ŸŒธ getProblemType()

Get the problem type from the NEP object. she's telling you what kind of problem she's solving, no cap ๐Ÿ’–

Not collective.

Returns: the problem type that was previously set.

Return type: ProblemType

See also: setProblemType, NEPGetProblemType

๐Ÿ“Ž source: slepc4py/SLEPc/NEP.pyx:423

๐Ÿฆ‹ getRG()

Get the region object associated to the eigensolver. the region is giving "where do I even look for eigenvalues" main character energy ๐Ÿ‘‘

Not collective.

Returns: the region context.

Return type: RG

See also: setRG, NEPGetRG

๐Ÿ“Ž source: slepc4py/SLEPc/NEP.pyx:914

โœจ getRIIConstCorrectionTol()

Get the constant tolerance flag. tells you if the correction tolerance is just gonna sit there being constant or not ๐Ÿ™ˆ

Not collective.

Returns: if True, the petsc4py.PETSc.KSP relative tolerance is constant.

Return type: bool

See also: setRIIConstCorrectionTol, NEPRIIGetConstCorrectionTol

๐Ÿ“Ž source: slepc4py/SLEPc/NEP.pyx:1942

๐Ÿ’… getRIIDeflationThreshold()

Get the threshold value that controls deflation. deflation = yeeting stuff out of the way so it stops bothering the solver, lowkey iconic ๐Ÿ—‘๏ธ

Not collective.

Returns: the threshold value.

Return type: float

See also: setRIIDeflationThreshold, NEPRIIGetDeflationThreshold

๐Ÿ“Ž source: slepc4py/SLEPc/NEP.pyx:2081

๐ŸŒˆ getRIIHermitian()

Get if the Hermitian version must be used by the solver. Hermitian bestie, are we doing it or not ๐Ÿ’œ

Not collective.

Returns: if True, the Hermitian version is used.

Return type: bool

See also: setRIIHermitian, NEPRIIGetHermitian

๐Ÿ“Ž source: slepc4py/SLEPc/NEP.pyx:2031

๐Ÿ”ฅ getRIIKSP()

Get the linear solver object associated with the nonlinear eigensolver. little linear solver tucked inside the big nonlinear one, cute ๐Ÿซถ

Collective โ€” everybody in the communicator gets in on this one, fr fr.

Returns: the linear solver object.

Return type: petsc4py.PETSc.KSP

See also: setRIIKSP, NEPRIIGetKSP

๐Ÿ“Ž source: slepc4py/SLEPc/NEP.pyx:2117

๐Ÿ“ getRIILagPreconditioner()

Get how often the preconditioner is rebuilt. are we rebuilding every time or being lazy and reusing? ๐Ÿค”

Not collective.

Returns: the lag parameter.

Return type: int

See also: setRIILagPreconditioner, NEPRIIGetLagPreconditioner

๐Ÿ“Ž source: slepc4py/SLEPc/NEP.pyx:1898

โญ getRIIMaximumIterations()

Get the maximum number of inner iterations of RII. like, cap on how many times the inner loop is allowed to go ๐ŸŒ€

Not collective.

Returns: maximum inner iterations.

Return type: int

See also: setRIIMaximumIterations, NEPRIIGetMaximumIterations

๐Ÿ“Ž source: slepc4py/SLEPc/NEP.pyx:1983

๐Ÿงš getRefine()

Get the refinement strategy used by the NEP object. the glow-up phase of your eigenpairs โœจ

Not collective.

Returns:

  • ref (Refine) โ€“ the refinement type.
  • npart (int) โ€“ the number of partitions of the communicator.
  • tol (float) โ€“ the convergence tolerance.
  • its (int) โ€“ the maximum number of refinement iterations.
  • scheme (RefineScheme) โ€“ scheme for solving linear systems.

Return type: tuple[Refine, int, float, int, RefineScheme]

See also: setRefine, NEPGetRefine

๐Ÿ“Ž source: slepc4py/SLEPc/NEP.pyx:663

๐Ÿ’œ getRefineKSP()

Get the KSP object used by the eigensolver in the refinement phase. yes, the refinement phase has its own lil linear solver ๐Ÿ’–

Collective.

Returns: the linear solver object.

Return type: petsc4py.PETSc.KSP

See also: setRefine, NEPRefineGetKSP

๐Ÿ“Ž source: slepc4py/SLEPc/NEP.pyx:738

๐ŸŽ€ getSLPDeflationThreshold()

Get the threshold value that controls deflation. same deflation vibe, but the SLP edition ๐Ÿ’ซ

Not collective.

Returns: the threshold value.

Return type: float

See also: setSLPDeflationThreshold, NEPSLPGetDeflationThreshold

๐Ÿ“Ž source: slepc4py/SLEPc/NEP.pyx:2167

๐Ÿ‘‘ getSLPEPS()

Get the linear eigensolver object associated with the nonlinear eigensolver. it's giving "eigensolver inside an eigensolver", turducken but make it linear algebra ๐Ÿฆƒ

Collective.

Returns: the linear eigensolver.

Return type: EPS

See also: setSLPEPS, NEPSLPGetEPS

๐Ÿ“Ž source: slepc4py/SLEPc/NEP.pyx:2203

๐ŸŒธ getSLPEPSLeft()

Get the left eigensolver. yep, there's a left one too, not just the right one โ€” she contains multitudes ๐Ÿ’…

Collective.

Returns: the linear eigensolver.

Return type: EPS

getSLPKSP()

Bestie, this is the one that hands you the linear solver object that's linked up with your nonlinear eigensolver. ๐Ÿซถ

Collective. (yes queen, meaning every process in the communicator has to show up for this ๐Ÿ’…)

Returns: the linear solver object.

Return type: petsc4py.PETSc.KSP

See also: setSLPKSP, NEPSLPGetKSP

Source code lives at slepc4py/SLEPc/NEP.pyx:2279 โœจ

getSplitOperator()

Grabs the operator of the nonlinear eigenvalue problem, but in split form โ€” like, it's giving "we broke it into pieces" energy. ๐Ÿงš

Collective.

Returns:

  • A (list of petsc4py.PETSc.Mat) โ€” Coefficient matrices of the split form.
  • f (list of FN) โ€” Scalar functions of the split form.
  • structure (petsc4py.PETSc.Mat.Structure) โ€” Structure flag for matrices.

Return type: tuple[list[petsc4py.PETSc.Mat], list[FN], petsc4py.PETSc.Mat.Structure]

See also: setSplitOperator, NEPGetSplitOperatorInfo, NEPGetSplitOperatorTerm

Source code lives at slepc4py/SLEPc/NEP.pyx:1683 ๐ŸŒธ

getSplitPreconditioner()

Same energy as the last one but for the preconditioner โ€” it's the split version, okay?? ๐Ÿ˜Œ

Not collective.

Returns:

  • P (list of petsc4py.PETSc.Mat) โ€” Coefficient matrices of the split preconditioner.
  • structure (petsc4py.PETSc.Mat.Structure) โ€” Structure flag for matrices.

Return type: tuple[list[petsc4py.PETSc.Mat], petsc4py.PETSc.Mat.Structure]

See also: setSplitPreconditioner, NEPGetSplitPreconditionerTerm

Source code lives at slepc4py/SLEPc/NEP.pyx:1752 ๐Ÿ’œ

getStoppingTest()

Returns the stopping test function, aka the thing that decides when we're done here. ๐Ÿ›‘

Not collective.

Returns: the stopping test function.

Return type: NEPStoppingFunction

See also: setStoppingTest

Source code lives at slepc4py/SLEPc/NEP.pyx:1053 โœจ

getTarget()

Gets the value of the target. ๐ŸŽฏ

Not collective.

Returns: the value of the target.

Return type: Scalar

Notes

If the target was not set by the user, then zero is returned. (so like, no target = you get a 0, no cap ๐Ÿซ )

See also: setTarget, NEPGetTarget

Source code lives at slepc4py/SLEPc/NEP.pyx:521 ๐Ÿ’–

getTolerances()

Pulls up the tolerance and the maximum iteration count โ€” the two numbers the default NEP convergence tests are running on. ๐Ÿ“

Not collective.

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

Returns:

  • tol (float) โ€” The convergence tolerance.
  • maxit (int) โ€” The maximum number of iterations.

Return type: tuple[float, int]

See also: setTolerances, NEPGetTolerances

Source code lives at slepc4py/SLEPc/NEP.pyx:571 ๐ŸŒˆ

getTrackAll()

Checks the flag that says whether all residual norms have to be computed. Head empty, just residuals. ๐Ÿ’ญ

Not collective.

Returns: Whether the solver computes all residuals or not.

Return type: bool

See also: setTrackAll, NEPGetTrackAll

Source code lives at slepc4py/SLEPc/NEP.pyx:758 ๐Ÿฆ‹

getTwoSided()

Asks the age-old question: are we running a two-sided variant of the algorithm or not? ๐Ÿ‘€

Not collective.

Get the flag indicating whether a two-sided variant of the algorithm is being used or not.

Returns: Whether the two-sided variant is to be used or not.

Return type: bool

See also: setTwoSided, NEPGetTwoSided

Source code lives at slepc4py/SLEPc/NEP.pyx:1781 โญ

getType()

Tells you the NEP type of this object. Simple. Iconic. ๐Ÿ’…

Not collective.

Returns: The solver currently being used.

Return type: str

See also: setType, NEPGetType

Source code lives at slepc4py/SLEPc/NEP.pyx:316 ๐Ÿ”ฅ

getWhichEigenpairs()

Which slice of the spectrum are we hunting for? This is the getter that tells you. ๐Ÿ•ต๏ธโ€โ™€๏ธ

Not collective.

Returns: The portion of the spectrum to be sought by the solver.

Return type: Which

See also: setWhichEigenpairs, NEPGetWhichEigenpairs

Source code lives at slepc4py/SLEPc/NEP.pyx:467 ๐ŸŒธ

reset()

Resets the whole NEP object. Fresh start, clean slate, main character energy. โœจ

Collective.

See also: NEPReset

Source code lives at slepc4py/SLEPc/NEP.pyx:256 ๐Ÿ’œ

Return type: None

setBV(bv)

Wires up the basis vectors object to the eigensolver. Gotta give it somewhere to live, bestie. ๐ŸŽ€

Collective.

Parameters:

  • bv (BV) โ€” The basis vectors context.

Return type: None

See also: getBV, NEPSetBV

Source code lives at slepc4py/SLEPc/NEP.pyx:897 ๐Ÿ’–

โœจ setCISSExtraction(extraction) โœจ

bestie this one sets the extraction technique that the CISS solver uses ๐ŸŽ€

Logically collective โ€” everybody in the communicator gotta be on the same page, no solo missions ๐Ÿ’ซ

Parameters

  • extraction (CISSExtraction) โ€” the extraction technique. that's it, that's the whole thing.

Return type: None

See also: getCISSExtraction, NEPCISSSetExtraction

๐Ÿ“Ž Source code at slepc4py/SLEPc/NEP.pyx:2774

๐Ÿฆ‹ setCISSRefinement(inner=None, blsize=None) ๐Ÿฆ‹

sets the values of the various refinement parameters in the CISS solver. tuning era fr โœจ

Logically collective โ€” collective, bestie, everyone together ๐Ÿซถ

Parameters

  • inner (int | None) โ€” number of iterative refinement iterations (that's the inner loop ๐Ÿ’…).
  • blsize (int | None) โ€” number of iterative refinement iterations (and that's the blocksize loop ๐Ÿ‘‘).

Return type: None

See also: getCISSRefinement, NEPCISSSetRefinement

๐Ÿ“Ž Source code at slepc4py/SLEPc/NEP.pyx:2944

๐ŸŒธ setCISSSizes(ip=None, bs=None, ms=None, npart=None, bsmax=None, realmats=False) ๐ŸŒธ

sets the values of the various size parameters in the CISS solver. so many knobs, so little time ๐Ÿ˜ญ

Logically collective โ€” yep, collective again ๐ŸŒˆ

Parameters

  • ip (int | None) โ€” number of integration points.
  • bs (int | None) โ€” block size.
  • ms (int | None) โ€” moment size.
  • npart (int | None) โ€” number of partitions when splitting the communicator, iykyk.
  • bsmax (int | None) โ€” maximum block size.
  • realmats (bool) โ€” True if A and B are real.

Return type: None

Notes

the default number of partitions is 1. that means the internal petsc4py.PETSc.KSP object is shared among all processes of the NEP communicator โ€” one KSP, everyone sharing, community vibes ๐Ÿซ‚

otherwise (like, if you actually set npart), the communicator gets split into npart communicators, so that npart petsc4py.PETSc.KSP solves proceed simultaneously. parallel main character energy โšก

See also: getCISSSizes, setCISSThreshold, setCISSRefinement, NEPCISSSetSizes

๐Ÿ“Ž Source code at slepc4py/SLEPc/NEP.pyx:2811

๐Ÿ’œ setCISSThreshold(delta=None, spur=None) ๐Ÿ’œ

sets the values of the various threshold parameters in the CISS solver. thresholds are literally the vibe check of this solver ๐ŸŽ€

Logically collective โ€” collective, always ๐Ÿ’ซ

Parameters

  • delta (float | None) โ€” threshold for numerical rank.
  • spur (float | None) โ€” spurious threshold, used to discard spurious eigenpairs (bye felicia to the fake ones ๐Ÿ‘‹).

Return type: None

See also: getCISSThreshold, NEPCISSSetThreshold

๐Ÿ“Ž Source code at slepc4py/SLEPc/NEP.pyx:2899

๐Ÿ”ฅ setConvergenceTest(conv) ๐Ÿ”ฅ

sets how to compute the error estimate that gets used in the convergence test. choosing your metric, iconic behavior ๐Ÿ’…

Logically collective โ€” you already know ๐ŸŒธ

Parameters

  • conv (Conv) โ€” the method used to compute the error estimate used in the convergence test.

Return type: None

See also: getConvergenceTest, NEPSetConvergenceTest

๐Ÿ“Ž Source code at slepc4py/SLEPc/NEP.pyx:644

๐Ÿ“ setDS(ds) ๐Ÿ“

attaches a direct solver object to the eigensolver. like setting your eigensolver up with a whole direct solver bestie ๐Ÿ’ž

Collective โ€” collective, periodt ๐Ÿ‘‘

Parameters

  • ds (DS) โ€” the direct solver context.

Return type: None

See also: getDS, NEPSetDS

๐Ÿ“Ž Source code at slepc4py/SLEPc/NEP.pyx:971

โœจ setDimensions(nev=None, ncv=None, mpd=None) โœจ

sets the number of eigenvalues to compute. and also the dimension of the subspace while we're at it ๐Ÿ’–

Logically collective โ€” collective, no cap ๐Ÿ™ˆ

sets the number of eigenvalues to compute and the dimension of the subspace. two things, one call, efficiency slay.

Parameters

  • nev (int | None) โ€” number of eigenvalues 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 โ€” and that value depends on the solution method, so it's not a one-size-fits-all situation ๐Ÿงš

ncv and mpd are intimately related (they're giving soulmates fr fr), so you're advised to set at most one of them. normal usage goes like this:

  • when nev is small, you set ncv โ€” and a reasonable default is 2 * nev.
  • when nev is large, you set mpd.

the value of ncv should always be between nev and (nev + mpd), typically ncv = nev + mpd. if nev isn't too large, mpd = nev is a reasonable choice โ€” otherwise use a smaller value. that's the rule, bestie, don't fight it ๐Ÿ’…

See also: getDimensions, NEPSetDimensions

๐Ÿ“Ž Source code at slepc4py/SLEPc/NEP.pyx:823

๐ŸŒˆ setEigenvalueComparison(comparison, args=None, kargs=None) ๐ŸŒˆ

sets an eigenvalue comparison function. custom sorting, very much a choose-your-own-adventure moment ๐Ÿฆ‹

Logically collective โ€” collective, you know the drill โญ

Notes

this eigenvalue comparison function gets used when setWhichEigenpairs() is set to NEP.Which.USER. iykyk ๐Ÿ‘€

See also: getEigenvalueComparison, NEPSetEigenvalueComparison

๐Ÿ“Ž Source code at slepc4py/SLEPc/NEP.pyx:1070

Parameters

  • comparison (NEPEigenvalueComparison | None)
  • args (tuple[Any, ...] | None)
    • kargs (dict[str, Any] | None)

Return type: None

setFromOptions()</p>

okay bestie, this one sets all the NEP options straight from the options database. ๐Ÿ’…

Collective. (yes, everybody has to be on the same page, literally ๐Ÿซถ)

Notes ๐Ÿ“

  • To see every single option, just run your program with the -help option. it's giving "read the menu before you order" energy ๐Ÿ“
  • This routine must be called before setUp() if you want to let the user pick the solver type. no cap, order matters โญ

See also: setOptionsPrefix, NEPSetFromOptions

๐Ÿฆ‹ Source code at slepc4py/SLEPc/NEP.pyx:404

Return type: None

setFunction(function, F=None, P=None, args=None, kargs=None)</p>

Set the function that computes the nonlinear Function T(\lambda). โœจ

Collective.

So like, this sets the function to compute the nonlinear Function T(\lambda) and it tells SLEPc where to stash the matrix. two birds, one slay ๐Ÿฆ

Parameters ๐ŸŽ€

  • function (NEPFunction) โ€” the Function evaluation routine.
  • F (petsc4py.PETSc.Mat | None) โ€” the Function matrix.
  • P (petsc4py.PETSc.Mat | None) โ€” the Preconditioner matrix (usually the same as F).
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type: None

See also: setJacobian, getFunction, NEPSetFunction

๐Ÿฆ‹ Source code at slepc4py/SLEPc/NEP.pyx:1500

setInitialSpace(space)</p>

Set the initial space that the eigensolver starts iterating from. ๐ŸŒธ

Collective.

Parameters

  • space (Vec) โ€” The initial space.

Return type: None

Notes ๐Ÿ“

  • Some solvers start to iterate on a single vector (the initial vector). In that case, only the first vector is taken into account and the other vectors get ignored. sorry to the rest of them ๐Ÿ’€
  • These vectors do not persist from one solve() call to the other, so bestie you have to set the initial space every single time. it does not carry over ๐Ÿ™ˆ
  • The vectors do not need to be mutually orthonormal, because they get explicitly orthonormalized internally. so don't stress about it ๐Ÿงš
  • The common usage of this function is when the user can hand over a rough approximation of the wanted eigenspace. then convergence may be faster. and we love fast ๐Ÿ”ฅ

See also: setUp, NEPSetInitialSpace

๐Ÿฆ‹ Source code at slepc4py/SLEPc/NEP.pyx:990

setInterpolInterpolation(tol=None, deg=None)</p>

Set the tolerance and the maximum degree for the interpolation polynomial. ๐Ÿ’œ

Collective.

Parameters ๐ŸŽ€

  • tol (float | None) โ€” The tolerance to stop computing polynomial coefficients.
  • deg (int | None) โ€” The maximum degree of interpolation.

Return type: None

See also: getInterpolInterpolation, NEPInterpolSetInterpolation

๐Ÿฆ‹ Source code at slepc4py/SLEPc/NEP.pyx:2421

setInterpolPEP(pep)</p>

Set a polynomial eigensolver object that's associated to the nonlinear eigensolver. ๐Ÿ‘‘

Collective.

Parameters

  • pep (PEP) โ€” The polynomial eigensolver.

Return type: None

See also: getInterpolPEP, NEPInterpolSetPEP

๐Ÿฆ‹ Source code at slepc4py/SLEPc/NEP.pyx:2384

setJacobian(jacobian, J=None, args=None, kargs=None)</p>

Set the function that computes the Jacobian T'(\lambda). โœจ

Collective.

It sets the function to compute the Jacobian T'(\lambda), plus the location where the matrix gets stored. the dynamic duo fr fr ๐Ÿซถ

Parameters ๐ŸŽ€

  • jacobian (NEPJacobian) โ€” the Jacobian evaluation routine.
  • J (petsc4py.PETSc.Mat | None) โ€” the Jacobian matrix.
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type: None

See also: setFunction, getJacobian, NEPSetJacobian

๐Ÿฆ‹ Source code at slepc4py/SLEPc/NEP.pyx:1570

setMonitor(monitor, args=None, kargs=None)</p>

Append a monitor function to the list of monitors. ๐ŸŒˆ

Logically collective.

See also: getMonitor, cancelMonitor, NEPMonitorSet

๐Ÿฆ‹ Source code at slepc4py/SLEPc/NEP.pyx:1117

Parameters ๐ŸŽ€

  • monitor (NEPMonitorFunction | None)
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type: None

setNArnoldiKSP(ksp)</p>

Set a linear solver object that's associated to the nonlinear eigensolver. ๐Ÿ’…

Collective.

Parameters

  • ksp (KSP) โ€” The linear solver object.

Return type โ€” None <https://docs.python.org/3/library/constants.html#None>

See also: getNArnoldiKSP, NEPNArnoldiSetKSP <https://slepc.upv.es/release/manualpages/NEP/NEPNArnoldiSetKSP.html>

:sources:Source code at slepc4py/SLEPc/NEP.pyx:2301 <slepc4py/SLEPc/NEP.pyx#L2301>

setNArnoldiLagPreconditioner(lag)

Bestie, this one sets when the preconditioner gets rebuilt during the nonlinear solve. โœจ

Logically collective. ๐Ÿซถ

Parameters

Return type โ€” None <https://docs.python.org/3/library/constants.html#None>

Notes

The default is 1. ๐Ÿ“Œ And listen โ€” the preconditioner is ALWAYS built in the first iteration of a nonlinear solve. No takebacks, it's giving mandatory. ๐Ÿ’…

See also: getNArnoldiLagPreconditioner, NEPNArnoldiSetLagPreconditioner <https://slepc.upv.es/release/manualpages/NEP/NEPNArnoldiSetLagPreconditioner.html>

:sources:Source code at slepc4py/SLEPc/NEP.pyx:2338 <slepc4py/SLEPc/NEP.pyx#L2338>

setNLEIGSEPS(eps)

Ok so this one attaches a linear eigensolver object to the nonlinear eigensolver. ๐ŸŒธ

Collective. ๐Ÿ‘‘

Parameters

  • eps (EPS <#slepc4py.SLEPc.EPS>) โ€” The linear eigensolver.

Return type โ€” None <https://docs.python.org/3/library/constants.html#None>

See also: getNLEIGSEPS, NEPNLEIGSSetEPS <https://slepc.upv.es/release/manualpages/NEP/NEPNLEIGSSetEPS.html>

:sources:Source code at slepc4py/SLEPc/NEP.pyx:2658 <slepc4py/SLEPc/NEP.pyx#L2658>

setNLEIGSFullBasis(fullbasis=True)

Pick the TOAR-basis (that's the default, bestie ๐ŸŽ€) or the full-basis variant of the NLEIGS method.

Logically collective. โœจ

Toggle between TOAR-basis (default) and full-basis variants of the NLEIGS method.

Parameters

Return type โ€” None <https://docs.python.org/3/library/constants.html#None>

Notes

The default is to use a compact representation of the Krylov basis, that is, V = (I \otimes U) S, with a BV <#slepc4py.SLEPc.BV> of type TENSOR <#slepc4py.SLEPc.BV.Type.TENSOR>. ๐Ÿฆ‹ This behavior can be changed so that the full basis V is explicitly stored and operated with. This variant is more expensive in terms of memory and computation, but is necessary in some cases, particularly for two-sided computations, see setTwoSided().

In the full-basis variant, the NLEIGS solver uses an EPS <#slepc4py.SLEPc.EPS> object to explicitly solve the linearized eigenproblem, see getNLEIGSEPS().

See also: setTwoSided, getNLEIGSFullBasis, getNLEIGSEPS, NEPNLEIGSSetFullBasis <https://slepc.upv.es/release/manualpages/NEP/NEPNLEIGSSetFullBasis.html>

:sources:Source code at slepc4py/SLEPc/NEP.pyx:2606 <slepc4py/SLEPc/NEP.pyx#L2606>

setNLEIGSInterpolation(tol=None, deg=None)

Sets the tolerance AND the maximum degree for the interpolation polynomial. Two-for-one, iconic. ๐Ÿ’œ

Collective.

Set the tolerance and maximum degree when building the interpolation via divided differences.

Parameters

Return type โ€” None <https://docs.python.org/3/library/constants.html#None>

See also: getNLEIGSInterpolation, NEPNLEIGSSetInterpolation <https://slepc.upv.es/release/manualpages/NEP/NEPNLEIGSSetInterpolation.html>

:sources:Source code at slepc4py/SLEPc/NEP.pyx:2555 <slepc4py/SLEPc/NEP.pyx#L2555>

setNLEIGSLocking(lock)

Flip between the locking and non-locking variants of the NLEIGS method. ๐ŸŽ€

Logically collective.

Parameters

Return type โ€” None <https://docs.python.org/3/library/constants.html#None>

Notes

The default is to lock converged eigenpairs 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 โ€” that's the non-locking variant, bestie.

See also: getNLEIGSLocking, NEPNLEIGSSetLocking <https://slepc.upv.es/release/manualpages/NEP/NEPNLEIGSSetLocking.html>

:sources:Source code at slepc4py/SLEPc/NEP.pyx:2511 <slepc4py/SLEPc/NEP.pyx#L2511>

setNLEIGSRKShifts(shifts)

Hand it a whole list of shifts to use in the Rational Krylov method. ๐Ÿฆ‹

Collective.

Parameters

Return type โ€” None <https://docs.python.org/3/library/constants.html#None>

Notes

If only one shift is provided, the built subspace is equivalent to shift-and-invert Krylov-Schur (provided that the absolute convergence criterion is used). โญ Otherwise, the rational Krylov variant is run.

See also: getNLEIGSRKShifts, getNLEIGSKSPs, NEPNLEIGSSetRKShifts <https://slepc.upv.es/release/manualpages/NEP/NEPNLEIGSSetRKShifts.html>

:sources:Source code at slepc4py/SLEPc/NEP.pyx:2695 <slepc4py/SLEPc/NEP.pyx#L2695>

setNLEIGSRestart(keep)

Sets the restart parameter for the NLEIGS method โ€” like, how much of the basis survives the restart. ๐Ÿ’…

Logically collective.

The proportion of basis vectors that must be kept after restart.

Parameters

Return type โ€” None <https://docs.python.org/3/library/constants.html#None>

Notes

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

See also: getNLEIGSRestart, NEPNLEIGSSetRestart <https://slepc.upv.es/release/manualpages/NEP/NEPNLEIGSSetRestart.html>

:sources:Source code at slepc4py/SLEPc/NEP.pyx:2468 <slepc4py/SLEPc/NEP.pyx#L2468>

setOptionsPrefix(prefix=None)

Sets the prefix that gets used when searching for all NEP options in the database. It's the name tag of your NEP, basically. ๐Ÿท๏ธ

Logically collective.

Parameters

Return type โ€” None <https://docs.python.org/3/library/constants.html#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. Periodt.

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

N1.setOptionsPrefix("nep1_")
N2.setOptionsPrefix("nep2_")

See also: appendOptionsPrefix, getOptionsPrefix, NEPGetOptionsPrefix <https://slepc.upv.es/release/manualpages/NEP/NEPGetOptionsPrefix.html>

:sources:Source code at slepc4py/SLEPc/NEP.pyx:354 <slepc4py/SLEPc/NEP.pyx#L354>

setProblemType(problem_type)

Sets the type of the eigenvalue problem. ๐Ÿ‘‘

Logically collective.

Parameters

  • problem_type (ProblemType <#slepc4py.SLEPc.NEP.ProblemType>) โ€” The problem type to be set.

Return type โ€” None <https://docs.python.org/3/library/constants.html#None>

Notes

This function is used to provide a hint to the NEP solver to exploit certain properties of the nonlinear eigenproblem. ๐Ÿ’ก This hint may be used or not, depending on the solver. By default, no particular structure is assumed.

๐Ÿ”— :sources: Source code at slepc4py/SLEPc/NEP.pyx:442 <slepc4py/SLEPc/NEP.pyx#L442>

setRG(rg)

okay bestie, this one attaches a region object to your eigensolver ๐Ÿ’–

Collective. (yes, everybody in the communicator, together, periodt โœจ)

Parameters:

  • rg (RG <#slepc4py.SLEPc.RG>) โ€” the region context, that's it, that's the whole vibe ๐ŸŽ€

Return type: None <https://docs.python.org/3/library/constants.html#None>

๐Ÿ”— :sources: Source code at slepc4py/SLEPc/NEP.pyx:934 <slepc4py/SLEPc/NEP.pyx#L934>

setRIIConstCorrectionTol(cct)

Sets a flag so the tolerance used in the linear solver stays constant. No drifting, no shrinking, just vibes held steady ๐Ÿงš

Logically collective.

Parameters:

Return type: None <https://docs.python.org/3/library/constants.html#None>

Notes

so by default, the tolerance is set to decrease exponentially inside the KSP used within the nonlinear iteration โ€” the way that each Newton iteration asks for better accuracy than the one before it ๐Ÿ˜ญ. This constant correction tolerance flag stops that behavior. Like, it says "no more tightening, we're staying right here" ๐Ÿซถ

๐Ÿ”— :sources: Source code at slepc4py/SLEPc/NEP.pyx:1917 <slepc4py/SLEPc/NEP.pyx#L1917>

setRIIDeflationThreshold(deftol)

Sets the threshold used to switch between deflated and non-deflated. The girlies love a threshold ๐Ÿ’–

Logically collective.

Sets the threshold value used to switch between deflated and non-deflated iteration.

Parameters:

Return type: None <https://docs.python.org/3/library/constants.html#None>

Notes

ngl, normally the solver iterates on the extended problem so it can deflate the eigenpairs it already converged ๐Ÿ‘‘. But if you set this threshold to a nonzero value, then once the residual error drops below this threshold, the solver will continue the iteration without deflation. The intention? To be able to improve the current eigenpair further, even though you've got previous eigenpairs with kind of mid precision ๐Ÿ™ˆ. It's giving "let me cook".

๐Ÿ”— :sources: Source code at slepc4py/SLEPc/NEP.pyx:2050 <slepc4py/SLEPc/NEP.pyx#L2050>

setRIIHermitian(herm)

Sets a flag to use the Hermitian version of the solver ๐Ÿ’œ

Logically collective.

Sets a flag to indicate if the Hermitian version of the scalar nonlinear equation must be used by the solver.

Parameters:

Return type: None <https://docs.python.org/3/library/constants.html#None>

Notes

okay so by default, the scalar nonlinear equation

x^*T(\sigma)^{-1}T(z)x=0

is solved at each step of the nonlinear iteration ๐ŸŒˆ. When this flag is set, the simpler form

x^*T(z)x=0

is used โ€” which is supposed to be valid only for Hermitian problems. Only. For Hermitian. Do not play with this one, bestie ๐Ÿ˜ญ

๐Ÿ”— :sources: Source code at slepc4py/SLEPc/NEP.pyx:2002 <slepc4py/SLEPc/NEP.pyx#L2002>

setRIIKSP(ksp)

Attaches a linear solver object to the nonlinear eigensolver ๐ŸŽ€

Collective.

Parameters:

Return type: None <https://docs.python.org/3/library/constants.html#None>

๐Ÿ”— :sources: Source code at slepc4py/SLEPc/NEP.pyx:2100 <slepc4py/SLEPc/NEP.pyx#L2100>

setRIILagPreconditioner(lag)

Tells you when the preconditioner gets rebuilt in the nonlinear solve ๐Ÿฆ‹

Logically collective.

Parameters:

Return type: None <https://docs.python.org/3/library/constants.html#None>

๐Ÿ”— :sources: Source code at slepc4py/SLEPc/NEP.pyx:1878 <slepc4py/SLEPc/NEP.pyx#L1878>

setRIIMaximumIterations(its)

Sets the max number of inner iterations used in the RII solver โญ

Logically collective.

These are the Newton iterations related to the computation of the nonlinear Rayleigh functional, iykyk ๐Ÿ’ซ

Parameters:

Return type: None <https://docs.python.org/3/library/constants.html#None>

๐Ÿ”— :sources: Source code at slepc4py/SLEPc/NEP.pyx:1962 <slepc4py/SLEPc/NEP.pyx#L1962>

setRefine(ref, npart=None, tol=None, its=None, scheme=None)

Sets the refinement strategy used by the NEP object, plus all its little associated parameters ๐ŸŽ€โœจ

Logically collective.

Sets the refinement strategy used by the NEP object and the associated parameters.

Parameters:

Return type: None <https://docs.python.org/3/library/constants.html#None>

๐Ÿ”— :sources: Source code at slepc4py/SLEPc/NEP.pyx:694 <slepc4py/SLEPc/NEP.pyx#L694>

setSLPDeflationThreshold(deftol)

Sets the threshold used to switch between deflated and non-deflated. Yes, again, but this one's the SLP flavor ๐Ÿ’–

Logically collective.

Parameters:

Return type: None <https://docs.python.org/3/library/constants.html#None>

Notes

so normally, the solver iterates on the extended problem in order to deflate previously converged eigenpairs ๐Ÿ‘‘. If this threshold is set to a nonzero value, then once the residual error is below this threshold, the solver will continue the iteration without deflation. The intention is to be able to improve the current eigenpair further, despite having previous eigenpairs with somewhat bad precision ๐Ÿ™ˆ. Main character energy: fixing up the one eigenpair instead of babysitting the old ones.

๐Ÿ”— :sources: Source code at slepc4py/SLEPc/NEP.pyx:2139 <slepc4py/SLEPc/NEP.pyx#L2139>

๐ŸŒธ setSLPEPS(eps)

Bestie, this one attaches a linear eigensolver object to your nonlinear eigensolver. That's it, that's the whole vibe. ๐Ÿ’–

Collective. (so like, everyone in the comm has to call it together, okay?)

Parameters

  • eps (EPS) โ€” the linear eigensolver. ๐Ÿ’…

Return type: None

See also: getSLPEPS, NEPSLPSetEPS

Source code at slepc4py/SLEPc/NEP.pyx:2186

๐Ÿฆ‹ setSLPEPSLeft(eps)

Same energy as above, but make it left. Sets a linear eigensolver object associated to the nonlinear eigensolver. ๐ŸŽ€

Collective.

Lowkey the important bit: this one is used to compute left eigenvectors in the two-sided variant of SLP. So if you're doing two-sided, this is your girl.

Parameters

  • eps (EPS) โ€” the linear eigensolver. โœจ

Return type: None

See also: setTwoSided, setSLPEPS, getSLPEPSLeft, NEPSLPSetEPSLeft

Source code at slepc4py/SLEPc/NEP.pyx:2223

๐Ÿ’œ setSLPKSP(ksp)

Okay so this hooks up a linear solver object to the nonlinear eigensolver. Matching them up, getting them acquainted, iconic. ๐Ÿ‘‘

Collective.

Parameters

  • ksp (petsc4py.PETSc.KSP) โ€” the linear solver object. ๐Ÿ”ฅ

Return type: None

See also: getSLPKSP, NEPSLPSetKSP

Source code at slepc4py/SLEPc/NEP.pyx:2262

๐ŸŒธ setSplitOperator(A, f, structure=None)

Not me showing up with the split form operator of the nonlinear eigenvalue problem. Say it with me: split form. โœจ

Collective.

Parameters

  • A (petsc4py.PETSc.Mat | list[petsc4py.PETSc.Mat]) โ€” coefficient matrices of the split form.
  • f (FN | list[FN]) โ€” scalar functions of the split form.
  • structure (petsc4py.PETSc.Mat.Structure | None) โ€” structure flag for matrices.

Return type: None

Notes ๐Ÿซถ

The nonlinear operator is written as:

T(\lambda) = \sum_i A_i f_i(\lambda), for i=1,\dots,n.

And the derivative T'(\lambda) can be obtained using the derivatives of f_i. Math bestie behavior, honestly.

The structure flag provides information about A_i's nonzero pattern.

Real talk: this function must be called before setUp(). If you call it again after setUp(), then the NEP object is reset. No cap, the object just gets thrown back to square one. ๐Ÿ’€

See also: getSplitOperator, NEPSetSplitOperator

Source code at slepc4py/SLEPc/NEP.pyx:1632

๐ŸŽ€ setSplitPreconditioner(P, structure=None)

Set the operator in split form โ€” the preconditioner edition. ๐Ÿฆ‹

Collective.

So the tea: this sets the operator in split form from which to build the preconditioner to be used when solving the nonlinear eigenvalue problem in split form.

Parameters

  • P (petsc4py.PETSc.Mat | list[petsc4py.PETSc.Mat]) โ€” coefficient matrices of the split preconditioner.
  • structure (petsc4py.PETSc.Mat.Structure | None) โ€” structure flag for matrices.

Return type: None

See also: getSplitPreconditioner, NEPSetSplitPreconditioner

Source code at slepc4py/SLEPc/NEP.pyx:1719

๐Ÿ’– setStoppingTest(stopping, args=None, kargs=None)

Okay okay okay โ€” this one hands the solver a function that decides when to stop the outer iteration of the eigensolver. Like a little referee. ๐Ÿงš

Logically collective.

Parameters

  • stopping (NEPStoppingFunction | None)
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type: None

See also: getStoppingTest, NEPSetStoppingTestFunction

Source code at slepc4py/SLEPc/NEP.pyx:1029

โญ setTarget(target)

Sets the value of the target, bestie. ๐ŸŽฏ

Logically collective.

Parameters

  • target (Scalar) โ€” the value of the target.

Return type: None

Notes

The target is a scalar value used to determine the portion of the spectrum of interest. It's used in combination with setWhichEigenpairs() โ€” they're a package deal, iykyk. โœจ

Heads up: when PETSc is built with real scalars, it is not possible to specify a complex target. Sorry gorgeous, the math said no. ๐Ÿ˜ญ

See also: getTarget, setWhichEigenpairs, NEPSetTarget

Source code at slepc4py/SLEPc/NEP.pyx:544

๐ŸŒˆ setTolerances(tol=None, maxit=None)

Sets the tolerance and the maximum iteration count used in convergence tests. The classic duo. ๐Ÿ’…

Logically collective.

Parameters

  • tol (float | None) โ€” the convergence tolerance.
  • maxit (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. Let the solver pick for you, main character energy. ๐Ÿ‘‘

See also: getTolerances, NEPSetTolerances

Source code at slepc4py/SLEPc/NEP.pyx:596

๐Ÿ”ฅ setTrackAll(trackall)

Sets whether the solver must compute the residual of all approximate eigenpairs. All of them. Every single one. Obsessed. ๐Ÿ’€

Logically collective.

Parameters

  • trackall (bool) โ€” whether to compute all residuals or not.

Return type: None

Source code at slepc4py/SLEPc/NEP.pyx:1029

See also: getTrackAll, NEPSetTrackAll, https://slepc.upv.es/release/manualpages/NEP/NEPSetTrackAll.html

Source code at slepc4py/SLEPc/NEP.pyx:777

๐ŸŒธ setTwoSided(twosided)

Bestie, this one flips your solver into the two-sided era. ๐Ÿ’… Logically collective, so like, everyone shows up to the function.

Setting this makes the solver compute left eigenvectors too, not just the right ones.

Parameters

Return type: None, https://docs.python.org/3/library/constants.html#None

Notes ๐Ÿซถ

If the user sets twosided to True then the solver uses a variant of the algorithm that computes both right and left eigenvectors. This is usually much more costly. This option is not available in all solvers, no cap.

When using two-sided solvers, the problem matrices must have both the Mat.mult and Mat.multTranspose operations defined.

See also: getTwoSided, getLeftEigenvector, NEPSetTwoSided, https://slepc.upv.es/release/manualpages/NEP/NEPSetTwoSided.html

Source code at slepc4py/SLEPc/NEP.pyx:1803

๐Ÿ‘‘ setType(nep_type)

Pick which solver your NEP object is gonna be, basically choosing its whole personality. Logically collective. โœจ

Parameters

Return type: None, https://docs.python.org/3/library/constants.html#None

Notes ๐Ÿ’œ

The default is RII (#slepc4py.SLEPc.NEP.Type.RII). Normally, it's best to use setFromOptions() and then set the NEP type from the options database rather than by using this routine. Using the options database gives the user maximum flexibility in evaluating the different available methods. Periodt.

See also: getType, NEPSetType, https://slepc.upv.es/release/manualpages/NEP/NEPSetType.html

Source code at slepc4py/SLEPc/NEP.pyx:289

๐Ÿงš setUp()

Sets up all the internal data structures. Collective โ€” everybody in the group chat has to be here for this one. ๐ŸŒˆ

Notes

Sets up all the internal data structures necessary for the execution of the eigensolver.

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. Lowkey a timer flex. โฑ๏ธ

See also: solve, NEPSetUp, https://slepc.upv.es/release/manualpages/NEP/NEPSetUp.html

Source code at slepc4py/SLEPc/NEP.pyx:1174

Return type: None, https://docs.python.org/3/library/constants.html#None

๐Ÿฆ‹ setWhichEigenpairs(which)

Decides which slice of the spectrum we're hunting for. Logically collective, iconic behaviour only. ๐Ÿ’…

Parameters

  • which (Which, #slepc4py.SLEPc.NEP.Which) โ€” the portion of the spectrum to be sought by the solver.

Return type: None, https://docs.python.org/3/library/constants.html#None

Notes ๐ŸŒธ

Not all eigensolvers implemented in NEP account for all the possible values. Also, some values make sense only for certain types of problems. If SLEPc is compiled for real numbers, NEP.Which.LARGEST_IMAGINARY (#slepc4py.SLEPc.NEP.Which.LARGEST_IMAGINARY) and NEP.Which.SMALLEST_IMAGINARY (#slepc4py.SLEPc.NEP.Which.SMALLEST_IMAGINARY) use the absolute value of the imaginary part for eigenvalue selection. Not me being subtle about it. ๐Ÿ™ˆ

The target is a scalar value provided with setTarget().

The criterion NEP.Which.TARGET_IMAGINARY (#slepc4py.SLEPc.NEP.Which.TARGET_IMAGINARY) is available only in case PETSc and SLEPc have been built with complex scalars.

NEP.Which.ALL (#slepc4py.SLEPc.NEP.Which.ALL) is intended for use in the context of the PEP.Type.CISS (#slepc4py.SLEPc.PEP.Type.CISS) solver for computing all eigenvalues in a region.

See also: getWhichEigenpairs, setTarget, PEPSetWhichEigenpairs, https://slepc.upv.es/release/manualpages/PEP/PEPSetWhichEigenpairs.html

Source code at slepc4py/SLEPc/NEP.pyx:486

๐Ÿ”ฅ solve()

Solve the nonlinear eigenproblem. Collective. This is the main character moment of the whole file, fr fr. ๐Ÿ‘‘

Notes

solve() will return without generating an error regardless of whether all requested solutions were computed or not. So don't you dare assume victory โ€” call getConverged() to get the actual number of computed solutions, and getConvergedReason() to determine if the solver converged or failed and why. Vibe check accordingly. ๐Ÿ’€

See also: setUp, getConverged, getConvergedReason, NEPSolve, https://slepc.upv.es/release/manualpages/NEP/NEPSolve.html

Source code at slepc4py/SLEPc/NEP.pyx:1195

Return type: None, https://docs.python.org/3/library/constants.html#None

๐ŸŽ€ valuesView(viewer=None)

Display the computed eigenvalues in a viewer. Collective. โœจ

Parameters

Return type: None, https://docs.python.org/3/library/constants.html#None

See also: solve, vectorsView, errorView, NEPValuesView, https://slepc.upv.es/release/manualpages/NEP/NEPValuesView.html

Source code at slepc4py/SLEPc/NEP.pyx:1460

๐Ÿ“ vectorsView(viewer=None)

Output the computed eigenvectors to a viewer. Collective, bestie. ๐Ÿซถ

Parameters

Return type: None, https://docs.python.org/3/library/constants.html#None

See also: solve, valuesView, errorView, NEPVectorsView, https://slepc.upv.es/release/manualpages/NEP/NEPVectorsView.html

Source code at slepc4py/SLEPc/NEP.pyx:1479

๐Ÿ’– view(viewer=None)

Print the NEP data structure. Collective.

Parameters

Return type: None, https://docs.python.org/3/library/constants.html#None

See also: NEPView, https://slepc.upv.es/release/manualpages/NEP/NEPView.html

Source code at slepc4py/SLEPc/NEP.pyx:223

๐Ÿ“‹ Attributes Documentation ๐Ÿซถ

Get into it โ€” these are the attributes, and honestly they ate. ๐Ÿ’…

โญ bv

The basis vectors (BV, #slepc4py.SLEPc.BV) object associated.

Source code at slepc4py/SLEPc/NEP.pyx:3058

๐ŸŒˆ ds

The direct solver (DS, #slepc4py.SLEPc.DS) object associated.

Source code at slepc4py/SLEPc/NEP.pyx:3072

๐Ÿงฎ max_it

The maximum iteration count used by the NEP convergence tests.

Source code at slepc4py/SLEPc/NEP.pyx:3044

๐Ÿฆ‹ problem_type

The problem type from the NEP object.

Source code at slepc4py/SLEPc/NEP.pyx:3016

๐ŸŽ€ rg

The region (RG, #slepc4py.SLEPc.RG) object associated.

Source code at slepc4py/SLEPc/NEP.pyx:3065

๐ŸŽฏ target

The value of the target.

Source code at slepc4py/SLEPc/NEP.pyx:3030

๐ŸŒธ tol

The tolerance used by the NEP convergence tests.

Source code at slepc4py/SLEPc/NEP.pyx:3037

๐Ÿ” track_all

Compute the residual of all approximate eigenpairs.

Source code at slepc4py/SLEPc/NEP.pyx:3051

โœจ which

The portion of the spectrum to be sought.

Source code at slepc4py/SLEPc/NEP.pyx:3023

๐Ÿ’œ __init__()

๐Ÿ’œ classmethod __new__(*args, **kwargs)

okay bestie, we're deep in PEP territory now, and next up is its lil roster of enums โ€” think of them as the settings menu for everything polynomial-eigenvalue-shaped. ๐ŸŒธ every single one, coming right up:

โœจ Enumerations โœจ

  • Basis โ€” PEP basis type for the representation of the polynomial.
  • CISSExtraction โ€” PEP CISS extraction technique.
  • Conv โ€” PEP convergence test.
  • ConvergedReason โ€” PEP convergence reasons.
  • ErrorType โ€” PEP error type to assess accuracy of computed solutions.
  • Extract โ€” PEP extraction strategy used.
  • JDProjection โ€” PEP type of projection to be used in the Jacobi-Davidson solver.
  • ProblemType โ€” PEP problem type.
  • Refine โ€” PEP refinement strategy.
  • RefineScheme โ€” PEP scheme for solving linear systems during iterative refinement.
  • Scale โ€” PEP scaling strategy.
  • Stop โ€” PEP stopping test.
  • Type โ€” PEP type.
  • Which โ€” PEP desired part of spectrum.

๐Ÿฆ‹ slepc4py.SLEPc.PEP.Basis ๐Ÿฆ‹

Bases: object (the plain Python one, at https://docs.python.org/3/library/functions.html#object)

PEP basis type for the representation of the polynomial. โœจ

  • MONOMIAL: Monomials (default). โ† yes she's the default, main character behaviour fr ๐Ÿ’…
  • CHEBYSHEV1: Chebyshev polynomials of the 1st kind.
  • CHEBYSHEV2: Chebyshev polynomials of the 2nd kind.
  • LEGENDRE: Legendre polynomials.
  • LAGUERRE: Laguerre polynomials.
  • HERMITE: Hermite polynomials.

See also: PEPBasis โ€” https://slepc.upv.es/release/manualpages/PEP/PEPBasis.html

๐Ÿ“‹ Attributes Summary

  • CHEBYSHEV1 โ€” Constant CHEBYSHEV1 of type int.
  • CHEBYSHEV2 โ€” Constant CHEBYSHEV2 of type int.
  • HERMITE โ€” Constant HERMITE of type int.
  • LAGUERRE โ€” Constant LAGUERRE of type int.
  • LEGENDRE โ€” Constant LEGENDRE of type int.
  • MONOMIAL โ€” Constant MONOMIAL of type int.

๐Ÿ“– Attributes Documentation

  • CHEBYSHEV1: int = CHEBYSHEV1 โ€” Constant CHEBYSHEV1 of type int.
  • CHEBYSHEV2: int = CHEBYSHEV2 โ€” Constant CHEBYSHEV2 of type int.
  • HERMITE: int = HERMITE โ€” Constant HERMITE of type int.
  • LAGUERRE: int = LAGUERRE โ€” Constant LAGUERRE of type int.
  • LEGENDRE: int = LEGENDRE โ€” Constant LEGENDRE of type int.
  • MONOMIAL: int = MONOMIAL โ€” Constant MONOMIAL of type int.

and then the usual object-y duo, right at the bottom of the Basis class: ๐Ÿซถ

__init__()
classmethod __new__(*args, **kwargs)

not me just rattling off every single constant without missing one, because we do not skip, ever. ๐Ÿ’– keeping going bestie, there's more where that came fromโ€ฆ ๐ŸŒˆ

๐Ÿซถ slepc4py.SLEPc.PEP.CISSExtraction ๐Ÿซถ

class slepc4py.SLEPc.PEP.CISSExtraction

Bases: object

okay so this one is the PEP CISS extraction technique bestie, it's literally the vibe-picker for how PEP pulls its answers out of the CISS solver โœจ

  • RITZ โ€” Ritz extraction, the classic, the moment ๐Ÿ’…
  • HANKEL โ€” extraction via Hankel eigenproblem ๐ŸŒธ
  • CAA โ€” communication-avoiding Arnoldi, iconic ๐Ÿ”ฅ
See also: PEPCISSExtraction โ€” https://slepc.upv.es/release/manualpages/PEP/PEPCISSExtraction.html ๐Ÿ‘‘

โœจ Attributes Summary โœจ

  • CAA โ€” Constant CAA of type int
  • HANKEL โ€” Constant HANKEL of type int
  • RITZ โ€” Constant RITZ of type int

๐ŸŽ€ Attributes Documentation ๐ŸŽ€

  • CAA: int = CAA โ€” Constant CAA of type int
  • HANKEL: int = HANKEL โ€” Constant HANKEL of type int
  • RITZ: int = RITZ โ€” Constant RITZ of type int

๐Ÿฆ‹ Methods ๐Ÿฆ‹

  • __init__()
  • classmethod __new__(*args, **kwargs)

๐Ÿ’– slepc4py.SLEPc.PEP.Conv ๐Ÿ’–

class slepc4py.SLEPc.PEP.Conv

Bases: object

and THIS one is the PEP convergence test, aka how the solver decides it's done and can go home ๐Ÿซถ

  • ABS โ€” absolute convergence test, no notes ๐Ÿ“
  • REL โ€” convergence test relative to the eigenvalue ๐ŸŒˆ
  • NORM โ€” convergence test relative to the matrix norms โญ
  • USER โ€” user-defined convergence test, you're the main character now ๐Ÿ‘‘
See also: PEPConv โ€” https://slepc.upv.es/release/manualpages/PEP/PEPConv.html ๐Ÿ’œ

โœจ Attributes Summary โœจ

  • ABS โ€” Constant ABS of type int
  • NORM โ€” Constant NORM of type int
  • REL โ€” Constant REL of type int
  • USER โ€” Constant USER of type int

๐ŸŽ€ Attributes Documentation ๐ŸŽ€

  • ABS: int = ABS โ€” Constant ABS of type int
  • NORM: int = NORM โ€” Constant NORM of type int
  • REL: int = REL โ€” Constant REL of type int
  • USER: int = USER โ€” Constant USER of type int

๐Ÿฆ‹ Methods ๐Ÿฆ‹

  • __init__()
  • classmethod __new__(*args, **kwargs)

๐ŸŒŸ slepc4py.SLEPc.PEP.ConvergedReason ๐ŸŒŸ

class slepc4py.SLEPc.PEP.ConvergedReason

Bases: object

slay, this is the PEP convergence reasons โ€” the little receipts telling you why the solver stopped, and bestie you WILL want to check them ๐Ÿ˜ญ

  • CONVERGED_TOL โ€” all eigenpairs converged to the requested tolerance, we ate ๐Ÿ’…
  • CONVERGED_USER โ€” user-defined convergence criterion satisfied, your rules, your win ๐Ÿ‘‘
  • DIVERGED_ITS โ€” maximum number of iterations exceeded, rip ๐Ÿ’€
  • DIVERGED_BREAKDOWN โ€” solver failed due to breakdown, it's giving chaos ๐Ÿ™ˆ
  • DIVERGED_SYMMETRY_LOST โ€” Lanczos-type method could not preserve symmetry, the symmetry left the chat ๐Ÿ˜ญ
  • CONVERGED_ITERATING โ€” iteration not finished yet, hold on, we're still cooking ๐Ÿ”ฅ
See also: PEPConvergedReason โ€” https://slepc.upv.es/release/manualpages/PEP/PEPConvergedReason.html โœจ

โœจ Attributes Summary โœจ

  • CONVERGED_ITERATING โ€” Constant CONVERGED_ITERATING of type int
  • CONVERGED_TOL โ€” Constant CONVERGED_TOL of type int
  • CONVERGED_USER โ€” Constant CONVERGED_USER of type int
  • DIVERGED_BREAKDOWN โ€” Constant DIVERGED_BREAKDOWN of type int
  • DIVERGED_ITS โ€” Constant DIVERGED_ITS of type int
  • DIVERGED_SYMMETRY_LOST โ€” Constant DIVERGED_SYMMETRY_LOST of type int
  • ITERATING โ€” Constant ITERATING of type int

okay so the rest of the attributes are just... constants, bestie. every single one is an int, and every single one is literally named after itself ๐Ÿ’– lowkey iconic behaviour, no notes.

  • CONVERGED_ITERATING: int = CONVERGED_ITERATING โ€” constant CONVERGED_ITERATING of type int โœจ
  • CONVERGED_TOL: int = CONVERGED_TOL โ€” constant CONVERGED_TOL of type int
  • CONVERGED_USER: int = CONVERGED_USER โ€” constant CONVERGED_USER of type int
  • DIVERGED_BREAKDOWN: int = DIVERGED_BREAKDOWN โ€” constant DIVERGED_BREAKDOWN of type int ๐Ÿ’€
  • DIVERGED_ITS: int = DIVERGED_ITS โ€” constant DIVERGED_ITS of type int
  • DIVERGED_SYMMETRY_LOST: int = DIVERGED_SYMMETRY_LOST โ€” constant DIVERGED_SYMMETRY_LOST of type int ๐Ÿ˜ญ
  • ITERATING: int = ITERATING โ€” constant ITERATING of type int

and then the two lil method-looking guys that every single one of these classes has, fr fr:

  • __init__()
  • classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.PEP.ErrorType

class slepc4py.SLEPc.PEP.ErrorType

Bases: object ๐Ÿซถ

okay so this one is the PEP error type to assess accuracy of computed solutions โœจ like, which flavour of "how wrong are we tho" are you asking for.

  • ABSOLUTE โ€” absolute error. ๐ŸŽฏ
  • RELATIVE โ€” relative error.
  • BACKWARD โ€” backward error.

See also: PEPErrorType ๐ŸŒธ

Attributes Summary

  • ABSOLUTE โ€” constant ABSOLUTE of type int
  • BACKWARD โ€” constant BACKWARD of type int
  • RELATIVE โ€” constant RELATIVE of type int

Attributes Documentation

  • ABSOLUTE: int = ABSOLUTE โ€” constant ABSOLUTE of type int ๐Ÿ’–
  • BACKWARD: int = BACKWARD โ€” constant BACKWARD of type int
  • RELATIVE: int = RELATIVE โ€” constant RELATIVE of type int
  • __init__()
  • classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.PEP.Extract

class slepc4py.SLEPc.PEP.Extract

Bases: object ๐Ÿฆ‹

this is the PEP extraction strategy used โ€” and more specifically, the strategy used to obtain eigenvectors of the PEP from the eigenvectors of the linearization ๐Ÿงš like, you've got the linearization's vectors, now how do we turn them back into PEP eigenvectors? pick your fighter:

  • NONE โ€” use the first block. ๐Ÿ™ˆ
  • NORM โ€” use the first or last block depending on norm of H.
  • RESIDUAL โ€” use the block with smallest residual. ๐Ÿ“‰
  • STRUCTURED โ€” combine all blocks in a certain way.

See also: PEPExtract ๐ŸŒˆ

Attributes Summary

  • NONE โ€” constant NONE of type int
  • NORM โ€” constant NORM of type int
  • RESIDUAL โ€” constant RESIDUAL of type int
  • STRUCTURED โ€” constant STRUCTURED of type int

Attributes Documentation

  • NONE: int = NONE โ€” constant NONE of type int โœจ
  • NORM: int = NORM โ€” constant NORM of type int
  • RESIDUAL: int = RESIDUAL โ€” constant RESIDUAL of type int
  • STRUCTURED: int = STRUCTURED โ€” constant STRUCTURED of type int
  • __init__()
  • classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.PEP.JDProjection

class slepc4py.SLEPc.PEP.JDProjection

Bases: object ๐Ÿ’œ

the PEP type of projection to be used in the Jacobi-Davidson solver ๐Ÿ‘‘ Jacobi-Davidson girlies rise, you've got options:

  • HARMONIC โ€” harmonic projection. ๐ŸŽถ
  • ORTHOGONAL โ€” orthogonal projection.

See also: PEPJDProjection โญ

Attributes Summary

  • HARMONIC โ€” constant HARMONIC of type int
  • ORTHOGONAL โ€” constant ORTHOGONAL of type int

Attributes Documentation

  • HARMONIC: int = HARMONIC โ€” constant HARMONIC of type int ๐ŸŒธ
  • ORTHOGONAL: int = ORTHOGONAL โ€” constant ORTHOGONAL of type int
  • __init__()
  • classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.PEP.ProblemType

class slepc4py.SLEPc.PEP.ProblemType

Bases: object ๐ŸŽ€

SLEPc is giving us the PEP problem type menu, bestie, and it's honestly a whole vibe check on what structure your polynomial eigenproblem is allowed to have โœจ

  • GENERAL โ€” no structure at all, it's giving free spirit ๐Ÿฆ‹
  • HERMITIAN โ€” Hermitian structure, we love a self-adjoint moment ๐Ÿ’…
  • HYPERBOLIC โ€” QEP with Hermitian matrices, M>0, and (x^TCx)^2 > 4(x^TMx)(x^TKx)
  • GYROSCOPIC โ€” QEP with M, K Hermitian, M>0, and C skew-Hermitian

See also: PEPProblemType <https://slepc.upv.es/release/manualpages/PEP/PEPProblemType.html>

โœจ Attributes Summary โœจ

๐Ÿ’– Attributes Documentation ๐Ÿ’–

GENERAL: int <https://docs.python.org/3/library/functions.html#int> = GENERAL

Constant GENERAL of type int <https://docs.python.org/3/library/functions.html#int>

GYROSCOPIC: int <https://docs.python.org/3/library/functions.html#int> = GYROSCOPIC

Constant GYROSCOPIC of type int <https://docs.python.org/3/library/functions.html#int>

HERMITIAN: int <https://docs.python.org/3/library/functions.html#int> = HERMITIAN

Constant HERMITIAN of type int <https://docs.python.org/3/library/functions.html#int>

HYPERBOLIC: int <https://docs.python.org/3/library/functions.html#int> = HYPERBOLIC

Constant HYPERBOLIC of type int <https://docs.python.org/3/library/functions.html#int>

__init__()

classmethod __new__(*args, **kwargs)

class slepc4py.SLEPc.PEP.Refine ๐ŸŽ€

class slepc4py.SLEPc.PEP.Refine

Bases: object <https://docs.python.org/3/library/functions.html#object>

PEP refinement strategy โ€” how hard do we want to polish those eigenpairs, bestie? ๐Ÿซถ

  • NONE โ€” no refinement, we're keeping it raw
  • SIMPLE โ€” refine eigenpairs one by one, main character energy, one at a time
  • MULTIPLE โ€” refine all eigenpairs simultaneously (invariant pair), the way that everything gets handled at once is iconic

See also: PEPRefine <https://slepc.upv.es/release/manualpages/PEP/PEPRefine.html>

โœจ Attributes Summary โœจ

๐Ÿ’– Attributes Documentation ๐Ÿ’–

MULTIPLE: int <https://docs.python.org/3/library/functions.html#int> = MULTIPLE

Constant MULTIPLE of type int <https://docs.python.org/3/library/functions.html#int>

NONE: int <https://docs.python.org/3/library/functions.html#int> = NONE

Constant NONE of type int <https://docs.python.org/3/library/functions.html#int>

SIMPLE: int <https://docs.python.org/3/library/functions.html#int> = SIMPLE

Constant SIMPLE of type int <https://docs.python.org/3/library/functions.html#int>

__init__()

classmethod __new__(*args, **kwargs)

class slepc4py.SLEPc.PEP.RefineScheme ๐Ÿฆ‹

class slepc4py.SLEPc.PEP.RefineScheme

Bases: object <https://docs.python.org/3/library/functions.html#object>

PEP scheme for solving linear systems during iterative refinement โ€” so like, which linear-solve glow-up are we doing ๐Ÿ”ฅ

  • SCHUR โ€” Schur complement
  • MBE โ€” mixed block elimination
  • EXPLICIT โ€” build the explicit matrix, no shortcuts, we're doing the whole thing

See also: PEPRefineScheme <https://slepc.upv.es/release/manualpages/PEP/PEPRefineScheme.html>

โœจ Attributes Summary โœจ

๐Ÿ’– Attributes Documentation ๐Ÿ’–

EXPLICIT: int <https://docs.python.org/3/library/functions.html#int> = EXPLICIT

Constant EXPLICIT of type int <https://docs.python.org/3/library/functions.html#int>

MBE: int <https://docs.python.org/3/library/functions.html#int> = MBE

Constant MBE of type int <https://docs.python.org/3/library/functions.html#int>

SCHUR: int <https://docs.python.org/3/library/functions.html#int> = SCHUR

Constant SCHUR of type int <https://docs.python.org/3/library/functions.html#int>

__init__()

classmethod __new__(*args, **kwargs)

class slepc4py.SLEPc.PEP.Scale ๐ŸŒธ

class slepc4py.SLEPc.PEP.Scale

Bases: object <https://docs.python.org/3/library/functions.html#object>

PEP scaling strategy โ€” because sometimes your matrices just need a little proportional moment, ngl ๐ŸŽ€

  • NONE โ€” no scaling
  • SCALAR โ€” parameter scaling
  • DIAGONAL โ€” diagonal scaling
  • BOTH โ€” both parameter and diagonal scaling, why not both, we contain multitudes ๐Ÿ’…

See also: PEPScale <https://slepc.upv.es/release/manualpages/PEP/PEPScale.html>

โœจ Attributes Summary โœจ

okay bestie before we even get into the docs, here's the lineup of what this one's packing โ€” every single one of these is a constant of type int (https://docs.python.org/3/library/functions.html#int), so jot that down:

  • BOTH โ€” Constant BOTH of type int.
  • DIAGONAL โ€” Constant DIAGONAL of type int.
  • NONE โ€” Constant NONE of type int.
  • SCALAR โ€” Constant SCALAR of type int.

๐ŸŽ€ Attributes Documentation ๐ŸŽ€

the receipts, one by one, no skipping fr:

and then the construction girlies show up:

  • __init__()
  • classmethod __new__(*args, **kwargs)

๐Ÿฆ‹ slepc4py.SLEPc.PEP.Stop ๐Ÿฆ‹

class slepc4py.SLEPc.PEP.Stop

Bases: object (https://docs.python.org/3/library/functions.html#object)

okay so this is the PEP stopping test, aka the "when do we stop, bestie" vibe check โœจ

  • BASIC: Default stopping test. the one you get if you don't ask for anything special, iconic.
  • USER: User-defined stopping test. you're the main character, you decide.

See also:

โญ Attributes Summary โญ

๐Ÿ’œ Attributes Documentation ๐Ÿ’œ

and the usual init moment:

  • __init__()
  • classmethod __new__(*args, **kwargs)

๐ŸŒˆ slepc4py.SLEPc.PEP.Type ๐ŸŒˆ

class slepc4py.SLEPc.PEP.Type

Bases: object (https://docs.python.org/3/library/functions.html#object)

this one's the PEP type โ€” like, which flavour of solver energy are we bringing today, periodt:

  • TOAR: Two-level orthogonal Arnoldi.
  • STOAR: Symmetric TOAR.
  • QARNOLDI: Q-Arnoldi for quadratic problems.
  • LINEAR: Linearization via EPS.
  • JD: Polynomial Jacobi-Davidson.
  • CISS: Contour integral spectrum slice.

See also:

โœจ Attributes Summary โœจ

heads up, these ones are str objects, not ints โ€” plot twist:

๐Ÿ’– Attributes Documentation ๐Ÿ’–

and yeah, same deal:

  • __init__()
  • classmethod __new__(*args, **kwargs)

๐ŸŽ€ slepc4py.SLEPc.PEP.Which ๐ŸŽ€

class slepc4py.SLEPc.PEP.Which

Bases: object (https://docs.python.org/3/library/functions.html#object)

this is the PEP desired part of spectrum โ€” aka which eigenvalues we're actually gagging for, and bestie there are so many options:

  • LARGEST_MAGNITUDE: Largest magnitude (default). the default btw, so if you said nothing, this is what you got ๐Ÿ‘‘
  • SMALLEST_MAGNITUDE: Smallest magnitude.
  • LARGEST_REAL: Largest real parts.
  • SMALLEST_REAL: Smallest real parts.
  • LARGEST_IMAGINARY: Largest imaginary parts in magnitude.
  • SMALLEST_IMAGINARY: Smallest imaginary parts in magnitude.
  • TARGET_MAGNITUDE: Closest to target (in magnitude).
  • TARGET_REAL: Real part closest to target.
  • TARGET_IMAGINARY: Imaginary part closest to target.
  • ALL: All eigenvalues in an interval.
  • USER: User-defined criterion.

See also:

๐ŸŽ€ Attributes Summary ๐ŸŽ€

okay bestie, here's the whole little squad of class attributes ๐Ÿ’… every single one of them is an int, and every single one of them points at the Python int docs at https://docs.python.org/3/library/functions.html#int โ€” no cap, they all link to the same spot ๐Ÿ™ˆ

โœจ Attributes Documentation โœจ

this is the same eleven besties but with their full glow-up signatures ๐Ÿ’– like, each one is annotated int and defaults to literally itself. iconic behaviour, honestly.

and then, the two little methods that close out the list ๐Ÿซถ

  • __init__()
  • classmethod __new__(*args, **kwargs)
  • appendOptionsPrefix([prefix]) โ€” tack more onto the prefix that gets used when hunting down all the PEP options in the database. prefix stacking, we love to see it ๐Ÿ’…
  • cancelMonitor() โ€” nukes every monitor chilling on a PEP object. clear the whole feed bestie, nobody's watching anymore ๐Ÿซถ
  • computeError(i[, etype]) โ€” does the math on the error hanging off the i-th computed eigenpair, so you actually know how off it is ๐Ÿ˜ญ
  • create([comm]) โ€” birth the PEP object โœจ it exists now, it's giving newborn era ๐Ÿ‘‘
  • destroy() โ€” and now we say goodbye ๐Ÿฅ€ destroy the PEP object, no more memory debt, periodt.
  • errorView([etype, viewer]) โ€” shows off the errors attached to the computed solution, right there in a viewer for your eyeballs error aesthetic ๐Ÿ‘€
  • getBV() โ€” hands you the basis vectors object that's linked up to the eigensolver ๐Ÿ”ฅ
  • getBasis() โ€” tells you which flavour of polynomial basis is being used which basis are we in today ๐Ÿฆ‹
  • getCISSExtraction() โ€” reveals the extraction technique the CISS solver is running with โญ
  • getCISSKSPs() โ€” gives you the whole array of linear solver objects hooked up to the CISS solver a whole squad of KSPs ๐Ÿ’œ
  • getCISSRefinement() โ€” pulls the values of the various refinement parameters inside the CISS solver ๐ŸŽ€
  • getCISSSizes() โ€” same deal but for the various size parameters in the CISS solver size check ๐Ÿ“
  • getCISSThreshold() โ€” and for the various threshold parameters in the CISS solver ๐ŸŒธ
  • getConverged() โ€” how many eigenpairs actually converged? the number, and it's the number ๐Ÿ”ฅ
  • getConvergedReason() โ€” explains why the solve() iteration tapped out, like the receipts for why it stopped ๐Ÿ˜ญ
  • getConvergenceTest() โ€” coughs up the method that computes the error estimate used in the convergence test the method behind the method ๐Ÿ’…
  • getDS() โ€” grabs the direct solver attached to the eigensolver ๐Ÿ‘‘
  • getDimensions() โ€” how many eigenvalues you're computing and the dimension of the subspace, two facts in one call ๐Ÿ’–
  • getEigenpair(i[, Vr, Vi]) โ€” delivers the i-th solution of the eigenproblem exactly as solve() computed it the main character of eigenpairs โœจ
  • getEigenvalueComparison() โ€” hands over the eigenvalue comparison function ๐Ÿฆ‹
  • getErrorEstimate(i) โ€” the error estimate linked to the i-th computed eigenpair, so you can vibe check it ๐ŸŒˆ
  • getExtract() โ€” tells you the extraction technique the PEP object is using โญ
  • getInterval() โ€” spits out the computational interval used for spectrum slicing slice it up ๐Ÿ”ช
  • getIterationNumber() โ€” the current iteration number, right now, live ๐ŸŽ€
  • getJDFix() โ€” gives you the threshold for changing the target in the correction equation target acquired, kinda ๐Ÿ’œ
  • getJDMinimalityIndex() โ€” the maximum allowed value of the minimality index, all capped and respectful ๐Ÿ™ˆ
  • getJDProjection() โ€” hands you back the type of projection that's gonna be used in the Jacobi-Davidson solver ๐ŸŽ€
  • getJDRestart() โ€” returns the restart parameter the Jacobi-Davidson method is running with ๐Ÿ”
  • getJDReusePreconditioner() โ€” gives you the flag for reusing the preconditioner โ™ป๏ธ
  • getLinearEPS() โ€” fetches the eigensolver object that's tied to the polynomial eigenvalue solver ๐Ÿ’…
  • getLinearExplicitMatrix() โ€” tells you whether the matrices for the linearization are built explicitly or not โœจ
  • getLinearLinearization() โ€” gets the coeffs. (yes bestie, that's the whole description, we keep it exactly) ๐Ÿ“Ž
  • getMonitor() โ€” pulls up the list of monitor functions ๐Ÿ‘€
  • getOperators() โ€” returns the matrices associated with the eigenvalue problem ๐Ÿงฉ
  • getOptionsPrefix() โ€” gives you the prefix that's used for searching for all PEP options in the database ๐Ÿ”
  • getProblemType() โ€” reads the problem type straight off the PEP object ๐Ÿท๏ธ
  • getQArnoldiLocking() โ€” returns the locking flag the Q-Arnoldi method is using ๐Ÿ”’
  • getQArnoldiRestart() โ€” the restart parameter used in the Q-Arnoldi method ๐Ÿ”„
  • getRG() โ€” grabs the region object associated to the eigensolver ๐ŸŒ
  • getRefine() โ€” tells you the refinement strategy the PEP object is using โœจ
  • getRefineKSP() โ€” fetches the KSP object that the eigensolver uses during the refinement phase ๐ŸŒŠ
  • getST() โ€” returns the spectral transformation object associated to the eigensolver ๐ŸŒˆ
  • getSTOARCheckEigenvalueType() โ€” gives you the flag for the eigenvalue type check in spectrum slicing ๐Ÿ“
  • getSTOARDetectZeros() โ€” returns the flag that enforces zero detection in spectrum slicing ๐Ÿ•ต๏ธ
  • getSTOARDimensions() โ€” gets the dimensions used for each subsolve step ๐Ÿ“
  • getSTOARInertias() โ€” hands back the values of the shifts and their corresponding inertias โš–๏ธ
  • getSTOARLinearization() โ€” returns the coefficients that define the linearization of a quadratic eigenproblem ๐Ÿงฎ
  • getSTOARLocking() โ€” the locking flag used in the STOAR method ๐Ÿ”
  • getScale([Dl, Dr]) โ€” gets the strategy used for scaling the polynomial eigenproblem, with optional Dl and Dr scalings tucked in there ๐Ÿ“
  • getStoppingTest() โ€” fetches the stopping test function ๐Ÿ›‘
  • getTOARLocking() โ€” the locking flag used in the TOAR method ๐Ÿ”’
  • getTOARRestart() โ€” the restart parameter used in the TOAR method ๐Ÿ”
  • getTarget() โ€” grab the current value of the target ๐ŸŽฏ that's what the solver is aiming for, bestie.
  • getTolerances() โ€” spits back the tolerance and the maximum iteration count, both at once. two-for-one, we love that ๐Ÿ’…
  • getTrackAll() โ€” returns the flag that says whether all residual norms gotta be computed or not ๐Ÿ‘€
  • getType() โ€” tells you the PEP type of this object. like, what kind of polynomial eigenvalue problem are we even dealing with here bestie.
  • getWhichEigenpairs() โ€” reveals which portion of the spectrum is the one being sought ๐ŸŒˆ
  • reset() โ€” wipes the PEP object back to a clean slate. fresh start energy โœจ
  • setBV(bv) โ€” hooks up a basis vectors object</b> to the eigensolver ๐ŸŽ€
  • setBasis(basis) โ€” sets which type of polynomial basis gets used.
  • setCISSExtraction(extraction) โ€” picks the extraction technique the CISS solver is gonna run with.
  • setCISSRefinement([inner, blsize]) โ€” tunes the various refinement parameters over in the CISS solver. optional args, no pressure ๐Ÿซถ
  • setCISSRefinement([inner, blsize])... okay no, we're not doing that one twice ๐Ÿ’€ โ€” moving on:
  • setCISSSizes([ip, bs, ms, npart, bsmax, ...]) โ€” sets up the various size parameters for the CISS solver. yes there's a ... in there, it's giving "there are more, iykyk" ๐Ÿ˜ญ
  • setCISSThreshold([delta, spur]) โ€” dials in the various threshold parameters in the CISS solver.
  • setConvergenceTest(conv) โ€” decides how the error estimate feeding the convergence test actually gets computed ๐Ÿ”ฅ
  • setDS(ds) โ€” attaches a direct solver object</b> to the eigensolver ๐Ÿงš
  • setDimensions([nev, ncv, mpd]) โ€” sets how many eigenvalues to compute plus the dimension of the subspace. all optional, all iconic.
  • setEigenvalueComparison(comparison[, args, ...]) โ€” installs an eigenvalue comparison function, and sure, you can pass extra args and more ... along with it ๐Ÿ‘‘
  • setExtract(extract) โ€” picks the extraction strategy that's gonna be used.
  • setFromOptions() โ€” reads PEP options straight out of the options database. set it and forget it, periodt ๐Ÿ’…
  • setInitialSpace(space) โ€” sets the initial space the eigensolver kicks off its iterating from ๐ŸŒฑ
  • setInterval(inta, intb) โ€” sets the computational interval used for spectrum slicing.
  • setJDFix(fix) โ€” sets the threshold for switching up the target inside the correction equation ๐Ÿ”„
  • setJDMinimalityIndex(flag) โ€” sets the maximum allowed value for the minimality index.
  • setJDProjection(proj) โ€” sets what type of projection the Jacobi-Davidson solver is gonna use.
  • setJDRestart(keep) โ€” sets the restart parameter</c> for the Jacobi-Davidson method. keep, babe, keep ๐Ÿซถ
  • setJDReusePreconditioner(flag) โ€” flips a flag saying whether the preconditioner gets reused or not. recycling queen โ™ป๏ธ
  • setLinearEPS(eps) โ€” attaches an eigensolver object</b> to the polynomial eigenvalue solver. last one of the batch and it ate ๐Ÿ’–
  • setLinearExplicitMatrix(flag) โ€” flip flag and you're telling PEP to actually build out the matrices for the linearization instead of being sneaky about it. bestie is getting the full picture, no shortcuts ๐Ÿ’…
  • setLinearLinearization([alpha, beta]) โ€” hand over alpha and beta, the coefficients that define the linearization of a quadratic eigenproblem. that's it, that's the vibe โœจ
  • setMonitor(monitor[, args, kargs]) โ€” yeet a monitor function onto the end of the monitors list. you can pass args and kargs too, so your monitor gets all the tea it needs ๐Ÿซ–
  • setOperators(operators) โ€” drop in the matrices that go with the eigenvalue problem. the whole operators bundle, pls and thank you ๐ŸŽ€
  • setOptionsPrefix([prefix]) โ€” set the prefix PEP uses when it goes digging through the options database for all its settings. iykyk ๐Ÿ”
  • setProblemType(problem_type) โ€” tell it what kind of polynomial eigenvalue problem you're dealing with via problem_type. no guessing games ๐Ÿ’–
  • setQArnoldiLocking(lock) โ€” toggle lock to switch between the locking and non-locking flavors of the Q-Arnoldi method. pick your fighter โš”๏ธ
  • setQArnoldiRestart(keep) โ€” set the restart parameter keep for the Q-Arnoldi method. how much are we keeping around? your call ๐ŸŒธ
  • setRG(rg) โ€” attach a region object rg to the eigensolver. it's giving targeted energy ๐ŸŽฏ
  • setRefine(ref[, npart, tol, its, scheme]) โ€” pick the refinement strategy for the PEP object: ref plus the optional npart, tol, its and scheme. dial in that precision โœจ
  • setST(st) โ€” hook a spectral transformation object st up to the eigensolver. transformation era ๐Ÿ”ฅ
  • setSTOARCheckEigenvalueType(flag) โ€” set flag so it checks whether all the eigenvalues share the same definite type. consistency check, iconic ๐Ÿ‘‘
  • setSTOARDetectZeros(detect) โ€” set detect to force zero-detection during the factorizations. we are not letting zeros slip by unnoticed ๐Ÿ’€
  • setSTOARDimensions([nev, ncv, mpd]) โ€” set nev, ncv and mpd, the dimensions used for each subsolve step. size matters, fr fr ๐Ÿ“
  • setSTOARLinearization([alpha, beta]) โ€” pass alpha and beta, the coefficients defining the linearization of a quadratic eigenproblem. same energy, different method ๐Ÿ’œ
  • setSTOARLocking(lock) โ€” lock toggles between the locking and non-locking variants of the STOAR method. choose wisely โœจ
  • setScale(scale[, alpha, Dl, Dr, its, lbda]) โ€” set the scaling strategy scale, with optional alpha, Dl, Dr, its and lbda riding along. get that scaling just right ๐ŸŒˆ
  • setStoppingTest(stopping[, args, kargs]) โ€” give it a stopping function that decides when the eigensolver's outer iteration should call it quits. args and kargs welcome too ๐Ÿ›‘
  • setTOARLocking(lock) โ€” lock flips between locking and non-locking variants of the TOAR method. toggle toggle ๐Ÿฆ‹
  • setTOARRestart(keep) โ€” set the restart parameter keep for the TOAR method. keeping it cozy ๐Ÿงš
  • setTarget(target) โ€” set the value of the target. that's the whole thing, no notes ๐ŸŽฏ
  • setTolerances([tol, max_it]) โ€” set the tolerance tol and the maximum iteration count max_it. how patient are we feeling today? โญ
  • setTrackAll(trackall) โ€” set trackall to compute the residual of every approximate eigenpair. all of them. no skipping ๐Ÿ™ˆ
  • setType(pep_type) โ€” pick the exact solver pep_type that the PEP object is gonna use. main character selection ๐Ÿ’…
  • setUp() โ€” build out all the internal data structures. the pre-game ritual before anything actually happens ๐Ÿซถ
  • setWhichEigenpairs(which) โ€” picks which chunk of the spectrum we're actually hunting for ๐Ÿ‘‘
  • solve() โ€” solves the polynomial eigenproblem. the main event, the whole reason we're here โœจ
  • valuesView([viewer]) โ€” shows off the computed eigenvalues in a viewer ๐Ÿ’…
  • vectorsView([viewer]) โ€” pushes the computed eigenvectors out to a viewer ๐Ÿฆ‹
  • view([viewer]) โ€” prints the PEP data structure, like a little x-ray of the whole thing ๐Ÿซถ

Attributes Summary ๐Ÿ’–

  • bv โ€” the basis vectors (BV) object associated.
  • ds โ€” the direct solver (DS) object associated.
  • extract โ€” the type of extraction technique to be employed.
  • max_it โ€” the maximum iteration count.
  • problem_type โ€” the type of the eigenvalue problem.
  • rg โ€” the region (RG) object associated.
  • st โ€” the spectral transformation (ST) object associated.
  • target โ€” the value of the target.
  • tol โ€” the tolerance.
  • track_all โ€” compute the residual norm of all approximate eigenpairs.
  • which โ€” the portion of the spectrum to be sought.

Methods Documentation ๐Ÿ“–

appendOptionsPrefix(prefix=None)

okay so this one appends to the prefix that's used when searching for all PEP options in the database ๐ŸŽ€

Logically collective.

Parameters

  • prefix (str | None) โ€” the prefix string to prepend to all PEP option requests.

Return type

None

See also:

setOptionsPrefix, getOptionsPrefix, PEPAppendOptionsPrefix

Source code at slepc4py/SLEPc/PEP.pyx:467

cancelMonitor()

clears out all the monitors on a PEP object. all of them. gone. bye ๐Ÿ’…

Logically collective.

See also:

PEPMonitorCancel

Source code at slepc4py/SLEPc/PEP.pyx:1589

Return type

None

computeError(i, etype=None)

computes the error tied to the i-th computed eigenpair ๐Ÿฆ‹

Collective.

basically: compute the error (based on the residual norm) associated with the i-th computed eigenpair.

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 \|P(\lambda)x\|_2 where \lambda is the eigenvalue and x is the eigenvector.

Return type

float

Notes

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

See also:

getErrorEstimate, PEPComputeError

Source code at slepc4py/SLEPc/PEP.pyx:1785

create(comm=None)

creates the PEP object โœจ

Collective.

Parameters

  • comm (petsc4py.PETSc.Comm | None) โ€” MPI communicator. If you don't pass one, it defaults to all processes.

Return type

Self

See also:

PEPCreate

Source code at slepc4py/SLEPc/PEP.pyx:350

destroy()

destroys the PEP object. rip, but make it respectful ๐Ÿ™ˆ

Collective.

See also:

PEPDestroy

Source code at slepc4py/SLEPc/PEP.pyx:324

Return type

Self

errorView(etype=None, viewer=None)

displays the errors associated with the computed solution ๐Ÿ‘‘

Collective.

it displays the errors and the eigenvalues, together, in one place.

Parameters

  • etype (ErrorType | None) โ€” the error type to compute.
  • viewer (petsc4py.PETSc.Viewer | None) โ€” visualization context; if you don't provide one, the standard output is used.

Return type

None

Notes

...this function checks the error of all eigenpairs and prints the eigenvalues if all of them are below the requested tolerance. If the viewer has format ASCII_INFO_DETAIL then a table with eigenvalues and corresponding errors gets printed. โœจ

See also: solve, valuesView, vectorsView, PEPErrorView <https://slepc.upv.es/release/manualpages/PEP/PEPErrorView.html>

:sources: Source code at slepc4py/SLEPc/PEP.pyx:1823 (slepc4py/SLEPc/PEP.pyx#L1823)

getBV() ๐Ÿฆ‹

Get the basis vectors object that's attached to the eigensolver, bestie.

Not collective.

Returns โ€” The basis vectors context.

Return type โ€” BV <#slepc4py.SLEPc.BV>

See also: setBV, PEPGetBV <https://slepc.upv.es/release/manualpages/PEP/PEPGetBV.html>

:sources: Source code at slepc4py/SLEPc/PEP.pyx:1250 (slepc4py/SLEPc/PEP.pyx#L1250)

getBasis() ๐ŸŒธ

Get the type of polynomial basis being used.

Not collective.

Returns โ€” The basis that was previously set.

Return type โ€” Basis <#slepc4py.SLEPc.PEP.Basis>

See also: setBasis, PEPGetBasis <https://slepc.upv.es/release/manualpages/PEP/PEPGetBasis.html>

:sources: Source code at slepc4py/SLEPc/PEP.pyx:505 (slepc4py/SLEPc/PEP.pyx#L505)

getCISSExtraction() ๐ŸŽ€

Get the extraction technique in use over in the CISS solver.

Not collective.

Returns โ€” The extraction technique.

Return type โ€” CISSExtraction <#slepc4py.SLEPc.PEP.CISSExtraction>

See also: setCISSExtraction, PEPCISSGetExtraction <https://slepc.upv.es/release/manualpages/PEP/PEPCISSGetExtraction.html>

:sources: Source code at slepc4py/SLEPc/PEP.pyx:2729 (slepc4py/SLEPc/PEP.pyx#L2729)

getCISSKSPs() ๐Ÿ’…

Get the array of linear solver objects that belong to the CISS solver.

Collective.

Returns โ€” The linear solver objects.

Return type โ€” list <https://docs.python.org/3/library/stdtypes.html#list> of petsc4py.PETSc.KSP <https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.KSP.html#petsc4py.PETSc.KSP>

Notes ๐Ÿ“

The number of petsc4py.PETSc.KSP <https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.KSP.html#petsc4py.PETSc.KSP> solvers is equal to the number of integration points divided by the number of partitions. This value gets halved in the case of real matrices with a region centered at the real axis.

See also: setCISSSizes, PEPCISSGetKSPs <https://slepc.upv.es/release/manualpages/PEP/PEPCISSGetKSPs.html>

:sources: Source code at slepc4py/SLEPc/PEP.pyx:2926 (slepc4py/SLEPc/PEP.pyx#L2926)

getCISSRefinement() โœจ

Get the values of all the various refinement parameters in the CISS solver.

Not collective.

Returns

Return type โ€” tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]

See also: setCISSRefinement, PEPCISSGetRefinement <https://slepc.upv.es/release/manualpages/PEP/PEPCISSGetRefinement.html>

:sources: Source code at slepc4py/SLEPc/PEP.pyx:2904 (slepc4py/SLEPc/PEP.pyx#L2904)

getCISSSizes() ๐Ÿ“

Get the values of the various size parameters inside the CISS solver.

Not collective.

Returns

Return type โ€” tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>, bool <https://docs.python.org/3/library/functions.html#bool>]

See also: setCISSSizes, PEPCISSGetSizes <https://slepc.upv.es/release/manualpages/PEP/PEPCISSGetSizes.html>

:sources: Source code at slepc4py/SLEPc/PEP.pyx:2802 (slepc4py/SLEPc/PEP.pyx#L2802)

getCISSThreshold() ๐Ÿงš

Get the values of the various threshold parameters in the CISS solver.

Not collective.

Returns

๐Ÿ˜ญ bestie the original docstring really does just leave that paren hanging wide open, no cap. I'm keeping it exactly as it is, not my job to close it.

Return type โ€” tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[float <https://docs.python.org/3/library/functions.html#float>, float <https://docs.python.org/3/library/functions.html#float>]

See also: setCISSThreshold, PEPCISSGetThreshold <https://slepc.upv.es/release/manualpages/PEP/PEPCISSGetThreshold.html>

:sources: Source code at slepc4py/SLEPc/PEP.pyx:2859 (slepc4py/SLEPc/PEP.pyx#L2859)

getConverged() ๐Ÿ‘‘

Get the number of converged eigenpairs. The moment of truth fr fr.

Not collective.

Returns โ€” nconv โ€“ Number of converged eigenpairs.

Return type โ€” int <https://docs.python.org/3/library/functions.html#int>

Notes ๐Ÿ“

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

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

See also: setDimensions, solve, getEigenpair, PEPGetConverged <https://slepc.upv.es/release/manualpages/PEP/PEPGetConverged.html>

:sources: Source code at slepc4py/SLEPc/PEP.pyx:1689 (slepc4py/SLEPc/PEP.pyx#L1689)

getConvergedReason() ๐Ÿ’€

Get the reason why the solve() iteration got stopped.

Not collective.

Returns โ€” Negative value indicates diverged, positive value converged.

Return type โ€” ConvergedReason <#slepc4py.SLEPc.PEP.ConvergedReason>

See also: setTolerances, solve, PEPGetConvergedReason <https://slepc.upv.es/release/manualpages/PEP/PEPGetConvergedReason.html>

:sources: Source code at slepc4py/SLEPc/PEP.pyx:1670 (slepc4py/SLEPc/PEP.pyx#L1670)

getConvergenceTest() ๐ŸŒˆ

Get the method used to compute the error estimate that feeds into the convergence test.

Not collective.

Returns โ€” The method used to compute the error estimate used in the convergence test.

Return type โ€” Conv <#slepc4py.SLEPc.PEP.Conv>

See also: setConvergenceTest, PEPGetConvergenceTest <https://slepc.upv.es/release/manualpages/PEP/PEPGetConvergenceTest.html>

:sources: Source code at slepc4py/SLEPc/PEP.pyx:820 (slepc4py/SLEPc/PEP.pyx#L820)

getDS() ๐Ÿฆ‹

Get the direct solver that's associated with the eigensolver.

Not collective.

Returns โ€” The direct solver context.

Return type โ€” DS <#slepc4py.SLEPc.DS>

See also: setDS, PEPGetDS <https://slepc.upv.es/release/manualpages/PEP/PEPGetDS.html>

:sources: Source code at slepc4py/SLEPc/PEP.pyx:1324 (slepc4py/SLEPc/PEP.pyx#L1324)

getDimensions() ๐Ÿ”ฅ

Get the number of eigenvalues to compute and the dimension of the subspace.

Not collective. ๐Ÿ™…โ€โ™€๏ธ

What you get back (Returns):

  • nev (int) โ€” how many eigenvalues you're asking it to compute.
  • ncv (int) โ€” the biggest the subspace is allowed to get, dimension-wise.
  • mpd (int) โ€” the biggest dimension the projected problem is allowed to have.

Return type: tuple[int, int, int]

See also: setDimensions, PEPGetDimensions <https://slepc.upv.es/release/manualpages/PEP/PEPGetDimensions.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1038 <slepc4py/SLEPc/PEP.pyx#L1038>``

getEigenpair(i, Vr=None, Vi=None)

Get the i-th solution of the eigenproblem as computed by solve(). ๐ŸŽ€

Collective, bestie โ€” everybody has to show up for this one.

The solution is a two-for-one deal: you get the eigenvalue and the eigenvector.

Parameters

  • i (int) โ€” Index of the solution to be obtained.
  • Vr (Vec | None) โ€” Placeholder for the returned eigenvector (real part).
  • Vi (Vec | None) โ€” Placeholder for the returned eigenvector (imaginary part).

Returns: The computed eigenvalue.

Return type: complex

Notes

That index i has to be somewhere between 0 and nconv-1 (peep getConverged() for that). Eigenpairs get indexed based on whatever ordering criterion you set up with setWhichEigenpairs().

And the eigenvector comes normalized to unit norm, no cap. ๐Ÿ’…

See also: solve, getConverged, setWhichEigenpairs, PEPGetEigenpair <https://slepc.upv.es/release/manualpages/PEP/PEPGetEigenpair.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1715 <slepc4py/SLEPc/PEP.pyx#L1715>``

getEigenvalueComparison()

Get the eigenvalue comparison function. ๐Ÿฆ‹

Not collective.

Returns: The eigenvalue comparison function.

Return type: PEPEigenvalueComparison

See also: setEigenvalueComparison

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1530 <slepc4py/SLEPc/PEP.pyx#L1530>``

getErrorEstimate(i)

Get the error estimate that's attached to the i-th computed eigenpair. ๐Ÿ‘‘

Not collective.

Parameters

  • i (int) โ€” Index of the solution to be considered.

Returns: Error estimate.

Return type: float

Notes

Heads up though: this is the error estimate the eigensolver uses internally. The actual error bound? You get that from computeError(). Don't mix them up fr fr.

See also: computeError, PEPGetErrorEstimate <https://slepc.upv.es/release/manualpages/PEP/PEPGetErrorEstimate.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1756 <slepc4py/SLEPc/PEP.pyx#L1756>``

getExtract()

Get the extraction technique the PEP object is using. โœจ

Not collective.

Returns: The extraction strategy.

Return type: Extract

See also: setExtract, PEPGetExtract <https://slepc.upv.es/release/manualpages/PEP/PEPGetExtract.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:979 <slepc4py/SLEPc/PEP.pyx#L979>``

getInterval()

Get the computational interval for spectrum slicing. ๐ŸŒธ

Not collective.

Returns

  • inta (float) โ€” The left end of the interval.
  • intb (float) โ€” The right end of the interval.

Return type: tuple[float, float]

Notes

If you never set the interval yourself, do not panic โ€” it just hands you zeros. ๐ŸŒˆ

See also: setInterval, PEPGetInterval <https://slepc.upv.es/release/manualpages/PEP/PEPGetInterval.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:764 <slepc4py/SLEPc/PEP.pyx#L764>``

getIterationNumber()

Get the current iteration number. ๐Ÿ”ฅ

Not collective.

If the solve() call already finished, then this gives you the number of iterations the solution method actually carried out. Slay.

Returns: Iteration number.

Return type: int

See also: getConvergedReason, setTolerances, PEPGetIterationNumber <https://slepc.upv.es/release/manualpages/PEP/PEPGetIterationNumber.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1648 <slepc4py/SLEPc/PEP.pyx#L1648>``

getJDFix()

Get the threshold for changing the target in the correction equation. ๐ŸŽฏ

Not collective.

Returns: The threshold for changing the target.

Return type: float

See also: setJDFix, PEPJDGetFix <https://slepc.upv.es/release/manualpages/PEP/PEPJDGetFix.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:2566 <slepc4py/SLEPc/PEP.pyx#L2566>``

getJDMinimalityIndex()

Get the maximum allowed value of the minimality index. ๐Ÿ’œ

Not collective.

Returns: The maximum minimality index.

Return type: int

See also: setJDMinimalityIndex, PEPJDGetMinimalityIndex <https://slepc.upv.es/release/manualpages/PEP/PEPJDGetMinimalityIndex.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:2653 <slepc4py/SLEPc/PEP.pyx#L2653>``

getJDProjection()

Get the type of projection used in the Jacobi-Davidson solver. ๐Ÿงš

Not collective.

Returns: The type of projection.

Return type: JDProjection

See also: setJDProjection, PEPJDGetProjection <https://slepc.upv.es/release/manualpages/PEP/PEPJDGetProjection.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:2690 <slepc4py/SLEPc/PEP.pyx#L2690>``

getJDRestart()

Get the restart parameter used in the Jacobi-Davidson method. ๐Ÿซถ

Not collective.

Returns: The number of vectors to be kept at restart.

Return type: float

See also: setJDRestart, PEPJDGetRestart <https://slepc.upv.es/release/manualpages/PEP/PEPJDGetRestart.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:2523 <slepc4py/SLEPc/PEP.pyx#L2523>``

getJDReusePreconditioner()

Get the flag for reusing the preconditioner. โ™ป๏ธ

Not collective.

Returns: The reuse flag.

Return type: bool

See also: setJDReusePreconditioner, PEPJDGetReusePreconditioner <https://slepc.upv.es/release/manualpages/PEP/PEPJDGetReusePreconditioner.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:2610 <slepc4py/SLEPc/PEP.pyx#L2610>``

getLinearEPS()

Get the eigensolver object that's associated to the polynomial eigenvalue solver. ๐ŸŒŸ

Collective โ€” everyone's in on this one.

Returns: The linear eigensolver.

Return type: EPS

See also: setLinearEPS, PEPLinearGetEPS โ€” https://slepc.upv.es/release/manualpages/PEP/PEPLinearGetEPS.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1912 <slepc4py/SLEPc/PEP.pyx#L1912>``

getLinearExplicitMatrix()

Okay bestie, this one tells you whether the matrices for the linearization are being built explicitly. Like, actually materialized. Out in the open. No mysterious in-place magic. ๐Ÿ’…

Not collective. So every process is just vibing on its own copy of the answer.

Returns

  • A Boolean flag indicating if the matrices are built explicitly.

Return type: bool โ€” https://docs.python.org/3/library/functions.html#bool

See also: getLinearExplicitMatrix, PEPLinearSetExplicitMatrix โ€” https://slepc.upv.es/release/manualpages/PEP/PEPLinearSetExplicitMatrix.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1993 <slepc4py/SLEPc/PEP.pyx#L1993>``

getLinearLinearization()

This grabs the coefficients that define the linearization of a quadratic eigenproblem โœจ. Two little numbers, doing a whole lot of work.

Not collective.

Returns

  • alpha (float) โ€“ First parameter of the linearization.
  • beta (float) โ€“ Second parameter of the linearization.

Return type: tuple[float, float] โ€” https://docs.python.org/3/library/stdtypes.html#tuple

See also: setLinearLinearization, PEPLinearGetLinearization โ€” https://slepc.upv.es/release/manualpages/PEP/PEPLinearGetLinearization.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1953 <slepc4py/SLEPc/PEP.pyx#L1953>``

getMonitor()

Gets the list of monitor functions. The little gremlins that watch your solver and report back. ๐Ÿ‘€

Not collective.

Returns

  • The list of monitor functions.

Return type: PEPMonitorFunction โ€” <#slepc4py.typing.PEPMonitorFunction>

See also: setMonitor

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1572 <slepc4py/SLEPc/PEP.pyx#L1572>``

getOperators()

Get the matrices associated with the eigenvalue problem. The whole cast of characters. ๐ŸŽ€

Collective. โ€” so everybody on the communicator is in on this one, no solo acts.

Returns

  • The matrices associated with the eigensystem.

Return type: list of petsc4py.PETSc.Mat โ€” https://docs.python.org/3/library/stdtypes.html#list ยท https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat

See also: setOperators, PEPGetOperators โ€” https://slepc.upv.es/release/manualpages/PEP/PEPGetOperators.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1361 <slepc4py/SLEPc/PEP.pyx#L1361>``

getOptionsPrefix()

Returns the prefix that this PEP object uses when it goes digging through the options database for all its PEP-flavored options. ๐Ÿ”

Not collective.

Returns

  • The prefix string set for this PEP object.

Return type: str โ€” https://docs.python.org/3/library/stdtypes.html#str

See also: setOptionsPrefix, appendOptionsPrefix, PEPGetOptionsPrefix โ€” https://slepc.upv.es/release/manualpages/PEP/PEPGetOptionsPrefix.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:417 <slepc4py/SLEPc/PEP.pyx#L417>``

getProblemType()

Pulls the problem type straight out of the PEP object. Whatever you set before? This is it, boo. ๐Ÿ’–

Not collective.

Returns

  • The problem type that was previously set.

Return type: ProblemType โ€” <#slepc4py.SLEPc.PEP.ProblemType>

See also: setProblemType, PEPGetProblemType โ€” https://slepc.upv.es/release/manualpages/PEP/PEPGetProblemType.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:553 <slepc4py/SLEPc/PEP.pyx#L553>``

getQArnoldiLocking()

Gets the locking flag that the Q-Arnoldi method is using. ๐Ÿ”

Not collective.

Returns

  • The locking flag.

Return type: bool โ€” https://docs.python.org/3/library/functions.html#bool

See also: setQArnoldiLocking, PEPQArnoldiGetLocking โ€” https://slepc.upv.es/release/manualpages/PEP/PEPQArnoldiGetLocking.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:2084 <slepc4py/SLEPc/PEP.pyx#L2084>``

getQArnoldiRestart()

Gets the restart parameter for the Q-Arnoldi method โ€” how many vectors get to stay when everything resets. ๐Ÿฆ‹

Not collective.

Returns

  • The number of vectors to be kept at restart.

Return type: float โ€” https://docs.python.org/3/library/functions.html#float

See also: setQArnoldiRestart, PEPQArnoldiGetRestart โ€” https://slepc.upv.es/release/manualpages/PEP/PEPQArnoldiGetRestart.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:2040 <slepc4py/SLEPc/PEP.pyx#L2040>``

getRG()

Hands you the region object that's attached to the eigensolver. ๐Ÿ—บ๏ธ

Not collective.

Returns

  • The region context.

Return type: RG โ€” <#slepc4py.SLEPc.RG>

See also: setRG, PEPGetRG โ€” https://slepc.upv.es/release/manualpages/PEP/PEPGetRG.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1287 <slepc4py/SLEPc/PEP.pyx#L1287>``

getRefine()

Gets the refinement strategy the PEP object is running with. This one returns a whole โœจfive-part tupleโœจ so hold on tight.

Not collective.

Returns

  • ref (Refine) โ€“ The refinement type.
  • npart (int) โ€“ The number of partitions of the communicator.
  • tol (float) โ€“ The convergence tolerance.
  • its (int) โ€“ The maximum number of refinement iterations.
  • scheme (RefineScheme) โ€“ Scheme for solving linear systems.

Return type: tuple[Refine, int, float, int, RefineScheme] โ€” https://docs.python.org/3/library/stdtypes.html#tuple

See also: setRefine, PEPGetRefine โ€” https://slepc.upv.es/release/manualpages/PEP/PEPGetRefine.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:859 <slepc4py/SLEPc/PEP.pyx#L859>``

getRefineKSP()

Gets the KSP object the eigensolver uses while it's in the refinement phase. ๐Ÿงš

Collective.

Returns

  • The linear solver object.

Return type: petsc4py.PETSc.KSP โ€” https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.KSP.html#petsc4py.PETSc.KSP

See also: setRefine, PEPRefineGetKSP โ€” https://slepc.upv.es/release/manualpages/PEP/PEPRefineGetKSP.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:934 <slepc4py/SLEPc/PEP.pyx#L934>``

getST()

Gets the spectral transformation object hanging off the eigensolver. The โœจglow-upโœจ layer, if you will.

Not collective.

Returns

  • The spectral transformation.

Return type: ST โ€” <#slepc4py.SLEPc.ST>

See also: setST, PEPGetST โ€” https://slepc.upv.es/release/manualpages/PEP/PEPGetST.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1114 <slepc4py/SLEPc/PEP.pyx#L1114>``

getSTOARCheckEigenvalueType()

Gets the flag that controls the eigenvalue type check in spectrum slicing. ๐Ÿ”Ž

Not collective.

Returns

  • Whether the eigenvalue type is checked or not.

Return type: bool โ€” https://docs.python.org/3/library/functions.html#bool

See also: setSTOARCheckEigenvalueType, PEPSTOARGetCheckEigenvalueType โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSTOARGetCheckEigenvalueType.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:2476 <slepc4py/SLEPc/PEP.pyx#L2476>``

getSTOARDetectZeros()

Gets the flag that enforces zero detection in spectrum slicing. Because sometimes a zero is just out there, unbothered, hiding. ๐Ÿ•ต๏ธโ€โ™€๏ธ

Not collective.

Returns

  • The zero detection flag.

Return type: bool โ€” https://docs.python.org/3/library/functions.html#bool

  • See also: setSTOARDetectZeros, PEPSTOARGetDetectZeros (the manualpage lives over at slepc.upv.es, under manualpages/PEP/PEPSTOARGetDetectZeros.html)
  • :sources: Source code at slepc4py/SLEPc/PEP.pyx:2316 (yep, that's slepc4py/SLEPc/PEP.pyx#L2316 bestie, go peek ๐Ÿ’…)

getSTOARDimensions() ๐Ÿซถ

okay so this one hands you back the dimensions used for each subsolve step. Not collective, so no gossiping across ranks.

Returns โ€” a little bundle of three:

  • nev (int) โ€” Number of eigenvalues 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] โ€” three ints, chef's kiss ๐ŸŽ€

  • See also: setSTOARDimensions, PEPSTOARGetDimensions
๐Ÿ“œ Source code at slepc4py/SLEPc/PEP.pyx:2375 โ€” as in, slepc4py/SLEPc/PEP.pyx#L2375

getSTOARInertias() โœจ

Get the values of the shifts and their corresponding inertias. That's the whole vibe, but let me say it again the long way: it gets the values of the shifts and their corresponding inertias in case you're doing spectrum slicing for a computational interval.

Not collective.

Returns

  • shifts (ArrayReal) โ€” The values of the shifts used internally in the solver.
  • inertias (ArrayInt) โ€” The values of the inertia in each shift.

Return type: tuple[ArrayReal, ArrayInt]

Notes ๐ŸŒธ

  • This call makes sense only for spectrum slicing runs, that is, when an interval has been given with setInterval() and SINVERT is set.
  • If you call it after solve(), all shifts used internally by the solver come back to you โ€” including both endpoints and any intermediate ones. If you call it before solve() and after setUp(), then only the information of the endpoints of subintervals is available. Timing is literally everything, no cap.
  • See also: setInterval, PEPSTOARGetInertias
๐Ÿ“œ Source code at slepc4py/SLEPc/PEP.pyx:2400 โ€” a.k.a. slepc4py/SLEPc/PEP.pyx#L2400

getSTOARLinearization() ๐Ÿฆ‹

Get the coefficients that define the linearization of a quadratic eigenproblem. Quadratic girlies, this one's for you.

Not collective.

Returns

  • alpha (float) โ€” First parameter of the linearization.
  • beta (float) โ€” Second parameter of the linearization.

Return type: tuple[float, float]

  • See also: setSTOARLinearization, PEPSTOARGetLinearization
๐Ÿ“œ Source code at slepc4py/SLEPc/PEP.pyx:2217 โ€” that is slepc4py/SLEPc/PEP.pyx#L2217 ๐Ÿ’–

getSTOARLocking() ๐Ÿ”ฅ

Get the locking flag used in the STOAR method. Short and sweet, the way I like it.

Not collective.

Returns: The locking flag.

Return type: bool

  • See also: setSTOARLocking, PEPSTOARGetLocking
๐Ÿ“œ Source code at slepc4py/SLEPc/PEP.pyx:2264 โ€” slepc4py/SLEPc/PEP.pyx#L2264

getScale(Dl=None, Dr=None) ๐ŸŒˆ

Get the strategy used for scaling the polynomial eigenproblem. So iconic.

Not collective.

Parameters

  • Dl (petsc4py.PETSc.Vec | None) โ€” Placeholder for the returned left diagonal matrix.
  • Dr (petsc4py.PETSc.Vec | None) โ€” Placeholder for the returned right diagonal matrix.

Returns

  • scale (Scale) โ€” The scaling strategy.
  • alpha (float) โ€” The scaling factor.
  • its (int) โ€” The number of iterations of diagonal scaling.
  • lbda (float) โ€” Approximation of the wanted eigenvalues (modulus).

Return type: tuple[Scale, float, int, float] โ€” four things, one tuple, we love to see it ๐Ÿ‘‘

  • See also: setScale, PEPGetScale
๐Ÿ“œ Source code at slepc4py/SLEPc/PEP.pyx:1151 โ€” which is slepc4py/SLEPc/PEP.pyx#L1151

getStoppingTest() ๐ŸŽ€

Get the stopping test function. That's it, that's the whole job.

Not collective.

Returns: The stopping test function.

Return type: PEPStoppingFunction

  • See also: setStoppingTest
๐Ÿ“œ Source code at slepc4py/SLEPc/PEP.pyx:1483 โ€” you know the drill: slepc4py/SLEPc/PEP.pyx#L1483

getTOARLocking() ๐Ÿ’œ

Get the locking flag used in the TOAR method. (STOAR said hi, TOAR said hi back.)

Not collective.

Returns: The locking flag.

Return type: bool

  • See also: setTOARLocking, PEPTOARGetLocking
๐Ÿ“œ Source code at slepc4py/SLEPc/PEP.pyx:2175 โ€” slepc4py/SLEPc/PEP.pyx#L2175 โœจ

getTOARRestart() ๐Ÿ“

Get the restart parameter used in the TOAR method. Restart era fr fr.

Not collective.

Returns: The number of vectors to be kept at restart.

Return type: float

  • See also: setTOARRestart, PEPTOARGetRestart
๐Ÿ“œ Source code at slepc4py/SLEPc/PEP.pyx:2131 โ€” that's slepc4py/SLEPc/PEP.pyx#L2131 bestie

getTarget() ๐ŸŒธ

Get the value of the target. The main character of your solve, honestly.

Not collective.

Returns: The value of the target.

Return type: Scalar

Notes ๐Ÿ˜ญ

If the target was not set by the user, then zero is returned. So if you're staring at a 0 wondering who set that โ€” nobody did, it's just the default, okay?

  • See also: setTarget, PEPGetTarget
๐Ÿ“œ Source code at slepc4py/SLEPc/PEP.pyx:658 โ€” slepc4py/SLEPc/PEP.pyx#L658

getTolerances() ๐Ÿฆ‹

Get the tolerance and maximum iteration count. And when I say "the tolerance and maximum iteration count" I mean specifically the those used by the default PEP convergence tests, okay? Not some other random tolerances. These ones.

Not collective.

Returns

  • tol (float) โ€” The convergence tolerance.
  • max_it (int) โ€” The maximum number of iterations.

Return type โ€” tuple[float, int] ๐Ÿ’–

See also: setTolerances, PEPGetTolerances โ€” https://slepc.upv.es/release/manualpages/PEP/PEPGetTolerances.html

Source: slepc4py/SLEPc/PEP.pyx:708

getTrackAll()

okay so this one grabs the flag that says whether every single residual norm has to be computed or not.

Not collective โ€” so don't be out here expecting all ranks to be on the same page, bestie, they each answer for themselves ๐Ÿ™ˆ

Returns โ€” whether the solver computes all residuals or not.

Return type โ€” bool

See also: setTrackAll, PEPGetTrackAll โ€” https://slepc.upv.es/release/manualpages/PEP/PEPGetTrackAll.html

Source: slepc4py/SLEPc/PEP.pyx:998

getType()

bestie this is the vibe check for your solver ๐Ÿฆ‹ it tells you the PEP type of this object.

Not collective.

Returns โ€” the solver currently being used.

Return type โ€” str

See also: setType, PEPGetType โ€” https://slepc.upv.es/release/manualpages/PEP/PEPGetType.html

Source: slepc4py/SLEPc/PEP.pyx:398

getWhichEigenpairs()

which part of the spectrum are we hunting for?? ๐Ÿ‘€ this tells you.

Not collective.

Returns โ€” the portion of the spectrum to be sought by the solver.

Return type โ€” Which <#slepc4py.SLEPc.PEP.Which>

See also: setWhichEigenpairs, PEPGetWhichEigenpairs โ€” https://slepc.upv.es/release/manualpages/PEP/PEPGetWhichEigenpairs.html

Source: slepc4py/SLEPc/PEP.pyx:602

reset()

wipe it down, hard reset, factory settings โœจ this resets the PEP object.

Collective โ€” yes, collective, everybody participates, no lurking.

See also: PEPReset โ€” https://slepc.upv.es/release/manualpages/PEP/PEPReset.html

Source: slepc4py/SLEPc/PEP.pyx:338

Return type โ€” None

setBV(bv)

pairs a basis vectors object with your eigensolver ๐Ÿ’…

Collective.

Parameters

  • bv (BV <#slepc4py.SLEPc.BV>) โ€” the basis vectors context.

Return type โ€” None

See also: getBV, PEPSetBV โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSetBV.html

Source: slepc4py/SLEPc/PEP.pyx:1270

setBasis(basis)

sets which type of polynomial basis we're using, and ngl this one lowkey matters a lot.

Logically collective.

It sets the type of polynomial basis used to describe the polynomial eigenvalue problem, periodt.

Parameters

  • basis (Basis <#slepc4py.SLEPc.PEP.Basis>) โ€” the basis to be set.

Return type โ€” None

Notes

by default, the coefficient matrices you pass via setOperators() are expressed in the monomial basis, i.e.

P(\lambda)=A_0+\lambda A_1+\lambda^2 A_2+\dots+\lambda^d A_d

other polynomial bases may have better numerical behavior, but then you (yes, you, bestie) have to pass the coefficient matrices accordingly ๐Ÿ˜ญ go off though.

See also: getBasis, setOperators, PEPSetBasis โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSetBasis.html

Source: slepc4py/SLEPc/PEP.pyx:524

setCISSExtraction(extraction)

picks the extraction technique used in the CISS solver. CISS arc, we love her ๐Ÿงš

Logically collective.

Parameters

  • extraction (CISSExtraction <#slepc4py.SLEPc.PEP.CISSExtraction>) โ€” the extraction technique.

Return type โ€” None

See also: getCISSExtraction, PEPCISSSetExtraction โ€” https://slepc.upv.es/release/manualpages/PEP/PEPCISSSetExtraction.html

Source: slepc4py/SLEPc/PEP.pyx:2711

setCISSRefinement(inner=None, blsize=None)

tuning the refinement knobs in the CISS solver, and she has multiple knobs.

Logically collective.

Parameters

  • inner (int | None) โ€” number of iterative refinement iterations (inner loop).
  • blsize (int | None) โ€” number of iterative refinement iterations (blocksize loop).

Return type โ€” None

See also: getCISSRefinement, PEPCISSSetRefinement โ€” https://slepc.upv.es/release/manualpages/PEP/PEPCISSSetRefinement.html

Source: slepc4py/SLEPc/PEP.pyx:2881

setCISSSizes(ip=None, bs=None, ms=None, npart=None, bsmax=None, realmats=False)

the size-parameters moment ๐Ÿ’– all the dimensions, all the partitions, everything.

Logically collective.

Parameters

  • ip (int | None) โ€” number of integration points.
  • bs (int | None) โ€” block size.
  • ms (int | None) โ€” moment size.
  • npart (int | None) โ€” number of partitions when splitting the communicator.
  • bsmax (int | None) โ€” maximum block size.
  • realmats (bool) โ€” True if A and B are real.

Return type โ€” None

Notes

the default number of partitions is 1. this means the internal petsc4py.PETSc.KSP object is shared among all processes of the PEP communicator. otherwise, the communicator is split into npart communicators, so that npart petsc4py.PETSc.KSP solves proceed simultaneously ๐Ÿ”ฅ

See also: getCISSSizes, setCISSThreshold, setCISSRefinement, PEPCISSSetSizes โ€” https://slepc.upv.es/release/manualpages/PEP/PEPCISSSetSizes.html

Source: slepc4py/SLEPc/PEP.pyx:2748

setCISSThreshold(delta=None, spur=None)

threshold girlies rise up ๐ŸŽ€ these are the cutoff values in the CISS solver.

Logically collective.

Parameters

  • delta (float | None) โ€” threshold for numerical rank.
  • spur (float | None) โ€” spurious threshold (to discard spurious eigenpairs).

Return type โ€” None

See also: getCISSThreshold, PEPCISSSetThreshold โ€” https://slepc.upv.es/release/manualpages/PEP/PEPCISSSetThreshold.html

Source: slepc4py/SLEPc/PEP.pyx:2836

setConvergenceTest(conv)

decides how the error estimate used in the convergence test gets computed. it's giving quality control ๐Ÿ‘‘

Logically collective.

  • conv (Conv) โ€” the method used to compute the error estimate used in the convergence test. That's the vibe-check of "are we there yet bestie" ๐Ÿ’…

Return type None

See also: getConvergenceTest, PEPSetConvergenceTest โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSetConvergenceTest.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:840 <slepc4py/SLEPc/PEP.pyx#L840>``

setDS(ds)

Okay so you can bolt a direct solver object onto your eigensolver ๐Ÿซถ

Collective. (everyone in the group chat has to call it, no lurkers ๐Ÿ‘€)

Parameters

  • ds (DS) โ€” the direct solver context.

Return type None

See also: getDS, PEPSetDS โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSetDS.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1344 <slepc4py/SLEPc/PEP.pyx#L1344>``

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

Set how many eigenvalues you wanna compute AND how big the subspace gets. Two dials, one function, iconic โœจ

Logically collective.

Parameters

  • nev (int | None) โ€” number of eigenvalues 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 and it'll pick a reasonably good value for you, which lowkey depends on the solution method. Bestie, let it cook ๐Ÿ“

The parameters ncv and mpd are intimately related (they're giving soulmates fr fr), so you're advised to set at most one of them. Normal usage goes like this:

  • When nev is small, you set ncv (a reasonable default is 2 * nev).
  • When nev is large, you set mpd.

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

See also: getDimensions, PEPSetDimensions โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSetDimensions.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1063 <slepc4py/SLEPc/PEP.pyx#L1063>``

setEigenvalueComparison(comparison, args=None, kargs=None)

Set an eigenvalue comparison function. Custom sorting, your rules ๐Ÿ’…

Logically collective.

Notes

This eigenvalue comparison function is used when setWhichEigenpairs() is set to PEP.Which.USER. So like, only then, iykyk.

See also: getEigenvalueComparison, PEPSetEigenvalueComparison โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSetEigenvalueComparison.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1500 <slepc4py/SLEPc/PEP.pyx#L1500>``

Parameters

  • comparison (PEPEigenvalueComparison | None)
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type None

setExtract(extract)

Set the extraction strategy to be used ๐Ÿงš

Logically collective.

Parameters

  • extract (Extract) โ€” the extraction strategy.

Return type None

Notes

This one's relevant for solvers based on linearization. Once the solver has converged, the polynomial eigenvectors can be extracted from the eigenvectors of the linearized problem in different ways. Multiple routes to the same slay, bestie ๐ŸŒˆ

See also: getExtract, PEPSetExtract โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSetExtract.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:954 <slepc4py/SLEPc/PEP.pyx#L954>``

setFromOptions()

Set PEP options straight from the options database โœจ

Collective.

Notes

To see all options, run your program with the -help option. (Yes, go read the help. It's free. It's giving self-care ๐Ÿ’–)

This routine must be called before setUp() if the user is to be allowed to set the solver type. Order matters, no cap.

See also: setOptionsPrefix, PEPSetFromOptions โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSetFromOptions.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:486 <slepc4py/SLEPc/PEP.pyx#L486>``

Return type None

setInitialSpace(space)

Set the initial space from which the eigensolver starts to iterate. Give it a head start, a little warm-up, a little get ready with me ๐ŸŽ€

Collective.

Parameters

  • space (Vec | list[Vec]) โ€” the initial space.

Return type None

Notes

Some solvers start to iterate on a single vector (initial vector). In that case, only the first vector is taken into account and the other vectors are ignored. Sorry to the rest of them ๐Ÿ˜ญ

These vectors do not persist from one solve() call to the other, so the initial space should be set every single time. No leftover fits, we start fresh ๐Ÿ‘‘

The vectors do not need to be mutually orthonormal, since they are explicitly orthonormalized internally. So don't stress about it, bestie.

Common usage of this function is when the user can provide a rough approximation of the wanted eigenspace. Then, convergence may be faster. Basically: a good guess = speedrun energy ๐Ÿ”ฅ

See also: setUp, PEPSetInitialSpace โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSetInitialSpace.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1420 <slepc4py/SLEPc/PEP.pyx#L1420>``

setInterval(inta, intb)

Set the computational interval for spectrum slicing โœ‚๏ธ๐ŸŒˆ

Logically collective.

Parameters

  • inta (float) โ€” the left end of the interval.
  • intb (float) โ€” the right end of the interval.

Return type None

Notes

Spectrum slicing is a technique employed for computing all eigenvalues of symmetric quadratic eigenproblems in a given interval. This function provides the interval to be considered. It must be used in combination with PEP.Which.ALL, see setWhichEigenpairs(). Note that in polynomial eigenproblems spectrum slicing is implemented in STOAR only. Just STOAR. Nobody else. Periodt ๐Ÿ’…

See also: getInterval, PEPSetInterval โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSetInterval.html

:sources:Source code at slepc4py/SLEPc/PEP.pyx:790 <slepc4py/SLEPc/PEP.pyx#L790>``

setJDFix(fix)

Set the threshold for changing the target in the correction equation ๐Ÿฆ‹

Logically collective.

Parameters

  • fix (float) โ€” threshold for changing the target.

Return type None

Notes

okay so the target in the correction equation is locked in at the first iterations. when the norm of the residual vector dips below the fix value, the target gets switched over to the eigenvalue that matches it. no cap.

See also: getJDFix, PEPJDSetFix <https://slepc.upv.es/release/manualpages/PEP/PEPJDSetFix.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:2542 <slepc4py/SLEPc/PEP.pyx#L2542>``

setJDMinimalityIndex(flag)

picks the biggest minimality index you're allowed to use ๐Ÿ’…

Logically collective.

Parameters

Return type

None <https://docs.python.org/3/library/constants.html#None>

Notes

okay so the default is literally the degree of the polynomial. but if you already know your wanted eigenvectors are linearly independent, you can go smaller.

See also: getJDMinimalityIndex, PEPJDSetMinimalityIndex <https://slepc.upv.es/release/manualpages/PEP/PEPJDSetMinimalityIndex.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:2629 <slepc4py/SLEPc/PEP.pyx#L2629>``

setJDProjection(proj)

picks which type of projection the Jacobi-Davidson solver is gonna use ๐ŸŒ€

Logically collective.

Parameters

  • proj (JDProjection <#slepc4py.SLEPc.PEP.JDProjection>) โ€” the type of projection.

Return type

None <https://docs.python.org/3/library/constants.html#None>

See also: getJDProjection, PEPJDSetProjection <https://slepc.upv.es/release/manualpages/PEP/PEPJDSetProjection.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:2672 <slepc4py/SLEPc/PEP.pyx#L2672>``

setJDRestart(keep)

sets the restart parameter for the Jacobi-Davidson method ๐Ÿ”

Logically collective.

sets the restart parameter for the Jacobi-Davidson method โ€” specifically, the proportion of basis vectors that have to stick around after the restart.

Parameters

Return type

None <https://docs.python.org/3/library/constants.html#None>

Notes

the allowed values live in the range [0.1,0.9]. default is 0.5. bestie, stay in the range, i'm begging ๐Ÿซถ

See also: getJDRestart, PEPJDSetRestart <https://slepc.upv.es/release/manualpages/PEP/PEPJDSetRestart.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:2497 <slepc4py/SLEPc/PEP.pyx#L2497>``

setJDReusePreconditioner(flag)

sets a flag saying whether the preconditioner has to get reused or not ๐Ÿ‘‘

Logically collective.

Parameters

Return type

None <https://docs.python.org/3/library/constants.html#None>

Notes

default is False. if you set it to True, the preconditioner is built only at the beginning, using the target value. otherwise it may get rebuilt (all depends on the fix parameter) at each iteration, starting from the Ritz value. so like. pick your fighter.

See also: setJDFix, getJDReusePreconditioner, PEPJDSetReusePreconditioner <https://slepc.upv.es/release/manualpages/PEP/PEPJDSetReusePreconditioner.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:2585 <slepc4py/SLEPc/PEP.pyx#L2585>``

setLinearEPS(eps)

attaches an eigensolver object to the polynomial eigenvalue solver โœจ

Collective.

Parameters

  • eps (EPS <#slepc4py.SLEPc.EPS>) โ€” the linear eigensolver.

Return type

None <https://docs.python.org/3/library/constants.html#None>

See also: getLinearEPS, PEPLinearSetEPS <https://slepc.upv.es/release/manualpages/PEP/PEPLinearSetEPS.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1895 <slepc4py/SLEPc/PEP.pyx#L1895>``

setLinearExplicitMatrix(flag)

sets the flag for building the matrices for the linearization explicitly ๐Ÿงš

Logically collective.

Parameters

Return type

None <https://docs.python.org/3/library/constants.html#None>

See also: getLinearExplicitMatrix, PEPLinearSetExplicitMatrix <https://slepc.upv.es/release/manualpages/PEP/PEPLinearSetExplicitMatrix.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1975 <slepc4py/SLEPc/PEP.pyx#L1975>``

setLinearLinearization(alpha=1.0, beta=0.0)

sets the coefficients that define the linearization of a quadratic eigenproblem ๐ŸŒธ

Logically collective.

Parameters

Return type

None <https://docs.python.org/3/library/constants.html#None>

See also: getLinearLinearization, PEPLinearSetLinearization <https://slepc.upv.es/release/manualpages/PEP/PEPLinearSetLinearization.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1932 <slepc4py/SLEPc/PEP.pyx#L1932>``

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

appends a monitor function to the list of monitors ๐ŸŽ€

Logically collective.

See also: getMonitor, cancelMonitor, PEPMonitorSet <https://slepc.upv.es/release/manualpages/PEP/PEPMonitorSet.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1547 <slepc4py/SLEPc/PEP.pyx#L1547>``

Parameters

Return type

None <https://docs.python.org/3/library/constants.html#None>

setOperators(operators)

sets the matrices that go with the eigenvalue problem ๐Ÿฆ‹

Collective.

Parameters

Return type

None <https://docs.python.org/3/library/constants.html#None>

Notes

so the polynomial eigenproblem is defined as P(\lambda)x=0, where \lambda is the eigenvalue, x is the eigenvector, and P is defined as P(\lambda) = A_0 + \lambda A_1 + \dots + \lambda^d A_d, with d = nmat-1 (the degree of P). for non-monomial bases, this expression is different. iykyk ๐Ÿ’œ

See also: getOperators, PEPSetOperators <https://slepc.upv.es/release/manualpages/PEP/PEPSetOperators.html>

:sources:Source code at slepc4py/SLEPc/PEP.pyx:1387 <slepc4py/SLEPc/PEP.pyx#L1387>``

setOptionsPrefix(prefix=None)

sets the prefix that's used for searching for all PEP options in the database ๐Ÿ”

Logically collective.

Parameters

Return type

None <https://docs.python.org/3/library/constants.html#None>

Notes

do NOT put a hyphen (-) at the beginning of the prefix name. the first character of all runtime options is AUTOMATICALLY the hyphen. like it does that for you bestie, don't fight it ๐Ÿ’…

so if you wanna tell apart the runtime options for two different PEP contexts, you could call:

P1.setOptionsPrefix("pep1_")
P2.setOptionsPrefix("pep2_")

See also: appendOptionsPrefix, getOptionsPrefix, PEPGetOptionsPrefix (https://slepc.upv.es/release/manualpages/PEP/PEPGetOptionsPrefix.html)

Source code at slepc4py/SLEPc/PEP.pyx:436

setProblemType(problem_type) ๐ŸŒˆ

Bestie. This one sets the type of the polynomial eigenvalue problem. That's the whole vibe.

Logically collective. (so like, everybody's gotta be on the same page ๐Ÿซถ)

Parameters:

  • problem_type (ProblemType) โ€” the problem type you wanna set.

Return type: None

Notes โ€” okay so listen:

  • This tells SLEPc to exploit certain structure in the polynomial eigenproblem. By default, no particular structure is assumed โ€” it's giving "we don't know you like that".
  • If your matrices are Hermitian (symmetric in the real case) or Hermitian/skew-Hermitian, then the solver can use that fact to do less operations or be way more stable. Hyperbolic problems are a particular case of Hermitian problems, and some solvers just treat them as Hermitian, simple as that.

See also: setOperators, setType, getProblemType, PEPSetProblemType (https://slepc.upv.es/release/manualpages/PEP/PEPSetProblemType.html)

Source code at slepc4py/SLEPc/PEP.pyx:572

setQArnoldiLocking(lock) ๐Ÿ”’

Toggles between the locking and non-locking variants of the Q-Arnoldi method. Pick your fighter.

Logically collective.

Parameters:

  • lock (bool) โ€” True if the locking variant must be selected.

Return type: None

Notes:

  • The default is to lock converged eigenpairs when the method restarts. You can change that behavior so all directions stay in the working subspace even if they already converged to working accuracy โ€” that's the non-locking variant, the "we keep everyone, nobody gets left behind" option. ๐Ÿ’–

See also: getQArnoldiLocking, PEPQArnoldiSetLocking (https://slepc.upv.es/release/manualpages/PEP/PEPQArnoldiSetLocking.html)

Source code at slepc4py/SLEPc/PEP.pyx:2059

setQArnoldiRestart(keep) ๐Ÿ”

Sets the restart parameter for the Q-Arnoldi method โ€” specifically, the proportion of basis vectors that must be kept after restart. The way this one decides who gets to stay in the group chat.

Logically collective.

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. Respect the range, bestie, no cap.

See also: getQArnoldiRestart, PEPQArnoldiSetRestart (https://slepc.upv.es/release/manualpages/PEP/PEPQArnoldiSetRestart.html)

Source code at slepc4py/SLEPc/PEP.pyx:2014

setRG(rg) ๐Ÿ—บ๏ธ

Attaches a region object to the eigensolver. It's giving "this is YOUR zone".

Collective.

Parameters:

  • rg (RG) โ€” the region context.

Return type: None

See also: getRG, PEPSetRG (https://slepc.upv.es/release/manualpages/PEP/PEPSetRG.html)

Source code at slepc4py/SLEPc/PEP.pyx:1307

setRefine(ref, npart=None, tol=None, its=None, scheme=None) โœจ

Sets the refinement strategy used by the PEP object, plus all the associated parameters that come with it. Glow-up time.

Logically collective.

Parameters:

  • ref (Refine) โ€” the refinement type.
  • npart (int | None) โ€” the number of partitions of the communicator.
  • tol (float | None) โ€” the convergence tolerance.
  • its (int | None) โ€” the maximum number of refinement iterations.
  • scheme (RefineScheme | None) โ€” scheme for solving linear systems.

Return type: None

See also: getRefine, PEPSetRefine (https://slepc.upv.es/release/manualpages/PEP/PEPSetRefine.html)

Source code at slepc4py/SLEPc/PEP.pyx:890

setST(st) ๐ŸŒธ

Attaches a spectral transformation object to the eigensolver. Yes queen, transform the spectrum.

Collective.

Parameters:

  • st (ST) โ€” the spectral transformation.

Return type: None

See also: getST, PEPSetST (https://slepc.upv.es/release/manualpages/PEP/PEPSetST.html)

Source code at slepc4py/SLEPc/PEP.pyx:1134

setSTOARCheckEigenvalueType(flag) ๐Ÿ”

Sets a flag to check that all the eigenvalues obtained throughout the spectrum slicing computation have the same definite type. It's a vibe check for your eigenvalues, fr fr.

Logically collective.

Parameters:

  • flag (bool) โ€” whether the eigenvalue type is checked or not.

Return type: None

Notes:

  • This option is relevant only for spectrum slicing computations, and it's actually ignored for slepc4py.SLEPc.PEP.ProblemType.HYPERBOLIC problems.
  • This flag is turned on by default, to guarantee the computed eigenvalues have the same type โ€” otherwise, lowkey, the computed solution might be wrong. ๐Ÿ˜ญ But because the check is computationally quite expensive, you're allowed to turn it off if you know for sure that all eigenvalues in the requested interval have the same type. Only if you're sure, bestie. Absolutely sure.

See also: getSTOARCheckEigenvalueType, PEPSTOARSetCheckEigenvalueType (https://slepc.upv.es/release/manualpages/PEP/PEPSTOARSetCheckEigenvalueType.html)

Source code at slepc4py/SLEPc/PEP.pyx:2444

setSTOARDetectZeros(detect) ๐Ÿ’€

Sets a flag to enforce detection of zeros during the factorizations throughout the spectrum slicing computation. Zero-hunting mode: activated.

Logically collective.

Parameters:

  • detect (bool) โ€” True if zeros must checked for.

Return type: None

Notes:

  • This call only makes sense for spectrum slicing runs โ€” that is, when an interval has been given with setInterval() and SINVERT is set.
  • A zero in the factorization means a shift coincides with an eigenvalue. Not me finding a whole eigenvalue hiding in the factorization ๐Ÿ™ˆ
  • This flag is turned off by default, and it may be necessary in some cases. Heads up though: this feature currently requires an external package for factorizations with support for zero detection, e.g. MUMPS.

See also: setInterval, getSTOARDetectZeros, PEPSTOARSetDetectZeros (https://slepc.upv.es/release/manualpages/PEP/PEPSTOARSetDetectZeros.html)

Source code at slepc4py/SLEPc/PEP.pyx:2283

setSTOARDimensions(nev=None, ncv=None, mpd=None) ๐Ÿ“

Sets the dimensions used for each subsolve step. Every little subsolve gets its own measurements.

Logically collective.

Parameters:

  • nev (int | None) โ€” how many eigenvalues you're asking it to compute, bestie.
  • ncv (int | None) โ€” the max dimension of the subspace the solver is allowed to play in.
  • mpd (int | None) โ€” the biggest dimension allowed for the projected problem. yes it's a vibe limit.

Return type

None

Notes

This one only makes sense for spectrum slicing runs โ€” aka when you've given it an interval with setInterval() and SINVERT is set. Otherwise it's giving "why am I here". ๐Ÿซ 

The parameters mean exactly the same thing as in setDimensions(), except the ones here apply to every single subsolve that the child PEP object does. every. one. ๐Ÿ’…

See also

Source: slepc4py/SLEPc/PEP.pyx:2335

setSTOARLinearization(alpha=1.0, beta=0.0)

Sets the coefficients that define the linearization of a quadratic eigenproblem. โœจ

Logically collective.

Parameters

  • alpha (float) โ€” first parameter of the linearization.
  • beta (float) โ€” second parameter of the linearization.

Return type

None

See also

Source: slepc4py/SLEPc/PEP.pyx:2196

setSTOARLocking(lock)

Toggles between the locking and non-locking variants of the STOAR method. lowkey a big deal ngl ๐ŸŽ€

Logically collective.

Parameters

  • lock (bool) โ€” True if the locking variant must be selected.

Return type

None

Notes

Default behavior is to lock converged eigenpairs when the method restarts. You can flip that so all directions stay in the working subspace even if they've already converged to working accuracy โ€” that's the non-locking variant, periodt. ๐Ÿ‘‘

See also

Source: slepc4py/SLEPc/PEP.pyx:2239

setScale(scale, alpha=None, Dl=None, Dr=None, its=None, lbda=None)

Sets the scaling strategy to be used. this is the glow-up phase fr fr ๐ŸŒˆ

Collective. (yes, capital-C Collective, not "logically" โ€” the whole squad shows up.)

Parameters

  • scale (Scale) โ€” the scaling strategy.
  • alpha (float | None) โ€” the scaling factor.
  • Dl (petsc4py.PETSc.Vec | None) โ€” the left diagonal matrix.
  • Dr (petsc4py.PETSc.Vec | None) โ€” the right diagonal matrix.
  • its (int | None) โ€” the number of iterations of diagonal scaling.
  • lbda (float | None) โ€” approximation of the wanted eigenvalues (modulus).

Return type

None

See also

Source: slepc4py/SLEPc/PEP.pyx:1204

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

Sets a function that decides when to stop the outer iteration of the eigensolver. it's giving "we're done here" energy ๐Ÿ’€

Logically collective.

See also

Source: slepc4py/SLEPc/PEP.pyx:1459

Parameters

  • stopping (PEPStoppingFunction | None)
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type

None

setTOARLocking(lock)

Toggles between the locking and non-locking variants of the TOAR method. same energy as STOAR, different acronym bestie ๐Ÿฆ‹

Logically collective.

Parameters

  • lock (bool) โ€” True if the locking variant must be selected.

Return type

None

Notes

The default is to lock converged eigenpairs 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

Source: slepc4py/SLEPc/PEP.pyx:2150

setTOARRestart(keep)

Sets the restart parameter for the TOAR method. ๐Ÿ”

Logically collective.

Sets the restart parameter for the TOAR method โ€” specifically, 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 live in the range [0.1,0.9]. The default is 0.5. Don't go rogue outside that range, bestie, it's not the move. ๐Ÿ™ˆ

See also

Source: slepc4py/SLEPc/PEP.pyx:2105

setTarget(target)

Sets the value of the target. ๐ŸŽฏ

Logically collective.

Parameters

  • target (Scalar) โ€” the value of the target.

Return type

None

Notes

The target is a scalar value used to determine the portion of the spectrum you actually care about. It works together with setWhichEigenpairs() โ€” dynamic duo behavior, no cap. ๐Ÿ‘‘

When PETSc is built with real scalars, it is not possible to specify a complex target. so don't even try, it'll just be sad. ๐Ÿ˜ญ

See also

Source: slepc4py/SLEPc/PEP.pyx:681 (that one was the source line for the method above, bestie, just closing it out ๐Ÿ’…)

โœจ setTolerances(tol=None, max_it=None) โœจ

Sets the tolerance AND the maximum iteration count, together, in one call. Girlboss multitasking fr fr ๐ŸŽ€

Logically collective โ€” everybody in the group chat has to call it, no lurking allowed.

What it's actually doing: it sets the tolerance and maximum iteration count that the default PEP convergence tests use. ๐Ÿ’–

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 and it'll assign a reasonably good value โ€” and that value is dependent on the solution method, so it's giving ~adaptive~ ๐Ÿงš

See also: getTolerances, PEPSetTolerances โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSetTolerances.html

Source: slepc4py/SLEPc/PEP.pyx:733

โœจ setTrackAll(trackall) โœจ

Set flag to compute the residual of all the approximate eigenpairs. Every single one. No skipping. ๐Ÿ”ฅ

Logically collective โ€” all together now ๐Ÿซถ

This is literally: it sets whether the solver must compute the residual of all approximate eigenpairs, or not. That's the whole vibe check.

Parameters

  • trackall (bool) โ€” whether to compute all residuals or not.

Return type: None

See also: getTrackAll, PEPSetTrackAll โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSetTrackAll.html

Source: slepc4py/SLEPc/PEP.pyx:1017

โœจ setType(pep_type) โœจ

Picks the particular solver that's gonna get used inside the PE ๐Ÿ’… โ€” like choosing your main character for the run.

Logically collective. Yes, again. It's giving group project.

Parameters

  • pep_type (Type | str) โ€” the solver to be used.

Return type: None

Notes

The default is TOAR. โœจ But honestly? Normally it's best to use setFromOptions() and then set the PEP type from the options database instead of calling this routine. Why? Because the options database gives the user maximum flexibility in evaluating the different available methods. Flexibility is the aesthetic. ๐Ÿ‘‘

See also: getType, PEPSetType โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSetType.html

Source: slepc4py/SLEPc/PEP.pyx:371

โœจ setUp() โœจ

Sets up all the internal data structures, babe. All of them. ๐Ÿฆ‹

Collective.

Notes

It sets up all the internal data structures necessary for the execution of the eigensolver. And yes, that includes the setup of the internal ST object. ๐Ÿ’–

Here's the tea though โ€” in most cases you don't need to call this explicitly, because solve() calls it for you. The one time it's genuinely useful is when you want to measure the set-up time separately from the solve time. Timing girlies, this one's for you โฑ๏ธ๐ŸŒธ

See also: solve, PEPSetUp โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSetUp.html

Source: slepc4py/SLEPc/PEP.pyx:1604

Return type: None

โœจ setWhichEigenpairs(which) โœจ

Sets which portion of the spectrum is to be sought โ€” like, which part of the party are we going to ๐ŸŽ‰

Logically collective.

Parameters

  • which (Which) โ€” the portion of the spectrum to be sought by the solver.

Return type: None

Notes โ€” okay sit down for this one, it's a lot ๐Ÿ“

  • Not all eigensolvers implemented in PEP account for all the possible values. So like, don't assume ๐Ÿคท
  • Also, some values only make sense for certain types of problems.
  • If SLEPc is compiled for real numbers, PEP.Which.LARGEST_IMAGINARY and PEP.Which.SMALLEST_IMAGINARY use the absolute value of the imaginary part for eigenvalue selection. Yes, really. ๐Ÿ’€
  • The target is a scalar value provided with setTarget().
  • The criterion PEP.Which.TARGET_IMAGINARY is available only in case PETSc and SLEPc have been built with complex scalars. No complex scalars, no target imaginary, sorry bestie ๐Ÿ˜ญ
  • PEP.Which.ALL is intended for use in combination with an interval (see setInterval()), when all eigenvalues within the interval are requested โ€” or, in the context of the PEP.Type.CISS solver, for computing all eigenvalues in a region.

See also: getWhichEigenpairs, setTarget, setInterval, PEPSetWhichEigenpairs โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSetWhichEigenpairs.html

Source: slepc4py/SLEPc/PEP.pyx:621

โœจ solve() โœจ

Solve the polynomial eigenproblem. The moment we've all been waiting for. ๐Ÿ’…โœจ

Collective.

Notes

The problem matrices are specified with setOperators().

Now, important: solve() will return without generating an error, regardless of whether all requested solutions were computed or not. ๐Ÿ˜ญ It's not gonna tell you. It's not gonna warn you. So:

  • Call getConverged() to get the actual number of computed solutions.
  • Call getConvergedReason() to figure out whether the solver converged or failed, and why.

fr fr, check your reasons, don't just trust the vibe ๐Ÿ”

See also: setUp, setOperators, getConverged, getConvergedReason, PEPSolve โ€” https://slepc.upv.es/release/manualpages/PEP/PEPSolve.html

Source: slepc4py/SLEPc/PEP.pyx:1626

Return type: None

โœจ valuesView(viewer=None) โœจ

Display the computed eigenvalues in a viewer. Show off those values, they earned it ๐Ÿ‘‘

Collective.

Parameters

  • viewer (Viewer | None) โ€” visualization context; if not provided, the standard output is used. ๐ŸŒˆ

Return type: None

See also: solve, vectorsView, errorView, PEPValuesView โ€” https://slepc.upv.es/release/manualpages/PEP/PEPValuesView.html

Source: slepc4py/SLEPc/PEP.pyx:1855

โœจ vectorsView(viewer=None) โœจ

Outputs the computed eigenvectors to a viewer. Same energy as valuesView but for the vectors, as the name lowkey suggests ๐Ÿฆ‹

Collective.

Parameters

  • viewer (Viewer | None) โ€” visualization context; if not provided, the standard output is used. ๐ŸŒˆ

Return type: None

See also: solve, valuesView, errorView, PEPVectorsView โ€” https://slepc.upv.es/release/manualpages/PEP/PEPVectorsView.html

Source: slepc4py/SLEPc/PEP.pyx:1874

โœจ view(viewer=None) โœจ

Prints the whole PEP data structure. Just dumps the entire thing right there, no filter, no shame ๐Ÿ’€

Collective.

Parameters

  • viewer (Viewer | None) โ€” visualization context; if not provided, the standard output is used. ๐ŸŒˆ

Return type: None

See also: PEPView โ€” https://slepc.upv.es/release/manualpages/PEP/PEPView.html

Source: slepc4py/SLEPc/PEP.pyx:305

๐ŸŒˆ Attributes Documentation ๐ŸŒˆ

Okay now the attributes, aka the little objects hanging off your PEP that you can just reach in and grab ๐ŸŽ€

โญ bv

The basis vectors (BV) object associated. ๐Ÿ’–

Source: slepc4py/SLEPc/PEP.pyx:3011

โญ ds

The direct solver (DS) object associated. โœจ

Source: slepc4py/SLEPc/PEP.pyx:3025

โญ extract

The type of extraction technique to be employed. ๐Ÿงš

Source: slepc4py/SLEPc/PEP.pyx:2976

โญ max_it

The maximum iteration count.

โ€ฆand wrapping up that last one, quick vibe check: its source lives at slepc4py/SLEPc/PEP.pyx:2990 ๐ŸŽ€

  • problem_type โ€” the type of eigenvalue problem you're working with, bestie. yes this matters!! ๐Ÿ”ฅ

source: slepc4py/SLEPc/PEP.pyx:2955

  • rg โ€” the region (RG) object that's linked up with this thing. ๐Ÿ‘‘

source: slepc4py/SLEPc/PEP.pyx:3018

  • st โ€” the spectral transformation (ST) object it's coupled with. the way these two hold handsโ€ฆ iconic. โœจ

source: slepc4py/SLEPc/PEP.pyx:3004

  • target โ€” literally just the value of the target. that's it, that's the whole thing. ๐Ÿ’…

source: slepc4py/SLEPc/PEP.pyx:2969

  • tol โ€” the tolerance. how picky we're being, fr fr. ๐Ÿ™ˆ

source: slepc4py/SLEPc/PEP.pyx:2983

  • track_all โ€” compute the residual norm of all approximate eigenpairs. like, every single one. no skipping. ๐Ÿ’€

source: slepc4py/SLEPc/PEP.pyx:2997

  • which โ€” which slice of the spectrum we're hunting for. ๐Ÿฆ‹

source: slepc4py/SLEPc/PEP.pyx:2962

  • __init__() โ€” do the setup thing ๐Ÿซถ
  • classmethod __new__(*args, **kwargs) โ€” spawn a fresh one โญ

๐Ÿ‘‘ slepc4py.SLEPc.RG ๐Ÿ‘‘

class slepc4py.SLEPc.RG

Bases: Object โ€” that's petsc4py.PETSc.Object, see https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Object.html#petsc4py.PETSc.Object

Region. ๐ŸŒธ

Okay so the RG package is the girl who defines a region of the complex plane. she's the one everybody calls when they need to say "the eigenvalues we want are, like, over there" โ€” various eigensolvers use her to pin down exactly where the wanted eigenvalues are located. periodt. ๐Ÿ’–

Enumerations

  • QuadRule โ€” RG quadrature rule for contour integral methods.
  • Type โ€” RG type.

class slepc4py.SLEPc.RG.QuadRule

Bases: object โ€” see https://docs.python.org/3/library/functions.html#object

RG quadrature rule for contour integral methods. ๐Ÿงš

  • TRAPEZOIDAL: Trapezoidal rule.
  • CHEBYSHEV: Chebyshev points.

See also:

RGQuadRule โ€” https://slepc.upv.es/release/manualpages/RG/RGQuadRule.html

Attributes Summary

Attributes Documentation

class slepc4py.SLEPc.RG.Type

Bases: object โ€” see https://docs.python.org/3/library/functions.html#object

RG type. ๐ŸŽ€

  • INTERVAL: A (generalized) interval. ๐Ÿ“
  • POLYGON: A polygonal region defined by its vertices. ๐Ÿ”บ
  • ELLIPSE: An ellipse defined by its center, radius and vertical scale. ๐Ÿฅš
  • RING: A ring region. ๐Ÿ’

See also:

RGType โ€” https://slepc.upv.es/release/manualpages/RG/RGType.html

Attributes Summary

Attributes Documentation

โœจ Methods Summary โœจ

okay bestie, here's the full RG method lineup โ€” every single one, no skips, no cap ๐Ÿ’…๐Ÿงš

  • appendOptionsPrefix([prefix]) โ€” Append to the prefix used for searching for all RG options in the database. prefix stacking, but make it RG-coded โœจ
  • canUseConjugates([realmats]) โ€” Half of integration points can be avoided (use their conjugates). math girlies stay winning ๐Ÿง 
  • checkInside(a) โ€” Determine if a set of given points are inside the region or not. inside check, very demure ๐Ÿ’…
  • computeBoundingBox() โ€” Compute box containing the region. wrap it up, box it in ๐ŸŽ
  • computeContour(n) โ€” Compute points on the contour of the region. outline that vibe โœจ
  • computeQuadrature(quad, n) โ€” Compute the values of the parameters used in a quadrature rule. quad goals fr fr ๐ŸŒˆ
  • create([comm]) โ€” Create the RG object. new RG, who dis? ๐Ÿ’–
  • destroy() โ€” Destroy the RG object. bye bye bestie, no crumbs left ๐Ÿ’€
  • getComplement() โ€” Get the flag indicating whether the region is complemented or not. complement check, periodt โœจ
  • getEllipseParameters() โ€” Get the parameters that define the ellipse region. ellipse era ๐ŸŒธ
  • getIntervalEndpoints() โ€” Get the parameters that define the interval region. interval tea โ˜•
  • getOptionsPrefix() โ€” Get the prefix used for searching for all RG options in the database. prefix reveal ๐Ÿ‘‘
  • getPolygonVertices() โ€” Get the parameters that define the interval region. polygon vibes, lowkey geometric โœจ
  • getRingParameters() โ€” Get the parameters that define the ring region. ring ring, it's giving โœจ
  • getScale() โ€” Get the scaling factor. scale check, math girlie ๐Ÿงฎ
  • getType() โ€” Get the RG type of this object. type reveal, iykyk ๐Ÿ’…
  • isAxisymmetric([vertical]) โ€” Determine if the region is axisymmetric. symmetry slay ๐Ÿฆ‹
  • isTrivial() โ€” Tell whether it is the trivial region (whole complex plane). trivial? not me being basic ๐Ÿ˜ญ
  • setComplement([comp]) โ€” Set a flag to indicate that the region is the complement of the specified one. complement flag, set it off ๐Ÿ’…
  • setEllipseParameters(center, radius[, vscale]) โ€” Set the parameters defining the ellipse region. ellipse parameters, locked in ๐Ÿ”’
  • setFromOptions() โ€” Set RG options from the options database. options database says hi ๐Ÿ“€
  • setIntervalEndpoints(a, b, c, d) โ€” Set the parameters defining the interval region. interval endpoints, set the boundaries bestie ๐ŸŽ€
  • setOptionsPrefix([prefix]) โ€” Set the prefix used for searching for all RG options in the database. prefix set, no cap ๐Ÿ‘‘
  • setPolygonVertices(v) โ€” Set the vertices that define the polygon region. polygon vertices, connect the dots โœจ
  • setRingParameters(center, radius, vscale, ...) โ€” Set the parameters defining the ring region. ring parameters, bling bling ๐Ÿ’
  • setScale([sfactor]) โ€” Set the scaling factor to be used. scale it up, scale it down ๐ŸŽš๏ธ
  • setType(rg_type) โ€” Set the type for the RG object. type set, main character energy ๐Ÿ‘‘
  • view([viewer]) โ€” Print the RG data structure. view it, print it, display it ๐Ÿ’–

โœจ Attributes Summary โœจ

okay so before we get into the actual methods, here's the little vibe-check table of attributes you can peek at on an RG ๐Ÿ‘€

  • complement โ€” tells u if the region is the complement of the specified one. ๐Ÿ’…
  • scale โ€” the scaling factor that's gonna be used. โœจ

๐Ÿ› ๏ธ Methods Documentation ๐Ÿ› ๏ธ

appendOptionsPrefix(prefix=None)

Adds to the prefix that's used when searching for all the RG options in the database. bestie this is how u namespace ur options ๐ŸŽ€

Logically collective.

Parameters

  • prefix (str | None) โ€” the prefix string that gets prepended to all RG option requests.

Return type

None

See also: setOptionsPrefix, getOptionsPrefix, [RGAppendOptionsPrefix](https://slepc.upv.es/release/manualpages/RG/RGAppendOptionsPrefix.html)

:sources: Source code at slepc4py/SLEPc/RG.pyx:190 <slepc4py/SLEPc/RG.pyx#L190>

canUseConjugates(realmats=True)

Half of the integration points can be avoided (use their conjugates instead). slay ๐Ÿฆ‹

Not collective.

Used in contour integral methods to figure out whether half of the integration points can be skipped (use their conjugates).

Parameters

  • realmats (bool) โ€” True if the problem matrices are real.

Returns

Whether it's possible to use conjugates. โœจ

Return type

bool

Notes

If some integration points are the conjugates of other points, then the associated computational cost can be saved ๐Ÿ’ธ. This depends on the problem matrices being real and the region being symmetric with respect to the horizontal axis. The result is false if you're using real arithmetic, or in the case of a flat region (height equal to zero).

See also: isAxisymmetric, [RGCanUseConjugates](https://slepc.upv.es/release/manualpages/RG/RGCanUseConjugates.html)

:sources: Source code at slepc4py/SLEPc/RG.pyx:458 <slepc4py/SLEPc/RG.pyx#L458>

checkInside(a)

Determine if a set of given points are inside the region or not. fr fr a little in-or-out test ๐Ÿ”ฅ

Not collective.

Parameters

  • a (Sequence[complex]) โ€” the coordinates of the points.

Returns

Computed result for each point (1=inside, 0=on the contour, -1=outside).

Return type

ArrayInt

Notes

If a scaling factor was set, the points are scaled before checking. ๐ŸŽ€

See also: setScale, setComplement, [RGCheckInside](https://slepc.upv.es/release/manualpages/RG/RGCheckInside.html)

:sources: Source code at slepc4py/SLEPc/RG.pyx:355 <slepc4py/SLEPc/RG.pyx#L355>

computeBoundingBox()

Compute the box that contains the region. it's giving "draw me a rectangle around it" ๐Ÿ“ฆ๐Ÿ’–

Not collective.

Determine the endpoints of a rectangle in the complex plane that contains the region.

Returns

  • a (float) โ€” the left endpoint of the bounding box on the real axis.
  • b (float) โ€” the right endpoint of the bounding box on the real axis.
  • c (float) โ€” the bottom endpoint of the bounding box on the imaginary axis.
  • d (float) โ€” the top endpoint of the bounding box on the imaginary axis.

Return type

tuple[float, float, float, float]

See also: computeContour, setScale, [RGComputeBoundingBox](https://slepc.upv.es/release/manualpages/RG/RGComputeBoundingBox.html)

:sources: Source code at slepc4py/SLEPc/RG.pyx:430 <slepc4py/SLEPc/RG.pyx#L430>

computeContour(n)

Compute points on the contour of the region. โœจ outline baddie โœจ

Not collective.

Compute the coordinates of several points lying on the contour of the region.

Parameters

  • n (int) โ€” the number of points to compute.

Returns

Computed points.

Return type

list of complex

See also: computeBoundingBox, setScale, [RGComputeContour](https://slepc.upv.es/release/manualpages/RG/RGComputeContour.html)

:sources: Source code at slepc4py/SLEPc/RG.pyx:395 <slepc4py/SLEPc/RG.pyx#L395>

computeQuadrature(quad, n)

Compute the values of the parameters used in a quadrature rule. ๐Ÿงฎ bestie this is the math-math one iykyk

Not collective.

Compute the values of the parameters used in a quadrature rule for a contour integral around the boundary of the region.

Parameters

  • quad (QuadRule) โ€” the type of quadrature.
  • n (int) โ€” the number of quadrature points to compute.

Returns

  • z (ArrayScalar) โ€” quadrature points.
  • zn (ArrayScalar) โ€” normalized quadrature points.
  • w (ArrayScalar) โ€” quadrature weights.

Return type

tuple[ArrayScalar, ArrayScalar, ArrayScalar]

Notes

In complex scalars, the values returned in z are often the same as those computed by computeContour(), but that is not the case in real scalars, where all output arguments are real. ๐Ÿ‘€

The computed values change for different quadrature rules.

See also: computeContour, [RGComputeQuadrature](https://slepc.upv.es/release/manualpages/RG/RGComputeQuadrature.html)

:sources: Source code at slepc4py/SLEPc/RG.pyx:494 <slepc4py/SLEPc/RG.pyx#L494>

create(comm=None)

Create the RG object. ๐ŸŽ€ main character energy fr

Collective.

Parameters

  • comm (Comm | None) โ€” MPI communicator; if it's not provided, it defaults to all processes.

Return type

Self

See also: [RGCreate](https://slepc.upv.es/release/manualpages/RG/RGCreate.html)

:sources: Source code at slepc4py/SLEPc/RG.pyx:87 <slepc4py/SLEPc/RG.pyx#L87>

destroy()

Destroy the RG object. ๐Ÿ’€ we love a clean exit

Collective.

See also: [RGDestroy](https://slepc.upv.es/release/manualpages/RG/RGDestroy.html)

:sources: Source code at slepc4py/SLEPc/RG.pyx:73 <slepc4py/SLEPc/RG.pyx#L73>

Return type

Self

getComplement()

Get the flag indicating whether the region is complemented or not. ๐ŸŒธ

Not collective.

Returns

Whether the region is complemented or not.

getEllipseParameters() ๐ŸŽ€

okay so bestie, this pulls the parameters that define the ellipse region. Get the parameters that define the ellipse region. periodt.

Not collective. so every process has its own lil copy of the answer, no group chat required ๐Ÿ’–

Returns โ€” a tuple, in this exact order:

  • center (Scalar) โ€” the center ๐ŸŒธ
  • radius (float) โ€” the radius โœจ
  • vscale (float) โ€” the vertical scale ๐Ÿ“

Return type โ€” tuple (https://docs.python.org/3/library/stdtypes.html#tuple) of Scalar (#slepc4py.typing.Scalar), float (https://docs.python.org/3/library/functions.html#float), float (https://docs.python.org/3/library/functions.html#float).

See also โ€” setEllipseParameters, RGEllipseGetParameters โ€” https://slepc.upv.es/release/manualpages/RG/RGEllipseGetParameters.html ๐Ÿซถ

:sources: Source code at slepc4py/SLEPc/RG.pyx:572

getIntervalEndpoints() ๐Ÿ’…

grabbing the parameters that define the interval region. Get the parameters that define the interval region. yup, it's giving bounding-box energy ๐Ÿฆ‹

Not collective. nope, this one's all local, no MPI gossip ๐Ÿ’€

Returns โ€” four floats, and the order matters fr fr:

  • a (float) โ€” the left endpoint in the real axis
  • b (float) โ€” the right endpoint in the real axis
  • c (float) โ€” the bottom endpoint in the imaginary axis
  • d (float) โ€” the top endpoint in the imaginary axis

Return type โ€” tuple (https://docs.python.org/3/library/stdtypes.html#tuple) with four floats (https://docs.python.org/3/library/functions.html#float ร—4, they all point to the same link, iconic ๐Ÿ’…).

See also โ€” setIntervalEndpoints, RGIntervalGetEndpoints โ€” https://slepc.upv.es/release/manualpages/RG/RGIntervalGetEndpoints.html โœจ

:sources: Source code at slepc4py/SLEPc/RG.pyx:634

getOptionsPrefix() ๐ŸŒˆ

this one hands you the prefix that gets used when it's searching for all RG options in the database. Get the prefix used for searching for all RG options in the database. iykyk, prefixes are how you keep your options from mingling ๐Ÿซถ

Not collective. ๐Ÿ“

Returns โ€” the prefix string set for this RG object. yes. that's it. that's the whole return ๐Ÿ’–

Return type โ€” str (https://docs.python.org/3/library/stdtypes.html#str).

See also โ€” setOptionsPrefix, appendOptionsPrefix, RGGetOptionsPrefix โ€” https://slepc.upv.es/release/manualpages/RG/RGGetOptionsPrefix.html ๐ŸŽ€

:sources: Source code at slepc4py/SLEPc/RG.pyx:171

getPolygonVertices() ๐Ÿ‘‘

okay so this one is a mood โ€” the doc text literally says it gets the parameters that define the interval region, but bestie, it is the polygon vertices getter. that's what the original says, we are NOT fixing it, we are simply reporting it as-is ๐Ÿ’€ iconic behavior honestly.

Not collective. ๐Ÿ™ˆ

Returns โ€” the vertices. just the vertices. no cap ๐Ÿฆ‹

Return type โ€” ArrayComplex (#slepc4py.typing.ArrayComplex).

See also โ€” setPolygonVertices, RGPolygonGetVertices โ€” https://slepc.upv.es/release/manualpages/RG/RGPolygonGetVertices.html โญ

:sources: Source code at slepc4py/SLEPc/RG.pyx:690

getRingParameters() ๐Ÿ’œ

getting the parameters that define the ring region ๐Ÿ’ โ€” not ring as in phone, ring as in annulus, main character geometry energy.

Not collective. ๐ŸŒธ

Returns โ€” a whole little entourage of six values, in order:

  • center (Scalar) โ€” the center
  • radius (float) โ€” the radius
  • vscale (float) โ€” the vertical scale
  • start_ang (float) โ€” the right-hand side angle
  • end_ang (float) โ€” the left-hand side angle
  • width (float) โ€” the width of the ring

Return type โ€” tuple (https://docs.python.org/3/library/stdtypes.html#tuple) of Scalar (#slepc4py.typing.Scalar), then five floats (https://docs.python.org/3/library/functions.html#float), yes, five of them. count them. I counted. ๐Ÿ’…

See also โ€” setRingParameters, RGRingGetParameters โ€” https://slepc.upv.es/release/manualpages/RG/RGRingGetParameters.html โœจ

:sources: Source code at slepc4py/SLEPc/RG.pyx:775

getScale() ๐Ÿ“

just handing you the scaling factor. Get the scaling factor. short, sweet, ate ๐Ÿ“

Not collective. ๐ŸŽ€

Returns โ€” the scaling factor, bestie ๐Ÿ’–

Return type โ€” float (https://docs.python.org/3/library/functions.html#float).

See also โ€” setScale, RGGetScale โ€” https://slepc.upv.es/release/manualpages/RG/RGGetScale.html ๐Ÿซถ

:sources: Source code at slepc4py/SLEPc/RG.pyx:336

getType() ๐ŸŒŸ

tell me what you are, RG. Get the RG type of this object. this is the vibe check fr fr ๐Ÿ’…

Not collective. ๐ŸŒˆ

Returns โ€” the region type currently being used. that's the tea โ˜•

Return type โ€” str (https://docs.python.org/3/library/stdtypes.html#str).

See also โ€” setType, RGGetType โ€” https://slepc.upv.es/release/manualpages/RG/RGGetType.html โญ

:sources: Source code at slepc4py/SLEPc/RG.pyx:127

isAxisymmetric(vertical=False) ๐Ÿชž

figuring out if the region is axisymmetric, aka symmetric with respect to the real or imaginary axis. mirror mirror on the wall ๐Ÿฆ‹

Not collective. ๐Ÿ’–

Parameters

  • vertical (bool) โ€” True if symmetry must be checked against the vertical axis. default is False, so by default you're checking the other one, no cap ๐ŸŽ€

Returns โ€” True if the region is axisymmetric. ๐Ÿ‘‘

Return type โ€” bool (https://docs.python.org/3/library/functions.html#bool).

See also โ€” canUseConjugates, RGIsAxisymmetric โ€” https://slepc.upv.es/release/manualpages/RG/RGIsAxisymmetric.html โœจ

:sources: Source code at slepc4py/SLEPc/RG.pyx:249

isTrivial() ๐Ÿ’€

is it the trivial region? aka the WHOLE complex plane? Tell whether it is the trivial region (whole complex plane). big "yes i contain literally everything" energy ๐ŸŒŒ

Not collective. ๐ŸŒธ

Returns โ€” True if the region is equal to the whole complex plane, e.g., an interval region with all four endpoints unbounded or an ellipse with infinite radius. those are the two examples the docs give, and I am not adding a third, bestie, that would be lying ๐Ÿ˜ญ

Return type โ€” bool (https://docs.python.org/3/library/functions.html#bool).

See also โ€” checkInside, RGIsTrivial โ€” https://slepc.upv.es/release/manualpages/RG/RGIsTrivial.html ๐Ÿซถ

:sources: Source code at slepc4py/SLEPc/RG.pyx:228

setComplement(comp=True) ๐Ÿ”„

setting a flag that says the region is the complement of the specified one. yes bestie, you're flipping it inside out ๐Ÿ’… the default is comp=True so the complementation is ON unless you say otherwise. slay.

Logically collective. so all the processes need to agree on this one โ€” no solo missions ๐ŸŽ€

Parameters

  • comp (bool) โ€” activate/deactivate the complementation of the region. ๐Ÿฆ‹

Return type โ€” None (https://docs.python.org/3/library/constants.html#None). nothing comes back. it just does the thing. iconic ๐ŸคŒ

See also โ€” getComplement, RGSetComplement โ€” https://slepc.upv.es/release/manualpages/RG/RGSetComplement.html โœจ

:sources: Source code at slepc4py/SLEPc/RG.pyx:296

setEllipseParameters(center, radius, vscale=None) ๐Ÿฅš

setting the parameters that define the ellipse region โœจ

Logically collective. everybody gotta be on the same page for this one ๐Ÿ’–

Parameters

  • center (Scalar) โ€” the center.
  • radius (float) โ€” the radius.
  • vscale (float | None) โ€“ The vertical scale, bestie. That's the squish factor on the y-axis, literally.

Return type None

Notes

When PETSc is built with real scalars, the center is restricted to a real value. no imaginary adventures allowed, sorry ๐Ÿ’…

See also: getEllipseParameters, RGEllipseSetParameters

:sources:Source code at slepc4py/SLEPc/RG.pyx:542 <slepc4py/SLEPc/RG.pyx#L542>``

setFromOptions()

Set RG options from the options database. it just vibes with whatever flags you gave it โœจ

Collective.

Notes

To see all options, run your program with the -help option. do it, it's giving cheat code energy

See also: setOptionsPrefix, RGSetFromOptions

Return type None

:sources:Source code at slepc4py/SLEPc/RG.pyx:209 <slepc4py/SLEPc/RG.pyx#L209>``

setIntervalEndpoints(a, b, c, d)

Set the parameters defining the interval region. a whole lil rectangle of eigenvalues, periodt

Logically collective.

Parameters

  • a (float) โ€“ The left endpoint in the real axis.
  • b (float) โ€“ The right endpoint in the real axis.
  • c (float) โ€“ The bottom endpoint in the imaginary axis.
  • d (float) โ€“ The top endpoint in the imaginary axis.

Return type None

Notes

The region is defined as [a,b] x [c,d]. box moment ๐ŸŽ€ Particular cases are an interval on the real axis (c=d=0), similarly for the imaginary axis (a=b=0), the whole complex plane (a=-\infty,b=\infty,c=-\infty,d=\infty), and so on.

When PETSc is built with real scalars, the region must be symmetric with respect to the real axis.

See also: getIntervalEndpoints, RGIntervalSetEndpoints

:sources:Source code at slepc4py/SLEPc/RG.pyx:597 <slepc4py/SLEPc/RG.pyx#L597>``

setOptionsPrefix(prefix=None)

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

Logically collective.

Parameters

  • prefix (str | None) โ€“ The prefix string to prepend to all RG 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. do not add it yourself, i promise it's handling that ๐Ÿ’€

See also: appendOptionsPrefix, getOptionsPrefix, RGGetOptionsPrefix

:sources:Source code at slepc4py/SLEPc/RG.pyx:146 <slepc4py/SLEPc/RG.pyx#L146>``

setPolygonVertices(v)

Set the vertices that define the polygon region. connect the dots but make it eigenvalues ๐ŸŒˆ

Logically collective.

Parameters

  • v (Sequence[float] | Sequence[Scalar]) โ€“ The vertices.

Return type None

See also: getPolygonVertices, RGPolygonSetVertices

:sources:Source code at slepc4py/SLEPc/RG.pyx:662 <slepc4py/SLEPc/RG.pyx#L662>``

setRingParameters(center, radius, vscale, start_ang, end_ang, width)

Set the parameters defining the ring region. donut-shaped search zone, i'm obsessed ๐Ÿฉ

Logically collective.

Parameters

  • center (Scalar) โ€“ The center.
  • radius (float) โ€“ The radius.
  • vscale (float) โ€“ The vertical scale.
  • start_ang (float) โ€“ The right-hand side angle.
  • end_ang (float) โ€“ The left-hand side angle.
  • width (float) โ€“ The width of the ring.

Return type None

Notes

The values of center, radius and vscale have the same meaning as in the ellipse region. The start_ang and end_ang define the span of the ring (by default it is the whole ring), while the width is the separation between the two concentric ellipses (above and below the radius by width/2).

The start and end angles are expressed as a fraction of the circumference. The allowed range is [0,\dots,1], with 0 corresponding to 0 radians, 0.25 to \pi/2 radians, and so on. It is allowed to have start_ang > end_ang, in which case the ring region crosses over the zero angle. yes it wraps around, it's built different โœจ

When PETSc is built with real scalars, the center is restricted to a real value, and the start and end angles must be such that the region is symmetric with respect to the real axis.

See also: getRingParameters, RGRingSetParameters

:sources:Source code at slepc4py/SLEPc/RG.pyx:716 <slepc4py/SLEPc/RG.pyx#L716>``

setScale(sfactor=None)

Set the scaling factor to be used.

Logically collective.

Set the scaling factor to be used when checking that a point is inside the region and when computing the contour.

Parameters

  • sfactor (float) โ€“ The scaling factor (default=1).

Return type None

See also: getScale, checkInside, computeContour, RGSetScale

:sources:Source code at slepc4py/SLEPc/RG.pyx:314 <slepc4py/SLEPc/RG.pyx#L314>``

setType(rg_type)

Set the type for the RG object.

Logically collective.

Parameters

  • rg_type (Type | str) โ€“ The region type to be used.

Return type None

See also: getType, RGSetType

:sources:Source code at slepc4py/SLEPc/RG.pyx:108 <slepc4py/SLEPc/RG.pyx#L108>``

view(viewer=None)

Print the RG data structure. show me everything, no secrets ๐Ÿซถ

Collective.

Parameters

  • viewer (Viewer | None) โ€“ Visualization context; if not provided, the standard output is used.

Return type None

See also: RGView

:sources:Source code at slepc4py/SLEPc/RG.pyx:54 <slepc4py/SLEPc/RG.pyx#L54>``

โœจ Attributes Documentation โœจ

complement

If the region is the complement of the specified one. the "everything except this" era ๐Ÿฆ‹

:sources:Source code at slepc4py/SLEPc/RG.pyx:811 <slepc4py/SLEPc/RG.pyx#L811>``

scale

The scaling factor to be used.

:sources:Source code at slepc4py/SLEPc/RG.pyx:818 <slepc4py/SLEPc/RG.pyx#L818>``

__init__()

classmethod __new__(*args, **kwargs)

๐ŸŒˆ slepc4py.SLEPc.ST ๐ŸŒˆ

class slepc4py.SLEPc.ST

Bases: Object โ€” that's the petsc4py.PETSc.Object one, over at https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Object.html#petsc4py.PETSc.Object bestie, go look at your family tree ๐Ÿ’–

Spectral Transformation. Yeah. It said what it said.

The Spectral Transformation (ST) class encapsulates the functionality required for acceleration techniques based on the transformation of the spectrum. The eigensolvers implemented in EPS work by applying an operator to a set of vectors and this operator can adopt different forms. The ST object handles all the different possibilities in a uniform way, so that the solver can proceed without knowing which transformation has been selected. Polynomial eigensolvers in PEP also support spectral transformation.

Like, the whole point is that ST is the โœจglow-up artistโœจ for your spectrum โ€” it does the transformation work so your solver literally never has to know what's happening under the hood. Main character energy fr fr ๐Ÿ’…

โœจ Enumerations โœจ

  • FilterDamping โ€” ST filter damping.
  • FilterType โ€” ST filter type.
  • MatMode โ€” ST matrix mode.
  • Type โ€” ST type.

๐Ÿฆ‹ slepc4py.SLEPc.ST.FilterDamping ๐Ÿฆ‹

class slepc4py.SLEPc.ST.FilterDamping

Bases: object โ€” https://docs.python.org/3/library/functions.html#object

ST filter damping.

  • NONE: No damping
  • JACKSON: Jackson damping
  • LANCZOS: Lanczos damping
  • FEJER: Fejer damping

See also: STFilterDamping โ€” https://slepc.upv.es/release/manualpages/ST/STFilterDamping.html

๐ŸŒธ Attributes Summary ๐ŸŒธ

๐ŸŽ€ Attributes Documentation ๐ŸŽ€

FEJER: int = FEJER Constant FEJER of type int (https://docs.python.org/3/library/functions.html#int)

JACKSON: int = JACKSON Constant JACKSON of type int (https://docs.python.org/3/library/functions.html#int)

LANCZOS: int = LANCZOS Constant LANCZOS of type int (https://docs.python.org/3/library/functions.html#int)

NONE: int = NONE Constant NONE of type int (https://docs.python.org/3/library/functions.html#int)

__init__()

classmethod __new__(*args, **kwargs)

๐Ÿ’œ slepc4py.SLEPc.ST.FilterType ๐Ÿ’œ

class slepc4py.SLEPc.ST.FilterType

Bases: object โ€” https://docs.python.org/3/library/functions.html#object

ST filter type.

  • FILTLAN: An adapted implementation of the Filtered Lanczos Package.
  • CHEBYSEV: A polynomial filter based on a truncated Chebyshev series.

See also: STFilterType โ€” https://slepc.upv.es/release/manualpages/ST/STFilterType.html

ok so real talk: the bullet up there says CHEBYSEV and the attribute down there says CHEBYSHEV. That is what the original says, and I am not touching it. Both spellings stay, exactly as written, no cap ๐Ÿ’€

๐ŸŒธ Attributes Summary ๐ŸŒธ

๐ŸŽ€ Attributes Documentation ๐ŸŽ€

CHEBYSHEV: int = CHEBYSHEV Constant CHEBYSHEV of type int (https://docs.python.org/3/library/functions.html#int)

FILTLAN: int = FILTLAN Constant FILTLAN of type int (https://docs.python.org/3/library/functions.html#int)

__init__()

classmethod __new__(*args, **kwargs)

๐Ÿ”ฅ slepc4py.SLEPc.ST.MatMode ๐Ÿ”ฅ

class slepc4py.SLEPc.ST.MatMode

Bases: object โ€” https://docs.python.org/3/library/functions.html#object

ST matrix mode.

  • COPY: A working copy of the matrix is created.
  • INPLACE: The operation is computed in-place.
  • SHELL: The matrix A - \sigma B is handled as an implicit matrix.

See also: STMatMode โ€” https://slepc.upv.es/release/manualpages/ST/STMatMode.html

๐ŸŒธ Attributes Summary ๐ŸŒธ

๐ŸŽ€ Attributes Documentation ๐ŸŽ€

COPY: int = COPY Constant COPY of type int (https://docs.python.org/3/library/functions.html#int)

INPLACE: int = INPLACE Constant INPLACE of type int (https://docs.python.org/3/library/functions.html#int)

SHELL: int = SHELL Constant SHELL of type int (https://docs.python.org/3/library/functions.html#int)

__init__()

classmethod __new__(*args, **kwargs)

๐Ÿ‘‘ slepc4py.SLEPc.ST.Type ๐Ÿ‘‘

class slepc4py.SLEPc.ST.Type

Bases: object โ€” https://docs.python.org/3/library/functions.html#object

ST type.

  • SHIFT: Shift from origin.
  • SINVERT โ€” Shift-and-invert. ๐Ÿ’… the classic move, lowkey iconic.
  • CAYLEY โ€” Cayley transform. โœจ
  • PRECOND โ€” Preconditioner. ๐Ÿซถ doing the quiet heavy lifting fr fr.
  • FILTER โ€” Polynomial filter. ๐ŸŽ€
  • SHELL โ€” User-defined. ๐Ÿ‘‘ it's giving DIY main character energy, you build it yourself.

See also:

โœจ Attributes Summary โœจ

okay bestie, here's the little legend of every attribute this thing exposes, all of them are str objects (and yes, str links to the Python docs every single time, no cap):

๐ŸŒธ Attributes Documentation ๐ŸŒธ

every single one, spelled out, no skipping, we're doing the whole roster ๐Ÿ’–

CAYLEY: str = CAYLEY

Object CAYLEY of type str <https://docs.python.org/3/library/stdtypes.html#str>

FILTER: str = FILTER

Object FILTER of type str <https://docs.python.org/3/library/stdtypes.html#str>

PRECOND: str = PRECOND

Object PRECOND of type str <https://docs.python.org/3/library/stdtypes.html#str>

SHELL: str = SHELL

Object SHELL of type str <https://docs.python.org/3/library/stdtypes.html#str>

SHIFT: str = SHIFT

Object SHIFT of type str <https://docs.python.org/3/library/stdtypes.html#str>

SINVERT: str = SINVERT

Object SINVERT of type str <https://docs.python.org/3/library/stdtypes.html#str>

๐Ÿฆ‹ __init__()

that's the init, bestie. it exists. it does the setup thing. โœจ

๐Ÿฆ‹ classmethod __new__(*args, **kwargs)

and here's __new__, flagged as a classmethod, taking *args and **kwargs โ€” so it'll happily swallow whatever you hand it. ๐Ÿ™ˆ

โœจ Methods Summary โœจ

okay bestie, here's the full roster of ST method girlies ๐Ÿ’… every single one of them, no skips, no cuts:

  • appendOptionsPrefix([prefix]) โ€” tacks more stuff onto the prefix that gets used when hunting down, like, every ST option in the database ๐Ÿ”
  • apply(x, y) โ€” runs the spectral transformation operator on a vector โœจ
  • applyHermitianTranspose(x, y) โ€” applies the Hermitian-transpose of the operator to a vector ๐Ÿชž
  • applyMat(X, Y) โ€” runs the spectral transformation operator on a matrix, yes the whole matrix ๐Ÿ’…
  • applyTranspose(x, y) โ€” applies the transpose of the operator to a vector ๐Ÿ”„
  • create([comm]) โ€” makes the ST object exist, birth moment fr ๐ŸŒฑ
  • destroy() โ€” destroys the ST object, rip ๐Ÿชฆ
  • getCayleyAntishift() โ€” grab the value of the anti-shift for the Cayley spectral transformation ๐Ÿ‘‘
  • getFilterDamping() โ€” grab the type of damping used in the polynomial filter ใ€ฐ๏ธ
  • getFilterDegree() โ€” grab the degree of the filter polynomial, it's giving math ๐Ÿ“
  • getFilterInterval() โ€” grab the interval that contains the eigenvalues you actually want ๐ŸŽฏ
  • getFilterRange() โ€” grab the interval containing all the eigenvalues ๐ŸŒˆ
  • getFilterRange() โ€” wait no, it's getFilterRange() โ€” Get the interval containing all eigenvalues, we said that. moving on ๐Ÿ’€
  • getFilterType() โ€” grab the method that's gonna be used to build the polynomial filter ๐Ÿ› ๏ธ
  • getKSP() โ€” grab the KSP object that's associated with the spectral transformation ๐Ÿ”‘
  • getMatMode() โ€” grab a flag that tells you how the matrix is being shifted ๐Ÿ‘€
  • getMatStructure() โ€” grab the internal matrix structure attribute ๐Ÿงฌ
  • getMatrices() โ€” grab the matrices associated with the eigenvalue problem ๐Ÿ“š
  • getOperator() โ€” grab a shell matrix representing the operator of the spectral transformation ๐Ÿš
  • getOptionsPrefix() โ€” grab the prefix used for searching all ST options in the database ๐Ÿ”Ž
  • getPreconditionerMat() โ€” grab the matrix that was previously set by setPreconditionerMat() ๐ŸŽ
  • getShift() โ€” grab the shift associated with the spectral transformation ๐ŸŽš๏ธ
  • getSplitPreconditioner() โ€” grab the matrices that'll be used to build the preconditioner ๐Ÿงฉ
  • getTransform() โ€” grab the flag saying whether the transformed matrices are computed or not ๐Ÿค”
  • getType() โ€” grab the ST type of this object, what kind of ST are you bestie ๐Ÿท๏ธ
  • reset() โ€” reset the ST object, clean slate era โœจ
  • restoreOperator(op) โ€” restore the operator matrix you seized earlier, give it back ๐Ÿซถ
  • setCayleyAntishift(mu) โ€” set the value of the anti-shift for the Cayley spectral transformation ๐Ÿ‘‘

โ€ฆanti-shift for the Cayley spectral transformation. โ† okay that's the tail end of the last row from the option table before we got here, bestie, don't panic ๐Ÿ˜Œ continuing the table now ๐Ÿ’…

  • setFilterDamping(damping) โ€” Set the type of damping to be used in the polynomial filter. ๐ŸŽ€
  • setFilterDegree(deg) โ€” Set the degree of the filter polynomial. ๐Ÿ“
  • setFilterInterval(inta, intb) โ€” Set the interval containing the desired eigenvalues. ๐ŸŒธ
  • setFilterRange(left, right) โ€” Set the numerical range (or field of values) of the matrix. ๐ŸŒˆ
  • setFilterType(filter_type) โ€” Set the method to be used to build the polynomial filter. ๐Ÿงš
  • setFromOptions() โ€” Set ST options from the options database. ๐Ÿ—„๏ธโœจ
  • setKSP(ksp) โ€” Set the KSP object associated with the spectral transformation. ๐Ÿ”ฅ
  • setMatMode(mode) โ€” Set a flag related to management of transformed matrices. ๐Ÿ‘‘
  • setMatStructure(structure) โ€” Set the matrix structure attribute. ๐Ÿฆ‹
  • setMatrices(operators) โ€” Set the matrices associated with the eigenvalue problem. ๐Ÿ’œ
  • setOptionsPrefix([prefix]) โ€” Set the prefix used for searching for all ST options in the database. ๐Ÿ”
  • setPreconditionerMat([P]) โ€” Set the matrix to be used to build the preconditioner. ๐Ÿ› ๏ธ
  • setShift(shift) โ€” Set the shift associated with the spectral transformation. ๐ŸŽฏ
  • setSplitPreconditioner(operators[, structure]) โ€” Set the matrices to be used to build the preconditioner. ๐Ÿงฉ
  • setTransform([flag]) โ€” Set a flag to indicate whether the transformed matrices are computed or not. ๐Ÿšฉ
  • setType(st_type) โ€” Set the particular spectral transformation to be used. โญ
  • setUp() โ€” Prepare for the use of a spectral transformation. ๐ŸŽฌ
  • view([viewer]) โ€” Print the ST data structure. ๐Ÿ–จ๏ธ

โœจ Attributes Summary โœจ

these are the lil properties you can just peek at, no cap ๐Ÿซถ

  • ksp โ€” KSP object associated with the spectral transformation. ๐Ÿ’–
  • mat_mode โ€” How the transformed matrices are being stored in the ST. ๐Ÿ“ฆ
  • mat_structure โ€” Relation of the sparsity pattern of all ST matrices. ๐Ÿ•ธ๏ธ
  • shift โ€” Value of the shift. ๐ŸŽš๏ธ
  • transform โ€” If the transformed matrices are computed. โœ…

๐ŸŒŸ Methods Documentation ๐ŸŒŸ

๐Ÿซง appendOptionsPrefix(prefix=None)

Append to the prefix used for searching for all ST options in the database. ๐Ÿ—‚๏ธโœจ

Logically collective. (so likeโ€ฆ everybody has to be on the same page, fr fr)

Parameters

Return type

See also:

:sources: Source code at slepc4py/SLEPc/ST.pyx:256 (slepc4py/SLEPc/ST.pyx#L256)

๐Ÿซง apply(x, y)

Apply the spectral transformation operator to a vector. ๐Ÿ’ซ

Collective.

Apply the spectral transformation operator to a vector, for instance y=(A-\sigma B)^{-1}Bx in the case of the shift-and-invert transformation and generalized eigenproblem. ๐Ÿง ๐Ÿ”ฅ

Return type None โ€” which in docs-speak is https://docs.python.org/3/library/constants.html#None

See also: applyTranspose, applyHermitianTranspose, applyMat, STApply <https://slepc.upv.es/release/manualpages/ST/STApply.html> ๐Ÿ’–

:sources:Source code at slepc4py/SLEPc/ST.pyx:758 <slepc4py/SLEPc/ST.pyx#L758>``

๐ŸŒธ applyHermitianTranspose(x, y)

Apply the Hermitian-transpose of the operator to a vector. Yup. Hermitian-transpose. Say it with your chest ๐Ÿ’…

Collective. Literally everyone in the communicator shows up for this one.

So what it actually does: applies the Hermitian-transpose of the operator to a vector โ€” like, for instance y=B^*(A - \sigma B)^{-*}x in the case of the shift-and-invert transformation and generalized eigenproblem. Not me casually dropping an inverse-star in the group chat ๐Ÿ˜ญ

Parameters

Return type None โ€” https://docs.python.org/3/library/constants.html#None

See also: apply, applyTranspose, STApplyHermitianTranspose <https://slepc.upv.es/release/manualpages/ST/STApplyHermitianTranspose.html> ๐ŸŽ€

:sources:Source code at slepc4py/SLEPc/ST.pyx:804 <slepc4py/SLEPc/ST.pyx#L804>``

๐Ÿ‘‘ applyMat(X, Y)

Apply the spectral transformation operator to a matrix. Not a vector. A whole matrix. Main character behavior, honestly ๐ŸŒˆ

Collective. Yes, still collective. Solidarity ๐Ÿ’œ

Okay so it applies the spectral transformation operator to a matrix โ€” for instance Y=(A-\sigma B)^{-1}BX in the case of the shift-and-invert transformation and generalized eigenproblem. The way that formula just sits there, stunning โœจ

Parameters

Return type None โ€” https://docs.python.org/3/library/constants.html#None

See also: apply, STApplyMat <https://slepc.upv.es/release/manualpages/ST/STApplyMat.html> โญ

:sources:Source code at slepc4py/SLEPc/ST.pyx:827 <slepc4py/SLEPc/ST.pyx#L827>``

๐Ÿ’… applyTranspose(x, y)

Apply the transpose of the operator to a vector. Transpose girlies, this one's for you ๐Ÿ™ˆ

Collective. Group effort, always ๐Ÿซถ

Concretely: applies the transpose of the operator to a vector โ€” like, for instance y=B^T(A-\sigma B)^{-T}x in the case of the shift-and-invert transformation and generalized eigenproblem. Note that it's B^T with a plain T, not a star โ€” do not mix them up, iykyk ๐Ÿ’€

Parameters

Return type None โ€” https://docs.python.org/3/library/constants.html#None

See also: apply, applyHermitianTranspose, STApplyTranspose <https://slepc.upv.es/release/manualpages/ST/STApplyTranspose.html> ๐ŸŒธ

:sources:Source code at slepc4py/SLEPc/ST.pyx:781 <slepc4py/SLEPc/ST.pyx#L781>``

๐Ÿงš create(comm=None)

Create the ST object. Fresh out of the box, brand new, no notes ๐Ÿ‘‘

Collective.

Parameters

Return type Self โ€” https://docs.python.org/3/library/typing.html#typing.Self

See also: STCreate <https://slepc.upv.es/release/manualpages/ST/STCreate.html> ๐Ÿ’œ

:sources:Source code at slepc4py/SLEPc/ST.pyx:145 <slepc4py/SLEPc/ST.pyx#L145>``

๐Ÿ’€ destroy()

Destroy the ST object. It's giving closure. It's giving letting go ๐Ÿฅฒ

Collective.

See also: STDestroy <https://slepc.upv.es/release/manualpages/ST/STDestroy.html> ๐Ÿ™ˆ

:sources:Source code at slepc4py/SLEPc/ST.pyx:119 <slepc4py/SLEPc/ST.pyx#L119>``

Return type Self โ€” https://docs.python.org/3/library/typing.html#typing.Self

โœจ getCayleyAntishift()

Get the value of the anti-shift for the Cayley spectral transformation. Anti-shift. Not a shift. An anti-shift. Lowkey iconic naming ๐ŸŽ€

Not collective. Just you and your local info, bestie.

Returns The anti-shift.

Return type Scalar โ€” <#slepc4py.typing.Scalar>

See also: setCayleyAntishift, STCayleyGetAntishift <https://slepc.upv.es/release/manualpages/ST/STCayleyGetAntishift.html> ๐Ÿ’–

:sources:Source code at slepc4py/SLEPc/ST.pyx:942 <slepc4py/SLEPc/ST.pyx#L942>``

๐ŸŒˆ getFilterDamping()

Get the type of damping used in the polynomial filter. Because even filters need a lil damping sometimes ๐Ÿ˜Œ

Not collective.

Returns The type of damping.

Return type FilterDamping โ€” <#slepc4py.SLEPc.ST.FilterDamping>

See also: setFilterDamping, STFilterGetDamping <https://slepc.upv.es/release/manualpages/ST/STFilterGetDamping.html> โญ

:sources:Source code at slepc4py/SLEPc/ST.pyx:1164 <slepc4py/SLEPc/ST.pyx#L1164>``

๐Ÿฆ‹ getFilterDegree()

Get the degree of the filter polynomial. Just the degree. The polynomial's whole level of experience ๐Ÿ’…

Not collective.

Returns The polynomial degree.

Return type int โ€” https://docs.python.org/3/library/functions.html#int

See also: setFilterDegree, STFilterGetDegree <https://slepc.upv.es/release/manualpages/ST/STFilterGetDegree.html> ๐ŸŒธ

:sources:Source code at slepc4py/SLEPc/ST.pyx:1123 <slepc4py/SLEPc/ST.pyx#L1123>``

๐ŸŽ€ getFilterInterval()

Get the interval containing the desired eigenvalues. The desired ones specifically, okay? We're picky here ๐Ÿ’œ

Not collective.

Returns

Return type tuple[float, float] โ€” https://docs.python.org/3/library/stdtypes.html#tuple for the tuple, https://docs.python.org/3/library/functions.html#float for both floats

See also: setFilterInterval, STFilterGetInterval <https://slepc.upv.es/release/manualpages/ST/STFilterGetInterval.html> ๐Ÿ”ฅ

:sources:Source code at slepc4py/SLEPc/ST.pyx:1031 <slepc4py/SLEPc/ST.pyx#L1031>``

๐Ÿ‘‘ getFilterRange()

Get the interval containing all eigenvalues. All of them. Everyone's invited to this spectral range ๐Ÿซถ

Not collective.

Returns

Return type tuple[float, float] โ€” https://docs.python.org/3/library/stdtypes.html#tuple, plus https://docs.python.org/3/library/functions.html#float for good measure

See also: getFilterInterval, STFilterGetRange <https://slepc.upv.es/release/manualpages/ST/STFilterGetRange.html> ๐Ÿ’–

:sources:Source code at slepc4py/SLEPc/ST.pyx:1083 <slepc4py/SLEPc/ST.pyx#L1083>``

โญ getFilterType()

Get the method to be used to build the polynomial filter. Which flavor of filter are we building today, bestie ๐Ÿงš

Not collective.

Returns The type of filter.

Return type FilterType โ€” <#slepc4py.SLEPc.ST.FilterType>

See also: setFilterType, STFilterGetType <https://slepc.upv.es/release/manualpages/ST/STFilterGetType.html> ๐Ÿ’…

:sources:Source code at slepc4py/SLEPc/ST.pyx:979 <slepc4py/SLEPc/ST.pyx#L979>``

๐Ÿซถ getKSP()

Get the KSP object associated with the spectral transformation. Yes, the linear solver is emotionally attached to your ST, that's just how it is ๐Ÿฅฒ

Collective.

Returns The linear solver object.

Return type petsc4py.PETSc.KSP โ€” https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.KSP.html#petsc4py.PETSc.KSP

:sources: Source code at slepc4py/SLEPc/ST.pyx:585 <slepc4py/SLEPc/ST.pyx#L585>

getMatMode()

Okay so you wanna know how the matrix is being shifted? Say less. ๐Ÿ’…

Not collective, bestie โ€” every rank does its own lil thing here.

This grabs the flag that tells you how the matrix is being shifted in the shift-and-invert and Cayley spectral transformations. Iconic behavior tbh.

Returns : The mode flag.

Return type : MatMode <#slepc4py.SLEPc.ST.MatMode>

See also: : setMatMode, STGetMatMode โ€” https://slepc.upv.es/release/manualpages/ST/STGetMatMode.html

:sources: Source code at slepc4py/SLEPc/ST.pyx:430 <slepc4py/SLEPc/ST.pyx#L430>

getMatStructure()

Getting the internal matrix structure attribute โœจ

Not collective.

So basically this hands you the internal petsc4py.PETSc.Mat.Structure attribute โ€” https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.Structure.html#petsc4py.PETSc.Mat.Structure โ€” which tells you what the relation is between the sparsity patterns of the matrices. It's giving "are these twins or not" energy. ๐Ÿฆ‹

Returns : The structure flag.

Return type : petsc4py.PETSc.Mat.Structure โ€” https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.Structure.html#petsc4py.PETSc.Mat.Structure

See also: : setMatStructure, STGetMatStructure โ€” https://slepc.upv.es/release/manualpages/ST/STGetMatStructure.html

:sources: Source code at slepc4py/SLEPc/ST.pyx:545 <slepc4py/SLEPc/ST.pyx#L545>

getMatrices()

Grab the matrices associated with the eigenvalue problem ๐Ÿ‘‘

Collective. (So everybody's in on this one, fr fr.)

Returns : The matrices associated with the eigensystem.

Return type : list of petsc4py.PETSc.Mat โ€” https://docs.python.org/3/library/stdtypes.html#list, https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat

See also: : setMatrices, STGetNumMatrices (https://slepc.upv.es/release/manualpages/ST/STGetNumMatrices.html), STGetMatrix (https://slepc.upv.es/release/manualpages/ST/STGetMatrix.html)

:sources: Source code at slepc4py/SLEPc/ST.pyx:486 <slepc4py/SLEPc/ST.pyx#L486>

getOperator()

Get a shell matrix that represents the operator of the spectral transformation. ๐Ÿ”ฅ

Collective.

Returns : Operator matrix.

Return type : petsc4py.PETSc.Mat โ€” https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat

Notes

The operator is defined in linear eigenproblems only โ€” not in polynomial ones. So bestie, if you passed more than 2 matrices in setMatrices(), this call is gonna fail. ๐Ÿ˜ญ Not a vibe, but that's the rules.

The returned shell matrix is essentially a wrapper to the apply() and applyTranspose() operations. The operator can often be expressed as

Op = D K^{-1} M D^{-1}

where D is the balancing matrix, and M and K are two matrices corresponding to the numerator and denominator for spectral transformations that represent a rational matrix function. Math ate, honestly. ๐Ÿ’…

The preconditioner matrix K typically depends on the value of the shift, and its inverse is handled via an internal KSP object. Normal usage does not require explicitly calling getOperator(), but it can be used to force the creation of K and M, and then K is passed to the KSP. This is useful for setting options associated with the PCFactor (to set MUMPS options, for instance). Sneaky but valid. โœจ

The returned matrix must NOT be destroyed by the user. Instead, when no longer needed it must be returned with restoreOperator(). In particular, this is required before modifying the ST matrices or the shift. Do not skip this step, I am begging you. ๐Ÿซถ

See also: : apply, setMatrices, setShift, restoreOperator, STGetOperator โ€” https://slepc.upv.es/release/manualpages/ST/STGetOperator.html

:sources: Source code at slepc4py/SLEPc/ST.pyx:850 <slepc4py/SLEPc/ST.pyx#L850>

getOptionsPrefix()

Get the prefix used for searching for all ST options in the database ๐ŸŽ€

Not collective.

Returns : The prefix string set for this ST object.

Return type : str โ€” https://docs.python.org/3/library/stdtypes.html#str

See also: : setOptionsPrefix, appendOptionsPrefix, STGetOptionsPrefix โ€” https://slepc.upv.es/release/manualpages/ST/STGetOptionsPrefix.html

:sources: Source code at slepc4py/SLEPc/ST.pyx:237 <slepc4py/SLEPc/ST.pyx#L237>

getPreconditionerMat()

Get the matrix that was previously set by setPreconditionerMat(). Blast from the past, lowkey. ๐Ÿ•ฐ๏ธ

Not collective.

Returns : The matrix that will be used in constructing the preconditioner.

Return type : petsc4py.PETSc.Mat โ€” https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat

See also: : setPreconditionerMat, STGetPreconditionerMat โ€” https://slepc.upv.es/release/manualpages/ST/STGetPreconditionerMat.html

:sources: Source code at slepc4py/SLEPc/ST.pyx:649 <slepc4py/SLEPc/ST.pyx#L649>

getShift()

Get the shift associated with the spectral transformation ๐ŸŒธ

Not collective.

Returns : The value of the shift.

Return type : Scalar <#slepc4py.typing.Scalar>

See also: : setShift, STGetShift โ€” https://slepc.upv.es/release/manualpages/ST/STGetShift.html

:sources: Source code at slepc4py/SLEPc/ST.pyx:323 <slepc4py/SLEPc/ST.pyx#L323>

getSplitPreconditioner()

Get the matrices to be used to build the preconditioner. Teamwork makes the dream work, periodt. ๐Ÿ’œ

Not collective.

Returns

Return type : tuple[list[petsc4py.PETSc.Mat], petsc4py.PETSc.Mat.Structure] โ€” https://docs.python.org/3/library/stdtypes.html#tuple, https://docs.python.org/3/library/stdtypes.html#list, https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat, https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.Structure.html#petsc4py.PETSc.Mat.Structure

See also: : STGetSplitPreconditionerInfo (https://slepc.upv.es/release/manualpages/ST/STGetSplitPreconditionerInfo.html), STGetSplitPreconditionerTerm (https://slepc.upv.es/release/manualpages/ST/STGetSplitPreconditionerTerm.html)

:sources: Source code at slepc4py/SLEPc/ST.pyx:716 <slepc4py/SLEPc/ST.pyx#L716>

getTransform()

Get the flag indicating whether the transformed matrices are computed or not. Vibes = transformed? or not? ๐Ÿ™ˆ

Not collective.

Returns : This flag is intended for the case of polynomial eigenproblems solved via linearization. If this flag is False (default) the spectral transformation is applied to the linearization (handled by the eigensolver), otherwise it is applied to the original problem.

Return type : bool โ€” https://docs.python.org/3/library/functions.html#bool

See also: : setTransform, STGetTransform โ€” https://slepc.upv.es/release/manualpages/ST/STGetTransform.html

:sources: Source code at slepc4py/SLEPc/ST.pyx:364 <slepc4py/SLEPc/ST.pyx#L364>

getType()

Get the ST type of this object. Identity check but for transforms, iykyk. ๐Ÿงš

Not collective.

Returns : The spectral transformation currently being used.

Return type : str โ€” https://docs.python.org/3/library/stdtypes.html#str

See also: : setType, STGetType โ€” https://slepc.upv.es/release/manualpages/ST/STGetType.html

:sources: Source code at slepc4py/SLEPc/ST.pyx:193 <slepc4py/SLEPc/ST.pyx#L193>

reset()

Reset the ST object. Clean slate, fresh start, main character rebrand energy. ๐Ÿฆ‹โœจ

Collective.

See also: : STReset โ€” https://slepc.upv.es/release/manualpages/ST/STReset.html

:sources: Source code at slepc4py/SLEPc/ST.pyx:133 <slepc4py/SLEPc/ST.pyx#L133>

Return type : None โ€” https://docs.python.org/3/library/constants.html#None

restoreOperator(op)

Hand that operator matrix back, bestie โ€” you're done borrowing it. ๐Ÿ’… It's the reverse of getOperator().

Logically collective โ€” so everybody in the communicator's gotta show up for it. ๐Ÿซถ

Parameters

  • op (Mat) โ€” the operator matrix you picked up earlier with getOperator().

Return type: None

See also: getOperator, STRestoreOperator

Source: slepc4py/SLEPc/ST.pyx:898

setCayleyAntishift(mu)

Sets the anti-shift value for the Cayley spectral transformation. So demure, so mindful. โœจ

Logically collective.

Parameters

  • mu (Scalar) โ€” the anti-shift.

Return type: None

Notes

In the generalized Cayley transform, the operator can be expressed as (A - \sigma B)^{-1}(A + \mu B). This function sets the value of mu. Use setShift() for setting \sigma. ๐Ÿ™ˆ

See also: setShift, getCayleyAntishift, STCayleySetAntishift

Source: slepc4py/SLEPc/ST.pyx:918

setFilterDamping(damping)

Tells the polynomial filter which flavour of damping to use. ๐Ÿ“

Logically collective.

Parameter

  • damping โ€” the type of damping.

Notes

Only used in FilterType.CHEBYSHEV filters โ€” like, this one's literally for the Chebyshev girlies only. ๐Ÿ‘‘

See also: getFilterDamping, STFilterSetDamping

Source: slepc4py/SLEPc/ST.pyx:1142

Parameters

  • damping (FilterDamping)

Return type: None

setFilterDegree(deg)

Sets the degree of the filter polynomial. Higher degree = more work, so pick your battles bestie. ๐Ÿ’€

Logically collective.

Parameters

  • deg (int) โ€” the polynomial degree.

Return type: None

See also: getFilterDegree, STFilterSetDegree

Source: slepc4py/SLEPc/ST.pyx:1105

setFilterInterval(inta, intb)

Sets the interval that holds the eigenvalues you actually want. Main character eigenvalues only, no gatecrashers. ๐ŸŽ€

Logically collective.

Parameters

  • inta (float) โ€” the left end of the interval.
  • intb (float) โ€” the right end of the interval.

Return type: None

Notes

The filter gets configured to emphasize eigenvalues inside the given interval and damp out the ones outside it. If the interval is open, then the filter is low- or high-pass; otherwise it's mid-pass. ๐ŸŒˆ

Common usage is to set the interval in EPS with EPS.setInterval().

The interval must be contained within the numerical range of the matrix โ€” peep setFilterRange(). โš ๏ธ

See also: getFilterInterval, setFilterRange, STFilterSetInterval

Source: slepc4py/SLEPc/ST.pyx:998

setFilterRange(left, right)

Sets the numerical range (or field of values) of the matrix. It's givingโ€ฆ vibes, but make them mathematical. ๐Ÿ’œ

Logically collective.

Sets the numerical range (or field of values) of the matrix, that is, the interval containing all eigenvalues.

Parameters

  • left (float) โ€” the left end of the spectral range.
  • right (float) โ€” the right end of the spectral range.

Return type: None

Notes

The filter is most effective when the numerical range is tight โ€” i.e., left and right are good approximations to the leftmost and rightmost eigenvalues respectively. No cap. ๐Ÿ”ฅ

See also: setFilterInterval, getFilterRange, STFilterSetRange

Source: slepc4py/SLEPc/ST.pyx:1053

setFilterType(filter_type)

Picks the method used to build the polynomial filter. Choose your fighter. โญ

Logically collective.

Parameter

  • filter_type โ€” the type of filter.

See also: getFilterType, STFilterSetType

Source: slepc4py/SLEPc/ST.pyx:961

Parameters

  • filter_type (FilterType)

Return type: None

setFromOptions()

Reads all the ST options straight outta the options database. Iconic. โœจ

Collective.

Notes

To see all the 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, STSetFromOptions

Source: slepc4py/SLEPc/ST.pyx:275

Return type: None

setKSP(ksp)

Attaches the KSP object that's gonna hang with this spectral transformation. ๐Ÿฆ‹

Collective.

Parameters

  • ksp (KSP) โ€” the linear solver object.

Return type: None

See also: getKSP, STSetKSP

Source: slepc4py/SLEPc/ST.pyx:568

setMatMode(mode)

Sets a flag about how the transformed matrices get managed. This one's lowkey important, so pay attention bestie. ๐Ÿ‘‘

Logically collective.

The flag indicates how the transformed matrices are being stored in the spectral transformation.

Parameters

  • mode (MatMode) โ€” the mode flag.

Return type: None

Notes

By default (ST.MatMode.COPY), a copy of matrix A is made and then this copy is modified explicitly, e.g., A \leftarrow (A - \sigma B).

With ST.MatMode.INPLACE, the original matrix A is modified at setUp() and reverted at the end of the computations. Compared to the previous one, this mode avoids a copy of matrix A. However โ€” a backdraw is that the recovered matrix might be slightly different from the original one (due to roundoff). ๐Ÿ˜ญ So like, be aware.

With ST.MatMode.SHELL, the solver works with an implicit shell matrix that represents the shifted matrix. This mode is the most efficient at creating the transformed matrix, but it places serious limitations to the linear solves performed in each iteration of the eigensolver (typically, only iterative solvers with Jacobi preconditioning can be used). ๐Ÿ’€

In the two first modes, the efficiency of this computation can be controlled with setMatStructure().

See also: setMatrices, setMatStructure, getMatMode, STSetMatMode

Source: slepc4py/SLEPc/ST.pyx:387

setMatStructure(structure)

Sets the matrix structure attribute. ๐ŸŒธ

Logically collective.

Set an internal petsc4py.PETSc.Mat.Structure attribute so SLEPc knows how the sparsity patterns of all your ST matrices relate to each other ๐Ÿ’…

Parameters

  • structure (petsc4py.PETSc.Mat.Structure) โ€” The matrix structure specification โœจ

Return type

None

Notes

Okay so by default, everybody assumes the sparsity patterns are all different. But if they're actually equal, or one's a subset of another, bestie you GOTTA set this attribute โ€” it's for efficiency reasons, and specifically for internal Mat.axpy() operations ๐Ÿ”ฅ

This function literally does nothing in the case of standard eigenproblems (ngl, no effect whatsoever) ๐Ÿ™ˆ

In case of polynomial eigenproblems, the flag applies to all matrices relative to the first one.

See also:

getMatStructure, setMatrices, STSetMatStructure

:sources:Source code at slepc4py/SLEPc/ST.pyx:512

setMatrices(operators)

Set the matrices associated with the eigenvalue problem ๐ŸŽ€

Collective.

Parameters

  • operators (list[Mat]) โ€” The matrices associated with the eigensystem.

Return type

None

Notes

It must be called before setUp(). And if you call it again after setUp(), then the ST object is reset. (so like. be aware.)

In standard eigenproblems only one matrix is passed, while in generalized problems two matrices are provided. The number of matrices is larger in polynomial eigenproblems.

In normal usage, matrices are provided via the corresponding EPS of PEP interface function. iykyk ๐Ÿ’–

See also:

getMatrices, setUp, reset, STSetMatrices

:sources:Source code at slepc4py/SLEPc/ST.pyx:452

setOptionsPrefix(prefix=None)

Set the prefix used for searching for all ST options in the database ๐ŸŒธ

Logically collective.

Parameters

  • prefix (str | None) โ€” The prefix string to prepend to all ST 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. so do not do that, okay bestie โœ‹

See also:

appendOptionsPrefix, getOptionsPrefix, STGetOptionsPrefix

:sources:Source code at slepc4py/SLEPc/ST.pyx:212

setPreconditionerMat(P=None)

Set the matrix to be used to build the preconditioner ๐Ÿงš

Collective.

Parameters

  • P (Mat | None) โ€” The matrix that will be used in constructing the preconditioner.

Return type

None

Notes

This matrix gets passed to the internal KSP object (via the last argument of KSP.setOperators()) as the matrix to be used when constructing the preconditioner. If no matrix is set then A-\sigma B will be used to build the preconditioner, being \sigma the value set by setShift(). ๐Ÿซถ

More precisely: this is relevant for spectral transformations that represent a rational matrix function, and use a KSP object for the denominator. It includes also the PRECOND case. So if you've got a good approximation to the matrix that can be used to build a cheap preconditioner, pass it with this function. Note that it affects only the Pmat argument of KSP.setOperators(), not the Amat argument. lowkey important, bestie ๐Ÿ’…

If a preconditioner matrix is set, the default is to use an iterative KSP rather than a direct method.

An alternative to pass an approximation of A-\sigma B with this function is to provide approximations of A and B via setSplitPreconditioner(). The difference is that when \sigma changes the preconditioner is recomputed. โญ

A call with no matrix argument will remove a previously set matrix. bye felicia ๐Ÿ‘‹

See also:

getPreconditionerMat, STSetPreconditionerMat

:sources:Source code at slepc4py/SLEPc/ST.pyx:605

setShift(shift)

Set the shift associated with the spectral transformation โœจ

Collective.

Parameters

  • shift (Scalar) โ€” The value of the shift.

Return type

None

Notes

In some spectral transformations, changing the shift may have associated a lot of work, for example recomputing a factorization. ๐Ÿ’€ like, a LOT a lot.

This function is normally not directly called by users, since the shift is indirectly set by EPS.setTarget(). so hands off, it's giving main character energy behind the scenes

See also:

getShift, STSetShift

:sources:Source code at slepc4py/SLEPc/ST.pyx:296

setSplitPreconditioner(operators, structure=None)

Set the matrices to be used to build the preconditioner ๐Ÿ’œ

Collective.

Parameters

  • operators (list[petsc4py.PETSc.Mat]) โ€” The matrices associated with the preconditioner.
  • structure (petsc4py.PETSc.Mat.Structure | None) โ€” The matrix structure specification.

Return type

None

Notes

The number of matrices passed here must be the same as in setMatrices(). no cap, fr fr ๐Ÿ™ˆ

For linear eigenproblems, the preconditioner matrix is computed as P(\sigma) = A_0-\sigma B_0, where A_0,B_0 are approximations of A,B (the eigenproblem matrices) provided via the operators argument in this function. Compared to setPreconditionerMat(), this function allows setting a preconditioner in a way that is independent of the shift \sigma. Whenever the value of \sigma changes the preconditioner is recomputed. ๐Ÿ”ฅ

Similarly, for polynomial eigenproblems the matrix for the preconditioner is expressed as P(\sigma) = \sum_i P_i \phi_i(\sigma), for i=1,\dots,n, where P_i are given in operators and the \phi_i's are the polynomial basis functions. ๐ŸŒˆ

The structure flag provides information about the relative nonzero pattern of the operators matrices, in the same way as in setMatStructure().

See also:

getSplitPreconditioner, setPreconditionerMat, STSetSplitPreconditioner

:sources:Source code at slepc4py/SLEPc/ST.pyx:669

setTransform(flag=True)

Set a flag to indicate whether the transformed matrices are computed or not ๐ŸŽ€

Logically collective.

Parameters

  • flag (bool) โ€” This flag is intended for the case of polynomial eigenproblems solved via linearization. If this flag is False (default) the spectral transformation is applied to the linearization (handled by the eigensolver), otherwise it is applied to the original problem. ๐Ÿ‘‘

Return type is None, bestie โ€” that's it, nothing comes back at you. โœจ

See also: getTransform, STSetTransform (link: https://slepc.upv.es/release/manualpages/ST/STSetTransform.html)

:sources:Source code at slepc4py/SLEPc/ST.pyx:342 <slepc4py/SLEPc/ST.pyx#L342>``

setType(st_type) ๐Ÿ’ซ

Sets which specific spectral transformation is gonna be used. Like picking your outfit for the day, but for matrices.

Logically collective โ€” so everybody in the crew needs to be on the same page.

Parameters:

Return type: None (https://docs.python.org/3/library/constants.html#None)

Notes ๐Ÿ“

The default is SHIFT (#slepc4py.SLEPc.ST.Type.SHIFT) with a zero shift. Normally, it is best to use setFromOptions() and then set the ST type from the options database rather than by using this routine. Like, why lock yourself in? Using the options database gives the user maximum flexibility in evaluating the different available methods. Flexibility is the vibe, periodt.

See also: getType, STSetType (link: https://slepc.upv.es/release/manualpages/ST/STSetType.html)

:sources:Source code at slepc4py/SLEPc/ST.pyx:166 <slepc4py/SLEPc/ST.pyx#L166>``

setUp() ๐Ÿ› ๏ธ

Prepares for the use of a spectral transformation. Setting the stage, applying your primer, getting ready for the main character moment.

Collective.

See also: apply, STSetUp (link: https://slepc.upv.es/release/manualpages/ST/STSetUp.html)

:sources:Source code at slepc4py/SLEPc/ST.pyx:746 <slepc4py/SLEPc/ST.pyx#L746>``

Return type: None (https://docs.python.org/3/library/constants.html#None)

view(viewer=None) ๐Ÿ‘€

Prints out the ST data structure. Like holding your phone up to the mirror โ€” let's see what we're working with.

Collective.

Parameters:

Return type: None (https://docs.python.org/3/library/constants.html#None)

See also: STView (link: https://slepc.upv.es/release/manualpages/ST/STView.html)

:sources:Source code at slepc4py/SLEPc/ST.pyx:100 <slepc4py/SLEPc/ST.pyx#L100>``

Attributes Documentation ๐Ÿ’–

ksp

KSP object associated with the spectral transformation. Yep, they're linked, they're a package deal. ๐Ÿซถ

:sources:Source code at slepc4py/SLEPc/ST.pyx:1213 <slepc4py/SLEPc/ST.pyx#L1213>``

mat_mode

How the transformed matrices are being stored in the ST. Storage choices, very demure, very mindful.

:sources:Source code at slepc4py/SLEPc/ST.pyx:1199 <slepc4py/SLEPc/ST.pyx#L1199>``

mat_structure

Relation of the sparsity pattern of all ST matrices. Like, how are the zeros arranged, bestie.

:sources:Source code at slepc4py/SLEPc/ST.pyx:1206 <slepc4py/SLEPc/ST.pyx#L1206>``

shift

Value of the shift. The shift itself, the moment, the icon. โœจ

:sources:Source code at slepc4py/SLEPc/ST.pyx:1185 <slepc4py/SLEPc/ST.pyx#L1185>``

transform

If the transformed matrices are computed. A yes/no situation.

:sources:Source code at slepc4py/SLEPc/ST.pyx:1192 <slepc4py/SLEPc/ST.pyx#L1192>``

__init__()

classmethod __new__(*args, **kwargs)

๐ŸŒˆ slepc4py.SLEPc.SVD

class slepc4py.SLEPc.SVD

Bases: Object (https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Object.html#petsc4py.PETSc.Object)

Singular Value Decomposition Solver. ๐Ÿ‘‘

The Singular Value Decomposition Solver (SVD) is very similar to the EPS (#slepc4py.SLEPc.EPS) object, but intended for the computation of the partial SVD of a rectangular matrix. Yes, rectangular, not just square โ€” she contains multitudes. 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 (#slepc4py.SLEPc.EPS) eigensolvers. Reusing the fit, we love to see it. ๐Ÿ’…

Enumerations

  • Conv (#slepc4py.SLEPc.SVD.Conv) โ€” SVD convergence test.
  • ConvergedReason (#slepc4py.SLEPc.SVD.ConvergedReason) โ€” SVD convergence reasons.
  • ErrorType (#slepc4py.SLEPc.SVD.ErrorType) โ€” SVD error type to assess accuracy of computed solutions.
  • ProblemType (#slepc4py.SLEPc.SVD.ProblemType) โ€” SVD problem type.
  • Stop (#slepc4py.SLEPc.SVD.Stop) โ€” SVD stopping test.
  • TRLanczosGBidiag (#slepc4py.SLEPc.SVD.TRLanczosGBidiag) โ€” SVD TRLanczos bidiagonalization choices for the GSVD case.
  • Type (#slepc4py.SLEPc.SVD.Type) โ€” SVD type.
  • Which (#slepc4py.SLEPc.SVD.Which) โ€” SVD desired part of spectrum.

๐Ÿฆ‹ slepc4py.SLEPc.SVD.Conv

class slepc4py.SLEPc.SVD.Conv

Bases: object (https://docs.python.org/3/library/functions.html#object)

SVD convergence test. How do we know when to stop? She tells us. ๐ŸŽ€

  • ABS: Absolute convergence test.
  • REL: Convergence test relative to the singular value.
  • NORM: Convergence test relative to the matrix norms.
  • MAXIT: No convergence until maximum number of iterations has been reached. ๐Ÿ’€
  • USER: User-defined convergence test. Your rules, your world, bestie.

See also: SVDConv (link: https://slepc.upv.es/release/manualpages/SVD/SVDConv.html)

Attributes Summary

Attributes Documentation

ABS: int = ABS

Constant ABS of type int (https://docs.python.org/3/library/functions.html#int)

class slepc4py.SLEPc.SVD.ConvergedReason ๐Ÿ’–

okay bestie, sit down, this one's got lore. ๐Ÿ‘‘

class slepc4py.SLEPc.SVD.ConvergedReason

Bases: object <https://docs.python.org/3/library/functions.html#object>

SVD convergence reasons. Basically: the little report card your SVD solver hands back so you know how it went. ๐ŸŽ€

  • CONVERGED_TOL: All eigenpairs converged to requested tolerance.
  • CONVERGED_USER: User-defined convergence criterion satisfied.
  • CONVERGED_MAXIT: Maximum iterations completed in case MAXIT convergence criterion.
  • DIVERGED_ITS: Maximum number of iterations exceeded.
  • DIVERGED_BREAKDOWN: Solver failed due to breakdown.
  • DIVERGED_SYMMETRY_LOST: Underlying indefinite eigensolver was not able to keep symmetry.
  • CONVERGED_ITERATING: Iteration not finished yet.

See also:

SVDConvergedReason <https://slepc.upv.es/release/manualpages/SVD/SVDConvergedReason.html>

Attributes Summary ๐ŸŒธ

no cap, peep that ITERATING up top vs CONVERGED_ITERATING in the reasons list โ€” they're both here, exactly like that, and I'm not about to "fix" it for u ๐Ÿ’…

Attributes Documentation ๐Ÿฆ‹

class slepc4py.SLEPc.SVD.ErrorType โœจ

class slepc4py.SLEPc.SVD.ErrorType

Bases: object <https://docs.python.org/3/library/functions.html#object>

SVD error type to assess accuracy of computed solutions. like, how close did we actually get? vibe check on ur answer. ๐Ÿซถ

  • ABSOLUTE: Absolute error.
  • RELATIVE: Relative error.
  • NORM: Error relative to the matrix norm.

See also:

SVDErrorType <https://slepc.upv.es/release/manualpages/SVD/SVDErrorType.html>

Attributes Summary ๐ŸŒˆ

Attributes Documentation ๐Ÿ’œ

Quick heads-up before we go any further, bestie: every single "type int" in this whole stretch of the docs points at https://docs.python.org/3/library/functions.html#int โ€” yes, it's just Python's int, we been knew ๐Ÿ˜ญ, but the docs link it every. single. time. Iconic commitment to thoroughness honestly.

  • __init__() โ€” the constructor, doing its little thing ๐ŸŽ€
  • classmethod __new__(*args, **kwargs) โ€” takes *args, **kwargs, and is a classmethod ๐Ÿ’…

class slepc4py.SLEPc.SVD.ProblemType

Bases: object โ€” that Python object link again: https://docs.python.org/3/library/functions.html#object

SVD problem type. Like, which flavor of singular value problem are we even solving?? Let's get into it ๐Ÿฆ‹

  • STANDARD: Standard SVD.
  • GENERALIZED: Generalized singular value decomposition (GSVD).
  • HYPERBOLIC: Hyperbolic singular value decomposition (HSVD).
See also: SVDProblemType โ€” https://slepc.upv.es/release/manualpages/SVD/SVDProblemType.html

Attributes Summary

  • GENERALIZED โ€” Constant GENERALIZED of type int
  • HYPERBOLIC โ€” Constant HYPERBOLIC of type int
  • STANDARD โ€” Constant STANDARD of type int

Attributes Documentation

  • GENERALIZED: int = GENERALIZED โ€” Constant GENERALIZED of type int
  • HYPERBOLIC: int = HYPERBOLIC โ€” Constant HYPERBOLIC of type int
  • STANDARD: int = STANDARD โ€” Constant STANDARD of type int

(and yes the summary is literally the same list as the documentation, SLEPc said why not do it twice ๐Ÿ’€ we respect the hustle)

  • __init__()
  • classmethod __new__(*args, **kwargs)

class slepc4py.SLEPc.SVD.Stop

Bases: object

SVD stopping test. i.e. when do we decide we've done enough and stop iterating, the eternal question fr fr ๐ŸŒธ

  • BASIC: Default stopping test.
  • USER: User-defined stopping test.
  • THRESHOLD: Threshold stopping test.
See also: SVDStop โ€” https://slepc.upv.es/release/manualpages/SVD/SVDStop.html

Attributes Summary

  • BASIC โ€” Constant BASIC of type int
  • THRESHOLD โ€” Constant THRESHOLD of type int
  • USER โ€” Constant USER of type int

Attributes Documentation

  • BASIC: int = BASIC โ€” Constant BASIC of type int
  • THRESHOLD: int = THRESHOLD โ€” Constant THRESHOLD of type int
  • USER: int = USER โ€” Constant USER of type int
  • __init__()
  • classmethod __new__(*args, **kwargs)

class slepc4py.SLEPc.SVD.TRLanczosGBidiag

Bases: object

SVD TRLanczos bidiagonalization choices for the GSVD case. Okay this one is lowkey the most specific vibe in the whole file โ€” it's literally about which matrices get bidiagonalized and in which direction for the generalized case ๐Ÿ‘‘

  • SINGLE: Single bidiagonalization (Q_A).
  • UPPER: Joint bidiagonalization, both Q_A and Q_B in upper bidiagonal form.
  • LOWER: Joint bidiagonalization, Q_A lower bidiagonal, Q_B upper bidiagonal.
See also: SVDTRLanczosGBidiag โ€” https://slepc.upv.es/release/manualpages/SVD/SVDTRLanczosGBidiag.html

Attributes Summary

  • LOWER โ€” Constant LOWER of type int
  • SINGLE โ€” Constant SINGLE of type int
  • UPPER โ€” Constant UPPER of type int

Attributes Documentation

  • LOWER: int = LOWER โ€” Constant LOWER of type int
  • SINGLE: int = SINGLE โ€” Constant SINGLE of type int
  • UPPER: int = UPPER โ€” Constant UPPER of type int
  • __init__()
  • classmethod __new__(*args, **kwargs)

class slepc4py.SLEPc.SVD.Type

Bases: object

SVD type. The main character of the whole SVD menu, honestly โ€” this is where you pick which solver algorithm you're rolling with ๐Ÿ”ฅ

Native singular value solvers.

  • CROSS: Eigenproblem with the cross-product matrix.
  • CYCLIC: Eigenproblem with the cyclic matrix.
  • LANCZOS: Explicitly restarted Lanczos.
  • TRLANCZOS: Thick-restart Lanczos.
  • RANDOMIZED: Iterative RSVD for low-rank matrices.

Wrappers to external SVD solvers โ€” note bestie, these should be enabled during installation of SLEPc, so if they're not showing up for you that's an install-time situation, not a you problem ๐Ÿ™ˆ

  • LAPACK: Sequential dense SVD solver.
  • SCALAPACK: Parallel dense SVD solver.
  • KSVD: Parallel dense SVD solver.
  • ELEMENTAL: Parallel dense SVD solver.
  • PRIMME: Iterative SVD solvers of Davidson type.
See also: SVDType โ€” https://slepc.upv.es/release/manualpages/SVD/SVDType.html

โœจ Attributes Summary โœจ

okay bestie, here's the tea on all the SVD attribute constants ๐Ÿ’… they're all str objects, no cap. each one links to the Python docs for str if you wanna deep dive (iykyk).

๐Ÿ’… Attributes Documentation ๐Ÿ’…

now the full receipts, bestie. each attribute gets its own little moment. ๐Ÿ’–

CROSS: str = CROSS

Object CROSS of type str (link: https://docs.python.org/3/library/stdtypes.html#str)

CYCLIC: str = CYCLIC

Object CYCLIC of type str (link: https://docs.python.org/3/library/stdtypes.html#str)

ELEMENTAL: str = ELEMENTAL

Object ELEMENTAL of type str (link: https://docs.python.org/3/library/stdtypes.html#str)

KSVD: str = KSVD

Object KSVD of type str (link: https://docs.python.org/3/library/stdtypes.html#str)

LANCZOS: str = LANCZOS

Object LANCZOS of type str (link: https://docs.python.org/3/library/stdtypes.html#str)

LAPACK: str = LAPACK

Object LAPACK of type str (link: https://docs.python.org/3/library/stdtypes.html#str)

PRIMME: str = PRIMME

Object PRIMME of type str (link: https://docs.python.org/3/library/stdtypes.html#str)

RANDOMIZED: str = RANDOMIZED

Object RANDOMIZED of type str (link: https://docs.python.org/3/library/stdtypes.html#str)

SCALAPACK: str = SCALAPACK

Object SCALAPACK of type str (link: https://docs.python.org/3/library/stdtypes.html#str)

TRLANCZOS: str = TRLANCZOS

Object TRLANCZOS of type str (link: https://docs.python.org/3/library/stdtypes.html#str)

__init__()

classmethod __new__(*args, **kwargs)

๐Ÿ‘‘ slepc4py.SLEPc.SVD.Which ๐Ÿ‘‘

class slepc4py.SLEPc.SVD.Which

Bases: object (link: https://docs.python.org/3/library/functions.html#object)

SVD desired part of spectrum.

  • LARGEST: Largest singular values.
  • SMALLEST: Smallest singular values.

See also: SVDWhich (link: https://slepc.upv.es/release/manualpages/SVD/SVDWhich.html)

โœจ Attributes Summary โœจ

๐Ÿ’… Attributes Documentation ๐Ÿ’…

LARGEST: int = LARGEST

Constant LARGEST of type int (link: https://docs.python.org/3/library/functions.html#int)

SMALLEST: int = SMALLEST

Constant SMALLEST of type int (link: https://docs.python.org/3/library/functions.html#int)

__init__()

classmethod __new__(*args, **kwargs)

  • appendOptionsPrefix([prefix]) โ€” tack more onto the prefix that's used when hunting down every single SVD option in the database ๐ŸŽ€
  • cancelMonitor() โ€” wipes all the monitors for an SVD object, gone, bye ๐Ÿ’…
  • computeError(i[, etype]) โ€” crunches the error that goes with the i-th singular triplet ๐Ÿ“
  • create([comm]) โ€” make the SVD object exist, bestie โœจ
  • destroy() โ€” and now unmake it, rip ๐Ÿซถ
  • errorView([etype, viewer]) โ€” pop the errors for the computed solution up on screen ๐Ÿ‘€
  • getBV() โ€” hand over the basis vectors objects that are attached to the SVD object ๐Ÿฆ‹
  • getConverged() โ€” how many singular triplets actually converged, the number we all care about ๐Ÿ‘‘
  • getConvergedReason() โ€” the tea on why the solve() iteration stopped, like what happened ๐Ÿ˜ญ
  • getConvergenceTest() โ€” which method is being used to compute the error estimate that feeds the convergence test ๐Ÿงš
  • getCrossEPS() โ€” get the eigensolver object tied to the singular value solver ๐ŸŒธ
  • getCrossExplicitMatrix() โ€” get the flag that says whether A^*A is built explicitly, like actually constructed โญ
  • getCyclicEPS() โ€” get the eigensolver object tied to the singular value solver (yes, again, it's a different one) ๐Ÿ’œ
  • getCyclicExplicitMatrix() โ€” get the flag that says whether H(A) is built explicitly ๐Ÿ”ฅ
  • getDS() โ€” get the direct solver attached to the singular value solver, the whole support system fr fr ๐Ÿ’–
  • getDimensions() โ€” how many singular values we're computing, plus the dimension of the subspace ๐ŸŽ€
  • getImplicitTranspose() โ€” the mode used to handle the transpose of the associated matrix, iconic behaviour ๐ŸŒˆ
  • getIterationNumber() โ€” what iteration are we on right now, the current count ๐Ÿ’ซ
  • getLanczosOneSide() โ€” tells you if the variant of the Lanczos method in play is one-sided or two-sided ๐Ÿ‘‘
  • getMonitor() โ€” get the list of monitor functions, the lil watch party โœจ
  • 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() โ€” pulls the problem type straight out of the SVD object ๐Ÿ“
  • getSignature([omega]) โ€” get the signature matrix that defines a hyperbolic singular value problem, fancy ๐Ÿงš
  • getSingularTriplet(i[, U, V]) โ€” get the i-th triplet of the singular value decomposition, the main character of your solve ๐Ÿ˜Œ
  • getStoppingTest() โ€” get the stopping test function ๐Ÿ’œ
  • getTRLanczosExplicitMatrix() โ€” get the flag indicating if Z=[A^*,B^*]^* is builtโ€ฆ

and we're literally mid-sentence here, the list keeps going, hold on bestie ๐Ÿ’–

  • getTRLanczosGBidiag() โ€” grabs the bidiagonalization choice that the GSVD TRLanczos solver is using. peak config inspection vibes โœจ
  • getTRLanczosKSP() โ€” hands you the linear solver object that's tied to the SVD solver. iykyk ๐Ÿซถ
  • getTRLanczosLocking() โ€” tells you the locking flag situation in the thick-restart Lanczos method. locked in, literally ๐Ÿ’…
  • getTRLanczosOneSide() โ€” checks whether the method variant you're running is one-sided or two-sided. bestie pick a side ๐Ÿ˜ญ
  • getTRLanczosRestart() โ€” returns the restart parameter used by the thick-restart Lanczos method. the restart era ๐Ÿ”„
  • getThreshold() โ€” gives you the threshold value that the threshold stopping test is vibing on. set your bar, queen</peak> ๐ŸŽ€
  • getTolerances() โ€” pulls the tolerance and the maximum iteration count, both at once. two-for-one deal fr fr ๐Ÿ’–
  • getTrackAll() โ€” returns the flag that says whether all residual norms must be computed or not. all of them, or none ๐Ÿ‘‘
  • getType() โ€” gets the SVD type of this object. identity crisis resolved ๐ŸŒˆ
  • getValue(i) โ€” snags the i-th singular value, as computed by solve(). math but make it cute ๐Ÿ“
  • getVectors(i, U, V) โ€” grabs the i-th left and right singular vectors, exactly as computed by solve(). both sides of the story ๐Ÿฆ‹
  • getWhichSingularTriplets() โ€” reveals which singular triplets are being sought. manifesting specific triplets โญ
  • isGeneralized() โ€” tells you if the SVD corresponds to a generalized singular value problem. is it generalized? bestie let's find out ๐Ÿ’œ
  • isHyperbolic() โ€” tells you whether the SVD object corresponds to a hyperbolic singular value problem. hyperbolic behavior, honestly ๐ŸŒธ
  • reset() โ€” resets the SVD object. clean slate, fresh start ๐Ÿงš
  • setBV(V[, U]) โ€” sets the basis vectors objects associated to the SVD solver. U is optional, V is the moment โœจ
  • setConvergenceTest(conv) โ€” sets up how the error estimate gets computed for the convergence test. deciding your standards ๐Ÿ’…
  • setCrossEPS(eps) โ€” attaches an eigensolver object to the singular value solver. friend request accepted ๐Ÿซถ
  • setCrossExplicitMatrix([flag]) โ€” sets whether the eigensolver operator A^*A has to be computed. that's A^*A, not a typo, bestie ๐Ÿ’–
  • setCyclicEPS(eps) โ€” attaches an eigensolver object to the singular value solver. same energy, different method ๐Ÿ”ฅ
  • setCyclicExplicitMatrix([flag]) โ€” sets whether the eigensolver operator H(A) gets computed explicitly. spelled out, no shortcuts โญ
  • setDS(ds) โ€” sets a direct solver object associated to the singular value solver. direct solver, direct communication ๐ŸŒˆ
  • setDimensions([nsv, ncv, mpd]) โ€” sets how many singular values to compute and how big the subspace is. all the numbers are optional, slay ๐ŸŽ€
  • setFromOptions() โ€” sets the SVD options straight from the options database. let the command line speak ๐Ÿ‘‘
  • setImplicitTranspose(mode) โ€” sets how the transpose of the associated matrix gets handled. transpose drama, handled ๐Ÿฆ‹
  • setInitialSpace([spaceright, โ€” sets the initial spacesโ€ฆ and bestie the rest of this one is coming in the next part, don't come for me ๐Ÿ˜ญ๐Ÿ’€
  • setLanczosOneSide([flag]) โ€” says whether the Lanczos variant you're running is one-sided or two-sided. that's it, that's the whole job ๐Ÿ’…
  • setMonitor(monitor[, args, kargs]) โ€” tacks a monitor function onto the end of the monitors list. you can pass extra args and kargs along for the ride ๐Ÿซถ
  • setOperators(A[, B]) โ€” hands over the matrices that belong to the singular value problem. B is optional, A is not โœจ
  • setOptionsPrefix([prefix]) โ€” sets the prefix that's used when hunting down all the SVD options in the database ๐Ÿ”
  • setProblemType(problem_type) โ€” tells it which flavor of singular value problem you're dealing with, periodt.
  • setSignature([omega]) โ€” sets the signature matrix that defines a hyperbolic singular value problem. fancy, we know ๐Ÿ’œ
  • setStoppingTest(stopping[, args, kargs]) โ€” installs a function whose whole main character job is deciding when the outer iteration of the eigensolver should stop โœ‹ with optional args and kargs ๐Ÿ’–
  • setTRLanczosExplicitMatrix([flag]) โ€” decides whether the matrix Z=[A^*,B^*]^* has to be built explicitly or not ๐Ÿงฑ
  • setTRLanczosGBidiag(bidiag) โ€” picks the bidiagonalization choice for the GSVD TRLanczos solver to use ๐ŸŽ€
  • setTRLanczosKSP(ksp) โ€” attaches a linear solver object to the SVD solver. matching sets fr fr ๐Ÿซถ
  • setTRLanczosLocking(lock) โ€” toggles between the locking and non-locking variants of TRLanczos ๐Ÿ”’โ†”๏ธ๐Ÿ”“
  • setTRLanczosOneSide([flag]) โ€” same energy as the Lanczos one: is the variant of the method one-sided or two-sided? ๐Ÿ‘€
  • setTRLanczosRestart(keep) โ€” sets the restart parameter for the thick-restart Lanczos method. it's giving "keep what matters" ๐Ÿ”ฅ
  • setThreshold(thres[, rel]) โ€” sets the threshold that the threshold stopping test uses. rel is optional, thres is the whole point โญ
  • setTolerances([tol, max_it]) โ€” sets both the tolerance and the maximum iteration count being used. two for one, slay โœจ
  • setTrackAll(trackall) โ€” sets the flag that makes it compute the residual of all the singular triplets. every single one, no skips ๐Ÿ‘‘
  • setType(svd_type) โ€” locks in which particular solver the SVD object is gonna use ๐Ÿฆ‹
  • setUp() โ€” builds out all the internal data structures. the prep era before the solve era ๐ŸŒธ
  • setWhichSingularTriplets(which) โ€” says which singular triplets are the ones you're actually seeking. be specific bestie ๐ŸŽฏ
  • solve() โ€” solves the singular value problem. that's the moment, that's the whole point ๐Ÿ’–
  • valuesView([viewer]) โ€” shows off the computed singular values inside a viewer ๐Ÿ’…
  • vectorsView([viewer]) โ€” sends the computed singular vectors out to a viewer ๐ŸŽ€
  • view([viewer]) โ€” prints the SVD data structure. just a little peek at the internals ๐Ÿ™ˆ

โœจ Attributes Summary โœจ

okay so these are the attributes you can poke at on an SVD object ๐Ÿ’…

  • ds โ€” the direct solver (DS, aka slepc4py.SLEPc.DS) object that's associated with this whole thing ๐Ÿซถ
  • max_it โ€” the max iteration count, like the patience limit fr
  • problem_type โ€” the type of the eigenvalue problem ๐Ÿ‘‘
  • tol โ€” the tolerance (how close is close enough, bestie)
  • 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, bestie โ€” everyone's in on it โœจ

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 the monitors on an SVD object. Logically collective, periodt ๐Ÿ’…

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, no solo runs here ๐Ÿซ‚

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, and 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. ikyk ๐Ÿ’€

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 you don't hand one over, 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 โ€” say bye bestie ๐Ÿ˜ญ

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 you don't pass one, standard output gets 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. cute little table fr ๐Ÿ“Š

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. Don't jump the gun bestie ๐Ÿซฃ

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

๐ŸŒธ getConvergenceTest()

Gets the method used to compute the error estimate that feeds the convergence test. โœจ

Not collective. (so like, everybody in the MPI crew doesn't have to call it, okay bestie? ๐Ÿซถ)

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

Return type: Conv (that's slepc4py.SLEPc.SVD.Conv ๐Ÿ’–)

See also: setConvergenceTest, SVDGetConvergenceTest โ€” docs live at https://slepc.upv.es/release/manualpages/SVD/SVDGetConvergenceTest.html

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

๐Ÿ‘‘ getCrossEPS()

Gets the eigensolver object that's associated to the singular value solver. It's giving matchmaker energy fr. ๐Ÿ’˜

Collective. (bestie, everyone has to show up for this one ๐ŸŒˆ)

Returns the eigensolver object.

Return type: EPS (slepc4py.SLEPc.EPS)

See also: setCrossEPS, SVDCrossGetEPS โ€” docs at https://slepc.upv.es/release/manualpages/SVD/SVDCrossGetEPS.html

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

๐Ÿ’… getCrossExplicitMatrix()

Gets the flag telling you if A^*A is built explicitly. Lowkey the important question: did we actually construct it or are we being sneaky about it? ๐Ÿ™ˆ

Not collective.

Returns True if A^*A is built explicitly.

Return type: bool (that's a Python bool, at https://docs.python.org/3/library/functions.html#bool)

See also: setCrossExplicitMatrix, SVDCrossGetExplicitMatrix โ€” docs at https://slepc.upv.es/release/manualpages/SVD/SVDCrossGetExplicitMatrix.html

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

๐Ÿฆ‹ getCyclicEPS()

Gets the eigensolver object associated to the singular value solver. Yes it's basically the same vibe as getCrossEPS but cyclic edition, and we love her for it. โญ

Collective.

Returns the eigensolver object.

Return type: EPS (slepc4py.SLEPc.EPS)

See also: setCyclicEPS, SVDCyclicGetEPS โ€” docs at https://slepc.upv.es/release/manualpages/SVD/SVDCyclicGetEPS.html

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

๐Ÿ”ฅ getCyclicExplicitMatrix()

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

Not collective.

Gets the flag indicating if H(A) = [ 0\; A ; A^T\; 0 ] is built explicitly. Iconic block matrix behaviour, no cap. ๐Ÿ’œ

Returns True if H(A) is built explicitly.

Return type: bool (see https://docs.python.org/3/library/functions.html#bool)

See also: setCyclicExplicitMatrix, SVDCyclicGetExplicitMatrix โ€” docs at https://slepc.upv.es/release/manualpages/SVD/SVDCyclicGetExplicitMatrix.html

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

๐ŸŽ€ getDS()

Gets the direct solver that's associated to the singular value solver. The DS is literally the main character of the inner solve, iykyk. โœจ

Not collective.

Returns the direct solver context.

Return type: DS (slepc4py.SLEPc.DS)

See also: setDS, SVDGetDS โ€” docs at https://slepc.upv.es/release/manualpages/SVD/SVDGetDS.html

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

๐Ÿ’– getDimensions()

Gets the number of singular values to compute and the dimension of the subspace. Two-for-one, we love an efficient queen. ๐Ÿ‘‘

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] โ€” the Python tuple at https://docs.python.org/3/library/stdtypes.html#tuple and int at https://docs.python.org/3/library/functions.html#int ๐Ÿ’ซ

See also: setDimensions, SVDGetDimensions โ€” docs at https://slepc.upv.es/release/manualpages/SVD/SVDGetDimensions.html

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

๐ŸŒˆ getImplicitTranspose()

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

Not collective.

Returns how the transpose is handled: implicitly or not.

Return type: bool (https://docs.python.org/3/library/functions.html#bool)

See also: setImplicitTranspose, SVDGetImplicitTranspose โ€” docs at https://slepc.upv.es/release/manualpages/SVD/SVDGetImplicitTranspose.html

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

๐Ÿ“ getIterationNumber()

Gets the current iteration number. The little counter that could. ๐Ÿ’€

Not collective.

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

Returns the iteration number.

Return type: int (see https://docs.python.org/3/library/functions.html#int)

See also: getConvergedReason, setTolerances, SVDGetIterationNumber โ€” docs at https://slepc.upv.es/release/manualpages/SVD/SVDGetIterationNumber.html

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

๐Ÿงš getLanczosOneSide()

Gets whether the variant of the Lanczos method being used is one-sided or two-sided. The way that Lanczos has TWO whole personality modes is so real. ๐Ÿฆ‹

Not collective.

Returns True if the method is one-sided.

Return type: bool (https://docs.python.org/3/library/functions.html#bool)

See also: setLanczosOneSide, SVDLanczosGetOneSide โ€” docs at https://slepc.upv.es/release/manualpages/SVD/SVDLanczosGetOneSide.html

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

๐Ÿ‘€ getMonitor()

Gets the list of monitor functions. So you can see all the little watchers keeping an eye on your solve. ๐ŸŒธ

Not collective.

Returns the list of monitor functions.

Return type: SVDMonitorFunction (slepc4py.typing.SVDMonitorFunction)

See also: setMonitor

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

๐Ÿ’œ getOperators()

Gets the matrices associated with the singular value problem. Collective, bestie, because matrices are a whole group project. ๐Ÿ˜ญ

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] โ€” where tuple is at https://docs.python.org/3/library/stdtypes.html#tuple, None is at https://docs.python.org/3/library/constants.html#None, and Mat is petsc4py.PETSc.Mat at https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat โญ

See also: setOperators, SVDGetOperators โ€” docs at https://slepc.upv.es/release/manualpages/SVD/SVDGetOperators.html

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

๐ŸŽ€ getOptionsPrefix()

Gets the prefix used for searching for all SVD options in the database. Your little name tag but for options. ๐Ÿท๏ธ

Not collective.

Returns the prefix string set for this SVD object.

Return type: str (https://docs.python.org/3/library/stdtypes.html#str)

See also: setOptionsPrefix, appendOptionsPrefix, SVDGetOptionsPrefix โ€” docs at https://slepc.upv.es/release/manualpages/SVD/SVDGetOptionsPrefix.html

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

โœจ getProblemType()

Gets the problem type from the SVD object.

Not collective.

Returns the problem type that was previously set.

getSignature

getSignature(omega=None)

Bestie, this one grabs the signature matrix that defines a hyperbolic singular value problem. ๐Ÿ’…

Collective. (so yes, everyone's gotta show up for this one)

Parameters:

  • omega (Vec | None) โ€” optional vector where we stash the diagonal elements of the signature matrix.

Returns: a vector holding the diagonal elements of the signature matrix.

Return type: petsc4py.PETSc.Vec

See also: setSignature, SVDGetSignature โ€” https://slepc.upv.es/release/manualpages/SVD/SVDGetSignature.html

:sources:Source code at slepc4py/SLEPc/SVD.pyx:958 <slepc4py/SLEPc/SVD.pyx#L958>``

getSingularTriplet

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

Get the i-th triplet of the singular value decomposition. โœจ

Collective.

Okay so real talk: this pulls the i-th triplet of the SVD, exactly as computed by solve(). The solution is the singular value plus its left and right singular vectors โ€” the whole lil family ๐Ÿ‘‘

Parameters:

  • i (int) โ€” index of the solution you want.
  • 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 (peep getConverged()). Singular triplets are indexed according to the ordering criterion you set up with setWhichSingularTriplets(). Don't come for me if you index out of range, I warned you ๐Ÿ˜ญ

See also: getConverged, setWhichSingularTriplets, SVDGetSingularTriplet โ€” https://slepc.upv.es/release/manualpages/SVD/SVDGetSingularTriplet.html

:sources:Source code at slepc4py/SLEPc/SVD.pyx:1334 <slepc4py/SLEPc/SVD.pyx#L1334>``

getStoppingTest

getStoppingTest()

Get the stopping test function. ๐Ÿ›‘

Not collective.

Returns: the stopping test function.

Return type: SVDStoppingFunction

See also: setStoppingTest

:sources:Source code at slepc4py/SLEPc/SVD.pyx:1088 <slepc4py/SLEPc/SVD.pyx#L1088>``

getTRLanczosExplicitMatrix

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 โ€” https://slepc.upv.es/release/manualpages/SVD/SVDTRLanczosGetExplicitMatrix.html

:sources:Source code at slepc4py/SLEPc/SVD.pyx:1948 <slepc4py/SLEPc/SVD.pyx#L1948>``

getTRLanczosGBidiag

getTRLanczosGBidiag()

Get the bidiagonalization choice used in the GSVD TRLanczos solver. ๐ŸŽ€

Not collective.

Returns: the bidiagonalization choice.

Return type: TRLanczosGBidiag

See also: setTRLanczosGBidiag, SVDTRLanczosGetGBidiag โ€” https://slepc.upv.es/release/manualpages/SVD/SVDTRLanczosGetGBidiag.html

:sources:Source code at slepc4py/SLEPc/SVD.pyx:1780 <slepc4py/SLEPc/SVD.pyx#L1780>``

getTRLanczosKSP

getTRLanczosKSP()

Get the linear solver object hanging out with the SVD solver. ๐Ÿ’–

Collective.

Returns: the linear solver object.

Return type: petsc4py.PETSc.KSP

See also: setTRLanczosKSP, SVDTRLanczosGetKSP โ€” https://slepc.upv.es/release/manualpages/SVD/SVDTRLanczosGetKSP.html

:sources:Source code at slepc4py/SLEPc/SVD.pyx:1905 <slepc4py/SLEPc/SVD.pyx#L1905>``

getTRLanczosLocking

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 โ€” https://slepc.upv.es/release/manualpages/SVD/SVDTRLanczosGetLocking.html

:sources:Source code at slepc4py/SLEPc/SVD.pyx:1869 <slepc4py/SLEPc/SVD.pyx#L1869>``

getTRLanczosOneSide

getTRLanczosOneSide()

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

Not collective.

Basically: is the thick-restart Lanczos method you're about to run one-sided, or two-sided? This tells you which. Bestie, pick a side, any side.

Returns: True if the method is one-sided.

Return type: bool

See also: setTRLanczosOneSide, SVDLanczosGetOneSide โ€” https://slepc.upv.es/release/manualpages/SVD/SVDLanczosGetOneSide.html

:sources:Source code at slepc4py/SLEPc/SVD.pyx:1740 <slepc4py/SLEPc/SVD.pyx#L1740>``

getTRLanczosRestart

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 โ€” https://slepc.upv.es/release/manualpages/SVD/SVDTRLanczosGetRestart.html

:sources:Source code at slepc4py/SLEPc/SVD.pyx:1825 <slepc4py/SLEPc/SVD.pyx#L1825>``

getThreshold

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 โ€” https://slepc.upv.es/release/manualpages/SVD/SVDGetThreshold.html

:sources:Source code at slepc4py/SLEPc/SVD.pyx:561 <slepc4py/SLEPc/SVD.pyx#L561>``

getTolerances

getTolerances()

Get the tolerance and maximum iteration count. ๐ŸŒธ

Not collective.

These are the tolerance and max iteration count that the default SVD convergence tests be using. She's setting the vibe check for when we're done converging, periodt.

Returns:

  • tol (float) โ€” the convergence tolerance.
  • max_it (int) โ€” the maximum number of iterations.

Return type: tuple[float, int]

See also: setTolerances, SVDGetTolerances โ€” https://slepc.upv.es/release/manualpages/SVD/SVDGetTolerances.html

:sources:Source code at slepc4py/SLEPc/SVD.pyx:618 <slepc4py/SLEPc/SVD.pyx#L618>``

getTrackAll

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

Ok so this one hands you the SVD type of this object, bestie. That's it. That's the whole vibe. โœจ

Not collective. (so everybody do your own thing, no group chat needed)

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(). So like, you already did the solving, now you're collecting the receipts ๐Ÿ’…

Collective. (yes, the whole squad participates)

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

fr fr, if you go out of that range you're on your own ๐Ÿ˜ญ

See also: getConverged, setWhichSingularTriplets, SVDGetSingularTriplet

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

getVectors(i, U, V)

Grabs the i-th left and right singular vectors, as computed by solve(). Two vectors, one call, iconic behavior ๐Ÿซถ

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

same deal as before โ€” stay inside 0 to nconv-1, no cap ๐ŸŽ€

See also: getConverged, setWhichSingularTriplets, SVDGetSingularTriplet

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

getWhichSingularTriplets()

Tells you which singular triplets are being sought. Like, which ones are we even hunting for, bestie? ๐Ÿ‘‘

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

Asks the question: is this SVD actually a generalized singular value problem? Spilling the tea on your own problem type โ˜•

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

Checks whether the SVD object is out here living its hyperbolic singular value problem era ๐Ÿฆ‹

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. Clean slate, fresh start, main character rebirth arc โœจ

Collective.

See also: SVDReset

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

Return type: None

setBV(V, U=None)

Sets the basis vectors objects that are associated to the SVD solver. Giving your solver its little BV besties ๐Ÿ’–

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

note that U defaults to None, so you can absolutely just pass V and dip ๐ŸŒธ

See also: getBV, SVDSetBV

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

setConvergenceTest(conv)

Sets how to compute the error estimate that gets used in the convergence test. Choose your fighter ๐ŸฅŠ

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)

Sets an eigensolver object that's associated to the singular value solver. Cross-product era, but make it eigensolver ๐Ÿ”ฅ

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)

Sets whether the eigensolver operator A^*A must actually be computed โ€” like, built for real, not vibes-only.

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.

so if you don't flip this on, you get the shell-matrix treatment. iykyk ๐Ÿš

See also: getCrossExplicitMatrix, SVDCrossSetExplicitMatrix

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

setCyclicEPS(eps)

Sets an eigensolver object that's associated to the singular value solver โ€” cyclic edition, because of course there's a whole other one ๐ŸŒˆ

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)

Sets 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

Return type โ€” None (https://docs.python.org/3/library/constants.html#None)

Notes

ok so bestie, in GSVD and HSVD the equivalent eigenvalue problem is generalized, which means two matrices get built, not one. the way that multiplies your work... ๐Ÿ’€

by default tho, the matrices are NOT built explicitly โ€” they're handled as shell matrices instead. periodt.

See also: getCyclicExplicitMatrix, SVDCyclicSetExplicitMatrix (https://slepc.upv.es/release/manualpages/SVD/SVDCyclicSetExplicitMatrix.html)

๐Ÿ“„ Source code at slepc4py/SLEPc/SVD.pyx:1616 โ€” slepc4py/SLEPc/SVD.pyx#L1616

๐ŸŽ€ setDS(ds)

attach a direct solver object to your singular value solver. like, you're giving it a little helper. ๐Ÿซถ

Collective.

Parameters

  • ds (DS) โ€” the direct solver context.

Return type โ€” None (https://docs.python.org/3/library/constants.html#None)

See also: getDS, SVDSetDS (https://slepc.upv.es/release/manualpages/SVD/SVDSetDS.html)

๐Ÿ“„ Source code at slepc4py/SLEPc/SVD.pyx:894 โ€” slepc4py/SLEPc/SVD.pyx#L894

๐ŸŒธ setDimensions(nsv=None, ncv=None, mpd=None)

tells the solver how many singular values you want and how big the subspace can get. this is the "how much room do y'all need" conversation.

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 (https://docs.python.org/3/library/constants.html#None)

Notes

use DETERMINE for ncv and mpd to get a reasonably good value auto-assigned, and that value depends on the solution method you're running. ๐Ÿงš

ncv and mpd are intimately related (they're giving situationship fr), so pls set at most one of them. normal usage goes like this:

  • when nsv is small, you set ncv (a reasonable default is 2 * nsv).
  • when nsv is large, you set mpd.

ncv should always land between nsv and (nsv + mpd), typically ncv = nsv + mpd. and if nsv isn't too big, mpd = nsv is a totally reasonable choice โ€” otherwise pick something smaller. ๐Ÿ’…

See also: getDimensions, SVDSetDimensions (https://slepc.upv.es/release/manualpages/SVD/SVDSetDimensions.html)

๐Ÿ“„ Source code at slepc4py/SLEPc/SVD.pyx:778 โ€” slepc4py/SLEPc/SVD.pyx#L778

โœจ setFromOptions()

pulls the SVD options straight outta the options database. it's the "just read my settings, bestie" move.

Collective.

Notes

to see all the options, run your program with the -help option. ๐Ÿซถ

> โš ๏ธ heads up: this routine MUST be called before setUp() if you wanna be allowed to set the solver type. no setUp() first, no solver-type privileges.

See also: setOptionsPrefix, SVDSetFromOptions (https://slepc.upv.es/release/manualpages/SVD/SVDSetFromOptions.html)

๐Ÿ“„ Source code at slepc4py/SLEPc/SVD.pyx:376 โ€” slepc4py/SLEPc/SVD.pyx#L376

Return type โ€” None (https://docs.python.org/3/library/constants.html#None)

๐Ÿฆ‹ setImplicitTranspose(mode)

controls how the transpose of the associated matrix gets handled. explicitly or... vibes only. โœจ

Logically collective.

Parameters

Return type โ€” None (https://docs.python.org/3/library/constants.html#None)

Notes

by default, the transpose of the matrix is explicitly built โ€” but only if the matrix has defined the Mat.transpose() operation. iykyk.

if this flag is set to True, the solver does not build the transpose. instead it handles it implicitly via Mat.multTranspose() (or Mat.multHermitianTranspose() in the complex case). no cap. ๐Ÿ’…

See also: getImplicitTranspose, SVDSetImplicitTranspose (https://slepc.upv.es/release/manualpages/SVD/SVDSetImplicitTranspose.html)

๐Ÿ“„ Source code at slepc4py/SLEPc/SVD.pyx:497 โ€” slepc4py/SLEPc/SVD.pyx#L497

๐Ÿ’œ setInitialSpace(spaceright=None, spaceleft=None)

sets the initial spaces the SVD solver starts iterating from. like giving your solver a lil head start. ๐Ÿ‘‘

Collective.

Parameters

  • spaceright (list[Vec] | None) โ€” the right initial space.
  • spaceleft (list[Vec] | None) โ€” the left initial space.

Return type โ€” None (https://docs.python.org/3/library/constants.html#None)

Notes

the initial right and left spaces are rough approximations to the right and/or left singular subspaces that the solver starts iterating from. you do not have to provide both sets of vectors. it's giving flexible. ๐ŸŒธ

some solvers start iterating on a single vector (initial vector). in that case, the other vectors are just... ignored. ๐Ÿ™ˆ

these vectors do not persist from one solve() call to the other, so you gotta set the initial spaces every single time. no skipping, bestie.

the vectors don't need to be mutually orthonormal either, since they get explicitly orthonormalized internally. slay.

common usage of this function is when you can hand over a rough approximation of the singular spaces you want โ€” and then convergence may be faster. ๐Ÿ”ฅ

See also: SVDSetInitialSpaces (https://slepc.upv.es/release/manualpages/SVD/SVDSetInitialSpaces.html)

๐Ÿ“„ Source code at slepc4py/SLEPc/SVD.pyx:1007 โ€” slepc4py/SLEPc/SVD.pyx#L1007

๐ŸŒˆ setLanczosOneSide(flag=True)

picks whether the variant of the Lanczos method you're running is one-sided or two-sided. choose your fighter. โš”๏ธ

Logically collective.

Parameters

Return type โ€” None (https://docs.python.org/3/library/constants.html#None)

Notes

by default, a two-sided variant is selected, and ngl it's sometimes slightly more robust. buuut the one-sided variant is faster because it skips the orthogonalization associated with left singular vectors. it also saves the memory required for storing those vectors. less baggage, more speed. ๐Ÿ’…

See also: getLanczosOneSide, SVDLanczosSetOneSide (https://slepc.upv.es/release/manualpages/SVD/SVDLanczosSetOneSide.html)

๐Ÿ“„ Source code at slepc4py/SLEPc/SVD.pyx:1667 โ€” slepc4py/SLEPc/SVD.pyx#L1667

๐Ÿ“ setMonitor(monitor, args=None, kargs=None)

appends a monitor function to the list of monitors. so you can watch your solver do its thing in real time. very main character of you. ๐Ÿ‘€

Logically collective.

See also: getMonitor, cancelMonitor, SVDMonitorSet (https://slepc.upv.es/release/manualpages/SVD/SVDMonitorSet.html)

๐Ÿ“„ Source code at slepc4py/SLEPc/SVD.pyx:1107 โ€” slepc4py/SLEPc/SVD.pyx#L1107

Parameters

  • monitor (SVDMonitorFunction | None)
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

โ€ฆand for the record, its Return type: None, bestie <https://docs.python.org/3/library/constants.html#None> โ€” so nothing comes back, that's the whole vibe. Moving on ๐Ÿ’…

โœจ setOperators(A, B=None) โœจ

Sets up the matrices that are ~associated with~ the singular value problem. Like, you're handing it the actual math to chew on. ๐Ÿ“

Collective, meaning everyone in the gang has to call it.

Parameters

Return type: None <https://docs.python.org/3/library/constants.html#None>

See also: getOperators, SVDSetOperators <https://slepc.upv.es/release/manualpages/SVD/SVDSetOperators.html>

:sources:Source code at slepc4py/SLEPc/SVD.pyx:938 <slepc4py/SLEPc/SVD.pyx#L938>

โœจ setOptionsPrefix(prefix=None) โœจ

Sets the prefix that gets used when this thing goes hunting through the options database for all your SVD options. ๐Ÿ”Ž

Logically collective, so play nice.

Parameters

Return type: None <https://docs.python.org/3/library/constants.html#None>

Notes

๐Ÿšจ Bestie, do NOT put a hyphen (-) at the start of the prefix name. The first character of every runtime option is AUTOMATICALLY the hyphen. It does it for you. Stop doing the most.

So like, if you wanna tell two different SVD contexts apart in the runtime options, you'd call:

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

See also: appendOptionsPrefix, getOptionsPrefix, SVDGetOptionsPrefix <https://slepc.upv.es/release/manualpages/SVD/SVDGetOptionsPrefix.html>

:sources:Source code at slepc4py/SLEPc/SVD.pyx:326 <slepc4py/SLEPc/SVD.pyx#L326>

โœจ setProblemType(problem_type) โœจ

Sets which flavor of singular value problem we're doing. ๐ŸŒˆ

Logically collective, yes ma'am.

Parameters

  • problem_type (ProblemType <#slepc4py.SLEPc.SVD.ProblemType>) โ€” the problem type you wanna set.

Return type: None <https://docs.python.org/3/library/constants.html#None>

Notes

  • GSVD needs two matrices, and they gotta come in through setOperators().
  • HSVD needs a signature matrix, and it's gotta come in through setSignature().

See also: setOperators, setSignature, getProblemType, SVDSetProblemType <https://slepc.upv.es/release/manualpages/SVD/SVDSetProblemType.html>

:sources:Source code at slepc4py/SLEPc/SVD.pyx:414 <slepc4py/SLEPc/SVD.pyx#L414>

โœจ setSignature(omega=None) โœจ

Sets the signature matrix that defines a hyperbolic singular value problem. ๐Ÿฆ‹

Collective.

Parameters

Return type: None <https://docs.python.org/3/library/constants.html#None>

See also: getSignature, SVDSetSignature <https://slepc.upv.es/release/manualpages/SVD/SVDSetSignature.html>

:sources:Source code at slepc4py/SLEPc/SVD.pyx:987 <slepc4py/SLEPc/SVD.pyx#L987>

โœจ setStoppingTest(stopping, args=None, kargs=None) โœจ

Hands over a function that decides when the outer iteration of the eigensolver should ~stop~. Like a bouncer for the loop. ๐Ÿ›‘

Logically collective.

See also: getStoppingTest, SVDSetStoppingTestFunction <https://slepc.upv.es/release/manualpages/SVD/SVDSetStoppingTestFunction.html>

:sources:Source code at slepc4py/SLEPc/SVD.pyx:1064 <slepc4py/SLEPc/SVD.pyx#L1064>

Parameters

Return type: None <https://docs.python.org/3/library/constants.html#None>

โœจ setTRLanczosExplicitMatrix(flag=True) โœจ

Tells it whether the matrix Z=[A^*,B^*]^* has to be built explicitly. ๐Ÿ’ฅ

Logically collective.

Parameters

Return type: None <https://docs.python.org/3/library/constants.html#None>

Notes

This one only matters for the GSVD case, iykyk. Z is the coefficient matrix of the least-squares solver it uses internally.

See also: getTRLanczosExplicitMatrix, SVDTRLanczosSetExplicitMatrix <https://slepc.upv.es/release/manualpages/SVD/SVDTRLanczosSetExplicitMatrix.html>

:sources:Source code at slepc4py/SLEPc/SVD.pyx:1925 <slepc4py/SLEPc/SVD.pyx#L1925>

โœจ setTRLanczosGBidiag(bidiag) โœจ

Picks which bidiagonalization choice the GSVD TRLanczos solver is gonna use. ๐ŸŽ€

Logically collective.

Parameters

  • bidiag (TRLanczosGBidiag <#slepc4py.SLEPc.SVD.TRLanczosGBidiag>) โ€” the bidiagonalization choice.

Return type: None <https://docs.python.org/3/library/constants.html#None>

See also: getTRLanczosGBidiag, SVDTRLanczosSetGBidiag <https://slepc.upv.es/release/manualpages/SVD/SVDTRLanczosSetGBidiag.html>

:sources:Source code at slepc4py/SLEPc/SVD.pyx:1762 <slepc4py/SLEPc/SVD.pyx#L1762>

โœจ setTRLanczosKSP(ksp) โœจ

Attaches a linear solver object to the SVD solver. It's giving teamwork. ๐Ÿค

Collective.

Parameters

Return type: None <https://docs.python.org/3/library/constants.html#None>

See also: getTRLanczosKSP, SVDTRLanczosSetKSP <https://slepc.upv.es/release/manualpages/SVD/SVDTRLanczosSetKSP.html>

:sources:Source code at slepc4py/SLEPc/SVD.pyx:1888 <slepc4py/SLEPc/SVD.pyx#L1888>

โœจ setTRLanczosLocking(lock) โœจ

Flips between the locking and non-locking versions of TRLanczos. ๐Ÿ”’

Logically collective.

Parameters

Return type: None <https://docs.python.org/3/library/constants.html#None>

Notes

Default behavior is to lock converged singular triplets whenever the method restarts. But you can change that so all directions stick around in the working subspace even if they already converged to working accuracy โ€” that's the non-locking variant, bestie.

See also: getTRLanczosLocking, SVDTRLanczosSetLocking <https://slepc.upv.es/release/manualpages/SVD/SVDTRLanczosSetLocking.html>

:sources:Source code at slepc4py/SLEPc/SVD.pyx:1844 <slepc4py/SLEPc/SVD.pyx#L1844>

โœจ setTRLanczosOneSide(flag=True) โœจ

Sets whether the variant of the method you're running is one-sided or two-sided. ๐Ÿซถ

Logically collective.

Sets whether the variant of the thick-restart Lanczos method you're running is one-sided or two-sided.

Parameters

Return type: None <https://docs.python.org/3/library/constants.html#None>

Notes

๐Ÿซง The notes for this one keep going past the edge of this part โ€” hang tight, bestie, the tea spills over into the next chunk. ๐ŸŒธ

okay so, by default a two-sided variant gets selected, and lowkey it's sometimes a little more robust ๐Ÿ’ช. But bestie โ€” the one-sided variant is faster fr fr, because it dodges the orthogonalization that comes along with the left singular vectors. so if speed is the vibe and you don't need that extra sturdiness, one-sided is your girl. โœจ

see also: getTRLanczosOneSide, SVDLanczosSetOneSide

source: slepc4py/SLEPc/SVD.pyx:1712

๐Ÿ’– setTRLanczosRestart(keep)

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

logically collective ๐Ÿซถ

so basically: this sets the restart parameter for the thick-restart Lanczos method โ€” specifically the proportion of basis vectors that have to be kept around after a restart. main character energy for your convergence, honestly.

parameters

  • keep (float) โ€” the number of vectors to be kept at restart.

returns None

notes ๐ŸŒธ

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

see also: getTRLanczosRestart, SVDTRLanczosSetRestart

source: slepc4py/SLEPc/SVD.pyx:1799

๐ŸŽ€ setThreshold(thres, rel=False)

Sets the threshold used in the threshold stopping test.

logically collective ๐Ÿซถ

parameters

  • thres (float) โ€” the threshold.
  • rel (bool) โ€” whether the threshold is relative or not.

returns None

notes โœจ

Internally this sets a special stopping test based on the threshold, where singular values get computed in sequence until one of the computed singular values drops below/above the threshold โ€” which way depends on whether you're computing the largest or the smallest singular values. iykyk.

For the largest singular values case, you can make the threshold relative with respect to the largest singular value (i.e., the matrix norm). cute.

The details are given in SVDSetThreshold.

see also: setStoppingTest, getThreshold, SVDSetThreshold

source: slepc4py/SLEPc/SVD.pyx:583

๐Ÿฆ‹ setTolerances(tol=None, max_it=None)

Sets the tolerance and maximum iteration count used.

logically collective ๐Ÿซถ

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

returns None

notes ๐Ÿ’…

Use DETERMINE for max_it to get a reasonably good value assigned automatically โ€” it depends on the solution method, so it's giving โœจadaptiveโœจ.

see also: getTolerances, SVDSetTolerances

source: slepc4py/SLEPc/SVD.pyx:643

๐ŸŒˆ setTrackAll(trackall)

Sets the flag for computing the residual of all singular triplets.

logically collective ๐Ÿซถ

Tells the solver whether it has to compute the residual of all approximate singular triplets or not. no skipping, bestie.

parameters

  • trackall (bool) โ€” whether to compute all residuals or not.

returns None

see also: getTrackAll, SVDSetTrackAll

source: slepc4py/SLEPc/SVD.pyx:732

๐Ÿ‘‘ setType(svd_type)

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

logically collective ๐Ÿซถ

parameters

  • svd_type (Type | str) โ€” the solver to be used.

returns None

notes ๐Ÿ”ฅ

The default is CROSS. Normally it's best to use setFromOptions() and then set the SVD type from the options database instead of calling this routine directly โ€” because the options database gives the user maximum flexibility in evaluating the different available methods. periodt.

see also: getType, SVDSetType

source: slepc4py/SLEPc/SVD.pyx:261

๐Ÿงš setUp()

Sets up all the internal data structures.

collective ๐Ÿซถ

notes ๐ŸŒธ

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

You don't need to call this explicitly in most cases, since solve() calls it for you. It's useful though when you want to measure the set-up time separately from the solve time. timing girlies, this one's for you.

see also: solve, SVDSetUp

source: slepc4py/SLEPc/SVD.pyx:1164

returns None

โญ setWhichSingularTriplets(which)

Sets which singular triplets are to be sought.

logically collective ๐Ÿซถ

parameters

  • which (Which) โ€” the singular values to be sought (either largest or smallest).

returns None

see also: getWhichSingularTriplets, SVDSetWhichSingularTriplets

source: slepc4py/SLEPc/SVD.pyx:543

๐Ÿ’œ solve()

Solves the singular value problem.

collective ๐Ÿซถ

notes ๐Ÿ˜ญ

The problem matrices are specified with setOperators().

Here's the tea: solve() will return without generating an error regardless of whether all the requested solutions were actually computed or not. so please, bestie, call getConverged() to get the actual number of computed solutions, and getConvergedReason() to figure out if the solver converged or failed and why. don't just trust it blindly, that's the vibe check. ๐Ÿ™ˆ

see also: setUp, setOperators, getConverged, getConvergedReason, SVDSolve

source: slepc4py/SLEPc/SVD.pyx:1185

returns None

๐Ÿ“ valuesView(viewer=None)

Displays the computed singular values in a viewer.

collective ๐Ÿซถ

parameters

  • viewer (Viewer | None) โ€” visualization context; if it's not provided, standard output is used.

returns None

see also: solve, vectorsView, errorView, SVDValuesView

source: slepc4py/SLEPc/SVD.pyx:1456

๐Ÿ’– vectorsView(viewer=None)

Outputs the computed singular vectors to a viewer.

collective ๐Ÿซถ

Parameters (yes bestie the one from the method above, we're still in it ๐Ÿ’–)

  • viewer (Viewer | None) โ€” the visualization context, aka where your pretty output goes ๐ŸŽ€. If you don't hand one over, it just uses the standard output, no stress.

Return type

None

See also (go read these too, they're the whole friend group)

solve, valuesView, errorView, SVDVectorsView (slepc.upv.es/release/manualpages/SVD/SVDVectorsView.html)

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

view(viewer=None)

Prints the whole SVD data structure, like a soft launch for your object ๐Ÿ“ธ.

Collective. (meaning every process in the crew has to call it, no skipping, periodt ๐Ÿ‘‘)

Parameters

  • viewer (Viewer | None) โ€” Visualization context; if not provided, the standard output is used. Yep, same deal as before ๐Ÿ’ซ

Return type

None

See also

SVDView (slepc.upv.es/release/manualpages/SVD/SVDView.html)

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

โœจ Attributes Documentation โœจ

  • ds โ€” The direct solver (DS) object associated. Your SVD's little direct-solver bestie ๐Ÿซถ

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

  • max_it โ€” The maximum iteration count. Like, how many tries before we call it ๐Ÿ’…

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. How close is close enough, fr fr ๐ŸŒธ

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

  • track_all โ€” Compute the residual norm of all approximate eigenpairs. Not just the favourites, all of them ๐Ÿ˜ค

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. Which slice of the vibes are we hunting ๐Ÿ”

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

  • __init__()
  • classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.Sys

class slepc4py.SLEPc.Sys

Bases: object

System utilities. Your basic intel-gathering era, very lowkey essential ๐Ÿงš

Methods Summary

  • getVersion([devel, date, author]) โ€” Return SLEPc version information.
  • getVersionInfo() โ€” Return SLEPc version information.
  • hasExternalPackage(package) โ€” Return whether SLEPc has support for external package.
  • isFinalized() โ€” Return whether SLEPc has been finalized.
  • isInitialized() โ€” Return whether SLEPc has been initialized.

Methods Documentation

classmethod getVersion(devel=False, date=False, author=False)

Return SLEPc version information. Spill the tea about which version you're running โ˜•

Not collective.

Parameters

  • devel (bool) โ€” Additionally, return whether using an in-development version. Are we on the beta build, bestie ๐Ÿ‘€
  • date (bool) โ€” Additionally, return date information.
  • author (bool) โ€” Additionally, return author information.

Returns

  • major (int) โ€” Major version number.
  • minor (int) โ€” Minor version number.
  • micro (int) โ€” Micro (or patch) version number.

Return type

tuple[int, int, int]

See also

SlepcGetVersion (slepc.upv.es/release/manualpages/Sys/SlepcGetVersion.html), SlepcGetVersionNumber (slepc.upv.es/release/manualpages/Sys/SlepcGetVersionNumber.html)

Source code at slepc4py/SLEPc/Sys.pyx:8

classmethod getVersionInfo()

Return SLEPc version information. Same energy, but as a whole little dict this time ๐ŸŽ€

Not collective.

Returns

  • info โ€” Dictionary with version information.

Return type

dict

See also

SlepcGetVersion (slepc.upv.es/release/manualpages/Sys/SlepcGetVersion.html), SlepcGetVersionNumber (slepc.upv.es/release/manualpages/Sys/SlepcGetVersionNumber.html)

Source code at slepc4py/SLEPc/Sys.pyx:64

classmethod hasExternalPackage(package)

Return whether SLEPc has support for external package. Like, does it fw that package or not ๐Ÿ’…

Not collective.

Parameters

  • package (str) โ€” The external package name.

Return type

bool

See also

SlepcHasExternalPackage (slepc.upv.es/release/manualpages/Sys/SlepcHasExternalPackage.html)

Source code at slepc4py/SLEPc/Sys.pyx:118

classmethod isFinalized()

Return whether SLEPc has been finalized. We done here or not, bestie ๐Ÿ˜ญ

Not collective.

See also

isInitialized

Source code at slepc4py/SLEPc/Sys.pyx:103

Return type

bool

classmethod isInitialized()

Return whether SLEPc has been initialized. Did we even show up to the party yet ๐Ÿฆ‹

Not collective.

See also

isFinalized

Source code at slepc4py/SLEPc/Sys.pyx:90

Return type

bool

__init__()

classmethod __new__(*args, **kwargs)

slepc4py.SLEPc.Util

class slepc4py.SLEPc.Util

Bases: object

Other utilities such as the creation of structured matrices. The little misc drawer of helpful stuff, iconic tbh ๐ŸŒˆ

โœจ Methods Summary โœจ

okay bestie, here's the whole menu of what this class can do at a glance ๐ŸŽ€

  • createMatBSE(R, C) โ€” Create a matrix that can be used to define a BSE type problem. ๐Ÿฆ‹
  • createMatHamiltonian(A, B, C) โ€” Create matrix to be used for a structured Hamiltonian eigenproblem. ๐Ÿ‘‘
  • createMatLREP(AK, BM[, red]) โ€” Create a matrix that can be used to define a LREP type problem. ๐Ÿ’œ

๐Ÿ› ๏ธ Methods Documentation ๐Ÿ› ๏ธ

classmethod createMatBSE(R, C)

Create a matrix that can be used to define a BSE type problem. ๐Ÿซถ

Collective. like, every process has to show up for this one, no ghosting.

Create a matrix that can be used to define a structured eigenvalue problem of type BSE (Bethe-Salpeter Equation).

Parameters ๐ŸŒธ

Returns The matrix with the block form H = [ R; C; -C^*; -R^T ]. โœจ

Return type petsc4py.PETSc.Mat (docs at https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat)

See also: MatCreateBSE (at https://slepc.upv.es/release/manualpages/Sys/MatCreateBSE.html)

๐Ÿ“Ž Source code at slepc4py/SLEPc/Util.pyx:8 (link anchor slepc4py/SLEPc/Util.pyx#L8)

classmethod createMatHamiltonian(A, B, C)

Create matrix to be used for a structured Hamiltonian eigenproblem. ๐Ÿงš

Collective.

Parameters ๐ŸŒˆ

Returns The matrix with the block form H = [ A; B; C; -A^* ]. ๐Ÿ’…

Return type petsc4py.PETSc.Mat (docs at https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat)

See also: MatCreateHamiltonian (at https://slepc.upv.es/release/manualpages/Sys/MatCreateHamiltonian.html)

๐Ÿ“Ž Source code at slepc4py/SLEPc/Util.pyx:38 (link anchor slepc4py/SLEPc/Util.pyx#L38)

classmethod createMatLREP(AK, BM, red=False)

Create a matrix that can be used to define a LREP type problem. ๐Ÿ“

Collective.

Create a matrix that can be used to define a structured Linear Response eigenvalue problem.

Parameters ๐Ÿ’–

Returns The matrix with the block form H = [ A; B; -B; -A ] (non-reduced) or H = [ 0; K; M; 0 ] (reduced). ๐Ÿ˜Œ

Return type petsc4py.PETSc.Mat (docs at https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat)

See also: MatCreateLREP (at https://slepc.upv.es/release/manualpages/Sys/MatCreateLREP.html)

๐Ÿ“Ž Source code at slepc4py/SLEPc/Util.pyx:67 (link anchor slepc4py/SLEPc/Util.pyx#L67)

__init__()

(no body, just vibes โ€” she exists, that's it ๐Ÿ˜ญ)

classmethod __new__(*args, **kwargs)

๐Ÿซง Attributes ๐Ÿซง

the whole constant squad, look at them:

slepc4py.SLEPc.DECIDE

slepc4py.SLEPc.DECIDE: int = DECIDE (int docs at https://docs.python.org/3/library/functions.html#int)

Constant DECIDE of type int (docs at https://docs.python.org/3/library/functions.html#int) ๐Ÿ’ซ

slepc4py.SLEPc.DEFAULT

slepc4py.SLEPc.DEFAULT: int = DEFAULT (int docs at https://docs.python.org/3/library/functions.html#int)

Constant DEFAULT of type int (docs at https://docs.python.org/3/library/functions.html#int) ๐Ÿ’ซ

slepc4py.SLEPc.DETERMINE

slepc4py.SLEPc.DETERMINE: int = DETERMINE (int docs at https://docs.python.org/3/library/functions.html#int)

Constant DETERMINE of type int (docs at https://docs.python.org/3/library/functions.html#int) ๐Ÿ’ซ

slepc4py.SLEPc.CURRENT

slepc4py.SLEPc.CURRENT: int = CURRENT (int docs at https://docs.python.org/3/library/functions.html#int)

Constant CURRENT of type int (docs at https://docs.python.org/3/library/functions.html#int) ๐Ÿ’ซ

๐ŸŒˆ slepc4py demos ๐ŸŒˆ

ex1.py: Standard symmetric eigenproblem for the 1-D Laplacian

okay so this little cutie computes eigenvalues and eigenvectors of the discrete Laplacian on a one-dimensional domain with finite differences. iconic behavior honestly. ๐Ÿ”ฅ

The full source code for this demo can be downloaded at ../_static/ex1.py. ๐ŸŽ€

The first thing to do is initialize the libraries. This is normally not required, as it is done automatically at import time. However, if you want to gain access to the facilities for setting command-line options, the following lines must be executed by the main script prior to any petsc4py or slepc4py calls:

import sys, slepc4py
slepc4py.init(sys.argv)

Next, we have to import the relevant modules. Normally, both PETSc and SLEPc modules have to be imported in all slepc4py programs. It may be useful to import NumPy as well:

from petsc4py import PETSc
from slepc4py import SLEPc
import numpy

At this point, we can use any petsc4py and slepc4py operations. For instance, the following lines allow the user to specify an integer command-line argument n with a default value of 30 (see below for example usage of command-line options):

opts = PETSc.Options()
n = opts.getInt('n', 30)

It is necessary to build a matrix to define an eigenproblem (or two in the case of generalized eigenproblems). The following fragment of code creates the matrix object and then fills the non-zero elements one by one. The matrix of this particular example is tridiagonal, with value 2 in the diagonal, and -1 in off-diagonal positions. See petsc4py documentation for details about matrix objects:

A = PETSc.Mat(); A.create()
A.setSizes([n, n])
A.setFromOptions()

rstart, rend = A.getOwnershipRange()

# first row
if rstart == 0:
  A[0, :2] = [2, -1]
  rstart += 1
# last row
if rend == n:
  A[n-1, -2:] = [-1, 2]
  rend -= 1
# other rows
for i in range(rstart, rend):
  A[i, i-1:i+2] = [-1, 2, -1]

A.assemble()

Okay so the solver object? Built exactly like every other object in petsc4py. Iconic. No notes. ๐Ÿ’…

E = SLEPc.EPS(); E.create()

Now, once your object exists, you gotta say what the eigenvalue problem actually is. At minimum you need to hand it one matrix. And you also have to declare the problem type โ€” like, the vibes of the problem โ€” which here is HEP (Hermitian eigenvalue problem). Beyond that, you can totally drop in more settings right here (the computation tolerance, for instance, bestie). And once every option is set, you call the setFromOptions() <#slepc4py.SLEPc.EPS.setFromOptions> operation so that any options passed at run time on the command line get handed over to the solver object:

E.setOperators(A)
E.setProblemType(SLEPc.EPS.ProblemType.HEP)

history = []
def monitor(eps, its, nconv, eig, err):
    if nconv<len(err): history.append(err[nconv])
E.setMonitor(monitor)

E.setFromOptions()

Then boom โ€” the solve() <#slepc4py.SLEPc.EPS.solve> method runs whichever eigensolver got selected, and keeps the solution stored internally:

E.solve()

Computation done!! ๐ŸŽ‰ Now we print the results, obviously. First up, grab some informative data off the solver object:

Print = PETSc.Sys.Print

Print()
Print("******************************")
Print("*** SLEPc Solution Results ***")
Print("******************************")
Print()

its = E.getIterationNumber()
Print( "Number of iterations of the method: %d" % its )

eps_type = E.getType()
Print( "Solution method: %s" % eps_type )

nev, ncv, mpd = E.getDimensions()
Print( "Number of requested eigenvalues: %d" % nev )

tol, maxit = E.getTolerances()
Print( "Stopping condition: tol=%.4g, maxit=%d" % (tol, maxit) )

And to actually retrieve the solution, you first need to find out how many eigenpairs converged to the precision you asked for:

nconv = E.getConverged()
Print( "Number of converged eigenpairs %d" % nconv )

Then for each of those nconv eigenpairs, you can pull out the eigenvalue k and the eigenvector, which comes as two petsc4py vectors, vr and vi โ€” those are the real part and the imaginary part of the eigenvector, because for real matrices the eigenvalue and eigenvector can be complex, no cap. In this example though, we already know both the eigenvalue and eigenvector are real, so one single vector v is all we need. We also compute the matching relative errors so we can double-check the computed solution is actually correct:

if nconv > 0:
  # Create the results vectors
  v, _ = A.createVecs()
  #
  Print()
  Print("        k          ||Ax-kx||/||kx|| ")
  Print("----------------- ------------------")
  for i in range(nconv):
    k = E.getEigenpair(i, v)
    error = E.computeError(i)
    Print( " %12f       %12g" % (k, error) )
  Print()

๐ŸŒธ Example of command-line usage ๐ŸŒธ

Now let's show off how to pass command-line options, so you can unlock slepc4py's full potential, bestie. It's giving main character energy.

A plain run of the demo/ex1.py script gives you this:

$ python demo/ex1.py

******************************
*** SLEPc Solution Results ***
******************************

Number of iterations of the method: 4
Solution method: krylovschur
Number of requested eigenvalues: 1
Stopping condition: tol=1e-07, maxit=100
Number of converged eigenpairs 4

    k          ||Ax-kx||/||kx||
----------------- ------------------
     3.989739        5.76012e-09
     3.959060        1.41957e-08
     3.908279        6.74118e-08
     3.837916        8.34269e-08

Wanna change up the solver parameters? Just use SLEPc command-line options with the -eps prefix. Say you want a different number of requested eigenvalues and a different tolerance:

$ python demo/ex1.py -eps_nev 10 -eps_tol 1e-11

The method the solver object uses can also be set at run time:

$ python demo/ex1.py -eps_type subspace

And every single one of those settings can be changed inside the source code too, using the right slepc4py method. And since options can come from the code or the command line, it's super useful to just peek at which settings are currently in play:

$ python demo/ex1.py -eps_view

EPS Object: 1 MPI process
  type: krylovschur
    50% of basis vectors kept after restart
    using the locking variant
  problem type: symmetric eigenvalue problem
  selected portion of the spectrum: largest eigenvalues in magnitude
  number of eigenvalues (nev): 1
  number of column vectors (ncv): 16
  maximum dimension of projected problem (mpd): 16
  maximum number of iterations: 100
  tolerance: 1e-08
  convergence test: relative to the eigenvalue
BV Object: 1 MPI process
  type: mat
  17 columns of global length 30
  orthogonalization method: classical Gram-Schmidt
  orthogonalization refinement: if needed (eta: 0.7071)
  block orthogonalization method: GS
  doing matmult as a single matrix-matrix product
DS Object: 1 MPI process
  type: hep
  solving the problem with: Implicit QR method (_steqr)
ST Object: 1 MPI process
  type: shift
  shift: 0
  number of matrices: 1

Side note bestie: for computing eigenvalues of smallest magnitude you can use the option -eps_smallest_magnitude. But for interior eigenvalues? Lowkey it's not that straightforward. One option is to try harmonic extraction โ€” for example, to grab the eigenvalues closest to 0.6:

$ python demo/ex1.py -eps_harmonic -eps_target 0.6

But heads up โœจ depending on the problem, harmonic extraction may fail to converge. When that happens, you have to specify a spectral transformation that isn't the default. On the command line you indicate that with the -st_ prefix. For example, shift-and-invert with a shift value of 0.6 would be:

$ python demo/ex1.py -st_type sinvert -eps_target 0.6

๐Ÿฆ‹ ex2.py: Standard symmetric eigenproblem for the 2-D Laplacian ๐Ÿฆ‹

This example computes eigenvalues and eigenvectors of the discrete Laplacian on a two-dimensional domain, using finite differences. Slay.

The full source code for this demo can be downloaded here <../_static/ex2.py>.

Initialization is basically the same as the previous examples:

try: range = xrange
except: pass

import sys, slepc4py
slepc4py.init(sys.argv)

from petsc4py import PETSc
from slepc4py import SLEPc

Print = PETSc.Sys.Print

In this example we organized the code into several functions. This one builds the finite-difference Laplacian matrix by computing the indices of every entry. An alternative would be to use the functionality offered by DMDA <https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.DMDA.html#petsc4py.PETSc.DMDA>.

def construct_operator(m, n):
    # Create matrix for 2D Laplacian operator
    A = PETSc.Mat().create()
    A.setSizes([m*n, m*n])
    A.setFromOptions()
    # Fill matrix
    hx = 1.0/(m-1) # x grid spacing
    hy = 1.0/(n-1) # y grid spacing
    diagv = 2.0*hy/hx + 2.0*hx/hy
    offdx = -1.0*hy/hx
    offdy = -1.0*hx/hy
    Istart, Iend = A.getOwnershipRange()
    for I in range(Istart, Iend) :
        A[I,I] = diagv
        i = I//n    # map row number to
        j = I - i*n # grid coordinates
        if i> 0  : J = I-n; A[I,J] = offdx
        if i< m-1: J = I+n; A[I,J] = offdx
        if j> 0  : J = I-1; A[I,J] = offdy
        if j< n-1: J = I+1; A[I,J] = offdy
    A.assemble()
    return A

Then this next function takes the matrix plus the problem type, solves the eigenvalue problem, and prints info about the computed solution. Even though we know the eigenvalues and eigenvectors are real in this example, the function is set up to solve it as a non-symmetric problem, by passing SLEPc.EPS.ProblemType.NHEP <#slepc4py.SLEPc.EPS.ProblemType.NHEP> โ€” which is exactly why the code handles possibly complex eigenvalues and eigenvectors:

def solve_eigensystem(A, problem_type=SLEPc.EPS.ProblemType.HEP):
    # Create the result vectors
    xr, xi = A.createVecs()

    # Setup the eigensolver
    E = SLEPc.EPS().create()
    E.setOperators(A,None)
    E.setDimensions(3,PETSc.DECIDE)
    E.setProblemType(problem_type)
    E.setFromOptions()

    # Solve the eigensystem
    E.solve()

    Print("")
    its = E.getIterationNumber()
    Print("Number of iterations of the method: %i" % its)
    sol_type = E.getType()
    Print("Solution method: %s" % sol_type)
    nev, ncv, mpd = E.getDimensions()
    Print("Number of requested eigenvalues: %i" % nev)
    tol, maxit = E.getTolerances()
    Print("Stopping condition: tol=%.4g, maxit=%d" % (tol, maxit))
    nconv = E.getConverged()
    Print("Number of converged eigenpairs: %d" % nconv)
    if nconv > 0:
        Print("")
        Print("        k          ||Ax-kx||/||kx|| ")
        Print("----------------- ------------------")
        for i in range(nconv):
            k = E.getEigenpair(i, xr, xi)
            error = E.computeError(i)
            if k.imag != 0.0:
              Print(" %9f%+9f j  %12g" % (k.real, k.imag, error))
            else:
              Print(" %12f       %12g" % (k.real, error))
        Print("")

And the main program? It just processes three user-defined command-line options and calls the other two functions. Periodt.

def main():
    opts = PETSc.Options()
    N = opts.getInt('N', 32)
    m = opts.getInt('m', N)
    n = opts.getInt('n', m)
    Print("Symmetric Eigenproblem (sparse matrix), "
          "N=%d (%dx%d grid)" % (m*n, m, n))
    A = construct_operator(m,n)
    solve_eigensystem(A)

if __name__ == '__main__':
    main()

๐ŸŽ€ ex3.py: Matrix-free eigenproblem for the 2-D Laplacian ๐ŸŽ€

This example solves the eigenproblem for the 2-D discrete Laplacian without building the matrix explicitly. Matrix-free, bestie. No matrix, no problem. ๐Ÿ’€

<style>... actually no, I don't use that.</style>

The full source code for this demo can be downloaded at ../_static/ex3.py.

Setting up is literally the same vibe as all the other examples, no notes.

import sys, slepc4py
slepc4py.init(sys.argv)

from petsc4py import PETSc
from slepc4py import SLEPc
import numpy as np

Okay so bestie, this one cannot run in parallel, so we check that the number of MPI processes is exactly 1. If you wanna enable parallelism you'd have to implement a parallel matrix-vector operation yourself, and that is not what this example does. ๐Ÿ’…

assert PETSc.COMM_WORLD.getSize() == 1

Print = PETSc.Sys.Print

This next function computes the matrix-vector product f = L*x where the Laplacian L is not built explicitly, and the vectors x,f get viewed as two-dimensional arrays associated to grid points. Iconic matrix-free behavior, we love to see it. ๐Ÿฆ‹

def laplace2d(U, x, f):
    U[:,:] = 0
    U[1:-1, 1:-1] = x
    # Grid spacing
    m, n = x.shape
    hx = 1.0/(m-1) # x grid spacing
    hy = 1.0/(n-1) # y grid spacing
    # Setup 5-points stencil
    u  = U[1:-1, 1:-1] # center
    uN = U[1:-1,  :-2] # north
    uS = U[1:-1, 2:  ] # south
    uW = U[ :-2, 1:-1] # west
    uE = U[2:,   1:-1] # east
    # Apply Laplacian
    f[:,:] = \
         (2*u - uE - uW) * (hy/hx) \
       + (2*u - uN - uS) * (hx/hy) \

So for a matrix-free solution in slepc4py, we have to make a class that wraps the matrix-vector operation and optionally other operations of the matrix. In this case we're only giving it the constructor and the mult operation, which just calls the laplace2d function from above. Periodt.

class Laplacian2D(object):

    def __init__(self, m, n):
        self.m, self.n = m, n
        scalar = PETSc.ScalarType
        self.U = np.zeros([m+2, n+2], dtype=scalar)

    def mult(self, A, x, y):
        m, n = self.m, self.n
        xx = x.getArray(readonly=1).reshape(m,n)
        yy = y.getArray(readonly=0).reshape(m,n)
        laplace2d(self.U, xx, yy)

Building the matrix here literally just means making an object of the class we defined and handing it to a special petsc4py matrix via createPython() (link to the petsc4py PETSc.Mat.createPython reference, iykyk). ๐ŸŒˆ

def construct_operator(m, n):
    # Create shell matrix
    context = Laplacian2D(m,n)
    A = PETSc.Mat().createPython([m*n,m*n], context)
    return A

This function takes the matrix and the problem type, then solves the eigenvalue problem and prints the deets about the computed solution. Even though we know the eigenvalues and eigenvectors are real in this example, the function is still ready to solve it as a non-symmetric problem โ€” it does that by passing SLEPc.EPS.ProblemType.NHEP, which is exactly why the code deals with possibly complex eigenvalues and eigenvectors. Prepared queen. ๐Ÿ‘‘

def solve_eigensystem(A, problem_type=SLEPc.EPS.ProblemType.HEP):
    # Create the result vectors
    xr, xi = A.createVecs()

    # Setup the eigensolver
    E = SLEPc.EPS().create()
    E.setOperators(A,None)
    E.setDimensions(3,PETSc.DECIDE)
    E.setProblemType(problem_type)
    E.setFromOptions()

    # Solve the eigensystem
    E.solve()
    Print("")
    its = E.getIterationNumber()
    Print("Number of iterations of the method: %i" % its)
    sol_type = E.getType()
    Print("Solution method: %s" % sol_type)
    nev, ncv, mpd = E.getDimensions()
    Print("Number of requested eigenvalues: %i" % nev)
    tol, maxit = E.getTolerances()
    Print("Stopping condition: tol=%.4g, maxit=%d" % (tol, maxit))
    nconv = E.getConverged()
    Print("Number of converged eigenpairs: %d" % nconv)
    if nconv > 0:
        Print("")
        Print("        k          ||Ax-kx||/||kx|| ")
        Print("----------------- ------------------")
        for i in range(nconv):
            k = E.getEigenpair(i, xr, xi)
            error = E.computeError(i)
            if k.imag != 0.0:
              Print(" %9f%+9f j  %12g" % (k.real, k.imag, error))
            else:
              Print(" %12f       %12g" % (k.real, error))
        Print("")

And the main program is just doing the most: it reads three user-defined command-line options and calls the other two functions. Slay.

def main():
    opts = PETSc.Options()
    N = opts.getInt('N', 32)
    m = opts.getInt('m', N)
    n = opts.getInt('n', m)
    Print("Symmetric Eigenproblem (matrix-free), "
          "N=%d (%dx%d grid)" % (m*n, m, n))
    A = construct_operator(m,n)
    solve_eigensystem(A)

if __name__ == '__main__':
    main()

๐ŸŒธ ex4.py: Singular value decomposition of the Lauchli matrix ๐ŸŒธ

This example shows off the SVD solver in slepc4py. It computes the singular values and vectors of the Lauchli matrix, whose condition number depends on a parameter mu. ๐ŸŽ€

The full source code for this demo can be downloaded at ../_static/ex4.py.

Initialization is the same as before, bestie.

try: range = xrange
except: pass

import sys, slepc4py
slepc4py.init(sys.argv)

from petsc4py import PETSc
from slepc4py import SLEPc

This example takes two command-line arguments: the matrix size n and the mu parameter.

opts = PETSc.Options()
n  = opts.getInt('n', 30)
mu = opts.getReal('mu', 1e-6)

PETSc.Sys.Print( "Lauchli singular value decomposition, (%d x %d) mu=%g\n" % (n+1,n,mu) )

Time to create the matrix and fill in its nonzero entries. Every MPI process will insert only its locally owned part, and that's the whole point. ๐Ÿซถ

A = PETSc.Mat(); A.create()
A.setSizes([n+1, n])
A.setFromOptions()

rstart, rend = A.getOwnershipRange()

for i in range(rstart, rend):
  if i==0:
    for j in range(n):
      A[0,j] = 1.0
  else:
    A[i,i-1] = mu

A.assemble()

The singular value solver works just like the eigensolver from the previous examples. Here we pick the thick-restart Lanczos bidiagonalization method, which is a whole mood. โœจ

S = SLEPc.SVD(); S.create()

S.setOperator(A)
S.setType(S.Type.TRLANCZOS)
S.setFromOptions()

S.solve()

After solve, we print out the informative stuff and pull the computed solution, showing off the list of singular values and their corresponding residual errors. Ate.

Print = PETSc.Sys.Print

Print( "******************************" )
Print( "*** SLEPc Solution Results ***" )
Print( "******************************\n" )

svd_type = S.getType()
Print( "Solution method: %s" % svd_type )

its = S.getIterationNumber()
Print( "Number of iterations of the method: %d" % its )

nsv, ncv, mpd = S.getDimensions()
Print( "Number of requested singular values: %d" % nsv )

tol, maxit = S.getTolerances()
Print( "Stopping condition: tol=%.4g, maxit=%d" % (tol, maxit) )

nconv = S.getConverged()
Print( "Number of converged approximate singular triplets %d" % nconv )

if nconv > 0:
  v, u = A.createVecs()
  Print()
  Print("    sigma       residual norm ")
  Print("-------------  ---------------")
  for i in range(nconv):
    sigma = S.getSingularTriplet(i, u, v)
    error = S.computeError(i)
    Print( "   %6f     %12g" % (sigma, error) )
  Print()

๐Ÿฆ‹ ex5.py: Simple quadratic eigenvalue problem ๐Ÿฆ‹

This example solves a polynomial eigenvalue problem of degree 2, aka the one you find most often in real applications. Bigger-degree polynomials get handled the same way. The coefficient matrices in this example do not come from an application โ€” they're just simple matrices that are easy to build, purely to illustrate how it works. And ngl, the eigenvalues in this example are purely imaginary and come in conjugate pairs. ๐Ÿ˜ญ

The full source code for this demo can be downloaded at ../_static/ex5.py.

Initialization, once again, same as always.

import sys, slepc4py
slepc4py.init(sys.argv)

from petsc4py import PETSc
from slepc4py import SLEPc

Print = PETSc.Sys.Print

Here's a function to build the matrices. The lowest degree coefficient is the 2-D Laplacian, the highest degree one is the identity matrix, and the other matrix is set to zero โ€” which means this problem could totally have been solved as a linear eigenproblem. No cap.

def construct_operators(m,n):
    Print("Quadratic Eigenproblem, N=%d (%dx%d grid)"% (m*n, m, n))
    # K is the 2-D Laplacian
    K = PETSc.Mat().create()
    K.setSizes([n*m, n*m])
    K.setFromOptions()
    Istart, Iend = K.getOwnershipRange()
    for I in range(Istart,Iend):
        v = -1.0; i = I//n; j = I-i*n;
        if i>0:
            J=I-n; K[I,J] = v
        if i<m-1:
            J=I+n; K[I,J] = v
        if j>0:
            J=I-1; K[I,J] = v
        if j<n-1:
            J=I+1; K[I,J] = v
        v=4.0; K[I,I] = v
    K.assemble()
    # C is the zero matrix
    C = PETSc.Mat().create()
    C.setSizes([n*m, n*m])
    C.setFromOptions()
    C.assemble()
    # M is the identity matrix
    M = PETSc.Mat().createConstantDiagonal([n*m, n*m], 1.0)

    return M, C, K

The polynomial eigenvalue solver is similar to the linear eigensolver from the previous examples. The one big difference? You must provide a list of matrices, going from lowest to highest degree. ๐Ÿ”ฅ

def solve_eigensystem(M, C, K):
    # Setup the eigensolver
    Q = SLEPc.PEP().create()
    Q.setOperators([K, C, M])
    Q.setDimensions(6)
    Q.setProblemType(SLEPc.PEP.ProblemType.GENERAL)
    Q.setFromOptions()
    # Solve the eigensystem
    Q.solve()
    # Create the result vectors
    xr, xi = K.createVecs()

...and then we spill all the tea about what the solver actually did ๐Ÿ’…:

              its = Q.getIterationNumber()
              Print("Number of iterations of the method: %i" % its)
              sol_type = Q.getType()
              Print("Solution method: %s" % sol_type)
              nev, ncv, mpd = Q.getDimensions()
              Print("")
              Print("Number of requested eigenvalues: %i" % nev)
              tol, maxit = Q.getTolerances()
              Print("Stopping condition: tol=%.4g, maxit=%d" % (tol, maxit))
              nconv = Q.getConverged()
              Print("Number of converged approximate eigenpairs: %d" % nconv)
              if nconv > 0:
                  Print("")
                  Print("          k           ||(k^2M+Ck+K)x||/||kx|| ")
                  Print("-------------------- -------------------------")
                  for i in range(nconv):
                      k = Q.getEigenpair(i, xr, xi)
                      error = Q.computeError(i)
                      if k.imag != 0.0:
                          Print("%9f%+9f j    %12g" % (k.real, k.imag, error))
                      else:
                          Print("%12f         %12g" % (k.real, error))
              Print("")

The main program is doing the absolute least, honestly, and we love that for it ๐Ÿซถ โ€” it just grabs two user-defined command-line options (the dimensions of the mesh) and calls the other two functions.

          if __name__ == '__main__':
              opts = PETSc.Options()
              m = opts.getInt('m', 32)
              n = opts.getInt('n', m)
              M, C, K = construct_operators(m,n)
              solve_eigensystem(M, C, K)
              M = C = K = None

โœจ ex6.py: Compute exp(t*A)*v for a matrix from a Markov model โœจ

This example is showing off the matrix-function functionality in slepc4py โ€” or, to be more precise, applying a matrix function to a given vector. It works with the exponential function, which is like the most commonly found one in applications, no cap.

The main character of slepc4py is the eigenvalue and singular value problem, bestie, but it also has some codes for dealing with matrix functions โ€” which sometimes show up in the context of eigenproblems, but also have interest all on their own. ๐ŸŒธ

The full source code for this demo can be downloaded here: ../_static/ex6.py.

Initialization is the same vibe as the previous examples.

          import sys, slepc4py
          slepc4py.init(sys.argv)

          from petsc4py import PETSc
          from slepc4py import SLEPc

          Print = PETSc.Sys.Print

This function builds a matrix that implements a Markov model of a random walk on a triangular grid. The entries of the matrix represent probabilities of moving to neighboring cells in the grid. ๐ŸŽฒ

          def build_matrix(m):
              N = m*(m+1)/2
              Print("Markov y=exp(t*A)*e_1, N=%d (m=%d)"% (N, m))
              A = PETSc.Mat().create()
              A.setSizes([N, N])
              A.setFromOptions()
              Istart, Iend = A.getOwnershipRange()
              ix = 0
              cst = 0.5/(m-1)
              for i in range(1,m+1):
                 jmax = m-i+1
                 for j in range(1,jmax+1):
                     ix = ix + 1
                     if ix-1<Istart or ix>Iend:
                         continue  # compute only owned rows
                     if j!=jmax:
                         pd = cst*(i+j-1)
                         # north
                         if i==1:
                             A[ix-1,ix] = 2*pd
                         else:
                             A[ix-1,ix] = pd
                         # east
                         if j==1:
                             A[ix-1,ix+jmax-1] = 2*pd
                         else:
                             A[ix-1,ix+jmax-1] = pd
                     # south
                     pu = 0.5 - cst*(i+j-3)
                     if j>1:
                         A[ix-1,ix-2] = pu
                     # west
                     if i>1:
                         A[ix-1,ix-jmax-2] = pu

              A.assemble()
              return A

The following function solves the problem. This case is quite different from eigenproblems โ€” it's way more similar to solving a linear system of equations with KSP (https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.KSP.html#petsc4py.PETSc.KSP). To configure the problem we have to hand over the matrix and the function (the exponential in this case). Notice how the internal FN object (slepc4py.SLEPc.FN) is extracted from the MFN solver (slepc4py.SLEPc.MFN). Also, it's often necessary to specify a scale factor, which here represents the time for which we want to obtain the evolved state. Once the solver is set up, we call solve() (slepc4py.SLEPc.MFN.solve), passing the right-hand side vector b and the solution vector x. ๐Ÿ’ซ

          def solve_exp(t, A, b, x):
              # Setup the solver
              M = SLEPc.MFN().create()
              M.setOperator(A)
              f = M.getFN()
              f.setType(SLEPc.FN.Type.EXP)
              f.setScale(t)
              M.setTolerances(1e-7)
              M.setFromOptions()
              # Solve the problem
              M.solve(b,x)

              its = M.getIterationNumber()
              Print("Number of iterations of the method: %i" % its)
              sol_type = M.getType()
              Print("Solution method: %s" % sol_type)
              ncv = M.getDimensions()
              Print("")
              Print("Subspace dimension: %i" % ncv)
              tol, maxit = M.getTolerances()
              Print("Stopping condition: tol=%.4g, maxit=%d" % (tol, maxit))
              Print("Computed vector at time t=%.4g has norm %g" % (t.real, x.norm()))
              Print("")

The main program handles the command-line option m (size of the grid), builds the matrix and calls the solver. Note how the vectors are created from the matrix. In this case, the right-hand side vector is the first element of the canonical basis. ๐Ÿ‘‘

          if __name__ == '__main__':
              opts = PETSc.Options()
              m = opts.getInt('m', 15)
              A = build_matrix(m)   # transition probability matrix
              x, b = A.createVecs()
              x.set(0)
              b.set(0)
              b[0] = 1
              b.assemble()
              t = 2
              solve_exp(t, A, b, x)    # compute x=exp(t*A)*b
              A = None
              b = x = None

๐ŸŒˆ ex7.py: Nonlinear eigenproblem with callback functions ๐ŸŒˆ

This example solves a nonlinear eigenvalue problem that comes from the discretization of a PDE on a one-dimensional domain with finite differences. The nonlinearity is giving boundary conditions, fr fr. The PDE is

                               -u'' = \lambda u

defined on the interval [0,1] and subject to the boundary conditions

       u(0)=0, u'(1)=u(1)\lambda\frac{\kappa}{\kappa-\lambda},

where \lambda is the eigenvalue and \kappa is a parameter. ๐Ÿฆ‹

The full source code for this demo can be downloaded here: ../_static/ex7.py.

Initialization is similar to previous examples.

          import sys, slepc4py
          slepc4py.init(sys.argv)

          from petsc4py import PETSc
          from slepc4py import SLEPc
          from numpy import sqrt, sin

          Print = PETSc.Sys.Print

When implementing a nonlinear eigenproblem with callback functions we must provide code that builds the function matrix T(\lambda) for a given \lambda, and optionally the Jacobian matrix T'(\lambda) โ€” that's the derivative with respect to the eigenvalue. โœจ

In slepc4py the callbacks are integrated in a class. In this example, apart from the constructor, we have three methods:

  • formFunction to fill the function matrix F. Note that F is received as an argument and we just need to fill its entries using the value of the parameter mu. Matrix B is used to build the preconditioner, and is usually equal to F.
  • formJacobian to fill the Jacobian matrix J. Some eigensolvers do not need this, but it is recommended to implement it.
  • checkSolution is just a convenience method to check that a given solution satisfies the PDE. ๐Ÿ™ˆ
          class MyPDE(object):

              def __init__(self, kappa, h):
                  self.kappa = kappa
                  self.h     = h

              def formFunction(self, nep, mu, F, B):
                  n, m = F.getSize()
                  Istart, Iend = F.getOwnershipRange()
                  i1 = Istart
                  if Istart==0: i1 = i1 + 1
                  i2 = Iend
                  if Iend==n: i2 = i2 - 1
                  h = self.h
                  c = self.kappa/(mu-self.kappa)
                  d = n

                  # Interior grid points
                  for i in range(i1,i2):
                      val = -d-mu*h/6.0
                      F[i,i-1] = val
                      F[i,i]   = 2.0*(d-mu*h/3.0)
                      F[i,i+1] = val

                  # Boundary points
                  if Istart==0:
                      F[0,0] = 2.0*(d-mu*h/3.0)
                      F[0,1] = -d-mu*h/6.0
                  if Iend==n:
                      F[n-1,n-2] = -d-mu*h/6.0
                      F[n-1,n-1] = d-mu*h/3.0+mu*c

                  F.assemble()
                  if B != F: B.assemble()
                  return PETSc.Mat.Structure.SAME_NONZERO_PATTERN

              def formJacobian(self, nep, mu, J):
                  n, m = J.getSize()
                  Istart, Iend = J.getOwnershipRange()
                  i1 = Istart
                  if Istart==0: i1 = i1 + 1
                  i2 = Iend
                  if Iend==n: i2 = i2 - 1
                  h = self.h
                  c = self.kappa/(mu-self.kappa)

                  # Interior grid points
                  for i in range(i1,i2):
                      J[i,i-1] = -h/6.0
                      J[i,i]   = -2.0*h/3.0
                      J[i,i+1] = -h/6.0

                  # Boundary points
                  if Istart==0:
                      J[0,0] = -2.0*h/3.0
                      J[0,1] = -h/6.0
                  if Iend==n:
                      J[n-1,n-2] = -h/6.0
                      J[n-1,n-1] = -h/3.0-c*c

                  J.assemble()
                  return PETSc.Mat.Structure.SAME_NONZERO_PATTERN

              def checkSolution(self, mu, y):
                  nu = sqrt(mu)
                  u = y.duplicate()
                  n = u.getSize()
                  Istart, Iend = J.getOwnershipRange()
                  h = self.h
                  for i in range(Istart,Iend):
                      x = (i+1)*h
                      u[i] = sin(nu*x);
                  u.assemble()
                  u.normalize()
                  u.axpy(-1.0,y)
                  return u.norm()

We use an auxiliary function FixSign to force the computed eigenfunction to be real and positive, since some eigensolvers may return the eigenvector multiplied by a complex number of modulus one. ๐Ÿ’…

          def FixSign(x):
              comm = x.getComm()
              rank = comm.getRank()
              n = 1 if rank == 0 else 0
              aux = PETSc.Vec().createMPI((n, PETSc.DECIDE), comm=comm)
              if rank == 0: aux[0] = x[0]
              aux.assemble()
              x0 = aux.sum()
              sign = x0/abs(x0)
              x.scale(1.0/sign)

The main program processes two command-line options, n (size of the grid) and kappa (the parameter of the PDE), then creates an object of the class we defined earlier. ๐ŸŽ€

          opts = PETSc.Options()
          n = opts.getInt('n', 128)
          kappa = opts.getReal('kappa', 1.0)
          pde = MyPDE(kappa, 1.0/n)

In order to set up the solver we have to pass the two callback functions (methods of the class) together with the matrix objects that will be used every time these methods are called. In this simple example we can do a preallocation of the matrices, although this is not necessary.

nep = SLEPc.NEP().create()
F = PETSc.Mat().create()
F.setSizes([n, n])
F.setType('aij')
F.setPreallocationNNZ(3)
nep.setFunction(pde.formFunction, F)

J = PETSc.Mat().create()
J.setSizes([n, n])
J.setType('aij')
J.setPreallocationNNZ(3)
nep.setJacobian(pde.formJacobian, J)

bestie look at that preallocation, we're being so tidy and organised ๐Ÿ’…

After setting some options, we can solve the problem. Here we also illustrate how to pass an initial guess to the solver.

nep.setTolerances(tol=1e-9)
nep.setDimensions(1)
nep.setFromOptions()

x = F.createVecs('right')
x.set(1.0)
nep.setInitialSpace(x)
nep.solve()
not me setting the whole vector to 1.0 as the initial space, main character energy โœจ

Once the solver has finished, we print some information together with the computed solution. For each computed eigenpair, we print the residual norm and also the error estimated with the class method checkSolution.

its = nep.getIterationNumber()
Print("Number of iterations of the method: %i" % its)
sol_type = nep.getType()
Print("Solution method: %s" % sol_type)
nev, ncv, mpd = nep.getDimensions()
Print("")
Print("Subspace dimension: %i" % ncv)
tol, maxit = nep.getTolerances()
Print("Stopping condition: tol=%.4g" % tol)
Print("")

nconv = nep.getConverged()
Print( "Number of converged eigenpairs %d" % nconv )

if nconv > 0:
  Print()
  Print("        k              ||T(k)x||          error ")
  Print("----------------- ------------------ ------------------")
  for i in range(nconv):
    k = nep.getEigenpair(i, x)
    FixSign(x)
    res = nep.computeError(i)
    error = pde.checkSolution(k.real, x)
    if k.imag != 0.0:
      Print( " %9f%+9f j %12g     %12g" % (k.real, k.imag, res, error) )
    else:
      Print( " %12f       %12g     %12g" % (k.real, res, error) )
  Print()

๐Ÿฆ‹ ex8.py: Nonlinear eigenproblem with split form ๐Ÿฆ‹

This example solves a nonlinear eigenvalue problem where the nonlinear function is expressed in split form.

We want to solve the following parabolic partial differential equation with time delay \tau

               u_t    &= u_{xx} + a u(t) + b u(t-\tau) \\
u(0,t) &= u(\pi,t) = 0

with a = 20 and b(x) = -4.1+x (1-e^{x-\pi}).

the way this is a whole PDE turning into a nonlinear eigenproblem... Discretization leads to a DDE of dimension n

                       -u' = A u(t) + B u(t-\tau)

which results in the nonlinear eigenproblem

               (-\lambda I + A + e^{-\tau\lambda}B)u = 0.

The full source code for this demo can be downloaded here <../_static/ex8.py>.

Initialization is similar to previous examples. In this case we also need to import some math symbols.

import sys, slepc4py
slepc4py.init(sys.argv)

from petsc4py import PETSc
from slepc4py import SLEPc
from numpy import exp
from math import pi

Print = PETSc.Sys.Print

This script has two command-line options: the discretization size n and the time delay tau.

opts = PETSc.Options()
n = opts.getInt('n', 128)
tau = opts.getReal('tau', 0.001)
a = 20
h = pi/(n+1)

Next we have to set up the solver. In this case, we are going to represent the nonlinear problem in split form, i.e., as a sum of terms made of a constant matrix multiplied by a scalar nonlinear function.

nep = SLEPc.NEP().create()

The first term involves the identity matrix.

Id = PETSc.Mat().createConstantDiagonal([n, n], 1.0)

The second term has a tridiagonal matrix obtained from the discretization, A = \frac{1}{h^2}\operatorname{tridiag}(1,-2,1) + a I.

A = PETSc.Mat().create()
A.setSizes([n, n])
A.setFromOptions()
rstart, rend = A.getOwnershipRange()
vd = -2.0/(h*h)+a
vo = 1.0/(h*h)
if rstart == 0:
  A[0, :2] = [vd, vo]
  rstart += 1
if rend == n:
  A[n-1, -2:] = [vo, vd]
  rend -= 1
for i in range(rstart, rend):
  A[i, i-1:i+2] = [vo, vd, vo]
A.assemble()

The third term includes a diagonal matrix B = \operatorname{diag}(b(x_i)).

B = PETSc.Mat().create()
B.setSizes([n, n])
B.setFromOptions()
rstart, rend = B.getOwnershipRange()
for i in range(rstart, rend):
  xi = (i+1)*h
  B[i, i] = -4.1+xi*(1.0-exp(xi-pi));
B.assemble()
B.setOption(PETSc.Mat.Option.HERMITIAN, True)

<cute>B.setOption(PETSc.Mat.Option.HERMITIAN, True) โ€” flagging the vibe of that matrix, iconic ๐Ÿ’–</cute>

Apart from the matrices, we have to create the functions, represented with FN objects (the slepc4py.SLEPc.FN class): f_1=-\lambda, f_2=1, f_3=\exp(-\tau\lambda).

f1 = SLEPc.FN().create()
f1.setType(SLEPc.FN.Type.RATIONAL)
f1.setRationalNumerator([-1, 0])
f2 = SLEPc.FN().create()
f2.setType(SLEPc.FN.Type.RATIONAL)
f2.setRationalNumerator([1])
f3 = SLEPc.FN().create()
f3.setType(SLEPc.FN.Type.EXP)
f3.setScale(-tau)

Put all the information together to define the split operator. Note that A is passed first so that SUBSET (petsc4py.PETSc.Mat.Structure.SUBSET) nonzero_pattern can be used.

nep.setSplitOperator([A, Id, B], [f2, f1, f3], PETSc.Mat.Structure.SUBSET)

Now we can set some options and call the solver.

nep.setTolerances(tol=1e-9)
nep.setDimensions(1)
nep.setFromOptions()

nep.solve()

Once the solver has finished, we print some information together with the computed solution. For each computed eigenpair, we print the eigenvalue and the residual norm.

its = nep.getIterationNumber()
Print("Number of iterations of the method: %i" % its)
sol_type = nep.getType()
Print("Solution method: %s" % sol_type)
nev, ncv, mpd = nep.getDimensions()
Print("")
Print("Subspace dimension: %i" % ncv)
tol, maxit = nep.getTolerances()
Print("Stopping condition: tol=%.4g" % tol)
Print("")

nconv = nep.getConverged()
Print( "Number of converged eigenpairs %d" % nconv )

if nconv > 0:
  x = Id.createVecs('right')
  x.set(1.0)
  Print()
  Print("        k              ||T(k)x||")
  Print("----------------- ------------------")
  for i in range(nconv):
    k = nep.getEigenpair(i, x)
    res = nep.computeError(i)
    if k.imag != 0.0:
      Print( " %9f%+9f j %12g" % (k.real, k.imag, res) )
    else:
      Print( " %12f       %12g" % (k.real, res) )
  Print()

๐ŸŒˆ ex9.py: Generalized symmetric-definite eigenproblem ๐ŸŒˆ

This example computes eigenvalues and eigenvectors of a generalized symmetric-definite eigenvalue problem, where the first matrix is the discrete Laplacian in two dimensions and the second matrix is quasi diagonal.

The full source code for this demo can be downloaded here <../_static/ex9.py>.

Initialization is similar to previous examples.

try: range = xrange
except: pass

import sys, slepc4py
slepc4py.init(sys.argv)

from petsc4py import PETSc
from slepc4py import SLEPc

Print = PETSc.Sys.Print

This function builds the discretized Laplacian operator in 2 dimensions.

def Laplacian2D(m, n):
    # Create matrix for 2D Laplacian operator
    A = PETSc.Mat().create()
    A.setSizes([m*n, m*n])
    A.setFromOptions()
    # Fill matrix
    hx = 1.0/(m-1) # x grid spacing
    hy = 1.0/(n-1) # y grid spacing
    diagv = 2.0*hy/hx + 2.0*hx/hy
    offdx = -1.0*hy/hx
    offdy = -1.0*hx/hy
    Istart, Iend = A.getOwnershipRange()
    for I in range(Istart, Iend):
        A[I,I] = diagv
        i = I//n    # map row number to
        j = I - i*n # grid coordinates
        if i> 0  : J = I-n; A[I,J] = offdx
        if i< m-1: J = I+n; A[I,J] = offdx
        if j> 0  : J = I-1; A[I,J] = offdy
        if j< n-1: J = I+1; A[I,J] = offdy
    A.assemble()
    return A

This function builds a quasi-diagonal matrix. It is two times the identity matrix except for the 2x2 leading submatrix [6 -1; -1 1].

def QuasiDiagonal(N):
    # Create matrix
    B = PETSc.Mat().create()
    B.setSizes([N, N])
    B.setFromOptions()
    # Fill matrix
    Istart, Iend = B.getOwnershipRange()
    for I in range(Istart, Iend):
        B[I,I] = 2.0
    if Istart==0:
        B[0,0] = 6.0
        B[0,1] = -1.0
        B[1,0] = -1.0
        B[1,1] = 1.0
    B.assemble()
    return B

The following function receives the two matrices and solves the eigenproblem. In this example we illustrate how to pass objects that have been created beforehand, instead of extracting the internal objects. We are using a spectral transformation of type ST.Type.PRECOND and a Block Jacobi preconditioner. We want to compute the leftmost eigenvalues. The selected eigensolver is LOBPCG, which is appropriate for this use case. After the solve, we print the computed solution.

def solve_eigensystem(A, B, problem_type=SLEPc.EPS.ProblemType.GHEP):
    # Create the results vectors
    xr, xi = A.createVecs()

    pc = PETSc.PC().create()
    # pc.setType(pc.Type.HYPRE)
    pc.setType(pc.Type.BJACOBI)

    ksp = PETSc.KSP().create()
    ksp.setType(ksp.Type.PREONLY)
    ksp.setPC( pc )

    F = SLEPc.ST().create()
    F.setType(F.Type.PRECOND)
    F.setKSP( ksp )
    F.setShift(0)

    # Setup the eigensolver
    E = SLEPc.EPS().create()
    E.setST(F)
    E.setOperators(A,B)
    E.setType(E.Type.LOBPCG)
    E.setDimensions(10,PETSc.DECIDE)
    E.setWhichEigenpairs(E.Which.SMALLEST_REAL)
    E.setProblemType( problem_type )
    E.setFromOptions()

    # Solve the eigensystem
    E.solve()

okay but the commented-out # pc.setType(pc.Type.HYPRE) line is still living there rent free ๐Ÿ™ˆ

...picking right back up inside that example, right where we're actually looking at what the solver found ๐Ÿ‘€โœจ

Print("")
its = E.getIterationNumber()
Print("Number of iterations of the method: %i" % its)
sol_type = E.getType()
Print("Solution method: %s" % sol_type)
nev, ncv, mpd = E.getDimensions()
Print("Number of requested eigenvalues: %i" % nev)
tol, maxit = E.getTolerances()
Print("Stopping condition: tol=%.4g, maxit=%d" % (tol, maxit))
nconv = E.getConverged()
Print("Number of converged eigenpairs: %d" % nconv)
if nconv > 0:
    Print("")
    Print("        k          ||Ax-kx||/||kx|| ")
    Print("----------------- ------------------")
    for i in range(nconv):
        k = E.getEigenpair(i, xr, xi)
        error = E.computeError(i)
        if k.imag != 0.0:
          Print(" %9f%+9f j  %12g" % (k.real, k.imag, error))
        else:
          Print(" %12f       %12g" % (k.real, error))
    Print("")

And then main is literally just doing the absolute bare minimum, no cap โ€” it grabs three command-line options you define yourself and hands off to the other functions ๐Ÿซถ

def main():
    opts = PETSc.Options()
    N = opts.getInt('N', 10)
    m = opts.getInt('m', N)
    n = opts.getInt('n', m)
    Print("Symmetric-definite Eigenproblem, N=%d (%dx%d grid)" % (m*n, m, n))
    A = Laplacian2D(m,n)
    B = QuasiDiagonal(m*n)
    solve_eigensystem(A,B)

if __name__ == '__main__':
    main()

๐Ÿฆ‹ ex10.py: Laplace problem using the Proper Orthogonal Decomposition ๐Ÿฆ‹

okay so THIS one is doing the Laplace problem but with the Proper Orthogonal Decomposition (POD) reduced-order modeling technique ๐Ÿ’… and if you want the full academic lore on how the technique works, the reader is referred to [1], [2] โ€” the source material said so and we respect it โœจ

The whole thing gets split into an offline phase (the computationally intensive one, the one that does the work ๐Ÿ’ช) and an online phase (the computationally cheap one, the little guy ๐Ÿฅบ). Why would you bother? Because this has so many applications: real-time simulation, uncertainty quantification, and inverse problems โ€” literally any situation where similar models have to get evaluated fast and a bunch of times. it's giving "build once, reuse forever" ๐ŸŒˆ

Offline phase:

  1. A set of solution snapshots of the 1D Laplace problem in the full problem space are constructed and assembled into the columns of a dense matrix S.
  2. A standard eigenvalue decomposition is performed on the matrix S^T S.
  3. The eigenvectors and eigenvalues are projected back to the original eigenvalue problem S.
  4. The leading eigenvectors then form the POD basis.

Online phase:

  1. The operator corresponding to the discrete Laplacian is projected onto the POD basis.
  2. The operator corresponding to the right-hand side is projected onto the POD basis.
  3. The reduced (dense) problem expressed in the POD basis is solved.
  4. The reduced solution is projected back to the full problem space.

Contributed by: Elisa Schenone, Jack S. Hale.

The full source code for this demo can be downloaded here <../_static/ex10.py> โฌ‡๏ธ

Initialization is basically the same vibe as the previous examples, except we're importing some extra modules on top ๐ŸŒธ

try: range = xrange
except: pass

import sys, slepc4py
slepc4py.init(sys.argv)

from petsc4py import PETSc
from slepc4py import SLEPc
import numpy

import random
import math

This next function builds the discrete Laplacian operator in 1 dimension with homogeneous Dirichlet boundary conditions โœจ (yes the boundary conditions are the whole personality of it)

def construct_operator(m):
    # Create matrix for 1D Laplacian operator
    A = PETSc.Mat().create(PETSc.COMM_SELF)
    A.setSizes([m, m])
    A.setFromOptions()
    # Fill matrix
    hx = 1.0/(m-1) # x grid spacing
    diagv = 2.0/hx
    offdx = -1.0/hx
    Istart, Iend = A.getOwnershipRange()
    for i in range(Istart, Iend):
        if i != 0 and i != (m - 1):
            A[i, i] = diagv
            if i > 1: A[i, i - 1] = offdx
            if i < m - 2: A[i, i + 1] = offdx
        else:
            A[i, i] = 1.

    A.assemble()

    return A

Then we set a bell-shape function as the solution of the Laplacian problem in 1 dimension with homogeneous Dirichlet boundary conditions, and compute the associated discrete RHS ๐Ÿ””

def set_problem_rhs(m):
    # Create 1D mass matrix operator
    M = PETSc.Mat().create(PETSc.COMM_SELF)
    M.setSizes([m, m])
    M.setFromOptions()
    # Fill matrix
    hx = 1.0/(m-1) # x grid spacing
    diagv = hx/3
    offdx = hx/6
    Istart, Iend = M.getOwnershipRange()
    for i in range(Istart, Iend):
        if i != 0 and i != (m - 1):
            M[i, i] = 2*diagv
        else:
            M[i, i] = diagv
        if i > 1: M[i, i - 1] = offdx
        if i < m - 2: M[i, i + 1] = offdx

    M.assemble()

    x_0 = 0.3
    x_f = 0.7
    mu = x_0 + (x_f - x_0)*random.random()
    sigma = 0.1**2
    uex, f = M.createVecs()
    for j in range(Istart, Iend):
        value = 2/sigma * math.exp(-(hx*j - mu)**2/sigma) * (1 - 2/sigma * (hx*j - mu)**2 )
        f.setValue(j, value)
        value = math.exp(-(hx*j - mu)**2/sigma)
        uex.setValue(j, value)
    f.assemble()
    uex.assemble()

    RHS = f.duplicate()
    M.mult(f, RHS)
    RHS.setValue(0, 0.)
    RHS.setValue(m-1, 0.)
    RHS.assemble()

    return RHS, uex

Solve the 1D Laplace problem with FEM ๐Ÿ‘‘

def solve_laplace_problem(A, RHS):
    u = A.createVecs('right')
    r, c = A.getOrdering("natural")
    A.factorILU(r, c)
    A.solve(RHS, u)
    A.setUnfactored()
    return u

Solve the 1D Laplace problem with POD, using a dense matrix ๐ŸŽ€

def solve_laplace_problem_pod(A, RHS, u):
    ksp = PETSc.KSP().create(PETSc.COMM_SELF)
    ksp.setOperators(A)
    ksp.setType('preonly')
    pc = ksp.getPC()
    pc.setType('none')
    ksp.setFromOptions()

    ksp.solve(RHS, u)

    return u

Set N solutions of the 1D Laplace problem as the columns of a matrix (the snapshot matrix) ๐Ÿ“ธ

Note: For simplicity we do not perform a linear solve, but use some analytical solution: z(x) = \exp(-(x - \mu)^2 / \sigma).
def construct_snapshot_matrix(A, N, m):
    snapshots = PETSc.Mat().create(PETSc.COMM_SELF)
    snapshots.setSizes([m, N])
    snapshots.setType('seqdense')

    Istart, Iend = snapshots.getOwnershipRange()
    hx = 1.0/(m - 1)
    x_0 = 0.3
    x_f = 0.7
    sigma = 0.1**2
    for i in range(N):
        mu = x_0 + (x_f - x_0)*random.random()
        for j in range(Istart, Iend):
            value = math.exp(-(hx*j - mu)**2/sigma)
            snapshots.setValue(j, i, value)
    snapshots.assemble()

    return snapshots

Solve the eigenvalue problem โ€” and bestie, the eigenvectors of this problem are what form the POD basis โœจ๐Ÿ”ฅ

def solve_eigenproblem(snapshots, N):
    print('Solving POD basis eigenproblem using eigensolver...')

    Es = SLEPc.EPS()
    Es.create(PETSc.COMM_SELF)
    Es.setDimensions(N)
    Es.setProblemType(SLEPc.EPS.ProblemType.NHEP)
    Es.setTolerances(1.0e-8, 500);
    Es.setKrylovSchurRestart(0.6)
    Es.setWhichEigenpairs(SLEPc.EPS.Which.LARGEST_REAL)
    Es.setOperators(snapshots)
    Es.setFromOptions()

    Es.solve()
    print('Solved POD basis eigenproblem.')
    return Es

Function to project S^TS eigenvectors back onto S eigenvectors ๐Ÿฆ‹

def project_STS_eigenvectors_to_S_eigenvectors(bvEs, S):
    sizes = S.getSizes()[0]
    N = bvEs.getActiveColumns()[1]
    bv = SLEPc.BV().create(PETSc.COMM_SELF)
    bv.setSizes(sizes, N)
    bv.setActiveColumns(0, N)
    bv.setFromOptions()

    tmpvec2 = S.createVecs('left')
    for i in range(N):
        tmpvec = bvEs.getColumn(i)
        S.mult(tmpvec, tmpvec2)
        bv.insertVec(i, tmpvec2)
        bvEs.restoreColumn(i, tmpvec)

    return bv

Function to project the reduced space back to the full space ๐ŸŒˆ

def project_reduced_to_full_space(alpha, bv):
    uu = bv.getColumn(0)
    uPOD = uu.duplicate()
    bv.restoreColumn(0,uu)

    scatter, Wr = PETSc.Scatter.toAll(alpha)
    scatter.begin(alpha, Wr, PETSc.InsertMode.INSERT, PETSc.ScatterMode.FORWARD)
    scatter.end(alpha, Wr, PETSc.InsertMode.INSERT, PETSc.ScatterMode.FORWARD)
    PODcoeff = Wr.getArray(readonly=1)

    bv.multVec(1., 0., uPOD, PODcoeff)

    return uPOD

And main here is the whole procedure, start to finish, the main character fr fr ๐Ÿ‘‘

def main():
    problem_dim = 200
    num_snapshots = 30
    num_pod_basis_functions = 8

    assert(num_pod_basis_functions <= num_snapshots)

    A = construct_operator(problem_dim)
    S = construct_snapshot_matrix(A, num_snapshots, problem_dim)

    # Instead of solving the SVD of S, we solve the standard
    # eigenvalue problem on S.T*S
    STS = S.transposeMatMult(S)

    Es = solve_eigenproblem(STS, num_pod_basis_functions)
    nconv = Es.getConverged()
    print('Number of converged eigenvalues: %i' % nconv)
    Es.view()

    # get the EPS solution in a BV object
    bvEs = Es.getBV()
    bvEs.setActiveColumns(0, num_pod_basis_functions)

    # set the bv POD basis
    bv = project_STS_eigenvectors_to_S_eigenvectors(bvEs, S)
    # rescale the eigenvectors
    for i in range(num_pod_basis_functions):
        ll = Es.getEigenvalue(i)
        print('Eigenvalue '+str(i)+': '+str(ll.real))
        bv.scaleColumn(i,1.0/math.sqrt(ll.real))

    print('--------------------------------')
    # Verify that the active columns of bv form an orthonormal subspace, i.e. that X^H*X = Id
    print('Check that bv.dot(bv) is close to the identity matrix')
    XtX = bv.dot(bv)
    XtX.view()
    XtX_array = XtX.getDenseArray()
    n,m = XtX_array.shape
    assert numpy.allclose(XtX_array, numpy.eye(n, m))
    print('--------------------------------')
    print('Solve the problem with POD')

    # Project the linear operator A
    Ared = bv.matProject(A,bv)

    # Set the RHS and the exact solution
    RHS, uex = set_problem_rhs(problem_dim)

    # Project the RHS on the POD basis
    RHSred = PETSc.Vec().createWithArray(bv.dotVec(RHS))

    # Solve the problem with POD
    alpha = Ared.createVecs('right')
    alpha = solve_laplace_problem_pod(Ared,RHSred,alpha)

okay so the POD projection is done, alpha's been transformed back into the big FE space, and now we're doing the vibe check on how wrong we are ๐Ÿ’…

# Project the POD solution back to the FE space
uPOD = project_reduced_to_full_space(alpha, bv)

# Compute the L2 and Linf norm of the error
error = uex.copy()
error.axpy(-1,uPOD)
errorL2 = math.sqrt(error.dot(error).real)
print('The L2-norm of the error is: '+str(errorL2))

print("NORMAL END")

if __name__ == '__main__':
    main()

and like, obviously we cite our sources bestie, academic integrity is the whole aesthetic ๐Ÿ’–

  • [1] K. Kunisch and S. Volkwein. Galerkin proper orthogonal decomposition methods for a general equation in fluid dynamics. SIAM Journal on Numerical Analysis, 40(2):492-515, 2003.
  • [2] S. Volkwein, Optimal control of a phase-field model using the proper orthogonal decomposition, Z. Angew. Math. Mech., 81:83-97, 2001.

ex11.py: 2-D Laplacian eigenproblem solved with contour integral โœจ

so this one is basically ex2.py's twin but make it contour integral โ€” it's giving sophisticated fr fr. It shows you how to define a region of the complex plane using an RG object โ€” that's slepc4py.SLEPc.RG if you're taking notes ๐ŸŽ€

The full source code for this demo can be downloaded here <../_static/ex11.py>.

Setting up is the exact same ritual as every other example, no cap:

try: range = xrange
except: pass

import sys, slepc4py
slepc4py.init(sys.argv)

from petsc4py import PETSc
from slepc4py import SLEPc

Print = PETSc.Sys.Print

Now we build the finite-difference 2-D Laplacian matrix โ€” this is the main character construction moment ๐Ÿ‘‘

def construct_operator(m, n):
    # Create matrix for 2D Laplacian operator
    A = PETSc.Mat().create()
    A.setSizes([m*n, m*n])
    A.setFromOptions()
    # Fill matrix
    hx = 1.0/(m-1) # x grid spacing
    hy = 1.0/(n-1) # y grid spacing
    diagv = 2.0*hy/hx + 2.0*hx/hy
    offdx = -1.0*hy/hx
    offdy = -1.0*hx/hy
    Istart, Iend = A.getOwnershipRange()
    for I in range(Istart, Iend) :
        A[I,I] = diagv
        i = I//n    # map row number to
        j = I - i*n # grid coordinates
        if i> 0  : J = I-n; A[I,J] = offdx
        if i< m-1: J = I+n; A[I,J] = offdx
        if j> 0  : J = I-1; A[I,J] = offdy
        if j< n-1: J = I+1; A[I,J] = offdy
    A.assemble()
    return A

so in main(): first we read two command-line options to set the grid dimensions. Then we build the matrix and hand it to the solver object. In this case, the solver is configured to use the contour integral method. Next, the region of interest gets defined โ€” and in our case it's an ellipse centered at the origin, with radius 0.2 and vertical scaling of 0.1. Finally, we run the solver. And the lil flex in this example? We're showing you how to print the solution using the solver method errorView() from slepc4py.SLEPc.EPS.errorView ๐Ÿ’…

def main():
    opts = PETSc.Options()
    n = opts.getInt('n', 32)
    m = opts.getInt('m', 32)
    Print("2-D Laplacian Eigenproblem solved with contour integral, "
          "N=%d (%dx%d grid)\n" % (m*n, m, n))
    A = construct_operator(m,n)

    E = SLEPc.EPS().create()
    E.setOperators(A)
    E.setProblemType(SLEPc.EPS.ProblemType.HEP)
    E.setType(SLEPc.EPS.Type.CISS)

    R = E.getRG()
    R.setType(SLEPc.RG.Type.ELLIPSE)
    R.setEllipseParameters(0.0,0.2,0.1)
    E.setFromOptions()

    E.solve()

    vw = PETSc.Viewer.STDOUT()
    vw.pushFormat(PETSc.Viewer.Format.ASCII_INFO_DETAIL)
    E.errorView(viewer=vw)
    vw.popFormat()

if __name__ == '__main__':
    main()

ex12.py: Illustrate the use of arbitrary selection ๐Ÿฆ‹

okay this one slays. It solves a simple tridiagonal eigenproblem, and it illustrates how to set up the arbitrary selection of eigenvalues โ€” where which eigenvalue is "preferred" gets decided based not only on the value of the approximate eigenvalue but ALSO on the approximate eigenvector. multi-dimensional queen behavior ๐Ÿ’…

In this example, the selection criterion is based on the projection of the approximate eigenvector onto a precomputed eigenvector. That's literally why we solve the problem twice โ€” twice the work, twice the drama โœจ

The full source code for this demo can be downloaded here <../_static/ex12.py>.

Initialization, same as always:

import sys, slepc4py
slepc4py.init(sys.argv)

from petsc4py import PETSc
from slepc4py import SLEPc
import numpy

The matrix size n can be specified at the command line.

opts = PETSc.Options()
n = opts.getInt('n', 30)

Create the matrix tridiag([-1 0 -1]).

A = PETSc.Mat(); A.create()
A.setSizes([n, n])
A.setFromOptions()
rstart, rend = A.getOwnershipRange()
for i in range(rstart, rend):
    if i>0: A[i, i-1] = -1
    if i<n-1: A[i, i+1] = -1
A.assemble()

Configure the linear eigensolver initially to compute leftmost eigenvalues:

E = SLEPc.EPS(); E.create()
E.setOperators(A)
E.setProblemType(SLEPc.EPS.ProblemType.HEP)
E.setWhichEigenpairs(SLEPc.EPS.Which.SMALLEST_REAL)
E.setFromOptions()

Solve the eigenproblem and store the first computed eigenvector in sx so we can use it later. For the second solve, we configure the solver to select largest magnitude values with an arbitrary selection callback function myArbitrarySel(). Translation for the besties: instead of sorting eigenvalues, the solver sorts the approximations according to the largest values of whatever myArbitrarySel() returns when evaluated on the approximate eigenvectors. And in this way โ€” plot twist โ€” the same eigenvalue should get computed again ๐Ÿ˜ญ

E.solve()
nconv = E.getConverged()
Print = PETSc.Sys.Print
vw = PETSc.Viewer.STDOUT()
if nconv>0:
    sx, _ = A.createVecs()
    E.getEigenpair(0, sx)
    vw.pushFormat(PETSc.Viewer.Format.ASCII_INFO_DETAIL)
    E.errorView(viewer=vw)
    def myArbitrarySel(evalue, xr, xi, sx):
        return abs(xr.dot(sx))
    E.setArbitrarySelection(myArbitrarySel,sx)
    E.setWhichEigenpairs(SLEPc.EPS.Which.LARGEST_MAGNITUDE)
    E.solve()
    E.errorView(viewer=vw)
    vw.popFormat()
else:
    Print( "No eigenpairs converged" )

ex13.py: Nonlinear eigenproblem with contour integral ๐Ÿงš

bestie. this one is a nonlinear eigenvalue problem solved with the NEP module from slepc4py.SLEPc.NEP, configured to apply a contour integral method. it's giving "we don't do linear anymore" ๐Ÿ™ˆ

The problem arises from the PDE

u_{xx}(x) + n_c^2 \lambda^2 u(x) + g(\lambda) D_0 \lambda^2 u(x) = 0

where

              g(\lambda) &= g_t/(\lambda-k_a + i g_t), \\
k_a &= 8.0, \\ g_t &= 0.5, \\ D_0 &= 0.5, \\ n_c &= 1.2,

and the boundary conditions are

                              u(0) &= 0 \\
u_x(1) &= i \lambda u(1).

For the discretization, n grid points are used, x_1=0,\dots,x_n=1, with step size h = 1/(n-1). Hence,

      u_{xx}(x_i) &= \frac{1}{h^2} (u_{i-1} - 2 u_i + u_{i+1}) \\
            &= \frac{1}{h^2} [1, -2, 1] [u_{i-1}, u_i, u_{i+1}]^T.

The boundary condition at x=0 is u_1=0, and at x=1:

               u'(1) &= 1/2 ( u'(1+h/2) + u'(1-h/2) ) \\
      &= 1/2 ( (u_{n+1}-u_n)/h  + (u_n-u_{n-1})/h ) \\
      &= 1/(2h) (u_{n+1} - u_{n-1}) = i\lambda u_n,

and therefore

                 u_{n+1} = 2i h \lambda u_n + u_{n-1}.

The Laplace term for u_n is

             &= \frac{1}{h^2} (u_{n-1} - 2u_n + u_{n+1}) \\
&= \frac{1}{h^2} (u_{n-1} - 2u_n + 2ih\lambda u_n + u_{n-1}) \\ &=
\frac{1}{h^2} (2 u_{n-1} + (2ih\lambda - 2) u_n) \\ &= \frac{1}{h^2} [2,
2ih\lambda -2] [u_{n-1}, u_n]^T.

The above discretization allows us to write the nonlinear PDE in the following split-operator form

\{A + \lambda^2 n_c^2 I_d + g(\lambda) \lambda^2 D_0 I_d + 2i\lambda/h
                                D\} u = 0

so f_1 = 1, f_2 = n_c^2 \lambda^2, f_3 = g(\lambda) \lambda^2D_0, f_4 = 2i\lambda/h, with coefficient matrices

                        A = \begin{bmatrix}
1 & 0 & 0 & \dots & 0 \\
0 & * & * & \dots & 0 \\
0 & * & * & \dots & 0 \\
\vdots & \vdots & \vdots & \ddots & \vdots \\
0 & 0 & 0 & \dots & *
\end{bmatrix}, I_d = \begin{bmatrix}
0 & 0 & 0 & \dots & 0 \\
0 & 1 & 0 & \dots & 0 \\
0 & 0 & 1 & \dots & 0 \\
\vdots & \vdots & \vdots & \ddots & \vdots \\
0 & 0 & 0 & \dots & 0
\end{bmatrix}, D = \begin{bmatrix}
0 & 0 & 0 & \dots & 0 \\
0 & 0 & 0 & \dots & 0 \\
0 & 0 & 0 & \dots & 0 \\
\vdots & \vdots & \vdots & \ddots & \vdots \\
0 & 0 & 0 & \dots & 1
\end{bmatrix}.

Contributed by: Thomas Hisch. ๐Ÿซถ absolute legend, we love a credited contributor

The full source code for this demo can be downloaded here <../_static/ex13.py>.

Initialization by importing slepc4py, petsc4py, numpy and scipy:

import sys

import slepc4py

slepc4py.init(sys.argv)  # isort:skip

import numpy as np

try:
    import scipy
    import scipy.optimize
except ImportError:
    scipy = None

from petsc4py import PETSc
from slepc4py import SLEPc

Print = PETSc.Sys.Print
bestie WAIT. Check that the selected PETSc/SLEPc are built with complex scalars first, or this whole thing is giving nothing ๐Ÿ’€
if not np.issubdtype(PETSc.ScalarType, np.complexfloating):
    Print("Demo should only be executed with complex PETSc scalars")
    exit(0)

Long function that defines the nonlinear eigenproblem and solves it โ€” buckle up, it's a big one โœจ

def solve(n):
    L = 1.0
    h = L / (n - 1)
    nc = 1.2
    ka = 10.0
    gt = 4.0
    D0 = 0.5

    A = PETSc.Mat().create()
    A.setSizes([n, n])
    A.setFromOptions()
    A.setOption(PETSc.Mat.Option.HERMITIAN, False)

    rstart, rend = A.getOwnershipRange()
    d0, d1, d2 = (
        1 / h**2,
        -2 / h**2,
        1 / h**2,
    )
    Print(f"dterms={(d0, d1, d2)}")

    if rstart == 0:
        # dirichlet boundary condition at the left lead
        A[0, 0] = 1.0
        A[0, 1] = 0.0
        A[1, 0] = 0.0

        A[1, 1] = d1
        A[1, 2] = d2
        rstart += 2
    if rend == n:
        # at x=1.0 neumann boundary condition (not handled here but in a
        # different matrix (D))
        A[n - 1, n - 2] = 2.0 / h**2
        A[n - 1, n - 1] = (-2) / h**2  # + 2j*k*h / h**2 (neumann)
        rend -= 1

    for i in range(rstart, rend):
        A[i, i - 1 : i + 2] = [d0, d1, d2]

    A.assemble()
              Id = PETSc.Mat().create()
              Id.setSizes([n, n])
              Id.setFromOptions()
              Id.setOption(PETSc.Mat.Option.HERMITIAN, True)
              rstart, rend = Id.getOwnershipRange()
              if rstart == 0:
                  # due to dirichlet BC
                  rstart += 1
              for i in range(rstart, rend):
                  Id[i, i] = 1.0
              Id.assemble()

              D = PETSc.Mat().create()
              D.setSizes([n, n])
              D.setFromOptions()
              D.setOption(PETSc.Mat.Option.HERMITIAN, True)
              _, rend = D.getOwnershipRange()
              if rend == n:
                  D[n - 1, n - 1] = 1
              D.assemble()

              Print(f"DOF: {A.getInfo()['nz_used']}, MEM: {A.getInfo()['memory']}")

              f1 = SLEPc.FN().create()
              f1.setType(SLEPc.FN.Type.RATIONAL)
              f1.setRationalNumerator([1.0])
              f2 = SLEPc.FN().create()
              f2.setType(SLEPc.FN.Type.RATIONAL)
              f2.setRationalNumerator([nc**2, 0.0, 0.0])
              f3 = SLEPc.FN().create()
              f3.setType(SLEPc.FN.Type.RATIONAL)
              f3.setRationalNumerator([D0 * gt, 0.0, 0.0])
              f3.setRationalDenominator([1.0, -ka + 1j * gt])
              f4 = SLEPc.FN().create()
              f4.setType(SLEPc.FN.Type.RATIONAL)
              f4.setRationalNumerator([2j / h, 0])

              # Setup the solver
              nep = SLEPc.NEP().create()

              nep.setSplitOperator(
                  [A, Id, Id, D],
                  [f1, f2, f3, f4],
                  PETSc.Mat.Structure.SUBSET,
              )

              # Customize options
              nep.setTolerances(tol=1e-7)

              nep.setDimensions(nev=24)
              nep.setType(SLEPc.NEP.Type.CISS)

              # the rg params are chosen s.t. the singularity at k = ka - 1j*gt is
              # outside of the contour.
              radius = 3 * gt
              vscale = 0.5 * gt / radius
              rg_params = (ka, 3 * gt, vscale)
              R = nep.getRG()
              R.setType(SLEPc.RG.Type.ELLIPSE)
              Print(f"RG params: {rg_params}")
              R.setEllipseParameters(*rg_params)

              nep.setFromOptions()

              # Solve the problem
              nep.solve()

              its = nep.getIterationNumber()
              Print("Number of iterations of the method: %i" % its)
              sol_type = nep.getType()
              Print("Solution method: %s" % sol_type)
              nev, ncv, mpd = nep.getDimensions()
              Print("")
              Print("Subspace dimension: %i" % ncv)
              tol, maxit = nep.getTolerances()
              Print("Stopping condition: tol=%.4g" % tol)
              Print("")

              nconv = nep.getConverged()
              Print("Number of converged eigenpairs %d" % nconv)

              x = A.createVecs("right")

              evals = []
              modes = []
              if nconv > 0:
                  Print()
                  Print("        lam            ||T(lam)x||   |lam-lam_exact|/|lam_exact| ")
                  Print("--------------------- ------------- -----------------------------")
                  for i in range(nconv):
                      lam = nep.getEigenpair(i, x)
                      error = nep.computeError(i)

                      def eigenvalue_error_term(k):
                          gkmu = gt / (k - ka + 1j * gt)
                          nceff = np.sqrt(nc**2 + gkmu * D0)
                          return -1j / np.tan(nceff * k * L) - 1 / nceff

                      # compute the expected_eigenvalue

                      # we assume that the numerically calculated eigenvalue is close to
                      # the exact one, which we can determine using a Newton-Raphson
                      # method.
                      if scipy:
                          expected_lam = scipy.optimize.newton(
                              eigenvalue_error_term, np.complex128(lam), rtol=1e-11
                          )
                          rel_err = abs(lam - expected_lam) / abs(expected_lam)
                          rel_err = "%6g" % rel_err
                      else:
                          rel_err = "scipy not installed"

                      Print(" %9f%+9f j %12g   %s" % (lam.real, lam.imag, error, rel_err))

                      evals.append(lam)
                      modes.append(x.getArray().copy())
                  Print()

              return np.asarray(evals), rg_params, ka, gt

okay so that's the solver, bestie โœจ and then the main function? she reads the problem size n off the command line, runs solve on it, and then plots the eigenvalues she got. Like, that's the whole arc ๐Ÿ’–

          def main():
              opts = PETSc.Options()
              n = opts.getInt("n", 256)
              Print(f"n={n}")

              evals, rg_params, ka, gt = solve(n)

              if not opts.getBool("ploteigs", True) or PETSc.COMM_WORLD.getRank():
                  return

              try:
                  import matplotlib.pyplot as plt
                  from matplotlib.patches import Ellipse
              except ImportError:
                  print("plot is not shown, because matplotlib is not installed")
              else:
                  fig, ax = plt.subplots()
                  ax.plot(evals.real, evals.imag, "x")

                  height = 2 * rg_params[1] * rg_params[2]
                  ellipse = Ellipse(
                      xy=(rg_params[0], 0.0),
                      width=rg_params[1] * 2,
                      height=height,
                      edgecolor="r",
                      fc="None",
                      lw=2,
                  )
                  ax.add_patch(ellipse)

                  ax.grid()
                  ax.legend()
                  plt.show()

          if __name__ == "__main__":
              main()

๐ŸŒธ ex14.py: Lyapunov equation with the shifted 2-D Laplacian ๐ŸŒธ

this one is a whole different font of slay โ€” it shows off the slepc4py linear matrix equations solver object, aka the LME girlies ๐Ÿซถ specifically, we solve a Lyapunov equation where the coefficient matrix is the shifted 2-D Laplacian. iconic.

the full source code for this demo can be downloaded here, at ../_static/ex14.py ๐Ÿ’พ

initialization is, like, exactly the same vibe as the previous examples:

          import sys, slepc4py
          slepc4py.init(sys.argv)

          from petsc4py import PETSc
          from slepc4py import SLEPc

          Print = PETSc.Sys.Print

and once again we have a function building the discretized Laplacian operator in two dimensions ๐Ÿฆ‹ but bestie, read the fine print: this time it's the shifted negative Laplacian, because a Lyapunov equation needs the coefficient matrix to be stable. the math says so, not me ๐Ÿ’…

          def Laplacian2D(m, n, sigma):
              # Create matrix for 2D Laplacian operator
              A = PETSc.Mat().create()
              A.setSizes([m*n, m*n])
              A.setFromOptions()
              # Fill matrix
              Istart, Iend = A.getOwnershipRange()
              for I in range(Istart, Iend):
                  A[I,I] = -4.0-sigma
                  i = I//n    # map row number to
                  j = I - i*n # grid coordinates
                  if i> 0  : J = I-n; A[I,J] = 1.0
                  if i< m-1: J = I+n; A[I,J] = 1.0
                  if j> 0  : J = I-1; A[I,J] = 1.0
                  if j< n-1: J = I+1; A[I,J] = 1.0
              A.assemble()
              return A

next up, this function solves the continuous-time Lyapunov equation

                                    AX + XA^* = -C

where C is supposed to have low rank ๐Ÿ“‰ and the solution X also has low rank โ€” which gets restricted to rk if rk was handed in as an argument of the function. after solving, she computes and prints a residual norm. doing both at once? that's main character energy fr fr ๐Ÿ‘‘

          def solve_lyap(A, C, rk=0):
              # Setup the solver
              L = SLEPc.LME().create()
              L.setProblemType(SLEPc.LME.ProblemType.LYAPUNOV)
              L.setCoefficients(A)
              L.setRHS(C)

              N = C.size[0]
              if rk>0:
                  X1 = PETSc.Mat().createDense((N,rk))
                  X1.assemble()
                  X = PETSc.Mat().createLRC(None, X1, None, None)
                  L.setSolution(X)

              L.setTolerances(1e-7)
              L.setFromOptions()

              # Solve the problem
              L.solve()

              if rk==0:
                  X = L.getSolution()

              its = L.getIterationNumber()
              Print(f'Number of iterations of the method: {its}')
              sol_type = L.getType()
              Print(f'Solution method: {sol_type}')
              tol, maxit = L.getTolerances()
              Print(f'Stopping condition: tol={tol}, maxit={maxit}')
              Print(f'Error estimate reported by the solver: {L.getErrorEstimate()}')
              if N<500:
                  Print(f'Computed residual norm: {L.computeError()}')
              Print('')

              return X

then main chews through a bunch of command-line arguments โ€” the grid dimensions (n, m), the shift sigma, and the rank of the solution, rank ๐ŸŽ€

the coefficient matrix A comes from the function above โ˜๏ธ while the right-hand side matrix C has to be built as a low-rank matrix using Mat.createLRC(), docs at https://petsc.org/release/petsc4py/reference/petsc4py.PETSc.Mat.html#petsc4py.PETSc.Mat.createLRC ๐Ÿ“š

          if __name__ == '__main__':
              opts = PETSc.Options()
              n = opts.getInt('n', 15)
              m = opts.getInt('m', n)
              N = m*n
              sigma = opts.getScalar('sigma', 0.0)
              rk = opts.getInt('rank', 0)

              # Coefficient matrix A
              A = Laplacian2D(m, n, sigma)

              # Create a low-rank Mat to store the right-hand side C = C1*C1'
              C1 = PETSc.Mat().createDense((N,2))
              rstart, rend = C1.getOwnershipRange()
              v = C1.getDenseArray()
              for i in range(rstart,rend):
                  if i<N//2: v[i-rstart,0] = 1.0
                  if i==0: v[i-rstart,1] = -2.0
                  if i==1 or i==2: v[i-rstart,1] = -1.0
              C1.assemble()
              C = PETSc.Mat().createLRC(None, C1, None, None)

              X = solve_lyap(A, C, rk)

๐Ÿ‘‘ Author ๐Ÿ‘‘

Lisandro Dalcin โ€” the one and only, we stan ๐Ÿซถโœจ

and that's a wrap on the whole page, bestie ๐Ÿ˜ญ๐Ÿ’– you just read all 153 parts of SLEPC4PY(3), and honestly? ate. no crumbs. go run something and let the eigenvalues be in your favor ๐Ÿฆ‹๐ŸŒธ

this was version 3.25, dated Jun 18, 2026 โ€” so if you're reading this from a different timeline, vibe check first, iykyk ๐Ÿ’…
๐Ÿ“ฆ where this page comes from